From 47c1697d94f54a62de8d2db6a57f53dced3e7a5c Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 23:28:10 +0000 Subject: [PATCH] registry: propose ADR 0005, a canonical JCS JSON route for proof receipts Owner ruling 2026-11-16: rather than trope-checker emitting a deed, the reader in Mathesis should also accept a receipt that is canonical JCS I-JSON. This adds the proposal and an unwired prototype. docs/decisions/0005-jcs-json-receipt.adoc (status: proposed) maps each JSON field one to one onto the PROOF-POLICY 8.5.1 deed fields, with no pwg and no foundation_diverse. It makes JCS canonicality a hard requirement, and lists what the reader refuses. scripts/registry/json-receipt.mjs checks the JSON layer, writes the receipt as 8.5.1 deed text and lets the pinned canon reader derive each grade. The reader's own grade check serves as the oracle, so the prototype has no grading rule. claims-registry.mjs, READER and claims.jsonl are unchanged. tests/registry/json-receipt.test.mjs: three real deeds round-trip to an identical record. 36 refusal cases are each refused, and each is accepted by a permissive stub (JSON_RECEIPT_STUB=1 makes all 36 fail). trope-checker's verification/pwg.json is fetched at 0dceab6, checked against its sha256, and refused. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDg2kzHbnbH2pmDf2Ar --- docs/decisions/0005-jcs-json-receipt.adoc | 199 ++++++++++++++++ scripts/registry/json-receipt.mjs | 267 ++++++++++++++++++++++ tests/registry/json-receipt.test.mjs | 168 ++++++++++++++ 3 files changed, 634 insertions(+) create mode 100644 docs/decisions/0005-jcs-json-receipt.adoc create mode 100644 scripts/registry/json-receipt.mjs create mode 100644 tests/registry/json-receipt.test.mjs diff --git a/docs/decisions/0005-jcs-json-receipt.adoc b/docs/decisions/0005-jcs-json-receipt.adoc new file mode 100644 index 0000000..0684038 --- /dev/null +++ b/docs/decisions/0005-jcs-json-receipt.adoc @@ -0,0 +1,199 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell += Architecture Decision Record: 0005-jcs-json-receipt + +== 5. The claims registry also reads a proof receipt written as canonical JCS I-JSON + +Date: 2026-11-16 + +=== Status + +*Proposed. It is not accepted until the owner accepts it.* It follows the owner's ruling of +2026-11-16: trope-checker does not emit a praxis deed. Instead, the reader in +Mathesis also accepts a receipt that is canonical JCS I-JSON. This record says +how. The prototype (`scripts/registry/json-receipt.mjs`, tests in +`tests/registry/json-receipt.test.mjs`) is *not wired* into +`claims-registry.mjs`. The registry reads praxis deeds only until this record +is accepted, and no trope-checker row is added to `claims.jsonl` here. + +=== Context + +ADR 0004 pins each record's receipt as `{path, sha256}` and derives the grade +with the canon reader of PROOF-POLICY §8.5.1. That reader is `readProofReceipt` in +`metadatastician/standards` `1-formats/deed/tools/deed_lint.js`, pinned by commit +and digest in `READER`. The reader reads praxis deeds: S-expressions, with each +line at most 998 octets. + +`hyperpolymath/trope-checker` publishes its evidence as `verification/pwg.json`. +That file is I-JSON (RFC 7493) in canonical JCS form (RFC 8785), and +`scripts/pwg-check.sh` gates it. The owner rules out a deed there. Given to the +pinned reader as it stands, the file fails at once: "line 1: line is 26347 octets". + +Two constraints bind any answer: + +* PROOF-POLICY §8.4 and §8.5, and ADR 0004: grades are derived, never asserted. + Mathesis derives them from receipts and has no grading rule of its own + (WO 2.4). +* AUTHORITY: receipts stay home. The registry fetches them at a pinned commit + and does not copy them. + +=== Decision (proposed) + +==== The JSON receipt + +A JSON receipt is the §8.5.1 proof receipt, written field for field in +I-JSON, with *no grade*. The field names are those of the record that the +canon reader returns (`snake_case`). Nothing else is allowed. + +[cols="2,2,3",options="header"] +|=== +|JSON field |§8.5.1 deed field |Note + +|`profile` |`:profile proof-receipt` |Must be `"proof-receipt"`. +|`schema_version` |`:schema-version` |`"1.0.0"`. +|`repository` |`:repository` |`OWNER/REPO`. +|`source_commit` |`:source-commit` |40 lowercase hex. +|`trusted_base[]` `{prover, module, name, binding}` |`(trusted-base (primitive …))` |Required array. `[]` means the deed omits the clause. +|`echoes[]` `{source, image, witness, tree_sha256?, inputs?[] {prover, sha256}}` |`(echo …)`, `(inputs …)` |Required array, possibly empty. Commits are 40 hex. +|`claims[]` `{id, legs[]}` |`(claim :id …)` |*No* `pwg` and *no* `foundation_diverse`. +|`legs[]` `{prover, route, token?, state?, reason?, receipts[]}` |`(leg …)` |`receipts` is required, and empty for a waived or unavailable leg. +|`receipts[]` `{run, commit, checker, invocation, inputs_sha256?, state, reason?, inputs_manifest?[], axioms?[], result}` |`(receipt …)` |`commit` is 40 hex. +|`inputs_manifest[]` `{path, sha256}` |`(inputs-manifest (file …))` | +|`axioms[]` `{name, disposition}` |`(axioms (axiom …))` |An absent field and `[]` mean different things, as in the deed. `[]` means the checker reported no axiom. +|`result` |none |The only field with no deed counterpart: `pass` or `fail`. `current` requires `pass`, and `fail` requires `regressed`. In the deed, `:state` carries this. +|=== + +`:canonical-name` and `:beholding-chora` belong to the deed envelope. The +reader's record carries neither, so the JSON form leaves them out. + +==== What the reader refuses + +The JSON layer refuses a file: + +. that is not strict UTF-8, or that starts with a byte order mark; +. whose bytes differ from the JCS form of its value. One final LF is allowed, + as `scripts/check-ijson-jcs.sh` allows. This rule also refuses duplicate + keys, unsorted keys, insignificant whitespace and escapes that JCS does not + use. *Canonicality is a hard requirement*, because the `sha256` pin of + ADR 0004 needs exactly one byte form for each value; +. that holds a lone surrogate or a noncharacter in a key or a value (RFC 7493 §2.1); +. with an *asserted grade*: a key `pwg`, `grade`, `grades`, + `foundation_diverse` (or `foundation-diverse`, `foundationDiverse`) at any + depth. The reason given says that the registry derives the grade; +. with an unknown field at any depth, or a missing required field, or `null` + in place of a value (an optional field is left out instead); +. with a number or a boolean anywhere. No field of the form has either type; +. with a commit that is not 40 lowercase hex: short, abbreviated or uppercase; +. with a string value that is empty, holds a control character (a trailing + newline, a tab or a CR), or is longer than 900 UTF-8 octets; +. with a symbol-valued field (`prover`, `route`, `token`, `state`, + `disposition`, `witness`) that is not letters, digits and hyphens. This + stops deed syntax from being smuggled in; +. with a `result` outside `pass | fail`, a `current` receipt that failed, or a + `fail` that is not `regressed`. + +After the JSON layer, the *pinned canon reader* refuses whatever it refuses in +a deed: values outside its closed vocabularies (no coercion, so `PROVEN` is +refused where `proven` is meant), an Agda leg whose route is not `source`, a +manifest whose digest is not its `inputs_sha256`, duplicate claim ids, bad +echoes, and the rest. + +==== How the grade is derived + +The prototype adds no grading rule. It writes the receipt as §8.5.1 deed text +and hands that text to the pinned reader, which runs after `loadReader()` has +checked its digest. The reader checks a recorded `:pwg` and +`:foundation-diverse` against the values it derives, and refuses a mismatch. +The prototype uses that check as an oracle. For each claim it tries the closed +grade vocabulary, five grades times two flags. Exactly one pair is accepted, +and that pair is the derived grade. If the reader accepts no pair, the +prototype reports the reader's refusal. If it accepts more than one, the +prototype fails loudly. It then reads the whole receipt once more with the +derived pairs, so that the checks across claims also run. The result is the +canon reader's own record. The deed text is never stored. + +Tested equivalence: three receipts round-trip from deed to record to JSON to +record and come back byte-identical under JCS. They are this repository's +`theory_praxis.deed` (five claims, all `PWG-1`) and the standards worked +examples `example_praxis.deed` (`PWG-3`) and `echo_praxis.deed` (`PWG-1` +through an echo). + +==== Wiring, once accepted + +`readReceipt` in `claims-registry.mjs` would dispatch on the pinned path. A +`*_praxis.deed` would go to the reader directly, as now. A `*.json` would go +through `readJsonReceipt` and then the same reader. The rest of the derivation +would not change: the digest pin, `derive()`, and the §8.5.3 git checks. The +git checker in standards reads deeds only. A JSON receipt that reaches `PWG-1` +would therefore be catalogued as `PWG-2ii` ("§8.5.3 git checks cannot run on +a JSON receipt") until standards' checker accepts JSON too. See open question 2. + +=== trope-checker's file today + +`verification/pwg.json` at `0dceab6` (sha256 `3bf20a2e…5bda`) is canonical JCS. +It is an evidence ledger, though, not a receipt in this form. The prototype +refuses it ("unknown field commit"), and the test pins that refusal. To be read +as a receipt, the file would need these changes. They are work for +trope-checker, not for Mathesis: + +* *Envelope.* `repo`, `commit` and the `receipts` map would become + `repository`, `source_commit`, and receipts nested in their legs. `note`, + `policy`, `title`, `notes`, `reference` and `declarations` stay in the + ledger, not in the receipt. +* *Receipts.* `evidence` (the run URL) would become `run`. `checker` and + `checker_version` would become one `checker` string, as the deed writes it + (`"agda 2.7.0.1"`). +* *Inputs (hard gap).* `inputs_digest` is a git tree SHA-1 of a directory + (`git-tree verification/proofs/agda = 8d3370e…`). §8.5.1 wants a SHA-256 of + the sorted file manifest, *and* the manifest itself. Every `current` receipt + lacks both. +* *Axioms.* The axioms are bare names (`propext`, `Quot.sound`, + `Classical.choice`). §8.5.1 needs `{name, disposition}`, and the disposition + is the owner's call under TRUSTED-BASE-REDUCTION-POLICY, not an agent's. The + file itself notes that the Lean legs' Mathlib dependency is one PROOF-POLICY + §2 forbids for a recheck leg. +* *Vocabulary.* Tokens are uppercase (`PROVEN`). `PROVEN-WITH-AXIOMS` is not a + §5 token in the reader's vocabulary. `NOT-INVENTORIED` is not one of the + reader's states. Unavailable legs carry a token and a state, where the reader + wants neither but wants a `reason`. 19 of the 25 Agda legs use route + `re-proved`, where §8.5.1 wants `source`. +* *Scope.* Six claims have no Agda leg (route `unavailable`), and one claim is + `engineering`. The reader requires an Agda leg on every claim, and §8.1 + grades theory only. Those claims would be left out of the receipt. + +=== Alternatives considered + +* *trope-checker emits a deed.* Ruled out by the owner (2026-11-16). +* *Change the canon reader to read JSON.* This is the cleanest long-term + answer, and the source is the right place for it (doctrine 14). The reader + is a standards artefact, though, so the change is a standards proposal: split + `readProofReceipt` into a parse step and a `derive(record)` step that takes + either syntax. Until then the oracle approach reaches the same record without + touching the pin. This is the most elegant arm, and the proposal recommends + it as the destination (open question 1). +* *Read `pwg.json` as it is, with a mapping in Mathesis.* Rejected. It would + make Mathesis the interpreter of another repository's ledger, guessing + dispositions and translating vocabularies. That is assigning, not deriving. +* *Let the JSON carry `pwg` and check it, as the deed does.* Rejected, as the + ruling requires. A JSON grade would be a second thing to keep in step. + Leaving it out makes "derived, not asserted" structural. + +=== Consequences + +* A repository that can emit canonical JSON but not a deed has a route into + the registry, and still cannot assert its own grade. +* Mathesis carries a second syntax for one record. The equivalence tests keep + both syntaxes tied to the same reader. +* The 900-octet value limit comes from the deed's line limit. A longer + invocation needs the standards change of open question 1. + +=== Open questions for the owner + +. Should the destination be a standards change, `derive(record)` in the canon + reader, with this prototype retired once that change lands? +. §8.5.3 git checks for JSON receipts: should standards' `check-proof-receipt.sh` + accept JSON? Until it does, a JSON receipt cannot be catalogued at `PWG-1`. +. `result`: keep it, the one field with no deed counterpart, or drop it and + let `state` carry it, as the deed does? +. The final LF: allow it, as the estate JSON gate does, or require none, as + bare JCS output has? diff --git a/scripts/registry/json-receipt.mjs b/scripts/registry/json-receipt.mjs new file mode 100644 index 0000000..de83c6b --- /dev/null +++ b/scripts/registry/json-receipt.mjs @@ -0,0 +1,267 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell +// +// PROTOTYPE for the proposed ADR 0005 (docs/decisions/0005-jcs-json-receipt.adoc, +// status: proposed). Not wired into claims-registry.mjs: the registry still +// reads praxis deeds only, until the owner accepts the ADR. +// +// A JSON proof receipt is the PROOF-POLICY §8.5.1 receipt with the same fields +// in I-JSON (RFC 7493), serialised by JCS (RFC 8785), and with no grade. This +// file has no grading rule. It checks the JSON layer, projects the receipt to +// §8.5.1 deed text, and lets the PINNED canon reader (readProofReceipt, passed +// in by the caller after loadReader() has checked its digest) derive each grade. +// The reader's grade check is used as an oracle. For each claim, exactly one +// (:pwg, :foundation-diverse) pair in the closed vocabulary is accepted, and +// that pair is the derived grade. No grade is ever taken from the JSON. +// +// bun scripts/registry/json-receipt.mjs read FILE (needs MATHESIS_STANDARDS) +import {jcs} from './theory-ledger.mjs'; + +export const PROFILE = 'proof-receipt'; +export const SCHEMA_VERSION = '1.0.0'; + +// The grades and flags of PROOF-POLICY §8.2 and §8.3, in the order they are +// tried. They are tried, never read: a receipt that names one is refused. +const GRADES = ['ungraded', 'PWG-3', 'PWG-2i', 'PWG-2ii', 'PWG-1']; +const DIVERSE = ['#f', '#t']; +// Fields that would assert a grade. Refused anywhere in the receipt, with a +// reason that says so (§8.4: grades are derived, not asserted; WO 2.4). +const ASSERTED = new Set(['pwg', 'grade', 'grades', 'foundation_diverse', 'foundation-diverse', 'foundationDiverse']); +const RESULTS = new Set(['pass', 'fail']); +// The longest string value. Each value goes on its own line of the projected +// deed, and a deed line is at most 998 octets (deed.abnf v1.3.0). +export const MAX_VALUE_OCTETS = 900; + +export class JsonReceiptError extends Error { + constructor(message) { + super(message); + this.name = 'JsonReceiptError'; + } +} +const fail = m => { throw new JsonReceiptError(m); }; +const need = (ok, m) => { if (!ok) fail(m); }; + +// ── The schema: closed, typed, one form for each value ────────────────────── +// +// A field is [kind, required]. Kinds: 'string' (a deed string), 'symbol' (a +// deed symbol, letters, digits and hyphens), 'commit' (40 lowercase hex), +// 'hex64', 'result' (pass or fail), or a nested schema for an array of objects. +const S = (kind, required = true) => ({kind, required}); +const A = (schema, required = true) => ({kind: 'array', schema, required}); +const FILE = {path: S('string'), sha256: S('hex64')}; +const AXIOM = {name: S('string'), disposition: S('symbol')}; +const RECEIPT = { + run: S('string'), commit: S('commit'), checker: S('string'), invocation: S('string'), + inputs_sha256: S('hex64', false), state: S('symbol'), reason: S('string', false), result: S('result'), + inputs_manifest: A(FILE, false), axioms: A(AXIOM, false), +}; +const LEG = {prover: S('symbol'), route: S('symbol'), token: S('symbol', false), state: S('symbol', false), + reason: S('string', false), receipts: A(RECEIPT)}; +const CLAIM = {id: S('string'), legs: A(LEG)}; +const PRIMITIVE = {prover: S('symbol'), module: S('string'), name: S('string'), binding: S('string')}; +const INPUTS = {prover: S('symbol'), sha256: S('hex64')}; +const ECHO = {source: S('commit'), image: S('commit'), witness: S('symbol'), tree_sha256: S('hex64', false), + inputs: A(INPUTS, false)}; +const TOP = {profile: S('string'), schema_version: S('string'), repository: S('string'), source_commit: S('commit'), + trusted_base: A(PRIMITIVE), echoes: A(ECHO), claims: A(CLAIM)}; + +// RFC 7493 §2.1: no lone surrogate and no noncharacter, in a key or a value. +function checkCodePoints(s, where) { + for (let i = 0; i < s.length; i++) { + const c = s.charCodeAt(i); + if (c >= 0xd800 && c <= 0xdbff) { + const d = s.charCodeAt(i + 1); + need(d >= 0xdc00 && d <= 0xdfff, `${where}: a lone UTF-16 surrogate (RFC 7493 §2.1)`); + const cp = 0x10000 + ((c - 0xd800) << 10) + (d - 0xdc00); + need((cp & 0xfffe) !== 0xfffe, `${where}: a Unicode noncharacter (RFC 7493 §2.1)`); + i++; + } else { + need(!(c >= 0xdc00 && c <= 0xdfff), `${where}: a lone UTF-16 surrogate (RFC 7493 §2.1)`); + need(!(c >= 0xfdd0 && c <= 0xfdef) && (c & 0xfffe) !== 0xfffe, `${where}: a Unicode noncharacter (RFC 7493 §2.1)`); + } + } +} + +// A value as one deed string can hold it: not empty, no control character +// (so no trailing newline, tab or carriage return), and short enough for one line. +function checkString(v, where) { + need(typeof v === 'string', `${where} must be a string`); + need(v.trim() !== '', `${where} is empty`); + need(!/[\u0000-\u001f\u007f]/.test(v), `${where} holds a control character (a newline, tab or other); a value is one line`); + need(new TextEncoder().encode(v).length <= MAX_VALUE_OCTETS, `${where} is longer than ${MAX_VALUE_OCTETS} octets`); +} + +function checkValue(kind, v, where) { + if (kind === 'string') return checkString(v, where); + need(typeof v === 'string', `${where} must be a string`); + if (kind === 'symbol') need(/^[A-Za-z][A-Za-z0-9-]*$/.test(v), `${where} must be a symbol (letters, digits, hyphens), got ${JSON.stringify(v)}`); + else if (kind === 'commit') need(/^[0-9a-f]{40}$/.test(v), `${where} must be the full 40-character lowercase commit, got ${JSON.stringify(v)}`); + else if (kind === 'hex64') need(/^[0-9a-f]{64}$/.test(v), `${where} must be 64 lowercase hex digits`); + else if (kind === 'result') need(RESULTS.has(v), `${where} must be pass or fail, got ${JSON.stringify(v)}`); +} + +// Check one object against a closed schema, then recurse into its arrays. +function checkObject(o, schema, where) { + need(o !== null && typeof o === 'object' && !Array.isArray(o), `${where} must be an object`); + for (const k of Object.keys(o)) { + checkCodePoints(k, `${where}: a key`); + need(!ASSERTED.has(k), `${where} asserts a grade (${k}); a JSON receipt carries no grade, the registry derives it (PROOF-POLICY §8.4, WO 2.4)`); + need(k in schema, `${where}: unknown field ${k}`); + } + for (const [k, f] of Object.entries(schema)) { + const at = `${where}.${k}`; + if (!(k in o)) { need(!f.required, `${where} is missing ${k}`); continue; } + need(o[k] !== null, `${at} is null; leave an optional field out instead`); + if (f.kind === 'array') { + need(Array.isArray(o[k]), `${at} must be an array`); + o[k].forEach((e, i) => checkObject(e, f.schema, `${at}[${i}]`)); + } else { + if (typeof o[k] === 'string') checkCodePoints(o[k], at); + checkValue(f.kind, o[k], at); + } + } +} + +// ── The JSON layer ─────────────────────────────────────────────────────────── + +// Parse a JSON receipt from its bytes (a Uint8Array) or text, and refuse it +// unless it is strict UTF-8 with no byte order mark, I-JSON, byte-identical to +// its JCS form (one final LF allowed, as scripts/check-ijson-jcs.sh allows), +// and in the schema above. Returns the parsed object. +export function parseJsonReceipt(input) { + let text = input; + if (typeof input !== 'string') { + try { text = new TextDecoder('utf-8', {fatal: true, ignoreBOM: true}).decode(input); } + catch { fail('not UTF-8'); } + } + need(!text.startsWith(''), 'a byte order mark; I-JSON text has none'); + let value; + try { value = JSON.parse(text); } catch (e) { fail(`not JSON: ${e.message}`); } + // Every value in the schema is a string, an array or an object, so a number, + // a boolean or a null anywhere is refused below. Canonical form next: this + // also refuses a duplicate key (JSON.parse keeps the last one, so the JCS + // form is shorter), insignificant whitespace, unsorted keys and escapes JCS + // does not use. + const canonical = jcs(value); + need(text === canonical || text === canonical + '\n', + 'not canonical: the bytes differ from the JCS (RFC 8785) form of the value; the sha256 pin needs one form'); + checkObject(value, TOP, 'the receipt'); + need(value.profile === PROFILE, `profile must be ${PROFILE}`); + need(value.schema_version === SCHEMA_VERSION, `schema_version must be ${SCHEMA_VERSION}`); + need(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value.repository), 'repository must be OWNER/REPO'); + for (const c of value.claims) for (const l of c.legs) for (const r of l.receipts) { + const where = `claim ${JSON.stringify(c.id)}, ${l.prover} leg, receipt ${r.run}`; + // The deed has no result field: its :state carries it. A current receipt + // records a run that passed, and a failed run is kept only as regressed. + if (r.state === 'current') need(r.result === 'pass', `${where}: a current receipt has result pass`); + if (r.result === 'fail') need(r.state === 'regressed', `${where}: a receipt with result fail has state regressed`); + } + return value; +} + +// ── The projection to §8.5.1 deed text ─────────────────────────────────────── + +const str = v => `"${v.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`; + +function receiptText(r, pad) { + const out = [`${pad}(receipt :run ${str(r.run)}`, `${pad} :commit ${str(r.commit)}`, + `${pad} :checker ${str(r.checker)}`, `${pad} :invocation ${str(r.invocation)}`]; + if (r.inputs_sha256 !== undefined) out.push(`${pad} :inputs-sha256 ${str(r.inputs_sha256)}`); + out.push(`${pad} :state ${r.state}`); + if (r.reason !== undefined) out.push(`${pad} :reason ${str(r.reason)}`); + if (r.axioms !== undefined) { + out.push(`${pad} (axioms`, ...r.axioms.map(a => `${pad} (axiom :name ${str(a.name)} :disposition ${a.disposition})`), `${pad} )`); + } + if (r.inputs_manifest !== undefined) { + out.push(`${pad} (inputs-manifest`, ...r.inputs_manifest.map(f => `${pad} (file :path ${str(f.path)} :sha256 ${str(f.sha256)})`), `${pad} )`); + } + out.push(`${pad})`); + return out; +} + +function claimText(c, pwg, diverse) { + const out = [` (claim :id ${str(c.id)} :pwg ${pwg} :foundation-diverse ${diverse}`]; + for (const l of c.legs) { + let head = ` (leg :prover ${l.prover} :route ${l.route}`; + if (l.token !== undefined) head += ` :token ${l.token}`; + if (l.state !== undefined) head += ` :state ${l.state}`; + out.push(head); + if (l.reason !== undefined) out.push(` :reason ${str(l.reason)}`); + for (const r of l.receipts) out.push(...receiptText(r, ' ')); + out.push(' )'); + } + out.push(' )'); + return out; +} + +// The §8.5.1 deed text of a checked receipt, with the given grade for each +// claim (a Map id -> [pwg, diverse]). Only this file writes it, and only the +// canon reader reads it; it is never stored. +export function toDeed(r, grades, claims = r.claims) { + const out = [';; SPDX-License-Identifier: CC-BY-SA-4.0', '(praxis-deed', ' :schema-version "1.0.0"', + ' :canonical-name "json-proof-receipt"', ' :profile proof-receipt', + ` :repository ${str(r.repository)}`, ` :source-commit ${str(r.source_commit)}`]; + if (r.trusted_base.length) { + out.push(' (trusted-base', ...r.trusted_base.map(p => + ` (primitive :prover ${p.prover} :module ${str(p.module)} :name ${str(p.name)} :binding ${str(p.binding)})`), ' )'); + } + for (const c of claims) out.push(...claimText(c, ...grades.get(c.id))); + for (const e of r.echoes) { + let head = ` (echo :source ${str(e.source)} :image ${str(e.image)} :witness ${e.witness}`; + if (e.tree_sha256 !== undefined) head += ` :tree-sha256 ${str(e.tree_sha256)}`; + out.push(head, ...(e.inputs ?? []).map(i => ` (inputs :prover ${i.prover} :sha256 ${str(i.sha256)})`), ' )'); + } + out.push(')', ''); + return out.join('\n'); +} + +// ── Reading through the pinned canon reader ────────────────────────────────── + +const refused = e => ['LintError', 'ProofReceiptError'].includes(e?.name); + +// Read a JSON receipt into the canon reader's record. Each claim is tried +// alone, with each grade pair, and exactly one pair must be accepted. Then +// the whole receipt is read once with the derived pairs, so that checks +// across claims (duplicate ids, echoes) run too. Throws JsonReceiptError for +// the JSON layer, and the reader's error when the reader refuses. +export function readJsonReceipt(input, readProofReceipt) { + const r = parseJsonReceipt(input); + need(r.claims.length > 0, 'a proof receipt records at least one claim'); + const grades = new Map(); + for (const c of r.claims) { + const accepted = []; + let first = null; + for (const pwg of GRADES) for (const diverse of DIVERSE) { + try { + readProofReceipt(toDeed(r, new Map([[c.id, [pwg, diverse]]]), [c]), 'json_praxis.deed'); + accepted.push([pwg, diverse]); + } catch (e) { + if (!refused(e)) throw e; + first ??= e; + } + } + if (accepted.length === 0) throw first; + // The reader derives one grade, so two accepted pairs mean the oracle is broken. + need(accepted.length === 1, `claim ${JSON.stringify(c.id)}: the reader accepted ${accepted.length} grade pairs; expected exactly one`); + grades.set(c.id, accepted[0]); + } + return readProofReceipt(toDeed(r, grades), 'json_praxis.deed'); +} + +// ── Entry point ────────────────────────────────────────────────────────────── + +async function main() { + const [cmd, file] = process.argv.slice(2); + if (cmd !== 'read' || !file) { + console.error('usage: json-receipt.mjs read FILE'); + process.exit(2); + } + const {loadReader} = await import('./claims-registry.mjs'); + const {readFile} = await import('node:fs/promises'); + const record = readJsonReceipt(new Uint8Array(await readFile(file)), await loadReader()); + console.log(jcs(record)); +} + +if (process.argv[1] && import.meta.path === (await import('node:path')).resolve(process.argv[1])) { + main().catch(e => { console.error(`REFUSED: ${e.message ?? e}`); process.exit(1); }); +} diff --git a/tests/registry/json-receipt.test.mjs b/tests/registry/json-receipt.test.mjs new file mode 100644 index 0000000..d22c1a8 --- /dev/null +++ b/tests/registry/json-receipt.test.mjs @@ -0,0 +1,168 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell +// +// Tests of the PROTOTYPE JSON receipt reader (proposed ADR 0005). Like the +// registry tests, they need MATHESIS_STANDARDS: a checkout of +// metadatastician/standards at READER.commit. The grades come from the pinned +// canon reader, never from this file. +// +// Falsification: JSON_RECEIPT_STUB=1 swaps the reader for a permissive stub +// that only parses JSON. Run that way, every refusal test must fail, which +// shows that each refusal comes from a rule of the reader and not from a +// broken fixture. The standing control "the permissive stub accepts every +// refusal case" checks the same thing on every run. +import {test, expect, beforeAll} from 'bun:test'; +import {readFileSync} from 'node:fs'; +import {createHash} from 'node:crypto'; +import path from 'node:path'; +import {loadReader, READER} from '../../scripts/registry/claims-registry.mjs'; +import {readJsonReceipt as realRead, JsonReceiptError, MAX_VALUE_OCTETS} from '../../scripts/registry/json-receipt.mjs'; +import {jcs} from '../../scripts/registry/theory-ledger.mjs'; + +const stub = text => JSON.parse(typeof text === 'string' ? text : new TextDecoder().decode(text)); +const STUBBED = process.env.JSON_RECEIPT_STUB === '1'; +let readProofReceipt; +const readJson = text => (STUBBED ? stub(text) : realRead(text, readProofReceipt)); +beforeAll(async () => { readProofReceipt = await loadReader(); }); + +const standards = rel => readFileSync(path.join(process.env.MATHESIS_STANDARDS, rel), 'utf8'); +const ownReceipt = readFileSync(new URL('../../verification/receipts/theory_praxis.deed', import.meta.url), 'utf8'); + +// The JSON form of a record the canon reader returned: the inverse of the +// projection, used to build fixtures from real deeds. `result` has no deed +// field: a regressed receipt failed, and every other receipt passed. +const drop = o => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== null && v !== undefined)); +function fromRecord(rec) { + return { + profile: 'proof-receipt', schema_version: '1.0.0', repository: rec.repository, source_commit: rec.source_commit, + trusted_base: rec.trusted_base, + echoes: rec.echoes.map(e => drop({source: e.source, image: e.image, witness: e.witness, tree_sha256: e.tree_sha256, + inputs: e.witness === 'inputs-sha256' ? Object.entries(e.inputs).map(([prover, sha256]) => ({prover, sha256})) : null})), + claims: rec.claims.map(c => ({id: c.id, legs: c.legs.map(l => drop({prover: l.prover, route: l.route, token: l.token, + state: l.state, reason: l.reason, receipts: l.receipts.map(r => drop({run: r.run, commit: r.commit, checker: r.checker, + invocation: r.invocation, inputs_sha256: r['inputs-sha256'], state: r.state, reason: r.reason, + result: r.state === 'regressed' ? 'fail' : 'pass', inputs_manifest: r.inputs_manifest, axioms: r.axioms}))}))})), + }; +} +const canon = v => jcs(v) + '\n'; +const good = () => fromRecord(readProofReceipt(ownReceipt, 'theory_praxis.deed')); +// The first receipt of the first leg of the first claim (THY-1, Agda, current). +const firstReceipt = v => v.claims[0].legs[0].receipts[0]; +const edit = f => { const v = good(); f(v); return canon(v); }; + +// ── Equivalence: the JSON route gives the canon reader's own record ───────── + +test('a JSON receipt reads to the same record as its deed, for every worked receipt', () => { + for (const [name, text] of [['theory_praxis.deed', ownReceipt], + ['example_praxis.deed', standards('1-formats/deed/tools/fixtures/proof-receipt/example_praxis.deed')], + ['echo_praxis.deed', standards('1-formats/deed/tools/fixtures/proof-receipt/echo_praxis.deed')]]) { + const record = readProofReceipt(text, name); + expect(jcs(readJson(canon(fromRecord(record))))).toBe(jcs(record)); + } +}); + +test('the grade is derived from the legs: a lean leg that is not RECONCILED lowers THY-1 to PWG-2i (one recheck leg)', () => { + const v = good(); + v.claims[0].legs.find(l => l.prover === 'lean').state = 'BRIDGE-PENDING'; + const rec = readJson(canon(v)); + expect(rec.claims[0].pwg).toBe('PWG-2i'); + expect(rec.claims.slice(1).every(c => c.pwg === 'PWG-1')).toBe(true); +}); + +test('bytes, with or without one final LF, are accepted; the reader pin is the one in use', () => { + const v = good(); + expect(readJson(new TextEncoder().encode(jcs(v))).claims).toHaveLength(5); + expect(READER.commit).toMatch(/^[0-9a-f]{40}$/); +}); + +// ── Refusals ───────────────────────────────────────────────────────────────── +// +// Each case is valid JSON (the permissive stub parses it) with one defect. + +const CASES = [ + // Not canonical: the sha256 pin needs one byte form. + ['indented', () => JSON.stringify(good(), null, 2) + '\n', /not canonical/], + // JSON.stringify keeps insertion order (profile, schema_version, …), which is not JCS order. + ['keys out of order', () => JSON.stringify(good()) + '\n', /not canonical/], + ['duplicate key', () => canon(good()).replace('{"claims":', '{"claims":[],"claims":'), /not canonical/], + ['two final newlines', () => canon(good()) + '\n', /not canonical/], + ['escaped ASCII', () => canon(good()).replace('"proof-receipt"', '"proof\\u002dreceipt"'), /not canonical/], + ['byte order mark', () => '' + canon(good()), /byte order mark/], + // Unknown fields, top level and nested. + ['unknown top field', () => edit(v => { v.note = 'x'; }), /unknown field note/], + ['unknown receipt field', () => edit(v => { firstReceipt(v).checker_version = '2.7.0.1'; }), /unknown field checker_version/], + ['unknown leg field', () => edit(v => { v.claims[0].legs[0].declarations = ['x']; }), /unknown field declarations/], + // Asserted grades, anywhere. + ['claim asserts pwg', () => edit(v => { v.claims[0].pwg = 'PWG-1'; }), /asserts a grade \(pwg\)/], + ['claim asserts foundation_diverse', () => edit(v => { v.claims[0].foundation_diverse = 'false'; }), /asserts a grade \(foundation_diverse\)/], + ['top asserts grades', () => edit(v => { v.grades = []; }), /asserts a grade \(grades\)/], + ['receipt asserts pwg', () => edit(v => { firstReceipt(v).pwg = 'PWG-1'; }), /asserts a grade \(pwg\)/], + // Short commits. + ['short source_commit', () => edit(v => { v.source_commit = v.source_commit.slice(0, 12); }), /source_commit must be the full 40-character/], + ['short receipt commit', () => edit(v => { firstReceipt(v).commit = firstReceipt(v).commit.slice(0, 7); }), /commit must be the full 40-character/], + ['uppercase commit', () => edit(v => { v.source_commit = v.source_commit.toUpperCase(); }), /source_commit must be the full 40-character/], + // Values that end in a newline, or hold any other control character. + ['trailing newline in invocation', () => edit(v => { firstReceipt(v).invocation += '\n'; }), /control character/], + ['trailing newline in claim id', () => edit(v => { v.claims[0].id += '\n'; }), /control character/], + ['tab in checker', () => edit(v => { firstReceipt(v).checker += '\t'; }), /control character/], + ['empty reason', () => edit(v => { v.claims[0].legs[0].receipts[1].reason = ' '; }), /is empty/], + ['over-long value', () => edit(v => { firstReceipt(v).run = 'x'.repeat(MAX_VALUE_OCTETS + 1); }), /longer than/], + // Results outside pass|fail, and results that contradict the state. + ['result passed', () => edit(v => { firstReceipt(v).result = 'passed'; }), /must be pass or fail/], + ['result PASS', () => edit(v => { firstReceipt(v).result = 'PASS'; }), /must be pass or fail/], + ['result missing', () => edit(v => { delete firstReceipt(v).result; }), /missing result/], + ['current receipt that failed', () => edit(v => { firstReceipt(v).result = 'fail'; }), /current receipt has result pass/], + ['superseded receipt that failed', () => edit(v => { v.claims[0].legs[0].receipts[1].result = 'fail'; }), /result fail has state regressed/], + // I-JSON, types and one form for each value. + ['lone surrogate', () => edit(v => { firstReceipt(v).checker = 'agda \ud800'; }), /lone UTF-16 surrogate/], + ['a number', () => edit(v => { v.claims[0].id = 1; }), /must be a string/], + ['a boolean', () => edit(v => { v.trusted_base = true; }), /must be an array/], + ['null optional', () => edit(v => { v.claims[0].legs[0].reason = null; }), /is null/], + ['symbol injection', () => edit(v => { v.claims[0].legs[1].route = 're-proved :token proven'; }), /must be a symbol/], + ['wrong profile', () => edit(v => { v.profile = 'pwg-ledger'; }), /profile must be proof-receipt/], + // Refusals the pinned canon reader makes after the JSON layer: no coercion. + ['uppercase token', () => edit(v => { v.claims[0].legs[0].token = 'PROVEN'; }), /:token PROVEN .* is not one of/], + ['agda leg not source', () => edit(v => { v.claims[0].legs[0].route = 're-proved'; }), /route source belongs to the agda leg/], + ['manifest digest', () => edit(v => { firstReceipt(v).inputs_sha256 = '0'.repeat(64); }), /is not the SHA-256 of its \(inputs-manifest/], + ['duplicate claim id', () => edit(v => { v.claims[1].id = v.claims[0].id; }), /duplicate claim id/], +]; + +for (const [name, make, why] of CASES) { + test(`refuses: ${name}`, () => { + expect(() => readJson(make())).toThrow(why); + }); +} + +test('the permissive stub accepts every refusal case (each case is a well-formed JSON text)', () => { + for (const [name, make] of CASES) { + const text = make().replace(/^/, ''); + expect(() => stub(text), name).not.toThrow(); + } +}); + +test('a JSON-layer refusal is a JsonReceiptError; a reader refusal is the reader\'s', () => { + expect(() => realRead(edit(v => { v.claims[0].pwg = 'PWG-1'; }), readProofReceipt)).toThrow(JsonReceiptError); + try { realRead(edit(v => { v.claims[0].legs[0].token = 'PROVEN'; }), readProofReceipt); } catch (e) { + expect(e.name).toBe('ProofReceiptError'); + } +}); + +// ── trope-checker's published ledger, fetched at a pinned commit ───────────── +// +// verification/pwg.json is canonical JCS, but it is an evidence ledger, not a +// §8.5.1 receipt: the reader must refuse it as it stands. Fetched, never +// vendored (AUTHORITY: receipts stay home); a failed fetch fails the test. +const TROPE = { + url: 'https://raw.githubusercontent.com/hyperpolymath/trope-checker/0dceab68459d46b2cda22137c261023223c30e9a/verification/pwg.json', + sha256: '3bf20a2e79eabde1b9c2d898eb7cc04e1934abeb76cebd0ee45c4f35089b5bda', +}; + +test('trope-checker verification/pwg.json at 0dceab6 is canonical JCS, and is refused as a receipt', async () => { + const res = await fetch(TROPE.url); + expect(res.ok).toBe(true); + const bytes = new Uint8Array(await res.arrayBuffer()); + expect(createHash('sha256').update(bytes).digest('hex')).toBe(TROPE.sha256); + const text = new TextDecoder().decode(bytes); + expect(text).toBe(jcs(JSON.parse(text)) + '\n'); // the canonical layer already holds + expect(() => readJson(bytes)).toThrow(/unknown field commit/); +});