agents-can-communicate 0.9.1 → 0.10.0

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

@@ -2,7 +2,7 @@ import { AccError, EXIT, assertDecisionChange } from "@agents-can-communicate/pr
 
 // Resolve inherited recipients before retry comparison. Target messages and
 // their recipient sets are immutable, so receipt advancement cannot alter a retry.
-export function prepareDecisionChange(tx, input, session) {
+export async function prepareDecisionChange(tx, input, session) {
   if (input.decisionChange !== undefined) {
     throw new AccError(EXIT.USAGE, "send a decision change using supersedes or withdraws");
   }
@@ -15,22 +15,27 @@ export function prepareDecisionChange(tx, input, session) {
     messageIds: input.supersedes ?? input.withdraws,
   });
   decisionChange.messageIds = [...decisionChange.messageIds].sort();
-  const targets = decisionChange.messageIds.map(messageId => {
-    const message = tx.get("message", messageId);
+  const targets = [];
+  for (const messageId of decisionChange.messageIds) {
+    const message = await tx.load("message", messageId);
     if (message?.kind !== "decision" || message.workspaceId !== session.workspaceId) {
       throw new AccError(EXIT.DATA, "a decision change must reference existing decisions in this workspace",
         { messageId });
     }
-    return message;
-  });
+    targets.push(message);
+  }
   if (new Set(input.toParticipantIds).size !== input.toParticipantIds.length) {
     throw new AccError(EXIT.USAGE, "a participant may be addressed only once");
   }
-  const targetIds = new Set(decisionChange.messageIds);
-  const inherited = [...targets.map(message => message.fromParticipantId),
-    ...tx.list("receipt", receipt => targetIds.has(receipt.messageId))
-      .map(receipt => receipt.recipientParticipantId)]
-    .filter(participantId => participantId !== session.participantId);
+  const inherited = targets.map(message => message.fromParticipantId);
+  for (const message of targets) {
+    for (const id of await tx.lookup("receiptsByMessage", [session.workspaceId, message.messageId])) {
+      const receipt = await tx.load("receipt", id);
+      if (receipt !== null && receipt.workspaceId === session.workspaceId
+        && receipt.messageId === message.messageId) inherited.push(receipt.recipientParticipantId);
+    }
+  }
   return { ...input, decisionChange,
-    toParticipantIds: [...new Set([...input.toParticipantIds, ...inherited])].sort() };
+    toParticipantIds: [...new Set([...input.toParticipantIds,
+      ...inherited.filter(id => id !== session.participantId)])].sort() };
 }

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

@@ -2,6 +2,7 @@ import { AccError, EXIT, SCHEMA_VERSION, advanceReceipt }
   from "@agents-can-communicate/protocol";
 
 import { receiptId, recordMessageInTransaction } from "./conversations.mjs";
+import { assertExactTransaction } from "./ports.mjs";
 import { messagePage, messageSummary } from "./message-pages.mjs";
 import { decisionView, isCurrentDecision } from "./decision-state.mjs";
 
