The graph records where anchored source cites an entry address

problem

A test that checks one pinned declaration names its entry address only in its own text, so no view links the declaration to the line that checks it, and a reader holding the declaration cannot find its assertion.

outcome

Record each entry address an anchored source file cites, with its file and line, as an inferred citation that confers nothing, so a view can show the test line that checks a pinned declaration.

rule.anchoredFilesOnly line 30 · specs/extraction/entry-citations.sdp.md:30

The extractor reads citations from each source file it reads for anchors that carries at least one anchor, of either form and any namespace, after the same exclusions; a file that carries no anchor, a carrier and any other file is not read for citations.

spec:extraction.entry-citations.code-comment-cites-declaration · enabled, spec:extraction.entry-citations.test-title-cites-declaration · enabled, spec:extraction.entry-citations.unanchored-file-unread · enabled

rule.citationToken line 31 · specs/extraction/entry-citations.sdp.md:31

A citation is a token the prose-mention scan would read as a mention, found anywhere in such a file's text, in a comment, a string or a template literal, that holds #; a token followed by ${, directly or after the trailing punctuation the mention scan strips, is the prefix of a computed address and records no citation, whether or not the prefix parses as an entry address; a bare Spec id is not a citation.

spec:extraction.entry-citations.test-title-cites-declaration · enabled

rule.citationRow line 32 · specs/extraction/entry-citations.sdp.md:32

Each citation records the address as written, the file's root-relative path and the 1-based line the token starts on; one address written twice on one line is one row.

spec:extraction.entry-citations.test-title-cites-declaration · enabled

rule.citationTable line 33 · specs/extraction/entry-citations.sdp.md:33

The citations ride in a table of their own beside the location table, sorted and deterministic as the graph is, and Primitive and Pack nodes stay free of them.

no example exercises it

rule.inferredClaim line 34 · specs/extraction/entry-citations.sdp.md:34

The table's definition gives every citation the inferred claim, and every reader row of a citation carries it, so no consumer reads a citation as an authored binding.

no example exercises it

rule.confersNothing line 35 · specs/extraction/entry-citations.sdp.md:35

A citation mints no node or edge, confers no delivery fact, moves no readiness floor, feeds no Protocol validator and records no verdict on the citing file; removing every citation changes no node, edge, fact, floor or finding.

no example exercises it

rule.readerRows line 36 · specs/extraction/entry-citations.sdp.md:36

The reader resolves each citation by the rules address resolution applies, and the Spec context carries the citations whose address names that Spec as its entry citations, each with the entry it names, whether it resolves and why not, the citing file and line, the anchors recorded at that file and those of them that are test anchors verifying the Spec.

spec:extraction.entry-citations.test-title-cites-declaration · enabled, spec:extraction.entry-citations.unresolved-citation · enabled

rule.declarationLines line 37 · specs/extraction/entry-citations.sdp.md:37

Those rows let a view show, beside each pinned declaration of a Spec, the anchored lines that cite it, with no join of its own; a row reads as a test line only when a test: anchor at its file verifies the cited Spec, directly or through an example that verifies it, every other row stays a citation with its file and line, and no row says what a test asserts or whether it passed.

spec:extraction.entry-citations.code-comment-cites-declaration · enabled, spec:extraction.entry-citations.test-title-cites-declaration · enabled

rule.citationRecipe line 38 · specs/extraction/entry-citations.sdp.md:38

Entry citations, recipe 51, lists for a Pack, a list of Specs or the corpus each pinned declaration and every other cited entry with the lines that cite it, and every citation that does not resolve, and answers each citation that does not resolve, and only those, as a finding, so a corpus may name the shipped file as a rules file.

spec:extraction.entry-citations.unresolved-citation · enabled

rule.unresolvedReports line 39 · specs/extraction/entry-citations.sdp.md:39

An unresolved citation stays in the table and reports only through the reader's rows and the recipe's answer, never as a Protocol finding: whether it fails a gate is the corpus's choice of rules file.

spec:extraction.entry-citations.unresolved-citation · enabled

0 unkeyed rules.

Verifying examples

Given a probe corpus whose Spec pins the declaration {declaration: "spec:probe.one#design.typeOne"}
Given a source file that {anchored: "carries a code anchor referencing the Spec"} and names the address {address: "spec:probe.one#design.typeOne"} on line {line: 9}
When the graph is derived
Then the Spec context lists {citations: 1} entry citations
Then the citation {recorded: "resolves"}
Then the citing line reads as a test line: {testLine: false}

Given a probe corpus whose Spec pins the declaration {declaration: "spec:probe.one#design.typeOne"}
Given a source file that {anchored: "carries a test anchor verifying the Spec"} and names the address {address: "spec:probe.one#design.typeOne"} on line {line: 9}
When the graph is derived
Then the Spec context lists {citations: 1} entry citations
Then the citation {recorded: "resolves"}
Then the citing line reads as a test line: {testLine: true}
Then the shipped entry-citations file named as a rules file exits {exitCode: 0}

