@fungi.computer/carrier 0.0.0-stage → 0.0.1

package/dist/internal/post-sql.d.ts

@@ -0,0 +1,51 @@
+import type { WatchdogRunningJob } from "@fungi.computer/watchdog";
+import { type PostEnvelope, type PostRegistryRoute, type PostRow } from "../post.js";
+export type Value = string | number | null;
+export type Statement = Readonly<{
+    text: string;
+    values: readonly Value[];
+}>;
+export type Row = Record<string, Value>;
+export type PostSql = Readonly<{
+    query: (statement: Statement) => Promise<readonly Row[]>;
+    commit: (statements: readonly Statement[], key: string, jobId: string) => Promise<void>;
+}>;
+/** SQL native Carrier runtime configuration; route decisions remain in Post. */
+export type SqlPostOptions<R extends Record<string, PostRegistryRoute>> = Readonly<{
+    /** The same address/event registry used by SQLite Post. */
+    routes: R;
+    /** Optional bounded, redacted family diagnostic; never persist raw provider errors. */
+    failureDetail?: (cause: unknown) => string;
+    /** Family policy may tighten the twenty-attempt Post ceiling. */
+    retry?: Readonly<{
+        maxAttempts: number;
+        baseDelayMs: number;
+        maxDelayMs: number;
+    }>;
+    /** Clock shared with the database's Watchdog. */
+    now: () => number;
+    /** Arm a durable wake after committed progress. */
+    scheduleWake: (at: number) => Promise<void>;
+}>;
+/** Async inspection and Watchdog executor shared by D1 and PostgreSQL. */
+export type SqlPostRuntime = Readonly<{
+    /** Execute an already claimed Post job through the registered receiver. */
+    execute: (job: WatchdogRunningJob, signal?: AbortSignal) => Promise<Readonly<{
+        kind: "completed";
+    }>>;
+    /** Recover a bounded page of settled attempts into new Watchdog jobs. */
+    enqueueDue: (limit?: number, afterKey?: string) => Promise<string | undefined>;
+    /** Read one producer receipt or pending envelope. */
+    read: (key: string) => Promise<PostRow | undefined>;
+}>;
+export declare function postSchema(postgres: boolean): readonly string[];
+export declare function admitPostSelect(source: Statement): Statement;
+export declare function jobSelect(key: string, postgres: boolean, expectedJobId?: string): Statement;
+export declare function preparePost<R extends Record<string, PostRegistryRoute>>(options: SqlPostOptions<R>, input: PostEnvelope): {
+    key: string;
+    statement: Readonly<{
+        text: string;
+        values: readonly Value[];
+    }>;
+};
+export declare function openSqlPost<R extends Record<string, PostRegistryRoute>>(database: PostSql, options: SqlPostOptions<R>): SqlPostRuntime;

package/dist/internal/post-sql.js

