agents-can-communicate 0.9.0 → 0.10.0

package/node_modules/@agents-can-communicate/core/src/receipts.mjs

@@ -1,6 +1,7 @@
 import { AccError, EXIT, SCHEMA_VERSION, advanceReceipt }
   from "@agents-can-communicate/protocol";
 
+import { assertExactTransaction } from "./ports.mjs";
 import { receiptId } from "./conversations.mjs";
 
 // How long a live offer may stand with nothing after it before the next turn
@@ -78,6 +79,12 @@ function requireReceipt(tx, messageId, recipientParticipantId) {
   return { message, receipt };
 }
 
+async function loadReceipt(tx, input) {
+  assertExactTransaction(tx);
+  await tx.load("receipt", receiptId(input.messageId, input.recipientParticipantId));
+  await tx.load("message", input.messageId);
+}
+
 function requireOfferableReceipt(tx, input, { allowRoomNextTurn }) {
   const found = requireReceipt(tx, input.messageId, input.recipientParticipantId);
   if (found.message.toParticipantIds.length === 0
@@ -105,8 +112,10 @@ export function createReceiptService(ports) {
   const { store, clock, ids } = ports;
 
   async function readReceipt(input) {
-    return store.transaction(tx => requireReceipt(tx, input.messageId,
-      input.recipientParticipantId).receipt, { kinds: ["message", "receipt"] });
+    return store.transaction(async tx => {
+      await loadReceipt(tx, input);
+      return requireReceipt(tx, input.messageId, input.recipientParticipantId).receipt;
+    }, { kinds: ["message", "receipt"], exactKinds: ["message", "receipt"] });
   }
 
   async function recordOfferSucceeded(input) {
@@ -116,7 +125,9 @@ export function createReceiptService(ports) {
         { messageId: input.messageId, transport: input.transport });
     }
     const now = clock.now();
-    return store.transaction(tx => {
+    return store.transaction(async tx => {
+      await loadReceipt(tx, input);
+      await tx.load("session", input.targetSessionId);
       const id = receiptId(input.messageId, input.recipientParticipantId);
       const receipt = requireOfferableReceipt(tx, input, { allowRoomNextTurn: true });
       const target = requireTarget(tx, input, { mustBeOpen: true });
@@ -153,7 +164,8 @@ export function createReceiptService(ports) {
       tx.put("receipt", id, offered, tx.generationOf("receipt", id));
       success({});
       return offered;
-    }, { kinds: ["session", "message", "receipt"], deadlineAt: input.deadlineAt });
+    }, { kinds: ["session", "message", "receipt"],
+      exactKinds: ["session", "message", "receipt"], deadlineAt: input.deadlineAt });
   }
 
   async function recordOfferFailed(input) {
@@ -162,7 +174,9 @@ export function createReceiptService(ports) {
         { safeErrorCode: input.safeErrorCode });
     }
     const now = clock.now();
-    return store.transaction(tx => {
+    return store.transaction(async tx => {
+      await loadReceipt(tx, input);
+      await tx.load("session", input.targetSessionId);
       const receipt = requireOfferableReceipt(tx, input, { allowRoomNextTurn: false });
       const target = requireTarget(tx, input, { mustBeOpen: false });
       return tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
@@ -174,7 +188,7 @@ export function createReceiptService(ports) {
           targetGeneration: target.generation,
           transport: input.transport, adapterId: input.adapterId,
           clientVersion: input.clientVersion, safeErrorCode: input.safeErrorCode } });
-    }, { kinds: ["session", "message", "receipt"] });
+    }, { kinds: ["session", "message", "receipt"], exactKinds: ["session", "message", "receipt"] });
   }
 
   return { readReceipt, recordOfferSucceeded, recordOfferFailed };

package/node_modules/@agents-can-communicate/delivery-router/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/delivery-router",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/hook-runner/src/runner.mjs

