agents-can-communicate 0.6.3 → 0.7.1

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

@@ -0,0 +1,272 @@
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { readActiveJournal } from "./active-journal.mjs";
+import { listDirectoryEntries, readJsonIfPresent } from "./atomic-json.mjs";
+import { condemn, detachDoomed, discard, discardLeftovers, expired } from "./doomed-directory.mjs";
+import { assertSequence, raiseEventFloor, readEventFloor } from "./event-floor.mjs";
+import { statePath } from "./record-id.mjs";
+
+// Shared with the stage sweep that calls this, so one pass cannot spend two
+// budgets. Exported for the caller that wants to reclaim without a bound.
+export const RECLAIM_BUDGET = 512;
+
+const jsonNames = async (directory, root) =>
+  (await listDirectoryEntries(directory, { root }))
+    .filter(entry => entry.isFile() && entry.name.endsWith(".json"))
+    .map(entry => entry.name);
+
+/**
+ * Which transaction the store is in the middle of, or null when it cannot tell.
+ *
+ * `readActiveJournal` throws on a store with no authority record. Not knowing
+ * which entry is active is not a licence to guess, so that answer suppresses
+ * journal reclamation rather than failing the store open it runs inside.
+ *
+ * It suppresses it without holding the pass open. A store missing its authority
+ * is one `openFilesystemStore` would have initialised, so it is broken rather
+ * than busy, and doctor is what reports a broken store. Reporting work as
+ * remaining would re-run this pass on every open forever, to keep finding the
+ * same answer about files that are inert either way.
+ */
+async function activeTransaction(paths, root) {
+  try {
+    const active = await readActiveJournal(paths, root);
+    return { known: true, transactionId: active.state === "open" ? active.transactionId : null };
+  } catch {
+    return { known: false, transactionId: null };
+  }
+}
+
+/**
+ * Condemn every journal entry that has been retired, with its completion marker.
+ *
+ * `retireJournalEntry` calls `retainFile`, which by construction never unlinks,
+ * so a completed entry was kept forever; `completeJournal` then wrote a marker
+ * that nothing reads. Both halves go together: a marker outliving its entry
+ * records the completion of a file nothing can find.
+ *
+ * The marker directory is listed once rather than read per entry. A workspace
+ * in daily use reaches thousands of retired transactions, and one open each
+ * would be the cost this pass exists to remove.
+ */
+async function condemnRetiredJournals(paths, root, doomed, budget, deadlineAt) {
+  let spent = 0;
+  const active = await activeTransaction(paths, root);
+  if (!active.known) return { spent, drained: true };
+
+  const markerDirectory = path.join(paths.retained, "journal");
+  const completed = new Set(await jsonNames(markerDirectory, root));
+  for (const name of await jsonNames(paths.journal, root)) {
+    if (spent + 2 > budget || expired(deadlineAt)) return { spent, drained: false };
+    if (!completed.has(name)) continue;
+    // The marker is written before the pointer goes idle, so a crash between
+    // the two leaves a completed marker on the entry recovery still owns.
+    if (path.basename(name, ".json") === active.transactionId) continue;
+    await condemn(path.join(paths.journal, name), doomed);
+    await condemn(path.join(markerDirectory, name), doomed);
+    spent += 2;
+  }
+  return { spent, drained: true };
+}
+
+// Ordered as numbers, not as strings: a sequence can outgrow its padding, which
+// is the same reason latestEphemeralMarker sorts this way. A name that is not a
+// sequence is left alone rather than guessed at.
+function supersededNames(names) {
+  const sequenced = names.map(name => {
+    const digits = path.basename(name, ".json");
+    return /^\d+$/.test(digits) ? { name, order: BigInt(digits) } : null;
+  }).filter(Boolean).sort((left, right) => (left.order < right.order ? 1 : -1));
+  return sequenced.slice(1).map(entry => entry.name);
+}
+
+/**
+ * Condemn every ephemeral retention marker except the newest of each record.
+ *
+ * `latestEphemeralMarker` reads only the newest and lists the rest to find it,
+ * so an older marker is pure listing cost on a path that runs inside hooks.
+ */
+async function condemnSupersededMarkers(paths, root, doomed, budget, deadlineAt) {
+  let spent = 0;
+  const area = path.join(paths.retained, "ephemeral");
+  for (const kind of await listDirectoryEntries(area, { root })) {
+    if (!kind.isDirectory()) continue;
+    const kindDirectory = path.join(area, kind.name);
+    for (const record of await listDirectoryEntries(kindDirectory, { root })) {
+      if (!record.isDirectory()) continue;
+      const directory = path.join(kindDirectory, record.name);
+      for (const name of supersededNames(await jsonNames(directory, root))) {
+        if (spent >= budget || expired(deadlineAt)) return { spent, drained: false };
+        await condemn(path.join(directory, name), doomed);
+        spent += 1;
+      }
+    }
+  }
+  return { spent, drained: true };
+}
+
+/**
+ * Reclaim what the store keeps and no longer reads.
+ *
+ * Both classes are provably unread - a retired journal entry has no reader at
+ * all, and a superseded ephemeral marker is skipped by the only function that
+ * looks - which is what lets this run without an operator asking. Anything that
+ * carries meaning waits for `acc prune`.
+ *
+ * @returns {Promise<{ reclaimed: number, remaining: boolean }>}
+ */
+export async function reclaimRetired(paths,
+  { root, limit = RECLAIM_BUDGET, deadlineAt } = {}) {
+  if (expired(deadlineAt)) return { reclaimed: 0, remaining: true };
+  let spent = 0;
+
+  const leftovers = await discardLeftovers(root, limit, deadlineAt);
+  spent += leftovers.spent;
+  // What a previous pass already moved has left its live name; removing it is
+  // what reclaims it, so it counts here exactly as this pass's own work does.
+  let reclaimed = leftovers.spent;
+  if (!leftovers.drained) return { reclaimed, remaining: true };
+
+  const doomed = await detachDoomed(root);
+  const journals = await condemnRetiredJournals(paths, root, doomed, limit - spent, deadlineAt);
+  spent += journals.spent;
+  const markers = journals.drained
+    ? await condemnSupersededMarkers(paths, root, doomed, limit - spent, deadlineAt)
+    : { spent: 0, drained: false };
+  spent += markers.spent;
+
+  const removed = await discard(doomed, root, limit - spent, deadlineAt);
+  reclaimed += removed.spent;
+  return { reclaimed,
+    remaining: !journals.drained || !markers.drained || !removed.drained };
+}
+
+/**
+ * Reclaim named state records, each with every retention marker it owns.
+ *
+ * `tx.remove` is the wrong instrument here and the difference matters. It
+ * publishes a deletion marker, which hides the record and *adds* a file, and
+ * `listState` then reads the record before asking whether that marker exists.
+ * Removing records that way would make the store larger and its listings
+ * slower, which is the opposite of what an operator ran this for. A marker only
+ * exists because the store cannot unlink a live name; when the record itself
+ * can be moved out, the marker has nothing left to say.
+ *
+ * `generation` is the caller's optimistic lock. Eligibility is decided from a
+ * snapshot and applied later, and a claim can be renewed in between, which
+ * writes a new generation onto the same id. A record that no longer matches is
+ * skipped rather than removed: it is no longer the record that was judged.
+ *
+ * @param {{kind: string, id: string, generation: string}[]} entries
+ * @returns {Promise<{ reclaimed: number, skipped: number, remaining: boolean }>}
+ */
+export async function reclaimStateRecords(paths, entries,
+  { root, limit = RECLAIM_BUDGET, deadlineAt } = {}) {
+  if (expired(deadlineAt)) return { reclaimed: 0, skipped: 0, remaining: entries.length > 0 };
+  let spent = 0;
+  let skipped = 0;
+
+  const leftovers = await discardLeftovers(root, limit, deadlineAt);
+  spent += leftovers.spent;
+  if (!leftovers.drained) {
+    return { reclaimed: leftovers.spent, skipped, remaining: true };
+  }
+
+  const doomed = await detachDoomed(root);
+  let condemned = 0;
+  let drained = true;
+  for (const entry of entries) {
+    // Two condemnations per record, asked for together, so a budget never
+    // leaves a record half removed - its markers gone and the record itself
+    // still listed, which would read as a live record whose deletion history
+    // had been erased.
+    if (spent + 2 > limit || expired(deadlineAt)) {
+      drained = false;
+      break;
+    }
+    const filePath = statePath(paths, entry.kind, entry.id);
+    const found = await readJsonIfPresent(filePath, root).catch(() => null);
+    if (found === null || found.value?.generation !== entry.generation) {
+      skipped += 1;
+      continue;
+    }
+    await condemn(filePath, doomed);
+    spent += 1;
+    condemned += 1;
+    try {
+      await condemn(path.join(paths.retained, "state", entry.kind, entry.id), doomed);
+      spent += 1;
+      // Counted only when it moved. Most records own no marker directory at
+      // all, and counting one anyway made `remaining` compare what was
+      // condemned against a number larger than could ever be discarded - so a
+      // finished pass reported work left and asked to be run again forever.
+      condemned += 1;
+    } catch (error) {
+      // A record whose generation was never superseded owns no markers.
+      // Nothing to move is the ordinary case, not a fault.
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+
+  const removed = await discard(doomed, root, limit - spent, deadlineAt);
+  return { reclaimed: leftovers.spent + removed.spent, skipped,
+    remaining: !drained || !removed.drained || removed.spent < condemned };
+}
+
+/**
+ * Trim the event log to a boundary, reclaiming every event at or below it.
+ *
+ * The floor is raised before a single file moves, and that order is the whole
+ * safety argument. A floor ahead of the trim reports a boundary for events that
+ * are still present, which costs a reader nothing. A trim ahead of the floor is
+ * a silent gap, which is the failure the floor exists to prevent.
+ *
+ * @returns {Promise<{ reclaimed: number, trimmedThrough: string, remaining: boolean }>}
+ */
+export async function trimEventLog(paths, boundary,
+  { root, publish, limit = RECLAIM_BUDGET, deadlineAt } = {}) {
+  assertSequence(boundary, "before");
+  if (expired(deadlineAt)) {
+    return { reclaimed: 0, trimmedThrough: (await readEventFloor(paths, root)) ?? boundary,
+      remaining: true };
+  }
+
+  const names = (await jsonNames(paths.events, root)).sort();
+  const newest = names.at(-1);
+  const allocated = newest === undefined
+    ? await readEventFloor(paths, root)
+    : path.basename(newest, ".json");
+  // A boundary past what this store has ever issued is not a point in its
+  // history. Persisting one would raise the floor above every sequence that can
+  // still be allocated, so a single mistyped cursor would leave a workspace
+  // that can never publish again. Refused rather than clamped: an operator who
+  // named the wrong cursor should hear about it.
+  if (allocated === null || boundary > allocated) {
+    throw new AccError(EXIT.USAGE,
+      "before is past the newest event this workspace has issued",
+      { before: boundary, newest: allocated });
+  }
+  const trimmedThrough = await raiseEventFloor(paths, { ...publish, root }, boundary);
+
+  let spent = 0;
+  let drained = true;
+  const doomed = await detachDoomed(root);
+  for (const name of names) {
+    // Sequences are fixed-width, so comparing the names is comparing the
+    // numbers, and the sorted listing lets this stop at the boundary rather
+    // than walk a log that is mostly newer than it.
+    if (path.basename(name, ".json") > boundary) break;
+    if (spent >= limit || expired(deadlineAt)) {
+      drained = false;
+      break;
+    }
+    await condemn(path.join(paths.events, name), doomed);
+    spent += 1;
+  }
+
+  const removed = await discard(doomed, root, limit - spent, deadlineAt);
+  return { reclaimed: removed.spent, trimmedThrough,
+    remaining: !drained || !removed.drained };
+}

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

@@ -3,22 +3,62 @@ import path from "node:path";
 import { AccError, EXIT, validateRecord } from "@agents-can-communicate/protocol";
 
 import { listDirectoryEntries, listJsonFiles, readJsonIfPresent } from "./atomic-json.mjs";
+import { readEventFloor } from "./event-floor.mjs";
 import { readStoreIdentity } from "./identity.mjs";
 import { readOpenJournals, rollForward } from "./journal.mjs";
 import { assertEventBinding, assertStateBinding } from "./record-id.mjs";
+import { reclaimRetired } from "./reclaim.mjs";
+import { sweepAcceptedStages } from "./stage-sweep.mjs";
 import { storePaths } from "./store.mjs";
 import { withWriterMutex } from "./writer-mutex.mjs";
 
 /** @typedef {{ healthy: boolean, repaired: string[], blocked: string[],
- * corrupt: string[] }} RepairReport */
+ * corrupt: string[], swept: number, staged: number, partials: number, retired: number,
+ * trimmedThrough: string|null }} RepairReport */
 
