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
This commit is contained in:
alexmandClaude committed 2026-10-17 20:12:04 -04:00
1 parent 44a8e3f07c
commit 7890fa1ad7
25 files changed
+966 -50

No files matched your search

+7 -3
View File
@@ -52,7 +52,7 @@ The procedure is the same for every file:
3.
Find the inputs and the expected outputs of the case.
The table below says which fields are which, and the chapter it links defines the rule.
Only six files, `alignment`, `corrections`, `grading`, `resolve`, `rights` and `targets`, put the expected outputs under `expect`.
Only seven files, `alignment`, `corrections`, `grading`, `resolve`, `rights`, `targets` and `traces`, put the expected outputs under `expect`.
In the other nineteen the expected outputs are fields beside the inputs, such as `output`, `sha256`, `canonical` or `parsed`.
4.
Compute each output from the inputs with your implementation.
@@ -74,11 +74,14 @@ Some files change the procedure:
- `fingerprints.jsonl` needs the download-stamp rules in [registry/stamps/scienting-stamps-1.json](../registry/stamps/scienting-stamps-1.json), which each case names in `rules`.
- `resolve.jsonl`, `grading.jsonl` and `targets.jsonl` name a package by a path from the repository root.
All three use `fixtures/packages/hale2026harmonic-damb`.
- `traces.jsonl` names two packages, `citing` (the draft) and `cited` (the main example), and for a `resolve` case lists the corrections to apply to each, in order, before judging the trace, and the `same_as` identifiers of the cited work.
Apply them with the gate ([11.4](../spec/11-corrections.md#114-the-gate)) to the package's state at its own revision.
A `problems` case gives the packages' states as they are, and `cited` is null when the trace names no passage in the main example.
Several files also mix more than one kind of case, told apart by their fields.
`ids.jsonl` has minting cases and letter-first cases, `keyed.jsonl` and `signatures.jsonl` have a case for each derivation or record, `spotcheck.jsonl` has sample-size cases and one full sample, and `rights.jsonl` has stage checks (a `stage` field), backend checks (a `backend` field) and one combining case (neither).
The reference checker, `paperspec check` ([tools/](../tools/README.md)), runs all twenty-five files, together with the rest of the repository's checks:
The reference checker, `paperspec check` ([tools/](../tools/README.md)), runs all twenty-six files, together with the rest of the repository's checks:
```sh
paperspec check --quick
@@ -120,6 +123,7 @@ The table below uses a few terms that the chapters define:
| `alignment.jsonl` | Two readings of a document, their pairs and their suspects. | [5.6](../spec/05-hashes.md#56-alignment) |
| `corrections.jsonl` | Each operation and refusal on a small document: the state before, the correction, and the record and state after, or the rule broken; with the reference records for a `resolve`, and the leaf as printed for an `emend`. | [11](../spec/11-corrections.md) |
| `resolve.jsonl` | Anchors made on the example paper's first reading, and how each resolves after its corrections. | [6.5](../spec/06-anchors.md#65-resolution) |
| `traces.jsonl` | Traced citations: a trace on the draft's sentence that cites the main example, with the corrections that make it current, changed, stale, unlinked or misresolved, the passage's current address and the citations inside it (`op` `resolve`); and traces that break `layer.trace.source` or `layer.trace.target` (`op` `problems`). | [18.5](../spec/18-layers.md#185-traced-citations) |
| `rights.jsonl` | Stage checks with policies and expiry, the combining rule, and backend conditions. | [14](../spec/14-rights.md) |
| `grading.jsonl` | Exercises, submissions and the grades they earn. | [19.4](../spec/19-exercises.md#194-grading) |
| `targets.jsonl` | The target set of targeted F3 for the example paper under each digit rule, given the anchored nodes. | [8.10](../spec/08-fidelity.md#810-targeted-f3) |
@@ -138,7 +142,7 @@ A candidate format changes only with a recorded reason and a new or changed vect
A passing run shows one thing: for these inputs, your implementation computes the same values as the reference implementation in `src/paperspec/`.
That code computed the expected outputs, and `pixi run build` regenerates them ([tools/](../tools/README.md)).
The vectors hold 330 cases in all, some of them small: `hashes.jsonl` has two documents, `alignment.jsonl` two pairs of readings, `offsets.jsonl` two cases.
The vectors hold 359 cases in all, some of them small: `hashes.jsonl` has two documents, `alignment.jsonl` two pairs of readings, `offsets.jsonl` two cases.
The vectors do not show the following.