@conarium-ai/core 0.2.36 → 0.2.37

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.
Files changed (39) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/LIMITATIONS.md +32 -3
  3. package/LIMITATIONS.tr.md +67 -2
  4. package/README.md +5 -2
  5. package/bin/conarium-reconcile.mjs +297 -13
  6. package/bin/conarium-stamp.mjs +2 -2
  7. package/conformance/cases/reconciliation/v2-clocks-declared.json +16 -0
  8. package/conformance/cases/reconciliation/v2-clocks-undeclared-profile.json +16 -0
  9. package/conformance/cases/reconciliation/v2-excluded.json +16 -0
  10. package/conformance/cases/reconciliation/v2-indeterminate.json +14 -0
  11. package/conformance/cases/reconciliation/v2-matched.json +16 -0
  12. package/conformance/cases/reconciliation/v2-neg-unattributed.json +15 -0
  13. package/conformance/cases/reconciliation/v2-neg-undeclared-exclusion.json +16 -0
  14. package/conformance/cases/reconciliation/v2-neg-undeclared-multiplicity.json +16 -0
  15. package/conformance/cases/reconciliation/v2-neg-undeclared-skew.json +15 -0
  16. package/conformance/cases/reconciliation/v2-observed-without-receipt.json +14 -0
  17. package/conformance/cases/reconciliation/v2-receipted-without-observation.json +14 -0
  18. package/conformance/fixtures/reconciliation/after-customers-1.json +1 -0
  19. package/conformance/fixtures/reconciliation/after-customers-15.json +1 -0
  20. package/conformance/fixtures/reconciliation/after-empty.json +1 -0
  21. package/conformance/fixtures/reconciliation/after-set.json +1 -0
  22. package/conformance/fixtures/reconciliation/after-unattributed.json +1 -0
  23. package/conformance/fixtures/reconciliation/before-customers-10.json +1 -0
  24. package/conformance/fixtures/reconciliation/before-empty.json +1 -0
  25. package/conformance/fixtures/reconciliation/profile-clocks.json +9 -0
  26. package/conformance/fixtures/reconciliation/profile-exclusion.json +7 -0
  27. package/conformance/fixtures/reconciliation/profile-multiplicity.json +9 -0
  28. package/conformance/fixtures/reconciliation/profile-no-clocks.json +4 -0
  29. package/conformance/fixtures/reconciliation/receipts-customers-early.jsonl +1 -0
  30. package/conformance/fixtures/reconciliation/receipts-customers.jsonl +1 -0
  31. package/conformance/fixtures/reconciliation/receipts-empty.jsonl +0 -0
  32. package/conformance/run.mjs +59 -0
  33. package/docs/API-STABILITY.md +1 -1
  34. package/docs/ARCHITECTURE.md +2 -2
  35. package/docs/RECEIPT-SPEC.md +92 -15
  36. package/docs/claims/retracted-phrasings.json +7 -0
  37. package/docs/claims/reviews/0.2.37.md +180 -0
  38. package/docs/claims/surfaces.json +115 -0
  39. package/package.json +1 -1
@@ -0,0 +1 @@
1
+ {"v":"conarium-receipt/0.3","ts":"2026-08-06T11:00:00.000Z","request":{"tool":"query","target":"zion-rest","argsHash":"sha256:00"},"dataRefs":[{"source":"zion-rest","object":"zion.customers","fieldsRequested":[]}],"policy":{"decision":"allow"},"chain":{"seq":1}}
@@ -97,6 +97,56 @@ function resistanceStatusFor(c, empirical, claimsFile) {
97
97
  return empirical.denied ? 'ENFORCED' : 'NOT_COVERED'
98
98
  }
99
99
 
