@mikeargento/bitgraph-mcp 0.4.0 → 0.5.0

package/src/__tests__/format.test.ts

@@ -37,7 +37,7 @@ test("record markdown mentions again=true only when something was already on rec
     { ...base, path: "/b", outcome: "on record", artifact_digest: null, placement: null, member: null, member_count: null },
   ]);
   assert.ok(mixed.includes("again=true"));
-  assert.ok(mixed.startsWith("1 fused, 1 already on record."));
+  assert.ok(mixed.startsWith("1 fused, 1 already on record (indexed before 2026-09-08)."));
 });
 
 test("record markdown names the set once and its members by row", () => {
@@ -54,12 +54,12 @@ test("record markdown names the set once and its members by row", () => {
   };
   const row = { digest: toUrlSafeB64(DIGEST), counter: "1386", epoch: toUrlSafeB64(EPOCH), total_positions: 1, proof_url: "https://bitgraph.ing/proof/x", artifact_digest: "ZnVzZWQ", outcome: "fused" as const, member_count: 2 };
   const md = renderRecordMarkdown([{ ...row, path: "/a.png", placement: "trailer/1", member: 2 }, { ...row, path: "/b.txt", placement: "container/2", member: 1 }], set);
-  assert.ok(md.startsWith("2 files BitGraphed as one set at #1386 (set of 2), 0 already on record."), md);
+  assert.ok(md.startsWith("2 files BitGraphed as one set at #1386 (set of 2), 0 already on record (indexed before 2026-09-08)."), md);
   assert.ok(md.includes("- #1386 · set of 2 · https://bitgraph.ing/proof/c2V0?counter=1386"), md);
   assert.ok(md.includes("- fused · /a.png (2 of 2, trailer/1)"), md);
   assert.ok(md.includes("- fused · /b.txt (1 of 2, container/2)"), md);
   const waiting = renderRecordMarkdown([{ ...row, path: "/a.png", placement: "trailer/1", member: 1 }], { ...set, set: "set/2", index: { written: 0, pending: 2 } });
-  assert.ok(waiting.includes("not findable by hash"), waiting);
+  assert.ok(waiting.includes("does not index new proofs by hash"), waiting);
 });
 
 test("proof markdown states the window as between lower and upper", () => {

package/src/__tests__/tools.test.ts

@@ -17,7 +17,7 @@ import { join } from "node:path";
 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 FuseSetFn } from "../server.js";
+import { buildServer, pendingIndexCount, ROW_CAP, SET_INDEX_CHUNK, type FuseFileFn, type FuseSetFn } from "../server.js";
 import { toUrlSafeB64 } from "../encoding.js";
 
 interface Recorded {
@@ -202,8 +202,16 @@ const fakeFuseSet: FuseSetFn = async (files, _config, opts) => {
     }),
   };
 };
+/** A stand-in for the single-file pipeline: records what it was asked to fuse. */
+const soloCalls: Array<{ name: string; digestB64: string }> = [];
+const fakeFuseFile: FuseFileFn = async (file) => {
+  soloCalls.push({ name: file.name, digestB64: file.digestB64 });
+  if (fuseMode === "fail") throw new FuseError("tee-restarting", "the boundary is restarting", 503);
+  const artifactDigestB64 = createHash("sha256").update("fused:" + file.digestB64).digest("base64");
+  return { proof: proofFor(artifactDigestB64), frame: { type: "bitgraph-fuse/1" }, placement: file.placement, artifactDigestB64, originDigestB64: file.digestB64 };
+};
 async function connectedClient(): Promise<Client> {
-  const server = buildServer({ fuseSet: fakeFuseSet });
+  const server = buildServer({ fuseSet: fakeFuseSet, fuseFile: fakeFuseFile });
   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)]);