-const report = ({ repaired = [], blocked = [], corrupt = [] }) => ({
+const report = ({ repaired = [], blocked = [], corrupt = [], swept = 0, staged = 0,
+  partials = 0, retired = 0, trimmedThrough = null }) => ({
   healthy: blocked.length === 0 && corrupt.length === 0,
   repaired: [...repaired].sort(),
   blocked: [...blocked].sort(),
   corrupt: [...corrupt].sort(),
+  swept,
+  staged,
+  partials,
+  retired,
+  trimmedThrough,
 });
 
+// Counting, never touching. A stage held in tmp by an older version is an
+// accepted stage wherever it sits, so both places are counted as staged, while
+// a partial is only ever the unfinished temporary a failed publication left.
+async function countStaging(paths, root) {
+  const entries = async directory => {
+    try {
+      return await listDirectoryEntries(directory, { root });
+    } catch (error) {
+      if (error.code === "ENOENT") return [];
+      throw error;
+    }
+  };
+  const accepted = name => name.endsWith(".published");
+  const staged = (await entries(paths.stage)).filter(entry => entry.isFile()
+    && accepted(entry.name)).length;
+  const inTmp = await entries(paths.tmp);
+  // A retired journal entry is one the store keeps and never reads again, so
+  // counting them is what tells an operator the automatic pass has work left.
+  const completed = new Set((await entries(path.join(paths.retained, "journal")))
+    .filter(entry => entry.isFile()).map(entry => entry.name));
+  const retired = (await entries(paths.journal))
+    .filter(entry => entry.isFile() && completed.has(entry.name)).length;
+  return {
+    staged: staged + inTmp.filter(entry => accepted(entry.name)).length,
+    partials: inTmp.filter(entry => entry.name.endsWith(".tmp")).length,
+    retired,
+    trimmedThrough: await readEventFloor(paths, root),
+  };
+}
+
 async function inspect(root) {
   const paths = storePaths(root);
   const blocked = [];
@@ -82,6 +122,7 @@ export async function diagnoseFilesystemStore({ root }) {
     blocked: state.blocked,
     corrupt: state.corrupt,
     repaired: state.pending.map(entry => entry.transactionId),
+    ...await countStaging(state.paths, root),
   });
 }
 
@@ -92,18 +133,24 @@ export async function repairFilesystemStore({ root, clock }) {
     // would turn an ambiguous store into a confidently wrong one.
     return report({ blocked: state.blocked, corrupt: state.corrupt });
   }
-  if (state.pending.length === 0) return report({});
-
-  const repaired = await withWriterMutex(state.paths, { root, tmpDir: state.paths.tmp, clock },
+  // No early return for an empty journal any more: a store with nothing to roll
+  // forward is exactly the store whose staging directory needs reclaiming.
+  return withWriterMutex(state.paths, { root, tmpDir: state.paths.tmp, clock },
     async () => {
       const completed = [];
       for (const entry of await readOpenJournals(state.paths, root)) {
         await rollForward(state.paths, { root, tmpDir: state.paths.tmp, clock }, entry);
         completed.push(entry.transactionId);
       }
-      return completed;
+      // An operator is waiting on this and a hook is not, so the sweep runs
+      // without the per-pass bound the automatic one obeys.
+      // An operator is waiting on this, and a hook is not, so neither pass is
+      // bounded here.
+      const { swept } = await sweepAcceptedStages(state.paths, { root, limit: Infinity });
+      const reclaimed = await reclaimRetired(state.paths, { root, limit: Infinity });
+      return report({ repaired: completed, swept: swept + reclaimed.reclaimed,
+        ...await countStaging(state.paths, root) });
     });
-  return report({ repaired });
 }
 
 export function assertRepairable(reportValue) {

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

@@ -0,0 +1,174 @@
+import { rename } from "node:fs/promises";
+import path from "node:path";
+
+import { EXIT } from "@agents-can-communicate/protocol";
+
+import { encode, listDirectoryEntries, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
+import { discard, discardLeftovers, doomedName, expired, syncDirectory }
+  from "./doomed-directory.mjs";
+import { reclaimRetired } from "./reclaim.mjs";
+import { ensureManagedDirectory } from "./safe-directory.mjs";
+
+// One pass never touches more than this many entries, counting both the legacy
+// entries it moves and the entries it discards. A store left unopened can hold
+// as many accepted stages as an unswept tmp/ did - tens of thousands - and an
+// unbounded removal inside a hook is the budget failure this exists to avoid.
+export const SWEEP_BUDGET = 512;
+
+// A day between passes. A count-based threshold costs either a full listing of
+// the directory this keeps small, or an fsync'ed write on every transaction. A
+// timestamp costs one read.
+export const SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+// An older ACC keeps renaming accepted stages onto tmp, because it does not
+// know stage exists, so this is a standing rule rather than a one-off
+// migration. They are moved rather than unlinked: joining the doomed directory
+// costs one rename and keeps the no-unlink rule intact. A partial from a failed
+// publication does not end in .published and never moves.
+async function reclaimLegacy(paths, root, detached, budget, deadlineAt) {
+  let spent = 0;
+  for (const entry of await listDirectoryEntries(paths.tmp, { root })) {
+    if (spent >= budget || expired(deadlineAt)) return { spent, drained: false };
+    if (!entry.isFile() || !entry.name.endsWith(".published")) continue;
+    await rename(path.join(paths.tmp, entry.name), path.join(detached, entry.name));
+    spent += 1;
+  }
+  return { spent, drained: true };
+}
+
+/**
+ * Empty the store's accepted staging directory.
+ *
+ * `spent` is what the budget bought, which the caller needs to give whatever
+ * runs next the part of the budget this pass did not use.
+ *
+ * @returns {Promise<{ swept: number, remaining: boolean, spent: number }>}
+ */
+export async function sweepAcceptedStages(paths,
+  { root, limit = SWEEP_BUDGET, deadlineAt } = {}) {
+  // Two counters, because they answer different questions. `spent` is what the
+  // budget bought: moving a legacy entry and removing one both cost a syscall
+  // on the same directory. `swept` is what left the store, and a legacy entry
+  // that was only moved has not left it yet. Counting a move as a sweep would
+  // report two reclaimed records where one record was reclaimed.
+  let spent = 0;
+  let swept = 0;
+  let remaining = false;
+
+  // Finish what an interrupted pass left before starting another one. This runs
+  // first for a second reason: a pass that stops here never detaches a further
+  // directory, so an exhausted budget cannot make them accumulate.
+  const leftovers = await discardLeftovers(root, limit, deadlineAt);
+  spent += leftovers.spent;
+  swept += leftovers.spent;
+  if (!leftovers.drained) return { swept, remaining: true, spent };
+
+  const detached = doomedName(root);
+  // A store written by an older version has no stage directory at all, because
+  // nothing ever published into one. Creating it before the detach makes that
+  // the ordinary case rather than an error, and such a store is exactly the one
+  // whose accepted stages are all still in tmp for the reclamation below.
+  await ensureManagedDirectory(root, paths.stage);
+  await rename(paths.stage, detached);
+  await ensureManagedDirectory(root, paths.stage);
+  await syncDirectory(root);
+
+  const reclaimed = await reclaimLegacy(paths, root, detached, limit - spent, deadlineAt);
+  spent += reclaimed.spent;
+  if (!reclaimed.drained) return { swept, remaining: true, spent };
+
+  const removed = await discard(detached, root, limit - spent, deadlineAt);
+  spent += removed.spent;
+  swept += removed.spent;
+  if (!removed.drained) remaining = true;
+  return { swept, remaining, spent };
+}
+
+const markerPath = paths => path.join(paths.locks, "stage-sweep.json");
+
+// A lost lock and a lapsed budget are the same answer: not now, next open. They
+// both arrive as CONFLICT, and neither is a reason to fail the caller.
+async function withLockTolerantly(withLock, operation) {
+  try {
+    return await withLock(operation);
+  } catch (error) {
+    if (error?.code !== EXIT.CONFLICT) throw error;
+    return { swept: 0, remaining: true };
+  }
+}
+
+// An unreadable marker means the interval is unknown, and an unknown interval
+// is treated as due: maintenance that refuses to run because its own bookkeeping
+// is damaged is the failure it exists to prevent.
+async function sweptAt(paths, root) {
+  const found = await readJsonIfPresent(markerPath(paths), root).catch(() => null);
+  const value = Date.parse(found?.value?.sweptAt ?? "");
+  return Number.isNaN(value) ? null : value;
+}
+
+/**
+ * Sweep only when the recorded pass is older than SWEEP_INTERVAL_MS.
+ *
+ * The due check is one read and it happens before the lock. Sweeping is a
+ * write and needs the writer mutex, but taking that mutex is itself a mkdir, a
+ * write, an fsync and a rename, and this runs on every store open - which means
+ * inside every hook. Paying for the lock on the days there is nothing to sweep
+ * would put that cost on every hook to do nothing, which is the shape of the
+ * slowdown that made hooks time out in 0.6.1.
+ *
+ * `withLock` is the seam: production passes the writer mutex, tests count calls.
+ *
+ * @returns {Promise<{ swept: number, remaining: boolean }>}
+ */
+export async function sweepIfDue(paths,
+  { root, clock, limit = SWEEP_BUDGET, deadlineAt, withLock = operation => operation() } = {}) {
+  // Nothing below tolerates an expired budget: withWriterMutex refuses one, and
+  // so does the publishAtomic that writes the marker. Leaving the work for the
+  // next open is the whole point of a bounded pass, so leave before the first
+  // call that would throw instead of failing the open this runs inside.
+  if (expired(deadlineAt)) return { swept: 0, remaining: true };
+
+  const now = Date.parse(clock.now());
+  const last = await sweptAt(paths, root);
+  if (last !== null && now - last < SWEEP_INTERVAL_MS) return { swept: 0, remaining: false };
+
+  // The budget can lapse after the check above: the lock may be granted late,
+  // or granted to someone else first. Both arrive as CONFLICT, from the mutex
+  // or from the publishAtomic that writes the marker. Leaving that pass for the
+  // next open is the bounded behaviour working, so it is answered here rather
+  // than left for whoever called - maintenance never decides whether a store
+  // can be opened. Every other fault is a real store problem and propagates.
+  return withLockTolerantly(withLock, async () => {
+    // Re-read under the lock: another process may have swept while this one
+    // waited for it, and two sweeps in a row would detach an empty directory
+    // for nothing.
+    const holder = await sweptAt(paths, root);
+    if (holder !== null && holder !== last && Date.parse(clock.now()) - holder < SWEEP_INTERVAL_MS) {
+      return { swept: 0, remaining: false };
+    }
+    const stages = await sweepAcceptedStages(paths, { root, limit, deadlineAt });
+    // One budget for the whole pass. The reclaimer gets what the stage sweep
+    // did not spend, so opening a store never pays the bound twice, and a stage
+    // sweep that ran out leaves the reclaimer for the next open rather than
+    // borrowing against it.
+    const retired = stages.remaining
+      ? { reclaimed: 0, remaining: true }
+      : await reclaimRetired(paths, { root, limit: limit - stages.spent, deadlineAt });
+    const result = { swept: stages.swept + retired.reclaimed,
+      remaining: stages.remaining || retired.remaining };
+    // The marker records a *finished* pass, never an attempted one. A pass that
+    // stopped at its entry budget or ran out of time leaves it unwritten, so
+    // the next open carries on immediately. Recording an unfinished pass as
+    // done would park the remainder for a whole interval: a store holding
+    // 17,880 entries would drain over weeks rather than over a few opens.
+    //
+    // Writing it after an expired deadline would also throw, since
+    // publishAtomic refuses one - out of the store open this runs inside.
+    if (result.remaining || expired(deadlineAt)) {
+      return { swept: result.swept, remaining: true };
+    }
+    await publishAtomic(markerPath(paths), encode({ sweptAt: clock.now() }),
+      { root, tmpDir: paths.tmp, stageDir: paths.stage, replace: true, deadlineAt });
+    return result;
+  });
+}