Spec Studio

Bindings are optional, plural, and may reference a design

spec:decisions.anchor-binding-grainDecision Record · featureready floor ready

Packs: pack:self-hosting-v1

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

Findings: no errors, no warnings

specs/decisions/anchor-binding-grain.sdp.md

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

Intent
outcome
Let a code anchor name zero, one, or several Specs it realizes, and name the Specs it answers to without claiming to realize them, so an anchor can state exactly what its code does and the graph can reach a design from the code that answers to it.
Decision
context
Before this ruling a code anchor carried one required satisfies and a test anchor one verifies. The first adopter split Specs so that an anchor could claim only what its code does, a stub reads as implemented because the only way to name a design from code is to claim to realize it, and a relationship the design states in prose cannot reach a page. The original design made satisfies optional and plural on an anchor (docs/lineage/v0-design/04-authoring-surfaces.md §2.4) and drew the line that anchors carry identity and structure, never readiness, intent, behavior, or verification. The annotation scout under docs/lineage/ found no informational code-to-Spec edge in either lineage and proposed one as the smallest extension.
decision
On a code anchor, satisfies is optional and plural; on a test anchor, verifies is plural and non-empty. The constant form accepts one ref(…) or a fresh array literal of them. Each resolving target confers its fact, and implemented stays a whole-Spec fact. An anchored edge references runs from a CodeNode to a Spec, from references?: readonly SpecId[] on a code anchor; it may target any Spec, decisions included, confers no delivery fact, moves no readiness floor, and the drift alarm ignores it. It says this code answers to that design without claiming to realize it: the unit follows the design without realizing any of its promises, or realizes part of a Spec whose remaining promises no unit yet realizes, so a change to the design asks the code to follow. A design that builds on existing code states that by a typed relation to the Spec the code satisfies, never by a reference from the code. A target named in both satisfies and references is an error. An identity-only code anchor, with no satisfies and no references, is lawful: it mints a CodeNode for structure and for byFile, and nothing else.
rationale
  • Hard to reverse: the anchor contract and the closed edge list are contracts for the extractor, the validators, the reader, and every adopter's anchors. Surprising without context: the obvious move is to let satisfies name a design the code only partly realizes, and this ruling refuses that in favor of a second edge that confers nothing. Real trade-off: a non-conferring edge can be written where a realization claim is due, and nothing in the graph says which; in exchange, implemented keeps its one meaning and an honest anchor is always writable.
  • Bindings state existence, not liveness, and references states less than existence of realization: only that the code answers to the design. Keeping that below the delivery facts preserves the drift alarm's meaning.
consequences
  • The closed edge list includes references, derived and anchored; satisfies and verifies edges are one per target.
  • A present references is non-empty and unique; a non-resolving target confers nothing and reports as a non-resolving satisfies target does.
  • satisfies keeps its posture: code never satisfies a decision Spec directly, because a ruling is not something code realizes, and a unit may reference the decisions it follows; an anchor is never pointed at an unfinished Spec to manufacture coverage, and a unit that answers to such a Spec references it.
  • satisfies is a claim a set of units makes about a Spec: a unit satisfies a Spec when it realizes at least one promise the Spec carries, and the units that satisfy it together realize every promise it carries. A unit that follows a design without realizing any promise of it references the design. A promise no satisfying unit realizes is a binding defect: split that part into a child Spec, or write references until it is built. A component and its members are one set for this test, and a component anchor is never added only to complete a set. The set reading keeps implemented a Spec-grain fact that does not depend on how the code is split into modules.
  • A Spec that restates law a narrower Spec carries, as a model Spec defining its terms does, states a definition with a pointer, not a second promise: the narrower Spec carries the promise and its bindings, and a unit satisfies the broader Spec only for a promise that Spec alone carries.
  • An identity-only anchor derives no satisfies edge, so it never confers implemented; a stub that answers to a design references the design rather than satisfying it.
  • byFile may lawfully return a CodeNode with an empty Spec list; an empty list is the identity-only anchor's honest answer, not a lookup failure.
  • blastRadius reports changed identity-only CodeNodes as their own list, neither dropped nor folded into coverage-unknown, because the graph records the node and nothing it binds.
  • The drift alarm ignores references and still reports a satisfies target that states below ready, target by target.
  • The build backlog predicate (recipe 1) is unchanged: references neither adds nor removes a row.
  • The reader's Spec context names the CodeNodes that reference the Spec with their file and line; blast radius traverses references as a binding and names the edge type in its reason.
  • The Design Review Spec page lists the units that reference the Spec, and the census renders references beside the structural edges.
  • Anchor targets name whole Specs. An entry address never narrows a binding and never carries a delivery fact; a part of a Spec that needs its own realization tracking is its own Spec.
  • A references edge is authored for the design relationship it names; an edge whose reason is a test, a count, or a byFile answer is removed.
