Derived runnable modules freeze the registrar interface

problem

A bound example test would otherwise repeat registration, step dispatch and oracle comparison that the graph and contracts already determine.

outcome

Give each bindable example a generated registrar, so its authored test keeps semantics derivation cannot supply.

value

A Spec and a small authored semantics module express the test while the engine neither loads nor executes adopter code.

rule line 28 · specs/extraction/runnable-modules.sdp.md:28

Code generation emits a registrar called with createWorld, invoke, observe, expected and optional assertions. It owns describe/it registration, step dispatch, the three-way comparator and failure rendering. The authored test keeps its top-level specTest anchor and one activation call beside its semantics. The authored file imports the generated registrar; the generated module imports no authored code. Normal runner discovery loads the authored file and activates registration. Generated modules never self-register; the graph records binding, never liveness.

rule line 29 · specs/extraction/runnable-modules.sdp.md:29

Generated sibling path — for each bindable example, codegen emits exactly one generated registration module as a sibling *.generated.ts of the authored .test.ts (deterministic filename keyed by Spec ID, not by the authored suite filename). One authored suite may verify many examples without their registrar map keys or output paths colliding. Exactly one generated registration per example; a second registration path for the same example is refused. Generated siblings are disposable build output: an adopted registrar is committed because authored code imports it, while unadopted registrars remain ignored, regenerable output and confer no migration claim.

rule line 30 · specs/extraction/runnable-modules.sdp.md:30

generated/registrars.json is a versioned, sorted manifest of every extraction-root-relative registrar sibling owed by the build. Publication reconciles the manifest and removes siblings no longer owed under the build-pipeline law. --check-clean compares the manifest and every sibling byte with fresh generation. Preflight independently compares every tracked adopted registrar in the worktree and Git index with regenerated bytes.

rule line 31 · specs/extraction/runnable-modules.sdp.md:31

Registration-path loudness — multiple anchors in one authored suite still locate one registrar sibling; when one example resolves to more than one distinct authored suite path, generation emits a named finding and withholds that registrar rather than selecting a path silently.

rule line 32 · specs/extraction/runnable-modules.sdp.md:32

Generated registrars import shared runtime helpers from @libar-dev/software-delivery-protocol/testing and types through public package subpaths. Public exports are the root for model, anchors and public types, ./anchors for zero-dependency anchor builders, ./runner for the framework-neutral plan/run core, ./vitest for bindExample, and ./testing for the registrar runtime. Authored suites may import anchor builders through the root or ./anchors. Authored and generated modules never import private src paths. The supported optional Vitest peer range is >=2, as declared by the package.

rule line 33 · specs/extraction/runnable-modules.sdp.md:33

Step identity is the step's contract key: its step key under spec:carrier.step-keys, or its skeleton text when it has none, and generation introduces no ordinal or slug identity. A directly authored bindExample handler map fails the typecheck when one of its keys goes stale. An adopted registrar holds no authored per-step handler: a stale committed registrar fails the regeneration preflight, and its internal handlers change with the contract when it is regenerated. The contract key of a Then step of the example space also names an Outcome kind, so changing it fails the typecheck of an authored oracle that names the old kind.

rule line 34 · specs/extraction/runnable-modules.sdp.md:34

Handler resolution — the generated registrar's internal dispatch object is an exhaustive mapped type over the contract's step keys: removing or staling one of those generated callbacks is a tsc error naming that step. The adopted authored surface retains no per-step callbacks (and therefore no step keys); its five adapters are required keys (assertions optional), so a missing or stale authored callback is a tsc error naming that adapter. These are the two exhaustive mapped-type checks; demanding an authored error name a step while simultaneously retaining no authored per-step surface is refused as contradictory. Codegen cannot statically see authored handlers, so no generation-time handler refusal is promised — the type system carries it. Existing generation-time refusals (unbindable example, incompatible vocabulary, colliding path) are reused unchanged.

rule line 35 · specs/extraction/runnable-modules.sdp.md:35

Scenario-level invocation — the five-adapter interface carries one product invoke per example, so the first When occurrence invokes it and later When occurrences in the same lawful scenario do not repeat side effects.

rule line 36 · specs/extraction/runnable-modules.sdp.md:36

At the first Then, the comparator refuses an incomplete point before calling the oracle and otherwise evaluates and caches expected(point). It finds the authored Then whose contract key equals expected.kind, compares that step's authored parameters with the oracle payload, reads observe(world), compares observed and oracle outcomes, and runs additional assertions separately. Actual-equals-oracle alone is insufficient: a Spec parameter mutation must fail. The oracle accepts Partial<Conditions>; the registrar never casts a partial point to Conditions.

rule line 37 · specs/extraction/runnable-modules.sdp.md:37

Oracle payload versus Spec Then parameters and observed versus oracle outcomes use deep structural equality on the authored shape. Diagnostics name missing, extra or changed values by path and show expected and actual values. The comparator quotes authored Then parameters and skeleton text without rephrasing them.

