@crowdsource.you/core 1.2.0

package/dist/outbox/postgres/store/events.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postgresEventStore = postgresEventStore;
+const drizzle_orm_1 = require("drizzle-orm");
+/**
+ * The inbound webhook event log, in Postgres.
+ *
+ * ## The one place this backend is structurally better rather than equivalent
+ *
+ * Everything else in this port aims for parity. This claim does not: it removes a
+ * failure mode instead of handling it, and the difference is worth being precise
+ * about, because "better" is otherwise just an adjective.
+ *
+ * **Mongo's claim throws and catches.** It inserts, and reads `code === 11000` to
+ * tell "somebody else has this event" from a real fault; everything that is not
+ * 11000 is rethrown, so a lost connection or a failover answers non-2xx and the
+ * event stays on the sender's retry schedule. That property is correct — and it
+ * lives in a PREDICATE. `catch { return false }` is one keystroke away, it
+ * type-checks, and it turns a connection failure into "already processed": the
+ * receiver answers 200 and a decision is retired that nobody ever handled. The
+ * only thing standing between those two behaviours is a conditional somebody
+ * could widen, and a test can only catch that by injecting a driver failure.
+ *
+ * **Postgres's claim does not throw at all.** `ON CONFLICT DO NOTHING` plus
+ * `RETURNING` makes a duplicate a ROW COUNT rather than an error: one row means
+ * this call took the claim, zero means somebody else holds it. So there is no
+ * catch block here — and therefore
+ *
+ *   - no predicate to widen,
+ *   - no code path that can convert a fault into a negative answer,
+ *   - and the "rethrow everything else" guarantee holds by the ABSENCE of code
+ *     rather than by the presence of correct code.
+ *
+ * That is the mechanism: the Mongo version is a property of code that exists and
+ * can be edited wrongly; this one is a property of code that does not exist. Only
+ * the second cannot be broken by a well-meaning change.
+ *
+ * The consequence for the mutation suite, stated because its absence would
+ * otherwise look like a gap: there is nothing to DELETE on the insert side, so no
+ * mutation can attack it. The one that exists attacks the READ — `rows.length === 1`
+ * collapsing to `true`, which would hand the same event to two handlers.
+ */
+function postgresEventStore(input) {
+    const { db } = input;
+    const events = input.tables.events;
+    return {
+        async claim({ eventId, receivedAt, expiresAt }) {
+            /**
+             * The insert IS the claim, and a lost race is zero rows rather than an
+             * exception. `created_at`/`updated_at` are left to their column defaults:
+             * unlike the outbox, nothing here needs a repeated write to be provably a
+             * no-op, so the database's clock is the simpler authority.
+             */
+            const rows = await db
+                .insert(events)
+                .values({ id: eventId, state: 'claimed', receivedAt, expiresAt })
+                .onConflictDoNothing({ target: events.id })
+                .returning({ id: events.id });
+            return rows.length === 1;
+        },
+        /** Give the claim back so a redelivery can be processed. */
+        async release(eventId) {
+            await db.delete(events).where((0, drizzle_orm_1.eq)(events.id, eventId));
+        },
+        async markQueued({ eventId, type, caseId, payload, now }, tx) {
+            /**
+             * On the CALLER's transaction, which is the whole point: this row's
+             * completion and the outbox row that carries the work commit together, or a
+             * crash between them leaves an event permanently deduplicated with no work
+             * queued — a decision silently lost, with a row saying it arrived.
+             */
+            await tx
+                .update(events)
+                .set({
+                type,
+                caseId,
+                payload,
+                state: 'queued',
+                queuedAt: now,
+                updatedAt: now,
+            })
+                .where((0, drizzle_orm_1.eq)(events.id, eventId));
+        },
+        async markIgnored({ eventId, type, caseId, now }) {
+            await db
+                .update(events)
+                .set({
+                type,
+                /**
+                 * Absent means LEAVE IT, not write something. An event type carrying no
+                 * case id is ordinary — `case.created` before a case is linked — and
+                 * `caseId: String(caseId)` would store the four characters `null` or
+                 * the nine characters `undefined`, which then reads as a case id
+                 * everywhere downstream. Postgres keeps the column NULL.
+                 */
+                ...(caseId === undefined ? {} : { caseId }),
+                state: 'ignored',
+                updatedAt: now,
+            })
+                .where((0, drizzle_orm_1.eq)(events.id, eventId));
+        },
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/outbox/postgres/store/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../../src/outbox/postgres/store/events.ts"],"names":[],"mappings":";;AA2CA,gDAoEC;AA/GD,6CAAiC;AAKjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,SAAgB,kBAAkB,CAAC,KAGlC;IACC,MAAM,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC;IACrB,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IAEnC,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE;YAC5C;;;;;eAKG;YACH,MAAM,IAAI,GAAG,MAAM,EAAE;iBAClB,MAAM,CAAC,MAAM,CAAC;iBACd,MAAM,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;iBAChE,mBAAmB,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC;iBAC1C,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;YAEhC,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;QAC3B,CAAC;QAED,4DAA4D;QAC5D,KAAK,CAAC,OAAO,CAAC,OAAO;YACnB,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,IAAA,gBAAE,EAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;QACxD,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE;YAC1D;;;;;eAKG;YACH,MAAM,EAAE;iBACL,MAAM,CAAC,MAAM,CAAC;iBACd,GAAG,CAAC;gBACH,IAAI;gBACJ,MAAM;gBACN,OAAO;gBACP,KAAK,EAAE,QAAQ;gBACf,QAAQ,EAAE,GAAG;gBACb,SAAS,EAAE,GAAG;aACf,CAAC;iBACD,KAAK,CAAC,IAAA,gBAAE,EAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;QACnC,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;YAC9C,MAAM,EAAE;iBACL,MAAM,CAAC,MAAM,CAAC;iBACd,GAAG,CAAC;gBACH,IAAI;gBACJ;;;;;;mBAMG;gBACH,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;gBAC3C,KAAK,EAAE,SAAS;gBAChB,SAAS,EAAE,GAAG;aACf,CAAC;iBACD,KAAK,CAAC,IAAA,gBAAE,EAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/outbox/postgres/store/index.d.ts

@@ -0,0 +1,27 @@
+import type { ModerationStore } from '../../store/types.js';
+import type { ModerationReportFields } from '../../types.js';
+import type { ModerationReportTable } from '../reportColumns.js';
+import type { ModerationTables } from '../tables.js';
+import { type ModerationPgHandle } from './transaction.js';
+/**
+ * Everything this package writes, in Postgres.
+ *
+ * One factory rather than five, because the five members must share one handle: a
+ * report and its outbox row commit in the SAME transaction, and a store assembled
+ * from two handles would type-check perfectly and quietly lose that.
+ *
+ * Unlike the Mongo factory, this one CREATES NOTHING. There is no schema to
+ * register: the adopter's own migration created the tables, generated from the
+ * definitions this package exports, in the adopter's own journal. That asymmetry
+ * is deliberate and is the reason no migrations folder ships here — two journals
+ * against one `drizzle.__drizzle_migrations` table interleave, and the loser is
+ * skipped in silence with exit 0.
+ */
+export declare function postgresModerationStore<TReport extends ModerationReportFields>(input: {
+    db: ModerationPgHandle;
+    /** The application's own report table, built from `moderationReportColumns`. */
+    reportTable: ModerationReportTable;
+    /** The three tables this package owns, from `moderationTables`. */
+    tables: ModerationTables;
+}): ModerationStore<TReport, ModerationPgHandle>;
+//# sourceMappingURL=index.d.ts.map

package/dist/outbox/postgres/store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/outbox/postgres/store/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKrD,OAAO,EAA6B,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,SAAS,sBAAsB,EAAE,KAAK,EAAE;IACrF,EAAE,EAAE,kBAAkB,CAAC;IACvB,gFAAgF;IAChF,WAAW,EAAE,qBAAqB,CAAC;IACnC,mEAAmE;IACnE,MAAM,EAAE,gBAAgB,CAAC;CAC1B,GAAG,eAAe,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAuC/C"}

package/dist/outbox/postgres/store/index.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postgresModerationStore = postgresModerationStore;
+const drizzle_orm_1 = require("drizzle-orm");
+const enforcement_js_1 = require("./enforcement.js");
+const events_js_1 = require("./events.js");
+const outbox_js_1 = require("./outbox.js");
+const reports_js_1 = require("./reports.js");
+const transaction_js_1 = require("./transaction.js");
+/**
+ * Everything this package writes, in Postgres.
+ *
+ * One factory rather than five, because the five members must share one handle: a
+ * report and its outbox row commit in the SAME transaction, and a store assembled
+ * from two handles would type-check perfectly and quietly lose that.
+ *
+ * Unlike the Mongo factory, this one CREATES NOTHING. There is no schema to
+ * register: the adopter's own migration created the tables, generated from the
+ * definitions this package exports, in the adopter's own journal. That asymmetry
+ * is deliberate and is the reason no migrations folder ships here — two journals
+ * against one `drizzle.__drizzle_migrations` table interleave, and the loser is
+ * skipped in silence with exit 0.
+ */
+function postgresModerationStore(input) {
+    const { db, reportTable, tables } = input;
+    return {
+        transaction: (0, transaction_js_1.postgresTransactionRunner)(db),
+        outbox: (0, outbox_js_1.postgresOutboxStore)({ db, tables }),
+        events: (0, events_js_1.postgresEventStore)({ db, tables }),
+        enforcement: (0, enforcement_js_1.postgresEnforcementStore)({ db, tables }),
+        reports: (0, reports_js_1.postgresReportStore)({ db, reportTable }),
+        /**
+         * ASSERTS the schema, rather than creating it.
+         *
+         * The Mongo half calls `init()` and builds indexes; there is nothing here to
+         * build, so what remains is worth doing for its own sake: confirming the four
+         * tables this package queries exist BEFORE the first report is filed rather
+         * than at the first delivery.
+         *
+         * A missing table raises `42P01 undefined_table` and names it. `limit(0)`
+         * means Postgres parses and plans each statement — which is what proves the
+         * relation resolves — without reading a row.
+         *
+         * It cannot check COLUMNS. An adopter whose migration is a version behind
+         * gets a compile error from `ModerationReportTable` for a missing column and
+         * a `42703` from the query for a stale migration; both are loud, and neither
+         * is this function's job.
+         */
+        async ensureSchema() {
+            const present = [
+                tables.outbox,
+                tables.events,
+                tables.enforcements,
+                reportTable,
+            ];
+            for (const table of present) {
+                await db.select({ resolves: (0, drizzle_orm_1.sql) `1` }).from(table).limit(0);
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/outbox/postgres/store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/outbox/postgres/store/index.ts"],"names":[],"mappings":";;AA0BA,0DA6CC;AAvED,6CAAkC;AAMlC,qDAA4D;AAC5D,2CAAiD;AACjD,2CAAkD;AAClD,6CAAmD;AACnD,qDAAsF;AAEtF;;;;;;;;;;;;;GAaG;AACH,SAAgB,uBAAuB,CAAyC,KAM/E;IACC,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAE1C,OAAO;QACL,WAAW,EAAE,IAAA,0CAAyB,EAAC,EAAE,CAAC;QAC1C,MAAM,EAAE,IAAA,+BAAmB,EAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;QAC3C,MAAM,EAAE,IAAA,8BAAkB,EAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;QAC1C,WAAW,EAAE,IAAA,yCAAwB,EAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;QACrD,OAAO,EAAE,IAAA,gCAAmB,EAAU,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC;QAE1D;;;;;;;;;;;;;;;;WAgBG;QACH,KAAK,CAAC,YAAY;YAChB,MAAM,OAAO,GAAuB;gBAClC,MAAM,CAAC,MAAM;gBACb,MAAM,CAAC,MAAM;gBACb,MAAM,CAAC,YAAY;gBACnB,WAAW;aACZ,CAAC;YACF,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAA,iBAAG,EAAA,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/outbox/postgres/store/outbox.d.ts

@@ -0,0 +1,8 @@
+import type { ModerationOutboxStore } from '../../store/types.js';
+import type { ModerationTables } from '../tables.js';
+import type { ModerationPgHandle } from './transaction.js';
+export declare function postgresOutboxStore(input: {
+    db: ModerationPgHandle;
+    tables: ModerationTables;
+}): ModerationOutboxStore<ModerationPgHandle>;
+//# sourceMappingURL=outbox.d.ts.map

package/dist/outbox/postgres/store/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../../../src/outbox/postgres/store/outbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAqC3D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,EAAE,EAAE,kBAAkB,CAAC;IACvB,MAAM,EAAE,gBAAgB,CAAC;CAC1B,GAAG,qBAAqB,CAAC,kBAAkB,CAAC,CAkO5C"}

package/dist/outbox/postgres/store/outbox.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postgresOutboxStore = postgresOutboxStore;
+const drizzle_orm_1 = require("drizzle-orm");
+const pg_core_1 = require("drizzle-orm/pg-core");
+const service_js_1 = require("../../outbox/service.js");
+function postgresOutboxStore(input) {
+    const { db } = input;
+    const outbox = input.tables.outbox;
+    /**
+     * Due work, as one predicate.
+     *
+     * Either `pending` and past its `available_at`, or `processing` with an EXPIRED
+     * lease — the second arm is what makes a dead worker's event reclaimable rather
+     * than stranded. The two arms have an index each
+     * (`moderation_outbox_due_idx`, `moderation_outbox_lease_idx`).
+     */
+    const dueOrExpired = (now) => (0, drizzle_orm_1.or)((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(outbox.status, 'pending'), (0, drizzle_orm_1.lte)(outbox.availableAt, now)), (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(outbox.status, 'processing'), (0, drizzle_orm_1.lte)(outbox.leaseUntil, now)));
+    /** The lease this caller claims to hold, still live. Shared by all three transitions. */
+    const heldLease = (eventId, leaseOwner, now) => (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(outbox.id, eventId), (0, drizzle_orm_1.eq)(outbox.status, 'processing'), (0, drizzle_orm_1.eq)(outbox.leaseOwner, leaseOwner), (0, drizzle_orm_1.gt)(outbox.leaseUntil, now));
+    const toEvent = (row) => ({
+        id: row.id,
+        kind: row.kind,
+        payload: row.payload,
+        attempts: row.attempts,
+        availableAt: row.availableAt,
+        // `null` is how Postgres stores "no lease"; the event type says absent.
+        ...(row.leaseOwner === null ? {} : { leaseOwner: row.leaseOwner }),
+        ...(row.leaseUntil === null ? {} : { leaseUntil: row.leaseUntil }),
+        expiresAt: row.expiresAt,
+        createdAt: row.createdAt,
+    });
+    return {
+        async enqueue(event, tx) {
+            /**
+             * The guard, and it is not the same mistake Mongo's guards against.
+             *
+             * Both `db` and `tx` are a `ModerationPgHandle`, so handing this the POOL
+             * handle type-checks perfectly — and then the row commits on its own
+             * connection, independently of the domain write it was supposed to be
+             * atomic with. That is "the report was answered 201 and never delivered",
+             * reached by a different route than a session nobody opened a transaction
+             * on, with the same silence.
+             *
+             * `PgTransaction` is a real runtime class in `drizzle-orm/pg-core`, so this
+             * is a genuine check rather than a duck-typed guess.
+             */
+            if (!(tx instanceof pg_core_1.PgTransaction)) {
+                throw new service_js_1.ModerationOutboxTransactionError(event.eventId);
+            }
+            /**
+             * `ON CONFLICT DO NOTHING`, never `DO UPDATE`.
+             *
+             * A repeated enqueue is ORDINARY — a transaction retry, two concurrent
+             * duplicate submissions, a reconciliation sweep re-deriving an event — and
+             * the dispatcher is concurrently taking, renewing and completing leases on
+             * these same rows. `DO UPDATE` would make each repeat a real write, which
+             * conflicts with a live lease update and aborts the enclosing transaction:
+             * the exact defect the Mongo store's `timestamps: false` exists to prevent,
+             * reintroduced in a dialect where nothing forces it on you.
+             *
+             * One behavioural difference from Mongo, and Postgres has the better end of
+             * it: if a CONCURRENT UNCOMMITTED transaction holds this same key, Postgres
+             * WAITS for it and then proceeds (finding the row committed, and doing
+             * nothing), where Mongo raises `WriteConflict` (code 112) and aborts the
+             * enclosing transaction. Waiting is the outcome a caller wants.
+             *
+             * `created_at` and `updated_at` are written explicitly from the caller's
+             * clock rather than left to their defaults, so both backends stamp a row
+             * from one instant — and so a test can assert that a repeat changed
+             * NOTHING, which is a stronger claim than "no duplicate row".
+             */
+            await tx
+                .insert(outbox)
+                .values({
+                id: event.eventId,
+                kind: event.kind,
+                payload: event.payload,
+                status: 'pending',
+                attempts: 0,
+                availableAt: event.availableAt,
+                expiresAt: event.expiresAt,
+                createdAt: event.now,
+                updatedAt: event.now,
+            })
+                .onConflictDoNothing({ target: outbox.id });
+        },
+        async claim({ leaseOwner, leaseUntil, now, eventId }) {
+            /**
+             * `SKIP LOCKED` is load-bearing, not tuning.
+             *
+             * Without it, under READ COMMITTED the sub-select is evaluated once: the
+             * loser blocks on the head row and then returns ZERO rows. `claim` answers
+             * `null`, `dispatch` breaks out of its batch, and a deployment running N
+             * tasks silently drains at 1/N the rate with nothing failing anywhere.
+             *
+             * The `FOR UPDATE` lives in the SUB-SELECT because that is what locks the
+             * one row this claim intends to take, before the UPDATE touches it — the
+             * documented Postgres idiom for a work queue.
+             */
+            const due = db
+                .select({ id: outbox.id })
+                .from(outbox)
+                .where(eventId === undefined
+                ? dueOrExpired(now)
+                : (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(outbox.id, eventId), dueOrExpired(now)))
+                // Oldest first, so a backlog drains in the order it was filed rather than
+                // in whatever order the storage engine finds convenient.
+                .orderBy((0, drizzle_orm_1.asc)(outbox.createdAt))
+                .limit(1)
+                .for('update', { skipLocked: true });
+            const rows = await db
+                .update(outbox)
+                .set({
+                status: 'processing',
+                leaseOwner,
+                leaseUntil,
+                // The COLUMN is interpolated, not a value: `attempts` is incremented by
+                // the database so two claimers cannot both read 3 and both write 4.
+                attempts: (0, drizzle_orm_1.sql) `${outbox.attempts} + 1`,
+                // The previous attempt's error, cleared with the claim so a stale
+                // message can never be read as this attempt's. `null` CLEARS in
+                // drizzle; `undefined` would leave it alone.
+                lastError: null,
+                updatedAt: now,
+            })
+                .where((0, drizzle_orm_1.inArray)(outbox.id, due))
+                .returning({
+                id: outbox.id,
+                kind: outbox.kind,
+                payload: outbox.payload,
+                attempts: outbox.attempts,
+                availableAt: outbox.availableAt,
+                leaseOwner: outbox.leaseOwner,
+                leaseUntil: outbox.leaseUntil,
+                expiresAt: outbox.expiresAt,
+                createdAt: outbox.createdAt,
+            });
+            const [row] = rows;
+            return row === undefined ? null : toEvent(row);
+        },
+        /**
+         * ## Why all three transitions read `RETURNING`, and what that collapses
+         *
+         * Mongo's `complete` and `fail` answer `modifiedCount === 1` while its
+         * `renew` answers `matchedCount === 1`. `RETURNING` counts MATCHED rows, so
+         * this store answers the `matchedCount` question in all three places.
+         *
+         * That is equivalent HERE, and the argument is worth writing down because it
+         * is an argument rather than a test: the WHERE clause requires
+         * `status = 'processing'`, and `complete` and `fail` both write a different
+         * status, so a matched row is always a modified row. `renew` writes only
+         * `lease_until`/`updated_at` and Mongo already used `matchedCount` for it —
+         * a renewal that lands on the values already stored is still a lease this
+         * caller holds, and reporting it as lost would make a dispatcher abandon an
+         * event it still owns.
+         *
+         * If a later transition ever stops changing `status`, this equivalence stops
+         * holding and the difference becomes silent.
+         */
+        async complete({ eventId, leaseOwner, now }) {
+            const rows = await db
+                .update(outbox)
+                .set({
+                status: 'processed',
+                processedAt: now,
+                updatedAt: now,
+                leaseOwner: null,
+                leaseUntil: null,
+                lastError: null,
+            })
+                .where(heldLease(eventId, leaseOwner, now))
+                .returning({ id: outbox.id });
+            return rows.length === 1;
+        },
+        async renew({ eventId, leaseOwner, leaseUntil, now }) {
+            const rows = await db
+                .update(outbox)
+                .set({ leaseUntil, updatedAt: now })
+                .where(heldLease(eventId, leaseOwner, now))
+                .returning({ id: outbox.id });
+            return rows.length === 1;
+        },
+        async fail({ eventId, leaseOwner, status, availableAt, lastError, now }) {
+            const rows = await db
+                .update(outbox)
+                .set({
+                status,
+                availableAt,
+                lastError,
+                updatedAt: now,
+                leaseOwner: null,
+                leaseUntil: null,
+            })
+                .where(heldLease(eventId, leaseOwner, now))
+                .returning({ id: outbox.id });
+            return rows.length === 1;
+        },
+        async statusOf(eventId) {
+            const rows = await db
+                .select({ status: outbox.status })
+                .from(outbox)
+                .where((0, drizzle_orm_1.eq)(outbox.id, eventId))
+                .limit(1);
+            const [row] = rows;
+            return row === undefined ? null : row.status;
+        },
+    };
+}
+//# sourceMappingURL=outbox.js.map

package/dist/outbox/postgres/store/outbox.js.map

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

package/dist/outbox/postgres/store/reports.d.ts

@@ -0,0 +1,69 @@
+import type { ModerationReportStore } from '../../store/types.js';
+import type { ModerationReportFields } from '../../types.js';
+import type { ModerationReportTable } from '../reportColumns.js';
+import type { ModerationPgHandle } from './transaction.js';
+/**
+ * The application's own report table, in Postgres.
+ *
+ * The only store that takes a table it did not define, which is what makes the
+ * structural type worth having: an adopter who forgets a column this package
+ * queries gets a COMPILE ERROR at the `postgresModerationStore(...)` call rather
+ * than a runtime failure on the first delivery.
+ *
+ * `scripts/test-report-table-type.mjs` proves that gate in both directions and
+ * records exactly what it does not catch — a column present under the right name
+ * but the wrong TYPE passes, because every member of `ModerationReportTable` is a
+ * bare `PgColumn`. The DDL and the schema tests are what cover that half.
+ *
+ * ## Two Mongo hazards that do not exist here
+ *
+ * **A malformed id is not an error.** `id` is `text`, so an id nothing could have
+ * generated simply matches no rows and `findById` answers `null` — which is
+ * exactly what the delivery worker already does with "the report is gone".
+ * Mongoose raises a `CastError` for the same input and its store has to catch it.
+ * There is nothing to catch here, and adding a branch for `22P02` would be
+ * writing a handler for an error this column cannot raise.
+ *
+ * **A bound parameter cannot become a query operator.** `requireIdentifier` in
+ * `intake.ts` still runs, and still should — a non-string corrupts data on any
+ * backend, and the function is exported for callers with no route validation. But
+ * the specific failure it was written for, `{ $ne: null }` arriving as a value and
+ * matching an unrelated report, is a Mongo shape: here a parameter is a parameter.
+ *
+ * ## One thing that is worse, stated plainly
+ *
+ * Every read hands the caller `TReport`, and no type can prove that: the adopter
+ * owns the type AND the table, and the two are only connected by their names. See
+ * {@link asReport}.
+ */
+/**
+ * The fields `ModerationReportFields` declares OPTIONAL, computed from the type.
+ *
+ * Postgres stores an absent value as NULL; Mongo omits the field. Both are the
+ * same claim — "this never happened" — and one suite has to be able to assert it
+ * once, so the package's own optional fields come back ABSENT from either
+ * backend. Two `describe.each` pairs failed on exactly this before it was
+ * settled, both reading `expected null to be undefined`, and neither was about
+ * behaviour.
+ *
+ * Only the fields the PORT owns are normalised. An adopter's own nullable column
+ * is theirs: `extra` goes in untouched and comes back untouched.
+ */
+type OptionalReportField = {
+    [K in keyof ModerationReportFields]-?: undefined extends ModerationReportFields[K] ? K : never;
+}[keyof ModerationReportFields];
+declare const OPTIONAL_REPORT_FIELDS: readonly ["details", "localStatusReason", "crowdSourceReportId", "crowdSourceCaseId", "crowdSourceMerged", "contentSnapshotHash", "submittedAt", "lastDeliveryError", "decisionId", "decisionRevision", "decisionOutcome", "decisionStatus", "decidedAt", "enforcedAction", "enforcedAt"];
+/** `T` when it is `never`, and a compile error naming the field when it is not. */
+type AssertNever<T extends never> = T;
+/**
+ * The exhaustiveness gate. `satisfies` above refuses a field that is not optional;
+ * THIS refuses an optional field that is missing from the list — the direction
+ * that would otherwise ship as a backend difference nobody looked for.
+ */
+export type UncoveredOptionalReportField = AssertNever<Exclude<OptionalReportField, (typeof OPTIONAL_REPORT_FIELDS)[number]>>;
+export declare function postgresReportStore<TReport extends ModerationReportFields>(input: {
+    db: ModerationPgHandle;
+    reportTable: ModerationReportTable;
+}): ModerationReportStore<TReport, ModerationPgHandle>;
+export {};
+//# sourceMappingURL=reports.d.ts.map

package/dist/outbox/postgres/store/reports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reports.d.ts","sourceRoot":"","sources":["../../../../src/outbox/postgres/store/reports.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;;;;;GAYG;AACH,KAAK,mBAAmB,GAAG;KACxB,CAAC,IAAI,MAAM,sBAAsB,CAAC,CAAC,GAAG,SAAS,SAAS,sBAAsB,CAAC,CAAC,CAAC,GAC9E,CAAC,GACD,KAAK;CACV,CAAC,MAAM,sBAAsB,CAAC,CAAC;AAEhC,QAAA,MAAM,sBAAsB,2RAgBuB,CAAC;AAEpD,mFAAmF;AACnF,KAAK,WAAW,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC;AAEtC;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GAAG,WAAW,CACpD,OAAO,CAAC,mBAAmB,EAAE,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC,CACtE,CAAC;AA+BF,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,sBAAsB,EAAE,KAAK,EAAE;IACjF,EAAE,EAAE,kBAAkB,CAAC;IACvB,WAAW,EAAE,qBAAqB,CAAC;CACpC,GAAG,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAwMrD"}