@mikeargento/bitgraph 1.1.0 → 1.2.0

package/src/__tests__/audit-real-fixtures.test.ts

@@ -0,0 +1,153 @@
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+
+/**
+ * Real-fixture audit test (Phase 4e, G8 honesty).
+ *
+ * Builds a bundle from the repo's real embedded fixtures and asserts the
+ * audit reports them honestly:
+ *
+ *   - REALISTIC_PROOF mirrors what the TEE actually produces: a
+ *     real-shaped Ethereum anchor proof with a TRUNCATED attestation blob
+ *     and a placeholder signature. It must be observed, identified as an
+ *     Ethereum anchor by its SIGNED attribution, fail verification with
+ *     the verifier's precise NON-version reason (the placeholder
+ *     signature), and its attestation must report document-present-but-
+ *     invalid (the truncated blob), never a pass and never a version
+ *     failure.
+ *
+ *   - MOCK_PROOF is placeholder values throughout; it fails on the first
+ *     canonical check its placeholders trip (the non-base64 digest), also
+ *     a non-version reason.
+ *
+ * The fixtures are used verbatim from their shared modules and are never
+ * edited.
+ */
+
+import { describe, it, before, after } from "node:test";
+import * as assert from "node:assert/strict";
+import { rm } from "node:fs/promises";
+import { computeProofHash } from "@mikeargento/bitgraph-verify";
+import { buildJsonReport, runAudit } from "@mikeargento/bitgraph-audit";
+import type { AuditResult } from "@mikeargento/bitgraph-audit";
+import { makeTempDir, writeBundleDir } from "./audit-fixtures.js";
+import { REALISTIC_PROOF } from "./realistic-proof-fixture.js";
+import { MOCK_PROOF } from "./mock-proof-fixture.js";
+
+describe("audit over the repo's real embedded fixtures", () => {
+  let dir: string;
+  let result: AuditResult;
+  const realisticHash = computeProofHash(REALISTIC_PROOF as unknown as Record<string, unknown>);
+  const mockHash = computeProofHash(MOCK_PROOF as unknown as Record<string, unknown>);
+
+  before(async () => {
+    dir = await makeTempDir("bitgraph-audit-real-fixtures-");
+    await writeBundleDir(dir, {
+      "proofs/realistic.json": JSON.stringify(REALISTIC_PROOF),
+      "proofs/mock.json": JSON.stringify(MOCK_PROOF),
+    });
+    result = await runAudit(dir);
+  });
+
+  after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("observes both fixtures; neither is a version reject", () => {
+    assert.equal(result.ingest.counts.observed, 2);
+    assert.equal(result.ingest.counts.unsupportedVersion, 0);
+    const hashes = result.ingest.proofs.map((p) => p.proofHash).sort();
+    assert.deepEqual(hashes, [realisticHash, mockHash].sort());
+  });
+
+  it("REALISTIC_PROOF fails verification with the precise non-version signature reason", () => {
+    const proof = result.ingest.proofs.find((p) => p.proofHash === realisticHash);
+    assert.equal(proof?.verification?.tier, "integrity");
+    assert.equal(proof?.verification?.status, "failed");
+    assert.equal(
+      proof?.verification?.reason,
+      "signature verification failed: signature does not match"
+    );
+    assert.ok(!(proof?.verification?.reason as string).includes("version"));
+  });
+
+  it("MOCK_PROOF fails verification with a precise non-version placeholder reason", () => {
+    const proof = result.ingest.proofs.find((p) => p.proofHash === mockHash);
+    assert.equal(proof?.verification?.status, "failed");
+    assert.equal(proof?.verification?.reason, "artifact.digestB64 is not valid base64");
+    assert.ok(!(proof?.verification?.reason as string).includes("version"));
+  });
+
+  it("nothing passes: no proof is ever reported verified or artifact-unavailable", () => {
+    assert.equal(result.verification.verified, 0);
+    assert.equal(result.verification.artifactUnavailable, 0);
+    assert.equal(result.verification.failed, 2);
+  });
+
+  it("REALISTIC_PROOF is identified as an Ethereum anchor by its signed attribution", () => {
+    assert.equal(result.anchors.anchors.length, 1);
+    const anchor = result.anchors.anchors[0]!;
+    assert.equal(anchor.proofHash, realisticHash);
+    assert.equal(anchor.blockNumber, "24800448");
+    assert.equal(
+      anchor.blockHash,
+      "0x28ed3639cd705fb8cb2b915c1991e9f808b40e775bc8eb540702942729fec2c0"
+    );
+    // No unsigned metadata on the fixture: absent corroboration, not disagreement.
+    assert.equal(anchor.metadataCorroboration, "absent");
+    // The verification failure rides along unmodified.
+    assert.equal(anchor.verificationStatus, "failed");
+    // MOCK_PROOF's attribution ("test") never identifies an anchor.
+    assert.ok(!result.anchors.anchors.some((a) => a.proofHash === mockHash));
+    // No witness in the bundle: causal identification only, no wall-clock evidence.
+    assert.deepEqual(result.temporal.verifiedAnchorProofHashes, []);
+    assert.deepEqual(result.temporal.unverifiedAnchorProofHashes, [realisticHash]);
+  });
+
+  it("REALISTIC_PROOF attestation reports document-present-but-invalid, never a pass", () => {
+    const record = result.attestations.records.find((r) => r.proofHash === realisticHash);
+    assert.ok(record !== undefined);
+    assert.equal(record.declaredMeasurementPresent, true);
+    assert.equal(
+      record.declaredMeasurement,
+      "638d655ad6091bed5c358628b7780de0cdbe138a37fe09d52bf8021a720680a2b3c730fee9f6bef79c1dbe68ef3cdd94"
+    );
+    assert.equal(record.attestationFormat, "aws-nitro");
+    assert.equal(record.documentPresent, true);
+    assert.equal(record.documentValidated, false);
+    // The truncated blob fails with a precise reason, never silently.
+    assert.equal(typeof record.validationFailure, "string");
+    assert.ok((record.validationFailure as string).length > 0);
+    // Facts derived from an unvalidated document are never asserted.
+    assert.equal(record.pcr0MatchesDeclared, undefined);
+    assert.equal(record.userDataBoundToProof, undefined);
+    // Aggregates: documents present on both fixtures, zero validated.
+    assert.equal(result.attestations.counts.proofsWithDocument, 2);
+    assert.equal(result.attestations.counts.documentsValidated, 0);
+    assert.equal(result.attestations.counts.documentsFailed, 2);
+    assert.equal(result.attestations.counts.pcr0Matches, 0);
+    assert.equal(result.attestations.counts.userDataBound, 0);
+  });
+
+  it("the exact anomaly code multiset is honest: crypto and topology findings, no version failure", () => {
+    const report = buildJsonReport(result);
+    const codes = report.anomalies.map((a) => a.code).sort();
+    assert.deepEqual(codes, [
+      "attestation-invalid", // MOCK_PROOF's placeholder attestation blob
+      "attestation-invalid", // REALISTIC_PROOF's truncated attestation blob
+      "chain-break-malformed", // MOCK_PROOF's placeholder prevB64 ("prev==")
+    ]);
+    // REALISTIC_PROOF's real-shaped prevB64 into unobserved history is the
+    // frontier of its (single-proof) partition, so it is an expected bundle
+    // boundary, not a chain-integrity anomaly.
+    assert.equal(report.boundaryEntryPoints.length, 1);
+    assert.ok(!codes.includes("unsupported-version"));
+    assert.equal(report.summary.fullyVerified, 0);
+    // Still exit 3: attestation-invalid trips verification, chain-break-malformed
+    // trips chain anomalies. The boundary alone would never set an exit bit.
+    assert.deepEqual(report.summary.exit, {
+      verificationFailures: true,
+      chainAnomaliesOrDivergences: true,
+      code: 3,
+    });
+  });
+});