rule line 38 · specs/extraction/runnable-modules.sdp.md:38

Failure rendering reuses the contract's matching Then step plus the existing renderContractStep path. When the oracle selected no authored Then, emit a scenario-level diagnostic quoting Spec ID, oracle kind, and the contract keys of the available Then steps; preserve the original assertion as cause.

rule line 39 · specs/extraction/runnable-modules.sdp.md:39

Bound unspecified outcome — unspecified names a coverage gap in the example space, but a bound executable example selecting it reddens because no authored Then may silently witness that gap.

rule line 40 · specs/extraction/runnable-modules.sdp.md:40

The authored top-level specTest carries a non-empty verifies target naming the example. It remains the source of has-verifier; generated execution confers no delivery fact and records no pass state.

rule line 41 · specs/extraction/runnable-modules.sdp.md:41

Additive assertions — optional assertions may add domain checks the Outcome union cannot express; they never replace steps (3) or (5) of the three-way comparator and never silence a Spec-param or oracle mismatch.

rule line 42 · specs/extraction/runnable-modules.sdp.md:42

Case mapping and outlines — outline rows map one deterministic case per row in carrier order when a multi-row table sugar expands statically into sibling examples (point-per-example). Scenario Outlines and inline Examples tables stay refused as executable carrier constructs inside a single example; one example remains one point and earns exactly one generated registration.

rule line 43 · specs/extraction/runnable-modules.sdp.md:43

Registrars use no environment, global or module side channel, mutable global registry or singleton world shared across examples. Generated siblings export the registrar and never self-register. Generation derives no domain observation; the engine never loads or executes adopter code. Registrars do not become generated test harnesses. Scenario Outlines stay refused. The interface changes neither the claim taxonomy, anchor bindings nor the contract-key identity of steps.

16 unkeyed rules.

registrar line 46 · specs/extraction/runnable-modules.sdp.md:46

export declare function registerExample<World>(adapters: RunnableExampleAdapters<World, Conditions, Outcome>): void; is the signature template; substitute the generated function name and the parent's generated Conditions and Outcome names.

no citation recorded

registrarName line 47 · specs/extraction/runnable-modules.sdp.md:47

Prefix register to the example's final dot-delimited id segment in PascalCase after removing the first occurrence of the parent's final segment in PascalCase; if removal leaves an empty name, use the example's PascalCase segment. PascalCase splits that segment at non-alphanumeric characters, capitalizes each part, and prefixes X when the result starts with a digit.

adapters line 48 · specs/extraction/runnable-modules.sdp.md:48

interface RunnableExampleAdapters<W, C, O extends { readonly kind: string }> { readonly createWorld: (point: Partial<C>) => W; readonly invoke: (world: W, point: Partial<C>) => void | Promise<void>; readonly observe: (world: W) => O; readonly expected: (point: Partial<C>) => O; readonly assertions?: (world: W, observed: O) => void | Promise<void>; }

no citation recorded

registrarPath line 49 · specs/extraction/runnable-modules.sdp.md:49

The authored suite directory plus the example id without the spec: prefix and the suffix .test.generated.ts, retaining the id's dots.

registrarManifest line 50 · specs/extraction/runnable-modules.sdp.md:50

generated/registrars.json carries the versioned, sorted extraction-root-relative registrar paths owed by the build.

no citation recorded

thenBinding line 51 · specs/extraction/runnable-modules.sdp.md:51

compareContractOutcome(execution, { kind: "then", key, text, params }) is the generated binding of a Then step; it compares only the step whose key equals the oracle's kind.

no citation recorded

noMatchingThen line 52 · specs/extraction/runnable-modules.sdp.md:52

scenario <spec>: oracle selected "<kind>"; available Then steps: "<key>", … is the diagnostic when no authored Then matches, listing each Then step's contract key in contract order, with the original assertion as cause.

no citation recorded

Verifier bindings

• test:protocol.runnable-modules · verifies generated runnable-module registration and runtime semantics · anchored · test anchor binding present · test/testing.test.ts:58

  External run evidence from test/testing.test.ts

  Test anchors: test:protocol.runnable-modules. Specs verified by those bindings: spec:extraction.runnable-modules.

  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
  compares Spec Then params, oracle payload, and the observed outcome before assertions	generated registrar testing runtime	passed	1.86 ms
  invokes the scenario-level product call only once across repeated When steps	generated registrar testing runtime	passed	0.86 ms
  renders the matching contract step for a Spec/oracle payload mismatch	generated registrar testing runtime	passed	0.9 ms
  stops before domain assertions when observation disagrees with the oracle	generated registrar testing runtime	passed	1.11 ms
  emits a scenario diagnostic when the oracle selects no authored Then	generated registrar testing runtime	passed	0.33 ms
  refuses incomplete-point comparison at Then without calling the oracle	generated registrar testing runtime	passed	0.47 ms

