@conarium-ai/core 0.2.39 → 0.2.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,82 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.41 — a limit that was announced in the wrong place
4
+
5
+ Since 0.2.34 `docs/RECEIPT-SPEC.md` had carried a stated limit: the thirteen
6
+ receipt vectors are ASCII-keyed with integer and string values, a naive
7
+ sorted-key serialiser reproduces all thirteen hashes, and so matching them does
8
+ not demonstrate a conforming JCS implementation. That much was true, and stays
9
+ true.
10
+
11
+ The remedy named in the same paragraph was not. It said the disagreement would
12
+ first appear in "a receipt carrying a float, a large integer, or a non-ASCII
13
+ key". No such receipt can exist. The receipt body is a fixed shape whose only
14
+ numbers are `chain.seq`, `masking.pii` and `outcome.rows` — small integers — and
15
+ every key in it is ASCII. The paragraph described a vector nobody could write.
16
+
17
+ Caller-shaped JSON reaches canonicalisation at one point: `hashArgs()`, whose
18
+ argument is typed `any` and whose digest becomes `request.argsHash`. That is
19
+ where a second implementation can disagree with us, and its preimages were
20
+ published nowhere — vector 001 carries `sha256:abab...`, a placeholder standing
21
+ in for a hash of nothing.
22
+
23
+ `test-vectors/jcs/` now publishes eight preimages with frozen hashes: floats at
24
+ the `1e21` exponent boundary and the denormal minimum, integers past 2^53,
25
+ non-ASCII keys, a surrogate-pair sort order, the escape rules, and the
26
+ raw-string branch — where `hashArgs` digests the bytes it was handed rather than
27
+ canonicalising them, which is the case most likely to split two implementations
28
+ that otherwise agree.
29
+
30
+ `test/spec_jcs_class.mjs` measures our own conformance against the reference
31
+ data published with RFC 8785: six input/expected pairs compared over bytes, and
32
+ 3,000 of its published IEEE-754 doubles. All pass. The number evidence is a
33
+ **sample** of 100,000,000 and says so wherever it is cited. The guard also runs
34
+ eight mutants and fails if any of them reproduces the reference bytes, because
35
+ three checks in this repository have now reported success without comparing
36
+ anything, and the fix for that is not a fourth check that could do the same.
37
+
38
+ No behaviour changed. The verifier, the canonical form and all thirteen receipt
39
+ vectors are byte-identical to 0.2.40.
40
+
41
+ ## 0.2.40 — an exit code that answered a question it had not examined
42
+
43
+ `conarium-verify --anchor-check` over a chain where every receipt is unanchored
44
+ exited **0**. Each null anchor was skipped, which is correct — periodic anchoring
45
+ leaves most receipts null and failing on that would make the flag unusable. What
46
+ followed was not: with nothing left to compare, the run reported success. A
47
+ caller who asked whether the anchors held was answered by a code path that never
48
+ reached an anchor.
49
+
50
+ The count was always printed — the summary line said `0/N anchored` — so the
51
+ information was on screen. The exit code was the part that claimed more than had
52
+ been examined, and the exit code is what a machine reads.
53
+
54
+ It is now **15**, which already means "could not be checked" and is evaluated
55
+ ahead of 14 so that "I could not check" is never swallowed by "it does not hold".
56
+ `--require-head-anchor` keeps 14: there the caller asserted an anchor must be
57
+ present, and its absence is a failed assertion rather than an unread one. A chain
58
+ carrying at least one anchor is unaffected.
59
+
60
+ **This is a behaviour change.** A caller who ran `--anchor-check` over
61
+ never-anchored chains and treated 0 as success will now see 15. That is the
62
+ point — but it is a break, and it is why this is a version rather than a patch to
63
+ the last one.
64
+
65
+ The old answer was not an oversight: `test/anchor_verify.mjs` A6.5 asserted it.
66
+ The test had written the defect down, so the behaviour changed and the
67
+ expectation was corrected — the opposite of vector 008, where the implementation
68
+ was right and the expectation was wrong. A6.9 adds the multi-receipt case and a
69
+ control proving that a run which never asked about anchors still exits 0.
70
+
71
+ Found by applying a rule from the SCITT list to our own tool: a checker must
72
+ report that it did not compare, rather than return a verdict it did not earn.
73
+
74
+ Also here: four more Turkish identifiers in `bin/conarium-verify.mjs`
75
+ (`modelBildirilmemis`, `clientBildirilmemis`, `notlar`, `ek`) that 0.2.39's word
76
+ pass did not carry in its list. Translated, and the words added — which is the
77
+ second time that list has grown by being wrong, and is exactly the limit recorded
78
+ against it.
79
+
3
80
  ## 0.2.39 — 2026-08-21 — the package speaks the language its documentation is written in
4
81
 
5
82
  The executable package carried operational text in Turkish. Not in the
