The evaluation sink runs one body and prints its return

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

  External run evidence from test/reach-examples.test.ts

  Test anchors: test:protocol.consumers.agent-surface.address-and-cycle-recipes.chain-reports-nothing, test:protocol.consumers.agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run, test:protocol.consumers.agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run, test:protocol.consumers.agent-surface.evaluation-sink.exported-evaluator, test:protocol.consumers.agent-surface.evaluation-sink.recipe-call, test:protocol.consumers.agent-surface.evaluation-sink.unknown-recipe, test:protocol.validation.corpus-rules.params-edit-starts-a-cycle, test:protocol.validation.corpus-rules.rules-edit-starts-a-cycle, test:protocol.validation.corpus-rules.unreadable-params-fail-one-file. Specs verified by those bindings: spec:consumers.agent-surface.address-and-cycle-recipes, spec:consumers.agent-surface.address-and-cycle-recipes.chain-reports-nothing, spec:consumers.agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run, spec:consumers.agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run, spec:consumers.agent-surface.evaluation-sink, spec:consumers.agent-surface.evaluation-sink.exported-evaluator, spec:consumers.agent-surface.evaluation-sink.recipe-call, spec:consumers.agent-surface.evaluation-sink.unknown-recipe, spec:validation.corpus-rules, spec:validation.corpus-rules.params-edit-starts-a-cycle, spec:validation.corpus-rules.rules-edit-starts-a-cycle, spec:validation.corpus-rules.unreadable-params-fail-one-file.

  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
  gives every watch example the heavy-test timeout	not recorded	passed	2.43 ms
  leaves non-watch corpus-rule points and incomplete points unspecified	not recorded	passed	0.36 ms
  leaves address points outside the oracle's bound probes unspecified	not recorded	passed	0.17 ms
  executes the bound example against a fresh world	A body calls a shipped recipe and returns its answer unchanged (spec:consumers.agent-surface.evaluation-sink.recipe-call)	passed	21.85 ms
  executes the bound example against a fresh world	A call to a recipe the catalog does not hold fails the body (spec:consumers.agent-surface.evaluation-sink.unknown-recipe)	passed	3.48 ms
  executes the bound example against a fresh world	A script holding a graph runs a shipped recipe through the exported evaluator (spec:consumers.agent-surface.evaluation-sink.exported-evaluator)	passed	3.89 ms
  executes the bound example against a fresh world	A dependency chain with no cycle yields no finding (spec:consumers.agent-surface.address-and-cycle-recipes.chain-reports-nothing)	passed	3.1 ms
  executes the bound example against a fresh world	The shipped dependency-cycles file fails a rules run on a cycle (spec:consumers.agent-surface.address-and-cycle-recipes.cycle-fails-a-rules-run)	passed	5.52 ms
  executes the bound example against a fresh world	The shipped address-resolution file fails a rules run on an address that names no entry (spec:consumers.agent-surface.address-and-cycle-recipes.unresolved-address-fails-a-rules-run)	passed	3.86 ms
  executes the bound example against a fresh world	Rewriting a rules file under node_modules starts a cycle that runs the new body (spec:validation.corpus-rules.rules-edit-starts-a-cycle)	passed	16.19 ms
  executes the bound example against a fresh world	Editing a parameter file starts a cycle that reads the new parameters (spec:validation.corpus-rules.params-edit-starts-a-cycle)	passed	46.21 ms
  executes the bound example against a fresh world	A parameter file that stops being JSON fails only its own rules file, and the watcher runs on (spec:validation.corpus-rules.unreadable-params-fail-one-file)	passed	103.81 ms

