None.

problem

How sdp q takes a body, prints its answer and refuses is stated only in the CLI help and the reading skill, so a caller and a script that runs a recipe learn the contract by trial.

outcome

State how the evaluation sink takes a body, renders its return and refuses, so every caller relies on one contract.

rule line 19 · specs/consumers/agent-surface.evaluation-sink.sdp.md:19

sdp q takes one positional JavaScript async-function body, which takes precedence over stdin; with no positional body it reads non-terminal stdin, and absent, unreadable or empty input refuses with exit 1 before evaluation.

rule line 20 · specs/consumers/agent-surface.evaluation-sink.sdp.md:20

The sink supplies g, graph, report and params, permits await and prints the returned value using bounded util.inspect by default or JSON.stringify with --json; it does not suppress console output, so machine-consumed bodies must avoid it.

rule line 21 · specs/consumers/agent-surface.evaluation-sink.sdp.md:21

A body that returns undefined prints no answer, reports on stderr that return is the output contract and exits 0; a --json result with no JSON form or one that cannot be serialized refuses with exit 1 and no rendered answer.

rule line 22 · specs/consumers/agent-surface.evaluation-sink.sdp.md:22

An extraction error prevents evaluation, renders the extraction findings and exits 1; validation findings are supplied as report and do not gate evaluation. A compilation, evaluation or rendering failure exits 1 and reports its error on stderr.

rule line 23 · specs/consumers/agent-surface.evaluation-sink.sdp.md:23

A body that fails to parse is reported with the line and column of the error in the body the caller wrote.

rule.fifthBinding line 24 · specs/consumers/agent-surface.evaluation-sink.sdp.md:24

The sink supplies a fifth binding, recipes, beside g, graph, report and params, and every body it, the rules runner or the exported evaluator runs receives it, a recipe called through it included.

spec:consumers.agent-surface.evaluation-sink.recipe-call · enabled

rule.recipeCall line 25 · specs/consumers/agent-surface.evaluation-sink.sdp.md:25

A body calls a shipped recipe as a function of its catalog number and one parameters object; the call runs the recipe's body over the caller's own g, graph and report, with no second derivation and no copy, and resolves to the recipe's answer unchanged, { unknownParams, accepts } and { diagnostics } included.

spec:consumers.agent-surface.evaluation-sink.exported-evaluator · enabled, spec:consumers.agent-surface.evaluation-sink.recipe-call · enabled

rule.callRefusals line 26 · specs/consumers/agent-surface.evaluation-sink.sdp.md:26

A call names a recipe the catalog holds and passes one plain object or nothing; any other number or parameters reject the call with a message naming the recipe, and a recipe that throws rejects the call with its error, so a mistaken call fails loudly instead of answering for a sample.

spec:consumers.agent-surface.evaluation-sink.unknown-recipe · enabled

rule.oneEvaluator line 27 · specs/consumers/agent-surface.evaluation-sink.sdp.md:27

sdp q, the rules runner and the exported evaluator compile and run a body one way: the same compilation, the same parse error with its line and column, worded by each surface in its own pinned text, and the same five bindings.

spec:consumers.agent-surface.evaluation-sink.exported-evaluator · enabled

rule.exportedEvaluator line 28 · specs/consumers/agent-surface.evaluation-sink.sdp.md:28

The package exports the body evaluator, so a script that holds a graph runs a body, or a shipped recipe through recipes, without deriving the graph again; the evaluator writes and prints nothing and claims no sandbox, as the sink claims none.

spec:consumers.agent-surface.evaluation-sink.exported-evaluator · enabled

5 unkeyed rules.

Verifying examples

Given a probe corpus in which two Specs depend on each other through dependsOn
Given a body that calls {call: "recipe 26 with the severity warning"}
When the body runs {entrance: "through the exported evaluator over a graph derived once"}
Then the call {outcome: "resolves"}
Then the answer equals the shipped recipe file's own answer over the same graph and parameters: {sameAnswer: true}

Given a probe corpus in which two Specs depend on each other through dependsOn
Given a body that calls {call: "recipe 26 with no parameters"}
When the body runs {entrance: "through sdp q"}
Then the call {outcome: "resolves"}
Then the answer equals the shipped recipe file's own answer over the same graph and parameters: {sameAnswer: true}

Given a probe corpus in which two Specs depend on each other through dependsOn
Given a body that calls {call: "a recipe number the catalog does not hold"}
When the body runs {entrance: "through sdp q"}
Then the call {outcome: "rejects"}
Then the rejection reads {rejection: "recipes: the catalog holds no recipe 99"}

Example space

Given a probe corpus in which two Specs depend on each other through dependsOn
Given a body that calls {call:"recipe 26 with no parameters"|"recipe 26 with the severity warning"|"a recipe number the catalog does not hold"}
When the body runs {entrance:"through sdp q"|"through the exported evaluator over a graph derived once"}
Then the call {outcome:"resolves"|"rejects"}
Then the answer equals the shipped recipe file's own answer over the same graph and parameters: {sameAnswer:boolean}
Then the rejection reads {rejection:string}

parseErrorLine line 31 · specs/consumers/agent-surface.evaluation-sink.sdp.md:31

