Spec Studio

Bound examples execute their authored steps

spec:extraction.executable-examplesUse Case / Behavior · epicready floor ready

New since the base graph base da4b141. See the diff.

Base input: schema 0.11.0, 405 Specs.

Packs: pack:roadmaps-and-slices-v1, pack:self-hosting-v1

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

Findings: no errors, 1 warning

specs/extraction/executable-examples.sdp.md

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

The capability connects authored intent to an example's execution. Contract generation and the runner own narrower parts of that outcome; neither alone owns it. A change to the authored example must reach its test through the generated contract.

Intent
actor
An author binding an example to a test of the intended behavior.
problem
A separately handwritten test can drift from the Spec's own steps and expected outcome.
outcome
Run an example against its authored intent through graph-derived contracts and report failures in the words of its steps.
Behavior
rule.authoredSteps line 23 · specs/extraction/executable-examples.sdp.md:23
Execution reads the steps and bound values from contracts derived from the graph; it adds no second authored description of the example.

no example exercises it

rule.binding line 24 · specs/extraction/executable-examples.sdp.md:24
A bound test supplies the world and step handlers, and the runner executes the contract's steps in authored order. Contract generation and execution keep their separate responsibilities.

no example exercises it

rule.failure line 25 · specs/extraction/executable-examples.sdp.md:25
A failing step names the authored intent it exercised. An unspecified expected outcome remains explicit and cannot become a passing comparison by assumption.

no example exercises it

rule.facts line 26 · specs/extraction/executable-examples.sdp.md:26
A verifier binding says the example has a verifier. Execution results stay outside the graph and confer no readiness or delivery fact on this epic.

no example exercises it

0 unkeyed rules.

Verification · reviewed
criteria
  • Trace a bound example from its graph steps through generated contracts to runner dispatch, then change an expected outcome and check that its test fails in the example's words.
  • Read the epic's own binding facts separately from the bindings on its contract-generation and runner descendants.
mode
reviewed
Verification

Verifier bindings

No verifier binding recorded.

Design view

Requirement drawing

Requirement drawing for spec:extraction.executable-examples
  • E6: refines (5), verifies (9) · declared
The diagram as text
  • spec:extraction.executable-examples: Bound examples execute their authored steps · declared Spec
  • spec:extraction.example-runner: A bound example runs its contract steps against a fresh world · 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.example-runner.red-step-naming: A red step names itself before the assertion detail · declared Spec
  • spec:extraction.example-runner.step-order: A repeated step runs its one handler at each occurrence, in contract order · 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.contract-declarations: Pinned declarations give an adopter a derived module to typecheck · declared Spec
  • spec:extraction.build-pipeline: The build pipeline has one ordered flow · declared Spec
  • spec:extraction.runnable-modules: Derived runnable modules freeze the registrar interface · declared Spec
  • component:protocol.adapters: external runtime and source adapters · anchored code · src/adapters/vitest.ts:23
  • component:protocol.runner: provider-neutral example execution · anchored code · src/runner/index.ts:99
  • impl:protocol.delivery-facts: computes delivery facts from resolving binding edges · anchored code · src/graph/delivery-facts.ts:65
  • impl:protocol.example-runner: plans and executes a bound example against the caller's world · anchored code · src/runner/index.ts:108
  • impl:protocol.example-runner-adapter: registers one test per example and owns the fresh world lifecycle · anchored code · src/adapters/vitest.ts:32
  • impl:protocol.example-space: resolves example-space vocabulary for contracts and floors · anchored code · src/graph/example-space.ts:117
  • impl:protocol.example-testing-helpers: adapter-lifecycle and oracle-comparison helpers for bound examples · anchored code · src/testing/index.ts:50
  • impl:protocol.executable-contracts: derives step and example-space contracts from the graph · anchored code · src/codegen/contracts.ts:647
  • impl:protocol.runnable-modules: derives and publishes runnable registrar modules from the graph · anchored code · src/codegen/contracts.ts:658
  • test:protocol.example-runner-cleanup: the Vitest adapter cleans up a world whether its steps pass or fail · anchored test binding · binding present · test/vitest-adapter.test.ts:19
  • test:protocol.example-runner.red-step-naming: the red-step point verifies the self-naming failure law · anchored test binding · binding present · test/self-hosting-extraction.test.ts:798
  • test:protocol.example-runner.step-order: the step-order point verifies contract order and the one handler per step · anchored test binding · binding present · test/self-hosting-extraction.test.ts:789
  • 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.contract-declarations refines spec:extraction.executable-contracts · declared
  • spec:extraction.example-runner refines spec:extraction.executable-examples · declared — step dispatch and failure rendering execute a bound example
  • spec:extraction.example-runner.red-step-naming refines spec:extraction.example-runner · declared
  • spec:extraction.example-runner.red-step-naming verifies spec:extraction.example-runner · declared
  • spec:extraction.example-runner.step-order refines spec:extraction.example-runner · declared
  • spec:extraction.example-runner.step-order verifies spec:extraction.example-runner · 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
  • spec:extraction.runnable-modules refines spec:extraction.example-runner · declared
  • component:protocol.adapters satisfies spec:extraction.example-runner · anchored
  • component:protocol.runner satisfies spec:extraction.example-runner · anchored
  • impl:protocol.delivery-facts satisfies spec:extraction.executable-examples · anchored
  • impl:protocol.example-runner satisfies spec:extraction.example-runner · anchored
  • impl:protocol.example-runner satisfies spec:extraction.executable-examples · anchored
  • impl:protocol.example-runner-adapter satisfies spec:extraction.example-runner · anchored
  • impl:protocol.example-runner-adapter satisfies spec:extraction.executable-examples · anchored
  • impl:protocol.example-space satisfies spec:extraction.executable-contracts · anchored
  • impl:protocol.example-testing-helpers satisfies spec:extraction.executable-examples · anchored
  • impl:protocol.executable-contracts satisfies spec:extraction.executable-contracts · anchored
  • impl:protocol.executable-contracts satisfies spec:extraction.executable-examples · anchored
  • impl:protocol.runnable-modules satisfies spec:extraction.executable-examples · anchored
  • test:protocol.example-runner-cleanup verifies spec:extraction.example-runner · anchored
  • test:protocol.example-runner.red-step-naming verifies spec:extraction.example-runner.red-step-naming · anchored
  • test:protocol.example-runner.step-order verifies spec:extraction.example-runner.step-order · 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.adapters · external runtime and source adapters · src/adapters/vitest.ts:23 · layer adapter · context protocol

    Uses

    • component:protocol.runner · provider-neutral example execution · src/runner/index.ts:99 · layer application · context protocol
  • component:protocol.codegen · contracts and registrar output · src/codegen/contracts.ts:633 · 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.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
  • component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol

    Uses

  • component:protocol.runner · provider-neutral example execution · src/runner/index.ts:99 · layer application · context protocol

    Uses

  • component:protocol.testing · the generated registrar runtime · src/testing/index.ts:38 · layer adapter · context protocol

    Uses

    • component:protocol.adapters · external runtime and source adapters · src/adapters/vitest.ts:23 · layer adapter · context protocol
    • component:protocol.runner · provider-neutral example execution · src/runner/index.ts:99 · layer application · context protocol
  • impl:protocol.delivery-facts · computes delivery facts from resolving binding edges · src/graph/delivery-facts.ts:65

    Component: component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol

    Uses

    None.

  • impl:protocol.example-runner · plans and executes a bound example against the caller's world · src/runner/index.ts:108

    Component: component:protocol.runner · provider-neutral example execution · src/runner/index.ts:99 · layer application · context protocol

    Uses

    None.

  • impl:protocol.example-runner-adapter · registers one test per example and owns the fresh world lifecycle · src/adapters/vitest.ts:32

    Component: component:protocol.adapters · external runtime and source adapters · src/adapters/vitest.ts:23 · layer adapter · context protocol

    Uses

    • impl:protocol.example-runner · plans and executes a bound example against the caller's world · src/runner/index.ts:108
  • impl:protocol.example-testing-helpers · adapter-lifecycle and oracle-comparison helpers for bound examples · src/testing/index.ts:50

    Component: component:protocol.testing · the generated registrar runtime · src/testing/index.ts:38 · layer adapter · context protocol

    Uses

    None.

  • impl:protocol.executable-contracts · derives step and example-space contracts from the graph · src/codegen/contracts.ts:647

    Component: component:protocol.codegen · contracts and registrar output · src/codegen/contracts.ts:633 · layer application · context protocol

    Uses

    None.

  • impl:protocol.runnable-modules · derives and publishes runnable registrar modules from the graph · src/codegen/contracts.ts:658

    Component: component:protocol.codegen · contracts and registrar output · src/codegen/contracts.ts:633 · 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.executable-examples
