@mikeargento/bitgraph-mcp 0.5.1 → 0.6.0

package/src/__tests__/tools.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * End-to-end tool tests: a real MCP client drives the real server over an
@@ -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");
@@ -297,7 +297,7 @@ test("a single file is fused on its own, with its Frame; again=true fuses an on-
   assert.ok(row?.artifact_digest && structured.frames[row.artifact_digest], "the Frame rides in the structured result under the fused digest");
   assert.ok(row?.proof_url?.includes(encodeURIComponent(row.artifact_digest ?? "")), "a single file's proof page is its own");
   const text = textOf(result);
-  assert.ok(text.startsWith("1 fused, 0 already on record (indexed before 2026-09-08)."), text);
+  assert.ok(text.startsWith("1 fused, 0 already on record."), text);
   assert.ok(text.includes("its Frame is in the structured result"), text);
 });
 
@@ -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);
 });
 
@@ -374,7 +374,7 @@ test("evidence the site cannot index waits, blocks a new set, and is sent first
   const s1 = first.structuredContent as RecordStructured;
   assert.deepEqual(s1.set?.index, { written: 0, pending: BIG });
   assert.equal(pendingIndexCount(), BIG);
-  assert.ok(textOf(first).includes("does not index new proofs by hash"), textOf(first).slice(0, 400));
+  assert.ok(textOf(first).includes("The set proof beside the originals is the record either way."), textOf(first).slice(0, 400));
 
   // Still down: nothing new is made, so the members cannot be made again by mistake.
   requests.length = 0;
@@ -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/api.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * @mikeargento/bitgraph-mcp: HTTP client for the hosted BitGraph API.

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/encoding.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * @mikeargento/bitgraph-mcp: digest encoding and file hashing.

package/src/format.ts

@@ -1,14 +1,18 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * @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[] = [];
@@ -107,16 +129,17 @@ export function renderRecordMarkdown(outcomes: readonly RecordOutcome[], set: Se
   } else {
     parts.push(`${fmt(fused.length)} fused`);
   }
-  parts.push(`${fmt(onRecord.length)} already on record (indexed before 2026-09-08)`);
+  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) {
     lines.push(`- #${set.counter ?? "?"} · set of ${fmt(set.count)} · ${set.proof_url}`);
     if (set.index !== null && set.index.pending > 0) {
-      lines.push(`  The set is made. The evidence for ${fmt(set.index.pending)} of its ${fmt(set.count)} members has not reached BitGraph yet and is sent again at the start of the next bitgraph_record call. BitGraph does not index new proofs by hash; the set proof beside the originals is the record.`);
+      lines.push(`  The set is made. The evidence for ${fmt(set.index.pending)} of its ${fmt(set.count)} members has not reached BitGraph yet and is sent again at the start of the next bitgraph_record call. The set proof beside the originals is the record either way.`);
     }
     if (!set.manifest_echoed) {
-      lines.push(`  The boundary did not echo the committed artifact; the ledger's copy of this proof carries no member list. Keep the set's proof page.`);
+      lines.push(`  The boundary did not echo the committed artifact; BitGraph's copy of this proof carries no member list. Keep the set's proof page.`);
     }
   }
   const group = (rows: readonly RecordOutcome[], render: (o: RecordOutcome) => string, more: (n: number) => string) => {
@@ -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) {
@@ -156,7 +188,7 @@ export function renderRecordMarkdown(outcomes: readonly RecordOutcome[], set: Se
   }
   if (onRecord.length > 0) {
     lines.push(
-      "\nFiles BitGraph still indexes (recorded before 2026-09-08) were left alone. BitGraph does not index new proofs, so a file may already have a BitGraph in its holder's folder. To make a new one regardless, call bitgraph_record with again=true."
+      "\nFiles already on record were left alone. A file can also hold a BitGraph in its holder's folder, which no lookup here can see. To make a new one regardless, call bitgraph_record with again=true."
     );
   }
   if (omitted > 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}`);
     });
   }

package/src/index.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * @mikeargento/bitgraph-mcp: stdio entry point.

package/src/scan.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * @mikeargento/bitgraph-mcp: the scan.
@@ -39,6 +39,50 @@ export interface ScannedFile {
    * then needs the bytes again.
    */
   state: Hash | null;
+  /** True when the bytes carry what looks like a C2PA manifest (Content Credentials). */
+  c2pa: boolean;
+}
+
+/**
+ * Content Credentials detection, structural and cheap: a C2PA manifest lives
+ * in a JUMBF box whose description ("jumd") is followed within a few bytes by
+ * the store label "c2pa", in every container (JPEG APP11, PNG caBX, ISO BMFF).
+ * Requiring the pair in order and near each other keeps a stray "c2pa" in
+ * prose from counting. Detection, not judgment: the proof page parses and
+ * displays the manifest itself.
+ */
+const JUMD = Buffer.from("jumd", "ascii");
+const C2PA_LABEL = Buffer.from("c2pa", "ascii");
+const C2PA_NEAR = 96;
+
+function windowHasC2pa(buf: Buffer): boolean {
+  for (let i = buf.indexOf(JUMD); i !== -1; i = buf.indexOf(JUMD, i + 1)) {
+    const from = i + JUMD.length;
+    const to = Math.min(buf.length, i + C2PA_NEAR);
+    if (buf.subarray(from, to).indexOf(C2PA_LABEL) !== -1) return true;
+  }
+  return false;
+}
+
+class C2paSniffer {
+  found = false;
+  /** The last C2PA_NEAR + 4 bytes of the previous chunk, so a pair split across chunks is seen whole. */
+  private carry: Buffer = Buffer.alloc(0);
+  update(chunk: Buffer): void {
+    if (this.found) return;
+    const buf = this.carry.length > 0 ? Buffer.concat([this.carry, chunk]) : chunk;
+    if (windowHasC2pa(buf)) {
+      this.found = true;
+      return;
+    }
+    const keep = Math.min(buf.length, C2PA_NEAR + JUMD.length);
+    this.carry = Buffer.from(buf.subarray(buf.length - keep));
+  }
+}
+
+/** One-shot form for bytes already in memory (a carrier's committed bytes). */
+export function sniffC2paBytes(bytes: Uint8Array): boolean {
+  return windowHasC2pa(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength));
 }
 
 /** Bytes the placement decision reads: every magic number sits in the first 16. */
@@ -61,9 +105,11 @@ export async function scanFile(path: string): Promise<ScannedFile> {
     const prefix = getPlacement(p)?.scanPrefix?.(size) ?? null;
     if (prefix !== null && prefix.length > 0) run.fused = createHash("sha256").update(prefix);
   };
+  const sniffer = new C2paSniffer();
   const feed = (chunk: Buffer) => {
     origin.update(chunk);
     if (run.fused !== null) run.fused.update(chunk);
+    sniffer.update(chunk);
   };
   for await (const raw of createReadStream(path)) {
     const chunk = raw as Buffer;
@@ -96,6 +142,7 @@ export async function scanFile(path: string): Promise<ScannedFile> {
     originDigest: Uint8Array.from(digest),
     placement,
     state,
+    c2pa: sniffer.found,
   };
 }