@crowdsource.you/core 1.2.0

package/src/outbox/postgres/store/outbox.ts

@@ -0,0 +1,273 @@
+import { and, asc, eq, gt, inArray, lte, or, sql } from 'drizzle-orm';
+import { PgTransaction } from 'drizzle-orm/pg-core';
+import { ModerationOutboxTransactionError } from '../../outbox/service.js';
+import type { ModerationOutboxStore } from '../../store/types.js';
+import type { ModerationOutboxEvent } from '../../types.js';
+import type { ModerationTables } from '../tables.js';
+import type { ModerationPgHandle } from './transaction.js';
+
+/**
+ * The moderation outbox, in Postgres.
+ *
+ * Same six operations as the Mongo store, same policy handed down from the
+ * service above it, four places where the mechanism differs — and each of those
+ * is where the correctness lives:
+ *
+ * 1. **The transaction guard is `instanceof PgTransaction`.** Mongo's equivalent
+ *    asks a session whether a transaction is open; here the mistake is passing
+ *    the POOL handle where the `tx` belongs, which runs on a different connection
+ *    and commits independently. Same lost guarantee, different shape, and it
+ *    type-checks perfectly because both are `ModerationPgHandle`.
+ * 2. **The insert-if-absent is `ON CONFLICT DO NOTHING`.** A no-op by
+ *    construction rather than by suppressing an ORM's timestamp behaviour: it
+ *    writes nothing and takes no row lock on an already-committed conflicting
+ *    row. Never `DO UPDATE` — that reintroduces exactly the defect the Mongo
+ *    side's `timestamps: false` exists to prevent.
+ * 3. **The claim is `FOR UPDATE SKIP LOCKED`.** Load-bearing, not tuning: see
+ *    `claim`.
+ * 4. **Every lease transition asks `RETURNING` how many rows matched.**
+ */
+
+/** The columns a claimed event is read back through. */
+type ClaimedRow = {
+  id: string;
+  kind: ModerationOutboxEvent['kind'];
+  payload: ModerationOutboxEvent['payload'];
+  attempts: number;
+  availableAt: Date;
+  leaseOwner: string | null;
+  leaseUntil: Date | null;
+  expiresAt: Date;
+  createdAt: Date;
+};
+
+export function postgresOutboxStore(input: {
+  db: ModerationPgHandle;
+  tables: ModerationTables;
+}): ModerationOutboxStore<ModerationPgHandle> {
+  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: Date) =>
+    or(
+      and(eq(outbox.status, 'pending'), lte(outbox.availableAt, now)),
+      and(eq(outbox.status, 'processing'), lte(outbox.leaseUntil, now)),
+    );
+
+  /** The lease this caller claims to hold, still live. Shared by all three transitions. */
+  const heldLease = (eventId: string, leaseOwner: string, now: Date) =>
+    and(
+      eq(outbox.id, eventId),
+      eq(outbox.status, 'processing'),
+      eq(outbox.leaseOwner, leaseOwner),
+      gt(outbox.leaseUntil, now),
+    );
+
+  const toEvent = (row: ClaimedRow): ModerationOutboxEvent => ({
+    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 PgTransaction)) {
+        throw new 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)
+            : and(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(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: 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(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(eq(outbox.id, eventId))
+        .limit(1);
+      const [row] = rows;
+      return row === undefined ? null : row.status;
+    },
+  };
+}

package/src/outbox/postgres/store/reports.ts

