@nimbus-sh/fabric 0.1.0 → 0.3.0

package/dist/journal.d.ts

@@ -0,0 +1,111 @@
+/**
+ * journal.ts — an append-only event journal with dedupe and delivery leases,
+ * over a Durable Object's own SQLite.
+ *
+ * Modeled on Proteus's EventLog (`core/src/events/hub/log.ts`), which proved
+ * the contract this keeps:
+ *
+ *   - `publish` returns `{ id, admitted }` — a dedupe hit returns the
+ *     EXISTING id with `admitted: false` (log.ts:53-58), and the dedupe is
+ *     storage-level: a unique partial index over non-null keys, because its
+ *     schema comment calls the indexes "mandatory — without them recovery
+ *     scans regress to table-scans on the hot path" (hub/schema.ts:6-7).
+ *   - pending reads are priority-ordered: higher priority first, arrival
+ *     order within a priority.
+ *
+ * Where this deliberately differs: Proteus binds a delivery by writing
+ * `consumed_at` and then needs a cold-start sweep (`unbindStale`, 10 minutes,
+ * orchestrator.ts:196) to recover rows a dead activation left bound. Here a
+ * claim takes a LEASE that expires on its own — expiry alone re-pends the
+ * row, so recovery needs no sweep and no cold-start hook. A lease that
+ * expired and was re-claimed is fenced by a per-claim nonce: the dead
+ * holder's `done`/`defer`/`dismiss` returns false instead of clobbering the
+ * new claimant.
+ *
+ * Everything here is synchronous — DO SQLite is — so the journal is safe to
+ * touch from a constructor without awaiting on the init gate.
+ *
+ * The index set is derived from this module's own query set, not copied from
+ * the consumer's nine: the claim scan gets a partial index over pending rows
+ * in claim order, and the dedupe probe gets the unique partial index. No
+ * other query here repeats on a hot path.
+ */
+/** Synchronous DO SQLite, as the journal uses it. */
+export interface JournalSqlExec {
+    exec(query: string, ...bindings: Array<string | number | null>): Iterable<unknown>;
+}
+export interface JournalContext {
+    storage: {
+        sql: JournalSqlExec;
+    };
+}
+export interface JournalPublishResult {
+    /** The event id — the existing one when the publish was a duplicate. */
+    id: string;
+    /** False when the dedupe key already existed; nothing was written. */
+    admitted: boolean;
+}
+/** One claimed delivery: the record, and the lease that settles it. */
+export interface JournalClaim<P> {
+    id: string;
+    payload: P;
+    priority: number;
+    receivedAt: number;
+    lease: JournalLease;
+}
+/**
+ * One delivery lease. Every settle returns whether THIS lease still held the
+ * row — false means the lease expired and another claim owns it now, and
+ * nothing was written.
+ */
+export interface JournalLease {
+    /** The event is handled; it never delivers again. */
+    done(): boolean;
+    /** Release the lease and hide the event until `at`. */
+    defer(at: number): boolean;
+    /** The event is refused for good; it never delivers again. */
+    dismiss(reason: string): boolean;
+}
+/** One named journal on one hosting actor. Cheap accessor, like `timers()`. */
+export declare function journal<P>(ctx: JournalContext, name: string): Journal<P>;
+export declare class Journal<P> {
+    private readonly ctx;
+    private readonly table;
+    private schemaReady;
+    private lastId;
+    private seq;
+    private leaseSeq;
+    constructor(ctx: JournalContext, name: string);
+    private ensureSchema;
+    /** Same shape as the outbox's: time-ordered, forced above every stored id. */
+    private mintId;
+    /**
+     * Append one event. A dedupe key that already exists — pending, done, or
+     * dismissed — refuses the append and names the existing id.
+     */
+    publish(payload: P, opts?: {
+        dedupeKey?: string;
+        priority?: number;
+        now?: number;
+    }): JournalPublishResult;
+    /**
+     * Claim deliverable events under a lease: pending, at or past their
+     * revisit time, and not held by a live lease. Higher priority first,
+     * arrival order within a priority. Expiry alone re-pends a row a dead
+     * holder left leased — that is the whole recovery path.
+     */
+    claim(opts: {
+        leaseMs: number;
+        minPriority?: number;
+        limit?: number;
+        now?: number;
+    }): Array<JournalClaim<P>>;
+    /**
+     * The settle ops all share one fence: they write only while the row is
+     * still pending under THIS lease's nonce. An expired-and-reclaimed row has
+     * a different nonce, so the dead holder's settle is a refused no-op —
+     * synchronous SQL makes the check-then-write atomic on the actor thread.
+     */
+    private lease;
+}
+//# sourceMappingURL=journal.d.ts.map