package/src/__tests__/audit-real-live.test.ts

@@ -0,0 +1,128 @@
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+
+/**
+ * Real-ledger regression test for the audit pipeline.
+ *
+ * These three proofs (real-fixtures/live-proof-0.json .. live-proof-2.json)
+ * were captured from the live BitGraph ledger: a contiguous single-epoch
+ * chain (genesis commit counter 2, then 4, then 6, each linked to its
+ * predecessor by commit.prevB64). They are stored-form, carrying the
+ * ledger-added proofHash field.
+ *
+ * This test exists specifically because the synthetic fixtures shared the
+ * audit tool's ORIGINAL wrong assumptions and so masked two real bugs:
+ *
+ *   Bug A: real slot allocations carry NO time field (the enclave builds
+ *   slot bodies without a clock). The verifier used to require it, so real
+ *   slots failed verification. If this test's proofs verify at the
+ *   integrity tier (0 failed), Bug A is fixed.
+ *
+ *   Bug B: commit.prevB64 references computeChainHash(predecessor) (SHA-256
+ *   over the whole canonical proof minus the ledger proofHash), NOT
+ *   computeProofHash (the signed-body subset). The synthetic fixtures built
+ *   their prevB64 from computeProofHash, the same wrong value the tool
+ *   assumed, so they linked "by accident". Real proofs use the true chain
+ *   hash. If this real chain reconstructs as ONE intact component with ZERO
+ *   anomalies, Bug B is fixed.
+ *
+ * No synthetic construction: the assertions ride entirely on real bytes.
+ */
+
+import { describe, it, before, after } from "node:test";
+import * as assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, rm, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  runAudit,
+  buildJsonReport,
+  computeExitFlags,
+  type AuditResult,
+} from "@mikeargento/bitgraph-audit";
+import { computeProofHash, type BitGraphProof } from "@mikeargento/bitgraph-verify";
+
+/** Filesystem-safe token from a base64/arbitrary string. */
+function safe(value: string): string {
+  return value.replace(/[^A-Za-z0-9]/g, "_");
+}
+
+describe("audit: real live-ledger chain (Bug A + Bug B regression)", () => {
+  let dir: string;
+  let result: AuditResult;
+  let proofs: Array<BitGraphProof & { proofHash?: string }>;
+
+  before(async () => {
+    // Load the three captured real proofs from src/__tests__/real-fixtures.
+    // The test runs from dist/__tests__, so reach back into src.
+    proofs = [];
+    for (const i of [0, 1, 2]) {
+      const url = new URL(
+        `../../src/__tests__/real-fixtures/live-proof-${i}.json`,
+        import.meta.url
+      );
+      const raw = await readFile(fileURLToPath(url), "utf8");
+      proofs.push(JSON.parse(raw) as BitGraphProof & { proofHash?: string });
+    }
+
+    // Write a valid directory bundle: proofs/<epoch>/<counter>-<hash>.json.
+    // Bytes are the exact captured stored-form JSON; no re-serialization of
+    // the signed content, so nothing about the real proof is altered.
+    dir = await mkdtemp(join(tmpdir(), "bitgraph-audit-real-live-"));
+    for (const proof of proofs) {
+      const epochDir = join(dir, "proofs", safe(proof.commit.epochId as string));
+      await mkdir(epochDir, { recursive: true });
+      const name = `${proof.commit.counter}-${safe(computeProofHash(proof))}.json`;
+      await writeFile(join(epochDir, name), JSON.stringify(proof));
+    }
+
+    result = await runAudit(dir);
+  });
+
+  after(async () => {
+    if (dir !== undefined) await rm(dir, { recursive: true, force: true });
+  });
+
+  it("verifies every real proof at the integrity tier (Bug A: clockless slots verify)", () => {
+    // All three are observed, none rejected as an unsupported version.
+    assert.equal(result.ingest.counts.observed, 3);
+    assert.equal(result.ingest.counts.unsupportedVersion, 0);
+
+    // Bug A proof: real slot allocations carry no time field. If the
+    // verifier still required it, these would be "failed", not
+    // "artifact-unavailable". No artifact bytes are in the bundle, so the
+    // integrity tier is the ceiling and every proof must pass it.
+    assert.equal(result.verification.failed, 0);
+    assert.equal(result.verification.verified, 0);
+    assert.equal(result.verification.artifactUnavailable, 3);
+  });
+
+  it("reconstructs the real chain as one intact component (Bug B: prevB64 is the chain hash)", () => {
+    const report = buildJsonReport(result);
+
+    // One signer, one epoch, one chain -> exactly one partition.
+    assert.equal(result.reconstruction.partitions.length, 1);
+    const partition = result.reconstruction.partitions[0]!;
+
+    // The three proofs link into a SINGLE connected component of all three
+    // members. This only holds if commit.prevB64 resolves against
+    // computeChainHash(predecessor); against computeProofHash it would
+    // fragment into three genesis components with chain breaks.
+    assert.equal(partition.components.length, 1);
+    assert.equal(partition.components[0]!.memberProofHashes.length, 3);
+
+    // No anomalies of any kind, no divergences, chain intact.
+    assert.equal(result.anomalies.anomalies.length, 0);
+    assert.equal(result.anomalies.divergences.length, 0);
+    assert.equal(report.summary.chainIntact, true);
+    assert.equal(report.summary.partitionsIntact, 1);
+  });
+
+  it("exits clean (code 0) over the real bundle", () => {
+    assert.deepEqual(computeExitFlags(result), {
+      verificationFailures: false,
+      chainAnomaliesOrDivergences: false,
+      code: 0,
+    });
+  });
+});