@@ -0,0 +1,349 @@
+import { and, asc, eq, inArray, isNull, lt, lte, or, sql } from 'drizzle-orm';
+import type {
+  ModerationReportDecisionUpdate,
+  ModerationReportRef,
+  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];
+
+const OPTIONAL_REPORT_FIELDS = [
+  'details',
+  'localStatusReason',
+  'crowdSourceReportId',
+  'crowdSourceCaseId',
+  'crowdSourceMerged',
+  'contentSnapshotHash',
+  'submittedAt',
+  'lastDeliveryError',
+  'decisionId',
+  'decisionRevision',
+  'decisionOutcome',
+  'decisionStatus',
+  'decidedAt',
+  'enforcedAction',
+  'enforcedAt',
+] as const satisfies readonly OptionalReportField[];
+
+/** `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]>
+>;
+
+/** Drop the package's own optional fields when the column is NULL. */
+function absentWhereNull(row: Record<string, unknown>): Record<string, unknown> {
+  const normalised: Record<string, unknown> = { ...row };
+  for (const field of OPTIONAL_REPORT_FIELDS) {
+    if (normalised[field] === null) delete normalised[field];
+  }
+  return normalised;
+}
+
+/**
+ * The row, as the port declares it.
+ *
+ * An unchecked declaration, not a conversion — the same escape the Mongoose store
+ * takes with `.lean<TReport>()`, and for the same reason: a driver cannot know an
+ * adopter's row type, and `ModerationReportTable` deliberately erases column types
+ * so that any adopter's table is accepted.
+ *
+ * What bounds it is that both halves are checked elsewhere. Column PRESENCE is a
+ * compile error, gated by `scripts/test-report-table-type.mjs`. Column VALUES are
+ * asserted by round-trips against a real database in
+ * `postgresReportStore.test.ts`. What remains unchecked is a column declared with
+ * the wrong TYPE, which the migration and the schema test cover instead.
+ */
+function asReport<TReport extends ModerationReportFields>(
+  row: Record<string, unknown>,
+): TReport {
+  return absentWhereNull(row) as TReport;
+}
+
+export function postgresReportStore<TReport extends ModerationReportFields>(input: {
+  db: ModerationPgHandle;
+  reportTable: ModerationReportTable;
+}): ModerationReportStore<TReport, ModerationPgHandle> {
+  const { db } = input;
+  const reports = input.reportTable;
+
+  /**
+   * `count(*)::int`, and the cast is load-bearing.
+   *
+   * `count(*)` is `bigint`, which postgres.js hands back as a STRING to avoid
+   * losing precision — so `sql<number>` without the cast is an assertion that
+   * quietly lies, and the caller's `number` is `'3'`. The `::int` makes the
+   * database do the conversion.
+   */
+  const total = sql<number>`count(*)::int`;
+
+  return {
+    async findDuplicate({ reporter, reportedId, reportedType }, tx) {
+      const rows = await tx
+        .select()
+        .from(reports)
+        .where(
+          and(
+            eq(reports.reporter, reporter),
+            eq(reports.reportedId, reportedId),
+            eq(reports.reportedType, reportedType),
+          ),
+        )
+        .limit(1);
+      const [row] = rows;
+      return row === undefined ? null : asReport<TReport>(row);
+    },
+
+    async insert(report, tx) {
+      const rows = await tx
+        .insert(reports)
+        .values({
+          /**
+           * The application's own columns FIRST, so a field this package owns can
+           * never be overwritten by one it knows nothing about. A report whose
+           * `localStatus` came from `extra` would be queued with nothing to
+           * deliver it, or received with a delivery event that tries anyway.
+           *
+           * A key that is not a column raises here — Postgres has no silent
+           * discard. Mongoose strict mode drops an undeclared path with no throw
+           * and no warning, which is why the Mongo half needs a standing test
+           * that every DTO field resolves to a schema path.
+           */
+          ...report.extra,
+          reportedType: report.reportedType,
+          reportedId: report.reportedId,
+          reporter: report.reporter,
+          categories: [...report.categories],
+          ...(report.details === undefined ? {} : { details: report.details }),
+          localStatus: report.localStatus,
+          ...(report.localStatusReason === undefined
+            ? {}
+            : { localStatusReason: report.localStatusReason }),
+        })
+        .returning();
+
+      const [row] = rows;
+      if (row === undefined) {
+        throw new Error('The moderation report insert returned no row.');
+      }
+      return asReport<TReport>(row);
+    },
+
+    async findById(reportId) {
+      const rows = await db.select().from(reports).where(eq(reports.id, reportId)).limit(1);
+      const [row] = rows;
+      return row === undefined ? null : asReport<TReport>(row);
+    },
+
+    async findByCaseId(caseId) {
+      const rows = await db
+        .select({
+          id: reports.id,
+          reportedType: reports.reportedType,
+          reportedId: reports.reportedId,
+        })
+        .from(reports)
+        .where(eq(reports.crowdSourceCaseId, caseId));
+
+      return rows.map(
+        (row): ModerationReportRef => ({
+          id: String(row.id),
+          reportedType: String(row.reportedType),
+          reportedId: String(row.reportedId),
+        }),
+      );
+    },
+
+    async applyDecision(reportId, update, maxRevision) {
+      const rows = await db
+        .update(reports)
+        .set(decisionSet(update))
+        .where(
+          and(
+            eq(reports.id, reportId),
+            /**
+             * The revision guard, in the WHERE clause. It is the DATABASE that
+             * refuses a stale write rather than a read-then-write in this
+             * process: deliveries overlap — CrowdSource retries for 24 hours, and
+             * a correction can arrive while the decision it supersedes is still
+             * being applied — and an older revision landing last would otherwise
+             * overwrite the current answer.
+             *
+             * `IS NULL` is the port of Mongo's `$exists: false`, because a report
+             * with no decision yet stores NULL rather than omitting the column.
+             * `<=` rather than `<` is deliberate: a redelivery of the SAME
+             * revision rewrites, which is harmless and keeps a partially-applied
+             * decision converging.
+             */
+            or(
+              isNull(reports.decisionRevision),
+              lte(reports.decisionRevision, maxRevision),
+            ),
+          ),
+        )
+        .returning({ id: reports.id });
+
+      return rows.length === 1;
+    },
+
+    async markSubmitted(reportId, submission) {
+      await db
+        .update(reports)
+        .set({
+          localStatus: 'submitted',
+          crowdSourceReportId: submission.crowdSourceReportId,
+          crowdSourceCaseId: submission.crowdSourceCaseId,
+          crowdSourceMerged: submission.crowdSourceMerged,
+          contentSnapshotHash: submission.contentSnapshotHash,
+          submittedAt: submission.submittedAt,
+          // A report that has landed carries no failure and no reason it was
+          // going nowhere. `null` CLEARS in drizzle; `undefined` would leave the
+          // stale value in place, which is the port of Mongo's `$unset`.
+          lastDeliveryError: null,
+          localStatusReason: null,
+        })
+        .where(eq(reports.id, reportId));
+    },
+
+    async markDeliveryFailed(reportId, lastDeliveryError) {
+      await db
+        .update(reports)
+        .set({ localStatus: 'delivery_failed', lastDeliveryError })
+        .where(eq(reports.id, reportId));
+    },
+
+    async close(reportId, localStatusReason) {
+      await db
+        .update(reports)
+        .set({ localStatus: 'closed', localStatusReason })
+        .where(eq(reports.id, reportId));
+    },
+
+    async findPendingOldestFirst(limit) {
+      /**
+       * `queued` and `delivery_failed` only. `received` is excluded deliberately
+       * and the omission is the safety property, not an oversight: those reports
+       * have no subject provider, so an event re-derived for one would fail on
+       * its first attempt and dead-letter.
+       *
+       * Oldest first, and ASC needs no explicit NULLS placement: both drizzle and
+       * Postgres default ascending to NULLS LAST, so this matches the
+       * `(local_status, created_at)` index. A DESCENDING order would need the
+       * placement spelled out — see the enforcement store's reversal lookup for
+       * what that costs when it is not.
+       */
+      const rows = await db
+        .select({ id: reports.id })
+        .from(reports)
+        .where(inArray(reports.localStatus, ['queued', 'delivery_failed']))
+        .orderBy(asc(reports.createdAt))
+        .limit(limit);
+
+      return rows.map((row) => String(row.id));
+    },
+
+    async countAwaitingDecision(submittedBefore) {
+      const rows = await db
+        .select({ total })
+        .from(reports)
+        .where(
+          and(
+            eq(reports.localStatus, 'submitted'),
+            lt(reports.submittedAt, submittedBefore),
+          ),
+        );
+      return rows[0]?.total ?? 0;
+    },
+
+    async countLocalOnly() {
+      const rows = await db
+        .select({ total })
+        .from(reports)
+        .where(eq(reports.localStatus, 'received'));
+      return rows[0]?.total ?? 0;
+    },
+  };
+}
+
+/**
+ * The `$set` a decision writes, as one object.
+ *
+ * `extra` FIRST, for the same reason it is first on insert: it is the adopter's
+ * legacy verdict field, and this package's own fields must win.
+ */
+function decisionSet(update: ModerationReportDecisionUpdate): Record<string, unknown> {
+  return {
+    ...update.extra,
+    localStatus: update.localStatus,
+    decisionId: update.decisionId,
+    decisionRevision: update.decisionRevision,
+    decisionOutcome: update.decisionOutcome,
+    decisionStatus: update.decisionStatus,
+    decidedAt: update.decidedAt,
+    ...(update.enforcedAction === undefined
+      ? {}
+      : { enforcedAction: update.enforcedAction }),
+    ...(update.enforcedAt === undefined ? {} : { enforcedAt: update.enforcedAt }),
+  };
+}