A body that does not parse prints one stderr line, sdp q: the body does not parse at line L, column C: <message>, with 1-based positions in the caller's body, exits 1 and prints nothing on stdout.

recipesBinding line 32 · specs/consumers/agent-surface.evaluation-sink.sdp.md:32

recipes(number, parameters?), where number is a recipe number the catalog's index lists, an integer, and parameters is one plain object, {} when omitted; it returns a promise of the value the recipe's body returns, the same value and never a copy or a JSON round trip.

no citation recorded

recipeSource line 33 · specs/consumers/agent-surface.evaluation-sink.sdp.md:33

a call runs the body the package ships for that number as dist/recipes/<NN>-<slug>.js, the file the catalog derives, read from the package that runs the engine and never from the corpus or the working directory.

calledBindings line 34 · specs/consumers/agent-surface.evaluation-sink.sdp.md:34

a called recipe receives the caller's g, graph and report, the same objects; its parameters object as params; and recipes itself, so one recipe may call another.

callRejections line 35 · specs/consumers/agent-surface.evaluation-sink.sdp.md:35

recipes: the catalog holds no recipe <number> rejects an integer the catalog does not list; recipes: <value> is not a recipe number rejects a value that is not an integer; recipes: recipe <number> takes one parameters object rejects parameters that are null, an array, a string, a number or a boolean.

no citation recorded

evaluatorExport line 36 · specs/consumers/agent-surface.evaluation-sink.sdp.md:36

evaluateBody(body: string, input: { graph: GraphSchema; report?: ValidationReport; params?: Readonly<Record<string, unknown>> }): Promise<unknown>, exported from the package's main entry, @libar-dev/software-delivery-protocol; it binds g to the reader over graph, report to the given report or, when absent, the validation report of graph, params to the given object or {}, and recipes over the same three, and resolves to the body's return.

no citation recorded

evaluatorRejections line 37 · specs/consumers/agent-surface.evaluation-sink.sdp.md:37

a body that does not parse rejects with an Error whose message is the body does not parse at line L, column C: <message>, the text the sink prints after sdp q: ; a body that throws rejects with what it threw; params that are not a plain object reject before the body runs.

Verifier bindings

• spec:consumers.agent-surface.evaluation-sink.exported-evaluator · A script holding a graph runs a shipped recipe through the exported evaluator · declared · example enabled · specs/consumers/agent-surface.evaluation-sink.exported-evaluator.sdp.md
• spec:consumers.agent-surface.evaluation-sink.recipe-call · A body calls a shipped recipe and returns its answer unchanged · declared · example enabled · specs/consumers/agent-surface.evaluation-sink.recipe-call.sdp.md
• spec:consumers.agent-surface.evaluation-sink.unknown-recipe · A call to a recipe the catalog does not hold fails the body · declared · example enabled · specs/consumers/agent-surface.evaluation-sink.unknown-recipe.sdp.md
• test:protocol.evaluation-sink · front-door checks verify how the sink takes a body, prints its return and refuses · anchored · test anchor binding present · test/cli-q.test.ts:81
• test:protocol.query-answer-shapes · anchored · test anchor binding present · test/cli-q.test.ts:730

Requirement drawing

Decisions

• spec:decisions.agent-front-door

  The front door is two entrances over one seam: the package exports the reader constructor, and the CLI carries a single evaluation sink that derives the graph in process, injects that same reader, and prints the body's pre-shaped return.

• api:protocol.evaluate-body · evaluates bodies and shipped recipes over one in-memory reader, graph and report · src/reader/evaluate-body.ts:120

  Component: component:protocol.reader · the typed graph contract and body evaluator · src/reader/reader.ts:671 · layer application · context protocol

  Uses

  None.

• 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
• component:protocol.reader · the typed graph contract and body evaluator · src/reader/reader.ts:671 · 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.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol
  • component:protocol.notation · the leaf step codec · src/notation/slots.ts:261 · layer domain · context protocol
  • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:72 · layer domain · 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

  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.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

outcome

Execute a recipe call with a parameter through evaluateBody over a graph the script derived once, and compare its answer with the recipe's shipped file evaluated over the same graph.

assumptions

• The world writes the probe corpus of the recipe-call example and derives its graph once with the package's extract. It awaits evaluateBody with the body return recipes(26, { severity: "warning" }); and that graph, then awaits evaluateBody with the text of dist/recipes/26-dependency-cycles.js, the same graph and the parameters { severity: "warning" }, and compares the two answers. Neither call derives the graph.

Examples

Given a probe corpus in which two Specs depend on each other through dependsOn
Given a body that calls {call: "recipe 26 with the severity warning"}
When the body runs {entrance: "through the exported evaluator over a graph derived once"}
Then the call {outcome: "resolves"}
Then the answer equals the shipped recipe file's own answer over the same graph and parameters: {sameAnswer: true}

Verifier bindings

• test:protocol.consumers.agent-surface.evaluation-sink.exported-evaluator · anchored · test anchor binding present · test/reach-examples.test.ts:416

Requirement drawing

• Satisfying or referencing units: no recorded binding.

Decisions

No decision record named.

No implementation neighborhood recorded.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

outcome