@@ -670,11 +670,11 @@ async function main(argv = process.argv.slice(2)) {
670
670
  // NOTE: receipts elements are wrapped as {file, receipt} — reading r.model
671
671
  // directly silently always yields 0 (this happened exactly once; the e2e run
672
672
  // caught it).
673
- const modelBildirilmemis = receipts.filter((r) => r.receipt?.model?.source === 'undeclared').length
674
- const clientBildirilmemis = receipts.filter((r) => r.receipt?.client?.source === 'undeclared').length
675
- const notlar = []
676
- if (modelBildirilmemis) notlar.push(`${modelBildirilmemis} with undeclared model`)
677
- if (clientBildirilmemis) notlar.push(`${clientBildirilmemis} with undeclared client`)
673
+ const undeclaredModelCount = receipts.filter((r) => r.receipt?.model?.source === 'undeclared').length
674
+ const undeclaredClientCount = receipts.filter((r) => r.receipt?.client?.source === 'undeclared').length
675
+ const notes = []
676
+ if (undeclaredModelCount) notes.push(`${undeclaredModelCount} with undeclared model`)
677
+ if (undeclaredClientCount) notes.push(`${undeclaredClientCount} with undeclared client`)
678
678
 
679
679
  if (opts.requireHeadAnchor && !headAnchored) {
680
680
  fail(14, 'head anchor required but head is not anchored', opts.json, {
@@ -684,6 +684,23 @@ async function main(argv = process.argv.slice(2)) {
684
684
  })
685
685
  }
686
686
 
687
+ // --anchor-check on a chain where no receipt carries an anchor used to exit 0:
688
+ // every null was skipped, nothing was compared, and the caller who asked
689
+ // whether the anchors held was told yes by a path that never reached one.
690
+ // That is the same defect as a checker returning a verdict on an input it
691
+ // never examined. The value for it already exists — 15 means "could not be
692
+ // checked", deliberately distinct from 14 "does not hold" — so this is 15.
693
+ // `--require-head-anchor` above stays 14: the caller asserted an anchor must
694
+ // be there, and its absence is a failed assertion rather than an unread one.
695
+ if (opts.anchorCheck && receipts.length > 0 && anchoredCount === 0) {
696
+ fail(
697
+ 15,
698
+ `anchor check requested but no receipt carries an anchor: 0/${receipts.length} anchored, nothing was compared`,
699
+ opts.json,
700
+ { anchored: 0, total: receipts.length, headAnchored: false },
701
+ )
702
+ }
703
+
687
704
  const summary = `${anchoredCount}/${receipts.length} anchored, head anchored: ${headAnchored ? 'yes' : 'no'}`
688
705
  const tailPinned = isTailPinned(opts)
689
706
  if (!tailPinned) console.error(TAIL_UNPINNED_NOTE)
@@ -693,16 +710,16 @@ async function main(argv = process.argv.slice(2)) {
693
710
  ok: true,
694
711
  code: 0,
695
712
  count: receipts.length,
696
- undeclaredModel: modelBildirilmemis,
697
- undeclaredClient: clientBildirilmemis,
713
+ undeclaredModel: undeclaredModelCount,
714
+ undeclaredClient: undeclaredClientCount,
698
715
  anchored: anchoredCount,
699
716
  headAnchored,
700
717
  anchorSummary: opts.anchorCheck ? summary : undefined,
701
718
  tailPinned,
702
719
  }))
703
720
  } else {
704
- const ek = notlar.length ? ` (${notlar.join(', ')})` : ''
705
- console.log(`ok: ${receipts.length} receipt(s) verified${ek}`)
721
+ const suffix = notes.length ? ` (${notes.join(', ')})` : ''
722
+ console.log(`ok: ${receipts.length} receipt(s) verified${suffix}`)
706
723
  if (opts.anchorCheck) console.log(summary)
707
724
  }
708
725
  process.exit(0)
@@ -193,12 +193,22 @@ are unchanged.
193
193
  | 11 | `prevHash` break — deleted or inserted; also `--expect-count` / `--expect-last-hash` mismatch |
194
194
  | 12 | `seq` gap / non-increasing — missing or reordered |
195
195
  | 13 | Signature invalid / pubkey missing (fail-closed) |
196
- | 14 | Claimed anchor invalid under `--anchor-check`, or `--require-head-anchor` when the head is unanchored. `anchor:null` receipts are skipped (periodic anchoring). |
197
- | 15 | Anchor **could not be checked** — calendar unreachable, or the OpenTimestamps verifier is not installed. Deliberately distinct from 14: "I could not verify this" is not "this is invalid". The digest comparison is performed offline and still holds; only the timestamp attestation is unconfirmed. A verifier that collapsed the two would be asserting something it did not measure. |
196
+ | 14 | Claimed anchor invalid under `--anchor-check`, or `--require-head-anchor` when the head is unanchored. An individual `anchor:null` receipt is skipped, not failed — periodic anchoring leaves most of them null. |
197
+ | 15 | Anchor **could not be checked** — calendar unreachable, the OpenTimestamps verifier is not installed, or `--anchor-check` reached no anchor at all because every receipt in the chain is unanchored. Deliberately distinct from 14: "I could not verify this" is not "this is invalid". The digest comparison is performed offline and still holds; only the timestamp attestation is unconfirmed. A verifier that collapsed the two would be asserting something it did not measure. |
198
198
  | 20 | Schema invalid |
199
199
 
200
200
  Fail-closed: if the verifier is unsure, it does not exit 0.
201
201
 
202
+ ⚠️ `--anchor-check` over a chain where **no** receipt carries an anchor is exit
203
+ **15**, not 0. Each null is still skipped rather than failed, which is right —
204
+ but skipping all of them and then reporting success answers the caller's question
205
+ from a path that never reached an anchor. The summary line always printed
206
+ `0/N anchored`; the exit code was the part that claimed more than was examined,
207
+ and the exit code is what a machine reads. `--require-head-anchor` stays 14: the
208
+ caller asserted an anchor must be there, and its absence is a failed assertion
209
+ rather than an unread one. *Changed in 0.2.40; it was 0 before, and a test had
210
+ written the old answer down.*
211
+
202
212
  ⚠️ Under `--anchor-check`, an OpenTimestamps **calendar** that cannot be
203
213
  reached is exit **15** (`anchor could not be checked`) — not 14. Digest
204
214
  comparison is offline and still holds. A `verify()` error that is *not*