@@ -35,7 +35,7 @@ import { appendStartOwner, appendToolOwner, assertOwnerQuotable, ownerHeader, ow
 const DEFAULT_BUDGET_MS = 5_000;
 // Failures the hook output explains with advice of its own; any other error
 // text stays out of what the client shows.
-const KNOWN_FAILURES = new Set(["workspace_contains_runtime", "workspace_path_unquotable"]);
+const KNOWN_FAILURES = new Set(["workspace_contains_runtime", "workspace_path_unquotable", "store_migration_required"]);
 // Windows reads the table through WMI in Script Host, 145 ms on a
 // windows-latest runner, and through PowerShell where Script Host is off, whose
 // first start on a machine took 3.8 s. It gets more of the budget there, and
@@ -822,6 +822,7 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     if (adapter === undefined) throw new Error(`no adapter named ${adapterId}`);
 
     const event = await adapter.normalizeHook(payload, { args });
+    trail.kind = event.kind;
     // A session start reads the process table once, and it depends on nothing
     // below: it starts now, while the store opens. On Windows it is the part
     // of a start that runs another program.
@@ -900,15 +901,34 @@ export async function runHook({ adapterId, payload, adapters, dataHome, env,
     });
     return await Promise.race([execute(), budget]);
   } catch (error) {
+    const failureCode = error instanceof AccError && KNOWN_FAILURES.has(error.details?.reasonCode)
+      ? error.details.reasonCode : null;
     return { ...fallback, failed: true, reason: error.message,
-      ...(error instanceof AccError && KNOWN_FAILURES.has(error.details?.reasonCode)
-        ? { failureCode: error.details.reasonCode } : {}),
+      ...(failureCode === null ? {} : { failureCode }),
+      ...(failureCode === "store_migration_required"
+        ? { stdout: migrationNotice(adapters?.[adapterId], trail.kind) } : {}),
       ...(Date.now() >= deadline ? { timedOut: true, phase: trail.phase } : {}) };
   } finally {
     clearTimeout(timer);
   }
 }
 
