@mikeargento/bitgraph-mcp 0.5.2 → 0.7.0

package/src/server.ts

@@ -19,24 +19,17 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { ServerNotification, ServerRequest } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { readFile } from "node:fs/promises";
-import { FuseError, MAX_SET_MEMBERS, builderFor, fuse, fuseSet, fusedNamesFor, type FuseSetMember, type FuseSetProgress } from "@mikeargento/bitgraph";
+import { FuseError, MAX_SET_MEMBERS, type FuseSetProgress } from "@mikeargento/bitgraph";
 import {
-  ApiError,
-  batchCheck,
-  configFromEnv,
-  getProofDetail,
-  indexSetMembers,
-  search,
-  type ApiConfig,
-} from "./api.js";
-import {
-  fromUrlSafeB64,
-  looksLikeDigest,
-  mapConcurrent,
-  sha256FileB64,
-  toUrlSafeB64,
-} from "./encoding.js";
+  ApiError, batchCheck, configFromEnv, getProofDetail, indexSetMembers, search, type ApiConfig,
+  fromUrlSafeB64, looksLikeDigest, mapConcurrent, sha256FileB64, toUrlSafeB64,
+  expandPaths, scanFile, type ScannedFile,
+  type CarrierWindowView,
+  classifyPath, fuseFilePipeline, fuseSetPipeline, MAX_LOADED_BYTES,
+  type CarrierRow, type FuseFileFn, type FuseSetFn, type FusedSummary, type SetSummary,
+  SLOT_TTL_SECONDS, beginTask, decodeTaskToken, sealTask, writeProofBeside,
+  type BitGraphProof, type ProofDetailResponse,
+} from "@mikeargento/bitgraph-sdk";
 import {
   capJson,
   positionOf,
@@ -48,11 +41,11 @@ import {
   type RecordOutcome,
   type SetOutcome,
 } from "./format.js";
-import { expandPaths, fusedDigestFor, scanFile, type ScannedFile } from "./scan.js";
-import { SLOT_TTL_SECONDS, TASK_INSTRUCTIONS, beginTask, decodeTaskToken, sealTask, writeProofBeside } from "./task.js";
-import type { BitGraphProof } from "./types.js";
+import { TASK_INSTRUCTIONS } from "./instructions.js";
+
+export type { FuseFileFn, FuseSetFn, FusedSummary, SetSummary } from "@mikeargento/bitgraph-sdk";
 
-export const SERVER_VERSION = "0.5.2";
+export const SERVER_VERSION = "0.7.0";
 
 const SCAN_CONCURRENCY = 4;
 /** Paths per call; a directory counts once and expands to its files. */
@@ -62,7 +55,6 @@ export const MAX_MEMBERS = 100_000;
 /** Files one check may cover after directories expand. */
 const MAX_CHECK_FILES = 10_000;
 /** A file whose length changed while it was read is fused from its bytes instead; above this it is left out rather than held in memory. */
-const MAX_LOADED_BYTES = 256 * 1024 * 1024;
 /** A single file up to this size is fused on its own, in memory, with its Frame; a larger one is a set of one, never held. */
 const MAX_SOLO_BYTES = 256 * 1024 * 1024;
 /** Rows the structured result lists in full; every fused row shares the set's position. */
@@ -71,42 +63,6 @@ export const ROW_CAP = 500;
 export const SET_INDEX_CHUNK = 2500;
 
 /** What one set yields, in the shape the tool reports; tests inject a stand-in. */
-export interface SetSummary {
-  set: "set/1" | "set/2";
-  proof: BitGraphProof;
-  /** Standard base64: the committed artifact's digest. */
-  artifactDigestB64: string;
-  count: number;
-  manifestEchoed: boolean;
-  recovered: boolean;
-  /** In the order the files were given. */
-  members: Array<{
-    index: number;
-    /** The row's ordinal in the committed artifact. */
-    manifestIndex: number;
-    placement: string;
-    originDigestB64: string;
-    artifactDigestB64: string;
-    /** set/2 only: the member's evidence, for the site's index. */
-    memberProof?: unknown;
-  }>;
-}
-export type FuseSetFn = (
-  files: readonly ScannedFile[],
-  config: ApiConfig,
-  opts: { set: "set/1" | "set/2"; onProgress?: (p: FuseSetProgress) => void }
-) => Promise<SetSummary>;
-
-/** What fusing one file on its own yields. */
-export interface FusedSummary {
-  proof: BitGraphProof;
-  frame: unknown;
-  placement: string;
-  artifactDigestB64: string;
-  originDigestB64: string;
-}
-export type FuseFileFn = (file: ScannedFile, config: ApiConfig) => Promise<FusedSummary>;
-
 export interface ServerDeps {
   /** The set pipeline; tests inject a stand-in. Default: the core package's fuseSet() against the configured site. */
   fuseSet?: FuseSetFn;
@@ -114,76 +70,6 @@ export interface ServerDeps {
   fuseFile?: FuseFileFn;
 }
 
-/**
- * A single file, the way a single drop on the site goes: the bytes in hand,
- * the placement chosen from them, one slot, the fused bytes built in memory
- * and hashed, committed under that exact slot, verified against the bytes,
- * and a Frame returned. The fused bytes are not kept.
- */
-async function fuseFileDefault(file: ScannedFile, config: ApiConfig): Promise<FusedSummary> {
-  const bytes = new Uint8Array(await readFile(file.path));
-  const placement = file.placement;
-  const { fusedName } = fusedNamesFor(file.name, placement);
-  const r = await fuse(builderFor(placement, bytes), {
-    placement,
-    original: bytes,
-    fusedFile: fusedName,
-    keepFused: false,
-    transport: { baseUrl: config.baseUrl, ...(config.apiKey ? { apiKey: config.apiKey } : {}) },
-  });
-  return {
-    proof: r.proof as unknown as BitGraphProof,
-    frame: r.frame,
-    placement,
-    artifactDigestB64: r.artifactDigestB64,
-    originDigestB64: r.originDigestB64 ?? file.digestB64,
-  };
-}
-
-/**
- * The default pipeline, the one the site's drop runs: one slot for the set,
- * every member a hashed member whose fused digest is finished from the
- * scan's open hasher with its placement's suffix for that slot, the set's
- * manifest (or, for a set/2, its root document) committed under the same
- * slot, and the returned proof verified against the committed artifact with
- * every member bound to it by digest. A file whose length changed during the
- * scan is a loaded member: read again when it is its turn, checked against
- * the scan's digest, fused in memory, hashed and released.
- */
-async function fuseSetDefault(
-  files: readonly ScannedFile[],
-  config: ApiConfig,
-  opts: { set: "set/1" | "set/2"; onProgress?: (p: FuseSetProgress) => void }
-): Promise<SetSummary> {
-  const members: FuseSetMember[] = files.map((f) =>
-    f.state !== null
-      ? { originDigest: f.originDigest, placement: f.placement, name: f.name, fusedDigest: ({ commitment }) => fusedDigestFor(f, commitment) }
-      : { load: async () => new Uint8Array(await readFile(f.path)), originDigest: f.originDigest, placement: f.placement, name: f.name }
-  );
-  const r = await fuseSet(members, {
-    set: opts.set,
-    keepFused: false,
-    ...(opts.onProgress !== undefined ? { onProgress: opts.onProgress } : {}),
-    transport: { baseUrl: config.baseUrl, ...(config.apiKey ? { apiKey: config.apiKey } : {}) },
-  });
-  return {
-    set: r.set,
-    proof: r.proof as unknown as BitGraphProof,
-    artifactDigestB64: r.artifactDigestB64,
-    count: r.members.length,
-    manifestEchoed: r.manifestEchoed,
-    recovered: r.recovered,
-    members: r.members.map((m) => ({
-      index: m.index,
-      manifestIndex: m.manifestIndex,
-      placement: m.placement,
-      originDigestB64: m.originDigestB64,
-      artifactDigestB64: m.artifactDigestB64,
-      ...(m.memberProof !== undefined ? { memberProof: m.memberProof } : {}),
-    })),
-  };
-}
-
 /** Hash the given paths (bounded concurrency). Throws before any network call. */
 async function hashPaths(paths: readonly string[]): Promise<string[]> {
   const failures: string[] = [];
@@ -323,8 +209,8 @@ async function flushIndex(config: ApiConfig, report: Report): Promise<{ written:
 }
 
 export function buildServer(deps: ServerDeps = {}): McpServer {
-  const fuseSetPipeline = deps.fuseSet ?? fuseSetDefault;
-  const fuseFilePipeline = deps.fuseFile ?? fuseFileDefault;
+  const runFuseSet = deps.fuseSet ?? fuseSetPipeline;
+  const runFuseFile = deps.fuseFile ?? fuseFilePipeline;
   const server = new McpServer(
     {
       name: "bitgraph-mcp-server",
@@ -334,6 +220,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
       instructions:
         "BitGraph gives a file's bytes a causal position in a public sequence bracketed by Ethereum anchors. bitgraph_record makes ONE BitGraph of everything in a call, files and folders alike: a single file is fused on its own; two or more become one set under one slot, one position, every file's new fused bytes listed by digest in the committed artifact. " +
         "Files are read on this machine and never uploaded or modified; the new bytes are virtual and never written. Recordings are permanent: only make BitGraphs of files the user asked for, and never generate content just to record it. bitgraph_check and bitgraph_get_proof are read-only. " +
+        "A BitGraphed file (one that carries its own proof, bitgraph-carrier/1) is recognized by its structure: bitgraph_check judges it offline from the proof inside and states the window, and bitgraph_record never re-mints it, because the envelope is not the recorded thing, the bytes inside are. " +
         "To do work INSIDE a BitGraph, call bitgraph_open BEFORE starting: it returns a position and its commitment; put the commitment string into the task, seal the task with bitgraph_commit within 120 seconds, then record the outputs with bitgraph_record. The task then could not have existed before the position's floor block, and the outputs sit after it.",
     }
   );
@@ -348,6 +235,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
         "Files are never modified and never uploaded: only digests, the committed artifact and slot records leave the machine. " +
         "Give file paths, directory paths, or both (absolute paths preferred): a directory is every regular file under it, recursively, with hidden entries and symbolic links left out. " +
         "Files already on record are NOT made again by default; they come back as 'on record' with their earliest position. A file can also hold a BitGraph its holder keeps, which no lookup sees. Pass again=true to make a new BitGraph regardless. " +
+        "A BitGraphed file (bitgraph-carrier/1, a file that carries its own proof) is never minted, with or without again: its carried proof is judged offline and reported, because the envelope is not the recorded thing, the bytes inside are. " +
         "Positions are permanent and the proof comes back to you to keep, so only BitGraph files the user asked to, and never generate content just to record it. " +
         "Returns one outcome per file: 'fused' (for a set, its row, one of N, and the set's position and proof page; for a single file, its own position and Frame), 'on record', or 'not fused' (with the reason). Keep the proof beside the files; BitGraph does not index it. " +
         "Use bitgraph_check instead when the user only wants to know whether files are on record.",
@@ -393,15 +281,18 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
           }
         }
 
-        // 2. The scan: one pass per file.
+        // 2. The scan: one pass per file. A BitGraphed file is set aside here,
+        //    judged from the proof it carries, and never enters the mint below.
         let scanned = 0;
         report(0, files.length, `hashing ${files.length} files`);
-        const scans = await mapConcurrent(files, SCAN_CONCURRENCY, async (p) => {
-          const s = await scanFile(p);
+        const classified = await mapConcurrent(files, SCAN_CONCURRENCY, async (p) => {
+          const c = await classifyPath(p);
           scanned += 1;
           report(scanned, files.length, `hashed ${scanned} of ${files.length}`);
-          return s;
+          return c;
         });
+        const scans = classified.filter((c): c is { kind: "plain"; file: ScannedFile } => c.kind === "plain").map((c) => c.file);
+        const carriers = classified.filter((c): c is CarrierRow => c.kind === "carrier");
 
         // 3. Unique by content; the first path names the member, every path is reported.
         const byDigest = new Map<string, { file: ScannedFile; paths: string[] }>();
@@ -412,14 +303,22 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
         }
         const unique = [...byDigest.keys()];
 
-        // 4. What is on record already.
+        // 4. What is on record already. A BitGraphed file is looked up by the
+        //    digest of its committed bytes, never by the envelope's.
         report(0, 1, "checking BitGraph's copy");
-        const checked = await batchCheck(config, unique.map(toUrlSafeB64));
+        const carrierInner = [...new Set(carriers.filter((c) => c.innerDigestB64 !== null).map((c) => c.innerDigestB64 as string))];
+        const lookups = [...new Set([...unique, ...carrierInner])];
+        const checked = lookups.length > 0 ? await batchCheck(config, lookups.map(toUrlSafeB64)) : { results: {} as Record<string, { proofs: Array<{ proof: BitGraphProof }> }> };
         const existing = new Map<string, Array<{ proof: BitGraphProof }>>();
         for (const d of unique) {
           const entry = checked.results[toUrlSafeB64(d)];
           if (entry && entry.proofs.length > 0) existing.set(d, entry.proofs);
         }
+        const carrierLedger = new Map<string, Array<{ proof: BitGraphProof }>>();
+        for (const d of carrierInner) {
+          const entry = checked.results[toUrlSafeB64(d)];
+          if (entry && entry.proofs.length > 0) carrierLedger.set(d, entry.proofs);
+        }
 
         // 5. The set: every fresh file (every file, with again), one call.
         const excluded = new Map<string, string>();
@@ -441,14 +340,14 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
           // One file, as a single drop on the site goes: its own slot, its own Frame.
           report(0, 1, "fusing");
           try {
-            solo = { ...(await fuseFilePipeline(one, config)), file: one };
+            solo = { ...(await runFuseFile(one, config)), file: one };
           } catch (err) {
             failure = setFailureText(err);
           }
         } else if (toMint.length > 0) {
           const kind: "set/1" | "set/2" = toMint.length > MAX_SET_MEMBERS ? "set/2" : "set/1";
           try {
-            made = await fuseSetPipeline(toMint, config, {
+            made = await runFuseSet(toMint, config, {
               set: kind,
               onProgress: (p) => report(p.done, p.total, `${PHASES[p.phase]} ${p.done} of ${p.total}`),
             });
@@ -494,7 +393,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
           const m = memberOf.get(digest);
           const prior = existing.get(digest);
           for (const path of entry.paths) {
-            const base = { path, digest: toUrlSafeB64(digest) };
+            const base = { path, digest: toUrlSafeB64(digest), ...(entry.file.c2pa ? { c2pa: true as const } : {}) };
             if (solo !== null && solo.file.digestB64 === digest) {
               const { counter, epoch } = positionOf(solo.proof);
               outcomes.push({
@@ -555,8 +454,36 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
             }
           }
         }
+        // 7b. BitGraphed files: judged from the proof inside, never minted.
+        for (const c of carriers) {
+          if (c.status !== "ok" || c.innerDigestB64 === null) {
+            outcomes.push({
+              path: c.path, digest: "", outcome: "not fused", artifact_digest: null, placement: null,
+              counter: null, epoch: null, member: null, member_count: null, total_positions: 0, proof_url: null,
+              error: c.reason ?? "unreadable BitGraphed file",
+            });
+            continue;
+          }
+          const inner = c.innerDigestB64;
+          const rows = carrierLedger.get(inner);
+          const extras = { ...(c.view ? { carrier: c.view } : {}), ...(c.c2pa ? { c2pa: true as const } : {}) };
+          if (rows !== undefined && rows.length > 0) {
+            const first = rows[0] as { proof: BitGraphProof; member?: { index: number; count: number } };
+            const { counter, epoch } = positionOf(first.proof);
+            outcomes.push({
+              path: c.path, digest: toUrlSafeB64(inner), outcome: "on record", artifact_digest: null, placement: null,
+              counter, epoch, member: first.member ? first.member.index + 1 : null, member_count: first.member ? first.member.count : null,
+              total_positions: rows.length, proof_url: proofUrl(config.baseUrl, inner), ...extras,
+            });
+          } else {
+            outcomes.push({
+              path: c.path, digest: toUrlSafeB64(inner), outcome: "carried", artifact_digest: null, placement: null,
+              counter: null, epoch: null, member: null, member_count: null, total_positions: 0, proof_url: null, ...extras,
+            });
+          }
+        }
         // Rows that need reading come first, so a cap drops fused rows, which all share one position.
-        const order = { "not fused": 0, "on record": 1, fused: 2 } as const;
+        const order = { "not fused": 0, "on record": 1, carried: 2, fused: 3 } as const;
         outcomes.sort((a, b) => order[a.outcome] - order[b.outcome]);
         const listed = outcomes.slice(0, ROW_CAP);
         const omitted = outcomes.length - listed.length;
@@ -565,6 +492,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
           directories: expanded.directories,
           fused: outcomes.filter((o) => o.outcome === "fused").length,
           on_record: outcomes.filter((o) => o.outcome === "on record").length,
+          carried: outcomes.filter((o) => o.outcome === "carried").length,
           not_fused: outcomes.filter((o) => o.outcome === "not fused").length,
         };
         const structured = {
@@ -690,6 +618,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
         "Check whether files or digests are on record in BitGraph's copy, without recording anything. " +
         `Accepts file paths and directory paths (every regular file under them, up to ${MAX_CHECK_FILES} in all; hashed locally, only digests are sent) and/or raw SHA-256 digests in standard or URL-safe base64. ` +
         "Returns, per item: on_record (the bytes are on record, as an exact recording, as the original a new file was made from, or as a member of a set), every position by counter, and the proof page URL. " +
+        "A BitGraphed file (bitgraph-carrier/1) is recognized by structure: the proof it carries is verified OFFLINE here (signatures, floor identity, block-header witnesses) and its verdict and window are reported, and the lookup uses the committed bytes inside, never the envelope. " +
         "Read-only. Use bitgraph_record to BitGraph files that turn out not to be on record.",
       inputSchema: {
         paths: z
@@ -714,11 +643,20 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
     async ({ paths, digests, response_format }) => {
       const config = configFromEnv();
       try {
-        const inputs: Array<{ label: string; standardDigest: string }> = [];
+        const inputs: Array<{ label: string; standardDigest: string; carrier?: CarrierWindowView; c2pa?: boolean; note?: string }> = [];
         if (paths && paths.length > 0) {
           const { files } = await expandPaths(paths, MAX_CHECK_FILES);
-          const hashed = await hashPaths(files);
-          hashed.forEach((d, i) => inputs.push({ label: files[i] as string, standardDigest: d }));
+          const classified = await mapConcurrent(files, SCAN_CONCURRENCY, classifyPath);
+          classified.forEach((c, i) => {
+            const label = files[i] as string;
+            if (c.kind === "plain") {
+              inputs.push({ label, standardDigest: c.file.digestB64, ...(c.file.c2pa ? { c2pa: true } : {}) });
+            } else if (c.status === "ok" && c.innerDigestB64 !== null) {
+              inputs.push({ label, standardDigest: c.innerDigestB64, ...(c.view ? { carrier: c.view } : {}), ...(c.c2pa ? { c2pa: true } : {}) });
+            } else {
+              inputs.push({ label, standardDigest: "", note: c.reason ?? "unreadable BitGraphed file" });
+            }
+          });
         }
         for (const d of digests ?? []) {
           const trimmed = d.trim();
@@ -736,23 +674,24 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
           return fail(`Error: ${inputs.length} items; check at most ${MAX_CHECK_FILES} at a time.`);
         }
 
-        const checked = await batchCheck(
-          config,
-          inputs.map((i) => toUrlSafeB64(i.standardDigest))
-        );
+        const lookable = [...new Set(inputs.filter((i) => i.standardDigest !== "").map((i) => toUrlSafeB64(i.standardDigest)))];
+        const checked = lookable.length > 0 ? await batchCheck(config, lookable) : { results: {} };
 
         const outcomes: CheckOutcome[] = inputs.map((input) => {
-          const entry = checked.results[toUrlSafeB64(input.standardDigest)];
+          const entry = input.standardDigest === "" ? undefined : checked.results[toUrlSafeB64(input.standardDigest)];
           const proofs = entry?.proofs ?? [];
           const positions = proofs.map((p) => ({ ...positionOf(p.proof), ...(p.member ? { member: p.member } : {}) }));
           return {
             input: input.label,
-            digest: toUrlSafeB64(input.standardDigest),
+            digest: input.standardDigest === "" ? "" : toUrlSafeB64(input.standardDigest),
             // A fused descendant that names these bytes as origin is not a recording of them.
             // The original and the new file made from it find the same proof.
             on_record: proofs.length > 0,
             positions,
             proof_url: proofs.length > 0 ? proofUrl(config.baseUrl, input.standardDigest) : null,
+            ...(input.carrier ? { carrier: input.carrier } : {}),
+            ...(input.c2pa ? { c2pa: true } : {}),
+            ...(input.note !== undefined ? { note: input.note } : {}),
           };
         });
 
@@ -778,7 +717,8 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
       title: "Get a BitGraph proof",
       description:
         "Fetch a BitGraph proof and its context: causal position, every position the same bytes occupy, the row a set member holds (one of N), and the two-sided Ethereum anchor window " +
-        "('BitGraphed between X and Y'). Look up by digest (base64, either form), by BitGraph number (e.g. '4523' or '#4,523', current epoch), or by file path (hashed locally). " +
+        "(after the floor block's time; before the ANCHORING of the later block, a position bound, never that block's mine time). Look up by digest (base64, either form), by BitGraph number (e.g. '4523' or '#4,523', current epoch), or by file path (hashed locally). " +
+        "A path to a BitGraphed file (bitgraph-carrier/1) looks up the committed bytes inside it, and when the ledger has no row the proof the file carries answers offline. " +
         "Exactly one of digest, number, or path is required. Read-only. " +
         "markdown returns a summary; json returns the full proof object with positions and anchor window.",
       inputSchema: {
@@ -822,6 +762,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
 
         let urlSafeDigest: string;
         let selCounter = counter;
+        let carrierRow: CarrierRow | null = null;
         if (number !== undefined) {
           const result = await search(config, number);
           if (!result.found || result.digest === undefined) {
@@ -832,8 +773,16 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
           urlSafeDigest = result.digest;
           if (selCounter === undefined && result.counter != null) selCounter = result.counter;
         } else if (path !== undefined) {
-          const hashed = await hashPaths([path]);
-          urlSafeDigest = toUrlSafeB64(hashed[0] as string);
+          const c = await classifyPath(path);
+          if (c.kind === "carrier") {
+            if (c.status !== "ok" || c.innerDigestB64 === null) {
+              return fail(`Error: ${c.reason ?? "unreadable BitGraphed file"}`);
+            }
+            carrierRow = c;
+            urlSafeDigest = toUrlSafeB64(c.innerDigestB64);
+          } else {
+            urlSafeDigest = toUrlSafeB64(c.file.digestB64);
+          }
         } else {
           const trimmed = (digest as string).trim();
           if (!looksLikeDigest(trimmed)) {
@@ -848,16 +797,41 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
         const selEpoch = epoch !== undefined ? toUrlSafeB64(fromUrlSafeB64(epoch)) : undefined;
         const detail = await getProofDetail(config, urlSafeDigest, selCounter, selEpoch);
         if (detail.proofs.length === 0) {
+          if (carrierRow !== null && carrierRow.view !== null && carrierRow.proof !== null) {
+            // The ledger has no row, and the file answers for itself.
+            const v = carrierRow.view;
+            const synth: ProofDetailResponse = {
+              proofs: [{ proof: carrierRow.proof as BitGraphProof }],
+              positions: [],
+              causalWindow: {
+                anchorBefore: v.not_before
+                  ? { blockNumber: v.not_before.block, blockHash: v.not_before.hash, etherscanUrl: `https://etherscan.io/block/${v.not_before.block}`, blockTime: v.not_before.time }
+                  : null,
+                anchorAfter: v.not_after
+                  ? { blockNumber: v.not_after.block, blockHash: v.not_after.hash, etherscanUrl: `https://etherscan.io/block/${v.not_after.block}`, blockTime: v.not_after.time }
+                  : null,
+              },
+            };
+            const offlineNote = `Judged offline from the proof this BitGraphed file carries: carried proof ${v.verdict}${v.not_after === null ? ", closing anchor NOT FETCHED" : ""}. Not found in this ledger.`;
+            const structured = { ...synth, carrier: v } as unknown as Record<string, unknown>;
+            if (response_format === "json") return ok(capJson(structured).text, structured);
+            return ok(`${renderProofMarkdown(synth, config.baseUrl)}\n\n${offlineNote}`, structured);
+          }
           return fail(
             `Not on record: no proof exists for digest ${urlSafeDigest}. Use bitgraph_record to make a BitGraph of the file.`
           );
         }
 
         if (response_format === "json") {
-          const capped = capJson(detail);
-          return ok(capped.text, detail as unknown as Record<string, unknown>);
+          const withCarrier = carrierRow?.view ? ({ ...detail, carrier: carrierRow.view } as unknown) : detail;
+          const capped = capJson(withCarrier);
+          return ok(capped.text, withCarrier as Record<string, unknown>);
         }
-        return ok(renderProofMarkdown(detail, config.baseUrl), detail as unknown as Record<string, unknown>);
+        const md = renderProofMarkdown(detail, config.baseUrl);
+        const carrierNote = carrierRow?.view
+          ? `\n\nThis file carries its own proof (carried proof ${carrierRow.view.verdict}, judged offline).`
+          : "";
+        return ok(`${md}${carrierNote}`, detail as unknown as Record<string, unknown>);
       } catch (err) {
         return fail(errorText(err));
       }

package/src/__tests__/encoding.test.ts

@@ -1,64 +0,0 @@
-// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
-
-import { test } from "node:test";
-import { strict as assert } from "node:assert";
-import { createHash } from "node:crypto";
-import { writeFile, mkdtemp } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  fromUrlSafeB64,
-  looksLikeDigest,
-  mapConcurrent,
-  sha256FileB64,
-  toUrlSafeB64,
-} from "../encoding.js";
-
-// A real 32-byte digest with + and / to exercise both substitutions.
-const STANDARD = createHash("sha256").update("bitgraph").digest("base64");
-
-test("url-safe round trip preserves the digest", () => {
-  const safe = toUrlSafeB64(STANDARD);
-  assert.ok(!safe.includes("+") && !safe.includes("/") && !safe.includes("="));
-  assert.equal(fromUrlSafeB64(safe), STANDARD);
-});
-
-test("fromUrlSafeB64 is a no-op on standard base64", () => {
-  assert.equal(fromUrlSafeB64(STANDARD), STANDARD);
-});
-
-test("looksLikeDigest accepts both forms, rejects junk", () => {
-  assert.ok(looksLikeDigest(STANDARD));
-  assert.ok(looksLikeDigest(toUrlSafeB64(STANDARD)));
-  assert.ok(!looksLikeDigest("not-a-digest"));
-  assert.ok(!looksLikeDigest(""));
-  assert.ok(!looksLikeDigest(Buffer.alloc(16).toString("base64"))); // 16 bytes, not 32
-});
-
-test("sha256FileB64 matches crypto over the same bytes", async () => {
-  const dir = await mkdtemp(join(tmpdir(), "bitgraph-mcp-"));
-  const file = join(dir, "sample.bin");
-  const bytes = Buffer.from("BitGraph proves causal ordering.\n");
-  await writeFile(file, bytes);
-  const expected = createHash("sha256").update(bytes).digest("base64");
-  assert.equal(await sha256FileB64(file), expected);
-});
-
-test("sha256FileB64 rejects directories and missing files", async () => {
-  await assert.rejects(() => sha256FileB64(tmpdir()), /Not a regular file/);
-  await assert.rejects(() => sha256FileB64(join(tmpdir(), "definitely-missing-9x7")));
-});
-
-test("mapConcurrent preserves order and honors the limit", async () => {
-  let inFlight = 0;
-  let peak = 0;
-  const out = await mapConcurrent([1, 2, 3, 4, 5, 6, 7, 8], 3, async (n) => {
-    inFlight += 1;
-    peak = Math.max(peak, inFlight);
-    await new Promise((r) => setTimeout(r, 5));
-    inFlight -= 1;
-    return n * 2;
-  });
-  assert.deepEqual(out, [2, 4, 6, 8, 10, 12, 14, 16]);
-  assert.ok(peak <= 3, `peak concurrency ${peak} exceeded 3`);
-});

package/src/__tests__/scan.test.ts

@@ -1,80 +0,0 @@
-// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
-
-/**
- * The scan's two promises: the digest is the file's own, and a state
- * finished with the placement's suffix for a slot is the hash of the
- * placement's own build for that slot. Both are pinned across sizes on both
- * sides of every boundary that matters (the 64-byte sniff, the tar block,
- * the 64 KB stream chunk) for both placements the scan makes.
- */
-
-import { test, before } from "node:test";
-import { strict as assert } from "node:assert";
-import { createHash, randomBytes } from "node:crypto";
-import { mkdtemp, mkdir, symlink, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { placementForBytes } from "@mikeargento/bitgraph";
-import { getPlacement } from "@mikeargento/bitgraph-verify";
-import { expandPaths, fusedDigestFor, scanFile } from "../scan.js";
-
-let root = "";
-before(async () => {
-  root = await mkdtemp(join(tmpdir(), "bitgraph-mcp-scan-"));
-});
-
-const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-const SIZES = [0, 1, 8, 63, 64, 65, 511, 512, 513, 1024, 65_535, 65_536, 65_537, 200_000];
-
-test("a scan's digest is the file's own and its state finishes to the placement's own build", async () => {
-  let checked = 0;
-  for (const size of SIZES) {
-    for (const kind of ["png", "txt"] as const) {
-      const lead = kind === "png" ? PNG : Buffer.from("txt:");
-      const bytes = Buffer.concat([lead, randomBytes(Math.max(0, size - lead.length))]).subarray(0, size);
-      const path = join(root, `${kind}-${size}.bin`);
-      await writeFile(path, bytes);
-      const s = await scanFile(path);
-      assert.equal(s.size, size);
-      assert.equal(s.digestB64, createHash("sha256").update(bytes).digest("base64"), `${kind} ${size}: digest`);
-      assert.equal(s.placement, placementForBytes(new Uint8Array(bytes)), `${kind} ${size}: the core's own placement choice`);
-      assert.ok(s.state !== null, "a file that did not change keeps its state");
-      const placement = getPlacement(s.placement);
-      if (placement === undefined) throw new Error("placement missing");
-      // Two slots, both finished from the same saved state: the copy leaves the state intact.
-      for (const commitment of [randomBytes(32), randomBytes(32)]) {
-        const built = placement.build({ original: new Uint8Array(bytes), originDigest: s.originDigest, commitment: new Uint8Array(commitment) });
-        const expected = createHash("sha256").update(built).digest();
-        assert.deepEqual(Buffer.from(fusedDigestFor(s, new Uint8Array(commitment))), expected, `${kind} ${size}: state finished == sha256(build)`);
-        checked += 1;
-      }
-    }
-  }
-  assert.equal(checked, SIZES.length * 4);
-});
-
-test("expandPaths: files, directories, hidden entries, links, duplicates, limits, missing paths", async () => {
-  const lone = join(root, "lone.txt");
-  await writeFile(lone, "lone");
-  const dir = join(root, "tree");
-  await mkdir(join(dir, "sub", ".secret"), { recursive: true });
-  await writeFile(join(dir, "a.txt"), "a");
-  await writeFile(join(dir, ".DS_Store"), "junk");
-  await writeFile(join(dir, "sub", "b.txt"), "b");
-  await writeFile(join(dir, "sub", ".secret", "c.txt"), "c");
-  await symlink(join(dir, "a.txt"), join(dir, "link.txt"));
-
-  const e = await expandPaths([lone, dir], 100);
-  assert.deepEqual(e.files, [lone, join(dir, "a.txt"), join(dir, "sub", "b.txt")]);
-  assert.equal(e.directories, 1);
-
-  const twice = await expandPaths([lone, lone, dir, join(dir, "a.txt")], 100);
-  assert.deepEqual(twice.files, [lone, join(dir, "a.txt"), join(dir, "sub", "b.txt")], "the same file twice is one file");
-
-  await assert.rejects(expandPaths([dir], 1), /more than 1 files/);
-  await assert.rejects(expandPaths([lone, join(root, "missing.txt")], 100), (err: Error) => {
-    assert.ok(err.message.includes("nothing was BitGraphed"));
-    assert.ok(err.message.includes(join(root, "missing.txt")));
-    return true;
-  });
-});