Spec Studio

Committed source derives byte-identical output

spec:extraction.determinismConstraint (NFR) · featureready floor ready

Changed since the base graph base da4b141: relation.refines:spec:extraction.derive-graph; relation.refines:spec:protocol.self-hosting

Base input: schema 0.11.0, 405 Specs.

Packs: pack:self-hosting-v1

Design: no design entries · no pinned declarations · no decisions

Findings: no errors, no warnings

specs/extraction/determinism.sdp.md

No open questions and no blocking questions; implementation binding present, verifier binding present, and expected-outcome oracle none.

Intent
outcome
Make regeneration independent of location and prior generated state.
Behavior
rule line 23 · specs/extraction/determinism.sdp.md:23
Nodes sort by id and edges by from, type and to. Generated graph and contract metadata contains no wall-clock timestamp or run-specific hash. Graph file locations are extraction-root-relative POSIX paths, never absolute paths; authored section text remains as authored.
rule line 24 · specs/extraction/determinism.sdp.md:24
sdp build --check-clean repeats extraction and contract generation independently, failing on any graph or generated-contract byte divergence.

2 unkeyed rules.

Constraints
Flavor
quality
Statement
Two clean derivations of the same committed source produce byte-identical generated trees.
Target
sha256(tree@run1) == sha256(tree@run2)
Measurable by
test:protocol.extraction-determinism
Measured value
not tracked
Verification