@@ -0,0 +1,255 @@
+import * as Schema from "effect/Schema";
+import { defineIdFamily } from "@fungi.computer/cairn";
+import { PostEnvelopeSchema, PostError, } from "../post.js";
+import { deliverPost, postDisposition, deliveryReceipt, } from "./post-execution.js";
+import { maxDeliveryAttempts, retryDelay } from "../post-outbox.js";
+const ids = defineIdFamily({
+    family: "post",
+    version: 1,
+    kinds: { work: { prefix: "post_work" } },
+});
+const EnvelopeJson = Schema.fromJsonString(PostEnvelopeSchema);
+const ReceiptJson = Schema.fromJsonString(Schema.Json);
+const Stored = Schema.Struct({
+    post_key: Schema.String,
+    envelope_json: Schema.String,
+    queue_name: Schema.String,
+    state: Schema.Literals(["pending", "delivered", "dead"]),
+    attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    next_attempt_at: Schema.Number,
+    job_id: Schema.String,
+    delivery_json: Schema.NullOr(Schema.String),
+    receipt_json: Schema.NullOr(ReceiptJson),
+    reason: Schema.NullOr(Schema.Literals(["refused", "exhausted"])),
+});
+const columns = "post_key,envelope_json,queue_name,state,attempts,next_attempt_at,job_id,delivery_json,reason,receipt_json";
+const JobReference = Schema.Struct({
+    source_job: Schema.NullOr(Schema.String),
+});
+const pageSize = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(64));
+export function postSchema(postgres) {
+    return [
+        `CREATE TABLE IF NOT EXISTS carrier_post_rows (
+      sequence ${postgres ? "SERIAL PRIMARY KEY" : "INTEGER PRIMARY KEY AUTOINCREMENT"},
+      post_key TEXT NOT NULL UNIQUE CHECK(length(post_key) BETWEEN 1 AND 256),
+      envelope_json TEXT NOT NULL,queue_name TEXT NOT NULL,
+      state TEXT NOT NULL DEFAULT 'pending' CHECK(state IN ('pending','delivered','dead')),
+      attempts INTEGER NOT NULL DEFAULT 0 CHECK(attempts>=0),
+      next_attempt_at ${postgres ? "DOUBLE PRECISION" : "INTEGER"} NOT NULL,
+      job_id TEXT NOT NULL,delivery_json TEXT,
+      reason TEXT CHECK(reason IN ('refused','exhausted')),
+      receipt_json TEXT,
+      settled_at ${postgres ? "DOUBLE PRECISION" : "INTEGER"},
+      last_error TEXT CHECK(last_error IS NULL OR length(last_error)<=2048),
+      attempt_until ${postgres ? "DOUBLE PRECISION" : "INTEGER"}
+    )`,
+        "CREATE INDEX IF NOT EXISTS idx_post_due ON carrier_post_rows(state,next_attempt_at,post_key)",
+        "CREATE INDEX IF NOT EXISTS idx_post_address ON carrier_post_rows(queue_name,state,sequence)",
+    ];
+}
+export function admitPostSelect(source) {
+    return {
+        text: `INSERT INTO carrier_post_rows(post_key,envelope_json,queue_name,next_attempt_at,job_id)
+    SELECT post_key,envelope_json,queue_name,next_attempt_at,job_id FROM (${source.text}) AS admission WHERE true
+    ON CONFLICT(post_key) DO UPDATE SET post_key=NULL
+    WHERE carrier_post_rows.envelope_json<>excluded.envelope_json OR carrier_post_rows.queue_name<>excluded.queue_name`,
+        values: source.values,
+    };
+}
+export function jobSelect(key, postgres, expectedJobId) {
+    const bind = postgres ? "$" : "?";
+    const payload = postgres
+        ? "json_build_object('postKey',post_key)::text"
+        : "json_object('postKey',post_key)";
+    return {
+        text: `SELECT job_id,queue_name,'post' AS lane,0 AS priority,${payload} AS payload_json,
+      CAST(NULL AS INTEGER) AS recovery_max FROM carrier_post_rows
+      WHERE post_key=${bind}1 AND state='pending' ${expectedJobId === undefined ? "" : `AND job_id=${bind}2`}`,
+        values: expectedJobId === undefined ? [key] : [key, expectedJobId],
+    };
+}
+export function preparePost(options, input) {
+    const incoming = Schema.decodeUnknownSync(PostEnvelopeSchema)(input);
+    const route = options.routes[incoming.kind];
+    if (route === undefined)
+        throw new PostError("unknown address kind");
+    const envelope = route.encodeEnvelope(incoming);
+    const queue = JSON.stringify([route.addressKind, route.nameOf(envelope)]);
+    const jobId = ids.work.generate();
+    return {
+        key: envelope.key,
+        statement: admitPostSelect({
+            text: `SELECT CAST($1 AS TEXT) AS post_key,CAST($2 AS TEXT) AS envelope_json,
+      CAST($3 AS TEXT) AS queue_name,CAST($4 AS DOUBLE PRECISION) AS next_attempt_at,CAST($5 AS TEXT) AS job_id`,
+            values: [
+                envelope.key,
+                Schema.encodeSync(EnvelopeJson)(envelope),
+                queue,
+                options.now(),
+                jobId,
+            ],
+        }),
+    };
+}
+function parseStored(raw) {
+    const stored = Schema.decodeUnknownSync(Stored)(raw);
+    const envelope = Schema.decodeUnknownSync(EnvelopeJson)(stored.envelope_json);
+    const delivery = stored.delivery_json === null
+        ? undefined
+        : Schema.decodeUnknownSync(EnvelopeJson)(stored.delivery_json);
+    return { ...stored, envelope, delivery };
+}
+function publicRow(stored) {
+    const receipt = stored.receipt_json;
+    if (stored.state === "delivered")
+        return receipt === null
+            ? { state: "delivered" }
+            : { state: "delivered", receipt };
+    if (stored.state === "dead") {
+        if (stored.reason === null)
+            throw new PostError("dead letter has no reason");
+        const dead = {
+            state: "dead",
+            envelope: stored.envelope,
+            attempts: stored.attempts,
+            reason: stored.reason,
+            delivery: stored.delivery,
+        };
+        return receipt === null ? dead : { ...dead, receipt };
+    }
+    return {
+        state: "pending",
+        envelope: stored.envelope,
+        attempts: stored.attempts,
+        nextAttemptAt: stored.next_attempt_at,
+        jobId: stored.job_id,
+        delivery: stored.delivery,
+    };
+}
+export function openSqlPost(database, options) {
+    const policy = Schema.decodeUnknownSync(Schema.Struct({
+        maxAttempts: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: maxDeliveryAttempts })),
+        baseDelayMs: Schema.Int.check(Schema.isGreaterThan(0)),
+        maxDelayMs: Schema.Int.check(Schema.isGreaterThan(0)),
+    }))(options.retry ?? {
+        maxAttempts: maxDeliveryAttempts,
+        baseDelayMs: retryDelay(1),
+        maxDelayMs: retryDelay(maxDeliveryAttempts),
+    });
+    const delay = (attempt) => Math.min(policy.baseDelayMs * 2 ** Math.max(0, attempt - 1), policy.maxDelayMs);
+    const retrySql = Array.from({ length: policy.maxAttempts }, (_, index) => `WHEN ${String(index)} THEN ${String(delay(index + 1))}`).join(" ");
+    for (const route of Object.values(options.routes)) {
+        // Synchronous owner hooks cannot participate in an asynchronous transaction.
+        if (route.recordDelivered !== undefined ||
+            route.recordRefused !== undefined ||
+            route.recordCursor !== undefined)
+            throw new PostError("SQL Post requires transaction-bound receipt projections");
+    }
+    const query = (text, values = []) => database.query({ text, values });
+    return {
+        read: async (key) => {
+            const raw = (await query(`SELECT ${columns} FROM carrier_post_rows WHERE post_key=$1`, [key]))[0];
+            return raw === undefined ? undefined : publicRow(parseStored(raw));
+        },
+        execute: async (job, signal) => {
+            const { postKey } = Schema.decodeUnknownSync(Schema.Struct({ postKey: Schema.String }))(job.payload);
+            const raw = (await query(`UPDATE carrier_post_rows SET attempts=attempts+1,
+        next_attempt_at=CAST($1 AS DOUBLE PRECISION)+CASE attempts ${retrySql} ELSE ${String(delay(policy.maxAttempts))} END,attempt_until=$2 WHERE post_key=$3 AND job_id=$4 AND state='pending'
+        AND attempts<$5 AND NOT EXISTS (SELECT 1 FROM carrier_post_rows AS earlier
+          WHERE earlier.queue_name=carrier_post_rows.queue_name AND earlier.state='pending'
+          AND earlier.sequence<carrier_post_rows.sequence) RETURNING ${columns}`, [
+                options.now(),
+                options.now() + 10_000,
+                postKey,
+                job.jobId,
+                policy.maxAttempts,
+            ]))[0];
+            if (raw === undefined)
+                return { kind: "completed" };
+            const stored = parseStored(raw);
+            const attempt = publicRow(stored);
+            if (attempt.state !== "pending")
+                throw new PostError("attempt is not pending");
+            const route = options.routes[attempt.envelope.kind];
+            if (route === undefined)
+                throw new PostError("unknown address kind");
+            await options.scheduleWake(attempt.nextAttemptAt);
+            const evidence = await deliverPost({
+                signal,
+                attempt,
+                route,
+                savePrepared: async (envelope) => {
+                    const saved = await query(`UPDATE carrier_post_rows SET delivery_json=$1
+          WHERE post_key=$2 AND job_id=$3 AND attempts=$4 AND state='pending' AND attempt_until>$5 RETURNING post_key`, [
+                        Schema.encodeSync(EnvelopeJson)(envelope),
+                        postKey,
+                        job.jobId,
+                        attempt.attempts,
+                        options.now(),
+                    ]);
+                    if (saved.length === 0)
+                        throw new PostError("preparation superseded");
+                },
+            });
+            const disposition = postDisposition(evidence, route, attempt.attempts, policy.maxAttempts);
+            if (disposition.state === "keep")
+                return { kind: "completed" };
+            const next = options.now() + delay(attempt.attempts);
+            const receipt = deliveryReceipt(evidence);
+            await query(`UPDATE carrier_post_rows SET state=$1,reason=$2,next_attempt_at=$3,attempt_until=NULL,last_error=$8,receipt_json=$9,settled_at=CASE WHEN $1='pending' THEN NULL ELSE CAST($10 AS DOUBLE PRECISION) END
+        WHERE post_key=$4 AND job_id=$5 AND attempts=$6 AND state='pending' AND attempt_until>$7`, [
+                disposition.state,
+                disposition.state === "dead" ? disposition.reason : null,
+                next,
+                postKey,
+                job.jobId,
+                attempt.attempts,
+                options.now(),
+                evidence.result === "unavailable" &&
+                    options.failureDetail !== undefined
+                    ? options.failureDetail(evidence.failure).slice(0, 2048)
+                    : null,
+                receipt === undefined
+                    ? null
+                    : Schema.encodeSync(ReceiptJson)(receipt),
+                options.now(),
+            ]);
+            await options.scheduleWake(disposition.state === "pending" ? next : options.now());
+            return { kind: "completed" };
+        },
+        enqueueDue: async (limit = 64, afterKey = "") => {
+            Schema.decodeUnknownSync(pageSize)(limit);
+            const rows = await query(`SELECT ${columns
+                .split(",")
+                .map((column) => `p.${column}`)
+                .join(",")},w.job_id AS source_job
+        FROM carrier_post_rows p LEFT JOIN watchdog_jobs w ON p.job_id=w.job_id
+        WHERE p.state='pending' AND (w.job_id IS NULL OR (w.state='settled' AND p.next_attempt_at<=$1)) AND p.post_key>$2
+        ORDER BY p.post_key LIMIT $3`, [options.now(), afterKey, limit]);
+            let cursor;
+            for (const raw of rows) {
+                if (Schema.decodeUnknownSync(JobReference)(raw).source_job === null)
+                    throw new PostError("delivery job is missing");
+                const row = parseStored(raw);
+                cursor = row.post_key;
+                const nextJobId = ids.work.generate();
+                await database.commit([
+                    {
+                        text: `UPDATE carrier_post_rows SET job_id=$1,state=CASE WHEN attempts>=$2 THEN 'dead' ELSE 'pending' END,
+            reason=CASE WHEN attempts>=$2 THEN 'exhausted' ELSE NULL END,
+            settled_at=CASE WHEN attempts>=$2 THEN CAST($5 AS DOUBLE PRECISION) ELSE NULL END
+            WHERE post_key=$3 AND job_id=$4 AND state='pending' AND next_attempt_at<=$5`,
+                        values: [
+                            nextJobId,
+                            policy.maxAttempts,
+                            row.post_key,
+                            row.job_id,
+                            options.now(),
+                        ],
+                    },
+                ], row.post_key, nextJobId);
+            }
+            return rows.length === limit ? cursor : undefined;
+        },
+    };
+}

