@mikeargento/bitgraph-audit 0.1.0

package/dist/report-md.js

@@ -0,0 +1,853 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+/**
+ * Markdown report builder: turns an AuditResult into audit-report.md.
+ *
+ * Two audiences, one document. The executive summary is written for a
+ * reader with no cryptography background: every cryptographic term is
+ * explained by its consequence, gap language follows the two-position
+ * counter reality (positions neither commit positions nor referenced
+ * slot positions; absence from the bundle does not, by itself, prove the
+ * authority failed to create them), and divergences are presented
+ * without choosing a winner. The detail sections that follow are for
+ * engineers: full tables and per-object walkthroughs.
+ *
+ * The markdown is rendered from the same buildJsonReport object, so its
+ * ordering is identical to the JSON report's. It is deterministic given
+ * the same bundle except for the run line naming the wall-clock start
+ * time, which is the only nondeterministic content.
+ *
+ * Long tables are capped at MAX_TABLE_ROWS rows with an explicit
+ * remainder line; the JSON report always carries the complete data.
+ */
+import { buildJsonReport } from "./report-json.js";
+const MAX_TABLE_ROWS = 200;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function buildMarkdownReport(result) {
+    const report = buildJsonReport(result);
+    const proofByHash = new Map(report.proofs.map((p) => [p.proofHash, p]));
+    const lines = [];
+    header(lines, report);
+    executiveSummary(lines, report, proofByHash);
+    detailSections(lines, report, proofByHash);
+    return lines.join("\n") + "\n";
+}
+// ---------------------------------------------------------------------------
+// Header
+// ---------------------------------------------------------------------------
+function header(lines, report) {
+    lines.push("# BitGraph Audit Report");
+    lines.push("");
+    lines.push(`Generated by bitgraph-audit ${report.toolVersion}. ` +
+        `Bundle: \`${report.runMetadata.bundlePath}\` (${report.runMetadata.container} container). ` +
+        `Run started ${report.runMetadata.startedAt}.`);
+    lines.push("");
+    lines.push("The start time above is the only content of this report that changes " +
+        "between runs on the same bundle. Everything else is derived entirely " +
+        "from the files supplied, with no network access of any kind. The " +
+        "machine-readable companion, audit-report.json, carries the complete " +
+        "data behind every table here (schema bitgraph-audit-report/1).");
+    lines.push("");
+}
+// ---------------------------------------------------------------------------
+// Executive summary
+// ---------------------------------------------------------------------------
+function executiveSummary(lines, report, proofByHash) {
+    const s = report.summary;
+    lines.push("## Executive summary");
+    lines.push("");
+    lines.push("This report examines a bundle of BitGraph proofs offline. A BitGraph " +
+        "proof is a small signed record stating that a specific file, " +
+        "identified by its digital fingerprint, was committed at a specific " +
+        "position in a sequence kept by an authority. Because each proof " +
+        "names the fingerprint of the proof before it, the sequence forms a " +
+        "chain whose order can be checked from the objects themselves: this " +
+        "is what is meant by causal order. The audit verifies what can be " +
+        "verified, reconstructs that order, and reports anything missing or " +
+        "conflicting. Where evidence is incomplete, it says so rather than " +
+        "guessing, and where valid records conflict, it presents all of them " +
+        "and chooses none.");
+    lines.push("");
+    // Proofs and verification tiers.
+    lines.push("### Proofs");
+    lines.push("");
+    lines.push(...table(["Category", "Count"], [
+        ["Proof objects observed", withCommas(s.proofsObserved)],
+        ["Fully verified (artifact bytes present and matched)", withCommas(s.fullyVerified)],
+        ["Failed verification", withCommas(s.failed)],
+        ["Observed without artifact bytes", withCommas(s.artifactUnavailable)],
+        ["Rejected as unsupported legacy versions", withCommas(s.unsupportedVersion)],
+        ["Duplicate copies (byte-identical)", withCommas(s.exactDuplicates)],
+        ["Duplicate copies (re-encoded, same identity)", withCommas(s.semanticDuplicates)],
+    ]));
+    lines.push("");
+    lines.push("Fully verified means two things held at once: the proof's internal " +
+        "cryptography checked out (its signature is valid and its parts are " +
+        "cryptographically bound together), and the original file was present " +
+        "in the bundle with contents matching the fingerprint recorded inside " +
+        "the signed proof. Such a proof is detectably invalid if altered: " +
+        "changing any byte of the proof or of the file breaks the check.");
+    if (s.artifactUnavailable > 0) {
+        lines.push("");
+        lines.push(`${withCommas(s.artifactUnavailable)} ${plural(s.artifactUnavailable, "proof", "proofs")} ` +
+            "arrived without the original file bytes. Their internal " +
+            "cryptography was checked and passed, but the link between proof " +
+            "and file could not be independently confirmed because there was no " +
+            "file to compare against. They are reported as observed, never as " +
+            "fully verified.");
+    }
+    if (s.failed > 0) {
+        lines.push("");
+        lines.push(`${withCommas(s.failed)} ${plural(s.failed, "proof", "proofs")} failed verification. ` +
+            "The exact reason for each failure is recorded in the detail " +
+            "sections and in the JSON report.");
+    }
+    if (s.unsupportedVersion > 0) {
+        lines.push("");
+        lines.push(`${withCommas(s.unsupportedVersion)} proof-shaped ${plural(s.unsupportedVersion, "file was", "files were")} ` +
+            "rejected because the version field is not bitgraph/1. Only " +
+            "bitgraph/1 proofs are supported; earlier pre-release data is " +
+            "permanently out of scope. Rejected files are listed with their " +
+            "paths and version strings in the detail sections.");
+    }
+    if (s.chainless > 0) {
+        lines.push("");
+        lines.push(`${withCommas(s.chainless)} ${plural(s.chainless, "proof carries", "proofs carry")} ` +
+            "neither a counter nor an epoch identifier. The schema permits " +
+            "this; such proofs are observed and verified but sit outside every " +
+            "chain, so no ordering claims are made about them.");
+    }
+    lines.push("");
+    // Causal chain.
+    lines.push("### Causal chain");
+    lines.push("");
+    lines.push("Proofs are grouped by the authority key, epoch, and chain they were " +
+        "committed under; each group is called a partition. Every proof " +
+        "occupies two counter positions: one reserved in advance (the slot) " +
+        "and one at the moment of commit. Slot positions never produce " +
+        "stored proof files of their own, so a healthy chain shows only " +
+        "committed proofs, each referencing its own slot position from " +
+        "inside its signed content.");
+    lines.push("");
+    if (report.partitions.length === 0) {
+        lines.push("No chain partitions were observed in this bundle.");
+        lines.push("");
+    }
+    for (const partition of report.partitions) {
+        lines.push(`**Partition ${partitionLabel(partition)}.** Chain intact: ${partition.intact ? "yes" : "no"}.`);
+        lines.push("");
+        lines.push(...partitionSummarySentences(report, partition));
+        lines.push("");
+    }
+    if (report.unchainedProofHashes.length > 0) {
+        lines.push(`${withCommas(report.unchainedProofHashes.length)} observed ` +
+            `${plural(report.unchainedProofHashes.length, "proof is", "proofs are")} ` +
+            "outside all partitions (no counter and no epoch identifier).");
+        lines.push("");
+    }
+    // Epochs.
+    lines.push("### Epochs");
+    lines.push("");
+    const epochCount = report.epochRelationships.epochs.length;
+    lines.push(`${withCommas(epochCount)} ${plural(epochCount, "epoch was", "epochs were")} observed. ` +
+        "An epoch is one uninterrupted run of the authority: every restart " +
+        "creates a fresh signing key and restarts the counter, so counters " +
+        "never order proofs across epochs. Epochs are ordered against each " +
+        "other only by verified evidence: a signed lineage link from one " +
+        "epoch's first proof back to the previous epoch's last proof, or " +
+        "independently verified Ethereum anchor evidence.");
+    lines.push("");
+    const hardPairs = report.epochRelationships.orderedPairs.length;
+    const anchorPairs = report.epochRelationships.anchorOrderedPairs.length;
+    const unorderedPairs = report.epochRelationships.unorderedPairs.length;
+    if (epochCount > 1 || hardPairs + anchorPairs > 0) {
+        lines.push(`Ordering evidence: ${withCommas(hardPairs)} epoch ${plural(hardPairs, "pair", "pairs")} ` +
+            `ordered by signed lineage links, ${withCommas(anchorPairs)} by anchor time bounds ` +
+            `(assumption-dependent, see the time evidence section), and ` +
+            `${withCommas(unorderedPairs)} ${plural(unorderedPairs, "pair", "pairs")} with no ordering ` +
+            "evidence in either direction. Epochs without ordering evidence " +
+            "are concurrent or unordered as far as this bundle shows, which " +
+            "is not by itself a conflict.");
+        lines.push("");
+    }
+    // Anomalies.
+    lines.push("### Anomalies");
+    lines.push("");
+    const codes = Object.entries(report.summary.anomalyCountsByCode);
+    if (codes.length === 0) {
+        lines.push("No anomalies of any type were detected.");
+    }
+    else {
+        lines.push(...table(["Code", "Count", "What it means"], codes.map(([code, count]) => [
+            inlineCode(code),
+            withCommas(count),
+            codeMeaning(code),
+        ])));
+    }
+    lines.push("");
+    // Divergences.
+    lines.push("### Divergences");
+    lines.push("");
+    if (report.divergences.length === 0) {
+        lines.push("No divergences were found: no two valid proofs claim the same " +
+            "position, the same predecessor, or the same epoch boundary.");
+        lines.push("");
+    }
+    else {
+        lines.push(`${withCommas(report.divergences.length)} ${plural(report.divergences.length, "divergence was", "divergences were")} ` +
+            "found. A divergence is a conflict between proofs that are each " +
+            "individually valid; it is presented as evidence, never resolved " +
+            "by this tool.");
+        lines.push("");
+        for (const divergence of report.divergences) {
+            lines.push(`- ${divergenceSummarySentence(divergence)}`);
+        }
+        lines.push("");
+    }
+    // Authorities and measurements.
+    lines.push("### Authorities and measurements");
+    lines.push("");
+    lines.push(`The observed proofs were signed under ${withCommas(s.distinctSignerCount)} ` +
+        `${plural(s.distinctSignerCount, "authority key", "authority keys")} and declare ` +
+        `${withCommas(s.distinctDeclaredMeasurementCount)} distinct software ` +
+        `${plural(s.distinctDeclaredMeasurementCount, "measurement", "measurements")}, in ` +
+        `${withCommas(s.authorityGroupCount)} authority ${plural(s.authorityGroupCount, "group", "groups")}. ` +
+        "A declared measurement is what a proof says about the software that " +
+        "produced it; on its own it is a self-description. An attested " +
+        "measurement comes from a hardware attestation document that was " +
+        "cryptographically validated; only that ties proofs to a specific " +
+        "program. The two are tracked separately throughout this report.");
+    lines.push("");
+    // Attestation coverage.
+    lines.push("### Attestation coverage");
+    lines.push("");
+    lines.push(...table(["Fact (tracked separately)", "Proofs"], [
+        ["Declared measurement present (self-reported)", withCommas(s.attestation.declaredMeasurementPresent)],
+        ["Attestation document present (presence alone proves nothing)", withCommas(s.attestation.documentsPresent)],
+        ["Document cryptographically validated offline", withCommas(s.attestation.documentsValidated)],
+        ["Validated document's measurement matches the declared one", withCommas(s.attestation.pcr0MatchesDeclared)],
+        ["Validated document bound to its specific proof", withCommas(s.attestation.userDataBound)],
+    ]));
+    lines.push("");
+    lines.push("These five facts are never merged. Carrying an attestation document " +
+        "is not the same as the document validating, and a validated " +
+        "document supports a proof only when it is bound to that specific " +
+        "proof and its measurement matches what the proof declares.");
+    lines.push("");
+    // External time evidence.
+    lines.push("### External time evidence");
+    lines.push("");
+    const t = s.temporal;
+    if (t.anchorsIdentified === 0) {
+        lines.push("No Ethereum anchor proofs were observed. The causal order of the " +
+            "proofs stands on its own; this report makes no wall-clock claims.");
+        lines.push("");
+    }
+    else {
+        lines.push(`${withCommas(t.anchorsIdentified)} Ethereum anchor ${plural(t.anchorsIdentified, "proof was", "proofs were")} ` +
+            "identified. An anchor is an ordinary chain member that committed " +
+            "the fingerprint of a public Ethereum block, giving the chain a " +
+            "contact point with a public timeline. " +
+            `${withCommas(t.anchorsWithVerifiedWitness)} ${plural(t.anchorsWithVerifiedWitness, "anchor", "anchors")} ` +
+            "came with witness material (the block header) that let this tool " +
+            "reconstruct the block fingerprint locally and confirm it against " +
+            "the signed anchor, entirely offline.");
+        lines.push("");
+        lines.push("A verified anchor bounds time in one direction at a time. Proofs " +
+            "that come after an anchor in the chain were committed no earlier " +
+            "than that block's timestamp, because the block's fingerprint " +
+            "could not have been known before the block existed. That lower " +
+            "bound additionally assumes the anchored header is a genuine, " +
+            "publicly published Ethereum block: this offline audit checks the " +
+            "header's structure and hash binding, not proof-of-work, " +
+            "consensus, or chain membership, so it cannot confirm the block " +
+            "is real. Proofs that come before an anchor existed before the " +
+            "commit that consumed the block; reading that as a wall-clock " +
+            "ceiling additionally assumes the anchor consumed a recently " +
+            "published block. Every such bound in this report states its " +
+            "assumption. No individual proof's exact creation time is ever " +
+            "stated.");
+        lines.push("");
+        lines.push(...table(["Temporal coverage", "Segments"], [
+            ["Bracketed (verified evidence on both sides)", withCommas(t.segmentsBracketed)],
+            ["Lower-bounded only (committed no earlier than a block time)", withCommas(t.segmentsLowerBounded)],
+            ["Upper-bounded only (existed before an anchor commit)", withCommas(t.segmentsUpperBounded)],
+            ["Ordered but unanchored (causal order only, no wall-clock evidence)", withCommas(t.segmentsUnanchored)],
+        ]));
+        lines.push("");
+    }
+}
+/** Plain sentences describing one partition's chain state, in the brief's style. */
+function partitionSummarySentences(report, partition) {
+    const out = [];
+    const memberCount = partition.memberProofHashes.length;
+    if (partition.components.length === 1) {
+        out.push(`${withCommas(memberCount)} ${plural(memberCount, "proof forms", "proofs form")} one ` +
+            "continuous observed causal sequence.");
+    }
+    else {
+        out.push(`The ${withCommas(memberCount)} observed ${plural(memberCount, "proof forms", "proofs form")} ` +
+            `${withCommas(partition.components.length)} disconnected sequences. The record between ` +
+            "them cannot be reconstructed from the supplied evidence.");
+    }
+    for (const anomaly of report.anomalies) {
+        if (anomaly.stage !== "chain" || anomaly.partition === undefined)
+            continue;
+        if (!samePartition(anomaly.partition, partition.key))
+            continue;
+        if (anomaly.code === "unexplained-counter-positions") {
+            const detail = anomaly.details;
+            const count = detail.count;
+            const singular = count === "1";
+            out.push(`${withCommas(count)} counter ${singular ? "position is neither a commit position nor a referenced slot position" : "positions are neither commit positions nor referenced slot positions"} ` +
+                "in the supplied bundle. An unexplained interior position may " +
+                "mean a proof is absent from the bundle, or a slot that was " +
+                "allocated but never committed (a routine, benign occurrence); " +
+                "this offline audit cannot tell the two apart. It does not, by " +
+                "itself, prove that the BitGraph authority failed to create or " +
+                "withheld any proof.");
+        }
+        else if (anomaly.code === "chain-break-missing") {
+            out.push("At least one proof names a predecessor that is absent from the " +
+                "bundle, so the history before that point cannot be " +
+                "reconstructed from the supplied evidence. The absence does " +
+                "not, by itself, prove that the predecessor never existed.");
+        }
+    }
+    return [out.join(" ")];
+}
+/** One-sentence executive-summary line for a divergence, matching the brief's style. */
+function divergenceSummarySentence(divergence) {
+    const n = divergence.parties.length;
+    const head = n === 2 ? "Two independently valid proof objects" : `${withCommas(n)} independently valid proof objects`;
+    const both = n === 2 ? "Both objects" : "All objects";
+    const tail = ` The audit tool does not choose between them. ${both} and their predecessor ` +
+        "relationships are shown in the divergence details for adjudication.";
+    switch (divergence.kind) {
+        case "counter-collision":
+            return (`${head} ${n === 2 ? "both claim" : "all claim"} commit counter ` +
+                `${withCommas(divergence.contested["counter"] ?? "?")} in the same epoch.` +
+                tail);
+        case "slot-collision":
+            return (`${head} ${n === 2 ? "both reference" : "all reference"} slot counter ` +
+                `${withCommas(divergence.contested["slotCounter"] ?? "?")} in the same epoch.` +
+                tail);
+        case "cross-kind-position-reuse":
+            return (`${head} allocate one causal position ` +
+                `${withCommas(divergence.contested["position"] ?? "?")} in the same epoch, at least one ` +
+                "committing it and at least one reserving it as a slot." +
+                tail);
+        case "predecessor-reuse":
+            return (`${head} name the same predecessor proof: the chain forks at that point.` + tail);
+        case "multiple-genesis":
+            return (`${head} each begin a chain without naming a predecessor in the same epoch.` + tail);
+        case "epochlink-fork":
+            return (`${head} claim the same predecessor epoch's terminal proof for different successor epochs.` +
+                tail);
+        default:
+            return `${head} conflict over ${JSON.stringify(divergence.contested)}.` + tail;
+    }
+}
+// ---------------------------------------------------------------------------
+// Detail sections (for engineers)
+// ---------------------------------------------------------------------------
+function detailSections(lines, report, proofByHash) {
+    lines.push("## Details");
+    lines.push("");
+    lines.push("The sections below are for technical readers. All hashes are " +
+        "canonical proof hashes (base64 SHA-256 over the canonical signed " +
+        "body) unless stated otherwise. The JSON report carries the " +
+        "complete, uncapped data.");
+    lines.push("");
+    perPartitionChains(lines, report, proofByHash);
+    anomalyDetails(lines, report);
+    divergenceDetails(lines, report);
+    anchorDetails(lines, report);
+    witnessDetails(lines, report);
+    temporalDetails(lines, report);
+    attestationDetails(lines, report);
+    unsupportedVersionDetails(lines, report);
+    manifestDetails(lines, report);
+}
+function perPartitionChains(lines, report, proofByHash) {
+    lines.push("### Per-partition chains");
+    lines.push("");
+    if (report.partitions.length === 0) {
+        lines.push("No partitions were observed.");
+        lines.push("");
+        return;
+    }
+    for (const partition of report.partitions) {
+        lines.push(`#### Partition ${partitionLabel(partition)}`);
+        lines.push("");
+        lines.push(`Signer key: ${inlineCode(partition.key.publicKeyB64)}. ` +
+            `Epoch: ${partition.key.epochId !== undefined ? inlineCode(partition.key.epochId) : "(none)"}. ` +
+            `Chain: ${inlineCode(partition.key.chainId)}. ` +
+            `Members: ${withCommas(partition.memberProofHashes.length)}. ` +
+            `Components: ${withCommas(partition.components.length)}. ` +
+            `Intact: ${partition.intact ? "yes" : "no"}.`);
+        lines.push("");
+        for (let c = 0; c < partition.components.length; c++) {
+            const component = partition.components[c];
+            if (component === undefined)
+                continue;
+            lines.push(`Component ${c + 1} of ${partition.components.length}` +
+                (component.positionRange !== undefined
+                    ? ` (positions ${withCommas(component.positionRange.min)} to ${withCommas(component.positionRange.max)})`
+                    : "") +
+                ":");
+            lines.push("");
+            const rows = [];
+            for (const hash of component.memberProofHashes.slice(0, MAX_TABLE_ROWS)) {
+                const proof = proofByHash.get(hash);
+                rows.push([
+                    proof?.counter !== undefined ? proof.counter : "",
+                    proof?.slotCounter !== undefined ? proof.slotCounter : "",
+                    inlineCode(hash),
+                    proof?.prevB64 !== undefined
+                        ? component.brokenLinkProofHashes.includes(hash)
+                            ? "unresolved"
+                            : "resolved"
+                        : "none (genesis)",
+                    proof?.verificationStatus ?? "unverified",
+                ]);
+            }
+            lines.push(...table(["Counter", "Slot", "Proof hash", "Predecessor", "Status"], rows));
+            if (component.memberProofHashes.length > MAX_TABLE_ROWS) {
+                lines.push("");
+                lines.push(`... and ${withCommas(component.memberProofHashes.length - MAX_TABLE_ROWS)} more members ` +
+                    "(complete list in the JSON report).");
+            }
+            lines.push("");
+        }
+    }
+    if (report.unchainedProofHashes.length > 0) {
+        lines.push("#### Unchained proofs");
+        lines.push("");
+        lines.push("Observed proofs with neither counter nor epoch identifier " +
+            "(permitted by the schema, outside all partitions, not anomalies):");
+        lines.push("");
+        for (const hash of report.unchainedProofHashes.slice(0, MAX_TABLE_ROWS)) {
+            lines.push(`- ${inlineCode(hash)}`);
+        }
+        lines.push("");
+    }
+    if (report.unpartitionedProofHashes.length > 0) {
+        lines.push("#### Unpartitioned proofs");
+        lines.push("");
+        lines.push("Observed proofs carrying chain fields but no signer key; they " +
+            "cannot join a signer lineage and their structural failure is " +
+            "recorded on the verification dimension:");
+        lines.push("");
+        for (const hash of report.unpartitionedProofHashes.slice(0, MAX_TABLE_ROWS)) {
+            lines.push(`- ${inlineCode(hash)}`);
+        }
+        lines.push("");
+    }
+}
+function anomalyDetails(lines, report) {
+    lines.push("### Anomaly details");
+    lines.push("");
+    if (report.anomalies.length === 0) {
+        lines.push("No anomalies of any type were detected.");
+        lines.push("");
+        return;
+    }
+    for (const anomaly of report.anomalies.slice(0, MAX_TABLE_ROWS)) {
+        lines.push(`- [${anomaly.stage}] ${inlineCode(anomaly.code)}: ${anomaly.message}`);
+        if (anomaly.path !== undefined)
+            lines.push(`  - path: ${inlineCode(anomaly.path)}`);
+        if (anomaly.partition !== undefined) {
+            lines.push(`  - partition: signer ${inlineCode(anomaly.partition.publicKeyB64)}, epoch ` +
+                `${anomaly.partition.epochId !== undefined ? inlineCode(anomaly.partition.epochId) : "(none)"}, ` +
+                `chain ${inlineCode(anomaly.partition.chainId)}`);
+        }
+        if (anomaly.proofHashes !== undefined && anomaly.proofHashes.length > 0) {
+            lines.push(`  - proofs: ${anomaly.proofHashes.map(inlineCode).join(", ")}`);
+        }
+        if (anomaly.details !== undefined) {
+            lines.push(`  - details: ${inlineCode(JSON.stringify(anomaly.details))}`);
+        }
+    }
+    if (report.anomalies.length > MAX_TABLE_ROWS) {
+        lines.push("");
+        lines.push(`... and ${withCommas(report.anomalies.length - MAX_TABLE_ROWS)} more anomalies ` +
+            "(complete list in the JSON report).");
+    }
+    lines.push("");
+}
+function divergenceDetails(lines, report) {
+    lines.push("### Divergence walkthroughs");
+    lines.push("");
+    if (report.divergences.length === 0) {
+        lines.push("No divergences were found.");
+        lines.push("");
+        return;
+    }
+    for (let i = 0; i < report.divergences.length && i < MAX_TABLE_ROWS; i++) {
+        const divergence = report.divergences[i];
+        if (divergence === undefined)
+            continue;
+        lines.push(`#### Divergence ${i + 1}: ${inlineCode(divergence.kind)}`);
+        lines.push("");
+        lines.push(divergence.explanation);
+        lines.push("");
+        lines.push(`Contested: ${inlineCode(JSON.stringify(divergence.contested))}.` +
+            (divergence.partition !== undefined
+                ? ` Partition: signer ${inlineCode(divergence.partition.publicKeyB64)}, epoch ` +
+                    `${divergence.partition.epochId !== undefined ? inlineCode(divergence.partition.epochId) : "(none)"}, ` +
+                    `chain ${inlineCode(divergence.partition.chainId)}.`
+                : ""));
+        lines.push("");
+        lines.push("Competing valid parties (this tool chooses none of them):");
+        lines.push("");
+        lines.push(...partyTable(divergence.parties));
+        if (divergence.invalidContext.length > 0) {
+            lines.push("");
+            lines.push("Cryptographically invalid proofs involved in the same conflict " +
+                "(context only, never competing branches):");
+            lines.push("");
+            lines.push(...partyTable(divergence.invalidContext));
+        }
+        lines.push("");
+    }
+}
+function partyTable(parties) {
+    return table(["Proof hash", "Counter", "Slot", "Predecessor", "Status", "Sources"], parties.map((party) => [
+        inlineCode(party.proofHash),
+        party.counter ?? "",
+        party.slotCounter ?? "",
+        party.prevB64 !== undefined ? inlineCode(party.prevB64) : "",
+        party.verificationStatus ?? "unverified",
+        party.sourcePaths.map(inlineCode).join(", "),
+    ]));
+}
+function anchorDetails(lines, report) {
+    lines.push("### Ethereum anchors");
+    lines.push("");
+    if (report.anchors.records.length === 0) {
+        lines.push("No anchor proofs were identified.");
+        lines.push("");
+        return;
+    }
+    lines.push(...table(["Proof hash", "Epoch", "Chain", "Counter", "Block number", "Block hash (signed)", "Metadata", "Status"], report.anchors.records
+        .slice(0, MAX_TABLE_ROWS)
+        .map((anchor) => [
+        inlineCode(anchor.proofHash),
+        anchor.epochId !== undefined ? inlineCode(anchor.epochId) : "",
+        inlineCode(anchor.chainId),
+        anchor.counter ?? "",
+        anchor.blockNumber ?? "(unparsed)",
+        anchor.blockHash !== undefined ? inlineCode(anchor.blockHash) : "",
+        anchor.metadataCorroboration,
+        anchor.verificationStatus ?? "unverified",
+    ])));
+    lines.push("");
+    if (report.anchors.metadataOnlyProofHashes.length > 0) {
+        lines.push("Proofs whose unsigned metadata claims to be an anchor while the " +
+            "signed content does not (never treated as anchors): " +
+            report.anchors.metadataOnlyProofHashes.map(inlineCode).join(", "));
+        lines.push("");
+    }
+}
+function witnessDetails(lines, report) {
+    lines.push("### Anchor witnesses");
+    lines.push("");
+    if (report.witnesses.outcomes.length === 0) {
+        lines.push("No anchor witness files were present. Anchors without a verified " +
+            "witness still establish causal order; they confer no wall-clock " +
+            "evidence.");
+        lines.push("");
+        return;
+    }
+    lines.push(...table(["Witness path", "Anchor proof", "Verified", "Reason", "Block number", "Block timestamp"], report.witnesses.outcomes
+        .slice(0, MAX_TABLE_ROWS)
+        .map((outcome) => [
+        inlineCode(outcome.witnessPath),
+        outcome.anchorProofHash !== undefined ? inlineCode(outcome.anchorProofHash) : "(unmatched)",
+        outcome.verified ? "yes" : "no",
+        outcome.reason !== undefined ? inlineCode(outcome.reason) : "",
+        outcome.blockNumber ?? "",
+        outcome.timestamp !== undefined ? formatTimestamp(outcome.timestamp) : "",
+    ])));
+    lines.push("");
+    lines.push("A verified witness means this tool decoded the supplied block " +
+        "header, recomputed the block fingerprint locally, and confirmed it " +
+        "against the fingerprint the authority signed into the anchor. A " +
+        "failed witness confers nothing and does not change the anchor " +
+        "proof's own standing.");
+    lines.push("");
+}
+function temporalDetails(lines, report) {
+    lines.push("### Temporal bounds");
+    lines.push("");
+    if (report.temporal.segments.length === 0) {
+        lines.push("No partitioned proofs exist, so no temporal segments were derived.");
+        lines.push("");
+        return;
+    }
+    for (let i = 0; i < report.temporal.segments.length && i < MAX_TABLE_ROWS; i++) {
+        const segment = report.temporal.segments[i];
+        if (segment === undefined)
+            continue;
+        lines.push(`Segment ${i + 1}: ${withCommas(segment.memberProofHashes.length)} ` +
+            `${plural(segment.memberProofHashes.length, "proof", "proofs")}` +
+            (segment.positionRange !== undefined
+                ? ` at positions ${withCommas(segment.positionRange.min)} to ${withCommas(segment.positionRange.max)}`
+                : "") +
+            ` in partition signer ${inlineCode(segment.partition.publicKeyB64)}, epoch ` +
+            `${segment.partition.epochId !== undefined ? inlineCode(segment.partition.epochId) : "(none)"}, ` +
+            `chain ${inlineCode(segment.partition.chainId)}. Status: ${segment.status}.`);
+        for (const bound of [...segment.lowerBounds, ...segment.upperBounds]) {
+            lines.push(`- ${boundLine(bound)}`);
+        }
+        lines.push("");
+    }
+    if (report.epochRelationships.anchorOrderedPairs.length > 0) {
+        lines.push("Anchor-derived epoch ordering (assumption-dependent, covered portions only):");
+        lines.push("");
+        for (const pair of report.epochRelationships.anchorOrderedPairs) {
+            lines.push(`- Covered portion of epoch ${inlineCode(pair.beforeEpochId)} ` +
+                `(${withCommas(pair.beforeCoveredProofCount)} of ${withCommas(pair.beforeTotalProofCount)} proofs) ` +
+                `before covered portion of epoch ${inlineCode(pair.afterEpochId)} ` +
+                `(${withCommas(pair.afterCoveredProofCount)} of ${withCommas(pair.afterTotalProofCount)} proofs) ` +
+                `(evidence: not-after ${pair.upperEvidence}, not-before ${pair.lowerEvidence}` +
+                `${pair.weaker ? ", weaker" : ""}). ${pair.note}`);
+        }
+        lines.push("");
+    }
+}
+function boundLine(bound) {
+    const direction = bound.kind === "not-before"
+        ? "Committed no earlier than"
+        : "Existed before the anchor commit that consumed a block published at";
+    return (`${direction} ${formatTimestamp(bound.timestamp)} ` +
+        `(block ${bound.blockNumber ?? "?"}, anchor ${inlineCode(bound.anchorProofHash)}, ` +
+        `evidence: ${bound.evidence}${bound.weaker ? ", weaker" : ""}). ${bound.claim}`);
+}
+function attestationDetails(lines, report) {
+    lines.push("### Attestation breakdown");
+    lines.push("");
+    const withDocs = report.attestations.records.filter((r) => r.documentPresent);
+    if (withDocs.length === 0) {
+        lines.push("No observed proof carries an attestation document. Declared " +
+            "measurements remain self-reported; no hardware-backed execution " +
+            "claim is made anywhere in this report.");
+        lines.push("");
+        return;
+    }
+    lines.push(...table(["Proof hash", "Declared measurement", "Document", "Validated", "Measurement match", "Bound to proof"], withDocs
+        .slice(0, MAX_TABLE_ROWS)
+        .map((record) => [
+        inlineCode(record.proofHash),
+        record.declaredMeasurementPresent ? "present" : "absent",
+        record.documentPresent ? "present" : "absent",
+        record.documentValidated ? "yes" : "no",
+        record.pcr0MatchesDeclared === undefined ? "not evaluated" : record.pcr0MatchesDeclared ? "yes" : "no",
+        record.userDataBoundToProof === undefined ? "not evaluated" : record.userDataBoundToProof ? "yes" : "no",
+    ])));
+    lines.push("");
+    const failures = withDocs.filter((r) => !r.documentValidated);
+    if (failures.length > 0) {
+        lines.push("Validation failures:");
+        lines.push("");
+        for (const record of failures.slice(0, MAX_TABLE_ROWS)) {
+            lines.push(`- ${inlineCode(record.proofHash)}: ${record.validationFailure ?? "validation failed"}`);
+        }
+        lines.push("");
+    }
+    lines.push("Measurement match and proof binding are evaluated only on documents " +
+        "that validated; values parsed from an unvalidated document prove " +
+        "nothing and are never compared.");
+    lines.push("");
+}
+function unsupportedVersionDetails(lines, report) {
+    lines.push("### Unsupported version inputs");
+    lines.push("");
+    if (report.unsupportedVersions.length === 0) {
+        lines.push("No proof-shaped files were rejected for their version.");
+        lines.push("");
+        return;
+    }
+    lines.push("The audit system supports exactly one proof schema, bitgraph/1. The " +
+        "following proof-shaped files were rejected at ingest and excluded " +
+        "from verification, chain reconstruction, and anomaly analysis:");
+    lines.push("");
+    lines.push(...table(["Path", "Version string", "File SHA-256"], report.unsupportedVersions
+        .slice(0, MAX_TABLE_ROWS)
+        .map((record) => [
+        inlineCode(record.path),
+        inlineCode(record.version),
+        inlineCode(record.fileSha256Hex),
+    ])));
+    lines.push("");
+}
+function manifestDetails(lines, report) {
+    lines.push("### Bundle manifest");
+    lines.push("");
+    const manifest = report.input.manifest;
+    if (manifest === undefined) {
+        lines.push("No manifest.json was present at the bundle root. The manifest is " +
+            "optional and advisory; its absence changes nothing about the " +
+            "evidence above.");
+        lines.push("");
+        lines.push(`Computed deterministic contents hash: ${inlineCode(report.input.computedContentsHashB64)}.`);
+        lines.push("");
+        return;
+    }
+    lines.push(`A manifest was present (parsed: ${manifest.parsed ? "yes" : "no"}, ` +
+        `recognized: ${manifest.recognized ? "yes" : "no"}). All manifest fields ` +
+        "are unsigned and advisory; the audit never treats them as evidence.");
+    lines.push("");
+    if (manifest.contentsHash !== undefined) {
+        lines.push(`Declared contents hash ${manifest.contentsHash.match ? "matches" : "does NOT match"} ` +
+            `the computed value. Declared: ${inlineCode(manifest.contentsHash.declaredB64)}. ` +
+            `Computed: ${inlineCode(manifest.contentsHash.computedB64)}.`);
+    }
+    else {
+        lines.push(`Computed deterministic contents hash: ${inlineCode(report.input.computedContentsHashB64)} ` +
+            "(the manifest declared none).");
+    }
+    if (manifest.problems.length > 0) {
+        lines.push("");
+        lines.push("Manifest field problems (advisory):");
+        for (const problem of manifest.problems)
+            lines.push(`- ${problem}`);
+    }
+    lines.push("");
+}
+// ---------------------------------------------------------------------------
+// Plain-language meaning per stable code
+// ---------------------------------------------------------------------------
+function codeMeaning(code) {
+    switch (code) {
+        case "unsupported-version":
+            return "A proof-shaped file whose version is not bitgraph/1 was rejected at ingest and excluded from every analysis.";
+        case "proofhash-mismatch":
+            return "A stored copy carries a proofHash label that does not match the identity computed from the proof's own signed content. The computed identity governs; the label is never trusted.";
+        case "exact-duplicate":
+            return "The same proof file appears more than once, byte for byte. Harmless; copies collapse into one observed proof.";
+        case "semantic-duplicate":
+            return "The same proof appears in more than one byte encoding. Harmless; identity is computed from the signed content, not the file bytes.";
+        case "unsafe-path":
+            return "A container entry declared a path that could escape the bundle root. The entry was skipped and never interpreted.";
+        case "duplicate-path":
+            return "Two container entries normalized to the same path; the later entry was used.";
+        case "manifest-unparseable":
+            return "The root manifest.json did not parse. The manifest is advisory; nothing about the proofs changes.";
+        case "manifest-unrecognized-version":
+            return "The manifest's version field is missing or unrecognized, so the manifest was reported but not interpreted.";
+        case "manifest-field-invalid":
+            return "A manifest field fails the bundle specification's type rules. Advisory only.";
+        case "manifest-contents-hash-mismatch":
+            return "The manifest's declared contents hash does not match the computed one. The manifest is advisory; the computed value governs.";
+        case "unexplained-counter-positions":
+            return "Counter positions inside the observed range are neither commit positions nor referenced slot positions. Such a position may be a proof absent from the bundle, or a slot that was allocated but never committed (routine and benign); this offline audit cannot distinguish them, and it does not, by itself, prove the authority failed to create or withheld any proof.";
+        case "counter-collision":
+            return "Two or more valid proofs claim the same commit counter. All are preserved; the audit tool does not choose between them.";
+        case "slot-collision":
+            return "Two or more valid proofs reference the same slot counter. All are preserved; the audit tool does not choose between them.";
+        case "cross-kind-position-reuse":
+            return "A commit counter in one proof equals a different valid proof's slot position in the same partition: one causal position allocated twice across kinds, which only enclave malfunction, replay, or compromise produces. All parties are preserved; the audit tool does not choose between them.";
+        case "predecessor-reuse":
+            return "Two or more valid proofs name the same predecessor: the chain forks at that point. All branches are preserved; the audit tool does not choose between them.";
+        case "chain-break-missing":
+            return "A proof names a predecessor absent from the bundle. History before that point cannot be reconstructed from the supplied evidence; the absence does not, by itself, prove the predecessor never existed.";
+        case "chain-break-malformed":
+            return "A proof's predecessor reference is not a well-formed hash and can never match any proof.";
+        case "chain-break-cross-partition":
+            return "A proof's predecessor reference resolves to a proof under a different signer, epoch, or chain. Predecessor links never bridge those boundaries.";
+        case "multiple-genesis":
+            return "More than one proof in the same partition starts a chain without naming a predecessor. A single such proof is the normal start of an epoch; several need adjudication.";
+        case "slot-order-violation":
+            return "A proof's slot position is not strictly before its commit position, violating the slot-then-commit ordering.";
+        case "epochlink-terminal-missing":
+            return "An epoch's first proof links to a prior epoch that is observed, but the specific proof it names is absent from the bundle.";
+        case "epochlink-dangling":
+            return "An epoch's first proof links to a prior epoch and proof, neither of which appears in the bundle.";
+        case "epochlink-fork":
+            return "Two or more successor epochs claim the same predecessor terminal proof. All claims are preserved; the audit tool does not choose between them.";
+        case "epochlink-cycle":
+            return "Epoch lineage links form a cycle, so the claimed epoch ordering is self-contradictory. No ordering is asserted for the affected pairs.";
+        case "epochlink-mismatch":
+            return "An epoch lineage link matches an observed proof, but the link's declared epoch, key, or counter disagrees with that proof. The link is not used as ordering evidence.";
+        case "mid-epoch-signer-change":
+            return "More than one signer key appears within a single epoch. An epoch is one uninterrupted run of the authority under one key, so this requires explanation.";
+        case "mid-epoch-measurement-change":
+            return "More than one declared software measurement appears within a single epoch, which a single uninterrupted run does not produce.";
+        case "anchor-metadata-disagreement":
+            return "A proof's signed content identifies it as an Ethereum anchor while its unsigned metadata says otherwise. The signed content governs.";
+        case "anchor-metadata-only-claim":
+            return "Unsigned metadata claims a proof is an Ethereum anchor, but the signed content does not. Metadata alone never makes a proof an anchor.";
+        case "anchor-title-unparseable":
+            return "An anchor's signed block reference does not parse as an Etherscan block URL, so the block number is treated as absent rather than guessed.";
+        case "witness-malformed":
+            return "An anchor witness file fails the bundle specification's field rules. It confers nothing.";
+        case "witness-rlp-invalid":
+            return "An anchor witness's block header bytes are not a well-formed header encoding. It confers nothing.";
+        case "witness-header-shape":
+            return "A witness header decoded, but the block number or timestamp field is missing or malformed where the specification requires it.";
+        case "witness-hash-mismatch":
+            return "The block fingerprint recomputed from the witness header does not equal the fingerprint the authority signed. The witness confers nothing.";
+        case "witness-digest-mismatch":
+            return "The signed block fingerprint is not correctly bound to the anchor proof's artifact digest. The witness confers nothing.";
+        case "witness-block-number-mismatch":
+            return "The witness header's block number disagrees with the witness's claim or the signed block reference.";
+        case "witness-claimed-hash-mismatch":
+            return "The witness's claimed block fingerprint does not equal the one recomputed from its own header bytes.";
+        case "witness-anchor-invalid":
+            return "The candidate anchor proof is not cryptographically valid, and a witness cannot rescue an invalid proof.";
+        case "witness-unmatched":
+            return "A witness's block fingerprint matches no observed anchor. It confers nothing.";
+        case "attestation-invalid":
+            return "An attestation document is present but failed offline cryptographic validation. Its contents prove nothing.";
+        case "attestation-measurement-mismatch":
+            return "A validated attestation document's measurement does not equal the measurement the proof declares.";
+        case "attestation-user-data-mismatch":
+            return "A validated attestation document is not bound to the specific proof that carries it.";
+        default:
+            return "See the anomaly details section.";
+    }
+}
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+function partitionLabel(partition) {
+    return (`signer ${inlineCode(shorten(partition.key.publicKeyB64))}, ` +
+        `epoch ${partition.key.epochId !== undefined ? inlineCode(partition.key.epochId) : "(none)"}, ` +
+        `chain ${inlineCode(partition.key.chainId)}`);
+}
+function samePartition(a, b) {
+    return a.publicKeyB64 === b.publicKeyB64 && a.epochId === b.epochId && a.chainId === b.chainId;
+}
+function shorten(value) {
+    return value.length > 16 ? `${value.slice(0, 12)}...` : value;
+}
+function inlineCode(value) {
+    return `\`${value.replace(/`/g, "'")}\``;
+}
+/** Unix seconds as "seconds (ISO UTC)". Pure conversion; no clock read. */
+function formatTimestamp(unixSeconds) {
+    return `${unixSeconds} (${new Date(unixSeconds * 1000).toISOString()})`;
+}
+/** Thousands separators for prose, matching the brief's style examples. */
+function withCommas(value) {
+    const s = String(value);
+    if (!/^\d+$/.test(s))
+        return s;
+    return s.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function plural(count, singular, pluralForm) {
+    return String(count) === "1" ? singular : pluralForm;
+}
+function table(headers, rows) {
+    const escape = (cell) => cell.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+    const out = [];
+    out.push(`| ${headers.map(escape).join(" | ")} |`);
+    out.push(`| ${headers.map(() => "---").join(" | ")} |`);
+    for (const row of rows)
+        out.push(`| ${row.map(escape).join(" | ")} |`);
+    return out;
+}
+//# sourceMappingURL=report-md.js.map