@conarium-ai/core 0.1.0

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 (188) hide show
  1. package/CHANGELOG.md +131 -0
  2. package/LICENSE +21 -0
  3. package/README.md +387 -0
  4. package/SECURITY.md +226 -0
  5. package/bin/conarium-anchor-service.mjs +77 -0
  6. package/bin/conarium-anchor-upgrade.mjs +108 -0
  7. package/bin/conarium-coverage.mjs +425 -0
  8. package/bin/conarium-doctor.mjs +480 -0
  9. package/bin/conarium-init.mjs +184 -0
  10. package/bin/conarium-reconcile.mjs +441 -0
  11. package/bin/conarium-stamp.mjs +161 -0
  12. package/bin/conarium-verify.mjs +610 -0
  13. package/conarium.config.json +43 -0
  14. package/deploy/anchor-service/README.md +79 -0
  15. package/deploy/anchor-service/conarium-anchor.service +21 -0
  16. package/deploy/anchor-service/dry-run.mjs +122 -0
  17. package/deploy/anchor-service/ecosystem.config.cjs +21 -0
  18. package/deploy/anchor-service/env.example +11 -0
  19. package/dist/anchor-service.d.ts +39 -0
  20. package/dist/anchor-service.d.ts.map +1 -0
  21. package/dist/anchor-service.js +278 -0
  22. package/dist/anchor-service.js.map +1 -0
  23. package/dist/anchor.d.ts +123 -0
  24. package/dist/anchor.d.ts.map +1 -0
  25. package/dist/anchor.js +246 -0
  26. package/dist/anchor.js.map +1 -0
  27. package/dist/audit-hash.d.ts +4 -0
  28. package/dist/audit-hash.d.ts.map +1 -0
  29. package/dist/audit-hash.js +12 -0
  30. package/dist/audit-hash.js.map +1 -0
  31. package/dist/audit.d.ts +104 -0
  32. package/dist/audit.d.ts.map +1 -0
  33. package/dist/audit.js +391 -0
  34. package/dist/audit.js.map +1 -0
  35. package/dist/config.d.ts +273 -0
  36. package/dist/config.d.ts.map +1 -0
  37. package/dist/config.js +44 -0
  38. package/dist/config.js.map +1 -0
  39. package/dist/connectors/docs.d.ts +23 -0
  40. package/dist/connectors/docs.d.ts.map +1 -0
  41. package/dist/connectors/docs.js +140 -0
  42. package/dist/connectors/docs.js.map +1 -0
  43. package/dist/connectors/index.d.ts +10 -0
  44. package/dist/connectors/index.d.ts.map +1 -0
  45. package/dist/connectors/index.js +37 -0
  46. package/dist/connectors/index.js.map +1 -0
  47. package/dist/connectors/jira.d.ts +16 -0
  48. package/dist/connectors/jira.d.ts.map +1 -0
  49. package/dist/connectors/jira.js +67 -0
  50. package/dist/connectors/jira.js.map +1 -0
  51. package/dist/connectors/openapi.d.ts +28 -0
  52. package/dist/connectors/openapi.d.ts.map +1 -0
  53. package/dist/connectors/openapi.js +447 -0
  54. package/dist/connectors/openapi.js.map +1 -0
  55. package/dist/connectors/postgres.d.ts +17 -0
  56. package/dist/connectors/postgres.d.ts.map +1 -0
  57. package/dist/connectors/postgres.js +131 -0
  58. package/dist/connectors/postgres.js.map +1 -0
  59. package/dist/connectors/slack.d.ts +16 -0
  60. package/dist/connectors/slack.d.ts.map +1 -0
  61. package/dist/connectors/slack.js +65 -0
  62. package/dist/connectors/slack.js.map +1 -0
  63. package/dist/connectors/supabase_rest.d.ts +35 -0
  64. package/dist/connectors/supabase_rest.d.ts.map +1 -0
  65. package/dist/connectors/supabase_rest.js +153 -0
  66. package/dist/connectors/supabase_rest.js.map +1 -0
  67. package/dist/connectors/zion.d.ts +24 -0
  68. package/dist/connectors/zion.d.ts.map +1 -0
  69. package/dist/connectors/zion.js +76 -0
  70. package/dist/connectors/zion.js.map +1 -0
  71. package/dist/console.d.ts +30 -0
  72. package/dist/console.d.ts.map +1 -0
  73. package/dist/console.js +257 -0
  74. package/dist/console.js.map +1 -0
  75. package/dist/coverage.d.ts +100 -0
  76. package/dist/coverage.d.ts.map +1 -0
  77. package/dist/coverage.js +175 -0
  78. package/dist/coverage.js.map +1 -0
  79. package/dist/executor.d.ts +12 -0
  80. package/dist/executor.d.ts.map +1 -0
  81. package/dist/executor.js +77 -0
  82. package/dist/executor.js.map +1 -0
  83. package/dist/governance.d.ts +124 -0
  84. package/dist/governance.d.ts.map +1 -0
  85. package/dist/governance.js +977 -0
  86. package/dist/governance.js.map +1 -0
  87. package/dist/http.d.ts +48 -0
  88. package/dist/http.d.ts.map +1 -0
  89. package/dist/http.js +221 -0
  90. package/dist/http.js.map +1 -0
  91. package/dist/index.d.ts +3 -0
  92. package/dist/index.d.ts.map +1 -0
  93. package/dist/index.js +25 -0
  94. package/dist/index.js.map +1 -0
  95. package/dist/keys.d.ts +51 -0
  96. package/dist/keys.d.ts.map +1 -0
  97. package/dist/keys.js +174 -0
  98. package/dist/keys.js.map +1 -0
  99. package/dist/license.d.ts +35 -0
  100. package/dist/license.d.ts.map +1 -0
  101. package/dist/license.js +122 -0
  102. package/dist/license.js.map +1 -0
  103. package/dist/llm-gate.d.ts +17 -0
  104. package/dist/llm-gate.d.ts.map +1 -0
  105. package/dist/llm-gate.js +19 -0
  106. package/dist/llm-gate.js.map +1 -0
  107. package/dist/openapi_connector.d.ts +6 -0
  108. package/dist/openapi_connector.d.ts.map +1 -0
  109. package/dist/openapi_connector.js +145 -0
  110. package/dist/openapi_connector.js.map +1 -0
  111. package/dist/pseudonymize.d.ts +19 -0
  112. package/dist/pseudonymize.d.ts.map +1 -0
  113. package/dist/pseudonymize.js +25 -0
  114. package/dist/pseudonymize.js.map +1 -0
  115. package/dist/rate_limit.d.ts +41 -0
  116. package/dist/rate_limit.d.ts.map +1 -0
  117. package/dist/rate_limit.js +66 -0
  118. package/dist/rate_limit.js.map +1 -0
  119. package/dist/receipt.d.ts +161 -0
  120. package/dist/receipt.d.ts.map +1 -0
  121. package/dist/receipt.js +210 -0
  122. package/dist/receipt.js.map +1 -0
  123. package/dist/scripts/discover_schema.d.ts +2 -0
  124. package/dist/scripts/discover_schema.d.ts.map +1 -0
  125. package/dist/scripts/discover_schema.js +75 -0
  126. package/dist/scripts/discover_schema.js.map +1 -0
  127. package/dist/scripts/dogfood_prove.d.ts +2 -0
  128. package/dist/scripts/dogfood_prove.d.ts.map +1 -0
  129. package/dist/scripts/dogfood_prove.js +41 -0
  130. package/dist/scripts/dogfood_prove.js.map +1 -0
  131. package/dist/search_policy.d.ts +23 -0
  132. package/dist/search_policy.d.ts.map +1 -0
  133. package/dist/search_policy.js +79 -0
  134. package/dist/search_policy.js.map +1 -0
  135. package/dist/server.d.ts +29 -0
  136. package/dist/server.d.ts.map +1 -0
  137. package/dist/server.js +379 -0
  138. package/dist/server.js.map +1 -0
  139. package/dist/tokens.d.ts +14 -0
  140. package/dist/tokens.d.ts.map +1 -0
  141. package/dist/tokens.js +58 -0
  142. package/dist/tokens.js.map +1 -0
  143. package/dist/types.d.ts +132 -0
  144. package/dist/types.d.ts.map +1 -0
  145. package/dist/types.js +2 -0
  146. package/dist/types.js.map +1 -0
  147. package/docs/ARCHITECTURE.md +42 -0
  148. package/docs/CONSENT-BINDING-SPEC.md +136 -0
  149. package/docs/CONSENT-BINDING-SPEC.md.anchors.jsonl +1 -0
  150. package/docs/PRIOR-ART.md +213 -0
  151. package/docs/PRIOR-ART.md.anchors.jsonl +3 -0
  152. package/docs/RECEIPT-SPEC.md +301 -0
  153. package/docs/RECEIPT-SPEC.md.anchors.jsonl +1 -0
  154. package/docs/dogfood/2026-07-31-anchor.anchors.jsonl +1 -0
  155. package/docs/dogfood/2026-08-06-reconcile.md +140 -0
  156. package/docs/plans/2026-07-02-redteam-harness.md +416 -0
  157. package/docs/specs/2026-07-02-redteam-harness-design.md +90 -0
  158. package/docs/superpowers/TODO-gate1-f4.md +23 -0
  159. package/docs/superpowers/plans/2026-07-29-conarium-receipt-plan.md +200 -0
  160. package/docs/superpowers/plans/2026-07-29-katman0-kapanis-plan.md +231 -0
  161. package/docs/superpowers/plans/2026-07-31-per-user-identity.md +667 -0
  162. package/docs/superpowers/specs/2026-07-29-conarium-receipt-design.md +202 -0
  163. package/docs/superpowers/specs/2026-07-31-per-user-identity-design.md +144 -0
  164. package/docs/superpowers/specs/2026-08-01-coverage-proof-design.md +139 -0
  165. package/docs/superpowers/specs/2026-08-05-receipt-meta-provenance-design.md +116 -0
  166. package/examples/claude-desktop-config.json +9 -0
  167. package/examples/cursor-mcp-settings.json +10 -0
  168. package/package.json +99 -0
  169. package/scripts/audit-chain-check.mjs +119 -0
  170. package/scripts/conarium_sabah_brief.mjs +107 -0
  171. package/scripts/gen-test-vectors.mjs +193 -0
  172. package/scripts/pg-snapshot.sql +27 -0
  173. package/scripts/start-mcp-c1.mjs +70 -0
  174. package/test-vectors/001-single-receipt/receipts.jsonl +1 -0
  175. package/test-vectors/002-chain-of-three/receipts.jsonl +3 -0
  176. package/test-vectors/003-tampered-field/receipts.jsonl +1 -0
  177. package/test-vectors/004-prevhash-break/receipts.jsonl +2 -0
  178. package/test-vectors/005-seq-gap/receipts.jsonl +2 -0
  179. package/test-vectors/006-bad-signature/receipts.jsonl +1 -0
  180. package/test-vectors/007-schema-invalid/receipts.jsonl +1 -0
  181. package/test-vectors/008-unsigned-no-pubkey/receipts.jsonl +1 -0
  182. package/test-vectors/009-unsigned-but-pubkey-given/receipts.jsonl +1 -0
  183. package/test-vectors/README.md +92 -0
  184. package/test-vectors/expected-hashes.json +24 -0
  185. package/test-vectors/keys/vector-key.SECRET-TEST-ONLY.pem +6 -0
  186. package/test-vectors/keys/vector-key.pub.pem +3 -0
  187. package/test-vectors/keys/vector-key.pub.pem.keyid +1 -0
  188. package/test-vectors/manifest.json +95 -0