Execute a recipe call through sdp q and compare its answer with the answer of the recipe's shipped file over the same graph.

assumptions

• The world writes a probe corpus of two story-altitude behavior Specs, each stating idea with an Intent outcome and each declaring dependsOn on the other. It runs sdp q --json on the probe root with the body return recipes(26);, then runs sdp q --json on the same root with the text of dist/recipes/26-dependency-cycles.js as the body, and compares the two printed answers.

Examples

Given a probe corpus in which two Specs depend on each other through dependsOn
Given a body that calls {call: "recipe 26 with no parameters"}
When the body runs {entrance: "through sdp q"}
Then the call {outcome: "resolves"}
Then the answer equals the shipped recipe file's own answer over the same graph and parameters: {sameAnswer: true}

Verifier bindings

• test:protocol.consumers.agent-surface.evaluation-sink.recipe-call · anchored · test anchor binding present · test/reach-examples.test.ts:404

Requirement drawing

• Satisfying or referencing units: no recorded binding.

Decisions

No decision record named.

No implementation neighborhood recorded.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

outcome

Execute a call to a recipe number the catalog does not list through sdp q and read the rejection.

assumptions

• The world writes the probe corpus of the recipe-call example and runs sdp q on its root with the body return recipes(99);. It reads the exit code and the one stderr line, and takes the rejection as that line's text after sdp q: .

Examples

Given a probe corpus in which two Specs depend on each other through dependsOn
Given a body that calls {call: "a recipe number the catalog does not hold"}
When the body runs {entrance: "through sdp q"}
Then the call {outcome: "rejects"}
Then the rejection reads {rejection: "recipes: the catalog holds no recipe 99"}

Verifier bindings

• test:protocol.consumers.agent-surface.evaluation-sink.unknown-recipe · anchored · test anchor binding present · test/reach-examples.test.ts:410

Requirement drawing

• Satisfying or referencing units: no recorded binding.

Decisions

No decision record named.

No implementation neighborhood recorded.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

problem

A corpus with rules of its own checks them off the one validation path, reading the carriers a second way and reporting in a form no Protocol surface reads.

outcome

Let a corpus author its own graph rules and have their findings join the one validation report, so no corpus re-parses its carriers to check itself.

rule line 38 · specs/validation/corpus-rules.sdp.md:38

A corpus rule is a graph body the corpus authors, given g, graph, report, params and recipes as a recipe body is, and returning findings that each carry a rule id, a subject, a message and a severity.

rule.readsGraphOnly line 39 · specs/validation/corpus-rules.sdp.md:39

A corpus rule reads the one derived graph, the Protocol's report and the params the operator supplies for its file, directly or through the shipped recipes it calls, and no carrier, source file or network; that is the rule author's obligation, because the runner evaluates the body with the trust sdp q asks and claims no sandbox.

no example exercises it

Cited at

• test/skills.test.ts:1475

rule.operatorNamed line 40 · specs/validation/corpus-rules.sdp.md:40

Validation runs corpus rules only from a file the operator names with sdp validate --rules PATH, which may repeat, and never from a file it finds in the corpus or in a configuration; it asks the trust sdp q already asks, to run code the operator chose.

no example exercises it

rule.namedOrder line 41 · specs/validation/corpus-rules.sdp.md:41

Rules files run one at a time in the order named, each to completion, after the Protocol's validators; every file receives the same Protocol report and none sees another file's findings, so the order changes only the order of the output.

spec:validation.corpus-rules.copies-contain-changes · enabled

rule.copiesPerFile line 42 · specs/validation/corpus-rules.sdp.md:42

Each rules file receives its own copy of the graph and the report, made after the graph is written, and its own params, so a body that changes what it receives changes no node, edge, delivery fact or Protocol finding, and nothing another rules file receives.

spec:validation.corpus-rules.copies-contain-changes · enabled

rule line 43 · specs/validation/corpus-rules.sdp.md:43

Each rules file receives as params only the parameters the operator names after its --rules and before the next --rules, or {} when none follow it, so no file receives a parameter meant for another.

rule line 44 · specs/validation/corpus-rules.sdp.md:44

A rule id names one check within its rules file; two files may use the same id, and their findings stay apart by the file that reported them.

rule line 45 · specs/validation/corpus-rules.sdp.md:45

Each corpus finding names its rule and its rules file as its source. The Protocol states none of these rules: a shipped recipe that a corpus names as a rules file checks the rule data the corpus passes it.

rule line 46 · specs/validation/corpus-rules.sdp.md:46

Corpus findings stand outside the conformance and honesty families, in a section of the output labelled as the corpus's own and tallied on a summary line of their own, so the two families keep their meaning, the guardrail that checks never judge content quality or workflow keeps binding the Protocol's own validators, and no corpus finding adds to, suppresses or changes a Protocol finding or the exit reason it sets.

rule.exitCode line 47 · specs/validation/corpus-rules.sdp.md:47

A corpus finding carries severity error or warning. When the operator names --rules, an error corpus finding makes sdp validate exit nonzero and a warning stays informative; without --rules no corpus rule runs and only the Protocol's validators set the exit code.

spec:validation.corpus-rules.error-finding-fails · enabled, spec:validation.corpus-rules.warning-finding-informs · enabled

