@conarium-ai/core 0.2.26 → 0.2.27

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,38 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.27 — 2026-08-17
4
+
5
+ `conarium-reconcile` could accuse the gateway of being bypassed because two
6
+ clocks disagreed by three seconds. Raised by Walter Hawkins on the IETF SCITT
7
+ list against `bin/conarium-reconcile.mjs` on main, and reproduced before it was
8
+ changed.
9
+
10
+ - **The window straddles two clocks, and the comparison was exact.** The window
11
+ is `[before.ts, after.ts]`, both from the database; a receipt's `ts` comes from
12
+ the gateway. A receipt three seconds early was counted `outOfWindow`, the table
13
+ it covered landed in `uncovered`, and the run exited 40 with "the gateway may
14
+ have been bypassed". The failure is asymmetric: skew manufactures the
15
+ accusation rather than any real gap, and the sub-second version is the
16
+ dangerous one, because it is believed.
17
+
18
+ - **The missing piece was qualification, not observation.** The tool already
19
+ counted those receipts; nothing asked how far outside they were, so a receipt
20
+ three seconds early and one six hours early produced the same verdict. A
21
+ pattern whose uncovered tables all have a receipt just outside the boundary is
22
+ now `indeterminate`, exit **41**, and the report names the skew that would have
23
+ to be true for it. 41 is a failure, not a pass — what it is not is an
24
+ accusation.
25
+
26
+ - **`--skew <duration>` declares the bound** (`500ms`, `5s`, `2m`, `1h`). Beyond
27
+ it, a receipt is not skew and its pattern stays unreconciled at 40. Without it
28
+ nothing decides the question, so nothing is asserted. An unreadable duration is
29
+ an error rather than a default: a tolerance nobody chose is the kind of number
30
+ this tool exists to refuse.
31
+
32
+ - **A real gap stays a real gap.** If even one uncovered table has no receipt
33
+ anywhere, the pattern remains unreconciled. A genuine finding is not made
34
+ indeterminate by a neighbour's clock.
35
+
3
36
  ## 0.2.26 — 2026-08-17
4
37
 
5
38
  The claim list that `test/claim_discipline.mjs` enforces now ships in the
@@ -48,6 +48,33 @@
48
48
  * counter regression — e.g. pg_stat_statements was reset mid-window)
49
49
  * 40 unreconciled DB activity: at least one pattern the DB recorded has no
50
50
  * covering receipt in the window (or could not be attributed to a table)
51
+ * 41 indeterminate: the only thing standing between a pattern and its
52
+ * receipt is the window boundary, and two clocks decide that boundary
53
+ *
54
+ * Two clocks, one window:
55
+ * The window is [before.ts, after.ts] and both come from the database. A
56
+ * receipt's ts comes from the gateway. Admitting a receipt on an exact
57
+ * comparison across those two clocks makes the failure asymmetric: a gateway
58
+ * trailing the database turns a receipt that genuinely covers a table into an
59
+ * out-of-window receipt, the table into an uncovered one, and the run into an
60
+ * accusation of bypass. Skew then manufactures the accusation rather than any
61
+ * real gap — and the sub-second version of that is the dangerous one, because
62
+ * it is believed.
63
+ *
64
+ * This tool already counted those receipts (`outOfWindow`). What was missing
65
+ * was not the observation but its qualification: how far outside, and against
66
+ * what declared bound. A pattern that is uncovered ONLY because a receipt sat
67
+ * outside the boundary is now indeterminate, not an accusation, and the
68
+ * report names the skew that would have to be true for it to be one.
69
+ *
70
+ * `--skew` declares the bound. Without it nothing decides the question, so
71
+ * nothing is asserted: the pattern is indeterminate and the report says the
72
+ * bound was never declared. With it, a receipt further out than the bound is
73
+ * not skew, and the pattern stays unreconciled.
74
+ *
75
+ * Reported for the operator, not resolved for them: this tool cannot tell a
76
+ * trailing clock from a receipt written late. That is why the class is
77
+ * "indeterminate" and not "covered".
51
78
  */