alternatives
  • A partial-realization delivery fact was refused: a fact that says "partly implemented" is a status on code, and the floor cannot read it honestly.
  • Folding the design relationship into satisfies was refused: it manufactures implemented on a Spec the code does not realize, which is the adopter's stub problem restated.
  • Declaring the relationship on the Spec, as a list of its own code bindings, was refused: a Spec-side list of bindings is authored delivery state and a second place for the binding to drift.
  • References from code that a design builds on were refused: that dependency is a relation from the building design to the Spec the code satisfies; a code-side copy is a second home for it and would make each unit's source list its consumers' designs.
  • A satisfies or references target at an entry address was refused: a per-entry implemented is the partial-realization fact by another name, it would put delivery facts below the Spec, and a design key is renamed freely while an anchor bound to one would break on every design edit.
Verification

Verifier bindings

No verifier binding recorded.

Design view

Requirement drawing

  • Declared verifying examples: no declared verifying example.
  • Test or oracle bindings: no recorded binding.
Requirement drawing for spec:decisions.anchor-binding-grain
The diagram as text
  • spec:decisions.anchor-binding-grain: Bindings are optional, plural, and may reference a design · declared Spec
  • spec:decisions.shipped-projections-frozen: The shipped projections stay frozen · declared Spec
  • spec:model.anchors: Source anchors bind code without carrying intent · declared Spec
  • impl:protocol.derive-graph: derives the graph from reified carriers and bindings · anchored code · src/extract/derive.ts:241
  • impl:protocol.schema-version: versioned graph nodes, claims, edges and located evidence · anchored code · src/graph/schema.ts:9
  • impl:protocol.structural-anchors: checks structural anchor validity and disjoint realization and reference targets · anchored code · src/validate/validators.ts:595
  • spec:decisions.anchor-binding-grain refines spec:decisions.shipped-projections-frozen · declared — carves out the Design Review's Referenced by list and the census References table
  • spec:decisions.anchor-binding-grain refines spec:model.anchors · declared
  • impl:protocol.derive-graph references spec:decisions.anchor-binding-grain · anchored
  • impl:protocol.schema-version references spec:decisions.anchor-binding-grain · anchored
  • impl:protocol.structural-anchors references spec:decisions.anchor-binding-grain · anchored
Mermaid source

Copyable source; the Studio draws static SVG.

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

Decisions

No decision record named.

Runtime

