agents-can-communicate 0.1.18 → 0.3.0

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

@@ -1,55 +1,28 @@
 import { AccError, EXIT } from "./errors.mjs";
 
-// recorded -> queued -> injected -> seen -> acknowledged, with failed branching
-// off before the message was ever exposed. States are monotonic: one
-// recipient's receipt can only move forwards, and never rewrites another
-// recipient's state.
-export const DELIVERY_STATES = Object.freeze(
-  ["recorded", "queued", "injected", "seen", "acknowledged", "failed"]);
+export const RECEIPT_STATES = Object.freeze(
+  ["queued", "offered", "retrieved", "acknowledged"]);
 
-const DELIVERY_NEXT = Object.freeze({
-  recorded: ["queued", "injected", "seen", "acknowledged", "failed"],
-  queued: ["injected", "seen", "acknowledged", "failed"],
-  injected: ["seen", "acknowledged"],
-  seen: ["acknowledged"],
+const RECEIPT_NEXT = Object.freeze({
+  queued: ["offered", "retrieved", "acknowledged"],
+  offered: ["retrieved", "acknowledged"],
+  retrieved: ["acknowledged"],
   acknowledged: [],
-  failed: [],
 });
 
-export const TASK_STATES = Object.freeze(
-  ["pending", "in_progress", "review", "done", "blocked"]);
-
-const TASK_NEXT = Object.freeze({
-  pending: ["in_progress", "blocked"],
-  in_progress: ["review", "done", "blocked"],
-  review: ["in_progress", "done", "blocked"],
-  blocked: ["pending", "in_progress"],
-  done: [],
-});
-
-function step(machine, allowed, label, current, next) {
-  if (!machine.includes(current)) {
-    throw new AccError(EXIT.DATA, `unknown ${label} state: ${String(current)}`,
+export function advanceReceipt(current, next) {
+  if (!RECEIPT_STATES.includes(current)) {
+    throw new AccError(EXIT.DATA, `unknown receipt state: ${String(current)}`,
       { current, next });
   }
-  if (!machine.includes(next)) {
-    throw new AccError(EXIT.DATA, `unknown ${label} state: ${String(next)}`,
+  if (!RECEIPT_STATES.includes(next)) {
+    throw new AccError(EXIT.DATA, `unknown receipt state: ${String(next)}`,
       { current, next });
   }
-  // Re-declaring the current state is idempotent. Adapters retry at safe
-  // points, and a repeated receipt is not a protocol violation.
   if (current === next) return next;
-  if (!allowed[current].includes(next)) {
+  if (!RECEIPT_NEXT[current].includes(next)) {
     throw new AccError(EXIT.CONFLICT,
-      `illegal ${label} transition from ${current} to ${next}`, { current, next });
+      `illegal receipt transition from ${current} to ${next}`, { current, next });
   }
   return next;
 }
-
-export function advanceDelivery(current, next) {
-  return step(DELIVERY_STATES, DELIVERY_NEXT, "delivery", current, next);
-}
-
-export function transitionTask(current, next) {
-  return step(TASK_STATES, TASK_NEXT, "task", current, next);
-}

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

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

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

@@ -0,0 +1,230 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import path from "node:path";
+
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
+
+import { encode, publishAtomic } from "./atomic-json.mjs";
+import { withRegularNoFollow } from "./safe-file.mjs";
+
+const ACTIVE_JOURNAL_VERSION = 2;
+const AUTHORITY_BYTES_LIMIT = 1024;
+const GENERATION_WIDTH = 16;
+const READ_ATTEMPTS = 4;
+
+const data = (message, details) => {
+  throw new AccError(EXIT.DATA, message, details);
+};
+
+export function activeJournalPath(paths, slot) {
+  if (slot !== 0 && slot !== 1) data("invalid active journal slot", { slot });
+  return path.join(paths.journal, `active.${slot}`);
+}
+
+function exactKeys(value, expected, filePath) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).sort().join("\0") !== [...expected].sort().join("\0")) {
+    data("active journal record is not closed", { filePath });
+  }
+}
+
+function checksum(record) {
+  return createHash("sha256").update(JSON.stringify(record)).digest("hex");
+}
+
+function encodeAuthority(record) {
+  return encode({ activeJournalChecksum: checksum(record), record });
+}
+
+function validateActiveRecord(record, filePath) {
+  const base = ["activeJournalVersion", "generation", "previousChecksum", "state"];
+  if (record?.state === "idle") exactKeys(record, base, filePath);
+  else if (record?.state === "open") {
+    exactKeys(record, [...base, "transactionId", "firstSequence"], filePath);
+  } else data("invalid active journal state", { filePath, state: record?.state });
+
+  if (record.activeJournalVersion !== ACTIVE_JOURNAL_VERSION) {
+    data("unknown active journal version", { filePath,
+      activeJournalVersion: record.activeJournalVersion });
+  }
+  if (typeof record.generation !== "string"
+    || !/^\d{16}$/.test(record.generation)) {
+    data("invalid active journal generation", { filePath, generation: record.generation });
+  }
+  const generation = BigInt(record.generation);
+  if (generation === 0n) {
+    if (record.state !== "idle" || record.previousChecksum !== null) {
+      data("invalid active journal genesis", { filePath });
+    }
+  } else if (typeof record.previousChecksum !== "string"
+    || !/^[0-9a-f]{64}$/.test(record.previousChecksum)) {
+    data("invalid active journal previous checksum", { filePath });
+  }
+  if (record.state === "open") {
+    assertPortableId(record.transactionId, "transaction id");
+    if (typeof record.firstSequence !== "string"
+      || !/^\d{16}$/.test(record.firstSequence)) {
+      data("invalid active journal first sequence", { filePath,
+        firstSequence: record.firstSequence });
+    }
+  }
+  return generation;
+}
+
+function decodeAuthority(bytes, filePath, slot) {
+  let envelope;
+  try {
+    envelope = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    data("invalid active journal authority", { filePath, cause: error.message });
+  }
+  exactKeys(envelope, ["activeJournalChecksum", "record"], filePath);
+  const generation = validateActiveRecord(envelope.record, filePath);
+  if (Number(generation % 2n) !== slot) {
+    data("active journal generation chain is invalid", { filePath,
+      generation: envelope.record.generation, slot });
+  }
+  if (typeof envelope.activeJournalChecksum !== "string"
+    || envelope.activeJournalChecksum !== checksum(envelope.record)) {
+    data("active journal checksum mismatch", { filePath });
+  }
+  if (!bytes.equals(encodeAuthority(envelope.record))) {
+    data("active journal authority is not canonical", { filePath });
+  }
+  return { checksum: envelope.activeJournalChecksum, generation,
+    record: envelope.record, slot };
+}
+
+async function readSlotBytes(paths, root, slot, openFile) {
+  const filePath = activeJournalPath(paths, slot);
+  try {
+    return await withRegularNoFollow(filePath, root, constants.O_RDONLY,
+      async (handle, stat) => {
+        if (stat.size < 1 || stat.size > AUTHORITY_BYTES_LIMIT) {
+          data("invalid active journal authority size", { filePath, size: stat.size });
+        }
+        return handle.readFile();
+      }, openFile);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function sameBytes(left, right) {
+  if (left === null || right === null) return left === right;
+  return left.equals(right);
+}
+
+// Slot zero is read twice. Because writers alternate slots and generations
+// never repeat, equal reads prove that the pair existed at one instant even if
+// another process published between descriptor opens.
+async function readStableSlots(paths, root, openFile) {
+  for (let attempt = 0; attempt < READ_ATTEMPTS; attempt += 1) {
+    const slot0 = await readSlotBytes(paths, root, 0, openFile);
+    const slot1 = await readSlotBytes(paths, root, 1, openFile);
+    const slot0Confirmation = await readSlotBytes(paths, root, 0, openFile);
+    if (sameBytes(slot0, slot0Confirmation)) return [slot0, slot1];
+  }
+  throw new AccError(EXIT.CONFLICT, "active journal changed while being read", {});
+}
+
+function validateTransition(current, previous, filePath) {
+  const expected = previous.state === "idle" ? "open" : "idle";
+  if (current.state !== expected) {
+    data("invalid active journal transition", { filePath,
+      previous: previous.state, current: current.state });
+  }
+}
+
+function compareGenerations(left, right) {
+  if (left.generation < right.generation) return -1;
+  if (left.generation > right.generation) return 1;
+  return 0;
+}
+
+function selectAuthority(paths, bytes) {
+  // Decode every present slot before selection. Falling back from a corrupt
+  // latest slot to an older valid peer would turn corruption into rollback.
+  const found = bytes.map((value, slot) => value === null
+    ? null
+    : decodeAuthority(value, activeJournalPath(paths, slot), slot)).filter(Boolean);
+  if (found.length === 0) return null;
+  if (found.length === 1) {
+    const [only] = found;
+    if (only.slot === 0 && only.generation === 0n) return only;
+    data("active journal authority peer is missing", { slot: only.slot,
+      generation: only.record.generation });
+  }
+  found.sort(compareGenerations);
+  const [previous, current] = found;
+  if (current.generation !== previous.generation + 1n) {
+    data("active journal generation chain is invalid", {
+      previous: previous.record.generation, current: current.record.generation });
+  }
+  if (current.record.previousChecksum !== previous.checksum) {
+    data("active journal checksum chain is invalid", { slot: current.slot });
+  }
+  validateTransition(current.record, previous.record,
+    activeJournalPath(paths, current.slot));
+  return current;
+}
+
+async function readCurrent(paths, root, openFile) {
+  return selectAuthority(paths, await readStableSlots(paths, root, openFile));
+}
+
+const genesis = () => ({ activeJournalVersion: ACTIVE_JOURNAL_VERSION,
+  generation: "0".repeat(GENERATION_WIDTH), previousChecksum: null, state: "idle" });
+
+export async function initialiseActiveJournal(paths, options) {
+  const current = await readCurrent(paths, options.root);
+  if (current !== null) return current.record;
+  try {
+    await publishAtomic(activeJournalPath(paths, 0), encodeAuthority(genesis()), options);
+  } catch (error) {
+    if (error.code !== EXIT.CONFLICT) throw error;
+  }
+  return readActiveJournal(paths, options.root);
+}
+
+export async function readActiveJournal(paths, root, openFile) {
+  const current = await readCurrent(paths, root, openFile);
+  if (current === null) data("active journal has no authority", { journal: paths.journal });
+  return current.record;
+}
+
+function nextGeneration(current) {
+  const next = current.generation + 1n;
+  const generation = next.toString().padStart(GENERATION_WIDTH, "0");
+  if (generation.length !== GENERATION_WIDTH) {
+    data("active journal generation is exhausted", { current: current.record.generation });
+  }
+  return generation;
+}
+
+async function appendTransition(paths, options, fields, expected) {
+  const current = await readCurrent(paths, options.root, options.openFile);
+  if (current === null || !expected(current.record)) {
+    throw new AccError(EXIT.CONFLICT, "active journal transition conflicts",
+      { current: current?.record ?? null, next: fields });
+  }
+  const record = { activeJournalVersion: ACTIVE_JOURNAL_VERSION,
+    generation: nextGeneration(current), previousChecksum: current.checksum, ...fields };
+  validateActiveRecord(record, activeJournalPath(paths, 1 - current.slot));
+  await publishAtomic(activeJournalPath(paths, 1 - current.slot), encodeAuthority(record),
+    { ...options, tmpDir: options.tmpDir ?? paths.tmp ?? path.join(options.root, "tmp"),
+      replace: true });
+  return record;
+}
+
+export function activateJournal(paths, options, entry) {
+  return appendTransition(paths, options, { state: "open",
+    transactionId: entry.transactionId, firstSequence: entry.firstSequence },
+    current => current.state === "idle");
+}
+
+export function idleJournal(paths, options, transactionId) {
+  return appendTransition(paths, options, { state: "idle" },
+    current => current.state === "open" && current.transactionId === transactionId);
+}

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

@@ -1,5 +1,5 @@
-import { randomUUID } from "node:crypto";
-import { link, open, readdir, rename, unlink } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { link, open, readdir, rename } from "node:fs/promises";
 import path from "node:path";
 
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
@@ -16,14 +16,6 @@ async function syncDirectory(directory) {
   }
 }
 
-async function unlinkIfPresent(filePath) {
-  try {
-    await unlink(filePath);
-  } catch (error) {
-    if (error.code !== "ENOENT") throw error;
-  }
-}
-
 export function encode(value) {
   const serialised = JSON.stringify(value, null, 2);
   if (serialised === undefined) {
@@ -41,6 +33,23 @@ async function bytesIfPresent(filePath, root, openFile) {
   }
 }
 
+function retainedStage(destination, root, tmpDir) {
+  const identity = createHash("sha256")
+    .update(path.relative(root, destination))
+    .digest("hex");
+  return path.join(tmpDir, `${identity}.published`);
+}
+
+async function replaceHandleBytes(handle, bytes) {
+  await handle.truncate(0);
+  let offset = 0;
+  while (offset < bytes.length) {
+    const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset, offset);
+    offset += bytesWritten;
+  }
+  await handle.sync();
+}
+
 /**
  * Publish bytes atomically.
  *
@@ -59,31 +68,64 @@ export async function publishAtomic(destination, bytes, { root, tmpDir, replace
     ensureManagedDirectory(root, tmpDir),
     ensureManagedDirectory(root, destinationDir),
   ]);
-  const temporary = path.join(tmpDir, `${path.basename(destination)}.${process.pid}.${randomUUID()}.tmp`);
-  const handle = await open(temporary, "wx");
+  if (!replace) {
+    const existing = await bytesIfPresent(destination, root);
+    if (existing !== null) {
+      if (existing.equals(bytes)) return "already_published";
+      throw new AccError(EXIT.CONFLICT, "record already published with different bytes",
+        { destination });
+    }
+  }
+
+  const stage = retainedStage(destination, root, tmpDir);
+  const temporary = `${stage}.${process.pid}.${randomUUID()}.tmp`;
+  let handle = await open(temporary, "wx");
+  let stageAcceptedBytes = false;
   try {
     await handle.writeFile(bytes);
     await handle.sync();
-  } finally {
-    await handle.close();
-  }
-  try {
     if (replace) {
+      await handle.close();
+      handle = null;
       await rename(temporary, destination);
       await syncDirectory(destinationDir);
       return "published";
     }
-    await link(temporary, destination);
-    await syncDirectory(destinationDir);
-    return "published";
-  } catch (error) {
-    if (error.code !== "EEXIST") throw error;
-    const existing = await bytesIfPresent(destination, root);
-    if (existing !== null && existing.equals(bytes)) return "already_published";
-    throw new AccError(EXIT.CONFLICT, "record already published with different bytes",
-      { destination });
+
+    try {
+      await link(temporary, destination);
+      stageAcceptedBytes = true;
+      await syncDirectory(destinationDir);
+      return "published";
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const existing = await bytesIfPresent(destination, root);
+      if (existing !== null && existing.equals(bytes)) {
+        stageAcceptedBytes = true;
+        return "already_published";
+      }
+      if (existing !== null) {
+        // This caller lost a different-payload race. Keep no rejected bytes:
+        // rewrite its still-open private inode with the accepted destination
+        // before consolidating every contender onto one retained stage name.
+        await replaceHandleBytes(handle, existing);
+        stageAcceptedBytes = true;
+      }
+      throw new AccError(EXIT.CONFLICT, "record already published with different bytes",
+        { destination });
+    }
   } finally {
-    await unlinkIfPresent(temporary);
+    await handle?.close();
+    if (stageAcceptedBytes) {
+      await assertManagedDirectory(root, tmpDir);
+      await rename(temporary, stage);
+      await syncDirectory(tmpDir);
+    } else {
+      // A crash/error before immutable acceptance keeps its unique partial.
+      // Retention avoids the unsafe parent-check/unlink pathname window, while
+      // the deterministic accepted stage bounds all ordinary retries.
+      await retainFile(temporary, { root });
+    }
   }
 }
 
@@ -132,6 +174,13 @@ export async function listJsonFiles(dirPath, options) {
     .sort((left, right) => left.localeCompare(right));
 }
 
-export async function removeIfPresent(filePath) {
-  await unlinkIfPresent(filePath);
+// Node exposes unlink only by pathname: directory handles cannot be passed to
+// unlinkat, so checking a parent and then unlinking still lets an adversary
+// replace that parent in between. Retention is the safe primitive. Callers
+// publish an append-only logical marker after this validation and never unlink
+// the retained path. The callback is the deterministic race seam.
+export async function retainFile(filePath, { root, afterValidation } = {}) {
+  await assertManagedDirectory(root, path.dirname(filePath));
+  await afterValidation?.();
+  return "retained";
 }

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

@@ -4,7 +4,7 @@ import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protoc
 
 import { encode, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
 
-export const STORE_VERSION = 2;
+export const STORE_VERSION = 6;
 
 export function identityPath(paths) {
   return path.join(paths.root, "protocol.json");

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

@@ -1,21 +1,51 @@
 import path from "node:path";
 
-import { AccError, EXIT } from "@agents-can-communicate/protocol";
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
 
-import { encode, listJsonFiles, publishAtomic, readJsonIfPresent, removeIfPresent }
+import { activateJournal, idleJournal, readActiveJournal } from "./active-journal.mjs";
+import { encode, publishAtomic, readJsonIfPresent, retainFile }
   from "./atomic-json.mjs";
+import { completeJournal } from "./retention.mjs";
 
-export const JOURNAL_VERSION = 1;
+export const JOURNAL_VERSION = 2;
 
-// A journal entry is written only after the transaction callback has succeeded
-// and every byte is known. Its existence therefore means "this transaction was
-// decided", which is what makes roll-forward - rather than rollback - the
-// correct recovery. Roll-forward is idempotent because publication is
-// no-replace and identical bytes are accepted as already published.
+// A journal entry is prepared only after the transaction callback has
+// succeeded and every byte is known. The subsequent synced active-log record
+// is the commit point: an orphan prepared journal is not a decided
+// transaction. Roll-forward is idempotent because identical immutable bytes
+// are accepted and materialised state carries generations.
 export function journalPath(paths, transactionId) {
+  assertPortableId(transactionId, "transaction id");
   return path.join(paths.journal, `${transactionId}.json`);
 }
 
+function publicationDestination(root, publicationPath) {
+  if (typeof publicationPath !== "string" || publicationPath === ""
+    || path.isAbsolute(publicationPath) || path.win32.isAbsolute(publicationPath)) {
+    throw new AccError(EXIT.DATA, "journal publication path must be relative",
+      { publicationPath });
+  }
+  const segments = publicationPath.split(/[\\/]/);
+  if (segments.some(segment => segment === "" || segment === "." || segment === "..")) {
+    throw new AccError(EXIT.DATA, "journal publication path is not managed",
+      { publicationPath });
+  }
+  const durablePublication = segments[0] === "events" || segments[0] === "state";
+  const stateRetention = segments[0] === "retained" && segments[1] === "state";
+  if (!(durablePublication || stateRetention)) {
+    throw new AccError(EXIT.DATA, "journal publication path is not managed",
+      { publicationPath });
+  }
+  const destination = path.resolve(root, ...segments);
+  const relative = path.relative(root, destination);
+  if (relative === "" || path.isAbsolute(relative) || relative === ".."
+    || relative.startsWith(`..${path.sep}`)) {
+    throw new AccError(EXIT.DATA, "journal publication path escapes the store root",
+      { publicationPath, root });
+  }
+  return destination;
+}
+
 export function journalEntry(transactionId, firstSequence, publications, startedAt) {
   return {
     journalVersion: JOURNAL_VERSION,
@@ -24,41 +54,61 @@ export function journalEntry(transactionId, firstSequence, publications, started
     startedAt,
     publications: publications.map(item => ({
       path: item.path,
-      // A removal is journalled like any other publication, so a crash between
-      // two deletions replays to the same end state rather than a partial one.
-      bytes: item.remove === true ? null : item.bytes.toString("base64"),
+      bytes: item.bytes.toString("base64"),
       replace: item.replace === true,
-      remove: item.remove === true,
+      retainedPath: item.retainedPath ?? null,
     })),
   };
 }
 
 export async function writeJournalEntry(paths, options, entry) {
   await publishAtomic(journalPath(paths, entry.transactionId), encode(entry), options);
+  await options.failAt?.("after-journal-prepared");
+  await activateJournal(paths, options, entry);
   return entry;
 }
 
-export async function retireJournalEntry(paths, transactionId) {
-  await removeIfPresent(journalPath(paths, transactionId));
+export async function retireJournalEntry(paths, options, transactionId) {
+  await retainFile(journalPath(paths, transactionId), { root: paths.root });
+  await completeJournal(paths, options, transactionId);
+  await options.failAt?.("before-journal-idle");
+  await idleJournal(paths, options, transactionId);
 }
 
 export async function readOpenJournals(paths, root) {
-  const files = await listJsonFiles(paths.journal, { root });
-  const entries = [];
-  for (const file of files) {
-    const found = await readJsonIfPresent(file, root);
-    if (found === null) continue;
-    const entry = found.value;
-    if (entry?.journalVersion !== JOURNAL_VERSION) {
-      throw new AccError(EXIT.DATA, "unknown journal version", { file,
-        journalVersion: entry?.journalVersion });
-    }
-    if (path.basename(file, ".json") !== entry.transactionId) {
-      throw new AccError(EXIT.DATA, "journal entry does not match its filename", { file });
+  const active = await readActiveJournal(paths, root);
+  if (active.state === "idle") return [];
+  const file = journalPath(paths, active.transactionId);
+  const found = await readJsonIfPresent(file, root);
+  if (found === null) {
+    throw new AccError(EXIT.DATA, "active journal entry is missing", { file });
+  }
+  const entry = found.value;
+  if (entry?.journalVersion !== JOURNAL_VERSION) {
+    throw new AccError(EXIT.DATA, "unknown journal version", { file,
+      journalVersion: entry?.journalVersion });
+  }
+  if (path.basename(file, ".json") !== entry.transactionId
+    || entry.transactionId !== active.transactionId
+    || entry.firstSequence !== active.firstSequence) {
+    throw new AccError(EXIT.DATA, "journal entry does not match its active record", { file });
+  }
+  assertPortableId(entry.transactionId, "transaction id");
+  if (!Array.isArray(entry.publications)) {
+    throw new AccError(EXIT.DATA, "journal publications must be an array", { file });
+  }
+  for (const publication of entry.publications) {
+    publicationDestination(root, publication?.path);
+    if (publication?.retainedPath !== null) {
+      publicationDestination(root, publication?.retainedPath);
     }
-    entries.push(entry);
   }
-  return entries.sort((left, right) => left.firstSequence.localeCompare(right.firstSequence));
+  return [entry];
+}
+
+export async function readJournalCeiling(paths, root) {
+  const active = await readActiveJournal(paths, root);
+  return active.state === "open" ? active.firstSequence : null;
 }
 
 // Publishing every listed file and then retiring the entry. Already-published
@@ -67,12 +117,10 @@ export async function readOpenJournals(paths, root) {
 export async function rollForward(paths, options, entry) {
   const published = [];
   for (const publication of entry.publications) {
-    const destination = path.resolve(options.root, publication.path);
-    if (publication.remove === true) {
-      await removeIfPresent(destination);
-      published.push(publication.path);
-      await options.failAt?.(`after:${publication.path}`);
-      continue;
+    const destination = publicationDestination(options.root, publication.path);
+    if (publication.retainedPath !== null) {
+      await retainFile(publicationDestination(options.root, publication.retainedPath),
+        { root: options.root });
     }
     const bytes = Buffer.from(publication.bytes, "base64");
     const outcome = await publishAtomic(destination, bytes,
@@ -82,6 +130,6 @@ export async function rollForward(paths, options, entry) {
     // same decided transaction.
     await options.failAt?.(`after:${publication.path}`);
   }
-  await retireJournalEntry(paths, entry.transactionId);
+  await retireJournalEntry(paths, options, entry.transactionId);
   return published;
 }