52
79
  import { readFileSync, existsSync } from 'fs'
53
80
 
@@ -224,6 +251,33 @@ export function receiptCoverage(receipts, fromMs, toMs) {
224
251
  return { covered, coveredRaw, inWindow, outOfWindow, unassigned }
225
252
  }
226
253
 
254
+ /**
255
+ * For every table named by a receipt that fell OUTSIDE the window, the smallest
256
+ * distance from that receipt to the nearest window boundary.
257
+ *
258
+ * This is the qualification the tool was missing. `outOfWindow` counted these
259
+ * receipts; nothing asked how far outside they were, so a receipt three seconds
260
+ * early and one six hours early produced the same verdict.
261
+ */
262
+ export function outsideBoundaryCoverage(receipts, fromMs, toMs) {
263
+ const byTable = new Map() // normalized table -> smallest offset in ms
264
+ for (const r of receipts) {
265
+ const t = Date.parse(r.ts)
266
+ if (Number.isNaN(t)) continue
267
+ if (t >= fromMs && t <= toMs) continue
268
+ const offset = t < fromMs ? fromMs - t : t - toMs
269
+ const named = []
270
+ for (const ref of r.dataRefs || []) if (ref.object) named.push(String(ref.object))
271
+ if (r.request?.tool === 'describe_table' && r.request?.target) named.push(String(r.request.target))
272
+ for (const obj of named) {
273
+ const key = normalizeObject(obj)
274
+ const prev = byTable.get(key)
275
+ if (prev === undefined || offset < prev) byTable.set(key, offset)
276
+ }
277
+ }
278
+ return byTable
279
+ }
280
+
227
281
  /**
228
282
  * Receipts in the window that name an object the database counters did not
229
283
  * increment. Distinct from `unassigned` (receipt named nothing).
@@ -259,7 +313,11 @@ export function unobservedReceipts(receipts, fromMs, toMs, observedTables) {
259
313
 
260
314
  // ─── reconciliation core ─────────────────────────────────────────────────────
261
315
 
262
- export function reconcile(before, after, receipts) {
316
+ export function reconcile(before, after, receipts, opts = {}) {
317
+ const declaredSkewMs =
318
+ typeof opts.skewMs === 'number' && Number.isFinite(opts.skewMs) && opts.skewMs >= 0
319
+ ? opts.skewMs
320
+ : null
263
321
  if (before.role !== after.role) {
264
322
  return { error: `role mismatch: before=${before.role}, after=${after.role}` }
265
323
  }
@@ -301,8 +359,11 @@ export function reconcile(before, after, receipts) {
301
359
 
302
360
  const cov = receiptCoverage(receipts, fromMs, toMs)
303
361
 
362
+ const outside = outsideBoundaryCoverage(receipts, fromMs, toMs)
363
+
304
364
  const reconciled = []
305
365
  const unreconciled = []
366
+ const indeterminate = []
306
367
  const unattributed = []
307
368
  const infrastructure = []
308
369
  for (const d of deltas) {
@@ -318,8 +379,23 @@ export function reconcile(before, after, receipts) {
318
379
  const uncovered = cls.tables.filter((t) => !cov.covered.has(t.table))
319
380
  if (uncovered.length === 0) {
320
381
  reconciled.push({ ...d, tables: cls.tables.map((t) => t.table) })
382
+ continue
383
+ }
384
+ const names = uncovered.map((t) => (t.schema ? `${t.schema}.${t.table}` : t.table))
385
+
386
+ // A pattern moves out of the accusation only if the boundary is the ONLY
387
+ // thing missing: every uncovered table must have a receipt just outside.
388
+ // One table with no receipt anywhere is a real gap, and a real gap is not
389
+ // made indeterminate by a neighbour's clock.
390
+ const offsets = uncovered.map((t) => outside.get(t.table))
391
+ const allExplained = offsets.every((o) => o !== undefined)
392
+ const requiredSkewMs = allExplained ? Math.max(...offsets) : null
393
+ const withinDeclared = declaredSkewMs === null || requiredSkewMs <= declaredSkewMs
394
+
395
+ if (allExplained && withinDeclared) {
396
+ indeterminate.push({ ...d, uncoveredTables: names, requiredSkewMs })
321
397
  } else {
322
- unreconciled.push({ ...d, uncoveredTables: uncovered.map((t) => (t.schema ? `${t.schema}.${t.table}` : t.table)) })
398
+ unreconciled.push({ ...d, uncoveredTables: names })
323
399
  }
324
400
  }
325
401
 
@@ -343,8 +419,14 @@ export function reconcile(before, after, receipts) {
343
419
  unassigned: cov.unassigned,
344
420
  coveredObjects: [...cov.coveredRaw].sort(),
345
421
  },
422
+ clocks: {
423
+ window: before.source,
424
+ receipts: 'gateway',
425
+ declaredSkewMs,
426
+ },
346
427
  reconciled,
347
428
  unreconciled,
429
+ indeterminate,
348
430
  unattributed,
349
431
  infrastructure,
350
432
  unobserved,
@@ -356,12 +438,35 @@ export function reconcile(before, after, receipts) {
356
438
  function usage(msg) {
357
439
  if (msg) console.error(msg)
358
440
  console.error(
359
- 'Usage: conarium-reconcile --before <snapshot.json> --after <snapshot.json> --receipts <receipts.jsonl> [--json]',
441
+ 'Usage: conarium-reconcile --before <snapshot.json> --after <snapshot.json> --receipts <receipts.jsonl> [--skew <duration>] [--json]',
442
+ )
443
+ console.error(
444
+ ' --skew how far the gateway clock may differ from the database clock (e.g. 500ms, 5s, 2m).',
445
+ )
446
+ console.error(
447
+ ' Receipts further outside the window than this are not skew. Without it, a pattern',
448
+ )
449
+ console.error(
450
+ ' uncovered only by the boundary is reported as indeterminate rather than decided.',
360
451
  )
361
452
  }
362
453
 
454
+ /**
455
+ * `500ms`, `5s`, `2m`, `1h`, or a bare number of milliseconds. Declaring the
456
+ * bound is the point, so an unparseable one is an error rather than a default:
457
+ * a tolerance nobody chose is the kind of number this tool exists to refuse.
458
+ */
459
+ export function parseDuration(text) {
460
+ const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(String(text).trim())
461
+ if (!m) return null
462
+ const n = Number(m[1])
463
+ const unit = m[2] || 'ms'
464
+ const scale = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[unit]
465
+ return Math.round(n * scale)
466
+ }
467
+
363
468
  function parseArgs(argv) {
364
- const out = { before: null, after: null, receiptsPath: null, json: false }
469
+ const out = { before: null, after: null, receiptsPath: null, json: false, skewMs: null }
365
470
  const args = [...argv]
366
471
  while (args.length) {
367
472
  const a = args.shift()
@@ -374,6 +479,12 @@ function parseArgs(argv) {
374
479
  } else if (a === '--receipts') {
375
480
  out.receiptsPath = args.shift() ?? null
376
481
  if (!out.receiptsPath) throw new Error('--receipts requires a path')
482
+ } else if (a === '--skew') {
483
+ const raw = args.shift() ?? null
484
+ if (!raw) throw new Error('--skew requires a duration (e.g. 500ms, 5s, 2m)')
485
+ const ms = parseDuration(raw)
486
+ if (ms === null) throw new Error(`--skew: cannot read "${raw}" as a duration (try 500ms, 5s, 2m, 1h)`)
487
+ out.skewMs = ms
377
488
  } else if (a === '--json') {
378
489
  out.json = true
379
490
  } else if (a === '--help' || a === '-h') {
@@ -417,13 +528,15 @@ async function main(argv = process.argv.slice(2)) {
417
528
  const rec = loadReceipts(opts.receiptsPath)
418
529
  if (rec.error) fail(20, rec.error, opts.json)
419
530
 
420
- const result = reconcile(b.snapshot, a.snapshot, rec.receipts)
531
+ const result = reconcile(b.snapshot, a.snapshot, rec.receipts, { skewMs: opts.skewMs })
421
532
  if (result.error) fail(20, result.error, opts.json)
422
533
 
423
534
  const problems = result.unreconciled.length + result.unattributed.length
535
+ const undecided = result.indeterminate.length
536
+ const exitCode = problems > 0 ? 40 : undecided > 0 ? 41 : 0
424
537
 
425
538
  if (opts.json) {
426
- console.log(JSON.stringify({ ok: problems === 0, code: problems === 0 ? 0 : 40, ...result }))
539
+ console.log(JSON.stringify({ ok: exitCode === 0, code: exitCode, ...result }))
427
540
  } else {
428
541
  console.log(
429
542
  `reconcile window: ${result.window.start} → ${result.window.end} ` +
@@ -458,13 +571,38 @@ async function main(argv = process.argv.slice(2)) {
458
571
  console.log(` · [${u.objects.join(', ')}] ${u.tool || 'receipt'} @ ${u.ts}`)
459
572
  }
460
573
  }
461
- if (problems === 0) {
574
+ if (result.indeterminate.length > 0) {
575
+ const bound =
576
+ result.clocks.declaredSkewMs === null
577
+ ? 'no --skew bound was declared, so nothing here decides the question'
578
+ : `declared --skew is ${result.clocks.declaredSkewMs}ms`
579
+ console.error(
580
+ `INDETERMINATE: ${result.indeterminate.length} pattern(s) are uncovered only by the window boundary — ` +
581
+ `${bound}:`,
582
+ )
583
+ for (const d of result.indeterminate) {
584
+ console.error(
585
+ ` ~ (+${d.delta}) table(s) [${d.uncoveredTables.join(', ')}] have a receipt ${d.requiredSkewMs}ms outside ` +
586
+ `the window: ${truncate(d.query)}`,
587
+ )
588
+ }
589
+ console.error(
590
+ `the window comes from ${result.clocks.window} and receipt timestamps come from the ${result.clocks.receipts} — ` +
591
+ 'two clocks. A receipt this far outside is either a trailing clock or a late receipt, and this tool cannot ' +
592
+ 'tell them apart. It is NOT reported as unreceipted access.',
593
+ )
594
+ }
595
+ if (problems === 0 && undecided === 0) {
462
596
  console.log('ok: every DB query pattern in the window is attributable to receipt(s) for the same table')
463
597
  console.log(
464
598
  'scope: this is object attribution within the window, not per-statement coverage — ' +
465
599
  'one receipt naming a table clears further statements against that table. See LIMITATIONS.md.',
466
600
  )
467
- } else {
601
+ }
602
+ // Guarded on `problems`, not on "not clean": a run whose only finding is
603
+ // indeterminate must never print the bypass sentence. Reaching that
604
+ // sentence through a clock difference is the defect this class exists for.
605
+ if (problems > 0) {
468
606
  if (result.unreconciled.length > 0) {
469
607
  console.error(
470
608
  `UNRECONCILED: ${result.unreconciled.length} pattern(s) recorded by the database have no covering receipt in the window:`,
@@ -487,10 +625,13 @@ async function main(argv = process.argv.slice(2)) {
487
625
  }
488
626
  // Literal çıkışlar bilerek ayrı: spec_exitcode_drift bekçisi sadece
489
627
  // literal sayıları tarar, ternary içindeki kod görünmez kalırdı.
490
- if (problems === 0) {
491
- process.exit(0)
628
+ if (problems > 0) {
629
+ process.exit(40)
630
+ }
631
+ if (undecided > 0) {
632
+ process.exit(41)
492
633
  }
493
- process.exit(40)
634
+ process.exit(0)
494
635
  }
495
636
 
496
637
  const isDirect =
@@ -65,7 +65,7 @@ No dates. Shipping 1.0 is a decision, not a document.
65
65
  | `conarium-doctor` | `--config` `--no-net` `--help` | experimental |
66
66
  | `conarium-verify` | `--pubkey` (repeatable) `--anchor-check` `--require-head-anchor` `--anchors` `--expect-seq-from` `--expect-count` `--expect-last-hash` `--strict` `--json` `--help` | **candidate** (exit codes + flags in RECEIPT-SPEC) |
67
67
  | `conarium-coverage` | `--pubkey` `--receipts` `--expect-seq-from` `--allow-gaps` `--json` `--help` | experimental |
68
- | `conarium-reconcile` | `--before` `--after` `--receipts` `--json` `--help` | experimental |
68
+ | `conarium-reconcile` | `--before` `--after` `--receipts` `--skew` `--json` `--help` | experimental |
69
69
  | `conarium-stamp` | `--sidecar` `--json` `--help` | experimental |
70
70
  | `conarium-anchor-upgrade` | `<anchors.jsonl>` | experimental |
71
71
  | `conarium-console` | `--config` `--port` `--host` `--install-shortcut` `--uninstall-shortcut` `--launch` `--help` | experimental |
@@ -319,6 +319,46 @@ Rules that keep the verdict honest:
319
319
  | 0 | Every DB query pattern in the window is attributable to receipt(s) for the same table — object attribution, not per-statement coverage |
320
320
  | 20 | Input invalid or window unreliable (schema error, counter regression) |
321
321
  | 40 | Unreconciled DB activity — recorded by the database, not receipted |
322
+ | 41 | Indeterminate — a pattern is uncovered only by the window boundary, and two clocks decide that boundary |
323
+
324
+ ### The window straddles two clocks
325
+
326
+ The window is `[before.ts, after.ts]` and both timestamps come from the database.
327
+ A receipt's `ts` comes from the gateway. Admitting receipts on an exact comparison
328
+ across those two clocks makes the failure **asymmetric**: a gateway trailing the
329
+ database turns a receipt that genuinely covers a table into an out-of-window
330
+ receipt, and the table into an accusation of bypass. Skew then manufactures the
331
+ accusation rather than any real gap, and the sub-second version is the dangerous
332
+ one, because it is believed.
333
+
334
+ A pattern whose uncovered tables **all** have a receipt outside the window is
335
+ reported as `indeterminate` and exits 41. It is not a pass — 41 is a failure —
336
+ but it is not the bypass sentence either, because this tool cannot tell a trailing
337
+ clock from a late receipt.
338
+
339
+ **Distance is reported, not judged, until you declare a bound.** Without `--skew`
340
+ there is no number that makes one offset skew and another not, so *any* covering
341
+ receipt outside the window puts its pattern here — three milliseconds out and six
342
+ hours out both land at 41, and the report prints which one it is. Reading that
343
+ number is the operator's job in the default mode; `--skew` is how you hand the
344
+ judgement to the tool:
345
+
346
+ ```
347
+ INDETERMINATE: 1 pattern(s) are uncovered only by the window boundary — no --skew bound was declared…
348
+ ~ (+5) table(s) [public.customers] have a receipt 3000ms outside the window: SELECT …
349
+ ```
350
+
351
+ `--skew <duration>` declares the bound (`500ms`, `5s`, `2m`, `1h`). A receipt
352
+ further out than the bound is not skew, and its pattern goes back to unreconciled
353
+ at 40 with the bypass sentence. An unreadable duration is an error, not a default:
354
+ a tolerance nobody chose is the kind of number this tool exists to refuse.
355
+
356
+ A pattern with even one table that has no receipt anywhere is a real gap and stays
357
+ at 40 in either mode: a genuine finding is not made indeterminate by a neighbour's
358
+ clock.
359
+
360
+ Credit: raised by Walter Hawkins on the IETF SCITT list, 2026-08-17, against
361
+ `bin/conarium-reconcile.mjs` on main.
322
362
 
323
363
  ## Stamping a document (priority dates)
324
364
 
@@ -0,0 +1,22 @@
1
+ # Claims review — 0.2.27
2
+
3
+ - base: v0.2.26
4
+ - head: cb4d2ee
5
+ - surface: sha256:0968a0b4fdbed3966bd1d7afd4490495fc2efef68056a69e8530ff6e26bf459b
6
+ - verdict: pass
7
+ - reviewer: Claude (release review before publish)
8
+
9
+ Two claim surfaces changed: `docs/RECEIPT-SPEC.md` gained the exit-41 row and a
10
+ section describing it, and `docs/API-STABILITY.md` gained `--skew` in the
11
+ `conarium-reconcile` flag list. The flag list matches the parser. The finding is
12
+ in the new section, and it is the same shape as the defect the release fixes:
13
+ prose implying a limit the mechanism does not enforce.
14
+
15
+ ## Findings
16
+
17
+ ### 1. docs/RECEIPT-SPEC.md — "a receipt just outside the boundary" described a proximity the default mode does not enforce
18
+
19
+ - Claim: "A pattern whose uncovered tables **all** have a receipt just outside the boundary is reported as `indeterminate` and exits 41", followed by "Without the flag nothing decides the question, so nothing is asserted."
20
+ - Mechanism: `reconcile()` moves a pattern to `indeterminate` when every uncovered table appears in `outsideBoundaryCoverage()` and, if `--skew` was given, the largest offset is within it. When `--skew` is absent there is no bound at all, so the offset is recorded and never compared.
21
+ - Why it falls short: without a declared bound there is no "just". Measured on the CLI against the same fixture, a receipt six hours outside the window produces `21600000ms outside` and exit 41, exactly as a three-second one produces `3000ms outside` and exit 41. A reader would take the sentence to mean a distant receipt still yields 40, and it does not. The second sentence has the opposite error, claiming less than the tool does: it does classify, into a weaker class.
22
+ - Disposition: reworded in `cb4d2ee`. The section now says distance is reported and not judged until a bound is declared, that any covering receipt outside the window lands at 41 in the default mode, and that reading the number is the operator's job there.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@conarium-ai/core",
3
- "version": "0.2.26",
3
+ "version": "0.2.27",
4
4
  "mcpName": "io.github.dogrucanemek-alt/conarium",
5
5
  "//files-artefakt": "examples/ altindaki uretilmis dosyalar (ozel anahtar, makbuz/denetim JSONL) ELENIR. .gitignore npm'i baglamaz: izin listesinde 'examples' oldugu icin demoyu kosturmus bir makinede 'npm publish' _keys/audit-ed25519.pem'i (OZEL ANAHTAR) ve makbuzlari yayinliyordu. test/pack_artefakt.mjs bunu kilitler. Elemeler examples/ ile SINIRLI: test-vectors/ altindaki receipts.jsonl ve .pub.pem YAYINLANMAK ZORUNDA, yoksa ucuncu taraf konformans vektorlerini kosturamaz.",
6
6
  "//files": "Pakete NE gireceginin izin listesi. Liste olmadan npm her seyi gonderiyordu: 296 dosya / 1.5 MB — CI workflowlari, gitleaks ayari, 137 KB pazarlama gorseli, sitenin api/chat.js dosyasi. Bir bankanin guvenlik ekibi tarball'i acip bunlari gorur. scripts/ BILEREK var: conarium-reconcile calisirken scripts/pg-snapshot.sql'e atif yapiyor, olmazsa kullanici destek maili yazar.",