@mikeargento/bitgraph-player 0.1.0

package/dist/verdict.js

@@ -0,0 +1,146 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+/**
+ * Verdict construction and serialization.
+ *
+ * Determinism is the product claim, so this module is where it is
+ * enforced: no wall-clock reads, no random values, no filesystem paths,
+ * and a fixed field order. Two machines evaluating the same rule bytes
+ * over the same bundle contents must produce byte-identical verdicts.
+ *
+ * The verdict labels its own trust boundary. `derived` is what BitGraph
+ * established; `declared` is what a named party asserted and Player took
+ * on faith — including the closed world itself, which nothing in BitGraph
+ * establishes: "there is no cancellation before approval" and "among the
+ * recordings you told me to consider, none precedes approval" are
+ * different claims, and the closed-world entry is what keeps the verdict
+ * from passing the first off as the second.
+ */
+import { readFileSync } from "node:fs";
+import { normalizeDigest } from "./rule.js";
+let cachedVersion;
+/** The player package's own version, read once from its package.json. */
+export function playerVersion() {
+    if (cachedVersion === undefined) {
+        const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+        cachedVersion = JSON.parse(raw).version;
+    }
+    return cachedVersion;
+}
+function resolutionLabel(res) {
+    switch (res.kind) {
+        case "resolved":
+            return "resolved";
+        case "absent":
+            return res.optional ? "absent-optional" : "absent-required";
+        case "ambiguous":
+            return "ambiguous";
+        case "invalid":
+            return "invalid";
+    }
+}
+export function buildVerdict(rule, ruleSha256Hex, resolutions, evaluation, audit) {
+    // Cast summary, in declaration order. Null prototype so a role named
+    // "__proto__" serializes as an ordinary key.
+    const cast = Object.create(null);
+    for (const [role, entry] of Object.entries(rule.cast)) {
+        const res = resolutions.get(role);
+        const summary = {
+            digestB64: normalizeDigest(entry.digest),
+            resolution: resolutionLabel(res),
+        };
+        if (res.kind === "resolved") {
+            summary.proofHash = res.proof.proofHash;
+            if (res.proof.epochId !== undefined)
+                summary.epochId = res.proof.epochId;
+            summary.chainId = res.proof.chainId;
+            if (res.proof.counter !== undefined)
+                summary.counter = res.proof.counter;
+            if (res.proof.slotCounter !== undefined)
+                summary.slotCounter = res.proof.slotCounter;
+        }
+        cast[role] = summary;
+    }
+    // Declared assertions, in cast declaration order, closed world last.
+    const declared = [];
+    for (const [role, entry] of Object.entries(rule.cast)) {
+        if (entry.means !== undefined) {
+            declared.push({
+                assertion: "means",
+                role,
+                verifiedHere: false,
+                means: entry.means,
+                digestB64: normalizeDigest(entry.digest),
+            });
+        }
+    }
+    for (const [role, entry] of Object.entries(rule.cast)) {
+        if (entry.at !== undefined) {
+            declared.push({
+                assertion: "pinned-occurrence",
+                role,
+                verifiedHere: false,
+                at: entry.at,
+            });
+        }
+    }
+    for (const [role, entry] of Object.entries(rule.cast)) {
+        if (entry.signedBy !== undefined) {
+            declared.push({
+                assertion: "signedBy",
+                role,
+                verifiedHere: false,
+                evidence: entry.signedBy,
+            });
+        }
+    }
+    declared.push({
+        assertion: "closed-world",
+        verifiedHere: false,
+        castSize: Object.keys(rule.cast).length,
+        recordingsInBundle: audit.ingest.counts.observed,
+        claim: "Absence is asserted only among the declared cast. Nothing in BitGraph establishes that the declared cast is complete; that completeness is the rule author's assertion.",
+    });
+    const verdict = {
+        verdict: "bitgraph-player-verdict/1",
+        result: evaluation.result,
+        rule: { id: rule.id, sha256: ruleSha256Hex },
+        cast,
+        derived: evaluation.steps,
+        declared,
+        evaluator: { name: "@mikeargento/bitgraph-player", version: playerVersion() },
+        network: "none",
+    };
+    if (rule.then !== undefined)
+        verdict.then = rule.then;
+    if (evaluation.weakestEvidence !== undefined) {
+        verdict.weakestEvidence = evaluation.weakestEvidence;
+    }
+    return verdict;
+}
+/**
+ * Deterministic bytes. Fixed key order (construction order), two-space
+ * indent, trailing newline. No timestamp: a `generatedAt` field would
+ * break byte-identical reproduction, which is the entire product claim.
+ * If a run timestamp is wanted it belongs in a sidecar, never here.
+ */
+export function serializeVerdict(verdict) {
+    // Emit top-level fields in the canonical order regardless of
+    // construction history, so optional fields land in a fixed place.
+    const ordered = {
+        verdict: verdict.verdict,
+        result: verdict.result,
+        rule: verdict.rule,
+    };
+    if (verdict.then !== undefined)
+        ordered["then"] = verdict.then;
+    if (verdict.weakestEvidence !== undefined) {
+        ordered["weakestEvidence"] = verdict.weakestEvidence;
+    }
+    ordered["cast"] = verdict.cast;
+    ordered["derived"] = verdict.derived;
+    ordered["declared"] = verdict.declared;
+    ordered["evaluator"] = verdict.evaluator;
+    ordered["network"] = verdict.network;
+    return JSON.stringify(ordered, null, 2) + "\n";
+}
+//# sourceMappingURL=verdict.js.map