@@ -362,7 +372,7 @@ sent to look at the wrong thing. The guard builds exactly that case — it
362
372
  removes the signature from the one receipt that already breaks the chain — and
363
373
  requires 11 and 12 rather than 13.
364
374
 
365
- ### Canonical form, and what the vectors do not measure — prose
375
+ ### Canonical form, and where JCS is actually reachable — measured
366
376
 
367
377
  Content bytes are canonicalised with **JCS (RFC 8785)** and digested with
368
378
  SHA-256, prefixed `sha256:`. `hash`, `sig` and `anchor` are removed first,
@@ -372,14 +382,50 @@ including the nested `chain.hash`.
372
382
  compare canonical bytes without holding our private key. Matching them is what
373
383
  interoperability actually requires; signing is RFC 8032 and none of it is ours.
374
384
 
375
- ⚠️ **Stated limit.** The published vectors are ASCII-keyed with integer and
376
- string values. A naive sorted-key serialiser reproduces every one of their
377
- hashes, so passing them does **not** demonstrate a conforming JCS
378
- implementation. The number formatting rules (RFC 8785 §3.2.2.3) and the
379
- UTF-16 code-unit sort order over non-ASCII keys are unexercised. A receipt
380
- carrying a float, a large integer, or a non-ASCII key is where two
381
- implementations will first disagree, and this repository does not currently
382
- publish a vector that would catch it.
385
+ ⚠️ **Correction to an earlier statement.** Up to 0.2.40 this section said the
386
+ limit would first bite on "a receipt carrying a float, a large integer, or a
387
+ non-ASCII key". No such receipt exists. The receipt body is a fixed shape: its
388
+ only numbers are `chain.seq`, `masking.pii` and `outcome.rows`, all small
389
+ integers, and every key in it is ASCII. `test/spec_jcs_class.mjs` measures that
390
+ across every shipped receipt rather than asserting it here. The limit was real;
391
+ it was announced in the wrong place.
392
+
393
+ Caller-shaped JSON reaches JCS at one point: `hashArgs()`, whose argument is
394
+ typed `any` and whose digest becomes `request.argsHash`. It is the only surface
395
+ whose *shape* is unbounded — arbitrary keys, arbitrary numbers — and until
396
+ 0.2.41 its preimages were published nowhere: vector 001 carries
397
+ `sha256:abab...`, a placeholder standing in for a hash of nothing.
398
+
399
+ It is not, however, the only place two implementations can part company.
400
+ `canonicalize` also digests countersign records, coverage rows and licence
401
+ payloads, and a receipt's string *values* — `actor.id`, `model.name`,
402
+ `policy.rules[]` — are free text that nothing constrains to ASCII. Keys are
403
+ fixed by the format; values are not. No shipped vector carries a non-ASCII
404
+ value today, which `test/spec_jcs_class.mjs` counts rather than asserts,
405
+ because the format permits one tomorrow.
406
+
407
+ **What is published now.** [`test-vectors/jcs/`](../test-vectors/jcs/) carries
408
+ the preimages, and `test/spec_jcs_class.mjs` measures all of it on every run:
409
+
410
+ | Evidence | Scope |
411
+ |---|---|
412
+ | The reference's own six input/expected pairs, compared over bytes | complete |
413
+ | 3,000 published IEEE-754 doubles from the reference's number vectors | **sampled** |
414
+ | Eight `argsHash` preimages: floats, integers past 2^53, non-ASCII keys, a surrogate-pair sort, escapes, the raw-string branch | complete |
415
+ | Eight mutants that must each be caught | complete |
416
+
417
+ **What is still a limit.** The number vectors are a sample: 3,000 lines of the
418
+ reference's 100,000,000, of which the first 2,168 are its deliberate
419
+ edge-case block and the rest are drawn from its pseudorandom stream. The space
420
+ of IEEE-754 doubles is not covered and cannot be. Separately, the thirteen
421
+ *receipt* vectors are unchanged and still exercise none of this — matching
422
+ their hashes demonstrates what it always did, no more.
423
+
424
+ ⚠️ One consequence worth stating plainly, because it is the case most likely to
425
+ break a second implementation: `hashArgs` does **not** canonicalise a string
426
+ argument. It digests the bytes it was handed. An implementation that parses and
427
+ re-canonicalises a string argument produces a different `argsHash` for input
428
+ both sides consider identical. Vector `008-raw-string` is that case.
383
429
 
384
430
  ### Which document is normative for what — prose
385
431
 
