Components are designed ahead of their code

problem

A design ahead of its code cannot state the components it adds, their layer and context and what they use, in a form the graph compares with the components the code later anchors.

outcome

Let a design name the components it will add, with their layer, context and uses, and compare that design with the anchored components once code exists.

risks

• A planned component kept apart from its realization is a second place for the component to drift, which is why the architectural annotation decision refused a separate architecture file and why the design lives in a Spec the realizing anchor satisfies.

0 unkeyed rules.

Verifying examples

Given a component design for {componentId: "component:probe.history"} that plans the layer {plannedLayer: "domain"} and uses {plannedUses: "component:probe.kernel"}
Given the component anchor for that design {anchor: "satisfies the design"}
Given that anchor states the layer {realizedLayer: "application"} and its member uses {realizedUses: "component:probe.audit"}
When the realization comparison runs
Then the comparison lists {unrealized: 0} unrealized designs, {matching: 0} matching designs and {differing: 2} differing rows
Then the differing fields are {fields: "layer, uses"}

Given a component design for {componentId: "component:probe.history"} that plans the layer {plannedLayer: "domain"} and uses {plannedUses: "component:probe.kernel"}
Given the component anchor for that design {anchor: "satisfies the design"}
Given that anchor states the layer {realizedLayer: "domain"} and its member uses {realizedUses: "component:probe.kernel"}
When the realization comparison runs
Then the comparison lists {unrealized: 0} unrealized designs, {matching: 1} matching designs and {differing: 0} differing rows
Then the differing fields are {fields: ""}

Given a component design for {componentId: "component:probe.history"} that plans the layer {plannedLayer: "domain"} and uses {plannedUses: "component:probe.kernel"}
Given the component anchor for that design {anchor: "is absent"}
Given that anchor states the layer {realizedLayer: "absent"} and its member uses {realizedUses: ""}
When the realization comparison runs
Then the comparison lists {unrealized: 1} unrealized designs, {matching: 0} matching designs and {differing: 0} differing rows
Then the differing fields are {fields: ""}

Example space

Given a component design for {componentId:string} that plans the layer {plannedLayer:"domain"|"application"} and uses {plannedUses:string}
Given the component anchor for that design {anchor:"is absent"|"satisfies the design"}
Given that anchor states the layer {realizedLayer:"domain"|"application"|"absent"} and its member uses {realizedUses:string}
When the realization comparison runs
Then the comparison lists {unrealized:number} unrealized designs, {matching:number} matching designs and {differing:number} differing rows
Then the differing fields are {fields:string}

component design line 29 · specs/model/planned-architecture.sdp.md:29

A Spec that states a component the code does not yet realize and what it is for. Its Design entries are keyed as the anchor's attributes are named: id for the planned component: anchor's own id, layer, context, uses for the components it will use, and optionally role. The keys are a convention recipes read; the Protocol closes no Design shape, and the Spec confers nothing and mints no code unit.

planned component line 30 · specs/model/planned-architecture.sdp.md:30

The component a component design names. It stays intent until a component: anchor realizes it, and that anchor satisfies the component design; the graph holds no component node before the anchor exists.

realization comparison line 31 · specs/model/planned-architecture.sdp.md:31

Recipe 43, planned against realized components, which reads each component design beside the component: anchor that satisfies it, resolving members through memberOf as recipe 32 does, and lists a design no anchor satisfies yet, a layer, context or role that differs, and a uses named on one side only. It reports and refuses nothing.

provider line 32 · specs/model/planned-architecture.sdp.md:32

A code unit that supplies an interface another unit requires; a composition selects one provider for each requirement, and a test may select another. A component design names its providers and that selection in prose, and none of them earns graph structure beyond uses.

componentDesign line 35 · specs/model/planned-architecture.sdp.md:35

a Spec is a component design when its Design id value, bare or in the code span that opens it, is a component: id; the curation report and the realization comparison select designs this way, and no validator reads the convention.

designKeys line 36 · specs/model/planned-architecture.sdp.md:36

the comparison reads five Design keys, id, layer, context, role and uses, and no other; layer takes one of the five layers, context and role one token on the role grammar, and uses either none for the empty list or component: ids separated by commas, each trimmed, read as the set of distinct ids; each value is read bare when it is the whole value, or from the code span that opens it, with prose after the span free to say why.

comparisonRecipe line 37 · specs/model/planned-architecture.sdp.md:37

recipe 43, planned against realized components, takes no parameter, so any parameter name returns { unknownParams, accepts: [] } alone, as every catalog recipe answers a name it does not take; otherwise it returns { totals, unrealized, differing, unreadable }, where totals is { designs, realized, matching, unrealized, differing, unreadable }, matching counts the realized designs with neither a differing row nor an unreadable row, and differing counts rows.

realizedWhen line 38 · specs/model/planned-architecture.sdp.md:38

a design is realized when its component: CodeNode is anchored and has an anchored satisfies edge to the design, as the curation report reads it; a design whose component exists without that edge stays unrealized, with anchorExists: true.

comparedFields line 39 · specs/model/planned-architecture.sdp.md:39

for a realized design, each of layer, context, role and uses the design states is compared with the anchored component, and a key the design leaves out is not compared; the realized uses are the components other than its own that an anchored uses edge from the component or one of its members reaches, each end resolved to its component as recipe 32 resolves it.

