@conarium-ai/core 0.3.6 → 0.3.8

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,57 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.8 - the patterns beside a join that a Receipt names in part are decided together
4
+
5
+ 0.3.7 said its comparison errs toward `indeterminate` for a pattern over
6
+ several objects that a Receipt names in part. That was not so for the patterns
7
+ beside it. With a bound of 1, Receipts naming customers and orders, customers,
8
+ and orders, two statements of a customers-orders join and one on orders, 0.3.7
9
+ reported the orders pattern `matched`. Covering both join statements, one with
10
+ the join Receipt and one with the other two, leaves the orders statement
11
+ uncovered and covers as many statements as any assignment can, so the orders
12
+ pattern is `indeterminate`. In 0.3.8 the patterns that share a Receipt with
13
+ such a pattern are decided together: if any of their statements is left
14
+ uncovered, each of them not over the bound on its own is `indeterminate`. The
15
+ conformance case `v2-multiplicity-join-neighbour` is added; it fails on 0.3.7.
16
+ The `/1` JSON body and the exit codes do not change.
17
+
18
+ ## 0.3.7 - a multiplicity bound counts per Receipt
19
+
20
+ `multiplicity.maxStatementsPerReceipt` is documented as how many source
21
+ statements one Receipt may cover, and issue #161 reported that the `/2` result
22
+ compared it with one pattern's statement count, whatever the number of
23
+ Receipts. Three Receipts, three statements and a bound of 1 reported
24
+ `multiplicity-exceeded`. Two patterns of one statement each against one Receipt
25
+ were both `matched`, which erred the other way.
26
+
27
+ A Receipt's bound is now one budget, however many objects the Receipt names,
28
+ and the patterns whose objects all have a Receipt in the Window draw on the
29
+ in-window Receipts together. A statement is covered by one Receipt that names
30
+ all of its pattern's objects or, when none does, by a Receipt for each object.
31
+ Of the patterns that draw, one whose statements are more than bound × the
32
+ in-window Receipts naming one of its objects is `observed-without-receipt`
33
+ with reason `multiplicity-exceeded`, as before, and carries
34
+ `multiplicity: { bound, object, receipts, statements }`. The statements of the
35
+ patterns that draw, that one's included, are then assigned to Receipts as a
36
+ maximum flow. Any other pattern that draws and that some maximum assignment
37
+ leaves with a statement uncovered is `indeterminate` with the new reason
38
+ `multiplicity-shared`, and carries `multiplicity: { bound, objects, receipts,
39
+ statements }` for the patterns it competes with. One Receipt that names
40
+ customers and orders, at a bound of 1, admits one of a customers statement and
41
+ an orders statement, not both. Two cases err toward `indeterminate`;
42
+ `LIMITATIONS.md` names them.
43
+
44
+ A boundary item's `multiplicity` gains `object` and `receipts`, and
45
+ `exceededIfAdmitted` now counts every Receipt with a readable timestamp that
46
+ names the object: two Receipts just outside the Window at a bound of 1 admit
47
+ two statements. Its
48
+ outcome stays `indeterminate`, as draft-07 requires.
49
+
50
+ This changes which `/2` items are `matched`. The `/1` JSON body and the exit
51
+ codes do not change. Three conformance cases are added,
52
+ `v2-multiplicity-per-receipt`, `v2-multiplicity-shared` and
53
+ `v2-multiplicity-one-receipt-two-objects`.
54
+
3
55
  ## 0.3.6 - a boundary item shows its size; the sink lock error says what resolves it
4
56
 
5
57
  A pattern uncovered only by the window boundary is `indeterminate`, and
package/LIMITATIONS.md CHANGED
@@ -308,13 +308,34 @@ statement was itself receipted. `--json-v2` prints a separate
308
308
  as `/2`. Without a Mapping Profile the `/2` object leaves multiplicity-bound
309
309
  items `indeterminate` rather than treating one receipt as a bound of one.
310
310
 
311
- A declared multiplicity bound is compared with one pattern's statement count in
312
- the window. The number of receipts naming the pattern's objects does not raise
313
- it, whatever the field name `maxStatementsPerReceipt` suggests: three receipts,
314
- three statements and a bound of 1 report `multiplicity-exceeded`. Statements of
315
- separate patterns are not added together against one receipt either. `/2` does
316
- not change the exit codes, so a run whose `/2` outcome is `exceptions` can still
317
- exit 0. A check on this channel reads `outcome`, not only the exit code.
311
+ A declared multiplicity bound is how many statements one receipt may cover,
312
+ however many objects the receipt names. A statement is covered by one receipt
313
+ in the window that names all of its pattern's objects or, when none names them
314
+ all, by a receipt for each object. The patterns whose objects all have a
315
+ receipt in the window draw on those receipts together; a pattern with an
316
+ object no receipt in the window names takes its outcome from that object and
317
+ draws on none. Of the patterns that draw, one whose statements are more than
318
+ bound × the receipts in the window that name one of its objects is
319
+ `observed-without-receipt` with reason `multiplicity-exceeded`. Any other
320
+ pattern that draws, whose statements the receipts cannot be shown to cover
321
+ beside the patterns that draw on the same receipts, is `indeterminate` with reason `multiplicity-shared`, because the
322
+ evidence does not say which statements the receipts covered. The comparison
323
+ is approximate for a pattern that draws, over several objects, when a receipt
324
+ in the window names one of its objects but not all of them. If some receipt in the window
325
+ names the pattern whole, it draws only on the receipts that name it whole, even
326
+ when the others would cover the rest. If none does, it counts a receipt that
327
+ names two of its objects once for each, unless every receipt that names one of
328
+ the two names the other. Either way, a pattern beside it could look covered
329
+ when another assignment would leave it short. So every pattern that draws and
330
+ shares a receipt in the window with such a pattern, directly or through other
331
+ patterns that draw, is decided together with it: if any of their statements is left uncovered,
332
+ each of them not over the bound on its own is `indeterminate`, even one that a
333
+ closer count would show covered. The comparison errs only toward
334
+ `indeterminate`. Receipts outside the window do not count toward this comparison, even
335
+ when one of them would cover the shortfall: such an item is decided by the
336
+ in-window receipts alone, not reported as a boundary item. `/2` does not change the exit
337
+ codes, so a run whose `/2` outcome is `exceptions` can still exit 0. A check on
338
+ this channel reads `outcome`, not only the exit code.
318
339
 
319
340
  ## Reconciliation cannot tell a trailing clock from a late receipt
320
341
  <!-- s: reconcile-trailing-clock -->
@@ -326,9 +347,9 @@ reported as `indeterminate` (exit 41) rather than as unreceipted access,
326
347
  because this tool has no way to know which of the two happened. That is a
327
348
  limit, not a verdict: 41 is a failure and the run does not pass, but nothing
328
349
  is proven either way. Under a declared bound the `/2` item says whether the
329
- statement count exceeds it even if the receipt were admitted
330
- (`multiplicity.exceededIfAdmitted`). The outcome does not change: the item stays
331
- `indeterminate`, and `false` is not a pass.
350
+ statement count exceeds it even if every receipt naming its objects were
351
+ admitted (`multiplicity.exceededIfAdmitted`). The outcome does not change: the
352
+ item stays `indeterminate`, and `false` is not a pass.
332
353
 
333
354
  The exculpation is bounded by the window's own length — an offset larger than
334
355
  the window cannot be a boundary artefact, and the report says so instead of
package/LIMITATIONS.tr.md CHANGED
@@ -304,13 +304,37 @@ havuzu, ORM). 1:1 kuralı böyle her kurulumda sahte "kapsanmamış etkinlik"
304
304
  `/2` diye okunmaz. Mapping Profile yoksa `/2` çokluğa bağlı kalemleri
305
305
  `matched` saymaz, `indeterminate` bırakır.
306
306
 
