@mikeargento/bitgraph-mcp 0.3.0 → 0.4.1

package/src/api.ts

@@ -3,17 +3,15 @@
 /**
  * @mikeargento/bitgraph-mcp: HTTP client for the hosted BitGraph API.
  *
- * All recording goes through the website's /api/commit proxy rather than the
- * TEE directly: the proxy is what maintains the per-position by-digest index
- * that makes every causal position of a file discoverable afterward.
+ * The reads: the batch lookup, the proof detail, the number search. Making a
+ * BitGraph goes through the core package's own transport against the same
+ * site (its /api/fuse routes), which is what maintains the per-position
+ * by-digest index that makes every member of a set discoverable afterward;
+ * the one write here is a set/2's member evidence, indexed after the commit.
  */
 
-import type {
-  BatchCheckResponse,
-  BitGraphProof,
-  ProofDetailResponse,
-  SearchResponse,
-} from "./types.js";
+import { mapConcurrent } from "./encoding.js";
+import type { BatchCheckResponse, ProofDetailResponse, SearchResponse, SetIndexResponse } from "./types.js";
 
 export interface ApiConfig {
   baseUrl: string;
@@ -27,13 +25,13 @@ export function configFromEnv(): ApiConfig {
   return apiKey ? { baseUrl, apiKey } : { baseUrl };
 }
 
-/** Matches the website client: 50 digests per commit request (~1s of TEE work each). */
-export const COMMIT_CHUNK_SIZE = 50;
 /** Matches the batch endpoint's MAX_DIGESTS. */
 export const BATCH_CHECK_LIMIT = 500;
+/** Batch lookups in flight at once: a large folder is many pages. */
+const BATCH_CHECK_CONCURRENCY = 4;
 
 const CHECK_TIMEOUT_MS = 30_000;
-const COMMIT_TIMEOUT_MS = 120_000;
+const SET_INDEX_TIMEOUT_MS = 60_000;
 
 export class ApiError extends Error {
   readonly status: number;
@@ -104,83 +102,44 @@ async function postJson<T>(
 
 /**
  * Look up which digests are on record. Input digests must be URL-safe base64;
- * the response is keyed by the exact strings sent. Batches of up to 500.
+ * the response is keyed by the exact strings sent. Pages of up to 500, a few
+ * in flight at once.
  */
 export async function batchCheck(
   config: ApiConfig,
   urlSafeDigests: readonly string[]
 ): Promise<BatchCheckResponse> {
-  const merged: BatchCheckResponse = { results: {} };
+  const chunks: string[][] = [];
   for (let offset = 0; offset < urlSafeDigests.length; offset += BATCH_CHECK_LIMIT) {
-    const chunk = urlSafeDigests.slice(offset, offset + BATCH_CHECK_LIMIT);
-    const page = await postJson<BatchCheckResponse>(
-      config,
-      "/api/proofs/batch",
-      { digests: chunk },
-      CHECK_TIMEOUT_MS,
-      false
-    );
-    Object.assign(merged.results, page.results);
+    chunks.push(urlSafeDigests.slice(offset, offset + BATCH_CHECK_LIMIT));
   }
+  const pages = await mapConcurrent(chunks, BATCH_CHECK_CONCURRENCY, (chunk) =>
+    postJson<BatchCheckResponse>(config, "/api/proofs/batch", { digests: chunk }, CHECK_TIMEOUT_MS, false)
+  );
+  const merged: BatchCheckResponse = { results: {} };
+  for (const page of pages) Object.assign(merged.results, page.results);
   return merged;
 }
 
-/**
- * Record digests at new causal positions. Input digests must be STANDARD
- * base64 (as stored in proofs). Commits sequentially in chunks of 50, matching
- * the website client; the TEE serializes commits anyway.
- *
- * On a mid-batch failure the error carries how many proofs were already
- * minted (those are permanent); the caller must report partial results
- * honestly rather than pretending all-or-nothing.
- */
-export async function commitDigests(
-  config: ApiConfig,
-  standardDigests: readonly string[],
-  attribution?: { name?: string | undefined; title?: string | undefined; message?: string | undefined }
-): Promise<BitGraphProof[]> {
-  const proofs: BitGraphProof[] = [];
-  for (let offset = 0; offset < standardDigests.length; offset += COMMIT_CHUNK_SIZE) {
-    const chunk = standardDigests.slice(offset, offset + COMMIT_CHUNK_SIZE);
-    const body: Record<string, unknown> = {
-      digests: chunk.map((digestB64) => ({ digestB64, hashAlg: "sha256" })),
-      chainId: "bitgraph:main",
-    };
-    if (attribution) body["attribution"] = attribution;
-    try {
-      const raw = await postJson<BitGraphProof[] | BitGraphProof>(
-        config,
-        "/api/commit",
-        body,
-        COMMIT_TIMEOUT_MS,
-        true
-      );
-      proofs.push(...(Array.isArray(raw) ? raw : [raw]));
-    } catch (err) {
-      throw new PartialCommitError(proofs, standardDigests.length, err);
-    }
-  }
-  return proofs;
+/** One request's worth of a set/2's member evidence, for the site to index. */
+export interface SetIndexRequest {
+  /** The set proof's artifact digest, URL-safe base64. */
+  setDigest: string;
+  /** The set proof's epoch id, URL-safe base64. */
+  epoch: string;
+  /** The set proof's commit counter. */
+  counter: string;
+  members: unknown[];
 }
 
-/** A commit batch failed partway: `minted` proofs are already permanent. */
-export class PartialCommitError extends Error {
-  readonly minted: BitGraphProof[];
-  readonly requested: number;
-  readonly cause2: unknown;
-
-  constructor(minted: BitGraphProof[], requested: number, cause: unknown) {
-    const reason = cause instanceof Error ? cause.message : String(cause);
-    super(
-      `Recording stopped after ${minted.length} of ${requested} digests: ${reason}` +
-        (cause instanceof ApiError && cause.retryAfterSec !== null
-          ? ` (retry after ${cause.retryAfterSec}s)`
-          : "")
-    );
-    this.minted = minted;
-    this.requested = requested;
-    this.cause2 = cause;
-  }
+/**
+ * Index members of a set/2 from their evidence. The site reads the set proof
+ * from its own position, binds the root document, and checks every member's
+ * path before writing a key; a row that does not bind is rejected, never
+ * written.
+ */
+export async function indexSetMembers(config: ApiConfig, body: SetIndexRequest): Promise<SetIndexResponse> {
+  return postJson<SetIndexResponse>(config, "/api/fuse/set-index", body, SET_INDEX_TIMEOUT_MS, false);
 }
 
 /** Full detail for one digest: proof, all causal positions, anchor window. */

package/src/format.ts

@@ -9,9 +9,11 @@
  */
 
 import { toUrlSafeB64 } from "./encoding.js";
-import type { BitGraphProof, PositionView, ProofDetailResponse } from "./types.js";
+import type { BitGraphProof, PositionView, ProofDetailResponse, SetMemberView } from "./types.js";
 
 export const CHARACTER_LIMIT = 25_000;
+/** Rows per group a markdown summary lists before "and N more". */
+export const MARKDOWN_ROWS = 50;
 
 /** Public proof page URL for a digest, optionally pinned to one causal position. */
 export function proofUrl(
@@ -31,32 +33,54 @@ export function proofUrl(
 }
 
 /**
- * One outcome per path, in the product's own vocabulary. "fused": a new fused
- * artifact was built from the file and committed under its own slot. "on
- * record": the bytes already had a recording or a fused artifact naming them
- * as origin, and nothing was minted. "not fused": the attempt failed; never
- * claim "on record" for bytes that have no proof.
+ * One outcome per path, in the product's own vocabulary. "fused": the file is
+ * a member of the set just made, its new fused bytes listed by digest in the
+ * committed artifact. "on record": the bytes already had a recording or a
+ * fused artifact naming them as origin, and nothing was made. "not fused":
+ * the attempt failed or the file was left out; never claim "on record" for
+ * bytes that have no proof.
  */
 export interface RecordOutcome {
   path: string;
-  /** The file's own digest (URL-safe): the origin of the fused artifact. */
+  /** The file's own digest (URL-safe): the origin of its fused bytes. */
   digest: string;
   outcome: "fused" | "on record" | "not fused";
-  /** The fused artifact's digest (URL-safe), present on a "fused" outcome. */
+  /** The member's fused digest (URL-safe), present on a "fused" outcome. */
   artifact_digest: string | null;
   placement: string | null;
   counter: string | null;
   epoch: string | null; // URL-safe
+  /** The file's row in the set just made, 1-based, of member_count. */
+  member: number | null;
+  member_count: number | null;
   total_positions: number;
   proof_url: string | null;
   error?: string;
 }
 
+/** The one BitGraph a record call makes: a set, one position for every fused row. */
+export interface SetOutcome {
+  /** "set/1": the committed artifact lists every member. "set/2": it is a Merkle root over the rows, and each member's evidence is indexed on the site. */
+  set: "set/1" | "set/2";
+  count: number;
+  counter: string | null;
+  epoch: string | null; // URL-safe
+  /** The committed artifact's digest (URL-safe): the manifest or the root document. */
+  artifact_digest: string;
+  proof_url: string;
+  /** True when the boundary echoed the committed artifact in the proof's metadata, so the ledger's copy carries it. */
+  manifest_echoed: boolean;
+  /** True when the commit response was lost and the proof was read back by digest. */
+  recovered: boolean;
+  /** set/2 only: members whose evidence the site has indexed, and members still waiting. */
+  index: { written: number; pending: number } | null;
+}
+
 export interface CheckOutcome {
   input: string;
   digest: string; // URL-safe
   on_record: boolean;
-  positions: Array<{ counter: string | null; epoch: string | null }>;
+  positions: Array<{ counter: string | null; epoch: string | null; member?: SetMemberView }>;
   proof_url: string | null;
 }
 
@@ -66,56 +90,94 @@ export function positionOf(proof: BitGraphProof): { counter: string | null; epoc
   return { counter, epoch: epochId !== undefined ? toUrlSafeB64(epochId) : null };
 }
 
-export function renderRecordMarkdown(outcomes: readonly RecordOutcome[]): string {
+const fmt = (n: number): string => n.toLocaleString("en-US");
+
+function memberNote(m: SetMemberView | undefined): string {
+  return m ? ` (member ${fmt(m.index + 1)} of ${fmt(m.count)})` : "";
+}
+
+export function renderRecordMarkdown(outcomes: readonly RecordOutcome[], set: SetOutcome | null = null, omitted = 0): string {
   const fused = outcomes.filter((o) => o.outcome === "fused");
   const onRecord = outcomes.filter((o) => o.outcome === "on record");
   const notFused = outcomes.filter((o) => o.outcome === "not fused");
   const lines: string[] = [];
-  let headline = `${fused.length} fused, ${onRecord.length} already on record.`;
-  if (notFused.length > 0) {
-    headline = `${fused.length} fused, ${onRecord.length} already on record, ${notFused.length} NOT fused.`;
+  const parts: string[] = [];
+  if (set !== null && fused.length > 0) {
+    parts.push(`${fmt(fused.length)} file${fused.length === 1 ? "" : "s"} BitGraphed as one set at #${set.counter ?? "?"} (set of ${fmt(set.count)})`);
+  } else {
+    parts.push(`${fmt(fused.length)} fused`);
   }
-  lines.push(headline);
-  for (const o of outcomes) {
-    if (o.outcome === "not fused") {
-      lines.push(`- not fused · ${o.path}${o.error ? `: ${o.error}` : ""}`);
-      continue;
+  parts.push(`${fmt(onRecord.length)} already on record`);
+  if (notFused.length > 0) parts.push(`${fmt(notFused.length)} NOT fused`);
+  lines.push(`${parts.join(", ")}.`);
+  if (set !== null && fused.length > 0) {
+    lines.push(`- #${set.counter ?? "?"} · set of ${fmt(set.count)} · ${set.proof_url}`);
+    if (set.index !== null && set.index.pending > 0) {
+      lines.push(`  The set is on the ledger, but the evidence for ${fmt(set.index.pending)} of its ${fmt(set.count)} members is not indexed yet, so those files are not findable by hash until it is. It is sent again at the start of the next bitgraph_record call.`);
+    }
+    if (!set.manifest_echoed) {
+      lines.push(`  The boundary did not echo the committed artifact; the ledger's copy of this proof carries no member list. Keep the set's proof page.`);
     }
-    const note =
-      o.outcome === "on record"
-        ? o.total_positions > 1
-          ? ` (${o.total_positions} positions, earliest shown)`
-          : ""
-        : o.placement
-          ? ` (${o.placement})`
-          : "";
-    lines.push(`- ${o.outcome} · #${o.counter ?? "?"} · ${o.path}${note}\n  ${o.proof_url}`);
   }
-  if (fused.length > 0) {
+  const group = (rows: readonly RecordOutcome[], render: (o: RecordOutcome) => string, more: (n: number) => string) => {
+    for (const o of rows.slice(0, MARKDOWN_ROWS)) lines.push(render(o));
+    if (rows.length > MARKDOWN_ROWS) lines.push(`- ${more(rows.length - MARKDOWN_ROWS)}`);
+  };
+  group(
+    notFused,
+    (o) => `- not fused · ${o.path}${o.error ? `: ${o.error}` : ""}`,
+    (n) => `and ${fmt(n)} more not fused`
+  );
+  group(
+    onRecord,
+    (o) => {
+      const note = o.total_positions > 1 ? ` (${fmt(o.total_positions)} positions, earliest shown)` : "";
+      const row = o.member !== null && o.member_count !== null ? ` (member ${fmt(o.member)} of ${fmt(o.member_count)})` : "";
+      return `- on record · #${o.counter ?? "?"}${row} · ${o.path}${note}\n  ${o.proof_url}`;
+    },
+    (n) => `and ${fmt(n)} more already on record`
+  );
+  group(
+    fused,
+    (o) =>
+      o.member === null
+        ? `- fused · #${o.counter ?? "?"} · ${o.path} (${o.placement ?? "?"})\n  ${o.proof_url}`
+        : `- fused · ${o.path} (${fmt(o.member)} of ${fmt(o.member_count ?? 0)}, ${o.placement ?? "?"})`,
+    (n) => `and ${fmt(n)} more files in the same set`
+  );
+  if (set !== null && fused.length > 0) {
+    lines.push(
+      "\nOne BitGraph holds every file made here: one slot, one position, and the committed artifact lists each file's new fused bytes by digest. Those bytes were hashed on this machine and never written or uploaded; the file itself is unchanged, and the original plus the set proof rebuilds them. A lookup by any file's own digest finds the set."
+    );
+  } else if (fused.length > 0) {
     lines.push(
-      "\nEach fused artifact was built in memory from the file, hashed and committed under its own slot; the file itself is unchanged and was not uploaded. The original plus the proof rebuilds the fused bytes; the Frame for each is in the structured result."
+      "\nThe new fused file was built in memory from the file, hashed and committed under its own slot; the file itself is unchanged and was not uploaded. The original plus the proof rebuilds the new file; its Frame is in the structured result."
     );
   }
   if (onRecord.length > 0) {
     lines.push(
-      "\nFiles already on record were left alone. To make a new fused artifact from one of them deliberately, call bitgraph_record with again=true."
+      "\nFiles already on record were left alone. To make a new BitGraph of them deliberately, call bitgraph_record with again=true."
     );
   }
+  if (omitted > 0) {
+    lines.push(`\nThe structured result lists the first rows only (${fmt(omitted)} omitted); every fused file shares the set's position above.`);
+  }
   return lines.join("\n");
 }
 
 export function renderCheckMarkdown(outcomes: readonly CheckOutcome[]): string {
   const found = outcomes.filter((o) => o.on_record).length;
-  const lines: string[] = [`${found} of ${outcomes.length} on record.`];
-  for (const o of outcomes) {
+  const lines: string[] = [`${fmt(found)} of ${fmt(outcomes.length)} on record.`];
+  for (const o of outcomes.slice(0, MARKDOWN_ROWS)) {
     if (o.on_record) {
       const first = o.positions[0];
-      const extra = o.positions.length > 1 ? ` and ${o.positions.length - 1} more position(s)` : "";
-      lines.push(`- on record · #${first?.counter ?? "?"}${extra} · ${o.input}\n  ${o.proof_url}`);
+      const extra = o.positions.length > 1 ? ` and ${fmt(o.positions.length - 1)} more position(s)` : "";
+      lines.push(`- on record · #${first?.counter ?? "?"}${memberNote(first?.member)}${extra} · ${o.input}\n  ${o.proof_url}`);
     } else {
       lines.push(`- not on record · ${o.input}`);
     }
   }
+  if (outcomes.length > MARKDOWN_ROWS) lines.push(`- and ${fmt(outcomes.length - MARKDOWN_ROWS)} more; the structured result lists every one`);
   return lines.join("\n");
 }
 
@@ -142,11 +204,17 @@ export function renderProofMarkdown(
   if (!proof) return "No proof found for that digest.";
   const digest = proof.artifact?.digestB64 ?? "";
   const { counter, epoch } = positionOf(proof);
+  const positions: PositionView[] = detail.positions ?? [];
+  const here = positions.find((p) => p.counter === counter) ?? positions[0];
   const lines: string[] = [];
   lines.push(`# BitGraph #${counter ?? "?"}`);
   lines.push("");
   lines.push(`- Digest (SHA-256): ${toUrlSafeB64(digest)}`);
   if (epoch) lines.push(`- Position: counter ${counter ?? "?"} in epoch ${epoch.slice(0, 12)}…`);
+  if (here?.member) {
+    const role = here.member.role === "fused" ? "its new fused bytes" : "the original";
+    lines.push(`- Set: member ${fmt(here.member.index + 1)} of ${fmt(here.member.count)}, as ${role}${here.placement ? ` (${here.placement})` : ""}`);
+  }
   const window = renderWindow(detail);
   if (window) lines.push(`- ${window}`);
   const etherscan =
@@ -162,15 +230,14 @@ export function renderProofMarkdown(
       .join(": ");
     lines.push(`- Submitter's note (self-attributed, not verified): ${note}`);
   }
-  const positions: PositionView[] = detail.positions ?? [];
   if (positions.length > 1) {
     lines.push("");
-    lines.push(`## Causal positions (${positions.length})`);
+    lines.push(`## Causal positions (${fmt(positions.length)})`);
     positions.forEach((p, i) => {
       const label = i === 0 ? " · original" : "";
       const bracket =
         p.lowerTime && p.upperTime ? ` · between ${p.lowerTime} and ${p.upperTime}` : "";
-      lines.push(`- #${p.counter ?? "?"}${label}${bracket}`);
+      lines.push(`- #${p.counter ?? "?"}${label}${p.member ? ` · set of ${fmt(p.member.count)}` : ""}${bracket}`);
     });
   }
   lines.push("");

package/src/scan.ts

@@ -0,0 +1,173 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * @mikeargento/bitgraph-mcp: the scan.
+ *
+ * One pass over each file yields its SHA-256 (the member's origin) and a
+ * hasher left open after the placement's prefix and the file's last byte, so
+ * the member's fused digest can be finished later, for whatever slot the set
+ * is made under, without reading the file again. A placement is prefix,
+ * original, suffix (its frame): trailer/1 has no prefix and container/2's is
+ * the original's tar header, which depends on the size alone; the suffix
+ * carries the commitment and is hashed at BitGraph time. Node's SHA-256 is
+ * the platform's own, and a Hash can be copied mid-stream, which is the whole
+ * trick: the copy takes the suffix, so no file is read twice or held in
+ * memory, and the original is never touched.
+ */
+
+import { createHash, type Hash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { placementForBytes } from "@mikeargento/bitgraph";
+import { getPlacement } from "@mikeargento/bitgraph-verify";
+
+/** The placements the scan makes: chosen from the bytes by the core, never from the name. */
+export type ScanPlacement = "trailer/1" | "container/2";
+
+export interface ScannedFile {
+  path: string;
+  name: string;
+  size: number;
+  /** SHA-256 of the file, standard base64: the member's origin. */
+  digestB64: string;
+  originDigest: Uint8Array;
+  placement: ScanPlacement;
+  /**
+   * The hasher after the placement's prefix and the file's bytes, still open.
+   * Null when the file's length changed while it was read: its fused digest
+   * then needs the bytes again.
+   */
+  state: Hash | null;
+}
+
+/** Bytes the placement decision reads: every magic number sits in the first 16. */
+const SNIFF = 64;
+
+/** Hash one file in a single pass. Throws, before any network call, when the path is not a regular file. */
+export async function scanFile(path: string): Promise<ScannedFile> {
+  const info = await stat(path);
+  if (!info.isFile()) throw new Error(`Not a regular file: ${path}`);
+  const size = info.size;
+  const origin = createHash("sha256");
+  // Held in one object: the closures below assign to it.
+  const run: { fused: Hash | null; placement: ScanPlacement | null } = { fused: null, placement: null };
+  let head: Buffer | null = null;
+  let bytes = 0;
+  const start = (p: ScanPlacement) => {
+    run.placement = p;
+    // A second hasher runs over prefix and bytes when the prefix is not
+    // empty; with an empty prefix the origin hasher's own state is the fused state.
+    const prefix = getPlacement(p)?.scanPrefix?.(size) ?? null;
+    if (prefix !== null && prefix.length > 0) run.fused = createHash("sha256").update(prefix);
+  };
+  const feed = (chunk: Buffer) => {
+    origin.update(chunk);
+    if (run.fused !== null) run.fused.update(chunk);
+  };
+  for await (const raw of createReadStream(path)) {
+    const chunk = raw as Buffer;
+    if (run.placement === null) {
+      head = head === null ? chunk : Buffer.concat([head, chunk]);
+      if (head.length >= SNIFF) {
+        start(placementForBytes(new Uint8Array(head.subarray(0, SNIFF))));
+        feed(head);
+        head = null;
+      }
+    } else {
+      feed(chunk);
+    }
+    bytes += chunk.length;
+  }
+  if (run.placement === null) {
+    // A short file: decide from what there is, then hash it.
+    start(placementForBytes(new Uint8Array(head ?? Buffer.alloc(0))));
+    if (head !== null) feed(head);
+  }
+  const placement = run.placement as ScanPlacement;
+  const state = bytes !== size ? null : (run.fused ?? origin);
+  // When the origin hasher is the state its digest is taken from a copy, so it stays open.
+  const digest = state === origin ? origin.copy().digest() : origin.digest();
+  return {
+    path,
+    name: basename(path),
+    size,
+    digestB64: digest.toString("base64"),
+    originDigest: Uint8Array.from(digest),
+    placement,
+    state,
+  };
+}
+
+/**
+ * A member's fused digest for a slot: the open hasher, copied, finished with
+ * the placement's suffix for that slot's commitment. The hash of prefix,
+ * original, suffix is exactly the hash of the placement's own build, which
+ * a test pins.
+ */
+export function fusedDigestFor(file: ScannedFile, commitment: Uint8Array): Uint8Array {
+  if (file.state === null) throw new Error(`${file.path}: the file changed while it was read`);
+  const placement = getPlacement(file.placement);
+  if (placement?.frame === undefined) throw new Error(`placement ${file.placement} has no frame`);
+  const { suffix } = placement.frame({ originalSize: file.size, originDigest: file.originDigest, commitment });
+  return Uint8Array.from(file.state.copy().update(suffix).digest());
+}
+
+export interface Expansion {
+  /** Regular files in the order given; a directory contributes its files sorted by name, depth first. */
+  files: string[];
+  /** How many of the inputs were directories. */
+  directories: number;
+}
+
+/**
+ * Paths to files: a regular file is itself; a directory is every regular
+ * file under it, recursively, with hidden entries (names starting with a
+ * dot) and symbolic links left out. The same file twice is one file. A path
+ * that is missing or neither kind, or more than `limit` files in all, throws
+ * before any network call; the message names every path that failed.
+ */
+export async function expandPaths(paths: readonly string[], limit: number): Promise<Expansion> {
+  const files: string[] = [];
+  const seen = new Set<string>();
+  const failures: string[] = [];
+  let directories = 0;
+  const push = (p: string) => {
+    if (seen.has(p)) return;
+    seen.add(p);
+    files.push(p);
+    if (files.length > limit) throw new Error(`more than ${limit} files; BitGraph fewer at a time`);
+  };
+  const walk = async (dir: string): Promise<void> => {
+    const entries = (await readdir(dir, { withFileTypes: true }))
+      .filter((e) => !e.name.startsWith("."))
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory()) await walk(full);
+      else if (e.isFile()) push(full);
+    }
+  };
+  for (const p of paths) {
+    try {
+      const info = await stat(p);
+      if (info.isDirectory()) {
+        directories += 1;
+        await walk(p);
+      } else if (info.isFile()) {
+        push(p);
+      } else {
+        throw new Error("not a regular file or a directory");
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.startsWith("more than ")) throw err;
+      failures.push(`${p}: ${message}`);
+    }
+  }
+  if (failures.length > 0) {
+    throw new Error(`Could not read ${failures.length} path(s); nothing was BitGraphed.\n${failures.join("\n")}\nUse absolute paths to existing regular files or directories.`);
+  }
+  return { files, directories };
+}