package/dist/verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../src/verdict.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mikeargento/bitgraph-player",
+  "version": "0.1.0",
+  "description": "Deterministic evaluation of causal rules over BitGraph proof bundles: a pure function from (rule, verified evidence) to a reproducible verdict.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "bitgraph-play": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "SPEC.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc && node --test \"dist/__tests__/*.test.js\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@mikeargento/bitgraph-audit": "^0.1.3",
+    "@mikeargento/bitgraph-verify": "^1.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/__tests__/cast-order.test.ts

@@ -0,0 +1,473 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { resolveRole } from "../cast.js";
+import { compare } from "../order.js";
+import { digestFor, makeAudit, proofHashOf } from "./fixtures.js";
+import type { ObservedProof } from "@mikeargento/bitgraph-audit";
+
+const D1 = digestFor("doc-one");
+const D2 = digestFor("doc-two");
+
+function proofByName(audit: ReturnType<typeof makeAudit>, name: string): ObservedProof {
+  const p = audit.ingest.proofs.find((x) => x.proofHash === proofHashOf(name));
+  assert.ok(p, `fixture proof ${name}`);
+  return p as ObservedProof;
+}
+
+// ---------------------------------------------------------------------------
+// Cast resolution: the multiplicity table.
+// ---------------------------------------------------------------------------
+
+test("exactly one verified match resolves", () => {
+  const audit = makeAudit({
+    proofs: [{ name: "a", digestB64: D1, epochId: "E1", counter: "10" }],
+    partitions: [{ epochId: "E1", members: ["a"] }],
+  });
+  const res = resolveRole("doc", { digest: D1 }, audit);
+  assert.equal(res.kind, "resolved");
+});
+
+test("zero matches: absent, optional vs required distinguished", () => {
+  const audit = makeAudit({ proofs: [] });
+  const required = resolveRole("doc", { digest: D1 }, audit);
+  assert.deepEqual(required, { kind: "absent", role: "doc", optional: false });
+  const optional = resolveRole("doc", { digest: D1, optional: true }, audit);
+  assert.deepEqual(optional, { kind: "absent", role: "doc", optional: true });
+});
+
+test("two recordings of the same bits with no pin is ambiguous, never a silent pick", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a1", digestB64: D1, epochId: "E1", counter: "10" },
+      { name: "a2", digestB64: D1, epochId: "E2", counter: "3" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a1"] },
+      { epochId: "E2", members: ["a2"], publicKeyB64: "key-B" },
+    ],
+  });
+  const res = resolveRole("doc", { digest: D1 }, audit);
+  assert.equal(res.kind, "ambiguous");
+  assert.equal((res as { matchCount: number }).matchCount, 2);
+});
+
+test("a pin selects one occurrence among several", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a1", digestB64: D1, epochId: "E1", counter: "10" },
+      { name: "a2", digestB64: D1, epochId: "E2", counter: "3" },
+    ],
+  });
+  const byHash = resolveRole("doc", { digest: D1, at: { proofHash: proofHashOf("a2") } }, audit);
+  assert.equal(byHash.kind, "resolved");
+  assert.equal((byHash as { proof: ObservedProof }).proof.proofHash, proofHashOf("a2"));
+
+  const byPosition = resolveRole(
+    "doc",
+    { digest: D1, at: { epochId: "E1", counter: "10" } },
+    audit
+  );
+  assert.equal(byPosition.kind, "resolved");
+  assert.equal((byPosition as { proof: ObservedProof }).proof.proofHash, proofHashOf("a1"));
+});
+
+test("a pin matching nothing is invalid, not silently ignored", () => {
+  const audit = makeAudit({
+    proofs: [{ name: "a1", digestB64: D1, epochId: "E1", counter: "10" }],
+  });
+  const res = resolveRole("doc", { digest: D1, at: { proofHash: "nope" } }, audit);
+  assert.equal(res.kind, "invalid");
+});
+
+test("matches that all fail verification are invalid, not absent", () => {
+  // "Only broken recordings" and "no recordings" are different situations:
+  // only the second supports a closed-world absence claim.
+  const audit = makeAudit({
+    proofs: [{ name: "a1", digestB64: D1, epochId: "E1", counter: "10", verified: false }],
+  });
+  const res = resolveRole("doc", { digest: D1, optional: true }, audit);
+  assert.equal(res.kind, "invalid");
+});
+
+test("a failed-verification copy does not shadow the verified recording", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "bad", digestB64: D1, epochId: "E1", counter: "9", verified: false },
+      { name: "good", digestB64: D1, epochId: "E1", counter: "10" },
+    ],
+  });
+  const res = resolveRole("doc", { digest: D1 }, audit);
+  assert.equal(res.kind, "resolved");
+  assert.equal((res as { proof: ObservedProof }).proof.proofHash, proofHashOf("good"));
+});
+
+// ---------------------------------------------------------------------------
+// Ordering: same partition.
+// ---------------------------------------------------------------------------
+
+test("a directed prevB64 path is chain-link, strict, both directions", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "10" },
+      { name: "b", digestB64: D2, epochId: "E1", counter: "20", prev: "a" },
+    ],
+    partitions: [{ epochId: "E1", members: ["a", "b"], components: [["a", "b"]] }],
+  });
+  const ab = compare(proofByName(audit, "a"), proofByName(audit, "b"), audit);
+  assert.equal(ab.relation, "before");
+  assert.equal(ab.basis, "chain-link");
+  assert.equal(ab.tier, "hash-linked");
+  assert.equal(ab.weaker, false);
+  assert.equal(ab.assumptionDependent, false);
+  const ba = compare(proofByName(audit, "b"), proofByName(audit, "a"), audit);
+  assert.equal(ba.relation, "after");
+});
+
+test("fork branches with no path between them are counter-order, NOT chain-link", () => {
+  // Predecessor-reuse fork: x and y both link to g, no path between them.
+  // Their relative order rests solely on counter discipline — which the
+  // fork itself demonstrates is broken — so the hash-linked tier must not
+  // be claimed even though all three share one undirected component.
+  const audit = makeAudit({
+    proofs: [
+      { name: "g", digestB64: digestFor("genesis"), epochId: "E1", counter: "1" },
+      { name: "x", digestB64: D1, epochId: "E1", counter: "2", prev: "g" },
+      { name: "y", digestB64: D2, epochId: "E1", counter: "3", prev: "g" },
+    ],
+    partitions: [{ epochId: "E1", members: ["g", "x", "y"], components: [["g", "x", "y"]] }],
+  });
+  const xy = compare(proofByName(audit, "x"), proofByName(audit, "y"), audit);
+  assert.equal(xy.relation, "before");
+  assert.equal(xy.basis, "counter-order");
+  assert.equal(xy.tier, "assumption-dependent");
+  assert.equal(xy.weaker, true);
+});
+
+test("a verified path contradicted by the counters is an anomaly, not an order", () => {
+  // b hash-links after a, but b's counter is SMALLER: link and counter
+  // evidence disagree, so neither may answer.
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "20" },
+      { name: "b", digestB64: D2, epochId: "E1", counter: "10", prev: "a" },
+    ],
+    partitions: [{ epochId: "E1", members: ["a", "b"], components: [["a", "b"]] }],
+  });
+  assert.equal(compare(proofByName(audit, "a"), proofByName(audit, "b"), audit).relation, "unordered");
+});
+
+test("non-decimal counters are no counter evidence: no crash, no fabricated order", () => {
+  for (const bad of ["abc", "1e5", "0x10", "-3", " 7 ", ""]) {
+    const audit = makeAudit({
+      proofs: [
+        { name: "a", digestB64: D1, epochId: "E1", counter: bad },
+        { name: "b", digestB64: D2, epochId: "E1", counter: "20" },
+      ],
+      partitions: [{ epochId: "E1", members: ["a", "b"], components: [["a"], ["b"]] }],
+    });
+    const result = compare(proofByName(audit, "a"), proofByName(audit, "b"), audit);
+    assert.equal(result.relation, "unordered", `counter ${JSON.stringify(bad)}`);
+  }
+});
+
+test("different components in one partition: counter-order, assumption-dependent", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "10" },
+      { name: "b", digestB64: D2, epochId: "E1", counter: "20" },
+    ],
+    partitions: [{ epochId: "E1", members: ["a", "b"], components: [["a"], ["b"]] }],
+  });
+  const ab = compare(proofByName(audit, "a"), proofByName(audit, "b"), audit);
+  assert.equal(ab.relation, "before");
+  assert.equal(ab.basis, "counter-order");
+  assert.equal(ab.assumptionDependent, true);
+  assert.equal(ab.weaker, true);
+});
+
+test("interleaved slot/commit ranges with clear commit order is BEFORE, not needless UNDETERMINED", () => {
+  // A reserved its slot first (48) but committed second (51); B reserved
+  // second (49) but committed first (50). The artifact position is the
+  // commit position; commit order decides.
+  const audit = makeAudit({
+    proofs: [
+      { name: "b", digestB64: D2, epochId: "E1", counter: "50", slotCounter: "49" },
+      { name: "a", digestB64: D1, epochId: "E1", counter: "51", slotCounter: "48", prev: "b" },
+    ],
+    partitions: [{ epochId: "E1", members: ["a", "b"], components: [["a", "b"]] }],
+  });
+  const ba = compare(proofByName(audit, "b"), proofByName(audit, "a"), audit);
+  assert.equal(ba.relation, "before");
+  assert.equal(ba.basis, "chain-link");
+});
+
+test("equal commit counters on distinct recordings is an anomaly, not an order", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "10" },
+      { name: "b", digestB64: D2, epochId: "E1", counter: "10" },
+    ],
+    partitions: [{ epochId: "E1", members: ["a", "b"], components: [["a"], ["b"]] }],
+  });
+  assert.equal(compare(proofByName(audit, "a"), proofByName(audit, "b"), audit).relation, "unordered");
+});
+
+test("same recording for both roles is 'same'", () => {
+  const audit = makeAudit({
+    proofs: [{ name: "a", digestB64: D1, epochId: "E1", counter: "10" }],
+    partitions: [{ epochId: "E1", members: ["a"] }],
+  });
+  const p = proofByName(audit, "a");
+  assert.equal(compare(p, p, audit).relation, "same");
+});
+
+// ---------------------------------------------------------------------------
+// Ordering: across partitions and epochs.
+// ---------------------------------------------------------------------------
+
+test("same epochId under different signer keys is not counter-comparable", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "10", publicKeyB64: "key-A" },
+      { name: "b", digestB64: D2, epochId: "E1", counter: "20", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a"], publicKeyB64: "key-A" },
+      { epochId: "E1", members: ["b"], publicKeyB64: "key-B" },
+    ],
+  });
+  assert.equal(compare(proofByName(audit, "a"), proofByName(audit, "b"), audit).relation, "unordered");
+});
+
+test("a covered epochLink succession orders the pair at the hash-linked tier", () => {
+  // a IS the referenced predecessor; b carries the link (successor key).
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "999", publicKeyB64: "key-A" },
+      { name: "b", digestB64: D2, epochId: "E2", counter: "1", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a"], publicKeyB64: "key-A" },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+    ],
+    edges: [{ predecessor: "a", via: "b" }],
+  });
+  const ab = compare(proofByName(audit, "a"), proofByName(audit, "b"), audit);
+  assert.equal(ab.relation, "before");
+  assert.equal(ab.basis, "epoch-lineage");
+  assert.equal(ab.tier, "hash-linked");
+  assert.equal(ab.assumptionDependent, false);
+  const ba = compare(proofByName(audit, "b"), proofByName(audit, "a"), audit);
+  assert.equal(ba.relation, "after");
+});
+
+test("lineage covers a path-linked ancestor of the referenced predecessor at hash-linked tier", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a0", digestB64: digestFor("earlier"), epochId: "E1", counter: "5", publicKeyB64: "key-A" },
+      { name: "p", digestB64: D1, epochId: "E1", counter: "999", publicKeyB64: "key-A", prev: "a0" },
+      { name: "b", digestB64: D2, epochId: "E2", counter: "1", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a0", "p"], publicKeyB64: "key-A", components: [["a0", "p"]] },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+    ],
+    edges: [{ predecessor: "p", via: "b" }],
+  });
+  const result = compare(proofByName(audit, "a0"), proofByName(audit, "b"), audit);
+  assert.equal(result.relation, "before");
+  assert.equal(result.tier, "hash-linked");
+});
+
+test("counter-only predecessor coverage downgrades lineage to the assumption-dependent tier", () => {
+  // a1 is not path-linked to the referenced predecessor p; only its
+  // smaller counter places it before p, so the whole answer rests on
+  // counter discipline.
+  const audit = makeAudit({
+    proofs: [
+      { name: "a1", digestB64: digestFor("unlinked"), epochId: "E1", counter: "7", publicKeyB64: "key-A" },
+      { name: "p", digestB64: D1, epochId: "E1", counter: "999", publicKeyB64: "key-A" },
+      { name: "b", digestB64: D2, epochId: "E2", counter: "1", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a1", "p"], publicKeyB64: "key-A", components: [["a1"], ["p"]] },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+    ],
+    edges: [{ predecessor: "p", via: "b" }],
+  });
+  const result = compare(proofByName(audit, "a1"), proofByName(audit, "b"), audit);
+  assert.equal(result.relation, "before");
+  assert.equal(result.basis, "epoch-lineage");
+  assert.equal(result.tier, "assumption-dependent");
+});
+
+test("lineage does NOT cover a recording after the referenced predecessor", () => {
+  // a2's counter exceeds the referenced predecessor's: the link only
+  // evidences that E2 began after p existed, which says nothing about a2.
+  const audit = makeAudit({
+    proofs: [
+      { name: "p", digestB64: D1, epochId: "E1", counter: "10", publicKeyB64: "key-A" },
+      { name: "a2", digestB64: digestFor("later"), epochId: "E1", counter: "999", publicKeyB64: "key-A" },
+      { name: "b", digestB64: D2, epochId: "E2", counter: "1", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["p", "a2"], publicKeyB64: "key-A", components: [["p"], ["a2"]] },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+    ],
+    edges: [{ predecessor: "p", via: "b" }],
+  });
+  assert.equal(compare(proofByName(audit, "a2"), proofByName(audit, "b"), audit).relation, "unordered");
+});
+
+test("a self-declared epochId string cannot ride another epoch's lineage", () => {
+  // evil declares epochId "E2" under its own key; the lineage edge covers
+  // only the partition the via proof belongs to, so evil gets nothing.
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "10", publicKeyB64: "key-A" },
+      { name: "b", digestB64: digestFor("real-successor"), epochId: "E2", counter: "1", publicKeyB64: "key-B" },
+      { name: "evil", digestB64: D2, epochId: "E2", counter: "1", publicKeyB64: "key-EVIL" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a"], publicKeyB64: "key-A" },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+      { epochId: "E2", members: ["evil"], publicKeyB64: "key-EVIL" },
+    ],
+    edges: [{ predecessor: "a", via: "b" }],
+  });
+  assert.equal(compare(proofByName(audit, "a"), proofByName(audit, "evil"), audit).relation, "unordered");
+});
+
+test("anchor bounds order cross-epoch recordings only on strict block inequality", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "5", publicKeyB64: "key-A" },
+      { name: "b", digestB64: D2, epochId: "E2", counter: "5", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a"], publicKeyB64: "key-A" },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+    ],
+    segments: [
+      {
+        members: ["a"],
+        upperBounds: [{ blockNumber: "100", timestamp: 1000, basis: "causal-precedence" }],
+      },
+      {
+        members: ["b"],
+        lowerBounds: [{ blockNumber: "200", timestamp: 2000 }],
+      },
+    ],
+  });
+  const ab = compare(proofByName(audit, "a"), proofByName(audit, "b"), audit);
+  assert.equal(ab.relation, "before");
+  assert.equal(ab.basis, "anchor-bounds");
+  assert.equal(ab.assumptionDependent, true);
+  const ba = compare(proofByName(audit, "b"), proofByName(audit, "a"), audit);
+  assert.equal(ba.relation, "after");
+});
+
+test("equal anchor blocks prove nothing: overlapping windows stay unordered", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "5", publicKeyB64: "key-A" },
+      { name: "b", digestB64: D2, epochId: "E2", counter: "5", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a"], publicKeyB64: "key-A" },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+    ],
+    segments: [
+      { members: ["a"], upperBounds: [{ blockNumber: "100", timestamp: 1000 }] },
+      { members: ["b"], lowerBounds: [{ blockNumber: "100", timestamp: 1000 }] },
+    ],
+  });
+  assert.equal(compare(proofByName(audit, "a"), proofByName(audit, "b"), audit).relation, "unordered");
+});
+
+test("anchor bounds strict in BOTH directions are contradictory: unordered", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "5", publicKeyB64: "key-A" },
+      { name: "b", digestB64: D2, epochId: "E2", counter: "5", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a"], publicKeyB64: "key-A" },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+    ],
+    segments: [
+      {
+        members: ["a"],
+        upperBounds: [{ blockNumber: "100", timestamp: 1000 }],
+        lowerBounds: [{ blockNumber: "500", timestamp: 5000 }],
+      },
+      {
+        members: ["b"],
+        upperBounds: [{ blockNumber: "100", timestamp: 1000 }],
+        lowerBounds: [{ blockNumber: "500", timestamp: 5000 }],
+      },
+    ],
+  });
+  assert.equal(compare(proofByName(audit, "a"), proofByName(audit, "b"), audit).relation, "unordered");
+});
+
+test("integrity-tier passes resolve: a proof verified without artifact bytes is a recording", () => {
+  const audit = makeAudit({
+    proofs: [{ name: "a", digestB64: D1, epochId: "E1", counter: "10", tier: "integrity" }],
+    partitions: [{ epochId: "E1", members: ["a"] }],
+  });
+  const res = resolveRole("doc", { digest: D1 }, audit);
+  assert.equal(res.kind, "resolved");
+  assert.equal((res as { verificationTier: string }).verificationTier, "integrity");
+});
+
+test("weaker bound evidence propagates to the answer", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "5", publicKeyB64: "key-A" },
+      { name: "b", digestB64: D2, epochId: "E2", counter: "5", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a"], publicKeyB64: "key-A" },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+    ],
+    segments: [
+      {
+        members: ["a"],
+        upperBounds: [{ blockNumber: "100", timestamp: 1000, evidence: "counter-order", weaker: true }],
+      },
+      { members: ["b"], lowerBounds: [{ blockNumber: "200", timestamp: 2000 }] },
+    ],
+  });
+  const ab = compare(proofByName(audit, "a"), proofByName(audit, "b"), audit);
+  assert.equal(ab.relation, "before");
+  assert.equal(ab.weaker, true);
+});
+
+test("concurrent epochs with no evidence are unordered", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1, epochId: "E1", counter: "5", publicKeyB64: "key-A" },
+      { name: "b", digestB64: D2, epochId: "E2", counter: "5", publicKeyB64: "key-B" },
+    ],
+    partitions: [
+      { epochId: "E1", members: ["a"], publicKeyB64: "key-A" },
+      { epochId: "E2", members: ["b"], publicKeyB64: "key-B" },
+    ],
+  });
+  assert.equal(compare(proofByName(audit, "a"), proofByName(audit, "b"), audit).relation, "unordered");
+});
+
+test("chainless recordings hold no causal position to compare", () => {
+  const audit = makeAudit({
+    proofs: [
+      { name: "a", digestB64: D1 },
+      { name: "b", digestB64: D2, epochId: "E1", counter: "5" },
+    ],
+    partitions: [{ epochId: "E1", members: ["b"] }],
+    unchained: ["a"],
+  });
+  assert.equal(compare(proofByName(audit, "a"), proofByName(audit, "b"), audit).relation, "unordered");
+});