package/dist/internal/receipt-schema.d.ts

@@ -0,0 +1,3 @@
+import * as Schema from "effect/Schema";
+/** Carrier's aggregate dispatch states at both storage and read boundaries. */
+export declare const CarrierStatusSchema: Schema.Literals<readonly ["queued", "dispatching", "provider_accepted", "outcome_unknown", "rejected", "refused", "expired", "superseded"]>;

package/dist/internal/receipt-schema.js

@@ -0,0 +1,12 @@
+import * as Schema from "effect/Schema";
+/** Carrier's aggregate dispatch states at both storage and read boundaries. */
+export const CarrierStatusSchema = Schema.Literals([
+    "queued",
+    "dispatching",
+    "provider_accepted",
+    "outcome_unknown",
+    "rejected",
+    "refused",
+    "expired",
+    "superseded",
+]);

package/dist/post-d1.d.ts

@@ -0,0 +1,36 @@
+import type { D1Database, D1PreparedStatement } from "@cloudflare/workers-types";
+import { type D1Watchdog } from "@fungi.computer/watchdog/d1";
+import type { PostEnvelope, PostRegistryRoute } from "./post.js";
+import { type SqlPostOptions, type SqlPostRuntime } from "./internal/post-sql.js";
+export type { SqlPostOptions, SqlPostRuntime } from "./internal/post-sql.js";
+/** Trusted SELECT yielding post_key, envelope_json, queue_name, next_attempt_at and job_id. */
+export type D1PostSource = Readonly<{
+    /** Trusted native SELECT text with SQLite ?NNN bindings. */
+    text: string;
+    /** Scalar values bound by the native driver. */
+    values: readonly (string | number | null)[];
+}>;
+/** Post admission statements; callers commit them with the originating D1 fact. */
+export type D1Post = SqlPostRuntime & Readonly<{
+    /** Prepare envelope and Watchdog admission without performing I/O. */
+    send: (envelope: PostEnvelope) => readonly D1PreparedStatement[];
+    /** Admit conditionally generated source facts entirely inside the producer batch. */
+    sendFromSelect: (source: D1PostSource) => readonly D1PreparedStatement[];
+}>;
+/** Carrier-owned D1 schema, applied by the deployment migration owner. */
+export declare const postD1Schema: readonly string[];
+/** Bind the Post registry to native D1 batch admission and the shared delivery engine. */
+export declare function createD1Post<R extends Record<string, PostRegistryRoute>>(options: SqlPostOptions<R> & Readonly<{
+    database: D1Database;
+    watchdog: D1Watchdog;
+}>): D1Post;
+/** Prepare conditional envelopes and their jobs inside the producer's D1 batch. */
+export declare function prepareD1PostAdmission(database: D1Database, source: D1PostSource): readonly D1PreparedStatement[];
+/** Native erasure statement; its values remain bound by the caller's D1 driver. */
+export type D1PostErasureStatement = Readonly<{
+    text: string;
+    values: readonly (string | number | null)[];
+}>;
+/** Remove selected recipient queues, including every envelope and attempt, atomically.
+ * The trusted SELECT yields queue_name from producer/envelope facts, not job state. */
+export declare function purgeD1Post(source: D1PostErasureStatement): readonly D1PostErasureStatement[];