rule.neverMovesFloor line 48 · specs/validation/corpus-rules.sdp.md:48

A corpus finding moves no readiness floor and reaches no other surface: not the report sdp q hands a body, not the reader, not the written graph, and not the Design Review or another projection.

no example exercises it

rule.brokenRuleFails line 49 · specs/validation/corpus-rules.sdp.md:49

A rules file that cannot be read or does not parse, a body that throws, or an answer that is not an object with a findings array of well-formed findings is a rule execution failure; sdp validate reports it in the corpus section and exits nonzero, so a broken rule never passes as a clean run. A failed file reports none of its findings, and the other files still run.

spec:validation.corpus-rules.malformed-finding-fails · enabled

rule.watchReruns line 50 · specs/validation/corpus-rules.sdp.md:50

sdp validate --watch with --rules reads and runs every named rules file afresh in each cycle, after the Protocol's validators, and a create, change, delete or rename of a named rules file starts a cycle as a carrier edit does, wherever the file lives, under a directory discovery skips such as node_modules included.

spec:validation.corpus-rules.rules-edit-starts-a-cycle · enabled

rule.watchedParams line 51 · specs/validation/corpus-rules.sdp.md:51

Under --watch, each cycle after the first reads again every file a --params @PATH or KEY=@PATH after a --rules names, and an edit to such a file starts a cycle, wherever the file lives; a file that cannot be read or parsed then fails only the rules file it belongs to, for that cycle, while the first cycle's read refuses the command as paramsFlag states.

spec:validation.corpus-rules.params-edit-starts-a-cycle · enabled, spec:validation.corpus-rules.unreadable-params-fail-one-file · enabled

rule.recipesAsRules line 52 · specs/validation/corpus-rules.sdp.md:52

Address resolution (recipe 25) and dependency cycles (recipe 26) answer with findings beside the rest of their answers, as the architecture walk (recipe 42), external registers (recipe 50) and entry citations (recipe 51) do, so a corpus names any of those shipped files as a rules file, or calls it through recipes from a rules file of its own.

spec:consumers.agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run · enabled, spec:consumers.agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run · enabled

rule line 53 · specs/validation/corpus-rules.sdp.md:53

When the graph does not derive, no rules file runs, and the corpus summary line says so.

6 unkeyed rules.

Verifying examples

Given a probe corpus in which {corpus: "two Specs depend on each other through dependsOn"}
Given the caller passes the addresses {addresses: "none"}
When the shipped {recipe: "dependency cycles"} file runs {invocation: "as a rules file named by sdp validate --rules"}
Then the command exits {exitCode: 1}
Then the answer carries {findings: 1} findings with the rule ids {ruleIds: "dependency-cycle"}

Given a probe corpus in which {corpus: "one Spec depends on another"}
Given the caller passes the addresses {addresses: "spec:probe.one#design.absent"}
When the shipped {recipe: "address resolution"} file runs {invocation: "as a rules file named by sdp validate --rules"}
Then the command exits {exitCode: 1}
Then the answer carries {findings: 1} findings with the rule ids {ruleIds: "unresolved-address"}

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "empties the graph it receives"}
Given a second rules file that returns one warning when the graph it receives holds no node
When the probe corpus is validated with the rules files named by --rules in that order
Then the command exits {exitCode: 0}
Then the Protocol summary line reads {protocolSummary: "validate: 0 errors · 0 warnings (conformance + honesty over the one graph)"}
Then the corpus summary line reads {corpusSummary: "corpus rules: 0 errors · 0 warnings · 0 of 2 files failed (the corpus's own rules)"}

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "returns one error finding"}
When the probe corpus is validated with the rules files named by --rules in that order
Then the command exits {exitCode: 1}
Then the Protocol summary line reads {protocolSummary: "validate: 0 errors · 0 warnings (conformance + honesty over the one graph)"}
Then the corpus summary line reads {corpusSummary: "corpus rules: 1 errors · 0 warnings · 0 of 1 files failed (the corpus's own rules)"}

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "returns a finding with no subject"}
When the probe corpus is validated with the rules files named by --rules in that order
Then the command exits {exitCode: 1}
Then the Protocol summary line reads {protocolSummary: "validate: 0 errors · 0 warnings (conformance + honesty over the one graph)"}
Then the corpus summary line reads {corpusSummary: "corpus rules: 0 errors · 0 warnings · 1 of 1 files failed (the corpus's own rules)"}

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "reads a parameter file that gains a key after the first cycle under --watch"}
Given a second rules file that returns one warning when the graph it receives holds no node
When the probe corpus is validated with the rules files named by --rules in that order
Then the second cycle's corpus summary line reads {corpusSummary: "corpus rules: 0 errors · 2 warnings · 0 of 2 files failed (the corpus's own rules)"}

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "is rewritten to return one error finding after the first cycle under --watch"}
Given a second rules file that returns one warning when the graph it receives holds no node
When the probe corpus is validated with the rules files named by --rules in that order
Then the second cycle's corpus summary line reads {corpusSummary: "corpus rules: 1 errors · 0 warnings · 0 of 2 files failed (the corpus's own rules)"}

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "reads a parameter file that stops being JSON after the first cycle under --watch"}
Given a second rules file that returns one warning when the graph it receives holds no node
When the probe corpus is validated with the rules files named by --rules in that order
Then the second cycle's corpus summary line reads {corpusSummary: "corpus rules: 0 errors · 0 warnings · 1 of 2 files failed (the corpus's own rules)"}
Then the watcher is still running after the second cycle: {running: true}

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "returns one warning finding"}
When the probe corpus is validated with the rules files named by --rules in that order
Then the command exits {exitCode: 0}
Then the Protocol summary line reads {protocolSummary: "validate: 0 errors · 0 warnings (conformance + honesty over the one graph)"}
Then the corpus summary line reads {corpusSummary: "corpus rules: 0 errors · 1 warnings · 0 of 1 files failed (the corpus's own rules)"}

