Spec Studio

The build pipeline has one ordered flow

spec:extraction.build-pipelineWorkflow · featureready floor ready

Packs: pack:self-hosting-v1

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

Findings: no errors, no warnings

specs/extraction/build-pipeline.sdp.md

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

Intent
outcome
Turn authored carriers into one graph and the artifacts derived from it, with every command that checks reading that same graph.
Workflow
flow line 18 · specs/extraction/build-pipeline.sdp.md:18
The build discovers carriers, reifies them, derives the graph, stops on any extraction error, and emits the graph, the executable contracts and the registrars without running the graph checks.
flow line 19 · specs/extraction/build-pipeline.sdp.md:19
Validation runs the build, then checks the graph that build derived and reports every finding, exiting nonzero on an error.
flow line 20 · specs/extraction/build-pipeline.sdp.md:20
Each projection verb runs validation, then renders its root from that same graph and publishes it whatever the findings, keeping validation's exit code.
flow line 21 · specs/extraction/build-pipeline.sdp.md:21
A query discovers, reifies and derives in process, stops on any extraction error, checks the graph, and hands the body the reader, the raw graph and the report from that one derivation, writing nothing.
rule.oneSeam line 22 · specs/extraction/build-pipeline.sdp.md:22
Every command that checks the graph checks the graph its own run derived, through the one validation seam; sdp build stops at extraction checks.

spec:extraction.build-pipeline.same-invocation · enabled

rule.emitOnClean line 23 · specs/extraction/build-pipeline.sdp.md:23
sdp build publishes derived outputs only after extraction reports no error. A warning does not fail the build; a contract-generation warning may withhold the contract or registrar it names under the executable-contracts law.

no example exercises it

rule.stagedPublication line 24 · specs/extraction/build-pipeline.sdp.md:24
Before replacing current outputs, sdp build stages the graph, the owed contracts, the registrar manifest, each registrar sibling whose bytes differ from the file on disk, and the imports when --imports is supplied, in temporary locations; a sibling whose bytes are unchanged is left untouched, with no temporary write and no rename. It then publishes the staged set and removes registrar siblings no longer owed.

no example exercises it

rule.failedPublication line 25 · specs/extraction/build-pipeline.sdp.md:25
On failure, sdp build removes its graph, contracts, manifest, temporary outputs and the confined registrar siblings known from the previous and new manifests. It removes imports only when that invocation requested them. A failed removal names the surviving path and says it must not be read as current; an untrusted registrar path is outside generated ownership.

no example exercises it

4 unkeyed rules.

Verifying examples

One query invocation shares its extracted graph and validation result · spec:extraction.build-pipeline.same-invocation · ready floor ready

Executable Spec

Given an extraction root containing the isolated spec {specId: "spec:probe.same-invocation"}
When one query invocation reads the reader, raw graph, and validation report
Then the query exits {exitCode: 0}
Then the reader and the raw graph both return the spec {returnedSpecId: "spec:probe.same-invocation"}
Then the validation report names the same subject {findingSubjectId: "spec:probe.same-invocation"}

Open example

Example space

Given an extraction root containing the isolated spec {specId:string}
When one query invocation reads the reader, raw graph, and validation report
Then the query exits {exitCode:number}
Then the reader and the raw graph both return the spec {returnedSpecId:string}
Then the validation report names the same subject {findingSubjectId:string}
Verification