307
- Beyan edilen çokluk sınırı tek desenin penceredeki ifade sayısıyla kıyaslanır.
308
- Alanın adı `maxStatementsPerReceipt` olsa da desenin nesnelerini adlandıran
309
- makbuz sayısı sınırı artırmaz: üç makbuz, üç ifade ve 1 sınırı
310
- `multiplicity-exceeded` verir. Ayrı desenlerin ifadeleri de tek makbuza karşı
311
- toplanmaz. `/2` çıkış kodlarını değiştirmez; bu yüzden `/2` sonucu `exceptions`
312
- olan bir koşu yine 0 ile çıkabilir. Bu kanalı kullanan bir denetim `outcome`
313
- alanını okur, yalnız çıkış koduna bakmaz.
307
+ Beyan edilen çokluk sınırı, bir makbuzun kaç ifadeyi karşılayabileceğidir;
308
+ makbuzun kaç nesne adlandırdığı bunu değiştirmez. Bir ifadeyi, pencere içinde
309
+ deseninin bütün nesnelerini adlandıran tek bir makbuz karşılar; hiçbiri hepsini
310
+ adlandırmıyorsa her nesne için bir makbuz karşılar. Bütün nesneleri pencere
311
+ içinde bir makbuzla adlandırılan desenler bu makbuzlardan birlikte pay alır;
312
+ pencere içinde hiçbir makbuzun adlandırmadığı bir nesnesi olan desen sonucunu o
313
+ nesneden alır ve bu makbuzlardan pay almaz. Pay alan desenlerden ifadeleri,
314
+ nesnelerinden birini pencere içinde adlandıran makbuzların sınır katından
315
+ fazla olan desen `observed-without-receipt` olur, gerekçesi
316
+ `multiplicity-exceeded`. Pay alan ve ifadelerinin, aynı makbuzlardan pay alan
317
+ desenlerin yanında makbuzlarca karşılandığı gösterilemeyen başka her desen
318
+ `indeterminate` olur, gerekçesi `multiplicity-shared`; çünkü kanıt, makbuzların hangi ifadeleri karşıladığını
319
+ söylemez. Pay alan ve birden çok nesneli bir desende, pencere içindeki bir
320
+ makbuz nesnelerinden birini adlandırıp hepsini adlandırmıyorsa kıyas
321
+ yaklaşıktır.
322
+ Deseni pencere içinde bütünüyle adlandıran bir makbuz varsa desen yalnız onu
323
+ bütünüyle adlandıran makbuzlardan pay alır, ötekiler kalanı karşılayacak olsa
324
+ bile. Yoksa iki nesnesini adlandıran bir makbuzu her biri için ayrı sayar; o
325
+ iki nesneden birini adlandıran her makbuz ötekini de adlandırıyorsa saymaz. İki
326
+ durumda da yanındaki bir desen, başka bir atamada açıkta kalacakken karşılanmış
327
+ görünebilir. Bu yüzden pay alan ve böyle bir desenle pencere içinde doğrudan ya
328
+ da pay alan başka desenler üzerinden makbuz paylaşan her desen onunla birlikte
329
+ karara bağlanır:
330
+ ifadelerinden biri açıkta kalırsa, tek başına sınırı aşmayan her biri
331
+ `indeterminate` olur, daha yakın bir sayımın karşılanmış göstereceği bir desen
332
+ bile. Kıyas yalnız `indeterminate` yönüne yanılır. Pencere dışındaki makbuzlar bu
333
+ kıyasa girmez, açığı kapatacak olsalar bile: böyle bir kalem yalnız pencere
334
+ içindeki makbuzlarla karara bağlanır, sınır kalemi olarak raporlanmaz. `/2` çıkış kodlarını
335
+ değiştirmez; bu yüzden `/2` sonucu `exceptions` olan bir koşu yine 0 ile
336
+ çıkabilir. Bu kanalı kullanan bir denetim `outcome` alanını okur, yalnız çıkış
337
+ koduna bakmaz.
314
338
 
315
339
  ## OpenTimestamps istemcisi
316
340
  <!-- s: ots-client -->
@@ -338,8 +362,8 @@ gateway'den geliyor. Yani sınıra iki ayrı saat karar veriyor. Bir deseni
338
362
  kapsayacak olan makbuz pencerenin dışına düşerse sonuç `indeterminate` olur
339
363
  (çıkış 41) — "makbuzsuz erişim" denmez, çünkü araç ikisinden hangisinin olduğunu
340
364
  bilemez. Bu bir hüküm değil, bir sınır: 41 başarısızlıktır, koşu geçmez, ama
341
- hiçbir yön kanıtlanmış olmaz. Sınır beyan edilmişse `/2` kalemi, makbuz kabul
342
- edilse bile ifade sayısının sınırı aşıp aşmadığını yazar
365
+ hiçbir yön kanıtlanmış olmaz. Sınır beyan edilmişse `/2` kalemi, nesnelerini
366
+ adlandıran her makbuz kabul edilse bile ifade sayısının sınırı aşıp aşmadığını yazar
343
367
  (`multiplicity.exceededIfAdmitted`). Sonuç değişmez, kalem yine `indeterminate`
344
368
  kalır; `false` değeri de geçti anlamına gelmez.
345
369
 
@@ -283,6 +283,255 @@ export function outsideBoundaryCoverage(receipts, fromMs, toMs) {
283
283
  return byTable
284
284
  }
285
285
 
