CI run records are joined to verifiers in a view

problem

A reader who wants to know whether a bound verifier passed has to leave the Protocol's views for CI, and an adopter that keeps run records has no view that shows them beside the binding without mistaking them for a delivery fact.

outcome

Show a verifier's recorded runs beside its binding in a view, labelled as external input with its commit, while the graph keeps recording only that the binding exists.

Open questions

• non-blocking · question.freshness line 28 · specs/observation/run-evidence.sdp.md:28 · How does a view say a run is stale: by its commit against the commit being read, or by whether the bound files changed between the two?Decider: ownerProvisional: Display the run and source commit identifiers when they differ, as the differing-commit rule requires; whether freshness also follows changes to bound files remains open.

rule.graphUntouched line 33 · specs/observation/run-evidence.sdp.md:33

Run records are an input a view reads beside the graph, named by the caller; the graph never holds them, and no node, edge or delivery fact derives from them.

spec:observation.run-evidence.absolute-path-joins · enabled, spec:observation.run-evidence.unanchored-file-unjoined · enabled

rule.fileGrain line 34 · specs/observation/run-evidence.sdp.md:34

A run record joins every verifier whose test anchor sits in the test file the record names, because the file is the binding grain of both anchor forms; each test name in the record shows as a row under that verifier. The join is at file grain: a result is evidence from the verifier's file, never the result of that verifier, because a file may hold several suites and a filtered run may exercise only one.

spec:observation.run-evidence.absolute-path-joins · enabled

rule.ctrfInput line 35 · specs/observation/run-evidence.sdp.md:35

The Protocol reads run records in the Common Test Report Format, CTRF, an open JSON schema with reporters for the common test runners, passed to a view as a recipe parameter. A record joins only when its reporter fills CTRF's optional filePath field, and an adopter with records of another shape maps them into CTRF itself.

spec:observation.run-evidence.absolute-path-joins · enabled

rule.pathNormalization line 36 · specs/observation/run-evidence.sdp.md:36

A record's file path joins a test anchor's file when, with each backslash written as a slash and a leading ./ removed, it equals that file or ends with a slash followed by that file; when several anchored files match, the longest joins.

spec:observation.run-evidence.absolute-path-joins · enabled

rule.unjoinedReported line 37 · specs/observation/run-evidence.sdp.md:37

A record that names no file path, or a file that holds no test anchor, is reported as unjoined with its reason, never dropped, and an input that is not a CTRF report is reported with its problem while the other inputs still join.

spec:observation.run-evidence.unanchored-file-unjoined · enabled

rule.commitField line 38 · specs/observation/run-evidence.sdp.md:38

A run's commit is CTRF's results.environment.commit, and a run without one reads not recorded; given the commit being read, the recipe says for each run whether its commit is that commit, and never says the run is fresh or stale.

no example exercises it

rule line 39 · specs/observation/run-evidence.sdp.md:39

A view shows each run beside the verifiers anchored in its file, with its result, its commit and the input it came from, labelled as external run evidence from that file and never as has-verifier, implemented or a pass verdict for one verifier.

rule line 40 · specs/observation/run-evidence.sdp.md:40

A run whose commit differs from the commit being read shows both commits, so a reader sees how old it is.

rule.studioInput line 41 · specs/observation/run-evidence.sdp.md:41

The Design Review stays a function of the graph alone and shows no run; run evidence appears only in a view that explicitly admits records as external input: recipe 45, and the Studio built with run records, which shows them on its runs page, in its tests lens and on the Spec pages of the Specs their files verify.

no example exercises it

2 unkeyed rules.

Verifying examples

Given a CTRF report whose test {testName: "renders the page"} names the file {filePath: "/home/runner/work/repo/repo/test/page.test.ts"} and reports the result {status: "passed"}
Given the graph holds a test anchor in the file {anchorFile: "test/page.test.ts"} that verifies {specId: "spec:probe.page"}
When recipe 45 reads the report
Then the test joins the file {joinedFile: "test/page.test.ts"}
Then the test is unjoined for the reason {reason: "none"}
Then the delivery facts of the verified Spec are unchanged: {factsUnchanged: true}

Given a CTRF report whose test {testName: "counts the rows"} names the file {filePath: "test/other.test.ts"} and reports the result {status: "failed"}
Given the graph holds a test anchor in the file {anchorFile: "test/page.test.ts"} that verifies {specId: "spec:probe.page"}
When recipe 45 reads the report
Then the test joins the file {joinedFile: ""}
Then the test is unjoined for the reason {reason: "noTestAnchor"}
Then the delivery facts of the verified Spec are unchanged: {factsUnchanged: true}

