@mikeargento/bitgraph-mcp 0.5.2 → 0.6.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 "../encoding.js";
+import { sniffC2paBytes, scanFile } from "../scan.js";
+
+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

@@ -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__/tools.test.ts

@@ -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/carrier-io.ts

@@ -0,0 +1,120 @@
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
+
+/**
+ * @mikeargento/bitgraph-mcp: BitGraphed files (bitgraph-carrier/1).
+ *
+ * A BitGraphed file is committed bytes followed by one structural block that
+ * carries the proof and the anchor evidence. The block is found from the END
+ * of the file, by structure, never by scanning. Everything here is local:
+ * an 8-byte tail read decides whether a file is a carrier at all, and the
+ * full judgment runs offline through @mikeargento/bitgraph-verify.
+ *
+ * The one rule that cannot bend: the envelope is never the recorded thing,
+ * the bytes inside it are. So the tools look up the INNER digest, and
+ * bitgraph_record never mints carrier bytes, the same structural guarantee
+ * the site's drop box gives.
+ */
+
+import { open } from "node:fs/promises";
+import {
+  CARRIER_MAGIC, CARRIER_OVERHEAD, parseCarrier, verifyCarrier,
+  type CarrierVerifyResult,
+} from "@mikeargento/bitgraph-verify";
+
+/** ISO string for a witness timestamp (seconds), or null when the header was unreadable. */
+const iso = (ts: number | null): string | null => (ts === null ? null : new Date(ts * 1000).toISOString());
+
+/** The window as the tools state it. not_after null = NOT FETCHED, in those words. */
+export interface CarrierWindowView {
+  verdict: "TRUE" | "FALSE" | "UNDETERMINED";
+  not_before: { block: number; hash: string; time: string | null } | null;
+  /** null when the ceiling has not been fetched into the file yet. */
+  not_after: { block: number; hash: string; time: string | null } | null;
+  ceiling: "present" | "unfetched" | null;
+  reasons: string[];
+}
+
+export function carrierWindowView(r: CarrierVerifyResult): CarrierWindowView {
+  return {
+    verdict: r.verdict,
+    not_before: r.bounds ? { block: r.bounds.notBefore.blockNumber, hash: r.bounds.notBefore.blockHash, time: iso(r.bounds.notBefore.timestamp) } : null,
+    not_after: r.bounds?.notAfter ? { block: r.bounds.notAfter.blockNumber, hash: r.bounds.notAfter.blockHash, time: iso(r.bounds.notAfter.timestamp) } : null,
+    ceiling: r.ceiling,
+    reasons: r.reasons,
+  };
+}
+
+/**
+ * One line for a markdown row: the verdict and the window, in the stated
+ * words. The floor is temporal (after the block's own time, cryptographically);
+ * the ceiling is POSITIONAL: committed before the ANCHORING of the later
+ * block, never before that block's mine time, because an anchor is built
+ * after the block it carries. Canon §3.5/§3.6: floor in time, ceiling in
+ * position; converting the positional ceiling into a clock reading is the
+ * one error.
+ */
+export function carrierLine(view: CarrierWindowView): string {
+  const parts: string[] = [`carried proof ${view.verdict}`];
+  if (view.not_before) parts.push(`after block ${view.not_before.block}${view.not_before.time ? ` (mined ${view.not_before.time})` : ""}`);
+  parts.push(
+    view.not_after
+      ? `before the anchoring of block ${view.not_after.block}${view.not_after.time ? ` (block mined ${view.not_after.time})` : ""}`
+      : "closing anchor NOT FETCHED (drop the file on bitgraph.ing to complete it)"
+  );
+  return parts.join(" · ");
+}
+
+/**
+ * True when the file's last 8 bytes are the carrier magic. One positioned
+ * read; no file that is not a carrier pays more than that.
+ */
+export async function sniffCarrierTail(path: string, size: number): Promise<boolean> {
+  if (size < CARRIER_OVERHEAD) return false;
+  const fd = await open(path, "r");
+  try {
+    const tail = Buffer.alloc(CARRIER_MAGIC.length);
+    await fd.read(tail, 0, tail.length, size - tail.length);
+    return tail.equals(Buffer.from(CARRIER_MAGIC));
+  } finally {
+    await fd.close();
+  }
+}
+
+export interface CarrierFileResult {
+  /** "ok": readable block, judged. "corrupt": block found but unreadable. */
+  status: "ok" | "corrupt";
+  /** Standard base64 SHA-256 of the COMMITTED bytes inside; the digest every lookup uses. */
+  innerDigestB64: string | null;
+  /** The committed bytes, for callers that go on to sniff or serve them. */
+  inner: Uint8Array | null;
+  result: CarrierVerifyResult | null;
+  view: CarrierWindowView | null;
+  corruptReason: string | null;
+}
+
+/**
+ * Read a tail-confirmed carrier whole and judge it offline: the carried
+ * proof, the floor by identity, the witnesses, the ceiling when present.
+ * Proof-level judgment (attestation depth stays the audit CLI's job).
+ */
+export async function readCarrierFile(path: string): Promise<CarrierFileResult> {
+  const fd = await open(path, "r");
+  let bytes: Uint8Array;
+  try {
+    const info = await fd.stat();
+    const buf = Buffer.alloc(info.size);
+    await fd.read(buf, 0, info.size, 0);
+    bytes = new Uint8Array(buf);
+  } finally {
+    await fd.close();
+  }
+  const parsed = parseCarrier(bytes);
+  if (parsed.kind !== "carrier") {
+    const reason = parsed.kind === "corrupt" ? parsed.reason : "the tail magic matched but no block parsed";
+    return { status: "corrupt", innerDigestB64: null, inner: null, result: null, view: null, corruptReason: reason };
+  }
+  const result = await verifyCarrier(bytes);
+  const { createHash } = await import("node:crypto");
+  const innerDigestB64 = createHash("sha256").update(parsed.inner).digest("base64");
+  return { status: "ok", innerDigestB64, inner: parsed.inner, result, view: carrierWindowView(result), corruptReason: null };
+}

package/src/format.ts

@@ -4,11 +4,15 @@
  * @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 { carrierLine, type CarrierWindowView } from "./carrier-io.js";
 import type { BitGraphProof, PositionView, ProofDetailResponse, SetMemberView } from "./types.js";
 
 export const CHARACTER_LIMIT = 25_000;
@@ -38,13 +42,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 +88,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 +113,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 +130,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 +156,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 +201,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 +226,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 +273,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}`);
     });
   }