Mermaid renders bounded one-hop and Pack diagrams without becoming a graph browser

outcome

Give maintainers disposable, deterministic Mermaid diagrams of each Spec's one-hop neighborhood and each Pack's membership without ever projecting the whole graph or inventing a second truth store.

rule line 19 · specs/consumers/mermaid-view.sdp.md:19

renderMermaid is a pure Reader -> pages projection with no filesystem or clock access; equal reader data produces byte-identical pages.

rule line 20 · specs/consumers/mermaid-view.sdp.md:20

The page set is one page per Spec, selecting that Spec and every node one edge away, code units and test anchors included, one page per Pack selecting the Pack and its members, and one deterministic index that links them. A selected diagram is rendered or refused under the hard bounds; the projection never emits a whole-graph diagram.

rule line 21 · specs/consumers/mermaid-view.sdp.md:21

Machine node tokens are injective encodings of the full graph ID. Titles and other display text never become machine tokens.

rule line 22 · specs/consumers/mermaid-view.sdp.md:22

Visible labels are escaped for Mermaid's own syntax, apart from the Design Review's Markdown escaping, so no label can close or break a diagram.

rule line 23 · specs/consumers/mermaid-view.sdp.md:23

Every emitted record — pages, node declarations, edge declarations, index rows — is ordered by deterministic code-unit order independent of graph input order.

rule line 24 · specs/consumers/mermaid-view.sdp.md:24

An unresolved relation or edge target renders as an explicit unresolved placeholder node rather than disappearing or being invented.

rule line 25 · specs/consumers/mermaid-view.sdp.md:25

A cycle through the root renders as its ordinary edges; the projection computes no transitive closure and no layout.

rule line 26 · specs/consumers/mermaid-view.sdp.md:26

Disconnected neighborhoods and foreign edge types remain visible when they appear in the selected one-hop or Pack slice; absence of a neighbor is honest silence, not a synthetic hub.

rule line 27 · specs/consumers/mermaid-view.sdp.md:27

Hard bounds are exact: maxNodesPerDiagram = 64 and maxEdgesPerDiagram = 128. A token collision or an overflow of either bound refuses the affected diagram with a deterministic refusal that names the bound, while every in-bound diagram still publishes and the command exits 0. The projection never silently truncates, shards partially, drops edges to fit, or aborts the whole page set because one diagram overflowed.

rule line 28 · specs/consumers/mermaid-view.sdp.md:28

After the shared build, publication owns only generated/mermaid/ and uses the explicit sdp mermaid surface. It is not a child of or an extra write inside Design Review's transaction, and it shares no publication bus or hidden side channel with other projections.

rule line 29 · specs/consumers/mermaid-view.sdp.md:29

A Mermaid run writes its complete page set to generated/mermaid.tmp/, removes the prior Mermaid root, and renames the temporary root into place. The shared build invalidates this root and all sibling projection roots before extraction, as spec:consumers.wholesale-view-rewrite#rule.buildInvalidates states, so failure leaves honest absence rather than stale output that looks current. A failed publish removes any live or temporary Mermaid root it cannot certify.

rule line 30 · specs/consumers/mermaid-view.sdp.md:30

sdp mermaid --check-clean renders an independent twin, refuses divergent renders, and compares the current generated root with the new render. Missing or drifted output returns nonzero and is removed; clean output is replaced wholesale with byte-identical content.

rule line 31 · specs/consumers/mermaid-view.sdp.md:31

When extraction succeeds but graph validation reports errors, Mermaid still publishes the labelled diagnostic projection and returns the nonzero validation exit code.

rule line 32 · specs/consumers/mermaid-view.sdp.md:32

The projection adds no Mermaid-specific Reader accessors, maintains no projection-owned taxonomy list, and confers nothing back into the graph.

14 unkeyed rules.

Example space

