@conarium-ai/core 0.2.41 → 0.2.42

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,34 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.42 — a usage error is not a schema verdict
4
+
5
+ `conarium-verify` exited **20** for an unknown flag and for a missing path.
6
+ The published tables give 20 one meaning: *Schema invalid*. A machine that
7
+ typed the command wrong was therefore handed a verdict about a receipt it
8
+ had never opened. That is the same shape as the 0.2.40 `--anchor-check`
9
+ defect: the code named an event that had not occurred.
10
+
11
+ Usage errors are now **2**, which sits outside the verdict range (10–20).
12
+ A real schema failure — vector 007, or `fail(20, …)` after a receipt is
13
+ read — is still 20. The uncaught-exception path at the bottom of the file
14
+ is also still 20; it is not a schema diagnosis, and this release does not
15
+ rename it.
16
+
17
+ Nor is a target that is not there. `conarium-verify missing.jsonl --pubkey
18
+ <key>` prints `path not found` and exits **20**, having opened no receipt.
19
+ That is the same defect one path over, and this release does not fix it:
20
+ whether an unreachable input is a usage error, a verdict, or a third thing
21
+ is a decision about the exit-code contract, not a typo. It is written down
22
+ in `docs/RECEIPT-SPEC.md` where the table can be read against the binary,
23
+ and it is the next change to this file.
24
+
25
+ **This is a behaviour change.** A script that treated every 20 as "schema
26
+ invalid" was already folding typos into that bucket. Those typos will now
27
+ be 2. Schema-invalid inputs are unaffected.
28
+
29
+ `conarium-coverage`, `conarium-reconcile` and `conarium-stamp` still exit
30
+ 20 on usage errors. They were measured, not changed.
31
+
3
32
  ## 0.2.41 — a limit that was announced in the wrong place
4
33
 
5
34
  Since 0.2.34 `docs/RECEIPT-SPEC.md` had carried a stated limit: the thirteen
@@ -21,6 +21,7 @@
21
21
  * (null anchors are skipped; --require-head-anchor fails if head is unanchored)
22
22
  * 15 anchor COULD NOT BE CHECKED (calendar unreachable, verifier not installed)
23
23
  * — deliberately distinct from 14: "I could not verify" is not "this is invalid"
24
+ * 2 usage error — no receipt was read
24
25
  * 20 schema invalid
25
26
  */
26
27
  import { createHash, createPublicKey, verify as cryptoVerify } from 'crypto'
@@ -425,11 +426,11 @@ async function main(argv = process.argv.slice(2)) {
425
426
  opts = parseArgs(argv)
426
427
  } catch (err) {
427
428
  usage(err.message)
428
- process.exit(20)
429
+ process.exit(2)
429
430
  }
430
431
  if (!opts.target) {
431
432
  usage('missing <file|dir>')
432
- process.exit(20)
433
+ process.exit(2)
433
434
  }
434
435
 
