feat: add chainweaver attest <flow> for observed-determinism evidence (#154)

[dgenio]

Summary

Adds chainweaver/attest.py plus the chainweaver attest <flow> CLI verb. Turns ChainWeaver's "compiled flows are deterministic" claim into a reproducible, machine-verifiable artifact.

Stacked on top of #161 (analyzer foundation); base cascades through #161 → #160 → #159 → #158 → #157 → main as those merge.

Closes #154.

Changes

• chainweaver/attest.py — new module (~330 LoC). attest_flow() API + AttestationReport (Pydantic) + AttestationInputError + a seeded stdlib input generator.
• chainweaver/cli.py — new attest_command (~165 LoC including table renderer + flag definitions).
• chainweaver/__init__.py — exports AttestationInputError, AttestationReport, attest_flow via __all__.
• tests/test_attest.py — new file, 16 test cases (API + CLI + generator coverage).

Pipeline

1. Generate N reproducible inputs (seed-driven random.Random) or accept a user-supplied list via --seed-input.
2. For each input, run the flow M times.
3. Hash the canonical JSON of every final_output; assert all M agree.
4. Emit an AttestationReport: ChainWeaver version, flow name+version, flow_schema_fingerprint, tool_schema_hashes, N, repeats, seed, host info (no PII), duration, observed_deterministic, aggregate_fingerprint, divergences.

Framing

This is observed-deterministic evidence, not a formal proof. Re-running with the same flow, tools, and seed yields a byte-identical aggregate_fingerprint.

CLI surface

Flag	Meaning
--tools <module> (-t, repeatable)	tool import paths
--runs N (default 100)	number of distinct inputs
--repeats M (default 3, must be >= 2)	runs per input
--seed S (default 0)	generator seed (same → same inputs)
--seed-input <file>	bypass generator with a JSON array of objects
--format json|table (-f)	default json — the attestation artifact

Exit codes

• 0 — observed-deterministic across all inputs.
• 1 — divergence, execution failure, or CLI-level error.
• 2 — flow file or tools module not found / not importable.

Scope-delta call (Mode B)

The issue body says "use Hypothesis strategies as in #143." I shipped a stdlib random.Random-seeded generator instead. Reasoning:

• Hypothesis is built around @given for property exploration and shrinking, not "give me N reproducible inputs by seed."
• Getting deterministic enumeration from Hypothesis requires reaching into its internals (ConjectureData, etc.).
• The stdlib generator is ~60 LoC, fully deterministic by construction, and covers the common subset of Pydantic types (int, float, bool, str, list[X], dict[K, V], Literal, Optional[X], nested BaseModel).
• The seam is explicit: _generate_inputs() can be swapped for a Hypothesis-backed implementation once Add Hypothesis property-based determinism test harness #143 lands, without touching the rest of the loop.

Net: no hypothesis dependency added. If you'd rather take the hypothesis route, say the word and I'll swap _generate_inputs() behind an optional extra.

Testing

• Linting passes (ruff check chainweaver/ tests/ examples/)
• Formatting check passes (ruff format --check chainweaver/ tests/ examples/)
• Type checking passes (python -m mypy chainweaver/ tests/)
• All existing tests pass — 543/543 passed in 2.12s (527 pre-existing + 16 new)
• New tests added for new functionality

$ ruff check chainweaver/ tests/ examples/
All checks passed!
$ ruff format --check chainweaver/ tests/ examples/
56 files already formatted
$ python -m mypy chainweaver/ tests/
Success: no issues found in 48 source files
$ python -m pytest tests/ -q --no-cov
543 passed in 2.12s

Tests cover both halves: the programmatic attest_flow() API (deterministic happy path, seed reproducibility, different seeds → different fingerprints, flaky-tool failure, seed_inputs bypass, validation errors, structural-fingerprint sensitivity, multi-type generator coverage) and the CLI surface (happy-path JSON, table format, --seed-input bypass, missing flow file, repeats validation, malformed/non-array seed-input).

Diff stat: 4 files changed, 1136 insertions(+).

Related Issues

Closes #154. Companion to:

• ChainAnalyzer (feat: add ChainAnalyzer for offline schema-compatibility analysis (#77) #161) — static analysis; this is the runtime equivalent.
• Hypothesis property-test harness (Add Hypothesis property-based determinism test harness #143, not yet filed) — the natural follow-up; the generator seam is explicit.

Checklist

• Code follows project conventions (see AGENTS.md and docs/agent-context/)
• Public API changes are documented — AttestationInputError, AttestationReport, attest_flow in __all__; CLI docstring lists attest
• No secrets or credentials included

Tradeoffs / risks

• Stdlib random.Random vs Hypothesis. Documented above; the user accepted the relaxation but property-based testing wasn't the right tool for "reproducible N samples by seed." Switching later is a localized change to _generate_inputs().
• flow_schema_fingerprint excludes status / description. Intentional: those fields don't affect runtime behavior, and including them would cause aggregate_fingerprint to change on cosmetic edits.
• Host info is non-PII by construction. Only OS family, Python version, and architecture are recorded. Hostnames and usernames are deliberately excluded.
• executor._tools access. attest_flow() reads the executor's private tool registry to compute tool_schema_hashes. Adding a public iterator on FlowExecutor would be cleaner but is out of scope here (touches an unrelated class). Same-package access is consistent with how cli.py already reaches into module internals.
• No cryptographic signing. The artifact is reproducible but not signed. A Sigstore bundle follow-up was flagged in the original issue body — kept out of scope.

Scope notes

Closes #154 only. Adjacent items deferred:

• Sigstore bundle for cryptographic signing of the attestation JSON — future.
• Hypothesis-backed generator — depends on Add Hypothesis property-based determinism test harness #143 being filed and landed; seam is ready.
• FlowExecutor.tools public iterator — small follow-up; not bundled.

https://claude.ai/code/session_01QcSJ3NWhe5B4k1EP25Hx3n

---

Generated by Claude Code