Given a graph containing Specs, Packs, one-hop relations, an unresolved target, a cycle, and a neighborhood within the stated bounds
When the Mermaid projection renders and publishes through the explicit mermaid command
Then each Spec page holds only that Spec's one-hop neighborhood
Then each Pack page holds only that Pack and its members
Then the index links every diagram deterministically
Then machine tokens remain injective full-ID encodings
Then hostile label characters cannot close or break Mermaid syntax
Then an unresolved target renders as an explicit placeholder
Then a colliding token or a diagram past maxNodesPerDiagram = 64 or maxEdgesPerDiagram = 128 is refused by name while every in-bound diagram still publishes
Then generated/mermaid/ is the only current Mermaid root
Then a clean independent render is byte-identical
Then validation errors label the index as a diagnostic projection
Then no whole-graph diagram is emitted

Verifier bindings

• test:protocol.mermaid-view · verifies bounded deterministic Mermaid projection and publication · anchored · test anchor binding present · test/mermaid-render.test.ts:20

  External run evidence from test/mermaid-render.test.ts

  Test anchors: test:protocol.mermaid-view. Specs verified by those bindings: spec:consumers.mermaid-view.

  Run 1: external run evidence from vitest 4.1.10

  Build: CI 380 · Branch: feature/roadmap-and-slices-v0 · Commit: 34909918bf0be0e849959644401797191cae379f · Start: 2026-10-22T17:40:31.456Z · Stop: 2026-10-22T17:42:16.171Z

  Name	Suite	Result	Duration
  renders every checkout-v1 Spec, Pack, and index page as the reviewed golden	the bounded Mermaid projection	passed	88.81 ms
  is byte-identical under node and edge permutation with code-unit sorted records	the bounded Mermaid projection	passed	1.29 ms
  labels the index as diagnostic when validation errors are present	the bounded Mermaid projection	passed	1.1 ms
  escapes hostile labels without changing injective full-ID machine tokens	the bounded Mermaid projection	passed	0.78 ms
  refuses a diagram whose neighbor has a duplicated id and names that neighbor	the bounded Mermaid projection	passed	0.86 ms
  names each duplicated root in its own refusal	the bounded Mermaid projection	passed	0.36 ms
  keeps one-hop cycles, disconnected Pack members, foreign edges, and dangling placeholders without emitting a whole graph	the bounded Mermaid projection	passed	0.59 ms
  withholds only the affected diagram when identities collide or a bound overflows	the bounded Mermaid projection	passed	2.14 ms
  accepts diagrams exactly at the 64-node and 128-edge bounds	the bounded Mermaid projection	passed	1.99 ms
  withholds an oversized Pack and still renders every in-bound Spec diagram	the bounded Mermaid projection	passed	10.84 ms

Requirement drawing

• Declared verifying examples: no declared verifying example.

Decisions

• The shipped projections stay frozen

  Re-specifying the shipped Design Review, census, Mermaid, or Gherkin projection is refused. These four projections are the ruled read surfaces over the one graph. A later decision Spec that supersedes this one replaces the ruling whole; a decision Spec that refines this one narrows it for one projection or one rendering and leaves the rest frozen. Either passes the ADR three-part test.

• component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  • component:protocol.adapters · external runtime and source adapters · src/adapters/vitest.ts:23 · layer adapter · context protocol
  • component:protocol.codegen · contracts and registrar output · src/codegen/contracts.ts:633 · layer application · context protocol
  • component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · context protocol
  • component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol
  • component:protocol.import · canonical conversion with a fidelity boundary · src/import/import.ts:45 · layer application · context protocol
  • component:protocol.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol
  • component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol
  • component:protocol.reader · the typed graph contract and body evaluator · src/reader/reader.ts:671 · layer application · context protocol
  • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:72 · layer domain · context protocol
• component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol

  Uses

  • component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · context protocol
  • component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol
  • component:protocol.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol
  • component:protocol.notation · the leaf step codec · src/notation/slots.ts:261 · layer domain · context protocol
  • component:protocol.reader · the typed graph contract and body evaluator · src/reader/reader.ts:671 · layer application · context protocol
  • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:72 · layer domain · context protocol
• impl:protocol.mermaid-view · renders bounded Spec one-hop and Pack membership diagrams · src/projections/mermaid.ts:14

  Component: component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol

  Uses

  None.

• impl:protocol.mermaid-view-cli · publishes Mermaid through the explicit sdp mermaid surface · src/cli/mermaid-command.ts:82

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.