package/dist/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE;QAAE,GAAG,EAAE,cAAc,CAAA;KAAE,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,IAAI,IAAI,OAAO,CAAC;IAChB,uDAAuD;IACvD,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,8DAA8D;IAC9D,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAWD,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAExE;AAED,qBAAa,OAAO,CAAC,CAAC;IAOR,OAAO,CAAC,QAAQ,CAAC,GAAG;IANhC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,QAAQ,CAAK;gBAEQ,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM;IAO9D,OAAO,CAAC,YAAY;IA4BpB,8EAA8E;IAC9E,OAAO,CAAC,MAAM;IAOd;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,oBAAoB;IAmB7G;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAgC5G;;;;;OAKG;IACH,OAAO,CAAC,KAAK;CAoCd"}

package/dist/journal.js

@@ -0,0 +1,177 @@
+/**
+ * journal.ts — an append-only event journal with dedupe and delivery leases,
+ * over a Durable Object's own SQLite.
+ *
+ * Modeled on Proteus's EventLog (`core/src/events/hub/log.ts`), which proved
+ * the contract this keeps:
+ *
+ *   - `publish` returns `{ id, admitted }` — a dedupe hit returns the
+ *     EXISTING id with `admitted: false` (log.ts:53-58), and the dedupe is
+ *     storage-level: a unique partial index over non-null keys, because its
+ *     schema comment calls the indexes "mandatory — without them recovery
+ *     scans regress to table-scans on the hot path" (hub/schema.ts:6-7).
+ *   - pending reads are priority-ordered: higher priority first, arrival
+ *     order within a priority.
+ *
+ * Where this deliberately differs: Proteus binds a delivery by writing
+ * `consumed_at` and then needs a cold-start sweep (`unbindStale`, 10 minutes,
+ * orchestrator.ts:196) to recover rows a dead activation left bound. Here a
+ * claim takes a LEASE that expires on its own — expiry alone re-pends the
+ * row, so recovery needs no sweep and no cold-start hook. A lease that
+ * expired and was re-claimed is fenced by a per-claim nonce: the dead
+ * holder's `done`/`defer`/`dismiss` returns false instead of clobbering the
+ * new claimant.
+ *
+ * Everything here is synchronous — DO SQLite is — so the journal is safe to
+ * touch from a constructor without awaiting on the init gate.
+ *
+ * The index set is derived from this module's own query set, not copied from
+ * the consumer's nine: the claim scan gets a partial index over pending rows
+ * in claim order, and the dedupe probe gets the unique partial index. No
+ * other query here repeats on a hot path.
+ */
+import { z } from 'zod/v4';
+const ClaimRowSchema = z.object({
+    id: z.string(),
+    payload: z.string(),
+    priority: z.number(),
+    received_at: z.number(),
+});
+const NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
+/** One named journal on one hosting actor. Cheap accessor, like `timers()`. */
+export function journal(ctx, name) {
+    return new Journal(ctx, name);
+}
+export class Journal {
+    ctx;
+    table;
+    schemaReady = false;
+    lastId = '';
+    seq = 0;
+    leaseSeq = 0;
+    constructor(ctx, name) {
+        this.ctx = ctx;
+        if (!NAME_PATTERN.test(name)) {
+            throw new Error(`fabric: journal name '${name}' must match ${NAME_PATTERN}`);
+        }
+        this.table = `journal_${name}`;
+    }
+    ensureSchema() {
+        if (this.schemaReady)
+            return;
+        const sql = this.ctx.storage.sql;
+        sql.exec(`CREATE TABLE IF NOT EXISTS ${this.table} (
+      id             TEXT    PRIMARY KEY,
+      payload        TEXT    NOT NULL,
+      dedupe_key     TEXT,
+      priority       INTEGER NOT NULL DEFAULT 0,
+      state          TEXT    NOT NULL DEFAULT 'pending'
+                             CHECK (state IN ('pending', 'done', 'dismissed')),
+      received_at    INTEGER NOT NULL,
+      not_before     INTEGER NOT NULL DEFAULT 0,
+      lease_id       TEXT,
+      lease_until    INTEGER,
+      done_at        INTEGER,
+      dismiss_reason TEXT
+    )`);
+        sql.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_${this.table}_dedupe
+      ON ${this.table} (dedupe_key) WHERE dedupe_key IS NOT NULL`);
+        // The claim scan in its own order, over pending rows only — done history
+        // grows without bound and must never be what recovery reads through.
+        sql.exec(`CREATE INDEX IF NOT EXISTS idx_${this.table}_pending
+      ON ${this.table} (priority DESC, id) WHERE state = 'pending'`);
+        const rows = [...sql.exec(`SELECT MAX(id) AS id FROM ${this.table}`)];
+        this.lastId = rows[0]?.id ?? '';
+        this.schemaReady = true;
+    }
+    /** Same shape as the outbox's: time-ordered, forced above every stored id. */
+    mintId(now) {
+        let id = `${now.toString(36).padStart(9, '0')}-${(this.seq++).toString(36).padStart(6, '0')}`;
+        if (this.lastId !== '' && id <= this.lastId)
+            id = `${this.lastId}0`;
+        this.lastId = id;
+        return id;
+    }
+    /**
+     * Append one event. A dedupe key that already exists — pending, done, or
+     * dismissed — refuses the append and names the existing id.
+     */
+    publish(payload, opts = {}) {
+        this.ensureSchema();
+        const now = opts.now ?? Date.now();
+        const sql = this.ctx.storage.sql;
+        if (opts.dedupeKey !== undefined) {
+            const existing = [...sql.exec(`SELECT id FROM ${this.table} WHERE dedupe_key = ?`, opts.dedupeKey)];
+            if (existing.length > 0)
+                return { id: existing[0].id, admitted: false };
+        }
+        const id = this.mintId(now);
+        sql.exec(`INSERT INTO ${this.table} (id, payload, dedupe_key, priority, received_at, not_before)
+       VALUES (?, ?, ?, ?, ?, 0)`, id, JSON.stringify(payload), opts.dedupeKey ?? null, opts.priority ?? 0, now);
+        return { id, admitted: true };
+    }
+    /**
+     * Claim deliverable events under a lease: pending, at or past their
+     * revisit time, and not held by a live lease. Higher priority first,
+     * arrival order within a priority. Expiry alone re-pends a row a dead
+     * holder left leased — that is the whole recovery path.
+     */
+    claim(opts) {
+        this.ensureSchema();
+        const now = opts.now ?? Date.now();
+        const sql = this.ctx.storage.sql;
+        const rows = [...sql.exec(`SELECT id, payload, priority, received_at FROM ${this.table}
+       WHERE state = 'pending'
+         AND priority >= ?
+         AND not_before <= ?
+         AND (lease_until IS NULL OR lease_until <= ?)
+       ORDER BY priority DESC, id
+       LIMIT ?`, opts.minPriority ?? -2147483648, now, now, opts.limit ?? 50)].map((row) => ClaimRowSchema.parse(row));
+        const claims = [];
+        for (const row of rows) {
+            const leaseId = `${now.toString(36)}-${(this.leaseSeq++).toString(36)}`;
+            sql.exec(`UPDATE ${this.table} SET lease_id = ?, lease_until = ? WHERE id = ?`, leaseId, now + opts.leaseMs, row.id);
+            claims.push({
+                id: row.id,
+                payload: JSON.parse(row.payload),
+                priority: row.priority,
+                receivedAt: row.received_at,
+                lease: this.lease(row.id, leaseId),
+            });
+        }
+        return claims;
+    }
+    /**
+     * The settle ops all share one fence: they write only while the row is
+     * still pending under THIS lease's nonce. An expired-and-reclaimed row has
+     * a different nonce, so the dead holder's settle is a refused no-op —
+     * synchronous SQL makes the check-then-write atomic on the actor thread.
+     */
+    lease(id, leaseId) {
+        const sql = this.ctx.storage.sql;
+        const holds = () => {
+            const rows = [...sql.exec(`SELECT 1 AS held FROM ${this.table} WHERE id = ? AND state = 'pending' AND lease_id = ?`, id, leaseId)];
+            return rows.length > 0;
+        };
+        return {
+            done: () => {
+                if (!holds())
+                    return false;
+                sql.exec(`UPDATE ${this.table} SET state = 'done', done_at = ?, lease_id = NULL, lease_until = NULL WHERE id = ?`, Date.now(), id);
+                return true;
+            },
+            defer: (at) => {
+                if (!holds())
+                    return false;
+                sql.exec(`UPDATE ${this.table} SET not_before = ?, lease_id = NULL, lease_until = NULL WHERE id = ?`, at, id);
+                return true;
+            },
+            dismiss: (reason) => {
+                if (!holds())
+                    return false;
+                sql.exec(`UPDATE ${this.table} SET state = 'dismissed', dismiss_reason = ?, lease_id = NULL, lease_until = NULL WHERE id = ?`, reason, id);
+                return true;
+            },
+        };
+    }
+}

package/dist/outbox.d.ts

@@ -0,0 +1,249 @@
+/**
+ * outbox.ts — a durable retry outbox over a Durable Object's own SQLite.
+ *
+ * Proteus built this discipline twice by hand and says so: its email outbox
+ * (`cf-backend/src/email/outbox.ts:7` — "The discipline mirrors the peer
+ * outbox", 8 attempts from a 30s base) and its peer transport
+ * (`core/src/events/ingress/peer.ts` — 8 attempts from a 5s base, per-receiver
+ * ordering, an ask/reply waiter over the same rows). Both carry the same
+ * mechanism: a write-ahead intent row in `state='pending'`, an
+ * `attempt_count`, a `next_attempt_at` with a partial index over pending rows,
+ * backoff `next = now + base * 2**(attempts-1)`, and a `nextRetryAt()` folded
+ * into the object's single alarm. This module is that mechanism once.
+ *
+ * What the consumers proved and this keeps:
+ *   - WRITE-AHEAD. The row commits before send runs. On a Durable Object the
+ *     output gate orders it: an outbound message cannot leave before the
+ *     writes of its turn are durable, so no explicit sync is needed here.
+ *   - DISPOSITION, not a boolean. peer.ts:476-526 separates three failures: a
+ *     RESOLVED refusal is permanent (dlq now), a THROWN send is transport
+ *     trouble (backoff), a malformed row is poison (dlq now, no send). A
+ *     boolean cannot carry that, and retrying a refusal re-offends.
+ *   - ORDERING per key. Rows drain in id order. A transient failure blocks
+ *     later rows with the same order key until the head clears (peer.ts:465
+ *     head-of-line set); a dead-lettered head does not block, and keyless rows
+ *     never block each other (the email outbox has no ordering at all).
+ *   - IDEMPOTENCY. A dedupe key already queued or sent is refused with the
+ *     existing id, and a sent key never reaches send again.
+ *
+ * What the consumers lacked and this adds:
+ *   - The drain registers with `timers` (one reason in the shared map) instead
+ *     of owning an alarm, and the dispatch-side handler re-arms through its
+ *     RETURN value — calling schedule() from inside the dispatcher's chain
+ *     would deadlock on the chain that serializes the reason map. A host
+ *     whose alarm belongs to another framework (the Agents SDK, agent-core's
+ *     reconciler) uses the scheduler-seam form instead: fabric hands every
+ *     next due time to the policy's `schedule` and touches no timer storage.
+ *   - The drain is turn-bounded through a {@link TurnBudget}: both consumer
+ *     drains iterate every due row in one turn, which is the same
+ *     thread-holding shape the pacer exists to end.
+ *
+ * ADOPTION IS A DATA MIGRATION for a live consumer. The rows live in
+ * fabric's own table (`outbox_<name>`), and nothing moves itself: a consumer
+ * with pending intents or a sent-key dedupe history in its old table keeps
+ * them there. The ported EmailOutbox went from `email_outbox` to
+ * `outbox_email` — deployed live without a migration, its pending mail would
+ * never send and every sent key would deliver a second time.
+ */
+import { type TimerContext, type TimerHandlerResult, type TimerHost, type TimerStorage } from './timers.js';
+import type { TurnBudget } from './turn-budget.js';
+/** Synchronous DO SQLite, as the outbox uses it. `exec` returns row objects. */
+export interface OutboxSqlExec {
+    exec(query: string, ...bindings: Array<string | number | null>): Iterable<unknown>;
+}
+/** The hosting actor's storage: its SQLite plus the shared timer map's keys. */
+export interface OutboxStorage extends TimerStorage {
+    sql: OutboxSqlExec;
+}
+export interface OutboxContext extends TimerContext {
+    storage: OutboxStorage;
+}
+/**
+ * All a scheduler-seam outbox needs from its host: the SQLite the rows live
+ * in. The timer map's keys belong to the {@link TimerHost} path only.
+ */
+export interface OutboxSqlContext {
+    storage: {
+        sql: OutboxSqlExec;
+    };
+}
+/**
+ * What one send attempt concluded. A resolved `retry` and a thrown send are
+ * the same transient class; `poison` is the resolved refusal that must never
+ * be retried — the split the peer transport proved necessary.
+ */
+export type OutboxDisposition = {
+    status: 'sent';
+} | {
+    status: 'retry';
+    reason: string;
+} | {
+    status: 'poison';
+    reason: string;
+};
+export interface OutboxPolicy<M, C = void> {
+    /** Attempts before a row dead-letters. Email uses 8; peer uses 8. */
+    maxAttempts: number;
+    /** Backoff base: `next = now + baseMs * 2**(attempts-1)`. */
+    baseMs: number;
+    /**
+     * Per-key delivery order (the peer transport's per-receiver key). Rows
+     * without a key deliver independently, as the email outbox's do.
+     */
+    orderBy?(message: M): string;
+    /**
+     * Deliver one message. Throwing is transient, same as `retry`. `context`
+     * is the caller's per-drain state — Proteus's email outbox resolves its
+     * transport binding per call, and a policy closed at construction cannot
+     * hold it (the ported consumer smuggled it through an instance field).
+     */
+    send(message: M, info: {
+        id: string;
+        attempt: number;
+    }, context: C): Promise<OutboxDisposition>;
+}
+/**
+ * `context` carries the caller's per-drain state into `send`. Required when
+ * the policy declares one; absent (and unpayable) when it does not.
+ */
+export type OutboxDrainOptions<C> = {
+    budget?: TurnBudget;
+} & ([C] extends [void] ? {
+    context?: C;
+} : {
+    context: C;
+});
+type OutboxDrainArgs<C> = [C] extends [void] ? [opts?: OutboxDrainOptions<C>] : [opts: OutboxDrainOptions<C>];
+type OutboxHandlerArgs<C> = [C] extends [void] ? [] : [context: C];
+/**
+ * The policy of an outbox whose host owns the alarm. Proteus's Durable
+ * Object alarm belongs to the Agents SDK and agent-core's to its own
+ * reconciler; neither can give fabric the alarm slot. `schedule` receives
+ * every next due time — queue's admission instant, and the earliest pending
+ * deadline after each drain — and the consumer folds it into its own alarm.
+ */
+export interface ScheduledOutboxPolicy<M, C = void> extends OutboxPolicy<M, C> {
+    schedule(at: number): Promise<void>;
+}
+type OutboxScheduling = {
+    kind: 'timers';
+    host: TimerHost;
+    ctx: OutboxContext;
+} | {
+    kind: 'schedule';
+    schedule: (at: number) => Promise<void>;
+};
+export interface OutboxDrainResult {
+    sent: number;
+    retried: number;
+    deadLettered: number;
+}
+/**
+ * One row, as {@link Outbox.status} and {@link Outbox.find} report it. Both
+ * ported consumers read fabric's table with raw SQL for exactly this: the
+ * email outbox to answer sent/deduped/failed per key, the peer transport to
+ * correlate a reply with its stored ask — which is why the record carries
+ * the stored message, not just the state.
+ */
+export interface OutboxRecord<M> {
+    id: string;
+    state: 'pending' | 'sent' | 'dlq';
+    /** Null when the stored payload no longer parses (a poison-parse row). */
+    message: M | null;
+    dedupeKey: string | null;
+    attemptCount: number;
+    lastError: string | null;
+}
+export interface OutboxDeadLetter<M> {
+    id: string;
+    /** Null when the stored payload no longer parses (a poison-parse row). */
+    message: M | null;
+    dedupeKey: string | null;
+    attemptCount: number;
+    lastError: string;
+}
+/** One named outbox on one hosting actor. Cheap accessor, like `timers()`. */
+export declare function outbox<M, C = void>(host: TimerHost, ctx: OutboxContext, name: string, policy: OutboxPolicy<M, C>): Outbox<M, C>;
+/** The scheduler-seam form: the host owns the alarm, fabric owns the rows. */
+export declare function outbox<M, C = void>(ctx: OutboxSqlContext, name: string, policy: ScheduledOutboxPolicy<M, C>): Outbox<M, C>;
+export declare class Outbox<M, C = void> {
+    private readonly ctx;
+    private readonly policy;
+    private readonly scheduling;
+    /** The timer reason this outbox arms in the shared map. */
+    readonly reason: string;
+    private readonly table;
+    private schemaReady;
+    private draining;
+    /** Largest id ever seen, so a replacement instance mints above it. */
+    private lastId;
+    private seq;
+    constructor(ctx: OutboxSqlContext, name: string, policy: OutboxPolicy<M, C>, scheduling: OutboxScheduling);
+    private ensureSchema;
+    /**
+     * Ids order the drain, so they must grow: time-prefixed, tie-broken by a
+     * per-instance counter, and forced above the largest stored id so a
+     * replacement instance with a lagging clock cannot mint into the past.
+     */
+    private mintId;
+    /**
+     * Write the intent ahead of any send. Returns `admitted: false` with the
+     * existing id when the dedupe key is already queued, sent, or dead-lettered
+     * — a sent key never reaches send again (the email outbox's short-circuit).
+     *
+     * `onDuplicate: 'retry-now'` treats a re-ask for an UNSENT key as new
+     * intent: the row's retry instant is clamped to `now` and a dead letter
+     * returns to 'pending', its attempt count kept — so every re-ask buys one
+     * more delivery attempt, past the attempt budget. The monitor's alert-once
+     * contract needs exactly this: a failed alert is retried by each sweep
+     * until it lands. A sent key stays final either way.
+     *
+     * Arms the scheduler at `now`, so delivery is owed by the alarm even
+     * when the caller never drains inline.
+     */
+    queue(message: M, opts?: {
+        dedupeKey?: string;
+        now?: number;
+        onDuplicate?: 'refuse' | 'retry-now';
+    }): Promise<{
+        id: string;
+        admitted: boolean;
+    }>;
+    /** Hand a due time to whichever scheduler this outbox was built on. */
+    private arm;
+    /** The single-alarm fold: the earliest pending deadline, or null. */
+    nextRetryAt(): number | null;
+    /** The row queue() named, by its id. Null when no such row exists. */
+    status(id: string): OutboxRecord<M> | null;
+    /** The row a dedupe key admitted, whatever its state. Null when none. */
+    find(dedupeKey: string): OutboxRecord<M> | null;
+    private record;
+    /** Dead-lettered rows, for inspection. Terminal: nothing retries out. */
+    dlq(): Array<OutboxDeadLetter<M>>;
+    /**
+     * Deliver every due pending row, in id order, honouring per-key blocking.
+     * Reentrancy-guarded: the alarm and an inline post-queue drain overlap on
+     * the same activation (peer.ts:452 carries the same guard).
+     *
+     * `budget` bounds the turn: the drain spends each processed row's payload
+     * size and suspends when a chunk is full, so a large backlog crosses turns
+     * instead of holding the actor's only thread.
+     *
+     * `context` is handed to every `send` this drain makes — the seam for
+     * per-call state such as a transport binding resolved by the caller.
+     */
+    drain(now?: number, ...rest: OutboxDrainArgs<C>): Promise<OutboxDrainResult>;
+    private deadLetter;
+    /**
+     * The dispatch-side entry for the embedder's timer handler map. Re-arms
+     * through the RETURN value: the dispatcher runs handlers inside the chain
+     * that serializes the reason map, so a schedule() call from here would
+     * deadlock on its own chain.
+     *
+     * An alarm fires with no caller, so a policy that declares a drain context
+     * receives it here once, closed over every alarm-driven drain.
+     */
+    handler(...context: OutboxHandlerArgs<C>): (now: number) => Promise<TimerHandlerResult>;
+}
+export {};
+//# sourceMappingURL=outbox.d.ts.map

package/dist/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../src/outbox.ts"],"names":[],"mappings":"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"}