feat: trace annotation body for traced citations; paperspec.traces

A trace follows one citation of a sentence of a citing paper to a passage of the
cited paper (spec/18 section 18.5). Minor change: a new body kind, optional
properties and two rules, with no valid file made invalid.

- annotation schema branch (source, selector, reference, note, verdict, proposer;
  proposer required for a Software creator); body_kind in sql/store.sql; the note
  and proposer terms of the JSON-LD context; rules layer.trace.source and
  layer.trace.target.
- paperspec.traces: resolve(annotation, citing_state, cited_state, same_as) gives
  current, changed, stale, unlinked or misresolved with open and cites; problems,
  disputes, disputed.
- fixtures/records/traces/ on writer2027fixed-ynr7.v3 and vectors/traces.jsonl
  (29 cases); check.py runs the record checks over both layers; counts, glossary,
  examples and CHANGELOG updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uy4ZYbWRoCdUtWLEfigysY

docs/comparison.md

@@ -428,7 +428,7 @@ Keep using it as a reading and distribution format.
 *Status.*
 The specification is version 0.1.0.
 `registry/formats.json` lists 32 formats: 19 are `candidate` (complete, with vectors and fixtures, ready to implement) and 13 are `provisional` (complete; expected to change as implementations gain experience): project, bundle, dataset, digitization, view, snapshot, draft-ids, exercise, submission, grade, checklist, log-entry and checkpoint ([spec/00 §0.4](../spec/00-introduction.md#04-status)).
-The repository holds 24 chapters, 43 JSON Schemas, 25 vector files, five valid fixture packages, one of them also zipped, and 31 invalid ones, each naming the rule it breaks, and a reference checker, `paperspec check`.
+The repository holds 24 chapters, 43 JSON Schemas, 26 vector files, five valid fixture packages, one of them also zipped, and 31 invalid ones, each naming the rule it breaks, and a reference checker, `paperspec check`.
 Licenses: prose CC BY 4.0; schemas, SQL, the JSON-LD context, registries, vectors and fixtures CC0 1.0; the code in `src/` Apache-2.0 ([README.md](../README.md#licenses)).
 
 *No adoption claim.*

docs/concepts.md

@@ -376,8 +376,10 @@ Claims are not defined in this repository.
 A comment, caveat or question also says what it is about with a `category` from a fixed list: a general `comment`, `context`, a `critique`, a `question`, a `correction` of an error in the paper, `feedback` for the authors, or a `resource`.
 Model-written text is always a `generated` annotation, never source, and a model's annotation stays `proposed` until a person confirms it.
 Whether a generic Web Annotation client displays an `AnchorSelector` has not been tested; the fallback exists so that it can still use the quote.
+A `trace` annotation follows a citation to the passage it rests on: it targets the citing sentence and its body names the reference, the cited paper and the passage in it.
+Whether a trace still leads there is computed from both papers rather than stored: `current`, `changed`, `stale`, `unlinked` or `misresolved`.
 Layers are `candidate`.
-Pinned by the layer records in `fixtures/records/layer/`.
+Pinned by the layer records in `fixtures/records/layer/` and `fixtures/records/traces/`, and by [vectors/traces.jsonl](../vectors/traces.jsonl).
 See [chapter 18](../spec/18-layers.md).
 
 ## Exercises

docs/examples.md

@@ -212,6 +212,38 @@ Receipts by `ana` raise `ec5jc93` and `a4jrz2t` to F3; `xjns57z` stays at F0 bec
 To compute the final level, check each receipt's signature, revocations and spot-checks, as [chapter 8](../spec/08-fidelity.md#82-levels) describes.
 The `scope` column of the third query shows the value `targeted:paperclaim`, which is data in the fixture, copied here exactly as the query prints it.
 
+## Follow a traced citation
+
+This shows how a citation leads to the passage it rests on, and how to tell that it still does.
+A trace is an annotation from the sentence that cites a paper to a passage of that paper, with the reference it follows ([chapter 18](../spec/18-layers.md#185-traced-citations)).
+The draft in the fixtures cites the main example once, and its layer of traces holds three: a model's, a person's, and a candidate a person rejected.
+The Python package `paperspec.traces` judges each against the current state of both papers:
+
+```python
+import json
+from paperspec import package, traces
+
+draft = package.read_state("fixtures/packages/writer2027fixed-ynr7.v3")
+paper = package.read_state("fixtures/packages/hale2026harmonic-damb")
+same_as = json.load(open("fixtures/packages/hale2026harmonic-damb/document.json"))["work"]["same_as"]
+annotations = [json.loads(line) for line in open("fixtures/records/traces/annotations.jsonl", encoding="utf-8")]
+for a in annotations:
+    if a["body"]["kind"] == "trace":
+        r = traces.resolve(a, draft, paper, same_as)
+        print(a["status"], r["result"], r["open"], traces.disputed(a["id"], annotations))
+```
+
+```text
+confirmed current smithlab/hale2026harmonic-damb#mhp0at8@ee42c4[48:60] True
+rejected current smithlab/hale2026harmonic-damb#kea5026@b836d5[81:105] False
+confirmed current smithlab/hale2026harmonic-damb#hj4s7pb@6c6fba False
+```
+
+Each line gives the trace's status, its outcome, the current address of the passage it leads to, and whether a reply disputes it.
+The first trace is disputed by a reply that says the table is the better passage, which is where the third trace leads.
+The outcomes here are all `current`; [vectors/traces.jsonl](../vectors/traces.jsonl) corrects the draft or the paper and shows the others: `changed` when the passage was reworded but is still found, `stale` when it is gone, `unlinked` when the sentence no longer cites the reference, and `misresolved` when the reference now resolves to another paper.
+Resolving a trace also lists the citations inside the passage, so a chain of "as previously reported" is followed one trace at a time.
+
 ## Test your implementation against a vector
 
 A test vector is a recorded input together with the output every correct implementation must produce.

docs/faq.md

@@ -107,7 +107,7 @@ A `candidate` format is complete, with vectors and fixtures, and ready to implem
 A `provisional` one is complete and expected to change as implementations gain experience.
 The provisional formats are dataset, digitization, view, project, bundle, snapshot, draft-ids, exercise, submission, grade, checklist, log-entry and checkpoint.
 
-The repository holds a reference checker (`paperspec check`), 25 vector files, five valid packages, one of them also as a zip, and 31 deliberately broken packages ([spec/00 §0.4](../spec/00-introduction.md#04-status), [spec/22](../spec/22-conformance.md)).
+The repository holds a reference checker (`paperspec check`), 26 vector files, five valid packages, one of them also as a zip, and 31 deliberately broken packages ([spec/00 §0.4](../spec/00-introduction.md#04-status), [spec/22](../spec/22-conformance.md)).
 
 ## What does it not do?
 

docs/glossary.md

@@ -194,6 +194,10 @@ Text policy
 Tile
 :   One file of a transparency log served statically: 256 hashes of one level of the tree, or 256 entries, so a client fetches only the subtrees it needs. ([23.4](../spec/23-log.md#234-serving-a-log))
 
+Trace
+:   An annotation that follows one citation of a sentence to the passage of the cited paper it rests on, naming the reference it follows and, when a tool found the passage, the tool, its run, score and rank.
+Whether it still leads there is computed from both papers as current, changed, stale, unlinked or misresolved, and it is disputed while a reply assesses it. ([18.5](../spec/18-layers.md#185-traced-citations))
+
 Verdict
 :   A judgment of whether a cited passage supports a citing sentence: supports, partly, does not, or cannot tell. ([19.2](../spec/19-exercises.md#192-verdicts))
 

docs/overview.md

@@ -56,7 +56,7 @@ It appears inside hashed data and test vectors, and it is separate from the repo
 | [registry/](../registry/README.md) | The list of formats, the rule IDs a checker reports, download-stamp rules, and default rights requirements. |
 | [tools/](../tools/README.md) | How to run the reference commands: `paperspec check` checks everything, `paperspec build` rebuilds the fixtures and vectors, and `paperspec load` loads packages into SQLite. |
 | [src/paperspec/](../src/paperspec/) | The oracle, a compact implementation of every rule, which the other repositories of the project install as the Python package `paperspec`. |
-| [vectors/](../vectors/README.md) | 25 files of test vectors: inputs and the exact outputs every implementation must compute. |
+| [vectors/](../vectors/README.md) | 26 files of test vectors: inputs and the exact outputs every implementation must compute. |
 | [fixtures/](../fixtures/README.md) | Five valid example packages, one of them also as a zip, 31 deliberately broken ones that each break one named rule, example records, and the test keys that signed them. All text is synthetic. |
 | [sql/](../sql/README.md) | Tables for SQLite, Dolt and PostgreSQL, and a SQLite bundle with full-text search. |
 | [context/](../context/README.md) | The JSON-LD context that makes annotation layers W3C Web Annotations. |