package/src/outbox/postgres/store/transaction.ts

@@ -0,0 +1,64 @@
+import type { TablesRelationalConfig } from 'drizzle-orm';
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { ModerationTransactionRunner } from '../../store/types.js';
+
+/**
+ * The drizzle handle this package's Postgres stores talk to.
+ *
+ * Deliberately the BASE `PgDatabase` rather than a `PostgresJsDatabase`: the
+ * stores must accept both the pool handle an adopter builds and the `tx` handed
+ * to a `db.transaction` callback, and those are different types. Written this
+ * way, one signature serves both and no store needs to know which it holds.
+ *
+ * ## The generic that has to be `Record<string, unknown>`, and the error you get
+ *
+ * `TablesRelationalConfig` and `Record<string, unknown>` are the only spellings
+ * that accept both. The narrow one a reader reaches for first —
+ * `Record<string, never>` for the schema — accepts NEITHER (`TS2345`, the schema
+ * generic is invariant).
+ *
+ * The consequence lands on the ADOPTER, so it is worth stating: a handle built
+ * with NO schema (`drizzle(client)`, or `PostgresJsDatabase<Record<string, never>>`)
+ * is not assignable either, and the compiler explains it as
+ * `Seems like the schema generic is missing - did you forget to add it to your DB
+ * type?` — an error about `query`, on a store call that never touches the
+ * relational query builder. Pass your schema to `drizzle()` (or use
+ * `createDatabase({ databaseUrl, schema })` from `@oxy.so/db`) and it resolves.
+ * Both directions are verified in this package's own type-check.
+ */
+export type ModerationPgHandle = PgDatabase<
+  PgQueryResultHKT,
+  Record<string, unknown>,
+  TablesRelationalConfig
+>;
+
+/**
+ * The transaction runner, in Postgres.
+ *
+ * READ COMMITTED, explicitly, and not `repeatable read`. Neither multi-statement
+ * transaction this package runs — a report insert plus an outbox upsert, an event
+ * update plus an outbox upsert — reads-then-decides in a way snapshot isolation
+ * protects, so `repeatable read` would import `40001` serialization failures and
+ * a retry loop for no benefit.
+ *
+ * What it deliberately does NOT promise: intake's duplicate-check-then-insert is
+ * not serialized at READ COMMITTED, and the "one report per reporter per object"
+ * unique index is explicitly the application's responsibility.
+ *
+ * The failure this runner exists to make impossible is subtler than Mongo's. A
+ * store call given `db` instead of `tx` inside the callback runs on a DIFFERENT
+ * pooled connection and commits on its own — no error, no warning, and the
+ * atomicity the outbox exists for is simply gone. `postgresOutboxStore.enqueue`
+ * refuses a handle that is not a transaction for exactly that reason.
+ */
+export function postgresTransactionRunner(
+  db: ModerationPgHandle,
+): ModerationTransactionRunner<ModerationPgHandle> {
+  return {
+    async run<T>(operation: (tx: ModerationPgHandle) => Promise<T>): Promise<T> {
+      return await db.transaction(async (tx) => await operation(tx), {
+        isolationLevel: 'read committed',
+      });
+    },
+  };
+}