Example space

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first:"returns one error finding"|"returns one warning finding"|"returns a finding with no subject"|"empties the graph it receives"|"is rewritten to return one error finding after the first cycle under --watch"|"reads a parameter file that gains a key after the first cycle under --watch"|"reads a parameter file that stops being JSON after the first cycle under --watch"}
Given a second rules file that returns one warning when the graph it receives holds no node
When the probe corpus is validated with the rules files named by --rules in that order
Then the command exits {exitCode:number}
Then the Protocol summary line reads {protocolSummary:string}
Then the corpus summary line reads {corpusSummary:string}
Then the second cycle's corpus summary line reads {corpusSummary:string}
Then the watcher is still running after the second cycle: {running:boolean}

rulesFlag line 56 · specs/validation/corpus-rules.sdp.md:56

sdp validate [root] [--exclude PATH]... [--check-clean | --watch] [--rules PATH [--params JSON | --params @PATH | --params KEY=@PATH]...]...; --rules and --params are options of validate alone, a --params before the first --rules is refused, one file named twice is refused, including through a symlink, and each PATH resolves from the working directory, as a --params @PATH file does. Diagnostics retain the path the operator named.

no citation recorded

paramsFlag line 57 · specs/validation/corpus-rules.sdp.md:57

--params on validate takes the three forms of sdp q --params with the same refusals, before the graph derives; each --params belongs to the nearest --rules before it in the argument list, whatever other options stand between them; one file's parameters merge as sdp q merges them, a key given twice for one file is refused, two files may each take the same key, and a file with no --params after it receives {}.

no citation recorded

rulesFile line 58 · specs/validation/corpus-rules.sdp.md:58

a rules file is UTF-8 text holding one plain JavaScript async function body, the form sdp q evaluates, with the bindings g, graph, report, params and recipes; the runner reads the text and never imports it as a module, so no file extension is required and a catalog recipe file under dist/recipes/ is a lawful rules file.

ruleAnswer line 59 · specs/validation/corpus-rules.sdp.md:59

{ findings: [] }: the body returns an object whose findings is an array, possibly empty; the runner reads findings and nothing else, so the answer's other keys stay the body's own data and are never printed.

no citation recorded

ruleFinding line 60 · specs/validation/corpus-rules.sdp.md:60

{ validatorId, subjectId, severity, message, relatedId?, path?, file?, line? }, where validatorId is the rule id, one token matching ^[a-z][a-z0-9-]*$, so it never reads as a Protocol validator id; subjectId and message are non-empty strings; severity is "error" or "warning"; relatedId and path are strings; file is a non-empty root-relative POSIX path, with absolute paths, backslashes and traversal above the root refused, and line a positive integer that requires file; the runner ignores a finding's other keys.

Cited at

• test/skills.test.ts:1474

corpusFinding line 61 · specs/validation/corpus-rules.sdp.md:61

{ rulesFile, validatorId, subjectId, severity, message, relatedId?, path?, file?, line? } is the corpus branch of the finding currency, where rulesFile is the path as the operator named it; it carries no family, and the Protocol's findings keep their shape.

no citation recorded

corpusReport line 62 · specs/validation/corpus-rules.sdp.md:62

the report a run with --rules builds keeps the Protocol's findings unchanged in findings and adds corpusFindings, the corpus findings of each file that did not fail, in the order the files are named and then in the order returned, and corpusFailures, one { rulesFile, reason } for each failed file in the order named, never a finding; the report a rules file receives, like the one sdp q hands a body, carries neither.

corpusSection line 63 · specs/validation/corpus-rules.sdp.md:63

on standard error, after every Protocol finding, each rules file in the order named prints the line corpus rules <path> and then its findings in the order returned, each in the one composition of location, severity in brackets, rule id and message; a failed file prints corpus rules <path> failed: <reason> in place of its findings.

corpusSummary line 64 · specs/validation/corpus-rules.sdp.md:64

