papers/paperspec
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

fixtures/README.md
+1
View File
@@ -48,6 +48,7 @@ Each record is a single file, or a folder where a format needs several files.
| `profile-acme.json`, `profile-smithlab.json` | What those conditions ask about a team: its purpose, its funding and whom it competes with. |
| `roster.json` | The keys that may sign, the role of each key's holder in the team, and what each key may sign. Ana is the owner, so she may revoke anyone's receipt. |
| `layer/` | A layer of annotations on the main example (`layer.json`, `annotations.jsonl`) and the receipt that confirms them (`receipt.json`). Its claim link and its symbol name the claim `amber/k-bond` of paperclaim's example store as paperclaim references it, `claim:272XTX7C`, pinned at `claim:272XTX7C@02f47b`; the symbol names `K_r` by its key, `K_{r}`. |
| `traces/` | A layer of traced citations on the Typst draft, which cites the main example (`layer.json`, `annotations.jsonl`, `receipt.json`): a trace a model proposed from the draft's citation of "a two-step fit" to the abstract of the main example and a person confirmed, with its receipt; a second candidate, the introduction's sentence, that a person rejected; a person's trace of the same sentence to Table 1; and a person's reply that disputes the first ([spec/18 §18.5](../spec/18-layers.md#185-traced-citations)). `vectors/traces.jsonl` resolves them after corrections. |
| `submissions/`, `grades/` | A student's answers to exercises in the layer, and the grader's result for each. |
| `suspect.json` | A doubtful reading raised for review: the converter's reading of an exponent in the main example, before the first correction answered it. |
| `qa-report.json` | Reviewer error bounds for a delivery that covers two of the main example's receipts, signed by the team's owner key. |
fixtures/records/project.json
+1 -1
View File
@@ -1 +1 @@
{"claims":{"paperclaim":"amber"},"datasets":["ds-hale-bond-params","ds-hale-ctct-scan"],"documents":[{"doc":"smithlab/hale2026harmonic-damb","reason":"The bond constants we start from.","status":{"Ben Example":"read","Cara Example":"reading"},"tags":["parameters"]},{"doc":"okafor2025solvent-acth","reason":"Solvent shifts for the validation set.","tags":["spectra"]}],"drafts":["smithlab/writer2027fixed-ynr7.v3"],"format":"scienting-project/1","key":"smithlab-charges","layers":["tag:scient.ing,2026:layer:smithlab/kp4m2x7q"],"members":[{"keys":["ana"],"person":"Ana Example","role":"owner"},{"keys":["ben","ben-spot"],"person":"Ben Example","role":"editor"},{"keys":["cara"],"person":"Cara Example","role":"reader"}],"name":"Charges and bonds","paths":[{"id":"onboarding","steps":[{"note":"Read the introduction.","ref":"smithlab/hale2026harmonic-damb","type":"document"},{"note":"Then the table.","ref":"smithlab/hale2026harmonic-damb#hj4s7pb","type":"node"},{"note":"The bond force constant, amber/k-bond.","ref":"claim:272XTX7C","type":"claim"}],"title":"First week"}],"settings":{"digit_rule":"anchored-sections","drift_threshold":"0.25","log":{"origin":"scient.ing/log/smithlab","threshold":1,"witnesses":["wit"]},"rights_unknown":"refuse","spot_check":{"minimum":10,"rate":"0.05"},"stages":"scienting-stages-default"},"store":"smithlab","views":["ctct-scan"]}
{"claims":{"paperclaim":"amber"},"datasets":["ds-hale-bond-params","ds-hale-ctct-scan"],"documents":[{"doc":"smithlab/hale2026harmonic-damb","reason":"The bond constants we start from.","status":{"Ben Example":"read","Cara Example":"reading"},"tags":["parameters"]},{"doc":"okafor2025solvent-acth","reason":"Solvent shifts for the validation set.","tags":["spectra"]}],"drafts":["smithlab/writer2027fixed-ynr7.v3"],"format":"scienting-project/1","key":"smithlab-charges","layers":["tag:scient.ing,2026:layer:smithlab/kp4m2x7q","tag:scient.ing,2026:layer:smithlab/tr6c3q8m"],"members":[{"keys":["ana"],"person":"Ana Example","role":"owner"},{"keys":["ben","ben-spot"],"person":"Ben Example","role":"editor"},{"keys":["cara"],"person":"Cara Example","role":"reader"}],"name":"Charges and bonds","paths":[{"id":"onboarding","steps":[{"note":"Read the introduction.","ref":"smithlab/hale2026harmonic-damb","type":"document"},{"note":"Then the table.","ref":"smithlab/hale2026harmonic-damb#hj4s7pb","type":"node"},{"note":"The bond force constant, amber/k-bond.","ref":"claim:272XTX7C","type":"claim"}],"title":"First week"}],"settings":{"digit_rule":"anchored-sections","drift_threshold":"0.25","log":{"origin":"scient.ing/log/smithlab","threshold":1,"witnesses":["wit"]},"rights_unknown":"refuse","spot_check":{"minimum":10,"rate":"0.05"},"stages":"scienting-stages-default"},"store":"smithlab","views":["ctct-scan"]}
fixtures/records/traces/annotations.jsonl
+4
View File
@@ -0,0 +1,4 @@
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"kind":"trace","note":"The abstract states the two steps: a scan first, then vibrational frequencies.","proposer":{"model":{"name":"example-model","parameters":"998b5161e39e01c8bc43ef81ec89141e15b7ea53b2e936707920a6097dbcb2c5","processor":"local","prompt":"9cc338fba7c62db7266f530cb555a5ee36910d41a0120a3fe7fd7de1944d0931","provider":"Example Models (illustrative)","version":"2026-09","weights":"504b2d340045b92c22682b60020c21103aae7ff41172bb632fbe305eb4af9b5e"},"rank":1,"run":"illustrative-run-2","score":"0.8731"},"reference":"ebcq5cy","selector":[{"anchor":{"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"sentence","node":"mhp0at8","node_hash":"ee42c4780724a411697e3a95daf182d37c792d4689a7172f32929785d5fd968e","own_hash":"24cc437784bf358d639755dbf59984ad2c0c7a0e7f9448b23e965039b67f759b","quote":{"exact":"in two steps","prefix":"bond constants for twelve bonds ","suffix":", first to a scan and then to vi"},"rev":12,"span":[48,60],"store":"smithlab"},"type":"AnchorSelector"},{"exact":"in two steps","prefix":"bond constants for twelve bonds ","suffix":", first to a scan and then to vi","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource","verdict":"supports"},"created":"2026-10-12T09:00:00Z","creator":{"id":"tag:scient.ing,2026:software:example-model","name":"A model (illustrative)","type":"Software"},"id":"tag:scient.ing,2026:annotation:smithlab/jh0e4st2c0kpt","layer":"tag:scient.ing,2026:layer:smithlab/tr6c3q8m","motivation":"linking","receipt":"qvckzaatz5d1v","status":"confirmed","target":{"selector":[{"anchor":{"doc":"writer2027fixed-ynr7.v3","format":"scienting-anchor/1","kind":"sentence","node":"qgh1k31","node_hash":"93a39490870e694299e88e6f475d42c38078d1442959e555bdbdf58488dcf187","own_hash":"e004436e7b28ff3dc41e0056f231ba707d9be985694e68acb911345a547842ed","quote":{"exact":"two-step fit","prefix":"Its constants come from a ","suffix":" (Hale and Osei, Table 1).1"},"rev":0,"span":[26,38],"store":"smithlab"},"type":"AnchorSelector"},{"exact":"two-step fit","prefix":"Its constants come from a ","suffix":" (Hale and Osei, Table 1).1","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/writer2027fixed-ynr7.v3","type":"SpecificResource"},"type":"Annotation"}
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"kind":"trace","note":"Says harmonic terms are common, not how the constants were fitted.","proposer":{"model":{"name":"example-model","parameters":"998b5161e39e01c8bc43ef81ec89141e15b7ea53b2e936707920a6097dbcb2c5","processor":"local","prompt":"9cc338fba7c62db7266f530cb555a5ee36910d41a0120a3fe7fd7de1944d0931","provider":"Example Models (illustrative)","version":"2026-09","weights":"504b2d340045b92c22682b60020c21103aae7ff41172bb632fbe305eb4af9b5e"},"rank":2,"run":"illustrative-run-2","score":"0.6410"},"reference":"ebcq5cy","selector":[{"anchor":{"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"sentence","node":"kea5026","node_hash":"b836d5872ca37471fa996be04c538254a8b1e37ca12e8f1b4a40837b503afa33","own_hash":"d673d236c03d9583ecf6e01fa819765ec324dc684bd9bbc6967fa50f216e34d2","quote":{"exact":"classical force fields.1","prefix":"ption of covalent stretching in "},"rev":12,"span":[81,105],"store":"smithlab"},"type":"AnchorSelector"},{"exact":"classical force fields.1","prefix":"ption of covalent stretching in ","suffix":"","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource"},"created":"2026-10-12T09:00:00Z","creator":{"id":"tag:scient.ing,2026:software:example-model","name":"A model (illustrative)","type":"Software"},"id":"tag:scient.ing,2026:annotation:smithlab/arm3zmj6be9fz","layer":"tag:scient.ing,2026:layer:smithlab/tr6c3q8m","motivation":"linking","status":"rejected","target":{"selector":[{"anchor":{"doc":"writer2027fixed-ynr7.v3","format":"scienting-anchor/1","kind":"sentence","node":"qgh1k31","node_hash":"93a39490870e694299e88e6f475d42c38078d1442959e555bdbdf58488dcf187","own_hash":"e004436e7b28ff3dc41e0056f231ba707d9be985694e68acb911345a547842ed","quote":{"exact":"two-step fit","prefix":"Its constants come from a ","suffix":" (Hale and Osei, Table 1).1"},"rev":0,"span":[26,38],"store":"smithlab"},"type":"AnchorSelector"},{"exact":"two-step fit","prefix":"Its constants come from a ","suffix":" (Hale and Osei, Table 1).1","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/writer2027fixed-ynr7.v3","type":"SpecificResource"},"type":"Annotation"}
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"kind":"trace","note":"Table 1 lists the fitted constants of both parameter sets.","reference":"ebcq5cy","selector":[{"anchor":{"doc":"hale2026harmonic-damb","format":"scienting-anchor/1","kind":"table","node":"hj4s7pb","node_hash":"6c6fba200faf41cd06fa8b64e06e2aa29ff8848568b859ae42d1902596348643","own_hash":"66310a9ab1c92568f4c6cae012e35d4245d4ca4b89d2542b7c2113a31ad379ed","rev":12,"store":"smithlab"},"type":"AnchorSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/hale2026harmonic-damb","type":"SpecificResource","verdict":"supports"},"created":"2026-10-12T09:10:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"id":"tag:scient.ing,2026:annotation:smithlab/fhnynfb8jx0wc","layer":"tag:scient.ing,2026:layer:smithlab/tr6c3q8m","motivation":"linking","receipt":"qvckzaatz5d1v","status":"confirmed","target":{"selector":[{"anchor":{"doc":"writer2027fixed-ynr7.v3","format":"scienting-anchor/1","kind":"sentence","node":"qgh1k31","node_hash":"93a39490870e694299e88e6f475d42c38078d1442959e555bdbdf58488dcf187","own_hash":"e004436e7b28ff3dc41e0056f231ba707d9be985694e68acb911345a547842ed","quote":{"exact":"Its constants come from a two-step fit (Hale and Osei, Table 1).1"},"rev":0,"store":"smithlab"},"type":"AnchorSelector"},{"exact":"Its constants come from a two-step fit (Hale and Osei, Table 1).1","prefix":"","suffix":"","type":"TextQuoteSelector"}],"source":"tag:scient.ing,2026:doc:smithlab/writer2027fixed-ynr7.v3","type":"SpecificResource"},"type":"Annotation"}
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"body":{"category":"critique","kind":"comment","type":"TextualBody","value":"The abstract names the two steps but not the constants; the table is the better passage."},"created":"2026-10-12T10:00:00Z","creator":{"id":"tag:scient.ing,2026:key:ben","name":"Ben Example","type":"Person"},"id":"tag:scient.ing,2026:annotation:smithlab/g4fm8f93czwkk","layer":"tag:scient.ing,2026:layer:smithlab/tr6c3q8m","motivation":"assessing","status":"proposed","target":{"source":"tag:scient.ing,2026:annotation:smithlab/jh0e4st2c0kpt","type":"SpecificResource"},"type":"Annotation"}
fixtures/records/traces/layer.json
+1
View File
@@ -0,0 +1 @@
{"@context":["http://www.w3.org/ns/anno.jsonld","https://paperspec.scient.ing/context/scienting-1.jsonld"],"audience":"expert","created":"2026-10-12T09:00:00Z","creator":{"id":"tag:scient.ing,2026:key:ana","name":"Ana Example","type":"Person"},"docs":["smithlab/writer2027fixed-ynr7.v3"],"format":"scienting-layer/1","id":"tag:scient.ing,2026:layer:smithlab/tr6c3q8m","label":"Where the draft's citations lead","license":{"spdx":"CC-BY-4.0"},"project":"smithlab-charges","purpose":"Traces from the draft's citations of Hale and Osei to the passages they rest on.","total":4,"type":"AnnotationCollection","visibility":"team"}
fixtures/records/traces/receipt.json
+1
View File
@@ -0,0 +1 @@
{"at":"2026-10-12T09:30:00Z","by":"ana","doc":"writer2027fixed-ynr7.v3","evidence":[],"format":"scienting-receipt/1","id":"qvckzaatz5d1v","level":"F3","nodes":[],"records":[["annotation","fhnynfb8jx0wc","a1115243473b190f7ed8877780f29c935f29801d6c9fe0b423601247ebf078f8"],["annotation","jh0e4st2c0kpt","b774528344f096051420b6df73c089fdce4d0e1093e4ea3d845fff023c17dee7"]],"rev":0,"root":"d1b96ae5b9887ae843cd209d7da5ea9bb454f1bab77b93d05d38fbfc2b21e826","scope":"targeted:traces","signature":{"key":"ana","scheme":"ed25519","value":"d2xj2bQY3AoDEVV7yzs31mQpMoGre+V919NUM/Ba/qj+ySb1QKs7D9ZidM6+ksl1xlNsCLNU2rdeclUduoZZBA=="}}