Example space

Given a CTRF report whose test {testName:string} names the file {filePath:string} and reports the result {status:"passed"|"failed"|"skipped"}
Given the graph holds a test anchor in the file {anchorFile:string} that verifies {specId:string}
When recipe 45 reads the report
Then the test joins the file {joinedFile:string}
Then the test is unjoined for the reason {reason:"none"|"noFilePath"|"noTestAnchor"}
Then the delivery facts of the verified Spec are unchanged: {factsUnchanged:boolean}

runsRecipe line 44 · specs/observation/run-evidence.sdp.md:44

recipe 45, run evidence, takes params.runs, one CTRF report or a list of them in input order, required; params.commit, the commit being read, optional; and params.spec, a Spec id, optional, which keeps only the files whose test anchors verify that Spec directly or through an enabled example. It returns { inputs, diagnostics, totals, files, unjoined }, and { diagnostics } alone when params.runs is missing or holds no report it can read.

ctrfFields line 45 · specs/observation/run-evidence.sdp.md:45

the recipe reads reportFormat and specVersion; results.tool.name and version; results.summary with tests, passed, failed, skipped, pending, other, start and stop; results.environment with commit, branchName, buildName and buildNumber; and per test name, status, duration, filePath and suite; it reads no other field. A readable CTRF report has reportFormat: "CTRF" and a specVersion, as the CTRF schema requires; a report missing either produces a run diagnostic and contributes no run rows.

runInput line 46 · specs/observation/run-evidence.sdp.md:46

{ index: number; tool: string | null; toolVersion: string | null; specVersion: string; commit: string | null; branch: string | null; build: string | null; start: number | null; stop: number | null; summary: { tests: number; passed: number; failed: number; skipped: number; pending: number; other: number }; sameCommit: boolean | null }, one per readable report, index its position from 0, build the build name and number joined by a space, and sameCommit null without params.commit or without a run commit.

no citation recorded

runFile line 47 · specs/observation/run-evidence.sdp.md:47

{ file: string; anchors: { id: string; verifies: string[] }[]; specs: string[]; results: { input: number; name: string; suite: string | null; status: string; duration: number | null }[] }, one per anchored test file a record joins, sorted by file, specs the Specs its anchors verify directly or through an enabled example, sorted, and results in input order and then record order, suite the record's suite path joined by > , and duration the recorded milliseconds without rounding; a view formats that number for display.

no citation recorded

unjoinedRow line 48 · specs/observation/run-evidence.sdp.md:48

{ input: number; name: string; filePath: string | null; status: string; reason: "noFilePath" | "noTestAnchor" }, in input order and then record order.

no citation recorded

runDiagnostic line 49 · specs/observation/run-evidence.sdp.md:49

{ input: number | null; problem: string }, for a missing params.runs, with input null, or for an input that is not an object, has no results.tests list, lacks reportFormat or specVersion, or names a reportFormat other than CTRF.

no citation recorded

runTotals line 50 · specs/observation/run-evidence.sdp.md:50

{ inputs: number; tests: number; joined: number; unjoined: number; files: number; specs: number }, counting the readable reports, every test they hold, the tests joined and unjoined, the files joined, and the distinct Specs those files verify.

no citation recorded

Verifier bindings

