@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/runtime/mailbox.js

@@ -0,0 +1,582 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mailbox = exports.MailboxCorruptionError = void 0;
+exports.isStimulusKind = isStimulusKind;
+const stimulus_payload_js_1 = require("./stimulus-payload.js");
+const native_input_journal_js_1 = require("./native-input-journal.js");
+const STIMULUS_KINDS = new Set([
+    'owner_message',
+    'source_delta',
+    'scheduled',
+    'native_event',
+]);
+function isStimulusKind(value) {
+    return typeof value === 'string' && STIMULUS_KINDS.has(value);
+}
+/** A row the mailbox refused to parse. Parked dead, never silently dropped. */
+class MailboxCorruptionError extends Error {
+    rowId;
+    code = 'MAILBOX_CORRUPT';
+    constructor(rowId, cause) {
+        super(`Mailbox row ${rowId} is corrupt`, { cause });
+        this.rowId = rowId;
+        this.name = 'MailboxCorruptionError';
+    }
+}
+exports.MailboxCorruptionError = MailboxCorruptionError;
+/**
+ * The backoff and retention schedule, carried over unchanged from the intake
+ * this generalises: five attempts, then the row parks dead and visible.
+ */
+const MAX_ATTEMPTS = 5;
+const ACKED_RETENTION_MS = 7 * 86_400_000;
+/**
+ * Pending rows older than this park as dead so a long provider outage cannot
+ * replay months of stale input. Dead rows stay visible in depth().
+ */
+const PENDING_RETENTION_MS = 7 * 86_400_000;
+/**
+ * Dedupe horizon. Ref ids must outlive their row or a redelivery after pruning
+ * re-processes old input — but not forever either (one TEXT-PK row per ref ever
+ * accepted). 30 days is far wider than any redelivery gap a cursor produces.
+ */
+const REF_RETENTION_MS = 30 * 86_400_000;
+const SEEN_CHUNK = 500; // stay under SQLITE_MAX_VARIABLE_NUMBER
+/**
+ * Replay deltas intentionally carry one channel's bounded source history. The
+ * feeder preflights this same contract before accepting any window so a
+ * large channel cannot be silently split or partially delivered.
+ */
+const MAX_REFS = 500;
+function backoffCase(column) {
+    return `CASE ${column}
+    WHEN 0 THEN 60000
+    WHEN 1 THEN 300000
+    WHEN 2 THEN 1800000
+    WHEN 3 THEN 7200000
+    ELSE 43200000
+  END`;
+}
+class Mailbox {
+    db;
+    clock;
+    nativeInputs;
+    stmtInsertSeen;
+    stmtInsert;
+    stmtInsertRef;
+    stmtRefsFor;
+    stmtClaimSelect;
+    stmtClaimSelectKind;
+    stmtClaimUpdate;
+    stmtAck;
+    stmtRetry;
+    stmtRetryStatus;
+    stmtPruneAcked;
+    stmtPrunePending;
+    stmtPruneSeen;
+    stmtReplay;
+    stmtDepth;
+    stmtPendingCoalesced;
+    stmtAppendPreview;
+    stmtIdentityPayload;
+    constructor(db, clock = () => Date.now()) {
+        this.db = db;
+        this.clock = clock;
+        // Declared by core migrations 086/087. Repeated here for the same reason every
+        // core store repeats its own shape: a consumer may open this against a
+        // database its own assembly created.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS mailbox_inputs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        stimulus_id TEXT NOT NULL,
+        kind TEXT,
+        principal_id TEXT NOT NULL,
+        channel_key TEXT NOT NULL,
+        preview_json TEXT NOT NULL DEFAULT '[]',
+        payload_json TEXT,
+        reply_to TEXT,
+        coalesce_key TEXT,
+        occurred_at INTEGER NOT NULL,
+        created_at INTEGER NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending'
+          CHECK (status IN ('pending','claimed','acked','dead')),
+        attempts INTEGER NOT NULL DEFAULT 0,
+        last_error TEXT,
+        claimed_at INTEGER,
+        acked_at INTEGER,
+        retry_after INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_mailbox_inputs_status
+        ON mailbox_inputs(status, id);
+      CREATE INDEX IF NOT EXISTS idx_mailbox_inputs_coalesce
+        ON mailbox_inputs(status, coalesce_key);
+      CREATE INDEX IF NOT EXISTS idx_mailbox_inputs_identity
+        ON mailbox_inputs(principal_id, stimulus_id);
+      CREATE TABLE IF NOT EXISTS mailbox_input_refs (
+        input_id INTEGER NOT NULL REFERENCES mailbox_inputs(id) ON DELETE CASCADE,
+        ref_id TEXT NOT NULL,
+        observation_ref TEXT,
+        PRIMARY KEY (input_id, ref_id)
+      );
+      CREATE TABLE IF NOT EXISTS mailbox_seen (
+        ref_id TEXT PRIMARY KEY,
+        seen_at INTEGER NOT NULL DEFAULT 0
+      );
+      CREATE INDEX IF NOT EXISTS idx_mailbox_seen_at ON mailbox_seen(seen_at);
+      CREATE TABLE IF NOT EXISTS mailbox_schedules (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        channel_key TEXT NOT NULL,
+        due_at INTEGER NOT NULL,
+        created_at INTEGER NOT NULL,
+        fired_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_mailbox_schedules_due
+        ON mailbox_schedules(fired_at, due_at);
+    `);
+        this.nativeInputs = new native_input_journal_js_1.NativeInputJournal(db, clock);
+        // Prepared once: enqueue runs per producer tick and re-preparing per call
+        // was measurable on backfill drains.
+        this.stmtInsertSeen = this.db.prepare(`INSERT OR IGNORE INTO mailbox_seen (ref_id, seen_at) VALUES (?, ?)`);
+        this.stmtInsert = this.db.prepare(`INSERT INTO mailbox_inputs
+         (stimulus_id, kind, principal_id, channel_key, preview_json, payload_json, reply_to,
+          coalesce_key, occurred_at, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        this.stmtInsertRef = this.db.prepare(`INSERT OR IGNORE INTO mailbox_input_refs (input_id, ref_id, observation_ref)
+       VALUES (?, ?, ?)`);
+        this.stmtRefsFor = this.db.prepare(`SELECT ref_id, observation_ref FROM mailbox_input_refs WHERE input_id = ? ORDER BY rowid ASC`);
+        this.stmtClaimSelect = this.db.prepare(`SELECT id, stimulus_id, kind, principal_id, channel_key, preview_json, payload_json, reply_to,
+              coalesce_key, occurred_at, created_at, attempts
+         FROM mailbox_inputs
+        WHERE status = 'pending' AND COALESCE(retry_after, 0) <= ?
+          AND NOT EXISTS (SELECT 1 FROM native_input_deliveries n WHERE n.input_id=mailbox_inputs.id AND n.state!='prepared')
+        ORDER BY id ASC LIMIT 1`);
+        this.stmtClaimSelectKind = this.db.prepare(`SELECT id, stimulus_id, kind, principal_id, channel_key, preview_json, payload_json, reply_to,
+              coalesce_key, occurred_at, created_at, attempts
+         FROM mailbox_inputs
+        WHERE status = 'pending' AND COALESCE(retry_after, 0) <= ? AND kind = ?
+          AND NOT EXISTS (SELECT 1 FROM native_input_deliveries n WHERE n.input_id=mailbox_inputs.id AND n.state!='prepared')
+        ORDER BY id ASC LIMIT 1`);
+        this.stmtClaimUpdate = this.db.prepare(`UPDATE mailbox_inputs SET status = 'claimed', claimed_at = ?
+        WHERE id = ? AND status = 'pending'`);
+        this.stmtAck = this.db.prepare(`UPDATE mailbox_inputs SET status = 'acked', acked_at = ? WHERE id = ?`);
+        this.stmtRetry = this.db.prepare(`UPDATE mailbox_inputs
+          SET status = CASE WHEN attempts + 1 >= ${MAX_ATTEMPTS} THEN 'dead' ELSE 'pending' END,
+              attempts = attempts + 1, last_error = ?, claimed_at = NULL,
+              retry_after = ? + ${backoffCase('attempts')}
+        WHERE id = ? AND status = 'claimed'`);
+        this.stmtRetryStatus = this.db.prepare(`SELECT status FROM mailbox_inputs WHERE id = ?`);
+        this.stmtPruneAcked = this.db.prepare(`DELETE FROM mailbox_inputs WHERE status = 'acked' AND acked_at <= ?
+          AND NOT EXISTS (SELECT 1 FROM native_input_deliveries n WHERE n.input_id=mailbox_inputs.id AND n.state IN ('dispatching','accepted','uncertain'))`);
+        this.stmtPrunePending = this.db.prepare(`UPDATE mailbox_inputs
+          SET status = 'dead', last_error = 'stale_pending_expired'
+        WHERE status = 'pending' AND created_at <= ?
+          AND NOT EXISTS (SELECT 1 FROM native_input_deliveries n WHERE n.input_id=mailbox_inputs.id AND n.state IN ('dispatching','accepted','uncertain'))`);
+        this.stmtPruneSeen = this.db.prepare(`DELETE FROM mailbox_seen WHERE seen_at <= ?
+      AND NOT EXISTS (SELECT 1 FROM mailbox_input_refs r JOIN native_input_deliveries n ON n.input_id=r.input_id
+        WHERE r.ref_id=mailbox_seen.ref_id AND n.state IN ('dispatching','accepted','uncertain'))`);
+        // Same poison cap as retry(): a claim that expires its lease repeatedly
+        // (hung run, process death mid-flight) parks dead too, rather than
+        // re-pending forever at the head of the queue.
+        this.stmtReplay = this.db.prepare(`UPDATE mailbox_inputs
+          SET status = CASE WHEN attempts + 1 >= ${MAX_ATTEMPTS} THEN 'dead' ELSE 'pending' END,
+              attempts = attempts + 1, claimed_at = NULL,
+              retry_after = ? + ${backoffCase('attempts')}
+        WHERE status = 'claimed' AND COALESCE(claimed_at, 0) <= ?
+          AND NOT EXISTS (SELECT 1 FROM native_input_deliveries n WHERE n.input_id=mailbox_inputs.id AND n.state!='prepared')`);
+        // Grouped on the (status, id) index; never scans the acked bulk.
+        this.stmtDepth = this.db.prepare(`SELECT status, COUNT(*) AS n FROM mailbox_inputs
+        WHERE status IN ('pending','claimed','dead') GROUP BY status`);
+        this.stmtPendingCoalesced = this.db.prepare(`SELECT id, preview_json FROM mailbox_inputs
+        WHERE status = 'pending' AND coalesce_key = ? AND principal_id = ?
+          AND payload_json IS ? AND kind IS ? AND channel_key = ? AND reply_to IS ?
+          AND NOT EXISTS (SELECT 1 FROM native_input_deliveries n WHERE n.input_id=mailbox_inputs.id AND n.state!='prepared')
+        ORDER BY id ASC LIMIT 1`);
+        this.stmtAppendPreview = this.db.prepare(`UPDATE mailbox_inputs SET preview_json = ? WHERE id = ? AND status = 'pending'`);
+        this.stmtIdentityPayload = this.db.prepare(`SELECT payload_json FROM mailbox_inputs
+        WHERE principal_id = ? AND (stimulus_id = ? OR id IN (
+          SELECT input_id FROM mailbox_input_refs WHERE ref_id = ?
+        )) ORDER BY id DESC LIMIT 1`);
+    }
+    now() {
+        return this.clock();
+    }
+    /**
+     * Make a stimulus durable. Returns the row id, or `null` when every ref it
+     * carries was already accepted.
+     *
+     * Dedupe is PER REF, not per stimulus shape. A boundary key fails on partial
+     * redelivery: [r1] enqueues, the producer's cursor commit fails, the next
+     * tick delivers [r1,r2] under a different boundary — and r1 runs twice.
+     * A stimulus with no unseen ref is dropped; one with any unseen ref is
+     * stored with exactly its unseen refs.
+     */
+    enqueue(stimulus) {
+        if (!isStimulusKind(stimulus.kind)) {
+            throw new Error(`Mailbox: unknown stimulus kind "${String(stimulus.kind)}"`);
+        }
+        if (stimulus.principalId.trim() === '') {
+            throw new Error('Mailbox: a stimulus states whose it is');
+        }
+        if (stimulus.channelKey.trim() === '') {
+            throw new Error('Mailbox: a stimulus states where it came from');
+        }
+        const payload = (0, stimulus_payload_js_1.encodeStimulusPayload)(stimulus.payload);
+        const accepted = this.stmtIdentityPayload.get(stimulus.principalId, stimulus.id, stimulus.id);
+        if (accepted && accepted.payload_json !== payload) {
+            throw new Error('Mailbox payload conflict for an accepted stimulus identity');
+        }
+        // With no refs stated the producer's own id is the identity, so a
+        // redelivery of the same stimulus dedupes on it rather than opening a
+        // second row.
+        const stated = stimulus.refs && stimulus.refs.length > 0
+            ? stimulus.refs.map((ref) => ({ refId: ref.refId, observationRef: ref.observationRef }))
+            : [{ refId: stimulus.id, observationRef: null }];
+        if (stated.length > MAX_REFS) {
+            throw new Error(`Mailbox: a stimulus carries at most ${MAX_REFS} refs`);
+        }
+        for (const ref of stated) {
+            if (typeof ref.refId !== 'string' || ref.refId.trim() === '') {
+                throw new Error('Mailbox: a ref states its id');
+            }
+        }
+        const seen = new Set();
+        const refIds = stated.map((ref) => ref.refId);
+        for (let i = 0; i < refIds.length; i += SEEN_CHUNK) {
+            const chunk = refIds.slice(i, i + SEEN_CHUNK);
+            const rows = this.db
+                .prepare(`SELECT ref_id FROM mailbox_seen WHERE ref_id IN (${chunk.map(() => '?').join(',')})`)
+                .all(...chunk);
+            for (const row of rows)
+                seen.add(row.ref_id);
+        }
+        const fresh = stated.filter((ref) => !seen.has(ref.refId));
+        if (fresh.length === 0) {
+            return null; // fully redelivered — already durable
+        }
+        const preview = [...(stimulus.preview ?? [])];
+        return this.db.transaction(() => {
+            const now = this.now();
+            for (const ref of fresh) {
+                this.stmtInsertSeen.run(ref.refId, now);
+            }
+            // Mechanical merge: an existing pending row with the same producer key
+            // and principal takes these refs instead of opening a second row. Both
+            // rows are still pending, so nothing that was already handed to the loop
+            // is touched.
+            const key = stimulus.coalesceKey ?? null;
+            if (key !== null && key !== '') {
+                const open = this.stmtPendingCoalesced.get(key, stimulus.principalId, payload, stimulus.kind, stimulus.channelKey, stimulus.replyTo ?? null);
+                if (open) {
+                    for (const ref of fresh) {
+                        this.stmtInsertRef.run(open.id, ref.refId, ref.observationRef);
+                    }
+                    if (preview.length > 0) {
+                        const existing = JSON.parse(open.preview_json);
+                        this.stmtAppendPreview.run(JSON.stringify([...existing, ...preview]), open.id);
+                    }
+                    return open.id;
+                }
+            }
+            const inserted = this.stmtInsert.run(stimulus.id, stimulus.kind, stimulus.principalId, stimulus.channelKey, JSON.stringify(preview), payload, stimulus.replyTo ?? null, key, stimulus.occurredAt, now);
+            const id = Number(inserted.lastInsertRowid);
+            for (const ref of fresh) {
+                this.stmtInsertRef.run(id, ref.refId, ref.observationRef);
+            }
+            return id;
+        });
+    }
+    /**
+     * Take the next pending row under a lease. A corrupt row parks dead and the
+     * scan continues.
+     *
+     * `prefer` orders kinds ahead of the rest, oldest-first within each. It is
+     * ordering, not meaning: §4.3 forbids a host FIFO in which the person's
+     * current request waits behind a mass replay, and the kind a producer stated
+     * is the only thing that can say which is which without reading content.
+     */
+    claimNext(options = {}) {
+        const prefer = options.prefer ?? [];
+        const select = () => {
+            const now = this.now();
+            for (const kind of prefer) {
+                const preferred = this.stmtClaimSelectKind.get(now, kind);
+                if (preferred)
+                    return preferred;
+            }
+            return this.stmtClaimSelect.get(now);
+        };
+        let row = select();
+        while (row) {
+            const candidate = row;
+            let preview;
+            let hydrated;
+            try {
+                preview = JSON.parse(candidate.preview_json);
+                if (!Array.isArray(preview) || preview.some((line) => typeof line !== 'string')) {
+                    throw new Error('preview_json is invalid');
+                }
+                hydrated = this.hydrate(candidate, preview);
+            }
+            catch (error) {
+                const diagnostic = new MailboxCorruptionError(candidate.id, error);
+                this.db
+                    .prepare(`UPDATE mailbox_inputs SET status = 'dead', last_error = ?, claimed_at = NULL
+              WHERE id = ? AND status = 'pending'`)
+                    .run(`${diagnostic.code}:row-${candidate.id}`, candidate.id);
+                row = select();
+                continue;
+            }
+            const claimed = this.stmtClaimUpdate.run(this.now(), candidate.id);
+            if (claimed.changes !== 1) {
+                return null;
+            }
+            return { ...hydrated, status: 'claimed' };
+        }
+        return null;
+    }
+    hydrate(row, preview) {
+        const nativeDelivery = this.nativeInputs.get(row.id);
+        const refs = this.stmtRefsFor.all(row.id).map((ref) => ({ refId: ref.ref_id, observationRef: ref.observation_ref }));
+        return {
+            id: row.id,
+            stimulusId: row.stimulus_id,
+            kind: isStimulusKind(row.kind) ? row.kind : null,
+            principalId: row.principal_id,
+            channelKey: row.channel_key,
+            refs,
+            preview,
+            ...(row.payload_json === null ? {} : { payload: (0, stimulus_payload_js_1.decodeStimulusPayload)(row.payload_json) }),
+            replyTo: row.reply_to,
+            coalesceKey: row.coalesce_key,
+            occurredAt: row.occurred_at,
+            createdAt: row.created_at,
+            status: 'pending',
+            attempts: row.attempts,
+            ...(nativeDelivery ? { nativeDelivery } : {}),
+        };
+    }
+    /** Renew only a live runtime-owned claim; native ACKs remain independent. */
+    renewClaim(id, now = this.now()) {
+        this.db
+            .prepare("UPDATE mailbox_inputs SET claimed_at=? WHERE id=? AND status='claimed'")
+            .run(now, id);
+    }
+    /** Inspect one accepted input without claiming it or changing its lease. */
+    readInput(stimulusId, principalId) {
+        const row = this.db
+            .prepare(`SELECT id, stimulus_id, kind, principal_id, channel_key,
+      preview_json, payload_json, reply_to, coalesce_key, occurred_at, created_at, attempts, status
+      FROM mailbox_inputs WHERE stimulus_id = ? AND principal_id = ? ORDER BY id DESC LIMIT 1`)
+            .get(stimulusId, principalId);
+        if (!row)
+            return null;
+        try {
+            const preview = JSON.parse(row.preview_json);
+            if (!Array.isArray(preview) || preview.some((line) => typeof line !== 'string')) {
+                throw new Error('Invalid input preview');
+            }
+            return { ...this.hydrate(row, preview), status: row.status };
+        }
+        catch (error) {
+            throw new MailboxCorruptionError(row.id, error);
+        }
+    }
+    /** Reopen claims that never crossed the native dispatch boundary. */
+    recoverOrphanedClaims(now = this.now()) {
+        return this.db.transaction(() => {
+            const replayed = this.db
+                .prepare(`UPDATE mailbox_inputs
+              SET status='pending', claimed_at=NULL, retry_after=NULL
+            WHERE status='claimed'
+              AND NOT EXISTS (
+                SELECT 1 FROM native_input_deliveries n
+                 WHERE n.input_id=mailbox_inputs.id
+                   AND n.state IN ('dispatching','accepted','uncertain','settled')
+              )`)
+                .run().changes;
+            this.db
+                .prepare(`UPDATE mailbox_inputs
+              SET status='acked', acked_at=COALESCE(acked_at, ?), claimed_at=NULL
+            WHERE status='claimed'
+              AND EXISTS (
+                SELECT 1 FROM native_input_deliveries n
+                 WHERE n.input_id=mailbox_inputs.id AND n.state='settled'
+              )`)
+                .run(now);
+            return replayed;
+        });
+    }
+    /** Identity lookup for transport recovery; never returns another principal's payload. */
+    principalsForInput(stimulusId) {
+        return this.db
+            .prepare('SELECT DISTINCT principal_id FROM mailbox_inputs WHERE stimulus_id = ?')
+            .all(stimulusId).map((row) => row.principal_id);
+    }
+    /** The exact native turn's accepted input cohort, scoped to its principal. */
+    readNativeTurnInputs(stimulusId, principalId, options = {}) {
+        const primary = this.db
+            .prepare('SELECT id FROM mailbox_inputs WHERE stimulus_id=? AND principal_id=? ORDER BY id DESC LIMIT 1')
+            .get(stimulusId, principalId);
+        if (!primary)
+            throw new Error('Native turn input is not visible to this principal');
+        const receipt = this.nativeInputs.get(primary.id)?.receipt;
+        if (!receipt)
+            throw new Error('Native turn input has no accepted receipt');
+        const page = this.nativeInputs.listByReceipt(receipt, principalId, options);
+        if (page.inputIds.length === 0)
+            return { items: [], nextCursor: null };
+        const placeholders = page.inputIds.map(() => '?').join(',');
+        const rows = this.db
+            .prepare(`SELECT id, stimulus_id, kind, channel_key, occurred_at, status
+         FROM mailbox_inputs WHERE id IN (${placeholders}) AND principal_id=?`)
+            .all(...page.inputIds, principalId);
+        if (rows.length !== page.inputIds.length) {
+            throw new Error('Native turn input cohort is incomplete');
+        }
+        const byId = new Map(rows.map((row) => [row.id, row]));
+        return {
+            items: page.inputIds.map((id) => {
+                const row = byId.get(id);
+                return {
+                    id,
+                    stimulusId: row.stimulus_id,
+                    kind: isStimulusKind(row.kind) ? row.kind : null,
+                    channelKey: row.channel_key,
+                    occurredAt: row.occurred_at,
+                    status: row.status,
+                };
+            }),
+            nextCursor: page.nextCursor,
+        };
+    }
+    /** Inputs needing native/result reconciliation, never a second model execution. */
+    unsettledNative(limit, afterId = 0) {
+        return this.nativeInputs.pending(limit, afterId).map((id) => {
+            const row = this.db
+                .prepare('SELECT * FROM mailbox_inputs WHERE id=?')
+                .get(id);
+            if (!row)
+                throw new Error(`Native delivery input ${id} is missing`);
+            const preview = JSON.parse(row.preview_json);
+            if (!Array.isArray(preview) || preview.some((line) => typeof line !== 'string')) {
+                throw new MailboxCorruptionError(id, new Error('Invalid input preview'));
+            }
+            return { ...this.hydrate(row, preview), status: row.status };
+        });
+    }
+    /**
+     * The loop took this stimulus.
+     *
+     * That is all this says. It is not a claim that anything was read, decided
+     * or done — §4.4 is explicit that a delivery ACK is not a work receipt, and
+     * there is deliberately no field here to record one in.
+     */
+    ack(id) {
+        this.stmtAck.run(this.now(), id);
+    }
+    /**
+     * Return a claim to pending, or park it dead after MAX_ATTEMPTS. Returns the
+     * resulting status so the caller can be LOUD about a dead row — a permanent
+     * loss must never be silent.
+     */
+    retry(id, error) {
+        const result = this.stmtRetry.run(error.slice(0, 500), this.now(), id);
+        if (result.changes !== 1) {
+            return 'noop'; // replayStale already flipped it
+        }
+        const row = this.stmtRetryStatus.get(id);
+        return row?.status === 'dead' ? 'dead' : 'pending';
+    }
+    /** Park a row dead without spending an attempt. */
+    quarantine(id, reason) {
+        this.db
+            .prepare(`UPDATE mailbox_inputs SET status = 'dead', last_error = ?, claimed_at = NULL
+          WHERE id = ? AND status IN ('claimed', 'pending')`)
+            .run(reason.slice(0, 500), id);
+    }
+    replayStale(olderThanMs, now = this.now()) {
+        return this.replayStaleDetailed(olderThanMs, now).replayed;
+    }
+    replayStaleDetailed(olderThanMs, now = this.now()) {
+        // Housekeeping rides along: acked rows age out, stale pending rows park as
+        // dead (visible, bounded), and the dedupe horizon stays wide but finite —
+        // no table here grows without bound.
+        const stalePending = this.db
+            .prepare(`SELECT id, stimulus_id, kind, principal_id, channel_key, preview_json, payload_json, reply_to,
+                coalesce_key, occurred_at, created_at, attempts
+           FROM mailbox_inputs
+          WHERE status = 'pending' AND created_at <= ?
+          AND NOT EXISTS (SELECT 1 FROM native_input_deliveries n WHERE n.input_id=mailbox_inputs.id AND n.state IN ('dispatching','accepted','uncertain'))
+          ORDER BY id ASC`)
+            .all(now - PENDING_RETENTION_MS);
+        this.stmtPruneAcked.run(now - ACKED_RETENTION_MS);
+        this.stmtPrunePending.run(now - PENDING_RETENTION_MS);
+        this.stmtPruneSeen.run(now - REF_RETENTION_MS);
+        const cutoff = now - olderThanMs;
+        const dying = this.db
+            .prepare(`SELECT id, stimulus_id, kind, principal_id, channel_key, preview_json, payload_json, reply_to,
+                coalesce_key, occurred_at, created_at, attempts
+           FROM mailbox_inputs
+          WHERE status = 'claimed' AND attempts + 1 >= ${MAX_ATTEMPTS}
+            AND COALESCE(claimed_at, 0) <= ?
+          AND NOT EXISTS (SELECT 1 FROM native_input_deliveries n WHERE n.input_id=mailbox_inputs.id AND n.state IN ('dispatching','accepted','uncertain'))
+          ORDER BY id ASC`)
+            .all(cutoff);
+        const result = this.stmtReplay.run(now, cutoff);
+        const dead = (row, attempts) => {
+            let preview = [];
+            try {
+                preview = JSON.parse(row.preview_json);
+            }
+            catch {
+                preview = [];
+            }
+            return { ...this.hydrate(row, preview), status: 'dead', attempts };
+        };
+        return {
+            replayed: result.changes,
+            newlyDead: [
+                ...stalePending.map((row) => dead(row, row.attempts)),
+                ...dying.map((row) => dead(row, row.attempts + 1)),
+            ],
+        };
+    }
+    depth() {
+        const rows = this.stmtDepth.all();
+        const byStatus = new Map(rows.map((row) => [row.status, row.n]));
+        return {
+            pending: byStatus.get('pending') ?? 0,
+            claimed: byStatus.get('claimed') ?? 0,
+            dead: byStatus.get('dead') ?? 0,
+        };
+    }
+    /**
+     * Schedule a wake. The fourth job: when to come back, and for what channel.
+     *
+     * `mailbox_schedules` is this daemon's own alarm clock, not anyone's
+     * calendar — a consumer's calendar is source data and is read through the
+     * source actions (design §6.3).
+     */
+    scheduleWake(channelKey, dueAt) {
+        const inserted = this.db
+            .prepare(`INSERT INTO mailbox_schedules (channel_key, due_at, created_at) VALUES (?, ?, ?)`)
+            .run(channelKey, dueAt, this.now());
+        return Number(inserted.lastInsertRowid);
+    }
+    /** Wakes that are due and have not fired. The caller marks them fired when it acts. */
+    dueWakes(now = this.now(), limit = 50) {
+        return this.db
+            .prepare(`SELECT id, channel_key, due_at FROM mailbox_schedules
+            WHERE fired_at IS NULL AND due_at <= ?
+            ORDER BY due_at ASC, id ASC LIMIT ?`)
+            .all(now, Math.min(Math.max(limit, 1), 500)).map((row) => ({ id: row.id, channelKey: row.channel_key, dueAt: row.due_at }));
+    }
+    /** Mark a wake fired. Idempotent: a second call changes nothing. */
+    markWakeFired(id) {
+        return (this.db
+            .prepare(`UPDATE mailbox_schedules SET fired_at = ? WHERE id = ? AND fired_at IS NULL`)
+            .run(this.now(), id).changes === 1);
+    }
+}
+exports.Mailbox = Mailbox;
+//# sourceMappingURL=mailbox.js.map

package/dist/runtime/model-run-store.d.ts

@@ -0,0 +1,28 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { BeginModelRunInput, ModelRunRecord, ModelRunStatus } from './model-run-types.js';
+type ModelRunAdapter = Pick<DatabaseAdapter, 'prepare'>;
+export declare function beginModelRun(adapter: ModelRunAdapter, input: BeginModelRunInput): ModelRunRecord;
+export declare function commitModelRun(adapter: ModelRunAdapter, modelRunId: string, summary?: string, tokenCount?: number): ModelRunRecord;
+export declare function failModelRun(adapter: ModelRunAdapter, modelRunId: string, errorSummary: string, tokenCount?: number): ModelRunRecord;
+export declare function getModelRun(adapter: ModelRunAdapter, modelRunId: string): ModelRunRecord | null;
+export interface ModelRunNativeInput {
+    inputId: number;
+    stimulusId: string;
+    kind: string;
+    principalId: string;
+    channelKey: string;
+    occurredAt: number;
+    status: string;
+    nativeState: string;
+}
+/** Read one run's native input cohort without copying payloads or inventing legacy principals. */
+export declare function listModelRunNativeInputs(adapter: ModelRunAdapter, modelRunId: string, principalId: string, options?: {
+    afterId?: number;
+    limit?: number;
+}): {
+    items: ModelRunNativeInput[];
+    nextCursor: number | null;
+    runStatus: ModelRunStatus;
+};
+export {};
+//# sourceMappingURL=model-run-store.d.ts.map