The CLI names the engine that produced a result

problem

An adopter pinned to a build of the Protocol needs to name that build: the package version alone does not change between commits, so when a check changes with no Spec changed, nothing tells the engine moving from the corpus moving.

outcome

Let sdp --version name the package version and the commit the build came from, without putting either into the graph.

rule line 22 · specs/consumers/engine-provenance.sdp.md:22

sdp --version prints one line, sdp <version> (<commit>), and exits 0. The version is the package's own version; the commit is the full hash the build was made from, or unknown when the build could not read one; a build from a checkout with uncommitted changes names the commit checked out when it ran.

rule line 23 · specs/consumers/engine-provenance.sdp.md:23

The build records the commit in a file beside the compiled CLI, and the CLI reads that file; it never runs git at run time.

rule line 24 · specs/consumers/engine-provenance.sdp.md:24

The build reads the commit from git first. When git gives no full commit, it reads the archive's substituted commit file; a full commit there names the archived revision, and an absent, unsubstituted or malformed file leaves the commit unknown.

rule line 25 · specs/consumers/engine-provenance.sdp.md:25

Neither the version nor the commit enters the graph, a projection or a generated contract, so a derived artifact stays a function of the corpus alone.

4 unkeyed rules.

archiveCommit line 28 · specs/consumers/engine-provenance.sdp.md:28

.git-archive-commit contains $Format:%H$ in a checkout and is marked export-subst in .gitattributes, so git archives carry their full commit. The build reads the trimmed file only as a full Git object name, never as a command or an abbreviated hash.

no citation recorded

Verifier bindings