Verifier bindings

  • test:protocol.extraction-determinism · clean-repo pipeline determinism verifies byte-identical output · anchored · test anchor binding present · test/cli.test.ts:2348

    External run evidence from test/cli.test.ts

    Test anchors: test:protocol.engine-provenance, test:protocol.extraction-determinism, test:protocol.projections-model.publication, test:protocol.regenerability, test:protocol.validate-watch. Specs verified by those bindings: spec:consumers.engine-provenance, spec:consumers.projections-model, spec:consumers.validate-watch, spec:extraction.determinism, spec:extraction.regenerability.

    Run 2: external run evidence from vitest 4.1.10

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

    NameSuiteResultDuration
    prints the exact help text for no argssdp clipassed1.39 ms
    points operators to the shipped on-ramps and Protocol corpussdp clipassed1.4 ms
    describes both anchor forms and non-failing warnings in helpsdp clipassed0.33 ms
    prints the exact help text for --helpsdp clipassed0.14 ms
    builds the checkout-v1 example: writes graph, contracts, and registrar manifest atomicallysdp clipassed92.85 ms
    invalidates an existing Design Review when build replaces its source graphsdp clipassed51.1 ms
    views the self-hosting corpus from the default repository rootsdp clipassed8406.8 ms
    renders contracts warnings through the one formatter and counts them in the summarysdp clipassed6.91 ms
    withholds case-colliding contract paths with a warning: graph kept, nothing gatessdp clipassed3.45 ms
    passes --check-clean on the example (determinism self-check through the CLI)sdp clipassed28.36 ms
    end-to-end determinism self-check: delete generated/, rebuild, byte-identicalsdp clipassed106.14 ms
    fails clean on a root that is not a directory: one line, exit 1, never a stack tracesdp clipassed0.32 ms
    rejects an unknown option: one line, exit 1, nothing runssdp clipassed0.1 ms
    accepts repeatable --exclude paths for buildsdp clipassed3.25 ms
    accepts repeatable --exclude paths for validatesdp clipassed3.57 ms
    accepts repeatable --exclude paths for viewsdp clipassed4.61 ms
    uses the identical normalized exclusions in both --check-clean extractionssdp clipassed4.99 ms
    refuses invalid --exclude path "" before build writessdp clipassed0.75 ms
    refuses invalid --exclude path "." before build writessdp clipassed0.21 ms
    refuses invalid --exclude path "./explorations" before build writessdp clipassed0.27 ms
    refuses invalid --exclude path "explorations/" before build writessdp clipassed0.16 ms
    refuses invalid --exclude path "/explorations" before build writessdp clipassed0.19 ms
    refuses invalid --exclude path "../x" before build writessdp clipassed0.18 ms
    refuses invalid --exclude path "a/../b" before build writessdp clipassed0.13 ms
    refuses invalid --exclude path "a//b" before build writessdp clipassed0.12 ms
    refuses invalid --exclude path "a\\b" before build writessdp clipassed0.21 ms
    refuses a missing --exclude operand before build writessdp clipassed0.28 ms
    names a flag supplied as an --exclude operand before build writessdp clipassed0.19 ms
    documents repeatable --exclude paths in helpsdp clipassed0.06 ms
    rejects a second root argument: one line, exit 1, nothing runssdp clipassed0.16 ms
    notes an empty authored model: zero spec files still builds and exits 0, but says where it lookedsdp clipassed0.59 ms
    renders a finding's location exactly once, from the structured fields: file:line — [severity]sdp clipassed2.19 ms
    renders a Gherkin parser failure through the public CLIsdp clipassed1.24 ms
    exits 1, writes nothing, and removes a stale graph.json on a hard-error corpussdp clipassed1.87 ms
    fails build on an integer-like design key holding a static valuesdp clipassed1.25 ms
    fails build on an integer-like design key holding a non-static valuesdp clipassed1.05 ms
    fails build on an integer-like design key holding a methodsdp clipassed1.09 ms
    fails build on an integer-like design key holding an accessorsdp clipassed1.22 ms
    fails --check-clean on a diverging second extraction: exit 1, the stale graph.json removedsdp clipassed7.21 ms
    fails --check-clean on a diverging second contract generation: exit 1, no artifact survivessdp clipassed18.15 ms
    owns the contracts tree wholesale: with nothing to generate, a stale contracts dir is removedsdp clipassed2.71 ms
    reconciles a registrar sibling that a later generation no longer owessdp clipassed19.57 ms
    fails --check-clean on registrar-byte drift and removes the uncertified known setsdp clipassed26.76 ms
    passes --check-clean without a prior manifest when no registrars are owedsdp clipassed3.91 ms
    fails --check-clean on registrar manifest whitespace driftsdp clipassed26 ms
    fails --check-clean on registrar manifest ignored property driftsdp clipassed26.54 ms
    removes graph, contracts, manifest, and registrar siblings after a staged write failuresdp clipassed19.02 ms
    fails clean when extraction throws past discovery: one line, exit 1, the stale graph.json removedsdp clipassed0.6 ms
    fails clean when generated exists as a file: one line each for build and view, never a stack tracesdp clipassed5.38 ms
    names the survivor when a recovery-path removal is denied: a stale artifact never silently reads as currentsdp clipassed0.56 ms
    stops a build when an existing Design Review cannot be invalidatedsdp clipassed1.62 ms
    fails clean when the checks throw: one line, exit 1, the built graph.json stayssdp clipassed2.52 ms
    suppresses the empty-model note when spec files were found but none reified — a failed file is not an absent onesdp clipassed1.52 ms
    treats a root of only ordinary .feature files as an empty authored model, not a missing-identity errorsdp clipassed0.65 ms
    suppresses the empty-model note when a failed .sdp.gherkin finding.file matches the carrier suffix predicatesdp clipassed1.01 ms
    builds a mixed root with one .sdp.gherkin carrier and ignores the ordinary .feature siblingsdp clipassed0.88 ms
    removes the temp twin on a failed build and a failed view — no partial .tmp artifact survivessdp clipassed8.95 ms
    recognizes the published-bin path: a .bin-style symlink resolves to the entry modulesdp clipassed0.43 ms
    exits 0 quietly on a stdout EPIPE and stays fatal for any other stream errorsdp clipassed0.53 ms
    validates the example: exit 0, the artifact written, and no warningsdp clipassed28.78 ms
    gates on the checks, not the build: a clean-building broken link validates to exit 1 with the artifact keptsdp clipassed2.67 ms
    short-circuits the checks on extraction hard errors: validate keeps build semanticssdp clipassed1.64 ms
    prints help plus an unknown-command errorsdp clipassed0.13 ms
    views the example: validate + the Design Review written, with no warningsdp clipassed33.87 ms
    owns the view directory wholesale: a stale page does not survive a re-rendersdp clipassed15.8 ms
    regenerates the view byte-identically: delete generated/, re-view, same bytessdp clipassed24.79 ms
    writes the view even when checks fail: findings render in it, the exit code is validate'ssdp clipassed2.06 ms
    keeps build semantics on extraction hard errors: no graph, no view, stale view removedsdp clipassed1.87 ms
    fails view --check-clean on a diverging second render: exit 1, the stale view removedsdp clipassed6.53 ms
    fails clean when the render throws: one line on stderr, exit 1, the stale view removedsdp clipassed2.71 ms
    closes the compiled watch process with exit 0 after operator SIGINTsdp validate --watchpassed299.82 ms
    documents --watch as a validate-only authoring loopsdp validate --watchpassed0.19 ms
    rejects --watch on build with a named error and no watchersdp validate --watchpassed0.18 ms
    rejects --watch on view with a named error and no watchersdp validate --watchpassed0.06 ms
    rejects --watch on census with a named error and no watchersdp validate --watchpassed0.05 ms
    rejects --watch on mermaid with a named error and no watchersdp validate --watchpassed0.05 ms
    rejects --watch on gherkin with a named error and no watchersdp validate --watchpassed0.04 ms
    rejects --watch on import with a named error and no watchersdp validate --watchpassed0.17 ms
    rejects --watch on new with a named error and no watchersdp validate --watchpassed0.2 ms
    rejects --watch on q with a named error and no watchersdp validate --watchpassed0.18 ms
    rejects --watch --check-clean with a named error and no watchersdp validate --watchpassed0.12 ms
    installs the watcher before the first validation cyclesdp validate --watchpassed4.45 ms
    catches an edit during the first cycle with exactly one coalesced rerunsdp validate --watchpassed5.23 ms
    coalesces a burst during an active cycle into exactly one rerunsdp validate --watchpassed4.92 ms
    prints validation findings and keeps watching until abort exits 0sdp validate --watchpassed2.68 ms
    ignores generated, dist, node_modules, coverage, dot directories, and configured excludessdp validate --watchpassed5.24 ms
    coalesces production-shaped events from later turns into one pending rerunsdp validate --watchpassed7.83 ms
    does not natively subscribe to excluded or generated subtreessdp validate --watchpassed69.25 ms
    routes a native watcher error through a typed channel and closes oncesdp validate --watchpassed3.1 ms
    clean-repo determinism: the full pipeline at a different absolute path is byte-identicalnot recordedpassed67.67 ms
    prints one line naming the package version and the recorded commit, and exits 0sdp --versionpassed0.49 ms
    names the commit unknown when the build recorded none or recorded something elsesdp --versionpassed0.33 ms
    reads the version from the package manifest two directories above the CLI modulesdp --versionpassed0.38 ms
    documents --version and --params in the usage textsdp --versionpassed0.14 ms
    records the checked-out commit at build time, or unknown when git cannot name onesdp --versionpassed11.15 ms
    publishes the commit the build step reads from git beside the CLIsdp --versionpassed0.9 ms
    builds commit metadata from a substituted git archive extracted without .gitsdp --versionpassed64.59 ms
    uses only a full archive commit when git gives none, keeping git firstsdp --versionpassed0.68 ms
    answers from the compiled CLI with the commit its build recorded beside itsdp --versionpassed327.1 ms
    runs recipe 4 as shipped, its changed files passed with --params @PATHa shipped recipe file through the compiled CLIpassed363.4 ms
