@kairos-es/store-postgres 0.0.0

package/src/internal/ddl.ts

@@ -0,0 +1,599 @@
+/**
+ * Internal DDL and object-naming for the Postgres `DcbEventStore` backend.
+ *
+ * This module is the single source of truth for every object name a store owns
+ * and for the plpgsql function bodies. It is deliberately factored apart from
+ * the public engine so that:
+ *
+ * 1. names are derived ONCE, from `{ schema, tablePrefix }`, and reused by both
+ *    `ensureSchema` (DDL) and the runtime (`append`/`read`/`subscribe`), so the
+ *    migration and the queries can never disagree about what a table is called;
+ * 2. the append-function body is assembled from COMPOSABLE parts — in
+ *    particular the `LOCK TABLE … IN EXCLUSIVE MODE` clause is an omittable
+ *    fragment — so a test can `CREATE OR REPLACE` a deliberately-LOCKLESS twin of
+ *    the append function to prove the shared contract suite actually detects a
+ *    non-serialising store. The production Layer never exposes a lockless option;
+ *    the seam lives here, in an internal module, reachable only from the test
+ *    graph.
+ *
+ * WHY names are never string-concatenated: every identifier flows through
+ * `sql(identifier)`, which quotes and dot-splits safely, so a hostile or merely
+ * awkward `schema`/`tablePrefix` cannot inject SQL or collide with a reserved
+ * word. The plpgsql *bodies*, which must embed the resolved names as literal
+ * text inside a `CREATE FUNCTION … $$ … $$` string, use the SAME quoting via a
+ * small `quoteQualified` helper so the body text matches what `sql(identifier)`
+ * would emit; VALUES stay bound parameters (`sql.unsafe` with `params`) and are
+ * never interpolated.
+ */
+import type { SqlClient, Statement } from '@effect/sql'
+import {
+  allowedTypesPredicate,
+  eventRecordsetColumns,
+  qualifiedRows,
+  taggedMatchChain,
+} from './matchSql'
+
+/**
+ * A store is one physical `{ schema, tablePrefix }` pair. Every object it owns
+ * (both tables, both indexes, both functions, and the NOTIFY channel) is derived
+ * from this pair, so one prefix is one completely isolated store: its own
+ * bigserial sequence, its own exclusive-lock scope, its own wake channel.
+ */
+export interface ResolvedNames {
+  readonly schema: string
+  readonly tablePrefix: string
+  /** `<schema>.<prefix>` — the main event table. */
+  readonly mainTable: string
+  /** `<schema>.<prefix>_tags` — the junction tag table. */
+  readonly tagTable: string
+  /** `<prefix>_idx_id_type` — the covering unique index on the main table. */
+  readonly mainIndex: string
+  /** `<prefix>_idx_tag_main_id` — the composite B-tree on the tag table. */
+  readonly tagIndex: string
+  /** `<schema>.<prefix>_append` — the conditional (lock → check → insert → notify) function. */
+  readonly appendFn: string
+  /**
+   * `<schema>.<prefix>_append_unconditional` — the check-free insert twin. It takes
+   * the SAME exclusive lock as the conditional one, which is what discharges the
+   * subscribe machine's ascending-commit-order precondition on this engine;
+   * `unconditionalAppendBody` owns why a lock-free twin would not.
+   */
+  readonly appendUnconditionalFn: string
+  /**
+   * The `LISTEN`/`NOTIFY` channel: the fully-qualified events-table name with
+   * dots replaced by `_`. A channel is a single unqualified identifier, so the
+   * schema is folded into the name to keep two stores in different schemas but
+   * with the same prefix from sharing a channel.
+   */
+  readonly channel: string
+}
+
+/** Default schema when the config omits one. */
+export const DEFAULT_SCHEMA = 'public'
+/** Default table prefix when the config omits one. */
+export const DEFAULT_TABLE_PREFIX = 'dcb_events'
+
+/**
+ * Postgres truncates any identifier to 63 bytes (`NAMEDATALEN - 1`) with only a
+ * notice. Two configs whose derived names share a 63-byte prefix would then
+ * collide silently: `CREATE INDEX IF NOT EXISTS` sees a name-match and SKIPS
+ * creating the second store's index (an invisible performance cliff), and two
+ * NOTIFY channels truncate into one (cross-store wakes, defeating cohabitation).
+ */
+const MAX_IDENTIFIER_BYTES = 63
+
+/** UTF-8 byte length (identifiers are bytes, not chars, to Postgres). */
+const utf8ByteLength = (value: string): number =>
+  new TextEncoder().encode(value).length
+
+/**
+ * The single-atom identifiers Postgres actually materialises for a config —
+ * every table/index/function base name plus the NOTIFY channel. `schema.prefix`
+ * qualified names are two atoms to Postgres (`schema` and the table name), so
+ * each atom is measured separately, not the dotted whole.
+ */
+const derivedAtoms = (config: {
+  readonly schema?: string
+  readonly tablePrefix?: string
+}): ReadonlyArray<readonly [string, string]> => {
+  const schema = config.schema ?? DEFAULT_SCHEMA
+  const tablePrefix = config.tablePrefix ?? DEFAULT_TABLE_PREFIX
+  return [
+    ['schema', schema],
+    ['events table', tablePrefix],
+    ['tag table', `${tablePrefix}_tags`],
+    ['main index', `${tablePrefix}_idx_id_type`],
+    ['tag index', `${tablePrefix}_idx_tag_main_id`],
+    ['append function', `${tablePrefix}_append`],
+    ['unconditional append function', `${tablePrefix}_append_unconditional`],
+    ['NOTIFY channel', `${schema}_${tablePrefix}`.replace(/\./g, '_')],
+  ]
+}
+
+/**
+ * The first derived identifier that exceeds 63 bytes, as a human-readable
+ * message, or `undefined` when every name fits. Shared by `resolveNames` (which
+ * throws) and the `PostgresStoreConfig` schema filter (which fails validation),
+ * so the byte bound is enforced identically at both the name-derivation and the
+ * config-decode boundary.
+ */
+export const oversizedIdentifier = (config: {
+  readonly schema?: string
+  readonly tablePrefix?: string
+}): string | undefined => {
+  for (const [label, atom] of derivedAtoms(config)) {
+    const bytes = utf8ByteLength(atom)
+    if (bytes > MAX_IDENTIFIER_BYTES) {
+      return `the ${label} identifier "${atom}" is ${bytes} bytes, over Postgres's ${MAX_IDENTIFIER_BYTES}-byte limit; it would be silently truncated, risking a cross-store index-skip or NOTIFY-channel collision`
+    }
+  }
+  return undefined
+}
+
+/**
+ * Derive every owned object name from `{ schema, tablePrefix }`. The index and
+ * function *base* names are unqualified prefixes (`<prefix>_…`) because an index
+ * name is scoped to its table's schema and a function is created in `<schema>`;
+ * the tables and functions carry the schema explicitly so `sql(identifier)`
+ * dot-splits them.
+ *
+ * Throws at construction if any derived identifier would be silently truncated
+ * (see `oversizedIdentifier` / `MAX_IDENTIFIER_BYTES`) — a loud failure at the
+ * single choke point beats an invisible index-skip or channel collision later.
+ */
+export const resolveNames = (config: {
+  readonly schema?: string
+  readonly tablePrefix?: string
+}): ResolvedNames => {
+  const problem = oversizedIdentifier(config)
+  if (problem !== undefined) {
+    throw new Error(`resolveNames: ${problem}`)
+  }
+  const schema = config.schema ?? DEFAULT_SCHEMA
+  const tablePrefix = config.tablePrefix ?? DEFAULT_TABLE_PREFIX
+  return {
+    schema,
+    tablePrefix,
+    mainTable: `${schema}.${tablePrefix}`,
+    tagTable: `${schema}.${tablePrefix}_tags`,
+    mainIndex: `${tablePrefix}_idx_id_type`,
+    tagIndex: `${tablePrefix}_idx_tag_main_id`,
+    appendFn: `${schema}.${tablePrefix}_append`,
+    appendUnconditionalFn: `${schema}.${tablePrefix}_append_unconditional`,
+    channel: `${schema}_${tablePrefix}`.replace(/\./g, '_'),
+  }
+}
+
+/**
+ * Quote a possibly-qualified identifier for embedding inside a plpgsql body as
+ * literal text. Splits on `.` and double-quotes each atom, mirroring what
+ * `sql(identifier)` emits, so the body's table references and the runtime's
+ * `sql(identifier)` references resolve to exactly the same object. Any embedded
+ * `"` is doubled per SQL identifier-quoting rules.
+ */
+export const quoteQualified = (name: string): string =>
+  name
+    .split('.')
+    .map((atom) => `"${atom.replace(/"/g, '""')}"`)
+    .join('.')
+
+/**
+ * A quoted single-atom identifier (no dot-splitting) — used where a bare name is
+ * required, e.g. index/schema names.
+ */
+const quoteAtom = (name: string): string => `"${name.replace(/"/g, '""')}"`
+
+/**
+ * A single-quoted SQL string LITERAL (not an identifier). Used for the
+ * `pg_notify(channel, payload)` channel argument, which is a `text` VALUE, not
+ * an identifier — double-quoting it there would (wrongly) parse as a column
+ * reference. Embedded single quotes are doubled per SQL string-literal rules.
+ */
+const quoteLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`
+
+/**
+ * The autovacuum storage parameters, ported verbatim from upstream
+ * `postgres_tt.py`: the event log is append-heavy and effectively immutable, so
+ * vacuum is tuned to run rarely (huge thresholds) while analyze stays keen
+ * (small thresholds) to keep the planner's row estimates fresh for the tag-first
+ * CTE. Applied identically to both tables.
+ */
+const AUTOVACUUM_WITH =
+  'autovacuum_enabled = true, ' +
+  'autovacuum_vacuum_threshold = 100000000, ' +
+  'autovacuum_vacuum_scale_factor = 0.5, ' +
+  'autovacuum_analyze_threshold = 1000, ' +
+  'autovacuum_analyze_scale_factor = 0.01'
+
+/**
+ * The `LOCK TABLE <main> IN EXCLUSIVE MODE;` clause — the serialisation point of
+ * the whole engine. `EXCLUSIVE` blocks other writers (and other conditional
+ * appends) but lets readers proceed, so the check-then-insert of one append
+ * cannot interleave with another's: exactly-one-wins holds by construction, with
+ * no dependence on isolation level or unique constraints.
+ *
+ * It is a SEPARATE, OMITTABLE fragment purely so the test-only lockless twin can
+ * drop it. Production always includes it.
+ */
+const lockClause = (names: ResolvedNames): string =>
+  `LOCK TABLE ${quoteQualified(names.mainTable)} IN EXCLUSIVE MODE;`
+
+/**
+ * The named body-fragment seams, replacing positional boolean flags — the old
+ * `unconditionalAppendBody(names, true, false)` was boolean-blind. Both knobs
+ * default to the production configuration (locked + notifying); a test twin
+ * overrides one field BY NAME. This is the union of both knobs; each body `Pick`s
+ * only the ones it actually varies — the conditional body always notifies, so it
+ * never took `notify`.
+ *
+ * - `lock` — include the `LOCK TABLE … IN EXCLUSIVE MODE` clause (default true).
+ *   BOTH twins vary it: the test-only lockless twins pass `false` to prove the
+ *   lock is load-bearing (the conditional path's lockless meta-test and the
+ *   unconditional commit-order repro).
+ * - `notify` — include the `pg_notify` wake (default true). ONLY the unconditional
+ *   twin varies it: the poll-only delivery test passes `false` to prove the
+ *   periodic poll, not NOTIFY, is the delivery guarantee.
+ */
+export interface AppendBodyOptions {
+  readonly lock?: boolean
+  readonly notify?: boolean
+}
+
+/**
+ * The shared insert → tag fan-out → NOTIFY body, emitting into a local
+ * `new_head bigint` and then `RETURN QUERY SELECT new_head`. Written as explicit
+ * sequential statements (not one mega-CTE) so control flow is obvious and the
+ * `pg_notify` fires unconditionally after a successful insert rather than
+ * depending on a data-modifying CTE being referenced.
+ *
+ * A single `INSERT … SELECT … FROM jsonb_to_recordset(…) ORDER BY ordinality`
+ * preserves batch order, and `RETURNING id, tags` is captured into a temp
+ * result set so the tag fan-out and the head can both read it. `data` arrives as
+ * a base64 text field and is `decode(…, 'base64')`-restored to `bytea`.
+ */
+const insertFanoutNotify = (
+  names: ResolvedNames,
+  options: Pick<AppendBodyOptions, 'notify'> = {},
+): string => {
+  const main = quoteQualified(names.mainTable)
+  const tag = quoteQualified(names.tagTable)
+  const channel = quoteLiteral(names.channel)
+  // `notify` is an OMITTABLE fragment (like the lock): production always
+  // notifies; the poll-only delivery test `CREATE OR REPLACE`s a NOTIFY-suppressed
+  // UNCONDITIONAL twin over its own prefix to prove the periodic poll — not
+  // NOTIFY — is the delivery guarantee. The conditional body never suppresses it.
+  const notify =
+    (options.notify ?? true)
+      ? `
+  -- Wake subscribers only if we actually inserted rows. NOTIFY is a payload-less
+  -- signal in spirit; a constant '1' payload is sent purely because the built-in
+  -- ref-counted listen client drops empty-payload notifications — the TS side
+  -- treats every notification as an opaque wake and ignores the payload.
+  IF new_head IS NOT NULL THEN
+    PERFORM pg_notify(${channel}, '1');
+  END IF;`
+      : ''
+  return `  WITH ne AS (
+    SELECT type, data, tags, uuid, occurred_at, ordinality
+    FROM ROWS FROM(
+      jsonb_to_recordset(new_events) AS (${eventRecordsetColumns})
+    ) WITH ORDINALITY
+  ),
+  inserted AS (
+    INSERT INTO ${main} (type, data, tags, uuid, occurred_at)
+    SELECT ne.type, decode(ne.data, 'base64'), ne.tags, ne.uuid,
+           ne.occurred_at
+    FROM ne
+    ORDER BY ne.ordinality
+    RETURNING id, tags
+  ),
+  fanned AS (
+    INSERT INTO ${tag} (tag, main_id)
+    SELECT unnest(inserted.tags), inserted.id
+    FROM inserted
+    RETURNING main_id
+  )
+  -- fanned is a DATA-MODIFYING CTE: Postgres runs it exactly once to completion
+  -- whether or not the primary query reads its output, so the tag fan-out
+  -- happens even though nothing selects from it — and so a count(*) over it
+  -- would add nothing but work.
+  SELECT MAX(inserted.id)
+  INTO new_head
+  FROM inserted;
+${notify}`
+}
+
+/**
+ * Build the body of the CONDITIONAL append function (lock → check → insert →
+ * notify), ported from upstream `dcb_conditional_append_tt` with the
+ * JSON-transport divergence (ADR-0002).
+ *
+ * Module-private: the ONLY caller is `appendFunctionStatement`, which owns the
+ * full `CREATE OR REPLACE` wrapper. Keeping the body builders unexported means a
+ * caller cannot re-introduce a hand-rolled wrapper (the drift this consolidation
+ * removes) — the wrapper is single-sourced.
+ */
+const conditionalAppendBody = (
+  names: ResolvedNames,
+  options: Pick<AppendBodyOptions, 'lock'> = {},
+): string => {
+  const main = quoteQualified(names.mainTable)
+  const tag = quoteQualified(names.tagTable)
+  const lock = (options.lock ?? true) ? `  ${lockClause(names)}\n` : ''
+  // The conditional body always notifies — `insertFanoutNotify` defaults to it,
+  // and there is deliberately no `notify` seam here: only the unconditional twin
+  // is ever notify-suppressed, by the poll-only delivery test.
+  // The tagged branch shares its match SQL with the TS read path via one builder
+  // (`internal/matchSql.ts`) — plpgsql parameter tokens here (`query_items`,
+  // `COALESCE(after_id,0)`), bound `$n` on the read side. The wildcard/tagless
+  // branches are conflict-only (the read dispatches those shapes in TS) and reuse
+  // `qi` + the shared allowed-types predicate.
+  //
+  // No compiler reaches any of this. Core's `ServableQueryShape` appears nowhere in
+  // the body text, so a member added to that union is invisible here, where
+  // `internal/readPlan.ts`'s exhaustive `switch` stops compiling — and what stands
+  // in for the compiler is the generality the body comment below claims. Worth
+  // naming is why that claim holds: the three contributions partition a query by
+  // its ITEMS — none at all, an item carrying no tags, an item carrying tags —
+  // which between them cover every `Query` value the grammar can express, so a new
+  // SHAPE changes which SQL the read compiles without changing what this body has
+  // to match. The exposure is the GRAMMAR itself: a new `QueryItem` field, or a new
+  // meaning for an existing one, is something this body ignores rather than fails
+  // on, and no `switch` over the shape union would have caught that either.
+  const after = 'COALESCE(after_id, 0)'
+  return `
+DECLARE
+  conflict_exists boolean;
+  new_head bigint;
+BEGIN
+  -- lock_timeout is set per-call by the caller via set_config(..., is_local),
+  -- so the same function honours the configured timeout without recompilation.
+${lock}  -- Conflict check, reduced to EXISTS/LIMIT 1: does ANY event after
+  -- COALESCE(after_id, 0) satisfy the guard query (items OR'd; within an item,
+  -- types OR-filter AND tags AND-superset)? Three contributions, OR'd:
+  --   * the WILDCARD (empty query_items) - any event after after_id conflicts;
+  --   * TAGLESS items (empty tags, maybe types) - a type-only / match-all item,
+  --     matched by type = ANY(types) (or any type when types is empty);
+  --   * TAGGED items - the shared tag-first match chain, identical to the read.
+  -- The servable grammar (assertServableQuery) guarantees a tagless item only
+  -- appears as the whole single-item query or the wildcard, but the check is
+  -- written generically so plain-data assembly cannot surprise it.
+  WITH ${taggedMatchChain({ queryItemsExpr: 'query_items', afterExpr: after, main, tag })},
+  -- Wildcard: no items at all means "match everything".
+  wildcard_conflict AS (
+    SELECT 1
+    FROM ${main} m
+    WHERE NOT EXISTS (SELECT 1 FROM qi)
+      AND m.id > ${after}
+    LIMIT 1
+  ),
+  -- Tagless items: match by type (or any type when the item has no types).
+  tagless_conflict AS (
+    SELECT 1
+    FROM qi
+    JOIN ${main} m ON m.id > ${after}
+    WHERE (qi.tags IS NULL OR array_length(qi.tags, 1) IS NULL)
+      AND ${allowedTypesPredicate('qi.types')}
+    LIMIT 1
+  ),
+  -- Tagged items: distinct-tag-count AND-superset matching (the shared source).
+  tagged_conflict AS (
+    SELECT 1
+    ${qualifiedRows({ main, afterExpr: after })}
+    LIMIT 1
+  )
+  SELECT
+    EXISTS (SELECT 1 FROM wildcard_conflict)
+    OR EXISTS (SELECT 1 FROM tagless_conflict)
+    OR EXISTS (SELECT 1 FROM tagged_conflict)
+  INTO conflict_exists;
+
+  IF NOT conflict_exists THEN
+    -- No conflict: insert the batch, fan tags out, wake subscribers, return head.
+${insertFanoutNotify(names)}
+    RETURN QUERY SELECT new_head WHERE new_head IS NOT NULL;
+  END IF;
+  -- conflict_exists = true falls through, returning zero rows = a conflict.
+  RETURN;
+END;
+`
+}
+
+/**
+ * Build the body of the UNCONDITIONAL append function: no conflict check, but the
+ * SAME `LOCK TABLE … IN EXCLUSIVE MODE` as the conditional twin.
+ *
+ * WHY the lock (a deliberate divergence from upstream's lock-free twin, ADR-0002):
+ * `bigserial` ids are allocated NON-transactionally, so two lock-free
+ * unconditional writers can allocate ids 5 and 6 and COMMIT them in reverse
+ * order. Commit-order then diverges from id-order, and two invariants the rest of
+ * the engine leans on silently break:
+ *
+ *   1. a `subscribe` poll that lands between the two commits sees id 6, advances
+ *      its strict `> cursor` past 6, and PERMANENTLY skips id 5 when it commits
+ *      milliseconds later — silent event loss on the live tail;
+ *   2. a no-limit read taken while the lower id is in flight returns `head` PAST
+ *      an id no snapshot can yet see, so a decision model appending under
+ *      `{ after: head }` never examines that id as a conflict — an escaped guard.
+ *
+ * The check-free FAST PATH is preserved (no conflict CTE); only the lock is
+ * added. It restores commit-order = id-order for EVERY append, making ADR-0002's
+ * "every append participates in the same mechanism by construction" true in the
+ * strong sense. The cost — unconditional writers serialise with all other writers
+ * — is exactly the write ceiling ADR-0002 already accepts and marks benchmarkable.
+ *
+ * `options.lock` is the same OMITTABLE-fragment seam as `conditionalAppendBody`:
+ * production defaults to `true`; the commit-order repro passes `{ lock: false }`
+ * over its own prefix to prove the subscribe-skip / head-overtake scenario
+ * genuinely reproduces the bug when the lock is absent (non-vacuity), exactly as
+ * the lockless meta-test does for the conditional path.
+ *
+ * `options.notify` is the analogous seam for the poll-only delivery test — a
+ * NOTIFY-suppressed twin (`{ notify: false }`) proves the periodic poll (not
+ * NOTIFY) is the delivery guarantee. Production always notifies.
+ *
+ * Module-private, like `conditionalAppendBody`: reached only via
+ * `appendFunctionStatement`.
+ */
+const unconditionalAppendBody = (
+  names: ResolvedNames,
+  options: AppendBodyOptions = {},
+): string => {
+  const lock = (options.lock ?? true) ? `  ${lockClause(names)}\n` : ''
+  // Pass the `notify` option straight through — no unwrap-then-rewrap;
+  // `insertFanoutNotify` owns the default.
+  return `
+DECLARE
+  new_head bigint;
+BEGIN
+${lock}${insertFanoutNotify(names, options)}
+  RETURN QUERY SELECT new_head WHERE new_head IS NOT NULL;
+END;
+`
+}
+
+/**
+ * Which append function to (re)create, plus the body-fragment seams. `kind`
+ * selects the conditional (guarded) or unconditional (check-free) twin — fixing
+ * the function NAME and SIGNATURE — and the seams default to the production
+ * configuration.
+ *
+ * A DISCRIMINATED union, not `extends AppendBodyOptions`, so the seams a `kind`
+ * cannot vary are un-expressible: the conditional twin exposes only `lock` (it
+ * always notifies), so `{ kind: 'conditional', notify: false }` is a compile error
+ * rather than a silently-ignored dead option.
+ */
+export type AppendFunctionOptions =
+  | ({ readonly kind: 'conditional' } & Pick<AppendBodyOptions, 'lock'>)
+  | ({ readonly kind: 'unconditional' } & AppendBodyOptions)
+
+/**
+ * Build ONE complete `CREATE OR REPLACE FUNCTION … RETURNS SETOF bigint LANGUAGE
+ * plpgsql AS $kairos$…$kairos$` statement for an append function. This is the
+ * single source of the wrapper — its qualified name, argument SIGNATURE, and
+ * `$kairos$`-delimited body — consumed by `ddlStatements` (production, both twins)
+ * AND by the test installers that `CREATE OR REPLACE` a lockless / notify-
+ * suppressed twin over their own prefix.
+ *
+ * WHY one builder: `ddlStatements` plus three test twins previously hand-restated
+ * this wrapper, several with string-INTERPOLATED identifiers this module's own
+ * doctrine forbids (`"${schema}"."${prefix}_append"` rather than
+ * `quoteQualified(names.appendFn)`). A drift in the SIGNATURE across those copies
+ * is a silent footgun: `CREATE OR REPLACE` with a changed argument list creates a
+ * new OVERLOAD instead of replacing, leaving the original production function live
+ * under test. Single-sourcing name + signature makes a twin unable to diverge —
+ * a twin `CREATE OR REPLACE`s exactly the function `ddlStatements` created.
+ */
+export const appendFunctionStatement = (
+  names: ResolvedNames,
+  options: AppendFunctionOptions,
+): string => {
+  // Only the qualified name, the argument SIGNATURE, and the body differ between
+  // the twins; the `CREATE OR REPLACE … RETURNS SETOF bigint … $kairos$…$kairos$`
+  // wrapper is one template, emitted once rather than restated per arm of the
+  // ternary below.
+  const [qualifiedName, argList, body]: readonly [string, string, string] =
+    options.kind === 'conditional'
+      ? [
+          names.appendFn,
+          'query_items jsonb, after_id bigint, new_events jsonb',
+          conditionalAppendBody(names, options),
+        ]
+      : [
+          names.appendUnconditionalFn,
+          'new_events jsonb',
+          unconditionalAppendBody(names, options),
+        ]
+  return `CREATE OR REPLACE FUNCTION ${quoteQualified(qualifiedName)}(
+       ${argList}
+     ) RETURNS SETOF bigint
+     LANGUAGE plpgsql AS $kairos$${body}$kairos$;`
+}
+
+/**
+ * The full ordered list of idempotent DDL statements that create/refresh a
+ * store's objects. Each entry is a `sql.unsafe` statement string; VALUES are not
+ * involved (pure DDL), and every identifier is pre-quoted via `quoteQualified`
+ * to match the runtime's `sql(identifier)` resolution.
+ *
+ * Ordering matters: tables before their indexes and before the tag table's FK,
+ * functions last (they reference the tables). Everything is `IF NOT EXISTS` /
+ * `CREATE OR REPLACE`, so re-running is a no-op — the migration payload is safe
+ * to register in any migrator or to run directly.
+ */
+export const ddlStatements = (names: ResolvedNames): ReadonlyArray<string> => {
+  const main = quoteQualified(names.mainTable)
+  const tag = quoteQualified(names.tagTable)
+  const schema = quoteAtom(names.schema)
+  const mainIndex = quoteAtom(names.mainIndex)
+  const tagIndex = quoteAtom(names.tagIndex)
+
+  return [
+    // The schema may already exist (e.g. `public`); create it defensively so a
+    // custom schema does not require a separate provisioning step.
+    `CREATE SCHEMA IF NOT EXISTS ${schema};`,
+
+    // Main event table. `id bigserial` gives strictly-increasing (NOT gapless)
+    // positions — a rolled-back insert permanently consumes its id, which is
+    // fine: ordering is by id alone and the store is never made gapless.
+    // `data` is NULLABLE (a payload-less event is valid); `occurred_at` is
+    // informational domain time, never an ordering key.
+    `CREATE TABLE IF NOT EXISTS ${main} (
+       id bigserial,
+       type text NOT NULL,
+       data bytea,
+       tags text[] NOT NULL,
+       uuid text NOT NULL,
+       occurred_at timestamptz NOT NULL
+     ) WITH (${AUTOVACUUM_WITH});`,
+
+    // Covering unique index: uniqueness on id plus INCLUDE(type) so the read
+    // path's id→type lookups are index-only.
+    `CREATE UNIQUE INDEX IF NOT EXISTS ${mainIndex}
+       ON ${main} (id) INCLUDE (type);`,
+
+    // Junction tag table: one row per (tag, event) OCCURRENCE, under NO
+    // uniqueness constraint — the fan-out is a plain `unnest(tags)`, so an event
+    // whose own `tags` list repeats a tag lands TWO rows here. That is not a
+    // defect to close by constraining the table: a repeated tag is legal on an
+    // event and carries no information, so refusing it would break parity with
+    // the in-memory oracle over a physical-design decision the contract knows
+    // nothing about. The match side absorbs it instead, by counting DISTINCT tags
+    // per event — `internal/matchSql.ts` owns what that buys and what it obliges
+    // the requirement count to be.
+    //
+    // The `main_id … REFERENCES` FK ties a tag row to its event; it is a VERBATIM
+    // port of upstream `postgres_tt.py` (its junction DDL carries the same
+    // `main_id bigint REFERENCES {events_table} (id)`), not an addition —
+    // ADR-0002 adopts that design. Both inserts run in one
+    // statement/transaction so the referenced main row is always visible to the
+    // tag insert. Same autovacuum tuning as the main table.
+    `CREATE TABLE IF NOT EXISTS ${tag} (
+       tag text,
+       main_id bigint REFERENCES ${main} (id)
+     ) WITH (${AUTOVACUUM_WITH});`,
+
+    // Composite B-tree (tag, main_id): the tag-first CTE probes by tag then
+    // joins by main_id, so this index serves both the conflict check and reads.
+    `CREATE INDEX IF NOT EXISTS ${tagIndex}
+       ON ${tag} (tag, main_id);`,
+
+    // Conditional append (production): lock → check → insert → notify.
+    appendFunctionStatement(names, { kind: 'conditional' }),
+
+    // Unconditional twin: lock → insert → notify, no conflict check.
+    appendFunctionStatement(names, { kind: 'unconditional' }),
+  ]
+}
+
+/**
+ * Run the ordered DDL against the generic `SqlClient`. Kept here (not in the
+ * public `ensureSchema`) so the same builder feeds both the public migration
+ * payload and any internal test setup. Each statement is a separate `sql.unsafe`
+ * call so a driver that rejects multi-statement strings still works.
+ */
+export const runDdl = (
+  sql: SqlClient.SqlClient,
+  names: ResolvedNames,
+): ReadonlyArray<Statement.Statement<unknown>> =>
+  ddlStatements(names).map((statement) => sql.unsafe(statement))