• spec:observation.run-evidence.absolute-path-joins · A test whose reporter wrote an absolute path joins its anchored file · declared · example enabled · specs/observation/run-evidence.absolute-path-joins.sdp.md

  External run evidence from test/studio-s4.test.ts

  Test anchors: test:protocol.run-absolute, test:protocol.run-external, test:protocol.run-unjoined, test:protocol.studio-graph-only, test:protocol.studio-inputs-both-given, test:protocol.studio-stamp-apart. Specs verified by those bindings: spec:consumers.spec-studio.data.inputs, spec:consumers.spec-studio.data.inputs.both-given, spec:consumers.spec-studio.data.inputs.graph-only, spec:consumers.spec-studio.runs-page, spec:consumers.spec-studio.runs-page.external-evidence, spec:consumers.spec-studio.sharing, spec:consumers.spec-studio.sharing.stamp-written-apart, spec:observation.run-evidence, spec:observation.run-evidence.absolute-path-joins, spec:observation.run-evidence.unanchored-file-unjoined.

  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
  recipe 45 joins normalized paths, preserves records and graph facts, and diagnoses other inputs	not recorded	passed	40.92 ms
  renders external run evidence with result rows, metadata, diagnostics and conditional navigation	not recorded	passed	67.13 ms
  reads repeated --runs before extraction and leaves input bytes untouched	not recorded	passed	77.06 ms
  stamps apart, touches no page, refuses bad sources and removes the stamp on rebuild	not recorded	passed	32.06 ms
  executes the bound example against a fresh world	A test whose reporter wrote an absolute path joins its anchored file (spec:observation.run-evidence.absolute-path-joins)	passed	3.95 ms
  executes the bound example against a fresh world	A test in a file with no test anchor is reported as unjoined (spec:observation.run-evidence.unanchored-file-unjoined)	passed	8.41 ms
  executes the bound example against a fresh world	The runs page shows a run as external evidence from a test file (spec:consumers.spec-studio.runs-page.external-evidence)	passed	12.66 ms
  executes the bound example against a fresh world	Without inputs the page set is the graph's alone (spec:consumers.spec-studio.data.inputs.graph-only)	passed	34.33 ms
  executes the bound example against a fresh world	Both inputs add their pages, named, and the same inputs write the same bytes (spec:consumers.spec-studio.data.inputs.both-given)	passed	96.39 ms
  executes the bound example against a fresh world	The stamp is written beside the page set, and a later build removes it (spec:consumers.spec-studio.sharing.stamp-written-apart)	passed	39.65 ms
  the stamp links source locations only after an HTTP stamp loads, encoding path segments	not recorded	passed	7.34 ms
  recipe 45 picks the longest suffix and scopes through enabled examples at file grain	not recorded	passed	11.36 ms
  ships a reusable preview, disabled by default, and deploys its own pull requests with runs and diff	not recorded	passed	14.97 ms
  the tests lens counts file results once per Spec and names every run input	not recorded	passed	27.49 ms
  the Pack sentence keeps the graph's binding limit and positively names external evidence	not recorded	passed	16.99 ms
  run metadata labels build and branch, and absent fields read not recorded	not recorded	passed	0.47 ms
  unjoined records escape outside names and explain both reason codes in words	not recorded	passed	11.52 ms
  run files show the file alone, bindings and Suite, with one header per run	not recorded	passed	15.6 ms
  recipe 45 does not join a suffix inside a path segment	not recorded	passed	3.52 ms
  stamp defaults to unknown and a stamped page set passes check-clean	not recorded	passed	53.15 ms
  every reusable preview job's permissions fit the CI caller's grant	not recorded	passed	15.05 ms
  PR checks and preview stamps name the same default merge checkout	not recorded	passed	8 ms
  preview download is optional and cancelled or skipped checks do not call it	not recorded	passed	5.14 ms
  deploy checks the enabled Pages source before writing: gh-pages	not recorded	passed	19.63 ms
  deploy checks the enabled Pages source before writing: main	not recorded	passed	30.39 ms
  deploy checks the enabled Pages source before writing: disabled	not recorded	passed	17.67 ms
  deploy succeeds only once Pages publishes the pushed commit: an unrelated errored build is newest	not recorded	passed	140.26 ms
  deploy succeeds only once Pages publishes the pushed commit: a retried build follows an errored one	not recorded	passed	28.04 ms
  deploy succeeds only once Pages publishes the pushed commit: the build errors	not recorded	passed	54.7 ms
  deploy succeeds only once Pages publishes the pushed commit: the commit is never built	not recorded	passed	180.31 ms
  deploy succeeds only once Pages publishes the pushed commit: the answer arrives after the wait	not recorded	passed	1540.7 ms
  preview still stamps and uploads rendered pages when evidence is absent and validation fails	not recorded	passed	59.93 ms
  places external file rows under their verifier and renders shared files once	not recorded	passed	35.82 ms
  accepts the preview workflow's base and run flags together	not recorded	passed	18.01 ms
  formats external run durations to at most two decimals on every page	not recorded	passed	10.89 ms

• spec:observation.run-evidence.unanchored-file-unjoined · A test in a file with no test anchor is reported as unjoined · declared · example enabled · specs/observation/run-evidence.unanchored-file-unjoined.sdp.md

Requirement drawing

Decisions

• Bindings state existence, not liveness

  Delivery facts record bindings and enabled verifier existence; coverage gaps and human readiness practice remain explicit without becoming graph facts.

• component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol

  Uses

  • 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.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.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.run-evidence-recipe · asserts realization of Run evidence in docs/agent-surface/recipes.md · test/recipes.test.ts:7277

  Uses

  None.

• impl:protocol.studio-runs-page · renders readable CTRF inputs, file results, unjoined records and diagnostics · src/projections/studio/pages/runs-page.ts:6

  Component: component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · 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.