@conarium-ai/core 0.2.42 → 0.2.44

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,96 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.44 — a verdict code, on all four tools, now means something was read
4
+
5
+ **This is a behaviour change to every command-line tool in the package. Read
6
+ the table before upgrading a script that branches on exit codes.**
7
+
8
+ 0.2.42 moved `conarium-verify`'s usage errors out of the verdict range and said
9
+ the remaining misuse of 20 was the uncaught-exception handler. That was written
10
+ from reading the file. Running it found `conarium-verify missing.jsonl` exiting
11
+ **20** — *Schema invalid* — with no receipt opened, from a `return { code: 20 }`
12
+ inside `loadReceipts`. 0.2.43 documented it. This release fixes it, and finishes
13
+ the job across the three tools that were measured in 0.2.42 and left alone.
14
+
15
+ Two codes now sit outside the verdict range, and mean the same thing on all
16
+ four binaries:
17
+
18
+ | Exit | Meaning |
19
+ |---|---|
20
+ | 1 | The tool failed unexpectedly — no verdict was reached |
21
+ | 2 | The command could not be run as given — an unknown flag, a required argument that was not given, or a target that is not there. Nothing was read. |
22
+
23
+ What moved, measured before and after:
24
+
25
+ | Invocation | 0.2.43 | 0.2.44 |
26
+ |---|---|---|
27
+ | `conarium-verify <missing path>` | 20 | **2** |
28
+ | `conarium-coverage` — unknown flag, missing argument, missing declaration or receipts file | 20 | **2** |
29
+ | `conarium-reconcile` — unknown flag, missing flags, missing snapshot, receipts or profile | 20 | **2** |
30
+ | `conarium-stamp` — unknown flag, missing argument, missing or unreadable target | 20 | **2** |
31
+ | all four — uncaught exception | 20 | **1** |
32
+
33
+ Unchanged, and asserted in the same test run so the release cannot trade one
34
+ wrong answer for another: a valid chain is 0, a schema failure on a receipt that
35
+ was read is 20, a bad signature is 13, and **a missing `--pubkey` is still 13**.
36
+ That last one is a usage mistake by any ordinary reading, and it stays a verdict
37
+ on purpose: 13 is fail-closed, a script that has special-cased it is asserting
38
+ *do not trust this*, and moving it to 2 would turn that assertion off in the
39
+ name of tidiness. `--help` is 0 on all four.
40
+
41
+ **Who breaks.** A script reading 20 as "schema invalid" was already folding
42
+ typos and missing files into that bucket; those now arrive as 2, and genuine
43
+ schema failures are unaffected. A script treating any non-zero as failure sees
44
+ no change. A script that branches on 20 to page a human about a malformed
45
+ receipt will now page correctly — the missing-file case that used to reach it
46
+ was never a malformed receipt.
47
+
48
+ `test/exit_contract.mjs` is new and runs all four binaries: twelve invocations
49
+ that reach no artefact, nine verdicts and `--help` cases that must not move. It
50
+ was written first and failed on eleven of the twelve, which is the record of
51
+ what this release actually changed. The uncaught-exception path is the one line
52
+ here not covered by it — no CLI input reaches that handler, which is why it is
53
+ last-resort, and the change is covered by reading rather than by a run. Said
54
+ plainly rather than implied by an untested green.
55
+
56
+ ## 0.2.43 — the number watching the Turkish was reporting a third of it
57
+
58
+ `test/pack_locale.mjs` has always ended with a line naming what it does *not*
59
+ fix: Turkish left under `docs/`, out of interface scope, printed so it stays
60
+ visible. The line read `324 occurrences across 22 files`. The letter pass finds
61
+ **1034 lines across 29 files**. The remainder was counted by `wordProbe` alone —
62
+ the pass written for Turkish that carries *no* Turkish letter, and therefore the
63
+ wrong instrument for Turkish prose. Both passes now run and the union is
64
+ reported.
65
+
66
+ What the package was shipping under that number: `docs/superpowers/`,
67
+ `docs/plans/`, `docs/specs/` and `docs/audit/` — dated internal design and
68
+ process documents, in Turkish, including plan files whose first instruction is
69
+ addressed to an agent rather than to a reader. They are out of the package, the
70
+ way `docs/reviews` and `docs/teaching` already were. **243 packed paths, down
71
+ from 257.** The remainder is **34 lines across 14 files**: the bilingual
72
+ limitation paragraphs in `README.md` and `docs/RECEIPT-SPEC.md`, product strings
73
+ quoted in this changelog, and a TURKPATENT citation in `docs/PRIOR-ART.md`.
74
+
75
+ Two sentences were translated rather than dropped: the specification test in
76
+ `conformance/README.md`, and a Turkish parenthetical inside an English paragraph
77
+ of `docs/RECEIPT-SPEC.md`.
78
+
79
+ The remainder is now **pinned** in `docs/claims/locale-residue.json` and the
80
+ guard fails when the tree disagrees with it — in either direction. A printed
81
+ number nobody compares against anything is how this one drifted through three
82
+ releases; it was copied into a handover note as `308 / 19`, a figure that
83
+ reproduces under no definition and matched no release.
84
+
85
+ `test/pack_path_refs.mjs` is new. Dropping `docs/superpowers/` turned the
86
+ "Design source:" line at the top of `docs/RECEIPT-SPEC.md` into a path a reader
87
+ who installed the package cannot open — a dead reference created by a packaging
88
+ change, with no character of that sentence edited. The check reads the documents
89
+ npm packs and fails when one names a path that exists in the repository and not
90
+ in the package. It only considers directories the package *partially* ships:
91
+ `src/` and `test/` are wholly absent and always were, and a check that reports
92
+ those is a check that gets switched off.
93
+
3
94
  ## 0.2.42 — a usage error is not a schema verdict