286
+ /**
287
+ * How many Receipts name each object: those in the window, and all of them.
288
+ * A Receipt that names one object twice is one Receipt. Same attribution rule
289
+ * as receiptCoverage. A Receipt whose timestamp does not parse is in neither
290
+ * count, because no reading of the clock admits it.
291
+ *
292
+ * `groups` holds the in-window Receipts by the set of objects they name.
293
+ * Receipts that name the same objects are interchangeable against a bound, so
294
+ * one group stands for all of them.
295
+ */
296
+ export function namingReceiptCounts(receipts, fromMs, toMs) {
297
+ const inWindow = new Map()
298
+ const all = new Map()
299
+ const groups = new Map()
300
+ for (const r of receipts) {
301
+ const t = Date.parse(r.ts)
302
+ if (Number.isNaN(t)) continue
303
+ const named = new Set()
304
+ for (const ref of r.dataRefs || []) if (ref.object) named.add(normalizeObject(ref.object))
305
+ if (r.request?.tool === 'describe_table' && r.request?.target) named.add(normalizeObject(r.request.target))
306
+ const inside = t >= fromMs && t <= toMs
307
+ for (const key of named) {
308
+ all.set(key, (all.get(key) ?? 0) + 1)
309
+ if (inside) inWindow.set(key, (inWindow.get(key) ?? 0) + 1)
310
+ }
311
+ if (inside && named.size > 0) {
312
+ const objects = [...named].sort()
313
+ const key = objects.join('\u0000')
314
+ const g = groups.get(key)
315
+ if (g) g.count += 1
316
+ else groups.set(key, { objects, count: 1 })
317
+ }
318
+ }
319
+ return { inWindow, all, groups: [...groups.values()] }
320
+ }
321
+
322
+ /**
323
+ * Maximum flow (Dinic) over integer capacities. `reachable()` after `run()` is
324
+ * the set of nodes reachable from the source in the residual graph: the same
325
+ * set for every maximum flow.
326
+ */
327
+ class FlowNetwork {
328
+ constructor(n) {
329
+ this.head = new Array(n).fill(-1)
330
+ this.to = []
331
+ this.cap = []
332
+ this.next = []
333
+ }
334
+
335
+ add(u, v, c) {
336
+ for (const [a, b, k] of [[u, v, c], [v, u, 0]]) {
337
+ this.to.push(b)
338
+ this.cap.push(k)
339
+ this.next.push(this.head[a])
340
+ this.head[a] = this.to.length - 1
341
+ }
342
+ }
343
+
344
+ levels(s) {
345
+ const level = new Array(this.head.length).fill(-1)
346
+ level[s] = 0
347
+ const queue = [s]
348
+ for (let i = 0; i < queue.length; i++) {
349
+ const u = queue[i]
350
+ for (let e = this.head[u]; e !== -1; e = this.next[e]) {
351
+ if (this.cap[e] > 0 && level[this.to[e]] < 0) {
352
+ level[this.to[e]] = level[u] + 1
353
+ queue.push(this.to[e])
354
+ }
355
+ }
356
+ }
357
+ return level
358
+ }
359
+
360
+ run(s, t) {
361
+ let total = 0
362
+ for (;;) {
363
+ const level = this.levels(s)
364
+ if (level[t] < 0) return total
365
+ const it = [...this.head]
366
+ const push = (u, f) => {
367
+ if (u === t) return f
368
+ for (; it[u] !== -1; it[u] = this.next[it[u]]) {
369
+ const e = it[u]
370
+ const v = this.to[e]
371
+ if (this.cap[e] > 0 && level[v] === level[u] + 1) {
372
+ const got = push(v, Math.min(f, this.cap[e]))
373
+ if (got > 0) {
374
+ this.cap[e] -= got
375
+ this.cap[e ^ 1] += got
376
+ return got
377
+ }
378
+ }
379
+ }
380
+ return 0
381
+ }
382
+ for (let f = push(s, Infinity); f > 0; f = push(s, Infinity)) total += f
383
+ }
384
+ }
385
+
386
+ reachable(s) {
387
+ const level = this.levels(s)
388
+ return (u) => level[u] >= 0
389
+ }
390
+ }
391
+
392
+ /**
393
+ * Which reconciled patterns the in-window Receipts can be shown to cover under
394
+ * a bound of `max` statements per Receipt.
395
+ *
396
+ * A statement is covered by one Receipt that names all of its pattern's
397
+ * objects or by one Receipt for each object; a Receipt covers at most `max`
398
+ * statements. Every reconciled pattern draws on the Receipts, including one
399
+ * over the bound on its own, because its statements were observed. A pattern
400
+ * is shared when some maximum assignment leaves one of its statements
401
+ * uncovered: the evidence does not say which statements the Receipts covered.
402
+ * The rest are covered in every maximum assignment.
403
+ *
404
+ * The flow is exact except for a pattern over several objects that a Receipt
405
+ * names in part (rough). Where one draws, the patterns that share Receipts with
406
+ * it are all shared unless the flow covers every one of their statements, so
407
+ * the result errs only toward shared.
408
+ *
409
+ * A shared pattern's `group` is the patterns and Receipt groups it competes
410
+ * with: their statements are more than those Receipts admit, or, for a pattern
411
+ * shared only beside a rough one, all the patterns taken together with it.
412
+ */
413
+ export function boundAssignment(reconciled, groups, max) {
414
+ const S = 0
415
+ const T = 1
416
+ const groupNode = (gi) => 2 + gi
417
+ let next = 2 + groups.length
418
+ const nodes = [] // { pattern, demand, targets }
419
+ // The groups a pattern can draw on in fact: every one that names one of its
420
+ // objects. A pattern over several objects that one of them names without the
421
+ // rest is drawn on fewer, or on some twice, so the assignment below only
422
+ // approximates it (rough).
423
+ const reach = new Map()
424
+ const rough = new Set()
425
+ for (const [pi, d] of reconciled.entries()) {
426
+ const tables = [...new Set(d.tables)]
427
+ const naming = groups.flatMap((g, gi) => (tables.some((t) => g.objects.includes(t)) ? [gi] : []))
428
+ reach.set(pi, naming)
429
+ if (tables.length > 1 && naming.some((gi) => !tables.every((t) => groups[gi].objects.includes(t)))) rough.add(pi)
430
+ }
431
+ for (const [pi, d] of reconciled.entries()) {
432
+ const tables = [...new Set(d.tables)]
433
+ const full = groups.flatMap((g, gi) => (tables.every((t) => g.objects.includes(t)) ? [gi] : []))
434
+ if (full.length > 0) {
435
+ nodes.push({ pattern: pi, objects: tables, demand: d.delta, targets: full })
436
+ continue
437
+ }
438
+ // Objects named by exactly the same Receipt groups are covered by one
439
+ // Receipt per statement, so they share a node.
440
+ const byTargets = new Map()
441
+ for (const t of tables) {
442
+ const targets = groups.flatMap((g, gi) => (g.objects.includes(t) ? [gi] : []))
443
+ const key = targets.join(',')
444
+ if (byTargets.has(key)) byTargets.get(key).objects.push(t)
445
+ else byTargets.set(key, { pattern: pi, objects: [t], demand: d.delta, targets })
446
+ }
447
+ nodes.push(...byTargets.values())
448
+ }
449
+ const net = new FlowNetwork(next + nodes.length)
450
+ for (const [gi, g] of groups.entries()) net.add(groupNode(gi), T, g.count * max)
451
+ for (const n of nodes) {
452
+ n.id = next++
453
+ net.add(S, n.id, n.demand)
454
+ for (const gi of n.targets) net.add(n.id, groupNode(gi), n.demand)
455
+ }
456
+ net.run(S, T)
457
+ const inS = net.reachable(S)
458
+
459
+ // Groups of competing patterns: the nodes reachable from the source,
460
+ // connected through the edges between pattern and Receipt group nodes.
461
+ const parent = new Map()
462
+ const find = (x) => (parent.get(x) === x ? x : (parent.set(x, find(parent.get(x))), parent.get(x)))
463
+ const join = (a, b) => parent.set(find(a), find(b))
464
+ for (const n of nodes) {
465
+ if (!inS(n.id)) continue
466
+ if (!parent.has(n.id)) parent.set(n.id, n.id)
467
+ for (const gi of n.targets) {
468
+ const g = groupNode(gi)
469
+ if (!parent.has(g)) parent.set(g, g)
470
+ join(n.id, g)
471
+ }
472
+ }
473
+ const byRoot = new Map()
474
+ for (const n of nodes) {
475
+ if (!inS(n.id)) continue
476
+ const root = find(n.id)
477
+ if (!byRoot.has(root)) byRoot.set(root, { patterns: new Set(), objects: new Set(), groups: new Set() })
478
+ const c = byRoot.get(root)
479
+ c.patterns.add(n.pattern)
480
+ for (const o of n.objects) c.objects.add(o)
481
+ for (const gi of n.targets) c.groups.add(gi)
482
+ }
483
+ // A pattern covered one Receipt per object can sit in two groups; it reports
484
+ // the one furthest over the bound.
485
+ const shared = new Map()
486
+ const over = (g) => g.statements - g.receipts * max
487
+ for (const c of byRoot.values()) {
488
+ const group = {
489
+ objects: [...c.objects].sort(),
490
+ receipts: [...c.groups].reduce((sum, gi) => sum + groups[gi].count, 0),
491
+ statements: [...c.patterns].reduce((sum, pi) => sum + reconciled[pi].delta, 0),
492
+ }
493
+ for (const pi of c.patterns) if (!shared.has(pi) || over(group) > over(shared.get(pi))) shared.set(pi, group)
494
+ }
495
+
496
+ // Where a rough pattern draws, the assignment can leave a neighbour covered
497
+ // that another maximum assignment would not. So when the patterns that share
498
+ // Receipts with a rough pattern are not all covered, none of them is shown
499
+ // covered. When they are all covered, the assignment is a real one, and every
500
+ // maximum assignment covers them all.
501
+ const all = new Map()
502
+ const findAll = (x) => (all.get(x) === x ? x : (all.set(x, findAll(all.get(x))), all.get(x)))
503
+ const unite = (a, b) => {
504
+ for (const x of [a, b]) if (!all.has(x)) all.set(x, x)
505
+ all.set(findAll(a), findAll(b))
506
+ }
507
+ const patternKey = (pi) => `p${pi}`
508
+ for (const [pi] of reconciled.entries()) {
509
+ unite(patternKey(pi), patternKey(pi))
510
+ for (const gi of reach.get(pi)) unite(patternKey(pi), `g${gi}`)
511
+ }
512
+ const components = new Map()
513
+ for (const [pi] of reconciled.entries()) {
514
+ const root = findAll(patternKey(pi))
515
+ if (!components.has(root)) components.set(root, { patterns: new Set(), objects: new Set(), groups: new Set(), short: false, rough: false })
516
+ const c = components.get(root)
517
+ c.patterns.add(pi)
518
+ for (const t of reconciled[pi].tables || []) c.objects.add(t)
519
+ for (const gi of reach.get(pi)) c.groups.add(gi)
520
+ if (rough.has(pi)) c.rough = true
521
+ }
522
+ for (const n of nodes) if (inS(n.id)) components.get(findAll(patternKey(n.pattern))).short = true
523
+ for (const c of components.values()) {
524
+ if (!c.rough || !c.short) continue
525
+ const group = {
526
+ objects: [...c.objects].sort(),
527
+ receipts: [...c.groups].reduce((sum, gi) => sum + groups[gi].count, 0),
528
+ statements: [...c.patterns].reduce((sum, pi) => sum + reconciled[pi].delta, 0),
529
+ }
530
+ for (const pi of c.patterns) if (!shared.has(pi)) shared.set(pi, group)
531
+ }
532
+ return shared
533
+ }
534
+
286
535
  /**
287
536
  * Receipts in the window that name an object the database counters did not
288
537
  * increment. Distinct from `unassigned` (receipt named nothing).
@@ -424,7 +673,7 @@ export function reconcile(before, after, receipts, opts = {}) {
424
673
  }
425
674
  const unobserved = unobservedReceipts(receipts, fromMs, toMs, observedTables)
426
675
 
427
- return {
676
+ const out = {
428
677
  v: RECONCILE_V,
429
678
  window: { start: before.ts, end: after.ts },
430
679
  role: before.role,
@@ -449,6 +698,10 @@ export function reconcile(before, after, receipts, opts = {}) {
449
698
  infrastructure,
450
699
  unobserved,
451
700
  }
701
+ // Read by the /2 projection only. Not enumerable, so the /1 body, which is a
702
+ // compatibility contract, does not change shape.
703
+ Object.defineProperty(out, 'namingReceipts', { value: namingReceiptCounts(receipts, fromMs, toMs) })
704
+ return out
452
705
  }
453
706
 
454
707
  // ─── /2 projection ───────────────────────────────────────────────────────────
@@ -572,6 +825,21 @@ function infraRuleId(query) {
572
825
  return INFRA_QUERY_RE.test(query) ? 'infra-query' : 'infra-schema'
573
826
  }
574
827
 
828
+ /**
829
+ * What admitting every Receipt that names a boundary item's objects would
830
+ * settle against a declared bound. Each statement of the pattern touches every
831
+ * object it names, so the object with the fewest naming Receipts binds. This
832
+ * is the most generous reading of the clock: `exceededIfAdmitted: true` holds
833
+ * however the boundary is read.
834
+ */
835
+ export function boundaryMultiplicity(d, naming, max) {
836
+ const tables = [...new Set(classifyPattern(d.query).tables.map((t) => t.table))]
837
+ const count = (t) => naming.all.get(t) ?? 0
838
+ const object = tables.reduce((a, t) => (count(t) < count(a) ? t : a))
839
+ const receipts = count(object)
840
+ return { bound: max, object, receipts, statements: d.delta, exceededIfAdmitted: d.delta > receipts * max }
841
+ }
842
+
575
843
  /**
576
844
  * Project a /1 reconcile() result onto coverage-reconciliation/2.
577
845
  * Does not change /1 fields or exit codes.
@@ -625,40 +893,72 @@ export function projectResultV2(result, ctx) {
625
893
  }
626
894
 
627
895
  const max = profile?.maxStatementsPerReceipt ?? null
896
+ const naming = result.namingReceipts
897
+ if (max != null && !naming) {
898
+ throw new Error('projectResultV2: the result carries no receipt counts; pass the value reconcile() returned')
899
+ }
628
900
 
629
901
  // The temporal rule keeps a boundary item indeterminate whatever its size, so
630
902
  // the outcome alone shows 1 statement and 10,000 as the same finding. The item
631
- // carries the objects and, under a declared bound, the same comparison the
632
- // reconciled branch makes, so a reader sees what admitting the receipt would
633
- // and would not settle.
903
+ // carries the objects and, under a declared bound, what admitting every
904
+ // Receipt that names them would and would not settle.
634
905
  for (const d of result.indeterminate) {
635
906
  push('indeterminate', {
636
907
  pattern: patternDigest(d.query),
637
908
  reason: 'window-boundary',
638
909
  requiredSkewMs: d.requiredSkewMs,
639
910
  objects: d.uncoveredTables,
640
- ...(max != null
641
- ? { multiplicity: { bound: max, statements: d.delta, exceededIfAdmitted: d.delta > max } }
642
- : {}),
911
+ ...(max != null ? { multiplicity: boundaryMultiplicity(d, naming, max) } : {}),
643
912
  })
644
913
  }
645
914
 
646
- for (const d of result.reconciled) {
915
+ // The bound is how many statements one Receipt may cover. A Receipt names
916
+ // objects, not patterns, and its bound is one budget however many objects it
917
+ // names. Only patterns whose objects all have an in-window Receipt draw. A
918
+ // pattern with an unnamed object is decided by that object, and counting its
919
+ // statements here would let a bypass on one object turn a receipted neighbour
920
+ // into a finding. A pattern over the bound on its own, against the Receipts
921
+ // that name one of its objects, is observed-without-receipt. A pattern that
922
+ // fits on its own but that the Receipts cannot be shown to cover beside its
923
+ // neighbours is indeterminate: the evidence does not say which statements
924
+ // the Receipts covered (boundAssignment).
925
+ const receiptsIn = (t) => naming?.inWindow.get(t) ?? 0
926
+ const excess = (t, statements) => statements - receiptsIn(t) * max
927
+ const worst = (tables, statementsOf) =>
928
+ tables.reduce((a, t) => (excess(t, statementsOf(t)) > excess(a, statementsOf(a)) ? t : a))
929
+ const shared = max != null ? boundAssignment(result.reconciled, naming.groups, max) : new Map()
930
+
931
+ for (const [pi, d] of result.reconciled.entries()) {
647
932
  if (max == null) {
648
933
  push('indeterminate', {
649
934
  pattern: patternDigest(d.query),
650
935
  reason: 'multiplicity-undeclared',
651
936
  objects: d.tables || [],
652
937
  })
653
- } else if (d.delta <= max) {
654
- counts.matched += 1
655
- } else {
938
+ continue
939
+ }
940
+ const tables = [...new Set(d.tables)]
941
+ const alone = worst(tables, () => d.delta)
942
+ if (excess(alone, d.delta) > 0) {
656
943
  push('observed-without-receipt', {
657
944
  pattern: patternDigest(d.query),
658
945
  objects: d.tables || [],
659
946
  reason: 'multiplicity-exceeded',
947
+ multiplicity: { bound: max, object: alone, receipts: receiptsIn(alone), statements: d.delta },
660
948
  })
949
+ continue
661
950
  }
951
+ const group = shared.get(pi)
952
+ if (group) {
953
+ push('indeterminate', {
954
+ pattern: patternDigest(d.query),
955
+ objects: d.tables || [],
956
+ reason: 'multiplicity-shared',
957
+ multiplicity: { bound: max, ...group },
958
+ })
959
+ continue
960
+ }
961
+ counts.matched += 1
662
962
  }
663
963
 
664
964
  for (const u of result.unobserved) {
@@ -881,12 +1181,18 @@ async function main(argv = process.argv.slice(2)) {
881
1181
  const atBoundary = result.indeterminate.filter((d) => d.boundaryPlausible)
882
1182
  const beyond = result.indeterminate.filter((d) => !d.boundaryPlausible)
883
1183
  const max = profile?.maxStatementsPerReceipt ?? null
1184
+ const exceeded = (d) => {
1185
+ if (max == null) return ''
1186
+ const m = boundaryMultiplicity(d, result.namingReceipts, max)
1187
+ return m.exceededIfAdmitted
1188
+ ? `\n ${d.delta} statements exceed the declared multiplicity bound of ${max} even if all ` +
1189
+ `${m.receipts} receipt(s) naming ${m.object} are admitted`
1190
+ : ''
1191
+ }
884
1192
  const line = (d) =>
885
1193
  ` ~ (+${d.delta}) table(s) [${d.uncoveredTables.join(', ')}] have a receipt ${d.requiredSkewMs}ms outside ` +
886
1194
  `the window: ${truncate(d.query)}` +
887
- (max != null && d.delta > max
888
- ? `\n ${d.delta} statements exceed the declared multiplicity bound of ${max} even if that receipt is admitted`
889
- : '')
1195
+ exceeded(d)
890
1196
 
891
1197
  if (atBoundary.length > 0) {
892
1198
  const bound =
@@ -0,0 +1,18 @@
1
+ {
2
+ "id": "reconciliation/v2-multiplicity-join-neighbour",
3
+ "regime": "conformance",
4
+ "profile": "GACS-C1",
5
+ "claim": "reconciliation",
6
+ "harness": "reconcile-v2",
7
+ "before": "conformance/fixtures/reconciliation/before-empty.json",
8
+ "after": "conformance/fixtures/reconciliation/after-join-and-orders.json",
9
+ "receipts": "conformance/fixtures/reconciliation/receipts-join-whole-and-parts.jsonl",
10
+ "mappingProfile": "conformance/fixtures/reconciliation/profile-multiplicity-1.json",
11
+ "expectOutcome": "exceptions",
12
+ "expectCounts": { "matched": 0, "indeterminate": 2, "observed-without-receipt": 0 },
13
+ "expectItemOutcomes": ["indeterminate"],
14
+ "forbidItemOutcomes": ["matched", "observed-without-receipt"],
15
+ "expectItemFields": { "reason": "multiplicity-shared" },
16
+ "rationale": "The bound is 1. One Receipt names customers and orders, one names customers, one names orders. A customers-orders join has two statements and an orders pattern has one. Covering both join statements, one with the join Receipt and one with the customers Receipt and the orders Receipt, leaves the orders statement uncovered, and no assignment covers more than two statements. So the orders pattern is not shown covered, and neither is the join.",
17
+ "doesNotTest": "Whether the Receipts belong to the statements. The comparison is a count against a declared bound."
18
+ }
@@ -0,0 +1,18 @@
1
+ {
2
+ "id": "reconciliation/v2-multiplicity-one-receipt-two-objects",
3
+ "regime": "conformance",
4
+ "profile": "GACS-C1",
5
+ "claim": "reconciliation",
6
+ "harness": "reconcile-v2",
7
+ "before": "conformance/fixtures/reconciliation/before-empty.json",
8
+ "after": "conformance/fixtures/reconciliation/after-customers-orders.json",
9
+ "receipts": "conformance/fixtures/reconciliation/receipts-customers-orders-one.jsonl",
10
+ "mappingProfile": "conformance/fixtures/reconciliation/profile-multiplicity-1.json",
11
+ "expectOutcome": "exceptions",
12
+ "expectCounts": { "matched": 0, "indeterminate": 2, "observed-without-receipt": 0 },
13
+ "expectItemOutcomes": ["indeterminate"],
14
+ "forbidItemOutcomes": ["matched", "observed-without-receipt"],
15
+ "expectItemFields": { "reason": "multiplicity-shared", "multiplicity": { "bound": 1, "objects": ["customers", "orders"], "receipts": 1, "statements": 2 } },
16
+ "rationale": "The bound is how many statements one Receipt may cover, however many objects the Receipt names. One Receipt names customers and orders, the bound is 1, and there is one statement on each object, so the Receipt admits one of the two. Each pattern fits on its own, and the evidence does not say which one the Receipt covered, so neither is matched.",
17
+ "doesNotTest": "Whether the Receipt belongs to either statement. The comparison is a count against a declared bound."
18
+ }
@@ -0,0 +1,16 @@
1
+ {
2
+ "id": "reconciliation/v2-multiplicity-per-receipt",
3
+ "regime": "conformance",
4
+ "profile": "GACS-C1",
5
+ "claim": "reconciliation",
6
+ "harness": "reconcile-v2",
7
+ "before": "conformance/fixtures/reconciliation/before-empty.json",
8
+ "after": "conformance/fixtures/reconciliation/after-customers-3.json",
9
+ "receipts": "conformance/fixtures/reconciliation/receipts-customers-3.jsonl",
10
+ "mappingProfile": "conformance/fixtures/reconciliation/profile-multiplicity-1.json",
11
+ "expectOutcome": "no-exceptions",
12
+ "expectCounts": { "matched": 1, "observed-without-receipt": 0, "indeterminate": 0 },
13
+ "forbidItemOutcomes": ["observed-without-receipt", "indeterminate"],
14
+ "rationale": "The multiplicity bound is how many source statements one Receipt may cover. Three Receipts in the Window name the object, the bound is 1, and the pattern has three statements, so the bound admits all three.",
15
+ "doesNotTest": "Whether each Receipt belongs to one of the statements. The comparison is a count against a declared bound."
16
+ }
@@ -0,0 +1,18 @@
1
+ {
2
+ "id": "reconciliation/v2-multiplicity-shared",
3
+ "regime": "conformance",
4
+ "profile": "GACS-C1",
5
+ "claim": "reconciliation",
6
+ "harness": "reconcile-v2",
7
+ "before": "conformance/fixtures/reconciliation/before-empty.json",
8
+ "after": "conformance/fixtures/reconciliation/after-customers-two-patterns.json",
9
+ "receipts": "conformance/fixtures/reconciliation/receipts-customers.jsonl",
10
+ "mappingProfile": "conformance/fixtures/reconciliation/profile-multiplicity-1.json",
11
+ "expectOutcome": "exceptions",
12
+ "expectCounts": { "matched": 0, "indeterminate": 2, "observed-without-receipt": 0 },
13
+ "expectItemOutcomes": ["indeterminate"],
14
+ "forbidItemOutcomes": ["matched", "observed-without-receipt"],
15
+ "expectItemFields": { "reason": "multiplicity-shared", "multiplicity": { "bound": 1, "objects": ["customers"], "receipts": 1, "statements": 2 } },
16
+ "rationale": "A Receipt names objects, not patterns, so two patterns against one object draw on the same Receipts. One Receipt at a bound of 1 admits one of the two statements. Each pattern fits the bound on its own, and the evidence does not say which one the Receipt covered, so neither is matched.",
17
+ "doesNotTest": "A pattern over the bound on its own. That is observed-without-receipt with reason multiplicity-exceeded."
18
+ }
@@ -11,7 +11,7 @@
11
11
  "expectOutcome": "exceptions",
12
12
  "expectItemOutcomes": ["indeterminate"],
13
13
  "forbidItemOutcomes": ["matched", "observed-without-receipt"],
14
- "expectItemFields": { "reason": "window-boundary", "multiplicity": { "bound": 1, "statements": 5, "exceededIfAdmitted": true } },
15
- "rationale": "An item uncovered only by the window boundary stays indeterminate under the temporal rule of the draft, and it reports that its statement count exceeds the declared bound even if the Receipt outside the Window were admitted. The outcome alone would present 5 statements and 10,000 statements as the same finding.",
16
- "doesNotTest": "Whether the Receipt belongs to the recorded access, or a bound per Receipt: the comparison is the one the reconciled branch uses, the pattern's statement count against the declared bound."
14
+ "expectItemFields": { "reason": "window-boundary", "multiplicity": { "bound": 1, "object": "customers", "receipts": 1, "statements": 5, "exceededIfAdmitted": true } },
15
+ "rationale": "An item uncovered only by the window boundary stays indeterminate under the temporal rule of the draft, and it reports that its statement count exceeds the declared bound even if every Receipt naming its objects were admitted. The outcome alone would present 5 statements and 10,000 statements as the same finding.",
16
+ "doesNotTest": "Whether the Receipt belongs to the recorded access."
17
17
  }
@@ -11,7 +11,7 @@
11
11
  "expectOutcome": "exceptions",
12
12
  "expectItemOutcomes": ["indeterminate"],
13
13
  "forbidItemOutcomes": ["matched", "observed-without-receipt"],
14
- "expectItemFields": { "reason": "window-boundary", "multiplicity": { "bound": 8, "statements": 5, "exceededIfAdmitted": false } },
14
+ "expectItemFields": { "reason": "window-boundary", "multiplicity": { "bound": 8, "object": "customers", "receipts": 1, "statements": 5, "exceededIfAdmitted": false } },
15
15
  "rationale": "Same evidence as v2-window-boundary-bound-exceeded with a bound of 8: the count fits the bound, so the clock alone keeps this item from being matched. A held bound never turns a boundary item into matched.",
16
16
  "doesNotTest": "A declared skew bound. That is v2-clocks-declared."
17
17
  }
@@ -0,0 +1 @@
1
+ {"v":"conarium-dbsnapshot/0.1","ts":"2026-08-06T12:00:00.000Z","role":"conarium_c2","source":"pg_stat_statements","entries":[{"queryid":"1","query":"WITH pgrst_source AS (SELECT \"public\".\"customers\".* FROM \"public\".\"customers\") SELECT * FROM pgrst_source","calls":3}]}
@@ -0,0 +1 @@
1
+ {"v":"conarium-dbsnapshot/0.1","ts":"2026-08-06T12:00:00.000Z","role":"conarium_c2","source":"pg_stat_statements","entries":[{"queryid":"1","query":"WITH pgrst_source AS (SELECT \"public\".\"customers\".* FROM \"public\".\"customers\") SELECT * FROM pgrst_source","calls":1},{"queryid":"2","query":"SELECT \"public\".\"orders\".* FROM \"public\".\"orders\" LIMIT $1","calls":1}]}
@@ -0,0 +1 @@
1
+ {"v":"conarium-dbsnapshot/0.1","ts":"2026-08-06T12:00:00.000Z","role":"conarium_c2","source":"pg_stat_statements","entries":[{"queryid":"1","query":"WITH pgrst_source AS (SELECT \"public\".\"customers\".* FROM \"public\".\"customers\") SELECT * FROM pgrst_source","calls":1},{"queryid":"2","query":"WITH pgrst_source AS (SELECT \"public\".\"customers\".* FROM \"public\".\"customers\") SELECT * FROM pgrst_source /* second pattern */","calls":1}]}
@@ -0,0 +1 @@
1
+ {"v":"conarium-dbsnapshot/0.1","ts":"2026-08-06T12:00:00.000Z","role":"conarium_c2","source":"pg_stat_statements","entries":[{"queryid":"1","query":"SELECT \"public\".\"customers\".\"id\" FROM \"public\".\"customers\" JOIN \"public\".\"orders\" ON \"public\".\"orders\".\"customer_id\" = \"public\".\"customers\".\"id\"","calls":2},{"queryid":"2","query":"SELECT \"public\".\"orders\".* FROM \"public\".\"orders\" LIMIT $1","calls":1}]}
@@ -0,0 +1,3 @@
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}}
2
+ {"v":"conarium-receipt/0.3","ts":"2026-08-06T11:01:00.000Z","request":{"tool":"query","target":"zion-rest","argsHash":"sha256:00"},"dataRefs":[{"source":"zion-rest","object":"zion.customers","fieldsRequested":[]}],"policy":{"decision":"allow"},"chain":{"seq":2}}
3
+ {"v":"conarium-receipt/0.3","ts":"2026-08-06T11:02:00.000Z","request":{"tool":"query","target":"zion-rest","argsHash":"sha256:00"},"dataRefs":[{"source":"zion-rest","object":"zion.customers","fieldsRequested":[]}],"policy":{"decision":"allow"},"chain":{"seq":3}}
@@ -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":[]},{"source":"zion-rest","object":"zion.orders","fieldsRequested":[]}],"policy":{"decision":"allow"},"chain":{"seq":1}}
@@ -0,0 +1,3 @@
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":[]},{"source":"zion-rest","object":"zion.orders","fieldsRequested":[]}],"policy":{"decision":"allow"},"chain":{"seq":1}}
2
+ {"v":"conarium-receipt/0.3","ts":"2026-08-06T11:10:00.000Z","request":{"tool":"query","target":"zion-rest","argsHash":"sha256:00"},"dataRefs":[{"source":"zion-rest","object":"zion.customers","fieldsRequested":[]}],"policy":{"decision":"allow"},"chain":{"seq":2}}
3
+ {"v":"conarium-receipt/0.3","ts":"2026-08-06T11:20:00.000Z","request":{"tool":"query","target":"zion-rest","argsHash":"sha256:00"},"dataRefs":[{"source":"zion-rest","object":"zion.orders","fieldsRequested":[]}],"policy":{"decision":"allow"},"chain":{"seq":3}}
@@ -579,12 +579,63 @@ bound does not decide), and `receipted-without-observation` makes
579
579
  `outcome` `exceptions`. `bounds.exclusion` is `operator-declared` only