100
+ function runReconcileV2(c) {
101
+ const bin = join(REPO, 'bin', 'conarium-reconcile.mjs')
102
+ const args = [
103
+ bin,
104
+ '--before', resolve(REPO, c.before),
105
+ '--after', resolve(REPO, c.after),
106
+ '--receipts', resolve(REPO, c.receipts),
107
+ '--json-v2',
108
+ ]
109
+ if (c.mappingProfile) args.push('--profile', resolve(REPO, c.mappingProfile))
110
+ const r = spawnSync(process.execPath, args, { encoding: 'utf8', cwd: REPO, windowsHide: true })
111
+ let body
112
+ try {
113
+ body = JSON.parse((r.stdout || '').trim().split('\n').filter(Boolean).pop() || '')
114
+ } catch {
115
+ return { toolFailure: true, detail: `reconcile --json-v2 stdout was not JSON (exit ${r.status}): ${(r.stderr || r.stdout || '').trim()}` }
116
+ }
117
+ if (body.v !== 'coverage-reconciliation/2') {
118
+ return { ok: false, outcome: body.v, detail: `expected v coverage-reconciliation/2, got ${body.v}` }
119
+ }
120
+ const reasons = []
121
+ if (c.expectOutcome && body.outcome !== c.expectOutcome) {
122
+ reasons.push(`outcome ${body.outcome} != ${c.expectOutcome}`)
123
+ }
124
+ if (c.expectCounts) {
125
+ for (const [k, n] of Object.entries(c.expectCounts)) {
126
+ if ((body.counts?.[k] ?? 0) !== n) reasons.push(`counts.${k} ${body.counts?.[k]} != ${n}`)
127
+ }
128
+ }
129
+ if (c.expectBounds) {
130
+ for (const [k, n] of Object.entries(c.expectBounds)) {
131
+ if (body.bounds?.[k] !== n) reasons.push(`bounds.${k} ${body.bounds?.[k]} != ${n}`)
132
+ }
133
+ }
134
+ const itemOutcomes = (body.items || []).map((i) => i.outcome)
135
+ if (Array.isArray(c.expectItemOutcomes)) {
136
+ for (const want of c.expectItemOutcomes) {
137
+ if (!itemOutcomes.includes(want)) reasons.push(`missing item outcome ${want}`)
138
+ }
139
+ }
140
+ if (Array.isArray(c.forbidItemOutcomes)) {
141
+ for (const bad of c.forbidItemOutcomes) {
142
+ if (itemOutcomes.includes(bad) || (bad === 'matched' && (body.counts?.matched ?? 0) > 0)) {
143
+ reasons.push(`forbidden outcome present: ${bad}`)
144
+ }
145
+ }
146
+ }
147
+ return { ok: reasons.length === 0, outcome: body.outcome, detail: reasons.join('; ') || null }
148
+ }
149
+
100
150
  function evaluate(c, claimsFile, adapter) {
101
151
  const row = {
102
152
  id: c.id,
@@ -109,6 +159,15 @@ function evaluate(c, claimsFile, adapter) {
109
159
  expectedStatus: c.expectedStatus || null,
110
160
  }
111
161
 
162
+ if ((c.harness || 'query') === 'reconcile-v2') {
163
+ const v = runReconcileV2(c)
164
+ if (v.toolFailure) return { ...row, status: 'TOOL_FAILURE', detail: v.detail, unexpected: true }
165
+ const ok = v.ok
166
+ const status = label('conformance', conformanceStatus({ ok }))
167
+ const unexpected = status === 'FAIL' && claimed(claimsFile, c.claim)
168
+ return { ...row, status, outcome: v.outcome, unexpected, detail: v.detail || null }
169
+ }
170
+
112
171
  if ((c.harness || 'query') === 'verify') {
113
172
  const v = runVerify(claimsFile, c)
114
173
  if (v.toolFailure) return { ...row, status: 'TOOL_FAILURE', detail: v.detail, unexpected: true }
@@ -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` `--skew` `--json` `--help` | experimental |
68
+ | `conarium-reconcile` | `--before` `--after` `--receipts` `--skew` `--profile` `--json` `--json-v2` `--result-v2` `--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 |
@@ -6,9 +6,9 @@ MCP made "connect an AI assistant to your data" a commodity. The durable value i
6
6
 
7
7
  1. **Ingestion** of messy internal sources (schemas today; docs, ADRs, APIs next).
8
8
  2. **Governance + audit** — what the AI may see, and a record of what it saw.
9
- 3. **Self-hosting** — the gateway runs in the customer's network. Raw protected values stay there; the policy-approved disclosure is what reaches the customer's AI client, and `disclosure.hash` binds exactly which bytes those were. Protected values are not sent to us or to a vendor. Two outbound connections exist and are named so they can be checked, not because they carry those values:
9
+ 3. **Self-hosting** — the gateway runs in the customer's network. Raw protected values stay there; the policy-approved disclosure is what reaches the customer's AI client, and `disclosure.hash` binds exactly which bytes those were. Protected values are not sent to us or to a vendor. Outbound connections are named so they can be checked, not because they carry those values:
10
10
  - **npm version check** — `src/update-check.ts` `announceUpdate()`, called at start from both entry points, `src/index.ts` (stdio) and `src/http.ts` (HTTP gateway). Asks the public registry for `@conarium-ai/core`'s latest version number. Sends no installation identity. Disable with `CONARIUM_NO_UPDATE_CHECK=1`.
11
- - **OpenTimestamps calendars** — production profile (`src/config.ts`) sets `CONARIUM_ANCHOR_SINK=opentimestamps` when the operator did not; that path submits a digest, not row values, to the public calendars listed in `src/ots/calendar.ts`. Set `CONARIUM_ANCHOR_SINK=none` to keep it off.
11
+ - **OpenTimestamps calendars** — only when `conarium-stamp` or `conarium-anchor-service` runs. Those tools submit a digest, not row values, to the public calendars listed in `src/ots/calendar.ts`. The receipt write path does not. The production profile (`src/config.ts`) sets `CONARIUM_ANCHOR_SINK=opentimestamps` when the operator did not; that env selects the calendar client the tools use. Set `CONARIUM_ANCHOR_SINK=none` to keep the client off.
12
12
  4. **Freshness** — incremental re-index so context never goes stale.
13
13
 
14
14
  Conarium owns this layer and stays **tool-agnostic**: it speaks MCP, so it plugs into Cursor, Copilot, Claude Code, Windsurf, Continue.dev — whatever wins.
@@ -60,7 +60,7 @@ Version string: `conarium-receipt/0.4` (verifier also accepts `0.1`, `0.2`, and
60
60
  | `chain.seq` | coverage backbone | contiguous integer; required even before v0.2 coverage proofs |
61
61
  | `chain.prevHash` / `chain.hash` | integrity | JCS (RFC 8785 subset) → SHA-256 |
62
62
  | `sig` | Ed25519 over `chain.hash` | `{ alg, keyId, value }` |
63
- | `anchor` | transparency-log head | filled asynchronously; may be `null` |
63
+ | `anchor` | transparency-log head | `null` when written; filled only after `conarium-stamp` or `conarium-anchor-service` |
64
64
 
65
65
  `hash = sha256(canonicalize(receipt \ {hash, sig, anchor}))` with `chain.hash`
66
66
  stripped before hashing. Prefix: `sha256:` + hex.
@@ -254,7 +254,7 @@ occurred"** — an absent record is ambiguous by nature.
254
254
  ## Reconciliation (two-sided, v0.1)
255
255
 
256
256
  ```
257
- conarium-reconcile --before <snapshot.json> --after <snapshot.json> --receipts <receipts.jsonl> [--json]
257
+ conarium-reconcile --before <snapshot.json> --after <snapshot.json> --receipts <receipts.jsonl> [--skew <duration>] [--profile <path>] [--json] [--json-v2] [--result-v2 <path>]
258
258
  ```
259
259
 
260
260
  The coverage declaration is one-sided: it reports what the receipt chain says
@@ -322,6 +322,75 @@ Rules that keep the verdict honest:
322
322
  | 40 | Unreconciled DB activity — recorded by the database, not receipted |
323
323
  | 41 | Indeterminate — a pattern is uncovered only by the window boundary, and two clocks decide that boundary |
324
324
 
325
+ `--json` is the `/1` body (`conarium-reconcile/0.1`) and the exit codes
326
+ above are its contract. `--json-v2` prints a separate
327
+ `coverage-reconciliation/2` object; `--result-v2 <path>` writes that object
328
+ to a file. The two must not share a body: a consumer MUST NOT read a `/1`
329
+ result as a `/2` result. `/2` does not change these exit codes. Signing and
330
+ SCITT registration of the `/2` object are out of scope for this version.
331
+
332
+ Without a Mapping Profile (`--profile`), `/2` sets `profile` to `null`.
333
+ Every item whose outcome depends on a multiplicity bound is then
334
+ `indeterminate`, an unattributed pattern is `indeterminate` rather than
335
+ `observed-without-receipt`, an infrastructure pattern is `indeterminate`
336
+ rather than `excluded` (`bounds.exclusion` is `undeclared` — an undeclared
337
+ bound does not decide), and `receipted-without-observation` makes
338
+ `outcome` `exceptions`. `bounds.exclusion` is `operator-declared` only
339
+ when the profile lists at least one exclusion rule.
340
+
341
+ ### Mapping Profile (`conarium-mapping-profile/0.1`)
342
+
343
+ A Mapping Profile is an operator declaration. It is versioned, serialized as
344
+ JSON, and digested as raw file bytes (`sha256:` + hex). The result binds that
345
+ digest. The profile is not a measurement: a declared bound is
346
+ `operator-declared` on the result, never `measured`.
347
+
348
+ ```json
349
+ {
350
+ "v": "conarium-mapping-profile/0.1",
351
+ "version": "1",
352
+ "multiplicity": { "maxStatementsPerReceipt": 8 },
353
+ "exclusions": [ { "id": "infra-query", "version": "1" } ],
354
+ "clocks": {
355
+ "observation": "pg_stat_statements",
356
+ "receipt": "gateway",
357
+ "skew": "5s"
358
+ }
359
+ }
360
+ ```
361
+
362
+ `v` is the object type. `version` is the operator's identifier for this
363
+ profile (a string). Every other member is optional. Omitted members are
364
+ undeclared, not defaulted.
365
+
366
+ | Field | Type | Encoding | What it declares |
367
+ |---|---|---|---|
368
+ | `multiplicity.maxStatementsPerReceipt` | integer ≥ 1 | JSON number | how many source statements one receipt may cover |
369
+ | `exclusions[]` | array | `{ "id": string, "version": string }` | rules that remove items before comparison |
370
+ | `clocks.observation` | string | clock identifier | the clock that stamps the observation window (the Data Source). This implementation writes it on `/1` as `clocks.window`. Typical value here: `pg_stat_statements`. |
371
+ | `clocks.receipt` | string | clock identifier | the clock that stamps receipts (the Gateway). This implementation writes it on `/1` as `clocks.receipts`. Typical value here: `gateway`. |
372
+ | `clocks.skew` | string | duration | how far those two clocks may differ |
373
+
374
+ `clocks` accepts only those three keys. A declaration that both sides read
375
+ one clock still writes both identifiers (they may be the same string) and
376
+ still writes `skew` — including `0ms`. Zero is a declaration, not a default.
377
+
378
+ **Duration encoding** (the same grammar as `--skew`; there is not a second
379
+ one): a number, optional fraction, optional unit `ms` / `s` / `m` / `h`.
380
+ The number is scaled by `ms` = 1, `s` = 1000, `m` = 60 000, `h` = 3 600 000,
381
+ then rounded to an integer millisecond. A bare number is milliseconds.
382
+ Examples: `500ms`, `5s`, `2m`, `1h`, `5000`. An unreadable duration is an
383
+ error, not a default.
384
+
385
+ `--skew` and `clocks.skew` are both operator declarations. If both are
386
+ present and they do not parse to the same number of milliseconds, the run
387
+ fails (exit 20). This tool will not pick one: which bound won would be
388
+ invisible on the result. Equal values (`5s` and `5000`) are the same
389
+ declaration. If either is present, `/2` reports `bounds.skew` as
390
+ `operator-declared` and the comparison uses that bound. If neither is
391
+ present, `bounds.skew` is `undeclared` and a pattern uncovered only by the
392
+ window boundary stays `indeterminate`.
393
+
325
394
  ### The window straddles two clocks
326
395
 
327
396
  The window is `[before.ts, after.ts]` and both timestamps come from the database.
@@ -355,7 +424,8 @@ was *"NOT reported as unreceipted access"* — a sentence twenty-three hours of
355
424
  offset cannot support. 41 was never a silent pass, and is not one now; what
356
425
  changed is that the tool stops offering an excuse it cannot back.
357
426
 
358
- A declared `--skew` is the operator's own statement about their clocks and
427
+ A declared skew bound (`--skew` or Mapping Profile `clocks.skew`) is the
428
+ operator's own statement about their clocks and
359
429
  outranks the window rule. A window shorter than a clock correction is possible —
360
430
  a five-second window and a six-second step would read as beyond the boundary
361
431
  while being exactly the case the class exists for — and the operator is the one
@@ -363,11 +433,12 @@ who knows whether that is their deployment. We have not measured how often it
363
433
  happens; the flag exists so the answer does not have to come from us:
364
434
 
365
435
  ```
366
- INDETERMINATE: 1 pattern(s) are uncovered only by the window boundary — no --skew bound was declared…
436
+ INDETERMINATE: 1 pattern(s) are uncovered only by the window boundary — no skew bound was declared…
367
437
  ~ (+5) table(s) [public.customers] have a receipt 3000ms outside the window: SELECT …
368
438
  ```
369
439
 
370
- `--skew <duration>` declares the bound (`500ms`, `5s`, `2m`, `1h`). A receipt
440
+ `--skew <duration>` or Mapping Profile `clocks.skew` declares the bound
441
+ (`500ms`, `5s`, `2m`, `1h`). A receipt
371
442
  further out than the bound is not skew, and its pattern goes back to unreconciled
372
443
  at 40 with the bypass sentence. An unreadable duration is an error, not a default:
373
444
  a tolerance nobody chose is the kind of number this tool exists to refuse.
@@ -390,10 +461,12 @@ conarium-stamp <file> [--sidecar <path>] [--json]
390
461
  | 0 | Stamped; sidecar written (`pending` until upgraded) |
391
462
  | 50 | Stamping failed — calendars unreachable or timed out |
392
463
 
393
- Receipts are anchored automatically. Documents are not, and **a git commit date is
394
- not evidence** — `git commit --date` accepts whatever you type. This stamps the
464
+ Receipts are not anchored by the write path. An operator stamps a document
465
+ with `conarium-stamp`, or submits a chain-head hash through
466
+ `conarium-anchor-service`. A git commit date is **not evidence** —
467
+ `git commit --date` accepts whatever you type. This stamps the
395
468
  SHA-256 of a file to the OpenTimestamps calendars and writes the same sidecar shape
396
- receipt anchoring uses, so `conarium-anchor-upgrade` upgrades it to a Bitcoin block
469
+ those tools use, so `conarium-anchor-upgrade` upgrades it to a Bitcoin block
397
470
  height unchanged. Only the 32-byte digest leaves the machine.
398
471
 
399
472
  **What a stamp proves, exactly:** this file existed, byte for byte in this form, no
@@ -416,16 +489,20 @@ revision history is itself timestamped.
416
489
  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.
417
490
  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."**
418
491
  4. **Creation-time truth is not proven.** Without hardware attestation, an operator can still write false-but-well-formed receipts *before* anchoring.
419
- 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 is available** (`CONARIUM_ANCHOR_SINK=opentimestamps`) but starts as `pending` — Bitcoin finality is delayed (hours); see §Anchoring.
492
+ 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.
420
493
  6. **`argsHash` hurts debugging.** Support cases need the customer's own logs to correlate.
421
494
  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.
422
495
 
423
496
  ## Anchoring (OpenTimestamps)
424
497
 
425
- Chain-head hashes are optionally stamped with **OpenTimestamps** (opt-in:
426
- `CONARIUM_ANCHOR_SINK=opentimestamps`). Only the raw 32-byte digest is sent
427
- (our `sha256:<hex>` prefix is stripped first). Proofs live in a sidecar
428
- `<sink>.anchors.jsonl`; the receipt’s `anchor` field is a hash-exterior
498
+ Receipts are not stamped by the write path. `Audit.writeReceipt` emits
499
+ `anchor: null`. An operator stamps a file with `conarium-stamp`, or submits
500
+ a chain-head hash through `conarium-anchor-service`. Those tools talk to the
501
+ **OpenTimestamps** calendars. `CONARIUM_ANCHOR_SINK=opentimestamps` selects
502
+ the in-tree calendar client they use; it does not stamp receipts as they
503
+ are written. Only the raw 32-byte digest is sent (our `sha256:<hex>` prefix
504
+ is stripped first). Proofs live in a sidecar `<sink>.anchors.jsonl`; after
505
+ a stamp is submitted, the receipt’s `anchor` field is a hash-exterior
429
506
  reference: `{ "log": "opentimestamps", "ref": "sha256:…", "state": "pending"|"bitcoin" }`.
430
507
 
431
508
  | State | Meaning |
@@ -442,8 +519,8 @@ chain, not hash calendars.
442
519
  implementation; institutional buyers may prefer it, but it requires trusting a TSA.
443
520
 
444
521
  **Honest latency:** “not backdated” becomes Bitcoin-hard only after upgrade. Pending
445
- is disclosed — `conarium-verify --anchor-check` skips `anchor:null` (periodic
446
- anchoring), exits 0 with a stderr warning while pending, and exits 14 if a
522
+ is disclosed — `conarium-verify --anchor-check` skips `anchor:null` (nothing
523
+ has been submitted yet), exits 0 with a stderr warning while pending, and exits 14 if a
447
524
  *claimed* anchor's proof is missing or does not match the hash. The run prints
448
525
  `N/M anchored, head anchored: yes/no`. `--require-head-anchor` exits 14 when
449
526
  the chain head is unanchored.
@@ -89,6 +89,13 @@
89
89
  "why": "scanCharCap replaces a whole field with [MASKED_PII] even when it contains no identifier",
90
90
  "use": "a field longer than policy.scanCharCap is replaced whole with [MASKED_PII], even when it contains no identifier"
91
91
  },
92
+ {
93
+ "id": "anchored-automatically",
94
+ "re": "anchored automatically",
95
+ "flags": "i",
96
+ "why": "Audit.writeReceipt emits anchor:null and does not call the scheduler; stamp and the anchor service are manual",
97
+ "use": "receipts are not anchored by the write path; stamp a document or run conarium-anchor-service"
98
+ },
92
99
  {
93
100
  "id": "node-18-floor",
94
101
  "re": "(?:with\\s+)?node\\s*\\(?\\s*(?:≥|>=)\\s*18\\s*\\)?|engines[^\\n]{0,40}>=\\s*18\\b",
@@ -0,0 +1,180 @@
1
+ # Claims review — 0.2.37
2
+
3
+ - base: v0.2.36
4
+ - head: ef7b1dd
5
+ - surface: sha256:ccfef14ad8a5dddddd579822a9513c16680ef757c4e3007ed55c6858936357ef
6
+ - verdict: pass
7
+ - reviewer: Claude (Opus 5)
8
+
9
+ Six surfaces changed. The release began as a claim with no call site and a
10
+ result object that decided on bounds nobody had declared; two of the five
11
+ findings below were found while reviewing the fixes for the other three, which
12
+ is the only reason they are in this record rather than in the next one. The
13
+ shape that recurs: a sentence corrected once, in one of the places it was
14
+ written.
15
+
16
+ ## Findings
17
+
18
+ ### 1. docs/RECEIPT-SPEC.md — "Receipts are anchored automatically"
19
+
20
+ - Claim, as of 0.2.36: *"Receipts are anchored automatically. Documents are
21
+ not…"* — unconditional, on a surface that ships in the tarball. The same claim
22
+ was repeated in `README.md` (*"Opt-in anchoring: `CONARIUM_ANCHOR_SINK=…`"*,
23
+ which reads as: setting the variable stamps receipts), in `LIMITATIONS.md`
24
+ (*"Receipts already show `pending`"*), in `docs/ARCHITECTURE.md` (*"that path
25
+ submits a digest"*), and in the header of `bin/conarium-stamp.mjs`.
26
+ - Mechanism: `AnchorScheduler.maybeAnchor`, `createAnchorSinkFromEnv` and
27
+ `appendAnchorSidecar` in `src/anchor.ts`.
28
+ - Why it fell short: none of them has a caller. `src/audit.ts` contains no
29
+ occurrence of the string `anchor`; `src/receipt.ts:399` gives every receipt
30
+ `anchor: null`; the only production files importing `./anchor.js` are
31
+ `src/console.ts`, which classifies an anchor for display, and
32
+ `src/anchor-service.ts`, which is the hosted endpoint. Measured end to end
33
+ with `CONARIUM_ANCHOR_SINK=opentimestamps` and a receipt sink configured: the
34
+ receipt carried `anchor: null` and no `<sink>.anchors.jsonl` was written. The
35
+ variable selects a calendar client for the manual tools; it does not put the
36
+ write path in touch with a calendar.
37
+ - Disposition: the text is narrowed to the mechanism in all five places, and the
38
+ scheduler was deliberately **not** wired. Wiring it adds an outbound network
39
+ hop to the receipt path and changes the two-connection list in
40
+ `docs/ARCHITECTURE.md`; that is a product decision, and making a sentence true
41
+ by adding a network call to satisfy it is the wrong direction of fit.
42
+ - Guard: `test/anchor_wiring.mjs` — an automatic-anchoring claim on a claim
43
+ surface requires a write call in `src/` or `bin/`, excluding tests and
44
+ excluding the definitions themselves. Demonstrated in both directions rather
45
+ than one: with the claim restored and no call it exits 1 and prints the file
46
+ and line; with the claim present and a call added to `src/console.ts` it exits
47
+ 0 and prints the call site. A guard that has only been shown to fail proves it
48
+ can fail.
49
+ - Residual, and it is the same residual the guard has by construction: the rules
50
+ are phrasings. Finding 3 is what that costs.
51
+
52
+ ### 2. bin/conarium-reconcile.mjs — an undeclared exclusion decided the outcome
53
+
54
+ - Claim: the `/2` object implements `coverage-reconciliation/2` as
55
+ `draft-dogru-scitt-disclosure-evidence-04` defines it.
56
+ - Mechanism: `projectResultV2`, and §Exclusions of that draft: *"Exclusion rules
57
+ MUST be stated in the Mapping Profile and are therefore covered by its digest…
58
+ An implementation MUST NOT exclude items by a rule that is not in the
59
+ profile."*
60
+ - Why it fell short: with no profile, an infrastructure pattern was emitted as
61
+ `excluded` with `rule.version: "hardcoded"`, and the run reported
62
+ `outcome: no-exceptions` while `bounds.exclusion` said `undeclared` on the same
63
+ object. It named the bound as undeclared and then decided with it. The
64
+ inversion is what makes it a defect rather than a rough edge: measured on one
65
+ input, a profile that merely omitted the rule produced `indeterminate` and
66
+ `exceptions`, while **no profile at all** produced `excluded` and
67
+ `no-exceptions`. Strictly less declaration bought a strictly cleaner verdict,
68
+ which is Proposition 2b run backwards, on the outcome the draft calls the one
69
+ through which a reconciliation can be made to come out clean.
70
+ - Disposition: with no profile, an infrastructure pattern is `indeterminate`
71
+ (`reason: exclusion-undeclared`), and `bounds.exclusion` is
72
+ `operator-declared` only when the profile lists at least one exclusion rule —
73
+ a profile carrying no exclusions declares nothing about exclusion. Measured
74
+ after the fix on the same input: no profile → `indeterminate` / `exceptions`;
75
+ profile without the rule → `indeterminate` / `exceptions`; profile with the
76
+ rule → `excluded` / `no-exceptions`. Declaration and verdict now move in the
77
+ same direction.
78
+ - Second finding, inside the first: `conformance/cases/reconciliation/v2-excluded.json`
79
+ had pinned the defect. Its `expectOutcome` was `no-exceptions` with
80
+ `expectCounts.excluded: 1`, and its own `rationale` field said *"Without a
81
+ Mapping Profile the exclusion bound is undeclared."* The fixture stated the
82
+ undeclared bound and asserted the decision taken with it. A green vector over
83
+ a defect is worse than no vector: it converts the defect into a contract. The
84
+ case now runs against a profile that declares the rule, and the profile-less
85
+ input is a negative case (`v2-neg-undeclared-exclusion`).
86
+
87
+ ### 3. LIMITATIONS.md — the anchoring correction had a second copy
88
+
89
+ - Claim: *"Bitcoin confirmation still takes hours; receipts still show `pending`
90
+ until upgrade."* (`LIMITATIONS.md`, OpenTimestamps client section.)
91
+ - Mechanism: the same one as finding 1 — a receipt is born `anchor: null`.
92
+ - Why it fell short: the file contradicted itself. Its anchors section, rewritten
93
+ earlier in this same release, says `pending` appears only after an operator
94
+ submits a stamp; two hundred lines down the old sentence was still there, and
95
+ it is the more specific of the two, so a reader resolving the contradiction
96
+ would resolve it the wrong way. `LIMITATIONS.tr.md` had both places corrected,
97
+ so the two languages had also come apart — with the English, the surface that
98
+ ships to npm, holding the stale half.
99
+ - Why the guard did not catch it: the rule was `receipts already show
100
+ `pending``. The sentence says *still*. A rule pinned to one adverb guards one
101
+ sentence, not the claim the sentence makes.
102
+ - Disposition: sentence corrected to match the mechanism; the rule now matches
103
+ *already* / *still* / *are*, and was shown red against the live tree before the
104
+ sentence was touched — the check named `LIMITATIONS.md:249` and exited 1.
105
+ - Recorded because of when it was found: during the release review, not by the
106
+ guard written in the same release for exactly this claim. The guard is worth
107
+ keeping and its limit is worth stating rather than describing it as coverage.
108
+
109
+ ### 4. Two hand-written copies of the claim-surface list
110
+
111
+ - Claim: the release gate reviews the documents that carry promises, and the
112
+ retracted-phrasing scan reads the same documents.
113
+ - Mechanism: `SURFACES` in `test/denetci.mjs` (22 entries) and `SURFACES` in
114
+ `test/claim_discipline.mjs` (12 entries).
115
+ - Why it fell short: the second was a silent subset of the first. Measured: a
116
+ strict subset, no entry in the second that was absent from the first, so ten
117
+ documents — including `standards/README.md` and
118
+ `docs/security/THREAT-MODEL.md`, the two that carried stale sentences into
119
+ 0.2.35 — were exempt from the phrasing scan for no stated reason. 0.2.36's
120
+ record named this and deferred it to its own release; this is that release.
121
+ - Disposition: one file, `docs/claims/surfaces.json`, read by both. Every entry
122
+ carries the reason it is a surface, and the phrasing exemption is an explicit
123
+ per-entry field with a required justification — measured after the change: 22
124
+ entries, 22 reasons, zero exemptions. Widening the scan from 12 to 22 produced
125
+ one new red, `docs/PRIOR-ART.md` matching the Turkish-letter check on a
126
+ registry field name (*Yayın Numarası*); it was resolved by naming the example,
127
+ not by narrowing the list back.
128
+
129
+ ### 5. LIMITATIONS.tr.md — three limitations reached one language and not the other
130
+
131
+ - Claim: the Turkish limitations file is the Turkish limitations file.
132
+ - Mechanism: nothing. Two files, written by hand, with no relation between them.
133
+ - Why it fell short: 24 sections against 21. Missing in Turkish: the Node 20
134
+ end-of-life floor, the audit sink hash not being JCS, and reconciliation
135
+ establishing object attribution rather than per-statement coverage. All three
136
+ are limits a reader is entitled to before choosing this package; a reader in
137
+ one language was told and a reader in the other was not. The same shape lost
138
+ the SOC 2 answer for a release in 0.2.26.
139
+ - Disposition: the three sections written, and `test/limitations_locale.mjs`
140
+ compares the two files by a section key carried in an HTML comment — not by
141
+ heading text, which is translated and cannot be the join. Shown red first: with
142
+ one key removed the check exits 1, names the missing key, and names the
143
+ orphaned heading beside it.
144
+
145
+ ## What this release adds rather than corrects
146
+
147
+ `--profile` reads a Mapping Profile that declares the multiplicity bound, the
148
+ exclusion rules, and the two clocks. The clock fields are **declarations and
149
+ nothing more**: the tool does not verify that `clocks.observation` is the clock
150
+ that stamped the snapshots or that `clocks.receipt` is the one that stamped the
151
+ receipts, and `/2` therefore reports them at `operator-declared`, never
152
+ `measured`. What the declaration does change is the comparison — measured, not
153
+ asserted: against a receipt 3s outside the window, a declared bound of 5s leaves
154
+ the item `indeterminate` (a declaration does not invent a match) and a declared
155
+ bound of 1s moves it to `observed-without-receipt`. `--skew` and `clocks.skew`
156
+ are the same kind of statement, so disagreement between them fails the run rather
157
+ than resolving silently; `5s` and `5000` are the same declaration.
158
+
159
+ The field list and its duration grammar are written out in
160
+ `docs/RECEIPT-SPEC.md` because another specification in the same working group
161
+ asked to adopt the shape rather than invent a second one. That is the reason the
162
+ encoding is stated to the millisecond and the reason `0ms` is documented as a
163
+ declaration rather than a default.
164
+
165
+ ## What did not change
166
+
167
+ The policy gate, masking, the receipt format, `conarium-verify`, and the `/1`
168
+ reconciliation body and its exit codes. `/1` was re-measured on the same input
169
+ after each change and is byte-identical; `test/spec_exitcode_drift.mjs` reports
170
+ the same set. `standards/` is untouched — the published `-04` is immutable, and
171
+ the promises made to that list were kept in code and in `docs/`, not by editing
172
+ a posted draft. `-04`'s Implementation Status now understates this
173
+ implementation in four places; correcting it is `-05`'s work and is not done
174
+ here, because a draft describing an unpublished tree would be the same defect
175
+ pointed the other way.
176
+
177
+ Measured and not a finding, recorded so it is not re-raised: `package-lock.json`
178
+ carries `version: 0.2.24`. The published SBOM does not inherit it — `npm sbom
179
+ --package-lock-only` takes the root component from `package.json` and reports
180
+ `@conarium-ai/core@0.2.37`, 81 components, CycloneDX 1.5.
@@ -0,0 +1,115 @@
1
+ {
2
+ "_comment": "Single source for the claim-surface list. test/denetci.mjs and test/claim_discipline.mjs both read this file. A second copy of the list is how a document became a promise that nobody was assigned to read. phrasing=false is an exemption from retracted-phrasing scan and requires phrasingWhy. phrasing=true is not a silent default — every entry states it.",
3
+ "surfaces": [
4
+ {
5
+ "path": "README.md",
6
+ "why": "Published front page. A reader takes the opening sentences as a promise about what the package does.",
7
+ "phrasing": true
8
+ },
9
+ {
10
+ "path": "README.tr.md",
11
+ "why": "Turkish front page. The same promise surface in the other language; it may be absent from a given tree.",
12
+ "phrasing": true
13
+ },
14
+ {
15
+ "path": "SECURITY.md",
16
+ "why": "Security promises: outbound calls, countersigning, what is and is not operated.",
17
+ "phrasing": true
18
+ },
19
+ {
20
+ "path": "LIMITATIONS.md",
21
+ "why": "The measured-limits surface. A missing limit is itself a claim: the English reader is told something the other language is not.",
22
+ "phrasing": true
23
+ },
24
+ {
25
+ "path": "LIMITATIONS.tr.md",
26
+ "why": "Turkish measured-limits surface. The SOC 2 answer failed to reach this file in 0.2.26 for exactly this reason.",
27
+ "phrasing": true
28
+ },
29
+ {
30
+ "path": "docs.html",
31
+ "why": "Website documentation page. Not in the tarball; a reader of conarium.dev still takes it as a promise.",
32
+ "phrasing": true
33
+ },
34
+ {
35
+ "path": "dpa.html",
36
+ "why": "Data-processing terms a reader can treat as a legal promise.",
37
+ "phrasing": true
38
+ },
39
+ {
40
+ "path": "terms.html",
41
+ "why": "Terms of use. A promise surface even though it is not in the npm tarball.",
42
+ "phrasing": true
43
+ },
44
+ {
45
+ "path": "privacy.html",
46
+ "why": "Privacy page. The 2026-08-17 overclaim ('never receive, see, or store your data') lived here.",
47
+ "phrasing": true
48
+ },
49
+ {
50
+ "path": "docs/ARCHITECTURE.md",
51
+ "why": "Names the outbound connections and the request path. A reader auditing traffic starts here.",
52
+ "phrasing": true
53
+ },
54
+ {
55
+ "path": "docs/RECEIPT-SPEC.md",
56
+ "why": "The receipt-format contract. Exit codes, field meanings, and anchoring mood are taken as specification.",
57
+ "phrasing": true
58
+ },
59
+ {
60
+ "path": "docs/API-STABILITY.md",
61
+ "why": "States which flags and exit codes are candidate-stable. A reader pins a script to this page.",
62
+ "phrasing": true
63
+ },
64
+ {
65
+ "path": "docs/CONTRIBUTING.md",
66
+ "why": "Tells a contributor what the project claims to require. Not a product promise to a customer, but it is public and it is read.",
67
+ "phrasing": true
68
+ },
69
+ {
70
+ "path": "docs/COUNTERSIGN.md",
71
+ "why": "Documents the countersigning endpoint a reader is told to run. The missing bin-registration of conarium-anchor-service lived next to this page.",
72
+ "phrasing": true
73
+ },
74
+ {
75
+ "path": "docs/BENCHMARK.md",
76
+ "why": "Publishes numbers. A number without a method is a claim; a number with a method is still a claim about what was measured.",
77
+ "phrasing": true
78
+ },
79
+ {
80
+ "path": "docs/PRIOR-ART.md",
81
+ "why": "States what was searched and what was not. A reader treating this as legal advice would be wrong; a reader treating the search record as a search record must still get a current one.",
82
+ "phrasing": true
83
+ },
84
+ {
85
+ "path": "docs/CONSENT-BINDING-SPEC.md",
86
+ "why": "A specification page. Field names and binding rules are taken as the format.",
87
+ "phrasing": true
88
+ },
89
+ {
90
+ "path": "docs/security/THREAT-MODEL.md",
91
+ "why": "Two levels down, and for five days that was enough to hide it. The sentence 'two OS processes … have no file lock' stayed in the tree after the audit sink got a lock, because unlistedDocs only looked one level under docs/ and nothing ever asked why this file was absent from both lists.",
92
+ "phrasing": true
93
+ },
94
+ {
95
+ "path": "docs/security/PENTEST-SCOPE.md",
96
+ "why": "States that no independent pentest is on file. That is a claim with an expiry date attached to an event we intend to cause.",
97
+ "phrasing": true
98
+ },
99
+ {
100
+ "path": "standards/README.md",
101
+ "why": "Not in the tarball, public on GitHub, and the place a reader checks what we say our IETF standing is. It carried '-04 has not been submitted' for two days after -04 was posted.",
102
+ "phrasing": true
103
+ },
104
+ {
105
+ "path": "docs/PRICING.md",
106
+ "why": "Ships in the tarball and states a price, a refund window and what each tier delivers. It arrived in 0.2.31 unlisted, and the review that listed it found the Button column pointing at a checkout route that redirects to the waitlist form — a promise surface that no reader was assigned.",
107
+ "phrasing": true
108
+ },
109
+ {
110
+ "path": "docs/security/NPM-PROVENANCE.md",
111
+ "why": "Ships in the tarball and tells a reader how to check where the package came from. Unlisted until 0.2.33, by which point it had gone stale in the worst direction: it said 'this is not a published release' inside eight published releases, and pointed at a verification command that answers 404 for npm provenance. A page about how to distrust us is one a reader must be able to trust.",
112
+ "phrasing": true
113
+ }
114
+ ]
115
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@conarium-ai/core",
3
- "version": "0.2.36",
3
+ "version": "0.2.37",
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.",