@@ -109,6 +110,10 @@ export function createInboxService(ports, sessions) {
     const session = await requireOpen(input, "acknowledge a message");
     const now = clock.now();
     return store.transaction(async tx => {
+      assertExactTransaction(tx);
+      await tx.load("session", input.sessionId);
+      await tx.load("message", input.messageId);
+      await tx.load("receipt", receiptId(input.messageId, session.participantId));
       await requireOpen(input, "acknowledge a message", tx);
       const { message, receipt } = requireOwnedReceipt(tx, session, input.messageId);
       if (message.obligation === "reply" && receipt.state !== "acknowledged") {
@@ -117,18 +122,21 @@ export function createInboxService(ports, sessions) {
           { messageId: input.messageId, obligation: message.obligation });
       }
       return advanceOwned(tx, session, input.messageId, "acknowledged", now).receipt;
-    }, { kinds: ["session", "message", "receipt"] });
+    }, { kinds: ["session", "message", "receipt"], exactKinds: ["session", "message", "receipt"] });
   }
 
   async function replyToMessage(input) {
     const session = await requireOpen(input, "reply to a message");
     const now = clock.now();
     const replyId = ids.next("message");
-    return store.transaction(tx => {
+    return store.transaction(async tx => {
+      assertExactTransaction(tx);
+      await tx.load("message", input.messageId);
+      await tx.load("receipt", receiptId(input.messageId, session.participantId));
       const original = requireOwnedReceipt(tx, session, input.messageId);
       // A receipt settles delivery, not the conversation. Distinct replies may
       // follow an ack or an earlier answer; recording still enforces retry keys.
-      const recorded = recordMessageInTransaction({ tx, session, now, messageId: replyId, ids,
+      const recorded = await recordMessageInTransaction({ tx, session, now, messageId: replyId, ids,
         action: "reply to a message", input: {
           clientMessageId: input.clientMessageId,
           toParticipantIds: [original.message.fromParticipantId],
@@ -142,7 +150,7 @@ export function createInboxService(ports, sessions) {
         } });
       const receipt = advanceOwned(tx, session, input.messageId, "acknowledged", now).receipt;
       return { reply: recorded.message, receipt };
-    }, { kinds: ["participant", "session", "message", "receipt"] });
+    }, { kinds: ["participant", "session", "message", "receipt"], exactKinds: ["message", "receipt"] });
   }
 
   return { listInbox, readInbox, replyToMessage, acknowledgeMessage };

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

@@ -0,0 +1,43 @@
+import { isDeepStrictEqual } from "node:util";
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+const logicalContent = message => ({
+  toParticipantIds: message.toParticipantIds,
+  kind: message.kind,
+  obligation: message.obligation,
+  subject: message.subject,
+  body: message.body,
+  inReplyTo: message.inReplyTo,
+  artifacts: message.artifacts,
+  handoff: message.handoff,
+  decisionChange: message.decisionChange ?? null,
+});
+
+const normalizedContent = input => logicalContent({
+  toParticipantIds: input.toParticipantIds ?? [],
+  kind: input.kind,
+  obligation: input.obligation,
+  subject: input.subject,
+  body: input.body,
+  inReplyTo: input.inReplyTo ?? null,
+  artifacts: input.artifacts ?? [],
+  handoff: input.handoff ?? null,
+  decisionChange: input.decisionChange,
+});
+
+export async function findMessageRetry(tx, session, input) {
+  const candidates = await tx.lookup("messageByClientKey",
+    [session.workspaceId, session.participantId, input.clientMessageId]);
+  for (const id of candidates) {
+    const existing = await tx.load("message", id);
+    if (existing === null || existing.workspaceId !== session.workspaceId
+      || existing.fromParticipantId !== session.participantId
+      || existing.clientMessageId !== input.clientMessageId) continue;
+    if (!isDeepStrictEqual(logicalContent(existing), normalizedContent(input))) {
+      throw new AccError(EXIT.CONFLICT,
+        "clientMessageId was already used with different message content",
+        { clientMessageId: input.clientMessageId, messageId: existing.messageId });
+    }
+    return existing;
+  }
+}

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

@@ -4,12 +4,14 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
  * @typedef {{ now(): string }} Clock
  * @typedef {{ next(kind: string): string }} IdSource
  * @typedef {{ get(kind: string, id: string): object | null,
+ *   load(kind: string, id: string): Promise<object | null>,
+ *   lookup(index: string, tuple: string[]): Promise<string[]>,
  *   generationOf(kind: string, id: string): string | null,
  *   list(kind: string, predicate?: (record: object) => boolean): object[],
  *   put(kind: string, id: string, record: object, expectedGeneration?: string | null): string,
  *   append(event: object): object }} CoordinationTransaction
  * @typedef {{ transaction(callback: (tx: CoordinationTransaction) => unknown,
- *   options?: { kinds?: string[], deadlineAt?: number }): Promise<unknown>,
+ *   options?: { kinds?: string[], exactKinds?: string[], deadlineAt?: number }): Promise<unknown>,
  *   eventsSince(workspaceId: string, cursor: string | null, limit: number): Promise<object>,
  *   snapshot(workspaceId: string): Promise<object> }} CoordinationStore
  */
@@ -26,6 +28,15 @@ const REQUIRED = Object.freeze({
 // vanish with their session.
 const EPHEMERAL = ["get", "put", "update", "delete", "list"];
 
+export function assertExactTransaction(tx) {
+  for (const method of ["load", "lookup"]) {
+    if (typeof tx?.[method] !== "function") {
+      throw new AccError(EXIT.USAGE, `the exact transaction port must implement ${method}()`,
+        { port: "store.transaction", method });
+    }
+  }
+}
+
 // Ports are validated at construction rather than at first use. A core that
 // silently falls back to ambient time or randomness produces tests that pass
 // for the wrong reason and races that only appear on someone else's machine.

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.1",
+  "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.1",
+  "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.1",
+  "version": "0.10.0",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.9.1",
+  "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.1",
+  "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.1",
+  "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 });
+    }),
+  });
+}