@@ -0,0 +1,70 @@
1
+ # Claims review — 0.2.40
2
+
3
+ - base: v0.2.39
4
+ - head: 0c2239c
5
+ - surface: sha256:976a388eaaa1069876dcc0aaeb2f626abfe3fd731a69c4dc51cbe06c8a02d57d
6
+ - verdict: pass
7
+ - reviewer: maintainer, reading the exit-code table against a behaviour change it
8
+ is describing for the first time
9
+
10
+ The surface change is two rows of one table. The finding below is about what the
11
+ old row said rather than what the new one does, and it is the reason the code
12
+ moved.
13
+
14
+ ## Findings
15
+
16
+ ### 1. docs/RECEIPT-SPEC.md — exit 14's row described a skip and let a verdict follow it
17
+
18
+ - Claim: "`anchor:null` receipts are skipped (periodic anchoring)."
19
+ - Mechanism: `conarium-verify --anchor-check` skips each receipt whose `anchor`
20
+ is null rather than failing it, and prints `0/N anchored` in its summary.
21
+ - Why it falls short: the sentence is true of each receipt and silent about the
22
+ run. Skipping every receipt in a chain leaves nothing compared, and the tool
23
+ then exited 0 — which a caller reads as "the anchors hold". The claim describes
24
+ a per-receipt policy; the exit code asserted a per-chain result that no
25
+ comparison supported. Two tests had written the old answer down
26
+ (`test/anchor_verify.mjs` A6.5 and `src/receipt.test.ts` T5.8), so this was a
27
+ decision rather than an oversight, and it had to be argued rather than
28
+ corrected on sight.
29
+ - Disposition: behaviour changed in 0c2239c. A chain under `--anchor-check` where
30
+ no receipt carries an anchor is exit **15** — the value that already means
31
+ "could not be checked". Both rows now say what they cover: 14 keeps the
32
+ per-receipt skip and the `--require-head-anchor` failure, 15 gains the
33
+ nothing-reached case. The expectations were corrected along with the code, and
34
+ the direction of that correction is recorded in both tests rather than left to
35
+ the next reader to reconstruct.
36
+
37
+ ### 2. The summary line was never silent, and the report of this said less than it should
38
+
39
+ - Claim: the description of this defect, as first written and sent to the SCITT
40
+ list, said the tool "reports success, having compared nothing".
41
+ - Mechanism: the run prints `0/N anchored, head anchored: no` on every
42
+ `--anchor-check` invocation, before this change and after it.
43
+ - Why it falls short: the statement is accurate about the exit code and
44
+ incomplete about the output. A reader watching the terminal could always see
45
+ that nothing was anchored. What could not see it was anything consuming the
46
+ exit code, which is the interface that matters for a checker.
47
+ - Disposition: recorded here rather than corrected in flight. The spec, the
48
+ changelog and both tests now state the distinction explicitly — the count was
49
+ always printed, the exit code was the part that claimed more than had been
50
+ examined.
51
+
52
+ ## Limits recorded rather than left to be found
53
+
54
+ - **This is a breaking change for one caller shape.** Anyone running
55
+ `--anchor-check` over chains that are never anchored, and treating 0 as
56
+ success, now gets 15. That is the intent, and it is stated in the changelog
57
+ under its own heading rather than buried in a list.
58
+ - A chain with at least one anchored receipt is unaffected. A run without
59
+ `--anchor-check` is unaffected. Both have a control test, because a fix that
60
+ quietly widened its blast radius would be the same class of defect it was
61
+ written to close.
62
+ - The locale word list grew for the second time by being wrong: four identifiers
63
+ in the shipped verifier (`modelBildirilmemis`, `clientBildirilmemis`, `notlar`,
64
+ `ek`) carried no Turkish-specific letter and were not in the list either. They
65
+ are translated and the words added. The list remains a list of what this
66
+ codebase reached for, not a language detector, and the next miss is expected to
67
+ arrive the same way.
68
+ - Turkish design history under `docs/` still ships in the package. Unchanged from
69
+ 0.2.39, still counted on every green run of `test/pack_locale.mjs`, still a
70
+ packaging decision that has not been made.
@@ -0,0 +1,91 @@
1
+ # Claims review — 0.2.41
2
+
3
+ - base: v0.2.40
4
+ - head: dfce48b
5
+ - surface: sha256:7cc3272b04d9e8784ff14e73a882a7497998f7f0f12c240ec0c8c44e7609e51f
6
+ - verdict: pass
7
+ - reviewer: maintainer, reading a paragraph that was written to withdraw an
8
+ earlier version of itself
9
+
10
+ Two surfaces changed.
11
+
12
+ `docs/RECEIPT-SPEC.md` — one section, replacing a stated limit that was true
13
+ about the vectors and wrong about where the limit would bite. Its heading moves
14
+ from `prose` to `measured` because `test/spec_jcs_class.mjs` now measures every
15
+ claim under it. Findings 1 and 2 are against the replacement text, not the text
16
+ it replaces.
17
+
18
+ `standards/README.md` — a "What `-06` added" paragraph, which every other
19
+ posted revision already had. Finding 3.
20
+
21
+ ## Findings
22
+
23
+ ### 1. docs/RECEIPT-SPEC.md — "the only surface" counted one caller out of five
24
+
25
+ - Claim: "That is the only surface where a second implementation can disagree
26
+ with us about canonicalisation."
27
+ - Mechanism: `hashArgs()` is the one entry point taking `any`, so arbitrary keys
28
+ and arbitrary numbers can only arrive through it. That much holds.
29
+ - Why it falls short: `canonicalize` has five callers — receipt bodies,
30
+ countersign records, coverage rows, licence payloads, `hashArgs`. And a
31
+ receipt's string *values* (`actor.id`, `model.name`, `policy.rules[]`) are
32
+ free text with no ASCII constraint anywhere in `src/receipt.ts`, so
33
+ `receiptHash` reaches string escaping on its own. "Only surface" was a claim
34
+ about the whole codebase resting on a fact about one function signature.
35
+ Written in the same commit that added a guard against exactly this shape of
36
+ error.
37
+ - Disposition: reworded in `75dfe72`. The sentence now claims only that
38
+ `hashArgs` is the surface whose *shape* is unbounded, and the paragraph
39
+ names the other four callers and the free-text values.
40
+
41
+ ### 2. docs/RECEIPT-SPEC.md — the heading moved to `measured`, and one row of the table under it is a sample
42
+
43
+ - Claim: heading "Canonical form, and where JCS is actually reachable —
44
+ measured", over a table one of whose rows reads "3,000 published IEEE-754
45
+ doubles".
46
+ - Mechanism: `test/spec_jcs_class.mjs` runs all six reference pairs, all 3,000
47
+ vendored number lines, all eight preimages and all eight mutants on every
48
+ `test:checks` run, and check 6 fails if the stated sample size and the
49
+ fixture disagree.
50
+ - Why it falls short: `measured` is accurate for every row, but the number row
51
+ measures 3,000 of 100,000,000 published values. A reader who takes `measured`
52
+ to mean `covered` would be wrong about that one row, and the number class is
53
+ the row where the difference matters — it is the only unbounded one.
54
+ - Disposition: accepted, and answered in the text rather than by softening the
55
+ heading. The row is marked **sampled** in the table, a paragraph headed "What
56
+ is still a limit" gives the ratio and the split between the reference's
57
+ deliberate block and its pseudorandom tail, the guard prints `SAMPLED` on the
58
+ passing line, and `test-vectors/jcs/rfc8785/PROVENANCE.md` states what was
59
+ not vendored. Four places, because the one that gets read is not predictable.
60
+
61
+ ### 3. standards/README.md — a third hand-written declaration of what `-06` says
62
+
63
+ - Claim: the whole "What `-06` added" paragraph, e.g. "every behavioural
64
+ statement is bound to a run of the shipped reconciliation tool over a fixture
65
+ the document names".
66
+ - Mechanism: the statement is true of the code — `test/implementation_status.mjs`
67
+ holds the claim table between the prose and the CLI and runs every claim
68
+ against the shipped binary, and `test/reconciliation_label_coverage.mjs` reads
69
+ the outcome list from the tool's own result. The paragraph was written from
70
+ the `-05..-06` diff rather than from memory.
71
+ - Why it falls short: writing it from the diff is a procedure, not a check.
72
+ Nothing compares this paragraph to the draft it summarises. `standards_claim`
73
+ and `datatracker_draft_status` read this file for other properties and neither
74
+ reads this. So there are now three declarations of what `-06` contains — the
75
+ draft, this paragraph, and the changelog — and two of them are prose that can
76
+ drift while every test stays green. That is the same shape as the "twelve
77
+ frozen cases" fork against a manifest holding thirteen.
78
+ - Disposition: accepted, shipping. The draft is normative and posted; this
79
+ paragraph is a repo reader's summary, and the file already says two paragraphs
80
+ below that the Datatracker link is the check and a revision history written
81
+ here is not. The risk is bounded by that sentence rather than removed, and the
82
+ paragraph is short enough that the next revision rewrites it rather than
83
+ editing around it. Recorded because bounded is not the same as absent.
84
+
85
+ ## Not a finding, recorded so the next reader does not re-derive it
86
+
87
+ The thirteen receipt vectors still do not exercise JCS beyond ASCII keys with
88
+ integer and string values. That is unchanged and is now stated in both
89
+ `RECEIPT-SPEC.md` and `test-vectors/README.md` as an unchanged fact rather than
90
+ as a gap awaiting a fix — the gap was never in the receipt vectors. A receipt
91
+ cannot carry the class; `hashArgs` can, and that is where the vectors went.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@conarium-ai/core",
3
- "version": "0.2.39",
3
+ "version": "0.2.41",
4
4
  "mcpName": "io.github.dogrucanemek-alt/conarium",
