@volter/supercode-teams 0.3.159 → 0.3.161

package/mail/carrier.mjs

@@ -14,6 +14,7 @@
 // - 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 the carrier's record.
 import { render } from './envelope.mjs';
+import { expireDelivery, paneWaitReason, terminalReceipt } from './delivery-status.mjs';
 
 const FIRST_RETRY_MS = 2_000;
 const LAST_RETRY_MS = 300_000;
@@ -25,6 +26,10 @@ const OFFLINE_CEILING_MS = 30 * 24 * 60 * 60_000;
 // and the hand-over itself answers 'later' until it settles (MailSend.handOver), so a frozen door holds only its own
 // mailbox's wakes, and only for this long
 const HANDOVER_BOUND_MS = 150_000;
+// Each target proceeds independently, with bounded simultaneous door calls.
+// In-flight targets are excluded from the one next-due query until they settle.
+const MAX_ACTIVE_TARGETS = 16;
+const MAX_TIMER_MS = 2_147_483_647;
 
 const offline = (text) => String(text).includes('machine_offline');
 
@@ -35,195 +40,221 @@ 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, store, live, handOver, typeTurn, askMachine, log = () => {} }) {
-    Object.assign(this, { machine, store, live, handOver, typeTurn, askMachine, log });
+  constructor({ machine, store, live, handOver, typeTurn, typeUserTurns, paneOf, askMachine, log = () => {} }) {
+    Object.assign(this, { machine, store, live, handOver, typeTurn, typeUserTurns, paneOf, 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(`${address}\0${id}` → { address, id }): wakes for another machine
+    this.active = new Map(); // kind + target → the door call in progress
+    this.timer = null;
+    this.timerAt = null;
   }
 
-  /** 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. */
+  /** Writes refresh their target's persisted due row before notifying this
+   * scheduler. Only the startup/five-minute reconciliation walks all targets. */
   start() {
-    this.onWake = ({ address, id }) => this.#wake(address, id);
+    this.onWake = () => this.#schedule();
     this.store.on('wake', this.onWake);
+    this.onLive = () => {
+      if (this.stopped) return;
+      try { this.store.wakeIdleSessions(this.live.sessions().filter((row) => row.status === 'idle').map((row) => row.address)); }
+      catch (error) { this.log(`carrier: idle waits could not be resumed: ${error.message}`); }
+    };
+    this.live.on('changed', this.onLive);
     this.#sweep();
     this.sweeper = setInterval(() => this.#sweep(), LAST_RETRY_MS);
     this.sweeper.unref?.();
     return this;
   }
 
-  /** 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); }
+  #sweep() {
+    if (this.stopped) return;
+    try { this.store.reconcileDeliverySchedule(); this.#schedule(); }
+    catch (error) { this.log(`carrier: its delivery schedule could not be reconciled: ${error.message}`); }
+  }
 
-  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(); }
+  stop() {
+    this.stopped = true;
+    this.store.off('wake', this.onWake);
+    this.live.off('changed', this.onLive);
+    clearInterval(this.sweeper); clearTimeout(this.timer);
+    this.timer = null; this.timerAt = null;
+  }
 
-  /** 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(`${address}\0${id}`, { address, id });
-      this.#scheduleMachine(machine);
-      return;
+  #next() { return this.store.nextDeliveryTarget([...this.active.values()]); }
+
+  /** There is one due timer. A changed earlier deadline replaces it immediately,
+   * and a removed last delivery disarms it. Very distant dates are clamped to
+   * Node's timer range and queried again when that bound ends. */
+  #schedule() {
+    if (this.stopped) return;
+    let next;
+    try { next = this.active.size < MAX_ACTIVE_TARGETS ? this.#next() : null; }
+    catch (error) { this.log(`carrier: its next deadline could not be read: ${error.message}`); return; }
+    const at = next?.due_at_ms ?? null;
+    if (this.timer && this.timerAt === at) return;
+    clearTimeout(this.timer); this.timer = null; this.timerAt = at;
+    if (at == null) return;
+    this.timer = setTimeout(() => {
+      this.timer = null; this.timerAt = null;
+      try { this.#dispatch(); }
+      catch (error) { this.log(`carrier: its due target could not be read: ${error.message}`); }
+    }, Math.min(MAX_TIMER_MS, Math.max(0, at - Date.now())));
+    this.timer.unref?.();
+  }
+
+  #dispatch() {
+    if (this.stopped) return;
+    while (this.active.size < MAX_ACTIVE_TARGETS) {
+      const next = this.#next();
+      if (!next || next.due_at_ms > Date.now()) break;
+      const key = `${next.kind}\0${next.target}`;
+      this.active.set(key, { kind: next.kind, target: next.target });
+      let failed = false;
+      void (next.kind === 'mailbox' ? this.#local(next.target) : this.#carry(next.target))
+        .catch((error) => {
+          failed = true;
+          this.log(`carrier: ${next.target}'s attempt could not finish: ${error.message}`);
+          // A failed store operation must not create an immediate retry loop.
+          // An ordinary write may schedule sooner; reconciliation is the backstop.
+          if (!this.stopped) this.store.delayDeliveryTarget(next.kind, next.target, Date.now() + LAST_RETRY_MS);
+        })
+        .finally(() => {
+          this.active.delete(key);
+          if (!this.stopped) {
+            if (!failed) this.store.refreshDeliveryTarget(next.kind, next.target);
+            this.#schedule();
+          }
+        }).catch((error) => this.log(`carrier: ${next.target}'s schedule could not be kept: ${error.message}`));
     }
-    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(address); }, Math.max(0, (state.next_at_ms ?? 0) - Date.now()));
-    timer.unref?.();
-    this.timers.set(key, timer);
+    this.#schedule();
   }
 
   /** The wakes of one mailbox here that are due, attempted (mail_watch.rs `tick`, its local half). */
   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(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
-      const session = this.live.sessions().find((row) => row.address === address);
-      if ((session?.door === 'hook' || session?.door === 'pane') && session.pane) {
-        for (const id of due) {
-          const stored = this.store.findIn(address, id);
-          const envelope = stored ? this.store.body(stored) : null;
-          let carried;
-          if (!envelope) carried = { kind: 'filed' };
-          else {
-            try {
-              const typed = await this.typeTurn(session.pane, address.split(':')[2], render(envelope), [id]);
-              // held: the daemon's queue for the session types it once the composer frees; nothing asks it again
-              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(address, id, carried);
-        }
-        return;
+    const now = Date.now();
+    let due = this.store.dueWakes(address, 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
+    const session = this.live.sessions().find((row) => row.address === address);
+    const pane = session ? this.paneOf(session) : null;
+    const users = due.filter((id) => this.store.findIn(address, id)?.envelope.kind === 'user');
+    if (users.length) {
+      if (pane) await this.typeUserTurns(address, pane);
+      if (this.stopped) return;
+      for (const id of users) {
+        const found = this.store.findIn(address, id);
+        if (!found || found.state === 'read') this.#settle(address, id, { kind: 'filed' });
+        else this.store.setWakeState(address, id, { attempts: 0, next_at_ms: Date.now() + (pane ? FIRST_RETRY_MS : LAST_RETRY_MS), last_error: 'its user turn waits for an empty composer' });
       }
+      due = due.filter((id) => !users.includes(id));
+    }
+    // A terminal queue owns its accepted paste. Follow its durable outcome
+    // instead of sending another input or treating a queue entry as delivery.
+    due = due.filter((id) => {
+      const found = this.store.findIn(address, id);
+      if (!found || (found.state === 'read' && this.store.claimOf(address, id)?.recipient === true)) {
+        this.#settle(address, id, { kind: 'filed' });
+        return false;
+      }
+      const receipt = terminalReceipt(this.store, address, id);
+      if (!receipt) return true;
+      this.#settle(address, id, receipt.delivered ? { kind: 'delivered' }
+        : receipt.refused ? { kind: 'refused', reason: receipt.reason }
+          : { kind: 'pending', reason: receipt.reason });
+      return false;
+    });
+    if ((session?.door === 'hook' || session?.door === 'pane') && pane) {
       for (const id of due) {
-        const found = this.store.findIn(address, id);
+        const stored = this.store.findIn(address, id);
+        const envelope = stored ? this.store.body(stored) : null;
         let carried;
-        // its recipient has it already (its own read, or a hand-over by an attempt that ended before it was settled):
-        // never delivered twice; a read by anyone else does not count
-        if (!found || (found.state === 'read' && this.store.claimOf(address, id)?.recipient === true)) carried = { kind: 'filed' };
+        if (!envelope) carried = { kind: 'filed' };
         else {
           try {
-            let bound;
-            const answer = await Promise.race([
-              this.handOver(address, id),
-              new Promise((settle) => { bound = setTimeout(() => settle({ outcome: 'later', detail: `its hand-over was still running after ${HANDOVER_BOUND_MS / 1000} s` }), HANDOVER_BOUND_MS); bound.unref?.(); }),
-            ]).finally(() => clearTimeout(bound));
-            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}` }; }
+            const typed = await this.typeTurn(pane, address.split(':')[2], render(envelope), [id], address);
+            // held: the daemon's queue for the session types it once the composer frees; nothing asks it again
+            carried = typed?.delivered ? { kind: 'delivered' } : typed?.queued ? { kind: 'pending', reason: typed.reason }
+              : typed?.refused === true ? { kind: 'refused', reason: typed.reason } : { kind: 'later', reason: paneWaitReason(typed) };
+          } catch (error) { carried = { kind: 'later', reason: error.message }; }
         }
         if (this.stopped) return;
-        this.#record({ to: address, id, path: 'door', carried });
+        this.#record({ to: address, id, path: `${session.door}-pane`, carried });
         this.#settle(address, id, carried);
       }
-    } finally {
-      this.running.delete(address);
-      this.#rewake(address);
+      return;
     }
-  }
-
-  /** A mailbox's wakes followed again (each one scheduled at its own due time). */
-  #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(address) {
-    return this.store.wakes(address).filter((id) => {
-      if (this.store.findIn(address, id)) return true;
-      this.store.removeWake(address, id);
-      return false;
-    });
-  }
-
-  // ---- another machine's mail ------------------------------------------------------------------------------------
-
-  /** 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.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;
-      for (const { address, id } of this.#remoteWakes(machine)) at = Math.min(at, this.store.wakeState(address, id).next_at_ms ?? 0);
-      if (!Number.isFinite(at)) return;
+    for (const id of due) {
+      const found = this.store.findIn(address, id);
+      let carried;
+      // its recipient has it already (its own read, or a hand-over by an attempt that ended before it was settled):
+      // never delivered twice; a read by anyone else does not count
+      if (!found || (found.state === 'read' && this.store.claimOf(address, id)?.recipient === true)) carried = { kind: 'filed' };
+      else {
+        try {
+          let bound;
+          const answer = await Promise.race([
+            this.handOver(address, id),
+            new Promise((settle) => { bound = setTimeout(() => settle({ outcome: 'later', detail: `its hand-over was still running after ${HANDOVER_BOUND_MS / 1000} s` }), HANDOVER_BOUND_MS); bound.unref?.(); }),
+          ]).finally(() => clearTimeout(bound));
+          carried = answer?.outcome === 'delivered' ? { kind: 'delivered' } : answer?.outcome === 'filed' ? { kind: 'filed' }
+            : answer?.outcome === 'waiting' ? { kind: 'waiting', reason: answer.detail }
+              : answer?.outcome === 'pending' ? { kind: 'pending', reason: answer.detail } : { 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(address, id, carried);
     }
-    const timer = setTimeout(() => { this.machines.delete(machine); void this.#carry(machine); }, Math.max(0, at - Date.now()));
-    timer.unref?.();
-    this.machines.set(machine, timer);
   }
 
-  /** Every wake filed here for `machine` (as their events named them), with when its message was filed, oldest first; a
-   *  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) ?? []) {
-      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) 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);
-  }
+  // ---- another machine's mail ------------------------------------------------------------------------------------
 
-  /** 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. */
+  /** One offline probe establishes reachability. Once the machine answers,
+   * remaining batches obey each message's own retry deadline. */
   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 = 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.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;
-        }
-        if ((wait.next_probe_ms ?? 0) > now) return;
+    const now = Date.now();
+    let wait = this.store.machineWait(machine);
+    // Earlier candidates kept an online-draining wait. Its existence must not
+    // release newly assigned failure deadlines on this owner or after restart.
+    if (wait?.online_draining) { this.#setMachineWait(machine, null); wait = null; }
+    const offlineExpired = wait && now - (wait.offline_since_ms ?? now) >= OFFLINE_CEILING_MS;
+    const items = this.store.remoteWakes(machine, now, { probing: Boolean(wait), limit: wait && !offlineExpired ? 1 : 256 });
+    if (!items.length) return;
+    if (wait) {
+      // a machine away longer than the ceiling is not coming back for this mail: it expires, saying so
+      if (offlineExpired) {
+        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.address, item.id, this.store.wakeState(item.address, item.id).attempts ?? 0, reason);
+        if (!this.store.remoteWakes(machine, now, { probing: true, limit: 1 }).length) this.#setMachineWait(machine, null);
+        this.#line({ t: now, machine, outcome: 'expired', messages: items.length, reason });
+        return;
       }
-      let carriedHere = 0, offlineAnswer = null, called = false;
-      for (const item of items) {
-        if (!wait && (this.store.wakeState(item.address, item.id).next_at_ms ?? 0) > now) continue;
-        const found = this.store.findIn(item.address, item.id);
-        let carried;
-        // carried already (this carrier's own record): never carried twice
-        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, this.store.body(found));
-        }
-        if (this.stopped) return;
-        if (carried.kind === 'offline') { offlineAnswer = carried.reason; break; }
-        carriedHere++;
-        this.#settle(item.address, item.id, carried);
+      if ((wait.next_probe_ms ?? 0) > now) return;
+    }
+    let carriedHere = 0, offlineAnswer = null, called = false;
+    for (const item of items) {
+      if (!wait && (this.store.wakeState(item.address, item.id).next_at_ms ?? 0) > now) continue;
+      const found = this.store.findIn(item.address, item.id);
+      let carried;
+      // carried already (this carrier's own record): never carried twice
+      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, this.store.body(found));
       }
-      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 });
-      else if (called) this.#setMachineWait(machine, null);
-    } finally {
-      this.carrying.delete(machine);
-      this.#scheduleMachine(machine);
+      if (this.stopped) return;
+      if (carried.kind === 'offline') { offlineAnswer = carried.reason; break; }
+      carriedHere++;
+      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 });
+    // A refusal still proves that the machine answered. Clearing its wait
+    // restores due-row selection; this attempt's failure keeps its backoff,
+    // and unattempted due mail advances without probing that failure again.
+    else if (wait || called) this.#setMachineWait(machine, null);
   }
 
   /** One message carried to its machine's mail door, filed there with a wake. */
@@ -242,7 +273,7 @@ export class MailCarrier {
   }
 
   #setMachineWait(machine, wait) {
-    try { this.store.setMachineWait(machine, wait); } catch (error) { this.log(`carrier: ${machine}'s wait was not kept: ${error.message}`); }
+    this.store.setMachineWait(machine, wait);
   }
 
   // ---- what waits, and what expired (`message waiting`, `message expired`) -----------------------------------------
@@ -255,7 +286,8 @@ export class MailCarrier {
     for (const { address, id } of this.store.allWakes()) {
       const machine = address.split(':')[1];
       if (machine !== this.machine && !waits.has(machine)) waits.set(machine, this.store.machineWait(machine));
-      const wait = machine !== this.machine ? waits.get(machine) : null;
+      const heldWait = machine !== this.machine ? waits.get(machine) : null;
+      const wait = heldWait?.online_draining ? null : heldWait;
       {
         const state = this.store.wakeState(address, id);
         if (!wait && !(state.attempts > 0) && state.last_error == null) continue;
@@ -288,9 +320,25 @@ export class MailCarrier {
       return;
     }
     if (carried.kind === 'offline') return;
+    if (carried.kind === 'pending') {
+      const state = this.store.wakeState(address, id);
+      this.store.setWakeState(address, id, { ...state, next_at_ms: Date.now() + FIRST_RETRY_MS, last_error: carried.reason });
+      return;
+    }
+    if (carried.kind === 'waiting') {
+      const state = this.store.wakeState(address, id);
+      this.store.setWakeState(address, id, { ...state, waiting_for_idle: true, next_at_ms: Date.now() + LAST_RETRY_MS });
+      return;
+    }
     const now = Date.now();
     const state = this.store.wakeState(address, id);
+    const envelope = this.store.findIn(address, id)?.envelope;
+    if (envelope?.pool_reply_failure_notice || envelope?.delivery_failure_notice) {
+      this.store.setWakeState(address, id, { ...state, next_at_ms: now + LAST_RETRY_MS, last_error: carried.reason });
+      return;
+    }
     const attempts = (state.attempts ?? 0) + 1;
+    if (carried.kind === 'refused') { this.#expire(address, id, attempts, carried.reason); return; }
     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(address, id, attempts, carried.reason); return; }
@@ -300,10 +348,7 @@ export class MailCarrier {
 
   /** 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 ? 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 { this.store.expire(address, id, expiry); } catch (error) { this.log(`carrier: the expiry of ${id} was not recorded: ${error.message}`); }
+    expireDelivery(this.store, this.machine, address, id, attempts, reason);
   }
 
   /** One local delivery attempt in the carrier's record. */

package/mail/change-stream.mjs

@@ -0,0 +1,143 @@
+// Durable owner-side row changes. SQL triggers record each mutation in its
+// transaction; a commit event merely wakes readers of that persisted sequence.
+import { randomUUID } from 'node:crypto';
+
+export const MAX_CHANGE_ROWS = 100_000;
+const PAGE = 256;
+
+const ROWS = [
+  ['machine_record_heads', 'record-head', (row) => `json_object('role', ${row}.role, 'machine', ${row}.machine)`, (row) => `${row}.value`],
+  ['machine_record_rows', 'record-row', (row) => `json_object('role', ${row}.role, 'machine', ${row}.machine, 'section', ${row}.section, 'key', ${row}.key, 'position', ${row}.position)`, (row) => `${row}.value`],
+  ['messages', 'message', (row) => `json_object('address', ${row}.mailbox, 'id', ${row}.id)`,
+    (row) => `json_object('state', ${row}.state, 'body_expired_at_ms', ${row}.body_expired_at_ms)`],
+  ['deliveries', 'delivery', (row) => `json_object('address', ${row}.mailbox, 'id', ${row}.message)`,
+    (row) => `json_object('due_at_ms', ${row}.due_at_ms, 'attempts', ${row}.attempts)`],
+  ['claims', 'claim', (row) => `json_object('address', ${row}.mailbox, 'id', ${row}.message)`],
+  ['subscriptions', 'subscription', (row) => `json_object('address', ${row}.mailbox, 'id', ${row}.message)`],
+  ['mail_records', 'record', (row) => `json_object('collection', ${row}.collection, 'key', ${row}.key)`],
+  ['thread_markers', 'thread_marker', (row) => `json_object('thread', ${row}.thread, 'marker', ${row}.marker)`],
+  ['sent_messages', 'sent', (row) => `json_object('sender_key', ${row}.sender_key, 'id', ${row}.id, 'recipient', ${row}.recipient)`],
+];
+
+export const CHANGE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS machine_changes (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  at_ms INTEGER NOT NULL,
+  topic TEXT NOT NULL,
+  key TEXT NOT NULL CHECK (json_valid(key)),
+  operation TEXT NOT NULL CHECK (operation IN ('insert', 'update', 'delete')),
+  value TEXT CHECK (value IS NULL OR json_valid(value))
+) STRICT;
+CREATE INDEX IF NOT EXISTS machine_changes_topic ON machine_changes(topic, sequence);
+CREATE TRIGGER IF NOT EXISTS machine_changes_bound AFTER INSERT ON machine_changes BEGIN
+  DELETE FROM machine_changes WHERE sequence <= NEW.sequence - ${MAX_CHANGE_ROWS};
+END;
+${ROWS.flatMap(([table, topic, key, value]) => ['insert', 'update', 'delete'].map((operation) => {
+  const row = operation === 'delete' ? 'OLD' : 'NEW';
+  return `CREATE TRIGGER IF NOT EXISTS ${table}_change_${operation} AFTER ${operation.toUpperCase()} ON ${table} BEGIN
+    INSERT INTO machine_changes(at_ms, topic, key, operation, value)
+      VALUES (CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER), '${topic}', ${key(row)}, '${operation}', ${value && operation !== 'delete' ? value(row) : 'NULL'});
+  END;`;
+})).join('\n')}
+`;
+
+export class ChangeStream {
+  constructor(database) {
+    this.database = database;
+    this.id = database.metadata('change_stream_id');
+    if (!this.id) { this.id = randomUUID(); database.setMetadata('change_stream_id', this.id); }
+    this.readers = new Set();
+  }
+
+  cursor() {
+    const row = this.database.statement("SELECT seq FROM sqlite_sequence WHERE name = 'machine_changes'").get();
+    return { id: this.id, sequence: row?.seq ?? 0 };
+  }
+
+  /** A cursor is for this database, not merely a number that another fresh
+   * database may reach. A pruned gap is explicit and never a partial replay. */
+  read(after, { topics = [], addresses = [], limit = PAGE } = {}) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > PAGE) throw new Error('a change page has 1–256 rows');
+    if (![topics, addresses].every((items) => Array.isArray(items) && items.every((item) => typeof item === 'string'))) throw new Error('change filters must be string arrays');
+    const head = this.cursor();
+    const oldest = this.database.statement('SELECT min(sequence) AS sequence FROM machine_changes').get().sequence ?? head.sequence + 1;
+    let reason = null;
+    if (!after) reason = 'no cursor';
+    else if (after.id !== this.id) reason = 'the cursor names a different database';
+    else if (!Number.isSafeInteger(after.sequence) || after.sequence < 0 || after.sequence > head.sequence) reason = 'the cursor sequence is invalid';
+    else if (after.sequence < oldest - 1) reason = 'the retained change window no longer contains this cursor';
+    if (reason) return { cursor: head, reset: true, reason, changes: [], more: false };
+    const rows = this.database.statement(`SELECT sequence, at_ms, topic, key, operation, value FROM machine_changes
+      WHERE sequence > ? AND (json_array_length(?) = 0 OR topic IN (SELECT value FROM json_each(?)))
+      AND (json_array_length(?) = 0 OR json_extract(key, '$.address') IN (SELECT value FROM json_each(?)))
+      ORDER BY sequence LIMIT ?`).all(after.sequence, JSON.stringify(topics), JSON.stringify(topics), JSON.stringify(addresses), JSON.stringify(addresses), limit + 1);
+    const more = rows.length > limit;
+    if (more) rows.pop();
+    return {
+      cursor: { id: this.id, sequence: more ? rows.at(-1).sequence : head.sequence }, reset: false, more,
+      changes: rows.map(({ key, value, ...row }) => ({ ...row, key: JSON.parse(key), value: value == null ? null : JSON.parse(value) })),
+    };
+  }
+
+  /** Owner-generated changes (for example record row deltas) share the sequence
+   * with mail, and can be committed with the state that they describe. */
+  append(topic, key, value, operation = 'update') {
+    const row = this.database.statement('INSERT INTO machine_changes(at_ms, topic, key, operation, value) VALUES (?, ?, ?, ?, ?)')
+      .run(Date.now(), topic, JSON.stringify(key), operation, value == null ? null : JSON.stringify(value));
+    return { id: this.id, sequence: Number(row.lastInsertRowid) };
+  }
+
+  /** Subscribe before the first read. A synchronous commit between page reads
+   * marks the drain dirty; reconnects resume from the last delivered cursor. */
+  follow(write, { after = null, topics = [], addresses = [], initial = false } = {}) {
+    let cursor = after, closed = false, scheduled = false, first = true;
+    const stop = () => {
+      if (closed) return;
+      closed = true; this.database.off('commit', wake); this.readers.delete(stop);
+    };
+    const drain = () => {
+      scheduled = false;
+      if (closed || this.database.closed) return stop();
+      try {
+        const page = this.read(cursor, { topics, addresses });
+        cursor = page.cursor;
+        if (page.reset || page.changes.length || (first && initial)) {
+          const resumed = write(page);
+          if (resumed?.id === this.id && Number.isSafeInteger(resumed.sequence)) cursor = resumed;
+        }
+        first = false;
+        if (page.more) wake();
+      } catch (error) { stop(); try { write({ error: error.message }); } catch { /* its reader is gone */ } }
+    };
+    const wake = () => {
+      if (closed || scheduled) return;
+      scheduled = true; setImmediate(drain);
+    };
+    this.database.on('commit', wake); this.readers.add(stop); wake();
+    return stop;
+  }
+
+  /** A long-poll predicate is evaluated after installing the durable stream,
+   * closing the old read/listen gap. A cursor reset asks the predicate for its
+   * current snapshot. Stop resolves false before the database is closed. */
+  wait(predicate, { topics = [], addresses = [], timeoutMs = 0 } = {}) {
+    return new Promise((resolve, reject) => {
+      let timer, settled = false;
+      const finish = (value, error = null) => {
+        if (settled) return;
+        settled = true; clearTimeout(timer); stop(); this.readers.delete(ended);
+        error ? reject(error) : resolve(value);
+      };
+      const check = () => {
+        try { if (predicate()) finish(true); } catch (error) { finish(false, error); }
+      };
+      const ended = () => finish(false);
+      const stop = this.follow((page) => page.error ? finish(false, new Error(page.error)) : check(), { after: this.cursor(), topics, addresses });
+      this.readers.add(ended);
+      timer = setTimeout(() => finish(false), Math.max(0, timeoutMs));
+      check();
+    });
+  }
+
+  stop() { for (const stop of [...this.readers]) stop(); }
+}