580
580
  when the profile lists at least one exclusion rule.
581
581
 
582
+ A declared multiplicity bound is how many statements one Receipt may cover,
583
+ however many objects the Receipt names. A statement is covered by one in-window
584
+ Receipt that names all of its pattern's objects or by an in-window Receipt for
585
+ each object. The patterns whose
586
+ objects all have a Receipt in the Window draw on the in-window Receipts; a
587
+ pattern with an object no Receipt in the Window names takes its outcome from
588
+ that object and draws on none.
589
+
590
+ Of the patterns that draw, one whose call delta is more than bound × the
591
+ in-window Receipts that name one of its objects is `observed-without-receipt`
592
+ with reason `multiplicity-exceeded`; it still draws on the Receipts, because its statements
593
+ were observed. The statements of the patterns that draw are assigned to
594
+ Receipts as a maximum flow. Of the patterns not over the bound on their own,
595
+ one that some maximum assignment leaves with a statement uncovered is
596
+ `indeterminate` with reason `multiplicity-shared`: the evidence does not say
597
+ which statements the Receipts covered. Every other pattern is `matched`.
598
+
599
+ The assignment is exact except for a pattern that draws, over several objects,
600
+ where an in-window Receipt names one of its objects but not all of them. Such a
601
+ pattern
602
+ draws only on the Receipts that name it whole, where there are any. Where there
603
+ are none, it is drawn against each object's Receipts: objects named by exactly
604
+ the same Receipts share one draw, and a Receipt that names two of its objects
605
+ that do not share a draw is counted once for each. Either way the assignment
606
+ can show a pattern beside it covered when another maximum assignment would not.
607
+ So the patterns that draw and share an in-window Receipt with such a pattern,
608
+ directly or through other patterns that draw, are taken together; a pattern
609
+ that draws on none is not among them. When the assignment leaves any
610
+ of their statements uncovered, every one of them not over the bound on its own
611
+ is `indeterminate` with reason `multiplicity-shared`. When it covers them all,
612
+ the assignment is a real one, and they are `matched`. The comparison therefore
613
+ errs only toward `indeterminate`.
614
+
615
+ A `multiplicity-exceeded` item carries
616
+ `multiplicity: { bound, object, receipts, statements }`: `object` is the object
617
+ whose bound decided it, as Receipts are matched to it (the last name segment,
618
+ lower case), `receipts` the in-window Receipts naming it, and `statements` the
619
+ pattern's call delta. A `multiplicity-shared` item carries
620
+ `multiplicity: { bound, objects, receipts, statements }` for the patterns it
621
+ competes with for Receipts: `objects` are the objects they draw for, `receipts`
622
+ the in-window Receipts they can draw on, and `statements` their call deltas
623
+ added together. A pattern drawn one Receipt per object can compete in two such
624
+ groups; it reports the one whose statements are furthest over
625
+ `receipts × bound`. A pattern that is `indeterminate` only because it is taken
626
+ together with a pattern over several objects reports all the patterns taken
627
+ together: their objects, the in-window Receipts that name one of them, and
628
+ their call deltas added together.
629
+
582
630
  A `/2` item whose `reason` is `window-boundary` carries `requiredSkewMs` and the