• test:protocol.runnable-modules-generation · checks registrar generation, sibling paths and competing suite paths · anchored · test anchor binding present · test/codegen.test.ts:22

  External run evidence from test/codegen.test.ts

  Test anchors: test:protocol.runnable-modules-generation. Specs verified by those bindings: spec:extraction.runnable-modules.

  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
  emits a space contract per example-space parent and a step contract per bindable example	the contracts codegen stage	passed	5.81 ms
  emits an exhaustive sibling registrar for a bindable anchored example	the contracts codegen stage	passed	1.41 ms
  keys sibling registrar paths by Spec ID when one authored suite verifies multiple examples	the contracts codegen stage	passed	4.35 ms
  refuses multiple distinct registrar paths for one example	the contracts codegen stage	passed	1.32 ms
  is deterministic: two generations over one graph are byte-identical	the contracts codegen stage	passed	0.99 ms
  refuses a prose-only example and an unbound-slot example — refusing is the honest behavior	the contracts codegen stage	passed	0.6 ms
  emits a step contract with inferred param types when no parent vocabulary matches	the contracts codegen stage	passed	0.42 ms
  withholds a child contract when its steps drift outside an existing parent vocabulary	the contracts codegen stage	passed	1.48 ms
  withholds a child contract when multiple parent spaces type one skeleton incompatibly	the contracts codegen stage	passed	1 ms
  keeps a partial point honest: only the bound dimensions enter the point	the contracts codegen stage	passed	0.69 ms
  keeps incomplete contract points in reader and recipe coverage	the contracts codegen stage	passed	6.43 ms
  counts the review probe's small binding with an empty Then in recipe 44	the contracts codegen stage	passed	1.89 ms
  warns and drops an undeclared slot from the point — loud, never silent (L2)	the contracts codegen stage	passed	0.67 ms
  warns and drops an off-dimension value; the step contract widens the slot so it still compiles	the contracts codegen stage	passed	0.76 ms
  warns on a conflicting re-binding of one skeleton within one example — first wins (MD-17)	the contracts codegen stage	passed	0.71 ms
  warns on a conflicting dimension declaration across vocabulary steps — first wins	the contracts codegen stage	passed	0.34 ms
  warns on conflicting declarations of one dimension within a vocabulary step — first wins	the contracts codegen stage	passed	0.38 ms
  refuses to guess the single-quoted-literal vocabulary form — deferred to the grammar session, loudly	the contracts codegen stage	passed	0.47 ms
  warns on a vocabulary slot that declares no usable type — an authored slot never falls out silently (L2)	the contracts codegen stage	passed	0.43 ms
  binding a Then-vocabulary slot is ordinary (the outcome point) — no undeclared-slot warning	the contracts codegen stage	passed	0.69 ms
  emits nothing over a graph with no example spaces and no bindable examples	the contracts codegen stage	passed	0.19 ms
  derives contract AND point from the first complete entry, and names extra entries (MD-17 made loud)	the contracts codegen stage	passed	0.59 ms
  warns on a conflicting re-binding of one slot WITHIN a single step text — first wins	the contracts codegen stage	passed	0.52 ms
  withholds the contracts tree WHOLE on a case-colliding path — all-or-nothing, never a second gate	the contracts codegen stage	passed	0.81 ms

• test:protocol.runnable-modules-types · checks registrar skeletons and required authored adapters · anchored · test anchor binding present · test/runnable-modules.typecheck.ts:5

Requirement drawing

• Declared verifying examples: no declared verifying example.

Decisions

• Adopted runnable registrars are committed

  A registrar becomes adopted when tracked authored code imports it. Adopted registrars are committed and byte-checked against fresh generation; unadopted registrars remain ignored, regenerable output. A deterministic generated manifest owns reconciliation for both groups without turning registrar content into authored truth.

• The comment form is a second anchor representation

  An anchor has two extracted representations that feed one closed envelope, the constant form as ruled and a comment form. The comment form is a top-level /** … */ block in a .ts or .tsx file carrying reserved camelCase, TSDoc-compatible tags; @sdpAnchor <id> opens it, and the id's namespace selects the flavor exactly as the constant builders do. Comment prose still authors nothing: only the reserved tags are read, and a comment that does not open with /** is never read. Trust is by reserved grammar, not by builder import, so no import is required. The same id in two forms is a duplicate id. The package also ships a zero-dependency subpath @libar-dev/software-delivery-protocol/anchors exporting the id builders and the three anchor builders and nothing else, for runtimes that may import but must not load node:* modules or ts-morph; the extractor trusts that specifier as a Protocol builder module.

• Bindings state existence, not liveness

  Delivery facts record bindings and enabled verifier existence; coverage gaps and human readiness practice remain explicit without becoming graph facts.

• Each example binds one point

  An example binds exactly one point; table syntax may expand statically into sibling examples and renderers may project siblings as a table.

• 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.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.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.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.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.