@crowdsource.you/core 1.2.0

package/src/outbox/outbox/service.ts

@@ -0,0 +1,444 @@
+import { randomUUID } from 'crypto';
+import { MODERATION_OUTBOX_RETENTION_SECONDS } from '../retention.js';
+import type { ModerationOutboxStore } from '../store/types.js';
+import type {
+  ModerationDispatchResult,
+  ModerationLogger,
+  ModerationOutboxEvent,
+  ModerationOutboxKind,
+  ModerationOutboxPayload,
+  ModerationOutboxStatus,
+} from '../types.js';
+
+/**
+ * Claiming, completing and failing moderation outbox events.
+ *
+ * The contract is at-least-once: handlers MUST make every downstream effect
+ * idempotent using the event `id`, because an expired lease is reclaimable and
+ * a worker can die mid-delivery.
+ *
+ * What differs from an ordinary work queue is where retrying stops. A delivery
+ * failure the SDK marks as not retryable is a defect in the payload, not a blip
+ * — see {@link OutboxService.fail}.
+ *
+ * Every decision in this file is a POLICY decision — the retry ceiling, the
+ * backoff curve, the lease-length floor, what counts as retryable, how long a
+ * row is kept. The queries that carry them out belong to a
+ * {@link ModerationOutboxStore}, outside the PostgreSQL query implementation.
+ */
+
+const DEFAULT_LEASE_MS = 60_000;
+const DEFAULT_BATCH_SIZE = 50;
+const MAX_BATCH_SIZE = 500;
+const MAX_BACKOFF_MS = 6 * 60 * 60 * 1_000;
+const MIN_LEASE_RENEW_INTERVAL_MS = 250;
+
+/**
+ * Attempts after which a retryable failure is treated as permanent.
+ *
+ * Generous: a retryable failure means CrowdSource might still accept this exact
+ * payload, and with `MAX_BACKOFF_MS` capped at six hours this is several days of
+ * trying. A report that has not landed by then needs a human, not another
+ * attempt.
+ */
+const MAX_RETRYABLE_ATTEMPTS = 25;
+
+/**
+ * The event id for delivering a report.
+ *
+ * Derived from the report, not from the request: a transaction retry or two
+ * concurrent duplicate submissions upsert the SAME event rather than queueing
+ * two deliveries. There is exactly one delivery event per report for the life of
+ * the report, which is also what makes the CrowdSource-side idempotency key
+ * stable.
+ */
+export function reportSubmitEventId(reportId: string): string {
+  return `moderation:report.submit:${reportId}`;
+}
+
+/**
+ * The event id for applying an inbound decision.
+ *
+ * The webhook event id is the key, so a redelivery of the same event can never
+ * queue the work twice even if the dedupe claim were somehow released.
+ */
+export function decisionApplyEventId(eventId: string): string {
+  return `moderation:decision.apply:${eventId}`;
+}
+
+/**
+ * Raised when an outbox event is written outside a transaction.
+ *
+ * Never expected at runtime. It exists so the invariant is ENFORCED rather than
+ * reviewed. It is thrown by the STORE — only a backend knows what an open
+ * transaction looks like — and it lives here so that every backend throws the
+ * same error for the same mistake. See {@link ModerationOutboxStore.enqueue}.
+ */
+export class ModerationOutboxTransactionError extends Error {
+  constructor(eventId: string) {
+    super(
+      `Refusing to enqueue moderation outbox event '${eventId}' outside a transaction: ` +
+        'the domain write and this row must commit together, or a report is answered 201 ' +
+        'and never delivered.',
+    );
+    this.name = 'ModerationOutboxTransactionError';
+  }
+}
+
+/**
+ * A failure that says whether trying the same payload again could ever work.
+ *
+ * Every error `@crowdsource.you/core` throws carries `retryable`, which is the only
+ * thing a delivery worker needs from it. Anything else — a bug in this code, a
+ * Mongo error — is treated as retryable, because assuming a defect is permanent
+ * is how a recoverable outage becomes lost moderation work.
+ */
+export function isRetryableDeliveryError(error: unknown): boolean {
+  if (typeof error === 'object' && error !== null && 'retryable' in error) {
+    const retryable: unknown = (error as { retryable: unknown }).retryable;
+    if (typeof retryable === 'boolean') return retryable;
+  }
+  return true;
+}
+
+export interface ModerationOutboxFailure {
+  released: boolean;
+  deadLettered: boolean;
+}
+
+export type ModerationOutboxHandler = (event: ModerationOutboxEvent) => Promise<void>;
+
+interface LeaseHeartbeatResult {
+  lost: boolean;
+  error?: unknown;
+}
+
+function nextAttemptAt(attempts: number, now: Date): Date {
+  const exponent = Math.max(0, Math.min(attempts - 1, 20));
+  return new Date(now.getTime() + Math.min(1_000 * 2 ** exponent, MAX_BACKOFF_MS));
+}
+
+/**
+ * Draining the outbox: the one operation that never touches a transaction.
+ *
+ * Split out so {@link ModerationOutboxDispatcher} — which only ever asks for a
+ * batch — does not carry a backend's transaction type through a class that has
+ * no use for it.
+ */
+export interface OutboxDrain {
+  /** Drain up to `batchSize` due events. Bounded, at-least-once, lease-protected. */
+  dispatch(options: {
+    handler: ModerationOutboxHandler;
+    leaseOwner?: string;
+    batchSize?: number;
+    leaseMs?: number;
+    signal?: AbortSignal;
+  }): Promise<ModerationDispatchResult>;
+}
+
+export interface OutboxService<TTx> extends OutboxDrain {
+  /**
+   * Write the event in the CALLER's transaction.
+   *
+   * The transaction is required, not optional. This is the whole point of the
+   * collection: the domain write and this row commit together or not at all. An
+   * overload that let a caller enqueue outside a transaction would be the one
+   * line that quietly reintroduces "the report was answered 201 and then
+   * vanished".
+   *
+   * The type makes the transaction mandatory; the STORE makes it mandatory that
+   * the transaction is ACTUALLY OPEN, by throwing
+   * {@link ModerationOutboxTransactionError}. A required parameter is satisfied
+   * by any handle — including a bare Mongo `startSession()` nobody opened a
+   * transaction on, which type-checks perfectly and commits the row on its own.
+   * That is the shape of the mistake worth catching: it looks exactly like
+   * correct code, it passes any test that only asserts the row exists, and it
+   * fails as lost moderation work with no trace on the day something restarts
+   * between the two writes.
+   *
+   * This function is also the ONLY writer of that table — the dispatcher claims
+   * existing rows and never creates one — so there is no second queue that can
+   * drift out of sync with the outbox. A job here is never the only evidence
+   * that work exists, because the row IS the job.
+   */
+  enqueue(
+    input: {
+      eventId: string;
+      kind: ModerationOutboxKind;
+      payload: ModerationOutboxPayload;
+    },
+    tx: TTx,
+  ): Promise<string>;
+
+  /**
+   * Atomically claim one due event. An expired `processing` lease is
+   * reclaimable, so a dead worker cannot strand moderation work forever.
+   */
+  claim(options: {
+    leaseOwner: string;
+    eventId?: string;
+    now?: Date;
+    leaseMs?: number;
+  }): Promise<ModerationOutboxEvent | null>;
+
+  /** Complete only the lease this dispatcher currently owns. */
+  complete(eventId: string, leaseOwner: string, now?: Date): Promise<boolean>;
+
+  /** Extend only a live lease still owned by this dispatcher. */
+  renew(
+    eventId: string,
+    leaseOwner: string,
+    leaseMs: number,
+    now?: Date,
+  ): Promise<ModerationOutboxFailure['released']>;
+
+  /**
+   * Release a failed claim, with backoff — or stop.
+   *
+   * Stopping is not an optimisation. A 409 means this `externalReportId` already
+   * exists at CrowdSource with a different body, and no number of retries turns
+   * two payloads into one report; a 422 means the envelope is not processable.
+   * Both need the payload to change, so they become `dead_letter` immediately
+   * and stay visible with their error rather than accumulating attempts nobody
+   * reads.
+   */
+  fail(
+    event: Pick<ModerationOutboxEvent, 'id' | 'attempts'>,
+    leaseOwner: string,
+    error: unknown,
+    now?: Date,
+  ): Promise<ModerationOutboxFailure>;
+
+  /** The status of one event, or `null`. Read by reconciliation. */
+  statusOf(eventId: string): Promise<ModerationOutboxStatus | null>;
+}
+
+export function createOutboxService<TTx>(input: {
+  store: ModerationOutboxStore<TTx>;
+  logger: ModerationLogger;
+}): OutboxService<TTx> {
+  const { store, logger } = input;
+
+  const renew: OutboxService<TTx>['renew'] = async (
+    eventId,
+    leaseOwner,
+    leaseMs,
+    now = new Date(),
+  ) =>
+    await store.renew({
+      eventId,
+      leaseOwner,
+      // The floor is policy, not storage: a lease shorter than a second is
+      // reclaimable before the delivery it protects has begun.
+      leaseUntil: new Date(now.getTime() + Math.max(1_000, leaseMs)),
+      now,
+    });
+
+  function startLeaseHeartbeat(options: {
+    eventId: string;
+    leaseOwner: string;
+    leaseMs: number;
+  }): { stop: () => Promise<LeaseHeartbeatResult> } {
+    const renewIntervalMs = Math.max(
+      MIN_LEASE_RENEW_INTERVAL_MS,
+      Math.floor(options.leaseMs / 3),
+    );
+    let stopped = false;
+    let lost = false;
+    let renewalError: unknown;
+    let renewalInFlight: Promise<void> | null = null;
+
+    const tick = (): void => {
+      if (stopped || lost || renewalInFlight) return;
+      const renewal = renew(options.eventId, options.leaseOwner, options.leaseMs)
+        .then((stillOwner) => {
+          if (!stillOwner) lost = true;
+        })
+        .catch((error: unknown) => {
+          lost = true;
+          renewalError = error;
+        })
+        .finally(() => {
+          if (renewalInFlight === renewal) renewalInFlight = null;
+        });
+      renewalInFlight = renewal;
+    };
+
+    const timer = setInterval(tick, renewIntervalMs);
+    timer.unref?.();
+
+    return {
+      async stop(): Promise<LeaseHeartbeatResult> {
+        stopped = true;
+        clearInterval(timer);
+        await renewalInFlight;
+        return { lost, error: renewalError };
+      },
+    };
+  }
+
+  const claim: OutboxService<TTx>['claim'] = async (options) => {
+    const now = options.now ?? new Date();
+    const leaseMs = Math.max(1_000, options.leaseMs ?? DEFAULT_LEASE_MS);
+    return await store.claim({
+      leaseOwner: options.leaseOwner,
+      leaseUntil: new Date(now.getTime() + leaseMs),
+      now,
+      ...(options.eventId === undefined ? {} : { eventId: options.eventId }),
+    });
+  };
+
+  const complete: OutboxService<TTx>['complete'] = async (
+    eventId,
+    leaseOwner,
+    now = new Date(),
+  ) => await store.complete({ eventId, leaseOwner, now });
+
+  const fail: OutboxService<TTx>['fail'] = async (
+    event,
+    leaseOwner,
+    error,
+    now = new Date(),
+  ) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const retryable = isRetryableDeliveryError(error);
+    const deadLettered = !retryable || event.attempts >= MAX_RETRYABLE_ATTEMPTS;
+
+    const released = await store.fail({
+      eventId: event.id,
+      leaseOwner,
+      status: deadLettered ? 'dead_letter' : 'pending',
+      availableAt: deadLettered ? now : nextAttemptAt(event.attempts, now),
+      // Bounded here rather than by a column width, so both dialects agree: a
+      // Mongoose validator throws on overflow and Postgres errors 22001, and
+      // neither is what a failed delivery should turn into.
+      lastError: message.slice(0, 2_000),
+      now,
+    });
+    return { released, deadLettered };
+  };
+
+  return {
+    async enqueue(enqueueInput, tx) {
+      const now = new Date();
+      await store.enqueue(
+        {
+          eventId: enqueueInput.eventId,
+          kind: enqueueInput.kind,
+          payload: enqueueInput.payload,
+          availableAt: now,
+          expiresAt: new Date(
+            now.getTime() + MODERATION_OUTBOX_RETENTION_SECONDS * 1_000,
+          ),
+          now,
+        },
+        tx,
+      );
+      return enqueueInput.eventId;
+    },
+
+    claim,
+    complete,
+    renew,
+    fail,
+
+    async statusOf(eventId) {
+      return await store.statusOf(eventId);
+    },
+
+    async dispatch(options) {
+      const leaseOwner = options.leaseOwner ?? `moderation:${process.pid}:${randomUUID()}`;
+      const batchSize = Math.min(
+        Math.max(1, options.batchSize ?? DEFAULT_BATCH_SIZE),
+        MAX_BATCH_SIZE,
+      );
+      const leaseMs = Math.max(1_000, options.leaseMs ?? DEFAULT_LEASE_MS);
+      let processed = 0;
+      let failed = 0;
+      let deadLettered = 0;
+
+      for (let index = 0; index < batchSize; index += 1) {
+        // Shutdown stops claiming new work but lets the event already in flight
+        // reach a durable state.
+        if (options.signal?.aborted) break;
+
+        const event = await claim({ leaseOwner, leaseMs });
+        if (!event) break;
+
+        const heartbeat = startLeaseHeartbeat({
+          eventId: event.id,
+          leaseOwner,
+          leaseMs,
+        });
+        let deliveryError: unknown;
+        try {
+          await options.handler(event);
+        } catch (error: unknown) {
+          deliveryError = error;
+        }
+
+        // No completion/failure transition may race an owner-checked renewal.
+        const heartbeatResult = await heartbeat.stop();
+        if (heartbeatResult.lost) {
+          failed += 1;
+          logger.warn('[ModerationOutbox] event lease lost during delivery', {
+            eventId: event.id,
+            kind: event.kind,
+            attempts: event.attempts,
+            error:
+              heartbeatResult.error instanceof Error
+                ? heartbeatResult.error.message
+                : heartbeatResult.error
+                  ? String(heartbeatResult.error)
+                  : 'owner or lease expiry changed',
+          });
+          continue;
+        }
+
+        if (deliveryError) {
+          failed += 1;
+          const outcome = await fail(event, leaseOwner, deliveryError);
+          const context = {
+            eventId: event.id,
+            kind: event.kind,
+            attempts: event.attempts,
+            error:
+              deliveryError instanceof Error
+                ? deliveryError.message
+                : String(deliveryError),
+          };
+          // A dead letter is moderation work that will not happen without a
+          // human, so it must not be discoverable only by reading a warn-level
+          // log line.
+          if (outcome.deadLettered) {
+            deadLettered += 1;
+            logger.error('[ModerationOutbox] event dead-lettered', context);
+          } else {
+            logger.warn('[ModerationOutbox] event delivery failed, will retry', context);
+          }
+          if (!outcome.released) {
+            logger.warn('[ModerationOutbox] lease lost before failure release', {
+              eventId: event.id,
+              kind: event.kind,
+            });
+          }
+          continue;
+        }
+
+        const completed = await complete(event.id, leaseOwner);
+        if (!completed) {
+          failed += 1;
+          logger.warn('[ModerationOutbox] lease lost before completion', {
+            eventId: event.id,
+            kind: event.kind,
+            attempts: event.attempts,
+          });
+          continue;
+        }
+        processed += 1;
+      }
+
+      return { processed, failed, deadLettered };
+    },
+  };
+}