Given a probe corpus whose Spec pins the declaration {declaration: "spec:probe.one#design.typeOne"}
Given a source file that {anchored: "carries no anchor"} and names the address {address: "spec:probe.one#design.typeOne"} on line {line: 9}
When the graph is derived
Then the Spec context lists {citations: 0} entry citations
Then the citation {recorded: "is not recorded"}

Given a probe corpus whose Spec pins the declaration {declaration: "spec:probe.one#design.typeOne"}
Given a source file that {anchored: "carries a test anchor verifying the Spec"} and names the address {address: "spec:probe.one#design.typeTwo"} on line {line: 9}
When the graph is derived
Then the Spec context lists {citations: 1} entry citations
Then the citation {recorded: "does not resolve"}
Then the shipped entry-citations file named as a rules file exits {exitCode: 1}

Example space

Given a probe corpus whose Spec pins the declaration {declaration:string}
Given a source file that {anchored:"carries a test anchor verifying the Spec"|"carries a code anchor referencing the Spec"|"carries no anchor"} and names the address {address:string} on line {line:number}
When the graph is derived
Then the Spec context lists {citations:number} entry citations
Then the citation {recorded:"resolves"|"does not resolve"|"is not recorded"}
Then the citing line reads as a test line: {testLine:boolean}
Then the shipped entry-citations file named as a rules file exits {exitCode:number}

citationTable line 42 · specs/extraction/entry-citations.sdp.md:42

citations?: readonly { address: string; file: string; line: number }[] on the graph schema beside locations, rows sorted by file, then line, then address, in code-unit order; an absent table reads as empty, and the field is additive, so the schema version's minor part rises.

no citation recorded

citationAddress line 43 · specs/extraction/entry-citations.sdp.md:43

address is the token as the prose-mention scan cuts it, its trailing punctuation removed; the sections it may name are the package's exported ENTRY_ADDRESS_SECTIONS, so an address section the grammar gains is read with no change here.

no citation recorded

readerCitation line 44 · specs/extraction/entry-citations.sdp.md:44

entryCitations: readonly { address: string; entry: string | null; resolves: boolean; reason: "malformed" | "section" | "entry" | null; file: string; line: number; anchors: readonly string[]; testAnchors: readonly string[]; claim: "inferred" }[] on the Spec context, for every row whose address's Spec part, the text before its #, is this Spec's id, where entry is the location-table entry the address names, such as design.<key> or rule[<i>], or null when it does not resolve, reason is address resolution's reason for a miss, anchors lists the ids of the anchors recorded at file in code-unit order, and testAnchors lists those of them that are test: anchors verifying this Spec, directly or through an example that verifies it; rows sort by address, then file, then line.

no citation recorded

citationsRecipe line 45 · specs/extraction/entry-citations.sdp.md:45

recipe 51, entry citations, takes at most one scope, params.pack or params.specs, the whole corpus with neither, and params.severity, "error" by default or "warning"; both scopes, an id that does not resolve or another severity returns { diagnostics: [{ parameter, problem }] } and no findings.

citationsAnswer line 46 · specs/extraction/entry-citations.sdp.md:46

{ scope, totals: { citations, citedEntries, declarations, citedDeclarations, unresolved }, entries, unresolved, findings }, where scope is { corpus: true }, { pack } or { specs }, and the totals count within the scope: the citations whose Spec part names a Spec in it, the entry rows that some citation names, the pinned declarations, those an anchored line cites, and the unresolved rows.

no citation recorded

entryRow line 47 · specs/extraction/entry-citations.sdp.md:47

{ address, spec, pinned, line, citedBy: [{ file, line, anchors, testAnchors }] }, one per pinned declaration in scope and per other entry in scope that a citation names, sorted by address; line is the entry's own recorded line or null, citedBy sorts by file, then line, and an uncited pinned declaration has an empty citedBy.

no citation recorded

unresolvedRow line 48 · specs/extraction/entry-citations.sdp.md:48

{ address, reason, file, line }, one per citation that does not resolve whose Spec part names a Spec in scope, or every such citation with no scope, reason being address resolution's, spec for an absent Spec; rows sort by file, then line, then address.

no citation recorded

citationFinding line 49 · specs/extraction/entry-citations.sdp.md:49

{ validatorId: "unresolved-citation", subjectId, severity, message, file, line } for each unresolved row, in that order, where subjectId is the address, file and line the citing site, and message reads <address> cited at <file>:<line> does not resolve: <why>, <why> as address resolution's finding words it.

no citation recorded

Verifier bindings