corpus rules: <errors> errors · <warnings> warnings · <failed> of <files> files failed (the corpus's own rules), written to standard output directly after the Protocol's summary line, which stays as spec:validation.diagnostic-rendering pins it; without --rules no such line prints; when the graph does not derive, no rules file runs and no Protocol summary line prints, and the corpus line, the last line on standard output, reads corpus rules: not run, the graph did not derive.

no citation recorded

exitCodes line 65 · specs/validation/corpus-rules.sdp.md:65

with --rules, sdp validate exits 1 when a Protocol finding is an error, a corpus finding is an error, a rules file fails or the graph does not derive, and 0 otherwise; the two summary lines say which.

failureReasons line 66 · specs/validation/corpus-rules.sdp.md:66

<reason> is cannot be read (<cause>), does not parse at line <L>, column <C>: <cause>, threw: <message on one line>, returned no findings array, followed by ; diagnostics: <the answer's diagnostics as JSON> when the answer carries diagnostics or by ; unknownParams: <as JSON>; accepts: <as JSON> when it carries unknownParams, finding <N> has no lawful <field>, with N counted from 1, or, under --watch after the first cycle, its parameters cannot be read (<cause>) when a parameter file named after its --rules cannot be read or parsed.

no citation recorded

Verifier bindings

• spec:consumers.agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run · The shipped dependency-cycles file fails a rules run on a cycle · declared · example enabled · specs/consumers/agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run.sdp.md
• spec:consumers.agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run · The shipped address-resolution file fails a rules run on an address that names no entry · declared · example enabled · specs/consumers/agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run.sdp.md
• spec:validation.corpus-rules.copies-contain-changes · A rules file that empties its graph leaves the next file's graph whole · declared · example enabled · specs/validation/corpus-rules.copies-contain-changes.sdp.md
• spec:validation.corpus-rules.error-finding-fails · An error from a corpus rule fails validation and leaves the Protocol's line alone · declared · example enabled · specs/validation/corpus-rules.error-finding-fails.sdp.md
• spec:validation.corpus-rules.malformed-finding-fails · A finding with no subject fails its rules file · declared · example enabled · specs/validation/corpus-rules.malformed-finding-fails.sdp.md
• spec:validation.corpus-rules.params-edit-starts-a-cycle · Editing a parameter file starts a cycle that reads the new parameters · declared · example enabled · specs/validation/corpus-rules.params-edit-starts-a-cycle.sdp.md
• spec:validation.corpus-rules.rules-edit-starts-a-cycle · Rewriting a rules file under node_modules starts a cycle that runs the new body · declared · example enabled · specs/validation/corpus-rules.rules-edit-starts-a-cycle.sdp.md
• spec:validation.corpus-rules.unreadable-params-fail-one-file · A parameter file that stops being JSON fails only its own rules file, and the watcher runs on · declared · example enabled · specs/validation/corpus-rules.unreadable-params-fail-one-file.sdp.md
• spec:validation.corpus-rules.warning-finding-informs · A warning from a corpus rule informs and passes · declared · example enabled · specs/validation/corpus-rules.warning-finding-informs.sdp.md

Requirement drawing

Decisions

• spec:decisions.architectural-annotation

  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.

• 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.corpus-rule-runner · runs selected corpus rules and separates their failures · src/cli/corpus-rules.ts:65

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

• impl:protocol.corpus-rules · runs copied rule bodies after Protocol validation and composes the separate corpus report, output and exit · src/cli/validate-view-command.ts:79

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

• impl:protocol.validate-watch · watches carrier directories and coalesces events into a pending validation rerun · src/cli/validate-watch.ts:591

  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.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

outcome

Execute the watched-parameters rule on a parameter file, outside the probe root, that gains a key after the first cycle.

assumptions

• The world writes the probe corpus of the error example, a parameter file outside the probe root holding { "one": 1 }, a first rules file whose body returns one warning finding for each key of its params, named by --rules and followed by --params @PATH naming that file, and the second rules file of the copy example. It starts the watcher as the rules-edit example does and, after the first cycle, writes { "one": 1, "two": 2 } to the parameter file, then reads the second cycle's corpus summary line and stops the watcher.

Examples

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "reads a parameter file that gains a key after the first cycle under --watch"}
Given a second rules file that returns one warning when the graph it receives holds no node
When the probe corpus is validated with the rules files named by --rules in that order
Then the second cycle's corpus summary line reads {corpusSummary: "corpus rules: 0 errors · 2 warnings · 0 of 2 files failed (the corpus's own rules)"}

Verifier bindings

• test:protocol.validation.corpus-rules.params-edit-starts-a-cycle · anchored · test anchor binding present · test/reach-examples.test.ts:454

Requirement drawing

• Satisfying or referencing units: no recorded binding.

Decisions

No decision record named.

No implementation neighborhood recorded.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

outcome

Execute the watch rule on a rules file that lives under a directory discovery skips and is rewritten after the first cycle.

assumptions

• The world writes the probe corpus of the error example, a first rules file under the probe root's node_modules/probe/ whose body returns one warning finding, and the second rules file of the copy example. It starts sdp validate --watch on the probe root with the two files named by --rules in that order, waits for the first cycle, rewrites the first file to return one error finding in place of the warning, waits for the second cycle, reads its corpus summary line and stops the watcher.

Examples

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "is rewritten to return one error finding after the first cycle under --watch"}
Given a second rules file that returns one warning when the graph it receives holds no node
When the probe corpus is validated with the rules files named by --rules in that order
Then the second cycle's corpus summary line reads {corpusSummary: "corpus rules: 1 errors · 0 warnings · 0 of 2 files failed (the corpus's own rules)"}

Verifier bindings

