@volter/supercode-teams 0.3.151 → 0.3.152

package/mail/agents.mjs

@@ -2,116 +2,58 @@
 // docs/adr/0008-agent-mailbox.md). An agent is addressed `sc:<machine>:agent:<name>`; its record names its main session,
 // where a root addressed to it goes. A thread is a root and its replies, with its participants: a `to` participant
 // receives each line through its door, woken; a `cc` participant has it filed unread. `plan` decides who receives one
-// message. The records are mail_agent.rs's own files (`<mail>/agents/<name>.json`, `<mail>/threads/<id>.json`), written
-// as it writes them, under the same lock, since the native verbs that are 3b-2's still read and write them.
-import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+// message. The daemon owns these records in its mail database. A thread update
+// is one synchronous transaction; no other process opens a thread file or lock.
 import { spawn } from 'node:child_process';
-import { join } from 'node:path';
 import { blake3Hex } from './envelope.mjs';
 import { cameThroughLink, parseAddress, threadOf } from './compose.mjs';
 
 /** The pseudo-harness of an agent address. */
 export const AGENT_HARNESS = 'agent';
-/** How recent a folder time is not trusted to say its folder is unchanged (a coarse clock's tick, a 1 s filesystem). */
-const RACY_MS = 2000;
 /** How long a send waits for a resumed session to be reachable again. */
 export const RESUME_WAIT_MS = 45_000;
 
 const validName = (name) => typeof name === 'string' && /^[A-Za-z0-9._-]+$/.test(name);
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-/** A record written whole and renamed into place (mail_agent.rs `write_atomically`). */
-export function writeAtomically(path, text) {
-  mkdirSync(join(path, '..'), { recursive: true });
-  const temporary = `${path.replace(/\.[^./]*$/, '')}.tmp.${process.pid}`;
-  writeFileSync(temporary, text);
-  renameSync(temporary, path);
-}
-
-const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
-
-/** serde_json's `to_vec_pretty` of a thread, its fields in mail_agent.rs's order and its empty optionals left out. */
-function threadText(thread) {
+/** Preserve the former record's fields, leaving its empty optionals out. */
+function threadRecord(thread) {
   const out = { id: thread.id, agent: thread.agent, holder: thread.holder, participants: thread.participants.map(({ address, role }) => ({ address, role })) };
   if (thread.markers && Object.keys(thread.markers).length) out.markers = Object.fromEntries(Object.entries(thread.markers).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
   if (thread.surface != null) out.surface = thread.surface;
   out.created_at_ms = thread.created_at_ms;
   if (thread.holder_launched) out.holder_launched = true;
   if (thread.parent != null) out.parent = thread.parent;
-  return JSON.stringify(out, null, 2);
+  return out;
 }
 
 export class Agents {
-  constructor({ mailRoot, machine, supercodeBin, env = process.env, recordedConfig = async () => null, discover = async () => ({ sessions: [] }) }) {
-    Object.assign(this, { mailRoot, machine, supercodeBin, env, recordedConfig, discover });
-    this.agentsDir = join(mailRoot, 'agents');
-    this.threadsDir = join(mailRoot, 'threads');
-    this.locks = new Map(); // thread id → the write in progress here (one writer per thread in this process)
+  constructor({ store, machine, supercodeBin, env = process.env, recordedConfig = async () => null, discover = async () => ({ sessions: [] }) }) {
+    Object.assign(this, { store, machine, supercodeBin, env, recordedConfig, discover });
   }
 
   // ---- records ---------------------------------------------------------------------------------------------------
 
   /** The agent named `name`, when one is declared. */
-  load(name) { return validName(name) ? readJson(join(this.agentsDir, `${name}.json`)) : null; }
+  load(name) { return validName(name) ? this.store.record('agents', name) : null; }
 
   /** Every declared agent, by name. */
   all() {
-    let names = [];
-    try { names = readdirSync(this.agentsDir); } catch { return []; }
-    return names.filter((name) => name.endsWith('.json')).map((name) => readJson(join(this.agentsDir, name))).filter((agent) => agent?.name && agent?.main_session).sort((a, b) => (a.name < b.name ? -1 : 1));
+    return this.store.records('agents').map(({ value }) => value).filter((agent) => agent?.name && agent?.main_session).sort((a, b) => (a.name < b.name ? -1 : 1));
   }
 
   /** The thread `id`, when the mailbox keeps one. */
-  thread(id) { return validName(id) ? readJson(join(this.threadsDir, `${id}.json`)) : null; }
+  thread(id) { return validName(id) ? this.store.record('threads', id) : null; }
 
   /** Every thread, oldest first. */
-  threads() { return this.#records().list.map((thread) => structuredClone(thread)); }
-
-  /**
-   * The thread records, read once and kept while their folder is unchanged, with an index of them by holder and by
-   * channel marker. Every writer (this daemon, and mail_agent.rs's in the native watch until step 4) renames a whole
-   * record into the folder, which moves its time: one stat a call, never a read of every record, though a send's plan
-   * asks on every send and an agent's threads grow with its history. A folder time within RACY_MS of now is not trusted
-   * (a write in the same tick of a coarse clock leaves it unmoved): the folder is listed again, each record checked by
-   * its inode, until its time is older.
-   */
-  #records() {
-    let changed;
-    try { changed = statSync(this.threadsDir).mtimeMs; } catch { return { list: [], byHolder: new Map(), byMarker: new Map() }; }
-    const cache = this.threadsCache;
-    if (cache?.changed === changed && Date.now() - changed > RACY_MS) return cache;
-    // The folder changed, or changed too recently for its time to be trusted: its names are listed and each record's
-    // file is stat'ed, and only a record whose inode moved (every writer renames a whole new file into place) is read
-    // again. A burst of writes costs a listing and a stat a record, not a read of every record.
-    let names = [];
-    try { names = readdirSync(this.threadsDir); } catch { return { list: [], byHolder: new Map(), byMarker: new Map() }; }
-    const files = new Map();
-    for (const name of names) {
-      if (!name.endsWith('.json')) continue;
-      // its inode, time and size together (an inode can be used again once freed): a rename moves at least one
-      let stamp;
-      try { const stat = statSync(join(this.threadsDir, name)); stamp = `${stat.ino}:${stat.mtimeMs}:${stat.size}`; } catch { continue; }
-      const known = cache?.files?.get(name);
-      const thread = known && known.stamp === stamp ? known.thread : readJson(join(this.threadsDir, name));
-      if (thread?.id) files.set(name, { stamp, thread });
-    }
-    const list = [...files.values()].map((file) => file.thread)
-      .sort((a, b) => (a.created_at_ms - b.created_at_ms) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-    const byHolder = new Map(), byMarker = new Map();
-    for (const thread of list) {
-      byHolder.set(thread.holder, [...(byHolder.get(thread.holder) ?? []), thread]);
-      for (const [marker, id] of Object.entries(thread.markers ?? {})) if (!byMarker.has(marker)) byMarker.set(marker, { thread, id });
-    }
-    const records = { changed, list, byHolder, byMarker, files };
-    // kept either way (its records are each current by inode); trusted without a listing only once its time is old
-    this.threadsCache = records;
-    return records;
+  threads() {
+    return this.store.statement("SELECT record FROM mail_records WHERE collection = 'threads' ORDER BY json_extract(record, '$.created_at_ms'), json_extract(record, '$.id')")
+      .all().map(({ record }) => JSON.parse(record)).filter((thread) => thread?.id);
   }
 
 
   /** The thread `address` holds for an agent other than as its main session (mail_agent.rs `thread_held_by`). */
   heldBy(address) {
-    const held = [...(this.#records().byHolder.get(address) ?? [])].reverse().find((thread) => {
+    const held = this.store.statement("SELECT record FROM mail_records WHERE collection = 'threads' AND json_extract(record, '$.holder') = ? ORDER BY json_extract(record, '$.created_at_ms') DESC, json_extract(record, '$.id') DESC")
+      .all(address).map(({ record }) => JSON.parse(record)).find((thread) => {
       if (thread.parent != null) return false;
       const agent = this.load(thread.agent);
       return agent != null && agent.main_session !== address;
@@ -121,8 +63,10 @@ export class Agents {
 
   /** The thread whose channel message has the platform id `marker`, with that message's id. */
   ofMarker(marker) {
-    const found = this.#records().byMarker.get(marker);
-    return found ? { thread: structuredClone(found.thread), id: found.id } : null;
+    const found = this.store.statement(`SELECT r.record, m.message FROM thread_markers m
+      JOIN mail_records r ON r.collection = m.collection AND r.key = m.thread
+      WHERE m.marker = ? ORDER BY json_extract(r.record, '$.created_at_ms'), json_extract(r.record, '$.id') LIMIT 1`).get(marker);
+    return found ? { thread: JSON.parse(found.record), id: JSON.parse(found.message) } : null;
   }
 
   /** The agent `address` is a session of: its main, or a thread's holder. */
@@ -133,46 +77,17 @@ export class Agents {
     return held ? this.load(held.agent) : null;
   }
 
-  /**
-   * Change the thread `id` under its lock (`<id>.lock`, made with create-new; one older than 10 s is a dead writer's;
-   * a live one is waited on for 30 s, then the send fails), and answer it as saved; `create()` makes it when it is not
-   * kept yet (mail_agent.rs `update_thread`).
-   */
+  /** Change a thread and its marker index together; `create()` supplies a missing
+   * record. No native-door await or external writer belongs in this transaction. */
   async update(id, create, change) {
     if (!validName(id)) return null;
-    const previous = this.locks.get(id) ?? Promise.resolve();
-    let release;
-    const mine = new Promise((resolve) => { release = resolve; });
-    const chained = previous.then(() => mine);
-    this.locks.set(id, chained);
-    await previous;
-    try {
-      mkdirSync(this.threadsDir, { recursive: true });
-      const path = join(this.threadsDir, `${id}.json`);
-      const lock = join(this.threadsDir, `${id}.lock`);
-      const started = Date.now();
-      for (;;) {
-        try { closeSync(openSync(lock, 'wx')); break; }
-        catch (error) {
-          if (error.code !== 'EEXIST') throw error;
-          let stale = false;
-          try { stale = Date.now() - statSync(lock).mtimeMs > 10_000; } catch { /* gone meanwhile */ }
-          if (stale) { try { unlinkSync(lock); } catch { /* another took it */ } }
-          else if (Date.now() - started > 30_000) throw new Error(`thread ${id} is locked by another writer`);
-          await sleep(20);
-        }
-      }
-      try {
-        const thread = readJson(path) ?? create();
-        if (!thread) return null;
-        change(thread);
-        writeAtomically(path, threadText(thread));
-        return thread;
-      } finally { try { unlinkSync(lock); } catch { /* released */ } }
-    } finally {
-      release();
-      if (this.locks.get(id) === chained) this.locks.delete(id);
-    }
+    return this.store.transaction(() => {
+      const thread = this.thread(id) ?? create();
+      if (!thread) return null;
+      if (change(thread)?.then instanceof Function) throw new Error('mail thread updates must be synchronous');
+      this.store.putRecord('threads', id, threadRecord(thread));
+      return thread;
+    });
   }
 
   /** Record `agent`, replacing an earlier record of the same name (mail_agent.rs `declare`): its fields in its order, an
@@ -183,19 +98,23 @@ export class Agents {
     if (agent.folder != null) out.folder = agent.folder;
     if (agent.harness != null) out.harness = agent.harness;
     if (agent.idle_minutes != null) out.idle_minutes = agent.idle_minutes;
-    writeAtomically(join(this.agentsDir, `${agent.name}.json`), JSON.stringify(out, null, 2));
+    this.store.putRecord('agents', agent.name, out);
   }
 
   /** Name `name` the owner's account manager: every line the owner writes to any agent is CC'd to its main session. */
-  setOwnersAccountManager(name) { writeAtomically(join(this.agentsDir, 'owners-account-manager'), `${name}\n`); }
+  setOwnersAccountManager(name) { this.store.putRecord('agent_settings', 'owners-account-manager', name); }
 
   /** The owner's account manager, when one is named and declared. */
   ownersAccountManager() {
-    try { return this.load(readFileSync(join(this.agentsDir, 'owners-account-manager'), 'utf8').trim()); } catch { return null; }
+    const name = this.store.record('agent_settings', 'owners-account-manager');
+    return typeof name === 'string' ? this.load(name.trim()) : null;
   }
 
   /** The threads of the agent `name`, oldest first. */
-  threadsOf(name) { return this.#records().list.filter((thread) => thread.agent === name).map((thread) => structuredClone(thread)); }
+  threadsOf(name) {
+    return this.store.statement("SELECT record FROM mail_records WHERE collection = 'threads' AND json_extract(record, '$.agent') = ? ORDER BY json_extract(record, '$.created_at_ms'), json_extract(record, '$.id')")
+      .all(name).map(({ record }) => JSON.parse(record)).filter((thread) => thread?.id);
+  }
 
   /**
    * A line that reached an agent's main session through its own input (its terminal, its DM) is a root of the agent:
@@ -346,6 +265,7 @@ export class Agents {
    *  <its recorded mode>`: never open's unattended defaults (mail_agent.rs `resume`), and no window on the screen. */
   async resume(address) {
     const recorded = await this.#resumeArguments(address);
+    if (this.stopped) throw new Error('the daemon is stopping; no agent session was resumed');
     if (!recorded) throw new Error(`${address} has no recorded permissions to resume with; its mail waits`);
     const parsed = parseAddress(address);
     // a Claude holder comes back under a name of its own (its agent's, and its id's start), never its folder's, which
@@ -354,7 +274,7 @@ export class Agents {
       const thread = this.threads().find((item) => item.holder === address);
       if (thread) recorded.push('--name', `${thread.agent}-${[...parsed.session].slice(0, 6).join('')}`);
     }
-    writeAtomically(join(this.agentsDir, 'resumed', blake3Hex(address).slice(0, 24)), String(Date.now()));
+    this.store.putRecord('agent_resumed', blake3Hex(address).slice(0, 24), String(Date.now()));
     const { code, stderr } = await new Promise((resolve) => {
       // a holder resumed by mail runs in the background: no window opens on the machine's screen for it
       const child = spawn(this.supercodeBin, ['open', parsed.session, '--detach', '--window=false', '--', ...recorded], { stdio: ['ignore', 'ignore', 'pipe'], env: this.env });
@@ -382,6 +302,8 @@ export class Agents {
     if (config?.session_id !== parsed.session) return null;
     return resumeArguments(config);
   }
+
+  stop() { this.stopped = true; }
 }
 
 /** A recorded configuration as resume arguments, or null when it is of a kind not carried (mail_agent.rs). */
@@ -416,4 +338,3 @@ export function resumeArguments(config) {
   if (model) args.push('--model', model);
   return args;
 }
-

package/mail/carrier.mjs

@@ -1,20 +1,18 @@
 // The mailbox's own delivery (D140; docs/architecture/overview.md, step 4b): every message filed with a wake (by a filer
 // that does not wait, a board's dispatcher, a send to a hooked session) is handed to its session by the session's own
 // door, by this daemon. Mail for another machine is carried there through its mail door and filed with the same wake,
-// so that machine's daemon delivers it. The native watch did this by reading every mailbox every two seconds
-// (mail_watch.rs `MailCarrier`); here a wake is followed from its own file event (one read of the mail folder at start),
-// and each is attempted when it is due. Its rules and its records are the native carrier's, file for file:
-// - a failed attempt waits FIRST_RETRY_MS doubling to LAST_RETRY_MS, kept in the wake itself (`wake/<id>`);
+// so that machine's daemon delivers it. A wake is a row of the mail store (mail step 2), followed from the write that
+// makes it (the store's `wake` event; every wake read at start), and each is attempted when it is due. Its rules are the
+// native carrier's (mail_watch.rs `MailCarrier`, deleted):
+// - a failed attempt waits FIRST_RETRY_MS doubling to LAST_RETRY_MS, kept in the wake itself;
 // - a wake expires once it has failed WAKE_ATTEMPTS counted times and its first counted failure is older than its bound
 //   (LOCAL_WAKE_LIFETIME_MS here, REMOTE_WAKE_LIFETIME_MS for another machine): the message stays filed and unread, and
-//   the expiry is recorded in its mailbox (`expired/<id>.json`, read by `supercode message expired`);
+//   the expiry is recorded (read by `supercode message expired`);
 // - mail for a machine that is offline is not failing: the machine is probed once per LAST_RETRY_MS (its wait kept once
-//   per machine, `machines/<machine>.json`, read by `supercode message waiting`), all its mail is carried when it
+//   per machine, read by `supercode message waiting`), all its mail is carried when it
 //   answers, and the mail expires only past OFFLINE_CEILING_MS;
 // - a hand-over is waited for at most HANDOVER_BOUND_MS, and one mailbox's attempt never waits on another's;
-// - each attempt is a line of `carrier.jsonl`.
-import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+// - each attempt is a line of the carrier's record.
 import { render } from './envelope.mjs';
 
 const FIRST_RETRY_MS = 2_000;
@@ -28,9 +26,7 @@ const OFFLINE_CEILING_MS = 30 * 24 * 60 * 60_000;
 // mailbox's wakes, and only for this long
 const HANDOVER_BOUND_MS = 150_000;
 
-const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
 const offline = (text) => String(text).includes('machine_offline');
-const safeMachine = (machine) => String(machine).replace(/[^A-Za-z0-9._-]/g, '_');
 
 export class MailCarrier {
   /**
@@ -39,64 +35,59 @@ export class MailCarrier {
    * `typeTurn(pane, harness, text, ids)` a wake typed into a hooked session's pane; `askMachine(machine, request)` one
    * request to another machine's mail door.
    */
-  constructor({ machine, mailRoot, store, live, handOver, typeTurn, askMachine, log = () => {} }) {
-    Object.assign(this, { machine, mailRoot, store, live, handOver, typeTurn, askMachine, log });
-    this.timers = new Map(); // `${folder}\0${id}` → timer of a wake here, due
-    this.running = new Set(); // mailbox folders with an attempt in flight
+  constructor({ machine, store, live, handOver, typeTurn, askMachine, log = () => {} }) {
+    Object.assign(this, { machine, store, live, handOver, typeTurn, askMachine, log });
+    this.stopped = false;
+    this.timers = new Map(); // `${address}\0${id}` → timer of a wake here, due
+    this.running = new Set(); // mailboxes (addresses) with an attempt in flight
     this.machines = new Map(); // machine → timer of its next carry
     this.carrying = new Set(); // machines with a carry in flight
-    this.remote = new Map(); // machine → Map(`${folder}\0${id}` → { folder, address, id }): wakes for another machine
+    this.remote = new Map(); // machine → Map(`${address}\0${id}` → { address, id }): wakes for another machine
   }
 
-  /** Follow every wake: those filed before this daemon (one read of the mail folder), each as the store names it (its
-   *  file's event, or a mailbox the store read whole), and every wake again once per LAST_RETRY_MS, so a wake no event
-   *  named is carried within that bound. */
+  /** Follow every wake: those filed before this daemon (every wake the store holds), each as the store names it (the
+   *  write that made it), and every wake again once per LAST_RETRY_MS, so a wake no event named is carried within that
+   *  bound. */
   start() {
-    this.store.on('wake', ({ folder, id }) => this.#wake(folder, id));
+    this.onWake = ({ address, id }) => this.#wake(address, id);
+    this.store.on('wake', this.onWake);
     this.#sweep();
     this.sweeper = setInterval(() => this.#sweep(), LAST_RETRY_MS);
     this.sweeper.unref?.();
     return this;
   }
 
-  /** Every mailbox's wakes read from its folder and followed (one already due or scheduled is not scheduled twice). */
-  #sweep() {
-    let folders = [];
-    try { folders = readdirSync(this.mailRoot); } catch { return; }
-    for (const folder of folders) this.#rewake(folder);
-  }
-
-  stop() { clearInterval(this.sweeper); for (const timer of [...this.timers.values(), ...this.machines.values()]) clearTimeout(timer); this.timers.clear(); this.machines.clear(); }
+  /** Every wake followed (one already due or scheduled is not scheduled twice). */
+  #sweep() { for (const { address, id } of this.store.allWakes()) this.#wake(address, id); }
 
-  #address(folder) { try { return readFileSync(join(this.mailRoot, folder, 'address'), 'utf8').trim(); } catch { return null; } }
+  stop() { this.stopped = true; this.store.off('wake', this.onWake); clearInterval(this.sweeper); for (const timer of [...this.timers.values(), ...this.machines.values()]) clearTimeout(timer); this.timers.clear(); this.machines.clear(); }
 
-  /** A wake seen (its file written or changed): attempted when it is due. */
-  #wake(folder, id) {
-    if (!/^[A-Za-z0-9_-]+$/.test(id)) return;
-    const address = this.#address(folder);
-    if (!address) return;
+  /** A wake seen (written or changed): attempted when it is due. */
+  #wake(address, id) {
+    if (this.stopped || !/^[A-Za-z0-9_-]+$/.test(id) || !address) return;
     const machine = address.split(':')[1];
     if (machine !== this.machine) {
       if (!this.remote.has(machine)) this.remote.set(machine, new Map());
-      this.remote.get(machine).set(`${folder}\0${id}`, { folder, address, id });
+      this.remote.get(machine).set(`${address}\0${id}`, { address, id });
       this.#scheduleMachine(machine);
       return;
     }
-    const key = `${folder}\0${id}`;
+    const key = `${address}\0${id}`;
     if (this.timers.has(key)) return;
     const state = this.store.wakeState(address, id);
-    const timer = setTimeout(() => { this.timers.delete(key); void this.#local(folder, address); }, Math.max(0, (state.next_at_ms ?? 0) - Date.now()));
+    const timer = setTimeout(() => { this.timers.delete(key); void this.#local(address); }, Math.max(0, (state.next_at_ms ?? 0) - Date.now()));
     timer.unref?.();
     this.timers.set(key, timer);
   }
 
   /** The wakes of one mailbox here that are due, attempted (mail_watch.rs `tick`, its local half). */
-  async #local(folder, address) {
-    if (this.running.has(folder)) { setTimeout(() => this.#rewake(folder), 1000).unref?.(); return; }
-    this.running.add(folder);
+  async #local(address) {
+    if (this.stopped) return;
+    if (this.running.has(address)) { setTimeout(() => this.#rewake(address), 1000).unref?.(); return; }
+    this.running.add(address);
     try {
       const now = Date.now();
-      const due = this.#pending(folder, address).filter((id) => (this.store.wakeState(address, id).next_at_ms ?? 0) <= now);
+      const due = this.#pending(address).filter((id) => (this.store.wakeState(address, id).next_at_ms ?? 0) <= now);
       if (!due.length) return;
       // a session in a daemon pane whose mail is typed there: a hooked one (its hook shows it the rest), and one with no
       // hook and no relay (Grok), whose mail that found its composer busy waits here until it is free
@@ -104,7 +95,7 @@ export class MailCarrier {
       if ((session?.door === 'hook' || session?.door === 'pane') && session.pane) {
         for (const id of due) {
           const stored = this.store.findIn(address, id);
-          const envelope = stored ? readJson(stored.path) : null;
+          const envelope = stored ? this.store.body(stored) : null;
           let carried;
           if (!envelope) carried = { kind: 'filed' };
           else {
@@ -114,8 +105,9 @@ export class MailCarrier {
               carried = typed?.delivered ? { kind: 'delivered' } : typed?.queued ? { kind: 'filed' } : { kind: 'later', reason: 'its pane was not at its prompt' };
             } catch (error) { carried = { kind: 'later', reason: error.message }; }
           }
+          if (this.stopped) return;
           this.#record({ to: address, id, path: `${session.door}-pane`, carried });
-          this.#settle(folder, address, id, carried);
+          this.#settle(address, id, carried);
         }
         return;
       }
@@ -135,41 +127,34 @@ export class MailCarrier {
             carried = answer?.outcome === 'delivered' ? { kind: 'delivered' } : answer?.outcome === 'filed' ? { kind: 'filed' } : { kind: 'later', reason: answer?.detail ?? 'not handed over' };
           } catch (error) { carried = { kind: 'later', reason: `this machine's daemon did not hand it over: ${error.message}` }; }
         }
+        if (this.stopped) return;
         this.#record({ to: address, id, path: 'door', carried });
-        this.#settle(folder, address, id, carried);
+        this.#settle(address, id, carried);
       }
     } finally {
-      this.running.delete(folder);
-      this.#rewake(folder);
+      this.running.delete(address);
+      this.#rewake(address);
     }
   }
 
   /** A mailbox's wakes followed again (each one scheduled at its own due time). */
-  #rewake(folder) {
-    let ids = [];
-    try { ids = readdirSync(join(this.mailRoot, folder, 'wake')); } catch { return; }
-    for (const id of ids) this.#wake(folder, id);
-  }
+  #rewake(address) { if (this.stopped) return; for (const id of this.store.wakes(address)) this.#wake(address, id); }
 
   /** A mailbox's wakes whose message is still filed; a wake whose message is gone is let go (mailbox.rs `pending_wakes`). */
-  #pending(folder, address) {
-    let ids = [];
-    try { ids = readdirSync(join(this.mailRoot, folder, 'wake')); } catch { return []; }
-    return ids.filter((id) => {
+  #pending(address) {
+    return this.store.wakes(address).filter((id) => {
       if (this.store.findIn(address, id)) return true;
-      try { rmSync(join(this.mailRoot, folder, 'wake', id), { force: true }); } catch { /* gone */ }
+      this.store.removeWake(address, id);
       return false;
     });
   }
 
   // ---- another machine's mail ------------------------------------------------------------------------------------
 
-  #machineWaitPath(machine) { return join(this.mailRoot, 'machines', `${safeMachine(machine)}.json`); }
-
   /** A machine's mail carried at its next due time: its wait's next probe when it is offline, else its earliest wake. */
   #scheduleMachine(machine) {
-    if (this.machines.has(machine) || this.carrying.has(machine)) return;
-    const wait = readJson(this.#machineWaitPath(machine));
+    if (this.stopped || this.machines.has(machine) || this.carrying.has(machine)) return;
+    const wait = this.store.machineWait(machine);
     let at = wait?.next_probe_ms ?? null;
     if (at == null) {
       at = Infinity;
@@ -182,15 +167,14 @@ export class MailCarrier {
   }
 
   /** Every wake filed here for `machine` (as their events named them), with when its message was filed, oldest first; a
-   *  wake whose file or message is gone is let go. */
+   *  wake whose message is gone, or that is gone itself, is let go. */
   #remoteWakes(machine) {
     const items = [];
     for (const [key, item] of this.remote.get(machine) ?? []) {
-      let present = true;
-      try { readFileSync(join(this.mailRoot, item.folder, 'wake', item.id)); } catch { present = false; }
+      const present = this.store.hasWake(item.address, item.id);
       const found = present ? this.store.findIn(item.address, item.id) : null;
-      if (!found) { this.remote.get(machine).delete(key); if (present) { try { rmSync(join(this.mailRoot, item.folder, 'wake', item.id), { force: true }); } catch { /* gone */ } } continue; }
-      const envelope = readJson(found.path);
+      if (!found) { this.remote.get(machine).delete(key); if (present) this.store.removeWake(item.address, item.id); continue; }
+      const envelope = this.store.body(found);
       items.push({ ...item, filed: Number(envelope?.created_at_ms) || 0 });
     }
     return items.sort((a, b) => a.filed - b.filed);
@@ -199,17 +183,18 @@ export class MailCarrier {
   /** One machine's mail carried (mail_watch.rs `tick`, its remote half): its oldest due message probes the machine, and
    *  when it answers, the rest follow in this pass. */
   async #carry(machine) {
+    if (this.stopped) return;
     this.carrying.add(machine);
     try {
       const now = Date.now();
       const items = this.#remoteWakes(machine);
       if (!items.length) return;
-      const wait = readJson(this.#machineWaitPath(machine));
+      const wait = this.store.machineWait(machine);
       if (wait) {
         // a machine away longer than the ceiling is not coming back for this mail: it expires, saying so
         if (now - (wait.offline_since_ms ?? now) >= OFFLINE_CEILING_MS) {
           const reason = `${machine} has been offline for ${OFFLINE_CEILING_MS / 86_400_000} days (since epoch ms ${wait.offline_since_ms}): ${wait.last_error ?? 'not linked'}`;
-          for (const item of items) this.#expire(item.folder, item.address, item.id, this.store.wakeState(item.address, item.id).attempts ?? 0, reason);
+          for (const item of items) this.#expire(item.address, item.id, this.store.wakeState(item.address, item.id).attempts ?? 0, reason);
           this.#setMachineWait(machine, null);
           this.#line({ t: now, machine, outcome: 'expired', messages: items.length, reason });
           return;
@@ -225,11 +210,12 @@ export class MailCarrier {
         if (!found || (found.state === 'read' && this.store.claimOf(item.address, item.id)?.recipient === true)) carried = { kind: 'filed' };
         else {
           called = true;
-          carried = await this.#carryOne(machine, item.address, readJson(found.path));
+          carried = await this.#carryOne(machine, item.address, this.store.body(found));
         }
+        if (this.stopped) return;
         if (carried.kind === 'offline') { offlineAnswer = carried.reason; break; }
         carriedHere++;
-        this.#settle(item.folder, item.address, item.id, carried);
+        this.#settle(item.address, item.id, carried);
       }
       if (called) this.#line({ t: now, machine, outcome: offlineAnswer ? 'offline' : 'carried', waiting: items.length, carried: carriedHere, reason: offlineAnswer });
       if (offlineAnswer) this.#setMachineWait(machine, { machine, offline_since_ms: wait?.offline_since_ms ?? now, next_probe_ms: now + LAST_RETRY_MS, probes: (wait?.probes ?? 0) + 1, last_error: offlineAnswer });
@@ -256,10 +242,7 @@ export class MailCarrier {
   }
 
   #setMachineWait(machine, wait) {
-    const path = this.#machineWaitPath(machine);
-    if (!wait) { try { rmSync(path, { force: true }); } catch { /* gone */ } return; }
-    try { mkdirSync(join(this.mailRoot, 'machines'), { recursive: true }); writeFileSync(`${path}.tmp`, JSON.stringify(wait)); renameSync(`${path}.tmp`, path); }
-    catch (error) { this.log(`carrier: ${machine}'s wait was not kept: ${error.message}`); }
+    try { this.store.setMachineWait(machine, wait); } catch (error) { this.log(`carrier: ${machine}'s wait was not kept: ${error.message}`); }
   }
 
   // ---- what waits, and what expired (`message waiting`, `message expired`) -----------------------------------------
@@ -268,21 +251,16 @@ export class MailCarrier {
    *  filed first (mailbox.rs `waiting_mail`, field for field). */
   waiting() {
     const all = [];
-    let folders = [];
-    try { folders = readdirSync(this.mailRoot); } catch { return all; }
-    for (const folder of folders) {
-      let ids = [];
-      try { ids = readdirSync(join(this.mailRoot, folder, 'wake')); } catch { continue; }
-      if (!ids.length) continue;
-      const address = this.#address(folder);
-      if (!address) continue;
+    const waits = new Map();
+    for (const { address, id } of this.store.allWakes()) {
       const machine = address.split(':')[1];
-      const wait = machine !== this.machine ? readJson(this.#machineWaitPath(machine)) : null;
-      for (const id of ids) {
+      if (machine !== this.machine && !waits.has(machine)) waits.set(machine, this.store.machineWait(machine));
+      const wait = machine !== this.machine ? waits.get(machine) : null;
+      {
         const state = this.store.wakeState(address, id);
         if (!wait && !(state.attempts > 0) && state.last_error == null) continue;
         const found = this.store.findIn(address, id);
-        const envelope = found ? readJson(found.path) : null;
+        const envelope = found ? this.store.body(found) : null;
         if (!envelope) continue;
         all.push({ id, to: address, from: envelope.from ?? '', subject: envelope.subject ?? null, filed_at_ms: Number(envelope.created_at_ms) || 0,
           waiting_for: wait ? wait.machine : null, since_ms: wait?.offline_since_ms ?? state.failing_since_ms ?? (Number(envelope.created_at_ms) || 0),
@@ -293,23 +271,12 @@ export class MailCarrier {
   }
 
   /** Every wake that expired here, oldest first (mailbox.rs `expired_wakes`). */
-  expired() {
-    const all = [];
-    let folders = [];
-    try { folders = readdirSync(this.mailRoot); } catch { return all; }
-    for (const folder of folders) {
-      let names = [];
-      try { names = readdirSync(join(this.mailRoot, folder, 'expired')); } catch { continue; }
-      for (const name of names) { const expiry = readJson(join(this.mailRoot, folder, 'expired', name)); if (expiry?.id) all.push(expiry); }
-    }
-    return all.sort((a, b) => (a.expired_at_ms ?? 0) - (b.expired_at_ms ?? 0));
-  }
+  expired() { return this.store.expired(); }
 
   // ---- how an attempt went ---------------------------------------------------------------------------------------
 
   /** Record how a wake went: done, waiting for its next attempt, or expired at its bound (mail_watch.rs `settle`). */
-  #settle(folder, address, id, carried) {
-    const wakePath = join(this.mailRoot, folder, 'wake', id);
+  #settle(address, id, carried) {
     if (carried.kind === 'delivered' || carried.kind === 'filed') {
       if (carried.kind === 'delivered') {
         // the carrier's own hand-off record: delivered here by its door, or carried to its machine
@@ -317,7 +284,7 @@ export class MailCarrier {
         const found = this.store.findIn(address, id);
         if (found && found.state !== 'read') { try { this.store.markRead(address, found.path); } catch { /* read already */ } }
       }
-      try { rmSync(wakePath, { force: true }); } catch { /* gone */ }
+      this.store.removeWake(address, id);
       return;
     }
     if (carried.kind === 'offline') return;
@@ -326,29 +293,23 @@ export class MailCarrier {
     const attempts = (state.attempts ?? 0) + 1;
     const since = state.failing_since_ms ?? now;
     const lifetime = address.split(':')[1] === this.machine ? LOCAL_WAKE_LIFETIME_MS : REMOTE_WAKE_LIFETIME_MS;
-    if (attempts >= WAKE_ATTEMPTS && now - since >= lifetime) { this.#expire(folder, address, id, attempts, carried.reason); return; }
+    if (attempts >= WAKE_ATTEMPTS && now - since >= lifetime) { this.#expire(address, id, attempts, carried.reason); return; }
     const wait = Math.min(LAST_RETRY_MS, FIRST_RETRY_MS * 2 ** Math.min(attempts - 1, 16));
     this.store.setWakeState(address, id, { ...state, attempts, failing_since_ms: since, next_at_ms: now + wait, last_error: carried.reason });
   }
 
-  /** End a wake undelivered: the message stays filed and unread, and the expiry is recorded in its mailbox. */
-  #expire(folder, address, id, attempts, reason) {
+  /** End a wake undelivered: the message stays filed and unread, and the expiry is recorded. */
+  #expire(address, id, attempts, reason) {
     const found = this.store.findIn(address, id);
-    const envelope = found ? readJson(found.path) : null;
+    const envelope = found ? this.store.body(found) : null;
     const expiry = { id, to: address, from: envelope?.from ?? '', subject: envelope?.subject ?? null, filed_at_ms: Number(envelope?.created_at_ms) || 0, expired_at_ms: Date.now(), attempts, reason };
-    try {
-      mkdirSync(join(this.mailRoot, folder, 'expired'), { recursive: true });
-      const temporary = join(this.mailRoot, folder, 'tmp', `expired.${id}`);
-      writeFileSync(temporary, JSON.stringify(expiry));
-      renameSync(temporary, join(this.mailRoot, folder, 'expired', `${id}.json`));
-      rmSync(join(this.mailRoot, folder, 'wake', id), { force: true });
-    } catch (error) { this.log(`carrier: the expiry of ${id} was not recorded: ${error.message}`); }
+    try { this.store.expire(address, id, expiry); } catch (error) { this.log(`carrier: the expiry of ${id} was not recorded: ${error.message}`); }
   }
 
-  /** One local delivery attempt in the carrier's record (`carrier.jsonl`). */
+  /** One local delivery attempt in the carrier's record. */
   #record({ to, id, path, carried }) {
     this.#line({ t: Date.now(), to, id, path, outcome: carried.kind, reason: carried.reason ?? null });
   }
 
-  #line(line) { try { appendFileSync(join(this.mailRoot, 'carrier.jsonl'), `${JSON.stringify(line)}\n`); } catch { /* the record is best kept */ } }
+  #line(line) { this.store.carrierLine(line); }
 }