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/); +});