5
5
  "//files-artefakt": "Generated files under examples/ (private key, receipt/audit JSONL) are EXCLUDED. .gitignore does not bind npm: because the allow-list contained 'examples', `npm publish` on a machine that had run the demo was shipping _keys/audit-ed25519.pem (PRIVATE KEY) and the receipts. test/pack_artefakt.mjs locks this. The exclusions are LIMITED to examples/: receipts.jsonl and .pub.pem under test-vectors/ MUST ship, or a third party cannot run the conformance vectors.",
6
6
  "//files": "Allow-list of what enters the package. Without it npm sent everything: 296 files / 1.5 MB — CI workflows, gitleaks config, a 137 KB marketing image, the site's api/chat.js. A bank security team opens the tarball and sees those. scripts/ is here ON PURPOSE: conarium-reconcile references scripts/pg-snapshot.sql at runtime; without it the user files a support mail.",
@@ -22,6 +22,8 @@
22
22
  "!examples/**/conarium.tokens.json",
23
23
  "conformance",
24
24
  "test-vectors",
25
+ "!test-vectors/jcs/rfc8785",
26
+ "!test-vectors/jcs/rfc8785/**",
25
27
  "!**/*.pem",
26
28
  "test-vectors/keys/vector-key.pub.pem",
27
29
  "deploy",