• 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

  External run evidence from test/cli-q.test.ts

  Test anchors: test:protocol.evaluation-sink, test:protocol.query-answer-shapes, test:protocol.query-params. Specs verified by those bindings: spec:consumers.agent-surface.evaluation-sink, spec:consumers.agent-surface.recipe-parameters.

  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
  evaluates an argv body over the derived graph and prints the pre-shaped return	sdp q — the agent front door	passed	30.42 ms
  reads the body from stdin when stdin is not a terminal	sdp q — the agent front door	passed	9.06 ms
  prefers the argv body over stdin when both are available	sdp q — the agent front door	passed	14.89 ms
  refuses with no body when stdin is a terminal instead of waiting on it	sdp q — the agent front door	passed	0.38 ms
  refuses an empty body rather than evaluating nothing	sdp q — the agent front door	passed	0.26 ms
  prints JSON for --json	sdp q — the agent front door	passed	6.89 ms
  exits 1 and names the failure when the body throws	sdp q — the agent front door	passed	5.4 ms
  exits 1 on a body that does not compile	sdp q — the agent front door	passed	10.85 ms
  awaits an asynchronous body	sdp q — the agent front door	passed	6.69 ms
  injects a live reader: the entry adapters answer from the derived graph	sdp q — the agent front door	passed	6.81 ms
  injects the raw graph schema alongside the reader	sdp q — the agent front door	passed	7.44 ms
  injects the validation report as data, never as a gate	sdp q — the agent front door	passed	5.16 ms
  runs the body when the graph merely reports findings — checks never gate the read path	sdp q — the agent front door	passed	3.87 ms
  refuses to run the body when the graph does not derive, rendering the extraction findings	sdp q — the agent front door	passed	11.48 ms
  reports a body that returns nothing rather than printing a silent blank	sdp q — the agent front door	passed	9.5 ms
  refuses an unknown option and a second body without deriving anything	sdp q — the agent front door	passed	0.31 ms
  refuses an empty --root instead of reinterpreting it as the working directory	sdp q — the agent front door	passed	0.13 ms
  refuses a root that is not a directory, naming the resolved absolute path	sdp q — the agent front door	passed	0.15 ms
  honours --exclude, so the sink omits exactly the paths the caller names	sdp q — the agent front door	passed	3.39 ms
  runs the body when extraction itself only warns — the warning is data, never a gate	sdp q — the agent front door	passed	3.56 ms
  detects a terminal from the file descriptor, never from a stream property	sdp q — the agent front door	passed	3.91 ms
  puts --exclude through the strict exclusion contract before deriving anything	sdp q — the agent front door	passed	0.33 ms
  reports a throw from rendering the return value through the one diagnostic currency	sdp q — the agent front door	passed	3.17 ms
  refuses a --json return value whose toJSON yields no JSON form	sdp q — the agent front door	passed	4.15 ms
  writes nothing: the sink is a pure read tool	sdp q — the agent front door	passed	273.64 ms
  injects params as a fourth binding beside g, graph and report	sdp q --params — a recipe parameter as data	passed	12.05 ms
  binds params to an empty object without the flag	sdp q --params — a recipe parameter as data	passed	4.98 ms
  passes any JSON object through unchanged	sdp q --params — a recipe parameter as data	passed	8.55 ms
  reads params from a file named with @PATH, a byte-order mark dropped	sdp q --params — a recipe parameter as data	passed	4.8 ms
  refuses inline text that is not JSON before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.82 ms
  refuses an empty value before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.34 ms
  refuses null before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.29 ms
  refuses an array before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.27 ms
  refuses a string before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.18 ms
  refuses a number before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.18 ms
  refuses a boolean before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.16 ms
  refuses a file that cannot be read before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.33 ms
  refuses an @ with no path before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.37 ms
  refuses a missing value before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.27 ms
  refuses a flag in place of the value before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.21 ms
  refuses a repeated key before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.28 ms
  refuses a key outside the lower-camel grammar before the body runs: exit 1, one line, nothing on stdout	sdp q --params — a recipe parameter as data	passed	0.23 ms
  refuses a file whose JSON is not an object, in one line naming the file	sdp q --params — a recipe parameter as data	passed	0.38 ms
  refuses a file whose text is not JSON, in one line naming the file	sdp q --params — a recipe parameter as data	passed	0.35 ms
  locates a refused body return )	query body positions and merged parameters	passed	1.02 ms
  locates a refused body return 1; foo bar	query body positions and merged parameters	passed	0.61 ms
  locates a refused body let x = 'a' 'bcdef';	query body positions and merged parameters	passed	0.54 ms
  locates a refused body const value = 1; return )	query body positions and merged parameters	passed	0.46 ms
  locates a refused body return (	query body positions and merged parameters	passed	0.68 ms
  names a body that stops short instead of the wrapper's closing brace	query body positions and merged parameters	passed	0.52 ms
  keeps runtime failures separate, including a thrown SyntaxError	query body positions and merged parameters	passed	0.39 ms
  refuses repeated top-level keys inside one inline object before extraction	query body positions and merged parameters	passed	65.21 ms
  refuses repeated top-level keys inside one file object before extraction	query body positions and merged parameters	passed	80.84 ms
  accepts nested duplicates and duplicate-looking text inside values	query body positions and merged parameters	passed	1.16 ms
  binds a keyed file's JSON value null beside merged objects	query body positions and merged parameters	passed	1 ms
  binds a keyed file's JSON value 1 beside merged objects	query body positions and merged parameters	passed	37.32 ms
  binds a keyed file's JSON value "text" beside merged objects	query body positions and merged parameters	passed	14.05 ms
  binds a keyed file's JSON value 4 beside merged objects	query body positions and merged parameters	passed	46.29 ms
  binds a keyed file's JSON value true beside merged objects	query body positions and merged parameters	passed	58.06 ms
  binds a keyed file's JSON value {"nested":{"a":1}} beside merged objects	query body positions and merged parameters	passed	72.25 ms
  refuses duplicate keys from inline-file before extraction	query body positions and merged parameters	passed	0.63 ms
  refuses duplicate keys from file-inline before extraction	query body positions and merged parameters	passed	0.28 ms
  refuses duplicate keys from keyed-inline before extraction	query body positions and merged parameters	passed	96.72 ms
  refuses duplicate keys from inline-keyed before extraction	query body positions and merged parameters	passed	0.58 ms
  refuses duplicate keys from keyed-keyed before extraction	query body positions and merged parameters	passed	0.51 ms
  keeps merged parameter keys writable for the caller's body	query body positions and merged parameters	passed	0.91 ms
  refuses an invalid keyed input key=@ before extraction	query body positions and merged parameters	passed	0.34 ms
  refuses an invalid keyed input key=@missing-file.json before extraction	query body positions and merged parameters	passed	0.27 ms
  refuses an invalid keyed input bad-key=@missing-file.json before extraction	query body positions and merged parameters	passed	0.16 ms
  refuses an invalid keyed input bad_key=@missing-file.json before extraction	query body positions and merged parameters	passed	0.29 ms
  reads inline JSON and @PATH before KEY=@PATH when the input contains =@	query body positions and merged parameters	passed	0.69 ms
  refuses a keyed file holding invalid JSON before extraction	query body positions and merged parameters	passed	0.4 ms
  merges own keys without treating __proto__ as an assignment	query body positions and merged parameters	passed	0.57 ms

• test:protocol.query-answer-shapes · anchored · test anchor binding present · test/cli-q.test.ts:730

Requirement drawing

Decisions

• The agent front door is one evaluation sink over the exported reader

  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.