• test:protocol.validation.corpus-rules.rules-edit-starts-a-cycle · anchored · test anchor binding present · test/reach-examples.test.ts:448

Requirement drawing

• Satisfying or referencing units: no recorded binding.

Decisions

No decision record named.

No implementation neighborhood recorded.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

outcome

Execute the watched-parameters rule on a parameter file that holds text that is not JSON after the first cycle.

assumptions

• The world writes the probe corpus, parameter file and rules files of the parameter-edit example and starts the watcher as that example does. After the first cycle it writes text that is not JSON to the parameter file, waits for the second cycle, reads its corpus summary line and, on standard error, the line corpus rules <path> failed: its parameters cannot be read (<cause>) for the first file, then checks that the process is still running before it stops the watcher.

Examples

Given a probe corpus the Protocol's validators find clean
Given a first rules file that {first: "reads a parameter file that stops being JSON after the first cycle under --watch"}
Given a second rules file that returns one warning when the graph it receives holds no node
When the probe corpus is validated with the rules files named by --rules in that order
Then the second cycle's corpus summary line reads {corpusSummary: "corpus rules: 0 errors · 0 warnings · 1 of 2 files failed (the corpus's own rules)"}
Then the watcher is still running after the second cycle: {running: true}

Verifier bindings

• test:protocol.validation.corpus-rules.unreadable-params-fail-one-file · anchored · test anchor binding present · test/reach-examples.test.ts:460

Requirement drawing

• Satisfying or referencing units: no recorded binding.

Decisions

No decision record named.

No implementation neighborhood recorded.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

problem

An author editing a Spec re-runs sdp validate by hand after every save.

outcome

Let sdp validate --watch re-run the one validation path on every carrier change and stay alive after findings, as a loop for authoring and never a second validation path.

rule line 19 · specs/consumers/validate-watch.sdp.md:19

sdp validate --watch [root] installs its watcher first, then runs the same validate path sdp validate runs, from scratch, once at start and again after every carrier create, change, delete or rename under the root.

rule line 20 · specs/consumers/validate-watch.sdp.md:20

A carrier ends in .sdp.md, .sdp.gherkin or .sdp.ts. The watcher ignores the directories discovery skips, the configured exclusion prefixes and every non-carrier path other than the rules files and parameter files --rules names, which it watches wherever they live, as spec:validation.corpus-rules#rule.watchReruns and spec:validation.corpus-rules#rule.watchedParams state; a removed watched directory and an event with no filename each schedule a run because their affected carriers cannot be named.

rule line 21 · specs/consumers/validate-watch.sdp.md:21

Events that arrive while a run is in progress coalesce into one pending run.

rule.operatorStop line 22 · specs/consumers/validate-watch.sdp.md:22

Findings print as sdp validate prints them and the process stays alive; operator SIGINT terminates the process with exit 0 even while a rules body is active, without waiting for it. No further rules file runs or output is written after the stop.

no example exercises it

rule line 23 · specs/consumers/validate-watch.sdp.md:23

For sdp validate, --watch cannot combine with --check-clean, and it re-runs on carrier edits and on edits to the files --rules names, and never on source edits, so an author re-runs validation after editing an anchor. This rule restricts no other verb's --watch, which its own Spec states.

4 unkeyed rules.

Verifier bindings

• test:protocol.validate-watch · watch-loop checks verify the validate --watch authoring loop · anchored · test anchor binding present · test/cli.test.ts:1670
• test:protocol.validate-watch-rules · process checks verify operator stop during active corpus rules · anchored · test anchor binding present · test/corpus-rules.test.ts:343

Requirement drawing

• Declared verifying examples: no declared verifying example.

Decisions

No decision record named.

• 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.validate-watch · watches carrier directories and coalesces events into a pending validation rerun · src/cli/validate-watch.ts:591

  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.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

problem

An adopter that cites entry addresses outside its Specs resolves each one with its own grammar, and a Spec can rest on itself through a dependsOn chain no one has traced.

outcome

Resolve a list of entry addresses and report every dependsOn cycle with catalog recipes, so neither is rebuilt by hand.

rule line 28 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:28

Address resolution reads params.addresses, falling back to the catalog sample when absent, and returns one row per input in input order, repeats included; each row carries address, resolves, id, section, key, value, file, line and reason. A resolving row carries the entry text or value and its recorded file and line, null when unlocated, with reason null. A miss keeps id, section and key when parsed, keeps value, file and line null, and gives reason malformed for an input that is no entry address, a bare Spec id included, or spec, section or entry for an absent Spec, section or key; malformed carries expected, the grammar in one line, and section or entry carries available, the keys that section holds sorted in code-unit order.

rule line 29 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:29

Address resolution follows the checked-mentions address grammar: a design or ui key resolves as an own key other than description, a question key resolves when an open question carries it, a rule key resolves through behavior.ruleKeys to its rule or flow text, and a term key resolves through model.termKeys to its term's definition; totals count inputs, resolving rows and each miss reason.

rule line 30 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:30

Dependency cycles take no parameter other than severity and read the whole graph. They report every set of two or more Specs in which each Spec reaches every other through declared dependsOn edges, and every Spec that declares dependsOn on itself and belongs to no such set. An edge whose target is not a Spec in the graph is ignored.