583
631
  uncovered `objects`. When the profile declares a multiplicity bound it also
584
- carries `multiplicity: { bound, statements, exceededIfAdmitted }`: `statements` is
585
- the pattern's call delta in the window, and `exceededIfAdmitted` is
586
- `statements > bound`, the comparison a pattern inside the window gets. The item
587
- stays `indeterminate` either way, and `false` is not a pass.
632
+ carries `multiplicity: { bound, object, receipts, statements, exceededIfAdmitted }`:
633
+ `statements` is the pattern's call delta in the window, `receipts` the number of
634
+ Receipts with a readable timestamp that name `object`, inside the Window or out,
635
+ and `object` the one of the pattern's objects with the fewest such Receipts.
636
+ `exceededIfAdmitted` is `statements > receipts × bound`: the count exceeds the
637
+ bound even with every Receipt naming the object admitted. The item stays
638
+ `indeterminate` either way, and `false` is not a pass.
588
639
 
589
640
  ### Mapping Profile (`conarium-mapping-profile/0.1`)
590
641
 
@@ -613,7 +664,7 @@ undeclared, not defaulted.
613
664
 
614
665
  | Field | Type | Encoding | What it declares |
615
666
  |---|---|---|---|
616
- | `multiplicity.maxStatementsPerReceipt` | integer ≥ 1 | JSON number | how many source statements one receipt may cover. This implementation compares it with one pattern's statement count in the window, so more receipts do not raise it (`LIMITATIONS.md`) |
667
+ | `multiplicity.maxStatementsPerReceipt` | integer ≥ 1 | JSON number | how many source statements one receipt may cover, however many objects it names. The patterns whose objects all have a receipt in the window draw on the in-window receipts together |
617
668
  | `exclusions[]` | array | `{ "id": string, "version": string }` | rules that remove items before comparison |