Design view

Requirement drawing

  • Declared verifying examples: no declared verifying example.
Requirement drawing for spec:extraction.determinism
The diagram as text
  • spec:extraction.determinism: Committed source derives byte-identical output · declared Spec
  • spec:extraction.regenerability: Generated artifacts are disposable projections · declared Spec
  • spec:extraction.derive-graph: Carrier reification derives the one graph · declared Spec
  • impl:protocol.build-pipeline-emit: stages build outputs, checks determinism and invalidates projections · anchored code · src/cli/build-command.ts:251
  • impl:protocol.static-reification: reifies authored carriers from the AST and never evaluates them · anchored code · src/extract/reify.ts:2139
  • test:protocol.extraction-determinism: clean-repo pipeline determinism verifies byte-identical output · anchored test binding · binding present · test/cli.test.ts:2348
  • test:protocol.regenerability: delete and rebuild tests verify byte-identical generated artifacts · anchored test binding · binding present · test/cli.test.ts:53
  • spec:extraction.determinism refines spec:extraction.derive-graph · declared — deterministic output constrains the derivation capability
  • spec:extraction.regenerability refines spec:extraction.determinism · declared
  • impl:protocol.build-pipeline-emit satisfies spec:extraction.determinism · anchored
  • impl:protocol.build-pipeline-emit satisfies spec:extraction.regenerability · anchored
  • impl:protocol.static-reification satisfies spec:extraction.determinism · anchored
  • test:protocol.extraction-determinism verifies spec:extraction.determinism · anchored
  • test:protocol.regenerability verifies spec:extraction.regenerability · anchored
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred and chosen syntax: requirementDiagram; exact refines, satisfies and verifies, with claim words in nodes and per-edge comments.