package/dist/post-d1.js

@@ -0,0 +1,55 @@
+import { purgeD1Queues, prepareD1Admission, } from "@fungi.computer/watchdog/d1";
+import { admitPostSelect, jobSelect, openSqlPost, postSchema, preparePost, } from "./internal/post-sql.js";
+/** Carrier-owned D1 schema, applied by the deployment migration owner. */
+export const postD1Schema = postSchema(false);
+/** Bind the Post registry to native D1 batch admission and the shared delivery engine. */
+export function createD1Post(options) {
+    // Only package-owned templates use $N; caller SELECTs remain native SQL.
+    const prepare = (statement) => options.database
+        .prepare(statement.text.replace(/\$(\d+)/gu, "?$1"))
+        .bind(...statement.values);
+    const runtime = openSqlPost({
+        query: async (statement) => (await prepare(statement).all()).results,
+        commit: async (statements, key, jobId) => {
+            await options.database.batch([
+                ...statements.map(prepare),
+                options.watchdog.enqueueFromSelect(jobSelect(key, false, jobId)),
+            ]);
+        },
+    }, options);
+    return {
+        ...runtime,
+        send: (envelope) => {
+            const prepared = preparePost(options, envelope);
+            return [
+                prepare(prepared.statement),
+                options.watchdog.enqueueFromSelect(jobSelect(prepared.key, false)),
+            ];
+        },
+        sendFromSelect: (source) => prepareD1PostAdmission(options.database, source),
+    };
+}
+/** Prepare conditional envelopes and their jobs inside the producer's D1 batch. */
+export function prepareD1PostAdmission(database, source) {
+    return [
+        database.prepare(admitPostSelect(source).text).bind(...source.values),
+        prepareD1Admission(database).enqueueFromSelect({
+            text: `SELECT p.job_id,p.queue_name,'post' AS lane,0 AS priority,
+        json_object('postKey',p.post_key) AS payload_json,CAST(NULL AS INTEGER) AS recovery_max
+        FROM carrier_post_rows p JOIN (${source.text}) AS source ON p.post_key=source.post_key
+        WHERE p.state='pending'`,
+            values: source.values,
+        }),
+    ];
+}
+/** Remove selected recipient queues, including every envelope and attempt, atomically.
+ * The trusted SELECT yields queue_name from producer/envelope facts, not job state. */
+export function purgeD1Post(source) {
+    return [
+        ...purgeD1Queues(source),
+        {
+            text: `DELETE FROM carrier_post_rows WHERE queue_name IN (SELECT queue_name FROM (${source.text}) AS erasure)`,
+            values: source.values,
+        },
+    ];
+}