Verifier bindings

  • spec:extraction.build-pipeline.same-invocation · One query invocation shares its extracted graph and validation result · declared · example enabled · specs/extraction/build-pipeline.same-invocation.sdp.md

    External run evidence from test/self-hosting-extraction.test.ts

    Test anchors: test:protocol.build-pipeline.same-invocation, test:protocol.example-runner.red-step-naming, test:protocol.example-runner.step-order, test:protocol.excludes.refused-path, test:protocol.excludes.segment-boundary, test:protocol.executable-contracts.case-colliding-path, test:protocol.executable-contracts.concreteness-refusal, test:protocol.executable-contracts.multi-entry-example, test:protocol.schema-versioning.declared-version. Specs verified by those bindings: spec:extraction.build-pipeline, spec:extraction.build-pipeline.same-invocation, spec:extraction.example-runner, spec:extraction.example-runner.red-step-naming, spec:extraction.example-runner.step-order, spec:extraction.excludes, spec:extraction.excludes.refused-path, spec:extraction.excludes.segment-boundary, spec:extraction.executable-contracts, spec:extraction.executable-contracts.case-colliding-path, spec:extraction.executable-contracts.concreteness-refusal, spec:extraction.executable-contracts.multi-entry-example, spec:extraction.schema-versioning, spec:extraction.schema-versioning.declared-version.

    Run 1: external run evidence from vitest 4.1.10

    Build: CI 391 · Branch: cursor/media-plan-and-articles-09b1 · Commit: 076cd4f1f85640d8236e5cca1bffffa68ab79a33 · Start: 2026-10-31T15:32:20.471Z · Stop: 2026-10-31T15:34:02.073Z

    NameSuiteResultDuration
    executes the bound example against a fresh worldOne query invocation shares its extracted graph and validation result (spec:extraction.build-pipeline.same-invocation)passed16.91 ms
    executes the bound example against a fresh worldA prefix excludes its own tree and leaves a similar sibling standing (spec:extraction.excludes.segment-boundary)passed1.58 ms
    executes the bound example against a fresh worldA Windows-drive absolute path is refused rather than normalized (spec:extraction.excludes.refused-path)passed1.08 ms
    executes the bound example against a fresh worldA derived payload carries a schema version its consumer can read (spec:extraction.schema-versioning.declared-version)passed0.5 ms
    executes the bound example against a fresh worldAn unbound slot in a used step earns no step contract (spec:extraction.executable-contracts.concreteness-refusal)passed2.41 ms
    executes the bound example against a fresh worldA second structured entry is named, never left silently inert (spec:extraction.executable-contracts.multi-entry-example)passed2.37 ms
    executes the bound example against a fresh worldA case-only path collision withholds the whole contracts tree (spec:extraction.executable-contracts.case-colliding-path)passed0.95 ms
    executes the bound example against a fresh worldA repeated step runs its one handler at each occurrence, in contract order (spec:extraction.example-runner.step-order)passed0.4 ms
    executes the bound example against a fresh worldA red step names itself before the assertion detail (spec:extraction.example-runner.red-step-naming)passed0.45 ms

Example space

  • specId · string · declared by an extraction root containing the isolated spec {specId}

Bound points

ExamplespecId
spec:extraction.build-pipeline.same-invocation"spec:probe.same-invocation"

Oracle binding: none

Coverage

specId: "spec:probe.same-invocation" · spec:extraction.build-pipeline.same-invocation · not enumerable

Unbound

  • specId: None
Design view

Requirement drawing

Requirement drawing for spec:extraction.build-pipeline
  • E6: refines · declared — the build orchestrates derivation and publication of the one graph

Scroll horizontally to read the whole drawing.