Decisions

No decision record named.

Runtime
  • 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.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · context protocol

    Uses

    • 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.validate · one finding currency and ordered checks · src/validate/validators.ts:72 · layer domain · context protocol
  • impl:protocol.build-pipeline-emit · stages build outputs, checks determinism and invalidates projections · src/cli/build-command.ts:251

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

    Uses

    None.

  • impl:protocol.static-reification · reifies authored carriers from the AST and never evaluates them · src/extract/reify.ts:2139

    Component: component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · context protocol

    Uses

    None.

Runtime observation: not tracked.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact
Relations of spec:extraction.determinism
The diagram as text
  • spec:consumers.design-diff: Designs are compared between a base commit and the working tree at entry grain
  • spec:consumers.engine-provenance: The CLI names the engine that produced a result
  • spec:consumers.obsidian-vault: An Obsidian vault lets a person iterate on designs from the one graph
  • spec:consumers.spec-studio: The Spec Studio is a static HTML workbench over the one graph
  • spec:consumers.spec-studio.data: The Studio renders from the reader's values and embeds only what its script reads
  • spec:consumers.spec-studio.data.inputs: The Studio reads two named inputs beside the graph, a base graph and run records
  • spec:consumers.spec-studio.diagrams: A diagram is laid out from graph values into SVG with a text equivalent
  • spec:consumers.spec-studio.export: A Pack exports as one file, and every page prints as a document
  • spec:consumers.spec-studio.publisher: sdp studio publishes the Studio as one page set
  • spec:consumers.spec-studio.sharing: A Studio build is stamped and shared from a static host
  • spec:consumers.wholesale-view-rewrite: Every view run rewrites the view wholesale
  • spec:decisions.studio-diagram-renderer: The engine lays out every Studio diagram as static SVG when the page set is built
  • spec:extraction.derive-graph: Carrier reification derives the one graph
  • spec:extraction.determinism: Committed source derives byte-identical output
  • spec:extraction.entry-citations: The graph records where anchored source cites an entry address
  • spec:extraction.entry-locations: The graph records where each addressable entry is written
  • spec:extraction.pack-member-order: A Pack node keeps its members in authored order
  • spec:extraction.regenerability: Generated artifacts are disposable projections
  • spec:extraction.determinism refines spec:extraction.derive-graph · declared — deterministic output constrains the derivation capability
  • spec:consumers.design-diff constrainedBy spec:extraction.determinism · declared — equal sources derive equal graphs, so a difference records a source change
  • spec:consumers.engine-provenance constrainedBy spec:extraction.determinism · declared
  • spec:consumers.obsidian-vault constrainedBy spec:extraction.determinism · declared
  • spec:consumers.spec-studio constrainedBy spec:extraction.determinism · declared
  • spec:consumers.spec-studio.data constrainedBy spec:extraction.determinism · declared
  • spec:consumers.spec-studio.data.inputs constrainedBy spec:extraction.determinism · declared
  • spec:consumers.spec-studio.diagrams constrainedBy spec:extraction.determinism · declared
  • spec:consumers.spec-studio.export constrainedBy spec:extraction.determinism · declared
  • spec:consumers.spec-studio.publisher constrainedBy spec:extraction.determinism · declared
  • spec:consumers.spec-studio.sharing constrainedBy spec:extraction.determinism · declared
  • spec:extraction.derive-graph constrainedBy spec:extraction.determinism · declared
  • spec:extraction.entry-citations constrainedBy spec:extraction.determinism · declared
  • spec:extraction.entry-locations constrainedBy spec:extraction.determinism · declared
  • spec:extraction.pack-member-order constrainedBy spec:extraction.determinism · declared
  • spec:consumers.wholesale-view-rewrite dependsOn spec:extraction.determinism · declared — check-clean refuses when two renders of one graph differ
  • spec:decisions.studio-diagram-renderer dependsOn spec:extraction.determinism · declared — a diagram laid out from graph values alone keeps one graph to one set of bytes
  • spec:extraction.regenerability refines spec:extraction.determinism · declared
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.

