agents-can-communicate 0.6.3 → 0.7.1

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

@@ -16,6 +16,9 @@ import { assertEventBinding, assertStateBinding, eventPath, stateEnvelope, state
 import { ephemeralIsDeleted, markEphemeral, stateDeletionPublication,
   stateGenerationIsDeleted } from "./retention.mjs";
 import { ensureManagedDirectory } from "./safe-directory.mjs";
+import { readEventFloor } from "./event-floor.mjs";
+import { reclaimStateRecords, trimEventLog } from "./reclaim.mjs";
+import { sweepIfDue } from "./stage-sweep.mjs";
 import { withWriterMutex } from "./writer-mutex.mjs";
 
 // Kept cohesive above 300 lines because durable transactions and ephemeral
@@ -29,7 +32,15 @@ export const ZERO_CURSOR = "0".repeat(SEQUENCE_WIDTH);
 // corrupt record, so nothing ever had a reason to put one aside. An empty
 // directory that reads as a feature is the same mistake as an attention kind
 // with no rule behind it. If quarantining is ever built, it comes back with it.
-const DIRECTORIES = ["state", "events", "journal", "locks", "ephemeral", "retained", "tmp"];
+//
+// `stage` is the counter-example that keeps that rule rather than breaking it:
+// every immutable publication fills it and stage-sweep.mjs empties it. Holding
+// accepted stages apart from the partials in `tmp` is what lets the sweep
+// remove a whole directory instead of deciding file by file from a filename
+// suffix. A `stage` ever found empty by design rather than by sweeping is the
+// mistake described above, and should go.
+const DIRECTORIES = ["state", "events", "journal", "locks", "ephemeral", "retained", "tmp",
+  "stage"];
 
 const pad = value => String(value).padStart(SEQUENCE_WIDTH, "0");
 
@@ -68,7 +79,24 @@ async function loadAllState(paths, root, wanted = null) {
 
 async function nextSequence(paths, root) {
   const last = (await listJsonFiles(paths.events, { root })).at(-1);
-  return last === undefined ? 1 : Number(path.basename(last, ".json")) + 1;
+  // Only an empty directory consults the floor, so the path every transaction
+  // runs pays nothing for retention. Trimming removes the oldest events, so
+  // while any file remains the newest one still answers this. A log trimmed
+  // away entirely is the case that would otherwise restart at 1 and hand out a
+  // sequence a peer already holds a cursor for.
+  const highest = last === undefined
+    ? await readEventFloor(paths, root)
+    : path.basename(last, ".json");
+  if (highest === null) return 1;
+  // Counted as a BigInt whichever side it came from. A 16-digit sequence
+  // reaches past Number.MAX_SAFE_INTEGER, where adding one stops changing the
+  // value, so a Number here would eventually hand out a sequence twice.
+  // Refusing is the only honest answer left at that point.
+  const next = BigInt(highest) + 1n;
+  if (next > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new AccError(EXIT.DATA, "event sequence is exhausted", { highest });
+  }
+  return Number(next);
 }
 
 export async function openFilesystemStore({ root, clock, ids, workspaceId, failAt,
@@ -93,6 +121,18 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
   // must not roll the same journal forward concurrently.
   await recoverOpenJournals();
 
+  // Sweeping is a write, so it holds the same mutex recovery does and no
+  // publisher is in flight while the stage directory is detached. It is bounded
+  // per pass: a store carrying a large accumulation drains over several opens
+  // rather than spending one hook's whole budget on it. The mutex is taken only
+  // on the opens that actually sweep - see sweepIfDue, which decides before it
+  // locks, because this runs inside every hook.
+  // Maintenance never decides whether a store can be opened: sweepIfDue answers
+  // a lost lock and a lapsed budget itself, and raises only real store faults.
+  await sweepIfDue(paths, { root, clock, deadlineAt: storeDeadline,
+    withLock: operation => withWriterMutex(paths,
+      { root, tmpDir: paths.tmp, clock, deadlineAt: storeDeadline }, operation) });
+
   async function recoverOpenJournals() {
     const open = await readOpenJournals(paths, root);
     if (open.length === 0) return [];
@@ -253,7 +293,11 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
       events.push(event);
       if (events.length === limit) break;
     }
-    return { cursor: events.at(-1)?.sequence ?? after, events };
+    // A caller whose cursor precedes the boundary is served what is left and
+    // told where the log now starts. A short page that reads like a complete
+    // one is the failure trimming must not introduce.
+    return { cursor: events.at(-1)?.sequence ?? after, events,
+      trimmedThrough: await readEventFloor(paths, root) };
   }
 
   /**
@@ -365,6 +409,54 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
     },
   });
 
-  return Object.freeze({ transaction, eventsSince, snapshot, stateRecord, ephemeral, paths, root,
-    workspaceId });
+  /**
+   * Every live state record with the generation that identifies it.
+   *
+   * `snapshot` deliberately hands back records alone, because that is all any
+   * reader of coordination state needs. Reclaiming is the one caller that needs
+   * the envelope generation too: it decides what is eligible from a reading
+   * taken outside the writer mutex and applies it inside, and the generation is
+   * what proves the record did not change in between.
+   */
+  async function stateEnvelopes(workspace, { kinds } = {}) {
+    const wanted = kinds === undefined ? null : new Set(kinds);
+    return [...(await loadAllState(paths, root, wanted)).values()]
+      .filter(envelope => envelope.record.workspaceId === workspace);
+  }
+
+  /**
+   * Remove named state records and the retention markers they own.
+   *
+   * Under the writer mutex, because it competes with every transaction; the
+   * store deadline still bounds it, so an operator waiting on a busy store is
+   * told rather than blocked forever.
+   */
+  async function reclaimRecords(plan, { limit, deadlineAt } = {}) {
+    const bounded = Math.min(deadlineAt ?? Infinity, storeDeadline ?? Infinity);
+    return withWriterMutex(paths, { ...publishOptions, deadlineAt: bounded }, async () => {
+      // A function is decided here, holding the mutex, because eligibility is a
+      // statement about relationships between records and not only about each
+      // record. The generation on an entry proves that record did not change;
+      // it says nothing about a session opening for a participant this was
+      // about to remove. Deciding inside the lock is what closes that.
+      const entries = typeof plan === "function" ? await plan() : plan;
+      return reclaimStateRecords(paths, entries, { root, limit, deadlineAt: bounded });
+    });
+  }
+
+  /**
+   * Trim the event log to a boundary and report where it now starts.
+   *
+   * Under the writer mutex, because it competes with the sequence every
+   * transaction allocates.
+   */
+  async function trimHistory(boundary, { limit, deadlineAt } = {}) {
+    const bounded = Math.min(deadlineAt ?? Infinity, storeDeadline ?? Infinity);
+    const publish = { ...publishOptions, deadlineAt: bounded };
+    return withWriterMutex(paths, publish,
+      () => trimEventLog(paths, boundary, { root, publish, limit, deadlineAt: bounded }));
+  }
+
+  return Object.freeze({ transaction, eventsSince, snapshot, stateRecord, stateEnvelopes,
+    reclaimRecords, trimHistory, ephemeral, paths, root, workspaceId });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "accManagedUpdateProtocol": 2,
   "accStoreVersion": 6,
   "type": "module",