@mikeargento/bitgraph-mcp 0.5.2 → 0.7.0

package/src/__tests__/carrier.test.ts

@@ -0,0 +1,271 @@
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
+
+/**
+ * BitGraphed files through the MCP tools, end to end: a real client over an
+ * in-memory transport, a mock bitgraph.ing, and REAL carriers built from the
+ * verify package's fixture material (real proofs, real anchors, real block
+ * headers; nothing minted, no network). The two rules under test:
+ *
+ *   1. The lookups use the digest of the COMMITTED bytes inside, never the
+ *      envelope's, and the carried proof is judged offline (verdict, window).
+ *   2. bitgraph_record NEVER mints carrier bytes: the envelope is not the
+ *      recorded thing. The fake pipelines fail the test if a carrier reaches
+ *      them.
+ */
+
+import { test, before, after } from "node:test";
+import { strict as assert } from "node:assert";
+import { createHash } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import { readFileSync } from "node:fs";
+import { writeFile, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import {
+  buildCarrier,
+  type CarrierPayload,
+  type CarrierProof,
+  type CarrierWitness,
+} from "@mikeargento/bitgraph-verify";
+import { buildServer, type FuseFileFn, type FuseSetFn } from "../server.js";
+import { toUrlSafeB64 } from "@mikeargento/bitgraph-sdk";
+import { sniffC2paBytes, scanFile } from "@mikeargento/bitgraph-sdk";
+
+const fixtures = fileURLToPath(new URL("../../../verify/src/__tests__/fixtures/carrier/", import.meta.url));
+const readJson = <T>(name: string): T => JSON.parse(readFileSync(join(fixtures, name), "utf-8")) as T;
+
+let mock: Server;
+let completePath = ""; // demo2: floor + ceiling inside
+let undevPath = ""; // demo1: floor inside, ceiling unfetched
+let corruptPath = ""; // demo2 carrier with a broken payload byte
+let plainPath = ""; // an ordinary file that should still mint
+let c2paPath = ""; // an ordinary file carrying a synthetic C2PA marker
+let innerDigest2 = ""; // standard b64 of demo2's committed bytes
+let innerDigest1 = "";
+const EPOCH = createHash("sha256").update("carrier-epoch").digest("base64");
+
+before(async () => {
+  const root = await mkdtemp(join(tmpdir(), "bitgraph-mcp-carrier-"));
+
+  const demo2 = new Uint8Array(readFileSync(join(fixtures, "demo2.txt")));
+  const demo1 = new Uint8Array(readFileSync(join(fixtures, "demo1.txt")));
+  innerDigest2 = createHash("sha256").update(demo2).digest("base64");
+  innerDigest1 = createHash("sha256").update(demo1).digest("base64");
+
+  const complete: CarrierPayload = {
+    carrier: "bitgraph-carrier/1",
+    proof: readJson<CarrierProof>("demo2.proof.json"),
+    floor: { status: "present", anchor: readJson<CarrierProof>("floor2.anchor.json"), witness: readJson<CarrierWitness>("floor2.witness.json") },
+    ceiling: { status: "present", basis: "counter-order", anchor: readJson<CarrierProof>("ceiling2.anchor.json"), witness: readJson<CarrierWitness>("ceiling2.witness.json") },
+  };
+  const undeveloped: CarrierPayload = {
+    carrier: "bitgraph-carrier/1",
+    proof: readJson<CarrierProof>("demo1.proof.json"),
+    floor: { status: "present", anchor: readJson<CarrierProof>("floor1.anchor.json"), witness: readJson<CarrierWitness>("floor1.witness.json") },
+    ceiling: { status: "unfetched" },
+  };
+
+  completePath = join(root, "photo.bitgraph.txt");
+  await writeFile(completePath, buildCarrier(demo2, complete));
+  undevPath = join(root, "doc.bitgraph.txt");
+  await writeFile(undevPath, buildCarrier(demo1, undeveloped));
+
+  // Corrupt: the frame intact (tail magic still matches), one byte of the
+  // JSON payload broken, so the block is found but does not parse.
+  const corrupt = Buffer.from(buildCarrier(demo2, complete));
+  corrupt[demo2.length + 12] = 0x58; // the payload's first byte, "{" -> "X"
+  corruptPath = join(root, "broken.bitgraph.txt");
+  await writeFile(corruptPath, corrupt);
+
+  plainPath = join(root, "fresh.txt");
+  await writeFile(plainPath, "fresh bytes that should mint");
+
+  // A JUMBF description box shape: "jumd", a 16-byte type, a toggle, the "c2pa" label.
+  const c2pa = Buffer.concat([
+    Buffer.from("leading bytes "),
+    Buffer.from("jumd"),
+    Buffer.alloc(17, 3),
+    Buffer.from("c2pa\0and the rest of the file"),
+  ]);
+  c2paPath = join(root, "credentialed.bin");
+  await writeFile(c2paPath, c2pa);
+
+  mock = createServer((req, res) => {
+    let raw = "";
+    req.on("data", (d) => (raw += d));
+    req.on("end", () => {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      const body = raw.length > 0 ? (JSON.parse(raw) as unknown) : null;
+      const send = (status: number, payload: unknown) => {
+        res.writeHead(status, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(payload));
+      };
+      if (url.pathname === "/api/proofs/batch") {
+        const digests = (body as { digests: string[] }).digests;
+        const results: Record<string, { proofs: Array<{ proof: unknown; member?: unknown }> }> = {};
+        for (const d of digests) {
+          // Only demo2's COMMITTED bytes are in this ledger; the envelope digests never are.
+          results[d] =
+            d === toUrlSafeB64(innerDigest2)
+              ? { proofs: [{ proof: { artifact: { digestB64: innerDigest2 }, commit: { counter: "2874", epochId: EPOCH } } }] }
+              : { proofs: [] };
+        }
+        send(200, { results });
+      } else if (url.pathname.startsWith("/api/proofs/digest/")) {
+        const digest = decodeURIComponent(url.pathname.split("/").pop() ?? "");
+        if (digest === toUrlSafeB64(innerDigest2)) {
+          send(200, {
+            proofs: [{ proof: { artifact: { digestB64: innerDigest2 }, commit: { counter: "2874", epochId: EPOCH } } }],
+            positions: [{ counter: "2874", epoch: toUrlSafeB64(EPOCH), lowerTime: null, upperTime: null }],
+            causalWindow: null,
+          });
+        } else {
+          send(200, { proofs: [] });
+        }
+      } else {
+        send(404, { error: `unexpected ${url.pathname}` });
+      }
+    });
+  });
+  await new Promise<void>((resolve) => mock.listen(0, "127.0.0.1", resolve));
+  const address = mock.address();
+  if (address === null || typeof address === "string") throw new Error("no port");
+  process.env["BITGRAPH_API_URL"] = `http://127.0.0.1:${address.port}`;
+  process.env["BITGRAPH_API_KEY"] = "test-key-123";
+});
+
+after(() => {
+  mock.close();
+  delete process.env["BITGRAPH_API_URL"];
+  delete process.env["BITGRAPH_API_KEY"];
+});
+
+/** The pipelines fail the test when carrier bytes reach them. */
+const fusedNames: string[] = [];
+const guardFuseFile: FuseFileFn = async (file) => {
+  assert.ok(!file.name.includes(".bitgraph."), `a BitGraphed file reached the mint: ${file.name}`);
+  fusedNames.push(file.name);
+  const artifactDigestB64 = createHash("sha256").update("fused:" + file.digestB64).digest("base64");
+  return {
+    proof: { version: "bitgraph/1", artifact: { digestB64: artifactDigestB64 }, commit: { counter: "500", epochId: EPOCH } },
+    frame: { type: "bitgraph-fuse/1" },
+    placement: file.placement,
+    artifactDigestB64,
+    originDigestB64: file.digestB64,
+  };
+};
+const guardFuseSet: FuseSetFn = async (files) => {
+  for (const f of files) assert.ok(!f.name.includes(".bitgraph."), `a BitGraphed file reached the set mint: ${f.name}`);
+  throw new Error("no set expected in these tests");
+};
+
+async function connectedClient(): Promise<Client> {
+  const server = buildServer({ fuseSet: guardFuseSet, fuseFile: guardFuseFile });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: "test-client", version: "0.0.0" });
+  await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
+  return client;
+}
+
+const textOf = (result: unknown): string => ((result as { content: Array<{ text: string }> }).content[0] as { text: string }).text;
+const structuredOf = <T>(result: unknown): T => (result as { structuredContent: T }).structuredContent;
+
+test("check: a BitGraphed file is judged offline and looked up by its committed bytes", async () => {
+  const client = await connectedClient();
+  const result = await client.callTool({ name: "bitgraph_check", arguments: { paths: [completePath, undevPath, corruptPath, c2paPath] } });
+  const text = textOf(result);
+  const { results } = structuredOf<{ results: Array<Record<string, unknown>> }>(result);
+
+  const complete = results.find((r) => r["input"] === completePath) as Record<string, unknown>;
+  assert.equal(complete["on_record"], true);
+  assert.equal(complete["digest"], toUrlSafeB64(innerDigest2), "the lookup digest is the committed bytes', not the envelope's");
+  const view = complete["carrier"] as { verdict: string; not_before: { block: number }; not_after: { block: number } };
+  assert.equal(view.verdict, "TRUE");
+  assert.ok(view.not_before.block > 0 && view.not_after.block > view.not_before.block);
+
+  const undev = results.find((r) => r["input"] === undevPath) as Record<string, unknown>;
+  assert.equal(undev["on_record"], false);
+  const undevView = undev["carrier"] as { verdict: string; not_after: unknown; ceiling: string };
+  assert.equal(undevView.verdict, "TRUE");
+  assert.equal(undevView.not_after, null);
+  assert.equal(undevView.ceiling, "unfetched");
+  assert.ok(text.includes("not in this ledger"), "a foreign carrier is stated, not called unrecorded");
+  assert.ok(text.includes("NOT FETCHED"), "an absent ceiling is stated in those words");
+
+  const corrupt = results.find((r) => r["input"] === corruptPath) as Record<string, unknown>;
+  assert.equal(corrupt["on_record"], false);
+  assert.ok(String(corrupt["note"]).includes("unreadable"), "a corrupt block is a stated condition");
+  assert.ok(text.includes("not judged"), "a corrupt carrier is not judged, not 'not on record'");
+
+  const credentialed = results.find((r) => r["input"] === c2paPath) as Record<string, unknown>;
+  assert.equal(credentialed["c2pa"], true);
+  assert.ok(text.includes("Content Credentials (C2PA) detected"));
+});
+
+test("record: carrier bytes never mint; the plain file still does", async () => {
+  fusedNames.length = 0;
+  const client = await connectedClient();
+  const result = await client.callTool({ name: "bitgraph_record", arguments: { paths: [completePath, undevPath, plainPath] } });
+  const text = textOf(result);
+  const { summary, results } = structuredOf<{ summary: Record<string, number>; results: Array<Record<string, unknown>> }>(result);
+
+  assert.deepEqual(fusedNames, ["fresh.txt"], "exactly the plain file reached the mint");
+  assert.equal(summary["fused"], 1);
+  assert.equal(summary["on_record"], 1, "the ledger-confirmed carrier reports as on record");
+  assert.equal(summary["carried"], 1, "the foreign carrier reports as carried, nothing minted");
+  assert.equal(summary["not_fused"], 0);
+
+  const onRecord = results.find((r) => r["outcome"] === "on record") as Record<string, unknown>;
+  assert.equal(onRecord["digest"], toUrlSafeB64(innerDigest2));
+  assert.equal((onRecord["carrier"] as { verdict: string }).verdict, "TRUE");
+
+  const carried = results.find((r) => r["outcome"] === "carried") as Record<string, unknown>;
+  assert.equal(carried["digest"], toUrlSafeB64(innerDigest1));
+  assert.ok(text.includes("nothing minted"), "the markdown states the envelope rule");
+});
+
+test("record: a corrupt carrier is refused loudly and never minted", async () => {
+  fusedNames.length = 0;
+  const client = await connectedClient();
+  const result = await client.callTool({ name: "bitgraph_record", arguments: { paths: [corruptPath] } });
+  assert.equal((result as { isError?: boolean }).isError, true);
+  assert.deepEqual(fusedNames, [], "nothing reached the mint");
+  assert.ok(textOf(result).includes("unreadable"), "the reason names the corrupt block");
+});
+
+test("get_proof: a path to a foreign BitGraphed file answers offline from the proof inside", async () => {
+  const client = await connectedClient();
+  const result = await client.callTool({ name: "bitgraph_get_proof", arguments: { path: undevPath } });
+  const text = textOf(result);
+  assert.ok(text.includes("Judged offline from the proof this BitGraphed file carries"), text);
+  assert.ok(text.includes("carried proof TRUE"));
+  assert.ok(text.includes("NOT FETCHED"));
+});
+
+test("get_proof: a ledger-known BitGraphed file uses the ledger and states the carried verdict", async () => {
+  const client = await connectedClient();
+  const result = await client.callTool({ name: "bitgraph_get_proof", arguments: { path: completePath } });
+  const text = textOf(result);
+  assert.ok(text.includes("#2874"), text);
+  assert.ok(text.includes("carries its own proof (carried proof TRUE"), text);
+});
+
+test("c2pa sniff: the pair must be jumd then c2pa, near, in that order", async () => {
+  assert.equal(sniffC2paBytes(Buffer.concat([Buffer.from("jumd"), Buffer.alloc(17), Buffer.from("c2pa")])), true);
+  assert.equal(sniffC2paBytes(Buffer.from("c2pa then jumd the wrong way round")), false);
+  assert.equal(sniffC2paBytes(Buffer.from("jumd alone")), false);
+  assert.equal(sniffC2paBytes(Buffer.concat([Buffer.from("jumd"), Buffer.alloc(200), Buffer.from("c2pa")])), false, "too far apart");
+  // Streaming: the pair split across a 64 KiB read boundary is still seen.
+  const size = 64 * 1024;
+  const split = Buffer.alloc(size + 40);
+  Buffer.from("jumd").copy(split, size - 2);
+  Buffer.from("c2pa").copy(split, size + 19);
+  const root = await mkdtemp(join(tmpdir(), "bitgraph-mcp-c2pa-"));
+  const p = join(root, "split.bin");
+  await writeFile(p, split);
+  const scanned = await scanFile(p);
+  assert.equal(scanned.c2pa, true, "a pair straddling the chunk boundary is detected");
+});