package/dist/post-outbox.d.ts

@@ -0,0 +1,40 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/** Maximum receiver attempts retained from BirdDog. */
+export declare const maxDeliveryAttempts = 20;
+/** BirdDog's retained bounded retry schedule. */
+export declare const retryDelay: (attempts: number) => number;
+/** Durable, string-backed rows. A delivered receipt must outlive source replay. */
+export type PostOutboxStore<E> = Readonly<{
+    /** Commit one pending row or completion receipt. */
+    put: (key: string, value: string) => Effect.Effect<void, E>;
+    /** Inspect one durable row by key. */
+    read: (key: string) => Effect.Effect<string | undefined, E>;
+    /** Read an ordered bounded page. */
+    list: (limit: number, afterKey?: string) => Effect.Effect<readonly Readonly<{
+        key: string;
+        value: string;
+    }>[], E>;
+    /** Discard one malformed row. */
+    delete: (key: string) => Effect.Effect<void, E>;
+}>;
+/** Bounded generic delivery owned by Post. */
+export type PostOutbox<M, E> = Readonly<{
+    /** Queue a message and return its wake hint so a fan-out can schedule once. */
+    enqueue: (message: M, at?: number) => Effect.Effect<number | undefined, E>;
+    /** Attempt one bounded page and arrange the next wake. */
+    drain: () => Effect.Effect<void, E>;
+    /** Inspect exhausted messages in an ordered page. */
+    deadLetters: (limit: number, afterKey?: string) => Effect.Effect<M[], E>;
+}>;
+/** The same bounded delivery and receipt machinery serves Post and BirdDog. */
+export declare function makePostOutbox<M, E>(options: Readonly<{
+    message: Schema.Codec<M>;
+    key: (message: M) => string;
+    outbox: PostOutboxStore<E>;
+    deliver: (message: M) => Effect.Effect<boolean, E>;
+    scheduleWake: (at: number) => Effect.Effect<void, E>;
+    now: () => number;
+    invalidRow: () => E;
+    encodingFailed: () => E;
+}>): PostOutbox<M, E>;