comparisonRows line 40 · specs/model/planned-architecture.sdp.md:40

unrealized rows are { spec, componentId, anchorExists, layer, context, role, uses } with the planned values, null when unstated, and uses an empty list when the design states none; differing rows are { spec, componentId, field, planned, realized }, one for each differing field, where layer, context and role carry the two values or null and uses carries the two sorted lists of components named on that side only; unreadable rows are { spec, key, value } for a value outside its key's form, and that key is not compared; rows sort by spec, then by field or key.

no citation recorded

Verifier bindings

• spec:model.planned-architecture.differing-layer-and-uses · A realized component that differs from its design gives one row per field · declared · example enabled · specs/model/planned-architecture.differing-layer-and-uses.sdp.md

  External run evidence from test/self-hosting-corpus-checks.test.ts

  Test anchors: test:protocol.model.planned-architecture.differing-layer-and-uses, test:protocol.model.planned-architecture.matching-design, test:protocol.model.planned-architecture.unrealized-design, test:protocol.validation.architecture-constraints.forbidden-layer-pair, test:protocol.validation.architecture-constraints.isolated-context-as-rule, test:protocol.validation.architecture-constraints.unstated-layer-unclassified, test:protocol.validation.corpus-rules.copies-contain-changes, test:protocol.validation.corpus-rules.error-finding-fails, test:protocol.validation.corpus-rules.malformed-finding-fails, test:protocol.validation.corpus-rules.warning-finding-informs. Specs verified by those bindings: spec:model.planned-architecture, spec:model.planned-architecture.differing-layer-and-uses, spec:model.planned-architecture.matching-design, spec:model.planned-architecture.unrealized-design, spec:validation.architecture-constraints, spec:validation.architecture-constraints.forbidden-layer-pair, spec:validation.architecture-constraints.isolated-context-as-rule, spec:validation.architecture-constraints.unstated-layer-unclassified, spec:validation.corpus-rules, spec:validation.corpus-rules.copies-contain-changes, spec:validation.corpus-rules.error-finding-fails, spec:validation.corpus-rules.malformed-finding-fails, spec:validation.corpus-rules.warning-finding-informs.

  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
  executes the bound example against a fresh world	A rules file that empties its graph leaves the next file's graph whole (spec:validation.corpus-rules.copies-contain-changes)	passed	21.24 ms
  executes the bound example against a fresh world	An error from a corpus rule fails validation and leaves the Protocol's line alone (spec:validation.corpus-rules.error-finding-fails)	passed	4.29 ms
  executes the bound example against a fresh world	A finding with no subject fails its rules file (spec:validation.corpus-rules.malformed-finding-fails)	passed	3.72 ms
  executes the bound example against a fresh world	A warning from a corpus rule informs and passes (spec:validation.corpus-rules.warning-finding-informs)	passed	3.36 ms
  executes the bound example against a fresh world	A domain member that uses an infrastructure member breaks a forbidden pair (spec:validation.architecture-constraints.forbidden-layer-pair)	passed	16.29 ms
  executes the bound example against a fresh world	The walk named as a rules file fails validation on an isolation breach (spec:validation.architecture-constraints.isolated-context-as-rule)	passed	3.85 ms
  executes the bound example against a fresh world	A component with no layer leaves its edge unclassified (spec:validation.architecture-constraints.unstated-layer-unclassified)	passed	3.28 ms
  executes the bound example against a fresh world	A realized component that differs from its design gives one row per field (spec:model.planned-architecture.differing-layer-and-uses)	passed	10.85 ms
  executes the bound example against a fresh world	A realized component that matches its design gives no row (spec:model.planned-architecture.matching-design)	passed	5.28 ms
  executes the bound example against a fresh world	A component design no anchor satisfies is listed as unrealized (spec:model.planned-architecture.unrealized-design)	passed	4.57 ms

• spec:model.planned-architecture.matching-design · A realized component that matches its design gives no row · declared · example enabled · specs/model/planned-architecture.matching-design.sdp.md
• spec:model.planned-architecture.unrealized-design · A component design no anchor satisfies is listed as unrealized · declared · example enabled · specs/model/planned-architecture.unrealized-design.sdp.md

Requirement drawing

Decisions

• Architectural significance is annotated where it is realized

  Architectural significance is annotated on the anchor of the unit that realizes it. A code anchor may carry role, the architectural pattern the unit plays; a component: anchor may additionally carry layer, one of edge, application, domain, adapter, or infrastructure, and context, its bounded context. The component: anchor is anchored architecture: it is the declared component, and there is no separate architecture file, because the anchor sits where the component is realized. It is not the original design's declared Component that could exist before code; an unrealized component lives in Specs and never as an invented CodeNode. A role is a free, corpus-owned vocabulary whose taxonomy the census renders with counts from the graph; service, decider, projection, read-model, codec, contract, barrel, and utility are the lineage set, not a closed list. layer is a closed set, and a value outside it is an envelope error; layer or context on a non-component anchor is an envelope error. All three attributes are optional, and omission is lawful.

• impl:protocol.planned-components-recipe · asserts realization of the shipped planned against realized components recipe · test/architecture-recipes.test.ts:16

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.