• spec:extraction.entry-citations.code-comment-cites-declaration · A code file's comment cites a declaration without reading as a test line · declared · example enabled · specs/extraction/entry-citations.code-comment-cites-declaration.sdp.md

  External run evidence from test/entry-citations.test.ts

  Test anchors: test:protocol.entry-citations.code-comment-cites-declaration, test:protocol.entry-citations.test-title-cites-declaration, test:protocol.entry-citations.unanchored-file-unread, test:protocol.entry-citations.unresolved-citation. Specs verified by those bindings: spec:extraction.entry-citations, spec:extraction.entry-citations.code-comment-cites-declaration, spec:extraction.entry-citations.test-title-cites-declaration, spec:extraction.entry-citations.unanchored-file-unread, spec:extraction.entry-citations.unresolved-citation.

  Run 2: external run evidence from vitest 4.1.10

  Build: CI 439 · Branch: docs/articles-refresh-1 · Commit: 61576184ea9f39b7f91c51fef5ff991b0bf2d0e6 · Start: 2026-11-04T07:59:39.962Z · Stop: 2026-11-04T08:03:39.928Z

  Name	Suite	Result	Duration
  executes the bound example against a fresh world	A test title in an anchored file cites a pinned declaration (spec:extraction.entry-citations.test-title-cites-declaration)	passed	802.48 ms
  executes the bound example against a fresh world	A code file's comment cites a declaration without reading as a test line (spec:extraction.entry-citations.code-comment-cites-declaration)	passed	721.55 ms
  executes the bound example against a fresh world	A file that carries no anchor is not read for citations (spec:extraction.entry-citations.unanchored-file-unread)	passed	785.6 ms
  executes the bound example against a fresh world	A citation of an entry its Spec lacks reports through the recipe, never as a Protocol finding (spec:extraction.entry-citations.unresolved-citation)	passed	719.33 ms
  scans comments, strings and templates, deduplicates a line and keeps code-unit order	entry citation extraction and reader	passed	38.57 ms
  records no citation for a token continued by interpolation, even when its prefix parses	entry citation extraction and reader	passed	754.9 ms
  keeps a literal malformed token beside an interpolated token on the same line	entry citation extraction and reader	passed	0.55 ms
  keeps a malformed literal before a separate template interpolation	entry citation extraction and reader	passed	0.44 ms
  records no citation for a prefix with trailing punctuation before interpolation	entry citation extraction and reader	passed	0.44 ms
  does not report a computed order key as an unresolved citation in recipe 51	entry citation extraction and reader	passed	770 ms
  recipe 51 locates a citation of the second keyed question	entry citation extraction and reader	passed	10.59 ms
  ends citation tokens at source escapes before checking for an address	entry citation extraction and reader	passed	5.8 ms
  sorts in-memory citations by address on a shared source line	entry citation extraction and reader	passed	5.14 ms
  sorts reader citations by address before file and line	entry citation extraction and reader	passed	5.16 ms
  rejects a crashed rules file even when its exit code matches the example	entry citation extraction and reader	passed	805.38 ms
  counts Unicode source line separators as TypeScript does	entry citation extraction and reader	passed	5.61 ms
  reads a file carrying only an identity anchor, and ignores carriers and unanchored sources	entry citation extraction and reader	passed	3.25 ms
  includes only tests in the citing file that verify directly or through an example	entry citation extraction and reader	passed	7.88 ms
  reads a newly shared term address through termKeys even without location rows	entry citation extraction and reader	passed	5.55 ms
  does not treat future address sections as Model terms	entry citation extraction and reader	passed	5.04 ms
  resolves UI, rules, flows and questions without depending on entry locations	entry citation extraction and reader	passed	5.8 ms

• spec:extraction.entry-citations.test-title-cites-declaration · A test title in an anchored file cites a pinned declaration · declared · example enabled · specs/extraction/entry-citations.test-title-cites-declaration.sdp.md
• spec:extraction.entry-citations.unanchored-file-unread · A file that carries no anchor is not read for citations · declared · example enabled · specs/extraction/entry-citations.unanchored-file-unread.sdp.md
• spec:extraction.entry-citations.unresolved-citation · A citation of an entry its Spec lacks reports through the recipe, never as a Protocol finding · declared · example enabled · specs/extraction/entry-citations.unresolved-citation.sdp.md

Requirement drawing

Decisions

No decision record named.

• component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:197 · 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:263 · layer domain · context protocol
  • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:76 · layer domain · context protocol
• component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol

  Uses

  • 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:263 · layer domain · context protocol
• component:protocol.reader · the typed graph contract and body evaluator · src/reader/reader.ts:697 · 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:263 · layer domain · context protocol
  • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:76 · layer domain · context protocol
• impl:protocol.entry-address-resolution · resolves entry addresses for prose validation and citation readers · src/graph/entry-address.ts:6

  Component: component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol

  Uses

  None.

• impl:protocol.entry-citation-reader · resolves citations and joins file anchors with direct and example-based test verification · src/reader/entry-citations.ts:19

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

  Uses

  None.

• impl:protocol.entry-citation-recipe · asserts realization of Entry citations in docs/agent-surface/recipes.md · test/recipes.test.ts:7078

  Uses

  None.

• impl:protocol.entry-citation-scan · records prose-mention tokens with addresses in anchored source files · src/extract/entry-citations.ts:6

  Component: component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:197 · layer application · context protocol

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.