package/src/__tests__/format.test.ts

@@ -3,9 +3,9 @@
 import { test } from "node:test";
 import { strict as assert } from "node:assert";
 import { createHash } from "node:crypto";
-import { toUrlSafeB64 } from "../encoding.js";
+import { toUrlSafeB64 } from "@mikeargento/bitgraph-sdk";
 import { capJson, proofUrl, renderProofMarkdown, renderRecordMarkdown } from "../format.js";
-import type { ProofDetailResponse } from "../types.js";
+import type { ProofDetailResponse } from "@mikeargento/bitgraph-sdk";
 
 const DIGEST = createHash("sha256").update("bitgraph").digest("base64");
 const EPOCH = createHash("sha256").update("epoch").digest("base64");
@@ -62,7 +62,7 @@ test("record markdown names the set once and its members by row", () => {
   assert.ok(waiting.includes("The set proof beside the originals is the record either way."), waiting);
 });
 
-test("proof markdown states the window as between lower and upper", () => {
+test("proof markdown states the floor in time and the ceiling in position", () => {
   const detail: ProofDetailResponse = {
     proofs: [{ proof: { artifact: { digestB64: DIGEST }, commit: { counter: "42", epochId: EPOCH } } }],
     positions: [{ counter: "42", epoch: toUrlSafeB64(EPOCH), lowerTime: null, upperTime: null }],
@@ -73,7 +73,7 @@ test("proof markdown states the window as between lower and upper", () => {
   };
   const md = renderProofMarkdown(detail, "https://bitgraph.ing");
   assert.ok(
-    md.includes("BitGraphed between 2026-07-01T00:00:00.000Z (Ethereum block 100) and 2026-07-01T00:00:12.000Z (block 101)"),
+    md.includes("BitGraphed after 2026-07-01T00:00:00.000Z (Ethereum block 100), and before the anchoring of block 101 (that block mined 2026-07-01T00:00:12.000Z)."),
     md
   );
   assert.ok(md.includes("# BitGraph #42"));

package/src/__tests__/proof-beside.test.ts

@@ -3,7 +3,7 @@ import * as assert from "node:assert/strict";
 import { mkdtempSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { writeProofBeside } from "../task.js";
+import { writeProofBeside } from "@mikeargento/bitgraph-sdk";
 
 describe("the server writes the task proof beside the sealed file", () => {
   test("named after the file, whole, and never over an existing one", async () => {

package/src/__tests__/tools.test.ts

@@ -18,7 +18,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { FuseError } from "@mikeargento/bitgraph";
 import { buildServer, pendingIndexCount, ROW_CAP, SET_INDEX_CHUNK, type FuseFileFn, type FuseSetFn } from "../server.js";
-import { toUrlSafeB64 } from "../encoding.js";
+import { toUrlSafeB64 } from "@mikeargento/bitgraph-sdk";
 
 interface Recorded {
   method: string;
@@ -253,7 +253,7 @@ test("record makes ONE set of the fresh files and leaves on-record ones alone",
   const batchBody = batch.body as { digests: string[] };
   assert.ok(batchBody.digests.every((d) => !d.includes("+") && !d.includes("=")), "check uses url-safe digests");
   const structured = result.structuredContent as RecordStructured;
-  assert.deepEqual(structured.summary, { files: 3, directories: 0, fused: 2, on_record: 1, not_fused: 0 });
+  assert.deepEqual(structured.summary, { files: 3, directories: 0, fused: 2, on_record: 1, carried: 0, not_fused: 0 });
   assert.ok(structured.set, "the set is reported");
   assert.equal(structured.set?.count, 2);
   assert.ok(structured.set?.proof_url.includes("/proof/") && structured.set?.proof_url.includes("counter="), "the set's proof page is pinned to its position");
@@ -311,7 +311,7 @@ test("a directory is its regular files, hidden entries and links left out", asyn
   assert.ok(!result.isError, JSON.stringify(result.content));
   assert.deepEqual(setCalls[0]?.names, ["a1.txt", "a2.txt"]);
   const structured = result.structuredContent as RecordStructured;
-  assert.deepEqual(structured.summary, { files: 2, directories: 1, fused: 2, on_record: 0, not_fused: 0 });
+  assert.deepEqual(structured.summary, { files: 2, directories: 1, fused: 2, on_record: 0, carried: 0, not_fused: 0 });
   assert.equal(structured.set?.count, 2);
 });
 
@@ -414,7 +414,7 @@ test("a set failure labels every attempted file 'not fused', never 'on record'",
     const structured = result.structuredContent as RecordStructured;
     assert.equal(structured.set, null);
     assert.ok(structured.results.every((r) => r.outcome === "not fused" && r.proof_url === null));
-    assert.deepEqual(structured.summary, { files: 2, directories: 0, fused: 0, on_record: 0, not_fused: 2 });
+    assert.deepEqual(structured.summary, { files: 2, directories: 0, fused: 0, on_record: 0, carried: 0, not_fused: 2 });
   } finally {
     fuseMode = "ok";
   }
@@ -485,7 +485,8 @@ test("get_proof by number resolves through search and renders the window", async
   assert.ok(!result.isError, JSON.stringify(result.content));
   const text = textOf(result);
   assert.ok(text.includes("# BitGraph #10"));
-  assert.ok(text.includes("BitGraphed between 2026-07-01T00:00:00.000Z"));
+  assert.ok(text.includes("BitGraphed after 2026-07-01T00:00:00.000Z"));
+  assert.ok(text.includes("before the anchoring of block 2"), "the ceiling is stated in position, never as the block's mine time");
   assert.ok(text.includes("Causal positions (2)"));
   assert.ok(text.includes("/proof/"), "includes the proof page url");
 });

package/src/format.ts

@@ -4,12 +4,14 @@
  * @mikeargento/bitgraph-mcp: output shaping.
  *
  * Markdown for human-facing summaries, JSON for complete structured data.
- * Time statements come from the Ethereum anchor bracket ("BitGraphed between
- * X and Y"), never from advisory clock fields.
+ * Time statements come from the Ethereum anchor bracket, never from advisory
+ * clock fields, and they keep the canon's units: the floor is temporal
+ * ("after T", cryptographic), the ceiling is POSITIONAL ("before the
+ * anchoring of block M"), because an anchor is built after the block it
+ * carries, so a block's mine time is never an upper clock bound.
  */
 
-import { toUrlSafeB64 } from "./encoding.js";
-import type { BitGraphProof, PositionView, ProofDetailResponse, SetMemberView } from "./types.js";
+import { toUrlSafeB64, carrierLine, type CarrierWindowView, type BitGraphProof, type PositionView, type ProofDetailResponse, type SetMemberView } from "@mikeargento/bitgraph-sdk";
 
 export const CHARACTER_LIMIT = 25_000;
 /** Rows per group a markdown summary lists before "and N more". */
@@ -38,13 +40,19 @@ export function proofUrl(
  * 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.
+ * bytes that have no proof. "carried": the file is a BitGraphed file, its
+ * proof travels inside it; the committed bytes it holds were judged offline
+ * and NOTHING was minted, because the envelope is never the recorded thing.
  */
 export interface RecordOutcome {
   path: string;
-  /** The file's own digest (URL-safe): the origin of its fused bytes. */
+  /** The file's own digest (URL-safe): the origin of its fused bytes. For a "carried" row, the COMMITTED bytes' digest. */
   digest: string;
-  outcome: "fused" | "on record" | "not fused";
+  outcome: "fused" | "on record" | "not fused" | "carried";
+  /** A BitGraphed file's offline judgment: the carried proof's verdict and window. */
+  carrier?: CarrierWindowView;
+  /** True when the bytes carry Content Credentials (a C2PA manifest); the proof page displays them. */
+  c2pa?: boolean;
   /** The member's fused digest (URL-safe), present on a "fused" outcome. */
   artifact_digest: string | null;
   placement: string | null;
@@ -78,10 +86,17 @@ export interface SetOutcome {
 
 export interface CheckOutcome {
   input: string;
-  digest: string; // URL-safe
+  /** URL-safe. For a BitGraphed file, the digest of the COMMITTED bytes inside, never the envelope's. */
+  digest: string;
   on_record: boolean;
   positions: Array<{ counter: string | null; epoch: string | null; member?: SetMemberView }>;
   proof_url: string | null;
+  /** Present when the input is a BitGraphed file: the carried proof's offline judgment. */
+  carrier?: CarrierWindowView;
+  /** True when the bytes carry Content Credentials (a C2PA manifest). */
+  c2pa?: boolean;
+  /** A stated condition (an unreadable carrier block, an oversized file), never a verdict. */
+  note?: string;
 }
 
 export function positionOf(proof: BitGraphProof): { counter: string | null; epoch: string | null } {
@@ -96,9 +111,14 @@ function memberNote(m: SetMemberView | undefined): string {
   return m ? ` (member ${fmt(m.index + 1)} of ${fmt(m.count)})` : "";
 }
 
+/** The C2PA note a row earns, or an empty string. */
+const c2paNote = (o: { c2pa?: boolean }): string =>
+  o.c2pa === true ? `\n  Content Credentials (C2PA) detected in the file; the proof page displays them.` : "";
+
 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 carried = outcomes.filter((o) => o.outcome === "carried");
   const notFused = outcomes.filter((o) => o.outcome === "not fused");
   const lines: string[] = [];
   const parts: string[] = [];
@@ -108,6 +128,7 @@ export function renderRecordMarkdown(outcomes: readonly RecordOutcome[], set: Se
     parts.push(`${fmt(fused.length)} fused`);
   }
   parts.push(`${fmt(onRecord.length)} already on record`);
+  if (carried.length > 0) parts.push(`${fmt(carried.length)} BitGraphed file${carried.length === 1 ? "" : "s"} (proof inside, nothing minted)`);
   if (notFused.length > 0) parts.push(`${fmt(notFused.length)} NOT fused`);
   lines.push(`${parts.join(", ")}.`);
   if (set !== null && fused.length > 0) {
@@ -133,16 +154,25 @@ export function renderRecordMarkdown(outcomes: readonly RecordOutcome[], set: Se
     (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}`;
+      const carrier = o.carrier ? `\n  ${carrierLine(o.carrier)}` : "";
+      return `- on record · #${o.counter ?? "?"}${row} · ${o.path}${note}${carrier}${c2paNote(o)}\n  ${o.proof_url}`;
     },
     (n) => `and ${fmt(n)} more already on record`
   );
+  group(
+    carried,
+    (o) => {
+      const where = o.proof_url !== null ? `\n  ${o.proof_url}` : "\n  Not in this ledger; the proof travels in the file itself.";
+      return `- BitGraphed file · ${o.path}\n  ${o.carrier ? carrierLine(o.carrier) : "carried proof"} · nothing minted: the envelope is never the recorded thing, the bytes inside are${c2paNote(o)}${where}`;
+    },
+    (n) => `and ${fmt(n)} more BitGraphed files`
+  );
   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 ?? "?"})`,
+        ? `- fused · #${o.counter ?? "?"} · ${o.path} (${o.placement ?? "?"})${c2paNote(o)}\n  ${o.proof_url}`
+        : `- fused · ${o.path} (${fmt(o.member)} of ${fmt(o.member_count ?? 0)}, ${o.placement ?? "?"})${c2paNote(o)}`,
     (n) => `and ${fmt(n)} more files in the same set`
   );
   if (set !== null && fused.length > 0) {
@@ -169,12 +199,17 @@ export function renderCheckMarkdown(outcomes: readonly CheckOutcome[]): string {
   const found = outcomes.filter((o) => o.on_record).length;
   const lines: string[] = [`${fmt(found)} of ${fmt(outcomes.length)} on record.`];
   for (const o of outcomes.slice(0, MARKDOWN_ROWS)) {
+    const carrier = o.carrier ? `\n  BitGraphed file: ${carrierLine(o.carrier)} (judged offline from the proof inside)` : "";
     if (o.on_record) {
       const first = o.positions[0];
       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}`);
+      lines.push(`- on record · #${first?.counter ?? "?"}${memberNote(first?.member)}${extra} · ${o.input}${carrier}${c2paNote(o)}\n  ${o.proof_url}`);
+    } else if (o.carrier) {
+      lines.push(`- not in this ledger · ${o.input}${carrier}${c2paNote(o)}`);
+    } else if (o.note !== undefined) {
+      lines.push(`- not judged · ${o.input}\n  ${o.note}`);
     } else {
-      lines.push(`- not on record · ${o.input}`);
+      lines.push(`- not on record · ${o.input}${c2paNote(o)}`);
     }
   }
   if (outcomes.length > MARKDOWN_ROWS) lines.push(`- and ${fmt(outcomes.length - MARKDOWN_ROWS)} more; the structured result lists every one`);
@@ -189,9 +224,9 @@ function renderWindow(detail: ProofDetailResponse): string | null {
   const lowerBlock = w.anchorBefore?.blockNumber ?? null;
   const upperBlock = w.anchorAfter?.blockNumber ?? null;
   if (lower && upper) {
-    return `BitGraphed between ${lower} (Ethereum block ${lowerBlock ?? "?"}) and ${upper} (block ${upperBlock ?? "?"}).`;
+    return `BitGraphed after ${lower} (Ethereum block ${lowerBlock ?? "?"}), and before the anchoring of block ${upperBlock ?? "?"} (that block mined ${upper}).`;
   }
-  if (upper) return `BitGraphed before ${upper} (Ethereum block ${upperBlock ?? "?"}).`;
+  if (upper) return `BitGraphed before the anchoring of Ethereum block ${upperBlock ?? "?"} (that block mined ${upper}).`;
   if (lower) return `BitGraphed after ${lower} (Ethereum block ${lowerBlock ?? "?"}).`;
   return null;
 }
@@ -236,7 +271,7 @@ export function renderProofMarkdown(
     positions.forEach((p, i) => {
       const label = i === 0 ? " · original" : "";
       const bracket =
-        p.lowerTime && p.upperTime ? ` · between ${p.lowerTime} and ${p.upperTime}` : "";
+        p.lowerTime && p.upperTime ? ` · after ${p.lowerTime}, before the closing anchor (its block mined ${p.upperTime})` : "";
       lines.push(`- #${p.counter ?? "?"}${label}${p.member ? ` · set of ${fmt(p.member.count)}` : ""}${bracket}`);
     });
   }

package/src/index.ts

@@ -10,7 +10,7 @@
  */
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { configFromEnv } from "./api.js";
+import { configFromEnv } from "@mikeargento/bitgraph-sdk";
 import { buildServer, SERVER_VERSION } from "./server.js";
 
 async function main(): Promise<void> {

package/src/instructions.ts

@@ -0,0 +1,11 @@
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
+
+/** The task-form guidance spoken to MCP callers; the mechanics live in the SDK. */
+import { SLOT_TTL_SECONDS } from "@mikeargento/bitgraph-sdk";
+
+export const TASK_INSTRUCTIONS =
+  "You hold a position and its commitment, and no work exists yet. Put the commitment string INSIDE THE OUTPUT you are about to make whenever its format can hold text (SVG, HTML, code, JSON, Markdown, CSV, a document): as a comment, a field, a line that stays in the file. " +
+  `When the output exists, call bitgraph_commit with this fuse_token and the output file's path, within ${SLOT_TTL_SECONDS} seconds of opening: the output itself is sealed under the position, and the proof is written beside it. ` +
+  "If the output cannot hold text (a PNG, audio, video) or will take longer than that to make, put the commitment into a task file instead (the exact prompt or request you send), seal that file the same way, and when the output exists record it with bitgraph_record: the task is sealed before the output existed, and the output is recorded after. " +
+  "Keep the exact bytes that were sealed unchanged: a verifier recomputes the commitment from the proof and looks for the string inside them. " +
+  "Leave the proof file as written, whole, every field, environment.attestation.reportB64 included: a proof missing slotAllocation, environment, or the attestation cannot be verified.";