feat(diagrams): add mechanism diagrams to deep panels and docs

.github/workflows/ci.yml

@@ -70,3 +70,10 @@ jobs:
         run: |
           pnpm generate
           git diff --exit-code -- src/data/dataset.json
+
+      # The mechanism diagrams and their docs page are rendered from
+      # src/diagrams/ by the same rule: committed output must equal a fresh render.
+      - name: Verify public/diagrams and docs/mechanisms.md are regenerable byte-for-byte
+        run: |
+          pnpm diagrams
+          git diff --exit-code -- public/diagrams docs/mechanisms.md

README.md

@@ -38,6 +38,15 @@ resolves, every manifest claim is used, public evidence is revision-pinned,
 and private or operator-attested evidence is labeled without pretending it is
 publicly verifiable.
 
+## Mechanism diagrams
+
+Six static diagrams of the mechanisms (closure, handoff lease, airlock,
+freshness, spine rows, guard layers) live in each scene's "go deeper" panel and
+in [`docs/mechanisms.md`](docs/mechanisms.md). They are rendered from
+`src/diagrams/`, print only values computed from the dataset and vocabularies,
+wear the manifest's assurance level, and are regenerated with `pnpm diagrams`;
+CI fails if a committed file drifts from a fresh render.
+
 ## Accessibility
 
 Always-visible Pause on the global transport (WCAG SC 2.2.2), keyboard
@@ -58,6 +67,7 @@ pnpm install
 pnpm dev        # local console
 pnpm test       # unit + closure + property + contrast gates
 pnpm generate   # re-emit src/data/dataset.json from the seeded generator
