@conarium-ai/core 0.2.36 → 0.2.37
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +41 -0
- package/LIMITATIONS.md +32 -3
- package/LIMITATIONS.tr.md +67 -2
- package/README.md +5 -2
- package/bin/conarium-reconcile.mjs +297 -13
- package/bin/conarium-stamp.mjs +2 -2
- package/conformance/cases/reconciliation/v2-clocks-declared.json +16 -0
- package/conformance/cases/reconciliation/v2-clocks-undeclared-profile.json +16 -0
- package/conformance/cases/reconciliation/v2-excluded.json +16 -0
- package/conformance/cases/reconciliation/v2-indeterminate.json +14 -0
- package/conformance/cases/reconciliation/v2-matched.json +16 -0
- package/conformance/cases/reconciliation/v2-neg-unattributed.json +15 -0
- package/conformance/cases/reconciliation/v2-neg-undeclared-exclusion.json +16 -0
- package/conformance/cases/reconciliation/v2-neg-undeclared-multiplicity.json +16 -0
- package/conformance/cases/reconciliation/v2-neg-undeclared-skew.json +15 -0
- package/conformance/cases/reconciliation/v2-observed-without-receipt.json +14 -0
- package/conformance/cases/reconciliation/v2-receipted-without-observation.json +14 -0
- package/conformance/fixtures/reconciliation/after-customers-1.json +1 -0
- package/conformance/fixtures/reconciliation/after-customers-15.json +1 -0
- package/conformance/fixtures/reconciliation/after-empty.json +1 -0
- package/conformance/fixtures/reconciliation/after-set.json +1 -0
- package/conformance/fixtures/reconciliation/after-unattributed.json +1 -0
- package/conformance/fixtures/reconciliation/before-customers-10.json +1 -0
- package/conformance/fixtures/reconciliation/before-empty.json +1 -0
- package/conformance/fixtures/reconciliation/profile-clocks.json +9 -0
- package/conformance/fixtures/reconciliation/profile-exclusion.json +7 -0
- package/conformance/fixtures/reconciliation/profile-multiplicity.json +9 -0
- package/conformance/fixtures/reconciliation/profile-no-clocks.json +4 -0
- package/conformance/fixtures/reconciliation/receipts-customers-early.jsonl +1 -0
- package/conformance/fixtures/reconciliation/receipts-customers.jsonl +1 -0
- package/conformance/fixtures/reconciliation/receipts-empty.jsonl +0 -0
- package/conformance/run.mjs +59 -0
- package/docs/API-STABILITY.md +1 -1
- package/docs/ARCHITECTURE.md +2 -2
- package/docs/RECEIPT-SPEC.md +92 -15
- package/docs/claims/retracted-phrasings.json +7 -0
- package/docs/claims/reviews/0.2.37.md +180 -0
- package/docs/claims/surfaces.json +115 -0
- package/package.json +1 -1
|
@@ -67,19 +67,24 @@
|
|
|
67
67
|
* outside the boundary is now indeterminate, not an accusation, and the
|
|
68
68
|
* report names the skew that would have to be true for it to be one.
|
|
69
69
|
*
|
|
70
|
-
* `--skew` declares the bound. Without
|
|
71
|
-
* nothing
|
|
72
|
-
*
|
|
73
|
-
* not skew, and the pattern
|
|
70
|
+
* `--skew` or Mapping Profile `clocks.skew` declares the bound. Without
|
|
71
|
+
* either, nothing decides the question, so nothing is asserted: the pattern
|
|
72
|
+
* is indeterminate and the report says the bound was never declared. With
|
|
73
|
+
* a bound, a receipt further out than it is not skew, and the pattern
|
|
74
|
+
* stays unreconciled. If both declarations are present and they disagree,
|
|
75
|
+
* the run fails rather than picking one.
|
|
74
76
|
*
|
|
75
77
|
* Reported for the operator, not resolved for them: this tool cannot tell a
|
|
76
78
|
* trailing clock from a receipt written late. That is why the class is
|
|
77
79
|
* "indeterminate" and not "covered".
|
|
78
80
|
*/
|
|
79
|
-
import {
|
|
81
|
+
import { createHash } from 'crypto'
|
|
82
|
+
import { readFileSync, existsSync, writeFileSync } from 'fs'
|
|
80
83
|
|
|
81
84
|
const RECONCILE_V = 'conarium-reconcile/0.1'
|
|
82
85
|
const SNAPSHOT_V = 'conarium-dbsnapshot/0.1'
|
|
86
|
+
const RESULT_V2 = 'coverage-reconciliation/2'
|
|
87
|
+
const PROFILE_V = 'conarium-mapping-profile/0.1'
|
|
83
88
|
|
|
84
89
|
// ─── snapshot loading ────────────────────────────────────────────────────────
|
|
85
90
|
|
|
@@ -401,8 +406,9 @@ export function reconcile(before, after, receipts, opts = {}) {
|
|
|
401
406
|
// unreceipted access" — an exculpation 23 hours of offset cannot support.
|
|
402
407
|
//
|
|
403
408
|
// The threshold is the window's own length, so it is derived from the
|
|
404
|
-
// input rather than chosen. A declared
|
|
405
|
-
//
|
|
409
|
+
// input rather than chosen. A declared skew bound (--skew or
|
|
410
|
+
// Mapping Profile clocks.skew) is the operator's own statement about
|
|
411
|
+
// their clocks and outranks it.
|
|
406
412
|
const boundaryPlausible = declaredSkewMs !== null || requiredSkewMs <= toMs - fromMs
|
|
407
413
|
indeterminate.push({ ...d, uncoveredTables: names, requiredSkewMs, boundaryPlausible })
|
|
408
414
|
} else {
|
|
@@ -445,12 +451,244 @@ export function reconcile(before, after, receipts, opts = {}) {
|
|
|
445
451
|
}
|
|
446
452
|
}
|
|
447
453
|
|
|
454
|
+
// ─── /2 projection ───────────────────────────────────────────────────────────
|
|
455
|
+
//
|
|
456
|
+
// A separate object. The /1 JSON and the exit codes are a compatibility
|
|
457
|
+
// contract; a consumer MUST NOT read them as this. Draft
|
|
458
|
+
// draft-dogru-scitt-disclosure-evidence-04 §Result statement.
|
|
459
|
+
|
|
460
|
+
function sha256Of(buf) {
|
|
461
|
+
return 'sha256:' + createHash('sha256').update(buf).digest('hex')
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
function patternDigest(query) {
|
|
465
|
+
return sha256Of(Buffer.from(String(query), 'utf8'))
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
/**
|
|
469
|
+
* Mapping Profile as the draft names it: operator-declared bounds, versioned,
|
|
470
|
+
* digested. Absent a profile, every multiplicity-dependent item is
|
|
471
|
+
* indeterminate — this function does not invent a bound of one.
|
|
472
|
+
*/
|
|
473
|
+
export function loadMappingProfile(path) {
|
|
474
|
+
if (!existsSync(path)) return { error: `profile not found: ${path}` }
|
|
475
|
+
const raw = readFileSync(path)
|
|
476
|
+
let obj
|
|
477
|
+
try {
|
|
478
|
+
obj = JSON.parse(raw.toString('utf8'))
|
|
479
|
+
} catch (err) {
|
|
480
|
+
return { error: `profile is not valid JSON: ${err.message}` }
|
|
481
|
+
}
|
|
482
|
+
if (!obj || typeof obj !== 'object') return { error: 'profile: not an object' }
|
|
483
|
+
if (obj.v !== PROFILE_V) {
|
|
484
|
+
return { error: `profile: unsupported version ${JSON.stringify(obj.v)} (expected ${PROFILE_V})` }
|
|
485
|
+
}
|
|
486
|
+
if (typeof obj.version !== 'string' || !obj.version) {
|
|
487
|
+
return { error: 'profile: missing version identifier' }
|
|
488
|
+
}
|
|
489
|
+
let maxStatementsPerReceipt = null
|
|
490
|
+
if (obj.multiplicity != null) {
|
|
491
|
+
if (typeof obj.multiplicity !== 'object') return { error: 'profile: multiplicity must be an object' }
|
|
492
|
+
const n = obj.multiplicity.maxStatementsPerReceipt
|
|
493
|
+
if (!Number.isInteger(n) || n < 1) {
|
|
494
|
+
return { error: 'profile: multiplicity.maxStatementsPerReceipt must be a positive integer' }
|
|
495
|
+
}
|
|
496
|
+
maxStatementsPerReceipt = n
|
|
497
|
+
}
|
|
498
|
+
const exclusions = []
|
|
499
|
+
if (obj.exclusions != null) {
|
|
500
|
+
if (!Array.isArray(obj.exclusions)) return { error: 'profile: exclusions must be an array' }
|
|
501
|
+
for (const e of obj.exclusions) {
|
|
502
|
+
if (!e || typeof e.id !== 'string' || !e.id) return { error: 'profile: exclusion missing id' }
|
|
503
|
+
if (typeof e.version !== 'string' || !e.version) return { error: 'profile: exclusion missing version' }
|
|
504
|
+
exclusions.push({ id: e.id, version: e.version })
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
const clocks = { observation: null, receipt: null, skew: null, skewMs: null }
|
|
508
|
+
if (obj.clocks != null) {
|
|
509
|
+
if (typeof obj.clocks !== 'object' || Array.isArray(obj.clocks)) {
|
|
510
|
+
return { error: 'profile: clocks must be an object' }
|
|
511
|
+
}
|
|
512
|
+
for (const key of Object.keys(obj.clocks)) {
|
|
513
|
+
if (key !== 'observation' && key !== 'receipt' && key !== 'skew') {
|
|
514
|
+
return { error: `profile: clocks has unknown field ${JSON.stringify(key)} (expected observation, receipt, skew)` }
|
|
515
|
+
}
|
|
516
|
+
}
|
|
517
|
+
if (obj.clocks.observation != null) {
|
|
518
|
+
if (typeof obj.clocks.observation !== 'string' || !obj.clocks.observation) {
|
|
519
|
+
return { error: 'profile: clocks.observation must be a non-empty string' }
|
|
520
|
+
}
|
|
521
|
+
clocks.observation = obj.clocks.observation
|
|
522
|
+
}
|
|
523
|
+
if (obj.clocks.receipt != null) {
|
|
524
|
+
if (typeof obj.clocks.receipt !== 'string' || !obj.clocks.receipt) {
|
|
525
|
+
return { error: 'profile: clocks.receipt must be a non-empty string' }
|
|
526
|
+
}
|
|
527
|
+
clocks.receipt = obj.clocks.receipt
|
|
528
|
+
}
|
|
529
|
+
if (obj.clocks.skew != null) {
|
|
530
|
+
if (typeof obj.clocks.skew !== 'string' || !obj.clocks.skew) {
|
|
531
|
+
return { error: 'profile: clocks.skew must be a duration string (e.g. 500ms, 5s, 2m, 1h)' }
|
|
532
|
+
}
|
|
533
|
+
const ms = parseDuration(obj.clocks.skew)
|
|
534
|
+
if (ms === null) {
|
|
535
|
+
return { error: `profile: clocks.skew cannot read "${obj.clocks.skew}" as a duration (try 500ms, 5s, 2m, 1h)` }
|
|
536
|
+
}
|
|
537
|
+
clocks.skew = obj.clocks.skew
|
|
538
|
+
clocks.skewMs = ms
|
|
539
|
+
}
|
|
540
|
+
}
|
|
541
|
+
return {
|
|
542
|
+
profile: {
|
|
543
|
+
version: obj.version,
|
|
544
|
+
maxStatementsPerReceipt,
|
|
545
|
+
exclusions,
|
|
546
|
+
clocks,
|
|
547
|
+
},
|
|
548
|
+
raw,
|
|
549
|
+
}
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
/**
|
|
553
|
+
* `--skew` and `clocks.skew` are both operator declarations. If both are
|
|
554
|
+
* present and they do not parse to the same number of milliseconds, the run
|
|
555
|
+
* fails — silently preferring either would hide which bound the result used.
|
|
556
|
+
* Equal values (including `5s` and `5000`) are the same declaration.
|
|
557
|
+
*/
|
|
558
|
+
export function resolveDeclaredSkew(flagMs, profileSkewMs) {
|
|
559
|
+
const flag = typeof flagMs === 'number' && Number.isFinite(flagMs) ? flagMs : null
|
|
560
|
+
const fromProfile = typeof profileSkewMs === 'number' && Number.isFinite(profileSkewMs) ? profileSkewMs : null
|
|
561
|
+
if (flag != null && fromProfile != null && flag !== fromProfile) {
|
|
562
|
+
return {
|
|
563
|
+
error:
|
|
564
|
+
`--skew (${flag}ms) conflicts with Mapping Profile clocks.skew (${fromProfile}ms); ` +
|
|
565
|
+
'both are operator declarations and this tool will not pick one',
|
|
566
|
+
}
|
|
567
|
+
}
|
|
568
|
+
return { skewMs: flag ?? fromProfile }
|
|
569
|
+
}
|
|
570
|
+
|
|
571
|
+
function infraRuleId(query) {
|
|
572
|
+
return INFRA_QUERY_RE.test(query) ? 'infra-query' : 'infra-schema'
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
/**
|
|
576
|
+
* Project a /1 reconcile() result onto coverage-reconciliation/2.
|
|
577
|
+
* Does not change /1 fields or exit codes.
|
|
578
|
+
*/
|
|
579
|
+
export function projectResultV2(result, ctx) {
|
|
580
|
+
const profile = ctx.profile ?? null
|
|
581
|
+
const items = []
|
|
582
|
+
const counts = {
|
|
583
|
+
matched: 0,
|
|
584
|
+
excluded: 0,
|
|
585
|
+
'observed-without-receipt': 0,
|
|
586
|
+
'receipted-without-observation': 0,
|
|
587
|
+
indeterminate: 0,
|
|
588
|
+
}
|
|
589
|
+
|
|
590
|
+
const push = (outcome, extra) => {
|
|
591
|
+
counts[outcome] += 1
|
|
592
|
+
if (outcome !== 'matched') items.push({ outcome, ...extra })
|
|
593
|
+
}
|
|
594
|
+
|
|
595
|
+
const declaredExclusions = profile?.exclusions || []
|
|
596
|
+
const exclusionIds = new Set(declaredExclusions.map((e) => e.id))
|
|
597
|
+
const exclusionBoundDeclared = declaredExclusions.length > 0
|
|
598
|
+
|
|
599
|
+
for (const d of result.infrastructure) {
|
|
600
|
+
const id = infraRuleId(d.query)
|
|
601
|
+
if (!profile) {
|
|
602
|
+
push('indeterminate', { pattern: patternDigest(d.query), reason: 'exclusion-undeclared' })
|
|
603
|
+
continue
|
|
604
|
+
}
|
|
605
|
+
if (!exclusionIds.has(id)) {
|
|
606
|
+
push('indeterminate', { pattern: patternDigest(d.query), reason: 'exclusion-not-in-profile' })
|
|
607
|
+
continue
|
|
608
|
+
}
|
|
609
|
+
const declared = declaredExclusions.find((e) => e.id === id)
|
|
610
|
+
push('excluded', {
|
|
611
|
+
pattern: patternDigest(d.query),
|
|
612
|
+
rule: { id, version: declared.version },
|
|
613
|
+
})
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
for (const d of result.unattributed) {
|
|
617
|
+
push('indeterminate', { pattern: patternDigest(d.query), reason: 'unattributed' })
|
|
618
|
+
}
|
|
619
|
+
|
|
620
|
+
for (const d of result.unreconciled) {
|
|
621
|
+
push('observed-without-receipt', {
|
|
622
|
+
pattern: patternDigest(d.query),
|
|
623
|
+
objects: d.uncoveredTables || [],
|
|
624
|
+
})
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
for (const d of result.indeterminate) {
|
|
628
|
+
push('indeterminate', {
|
|
629
|
+
pattern: patternDigest(d.query),
|
|
630
|
+
reason: 'window-boundary',
|
|
631
|
+
requiredSkewMs: d.requiredSkewMs,
|
|
632
|
+
})
|
|
633
|
+
}
|
|
634
|
+
|
|
635
|
+
const max = profile?.maxStatementsPerReceipt ?? null
|
|
636
|
+
for (const d of result.reconciled) {
|
|
637
|
+
if (max == null) {
|
|
638
|
+
push('indeterminate', {
|
|
639
|
+
pattern: patternDigest(d.query),
|
|
640
|
+
reason: 'multiplicity-undeclared',
|
|
641
|
+
objects: d.tables || [],
|
|
642
|
+
})
|
|
643
|
+
} else if (d.delta <= max) {
|
|
644
|
+
counts.matched += 1
|
|
645
|
+
} else {
|
|
646
|
+
push('observed-without-receipt', {
|
|
647
|
+
pattern: patternDigest(d.query),
|
|
648
|
+
objects: d.tables || [],
|
|
649
|
+
reason: 'multiplicity-exceeded',
|
|
650
|
+
})
|
|
651
|
+
}
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
for (const u of result.unobserved) {
|
|
655
|
+
push('receipted-without-observation', { objects: u.objects, ts: u.ts })
|
|
656
|
+
}
|
|
657
|
+
|
|
658
|
+
const exceptions =
|
|
659
|
+
counts['observed-without-receipt'] > 0 ||
|
|
660
|
+
counts['receipted-without-observation'] > 0 ||
|
|
661
|
+
counts.indeterminate > 0
|
|
662
|
+
|
|
663
|
+
return {
|
|
664
|
+
v: RESULT_V2,
|
|
665
|
+
window: result.window,
|
|
666
|
+
source: result.source,
|
|
667
|
+
snapshots: {
|
|
668
|
+
start: sha256Of(ctx.snapshotStartRaw),
|
|
669
|
+
end: sha256Of(ctx.snapshotEndRaw),
|
|
670
|
+
},
|
|
671
|
+
receipts: sha256Of(ctx.receiptsRaw),
|
|
672
|
+
profile: profile
|
|
673
|
+
? { digest: sha256Of(ctx.profileRaw), version: profile.version }
|
|
674
|
+
: null,
|
|
675
|
+
bounds: {
|
|
676
|
+
multiplicity: max != null ? 'operator-declared' : 'undeclared',
|
|
677
|
+
skew: result.clocks.declaredSkewMs !== null ? 'operator-declared' : 'undeclared',
|
|
678
|
+
exclusion: exclusionBoundDeclared ? 'operator-declared' : 'undeclared',
|
|
679
|
+
},
|
|
680
|
+
outcome: exceptions ? 'exceptions' : 'no-exceptions',
|
|
681
|
+
items,
|
|
682
|
+
counts,
|
|
683
|
+
}
|
|
684
|
+
}
|
|
685
|
+
|
|
448
686
|
// ─── CLI ─────────────────────────────────────────────────────────────────────
|
|
449
687
|
|
|
450
688
|
function usage(msg) {
|
|
451
689
|
if (msg) console.error(msg)
|
|
452
690
|
console.error(
|
|
453
|
-
'Usage: conarium-reconcile --before <snapshot.json> --after <snapshot.json> --receipts <receipts.jsonl> [--skew <duration>] [--json]',
|
|
691
|
+
'Usage: conarium-reconcile --before <snapshot.json> --after <snapshot.json> --receipts <receipts.jsonl> [--skew <duration>] [--profile <path>] [--json] [--json-v2] [--result-v2 <path>]',
|
|
454
692
|
)
|
|
455
693
|
console.error(
|
|
456
694
|
' --skew how far the gateway clock may differ from the database clock (e.g. 500ms, 5s, 2m).',
|
|
@@ -478,7 +716,16 @@ export function parseDuration(text) {
|
|
|
478
716
|
}
|
|
479
717
|
|
|
480
718
|
function parseArgs(argv) {
|
|
481
|
-
const out = {
|
|
719
|
+
const out = {
|
|
720
|
+
before: null,
|
|
721
|
+
after: null,
|
|
722
|
+
receiptsPath: null,
|
|
723
|
+
profilePath: null,
|
|
724
|
+
json: false,
|
|
725
|
+
jsonV2: false,
|
|
726
|
+
resultV2: null,
|
|
727
|
+
skewMs: null,
|
|
728
|
+
}
|
|
482
729
|
const args = [...argv]
|
|
483
730
|
while (args.length) {
|
|
484
731
|
const a = args.shift()
|
|
@@ -491,6 +738,9 @@ function parseArgs(argv) {
|
|
|
491
738
|
} else if (a === '--receipts') {
|
|
492
739
|
out.receiptsPath = args.shift() ?? null
|
|
493
740
|
if (!out.receiptsPath) throw new Error('--receipts requires a path')
|
|
741
|
+
} else if (a === '--profile') {
|
|
742
|
+
out.profilePath = args.shift() ?? null
|
|
743
|
+
if (!out.profilePath) throw new Error('--profile requires a path')
|
|
494
744
|
} else if (a === '--skew') {
|
|
495
745
|
const raw = args.shift() ?? null
|
|
496
746
|
if (!raw) throw new Error('--skew requires a duration (e.g. 500ms, 5s, 2m)')
|
|
@@ -499,6 +749,11 @@ function parseArgs(argv) {
|
|
|
499
749
|
out.skewMs = ms
|
|
500
750
|
} else if (a === '--json') {
|
|
501
751
|
out.json = true
|
|
752
|
+
} else if (a === '--json-v2') {
|
|
753
|
+
out.jsonV2 = true
|
|
754
|
+
} else if (a === '--result-v2') {
|
|
755
|
+
out.resultV2 = args.shift() ?? null
|
|
756
|
+
if (!out.resultV2) throw new Error('--result-v2 requires a path')
|
|
502
757
|
} else if (a === '--help' || a === '-h') {
|
|
503
758
|
usage()
|
|
504
759
|
process.exit(0)
|
|
@@ -506,6 +761,9 @@ function parseArgs(argv) {
|
|
|
506
761
|
throw new Error(`unexpected argument: ${a}`)
|
|
507
762
|
}
|
|
508
763
|
}
|
|
764
|
+
if (out.json && out.jsonV2) {
|
|
765
|
+
throw new Error('--json and --json-v2 cannot share a body; a consumer MUST NOT read a /1 result as a /2 result')
|
|
766
|
+
}
|
|
509
767
|
return out
|
|
510
768
|
}
|
|
511
769
|
|
|
@@ -540,14 +798,40 @@ async function main(argv = process.argv.slice(2)) {
|
|
|
540
798
|
const rec = loadReceipts(opts.receiptsPath)
|
|
541
799
|
if (rec.error) fail(20, rec.error, opts.json)
|
|
542
800
|
|
|
543
|
-
|
|
801
|
+
let profile = null
|
|
802
|
+
let profileRaw = Buffer.from('')
|
|
803
|
+
if (opts.profilePath) {
|
|
804
|
+
const loaded = loadMappingProfile(opts.profilePath)
|
|
805
|
+
if (loaded.error) fail(20, loaded.error, opts.json)
|
|
806
|
+
profile = loaded.profile
|
|
807
|
+
profileRaw = loaded.raw
|
|
808
|
+
}
|
|
809
|
+
|
|
810
|
+
const resolved = resolveDeclaredSkew(opts.skewMs, profile?.clocks?.skewMs ?? null)
|
|
811
|
+
if (resolved.error) fail(20, resolved.error, opts.json)
|
|
812
|
+
|
|
813
|
+
const result = reconcile(b.snapshot, a.snapshot, rec.receipts, { skewMs: resolved.skewMs })
|
|
544
814
|
if (result.error) fail(20, result.error, opts.json)
|
|
545
815
|
|
|
816
|
+
const wantV2 = opts.jsonV2 || opts.resultV2
|
|
817
|
+
const v2 = wantV2
|
|
818
|
+
? projectResultV2(result, {
|
|
819
|
+
profile,
|
|
820
|
+
profileRaw,
|
|
821
|
+
snapshotStartRaw: readFileSync(opts.before),
|
|
822
|
+
snapshotEndRaw: readFileSync(opts.after),
|
|
823
|
+
receiptsRaw: readFileSync(opts.receiptsPath),
|
|
824
|
+
})
|
|
825
|
+
: null
|
|
826
|
+
if (opts.resultV2) writeFileSync(opts.resultV2, JSON.stringify(v2) + '\n')
|
|
827
|
+
|
|
546
828
|
const problems = result.unreconciled.length + result.unattributed.length
|
|
547
829
|
const undecided = result.indeterminate.length
|
|
548
830
|
const exitCode = problems > 0 ? 40 : undecided > 0 ? 41 : 0
|
|
549
831
|
|
|
550
|
-
if (opts.
|
|
832
|
+
if (opts.jsonV2) {
|
|
833
|
+
console.log(JSON.stringify(v2))
|
|
834
|
+
} else if (opts.json) {
|
|
551
835
|
console.log(JSON.stringify({ ok: exitCode === 0, code: exitCode, ...result }))
|
|
552
836
|
} else {
|
|
553
837
|
console.log(
|
|
@@ -593,8 +877,8 @@ async function main(argv = process.argv.slice(2)) {
|
|
|
593
877
|
if (atBoundary.length > 0) {
|
|
594
878
|
const bound =
|
|
595
879
|
result.clocks.declaredSkewMs === null
|
|
596
|
-
? 'no
|
|
597
|
-
: `declared
|
|
880
|
+
? 'no skew bound was declared (--skew or Mapping Profile clocks.skew), so the window\'s own length is the only reference'
|
|
881
|
+
: `declared skew bound is ${result.clocks.declaredSkewMs}ms`
|
|
598
882
|
console.error(
|
|
599
883
|
`INDETERMINATE: ${atBoundary.length} pattern(s) are uncovered only by the window boundary — ${bound}:`,
|
|
600
884
|
)
|
package/bin/conarium-stamp.mjs
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* conarium-stamp — timestamp a document to OpenTimestamps.
|
|
4
4
|
*
|
|
5
|
-
* Receipts
|
|
6
|
-
* file, a coverage declaration, a prior-art scan —
|
|
5
|
+
* Receipts are not anchored by the write path. Documents — a specification, a policy
|
|
6
|
+
* file, a coverage declaration, a prior-art scan — are stamped here, and a git commit date
|
|
7
7
|
* is not evidence: `git commit --date` accepts anything you type.
|
|
8
8
|
*
|
|
9
9
|
* This stamps the SHA-256 of a file to the OpenTimestamps calendars and writes a
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-clocks-declared",
|
|
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-1.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-customers-early.jsonl",
|
|
10
|
+
"mappingProfile": "conformance/fixtures/reconciliation/profile-clocks.json",
|
|
11
|
+
"expectOutcome": "exceptions",
|
|
12
|
+
"expectItemOutcomes": ["indeterminate"],
|
|
13
|
+
"expectBounds": { "skew": "operator-declared" },
|
|
14
|
+
"rationale": "A Mapping Profile that states observation clock, receipt clock, and skew bound makes bounds.skew operator-declared. The 3s-outside receipt stays indeterminate — declaring the bound does not invent a match.",
|
|
15
|
+
"doesNotTest": "Whether 5s is true of the deployment. A --skew flag that disagrees with the profile. Those are the conflict tests."
|
|
16
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-clocks-undeclared-profile",
|
|
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-1.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-customers-early.jsonl",
|
|
10
|
+
"mappingProfile": "conformance/fixtures/reconciliation/profile-no-clocks.json",
|
|
11
|
+
"expectOutcome": "exceptions",
|
|
12
|
+
"expectItemOutcomes": ["indeterminate"],
|
|
13
|
+
"expectBounds": { "skew": "undeclared" },
|
|
14
|
+
"rationale": "A Mapping Profile that omits clocks leaves bounds.skew undeclared. The window-boundary item stays indeterminate. Presence of a profile is not a skew declaration.",
|
|
15
|
+
"doesNotTest": "A profile that does declare clocks. That is v2-clocks-declared."
|
|
16
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-excluded",
|
|
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-set.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-empty.jsonl",
|
|
10
|
+
"mappingProfile": "conformance/fixtures/reconciliation/profile-exclusion.json",
|
|
11
|
+
"expectOutcome": "no-exceptions",
|
|
12
|
+
"expectCounts": { "excluded": 1, "indeterminate": 0 },
|
|
13
|
+
"expectItemOutcomes": ["excluded"],
|
|
14
|
+
"rationale": "Session housekeeping is excluded by a Mapping Profile rule. The exclusion is pinned to the profile digest. Pinning is not justification.",
|
|
15
|
+
"doesNotTest": "Whether excluding SET is the right operational choice. A profile that omits the rule. That is v2-neg-undeclared-exclusion."
|
|
16
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-indeterminate",
|
|
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-1.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-customers-early.jsonl",
|
|
10
|
+
"expectOutcome": "exceptions",
|
|
11
|
+
"expectItemOutcomes": ["indeterminate"],
|
|
12
|
+
"rationale": "The only naming receipt sits three seconds outside the window. /2 reports indeterminate. The item is not observed-without-receipt.",
|
|
13
|
+
"doesNotTest": "Which clock is wrong. The class exists because the tool cannot tell."
|
|
14
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-matched",
|
|
3
|
+
"regime": "conformance",
|
|
4
|
+
"profile": "GACS-C1",
|
|
5
|
+
"claim": "reconciliation",
|
|
6
|
+
"harness": "reconcile-v2",
|
|
7
|
+
"before": "conformance/fixtures/reconciliation/before-customers-10.json",
|
|
8
|
+
"after": "conformance/fixtures/reconciliation/after-customers-15.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-customers.jsonl",
|
|
10
|
+
"mappingProfile": "conformance/fixtures/reconciliation/profile-multiplicity.json",
|
|
11
|
+
"expectOutcome": "no-exceptions",
|
|
12
|
+
"expectCounts": { "matched": 1, "indeterminate": 0 },
|
|
13
|
+
"forbidItemOutcomes": [],
|
|
14
|
+
"rationale": "A declared multiplicity bound lets a naming receipt match a pattern whose delta is inside the bound. /2 outcome is no-exceptions.",
|
|
15
|
+
"doesNotTest": "Whether the bound is true of the deployment. The profile is an operator statement."
|
|
16
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-neg-unattributed",
|
|
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-unattributed.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-empty.jsonl",
|
|
10
|
+
"expectOutcome": "exceptions",
|
|
11
|
+
"expectItemOutcomes": ["indeterminate"],
|
|
12
|
+
"forbidItemOutcomes": ["observed-without-receipt"],
|
|
13
|
+
"rationale": "Negative: a counted pattern with no extractable table is indeterminate. It must not share the observed-without-receipt / NOT RECEIPTED class.",
|
|
14
|
+
"doesNotTest": "Whether the SQL could be attributed by a better parser. The report is about this parser's refusal to guess."
|
|
15
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-neg-undeclared-exclusion",
|
|
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-set.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-empty.jsonl",
|
|
10
|
+
"expectOutcome": "exceptions",
|
|
11
|
+
"expectCounts": { "excluded": 0, "indeterminate": 1 },
|
|
12
|
+
"expectItemOutcomes": ["indeterminate"],
|
|
13
|
+
"forbidItemOutcomes": ["excluded"],
|
|
14
|
+
"rationale": "Negative: session housekeeping with no Mapping Profile. /2 must not exclude — the exclusion bound was never declared. The item is indeterminate; outcome is exceptions.",
|
|
15
|
+
"doesNotTest": "A profile that does declare the exclusion rule. That is v2-excluded."
|
|
16
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-neg-undeclared-multiplicity",
|
|
3
|
+
"regime": "conformance",
|
|
4
|
+
"profile": "GACS-C1",
|
|
5
|
+
"claim": "reconciliation",
|
|
6
|
+
"harness": "reconcile-v2",
|
|
7
|
+
"before": "conformance/fixtures/reconciliation/before-customers-10.json",
|
|
8
|
+
"after": "conformance/fixtures/reconciliation/after-customers-15.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-customers.jsonl",
|
|
10
|
+
"expectOutcome": "exceptions",
|
|
11
|
+
"expectCounts": { "matched": 0 },
|
|
12
|
+
"expectItemOutcomes": ["indeterminate"],
|
|
13
|
+
"forbidItemOutcomes": ["matched"],
|
|
14
|
+
"rationale": "Negative: five new calls, one naming receipt, no Mapping Profile. /1 exits 0. /2 must not report matched — the multiplicity bound was never declared.",
|
|
15
|
+
"doesNotTest": "A profile that does declare the bound. That is v2-matched."
|
|
16
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-neg-undeclared-skew",
|
|
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-1.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-customers-early.jsonl",
|
|
10
|
+
"expectOutcome": "exceptions",
|
|
11
|
+
"expectItemOutcomes": ["indeterminate"],
|
|
12
|
+
"expectBounds": { "skew": "undeclared" },
|
|
13
|
+
"rationale": "Negative: no Mapping Profile and no --skew. bounds.skew is undeclared. The item whose only naming receipt sits 3s outside the window is indeterminate.",
|
|
14
|
+
"doesNotTest": "A profile or flag that does declare the bound. That is v2-clocks-declared."
|
|
15
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-observed-without-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-1.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-empty.jsonl",
|
|
10
|
+
"expectOutcome": "exceptions",
|
|
11
|
+
"expectItemOutcomes": ["observed-without-receipt"],
|
|
12
|
+
"rationale": "A user-table pattern the database counted, with no naming receipt, is observed-without-receipt. /2 outcome is exceptions.",
|
|
13
|
+
"doesNotTest": "Cause. Bypass, sink failure, and scope mismatch produce the same item."
|
|
14
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "reconciliation/v2-receipted-without-observation",
|
|
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-empty.json",
|
|
9
|
+
"receipts": "conformance/fixtures/reconciliation/receipts-customers.jsonl",
|
|
10
|
+
"expectOutcome": "exceptions",
|
|
11
|
+
"expectItemOutcomes": ["receipted-without-observation"],
|
|
12
|
+
"rationale": "A receipt that names an object the counters did not increment is receipted-without-observation and makes outcome exceptions. /1 still exits 0.",
|
|
13
|
+
"doesNotTest": "Whether the receipt is false. A reset, a pooler, and a delayed increment share the shape."
|
|
14
|
+
}
|
|
@@ -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}]}
|
|
@@ -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":15}]}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"v":"conarium-dbsnapshot/0.1","ts":"2026-08-06T12:00:00.000Z","role":"conarium_c2","source":"pg_stat_statements","entries":[]}
|
|
@@ -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":"SET search_path TO public","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 $1 + $2","calls":3}]}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"v":"conarium-dbsnapshot/0.1","ts":"2026-08-06T10: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":10}]}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"v":"conarium-dbsnapshot/0.1","ts":"2026-08-06T10:00:00.000Z","role":"conarium_c2","source":"pg_stat_statements","entries":[]}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"v":"conarium-receipt/0.3","ts":"2026-08-06T09:59:57.000Z","request":{"tool":"query","target":"zion-rest","argsHash":"sha256:00"},"dataRefs":[{"source":"zion-rest","object":"zion.customers","fieldsRequested":[]}],"policy":{"decision":"allow"},"chain":{"seq":1}}
|