4
95
 
5
96
  `conarium-verify` exited **20** for an unknown flag and for a missing path.
@@ -164,7 +164,7 @@ function loadVerifyKeys(paths) {
164
164
 
165
165
  function loadDeclaration(path) {
166
166
  if (!existsSync(path)) {
167
- return { error: `declaration not found: ${path}`, code: 20 }
167
+ return { error: `declaration not found: ${path}`, code: 2 }
168
168
  }
169
169
  let obj
170
170
  try {
@@ -177,7 +177,7 @@ function loadDeclaration(path) {
177
177
 
178
178
  function loadReceipts(path) {
179
179
  if (!existsSync(path)) {
180
- return { error: `receipts file not found: ${path}`, code: 20 }
180
+ return { error: `receipts file not found: ${path}`, code: 2 }
181
181
  }
182
182
  const raw = readFileSync(path, 'utf-8').trim()
183
183
  if (!raw) return { receipts: [] }
@@ -375,11 +375,11 @@ async function main(argv = process.argv.slice(2)) {
375
375
  opts = parseArgs(argv)
376
376
  } catch (err) {
377
377
  usage(err.message)
378
- process.exit(20)
378
+ process.exit(2)
379
379
  }
380
380
  if (!opts.target) {
381
381
  usage('missing <declaration.json>')
382
- process.exit(20)
382
+ process.exit(2)
383
383
  }
384
384
 
385
385
  const keyResult = loadVerifyKeys(opts.pubkeys)
@@ -504,6 +504,6 @@ const isDirect =
504
504
  if (isDirect) {
505
505
  main().catch((err) => {
506
506
  console.error(err)
507
- process.exit(20)
507
+ process.exit(1)
508
508
  })
509
509
  }
@@ -90,7 +90,7 @@ const PROFILE_V = 'conarium-mapping-profile/0.1'
90
90
 
91
91
  function loadSnapshot(path, label) {
92
92
  if (!existsSync(path)) {
93
- return { error: `${label} snapshot not found: ${path}` }
93
+ return { error: `${label} snapshot not found: ${path}`, code: 2 }
94
94
  }
95
95
  let obj
96
96
  try {
@@ -192,7 +192,7 @@ export function classifyPattern(query) {
192
192
  // ─── receipts ────────────────────────────────────────────────────────────────
193
193
 
194
194
  function loadReceipts(path) {
195
- if (!existsSync(path)) return { error: `receipts file not found: ${path}` }
195
+ if (!existsSync(path)) return { error: `receipts file not found: ${path}`, code: 2 }
196
196
  const raw = readFileSync(path, 'utf-8').trim()
197
197
  if (!raw) return { receipts: [] }
198
198
  const receipts = []
@@ -471,7 +471,7 @@ function patternDigest(query) {
471
471
  * indeterminate — this function does not invent a bound of one.
472
472
  */
473
473
  export function loadMappingProfile(path) {
474
- if (!existsSync(path)) return { error: `profile not found: ${path}` }
474
+ if (!existsSync(path)) return { error: `profile not found: ${path}`, code: 2 }
475
475
  const raw = readFileSync(path)
476
476
  let obj
477
477
  try {
@@ -784,25 +784,25 @@ async function main(argv = process.argv.slice(2)) {
784
784
  opts = parseArgs(argv)
785
785
  } catch (err) {
786
786
  usage(err.message)
787
- process.exit(20)
787
+ process.exit(2)
788
788
  }
789
789
  if (!opts.before || !opts.after || !opts.receiptsPath) {
790
790
  usage('missing required flag (--before, --after and --receipts are all required)')
791
- process.exit(20)
791
+ process.exit(2)
792
792
  }
793
793
 
794
794
  const b = loadSnapshot(opts.before, 'before')
795
- if (b.error) fail(20, b.error, opts.json)
795
+ if (b.error) fail(b.code ?? 20, b.error, opts.json)
796
796
  const a = loadSnapshot(opts.after, 'after')
797
- if (a.error) fail(20, a.error, opts.json)
797
+ if (a.error) fail(a.code ?? 20, a.error, opts.json)
798
798
  const rec = loadReceipts(opts.receiptsPath)
799
- if (rec.error) fail(20, rec.error, opts.json)
799
+ if (rec.error) fail(rec.code ?? 20, rec.error, opts.json)
800
800
 
801
801
  let profile = null
802
802
  let profileRaw = Buffer.from('')
803
803
  if (opts.profilePath) {
804
804
  const loaded = loadMappingProfile(opts.profilePath)
805
- if (loaded.error) fail(20, loaded.error, opts.json)
805
+ if (loaded.error) fail(loaded.code ?? 20, loaded.error, opts.json)
806
806
  profile = loaded.profile
807
807
  profileRaw = loaded.raw
808
808
  }
@@ -955,6 +955,6 @@ const isDirect =
955
955
  if (isDirect) {
956
956
  main().catch((err) => {
957
957
  console.error(err)
958
- process.exit(20)
958
+ process.exit(1)
959
959
  })
960
960
  }
@@ -65,15 +65,15 @@ async function main(argv = process.argv.slice(2)) {
65
65
  opts = parseArgs(argv)
66
66
  } catch (err) {
67
67
  usage(err.message)
68
- process.exit(20)
68
+ process.exit(2)
69
69
  }
70
70
  if (!opts.target) {
71
71
  usage('missing <file>')
72
- process.exit(20)
72
+ process.exit(2)
73
73
  }
74
74
  if (!existsSync(opts.target)) {
75
75
  console.error(`file not found: ${opts.target}`)
76
- process.exit(20)
76
+ process.exit(2)
77
77
  }
78
78
 
79
79
  let content
@@ -81,7 +81,7 @@ async function main(argv = process.argv.slice(2)) {
81
81
  content = readFileSync(opts.target)
82
82
  } catch (err) {
83
83
  console.error(`cannot read ${opts.target}: ${err.message}`)
84
- process.exit(20)
84
+ process.exit(2)
85
85
  }
86
86
 
87
87
  const digest = createHash('sha256').update(content).digest()
@@ -147,6 +147,6 @@ const isDirect =
147
147
  if (isDirect) {
148
148
  main().catch((err) => {
149
149
  console.error(err)
150
- process.exit(20)
150
+ process.exit(1)
151
151
  })
152
152
  }
@@ -249,7 +249,7 @@ function loadVerifyKeys(paths) {
249
249
 
250
250
  function loadReceipts(target) {
251
251
  if (!existsSync(target)) {
252
- return { error: `path not found: ${target}`, code: 20 }
252
+ return { error: `path not found: ${target}`, code: 2 }
253
253
  }
254
254
  const st = statSync(target)
255
255
  let files = []
@@ -734,6 +734,6 @@ const isDirect =
734
734
  if (isDirect) {
735
735
  main().catch((err) => {
736
736
  console.error(err)
737
- process.exit(20)
737
+ process.exit(1)
738
738
  })
739
739
  }
@@ -7,7 +7,8 @@ reference adapter; the suite does not import that product.
7
7
  A one-person team maintains both the suite and one implementation. That
8
8
  is stated here so nobody has to discover it later.
9
9
 
10
- Dokümandan implement edilemiyorsa spesifikasyon değil blog yazısıdır.
10
+ If it cannot be implemented from the document, it is not a specification;
11
+ it is a blog post.
11
12
 
12
13
  If a frozen case stops matching, do not edit the expectation so the
13
14
  suite goes green. Either the implementation changes, or the
@@ -9,7 +9,9 @@ re-signed when 0.4 fields appear.
9
9
  Implements the portable side of EU AI Act Articles 12 (logging) and 19 (content
10
10
  of logs) for Conarium's governed MCP gateway.
11
11
 
12
- Design source: `docs/superpowers/specs/2026-07-29-conarium-receipt-design.md`.
12
+ Design source: [`2026-07-29-conarium-receipt-design.md`](https://github.com/dogrucanemek-alt/conarium/blob/main/docs/superpowers/specs/2026-07-29-conarium-receipt-design.md),
13
+ in the repository only — it is written in Turkish and the npm package does not
14
+ carry it. This document is the normative one either way.
13
15
 
14
16
  ## Official claim (do not widen)
15
17
 
@@ -189,14 +191,15 @@ are unchanged.
189
191
  | Exit | Meaning |
190
192
  |---|---|
191
193
  | 0 | Chain intact, signatures valid |
192
- | 2 | Usage error — no receipt was read |
194
+ | 1 | The tool failed unexpectedly — no verdict was reached |
195
+ | 2 | The command could not be run as given — a flag that does not exist, a required argument that was not given, or a target that is not there. The artefact under test was never opened, so nothing is being judged. |
193
196
  | 10 | Hash mismatch — record altered |
194
197
  | 11 | `prevHash` break — deleted or inserted; also `--expect-count` / `--expect-last-hash` mismatch |
195
198
  | 12 | `seq` gap / non-increasing — missing or reordered |
196
199
  | 13 | Signature invalid / pubkey missing (fail-closed) |
197
200
  | 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. |
198
201
  | 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. |
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. |
202
+ | 20 | Schema invalid — a receipt was read and failed the schema |
200
203
 
201
204
  Fail-closed: if the verifier is unsure, it does not exit 0.
202
205
 
@@ -480,9 +483,11 @@ occurred"** — an absent record is ambiguous by nature.
480
483
  | Exit | Meaning |
481
484
  |---|---|
482
485
  | 0 | Declaration signature valid (+ consistent with receipts if given), chain contiguous. Unpinned window start is printed, not a silent complete. |
486
+ | 1 | The tool failed unexpectedly — no verdict was reached |
487
+ | 2 | The command could not be run as given — a flag that does not exist, a required argument that was not given, or a declaration or receipts file that is not there. The artefact under test was never opened, so nothing is being judged. |
483
488
  | 12 | Chain has gaps — coverage incomplete (`--allow-gaps` verifies authenticity only); also `--expect-seq-from` miss |
484
489
  | 13 | Signature invalid / pubkey missing (fail-closed); also a receipt Ed25519 failure under `--receipts` |
485
- | 20 | Schema invalid |
490
+ | 20 | Schema invalid — the declaration was read and failed the schema |
486
491
  | 30 | Inconsistent with the receipts file |
487
492
 
488
493
  ## Reconciliation (two-sided, v0.1)
@@ -552,7 +557,9 @@ Rules that keep the verdict honest:
552
557
  | Exit | Meaning |
553
558
  |---|---|
554
559
  | 0 | Every DB query pattern in the window is attributable to receipt(s) for the same table — object attribution, not per-statement coverage |
555
- | 20 | Input invalid or window unreliable (schema error, counter regression) |
560
+ | 1 | The tool failed unexpectedly — no verdict was reached |
561
+ | 2 | The command could not be run as given — a flag that does not exist, a required argument that was not given, or a snapshot, receipts file or profile that is not there. The artefact under test was never opened, so nothing is being judged. |
562
+ | 20 | Input was read and is invalid, or the window is unreliable (schema error, counter regression) |
556
563
  | 40 | Unreconciled DB activity — recorded by the database, not receipted |
557
564
  | 41 | Indeterminate — a pattern is uncovered only by the window boundary, and two clocks decide that boundary |
558
565
 
@@ -693,6 +700,8 @@ conarium-stamp <file> [--sidecar <path>] [--json]
693
700
  | Exit | Meaning |
694
701
  |---|---|
695
702
  | 0 | Stamped; sidecar written (`pending` until upgraded) |
703
+ | 1 | The tool failed unexpectedly — no verdict was reached |
704
+ | 2 | The command could not be run as given — a flag that does not exist, a required argument that was not given, or a target that is not there. The artefact under test was never opened, so nothing is being judged. |
696
705
  | 50 | Stamping failed — calendars unreachable or timed out |
697
706
 
698
707
  Receipts are not anchored by the write path. An operator stamps a document
@@ -723,7 +732,7 @@ revision history is itself timestamped.
723
732
  2. **`dataRefs[].fieldsRequested` and `policy.rulesApplied` are emitted empty.** Until 0.2.29 the first was filled from the masked-field list and the second from the set of SQL functions the query touched — in both cases a field whose name described something other than its contents. A reader takes `fieldsRequested` for the columns a query asked for, and `rulesApplied` for policy rule identifiers; neither was true, and both were signed. They are now empty, because in a signed document a field filled with the wrong thing is worse than a field left empty: empty says *unknown*, wrongly-filled says *known* and misleads. The correct contents are recoverable — selected columns from the SQL AST, rule identifiers from a policy engine that emits them — and neither is implemented; when it is, these fields carry it. **The conformance vectors under `test-vectors/` show both fields populated. Those vectors are hand-written to exercise the format and are not produced by this implementation; a populated value is valid, and an empty one is what this version emits.** Losing per-field masking detail from `dataRefs` is a regression and is stated here rather than absorbed silently — `masking.byClass` still carries the per-class counts.
724
733
  3. **Bypass detection — addressed as of reconcile v0.1, with stated limits.** Disabling Conarium and reading the DB directly still produces no receipt — no gateway can prevent that from inside. What changed: absence is now *checkable from both sides*. One-sided: `conarium-coverage` emits a signed declaration (chain contiguity + which declared objects have recorded access). Two-sided: `conarium-reconcile` compares the database's own per-role query counters against the in-window receipts and reports any DB-recorded pattern no receipt covers (see §Reconciliation). Remaining limits, stated: reconciliation trusts the DB's own counters (an attacker who can falsify `pg_stat_statements` is out of scope), requires a dedicated DB role per gateway instance, and matches per pattern/table — never per call count. **The language rule stands: "access NOT RECORDED", never "no access occurred."**
725
734
  4. **Creation-time truth is not proven.** Without hardware attestation, an operator can still write false-but-well-formed receipts *before* anchoring.
726
- 5. **In-file `sig` stripping + HMAC/`anchor` reduction.** Content `hash` is computed with `{hash, sig, anchor}` (and audit `signature`/`sig`) excluded, so an operator who controls the file can drop or thin those fields without invalidating the content hash itself. Contiguity and the trust store catch some boot-time cases, but full protection against in-file strip/reduce games is **not solvable in-file** (*in-file çözülemez*) — it needs an external transparency-log anchor and/or out-of-band key ceremony. **Opt-in strict boot (G3):** `CONARIUM_AUDIT_REQUIRE_SIG=1` rejects a chain with any unsigned line when a signing key is configured; the default stays the 08-05 compatibility open. **Mitigation available today, measured:** keep `CONARIUM_AUDIT_HMAC_KEY` enabled alongside Ed25519. HMAC is keyed, so an actor who strips `sig` and recomputes the unkeyed hashes still fails the HMAC check (`entry signature mismatch`). Verified by test: Ed25519 alone → strip-all passes the boot check; Ed25519 + HMAC → caught. `conarium-verify --pubkey` also catches it (exit 13, `missing sig`) because it is told to expect signatures. **Anchor client is available** (`conarium-stamp` / `conarium-anchor-service`; `CONARIUM_ANCHOR_SINK=opentimestamps` selects the calendars). Receipts start as `anchor: null`. After a stamp is submitted the sidecar is `pending` until Bitcoin finality (hours); see §Anchoring.
735
+ 5. **In-file `sig` stripping + HMAC/`anchor` reduction.** Content `hash` is computed with `{hash, sig, anchor}` (and audit `signature`/`sig`) excluded, so an operator who controls the file can drop or thin those fields without invalidating the content hash itself. Contiguity and the trust store catch some boot-time cases, but full protection against in-file strip/reduce games is **not solvable in-file** — it needs an external transparency-log anchor and/or out-of-band key ceremony. **Opt-in strict boot (G3):** `CONARIUM_AUDIT_REQUIRE_SIG=1` rejects a chain with any unsigned line when a signing key is configured; the default stays the 08-05 compatibility open. **Mitigation available today, measured:** keep `CONARIUM_AUDIT_HMAC_KEY` enabled alongside Ed25519. HMAC is keyed, so an actor who strips `sig` and recomputes the unkeyed hashes still fails the HMAC check (`entry signature mismatch`). Verified by test: Ed25519 alone → strip-all passes the boot check; Ed25519 + HMAC → caught. `conarium-verify --pubkey` also catches it (exit 13, `missing sig`) because it is told to expect signatures. **Anchor client is available** (`conarium-stamp` / `conarium-anchor-service`; `CONARIUM_ANCHOR_SINK=opentimestamps` selects the calendars). Receipts start as `anchor: null`. After a stamp is submitted the sidecar is `pending` until Bitcoin finality (hours); see §Anchoring.
727
736
  6. **`argsHash` hurts debugging.** Support cases need the customer's own logs to correlate.
728
737
  7. **Tail truncation is invisible to `conarium-verify` unless pinned.** Deleting the last N receipts leaves a consistent leftover chain (exit 0). `--expect-count` / `--expect-last-hash` exist for operators who have an external length or last-hash; they are opt-in so a verifier that saw the same file yesterday still exits 0 today. Anchoring the head, or `conarium-reconcile` against the database's own counters, are the other pins.
729
738
 
@@ -0,0 +1,7 @@
1
+ {
2
+ "lines": 34,
3
+ "files": 14,
4
+ "why": "bilingual limitation paragraphs, quoted product strings in the changelog, and a TURKPATENT citation",
5
+ "measuredBy": "test/pack_locale.mjs — union of the letter pass and the word pass over every path npm packs, excluding dist/bin/scripts/public and *.tr.md",
6
+ "rule": "A ceiling, not a target. Lower it whenever Turkish leaves the package. Raising it means a new Turkish file is shipping to strangers, which needs a reason written in the release note."
7
+ }
@@ -0,0 +1,75 @@
1
+ # Claims review — 0.2.43
2
+
3
+ - base: v0.2.42
4
+ - head: 392aadf
5
+ - surface: sha256:6cd0fa9075a09f70c75f3e5682d3454977f4a5c7025dbbe25540136aa6a89f40
6
+ - verdict: pass
7
+ - reviewer: maintainer. The release exists because a printed number was never
8
+ asked to agree with the tree, so every figure below was taken from the tree.
9
+
10
+ One surface changed: `docs/RECEIPT-SPEC.md`, twice. The "Design source" line at
11
+ the top was rewritten because the directory it pointed at left the package. A
12
+ Turkish parenthetical was deleted from limitation 5 — it restated in Turkish the
13
+ English words immediately beside it, "not solvable in-file", so nothing was
14
+ claimed or withdrawn. It is described rather than quoted here: the guard this
15
+ release fixes counts every packed document, and this file is one of them.
16
+
17
+ ## Findings
18
+
19
+ ### 1. docs/RECEIPT-SPEC.md:12 — "normative" is asserted where nothing compares the two documents
20
+
21
+ - Claim: "This document is the normative one either way."
22
+ - Mechanism: four checks read this file and measure it against the shipped
23
+ code — `spec_wire_contract.mjs`, `spec_jcs_class.mjs`,
24
+ `spec_exitcode_drift.mjs`, `implementation_status.mjs`. None of them, and
25
+ nothing else in the tree, reads the design document.
26
+ - Why it falls short: those checks establish that *this* document is held to the
27
+ code. They do not establish precedence, because precedence is only tested
28
+ where two documents disagree and nothing compares them. The design document
29
+ carries no marking on its own page saying it has been superseded, and it is
30
+ still in the repository, still dated, still readable — and now more likely to
31
+ be found on its own, since the sentence naming it links straight to it.
32
+ - Disposition: accepted, shipping. Dropping it from the package is the whole
33
+ remedy for the reader who arrived through `npm i`, which is the reader this
34
+ release is about. The repository reader is not covered. Marking the design
35
+ document would mean editing a dated record to keep a claim true, which is the
36
+ trade this project refuses elsewhere. Recorded rather than fixed.
37
+
38
+ ### 2. The pinned remainder measures the package, and will be read as measuring the project
39
+
40
+ - Claim: "34 Turkish line(s) across 14 packed doc file(s)" — the guard's line,
41
+ the pin in `docs/claims/locale-residue.json`, and the changelog paragraph.
42
+ - Mechanism: `docsRemainder` runs the letter pass and the word pass over the
43
+ output of `npm pack --dry-run`, so the figure is exactly the packed set.
44
+ - Why it falls short: the guard's own line says "packed", but the figure is
45
+ what gets copied out of it, and a figure copied out of a scope survives
46
+ without the scope. That is not a hypothetical — it is the defect this release
47
+ fixes. `324 / 22` was read as the size of the problem when it was the size of
48
+ what one probe could see, and it reached a handover note as `308 / 19`, a
49
+ number that reproduces under no definition at all. Measured, so the next
50
+ reader has both: the repository's tracked `.md`, `.txt` and `.json` carry
51
+ **1185 Turkish lines across 46 files**. The package carries 34 across 14.
52
+ - Disposition: accepted. `measuredBy` in the pin file now states the scope
53
+ beside the number rather than in a comment somewhere else, and the changelog
54
+ paragraph says "packed". The stronger remedy — a second pin over the whole
55
+ repository — is deliberately not taken: Turkish in a Turkish team's repository
56
+ is not a defect, and a guard that reports it every run is a guard that gets
57
+ switched off. The line that matters is the package boundary, and that is the
58
+ one now pinned.
59
+
60
+ ## Not a finding, recorded so the next reader does not re-derive it
61
+
62
+ The guard printed `N Turkish word occurrence(s)` for three releases while
63
+ counting **lines** — one hit per line, however many Turkish words that line
64
+ carried. The wording is corrected to `line(s)` here. It means the old figures
65
+ were further from an occurrence count than the 324-against-1034 gap alone
66
+ suggests, and that no comparison anyone made against them was measuring what
67
+ its own label said.
68
+
69
+ `test/pack_path_refs.mjs` is new and its first version was wrong in a way worth
70
+ writing down: it reported fifty-odd references to `src/` and `test/` paths as
71
+ broken, because it asked "is this path shipped?" instead of "is this path in a
72
+ directory the reader has reason to think is shipped?". `src/` and `test/` have
73
+ never been in the package; nobody is misled by a document that names them. The
74
+ check now derives the roots it polices from what npm actually packs, so it
75
+ covers `docs/` — which is half here — and leaves the wholly-absent roots alone.
@@ -0,0 +1,84 @@
1
+ # Claims review — 0.2.44
2
+
3
+ - base: v0.2.43
4
+ - head: 150f134
5
+ - surface: sha256:9383a93c1e38d7031c88b62995af3d03222a7f650c29d4f9f75180f9d42e3c14
6
+ - verdict: pass
7
+ - reviewer: maintainer, running the four binaries against the four tables. The
8
+ previous review of this defect was done by reading and missed half of it.
9
+
10
+ One surface changed: the four exit-code tables in `docs/RECEIPT-SPEC.md`. Two
11
+ rows added to each, three rows reworded to say what was read before a verdict
12
+ was given.
13
+
14
+ ## Findings
15
+
16
+ ### 1. docs/RECEIPT-SPEC.md — exit 1 is published on four tables and observed on none
17
+
18
+ - Claim: "| 1 | The tool failed unexpectedly — no verdict was reached |", now in
19
+ the verifier, coverage, reconciliation and stamping tables.
20
+ - Mechanism: `process.exit(1)` in the `main().catch` handler at the foot of each
21
+ of the four binaries, replacing `process.exit(20)`.
22
+ - Why it falls short: no CLI input reaches that handler. Four candidate triggers
23
+ were tried against `conarium-verify` — a directory passed to `--anchors`,
24
+ `/dev/null` passed to `--anchors`, a non-numeric `--expect-count`, a malformed
25
+ `--expect-last-hash` — and every one was caught by the code that owns it and
26
+ answered with its own exit code. That is the right result for a last-resort
27
+ handler and it is also the reason the row is unmeasured: `exit_contract.mjs`
28
+ runs twenty-one invocations and none of them produces a 1. The evidence for
29
+ this row is that the line is short and reads correctly. **That is reading
30
+ substituted for running, which is the substitution this release exists to
31
+ correct** — 0.2.42 named the remaining misuse of 20 by reading the file, and
32
+ the half it missed was found by executing it.
33
+ - Disposition: shipping, and said plainly rather than left to look measured. The
34
+ changelog states that this one line is covered by reading rather than by a
35
+ run. The alternative — an environment variable or hidden flag that forces a
36
+ throw so a test can observe it — puts a deliberate crash path into a security
37
+ tool to satisfy a checkbox, and that trade is worse than the gap.
38
+ - Second-order, recorded because it is the more useful half: **the drift guard
39
+ went green through all of this.** `test/spec_exitcode_drift.mjs` compares the
40
+ *set* of literal codes in the binaries against the set in the tables. `1` was
41
+ added on both sides, so the sets matched. It was equally blind when `20` named
42
+ two different events, which is how that survived to 0.2.42. A set comparison
43
+ cannot see meaning, and nothing in the tree can — `exit_contract.mjs` narrows
44
+ the gap by asserting what specific invocations return, but it asserts the
45
+ cases someone thought of.
46
+
47
+ ### 2. docs/RECEIPT-SPEC.md — "Nothing was read" was read as literally as it was written
48
+
49
+ - Claim, as first written in this release: "| 2 | The command could not be run
50
+ as given — … Nothing was read, so nothing is being judged. |"
51
+ - Mechanism: the paths that now exit 2 are a `parseArgs` throw, a missing
52
+ required argument, and a target that is absent or unreadable.
53
+ - Why it falls short: on several of those paths a file *has* been read. In
54
+ `conarium-verify` and `conarium-coverage` the public key is loaded before the
55
+ target is looked for, so `conarium-verify <missing> --pubkey <key>` opens and
56
+ parses a key file and then exits 2. In `conarium-stamp` the "cannot read"
57
+ branch has opened the target and failed partway. What is true — and what the
58
+ code actually establishes — is narrower: the artefact under test was never
59
+ opened. "Nothing" claimed the whole filesystem.
60
+ - Disposition: reworded in `150f134`, in all four tables. The row now says "The
61
+ artefact under test was never opened".
62
+
63
+ ## Not a finding, recorded so the next reader does not re-derive it
64
+
65
+ **`conarium-coverage <missing declaration>` with no `--pubkey` is 13, and 13 is
66
+ a verdict code.** `loadVerifyKeys` runs before the declaration path is checked,
67
+ so a file that does not exist is answered with *signature invalid / pubkey
68
+ missing*. It is the same shape as the defect this release fixes, one argument
69
+ over, and `exit_contract.mjs` asserts it deliberately rather than by omission.
70
+
71
+ It stays for the reason 0.2.42 gave for the verifier: 13 is fail-closed. A
72
+ caller that has special-cased it is asserting *do not trust this result*, and
73
+ moving a missing key to 2 would switch that assertion off in the name of a
74
+ tidier table. The ordering is the fixable part — checking the target before the
75
+ key would answer the more specific question first — and it is not fixed here,
76
+ because reordering the fail-closed check is a change to the safety posture and
77
+ belongs in a release that is about the safety posture.
78
+
79
+ **Three tests had written the old answer down.** `test/reconcile_cli.test.mjs`
80
+ asserted 20 for an unparseable `--skew`, for no arguments at all, and for
81
+ `--json --json-v2` together. All three are `parseArgs` throws — no snapshot is
82
+ opened in any of them — so all three were asserting the defect. Their
83
+ expectations moved to 2 with the reason written beside each one, rather than in
84
+ a commit message nobody reads at the line where the question comes up.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@conarium-ai/core",
3
- "version": "0.2.42",
3
+ "version": "0.2.44",
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.",
@@ -12,6 +12,14 @@
12
12
  "!docs/reviews",
13
13
  "!docs/teaching",
14
14
  "!docs/teaching/**",
15
+ "!docs/superpowers",
16
+ "!docs/superpowers/**",
17
+ "!docs/plans",
18
+ "!docs/plans/**",
19
+ "!docs/specs",
20
+ "!docs/specs/**",
21
+ "!docs/audit",
22
+ "!docs/audit/**",
15
23
  "!docs/benchmarks/*.cpuprofile",
16
24
  "public",
17
25
  "assets",
@@ -184,12 +184,13 @@ 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
+ 1: 'the tool failed unexpectedly — no verdict was reached',
188
+ 2: 'the command could not be run as given — nothing was read',
188
189
  10: 'hash mismatch — record altered',
189
190
  11: 'prevHash break — deleted or inserted',
190
191
  12: 'seq gap / non-increasing',
191
192
  13: 'signature invalid or missing while a pubkey was supplied',
192
- 20: 'schema invalid',
193
+ 20: 'schema invalid — a receipt was read and failed the schema',
193
194
  },
194
195
  cases,
195
196
  },
@@ -6,12 +6,13 @@
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
+ "1": "the tool failed unexpectedly — no verdict was reached",
10
+ "2": "the command could not be run as given — nothing was read",
10
11
  "10": "hash mismatch — record altered",
11
12
  "11": "prevHash break — deleted or inserted",
12
13
  "12": "seq gap / non-increasing",
13
14
  "13": "signature invalid or missing while a pubkey was supplied",
14
- "20": "schema invalid"
15
+ "20": "schema invalid — a receipt was read and failed the schema"
15
16
  },
16
17
  "cases": [
17
18
  {
@@ -1,69 +0,0 @@
1
- # E2E health — 2026-08-14
2
-
3
- O2. No refactor. Push / npm / Hetzner yok.
4
-
5
- ## a) Regresyon — temiz
6
-
7
- | Komut | Sonuç |
8
- |--|--|
9
- | `vitest run` | **483 geçti / 1 skip** (console-shortcut) |
10
- | `npm run test:checks` | **28/28** |
11
-
12
- Postgres `Governance.guardQuery` hâlâ `pgsql-ast-parser` + `sql-gate/rules` + `sql-gate/postgres`. MSSQL/Oracle ayrı fonksiyon; o yol değişmedi.
13
-
14
- ## b) Performans — temiz (karşılaştırma notu)
15
-
16
- `docs/BENCHMARK.md` alıntısı: same-limit partial, maxRows=100, ~**5 ms** (linux 2026-08-14T13:46Z: p50 **5.006** / p95 6.730 / p99 7.099).
17
-
18
- Bu tur: `docs/benchmarks/overhead-20260814T1644Z-win32.json` (Windows Node → Docker Postgres 16).
19
-
20
- | | eski p50 (linux) | yeni p50 (win32) |
21
- |--|--|--|
22
- | same-limit allow 100 | 2.850 ms | 1.992 ms |
23
- | same-limit partial 100 | **5.006 ms** | **3.158 ms** |
24
- | in-process guard allow | (yok / ayrı) | 0.359 ms |
25
-
26
- Ortak katman ayrımı guard yoluna ölçülebilir ek vergi koymadı. OS farklı; “ürün hızlandı” iddiası yok. 5 000 satır maskeli hâlâ saniye mertebesi (eski ~22 s linux / yeni ~7 s win32) — bilinen maliyet, yeni tıkanma değil.
27
-
28
- ## c) Uçtan uca zincir — temiz (kısmi bakılamadı)
29
-
30
- | Halka | Kanıt | Durum |
31
- |--|--|--|
32
- | sorgu → kapı | `governance.rowcap.test.ts`, `vectors.test.ts` postgres 28/28, `src/server.ts` `governance.guardQuery` | temiz |
33
- | maskeleme | `governance.masking.test.ts`, `http_gateway.e2e.mjs` search → `[MASKED_PII]`, email sızmıyor | temiz |
34
- | makbuz | `audit.receipt.test.ts`, e2e receipts 0→1 | temiz |
35
- | zincir | `audit.chain.test.ts` | temiz |
36
- | `conarium-verify` | e2e `verify exit 0` + `/verified/` | temiz |
37
- | panel | `console_receipts_tab.mjs` + `/api/receipts` (`console.ts`) | temiz (DOM sözleşmesi) |
38
-
39
- **Bakılamadı:** tarayıcıda, aynı süreçte üretilmiş bir makbuzun panele tıklanması. HTTP e2e SQL `query` aracını değil `search` (docs) yolunu koşuyor. MSSQL/Oracle’ın MCP `query` üzerinden seçilmesi — konnektör yok.
40
-
41
- ## d) Ölü kod / çift kaynak — bulgu
42
-
43
- | Bulgu | Kanıt | Etki | Öneri | Aciliyet |
44
- |--|--|--|--|--|
45
- | MCP `query` yalnız Postgres kapısı | `src/server.ts` `governance.guardQuery`; `console.ts` aynı. `guardMssqlQuery` / `guardOracleQuery` yalnız test + live betik | Beyan “SQL kapısı Oracle/MSSQL” doğru; **dağıtılan araç T-SQL/Oracle SQL’i Postgres parser’a verir** (fail-closed veya yanlış AST) | Lehçe seçimi ayrı karar. LIMITATIONS’a yazıldı | yüksek (iddia/yol) |
46
- | `matchGlob` üç kopya | `governance.ts` `match`, `mssql.ts`, `oracle.ts` | Kural sapması riski | Tek fonksiyon | düşük |
47
- | `*Adapter.inspect` sunucuda kullanılmıyor | yalnız `*.test.ts` | Ölü yüzey, zarar yok | Bırak veya bağla | düşük |
48
-
49
- ## e) `conarium-doctor` — bulgu
50
-
51
- `node bin/conarium-doctor.mjs --no-net` (repo `conarium.config.json`):
52
-
53
- - `maxRows: 50` eşik altı (100) → **uyarı yok** (doğru; eşiği görüyor).
54
- - Lehçe (MSSQL/Oracle) **yok**.
55
- - Özel PII deseni **yok** (config’de de yok).
56
- - FAIL: `DATABASE_READONLY_DSN` set değil — beklenen boş kurulum.
57
- - WARN: imza anahtarı yok.
58
-
59
- Yeni lehçeler doctorda sessiz.
60
-
61
- ## f) Paket bütünlüğü — temiz (not)
62
-
63
- `npm pack --dry-run`: `dist/sql-gate/{mssql,oracle,postgres,rules,types}.js` + `test-vectors/sql-gate/vectors.json` + `LIMITATIONS.md` var. Live betikler (`test/sql-gate-*-live.mjs`) pakette yok (doğru). `docs/audit/2026-08-14-*.md` tarball’a giriyor — müşteri verisi değil, gürültü.
64
-
65
- ## Bakılamayan
66
-
67
- - Canlı panel tıklaması (yukarı).
68
- - MSSQL/Oracle MCP `query` (konnektör yok).
69
- - `test:checks` 28; paket metni bazen “27” demişti — sayı 28, drift değil bu turda.