package/dist/post-outbox.js

@@ -0,0 +1,99 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+const PageSize = 64;
+/** Maximum receiver attempts retained from BirdDog. */
+export const maxDeliveryAttempts = 20;
+/** BirdDog's retained bounded retry schedule. */
+export const retryDelay = (attempts) => Math.min(2_000 * 2 ** Math.max(0, attempts - 1), 300_000);
+const earlier = (a, b) => b === undefined ? a : a === undefined ? b : Math.min(a, b);
+const logDeliveryFailure = (cause) => {
+    console.error("Carrier Post outbox delivery failed", {
+        failureKind: cause instanceof Error ? "Error" : "NonErrorThrown",
+    });
+};
+/** The same bounded delivery and receipt machinery serves Post and BirdDog. */
+export function makePostOutbox(options) {
+    const Pending = Schema.Struct({
+        mail: options.message,
+        attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+        nextAttemptAt: Schema.optional(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))),
+    });
+    const Row = Schema.Union([
+        Pending,
+        Schema.Struct({ state: Schema.Literal("delivered") }),
+    ]);
+    const Text = Schema.fromJsonString(Row);
+    const decode = (value) => Schema.decodeUnknownEffect(Text)(value).pipe(Effect.mapError(options.invalidRow));
+    const encode = (row) => Effect.try({
+        try: () => Schema.encodeSync(Text)(row),
+        catch: options.encodingFailed,
+    });
+    const enqueue = (message, at = options.now()) => Effect.gen(function* () {
+        const key = options.key(message);
+        const existing = yield* options.outbox.read(key);
+        if (existing !== undefined) {
+            const row = yield* decode(existing);
+            if ("state" in row || row.attempts >= maxDeliveryAttempts)
+                return;
+            return Math.max(at, row.nextAttemptAt ?? at);
+        }
+        const value = yield* encode({ mail: message, attempts: 0 });
+        yield* options.outbox.put(key, value);
+        return at;
+    });
+    const process = (stored, now) => Effect.gen(function* () {
+        const decoded = yield* Effect.result(decode(stored.value));
+        if (decoded._tag === "Failure") {
+            yield* options.outbox.delete(stored.key);
+            return undefined;
+        }
+        const row = decoded.success;
+        if ("state" in row || row.attempts >= maxDeliveryAttempts)
+            return undefined;
+        if (row.nextAttemptAt !== undefined && row.nextAttemptAt > now)
+            return row.nextAttemptAt;
+        const delivered = yield* options.deliver(row.mail).pipe(Effect.catch((cause) => Effect.sync(() => {
+            logDeliveryFailure(cause);
+        }).pipe(Effect.as(false))));
+        if (delivered) {
+            yield* options.outbox.put(stored.key, yield* encode({ state: "delivered" }));
+            return undefined;
+        }
+        const attempts = row.attempts + 1;
+        const nextAttemptAt = now + retryDelay(attempts);
+        yield* options.outbox.put(stored.key, yield* encode({ mail: row.mail, attempts, nextAttemptAt }));
+        return attempts < maxDeliveryAttempts ? nextAttemptAt : undefined;
+    });
+    let cursor;
+    let earliestFuture;
+    const drain = () => Effect.gen(function* () {
+        const now = options.now();
+        const rows = yield* options.outbox.list(PageSize, cursor);
+        for (const row of rows)
+            earliestFuture = earlier(earliestFuture, yield* process(row, now));
+        if (rows.length === PageSize) {
+            const lastKey = rows[rows.length - 1]?.key;
+            if (lastKey !== undefined &&
+                (yield* options.outbox.list(1, lastKey)).length > 0) {
+                cursor = lastKey;
+                yield* options.scheduleWake(now);
+                return;
+            }
+        }
+        cursor = undefined;
+        if (earliestFuture !== undefined)
+            yield* options.scheduleWake(Math.max(now, earliestFuture));
+        earliestFuture = undefined;
+    });
+    const deadLetters = (limit, afterKey) => Effect.gen(function* () {
+        const rows = yield* options.outbox.list(limit, afterKey);
+        const dead = [];
+        for (const stored of rows) {
+            const row = yield* decode(stored.value);
+            if (!("state" in row) && row.attempts >= maxDeliveryAttempts)
+                dead.push(row.mail);
+        }
+        return dead;
+    });
+    return { enqueue, drain, deadLetters };
+}