@@ -0,0 +1,441 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * conarium-reconcile — two-sided coverage: reconcile the database's own query
4
+ * counters against Conarium receipts over a time window.
5
+ *
6
+ * The question this answers is the one receipts alone cannot:
7
+ * "the database recorded query activity — is every bit of it receipted?"
8
+ * A pattern the DB counted but no receipt covers means access was RECORDED by
9
+ * the data source but NOT RECEIPTED by Conarium — the gateway may have been
10
+ * bypassed, or the receipt sink failed. The tool reports that fact; it does
11
+ * not claim intent.
12
+ *
13
+ * ZERO imports from src/. A third party must be able to run this single file
14
+ * without the Conarium package.
15
+ *
16
+ * Inputs:
17
+ * --before <snapshot.json> DB counter snapshot at window start
18
+ * --after <snapshot.json> DB counter snapshot at window end
19
+ * --receipts <receipts.jsonl>
20
+ *
21
+ * Snapshot schema (conarium-dbsnapshot/0.1) — produced by scripts/pg-snapshot.sql:
22
+ * { "v": "conarium-dbsnapshot/0.1", "ts": ISO8601, "role": "conarium_c2",
23
+ * "source": "pg_stat_statements", "entries": [ { "queryid": "…", "query": "…", "calls": 76 } ] }
24
+ *
25
+ * Honesty rules (same discipline as the coverage declaration):
26
+ * - Absence of a receipt is reported as "NOT RECEIPTED", never as proof of intent.
27
+ * - Matching is per query PATTERN and per TABLE, never per call count: one
28
+ * REST request may produce more than one SQL statement (PostgREST), so
29
+ * call counts and receipt counts are NOT compared 1:1.
30
+ * - A pattern whose target table cannot be determined is NOT silently
31
+ * cleared — it fails the reconciliation with its own message.
32
+ * - Receipt signatures are NOT checked here. Run conarium-verify first;
33
+ * this tool assumes the receipts file is already verified.
34
+ *
35
+ * Exit codes (documented in docs/RECEIPT-SPEC.md):
36
+ * 0 every DB query pattern in the window is covered by receipts
37
+ * 20 input invalid or window unreliable (schema error, role mismatch,
38
+ * counter regression — e.g. pg_stat_statements was reset mid-window)
39
+ * 40 unreconciled DB activity: at least one pattern the DB recorded has no
40
+ * covering receipt in the window (or could not be attributed to a table)
41
+ */
42
+ import { readFileSync, existsSync } from 'fs'
43
+
44
+ const RECONCILE_V = 'conarium-reconcile/0.1'
45
+ const SNAPSHOT_V = 'conarium-dbsnapshot/0.1'
46
+
47
+ // ─── snapshot loading ────────────────────────────────────────────────────────
48
+
49
+ function loadSnapshot(path, label) {
50
+ if (!existsSync(path)) {
51
+ return { error: `${label} snapshot not found: ${path}` }
52
+ }
53
+ let obj
54
+ try {
55
+ obj = JSON.parse(readFileSync(path, 'utf-8'))
56
+ } catch (err) {
57
+ return { error: `${label} snapshot is not valid JSON: ${err.message}` }
58
+ }
59
+ if (!obj || typeof obj !== 'object') return { error: `${label} snapshot: not an object` }
60
+ if (obj.v !== SNAPSHOT_V) {
61
+ return { error: `${label} snapshot: unsupported version ${JSON.stringify(obj.v)} (expected ${SNAPSHOT_V})` }
62
+ }
63
+ if (typeof obj.ts !== 'string' || Number.isNaN(Date.parse(obj.ts))) {
64
+ return { error: `${label} snapshot: ts missing or not ISO-8601` }
65
+ }
66
+ if (typeof obj.role !== 'string' || !obj.role) return { error: `${label} snapshot: missing role` }
67
+ if (typeof obj.source !== 'string' || !obj.source) return { error: `${label} snapshot: missing source` }
68
+ if (!Array.isArray(obj.entries)) return { error: `${label} snapshot: entries must be an array` }
69
+ const entries = new Map()
70
+ for (const e of obj.entries) {
71
+ if (!e || typeof e !== 'object') return { error: `${label} snapshot: entry is not an object` }
72
+ const qid = typeof e.queryid === 'number' ? String(e.queryid) : e.queryid
73
+ if (typeof qid !== 'string' || !qid) return { error: `${label} snapshot: entry missing queryid` }
74
+ if (typeof e.query !== 'string') return { error: `${label} snapshot: entry ${qid} missing query text` }
75
+ if (!Number.isInteger(e.calls) || e.calls < 0) {
76
+ return { error: `${label} snapshot: entry ${qid} calls must be a non-negative integer` }
77
+ }
78
+ if (entries.has(qid)) return { error: `${label} snapshot: duplicate queryid ${qid}` }
79
+ entries.set(qid, { queryid: qid, query: e.query, calls: e.calls })
80
+ }
81
+ return { snapshot: { v: obj.v, ts: obj.ts, role: obj.role, source: obj.source, entries } }
82
+ }
83
+
84
+ // ─── SQL pattern → table attribution ────────────────────────────────────────
85
+
86
+ /**
87
+ * Extract referenced relations from a (normalized) SQL pattern text.
88
+ * Returns [{schema|null, table}]. Best-effort by design: anything this cannot
89
+ * attribute is reported as UNATTRIBUTED and fails the reconciliation — it is
90
+ * never silently cleared.
91
+ */
92
+ export function extractTables(sql) {
93
+ const found = []
94
+ const seen = new Set()
95
+ // CTE adları (WITH x AS (…)) ilişki değildir — PostgREST her sorguyu
96
+ // `WITH pgrst_source AS (…) SELECT … FROM pgrst_source` diye sarar; CTE adı
97
+ // tablo sanılırsa her PostgREST deseni sahte "unreconciled" üretir.
98
+ const cteNames = new Set()
99
+ const cteRe = /("([^"]+)"|[a-z_][a-z0-9_$]*)\s+as\s*\(/gi
100
+ let c
101
+ while ((c = cteRe.exec(sql)) !== null) {
102
+ const name = c[2] !== undefined ? c[2] : c[1]
103
+ cteNames.add(name.toLowerCase())
104
+ }
105
+ const re = /\b(?:from|join|into|update)\s+(?:only\s+)?("([^"]+)"|[a-z_][a-z0-9_$]*)(?:\s*\.\s*("([^"]+)"|[a-z_][a-z0-9_$]*))?/gi
106
+ let m
107
+ while ((m = re.exec(sql)) !== null) {
108
+ const first = m[2] !== undefined ? m[2] : m[1]
109
+ const second = m[3] === undefined ? null : m[4] !== undefined ? m[4] : m[3]
110
+ let schema = null
111
+ let table
112
+ if (second !== null) {
113
+ schema = first
114
+ table = second
115
+ } else {
116
+ table = first
117
+ }
118
+ // `from (select …)` gives no name; regex already requires an identifier.
119
+ // Skip obvious keywords that can follow FROM in some dialects.
120
+ if (/^(select|values|lateral|unnest)$/i.test(table)) continue
121
+ if (schema === null && cteNames.has(table.toLowerCase())) continue
122
+ const key = `${schema ?? ''}.${table}`.toLowerCase()
123
+ if (seen.has(key)) continue
124
+ seen.add(key)
125
+ found.push({ schema: schema ? schema.toLowerCase() : null, table: table.toLowerCase() })
126
+ }
127
+ return found
128
+ }
129
+
130
+ const INFRA_SCHEMAS = new Set(['pg_catalog', 'information_schema'])
131
+ const INFRA_QUERY_RE = /^\s*(set\b|show\b|begin\b|commit\b|rollback\b|select\s+set_config\b|deallocate\b|discard\b)/i
132
+
133
+ /**
134
+ * Classify one DB pattern with a positive call delta.
135
+ * - 'infrastructure' session/catalog housekeeping (SET, pg_catalog, information_schema)
136
+ * - 'unattributed' no table could be determined — NOT cleared
137
+ * - 'data' touches at least one user relation
138
+ */
139
+ export function classifyPattern(query) {
140
+ if (INFRA_QUERY_RE.test(query)) return { kind: 'infrastructure', tables: [] }
141
+ const tables = extractTables(query)
142
+ if (tables.length === 0) return { kind: 'unattributed', tables: [] }
143
+ const userTables = tables.filter(
144
+ (t) => !(t.schema && INFRA_SCHEMAS.has(t.schema)) && !(t.schema === null && t.table.startsWith('pg_')),
145
+ )
146
+ if (userTables.length === 0) return { kind: 'infrastructure', tables }
147
+ return { kind: 'data', tables: userTables }
148
+ }
149
+
150
+ // ─── receipts ────────────────────────────────────────────────────────────────
151
+
152
+ function loadReceipts(path) {
153
+ if (!existsSync(path)) return { error: `receipts file not found: ${path}` }
154
+ const raw = readFileSync(path, 'utf-8').trim()
155
+ if (!raw) return { receipts: [] }
156
+ const receipts = []
157
+ const lines = raw.split('\n').filter(Boolean)
158
+ for (let i = 0; i < lines.length; i++) {
159
+ let r
160
+ try {
161
+ r = JSON.parse(lines[i])
162
+ } catch (err) {
163
+ return { error: `receipts line ${i + 1}: invalid JSON: ${err.message}` }
164
+ }
165
+ if (!r || typeof r !== 'object' || typeof r.ts !== 'string') {
166
+ return { error: `receipts line ${i + 1}: missing ts` }
167
+ }
168
+ receipts.push(r)
169
+ }
170
+ return { receipts }
171
+ }
172
+
173
+ /** Son nokta-parçası: "zion.customers" → "customers". Şema önekleri bağlayıcı farklı adlandırır. */
174
+ function normalizeObject(name) {
175
+ const parts = String(name).toLowerCase().split('.')
176
+ return parts[parts.length - 1]
177
+ }
178
+
179
+ /**
180
+ * Collect the set of tables the in-window receipts cover.
181
+ * Same attribution rule as src/coverage.ts computeCoverage:
182
+ * dataRefs[].object + describe_table's request.target. list_tables is schema
183
+ * listing, not data access. Receipts with no attributable object are counted —
184
+ * their presence makes any "not receipted" finding NOT definitive.
185
+ */
186
+ export function receiptCoverage(receipts, fromMs, toMs) {
187
+ const covered = new Set() // normalized table names
188
+ const coveredRaw = new Set() // raw object names for reporting
189
+ let inWindow = 0
190
+ let outOfWindow = 0
191
+ let unassigned = 0
192
+ for (const r of receipts) {
193
+ const t = Date.parse(r.ts)
194
+ if (Number.isNaN(t) || t < fromMs || t > toMs) {
195
+ outOfWindow++
196
+ continue
197
+ }
198
+ inWindow++
199
+ let hasObject = false
200
+ for (const ref of r.dataRefs || []) {
201
+ covered.add(normalizeObject(ref.object))
202
+ coveredRaw.add(String(ref.object))
203
+ hasObject = true
204
+ }
205
+ if (r.request?.tool === 'describe_table' && r.request?.target) {
206
+ covered.add(normalizeObject(r.request.target))
207
+ coveredRaw.add(String(r.request.target))
208
+ hasObject = true
209
+ }
210
+ if (!hasObject && (r.request?.tool === 'query' || r.request?.tool === 'search')) {
211
+ unassigned++
212
+ }
213
+ }
214
+ return { covered, coveredRaw, inWindow, outOfWindow, unassigned }
215
+ }
216
+
217
+ // ─── reconciliation core ─────────────────────────────────────────────────────
218
+
219
+ export function reconcile(before, after, receipts) {
220
+ if (before.role !== after.role) {
221
+ return { error: `role mismatch: before=${before.role}, after=${after.role}` }
222
+ }
223
+ if (before.source !== after.source) {
224
+ return { error: `source mismatch: before=${before.source}, after=${after.source}` }
225
+ }
226
+ const fromMs = Date.parse(before.ts)
227
+ const toMs = Date.parse(after.ts)
228
+ if (toMs <= fromMs) {
229
+ return { error: `window is empty or inverted: before.ts=${before.ts}, after.ts=${after.ts}` }
230
+ }
231
+
232
+ // Per-pattern call delta. A queryid new in `after` counts in full.
233
+ const deltas = []
234
+ for (const [qid, e] of after.entries) {
235
+ const prev = before.entries.get(qid)
236
+ const prevCalls = prev ? prev.calls : 0
237
+ if (e.calls < prevCalls) {
238
+ return {
239
+ error:
240
+ `counter regression on queryid ${qid} (before=${prevCalls}, after=${e.calls}) — ` +
241
+ `${after.source} was likely reset mid-window; the window is unreliable, take fresh snapshots`,
242
+ }
243
+ }
244
+ const delta = e.calls - prevCalls
245
+ if (delta > 0) deltas.push({ queryid: qid, query: e.query, delta })
246
+ }
247
+ // A queryid present before but absent after ALSO means a reset (eviction is
248
+ // possible under pressure, but silently assuming that would hide resets).
249
+ for (const [qid, e] of before.entries) {
250
+ if (!after.entries.has(qid)) {
251
+ return {
252
+ error:
253
+ `queryid ${qid} present in before but missing in after (calls=${e.calls}) — ` +
254
+ `${after.source} was likely reset or evicted mid-window; the window is unreliable`,
255
+ }
256
+ }
257
+ }
258
+
259
+ const cov = receiptCoverage(receipts, fromMs, toMs)
260
+
261
+ const reconciled = []
262
+ const unreconciled = []
263
+ const unattributed = []
264
+ const infrastructure = []
265
+ for (const d of deltas) {
266
+ const cls = classifyPattern(d.query)
267
+ if (cls.kind === 'infrastructure') {
268
+ infrastructure.push(d)
269
+ continue
270
+ }
271
+ if (cls.kind === 'unattributed') {
272
+ unattributed.push(d)
273
+ continue
274
+ }
275
+ const uncovered = cls.tables.filter((t) => !cov.covered.has(t.table))
276
+ if (uncovered.length === 0) {
277
+ reconciled.push({ ...d, tables: cls.tables.map((t) => t.table) })
278
+ } else {
279
+ unreconciled.push({ ...d, uncoveredTables: uncovered.map((t) => (t.schema ? `${t.schema}.${t.table}` : t.table)) })
280
+ }
281
+ }
282
+
283
+ return {
284
+ v: RECONCILE_V,
285
+ window: { start: before.ts, end: after.ts },
286
+ role: before.role,
287
+ source: before.source,
288
+ db: { patternsWithActivity: deltas.length, totalNewCalls: deltas.reduce((s, d) => s + d.delta, 0) },
289
+ receipts: {
290
+ inWindow: cov.inWindow,
291
+ outOfWindow: cov.outOfWindow,
292
+ unassigned: cov.unassigned,
293
+ coveredObjects: [...cov.coveredRaw].sort(),
294
+ },
295
+ reconciled,
296
+ unreconciled,
297
+ unattributed,
298
+ infrastructure,
299
+ }
300
+ }
301
+
302
+ // ─── CLI ─────────────────────────────────────────────────────────────────────
303
+
304
+ function usage(msg) {
305
+ if (msg) console.error(msg)
306
+ console.error(
307
+ 'Usage: conarium-reconcile --before <snapshot.json> --after <snapshot.json> --receipts <receipts.jsonl> [--json]',
308
+ )
309
+ }
310
+
311
+ function parseArgs(argv) {
312
+ const out = { before: null, after: null, receiptsPath: null, json: false }
313
+ const args = [...argv]
314
+ while (args.length) {
315
+ const a = args.shift()
316
+ if (a === '--before') {
317
+ out.before = args.shift() ?? null
318
+ if (!out.before) throw new Error('--before requires a path')
319
+ } else if (a === '--after') {
320
+ out.after = args.shift() ?? null
321
+ if (!out.after) throw new Error('--after requires a path')
322
+ } else if (a === '--receipts') {
323
+ out.receiptsPath = args.shift() ?? null
324
+ if (!out.receiptsPath) throw new Error('--receipts requires a path')
325
+ } else if (a === '--json') {
326
+ out.json = true
327
+ } else if (a === '--help' || a === '-h') {
328
+ usage()
329
+ process.exit(0)
330
+ } else {
331
+ throw new Error(`unexpected argument: ${a}`)
332
+ }
333
+ }
334
+ return out
335
+ }
336
+
337
+ function fail(code, message, jsonMode, extra = {}) {
338
+ console.error(message)
339
+ if (jsonMode) console.log(JSON.stringify({ ok: false, code, message, ...extra }))
340
+ process.exit(code)
341
+ }
342
+
343
+ function truncate(s, n = 110) {
344
+ const one = s.replace(/\s+/g, ' ').trim()
345
+ return one.length > n ? one.slice(0, n) + '…' : one
346
+ }
347
+
348
+ async function main(argv = process.argv.slice(2)) {
349
+ let opts
350
+ try {
351
+ opts = parseArgs(argv)
352
+ } catch (err) {
353
+ usage(err.message)
354
+ process.exit(20)
355
+ }
356
+ if (!opts.before || !opts.after || !opts.receiptsPath) {
357
+ usage('missing required flag (--before, --after and --receipts are all required)')
358
+ process.exit(20)
359
+ }
360
+
361
+ const b = loadSnapshot(opts.before, 'before')
362
+ if (b.error) fail(20, b.error, opts.json)
363
+ const a = loadSnapshot(opts.after, 'after')
364
+ if (a.error) fail(20, a.error, opts.json)
365
+ const rec = loadReceipts(opts.receiptsPath)
366
+ if (rec.error) fail(20, rec.error, opts.json)
367
+
368
+ const result = reconcile(b.snapshot, a.snapshot, rec.receipts)
369
+ if (result.error) fail(20, result.error, opts.json)
370
+
371
+ const problems = result.unreconciled.length + result.unattributed.length
372
+
373
+ if (opts.json) {
374
+ console.log(JSON.stringify({ ok: problems === 0, code: problems === 0 ? 0 : 40, ...result }))
375
+ } else {
376
+ console.log(
377
+ `reconcile window: ${result.window.start} → ${result.window.end} ` +
378
+ `(role ${result.role}, source ${result.source})`,
379
+ )
380
+ console.log(
381
+ `db: +${result.db.totalNewCalls} call(s) across ${result.db.patternsWithActivity} pattern(s) · ` +
382
+ `receipts in window: ${result.receipts.inWindow} · out of window: ${result.receipts.outOfWindow}`,
383
+ )
384
+ console.log(
385
+ 'note: matching is per pattern and per table, never per call count — one request may produce more than one statement',
386
+ )
387
+ console.error('note: receipt signatures are NOT checked here — run conarium-verify first')
388
+ if (result.infrastructure.length > 0) {
389
+ console.log(`infrastructure pattern(s) (session/catalog housekeeping, not data access): ${result.infrastructure.length}`)
390
+ for (const d of result.infrastructure) console.log(` ~ (+${d.delta}) ${truncate(d.query)}`)
391
+ }
392
+ for (const d of result.reconciled) {
393
+ console.log(` = (+${d.delta}) covered by receipt(s) for [${d.tables.join(', ')}]: ${truncate(d.query)}`)
394
+ }
395
+ if (result.receipts.unassigned > 0) {
396
+ console.warn(
397
+ `warning: ${result.receipts.unassigned} receipt(s) in the window could not be attributed to a table — ` +
398
+ `any "not receipted" finding below is NOT definitive`,
399
+ )
400
+ }
401
+ if (problems === 0) {
402
+ console.log('ok: every DB query pattern in the window is covered by receipts')
403
+ } else {
404
+ if (result.unreconciled.length > 0) {
405
+ console.error(
406
+ `UNRECONCILED: ${result.unreconciled.length} pattern(s) recorded by the database have no covering receipt in the window:`,
407
+ )
408
+ for (const d of result.unreconciled) {
409
+ console.error(` ! (+${d.delta}) table(s) [${d.uncoveredTables.join(', ')}]: ${truncate(d.query)}`)
410
+ }
411
+ }
412
+ if (result.unattributed.length > 0) {
413
+ console.error(
414
+ `UNATTRIBUTED: ${result.unattributed.length} pattern(s) could not be attributed to a table — not cleared:`,
415
+ )
416
+ for (const d of result.unattributed) console.error(` ? (+${d.delta}) ${truncate(d.query)}`)
417
+ }
418
+ console.error(
419
+ 'this means access was RECORDED by the database but NOT RECEIPTED by Conarium in this window — ' +
420
+ 'the gateway may have been bypassed, or the receipt sink failed. It does not by itself prove intent.',
421
+ )
422
+ }
423
+ }
424
+ // Literal çıkışlar bilerek ayrı: spec_exitcode_drift bekçisi sadece
425
+ // literal sayıları tarar, ternary içindeki kod görünmez kalırdı.
426
+ if (problems === 0) {
427
+ process.exit(0)
428
+ }
429
+ process.exit(40)
430
+ }
431
+
432
+ const isDirect =
433
+ process.argv[1] &&
434
+ (process.argv[1].endsWith('conarium-reconcile.mjs') || process.argv[1].endsWith('conarium-reconcile'))
435
+
436
+ if (isDirect) {
437
+ main().catch((err) => {
438
+ console.error(err)
439
+ process.exit(20)
440
+ })
441
+ }
@@ -0,0 +1,161 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * conarium-stamp — timestamp a document to OpenTimestamps.
4
+ *
5
+ * Receipts get anchored automatically. Documents — a specification, a policy
6
+ * file, a coverage declaration, a prior-art scan — do not, and a git commit date
7
+ * is not evidence: `git commit --date` accepts anything you type.
8
+ *
9
+ * This stamps the SHA-256 of a file to the OpenTimestamps calendars and writes a
10
+ * sidecar next to it. Upgrade later with `conarium-anchor-upgrade` to get the
11
+ * Bitcoin block height.
12
+ *
13
+ * What a stamp proves: the file existed, in exactly this form, no later than the
14
+ * anchored time. It does NOT prove the file is correct, nor that nobody wrote
15
+ * something similar earlier — only that ours is not backdated.
16
+ *
17
+ * Only the 32-byte digest leaves the machine. The file content never does.
18
+ *
19
+ * Usage:
20
+ * conarium-stamp <file> [--sidecar <path>] [--json]
21
+ *
22
+ * Exit codes (documented in docs/RECEIPT-SPEC.md):
23
+ * 0 stamped, sidecar written (state: pending until upgraded)
24
+ * 20 input invalid (file missing/unreadable, bad flag)
25
+ * 50 stamping failed (calendars unreachable or timed out)
26
+ */
27
+ import { createHash } from 'crypto'
28
+ import { readFileSync, existsSync, appendFileSync } from 'fs'
29
+ import { createRequire } from 'module'
30
+
31
+ const require = createRequire(import.meta.url)
32
+ const STAMP_TIMEOUT_MS = 30_000
33
+
34
+ function usage(msg) {
35
+ if (msg) console.error(msg)
36
+ console.error('Usage: conarium-stamp <file> [--sidecar <path>] [--json]')
37
+ }
38
+
39
+ function parseArgs(argv) {
40
+ const out = { target: null, sidecar: null, json: false }
41
+ const args = [...argv]
42
+ while (args.length) {
43
+ const a = args.shift()
44
+ if (a === '--sidecar') {
45
+ out.sidecar = args.shift() ?? null
46
+ if (!out.sidecar) throw new Error('--sidecar requires a path')
47
+ } else if (a === '--json') {
48
+ out.json = true
49
+ } else if (a === '--help' || a === '-h') {
50
+ usage()
51
+ process.exit(0)
52
+ } else if (a.startsWith('-')) {
53
+ throw new Error(`unknown flag: ${a}`)
54
+ } else if (!out.target) {
55
+ out.target = a
56
+ } else {
57
+ throw new Error(`unexpected argument: ${a}`)
58
+ }
59
+ }
60
+ return out
61
+ }
62
+
63
+ function loadOts() {
64
+ let mod = require('javascript-opentimestamps')
65
+ if (mod && mod.default) mod = mod.default
66
+ return mod
67
+ }
68
+
69
+ async function main(argv = process.argv.slice(2)) {
70
+ let opts
71
+ try {
72
+ opts = parseArgs(argv)
73
+ } catch (err) {
74
+ usage(err.message)
75
+ process.exit(20)
76
+ }
77
+ if (!opts.target) {
78
+ usage('missing <file>')
79
+ process.exit(20)
80
+ }
81
+ if (!existsSync(opts.target)) {
82
+ console.error(`file not found: ${opts.target}`)
83
+ process.exit(20)
84
+ }
85
+
86
+ let content
87
+ try {
88
+ content = readFileSync(opts.target)
89
+ } catch (err) {
90
+ console.error(`cannot read ${opts.target}: ${err.message}`)
91
+ process.exit(20)
92
+ }
93
+
94
+ const digest = createHash('sha256').update(content).digest()
95
+ const hash = `sha256:${digest.toString('hex')}`
96
+ const sidecarPath = opts.sidecar ?? `${opts.target}.anchors.jsonl`
97
+
98
+ let otsBase64
99
+ const submittedAt = new Date().toISOString()
100
+ try {
101
+ const mod = loadOts()
102
+ const detached = mod.DetachedTimestampFile.fromHash(new mod.Ops.OpSHA256(), digest)
103
+ await Promise.race([
104
+ mod.stamp(detached),
105
+ new Promise((_, reject) =>
106
+ setTimeout(() => reject(new Error(`stamp timed out after ${STAMP_TIMEOUT_MS}ms`)), STAMP_TIMEOUT_MS),
107
+ ),
108
+ ])
109
+ otsBase64 = Buffer.from(detached.serializeToBytes()).toString('base64')
110
+ } catch (err) {
111
+ console.error(`stamping failed: ${err.message}`)
112
+ process.exit(50)
113
+ }
114
+
115
+ // Same sidecar shape the receipt anchoring writes, so conarium-anchor-upgrade
116
+ // works on it unchanged.
117
+ //
118
+ // A revised document is stamped again and appended: the earlier row keeps proving
119
+ // the earlier revision existed, and the new row proves the current one. Sequence
120
+ // continues from what is already in the sidecar — two rows both claiming seq 1
121
+ // would misreport the order of revisions.
122
+ const priorRows = existsSync(sidecarPath)
123
+ ? readFileSync(sidecarPath, 'utf-8').split('\n').filter((l) => l.trim()).length
124
+ : 0
125
+ const record = {
126
+ seq: priorRows + 1,
127
+ hash,
128
+ log: 'opentimestamps',
129
+ ots: otsBase64,
130
+ state: 'pending',
131
+ submittedAt,
132
+ document: opts.target,
133
+ }
134
+ appendFileSync(sidecarPath, JSON.stringify(record) + '\n')
135
+
136
+ if (opts.json) {
137
+ console.log(JSON.stringify({ ok: true, code: 0, ...record, ots: `<${otsBase64.length} base64 chars>` }))
138
+ } else {
139
+ console.log(`ok: stamped ${opts.target}`)
140
+ console.log(` digest: ${hash}`)
141
+ console.log(` sidecar: ${sidecarPath} (${otsBase64.length} base64 chars)`)
142
+ console.log(` state: pending — Bitcoin confirmation takes hours;`)
143
+ console.log(` run conarium-anchor-upgrade ${sidecarPath} later for the block height`)
144
+ console.error(
145
+ 'note: a stamp proves this file existed in this exact form no later than the anchored time. ' +
146
+ 'It does not prove the file is correct, nor that no one published something similar earlier.',
147
+ )
148
+ }
149
+ process.exit(0)
150
+ }
151
+
152
+ const isDirect =
153
+ process.argv[1] &&
154
+ (process.argv[1].endsWith('conarium-stamp.mjs') || process.argv[1].endsWith('conarium-stamp'))
155
+
156
+ if (isDirect) {
157
+ main().catch((err) => {
158
+ console.error(err)
159
+ process.exit(20)
160
+ })
161
+ }