• test:protocol.engine-provenance · version checks verify the engine provenance line and the build's commit record · anchored · test anchor binding present · test/cli.test.ts:2371

  External run evidence from test/cli.test.ts

  Test anchors: test:protocol.engine-provenance, test:protocol.extraction-determinism, test:protocol.projections-model.publication, test:protocol.regenerability, test:protocol.validate-watch. Specs verified by those bindings: spec:consumers.engine-provenance, spec:consumers.projections-model, spec:consumers.validate-watch, spec:extraction.determinism, spec:extraction.regenerability.

  Run 2: external run evidence from vitest 4.1.10

  Build: CI 380 · Branch: feature/roadmap-and-slices-v0 · Commit: 34909918bf0be0e849959644401797191cae379f · Start: 2026-10-22T17:42:16.533Z · Stop: 2026-10-22T17:42:27.785Z

  Name	Suite	Result	Duration
  prints the exact help text for no args	sdp cli	passed	1.39 ms
  points operators to the shipped on-ramps and Protocol corpus	sdp cli	passed	1.4 ms
  describes both anchor forms and non-failing warnings in help	sdp cli	passed	0.33 ms
  prints the exact help text for --help	sdp cli	passed	0.14 ms
  builds the checkout-v1 example: writes graph, contracts, and registrar manifest atomically	sdp cli	passed	92.85 ms
  invalidates an existing Design Review when build replaces its source graph	sdp cli	passed	51.1 ms
  views the self-hosting corpus from the default repository root	sdp cli	passed	8406.8 ms
  renders contracts warnings through the one formatter and counts them in the summary	sdp cli	passed	6.91 ms
  withholds case-colliding contract paths with a warning: graph kept, nothing gates	sdp cli	passed	3.45 ms
  passes --check-clean on the example (determinism self-check through the CLI)	sdp cli	passed	28.36 ms
  end-to-end determinism self-check: delete generated/, rebuild, byte-identical	sdp cli	passed	106.14 ms
  fails clean on a root that is not a directory: one line, exit 1, never a stack trace	sdp cli	passed	0.32 ms
  rejects an unknown option: one line, exit 1, nothing runs	sdp cli	passed	0.1 ms
  accepts repeatable --exclude paths for build	sdp cli	passed	3.25 ms
  accepts repeatable --exclude paths for validate	sdp cli	passed	3.57 ms
  accepts repeatable --exclude paths for view	sdp cli	passed	4.61 ms
  uses the identical normalized exclusions in both --check-clean extractions	sdp cli	passed	4.99 ms
  refuses invalid --exclude path "" before build writes	sdp cli	passed	0.75 ms
  refuses invalid --exclude path "." before build writes	sdp cli	passed	0.21 ms
  refuses invalid --exclude path "./explorations" before build writes	sdp cli	passed	0.27 ms
  refuses invalid --exclude path "explorations/" before build writes	sdp cli	passed	0.16 ms
  refuses invalid --exclude path "/explorations" before build writes	sdp cli	passed	0.19 ms
  refuses invalid --exclude path "../x" before build writes	sdp cli	passed	0.18 ms
  refuses invalid --exclude path "a/../b" before build writes	sdp cli	passed	0.13 ms
  refuses invalid --exclude path "a//b" before build writes	sdp cli	passed	0.12 ms
  refuses invalid --exclude path "a\\b" before build writes	sdp cli	passed	0.21 ms
  refuses a missing --exclude operand before build writes	sdp cli	passed	0.28 ms
  names a flag supplied as an --exclude operand before build writes	sdp cli	passed	0.19 ms
  documents repeatable --exclude paths in help	sdp cli	passed	0.06 ms
  rejects a second root argument: one line, exit 1, nothing runs	sdp cli	passed	0.16 ms
  notes an empty authored model: zero spec files still builds and exits 0, but says where it looked	sdp cli	passed	0.59 ms
  renders a finding's location exactly once, from the structured fields: file:line — [severity]	sdp cli	passed	2.19 ms
  renders a Gherkin parser failure through the public CLI	sdp cli	passed	1.24 ms
  exits 1, writes nothing, and removes a stale graph.json on a hard-error corpus	sdp cli	passed	1.87 ms
  fails build on an integer-like design key holding a static value	sdp cli	passed	1.25 ms
  fails build on an integer-like design key holding a non-static value	sdp cli	passed	1.05 ms
  fails build on an integer-like design key holding a method	sdp cli	passed	1.09 ms
  fails build on an integer-like design key holding an accessor	sdp cli	passed	1.22 ms
  fails --check-clean on a diverging second extraction: exit 1, the stale graph.json removed	sdp cli	passed	7.21 ms
  fails --check-clean on a diverging second contract generation: exit 1, no artifact survives	sdp cli	passed	18.15 ms
  owns the contracts tree wholesale: with nothing to generate, a stale contracts dir is removed	sdp cli	passed	2.71 ms
  reconciles a registrar sibling that a later generation no longer owes	sdp cli	passed	19.57 ms
  fails --check-clean on registrar-byte drift and removes the uncertified known set	sdp cli	passed	26.76 ms
  passes --check-clean without a prior manifest when no registrars are owed	sdp cli	passed	3.91 ms
  fails --check-clean on registrar manifest whitespace drift	sdp cli	passed	26 ms
  fails --check-clean on registrar manifest ignored property drift	sdp cli	passed	26.54 ms
  removes graph, contracts, manifest, and registrar siblings after a staged write failure	sdp cli	passed	19.02 ms
  fails clean when extraction throws past discovery: one line, exit 1, the stale graph.json removed	sdp cli	passed	0.6 ms
  fails clean when generated exists as a file: one line each for build and view, never a stack trace	sdp cli	passed	5.38 ms
  names the survivor when a recovery-path removal is denied: a stale artifact never silently reads as current	sdp cli	passed	0.56 ms
  stops a build when an existing Design Review cannot be invalidated	sdp cli	passed	1.62 ms
  fails clean when the checks throw: one line, exit 1, the built graph.json stays	sdp cli	passed	2.52 ms
  suppresses the empty-model note when spec files were found but none reified — a failed file is not an absent one	sdp cli	passed	1.52 ms
  treats a root of only ordinary .feature files as an empty authored model, not a missing-identity error	sdp cli	passed	0.65 ms
  suppresses the empty-model note when a failed .sdp.gherkin finding.file matches the carrier suffix predicate	sdp cli	passed	1.01 ms
  builds a mixed root with one .sdp.gherkin carrier and ignores the ordinary .feature sibling	sdp cli	passed	0.88 ms
  removes the temp twin on a failed build and a failed view — no partial .tmp artifact survives	sdp cli	passed	8.95 ms
  recognizes the published-bin path: a .bin-style symlink resolves to the entry module	sdp cli	passed	0.43 ms
  exits 0 quietly on a stdout EPIPE and stays fatal for any other stream error	sdp cli	passed	0.53 ms
  validates the example: exit 0, the artifact written, and no warning	sdp cli	passed	28.78 ms
  gates on the checks, not the build: a clean-building broken link validates to exit 1 with the artifact kept	sdp cli	passed	2.67 ms
  short-circuits the checks on extraction hard errors: validate keeps build semantics	sdp cli	passed	1.64 ms
  prints help plus an unknown-command error	sdp cli	passed	0.13 ms
  views the example: validate + the Design Review written, with no warning	sdp cli	passed	33.87 ms
  owns the view directory wholesale: a stale page does not survive a re-render	sdp cli	passed	15.8 ms
  regenerates the view byte-identically: delete generated/, re-view, same bytes	sdp cli	passed	24.79 ms
  writes the view even when checks fail: findings render in it, the exit code is validate's	sdp cli	passed	2.06 ms
  keeps build semantics on extraction hard errors: no graph, no view, stale view removed	sdp cli	passed	1.87 ms
  fails view --check-clean on a diverging second render: exit 1, the stale view removed	sdp cli	passed	6.53 ms
  fails clean when the render throws: one line on stderr, exit 1, the stale view removed	sdp cli	passed	2.71 ms
  closes the compiled watch process with exit 0 after operator SIGINT	sdp validate --watch	passed	299.82 ms
  documents --watch as a validate-only authoring loop	sdp validate --watch	passed	0.19 ms
  rejects --watch on build with a named error and no watcher	sdp validate --watch	passed	0.18 ms
  rejects --watch on view with a named error and no watcher	sdp validate --watch	passed	0.06 ms
  rejects --watch on census with a named error and no watcher	sdp validate --watch	passed	0.05 ms
  rejects --watch on mermaid with a named error and no watcher	sdp validate --watch	passed	0.05 ms
  rejects --watch on gherkin with a named error and no watcher	sdp validate --watch	passed	0.04 ms
  rejects --watch on import with a named error and no watcher	sdp validate --watch	passed	0.17 ms
  rejects --watch on new with a named error and no watcher	sdp validate --watch	passed	0.2 ms
  rejects --watch on q with a named error and no watcher	sdp validate --watch	passed	0.18 ms
  rejects --watch --check-clean with a named error and no watcher	sdp validate --watch	passed	0.12 ms
  installs the watcher before the first validation cycle	sdp validate --watch	passed	4.45 ms
  catches an edit during the first cycle with exactly one coalesced rerun	sdp validate --watch	passed	5.23 ms
  coalesces a burst during an active cycle into exactly one rerun	sdp validate --watch	passed	4.92 ms
  prints validation findings and keeps watching until abort exits 0	sdp validate --watch	passed	2.68 ms
  ignores generated, dist, node_modules, coverage, dot directories, and configured excludes	sdp validate --watch	passed	5.24 ms
  coalesces production-shaped events from later turns into one pending rerun	sdp validate --watch	passed	7.83 ms
  does not natively subscribe to excluded or generated subtrees	sdp validate --watch	passed	69.25 ms
  routes a native watcher error through a typed channel and closes once	sdp validate --watch	passed	3.1 ms
  clean-repo determinism: the full pipeline at a different absolute path is byte-identical	not recorded	passed	67.67 ms
  prints one line naming the package version and the recorded commit, and exits 0	sdp --version	passed	0.49 ms
  names the commit unknown when the build recorded none or recorded something else	sdp --version	passed	0.33 ms
  reads the version from the package manifest two directories above the CLI module	sdp --version	passed	0.38 ms
  documents --version and --params in the usage text	sdp --version	passed	0.14 ms
  records the checked-out commit at build time, or unknown when git cannot name one	sdp --version	passed	11.15 ms
  publishes the commit the build step reads from git beside the CLI	sdp --version	passed	0.9 ms
  builds commit metadata from a substituted git archive extracted without .git	sdp --version	passed	64.59 ms
  uses only a full archive commit when git gives none, keeping git first	sdp --version	passed	0.68 ms
  answers from the compiled CLI with the commit its build recorded beside it	sdp --version	passed	327.1 ms
  runs recipe 4 as shipped, its changed files passed with --params @PATH	a shipped recipe file through the compiled CLI	passed	363.4 ms

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.build-artifacts · the build step that writes each catalog recipe to dist/recipes and records the build commit beside the CLI · src/cli/build-artifacts.ts:182

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

  Uses

  None.

• impl:protocol.engine-provenance-cli · prints sdp version and the commit parsed from the build-info file beside the compiled CLI · src/cli/sdp.ts:102

  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.