package/src/outbox/postgres/index.ts

@@ -0,0 +1,59 @@
+/**
+ * `@crowdsource.you/core/outbox/postgres` — the PostgreSQL half.
+ *
+ * An adopting application chooses its storage by which subpath it imports, and
+ * gets the same moderation pipeline either way. Everything drizzle-shaped lives
+ * behind this entry: the three tables this package owns, the columns to spread
+ * into your own report table, the two registry fragments to merge into your own
+ * gates, and the store the integration is wired with.
+ *
+ * ```ts
+ * import { createModerationIntegration } from '@crowdsource.you/core/outbox';
+ * import {
+ *   moderationTables,
+ *   moderationReportColumns,
+ *   moderationReportTableExtras,
+ *   postgresModerationStore,
+ * } from '@crowdsource.you/core/outbox/postgres';
+ * ```
+ *
+ * `drizzle-orm`, `postgres` and `@oxy.so/db` are OPTIONAL peers, which is what this
+ * split buys: a deployment on Mongo never installs them, and a bundler never has
+ * to resolve them. Importing this subpath without them fails at the import, by
+ * name — which is the failure you want, rather than a driver quietly missing at
+ * the first write.
+ *
+ * **This package ships NO migrations.** It ships table DEFINITIONS; your own
+ * `drizzle-kit generate` produces the SQL, in your journal. Two journals against
+ * one `drizzle.__drizzle_migrations` table interleave, and the loser is skipped
+ * silently with exit 0 — so a migrations folder in a library is a way to lose your
+ * migration rather than a convenience.
+ *
+ * The MODERATION_*_RETENTION_SECONDS windows are NOT here. They are policy both
+ * backends share, so they stay on the root entry — and `moderationExpirySweepTargets`
+ * is what turns them into deletions, because Postgres has no TTL index.
+ */
+
+export { postgresModerationStore } from './store/index.js';
+export { postgresTransactionRunner } from './store/transaction.js';
+export type { ModerationPgHandle } from './store/transaction.js';
+
+export { moderationTables } from './tables.js';
+export type { ModerationTables } from './tables.js';
+
+export {
+  moderationReportColumns,
+  moderationReportTableExtras,
+} from './reportColumns.js';
+export type {
+  ModerationReportBuiltColumns,
+  ModerationReportColumnName,
+  ModerationReportColumnOptions,
+  ModerationReportColumns,
+  ModerationReportTable,
+} from './reportColumns.js';
+
+export {
+  moderationExpirySweepTargets,
+  moderationIdColumnsWithoutForeignKey,
+} from './registries.js';