package/src/__tests__/audit-reconstruct.test.ts

@@ -0,0 +1,353 @@
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+
+/**
+ * Tests for @mikeargento/bitgraph-audit causal reconstruction:
+ * partitioning per (signer key, epochId, chainId), chain components from
+ * prevB64 hash links, genesis and terminal identification, counter
+ * evidence, and epoch relationships (epochLink lineage edges, hard-edge
+ * ordering, observed-but-unordered epochs).
+ */
+
+import { describe, test, after } from "node:test";
+import * as assert from "node:assert/strict";
+import { rm } from "node:fs/promises";
+import {
+  classifyAnomalies,
+  ingestBundle,
+  reconstructChains,
+  verifyObservedProofs,
+} from "@mikeargento/bitgraph-audit";
+import type { IngestResult, ReconstructionResult, AnomalyReport } from "@mikeargento/bitgraph-audit";
+import { sha256 } from "@noble/hashes/sha256";
+import {
+  b64,
+  healthyPairs,
+  makeConstructorProof,
+  makeCounterChain,
+  makeEpochLinkProof,
+  makeKey,
+  makeTempDir,
+  proofJson,
+  utf8,
+  writeBundleDir,
+} from "./audit-fixtures.js";
+
+const tempDirs: string[] = [];
+
+after(async () => {
+  for (const dir of tempDirs) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+async function auditBundle(files: Record<string, Uint8Array | string>): Promise<{
+  ingest: IngestResult;
+  reconstruction: ReconstructionResult;
+  report: AnomalyReport;
+}> {
+  const dir = await makeTempDir("bitgraph-audit-reconstruct-");
+  tempDirs.push(dir);
+  await writeBundleDir(dir, files);
+  const ingest = await ingestBundle(dir);
+  await verifyObservedProofs(ingest);
+  const reconstruction = await reconstructChains(ingest);
+  const report = await classifyAnomalies(ingest, reconstruction);
+  return { ingest, reconstruction, report };
+}
+
+// ---------------------------------------------------------------------------
+// The critical regression: a healthy chain is clean
+// ---------------------------------------------------------------------------
+
+describe("reconstruct: healthy slot/commit chain", () => {
+  test("one partition, one component, zero anomalies, zero unexplained positions", async () => {
+    const chain = await makeCounterChain({
+      epochId: "epoch-healthy",
+      chainId: "bitgraph:main",
+      pairs: healthyPairs(4), // slot 1/commit 2 ... slot 7/commit 8
+    });
+    const { ingest, reconstruction, report } = await auditBundle({
+      "proofs/p0.json": proofJson(chain.proofs[0]!.proof),
+      "proofs/p1.json": proofJson(chain.proofs[1]!.proof),
+      "proofs/p2.json": proofJson(chain.proofs[2]!.proof),
+      "proofs/p3.json": proofJson(chain.proofs[3]!.proof),
+    });
+
+    assert.equal(ingest.proofs.length, 4);
+    assert.equal(reconstruction.partitions.length, 1);
+    const partition = reconstruction.partitions[0]!;
+    assert.deepEqual(partition.key, {
+      publicKeyB64: chain.key.publicKeyB64,
+      epochId: "epoch-healthy",
+      chainId: "bitgraph:main",
+    });
+
+    assert.equal(partition.components.length, 1);
+    const component = partition.components[0]!;
+    assert.deepEqual(
+      component.memberProofHashes,
+      chain.proofs.map((p) => p.proofHash),
+      "link order must follow the hash chain from genesis to terminal"
+    );
+    assert.deepEqual(component.genesisProofHashes, [chain.proofs[0]!.proofHash]);
+    assert.deepEqual(component.terminalProofHashes, [chain.proofs[3]!.proofHash]);
+    assert.deepEqual(component.brokenLinkProofHashes, []);
+    assert.equal(component.hasCounterEvidence, true);
+    assert.deepEqual(component.positionRange, { min: "1", max: "8" });
+
+    // THE critical regression: a healthy slot/commit chain produces NO
+    // unexplained positions and no anomalies of any kind.
+    assert.deepEqual(report.anomalies, []);
+    assert.deepEqual(report.divergences, []);
+  });
+
+  test("reconstruction is link-driven: file order and counters are not the mechanism", async () => {
+    const chain = await makeCounterChain({
+      epochId: "epoch-shuffled",
+      pairs: healthyPairs(3),
+    });
+    // Write files in an order that reverses the causal order.
+    const { reconstruction } = await auditBundle({
+      "a-last.json": proofJson(chain.proofs[2]!.proof),
+      "b-middle.json": proofJson(chain.proofs[1]!.proof),
+      "c-first.json": proofJson(chain.proofs[0]!.proof),
+    });
+    const component = reconstruction.partitions[0]!.components[0]!;
+    assert.deepEqual(
+      component.memberProofHashes,
+      chain.proofs.map((p) => p.proofHash)
+    );
+  });
+
+  test("a counterless link chain still reconstructs as one component", async () => {
+    const chain = await makeCounterChain({
+      epochId: "epoch-no-counters",
+      pairs: [{}, {}, {}], // epochId only: hash links are the only evidence
+    });
+    const { reconstruction, report } = await auditBundle({
+      "p0.json": proofJson(chain.proofs[0]!.proof),
+      "p1.json": proofJson(chain.proofs[1]!.proof),
+      "p2.json": proofJson(chain.proofs[2]!.proof),
+    });
+    const partition = reconstruction.partitions[0]!;
+    assert.equal(partition.components.length, 1);
+    const component = partition.components[0]!;
+    assert.deepEqual(
+      component.memberProofHashes,
+      chain.proofs.map((p) => p.proofHash)
+    );
+    assert.equal(component.hasCounterEvidence, false);
+    assert.equal(component.positionRange, undefined);
+    assert.deepEqual(report.anomalies, []);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Partitioning
+// ---------------------------------------------------------------------------
+
+describe("reconstruct: partitioning", () => {
+  test("two independent lineages are never merged", async () => {
+    const chainA = await makeCounterChain({ epochId: "epoch-A", pairs: healthyPairs(2) });
+    const chainB = await makeCounterChain({ epochId: "epoch-B", pairs: healthyPairs(2) });
+    const { reconstruction, report } = await auditBundle({
+      "a0.json": proofJson(chainA.proofs[0]!.proof),
+      "a1.json": proofJson(chainA.proofs[1]!.proof),
+      "b0.json": proofJson(chainB.proofs[0]!.proof),
+      "b1.json": proofJson(chainB.proofs[1]!.proof),
+    });
+
+    assert.equal(reconstruction.partitions.length, 2);
+    const keys = reconstruction.partitions.map((p) => p.key.publicKeyB64).sort();
+    assert.deepEqual(keys, [chainA.key.publicKeyB64, chainB.key.publicKeyB64].sort());
+    // Same counters on both chains, yet no collisions: counters are
+    // partition-local.
+    assert.deepEqual(report.anomalies, []);
+    assert.deepEqual(report.divergences, []);
+  });
+
+  test("same signer and epoch on different chainIds are separate partitions (G6)", async () => {
+    const key = await makeKey();
+    const main = await makeCounterChain({
+      key,
+      epochId: "epoch-multichain",
+      chainId: "bitgraph:main",
+      pairs: healthyPairs(2),
+      payloadPrefix: "main",
+    });
+    const globalChain = await makeCounterChain({
+      key,
+      epochId: "epoch-multichain",
+      pairs: healthyPairs(2), // no chainId: normalized "global"
+      payloadPrefix: "global",
+    });
+    const { reconstruction, report } = await auditBundle({
+      "m0.json": proofJson(main.proofs[0]!.proof),
+      "m1.json": proofJson(main.proofs[1]!.proof),
+      "g0.json": proofJson(globalChain.proofs[0]!.proof),
+      "g1.json": proofJson(globalChain.proofs[1]!.proof),
+    });
+
+    assert.equal(reconstruction.partitions.length, 2);
+    assert.deepEqual(
+      reconstruction.partitions.map((p) => p.key.chainId).sort(),
+      ["bitgraph:main", "global"]
+    );
+    assert.deepEqual(report.anomalies, []);
+  });
+
+  test("chainless proofs stay outside partitions as observed-but-unchained", async () => {
+    const chain = await makeCounterChain({ epochId: "epoch-with-stray", pairs: healthyPairs(2) });
+    const chainless = await makeConstructorProof(); // no counter, no epochId
+    const { ingest, reconstruction, report } = await auditBundle({
+      "p0.json": proofJson(chain.proofs[0]!.proof),
+      "p1.json": proofJson(chain.proofs[1]!.proof),
+      "stray.json": proofJson(chainless.proof),
+    });
+
+    assert.equal(ingest.proofs.length, 3);
+    assert.equal(reconstruction.partitions.length, 1);
+    assert.equal(reconstruction.partitions[0]!.memberProofHashes.length, 2);
+    const strayHash = ingest.proofs.find((p) => p.chainless)!.proofHash;
+    assert.deepEqual(reconstruction.unchainedProofHashes, [strayHash]);
+    // Observed-but-unchained is not an anomaly.
+    assert.deepEqual(report.anomalies, []);
+  });
+
+  test("a proof with chain fields but no signer key is unpartitioned", async () => {
+    const broken = JSON.stringify({
+      version: "bitgraph/1",
+      artifact: { hashAlg: "sha256", digestB64: b64(sha256(utf8("broken-payload"))) },
+      commit: { nonceB64: "AAAA", counter: "2", epochId: "epoch-broken" },
+      signer: { publicKeyB64: 42, signatureB64: "AAAA" },
+    });
+    const { ingest, reconstruction } = await auditBundle({ "broken.json": broken });
+    assert.equal(ingest.proofs.length, 1);
+    assert.equal(reconstruction.partitions.length, 0);
+    assert.deepEqual(reconstruction.unpartitionedProofHashes, [ingest.proofs[0]!.proofHash]);
+    // The verification dimension reports the structural failure.
+    assert.equal(ingest.proofs[0]!.verification!.status, "failed");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Missing proofs split components
+// ---------------------------------------------------------------------------
+
+describe("reconstruct: missing middle proof", () => {
+  test("splits the partition into two components with the break identified", async () => {
+    const chain = await makeCounterChain({ epochId: "epoch-gap", pairs: healthyPairs(3) });
+    // Omit the middle proof (slot 3 / commit 4).
+    const { reconstruction } = await auditBundle({
+      "p0.json": proofJson(chain.proofs[0]!.proof),
+      "p2.json": proofJson(chain.proofs[2]!.proof),
+    });
+
+    const partition = reconstruction.partitions[0]!;
+    assert.equal(partition.components.length, 2);
+    const [first, second] = partition.components;
+    assert.deepEqual(first!.memberProofHashes, [chain.proofs[0]!.proofHash]);
+    assert.deepEqual(first!.genesisProofHashes, [chain.proofs[0]!.proofHash]);
+    assert.deepEqual(first!.terminalProofHashes, [chain.proofs[0]!.proofHash]);
+    assert.deepEqual(second!.memberProofHashes, [chain.proofs[2]!.proofHash]);
+    assert.deepEqual(second!.genesisProofHashes, []);
+    assert.deepEqual(second!.brokenLinkProofHashes, [chain.proofs[2]!.proofHash]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Epoch relationships
+// ---------------------------------------------------------------------------
+
+describe("reconstruct: epoch relationships", () => {
+  test("a valid epochLink produces a hard lineage edge and linked ordering", async () => {
+    const chainA = await makeCounterChain({ epochId: "epoch-lineage-A", pairs: healthyPairs(2) });
+    const terminalA = chainA.proofs[1]!;
+    const genesisB = await makeEpochLinkProof({
+      prevEpochId: "epoch-lineage-A",
+      prevCounter: terminalA.proof.commit.counter as string,
+      prevProofHashB64: terminalA.chainHash,
+      prevPublicKeyB64: chainA.key.publicKeyB64,
+      toEpochId: "epoch-lineage-B",
+      counter: "2",
+      slotCounter: "1",
+    });
+
+    const { reconstruction, report } = await auditBundle({
+      "a0.json": proofJson(chainA.proofs[0]!.proof),
+      "a1.json": proofJson(terminalA.proof),
+      "b-genesis.json": proofJson(genesisB.proof),
+    });
+
+    const { edges, epochs, orderedPairs } = reconstruction.epochRelationships;
+    assert.equal(edges.length, 1);
+    const edge = edges[0]!;
+    assert.equal(edge.resolution, "matched");
+    assert.equal(edge.fromEpochId, "epoch-lineage-A");
+    assert.equal(edge.toEpochId, "epoch-lineage-B");
+    assert.equal(edge.predecessorProofHash, terminalA.proofHash);
+    assert.equal(edge.metadataConsistent, true);
+    assert.equal(edge.referencedProofIsTerminal, true);
+    assert.equal(edge.viaProofValid, true);
+    assert.equal(edge.predecessorValid, true);
+    assert.equal(edge.hardEdge, true);
+
+    assert.deepEqual(orderedPairs, [
+      { beforeEpochId: "epoch-lineage-A", afterEpochId: "epoch-lineage-B" },
+    ]);
+    const epochA = epochs.find((e) => e.epochId === "epoch-lineage-A")!;
+    const epochB = epochs.find((e) => e.epochId === "epoch-lineage-B")!;
+    assert.equal(epochA.ordering, "linked");
+    assert.equal(epochB.ordering, "linked");
+    assert.deepEqual(epochA.linkedSuccessorEpochIds, ["epoch-lineage-B"]);
+    assert.deepEqual(epochB.linkedPredecessorEpochIds, ["epoch-lineage-A"]);
+    // The extension point stays untouched by reconstruction.
+    assert.equal(epochA.anchorBounds, undefined);
+
+    // Valid lineage is not an anomaly.
+    assert.deepEqual(report.anomalies, []);
+    assert.deepEqual(report.divergences, []);
+  });
+
+  test("a dangling epochLink yields no hard edge and no ordering", async () => {
+    const genesis = await makeEpochLinkProof({
+      prevEpochId: "epoch-never-observed",
+      prevCounter: "10",
+      prevProofHashB64: b64(sha256(utf8("terminal-never-observed"))),
+      toEpochId: "epoch-dangling-B",
+      counter: "2",
+      slotCounter: "1",
+    });
+    const { reconstruction } = await auditBundle({
+      "b-genesis.json": proofJson(genesis.proof),
+    });
+
+    const { edges, epochs, orderedPairs } = reconstruction.epochRelationships;
+    assert.equal(edges.length, 1);
+    assert.equal(edges[0]!.resolution, "dangling");
+    assert.equal(edges[0]!.hardEdge, false);
+    assert.deepEqual(orderedPairs, []);
+    assert.equal(epochs.find((e) => e.epochId === "epoch-dangling-B")!.ordering, "observed-but-unordered");
+  });
+
+  test("epochs with no lineage evidence are observed-but-unordered, never divergence", async () => {
+    const chainA = await makeCounterChain({ epochId: "epoch-solo-A", pairs: healthyPairs(2) });
+    const chainB = await makeCounterChain({ epochId: "epoch-solo-B", pairs: healthyPairs(2) });
+    const { reconstruction, report } = await auditBundle({
+      "a0.json": proofJson(chainA.proofs[0]!.proof),
+      "a1.json": proofJson(chainA.proofs[1]!.proof),
+      "b0.json": proofJson(chainB.proofs[0]!.proof),
+      "b1.json": proofJson(chainB.proofs[1]!.proof),
+    });
+
+    const { epochs, edges, orderedPairs } = reconstruction.epochRelationships;
+    assert.equal(edges.length, 0);
+    assert.deepEqual(orderedPairs, []);
+    for (const epoch of epochs) {
+      assert.equal(epoch.ordering, "observed-but-unordered");
+    }
+    // Concurrent-or-unordered is never divergence.
+    assert.deepEqual(report.divergences, []);
+    assert.deepEqual(report.anomalies, []);
+  });
+});