@mikeargento/bitgraph-audit 0.1.2 → 0.2.0

package/src/anomalies.ts

@@ -34,6 +34,7 @@
 
 import type {
   AnomalyReport,
+  BoundaryEntryPoint,
   ChainAnomaly,
   ChainPartition,
   DivergenceParty,
@@ -72,6 +73,7 @@ export async function classifyAnomalies(
 ): Promise<AnomalyReport> {
   const anomalies: ChainAnomaly[] = [];
   const divergences: DivergenceRecord[] = [];
+  const boundaryEntryPoints: BoundaryEntryPoint[] = [];
 
   const byHash = new Map<string, ObservedProof>(ingest.proofs.map((p) => [p.proofHash, p]));
   // Predecessor links (prevB64, epochLink.prevProofHashB64) reference the CHAIN
@@ -89,7 +91,7 @@ export async function classifyAnomalies(
     await analyzeCollisions(partition, members, "slot", anomalies, divergences);
     await analyzeCrossKindPositionReuse(partition, members, anomalies, divergences);
     await analyzePredecessorReuse(partition, members, byChainHash, anomalies, divergences);
-    analyzeChainBreaks(partition, members, byChainHash, partitionOf, anomalies);
+    analyzeChainBreaks(partition, members, byChainHash, partitionOf, anomalies, boundaryEntryPoints);
     await analyzeMultipleGenesis(partition, members, anomalies, divergences);
     analyzeSlotOrder(partition, members, anomalies);
   }
@@ -99,7 +101,7 @@ export async function classifyAnomalies(
   // happened upstream in reconstruct.ts against chain hashes.
   await analyzeEpochLinks(reconstruction.epochRelationships.edges, byHash, anomalies, divergences);
 
-  return { anomalies, divergences };
+  return { anomalies, divergences, boundaryEntryPoints };
 }
 
 // ---------------------------------------------------------------------------
@@ -385,10 +387,20 @@ function analyzeChainBreaks(
   members: ObservedProof[],
   byChainHash: Map<string, ObservedProof>,
   partitionOf: Map<string, PartitionKey>,
-  anomalies: ChainAnomaly[]
+  anomalies: ChainAnomaly[],
+  boundaryEntryPoints: BoundaryEntryPoint[]
 ): void {
   // prevB64 resolves in-partition when it equals a member's CHAIN hash.
   const memberChainHashes = new Set(members.map((m) => m.chainHash));
+  // Lowest observed commit counter: a dangling link AT the lowest position is
+  // the excerpt's frontier (an expected boundary); a dangling link ABOVE it is
+  // an interior hole (a real chain break, and the missing proof's positions
+  // also surface as unexplained-counter-positions).
+  let minCounter: bigint | undefined;
+  for (const m of members) {
+    const c = parseCounter(m.counter);
+    if (c !== undefined && (minCounter === undefined || c < minCounter)) minCounter = c;
+  }
   for (const m of [...members].sort(byCounterThenHash)) {
     if (m.prevB64 === undefined) continue;
     if (memberChainHashes.has(m.prevB64)) continue; // resolved in-partition
@@ -433,14 +445,42 @@ function analyzeChainBreaks(
       continue;
     }
 
+    // A well-formed, in-partition prevB64 whose predecessor is absent splits
+    // into two cases by position:
+    //
+    //  - FRONTIER (m is at the lowest observed counter): the excerpt simply
+    //    starts here; its predecessor precedes the exported window. This is the
+    //    EXPECTED boundary of any bounded bundle, not a defect. A validly
+    //    signed, attested proof only exists by extending the chain (fail-closed
+    //    construction), so its predecessor did exist; it is just not included.
+    //    Recorded as an informational boundary entry point — never sets the
+    //    exit code, never marks the partition non-intact. A full-epoch export
+    //    has none of these (its earliest proof is the genesis, no prevB64).
+    //
+    //  - INTERIOR (a lower-counter member is present): a proof sits below m yet
+    //    the link into m is broken — a genuine hole. Stays a chain-break-missing
+    //    anomaly. The missing proof's own positions also surface as
+    //    unexplained-counter-positions, so an interior hole always fails.
+    const c = parseCounter(m.counter);
+    const isFrontier = c === undefined || minCounter === undefined || c <= minCounter;
+    if (isFrontier) {
+      boundaryEntryPoints.push({
+        partition: partition.key,
+        proofHash: m.proofHash,
+        prevB64: m.prevB64,
+      });
+      continue;
+    }
+
     anomalies.push({
       code: "chain-break-missing",
       partition: partition.key,
       proofHashes: [m.proofHash],
       message:
-        "commit.prevB64 references a predecessor proof that is absent from the supplied bundle. The " +
-        "chain cannot be reconstructed across this link from the supplied evidence; this does not, by " +
-        "itself, establish that the predecessor never existed.",
+        "commit.prevB64 references a predecessor proof that is absent from the supplied bundle, and a " +
+        "lower-positioned proof IS present, so this is an interior break (a hole), not the excerpt's " +
+        "starting boundary. The chain cannot be reconstructed across this link from the supplied " +
+        "evidence; this does not, by itself, establish that the predecessor never existed.",
       details: { prevB64: m.prevB64 },
     });
   }

package/src/audit.ts

@@ -17,7 +17,6 @@
  * Zero network access, as everywhere in this package.
  */
 
-import { readFileSync } from "node:fs";
 import { ingestBundle } from "./ingest.js";
 import { verifyObservedProofs } from "./verify-tiers.js";
 import { reconstructChains } from "./reconstruct.js";
@@ -27,28 +26,49 @@ import { identifyAnchors } from "./anchors.js";
 import { verifyAnchorWitnesses } from "./witness.js";
 import { deriveTemporalBounds } from "./temporal.js";
 import { validateAttestations } from "./attestation.js";
-import type { AuditOptions, AuditResult, ExitFlags } from "./types.js";
+import type { AuditOptions, AuditResult, ExitFlags, IngestResult } from "./types.js";
 
-let cachedToolVersion: string | undefined;
+/**
+ * The audit package's own version, as a source constant rather than a
+ * runtime package.json read. The read had two failure modes in bundled
+ * embedders (esbuild/webpack output, browsers): a foreign package.json one
+ * level up supplies the WRONG version into every report, or there is no
+ * package.json at all and the read throws mid-audit. A unit test asserts
+ * this equals package.json's version, so the constant cannot drift silently
+ * across releases.
+ */
+export const AUDIT_VERSION = "0.2.0";
 
-/** The audit package's own version, read once from its package.json. */
+/** The audit package's own version. */
 export function auditToolVersion(): string {
-  if (cachedToolVersion === undefined) {
-    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
-    cachedToolVersion = (JSON.parse(raw) as { version: string }).version;
-  }
-  return cachedToolVersion;
+  return AUDIT_VERSION;
+}
+
+/** Options for auditIngest(): the audit options plus the run stamp. */
+export interface AuditIngestOptions extends AuditOptions {
+  /**
+   * The runMetadata.startedAt value. runAudit() stamps the wall clock here;
+   * an embedder that needs a fully deterministic result supplies its own
+   * (any string, for example ""). Defaults to the wall clock when omitted.
+   */
+  startedAt?: string;
 }
 
 /**
- * Run the complete audit pipeline over a bundle (directory, .tar, .tar.gz,
- * or .tgz) and return everything every stage produced.
+ * The pure tail of the pipeline over an already-ingested bundle: every
+ * stage after ingest, in canonical order, with no filesystem access. This
+ * is how a browser or an embedder that used ingestEntries() gets the same
+ * AuditResult the CLI gets from a path. runAudit() is exactly
+ * ingestBundle() followed by this.
  */
-export async function runAudit(bundlePath: string, options?: AuditOptions): Promise<AuditResult> {
-  // The ONLY wall-clock read in the pipeline. See AuditRunMetadata.
-  const startedAt = new Date().toISOString();
+export async function auditIngest(
+  ingest: IngestResult,
+  options?: AuditIngestOptions
+): Promise<AuditResult> {
+  // The ONLY wall-clock read in the pipeline, and only when the caller did
+  // not supply the stamp. See AuditRunMetadata.
+  const startedAt = options?.startedAt ?? new Date().toISOString();
 
-  const ingest = await ingestBundle(bundlePath);
   const verification = await verifyObservedProofs(
     ingest,
     options?.trustAnchors !== undefined ? { trustAnchors: options.trustAnchors } : undefined
@@ -72,7 +92,7 @@ export async function runAudit(bundlePath: string, options?: AuditOptions): Prom
     runMetadata: {
       toolVersion: auditToolVersion(),
       startedAt,
-      bundlePath,
+      bundlePath: ingest.bundlePath,
       container: ingest.container,
     },
     ingest,
@@ -87,6 +107,15 @@ export async function runAudit(bundlePath: string, options?: AuditOptions): Prom
   };
 }
 
+/**
+ * Run the complete audit pipeline over a bundle (directory, .tar, .tar.gz,
+ * or .tgz) and return everything every stage produced.
+ */
+export async function runAudit(bundlePath: string, options?: AuditOptions): Promise<AuditResult> {
+  const ingest = await ingestBundle(bundlePath);
+  return auditIngest(ingest, options);
+}
+
 /**
  * Anchor witness verification-failure codes: every finding the witness
  * stage emits is a failure (verifyAnchorWitnesses records findings only for

package/src/index.ts

@@ -45,6 +45,7 @@ export type {
   ReconstructionResult,
   ChainAnomaly,
   UnexplainedPositionsDetail,
+  BoundaryEntryPoint,
   DivergenceKind,
   DivergenceParty,
   DivergenceRecord,
@@ -84,7 +85,8 @@ export type {
   AuditJsonReport,
 } from "./types.js";
 
-export { ingestBundle, streamMatchedArtifacts, DEFAULT_INGEST_LIMITS } from "./ingest.js";
+export { ingestBundle, ingestEntries, streamMatchedArtifacts, DEFAULT_INGEST_LIMITS } from "./ingest.js";
+export type { BundleEntrySource } from "./ingest.js";
 
 export { verifyObservedProofs } from "./verify-tiers.js";
 
@@ -102,7 +104,8 @@ export { deriveTemporalBounds } from "./temporal.js";
 
 export { validateAttestations, validateNitroAttestationDocument } from "./attestation.js";
 
-export { runAudit, computeExitFlags, auditToolVersion } from "./audit.js";
+export { runAudit, auditIngest, computeExitFlags, auditToolVersion, AUDIT_VERSION } from "./audit.js";
+export type { AuditIngestOptions } from "./audit.js";
 
 export { buildJsonReport } from "./report-json.js";
 

package/src/ingest.ts

@@ -160,6 +160,141 @@ export async function ingestBundle(
     strippedRootPrefix = rootTracker.commonRoot();
   }
 
+  return finalizeIngest({
+    bundlePath,
+    container,
+    scanned,
+    strippedRootPrefix,
+    findings,
+    entriesScanned,
+    skippedUnsafePaths,
+  });
+}
+
+/**
+ * One in-memory bundle entry for ingestEntries(): a bundle-root-relative
+ * path (forward slashes) and a way to open its bytes. `open` may be called
+ * more than once (once to scan and hash, again to re-read matched artifact
+ * bytes for full-tier verification), and it may return the bytes whole,
+ * a promise of them, or an async chunk stream, so a browser can hand over
+ * File objects without buffering every artifact up front.
+ */
+export interface BundleEntrySource {
+  path: string;
+  open: () => Uint8Array | Promise<Uint8Array> | AsyncIterable<Uint8Array>;
+}
+
+/**
+ * Per-result registry of entry sources for in-memory ("memory" container)
+ * ingests, so streamMatchedArtifacts can re-read artifact bytes without the
+ * IngestResult carrying functions. Keyed by identity: a structurally cloned
+ * IngestResult loses its sources and yields no artifact bytes, which
+ * downgrades every proof to the integrity tier rather than crashing.
+ */
+const memorySources = new WeakMap<IngestResult, Map<string, BundleEntrySource>>();
+
+/**
+ * Ingest a bundle from in-memory entries: the filesystem-free counterpart
+ * of ingestBundle(), for browsers and embedders that already hold the
+ * bytes. Same discovery, classification, hashing, and matching, so the
+ * result feeds the same verification and reconstruction stages. Entries
+ * are ordered by path before scanning so the result is deterministic
+ * regardless of the order the caller supplied them; paths are normalized
+ * exactly as tar entries are (unsafe paths are skipped and reported).
+ * Performs no verification and no network access.
+ */
+export async function ingestEntries(
+  entries: Iterable<BundleEntrySource>,
+  options?: { label?: string }
+): Promise<IngestResult> {
+  const findings: AuditFinding[] = [];
+  let skippedUnsafePaths = 0;
+  let entriesScanned = 0;
+  const scanned: ScannedEntry[] = [];
+  const sources = new Map<string, BundleEntrySource>();
+
+  const ordered = Array.from(entries).sort((a, b) =>
+    a.path < b.path ? -1 : a.path > b.path ? 1 : 0
+  );
+  for (const entry of ordered) {
+    entriesScanned++;
+    const normalized = normalizeEntryPath(entry.path);
+    if (normalized.unsafe) {
+      skippedUnsafePaths++;
+      findings.push({
+        code: "unsafe-path",
+        path: entry.path,
+        message: `entry skipped: ${normalized.reason}`,
+      });
+      continue;
+    }
+    const hashed = await hashEntryStream(
+      normalized.path,
+      undefined,
+      undefined,
+      openAsChunks(entry.open())
+    );
+    scanned.push(makeScannedEntry(normalized.path, hashed));
+    sources.set(normalized.path, entry);
+  }
+
+  const result = finalizeIngest({
+    bundlePath: options?.label ?? "",
+    container: "memory",
+    scanned,
+    strippedRootPrefix: undefined,
+    findings,
+    entriesScanned,
+    skippedUnsafePaths,
+  });
+  memorySources.set(result, sources);
+  return result;
+}
+
+/** Adapt every accepted `open()` return shape to a chunk stream. */
+async function* openAsChunks(
+  opened: Uint8Array | Promise<Uint8Array> | AsyncIterable<Uint8Array>
+): AsyncGenerator<Uint8Array, void, void> {
+  const value = await Promise.resolve(opened as Uint8Array | Promise<Uint8Array>);
+  if (value instanceof Uint8Array) {
+    yield value;
+    return;
+  }
+  // Not a Uint8Array and not a promise of one: an async iterable.
+  for await (const chunk of opened as AsyncIterable<Uint8Array>) yield chunk;
+}
+
+/** Read an in-memory entry whole for artifact re-reads. */
+async function readSourceWhole(source: BundleEntrySource): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for await (const chunk of openAsChunks(source.open())) {
+    chunks.push(chunk);
+    total += chunk.length;
+  }
+  return concatBytes(chunks, total);
+}
+
+interface FinalizeParams {
+  bundlePath: string;
+  container: ContainerKind;
+  scanned: ScannedEntry[];
+  strippedRootPrefix: string | undefined;
+  findings: AuditFinding[];
+  entriesScanned: number;
+  skippedUnsafePaths: number;
+}
+
+/**
+ * The container-independent tail of ingest: path finalization, the
+ * contents hash, classification by schema shape, and content-addressed
+ * artifact matching. Both ingestBundle() and ingestEntries() end here, so
+ * a directory, an archive, and an in-memory entry set that hold the same
+ * bytes at the same paths classify identically.
+ */
+function finalizeIngest(params: FinalizeParams): IngestResult {
+  const { bundlePath, container, scanned, strippedRootPrefix, findings, entriesScanned, skippedUnsafePaths } = params;
+
   const finalByPath = new Map<string, FinalEntry>();
   for (const entry of scanned) {
     let finalPath = entry.rawPath;
@@ -318,6 +453,30 @@ export async function* streamMatchedArtifacts(
   const needed = ingest.artifacts.filter((a) => a.matchedProofHashes.length > 0);
   if (needed.length === 0) return;
 
+  if (ingest.container === "memory") {
+    // In-memory ingest: re-open through the registered sources. A result
+    // whose sources are unknown (cloned, or not from ingestEntries) yields
+    // nothing, so verification falls back to the integrity tier.
+    const sources = memorySources.get(ingest);
+    if (sources === undefined) return;
+    for (const artifact of needed) {
+      for (const relPath of artifact.paths) {
+        const source = sources.get(relPath);
+        if (source === undefined) continue;
+        let bytes: Uint8Array;
+        try {
+          bytes = await readSourceWhole(source);
+        } catch {
+          continue;
+        }
+        if (toHex(sha256(bytes)) !== artifact.sha256Hex) continue;
+        yield { sha256Hex: artifact.sha256Hex, path: relPath, bytes };
+        break;
+      }
+    }
+    return;
+  }
+
   if (ingest.container === "directory") {
     for (const artifact of needed) {
       for (const relPath of artifact.paths) {

package/src/report-json.ts

@@ -104,6 +104,7 @@ export function buildJsonReport(result: AuditResult): AuditJsonReport {
     },
     anomalies,
     divergences: result.anomalies.divergences,
+    boundaryEntryPoints: result.anomalies.boundaryEntryPoints,
     authorities: {
       groups: result.authorities.groups,
       sharedSignersAcrossEpochs: result.authorities.sharedSignersAcrossEpochs,
@@ -307,6 +308,7 @@ function buildSummary(
     epochsObserved: result.reconstruction.epochRelationships.epochs.length,
     anomalyCountsByCode,
     divergenceCount: result.anomalies.divergences.length,
+    boundaryEntryPoints: result.anomalies.boundaryEntryPoints.length,
     authorityGroupCount: result.authorities.groups.length,
     distinctSignerCount: signers.size,
     distinctDeclaredMeasurementCount: measurements.size,

package/src/report-md.ts

@@ -252,6 +252,23 @@ function executiveSummary(
   }
   lines.push("");
 
+  // Boundary entry points (expected excerpt frontiers, not anomalies).
+  const boundaries = report.boundaryEntryPoints.length;
+  if (boundaries > 0) {
+    lines.push("### Bundle boundaries");
+    lines.push("");
+    lines.push(
+      `${withCommas(boundaries)} ${plural(boundaries, "proof is", "proofs are")} the earliest of a ` +
+        "reconstructed chain and reference a predecessor that precedes the exported window. This is the " +
+        "expected boundary of a bounded excerpt (a single-file proof bundle or a small batch), not a " +
+        "chain-integrity defect: a validly signed, attested proof only comes into existence by extending " +
+        "the chain, so its predecessor did exist and is simply not included here. Boundaries never set the " +
+        "exit code. A full-epoch export has none (its earliest proof is the epoch genesis, which has no " +
+        "predecessor link)."
+    );
+    lines.push("");
+  }
+
   // Divergences.
   lines.push("### Divergences");
   lines.push("");

package/src/types.ts

@@ -385,7 +385,11 @@ export interface ManifestReport {
 // ---------------------------------------------------------------------------
 
 /** Accepted container forms per the bundle spec section 4. */
-export type ContainerKind = "directory" | "tar" | "tar-gz";
+/**
+ * "memory" is an ingestEntries() result: entries supplied by the caller
+ * with no container on disk. bundlePath is then the caller's label (or "").
+ */
+export type ContainerKind = "directory" | "tar" | "tar-gz" | "memory";
 
 export interface IngestCounts {
   /** Unique observed proofs by canonical identity. */
@@ -758,6 +762,36 @@ export interface ChainAnomaly {
   details?: Record<string, unknown>;
 }
 
+/**
+ * A chain link whose predecessor is absent from the supplied bundle: the
+ * earliest proof of a reconstructed run points to history that precedes the
+ * exported window.
+ *
+ * This is the EXPECTED boundary of any bounded excerpt (a single-file proof
+ * bundle, a small batch), NOT a chain-integrity defect: a validly signed,
+ * attested proof only comes into existence by extending the chain (the
+ * fail-closed construction property), so its own existence is evidence it
+ * occupied a real position; the predecessor is simply not included in this
+ * export. A full-epoch export has NO boundary entry points, its earliest
+ * proof is the epoch genesis, which carries no prevB64 at all. An INTERIOR
+ * hole never masquerades as a boundary: a missing mid-chain proof both
+ * fragments the component (so the successor becomes its own component's
+ * boundary) AND surfaces as an `unexplained-counter-positions` anomaly within
+ * the observed range, which still trips the exit code.
+ *
+ * Boundary entry points are informational: they never set the exit code and
+ * never mark a partition non-intact. The count is surfaced in the summary so a
+ * full-epoch audit (which expects zero) makes a stray boundary visible.
+ */
+export interface BoundaryEntryPoint {
+  /** The partition this boundary is scoped to. */
+  partition: PartitionKey;
+  /** The proof whose commit.prevB64 references a predecessor absent from the bundle. */
+  proofHash: string;
+  /** The unresolved predecessor chain hash (standard base64). */
+  prevB64: string;
+}
+
 /**
  * Detail payload of an "unexplained-counter-positions" anomaly (G2).
  * A position is explained when it is some observed proof's commit counter
@@ -833,6 +867,12 @@ export interface AnomalyReport {
   anomalies: ChainAnomaly[];
   /** Divergence records for every conflict between valid proofs. */
   divergences: DivergenceRecord[];
+  /**
+   * Expected excerpt boundaries: a bundle's earliest proofs whose predecessor
+   * precedes the exported window. Informational only, never affects the exit
+   * code or partition intactness. Zero for a full-epoch export.
+   */
+  boundaryEntryPoints: BoundaryEntryPoint[];
 }
 
 // ---------------------------------------------------------------------------
@@ -1448,6 +1488,13 @@ export interface ReportSummary {
   /** Anomaly counts keyed by stable code, keys sorted. */
   anomalyCountsByCode: Record<string, number>;
   divergenceCount: number;
+  /**
+   * Count of expected excerpt boundaries (earliest proofs whose predecessor
+   * precedes the exported window). Informational, never a failure. A
+   * full-epoch export has zero; a bounded proof bundle has one per included
+   * chain segment.
+   */
+  boundaryEntryPoints: number;
   authorityGroupCount: number;
   distinctSignerCount: number;
   distinctDeclaredMeasurementCount: number;
@@ -1506,6 +1553,8 @@ export interface AuditJsonReport {
   /** Unified anomaly list: stage order (ingest, chain, authority, anchor, witness, attestation), stage-internal detection order. */
   anomalies: ReportAnomaly[];
   divergences: DivergenceRecord[];
+  /** Expected excerpt boundaries (informational; never a failure). Empty for a full-epoch export. */
+  boundaryEntryPoints: BoundaryEntryPoint[];
   authorities: {
     groups: AuthorityGroup[];
     sharedSignersAcrossEpochs: SignerEpochSpan[];