package/src/outbox/postgres/registries.ts

@@ -0,0 +1,177 @@
+import { getTableName } from 'drizzle-orm';
+import type { Column } from 'drizzle-orm';
+import type { PgTable } from 'drizzle-orm/pg-core';
+import { sqlColumnName } from '@oxy.so/db';
+import type { ExpirySweepTarget } from '@oxy.so/db/expiry';
+import {
+  MODERATION_EVENT_RETENTION_SECONDS,
+  MODERATION_OUTBOX_RETENTION_SECONDS,
+} from '../retention.js';
+import type { ModerationReportTable } from './reportColumns.js';
+import type { ModerationTables } from './tables.js';
+
+/**
+ * The two registry FRAGMENTS an adopter merges into its own gates.
+ *
+ * `@oxy.so/db` holds the mechanisms — the expiry sweep, the id-column
+ * classification gate — and the REGISTRIES belong to the consumer, because they
+ * name the consumer's own tables. This package's three tables are in the
+ * adopter's database, so the entries for them are the adopter's to declare and
+ * this package's to KNOW: it is the only place that can say why
+ * `crowdsource_case_id` will never carry a foreign key.
+ *
+ * So each of these returns a fragment to spread, never a whole registry:
+ *
+ * ```ts
+ * const targets = [...myOwnTargets, ...moderationExpirySweepTargets(moderation)];
+ * const violations = findIdColumnViolations({
+ *   tables: [...myTables, moderation.outbox, moderation.events, moderation.enforcements],
+ *   deferred: myDeferred,
+ *   withoutForeignKey: [
+ *     ...myOwnUnclassified,
+ *     ...moderationIdColumnsWithoutForeignKey({ tables: moderation, reportTable: reports }),
+ *   ],
+ *   minimumTables: …,
+ * });
+ * ```
+ *
+ * Shipping them is what stops the first adopter writing these reasons by
+ * guessing — and every one of the eight id columns below would otherwise fail
+ * that adopter's inherited gate as `unclassified_id_column` on the day it adopts,
+ * with nothing to tell it whether that is a missing constraint or a decision.
+ */
+
+/** `<table>.<column>`, in the SQL names the gate compares against. */
+function describe(table: PgTable, column: Column): string {
+  return `${getTableName(table)}.${sqlColumnName(column)}`;
+}
+
+/**
+ * The two tables that carried a Mongo TTL index, as sweep targets.
+ *
+ * **A TTL index is a behaviour of the SOURCE that does not survive the port.**
+ * Mongo reaps; Postgres does not. Both tables here were declared
+ * `expireAfterSeconds: 0` on an `expiresAt` the WRITER computes, so
+ * `retentionSeconds` is 0: the column already IS the deadline, and the retention
+ * window lives in `src/retention.ts` where both backends read it.
+ *
+ * Without an entry, a table grows forever — no error, no failing test, no
+ * symptom of any kind until disk. Nothing about it is visible in a diff, because
+ * the thing doing the work was never in the consumer's code to be missed.
+ *
+ * ## What sweeping these two costs, stated because a registry entry with no such
+ * note reads as "unconditionally safe"
+ *
+ * The outbox holds unprocessed WORK. A stalled dispatcher plus this sweep
+ * discards moderation work that was never delivered — which is why the retention
+ * window is ninety days rather than hours, and why a `dead_letter` row is
+ * evidence somebody still has to look at rather than a row to reap quickly.
+ * Operational alerts must fire long before this deadline; the sweep is the
+ * backstop for a table nobody drained, not a queue policy.
+ *
+ * The event log holds the audit trail of what a third party told this deployment
+ * to do, and the dedupe claim. CrowdSource's retry schedule ends at 24 hours, so
+ * deleting a row after ninety days cannot resurrect a duplicate delivery; what it
+ * does cost is the answer to "did CrowdSource tell us about this case, and when",
+ * which is the first question asked when a report looks stuck.
+ *
+ * Neither read path depends on a swept row already being gone: the dispatcher
+ * claims by `available_at` and the receiver claims by primary key, so an
+ * unswept row is stale at worst and never unsafe.
+ */
+export function moderationExpirySweepTargets(
+  tables: ModerationTables,
+): readonly ExpirySweepTarget[] {
+  return [
+    {
+      table: tables.outbox,
+      column: tables.outbox.expiresAt,
+      retentionSeconds: 0,
+      reason:
+        'Deletes a delivered or dead-lettered moderation outbox event past its ' +
+        `${MODERATION_OUTBOX_RETENTION_SECONDS}s retention. A row still pending is ` +
+        'moderation work that was never delivered — alert long before this.',
+    },
+    {
+      table: tables.events,
+      column: tables.events.expiresAt,
+      retentionSeconds: 0,
+      reason:
+        'Deletes the audit row and dedupe claim for an inbound decision past its ' +
+        `${MODERATION_EVENT_RETENTION_SECONDS}s retention, long after CrowdSource's ` +
+        '24-hour retry schedule can redeliver it.',
+    },
+  ];
+}
+
+/**
+ * Every id-shaped column in this package's tables that will never carry a
+ * foreign key, with the reason.
+ *
+ * Eight entries, and the count is worth stating because the obvious count is
+ * six: `findIdColumnViolations` exempts a column only when `column.primary` is
+ * set, and a composite primary key declared in a table's extra config does NOT
+ * set it on its members — so `moderation_enforcements.decision_id` is scanned
+ * despite being part of the key.
+ *
+ * They fall into two kinds, and neither can be constrained:
+ *
+ * - **Ids in CrowdSource's database.** A decision, a case, a report as CrowdSource
+ *   knows it. There is no local table to point at; the row lives in another
+ *   service's store, and this deployment holds a copy of its identifier.
+ * - **The adopter's own opaque noun ids.** `subject_id` and `reported_id` name a
+ *   post, a listing, a message — whichever table the adopter's subject provider
+ *   resolves. The package cannot know which, and a single column cannot reference
+ *   several tables, which is precisely why they are stored as opaque text.
+ *
+ * The report table is passed in rather than assumed: the entries embed the
+ * adopter's own table name, and a ledger entry naming a table that is not in the
+ * gate's `tables` list is reported as `stale_ledger_entry`.
+ */
+export function moderationIdColumnsWithoutForeignKey(input: {
+  tables: ModerationTables;
+  reportTable: ModerationReportTable;
+}): readonly { column: string; reason: string }[] {
+  const { tables, reportTable } = input;
+
+  return [
+    {
+      column: describe(tables.events, tables.events.caseId),
+      reason: 'Names a case in CrowdSource’s database, not the adopter’s.',
+    },
+    {
+      column: describe(tables.enforcements, tables.enforcements.decisionId),
+      reason:
+        'Names a decision in CrowdSource’s database. Part of the composite ' +
+        'primary key, which does not set `column.primary` on its members.',
+    },
+    {
+      column: describe(tables.enforcements, tables.enforcements.caseId),
+      reason: 'Names a case in CrowdSource’s database.',
+    },
+    {
+      column: describe(tables.enforcements, tables.enforcements.subjectId),
+      reason:
+        'The adopter’s own opaque noun id; the package cannot know which table ' +
+        'it points at, and one column cannot reference several.',
+    },
+    {
+      column: describe(reportTable, reportTable.reportedId),
+      reason:
+        'The adopter’s own opaque noun id — same reason as ' +
+        '`moderation_enforcements.subject_id`.',
+    },
+    {
+      column: describe(reportTable, reportTable.crowdSourceReportId),
+      reason: 'A report id in CrowdSource’s database.',
+    },
+    {
+      column: describe(reportTable, reportTable.crowdSourceCaseId),
+      reason: 'A case id in CrowdSource’s database.',
+    },
+    {
+      column: describe(reportTable, reportTable.decisionId),
+      reason: 'A decision id in CrowdSource’s database.',
+    },
+  ];
+}