The diagram as text
  • spec:extraction.derive-graph: Carrier reification derives the one graph
  • spec:extraction.example-runner: A bound example runs its contract steps against a fresh world
  • spec:extraction.executable-contracts: The build derives step and space contracts from graph examples
  • spec:extraction.executable-examples: Bound examples execute their authored steps
  • spec:extraction.executable-examples dependsOn spec:extraction.derive-graph · declared — executable contracts read the one graph rather than another carrier path
  • spec:extraction.example-runner refines spec:extraction.executable-examples · declared — step dispatch and failure rendering execute a bound example
  • spec:extraction.executable-contracts refines spec:extraction.executable-examples · declared — typed contracts carry the authored steps and example space into execution
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		declaredexecutable contracts read the one graph rather than another carrier pathNone
refines · incomingA bound example runs its contract steps against a fresh world
spec:extraction.example-runner · resolves		declaredstep dispatch and failure rendering execute a bound exampleNone
refines · incomingThe build derives step and space contracts from graph examples
spec:extraction.executable-contracts · resolves		declaredtyped contracts carry the authored steps and example space into executionNone

Bindings

Implementation binding: present

  • impl:protocol.delivery-facts · computes delivery facts from resolving binding edges · src/graph/delivery-facts.ts:65 · role decider · component component:protocol.graph · layer domain · context protocol
  • impl:protocol.example-runner · plans and executes a bound example against the caller's world · src/runner/index.ts:108 · role service · component component:protocol.runner · layer application · context protocol
  • impl:protocol.example-runner-adapter · registers one test per example and owns the fresh world lifecycle · src/adapters/vitest.ts:32 · role adapter · component component:protocol.adapters · layer adapter · context protocol
  • impl:protocol.example-testing-helpers · adapter-lifecycle and oracle-comparison helpers for bound examples · src/testing/index.ts:50 · role adapter · component component:protocol.testing · layer adapter · context protocol
  • impl:protocol.executable-contracts · derives step and example-space contracts from the graph · src/codegen/contracts.ts:647 · role projection · component component:protocol.codegen · layer application · context protocol
  • impl:protocol.runnable-modules · derives and publishes runnable registrar modules from the graph · src/codegen/contracts.ts:658 · role projection · component component:protocol.codegen · layer application · context protocol

Design reference: none

Verifier binding: none

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

  • warning · honesty/gaps · spec:extraction.executable-examples · Spec "spec:extraction.executable-examples" states readiness "ready" with no resolving verifier — a gap, informative only (ready never requires delivery facts). · specs/extraction/executable-examples.sdp.md
Composing (0)

Composing needs the script.