docs(architecture): document how the six packages connect

[OM152002]

Closes #55.

Adds docs/architecture.md — the document that owns the chain between the six src/ packages. The docs/gate/*.md specs each describe one hop; this one describes what hands what to whom, under which contract, and where the chain is not connected yet.

Derived from the code at 6ad7151, not from sibling docs.

What's in it

1. The loop, in one mermaid flowchart LR — testbed → recorder → trajectory.json → compiler → bundle → cache write (pool/tenant split) → runner replay → repair → metrics NDJSON → gate report, with the governing contract on every edge.
2. Package table — responsibility, public entry point, contract read, contract written, spec doc, one row per package (plus experiments/gate-v1/).
3. Artifact table — every file the pipeline produces, where it lands, committed vs gitignored.
4. What is real vs stubbed today — eight rows, each with the file:line proving it and a live issue that fixes it.
5. Invariants that must not break — frozen assertions, fail-closed pool writes, no typed values in a trajectory, no_data over invented rates, and the harness staying throwaway.
6. Open questions / what I could not verify — including the doc-vs-code disagreements below.

⚠️ Two hops in the pipeline do not exist

The diagram draws these as dashed red edges rather than pretending the chain is whole:

1. The bundle never reaches the cache. Nothing outside src/cache/ and tests/ imports the cache package — so writeCacheRow, the authoritative write-time privacy boundary, is never called by the pipeline. The pool_eligible flag on a bundle row comes from the compiler's own pre-check (src/compiler/pool.ts). Both fail closed and the compiler's doc honestly calls itself a pre-check — but today nothing calls the authority.
2. The bundle never reaches the runner. The runner consumes CompiledProgram (src/runner/types.ts), a different shape from CompiledTrajectoryBundle, and no adapter exists. npm run gate:matrix loads a hand-written experiments/gate-v1/fixtures/compiled-program.json instead.

Both close with #52. Every hop is unit-tested; the seams between them are not.

Per the issue's constraint, I recorded rather than resolved the resulting doc conflicts — no sibling doc was edited:

• DEVELOPMENT.md "The data flow" shows cache write (fail-closed) as a step in the chain, and its layout table says cache-row.schema.json — compiler + cache write, runner reads.
• contracts/README.md lists cache-row.schema.json as read by "B4" (the runner) — true by shape, false by wiring.

Whether those are describing intent or are stale is the owners' call, so both are in Open questions.

Stub → issue mapping

Every stub links a live issue: StubRepairModelClient → #27 · cost_fresh zeros → #39 · run-matrix.ts exit-2 → #62 · placeholder versions.json → #26 · cache read path/persistence → #63 · confidence updates → #64 · both unwired hops → #52 · missing cache hit-rate metric → #67.

How this was verified

npm run lint:docs does not exist yet — it is #53, already flagged in DEVELOPMENT.md's own open questions. The issue's stated test could not be run, so I substituted stronger checks and noted this in the doc:

Check	Result
npm run ci	green (secret-scan, contracts, lint, typecheck, 35 unit tests)
npm run test:canary	green (6 tests)
Every repo path named in the doc exists at HEAD	scripted sweep — all resolve; the only misses are experiments/gate-v1/out/*, which are gitignored generated output and correctly described as such
Every file:line reference	spot-checked each one against sed -n output
Every relative doc link	scripted — all 12 resolve
Mermaid renders	rendered with real mermaid 11 in headless Chromium: RENDER_OK, 14 nodes / 14 edges, zero console errors, and linkStyle 4/7 confirmed to land on the two dashed edges
Artifact table accuracy	ran gate:matrix -- --dry-run + gate:report and diffed the produced file list against the table; also confirmed npm run compile leaves the committed bundle byte-identical
Aggregate claims	ran the report: 7 sections, no_data on exactly the four with no denominator

Frontmatter matches the CONTRIBUTING standard (doc_type: spec) and the doc ends with ## Open questions / what I could not verify. docs/README.md index row added under Start here.

The test the doc exists for

open it against a fresh checkout and confirm you can answer, without opening a source file, "where does a trajectory come from, and what reads it?"

There is a Reading the diagram subsection directly under the mermaid block that answers exactly that question in one paragraph, naming the CLI that writes it, the default output path, and the single reader.

Follow-up (not in this PR)

• When Add docs frontmatter + index linter (npm run lint:docs) and fix existing violations #53 lands, run npm run lint:docs against this doc and add it to the check table.
• The DEVELOPMENT.md / contracts/README.md conflicts above need an owner's adjudication — they are deliberately untouched here.
• If Add end-to-end integration test: record → compile → cache-write → replay #52 closes the two breaks, the dashed edges become solid and the "two breaks" prose should be deleted, not softened.

🤖 Generated with Claude Code

[myselfsiddharth]

Looks good