@@ -0,0 +1,206 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Generates the JCS class vectors under test-vectors/jcs/args/.
4
+ *
5
+ * Why these exist
6
+ * ---------------
7
+ * The thirteen receipt vectors are ASCII-keyed, with integer and string
8
+ * values. A naive sorted-key serialiser reproduces every one of their hashes.
9
+ * That was stated as a limit of the vectors, and the stated remedy was a
10
+ * receipt carrying a float or a non-ASCII key.
11
+ *
12
+ * There is no such receipt. The receipt body is a fixed shape: its only
13
+ * numbers are `chain.seq`, `masking.pii` and `outcome.rows`, all small
14
+ * integers, and every key in it is ASCII. A float cannot appear in a
15
+ * receipt's canonical bytes.
16
+ *
17
+ * The place where caller-shaped JSON does meet JCS is `hashArgs()`
18
+ * (src/receipt.ts), which canonicalises the tool arguments an operator's
19
+ * client sent — typed `any`, unbounded in shape. Its result is the
20
+ * `request.argsHash` field. That preimage was published nowhere: vector 001
21
+ * carries `sha256:abab...`, a placeholder standing in for a hash of nothing.
22
+ *
23
+ * So a second implementation could match all thirteen receipt hashes and
24
+ * still disagree with us on the first non-ASCII tool argument it saw. These
25
+ * vectors are the preimages that close that.
26
+ *
27
+ * The preimages are held below as raw JSON *text*, not as JavaScript values,
28
+ * because one of them is a trap that only exists in the text: the digits
29
+ * 9007199254740993 do not survive being parsed as a double. A generator that
30
+ * round-tripped through a JS literal would silently drop the case it was
31
+ * written to freeze.
32
+ *
33
+ * node scripts/gen-jcs-vectors.mjs
34
+ *
35
+ * Refuses to overwrite. If a change to this repository breaks one of these,
36
+ * the canonical form changed, and that is the signal they exist to raise.
37
+ */
38
+ import { createHash } from 'node:crypto'
39
+ import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
40
+ import path from 'node:path'
41
+ import { fileURLToPath } from 'node:url'
42
+
43
+ import { canonicalize, hashArgs } from '../dist/receipt.js'
44
+
45
+ const here = path.dirname(fileURLToPath(import.meta.url))
46
+ const root = path.resolve(here, '..')
47
+ const OUT = path.join(root, 'test-vectors', 'jcs', 'args')
48
+
49
+ /**
50
+ * kind: 'json' — the file holds a JSON document; it is parsed, then canonicalised.
51
+ * kind: 'string' — the file holds raw bytes; hashArgs hashes them AS THEY ARE.
52
+ * This branch does not canonicalise anything, and an
53
+ * implementation that canonicalises it anyway will disagree.
54
+ */
55
+ const CASES = [
56
+ {
57
+ name: '001-floats',
58
+ kind: 'json',
59
+ exercises:
60
+ 'RFC 8785 §3.2.2.3 number formatting: exponent boundary at 1e21, denormal minimum, negative zero, trailing zero',
61
+ text: [
62
+ '{',
63
+ ' "ratio": 333333333.33333329,',
64
+ ' "small": 2e-3,',
65
+ ' "large": 1E30,',
66
+ ' "trailing_zero": 4.50,',
67
+ ' "below_exponent_boundary": 999999999999999900000,',
68
+ ' "at_exponent_boundary": 1e21,',
69
+ ' "denormal_min": 5e-324,',
70
+ ' "negative_zero": -0,',
71
+ ' "python_would_print_1e_06": 0.000001',
72
+ '}',
73
+ ].join('\n'),
74
+ },
75
+ {
76
+ name: '002-integers-beyond-double',
77
+ kind: 'json',
78
+ exercises:
79
+ 'JSON numbers are IEEE-754 doubles. An implementation using arbitrary-precision integers produces different bytes for the same document.',
80
+ text: [
81
+ '{',
82
+ ' "safe_max": 9007199254740991,',
83
+ ' "not_representable": 9007199254740993,',
84
+ ' "reference_pair_low": 9007199254740994,',
85
+ ' "reference_pair_high": 9007199254740996',
86
+ '}',
87
+ ].join('\n'),
88
+ },
89
+ {
90
+ name: '003-non-ascii-keys',
91
+ kind: 'json',
92
+ exercises:
93
+ 'Key order is over UTF-16 code units and MUST ignore locale. A French collation puts these in a different order.',
94
+ text: [
95
+ '{',
96
+ ' "sin": "locale-independent",',
97
+ ' "pêche": "e-circumflex U+00EA",',
98
+ ' "péché": "e-acute U+00E9",',
99
+ ' "peach": "ascii",',
100
+ ' "École": "U+00C9 sorts after every ascii key, not next to E",',
101
+ ' "ecole": "ascii e"',
102
+ '}',
103
+ ].join('\n'),
104
+ },
105
+ {
106
+ name: '004-surrogate-key-order',
107
+ kind: 'json',
108
+ exercises:
109
+ 'The code-unit / code-point split. U+1F602 is stored as the surrogate pair D83D DE02; by code unit it sorts BEFORE U+FB33, by code point AFTER. Only one of those is RFC 8785.',
110
+ text: [
111
+ '{',
112
+ ' "דּ": "U+FB33 hebrew letter dalet with dagesh",',
113
+ ' "😂": "U+1F602 face with tears of joy",',
114
+ ' "€": "U+20AC euro sign",',
115
+ ' "z": "ascii tail"',
116
+ '}',
117
+ ].join('\n'),
118
+ },
119
+ {
120
+ name: '005-string-escapes',
121
+ kind: 'json',
122
+ exercises:
123
+ 'RFC 8785 §3.2.2.2: which characters are escaped and which are emitted literally. Solidus is NOT escaped; C0 controls without a short form use \\u00XX lower case.',
124
+ text: [
125
+ '{',
126
+ ' "quote_backslash": "\\"\\\\",',
127
+ ' "solidus_stays_bare": "a/b",',
128
+ ' "short_forms": "\\b\\f\\n\\r\\t",',
129
+ ' "control_no_short_form": "\\u0000\\u001f\\u007f",',
130
+ ' "literal_non_ascii": "€ é 😂"',
131
+ '}',
132
+ ].join('\n'),
133
+ },
134
+ {
135
+ name: '006-nested-tool-args',
136
+ kind: 'json',
137
+ exercises:
138
+ 'The realistic shape: what an MCP client actually sends. Nesting, arrays whose order is preserved, and the classes above reached through a nested path.',
139
+ text: [
140
+ '{',
141
+ ' "query": "select * from clients where montant > 0.1",',
142
+ ' "limit": 100,',
143
+ ' "filters": [',
144
+ ' { "field": "montant", "op": ">", "value": 1234.5 },',
145
+ ' { "field": "société", "op": "in", "value": ["FR", "DE"] }',
146
+ ' ],',
147
+ ' "options": { "timeout_s": 2e-3, "dry_run": false, "cursor": null }',
148
+ '}',
149
+ ].join('\n'),
150
+ },
151
+ {
152
+ name: '007-null',
153
+ kind: 'json',
154
+ exercises:
155
+ 'The default path. audit.ts calls hashArgs(entry.args ?? null), so this is the hash every receipt with no arguments carries.',
156
+ text: 'null',
157
+ },
158
+ {
159
+ name: '008-raw-string',
160
+ kind: 'string',
161
+ exercises:
162
+ 'hashArgs does NOT canonicalise a string argument — it hashes the bytes it was handed. The bytes below are valid JSON, which is the trap: an implementation that parses and re-canonicalises produces a different hash for the same input.',
163
+ text: '{"b":2,"a":1}',
164
+ },
165
+ ]
166
+
167
+ if (existsSync(path.join(OUT, 'expected-args-hashes.json'))) {
168
+ console.error('refusing to overwrite: test-vectors/jcs/args/expected-args-hashes.json exists')
169
+ console.error('these vectors are frozen. do not regenerate them to make a test pass.')
170
+ process.exit(1)
171
+ }
172
+
173
+ mkdirSync(OUT, { recursive: true })
174
+
175
+ const expected = { note: '', cases: [] }
176
+ for (const c of CASES) {
177
+ const file = `${c.name}.${c.kind === 'string' ? 'txt' : 'json'}`
178
+ writeFileSync(path.join(OUT, file), c.text, 'utf-8')
179
+
180
+ const args = c.kind === 'string' ? c.text : JSON.parse(c.text)
181
+ const argsHash = hashArgs(args)
182
+ const canonical = c.kind === 'string' ? c.text : canonicalize(args)
183
+
184
+ expected.cases.push({
185
+ name: c.name,
186
+ file,
187
+ kind: c.kind,
188
+ exercises: c.exercises,
189
+ canonicalBytes: Buffer.byteLength(canonical, 'utf-8'),
190
+ argsHash,
191
+ })
192
+ console.log(`${c.name.padEnd(28)} ${argsHash}`)
193
+ }
194
+
195
+ expected.note =
196
+ 'Preimages for request.argsHash. Feed the file to your hashArgs equivalent and compare. ' +
197
+ 'kind=json: parse, canonicalise (RFC 8785), SHA-256. ' +
198
+ 'kind=string: hash the bytes as they are — do NOT parse or re-canonicalise. ' +
199
+ 'Frozen: regenerate only if the canonical form itself changed on purpose.'
200
+
201
+ writeFileSync(
202
+ path.join(OUT, 'expected-args-hashes.json'),
203
+ JSON.stringify(expected, null, 2) + '\n',
204
+ 'utf-8',
205
+ )
206
+ console.log(`\nwrote ${CASES.length} preimages + expected-args-hashes.json`)
@@ -77,6 +77,33 @@ when the caller never asked for one. Silence is not a pass. This vector was
77
77
  originally written expecting `0`; the verifier disagreed and the verifier was