+// What a person reads when their workspace's store waits for its migration: a
+// client that shows hook output to the user says so, instead of the stderr line
+// no client showed (2026-10-06). Never a hook input or error text.
+const MIGRATION_NOTICE = "ACC: coordination is paused in this workspace until its store moves "
+  + "to the new format. ACC does this by itself once older ACC clients have stopped; to do it "
+  + "now, stop them and run: acc doctor --migrate-store";
+function migrationNotice(adapter, kind) {
+  if (typeof adapter?.failOpenNotice !== "function" || typeof kind !== "string") return "";
+  try {
+    const rendered = adapter.failOpenNotice({ kind, message: MIGRATION_NOTICE });
+    return typeof rendered === "string" ? rendered : "";
+  } catch {
+    return "";
+  }
+}
+
 /**
  * Register a client session before its first turn (#167).
  *

package/node_modules/@agents-can-communicate/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/installer/src/ownership.mjs

@@ -29,6 +29,7 @@ export async function fingerprint(file) {
 }
 
 const CLIENT_ORPHAN_MARKER = ".orphaned_at";
+const CLIENT_IN_USE_DIR = ".in_use";
 
 /**
  * Fingerprint of a whole directory ACC created.
@@ -50,8 +51,11 @@ export async function treeFingerprint(root) {
   // Claude Code marks a plugin cache version its registry no longer names with
   // `.orphaned_at`, and removes the marker again if the version comes back. That
   // is the client's own bookkeeping inside a copy ACC keeps on purpose, never an
-  // edit, and ACC never writes a file by that name.
-  const files = entries.filter(entry => entry.isFile() && entry.name !== CLIENT_ORPHAN_MARKER)
+  // edit, and ACC never writes a file by that name. A running session's
+  // `.in_use/<pid>` is the same kind of bookkeeping (2.1.286): after an update it
+  // stood in the previous version ACC keeps on purpose.
+  const files = entries.filter(entry => entry.isFile() && entry.name !== CLIENT_ORPHAN_MARKER
+    && path.basename(entry.parentPath ?? entry.path) !== CLIENT_IN_USE_DIR)
     .map(entry => path.relative(root, path.join(entry.parentPath ?? entry.path, entry.name)))
     .sort();
   const hash = createHash("sha256");

package/node_modules/@agents-can-communicate/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/protocol/src/index.mjs

@@ -12,3 +12,4 @@ export { CONFIG_FILENAME, CONFIG_SCHEMA_VERSION, RUNTIME_KEYS, defaultProjectCon
 export { RECEIPT_STATES, advanceReceipt } from "./states.mjs";
 export { assertMatchableResource, normaliseResource } from "./resources.mjs";
 export { assertDecisionChange } from "./decision-changes.mjs";
+export { TRANSACTION_INDEXES, assertIndexTuple, indexKeysFor } from "./transaction-indexes.mjs";

package/node_modules/@agents-can-communicate/protocol/src/transaction-indexes.mjs

@@ -0,0 +1,22 @@
+import { AccError, EXIT } from "./errors.mjs";
+import { assertPortableId } from "./ids.mjs";
+
+export const TRANSACTION_INDEXES = Object.freeze({
+  messageByClientKey: Object.freeze({ kind: "message", fields: ["workspaceId", "fromParticipantId", "clientMessageId"] }),
+  receiptsByMessage: Object.freeze({ kind: "receipt", fields: ["workspaceId", "messageId"] }),
+});
+
+export function assertIndexTuple(index, tuple) {
+  const definition = Object.hasOwn(TRANSACTION_INDEXES, index) ? TRANSACTION_INDEXES[index] : null;
+  if (definition === null || !Array.isArray(tuple) || tuple.length !== definition.fields.length) {
+    throw new AccError(EXIT.DATA, "invalid transaction index tuple", { index });
+  }
+  tuple.forEach((value, position) => assertPortableId(value, definition.fields[position]));
+  return tuple;
+}
+
+export function indexKeysFor(kind, record) {
+  return Object.entries(TRANSACTION_INDEXES).filter(([, definition]) => definition.kind === kind)
+    .map(([index, definition]) => ({ index,
+      tuple: assertIndexTuple(index, definition.fields.map(field => record[field])) }));
+}

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/storage-filesystem/src/identity.mjs

@@ -4,17 +4,26 @@ import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protoc
 
 import { encode, nameCommittedLater, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
 
-export const STORE_VERSION = 6;
+export const STORE_VERSION = 7;
 
 export function identityPath(paths) {
   return path.join(paths.root, "protocol.json");
 }
 
-function assertIdentity(record, workspaceId, filePath) {
-  if (record?.storeVersion !== STORE_VERSION) {
-    throw new AccError(EXIT.DATA, "unknown store version", { filePath,
-      storeVersion: record?.storeVersion });
+function assertIdentity(record, workspaceId, filePath, versions = [STORE_VERSION]) {
+  if (!versions.includes(record?.storeVersion)) {
+    const message = record?.storeVersion === 6
+      ? "store contract 6 requires explicit migration: stop other store users and run acc doctor --migrate-store"
+      : "unknown store version";
+    throw new AccError(EXIT.DATA, message, { filePath,
+      storeVersion: record?.storeVersion,
+      ...(record?.storeVersion === 6 ? { reasonCode: "store_migration_required" } : {}) });
   }
+  if (Object.keys(record).sort().join(",") !== "initialisedAt,storeVersion,workspaceId"
+    || typeof record.initialisedAt !== "string" || !Number.isFinite(Date.parse(record.initialisedAt))) {
+    throw new AccError(EXIT.DATA, "invalid store identity", { filePath });
+  }
+  assertPortableId(record.workspaceId, "store workspace id");
   if (record.workspaceId !== workspaceId) {
     throw new AccError(EXIT.DATA, "store belongs to a different workspace",
       { filePath, expected: workspaceId, actual: record.workspaceId });
@@ -63,9 +72,12 @@ export async function requireStoreIdentity(paths, { workspaceId, clock, create =
 export async function readStoreIdentity(paths) {
   const found = await readJsonIfPresent(identityPath(paths), paths.root);
   if (found === null) return null;
-  if (found.value?.storeVersion !== STORE_VERSION) {
-    throw new AccError(EXIT.DATA, "unknown store version",
-      { filePath: identityPath(paths), storeVersion: found.value?.storeVersion });
-  }
-  return found.value;
+  return assertIdentity(found.value, found.value?.workspaceId, identityPath(paths));
+}
+
+export async function readMigrationIdentity(paths, workspaceId) {
+  assertPortableId(workspaceId, "workspace id");
+  const found = await readJsonIfPresent(identityPath(paths), paths.root);
+  if (found === null) throw new AccError(EXIT.DATA, "store is not initialised", { filePath: identityPath(paths) });
+  return assertIdentity(found.value, workspaceId, identityPath(paths), [6, STORE_VERSION]);
 }

package/node_modules/@agents-can-communicate/storage-filesystem/src/index-cache.mjs

@@ -0,0 +1,144 @@
+import { AccError, EXIT, TRANSACTION_INDEXES, assertIndexTuple, indexKeysFor }
+  from "@agents-can-communicate/protocol";
+import { assertPublicationDeadline } from "./deadline.mjs";
+import { createIndexIO } from "./index-io.mjs";
+import { createIndexTree } from "./index-tree.mjs";
+import { encodeIndexPage, IndexCacheUnavailable } from "./index-pages.mjs";
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const matches = (kind, record, index, tuple) => indexKeysFor(kind, record)
+  .some(key => key.index === index && same(key.tuple, tuple));
+const references = page => page.type === "branch" ? page.children.map(([, hash]) => hash)
+  : page.type === "leaf" ? [...page.entries.map(entry => entry.ids), page.next].filter(Boolean)
+    : [page.next].filter(Boolean);
+
+export function createIndexCache({ paths, root, workspaceId, publishOptions, loadPrimary }) {
+  let diagnostic = [];
+  const note = (code, reason) => { diagnostic = [{ code, reason }]; };
+  const tools = deadlineAt => {
+    const io = createIndexIO({ paths, root, publishOptions: { ...publishOptions, deadlineAt } });
+    const bounded = Object.fromEntries(Object.entries(io).map(([name, operation]) => [name, (...args) => {
+      assertPublicationDeadline(deadlineAt); return operation(...args);
+    }]));
+    return { io: bounded, tree: createIndexTree(bounded) };
+  };
+  async function valid(io, active) {
+    const manifest = await io.readManifest();
+    if (manifest === null) return null;
+    if (active.state !== "idle" || manifest.workspaceId !== workspaceId
+      || manifest.journalGeneration !== active.generation) throw new IndexCacheUnavailable("stale_manifest");
+    // Descendants are validated on their selected route. A root fault cannot
+    // be carried across an unrelated writer by simply changing its epoch.
+    for (const hash of Object.values(manifest.roots)) if (hash !== null) await io.readPage(hash);
+    return manifest;
+  }
+  async function phase(name) {
+    try { await publishOptions.failAt?.(name); }
+    catch (error) { throw new IndexCacheUnavailable("cache_publication_failed", error); }
+  }
+  async function publishManifest(io, manifest) {
+    await phase("after-index-pages");
+    await phase("before-index-manifest");
+    await io.writeManifest(manifest);
+  }
+  async function rebuild(active, deadlineAt, { required = false } = {}) {
+    // Authoritative reads stay outside every cache-error catch.
+    const primaries = await loadPrimary({ deadlineAt });
+    const deltas = Object.fromEntries(Object.keys(TRANSACTION_INDEXES).map(index => [index, []]));
+    for (const entry of primaries.values()) {
+      assertPublicationDeadline(deadlineAt);
+      if (entry.record.workspaceId !== workspaceId) {
+        throw new AccError(EXIT.DATA, "indexed primary belongs to a different workspace");
+      }
+      for (const key of indexKeysFor(entry.kind, entry.record)) deltas[key.index].push({ ...key, id: entry.id, operation: "put" });
+    }
+    const pages = new Map();
+    const tree = createIndexTree({ readPage: async hash => pages.get(hash), writePage: async page => {
+      assertPublicationDeadline(deadlineAt);
+      const { hash } = encodeIndexPage(page); pages.set(hash, page); return hash;
+    } });
+    const roots = {};
+    for (const index of Object.keys(deltas)) roots[index] = await tree.apply(null, deltas[index]);
+    const manifest = { indexVersion: 1, workspaceId, journalGeneration: active.generation, roots };
+    const { io } = tools(deadlineAt);
+    try {
+      // Publish only the final reachable tree, children before parents. The
+      // path copies made during a rebuild need never reach the filesystem.
+      const published = new Set();
+      async function publish(hash) {
+        if (hash === null || published.has(hash)) return;
+        const page = pages.get(hash);
+        for (const child of references(page)) await publish(child);
+        await io.writePage(page); published.add(hash);
+      }
+      for (const hash of Object.values(roots)) await publish(hash);
+      await publishManifest(io, manifest);
+      note("index_rebuilt", "verified_primary");
+    } catch (error) {
+      if (!(error instanceof IndexCacheUnavailable)) throw error;
+      note("index_unavailable", error.reason);
+      if (required) throw error;
+    }
+    return { manifest, tree };
+  }
+  async function lookup(index, tuple, { active, staged, deadlineAt, verify }) {
+    assertIndexTuple(index, tuple);
+    let tree, manifest;
+    try {
+      const selected = tools(deadlineAt);
+      tree = selected.tree;
+      manifest = await valid(selected.io, active);
+      if (manifest === null) throw new IndexCacheUnavailable("missing_manifest");
+      return await select(await tree.lookup(manifest.roots[index], tuple));
+    } catch (error) {
+      if (!(error instanceof IndexCacheUnavailable)) throw error;
+    }
+    ({ manifest, tree } = await rebuild(active, deadlineAt));
+    return select(await tree.lookup(manifest.roots[index], tuple));
+
+    async function select(ids) {
+      const selected = new Set(ids), kind = TRANSACTION_INDEXES[index].kind;
+      for (const entry of staged.values()) {
+        if (entry.kind !== kind) continue;
+        selected.delete(entry.id);
+        if (entry.removed !== true && matches(kind, entry.record, index, tuple)) selected.add(entry.id);
+      }
+      const result = [];
+      // Match eager listJsonFiles ordering, including prefix IDs such as a/a-b.
+      for (const id of [...selected].sort((a, b) => `${a}.json`.localeCompare(`${b}.json`))) {
+        assertPublicationDeadline(deadlineAt);
+        if (await verify(id)) result.push(id);
+      }
+      return result;
+    }
+  }
+  function prepareDeltas(loaded, staged) {
+    const deltas = [];
+    for (const [id, next] of staged) {
+      const previous = loaded.get(id);
+      const oldKeys = previous == null ? [] : indexKeysFor(previous.kind, previous.record);
+      const newKeys = next.removed === true ? [] : indexKeysFor(next.kind, next.record);
+      for (const key of oldKeys) if (!newKeys.some(found => same(found, key))) deltas.push({ ...key, id: next.id, operation: "remove" });
+      for (const key of newKeys) if (!oldKeys.some(found => same(found, key))) deltas.push({ ...key, id: next.id, operation: "put" });
+    }
+    return deltas;
+  }
+  async function commit({ before, after, deltas, deadlineAt }) {
+    try {
+      await phase("after-primary-commit");
+      const { io, tree } = tools(deadlineAt), manifest = await valid(io, before);
+      if (manifest === null) return; // An unrelated writer never constructs a cache.
+      const roots = { ...manifest.roots };
+      for (const index of Object.keys(roots)) {
+        roots[index] = await tree.apply(roots[index], deltas.filter(delta => delta.index === index));
+      }
+      await publishManifest(io, { ...manifest, roots, journalGeneration: after.generation });
+    } catch (error) {
+      if (!(error instanceof IndexCacheUnavailable)
+        && !(error.code === EXIT.CONFLICT && Date.now() >= deadlineAt)) throw error;
+      note("index_unavailable", error instanceof IndexCacheUnavailable ? error.reason : "deadline_expired");
+    }
+  }
+  return Object.freeze({ lookup, prepareDeltas, commit, rebuild,
+    diagnostics: () => diagnostic.map(item => ({ ...item })) });
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/index-io.mjs

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { assertPortableId } from "@agents-can-communicate/protocol";
+import { publishAtomic } from "./atomic-json.mjs";
+import { withRegularNoFollow } from "./safe-file.mjs";
+import { assertPageHash, decodeIndexPage, encodeIndexPage, INDEX_PAGE_BYTES, IndexCacheUnavailable }
+  from "./index-pages.mjs";
+
+function manifestShape(value) {
+  const keys = object => object && !Array.isArray(object) ? Object.keys(object).sort().join(",") : "";
+  if (keys(value) !== "indexVersion,journalGeneration,roots,workspaceId"
+    || value.indexVersion !== 1 || !/^[0-9]{16}$/.test(value.journalGeneration)
+    || keys(value.roots) !== "messageByClientKey,receiptsByMessage") {
+    throw new IndexCacheUnavailable("invalid_manifest");
+  }
+  assertPortableId(value.workspaceId, "index workspace ID");
+  for (const hash of Object.values(value.roots)) if (hash !== null) assertPageHash(hash);
+  return value;
+}
+export function createIndexIO({ paths, root, publishOptions }) {
+  const directory = path.join(root, "indexes", "v1");
+  const options = { ...publishOptions, root, tmpDir: paths.tmp, stageDir: paths.stage, durability: "none" };
+  const cache = async operation => {
+    try { return await operation(); }
+    catch (error) {
+      if (error instanceof IndexCacheUnavailable) throw error;
+      throw new IndexCacheUnavailable(error.code === "ENOENT" ? "missing_page" : "unsafe_cache_io", error);
+    }
+  };
+  const readBytes = async file => {
+    const bytes = await withRegularNoFollow(file, root, "r", (handle, stat) =>
+      stat.size > INDEX_PAGE_BYTES ? null : handle.readFile());
+    if (bytes === null) throw new IndexCacheUnavailable("page_byte_limit");
+    return bytes;
+  };
+  return Object.freeze({
+    readPage: hash => cache(async () => decodeIndexPage(assertPageHash(hash),
+      await readBytes(path.join(directory, "pages", hash + ".json")))),
+    writePage: page => cache(async () => {
+      const { hash, bytes } = encodeIndexPage(page);
+      const file = path.join(directory, "pages", hash + ".json");
+      let damaged = false;
+      try { damaged = !(await readBytes(file)).equals(bytes); }
+      catch (error) {
+        if (error instanceof IndexCacheUnavailable && error.reason === "page_byte_limit") damaged = true;
+        else if (error.code !== "ENOENT") throw error;
+      }
+      // Valid pages stay immutable. A safely opened but damaged cache file is
+      // replaced with the verified bytes for its existing content address.
+      await publishAtomic(file, bytes, { ...options, replace: damaged });
+      return hash;
+    }),
+    readManifest: () => cache(async () => {
+      let bytes;
+      try { bytes = await readBytes(path.join(directory, "cache.json")); }
+      catch (error) { if (error.code === "ENOENT") return null; throw error; }
+      try { return manifestShape(JSON.parse(bytes.toString("utf8"))); }
+      catch (error) { throw new IndexCacheUnavailable("invalid_manifest", error); }
+    }),
+    writeManifest: manifest => cache(async () => {
+      manifestShape(manifest);
+      await publishAtomic(path.join(directory, "cache.json"),
+        Buffer.from(JSON.stringify(manifest) + "\n"), { ...options, replace: true });
+    }),
+  });
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/index-pages.mjs

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { assertPortableId } from "@agents-can-communicate/protocol";
+
+export const INDEX_PAGE_BYTES = 65_536;
+export const INDEX_PAGE_ENTRIES = 32;
+const HASH = /^[a-f0-9]{64}$/;
+export class IndexCacheUnavailable extends Error {
+  constructor(reason, cause) {
+    super(`transaction index unavailable: ${reason}`, { cause });
+    this.name = "IndexCacheUnavailable";
+    this.reason = reason;
+  }
+}
+const refuse = reason => { throw new IndexCacheUnavailable(reason); };
+export function assertPageHash(hash) {
+  if (typeof hash !== "string" || !HASH.test(hash)) refuse("invalid_reference");
+  return hash;
+}
+function closed(value, keys) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).sort().join(",") !== [...keys].sort().join(",")) refuse("invalid_page_shape");
+}
+function unique(values) {
+  if (new Set(values).size !== values.length) refuse("duplicate_page_entry");
+}
+export function canonicalTuple(tuple) {
+  if (!Array.isArray(tuple) || ![2, 3].includes(tuple.length)) refuse("invalid_tuple");
+  try { tuple.forEach(id => assertPortableId(id, "index tuple member")); }
+  catch (error) { throw new IndexCacheUnavailable("invalid_tuple", error); }
+  return JSON.stringify(tuple);
+}
+function limited(values, limit = INDEX_PAGE_ENTRIES) {
+  if (!Array.isArray(values) || values.length === 0 || values.length > limit) refuse("page_entry_limit");
+}
+export function validateIndexPage(page) {
+  if (page?.type === "branch") {
+    closed(page, ["type", "children"]); limited(page.children, 16);
+    const routes = [];
+    for (const child of page.children) {
+      if (!Array.isArray(child) || child.length !== 2 || !/^[a-f0-9]$/.test(child[0])) refuse("invalid_child");
+      assertPageHash(child[1]); routes.push(child[0]);
+    }
+    unique(routes);
+    if (routes.join("") !== [...routes].sort().join("")) refuse("noncanonical_routes");
+  } else if (page?.type === "leaf") {
+    closed(page, ["type", "entries", "next"]); limited(page.entries);
+    if (page.next !== null) assertPageHash(page.next);
+    const keys = [];
+    for (const entry of page.entries) {
+      closed(entry, ["digest", "tuple", "ids"]);
+      assertPageHash(entry.digest); assertPageHash(entry.ids); keys.push(canonicalTuple(entry.tuple));
+    }
+    unique(keys);
+    if (keys.some((key, i) => i > 0 && keys[i - 1].localeCompare(key) >= 0)) refuse("noncanonical_keys");
+  } else if (page?.type === "group") {
+    closed(page, ["type", "ids", "next"]); limited(page.ids);
+    if (page.next !== null) assertPageHash(page.next);
+    try { page.ids.forEach(id => assertPortableId(id, "index record ID")); }
+    catch (error) { throw new IndexCacheUnavailable("invalid_record_id", error); }
+    unique(page.ids);
+    if (page.ids.some((id, i) => i > 0 && page.ids[i - 1].localeCompare(id) >= 0)) refuse("noncanonical_ids");
+  } else refuse("unknown_page_type");
+  return page;
+}
+export function encodeIndexPage(page) {
+  validateIndexPage(page);
+  // Fixed field order makes insertion order irrelevant to content addressing.
+  const canonical = page.type === "branch" ? { type: page.type, children: page.children }
+    : page.type === "group" ? { type: page.type, ids: page.ids, next: page.next }
+      : { type: page.type, entries: page.entries.map(({ digest, tuple, ids }) => ({ digest, tuple, ids })), next: page.next };
+  const bytes = Buffer.from(JSON.stringify(canonical) + "\n");
+  if (bytes.length > INDEX_PAGE_BYTES) refuse("page_byte_limit");
+  return { bytes, hash: createHash("sha256").update(bytes).digest("hex") };
+}
+export function decodeIndexPage(hash, bytes) {
+  assertPageHash(hash);
+  if (!Buffer.isBuffer(bytes) || bytes.length > INDEX_PAGE_BYTES) refuse("page_byte_limit");
+  let page;
+  try { page = JSON.parse(bytes.toString("utf8")); }
+  catch (error) { throw new IndexCacheUnavailable("invalid_page_json", error); }
+  const encoded = encodeIndexPage(page);
+  if (!encoded.bytes.equals(bytes)) refuse("noncanonical_bytes");
+  if (encoded.hash !== hash) refuse("page_hash_mismatch");
+  return page;
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/index-reclaim-progress.mjs

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { publishAtomic } from "./atomic-json.mjs";
+import { withRegularNoFollow } from "./safe-file.mjs";
+
+const hash = value => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const digest = bytes => createHash("sha256").update(bytes).digest("hex");
+const file = root => path.join(root, "indexes/v1/reclaim.json");
+const fresh = () => ({ version: 1, pending: [], visited: [], cursor: null, done: false });
+const valid = state => state && Object.keys(state).sort().join(",") === "cursor,done,pending,version,visited"
+  && state.version === 1 && typeof state.done === "boolean"
+  && [state.pending, state.visited].every(items => Array.isArray(items) && items.every(hash))
+  && (state.cursor === null || /^[a-f0-9]{64}\.json$/.test(state.cursor))
+  && (!state.done || state.pending.length === 0);
+
+// This is optional, checksummed bookkeeping, never primary authority. Atomic
+// replacement means process death leaves the previous complete checkpoint;
+// lost/torn bytes restart marking before any further deletion. No fsync is due.
+export async function readReclaimProgress(root) {
+  try {
+    const bytes = await withRegularNoFollow(file(root), root, "r", (handle, stat) =>
+      stat.size > 64 * 1024 * 1024 ? null : handle.readFile());
+    if (bytes === null) return fresh();
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (!valid(value.state) || value.sha256 !== digest(JSON.stringify(value.state))) return fresh();
+    return value.state.done ? fresh() : value.state;
+  } catch { return fresh(); }
+}
+
+export async function writeReclaimProgress(paths, root, state, deadlineAt) {
+  const body = JSON.stringify(state);
+  await publishAtomic(file(root), Buffer.from(JSON.stringify({ state, sha256: digest(body) }) + "\n"), {
+    root, tmpDir: paths.tmp, stageDir: paths.stage, replace: true, durability: "none", deadlineAt,
+  });
+}