rule line 31 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:31

Each reported set lists its members sorted by id in code-unit order and one cycle through it as a closed path that starts and ends at its first member. The cycle is the shortest such path, found by a breadth-first walk from the first member over targets in code-unit order and restricted to the set; a Spec that depends only on itself reports the path of that Spec twice. Sets are ordered by their first member, and the totals count the sets, the self-dependent Specs, and the Specs in any set.

rule line 32 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:32

Both recipes report their answers and never refuse an authored dependency cycle.

rule.addressFindings line 33 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:33

Address resolution answers with findings beside its totals and rows: one finding for each row that does not resolve, in input order, the catalog sample's rows included, so the shipped file runs as a rules file over the addresses its --params names.

spec:consumers.agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run · enabled

rule.cycleFindings line 34 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:34

Dependency cycles answers with findings beside its totals and cycles: one finding for each entry of cycles, in that order, naming the first member and the closed path through the set.

spec:consumers.agent-surface.address-and-cycle-recipes.chain-reports-nothing · enabled, spec:consumers.agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run · enabled

rule.findingsSeverity line 35 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:35

Both recipes take params.severity, "error" by default or "warning", which every finding they return carries; another value returns { diagnostics } and no findings, which fails the file as a rules file.

spec:consumers.agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run · enabled, spec:consumers.agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run · enabled

rule.answersUnchanged line 36 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:36

Apart from findings, both answers keep their shapes: the totals, rows and cycles stated above.

spec:consumers.agent-surface.address-and-cycle-recipes.chain-reports-nothing · enabled

5 unkeyed rules.

Verifying examples

Given a probe corpus in which {corpus: "one Spec depends on another"}
Given the caller passes the addresses {addresses: "none"}
When the shipped {recipe: "dependency cycles"} file runs {invocation: "through sdp q"}
Then the command exits {exitCode: 0}
Then the answer carries {findings: 0} findings with the rule ids {ruleIds: ""}

Given a probe corpus in which {corpus: "two Specs depend on each other through dependsOn"}
Given the caller passes the addresses {addresses: "none"}
When the shipped {recipe: "dependency cycles"} file runs {invocation: "as a rules file named by sdp validate --rules"}
Then the command exits {exitCode: 1}
Then the answer carries {findings: 1} findings with the rule ids {ruleIds: "dependency-cycle"}

Given a probe corpus in which {corpus: "one Spec depends on another"}
Given the caller passes the addresses {addresses: "spec:probe.one#design.absent"}
When the shipped {recipe: "address resolution"} file runs {invocation: "as a rules file named by sdp validate --rules"}
Then the command exits {exitCode: 1}
Then the answer carries {findings: 1} findings with the rule ids {ruleIds: "unresolved-address"}

Example space

Given a probe corpus in which {corpus:"two Specs depend on each other through dependsOn"|"one Spec depends on another"}
Given the caller passes the addresses {addresses:string}
When the shipped {recipe:"address resolution"|"dependency cycles"} file runs {invocation:"through sdp q"|"as a rules file named by sdp validate --rules"}
Then the command exits {exitCode:number}
Then the answer carries {findings:number} findings with the rule ids {ruleIds:string}

addressFinding line 39 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:39

{ validatorId: "unresolved-address", subjectId, severity, message }, where subjectId is the input when it is a string holding at least one character that is not white space, and the input's JSON text otherwise, and message reads <subjectId> does not resolve: <why>, <why> being not an entry address, no Spec <id>, <id> has no <section> entries or <id> has no <section> entry <key> by the row's reason.

no citation recorded

cycleFinding line 40 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:40

{ validatorId: "dependency-cycle", subjectId, severity, message, file, line }, where subjectId is the entry's first member, message reads <first member> rests on itself through dependsOn: <cycle>, <cycle> being the entry's closed path joined by -> , file is the first member's carrier, and line is the line the location table records for its dependsOn relation to the path's second id, left out when not located.

no citation recorded

severityDiagnostic line 41 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:41

{ diagnostics: [{ parameter: "severity", problem: "Expected error or warning." }] } is the whole answer for a severity other than "error" or "warning".

no citation recorded

answerShapes line 42 · specs/consumers/agent-surface.address-and-cycle-recipes.sdp.md:42

address resolution returns { totals, rows, findings } and dependency cycles returns { totals, cycles, findings }; each recipe's accepted names gain severity, after its existing ones.

Verifier bindings

• spec:consumers.agent-surface.address-and-cycle-recipes.chain-reports-nothing · A dependency chain with no cycle yields no finding · declared · example enabled · specs/consumers/agent-surface.address-and-cycle-recipes.chain-reports-nothing.sdp.md
• spec:consumers.agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run · The shipped dependency-cycles file fails a rules run on a cycle · declared · example enabled · specs/consumers/agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run.sdp.md
• spec:consumers.agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run · The shipped address-resolution file fails a rules run on an address that names no entry · declared · example enabled · specs/consumers/agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run.sdp.md
• test:protocol.address-and-cycle-recipes · recipe checks verify the address resolution and dependency cycle recipes · anchored · test anchor binding present · test/recipes.test.ts:3577