78
78
  right, so the expectation was corrected rather than the behaviour.
79
79
 
80
+ ## JCS vectors — [`jcs/`](jcs/)
81
+
82
+ The thirteen cases above are ASCII-keyed with integer and string values, so a
83
+ naive sorted-key serialiser reproduces all thirteen hashes. That is still true
84
+ and is not a defect in them: a receipt body *cannot* carry a float or a
85
+ non-ASCII key. Its only numbers are `chain.seq`, `masking.pii` and
86
+ `outcome.rows`.
87
+
88
+ Canonicalisation is reachable from outside at one point — `hashArgs()`, the
89
+ tool arguments an operator's client sent, typed `any`, digested into
90
+ `request.argsHash`. [`jcs/args/`](jcs/args/) publishes eight preimages for it
91
+ with their frozen hashes: floats at the `1e21` exponent boundary and the
92
+ denormal minimum, integers past 2^53, non-ASCII keys, a surrogate-pair sort
93
+ order, escape rules, and the raw-string branch.
94
+
95
+ Read [`jcs/args/expected-args-hashes.json`](jcs/args/expected-args-hashes.json)
96
+ before implementing against them — `kind` decides whether the file is parsed
97
+ and canonicalised or digested as the bytes it is. Getting that wrong is the
98
+ single most likely way two implementations disagree here.
99
+
100
+ Our own conformance against the RFC's reference data — six input/expected pairs
101
+ byte for byte, and 3,000 published IEEE-754 doubles — is measured by
102
+ `test/spec_jcs_class.mjs`, alongside eight mutants it must catch. The number
103
+ evidence is a **sample** of the reference's 100,000,000 and says so; see
104
+ [`jcs/rfc8785/PROVENANCE.md`](jcs/rfc8785/PROVENANCE.md), which also records
105
+ that the vendored fixtures are Apache-2.0 and not ours.
106
+
80
107
  ## The key, and why the private half is not here
81
108
 
82
109
  `keys/vector-key.pub.pem` is published. The private half is not, and will not