435
436
  if (opts.strict && opts.expectSeqFrom === null) {
@@ -189,13 +189,14 @@ are unchanged.
189
189
  | Exit | Meaning |
190
190
  |---|---|
191
191
  | 0 | Chain intact, signatures valid |
192
+ | 2 | Usage error — no receipt was read |
192
193
  | 10 | Hash mismatch — record altered |
193
194
  | 11 | `prevHash` break — deleted or inserted; also `--expect-count` / `--expect-last-hash` mismatch |
194
195
  | 12 | `seq` gap / non-increasing — missing or reordered |
195
196
  | 13 | Signature invalid / pubkey missing (fail-closed) |
196
197
  | 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
198
  | 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
- | 20 | Schema invalid |
199
+ | 20 | Schema invalid — a receipt was read and failed the schema. ⚠️ Also returned when the target path does not exist (`path not found`) and on an uncaught exception, neither of which reads a receipt. Both are known and unfixed; `CHANGELOG.md` 0.2.42 says why. |
199
200
 
200
201
  Fail-closed: if the verifier is unsure, it does not exit 0.
201
202
 
@@ -0,0 +1,77 @@
1
+ # Claims review — 0.2.42
2
+
3
+ - base: v0.2.41
4
+ - head: 3f1e1ac
5
+ - surface: sha256:cd23938f0f7bb0b2d82600be062b9d7bd2910b3663fe9f897729b5bd4bc37639
6
+ - verdict: pass
7
+ - reviewer: maintainer, running the binary rather than reading it — which is
8
+ how the second finding was found and the first review missed it
9
+
10
+ One surface changed: the `conarium-verify` exit table in
11
+ `docs/RECEIPT-SPEC.md`. Two rows. The `2` row is new and is what the release
12
+ is for. The `20` row was rewritten during this review, in `3f1e1ac`, because
13
+ measuring it made the old text false.
14
+
15
+ ## Findings
16
+
17
+ ### 1. docs/RECEIPT-SPEC.md:191 — a table row is read as a class, and this one holds in only one direction
18
+
19
+ - Claim: "| 2 | Usage error — no receipt was read |"
20
+ - Mechanism: `bin/conarium-verify.mjs:428` and `:432` exit 2 on a `parseArgs`
21
+ throw and on a missing target. `test/verify_usage_exit.mjs` asserts an
22
+ unknown flag and a missing path are not 20, and that vector 007 still is.
23
+ - Why it falls short: the sentence is true of 2. An exit-code table is read as
24
+ a partition, so a reader also takes the converse — no receipt read, therefore
25
+ 2 — and the converse is false in the same binary. Measured, all with a valid
26
+ key: `--file x` → 2, no arguments → 2, `missing.jsonl` → **20**, no
27
+ `--pubkey` → **13**. Two of the four ways to hand this tool nothing it can
28
+ verify still answer inside the verdict range.
29
+ - Disposition: accepted, and answered in the `20` row rather than by weakening
30
+ the `2` row, which is accurate. 13 is left alone: omitting `--pubkey` is
31
+ documented fail-closed behaviour that predates this release and reversing it
32
+ would trade a naming defect for a safety one.
33
+
34
+ ### 2. CHANGELOG.md — the release named the remainder of its own defect, and the remainder was larger
35
+
36
+ - Claim, as written before this review: "The uncaught-exception path at the
37
+ bottom of the file is also still 20; it is not a schema diagnosis, and this
38
+ release does not rename it." Offered as the complete remainder.
39
+ - Mechanism: reading `bin/conarium-verify.mjs` for `exit(20)` and `fail(20`,
40
+ which finds the schema call at 521 and the catch at 735.
41
+ - Why it falls short: reading finds those two. `loadReceipts` returns
42
+ `{ error: 'path not found', code: 20 }` at line 252 — a literal on a return
43
+ object, not a call the reader's eye was scanning for — and it fires before
44
+ any file is opened. So a release whose entire subject is *a code that names
45
+ an event which did not occur* was published with an incomplete list of the
46
+ places it still does that. The check that caught it was running the command,
47
+ not reading the file, and the first review of this branch did not run it.
48
+ - Disposition: corrected in `3f1e1ac` before publish, in both the changelog and
49
+ the table. **The behaviour is unchanged and 0.2.42 does not fix it.** Whether
50
+ an unreachable target is a usage error, a verdict, or a third code is a
51
+ decision about the exit-code contract; making it in the last hour of the
52
+ release that found it is how the contract acquires a fourth meaning for a
53
+ number. It is named in the document where a reader can measure it.
54
+
55
+ ## Not a finding, recorded so the next reader does not re-derive it
56
+
57
+ An empty directory is exit **0**. Measured: `conarium-verify <empty dir>
58
+ --pubkey <key>` prints `warning: empty chain (0 receipts) — this is not a
59
+ verification that nothing was deleted` and exits 0.
60
+
61
+ This is the shape the spec already argues about elsewhere. Its own note on
62
+ `--anchor-check` says: "The summary line always printed `0/N anchored`; the
63
+ exit code was the part that claimed more than was examined, and the exit code
64
+ is what a machine reads." The empty chain is that sentence with the nouns
65
+ swapped — stderr names the limit, the exit code does not, and a machine reads
66
+ the exit code. It differs from 0.2.40 in one way that matters: the warning is
67
+ unconditional and says exactly what was not established, where `--anchor-check`
68
+ printed a number and left the reader to infer it.
69
+
70
+ Not raised as a finding because it is not on this diff's surface and the
71
+ remedy is the same open contract decision as finding 2. Recorded because it is
72
+ the third instance of one class in three releases, and the next person to open
73
+ this file should be told that before they find it a fourth time.
74
+
75
+ `conarium-coverage`, `conarium-reconcile` and `conarium-stamp` still exit 20 on
76
+ usage errors. They were measured in this cycle and deliberately not changed;
77
+ the changelog says so.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@conarium-ai/core",
3
- "version": "0.2.41",
3
+ "version": "0.2.42",
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.",
@@ -184,6 +184,7 @@ writeFileSync(
184
184
  note: 'Frozen conformance vectors. Run each case through your verifier and compare the exit code. KEYS/ in args resolves to the keys/ directory at the root of test-vectors.',
185
185
  exitCodes: {
186
186
  0: 'chain intact, signatures valid',
187
+ 2: 'Usage error — no receipt was read',
187
188
  10: 'hash mismatch — record altered',
188
189
  11: 'prevHash break — deleted or inserted',
189
190
  12: 'seq gap / non-increasing',
@@ -6,6 +6,7 @@
6
6
  "note": "Frozen conformance vectors. Run each case through your verifier and compare the exit code. KEYS/ in args resolves to the keys/ directory at the root of test-vectors.",
7
7
  "exitCodes": {
8
8
  "0": "chain intact, signatures valid",
9
+ "2": "Usage error — no receipt was read",
9
10
  "10": "hash mismatch — record altered",
10
11
  "11": "prevHash break — deleted or inserted",
11
12
  "12": "seq gap / non-increasing",