@@ -212,17 +220,18 @@ async function connectedClient(): Promise<Client> {
 
 interface RecordStructured {
   set: { set: string; count: number; counter: string | null; proof_url: string; index: { written: number; pending: number } | null } | null;
+  frames: Record<string, unknown>;
   results: Array<{ path: string; outcome: string; counter: string | null; placement: string | null; artifact_digest: string | null; member: number | null; member_count: number | null; total_positions: number; proof_url: string | null; error?: string }>;
   omitted: number;
   summary: { files: number; directories: number; fused: number; on_record: number; not_fused: number };
 }
 const textOf = (result: unknown): string => (((result as { content?: unknown }).content ?? []) as Array<{ text: string }>)[0]?.text ?? "";
 
-test("lists the three tools", async () => {
+test("lists the five tools", async () => {
   const client = await connectedClient();
   const tools = await client.listTools();
   const names = tools.tools.map((t) => t.name).sort();
-  assert.deepEqual(names, ["bitgraph_check", "bitgraph_get_proof", "bitgraph_record"]);
+  assert.deepEqual(names, ["bitgraph_check", "bitgraph_commit", "bitgraph_get_proof", "bitgraph_open", "bitgraph_record"]);
 });
 
 test("record makes ONE set of the fresh files and leaves on-record ones alone", async () => {
@@ -268,18 +277,28 @@ test("record makes ONE set of the fresh files and leaves on-record ones alone",
   assert.ok(text.includes("set of 2"), text);
 });
 
-test("record with again=true puts on-record files in the set", async () => {
+test("a single file is fused on its own, with its Frame; again=true fuses an on-record one", async () => {
   const client = await connectedClient();
   setCalls.length = 0;
+  soloCalls.length = 0;
   const result = await client.callTool({
     name: "bitgraph_record",
     arguments: { paths: [fileA], again: true },
   });
   assert.ok(!result.isError, JSON.stringify(result.content));
-  assert.deepEqual(setCalls.map((c) => c.digests), [[digestA]]);
+  assert.equal(setCalls.length, 0, "one file is not a set");
+  assert.deepEqual(soloCalls.map((c) => c.digestB64), [digestA]);
   const structured = result.structuredContent as RecordStructured;
-  assert.equal(structured.results[0]?.outcome, "fused");
-  assert.equal(structured.results[0]?.total_positions, 3, "two prior positions plus the new set");
+  assert.equal(structured.set, null);
+  const row = structured.results[0];
+  assert.equal(row?.outcome, "fused");
+  assert.equal(row?.member, null);
+  assert.equal(row?.total_positions, 3, "two prior positions plus the new BitGraph");
+  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.includes("its Frame is in the structured result"), text);
 });
 
 test("a directory is its regular files, hidden entries and links left out", async () => {
@@ -296,17 +315,19 @@ test("a directory is its regular files, hidden entries and links left out", asyn
   assert.equal(structured.set?.count, 2);
 });
 
-test("the same bytes under two paths are one member, reported twice", async () => {
+test("the same bytes under two paths are one file, fused once and reported twice", async () => {
   const client = await connectedClient();
   setCalls.length = 0;
+  soloCalls.length = 0;
   const result = await client.callTool({
     name: "bitgraph_record",
     arguments: { paths: [fileB, copyB] },
   });
   assert.ok(!result.isError, JSON.stringify(result.content));
-  assert.deepEqual(setCalls[0]?.digests, [digestB]);
+  assert.equal(setCalls.length, 0, "one distinct file is fused on its own");
+  assert.deepEqual(soloCalls.map((c) => c.digestB64), [digestB]);
   const structured = result.structuredContent as RecordStructured;
-  assert.equal(structured.set?.count, 1);
+  assert.equal(structured.set, null);
   assert.equal(structured.summary.fused, 2);
   assert.equal(structured.results[0]?.artifact_digest, structured.results[1]?.artifact_digest);
 });
@@ -353,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("not findable by hash"), textOf(first).slice(0, 400));
+  assert.ok(textOf(first).includes("does not index new proofs by hash"), textOf(first).slice(0, 400));
 
   // Still down: nothing new is made, so the members cannot be made again by mistake.
   requests.length = 0;

package/src/format.ts

@@ -107,13 +107,13 @@ export function renderRecordMarkdown(outcomes: readonly RecordOutcome[], set: Se
   } else {
     parts.push(`${fmt(fused.length)} fused`);
   }
-  parts.push(`${fmt(onRecord.length)} already on record`);
+  parts.push(`${fmt(onRecord.length)} already on record (indexed before 2026-09-08)`);
   if (notFused.length > 0) parts.push(`${fmt(notFused.length)} NOT fused`);
   lines.push(`${parts.join(", ")}.`);
   if (set !== null && fused.length > 0) {
     lines.push(`- #${set.counter ?? "?"} · set of ${fmt(set.count)} · ${set.proof_url}`);
     if (set.index !== null && set.index.pending > 0) {
-      lines.push(`  The set is on the ledger, but the evidence for ${fmt(set.index.pending)} of its ${fmt(set.count)} members is not indexed yet, so those files are not findable by hash until it is. It is sent again at the start of the next bitgraph_record call.`);
+      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.`);
     }
     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.`);
@@ -139,17 +139,24 @@ export function renderRecordMarkdown(outcomes: readonly RecordOutcome[], set: Se
   );
   group(
     fused,
-    (o) => `- fused · ${o.path} (${fmt(o.member ?? 0)} of ${fmt(o.member_count ?? 0)}, ${o.placement ?? "?"})`,
+    (o) =>
+      o.member === null
+        ? `- fused · #${o.counter ?? "?"} · ${o.path} (${o.placement ?? "?"})\n  ${o.proof_url}`
+        : `- fused · ${o.path} (${fmt(o.member)} of ${fmt(o.member_count ?? 0)}, ${o.placement ?? "?"})`,
     (n) => `and ${fmt(n)} more files in the same set`
   );
-  if (fused.length > 0) {
+  if (set !== null && fused.length > 0) {
+    lines.push(
+      "\nOne BitGraph holds every file made here: one slot, one position, and the committed artifact lists each file's new fused bytes by digest. Those bytes were hashed on this machine and never written or uploaded; the file itself is unchanged, and the original plus the set proof rebuilds them. Keep the set proof beside the originals; BitGraph does not index it."
+    );
+  } else if (fused.length > 0) {
     lines.push(
-      "\nOne BitGraph holds every file made here: one slot, one position, and the committed artifact lists each file's new fused bytes by digest. Those bytes were hashed on this machine and never written or uploaded; the file itself is unchanged, and the original plus the set proof rebuilds them. A lookup by any file's own digest finds the set."
+      "\nThe new fused file was built in memory from the file, hashed and committed under its own slot; the file itself is unchanged and was not uploaded. The original plus the proof rebuilds the new file; its Frame is in the structured result."
     );
   }
   if (onRecord.length > 0) {
     lines.push(
-      "\nFiles already on record were left alone. To make a new BitGraph of them deliberately, call bitgraph_record with again=true."
+      "\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."
     );
   }
   if (omitted > 0) {

package/src/server.ts

@@ -5,14 +5,14 @@
  *
  * Three gestures, the same three the website has: make a BitGraph, check
  * whether bytes are on record, fetch a proof. Making a BitGraph is one
- * gesture for any number of files: everything in a call becomes a member of
- * ONE set under ONE slot, the way a drop on the site does. Each file is read
- * once, on this machine, for its digest and a hasher state; the new fused
- * bytes are never written and never held, their digest is finished from that
- * state once the slot exists; and the set's committed artifact is hashed
- * and committed under the same slot. Only digests, that artifact and slot
- * records leave the machine. File contents are never uploaded and files are
- * never modified.
+ * gesture for any number of files, the way a drop on the site is: a single
+ * file is fused on its own slot, and two or more become members of ONE set
+ * under ONE slot. For a set each file is read once, on this machine, for its
+ * digest and a hasher state; the new fused bytes are never written and never
+ * held, their digest is finished from that state once the slot exists; and
+ * the set's committed artifact is hashed and committed under the same slot.
+ * Only digests, that artifact and slot records leave the machine. File
+ * contents are never uploaded and files are never modified.
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -20,7 +20,7 @@ import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/proto
 import type { ServerNotification, ServerRequest } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
-import { FuseError, MAX_SET_MEMBERS, fuseSet, type FuseSetMember, type FuseSetProgress } from "@mikeargento/bitgraph";
+import { FuseError, MAX_SET_MEMBERS, builderFor, fuse, fuseSet, fusedNamesFor, type FuseSetMember, type FuseSetProgress } from "@mikeargento/bitgraph";
 import {
   ApiError,
   batchCheck,
@@ -49,9 +49,10 @@ import {
   type SetOutcome,
 } from "./format.js";
 import { expandPaths, fusedDigestFor, scanFile, type ScannedFile } from "./scan.js";
+import { SLOT_TTL_SECONDS, TASK_INSTRUCTIONS, beginTask, decodeTaskToken, sealTask } from "./task.js";
 import type { BitGraphProof } from "./types.js";
 
-export const SERVER_VERSION = "0.4.0";
+export const SERVER_VERSION = "0.5.0";
 
 const SCAN_CONCURRENCY = 4;
 /** Paths per call; a directory counts once and expands to its files. */
@@ -62,6 +63,8 @@ export const MAX_MEMBERS = 100_000;
 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. */
 export const ROW_CAP = 500;
 /** Members' evidence per set-index request: the site's own chunk. */
@@ -93,9 +96,48 @@ export type FuseSetFn = (
   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;
+  /** The single-file pipeline; tests inject a stand-in. Default: the core package's fuse() against the configured site. */
+  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,
+  };
 }
 
 /**
@@ -282,6 +324,7 @@ 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 server = new McpServer(
     {
       name: "bitgraph-mcp-server",
@@ -289,8 +332,9 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
     },
     {
       instructions:
-        "BitGraph gives a file's bytes a causal position in a public ledger bracketed by Ethereum anchors. bitgraph_record makes ONE BitGraph of everything in a call, files and folders alike: 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.",
+        "BitGraph gives a file's bytes a causal position in a public ledger 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. " +
+        "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.",
     }
   );
 
@@ -299,13 +343,13 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
     {
       title: "Make a BitGraph",
       description:
-        "Make a BitGraph of files or folders. Everything in one call becomes ONE BitGraph: a set under a single slot in the BitGraph ledger (bitgraph.ing), one position for all of it, the way a drop on the site works. " +
-        "On this machine each file is read once for its SHA-256 (the origin) and a hasher state; an unused slot is allocated before any new file exists; every file's new fused bytes (the original plus a registered placement carrying the slot's commitment: a 48-byte trailer for JPEG, PNG, GIF, TIFF and TIFF-based raws, BMP, WebP, WAV and AVI, a small tar container with the original first for everything else) are hashed from that state without being written or held; and the canonical list of those digests (above 2,000 files, a Merkle root over it) is committed under the same slot. " +
+        "Make a BitGraph of files or folders. Everything in one call becomes ONE BitGraph, the way a drop on the site works: a single file is fused on its own slot; two or more files become a set under a single slot in the BitGraph ledger (bitgraph.ing), one position for all of them. " +
+        "On this machine each file is read once for its SHA-256 (the origin) and a hasher state; an unused slot is allocated before any new file exists; every file's new fused bytes (the original plus a registered placement carrying the slot's commitment: a 48-byte trailer for JPEG, PNG, GIF, TIFF and TIFF-based raws, BMP, WebP, WAV and AVI, a small tar container with the original first for everything else) are hashed from that state without being written or held; and for a set the canonical list of those digests (above 2,000 files, a Merkle root over it) is committed under the same slot. " +
         "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 (recorded, or the origin of a fused file) are NOT made again by default; they come back as 'on record' with their earliest position. Pass again=true to make a new BitGraph of them deliberately. " +
-        "BitGraphs are permanent: the ledger has 10-year retention and no deletes, so only BitGraph files the user asked to, and never generate content just to record it. " +
-        "Returns the set's position and proof page, and one outcome per file: 'fused' (its row in the set, one of N), 'on record', or 'not fused' (with the reason). A lookup by any file's own digest finds the set. " +
+        "Files BitGraph still indexes (recorded before 2026-09-08) are NOT made again by default; they come back as 'on record' with their earliest position. BitGraph does not index new proofs, so a file may already have a BitGraph its holder keeps. Pass again=true to make a new BitGraph regardless. " +
+        "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.",
       inputSchema: {
         paths: z
@@ -317,7 +361,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
           .boolean()
           .default(false)
           .describe(
-            "false (default): files already on record are returned as-is, nothing made. true: put every file in the set even if its bytes are already on record. Outcomes are per unique file content: two paths with identical bytes are one member."
+            "false (default): files BitGraph still indexes are returned as-is, nothing made. true: put every file in the set regardless. Outcomes are per unique file content: two paths with identical bytes are one member."
           ),
         response_format: responseFormatSchema,
       },
@@ -390,8 +434,18 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
         }
         const attempted = new Set(toMint.map((f) => f.digestB64));
         let made: SetSummary | null = null;
+        let solo: (FusedSummary & { file: ScannedFile }) | null = null;
         let failure: string | null = null;
-        if (toMint.length > 0) {
+        const one = toMint.length === 1 ? (toMint[0] as ScannedFile) : null;
+        if (one !== null && one.size <= MAX_SOLO_BYTES) {
+          // 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 };
+          } 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, {
@@ -433,13 +487,29 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
             index,
           };
         }
+        const frames: Record<string, unknown> = {};
+        if (solo !== null) frames[toUrlSafeB64(solo.artifactDigestB64)] = solo.frame;
         const outcomes: RecordOutcome[] = [];
         for (const [digest, entry] of byDigest) {
           const m = memberOf.get(digest);
           const prior = existing.get(digest);
           for (const path of entry.paths) {
             const base = { path, digest: toUrlSafeB64(digest) };
-            if (m !== undefined && made !== null && setOutcome !== null) {
+            if (solo !== null && solo.file.digestB64 === digest) {
+              const { counter, epoch } = positionOf(solo.proof);
+              outcomes.push({
+                ...base,
+                outcome: "fused",
+                artifact_digest: toUrlSafeB64(solo.artifactDigestB64),
+                placement: solo.placement,
+                counter,
+                epoch,
+                member: null,
+                member_count: null,
+                total_positions: (prior?.length ?? 0) + 1,
+                proof_url: proofUrl(config.baseUrl, solo.artifactDigestB64, counter ?? undefined, solo.proof.commit?.epochId),
+              });
+            } else if (m !== undefined && made !== null && setOutcome !== null) {
               outcomes.push({
                 ...base,
                 outcome: "fused",
@@ -500,6 +570,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
         const structured = {
           set: setOutcome,
           results: listed as unknown as Record<string, unknown>[],
+          frames,
           omitted,
           summary,
         };
@@ -522,6 +593,78 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
     }
   );
 
+  server.registerTool(
+    "bitgraph_open",
+    {
+      title: "Open a position before the work",
+      description:
+        "Ask for a BitGraph position BEFORE starting a task, so the task can be done inside the BitGraph. Returns a fuse_token, the position, its floor block, and the slot's commitment as a string. " +
+        "Put the commitment string into the task before running it (the prompt or request you send, a seed, a line in the document, text that must appear in the output), then call bitgraph_commit with the fuse_token and the task file's path within " + SLOT_TTL_SECONDS + " seconds. " +
+        "What that gives a stranger: the task could not have existed before the floor block (the commitment did not exist before the position did), and the outputs, recorded afterwards with bitgraph_record, sit at later positions. " +
+        "Nothing about the task is sent here; only its digest is, at commit. Positions are permanent: open one only when a task is about to run.",
+      inputSchema: {
+        response_format: responseFormatSchema,
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    async ({ response_format }) => {
+      const config = configFromEnv();
+      try {
+        const b = await beginTask(config);
+        const structured = { outcome: "opened", task: true, slot_counter: b.slotCounter, epoch: b.epoch, commitment: b.commitment, commitment_base64: b.commitmentB64, floor: b.floor, fuse_token: b.token, expires_in_seconds: SLOT_TTL_SECONDS, instructions: TASK_INSTRUCTIONS };
+        if (response_format === "json") return ok(JSON.stringify(structured, null, 2), structured);
+        return ok(
+          `Opened position ${b.slotCounter} before any work exists. Floor: ${b.floor ? `not before block ${b.floor.block}` : "the sealed proof will carry the signed floor"}.\n\n` +
+            `Commitment (put this string into the task): ${b.commitment}\n\n${TASK_INSTRUCTIONS}\n\n` +
+            "```json\n" + JSON.stringify({ fuse_token: b.token, commitment: b.commitment, slot_counter: b.slotCounter, epoch: b.epoch, floor: b.floor }, null, 2) + "\n```",
+          structured
+        );
+      } catch (err) {
+        return fail(errorText(err));
+      }
+    }
+  );
+
+  server.registerTool(
+    "bitgraph_commit",
+    {
+      title: "Seal the task under its position",
+      description:
+        "Step two of doing work inside a BitGraph: seal the task bytes that carry the commitment under the position bitgraph_open returned. Give the fuse_token and the path of the task file (the exact request, prompt or document that contains the commitment string), or its SHA-256 (base64) when the bytes are elsewhere. " +
+        "With a path, the file is read on this machine, the commitment string is looked for inside it BEFORE anything is sent (a task that does not carry it is refused and the slot stays held), and only the digest travels. " +
+        "Returns the proof: keep it beside the task bytes. Then record the outputs with bitgraph_record. Must be called within " + SLOT_TTL_SECONDS + " seconds of bitgraph_open.",
+      inputSchema: {
+        fuse_token: z.string().min(1).max(8000).describe("The fuse_token bitgraph_open returned."),
+        path: z.string().min(1).optional().describe("Path of the task file that contains the commitment string."),
+        digest: z.string().min(1).max(100).optional().describe("Instead of a path: SHA-256 of the task bytes, base64 (either form)."),
+        response_format: responseFormatSchema,
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    async ({ fuse_token, path, digest, response_format }) => {
+      const config = configFromEnv();
+      const state = decodeTaskToken(fuse_token);
+      if (state === null) return fail("Error: fuse_token is not one issued by bitgraph_open.");
+      if (path === undefined && digest === undefined) return fail("Error: give the task file's path, or its SHA-256 digest.");
+      try {
+        const sealed = await sealTask(config, state, path !== undefined ? { path } : { digestB64: fromUrlSafeB64(digest!.trim()) });
+        const counter = sealed.proof.commit?.counter ?? null;
+        const epoch = sealed.proof.commit?.epochId ?? null;
+        const floor = sealed.proof.commit?.slotAnchor?.blockNumber ?? null;
+        const structured = { outcome: "sealed", slot_counter: state.slot.counter, counter, epoch: epoch ? toUrlSafeB64(epoch) : null, floor_block: floor, artifact_digest: toUrlSafeB64(sealed.artifactDigestB64), commitment_offsets: sealed.offsets, proof: sealed.proof };
+        if (response_format === "json") return ok(JSON.stringify(structured, null, 2), structured);
+        return ok(
+          `Sealed the task at position ${counter ?? "?"} (slot ${state.slot.counter}).${floor !== null ? ` Not before block ${floor}.` : ""} ` +
+            (sealed.offsets !== null ? `The commitment string was found in the task bytes at offset ${sealed.offsets[0]}. ` : "The task bytes were not read here; a verifier looks for the commitment string in them. ") +
+            "Keep the proof beside the task bytes, and record the outputs with bitgraph_record when they exist.\n\n```json\n" + JSON.stringify(sealed.proof, null, 2) + "\n```",
+          structured
+        );
+      } catch (err) {
+        return fail(errorText(err));
+      }
+    }
+  );
+
   server.registerTool(
     "bitgraph_check",
     {

package/src/task.ts

@@ -0,0 +1,163 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * A position BEFORE the work: the task form of the stdio server.
+ *
+ * bitgraph_open with no files asks the site's own /api/fuse/allocate for a
+ * slot and returns its commitment, and nothing else. The caller puts the
+ * commitment into the task it is about to run (the prompt, the request, a
+ * seed, a line in the document) and, within the slot's life, commits the
+ * digest of those task bytes under the slot with the inline marker
+ * (bitgraph-fuse/1, title base64url): a verifier recomputes the commitment
+ * from the slot record and finds its base64url text inside the bytes.
+ * Outputs are recorded afterwards with bitgraph_record and sit later.
+ *
+ * The slot allocation and the commit go through the same two site routes
+ * the core package's fuse() uses; the recovery rule is the core's (read back
+ * by digest, refuse a proof under any other slot).
+ */
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { bytesToBase64, computeSlotCommitment, findCommitment, inlineAttribution, verifyProofIntegrity, ENCODING_BASE64URL } from "@mikeargento/bitgraph-verify";
+import type { BitGraphProof, SlotAllocation } from "@mikeargento/bitgraph-verify";
+import { ApiError, type ApiConfig } from "./api.js";
+import { toUrlSafeB64 } from "./encoding.js";
+
+export const SLOT_TTL_SECONDS = 120;
+const CHAIN = "bitgraph:main";
+const B64_32 = /^[A-Za-z0-9+/]{43}=$/;
+const B64_64 = /^[A-Za-z0-9+/]{86}==$/;
+
+export interface TaskState {
+  v: 1;
+  task: true;
+  slot: SlotAllocation;
+}
+
+function isSlotRecord(x: unknown): x is SlotAllocation {
+  if (x === null || typeof x !== "object" || Array.isArray(x)) return false;
+  const s = x as Record<string, unknown>;
+  return s.version === "bitgraph/slot/1" && typeof s.nonceB64 === "string" && B64_32.test(s.nonceB64) && typeof s.counter === "string" && /^(0|[1-9][0-9]*)$/.test(s.counter)
+    && typeof s.epochId === "string" && typeof s.publicKeyB64 === "string" && typeof s.signatureB64 === "string" && B64_64.test(s.signatureB64) && s.chainId === CHAIN;
+}
+
+export function encodeTaskToken(state: TaskState): string {
+  return Buffer.from(JSON.stringify(state), "utf8").toString("base64url");
+}
+
+export function decodeTaskToken(token: string): TaskState | null {
+  let parsed: unknown;
+  try { parsed = JSON.parse(Buffer.from(token, "base64url").toString("utf8")); } catch { return null; }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const s = parsed as Record<string, unknown>;
+  if (s.v !== 1 || s.task !== true || !isSlotRecord(s.slot)) return null;
+  return { v: 1, task: true, slot: s.slot };
+}
+
+async function post(config: ApiConfig, path: string, body: unknown, timeoutMs: number): Promise<{ status: number; json: unknown; retryAfterSec: number | null }> {
+  const headers: Record<string, string> = { "content-type": "application/json", accept: "application/json" };
+  if (config.apiKey) headers["authorization"] = `Bearer ${config.apiKey}`;
+  const res = await fetch(`${config.baseUrl}${path}`, { method: "POST", headers, body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs) });
+  let json: unknown = null;
+  try { json = await res.json(); } catch { /* non-JSON */ }
+  const raw = res.headers.get("retry-after");
+  const retry = raw !== null ? Number.parseInt(raw, 10) : NaN;
+  return { status: res.status, json, retryAfterSec: Number.isFinite(retry) ? retry : null };
+}
+
+const messageOf = (json: unknown, fallback: string): string => {
+  const e = (json as { error?: unknown } | null)?.error;
+  return typeof e === "string" ? e : fallback;
+};
+
+export interface Begun {
+  token: string;
+  /** Unpadded base64url: the string to put into the task. */
+  commitment: string;
+  commitmentB64: string;
+  slotCounter: string;
+  epoch: string;
+  floor: { block: number } | null;
+}
+
+/** Step one of the task form: a held slot and its commitment, before any work exists. */
+export async function beginTask(config: ApiConfig): Promise<Begun> {
+  const r = await post(config, "/api/fuse/allocate", {}, 20_000);
+  if (r.status !== 200) throw new ApiError(r.status, messageOf(r.json, `allocation refused (${r.status})`), r.retryAfterSec);
+  const slot = (r.json as { slot?: unknown } | null)?.slot;
+  if (!isSlotRecord(slot)) throw new ApiError(502, "the allocation response is not a slot record on bitgraph:main");
+  const commitmentB64 = bytesToBase64(computeSlotCommitment(slot));
+  let floor: Begun["floor"] = null;
+  try {
+    const res = await fetch(`${config.baseUrl}/api/proofs/anchors?counter=${encodeURIComponent(slot.counter)}&epoch=${encodeURIComponent(slot.epochId)}&before=1`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+    const data = res.status === 200 ? ((await res.json()) as { anchors?: Array<{ commit?: { anchor?: { blockNumber?: number } } }> }) : null;
+    const b = data?.anchors?.[0]?.commit?.anchor?.blockNumber;
+    if (typeof b === "number") floor = { block: b };
+  } catch { floor = null; }
+  return { token: encodeTaskToken({ v: 1, task: true, slot }), commitment: toUrlSafeB64(commitmentB64), commitmentB64, slotCounter: slot.counter, epoch: toUrlSafeB64(slot.epochId), floor };
+}
+
+export interface SealedTask {
+  proof: BitGraphProof;
+  artifactDigestB64: string;
+  /** Byte offsets of the commitment string inside the task bytes, when the bytes were given. */
+  offsets: number[] | null;
+}
+
+/**
+ * Step two: the task bytes (a path, or the bytes themselves) sealed under
+ * the held slot with the inline marker. When the bytes are in hand the
+ * commitment is looked for BEFORE the commit, so a task that does not carry
+ * it is refused without spending the slot.
+ */
+export async function sealTask(config: ApiConfig, state: TaskState, task: { path: string } | { bytes: Uint8Array } | { digestB64: string }): Promise<SealedTask> {
+  const { slot } = state;
+  const commitment = computeSlotCommitment(slot);
+  let bytes: Uint8Array | null = null;
+  let artifactDigestB64: string;
+  if ("digestB64" in task) {
+    if (!B64_32.test(task.digestB64)) throw new ApiError(400, "artifact digest must be a base64 SHA-256");
+    artifactDigestB64 = task.digestB64;
+  } else {
+    bytes = "path" in task ? new Uint8Array(await readFile(task.path)) : task.bytes;
+    artifactDigestB64 = createHash("sha256").update(bytes).digest("base64");
+  }
+  const offsets = bytes === null ? null : findCommitment(bytes, commitment, ENCODING_BASE64URL);
+  if (offsets !== null && offsets.length === 0) {
+    throw new ApiError(400, `the task bytes do not contain the commitment string ${toUrlSafeB64(bytesToBase64(commitment))}; put it in before sealing. Nothing was committed and the slot is still held.`);
+  }
+  const attribution = inlineAttribution();
+  const r = await post(config, "/api/fuse/commit", { digests: [{ digestB64: artifactDigestB64, hashAlg: "sha256" }], slotId: slot.nonceB64, slot, chainId: CHAIN, attribution }, 40_000);
+  let proof: BitGraphProof | null = null;
+  if (r.status === 200) proof = ((r.json as { proof?: BitGraphProof } | null)?.proof ?? null);
+  else if (r.status === 409 || r.status === 503) proof = await recover(config, artifactDigestB64, slot);
+  if (proof === null) throw new ApiError(r.status, messageOf(r.json, `commit refused (${r.status})`), r.retryAfterSec);
+  if (proof.artifact?.digestB64 !== artifactDigestB64 || proof.commit?.nonceB64 !== slot.nonceB64 || proof.slotAllocation?.nonceB64 !== slot.nonceB64) throw new ApiError(502, "the boundary returned a proof under a different slot; nothing is labelled sealed");
+  const a = proof.attribution;
+  if (a?.name !== attribution.name || a?.title !== attribution.title || a?.message !== undefined) throw new ApiError(502, "the returned proof does not carry the inline marker that was sent; nothing is labelled sealed");
+  const integrity = await verifyProofIntegrity({ proof });
+  if (!integrity.valid) throw new ApiError(502, `the returned proof does not verify: ${integrity.reason ?? "unknown reason"}`);
+  return { proof, artifactDigestB64, offsets };
+}
+
+async function recover(config: ApiConfig, artifactDigestB64: string, slot: SlotAllocation): Promise<BitGraphProof | null> {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    if (attempt > 0) await new Promise((r) => setTimeout(r, 1500));
+    try {
+      const res = await fetch(`${config.baseUrl}/api/proofs/${encodeURIComponent(toUrlSafeB64(artifactDigestB64))}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(15_000) });
+      if (res.status !== 200) continue;
+      const j = (await res.json()) as { proofs?: Array<{ proof?: BitGraphProof }> } | null;
+      for (const e of j?.proofs ?? []) {
+        const p = e.proof;
+        if (p && p.artifact?.digestB64 === artifactDigestB64 && p.commit?.nonceB64 === slot.nonceB64) return p;
+      }
+    } catch { /* try again */ }
+  }
+  return null;
+}
+
+export const TASK_INSTRUCTIONS =
+  "You hold a position and its commitment, and no work exists yet. Put the commitment string into the task before you run it: in the prompt or request you are about to send, as a seed, as a line in the document, as text that must appear in the output. " +
+  `Then call bitgraph_commit with this fuse_token and the path of the task file (or the SHA-256 of its bytes), within ${SLOT_TTL_SECONDS} seconds of opening: that seals the task under the position before its output exists. ` +
+  "Keep those exact bytes: a verifier recomputes the commitment from the proof and looks for the string inside them. " +
+  "When the output exists, record it with bitgraph_record; it will sit at a later position. What a stranger can then check: the task could not have existed before the position's floor block, and the output was recorded after it.";