@@ -0,0 +1,11 @@
1
+ {
2
+ "ratio": 333333333.33333329,
3
+ "small": 2e-3,
4
+ "large": 1E30,
5
+ "trailing_zero": 4.50,
6
+ "below_exponent_boundary": 999999999999999900000,
7
+ "at_exponent_boundary": 1e21,
8
+ "denormal_min": 5e-324,
9
+ "negative_zero": -0,
10
+ "python_would_print_1e_06": 0.000001
11
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "safe_max": 9007199254740991,
3
+ "not_representable": 9007199254740993,
4
+ "reference_pair_low": 9007199254740994,
5
+ "reference_pair_high": 9007199254740996
6
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "sin": "locale-independent",
3
+ "pêche": "e-circumflex U+00EA",
4
+ "péché": "e-acute U+00E9",
5
+ "peach": "ascii",
6
+ "École": "U+00C9 sorts after every ascii key, not next to E",
7
+ "ecole": "ascii e"
8
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "דּ": "U+FB33 hebrew letter dalet with dagesh",
3
+ "😂": "U+1F602 face with tears of joy",
4
+ "€": "U+20AC euro sign",
5
+ "z": "ascii tail"
6
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "quote_backslash": "\"\\",
3
+ "solidus_stays_bare": "a/b",
4
+ "short_forms": "\b\f\n\r\t",
5
+ "control_no_short_form": "\u0000\u001f\u007f",
6
+ "literal_non_ascii": "€ é 😂"
7
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "query": "select * from clients where montant > 0.1",
3
+ "limit": 100,
4
+ "filters": [
5
+ { "field": "montant", "op": ">", "value": 1234.5 },
6
+ { "field": "société", "op": "in", "value": ["FR", "DE"] }
7
+ ],
8
+ "options": { "timeout_s": 2e-3, "dry_run": false, "cursor": null }
9
+ }
@@ -0,0 +1 @@
1
+ null
@@ -0,0 +1 @@
1
+ {"b":2,"a":1}
@@ -0,0 +1,69 @@
1
+ {
2
+ "note": "Preimages for request.argsHash. Feed the file to your hashArgs equivalent and compare. kind=json: parse, canonicalise (RFC 8785), SHA-256. kind=string: hash the bytes as they are — do NOT parse or re-canonicalise. Frozen: regenerate only if the canonical form itself changed on purpose.",
3
+ "cases": [
4
+ {
5
+ "name": "001-floats",
6
+ "file": "001-floats.json",
7
+ "kind": "json",
8
+ "exercises": "RFC 8785 §3.2.2.3 number formatting: exponent boundary at 1e21, denormal minimum, negative zero, trailing zero",
9
+ "canonicalBytes": 228,
10
+ "argsHash": "sha256:57ab485264c96fe1732bafcab50763793d10c88503d7d2c9c3f4c4b76c0285d1"
11
+ },
12
+ {
13
+ "name": "002-integers-beyond-double",
14
+ "file": "002-integers-beyond-double.json",
15
+ "kind": "json",
16
+ "exercises": "JSON numbers are IEEE-754 doubles. An implementation using arbitrary-precision integers produces different bytes for the same document.",
17
+ "canonicalBytes": 143,
18
+ "argsHash": "sha256:d966f958a2df3f2726ca87fc14407d5486d5987932dc50c22c446558621019ba"
19
+ },
20
+ {
21
+ "name": "003-non-ascii-keys",
22
+ "file": "003-non-ascii-keys.json",
23
+ "kind": "json",
24
+ "exercises": "Key order is over UTF-16 code units and MUST ignore locale. A French collation puts these in a different order.",
25
+ "canonicalBytes": 181,
26
+ "argsHash": "sha256:421d8b0e71ae3234ec29d60ebe6fb68ec83da86e2997118a9f3b7be5d37766ef"
27
+ },
28
+ {
29
+ "name": "004-surrogate-key-order",
30
+ "file": "004-surrogate-key-order.json",
31
+ "kind": "json",
32
+ "exercises": "The code-unit / code-point split. U+1F602 is stored as the surrogate pair D83D DE02; by code unit it sorts BEFORE U+FB33, by code point AFTER. Only one of those is RFC 8785.",
33
+ "canonicalBytes": 130,
34
+ "argsHash": "sha256:a909c2091fb4403862084a333cc067cfb5c0954acd7be125ee8aafdb757862f6"
35
+ },
36
+ {
37
+ "name": "005-string-escapes",
38
+ "file": "005-string-escapes.json",
39
+ "kind": "json",
40
+ "exercises": "RFC 8785 §3.2.2.2: which characters are escaped and which are emitted literally. Solidus is NOT escaped; C0 controls without a short form use \\u00XX lower case.",
41
+ "canonicalBytes": 154,
42
+ "argsHash": "sha256:bdb9633a3b4d4507734c091261df3703e0cc06829952419f481a417809f4ad5c"
43
+ },
44
+ {
45
+ "name": "006-nested-tool-args",
46
+ "file": "006-nested-tool-args.json",
47
+ "kind": "json",
48
+ "exercises": "The realistic shape: what an MCP client actually sends. Nesting, arrays whose order is preserved, and the classes above reached through a nested path.",
49
+ "canonicalBytes": 233,
50
+ "argsHash": "sha256:1bc49cf8d4b78e4ea867078b78808e172ec460015367c31680f7baf17107ccb2"
51
+ },
52
+ {
53
+ "name": "007-null",
54
+ "file": "007-null.json",
55
+ "kind": "json",
56
+ "exercises": "The default path. audit.ts calls hashArgs(entry.args ?? null), so this is the hash every receipt with no arguments carries.",
57
+ "canonicalBytes": 4,
58
+ "argsHash": "sha256:74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b"
59
+ },
60
+ {
61
+ "name": "008-raw-string",
62
+ "file": "008-raw-string.txt",
63
+ "kind": "string",
64
+ "exercises": "hashArgs does NOT canonicalise a string argument — it hashes the bytes it was handed. The bytes below are valid JSON, which is the trap: an implementation that parses and re-canonicalises produces a different hash for the same input.",
65
+ "canonicalBytes": 13,
66
+ "argsHash": "sha256:3fb75453225c732a76b7899ea2096dda1455189c89817239732182f73fe5a09f"
67
+ }
68
+ ]
69
+ }