Rests on

Rested on by

Distance 1

Distance 2

Distance 3

Distance 4

Distance 5

Distance 6

Distance 7

Distance 8

Distance 9

Distance 10

Distance 11

Relations

Relation and directionOther endClaimReasonExercised keys
refines · outgoingCarrier reification derives the one graph
spec:extraction.derive-graph · resolves		declareddeterministic output constrains the derivation capabilityNone
constrainedBy · incomingDesigns are compared between a base commit and the working tree at entry grain
spec:consumers.design-diff · resolves		declaredequal sources derive equal graphs, so a difference records a source changeNone
constrainedBy · incomingThe CLI names the engine that produced a result
spec:consumers.engine-provenance · resolves		declaredNoneNone
constrainedBy · incomingAn Obsidian vault lets a person iterate on designs from the one graph
spec:consumers.obsidian-vault · resolves		declaredNoneNone
constrainedBy · incomingThe Spec Studio is a static HTML workbench over the one graph
spec:consumers.spec-studio · resolves		declaredNoneNone
constrainedBy · incomingThe Studio renders from the reader's values and embeds only what its script reads
spec:consumers.spec-studio.data · resolves		declaredNoneNone
constrainedBy · incomingThe Studio reads two named inputs beside the graph, a base graph and run records
spec:consumers.spec-studio.data.inputs · resolves		declaredNoneNone
constrainedBy · incomingA diagram is laid out from graph values into SVG with a text equivalent
spec:consumers.spec-studio.diagrams · resolves		declaredNoneNone
constrainedBy · incomingA Pack exports as one file, and every page prints as a document
spec:consumers.spec-studio.export · resolves		declaredNoneNone
constrainedBy · incomingsdp studio publishes the Studio as one page set
spec:consumers.spec-studio.publisher · resolves		declaredNoneNone
constrainedBy · incomingA Studio build is stamped and shared from a static host
spec:consumers.spec-studio.sharing · resolves		declaredNoneNone
constrainedBy · incomingCarrier reification derives the one graph
spec:extraction.derive-graph · resolves		declaredNoneNone
constrainedBy · incomingThe graph records where anchored source cites an entry address
spec:extraction.entry-citations · resolves		declaredNoneNone
constrainedBy · incomingThe graph records where each addressable entry is written
spec:extraction.entry-locations · resolves		declaredNoneNone
constrainedBy · incomingA Pack node keeps its members in authored order
spec:extraction.pack-member-order · resolves		declaredNoneNone
dependsOn · incomingEvery view run rewrites the view wholesale
spec:consumers.wholesale-view-rewrite · resolves		declaredcheck-clean refuses when two renders of one graph differNone
dependsOn · incomingThe engine lays out every Studio diagram as static SVG when the page set is built
spec:decisions.studio-diagram-renderer · resolves		declareda diagram laid out from graph values alone keeps one graph to one set of bytesNone
refines · incomingGenerated artifacts are disposable projections
spec:extraction.regenerability · resolves		declaredNoneNone

Bindings

Implementation binding: present

  • impl:protocol.build-pipeline-emit · stages build outputs, checks determinism and invalidates projections · src/cli/build-command.ts:251 · role service · component component:protocol.cli · layer edge · context protocol
  • impl:protocol.static-reification · reifies authored carriers from the AST and never evaluates them · src/extract/reify.ts:2139 · role extractor · component component:protocol.extract · layer application · context protocol

Design reference: none

Verifier binding: present

  • test:protocol.extraction-determinism · clean-repo pipeline determinism verifies byte-identical output · anchored · test/cli.test.ts:2348 · test anchor

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.