@volter/supercode-teams 0.3.150 → 0.3.152

package/mail/sqlite-store.mjs

@@ -0,0 +1,476 @@
+// Indexed mail state behind the machine socket. The row reference in `path` is
+// opaque compatibility data for owner-side callers; it is never a filesystem path.
+import { EventEmitter } from 'node:events';
+import { createHash, randomBytes } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { blake3Hex } from './envelope.mjs';
+import { MailDatabase, MailOwner, RETAINED_BODY } from './sqlite.mjs';
+import { migrateMaildir } from './retire-maildir.mjs';
+
+export const MIN_PREFIX_DIGITS = 4;
+export { RETAINED_BODY };
+const STATES = { new: 'unread', claimed: 'unread', cur: 'read' };
+const alive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+};
+const rowReference = (address, id) => `mail-row:${Buffer.from(JSON.stringify([address, id])).toString('base64url')}`;
+const reference = (value) => {
+  if (value && typeof value === 'object') return [value.address, value.envelope?.id ?? value.messageId];
+  if (typeof value !== 'string' || !value.startsWith('mail-row:')) return null;
+  try { return JSON.parse(Buffer.from(value.slice(9), 'base64url').toString()); } catch { return null; }
+};
+const stored = (row) => ({
+  address: row.mailbox, messageId: row.id, envelope: JSON.parse(row.header),
+  state: STATES[row.state], part: row.state, path: rowReference(row.mailbox, row.id),
+  ...(row.claim_token ? { claimToken: row.claim_token } : {}),
+});
+const COLUMNS = 'mailbox, id, header, state, claim_token';
+const validId = (id) => typeof id === 'string' && /^[A-Za-z0-9_-]+$/.test(id);
+
+export class SqliteMailStore extends EventEmitter {
+  constructor({ mailRoot, machine = null, log = () => {}, database = null, retention } = {}) {
+    super();
+    this.root = resolve(mailRoot);
+    this.machine = machine;
+    this.log = log;
+    this.database = database;
+    this.retention = retention;
+    this.unread = null;
+  }
+
+  /** Import is completed by the owner before this handle becomes available to
+   * clients. A completed database never opens a Maildir to answer a query. */
+  acquire() {
+    this.owner ??= new MailOwner(join(dirname(this.root), 'mail-owner.sqlite'));
+    return this;
+  }
+
+  async start() {
+    if (!this.owner) throw new Error('mail cannot open without this daemon\'s writer lease');
+    this.database ??= new MailDatabase(join(dirname(this.root), 'mail.sqlite'), { retention: this.retention });
+    this.imported = await migrateMaildir(this.database, this.root, { log: this.log });
+    this.database.retain();
+    this.database.on('message', (address) => this.emit('changed', address));
+    this.database.on('wake', ({ address, id }) => this.emit('wake', { address, id }));
+    this.database.on('subscriptions', (address) => this.emit('subscriptions', address));
+    this.retentionTimer = setInterval(() => {
+      try { this.database.retain(); }
+      catch (error) { this.log(`mail retention failed: ${error.message}`); }
+    }, 3_600_000);
+    this.retentionTimer.unref?.();
+    return this;
+  }
+
+  stop() {
+    clearInterval(this.retentionTimer);
+    this.removeAllListeners();
+    this.database?.close();
+    this.owner?.close(); this.owner = null;
+  }
+  statement(sql) { return this.database.statement(sql); }
+  transaction(operation) { return this.database.transaction(operation); }
+  record(collection, key) { return this.database.record(collection, key); }
+  records(collection) { return this.database.records(collection); }
+  putRecord(collection, key, value, options) { return this.database.putRecord(collection, key, value, options); }
+  removeRecord(collection, key) { return this.database.removeRecord(collection, key); }
+
+  statistics(now = Date.now()) {
+    const since = now - 86_400_000;
+    const states = this.statement('SELECT state, count(*) AS count FROM messages GROUP BY state ORDER BY state').all();
+    const writers = this.statement(`SELECT sender, kind, count(*) AS mailbox_copies, count(DISTINCT id) AS message_ids
+      FROM messages WHERE created_at_ms >= ? AND created_at_ms <= ?
+      GROUP BY sender, kind ORDER BY mailbox_copies DESC, sender, kind LIMIT 20`).all(since, now);
+    const pageSize = this.statement('PRAGMA page_size').get().page_size;
+    return {
+      at_ms: now,
+      schema: this.database.metadata('schema_version'),
+      messages: Object.fromEntries(states.map(({ state, count }) => [state, count])),
+      mailbox_count: this.statement('SELECT count(*) AS count FROM mailboxes').get().count,
+      pending_deliveries: this.statement('SELECT count(*) AS count FROM deliveries').get().count,
+      subscriptions: this.statement('SELECT count(*) AS count FROM subscriptions').get().count,
+      carrier_rows: this.statement('SELECT count(*) AS count FROM carrier_log').get().count,
+      terminal_log_rows: this.statement('SELECT count(*) AS count FROM terminal_log').get().count,
+      logical_bytes: this.statement('PRAGMA page_count').get().page_count * pageSize,
+      reusable_bytes: this.statement('PRAGMA freelist_count').get().freelist_count * pageSize,
+      recent_writers: { since_ms: since, through_ms: now, limit: 20, rows: writers, basis: 'stored envelope creation time; counts include recipient copies, not attempted calls' },
+      import: this.database.metadata('maildir_import'),
+      retirement: this.database.metadata('maildir_retirement'),
+      retention: this.database.metadata('retention'),
+    };
+  }
+
+  addresses() { return this.statement('SELECT address FROM mailboxes ORDER BY address').all().map((row) => row.address); }
+
+  boxOf(address) {
+    const row = this.statement('SELECT address, folder FROM mailboxes WHERE address = ?').get(address);
+    return row ? { ...row, dir: join(this.root, row.folder) } : null;
+  }
+
+  addressOfFolder(folder) { return this.statement('SELECT address FROM mailboxes WHERE folder = ?').get(folder)?.address ?? null; }
+
+  open(address) {
+    const known = this.boxOf(address);
+    if (known) return known;
+    const [, machine, harness, session] = String(address).split(':');
+    if (!machine || !harness || !session) throw new Error(`not a mail address: ${address}`);
+    const folder = `${harness.replace(/[^A-Za-z0-9-]/g, '_')}-${blake3Hex(String(address)).slice(0, 24)}`;
+    this.statement('INSERT INTO mailboxes(address, folder) VALUES (?, ?) ON CONFLICT(address) DO NOTHING').run(address, folder);
+    return this.boxOf(address);
+  }
+
+  inventory(address) {
+    return {
+      stored: this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? ORDER BY created_at_ms, id`).all(address).map(stored),
+      skipped: this.statement('SELECT source FROM mail_import_errors WHERE mailbox = ? ORDER BY source').all(address).map((row) => row.source),
+    };
+  }
+
+  unreadMessages(address) {
+    return this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? AND state IN ('new', 'claimed') ORDER BY created_at_ms, id`).all(address).map(stored);
+  }
+
+  typedSince(address, since, prefix) {
+    return this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? AND kind = 'user'
+      AND created_at_ms > ? AND id >= ? AND id < ? ORDER BY created_at_ms, id`)
+      .all(address, since, prefix, `${prefix}\uffff`).map(stored);
+  }
+
+  threadIn(address, thread) {
+    return this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? AND thread = ? ORDER BY created_at_ms, id`)
+      .all(address, thread).map(stored);
+  }
+
+  headerWindow(address, recent) {
+    if (!Number.isSafeInteger(recent) || recent < 0) throw Object.assign(new Error('recent must be a nonnegative integer'), { code: 400 });
+    return {
+      unread: this.unreadMessages(address),
+      recent: this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? ORDER BY created_at_ms DESC, id DESC LIMIT ?`).all(address, recent).map(stored),
+      count: this.statement('SELECT count(*) AS count FROM messages WHERE mailbox = ?').get(address).count,
+      skipped: this.statement('SELECT source FROM mail_import_errors WHERE mailbox = ? ORDER BY source').all(address).map(({ source }) => source),
+    };
+  }
+
+  history(address, last = null) {
+    if (last !== null && (!Number.isSafeInteger(last) || last < 0)) throw Object.assign(new Error('last must be a nonnegative integer'), { code: 400 });
+    return this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? AND (state = 'cur' OR (state = 'claimed' AND kind = 'user'))
+      ORDER BY created_at_ms DESC, id DESC LIMIT ?`).all(address, last ?? -1).reverse().map(stored);
+  }
+
+  timeline(address, last = null) {
+    if (last !== null && (!Number.isSafeInteger(last) || last < 0)) throw Object.assign(new Error('last must be a nonnegative integer'), { code: 400 });
+    return this.statement(`SELECT ${COLUMNS}, created_at_ms, 'in' AS direction FROM messages
+      WHERE mailbox = ? AND NOT (kind = 'question' AND sender = ?)
+      UNION ALL SELECT ${COLUMNS}, created_at_ms, 'out' AS direction FROM messages WHERE sender = ? AND mailbox <> ?
+      ORDER BY created_at_ms DESC, direction DESC, mailbox DESC, id DESC LIMIT ?`)
+      .all(address, address, address, address, last ?? -1).reverse()
+      .map((row) => ({ address: row.mailbox, stored: stored(row), direction: row.direction }));
+  }
+
+  replies(address, id) {
+    // Older reply headers could carry a ten-character prefix. The parent index
+    // serves the finite set of compatible spellings, scoped to this mailbox.
+    const parents = new Set([id]);
+    for (let length = 10; length < id.length; length++) parents.add(id.slice(0, length));
+    const query = this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? AND json_extract(header, '$.in_reply_to') = ? ORDER BY created_at_ms, id`);
+    const rows = [...parents].flatMap((parent) => query.all(address, parent));
+    rows.sort((a, b) => JSON.parse(a.header).created_at_ms - JSON.parse(b.header).created_at_ms || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return rows.map(stored);
+  }
+
+  replyParent(a, b, id) {
+    const row = this.statement(`SELECT json_extract(header, '$.in_reply_to') AS parent FROM messages
+      WHERE mailbox IN (?, ?) AND id = ? ORDER BY CASE mailbox WHEN ? THEN 0 ELSE 1 END LIMIT 1`).get(a, b, id, b);
+    return row ? row.parent : undefined;
+  }
+
+  body(item) {
+    const key = reference(item);
+    if (!Array.isArray(key) || key.length !== 2 || key.some((value) => typeof value !== 'string')) return null;
+    const row = this.statement('SELECT header, body, body_expired_at_ms FROM messages WHERE mailbox = ? AND id = ?').get(...key);
+    if (!row) return null;
+    const header = JSON.parse(row.header);
+    return row.body_expired_at_ms != null
+      ? { ...header, body: RETAINED_BODY, body_expired_at_ms: row.body_expired_at_ms }
+      : { ...header, body: row.body ?? '' };
+  }
+
+  find(id) {
+    const digits = id.includes('-') ? id.slice(id.indexOf('-') + 1).length : 0;
+    if (digits < MIN_PREFIX_DIGITS) return [];
+    const rows = this.statement(`SELECT ${COLUMNS} FROM messages WHERE id >= ? AND id < ? ORDER BY id, mailbox`).all(id, `${id}\uffff`);
+    const seen = new Set();
+    return rows.filter((row) => { if (seen.has(row.id)) return false; seen.add(row.id); return true; })
+      .map((row) => ({ address: row.mailbox, stored: stored(row) }));
+  }
+
+  firstLines(ids) {
+    const lines = new Map();
+    const query = this.statement('SELECT first_line FROM messages WHERE id = ? ORDER BY mailbox LIMIT 1');
+    for (const id of new Set(ids)) { const row = query.get(id); if (row) lines.set(id, row.first_line); }
+    return lines;
+  }
+
+  threadMessages(thread) {
+    return this.statement(`SELECT ${COLUMNS} FROM messages WHERE thread = ? ORDER BY created_at_ms, id, mailbox`).all(thread)
+      .map((row) => ({ address: row.mailbox, stored: stored(row) }));
+  }
+
+  /** Follow the same reply graph as the old thread verb, using the id, thread
+   * and parent indexes. A copy's canonical header is the first mailbox's, as
+   * the verb's former address-ordered map selected it. */
+  conversation(prefix) {
+    const matches = this.statement('SELECT count(DISTINCT id) AS count FROM messages WHERE id >= ? AND id < ?').get(prefix, `${prefix}\uffff`).count;
+    if (matches !== 1) return { matches, messages: [] };
+    const one = this.statement(`SELECT ${COLUMNS} FROM messages WHERE id >= ? AND id < ? ORDER BY mailbox LIMIT 1`).get(prefix, `${prefix}\uffff`);
+    const named = this.statement(`SELECT ${COLUMNS} FROM messages WHERE id = ? ORDER BY mailbox LIMIT 1`);
+    let root = one;
+    const ancestors = new Set();
+    for (;;) {
+      const parent = JSON.parse(root.header).in_reply_to;
+      if (typeof parent !== 'string' || ancestors.has(parent)) break;
+      const found = named.get(parent);
+      if (!found) break;
+      ancestors.add(parent); root = found;
+    }
+    const header = JSON.parse(root.header);
+    const canonical = 'NOT EXISTS (SELECT 1 FROM messages other WHERE other.id = m.id AND other.mailbox < m.mailbox)';
+    const columns = COLUMNS.split(', ').map((column) => `m.${column}`).join(', ');
+    const roots = this.statement(`SELECT ${columns} FROM messages m WHERE thread = ? AND ${canonical} ORDER BY created_at_ms, id, mailbox`)
+      .all(header.thread ?? header.id);
+    const children = this.statement(`SELECT ${columns} FROM messages m WHERE json_extract(header, '$.in_reply_to') = ? AND ${canonical} ORDER BY created_at_ms, id, mailbox`);
+    const queue = [root, ...roots], members = new Map();
+    while (queue.length) {
+      const row = queue.pop();
+      if (members.has(row.id)) continue;
+      members.set(row.id, { address: row.mailbox, stored: stored(row) });
+      for (const child of children.all(row.id)) queue.push(child);
+    }
+    return { matches, messages: [...members.values()] };
+  }
+
+  findIn(address, id) {
+    const row = this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? AND id = ?`).get(address, id);
+    return row ? stored(row) : null;
+  }
+
+  findPrefixIn(address, prefix) {
+    return this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? AND id >= ? AND id < ? ORDER BY created_at_ms, id`)
+      .all(address, prefix, `${prefix}\uffff`).map((row) => { const item = stored(row); return { ...item, envelope: this.body(item) }; });
+  }
+
+  links(address) {
+    return new Map(this.statement('SELECT id, json_extract(header, \'$.in_reply_to\') AS parent FROM messages WHERE mailbox = ?').all(address)
+      .map((row) => [row.id, row.parent ?? null]));
+  }
+
+  #recoverAbandoned(address) {
+    const pids = this.statement("SELECT DISTINCT claim_pid FROM messages WHERE mailbox = ? AND state = 'claimed'").all(address);
+    const release = this.statement("UPDATE messages SET state = 'new', claim_pid = NULL, claim_token = NULL WHERE mailbox = ? AND state = 'claimed' AND claim_pid = ?");
+    for (const { claim_pid: pid } of pids) {
+      if (!alive(pid) && release.run(address, pid).changes) this.database.changed('message', address);
+    }
+  }
+
+  hasClaimable(address, wanted = null) {
+    this.#recoverAbandoned(address);
+    if (!wanted) return Boolean(this.statement("SELECT 1 FROM messages WHERE mailbox = ? AND state = 'new' AND kind != 'user' LIMIT 1").get(address));
+    return this.statement("SELECT header FROM messages WHERE mailbox = ? AND state = 'new' AND kind != 'user'").all(address)
+      .some((row) => wanted(JSON.parse(row.header)));
+  }
+
+  claimUnread(address, via, caller, pid = process.pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error('mail reader PID must be a positive integer');
+    return this.transaction(() => {
+      this.#recoverAbandoned(address);
+      const rows = this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? AND state = 'new' AND kind != 'user' ORDER BY created_at_ms, id`).all(address);
+      const take = this.statement("UPDATE messages SET state = 'claimed', claim_pid = ?, claim_token = ? WHERE mailbox = ? AND id = ? AND state = 'new'");
+      const claimed = [];
+      for (const row of rows) {
+        const token = randomBytes(16).toString('hex');
+        if (!take.run(pid, token, address, row.id).changes) continue;
+        this.claimFor(address, row.id, { pid, via, caller: caller ?? null, recipient: true, at_ms: Date.now() });
+        claimed.push(stored({ ...row, state: 'claimed', claim_token: token }));
+      }
+      if (claimed.length) this.database.changed('message', address);
+      return claimed;
+    });
+  }
+
+  userTurns(address) {
+    return this.statement(`SELECT ${COLUMNS} FROM messages WHERE mailbox = ? AND state = 'new' AND kind = 'user'
+      AND COALESCE(json_extract(header, '$.in_reply_to'), '') NOT LIKE 'q-%' ORDER BY created_at_ms, id`)
+      .all(address).map((row) => { const item = stored(row); return { ...item, envelope: this.body(item) }; });
+  }
+
+  claimUserTurn(address, waiting) {
+    return this.transaction(() => {
+      this.#recoverAbandoned(address);
+      const token = randomBytes(16).toString('hex');
+      const changed = this.statement("UPDATE messages SET state = 'claimed', claim_pid = ?, claim_token = ? WHERE mailbox = ? AND id = ? AND state = 'new' AND kind = 'user'")
+        .run(process.pid, token, address, waiting.envelope.id).changes;
+      if (!changed) return null;
+      this.database.changed('message', address);
+      return { ...waiting, part: 'claimed', claimToken: token };
+    });
+  }
+
+  release(address, claimed) { return this.#settle(address, claimed, 'new'); }
+  acknowledge(address, claimed) { return this.#settle(address, claimed, 'cur'); }
+
+  #settle(address, claimed, state) {
+    if (!claimed.claimToken) return false;
+    const changed = this.statement(`UPDATE messages SET state = ?, claim_pid = NULL, claim_token = NULL, read_at_ms = ?
+      WHERE mailbox = ? AND id = ? AND state = 'claimed' AND claim_token = ?`)
+      .run(state, state === 'cur' ? Date.now() : null, address, claimed.envelope.id, claimed.claimToken).changes > 0;
+    if (changed) this.database.changed('message', address);
+    return changed;
+  }
+
+  claimFor(address, id, claim) {
+    this.statement('INSERT INTO claims(mailbox, message, record) VALUES (?, ?, ?) ON CONFLICT(mailbox, message) DO UPDATE SET record = excluded.record')
+      .run(address, id, JSON.stringify(claim));
+  }
+  recordClaim(box, id, claim) { return this.claimFor(box.address, id, claim); }
+  claimOf(address, id) { const row = this.statement('SELECT record FROM claims WHERE mailbox = ? AND message = ?').get(address, id); return row ? JSON.parse(row.record) : null; }
+
+  #deliver(address, envelope, state) {
+    if (this.machine && String(address).split(':')[1] !== this.machine && String(envelope?.sender_identity?.observation ?? '').startsWith('link:')) {
+      throw new Error(`not carried on to ${address}: a message that came to this machine through a link is for its own sessions only`);
+    }
+    if (!validId(envelope.id) || !Number.isSafeInteger(envelope.created_at_ms) || typeof envelope.body !== 'string') throw new Error('invalid mail envelope');
+    return this.transaction(() => {
+      this.open(address);
+      const { body, ...header } = envelope;
+      const firstLine = Array.from(body.split('\n', 1)[0]).slice(0, 400).join('');
+      const changed = this.statement(`INSERT INTO messages(mailbox, id, thread, sender, kind, subject, created_at_ms, state, header, body, first_line, read_at_ms)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(mailbox, id) DO NOTHING`)
+        .run(address, envelope.id, envelope.thread ?? envelope.id, envelope.from ?? '', envelope.kind ?? 'peer', envelope.subject ?? null,
+          envelope.created_at_ms, state, JSON.stringify(header), body, firstLine, state === 'cur' ? Date.now() : null).changes;
+      if (changed) this.database.changed('message', address);
+      return rowReference(address, envelope.id);
+    });
+  }
+  deliver(address, envelope) { return this.#deliver(address, envelope, 'new'); }
+  deliverRead(address, envelope) { return this.#deliver(address, envelope, 'cur'); }
+
+  #mark(address, path, state) {
+    const key = reference(path);
+    if (!key || key[0] !== address) throw new Error('mail row reference belongs to a different mailbox');
+    const changed = this.statement('UPDATE messages SET state = ?, claim_pid = NULL, claim_token = NULL, read_at_ms = ? WHERE mailbox = ? AND id = ?')
+      .run(state, state === 'cur' ? Date.now() : null, address, key[1]).changes;
+    if (changed) this.database.changed('message', address);
+  }
+  markRead(address, path) { return this.#mark(address, path, 'cur'); }
+  markUnread(address, path) { return this.#mark(address, path, 'new'); }
+
+  remove(address, path) {
+    const key = reference(path);
+    if (!key || key[0] !== address) throw new Error('mail row reference belongs to a different mailbox');
+    const changed = this.statement('DELETE FROM messages WHERE mailbox = ? AND id = ?').run(address, key[1]).changes > 0;
+    if (changed) this.database.changed('message', address);
+    return changed;
+  }
+
+  requestWake(address, id, { keep = false } = {}) {
+    if (!validId(id)) throw new Error('invalid wake message id');
+    this.open(address);
+    const sql = `INSERT INTO deliveries(mailbox, message, due_at_ms, attempts, record) VALUES (?, ?, 0, 0, '{}')
+      ON CONFLICT(mailbox, message) ${keep ? 'DO NOTHING' : "DO UPDATE SET due_at_ms = 0, attempts = 0, record = '{}'"}`;
+    if (this.statement(sql).run(address, id).changes) this.database.changed('wake', { address, id });
+  }
+  wakes(address) { return this.statement('SELECT message FROM deliveries WHERE mailbox = ? ORDER BY due_at_ms, message').all(address).map((row) => row.message); }
+  allWakes() { return this.statement('SELECT mailbox AS address, message AS id FROM deliveries ORDER BY due_at_ms, mailbox, message').all(); }
+  hasWake(address, id) { return validId(id) && Boolean(this.statement('SELECT 1 FROM deliveries WHERE mailbox = ? AND message = ?').get(address, id)); }
+  removeWake(address, id) { return this.statement('DELETE FROM deliveries WHERE mailbox = ? AND message = ?').run(address, id).changes > 0; }
+  wakeState(address, id) {
+    const row = this.statement('SELECT record FROM deliveries WHERE mailbox = ? AND message = ?').get(address, id);
+    return { attempts: 0, next_at_ms: 0, last_error: null, ...(row ? JSON.parse(row.record) : {}) };
+  }
+  setWakeState(address, id, state) {
+    const record = { attempts: state.attempts ?? 0, next_at_ms: state.next_at_ms ?? 0, last_error: state.last_error ?? null,
+      handover_at_ms: state.handover_at_ms ?? null, failing_since_ms: state.failing_since_ms ?? null };
+    if (this.statement('UPDATE deliveries SET record = ?, due_at_ms = ?, attempts = ? WHERE mailbox = ? AND message = ?')
+      .run(JSON.stringify(record), record.next_at_ms, record.attempts, address, id).changes) this.database.changed('wake', { address, id });
+  }
+
+  expire(address, id, expiry) {
+    return this.transaction(() => {
+      this.putRecord('expired', `${address}/${id}`, expiry);
+      this.removeWake(address, id);
+    });
+  }
+  expired() { return this.records('expired').map(({ value }) => value).filter((value) => value?.id).sort((a, b) => (a.expired_at_ms ?? 0) - (b.expired_at_ms ?? 0)); }
+  #machineKey(machine) { return `${String(machine).replace(/[^A-Za-z0-9._-]/g, '_')}.json`; }
+  machineWait(machine) { return this.record('machine_waits', this.#machineKey(machine)); }
+  setMachineWait(machine, wait) {
+    if (wait) this.putRecord('machine_waits', this.#machineKey(machine), wait);
+    else this.removeRecord('machine_waits', this.#machineKey(machine));
+  }
+  carrierLine(line) { this.database.appendCarrier(line); }
+  carrierLines(limit = 1000) {
+    return this.statement('SELECT record FROM (SELECT sequence, record FROM carrier_log ORDER BY sequence DESC LIMIT ?) ORDER BY sequence')
+      .all(limit).map(({ record }) => JSON.parse(record));
+  }
+
+  subscriptions(address) { return this.statement('SELECT record FROM subscriptions WHERE mailbox = ? ORDER BY message').all(address).map((row) => JSON.parse(row.record)); }
+  subscribed() { return this.statement('SELECT DISTINCT mailbox FROM subscriptions ORDER BY mailbox').all().map(({ mailbox }) => mailbox); }
+  removeSubscription(address, id) {
+    const changed = this.statement('DELETE FROM subscriptions WHERE mailbox = ? AND message = ?').run(address, id).changes > 0;
+    if (changed) this.database.changed('subscriptions', address);
+    return changed;
+  }
+  updateSubscription(address, subscription) {
+    if (this.statement('UPDATE subscriptions SET record = ? WHERE mailbox = ? AND message = ?')
+      .run(JSON.stringify(subscription), address, subscription.message_id).changes) this.database.changed('subscriptions', address);
+  }
+  subscribeIdle(address, subscription) {
+    this.open(address);
+    const record = { message_id: subscription.message_id, subscriber: subscription.subscriber, created_at_ms: subscription.created_at_ms ?? Date.now(),
+      seen_working: false, notice: subscription.notice !== false, final_reply: subscription.final_reply === true };
+    this.statement('INSERT INTO subscriptions(mailbox, message, record) VALUES (?, ?, ?) ON CONFLICT(mailbox, message) DO UPDATE SET record = excluded.record')
+      .run(address, record.message_id, JSON.stringify(record));
+    this.database.changed('subscriptions', address);
+  }
+
+  #senderKey(sender) { return blake3Hex(String(sender)).slice(0, 24); }
+  recordSend(sender, to, id, thread, continuation = null) {
+    const entry = { to, id, thread: thread ?? null, at_ms: Date.now(), ...(continuation ? { continuation } : {}) };
+    this.statement(`INSERT INTO sent_messages(sender_key, id, recipient, thread, at_ms, record) VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(sender_key, id, recipient) DO UPDATE SET thread = excluded.thread, at_ms = excluded.at_ms,
+        record = json_patch(sent_messages.record, excluded.record)`)
+      .run(this.#senderKey(sender), id, to, entry.thread, entry.at_ms, JSON.stringify(entry));
+  }
+  sendLog(sender) {
+    return this.statement('SELECT recipient AS "to", at_ms, id, thread, record FROM sent_messages WHERE sender_key = ? ORDER BY at_ms, id, recipient')
+      .all(this.#senderKey(sender)).map(({ record, ...legacy }) => ({ ...JSON.parse(record), ...legacy }));
+  }
+  sentIds(sender, prefix) {
+    return this.statement('SELECT DISTINCT id FROM sent_messages WHERE sender_key = ? AND id >= ? AND id < ? ORDER BY id')
+      .all(this.#senderKey(sender), prefix, `${prefix}\uffff`).map(({ id }) => id);
+  }
+  sentThread(sender, id) {
+    return this.statement('SELECT thread FROM sent_messages WHERE sender_key = ? AND id = ? AND thread IS NOT NULL ORDER BY at_ms, recipient LIMIT 1')
+      .get(this.#senderKey(sender), id)?.thread ?? null;
+  }
+  sentThreadHere(id) { return this.statement('SELECT thread FROM sent_messages WHERE id = ? AND thread IS NOT NULL ORDER BY at_ms, sender_key LIMIT 1').get(id)?.thread ?? null; }
+  sentMarker(sender, id) { return this.record('sent_receipts', `${this.#senderKey(sender)}/${id}`); }
+  setSentMarker(sender, id, text) { this.putRecord('sent_receipts', `${this.#senderKey(sender)}/${id}`, text); }
+  relayKnown(key) { return Boolean(this.statement("SELECT 1 FROM mail_records WHERE collection = 'relays' AND key >= ? AND key < ? LIMIT 1").get(`${key}/`, `${key}/\uffff`)); }
+
+  #terminalKey(recipient) { return `${createHash('sha256').update(recipient).digest('hex')}/queue.json`; }
+  terminalState(recipient) { return this.record('terminal_delivery', this.#terminalKey(recipient)); }
+  saveTerminalState(recipient, state) { return this.putRecord('terminal_delivery', this.#terminalKey(recipient), state); }
+  retainedTerminalStates() {
+    return this.statement(`SELECT record FROM mail_records WHERE collection = 'terminal_delivery'
+      AND (json_extract(record, '$.active') IS NOT NULL OR json_array_length(record, '$.pending') > 0) ORDER BY key`)
+      .all().map(({ record }) => JSON.parse(record));
+  }
+  terminalEvent(recipient, kind, record) {
+    return this.transaction(() => {
+      this.statement('INSERT INTO terminal_log(recipient, kind, record) VALUES (?, ?, ?)').run(recipient, kind, JSON.stringify(record));
+      this.statement('DELETE FROM terminal_log WHERE sequence <= (SELECT sequence FROM terminal_log ORDER BY sequence DESC LIMIT 1 OFFSET ?)')
+        .run(this.database.retention.maxTerminalLogRows);
+    });
+  }
+}