package/dist/post-postgres.d.ts

@@ -0,0 +1,25 @@
+import type { Pool, PoolClient } from "pg";
+import { type PostgresWatchdog } from "@fungi.computer/watchdog/postgres";
+import type { PostEnvelope, PostRegistryRoute } from "./post.js";
+import { type SqlPostOptions, type SqlPostRuntime } from "./internal/post-sql.js";
+export type { SqlPostOptions, SqlPostRuntime } from "./internal/post-sql.js";
+/** Post on PostgreSQL; the producer retains ownership of BEGIN and COMMIT. */
+export type PostgresPost = SqlPostRuntime & Readonly<{
+    /** Persist the envelope and job using the already checked-out transaction client. */
+    send: (client: Pick<PoolClient, "query">, envelope: PostEnvelope) => Promise<void>;
+}>;
+/** Carrier-owned PostgreSQL schema, applied by the deployment migration owner. */
+export declare const postPostgresSchema: readonly string[];
+/** Bind the Post registry to a PostgreSQL owner and the shared delivery engine. */
+export declare function createPostgresPost<R extends Record<string, PostRegistryRoute>>(options: SqlPostOptions<R> & Readonly<{
+    database: Pick<Pool, "query" | "connect">;
+    watchdog: PostgresWatchdog;
+}>): PostgresPost;
+/** Parameterized native erasure; the producer controls BEGIN and COMMIT. */
+export type PostgresPostErasureStatement = Readonly<{
+    text: string;
+    values: readonly (string | number | null)[];
+}>;
+/** Purge selected recipient queues, including all envelopes and attempts.
+ * The trusted SELECT yields queue_name from producer/envelope facts, not job state. */
+export declare function purgePostgresPost(source: PostgresPostErasureStatement): readonly PostgresPostErasureStatement[];