The diagram as text
  • spec:extraction.build-pipeline: The build pipeline has one ordered flow · declared Spec
  • spec:extraction.build-pipeline.same-invocation: One query invocation shares its extracted graph and validation result · declared Spec
  • spec:extraction.executable-contracts: The build derives step and space contracts from graph examples · declared Spec
  • spec:carrier.step-keys.conflicting-example-key-withheld: An example marker that disagrees with its vocabulary withholds the contract · declared Spec
  • spec:carrier.step-keys.key-equal-to-a-skeleton-withheld: A step key equal to another step's skeleton withholds the contract · declared Spec
  • spec:carrier.step-keys.reworded-keyed-step-stays-bound: A keyed step reworded in its vocabulary and its example keeps its binding · declared Spec
  • spec:carrier.step-keys.reworded-unkeyed-step-breaks: The same rewording without a key breaks the binding · declared Spec
  • spec:extraction.executable-contracts.case-colliding-path: A case-only path collision withholds the whole contracts tree · declared Spec
  • spec:extraction.executable-contracts.concreteness-refusal: An unbound slot in a used step earns no step contract · declared Spec
  • spec:extraction.executable-contracts.multi-entry-example: A second structured entry is named, never left silently inert · declared Spec
  • spec:carrier.step-keys: An example step may carry a key that survives rewording · declared Spec
  • spec:extraction.derive-graph: Carrier reification derives the one graph · declared Spec
  • spec:extraction.contract-declarations: Pinned declarations give an adopter a derived module to typecheck · declared Spec
  • spec:extraction.executable-examples: Bound examples execute their authored steps · declared Spec
  • component:protocol.cli: entry points, shared build and publication · anchored code · src/cli/build-command.ts:32
  • impl:protocol.build-pipeline-emit: stages build outputs, checks determinism and invalidates projections · anchored code · src/cli/build-command.ts:251
  • impl:protocol.build-pipeline-query: runQuery reads one body, derives the graph once for the reader, raw graph and report, and prints the return or refuses on stderr · anchored code · src/cli/q-command.ts:212
  • impl:protocol.example-space: resolves example-space vocabulary for contracts and floors · anchored code · src/graph/example-space.ts:117
  • impl:protocol.executable-contracts: derives step and example-space contracts from the graph · anchored code · src/codegen/contracts.ts:647
  • test:protocol.build-pipeline.same-invocation: the same-invocation point verifies the query extraction and validation seam · anchored test binding · binding present · test/self-hosting-extraction.test.ts:169
  • test:protocol.executable-contracts.case-colliding-path: the collision point verifies the all-or-nothing withholding · anchored test binding · binding present · test/self-hosting-extraction.test.ts:593
  • test:protocol.executable-contracts.concreteness-refusal: the concreteness point verifies the unbound-slot refusal · anchored test binding · binding present · test/self-hosting-extraction.test.ts:575
  • test:protocol.executable-contracts.multi-entry-example: the multi-entry point verifies the named second entry · anchored test binding · binding present · test/self-hosting-extraction.test.ts:584
  • test:protocol.step-keys.conflicting-example-key-withheld: test:protocol.step-keys.conflicting-example-key-withheld · anchored test binding · binding present · test/self-hosting-step-keys.test.ts:26
  • test:protocol.step-keys.key-equal-to-a-skeleton-withheld: test:protocol.step-keys.key-equal-to-a-skeleton-withheld · anchored test binding · binding present · test/self-hosting-step-keys.test.ts:120
  • test:protocol.step-keys.reworded-keyed-step-stays-bound: test:protocol.step-keys.reworded-keyed-step-stays-bound · anchored test binding · binding present · test/self-hosting-step-keys.test.ts:308
  • test:protocol.step-keys.reworded-unkeyed-step-breaks: test:protocol.step-keys.reworded-unkeyed-step-breaks · anchored test binding · binding present · test/self-hosting-step-keys.test.ts:355
  • spec:carrier.step-keys.conflicting-example-key-withheld refines spec:carrier.step-keys · declared
  • spec:carrier.step-keys.conflicting-example-key-withheld verifies spec:carrier.step-keys · declared
  • spec:carrier.step-keys.conflicting-example-key-withheld verifies spec:extraction.executable-contracts · declared
  • spec:carrier.step-keys.key-equal-to-a-skeleton-withheld refines spec:carrier.step-keys · declared
  • spec:carrier.step-keys.key-equal-to-a-skeleton-withheld verifies spec:carrier.step-keys · declared
  • spec:carrier.step-keys.key-equal-to-a-skeleton-withheld verifies spec:extraction.executable-contracts · declared
  • spec:carrier.step-keys.reworded-keyed-step-stays-bound refines spec:carrier.step-keys · declared
  • spec:carrier.step-keys.reworded-keyed-step-stays-bound verifies spec:carrier.step-keys · declared
  • spec:carrier.step-keys.reworded-keyed-step-stays-bound verifies spec:extraction.executable-contracts · declared
  • spec:carrier.step-keys.reworded-unkeyed-step-breaks refines spec:carrier.step-keys · declared
  • spec:carrier.step-keys.reworded-unkeyed-step-breaks verifies spec:carrier.step-keys · declared
  • spec:carrier.step-keys.reworded-unkeyed-step-breaks verifies spec:extraction.executable-contracts · declared
  • spec:extraction.build-pipeline refines spec:extraction.derive-graph · declared — the build orchestrates derivation and publication of the one graph
  • spec:extraction.build-pipeline.same-invocation refines spec:extraction.build-pipeline · declared
  • spec:extraction.build-pipeline.same-invocation verifies spec:extraction.build-pipeline · declared
  • spec:extraction.contract-declarations refines spec:extraction.executable-contracts · declared
  • spec:extraction.executable-contracts refines spec:extraction.build-pipeline · declared
  • spec:extraction.executable-contracts refines spec:extraction.executable-examples · declared — typed contracts carry the authored steps and example space into execution
  • spec:extraction.executable-contracts.case-colliding-path refines spec:extraction.executable-contracts · declared
  • spec:extraction.executable-contracts.case-colliding-path verifies spec:extraction.executable-contracts · declared
  • spec:extraction.executable-contracts.concreteness-refusal refines spec:extraction.executable-contracts · declared
  • spec:extraction.executable-contracts.concreteness-refusal verifies spec:extraction.executable-contracts · declared
  • spec:extraction.executable-contracts.multi-entry-example refines spec:extraction.executable-contracts · declared
  • spec:extraction.executable-contracts.multi-entry-example verifies spec:extraction.executable-contracts · declared
  • component:protocol.cli satisfies spec:extraction.build-pipeline · anchored
  • impl:protocol.build-pipeline-emit satisfies spec:extraction.build-pipeline · anchored
  • impl:protocol.build-pipeline-query satisfies spec:extraction.build-pipeline · anchored
  • impl:protocol.example-space satisfies spec:extraction.executable-contracts · anchored
  • impl:protocol.executable-contracts satisfies spec:extraction.executable-contracts · anchored
  • test:protocol.build-pipeline.same-invocation verifies spec:extraction.build-pipeline.same-invocation · anchored
  • test:protocol.executable-contracts.case-colliding-path verifies spec:extraction.executable-contracts.case-colliding-path · anchored
  • test:protocol.executable-contracts.concreteness-refusal verifies spec:extraction.executable-contracts.concreteness-refusal · anchored
  • test:protocol.executable-contracts.multi-entry-example verifies spec:extraction.executable-contracts.multi-entry-example · anchored
  • test:protocol.step-keys.conflicting-example-key-withheld verifies spec:carrier.step-keys.conflicting-example-key-withheld · anchored
  • test:protocol.step-keys.key-equal-to-a-skeleton-withheld verifies spec:carrier.step-keys.key-equal-to-a-skeleton-withheld · anchored
  • test:protocol.step-keys.reworded-keyed-step-stays-bound verifies spec:carrier.step-keys.reworded-keyed-step-stays-bound · anchored
  • test:protocol.step-keys.reworded-unkeyed-step-breaks verifies spec:carrier.step-keys.reworded-unkeyed-step-breaks · anchored
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: requirementDiagram. Chosen syntax: flowchart TB because folds require exact labels unavailable in requirement syntax.

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
  • 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.build-pipeline-query · runQuery reads one body, derives the graph once for the reader, raw graph and report, and prints the return or refuses on stderr · src/cli/q-command.ts:212

    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.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact
Relations of spec:extraction.build-pipeline
The diagram as text
  • spec:extraction.build-pipeline: The build pipeline has one ordered flow
  • spec:extraction.build-pipeline.same-invocation: One query invocation shares its extracted graph and validation result
  • spec:extraction.derive-graph: Carrier reification derives the one graph
  • spec:extraction.executable-contracts: The build derives step and space contracts from graph examples
  • spec:extraction.runnable-modules: Derived runnable modules freeze the registrar interface
  • spec:extraction.build-pipeline dependsOn spec:extraction.derive-graph · declared
  • spec:extraction.build-pipeline refines spec:extraction.derive-graph · declared — the build orchestrates derivation and publication of the one graph
  • spec:extraction.runnable-modules dependsOn spec:extraction.build-pipeline · declared — the build publishes the registrars and their manifest under its staged-publication law
  • spec:extraction.build-pipeline.same-invocation refines spec:extraction.build-pipeline · declared
  • spec:extraction.executable-contracts refines spec:extraction.build-pipeline · declared
  • spec:extraction.build-pipeline.same-invocation verifies spec:extraction.build-pipeline · 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

Relations

Relation and directionOther endClaimReasonExercised keys
dependsOn · outgoingCarrier reification derives the one graph
spec:extraction.derive-graph · resolves		declaredNoneNone
refines · outgoingCarrier reification derives the one graph
spec:extraction.derive-graph · resolves		declaredthe build orchestrates derivation and publication of the one graphNone
dependsOn · incomingDerived runnable modules freeze the registrar interface
spec:extraction.runnable-modules · resolves		declaredthe build publishes the registrars and their manifest under its staged-publication lawNone
refines · incomingOne query invocation shares its extracted graph and validation result
spec:extraction.build-pipeline.same-invocation · resolves		declaredNoneNone
refines · incomingThe build derives step and space contracts from graph examples
spec:extraction.executable-contracts · resolves		declaredNoneNone
verifies · incomingOne query invocation shares its extracted graph and validation result
spec:extraction.build-pipeline.same-invocation · resolves		declaredNoneoneSeam

Bindings

Implementation binding: present

  • component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · role service · layer edge · context protocol
  • 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.build-pipeline-query · runQuery reads one body, derives the graph once for the reader, raw graph and report, and prints the return or refuses on stderr · src/cli/q-command.ts:212 · role service · component component:protocol.cli · layer edge · context protocol

Design reference: none

Verifier binding: present

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.