618
669
  | `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`. |
619
670
  | `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`. |
@@ -0,0 +1,165 @@
1
+ # Claims review — 0.3.7
2
+
3
+ - base: v0.3.6
4
+ - head: 8563bc6
5
+ - surface: sha256:aefdbafd7270ffbf2fdb2f682303350e1b67fcb8c4dcf83e9adef1f5fe6afa53
6
+ - verdict: pass
7
+ - reviewer: Claude. Three claim surfaces changed between v0.3.6 and HEAD:
8
+ `LIMITATIONS.md`, `LIMITATIONS.tr.md` and `docs/RECEIPT-SPEC.md`
9
+ (`node test/denetci.mjs input v0.3.6 HEAD`).
10
+
11
+ The release changes `projectResultV2` and the text report in
12
+ `bin/conarium-reconcile.mjs`, adds `namingReceiptCounts`, `boundAssignment`
13
+ (a maximum flow from patterns to groups of in-window Receipts) and
14
+ `boundaryMultiplicity`, updates two conformance cases and adds three.
15
+
16
+ Each new sentence was set against what establishes it. The tests named are in
17
+ `test/reconcile_cli.test.mjs`, under `what a declared bound is compared with`
18
+ and `a boundary item carries what the outcome alone does not show`; each runs
19
+ the CLI and reads the `/2` body. "Seen failing" means the test went red when
20
+ the code it names was changed back, and green again when it was restored.
21
+
22
+ - "how many statements one Receipt may cover, however many objects the Receipt
23
+ names": `a receipt that names two objects is one budget, not one per object`,
24
+ and `conformance/cases/reconciliation/v2-multiplicity-one-receipt-two-objects.json`.
25
+ Seen failing with a group's capacity multiplied by the objects it names.
26
+ - "A statement is covered by one in-window Receipt that names all of its
27
+ pattern's objects or, when no in-window Receipt names them all, by an
28
+ in-window Receipt for each object": `one receipt that names both objects of
29
+ a join covers one statement of it`, `a join is covered by one receipt for
30
+ each of its objects`, `a join no receipt names whole is covered by receipts
31
+ that each name some of its objects`.
32
+ - "The patterns whose objects all have a Receipt in the Window draw on the
33
+ in-window Receipts": `two patterns against one object draw on the same
34
+ receipt and neither is matched`, `two receipts cover the two patterns`,
35
+ `three receipts at a bound of 1 cover three statements`, and
36
+ `v2-multiplicity-shared.json`, `v2-multiplicity-per-receipt.json`.
37
+ - "a pattern with an object no Receipt in the Window names takes its outcome
38
+ from that object and draws on none": `a pattern with an object no receipt
39
+ names does not draw on its neighbour's receipts`.
40
+ - "Of the patterns that draw, one whose call delta is more than bound × the
41
+ in-window Receipts that name one of its objects is `observed-without-receipt`": `one receipt at a
42
+ bound of 1 does not cover three statements`, `a pattern that names two
43
+ objects is bound by the object with fewer receipts`. "it still draws on the
44
+ Receipts": `one pattern over its own bound is not softened by a neighbour on
45
+ the same object`. Seen failing with such patterns left out of the flow.
46
+ - "one that some maximum assignment leaves with a statement uncovered is
47
+ `indeterminate` with reason `multiplicity-shared`" and "Every other pattern
48
+ is `matched`": `patterns that fit each object on its own can still be more
49
+ than their receipts cover together` (each object fits its own Receipts, the
50
+ two Receipts that name orders cover two of three statements), and `a pattern
51
+ with receipts to spare is matched beside a shortfall it cannot take part in`.
52
+ The second holds because the set of nodes reachable from the source in the
53
+ residual graph is the same for every maximum flow.
54
+ - "A pattern over several objects that some in-window Receipt names whole
55
+ draws only on the Receipts that name it whole": `a join that some receipt
56
+ names whole draws only on receipts that name it whole`. Seen failing with
57
+ that branch removed.
58
+ - "objects named by exactly the same Receipts share one draw; a Receipt that
59
+ names two of its objects that do not share a draw is counted once for each":
60
+ `a join no receipt names whole is covered by receipts that each name some of
61
+ its objects` (seen failing with one node per object) and `a join no receipt
62
+ names whole, named by receipts that overlap, counts a shared receipt once
63
+ per object`.
64
+ - `multiplicity-exceeded` fields: the two exceeded tests above. `object` "as
65
+ Receipts are matched to it": the same tests read `customers` and `orders`
66
+ for Receipts naming `zion.customers` and `zion.orders`.
67
+ - `multiplicity-shared` fields, "`objects` are the objects they draw for,
68
+ `receipts` the in-window Receipts they can draw on, and `statements` their
69
+ call deltas added together": the shared tests above (in the first, two of
70
+ three Receipts and three statements; the Receipt that names only products is
71
+ not counted). "it reports the one whose statements are furthest over":
72
+ `a join covered one receipt per object reports the group furthest over the
73
+ bound`. Seen failing with the last group written instead.
74
+ - "Receipts outside the window do not count toward this comparison": `a
75
+ receipt outside the Window does not count toward an in-window bound`.
76
+ - "`/2` does not change the exit codes": the exit code assertion in `one
77
+ receipt at a bound of 1 does not cover three statements`, and `the receipt
78
+ counts stay out of the /1 body` for the `/1` body. Seen failing when the
79
+ counts were made enumerable.
80
+ - Boundary item, "`receipts` the number of Receipts with a readable timestamp
81
+ that name `object`, inside the Window or out" and `exceededIfAdmitted`:
82
+ `every receipt naming the object counts when the item asks what admitting
83
+ them would settle` (two Receipts outside, two statements, `false`).
84
+ - "`object` the one of the pattern's objects with the fewest such Receipts": `a
85
+ boundary item that names two objects reports the one with fewer receipts`.
86
+ Seen failing with the comparison reversed.
87
+ - "The item stays `indeterminate` either way": the boundary tests, and
88
+ `v2-window-boundary-bound-exceeded.json` and `v2-window-boundary-bound-held.json`,
89
+ which forbid `matched` and `observed-without-receipt` on the item.
90
+
91
+ The changelog is not a claim surface, but its sentences were checked the same
92
+ way. The 0.3.6 behaviour it describes is the table in #161, measured on the
93
+ published 0.3.6. The three added conformance cases were run against the
94
+ previous `bin/conarium-reconcile.mjs` and failed.
95
+
96
+ ## Findings
97
+
98
+ ### 1. LIMITATIONS.md — which patterns draw on the receipts
99
+
100
+ - Claim: "every pattern on that object draws on the same receipts" (first
101
+ draft of this release, also in `LIMITATIONS.tr.md`, `docs/RECEIPT-SPEC.md` and
102
+ the changelog).
103
+ - Mechanism: the patterns `projectResultV2` assigns are `result.reconciled`
104
+ only.
105
+ - Why it falls short: a pattern with an object no in-window receipt names is in
106
+ `unreconciled` or `indeterminate` and draws on nothing, so "every pattern"
107
+ says more than the code does.
108
+ - Disposition: reworded before `8563bc6` to name the patterns that draw, with a
109
+ test for the case.
110
+
111
+ ### 2. LIMITATIONS.md — what an item short of in-window receipts is called
112
+
113
+ - Claim: "such an item is reported as `multiplicity-exceeded`, not as a
114
+ boundary item" (first draft, also in `LIMITATIONS.tr.md`).
115
+ - Mechanism: the reconciled branch of `projectResultV2`.
116
+ - Why it falls short: when the shortfall comes from patterns sharing
117
+ receipts, the item is `multiplicity-shared`, not `multiplicity-exceeded`.
118
+ - Disposition: reworded before `8563bc6` to "decided by the in-window receipts
119
+ alone, not reported as a boundary item".
120
+
121
+ ### 3. LIMITATIONS.md — one receipt's bound counted once per object
122
+
123
+ - Claim: "The receipts in the window that name an object admit receipts ×
124
+ bound statements against it" (a draft of this release, which compared each
125
+ object's receipts with the statements on that object).
126
+ - Mechanism: a load per object, set against the in-window receipts naming
127
+ that object.
128
+ - Why it falls short: a receipt that names two objects was counted in both
129
+ objects' capacity. One receipt naming customers and orders, at a bound of 1,
130
+ covered a customers statement and an orders statement, and both were
131
+ `matched`. Reproduced with the CLI;
132
+ `v2-multiplicity-one-receipt-two-objects` fails on that draft.
133
+ - Disposition: the code was changed before `788c641` to one budget per
134
+ receipt, assigned as a maximum flow, and the sentences rewritten. The two
135
+ cases where the flow errs toward `indeterminate` are stated in
136
+ `LIMITATIONS.md`, each with a test.
137
+
138
+ ### 4. docs/RECEIPT-SPEC.md — what is assigned, and when
139
+
140
+ - Claim: "Otherwise the statements are assigned to Receipts as a maximum
141
+ flow" (a draft of this release).
142
+ - Mechanism: `boundAssignment` puts every reconciled pattern in the flow.
143
+ - Why it falls short: "Otherwise" read as if a pattern over the bound on its
144
+ own were left out of the assignment; it is in it.
145
+ - Disposition: reworded before `8563bc6`. The same pass changed
146
+ "beside the patterns it shares them with" in `LIMITATIONS.md`, which did not
147
+ fit a pattern that is `multiplicity-shared` with no neighbour (the two
148
+ limit cases), and "named by receipts that overlap", which did not say when a
149
+ receipt is counted twice.
150
+
151
+ ### 5. docs/RECEIPT-SPEC.md — which patterns the bound decides
152
+
153
+ - Claim: "A pattern whose call delta is more than bound × the in-window
154
+ Receipts that name one of its objects is `observed-without-receipt`" (a
155
+ draft of this release, also in `LIMITATIONS.md`, `LIMITATIONS.tr.md` and the
156
+ changelog).
157
+ - Mechanism: the reconciled branch of `projectResultV2`, which sees only
158
+ patterns whose objects all have an in-window Receipt.
159
+ - Why it falls short: read alone, the sentence also covers a pattern whose
160
+ only Receipts are outside the Window: three statements against no in-window
161
+ Receipt are more than 1 × 0, yet that pattern is a boundary item and stays
162
+ `indeterminate` (`10,000 statements against one bound of 1 stay
163
+ indeterminate and say the bound is exceeded`).
164
+ - Disposition: reworded before `8563bc6` to "Of the patterns that draw", and
165
+ the `multiplicity-shared` sentences scoped the same way.
@@ -0,0 +1,122 @@
1
+ # Claims review — 0.3.8
2
+
3
+ - base: v0.3.7
4
+ - head: 438c920
5
+ - surface: sha256:0d261576d21c47737ed2ba9096af608c3d7574dcbcfdbbb5652acc49c0a870ce
6
+ - verdict: pass
7
+ - reviewer: Claude. Three claim surfaces changed between v0.3.7 and HEAD:
8
+ `LIMITATIONS.md`, `LIMITATIONS.tr.md` and `docs/RECEIPT-SPEC.md`
9
+ (`node test/denetci.mjs input v0.3.7 HEAD`).
10
+
11
+ The release changes `boundAssignment` in `bin/conarium-reconcile.mjs`: the
12
+ patterns that draw and share an in-window Receipt with a pattern that draws,
13
+ over several objects, that a Receipt names in part are decided together. It
14
+ adds one conformance case, two tests in `test/reconcile_cli.test.mjs` and
15
+ `test/bound_assignment_brute.test.mjs`, which enumerates every assignment of
16
+ 400 random inputs (up to three patterns of one or two objects each, over three
17
+ objects, up to three Receipt groups, a bound of 1 or 2) and compares
18
+ `boundAssignment` with the rule.
19
+
20
+ Each new sentence was set against what establishes it. "Seen failing" means
21
+ the test went red when the code it names was changed, and green again when it
22
+ was restored.
23
+
24
+ - "A statement is covered by one in-window Receipt that names all of its
25
+ pattern's objects or by an in-window Receipt for each object": the rule the
26
+ brute-force test enumerates, and `one receipt that names both objects of a
27
+ join covers one statement of it`, `a join is covered by one receipt for each
28
+ of its objects`.
29
+ - "The assignment is exact except for a pattern that draws, over several
30
+ objects, where an in-window Receipt names one of its objects but not all of
31
+ them": the
32
+ brute-force test requires the same answer as the rule, both ways, on every
33
+ input with no such pattern (more than 50 of the 400). Seen failing with
34
+ every pattern treated as one a Receipt names in part.
35
+ - "Such a pattern draws only on the Receipts that name it whole, where there
36
+ are any. Where there are none, it is drawn against each object's Receipts":
37
+ `a join that some receipt names whole draws only on receipts that name it
38
+ whole (LIMITATIONS.md)` and `a join no receipt names whole, named by
39
+ receipts that overlap, counts a shared receipt once per object
40
+ (LIMITATIONS.md)`.
41
+ - "Either way the assignment can show a pattern beside it covered when another
42
+ maximum assignment would not": the brute-force test fails on 0.3.7's
43
+ `boundAssignment`, and so do `a pattern beside a join that some receipt
44
+ names whole is not matched when the join could take its receipt` and
45
+ `conformance/cases/reconciliation/v2-multiplicity-join-neighbour.json`.
46
+ - "So the patterns that draw and share an in-window Receipt with such a
47
+ pattern, directly or through other patterns that draw, are taken together":
48
+ `a pattern on a receipt that a join could take for one of its objects is not
49
+ matched beside the join` (the Receipt names one object of the join). Seen
50
+ failing with the patterns not joined through their Receipts, with only the
51
+ Receipts that name a pattern whole joined, and with no pattern marked; each
52
+ also turns the brute-force test and the test above red. "a pattern that
53
+ draws on none is not among them": `a pattern with an object no receipt names
54
+ does not draw on its neighbour's receipts` (the customers pattern stays
55
+ matched beside a join whose orders no Receipt names).
56
+ - "When the assignment leaves any of their statements uncovered, every one of
57
+ them not over the bound on its own is `indeterminate` with reason
58
+ `multiplicity-shared`": the two tests above read both items.
59
+ - "When it covers them all, the assignment is a real one, and they are
60
+ `matched`": the brute-force test finds no pattern returned matched that some
61
+ maximum assignment leaves uncovered; `a join no receipt names whole is
62
+ covered by receipts that each name some of its objects` stays matched.
63
+ - "The comparison therefore errs only toward `indeterminate`": the
64
+ brute-force test, within its inputs. See finding 2.
65
+ - `LIMITATIONS.md` "even one that a closer count would show covered": the
66
+ brute-force test requires at least one pattern the rule matches that
67
+ `boundAssignment` shares.
68
+ - "reports all the patterns taken together: their objects, the in-window
69
+ Receipts that name one of them, and their call deltas added together": the
70
+ first test above reads `{ bound: 1, objects: [customers, orders],
71
+ receipts: 3, statements: 3 }` on the orders item. Seen failing with the
72
+ Receipt count set to 0.
73
+ - `LIMITATIONS.tr.md` says the same as `LIMITATIONS.md`, sentence for
74
+ sentence.
75
+
76
+ ## Findings
77
+
78
+ ### 1. LIMITATIONS.md — which way 0.3.7's comparison errs
79
+
80
+ - Claim: "The comparison errs toward `indeterminate` in two cases. A pattern
81
+ over several objects that some receipt in the window names whole draws only
82
+ on the receipts that name it whole, even when the others would cover the
83
+ rest." (0.3.7, also in `LIMITATIONS.tr.md` and `docs/RECEIPT-SPEC.md`).
84
+ - Mechanism: in 0.3.7 such a pattern's node drew only on the groups that name
85
+ it whole.
86
+ - Why it falls short: that errs toward `indeterminate` for the pattern itself,
87
+ not for the patterns beside it. With a bound of 1, Receipts naming customers
88
+ and orders, customers, and orders, two statements of the join and one on
89
+ orders, 0.3.7 reported the orders pattern `matched`; one maximum assignment
90
+ covers both join statements and leaves the orders statement uncovered. An
91
+ independent read of draft-08 found it; it was reproduced on the published
92
+ 0.3.7 package.
93
+ - Disposition: fixed in `db4941b`; the sentence is replaced in all three
94
+ files.
95
+
96
+ ### 2. docs/RECEIPT-SPEC.md — how far "errs only toward" is established
97
+
98
+ - Claim: "The comparison therefore errs only toward `indeterminate`."
99
+ - Mechanism: the argument in the comment on `boundAssignment` (a flow that
100
+ covers every statement of a component is an assignment the rule accepts;
101
+ otherwise every pattern in a component with a rough pattern is shared), and
102
+ the brute-force test.
103
+ - Why it falls short: the test enumerates inputs of up to three patterns of
104
+ one or two objects each, three objects and three Receipt groups. Patterns
105
+ over three objects, and anything larger, rest on the argument.
106
+ - Disposition: accepted, with the test's inputs stated here.
107
+
108
+ ### 3. docs/RECEIPT-SPEC.md — which patterns are taken together
109
+
110
+ - Claim: "So the patterns that share an in-window Receipt with such a pattern,
111
+ directly or through other patterns, are taken together" (a draft of this
112
+ release, also in `LIMITATIONS.md` and `LIMITATIONS.tr.md`).
113
+ - Mechanism: the components in `boundAssignment` are built over
114
+ `result.reconciled` only.
115
+ - Why it falls short: a pattern with an object no in-window Receipt names
116
+ shares a Receipt with its neighbours but draws on none, and is not taken
117
+ together with them. With one Receipt naming customers, two statements of a
118
+ customers-orders join and one on customers, the join is
119
+ `observed-without-receipt` and the customers pattern stays `matched`. An
120
+ independent read of the pull request text found it.
121
+ - Disposition: reworded in `438c920` to name the patterns that draw, in all
122
+ three files.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@conarium-ai/core",
3
- "version": "0.3.6",
3
+ "version": "0.3.8",
4
4
  "mcpName": "io.github.dogrucanemek-alt/conarium",
5
5
  "//files-artefakt": "Generated files under examples/ (private key, receipt/audit JSONL) are EXCLUDED. .gitignore does not bind npm: because the allow-list contained 'examples', `npm publish` on a machine that had run the demo was shipping _keys/audit-ed25519.pem (PRIVATE KEY) and the receipts. test/pack_artefakt.mjs locks this. The exclusions are LIMITED to examples/: receipts.jsonl and .pub.pem under test-vectors/ MUST ship, or a third party cannot run the conformance vectors.",
6
6
  "//files": "Allow-list of what enters the package. Without it npm sent everything: 296 files / 1.5 MB — CI workflows, gitleaks config, a 137 KB marketing image, the site's api/chat.js. A bank security team opens the tarball and sees those. scripts/ is here ON PURPOSE: conarium-reconcile references scripts/pg-snapshot.sql at runtime; without it the user files a support mail.",