package/dist/post-postgres.js

@@ -0,0 +1,79 @@
+import * as Schema from "effect/Schema";
+import { purgePostgresQueues, } from "@fungi.computer/watchdog/postgres";
+import { jobSelect, openSqlPost, postSchema, preparePost, } from "./internal/post-sql.js";
+/** Carrier-owned PostgreSQL schema, applied by the deployment migration owner. */
+export const postPostgresSchema = postSchema(true);
+const Job = Schema.Struct({
+    job_id: Schema.String,
+    queue_name: Schema.String,
+    lane: Schema.String,
+    priority: Schema.Number,
+    payload_json: Schema.fromJsonString(Schema.Unknown),
+});
+/** Bind the Post registry to a PostgreSQL owner and the shared delivery engine. */
+export function createPostgresPost(options) {
+    const enqueue = async (client, source) => {
+        const native = source;
+        const rows = (await client.query(native.text, [...native.values]))
+            .rows;
+        for (const raw of rows) {
+            const job = Schema.decodeUnknownSync(Job)(raw);
+            await options.watchdog.enqueue(client, {
+                jobId: job.job_id,
+                queue: job.queue_name,
+                lane: job.lane,
+                priority: job.priority,
+                payload: job.payload_json,
+                state: "queued",
+            });
+        }
+    };
+    const runtime = openSqlPost({
+        query: async (statement) => (await options.database.query(statement.text, [
+            ...statement.values,
+        ])).rows,
+        commit: async (statements, key, jobId) => {
+            const client = await options.database.connect();
+            try {
+                await client.query("BEGIN");
+                for (const statement of statements)
+                    await client.query(statement.text, [...statement.values]);
+                await enqueue(client, jobSelect(key, true, jobId));
+                await client.query("COMMIT");
+            }
+            catch (error) {
+                await client.query("ROLLBACK");
+                throw error;
+            }
+            finally {
+                client.release();
+            }
+        },
+    }, options);
+    return {
+        ...runtime,
+        send: async (client, envelope) => {
+            const prepared = preparePost(options, envelope);
+            await client.query(prepared.statement.text, [
+                ...prepared.statement.values,
+            ]);
+            await enqueue(client, jobSelect(prepared.key, true));
+        },
+    };
+}
+/** Purge selected recipient queues, including all envelopes and attempts.
+ * The trusted SELECT yields queue_name from producer/envelope facts, not job state. */
+export function purgePostgresPost(source) {
+    return [
+        // Serialize erasure with send/retry before taking the jobs' deletion snapshot.
+        {
+            text: `UPDATE carrier_post_rows SET post_key=post_key WHERE queue_name IN (SELECT queue_name FROM (${source.text}) AS erasure)`,
+            values: source.values,
+        },
+        ...purgePostgresQueues(source),
+        {
+            text: `DELETE FROM carrier_post_rows WHERE queue_name IN (SELECT queue_name FROM (${source.text}) AS erasure)`,
+            values: source.values,
+        },
+    ];
+}