+pnpm diagrams   # re-emit public/diagrams/*.svg from src/diagrams/
 pnpm guard      # forbidden-pattern scan (add --git for history)
 pnpm build      # production bundle (sourcemaps off)
 ```

docs/mechanisms.md

@@ -0,0 +1,110 @@
+# Mechanism diagrams
+
+<!-- Generated by scripts/render-diagrams.ts from src/diagrams/. Do not edit; run pnpm diagrams. -->
+
+6 pictures of how the Operator OS works, drawn from the same closed data the
+explainer replays. Each one lives in a scene's "go deeper" panel and here, as a
+static file. This page and the files under `public/diagrams/` are generated from
+`src/diagrams/` by `pnpm diagrams`; `src/diagrams/render.test.ts` and CI fail if a
+committed file no longer matches a fresh render, and `src/diagrams/facts.test.ts`
+fails if a printed figure no longer matches `src/data/dataset.json`.
+
+## What a diagram promises
+
+Every diagram wears the assurance level of the weakest architecture claim it
+depicts, taken from
+[`public/architecture-manifest-v1.json`](../public/architecture-manifest-v1.json):
+
+- **Explainer-local verified**: Evidence is in this public explainer source pinned to an immutable Git commit.
+- **Operator attested**: The claim describes operator practice and is an attestation, not independently verifiable public-source evidence.
+- **Private source verified**: Evidence was checked against private operator-controlled source; public readers cannot independently inspect it.
+- **Public source verified**: Evidence points to public source pinned to an immutable Git commit.
+
+Every count and clock time on a diagram is computed from the dataset or the
+vocabularies at build time; the in-app figure and the file here are rendered
+from one model per diagram, so they cannot say different things.
+
+## 01 · How the console stays honest
+
+<picture>
+  <source srcset="../public/diagrams/closure-deck.svg" media="(prefers-color-scheme: dark)">
+  <img src="../public/diagrams/closure-paper.svg" alt="Closed vocabularies feed a pure seeded generator that writes one committed dataset; the app imports only that file, three gates fail the build on any escape, the bundle ships without source maps, and the release lineage is an orphan tree. The real stores have no wire into the app.">
+</picture>
+
+Every shipped value is a member of an audited finite set by construction: the generator can only emit vocabulary members, the closure test proves nothing escaped, and the app has no wire to the real stores. The scanner is a backstop for mistakes in the allowlists themselves.
+
+Verify: pnpm test (closure, property, contrast, manifest) · pnpm guard · pnpm build, then inspect dist for .map files.
+
+Claims: `public-release-closure`, `deterministic-synthetic-replay`. Assurance: explainer-local verified. Scene: Coda.
+
+## 02 · A handoff is a lease with a receipt
+
+<picture>
+  <source srcset="../public/diagrams/lease-deck.svg" media="(prefers-color-scheme: dark)">
+  <img src="../public/diagrams/lease-paper.svg" alt="Three lanes: claude.ai, the spine, and Claude Code. Dispatch creates a pending handoff row; Claude Code reads the latest snapshot, picks the handoff up and receives a one-time completion capability; 15.5 s of mission work pass; both sides acknowledge a receipt; clear consumes the capability and the row reads cleared. Below, the SHIPPED tag on the activity row creates a sync obligation to the external build log.">
+</picture>
+
+Pickup is the one dangerous transition, pending to active, so it hands the claimant a one-time completion capability that only clear can consume. The 15.5 s gap is real: the Spine scene and the Finale share handoff 1 and mission 1.
+
+Verify: stages and statuses are closed sets in src/data/vocab.ts · times from src/data/dataset.json · capability and retention in the bridge-db README, Tools and Retention, pinned at e0a9560.
+
+Claims: `bridge-sqlite-spine`. Assurance: public source verified. Scene: The Spine.
+
+## 03 · Nothing leaves without a token
+
+<picture>
+  <source srcset="../public/diagrams/airlock-deck.svg" media="(prefers-color-scheme: dark)">
+  <img src="../public/diagrams/airlock-paper.svg" alt="Three lanes, agent, hub, operator, and a boundary marked outside the machine. The agent creates a draft and raises an approval. Only the operator mints the one-use confirmation token and opens the timed send window. The send gate opens to the outside only when both hold. The agent lane never reaches the boundary.">
+</picture>
+
+draft, approval, send are the 3 closed stages. The token and the send window are not stages: they are two conditions on the last edge, and both are operator-only. Every externally visible action is a reviewed, token-gated event.
+
+Verify: HUBFLOW_STAGES is a closed set of 3 in src/data/vocab.ts · no send event precedes its approval in src/data/dataset.json · the token and window boundary is private control-plane source, checked but not publicly inspectable.
+
+Claims: `approval-airlock`. Assurance: private source verified. Scene: The Hub.
+
+## 04 · Alerts fire only from fresh data
+
+<picture>
+  <source srcset="../public/diagrams/freshness-deck.svg" media="(prefers-color-scheme: dark)">
+  <img src="../public/diagrams/freshness-paper.svg" alt="Left: 5 spokes (bridge, event-bus, overlay, auditor, evals-ledger), each its own system of record, read by the hub through an adapter; the hub never calls external services. Right: a 4-state machine (fresh, aging, stale, unavailable). A tick moves any state to fresh; age moves fresh to aging to stale. Only fresh has an exit labeled alert eligible. In the fixture the overlay spoke goes stale and never recovers.">
+</picture>
+
+Each spoke keeps its own system of record; the hub only reads. Because the alert edge leaves the fresh state and no other, an aging or stale spoke goes quiet instead of lying, which is why the overlay light stays dark at the end of the replay.
+
+Verify: SPOKES and FRESHNESS_STATES are closed sets in src/data/vocab.ts · ticks from src/data/dataset.json · the alert eligibility boundary is private control-plane source, checked but not publicly inspectable.
+
+Claims: `freshness-gated-alerts`. Assurance: private source verified. Scene: The Hub.
+
+## 05 · One store, five row shapes, fixed writers
+
+<picture>
+  <source srcset="../public/diagrams/spine-rows-deck.svg" media="(prefers-color-scheme: dark)">
+  <img src="../public/diagrams/spine-rows-paper.svg" alt="A horizontal bus labeled bridge-db, SQLite plus FTS5, with 5 taps: activity, handoffs, snapshots, cost, sections. Under each tap, the systems allowed to write it under their fixed caller identity. Below, the retention rule for activity: untagged rows keep only the newest per source, rows tagged SHIPPED or LEDGER are kept for good, and SHIPPED creates a sync obligation. Every row carries a source trust value.">
+</picture>
+
+Nothing moves between systems except through these five shapes, each written under a fixed identity. Retention is structural: a protected tag is a property of the row, so no pruning pass and no cascade can orphan its receipt.
+
+Verify: shapes and writer sets mirror src/types/data.ts (Caller, SnapSystem, CostSystem, SectionOwner, SourceTrust, ActivityTag) · the bridge-db README, Architecture, Tools, Trust and Retention, pinned at e0a9560.
+
+Claims: `bridge-sqlite-spine`. Assurance: public source verified. Scene: The Spine.
+
+## 06 · Guards fire, the agent adapts
+
+<picture>
+  <source srcset="../public/diagrams/guards-deck.svg" media="(prefers-color-scheme: dark)">
+  <img src="../public/diagrams/guards-paper.svg" alt="7 guard layers stacked from outer intent to inner floor: permission-mode, deny-list, pretooluse-hook, hard-deny, confidence-gate, verify-gate, integrity-floor. 6 fabricated would-be actions enter from the left and each stops at the layer that catches it, then exits to the right as an adaptation. No line crosses to a privilege escalation. The integrity floor checks the other 6 are present.">
+</picture>
+
+Each layer works alone, so no single failure unlocks the system. A blocked action is a signal to adapt: open a branch, reword, reroute, verify first, or hand the decision to the operator.
+
+Verify: GUARD_LAYERS (7), RULE_CONCEPTS (6), ADAPTATIONS and GUARD_MAP in src/data/vocab.ts · the guard event at T+11.0 s in src/data/dataset.json · the layered practice itself is an operator attestation, not public source.
+
+Claims: `layered-operation-guards`. Assurance: operator attested. Scene: The Safety Layers.
+
+## Regenerating
+
+```sh
+pnpm diagrams   # rewrites public/diagrams/*.svg and this page from src/diagrams/
+pnpm test       # fails if a committed file or a printed fact has drifted
+```

e2e/product-quality.spec.ts

@@ -24,6 +24,17 @@ const viewports = [
 const titleFor = (heading: string) =>
 	`${heading} — Anatomy of an AI Operator OS`;
 
+/** Mechanism diagrams each scene's deep panel carries (src/diagrams placement). */
+const diagramsByRoute: Record<string, number> = {
+	"/": 0,
+	"/fleet": 0,
+	"/spine": 2,
+	"/safety": 1,
+	"/finale": 0,
+	"/hub": 2,
+	"/coda": 1,
+};
+
 async function openStable(page: Page, route: string) {
 	await page.emulateMedia({ reducedMotion: "reduce" });
 	await page.goto(route, { waitUntil: "domcontentloaded" });
@@ -428,12 +439,36 @@ test.describe("scene interaction dispositions", () => {
 			await disclosure.press("Enter");
 			const region = page.getByRole("region", { name: /go deeper/i });
 			await expect(region).toBeVisible();
+			const figures = region.locator("figure[data-diagram]");
+			await expect(figures).toHaveCount(diagramsByRoute[route.path] ?? 0);
+			for (const figure of await figures.all()) {
+				const svg = figure.getByRole("img");
+				await expect(svg).toBeVisible();
+				expect((await svg.getAttribute("aria-label"))?.length ?? 0).toBeGreaterThan(40);
+			}
 			const overflow = await page.evaluate(() =>
 				document.documentElement.scrollWidth - document.documentElement.clientWidth,
 			);
 			expect(overflow, `${route.path} expanded panel overflow`).toBe(0);
 		}
 	});
+
+	for (const width of [320, 1440] as const) {
+		for (const route of routes.filter((r) => (diagramsByRoute[r.path] ?? 0) > 0)) {
+			test(`${route.slug} deep panel with its diagrams passes WCAG checks at ${width}px`, async ({
+				page,
+			}) => {
+				await page.setViewportSize({ width, height: width === 320 ? 720 : 900 });
+				await openStable(page, route.path);
+				await page.getByRole("button", { name: /go deeper/i }).press("Enter");
+				await expect(page.getByRole("region", { name: /go deeper/i })).toBeVisible();
+				const results = await new AxeBuilder({ page })
+					.withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"])
+					.analyze();
+				expect(results.violations).toEqual([]);
+			});
+		}
+	}
 });
 
 test("all routes remain free of runtime console and page errors", async ({ page }) => {

package.json

@@ -16,6 +16,7 @@
 		"test:e2e": "playwright test",
 		"typecheck": "tsc -b",
 		"generate": "node scripts/generate-dataset.ts",
+		"diagrams": "node scripts/render-diagrams.ts",
 		"guard": "node scripts/guard-scan.ts",
 		"verify:live": "node scripts/check-live-parity.ts"
 	},