No implementation neighborhood recorded.

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:decisions.anchor-binding-grain
The diagram as text
  • spec:consumers.authoring-on-ramp: Authors move one Spec from intent to reviewed evidence
  • spec:consumers.census-page: Census renders the runtime taxonomy without becoming a registry
  • spec:consumers.design-review: Design Review renders graph context without becoming a gate
  • spec:consumers.design-slice: A slice reads a Pack as one design, with the architecture it touches and what each member needs next
  • spec:consumers.reader: The reader bridges agent entry points to composable graph context
  • spec:decisions.anchor-binding-grain: Bindings are optional, plural, and may reference a design
  • spec:decisions.architectural-annotation: Architectural significance is annotated where it is realized
  • spec:decisions.binding-not-liveness: Bindings state existence, not liveness
  • spec:decisions.shipped-projections-frozen: The shipped projections stay frozen
  • spec:extraction.derive-graph: Carrier reification derives the one graph
  • spec:model.anchors: Source anchors bind code without carrying intent
  • spec:protocol.significant-units-review: The engine's accepted set covers its significant abstractions and only those
  • spec:protocol.structural-self-binding: The engine's structural self-binding covers its architecturally significant units
  • spec:decisions.anchor-binding-grain dependsOn spec:decisions.binding-not-liveness · declared
  • spec:decisions.anchor-binding-grain refines spec:decisions.shipped-projections-frozen · declared — carves out the Design Review's Referenced by list and the census References table
  • spec:decisions.anchor-binding-grain refines spec:model.anchors · declared
  • spec:consumers.authoring-on-ramp decidedBy spec:decisions.anchor-binding-grain · declared — the skill teaches optional and plural targets, references and the collective promise test under this ruling
  • spec:consumers.census-page decidedBy spec:decisions.anchor-binding-grain · declared — the census renders the references edges ruled by this decision
  • spec:consumers.design-review decidedBy spec:decisions.anchor-binding-grain · declared — a Spec page lists the units that reference it apart from the units that realize it
  • spec:consumers.design-slice decidedBy spec:decisions.anchor-binding-grain · declared — the code a design builds on is reached through the design's own relations, never through a reference from that code
  • spec:consumers.reader decidedBy spec:decisions.anchor-binding-grain · declared
  • spec:extraction.derive-graph decidedBy spec:decisions.anchor-binding-grain · declared
  • spec:model.anchors decidedBy spec:decisions.anchor-binding-grain · declared
  • spec:protocol.significant-units-review decidedBy spec:decisions.anchor-binding-grain · declared
  • spec:protocol.structural-self-binding decidedBy spec:decisions.anchor-binding-grain · declared
  • spec:decisions.architectural-annotation dependsOn spec:decisions.anchor-binding-grain · 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 · outgoingBindings state existence, not liveness
spec:decisions.binding-not-liveness · resolves		declaredNoneNone
refines · outgoingThe shipped projections stay frozen
spec:decisions.shipped-projections-frozen · resolves		declaredcarves out the Design Review's Referenced by list and the census References tableNone
refines · outgoingSource anchors bind code without carrying intent
spec:model.anchors · resolves		declaredNoneNone
decidedBy · incomingAuthors move one Spec from intent to reviewed evidence
spec:consumers.authoring-on-ramp · resolves		declaredthe skill teaches optional and plural targets, references and the collective promise test under this rulingNone
decidedBy · incomingCensus renders the runtime taxonomy without becoming a registry
spec:consumers.census-page · resolves		declaredthe census renders the references edges ruled by this decisionNone
decidedBy · incomingDesign Review renders graph context without becoming a gate
spec:consumers.design-review · resolves		declareda Spec page lists the units that reference it apart from the units that realize itNone
decidedBy · incomingA slice reads a Pack as one design, with the architecture it touches and what each member needs next
spec:consumers.design-slice · resolves		declaredthe code a design builds on is reached through the design's own relations, never through a reference from that codeNone
decidedBy · incomingThe reader bridges agent entry points to composable graph context
spec:consumers.reader · resolves		declaredNoneNone
decidedBy · incomingCarrier reification derives the one graph
spec:extraction.derive-graph · resolves		declaredNoneNone
decidedBy · incomingSource anchors bind code without carrying intent
spec:model.anchors · resolves		declaredNoneNone
decidedBy · incomingThe engine's accepted set covers its significant abstractions and only those
spec:protocol.significant-units-review · resolves		declaredNoneNone
decidedBy · incomingThe engine's structural self-binding covers its architecturally significant units
spec:protocol.structural-self-binding · resolves		declaredNoneNone
dependsOn · incomingArchitectural significance is annotated where it is realized
spec:decisions.architectural-annotation · resolves		declaredNoneNone

Bindings

Implementation binding: none

Design reference: present

  • impl:protocol.derive-graph · derives the graph from reified carriers and bindings · src/extract/derive.ts:241 · role extractor · component component:protocol.extract · layer application · context protocol
  • impl:protocol.schema-version · versioned graph nodes, claims, edges and located evidence · src/graph/schema.ts:9 · role contract · component component:protocol.graph · layer domain · context protocol
  • impl:protocol.structural-anchors · checks structural anchor validity and disjoint realization and reference targets · src/validate/validators.ts:595 · role validator · component component:protocol.validate · layer domain · context protocol

Verifier binding: none

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.