@cosmicdrift/kumiko-framework 0.14.0 → 0.15.0

package/src/db/migrate-generator.ts

@@ -0,0 +1,350 @@
+// Build-time Generator: EntityTableMeta[] → reviewbares SQL-Migration-File.
+// Ersatz für `drizzle-kit generate`.
+//
+// **NO-MAGIC-ON-DATA Kernprinzip** (siehe drizzle-replacement.md):
+//   - Generator emittiert SQL-Files für PR-Review/Edit
+//   - Generator wird NIE zur App-Runtime aufgerufen
+//   - Output ist Start-Form; App-Author darf das SQL hand-editieren
+//     (BRIN-Index, partial-Index, performance-tuning) bevor committed
+//   - Append-only: bestehende Migration-Files werden NIE überschrieben.
+//     Neue Schema-Diffs landen in einem NEUEN File mit incrementierter
+//     Sequence-Number.
+//
+// **DESTRUCTIVE-ops** (DROP TABLE/COLUMN, INDEX-removal) werden als
+// AUSKOMMENTIERTE statements emittiert — Reviewer muss explizit
+// uncommenten + ggf. Data-Backup-Schritt vorlauf einfügen. Default:
+// niemals automatisch droppen.
+
+import { readFileSync, writeFileSync } from "node:fs";
+
+import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta";
+import { renderTableDdl } from "./render-ddl";
+
+const SNAPSHOT_VERSION = 1 as const;
+
+export type Snapshot = {
+  readonly version: typeof SNAPSHOT_VERSION;
+  readonly generatedAt: string; // ISO-8601
+  readonly tables: readonly EntityTableMeta[];
+};
+
+export type ColumnChange = {
+  readonly name: string;
+  readonly nullabilityChanged?: { readonly from: boolean; readonly to: boolean };
+  readonly defaultChanged?: { readonly from: string | undefined; readonly to: string | undefined };
+  readonly typeChanged?: { readonly from: string; readonly to: string };
+};
+
+export type TableDiff = {
+  readonly tableName: string;
+  readonly newColumns: readonly ColumnMeta[];
+  readonly droppedColumns: readonly string[];
+  readonly changedColumns: readonly ColumnChange[];
+  readonly newIndexes: readonly IndexMeta[];
+  readonly droppedIndexes: readonly string[];
+};
+
+export type SchemaDiff = {
+  readonly newTables: readonly EntityTableMeta[];
+  readonly droppedTables: readonly string[];
+  readonly changedTables: readonly TableDiff[];
+};
+
+export function snapshotFromMetas(metas: readonly EntityTableMeta[]): Snapshot {
+  // Stable ordering by tableName so the snapshot.json diff in PRs is
+  // meaningful (table-add isn't a noisy re-sort of everything).
+  const sorted = [...metas].sort((a, b) => a.tableName.localeCompare(b.tableName));
+  return {
+    version: SNAPSHOT_VERSION,
+    generatedAt: new Date().toISOString(),
+    tables: sorted,
+  };
+}
+
+export function loadSnapshotJson(path: string): Snapshot | null {
+  try {
+    const text = readFileSync(path, "utf8");
+    const parsed = JSON.parse(text) as { version?: unknown };
+    if (parsed.version !== SNAPSHOT_VERSION) {
+      throw new Error(
+        `Snapshot at ${path} has version ${String(parsed.version)}, expected ${SNAPSHOT_VERSION}`,
+      );
+    }
+    return parsed as Snapshot;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export function writeSnapshotJson(path: string, snapshot: Snapshot): void {
+  writeFileSync(path, `${JSON.stringify(snapshot, null, 2)}\n`);
+}
+
+function indexMetaKey(idx: IndexMeta): string {
+  // Index-Identität via Name (PG-Constraint: unique innerhalb der DB)
+  return idx.name;
+}
+
+function columnsByName(meta: EntityTableMeta): Map<string, ColumnMeta> {
+  const m = new Map<string, ColumnMeta>();
+  for (const c of meta.columns) m.set(c.name, c);
+  return m;
+}
+
+function indexesByName(meta: EntityTableMeta): Map<string, IndexMeta> {
+  const m = new Map<string, IndexMeta>();
+  for (const i of meta.indexes) m.set(indexMetaKey(i), i);
+  return m;
+}
+
+function diffOneTable(prev: EntityTableMeta, next: EntityTableMeta): TableDiff | null {
+  const prevCols = columnsByName(prev);
+  const nextCols = columnsByName(next);
+
+  const newColumns: ColumnMeta[] = [];
+  const droppedColumns: string[] = [];
+  const changedColumns: ColumnChange[] = [];
+
+  for (const [name, nextCol] of nextCols) {
+    const prevCol = prevCols.get(name);
+    if (!prevCol) {
+      newColumns.push(nextCol);
+      continue;
+    }
+    const change: ColumnChange = { name };
+    if (prevCol.notNull !== nextCol.notNull) {
+      Object.assign(change, {
+        nullabilityChanged: { from: prevCol.notNull, to: nextCol.notNull },
+      });
+    }
+    if (prevCol.defaultSql !== nextCol.defaultSql) {
+      Object.assign(change, {
+        defaultChanged: { from: prevCol.defaultSql, to: nextCol.defaultSql },
+      });
+    }
+    if (prevCol.pgType !== nextCol.pgType) {
+      Object.assign(change, {
+        typeChanged: { from: prevCol.pgType, to: nextCol.pgType },
+      });
+    }
+    if (change.nullabilityChanged || change.defaultChanged || change.typeChanged) {
+      changedColumns.push(change);
+    }
+  }
+  for (const name of prevCols.keys()) {
+    if (!nextCols.has(name)) droppedColumns.push(name);
+  }
+
+  const prevIdx = indexesByName(prev);
+  const nextIdx = indexesByName(next);
+  const newIndexes: IndexMeta[] = [];
+  const droppedIndexes: string[] = [];
+  for (const [name, idx] of nextIdx) {
+    if (!prevIdx.has(name)) newIndexes.push(idx);
+  }
+  for (const name of prevIdx.keys()) {
+    if (!nextIdx.has(name)) droppedIndexes.push(name);
+  }
+
+  const isEmpty =
+    newColumns.length === 0 &&
+    droppedColumns.length === 0 &&
+    changedColumns.length === 0 &&
+    newIndexes.length === 0 &&
+    droppedIndexes.length === 0;
+  if (isEmpty) return null;
+  return {
+    tableName: prev.tableName,
+    newColumns,
+    droppedColumns,
+    changedColumns,
+    newIndexes,
+    droppedIndexes,
+  };
+}
+
+export function diffSnapshots(prev: Snapshot | null, next: Snapshot): SchemaDiff {
+  const prevByName = new Map<string, EntityTableMeta>();
+  if (prev) {
+    for (const t of prev.tables) prevByName.set(t.tableName, t);
+  }
+  const nextByName = new Map<string, EntityTableMeta>();
+  for (const t of next.tables) nextByName.set(t.tableName, t);
+
+  const newTables: EntityTableMeta[] = [];
+  const droppedTables: string[] = [];
+  const changedTables: TableDiff[] = [];
+
+  for (const [name, nextMeta] of nextByName) {
+    const prevMeta = prevByName.get(name);
+    if (!prevMeta) {
+      newTables.push(nextMeta);
+      continue;
+    }
+    const td = diffOneTable(prevMeta, nextMeta);
+    if (td) changedTables.push(td);
+  }
+  for (const name of prevByName.keys()) {
+    if (!nextByName.has(name)) droppedTables.push(name);
+  }
+
+  return { newTables, droppedTables, changedTables };
+}
+
+// --- SQL-Render ---------------------------------------------------------
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+function renderColumnInline(col: ColumnMeta): string {
+  const parts: string[] = [quoteIdent(col.name), col.pgType];
+  if (col.defaultSql !== undefined) parts.push(`DEFAULT ${col.defaultSql}`);
+  if (col.notNull) parts.push("NOT NULL");
+  return parts.join(" ");
+}
+
+function renderAddColumn(tableName: string, col: ColumnMeta): string {
+  return `ALTER TABLE ${quoteIdent(tableName)} ADD COLUMN ${renderColumnInline(col)};`;
+}
+
+function renderColumnChange(tableName: string, change: ColumnChange): readonly string[] {
+  const out: string[] = [];
+  const col = quoteIdent(change.name);
+  const tbl = quoteIdent(tableName);
+  if (change.nullabilityChanged) {
+    const op = change.nullabilityChanged.to ? "SET NOT NULL" : "DROP NOT NULL";
+    out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} ${op};`);
+  }
+  if (change.defaultChanged) {
+    if (change.defaultChanged.to !== undefined) {
+      out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} SET DEFAULT ${change.defaultChanged.to};`);
+    } else {
+      out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} DROP DEFAULT;`);
+    }
+  }
+  if (change.typeChanged) {
+    // pg ALTER TYPE braucht oft USING-clause für nicht-implicit-castable
+    // type-changes. Wir emittieren das als Reviewer-Kommentar + raw cast —
+    // App-Author muss prüfen ob das gewünscht ist.
+    out.push(
+      `-- WARN: column-type-change ${change.typeChanged.from} → ${change.typeChanged.to}. Review USING-clause if needed.`,
+    );
+    out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE ${change.typeChanged.to};`);
+  }
+  return out;
+}
+
+function renderIndex(tableName: string, idx: IndexMeta): string {
+  const kind = idx.unique === true ? "UNIQUE INDEX" : "INDEX";
+  const colList = idx.columns.map(quoteIdent).join(", ");
+  const where = idx.whereSql !== undefined ? ` WHERE ${idx.whereSql}` : "";
+  return `CREATE ${kind} IF NOT EXISTS ${quoteIdent(idx.name)} ON ${quoteIdent(tableName)} (${colList})${where};`;
+}
+
+// Render the diff as a SQL-file content with header-comment + grouped
+// statements. Destructive operations (DROP TABLE/COLUMN, DROP INDEX where
+// the index serves performance) are emitted as commented-out statements
+// for explicit reviewer-action.
+export function renderMigrationSql(
+  diff: SchemaDiff,
+  options: { readonly name: string; readonly sequenceNumber: number },
+): string {
+  const lines: string[] = [];
+  const seq = options.sequenceNumber.toString().padStart(4, "0");
+  lines.push(`-- Migration ${seq}_${options.name}`);
+  lines.push(`-- Generated: ${new Date().toISOString()}`);
+  lines.push("-- ");
+  lines.push("-- This file is generated by `kumiko migrate generate`. You may");
+  lines.push("-- hand-edit it before committing — add partial-indexes, BRIN-");
+  lines.push("-- variants, performance-tuning. After commit + apply, NEVER edit");
+  lines.push("-- this file again (production-DBs already ran it). Write a new");
+  lines.push("-- migration instead.");
+  lines.push("");
+
+  if (diff.newTables.length > 0) {
+    lines.push("-- === New tables ===");
+    for (const tbl of diff.newTables) {
+      lines.push(...renderTableDdl(tbl));
+      lines.push("");
+    }
+  }
+
+  if (diff.changedTables.length > 0) {
+    lines.push("-- === Changed tables ===");
+    for (const td of diff.changedTables) {
+      lines.push(`-- ${td.tableName}`);
+      for (const col of td.newColumns) {
+        lines.push(renderAddColumn(td.tableName, col));
+      }
+      for (const ch of td.changedColumns) {
+        for (const stmt of renderColumnChange(td.tableName, ch)) lines.push(stmt);
+      }
+      for (const idx of td.newIndexes) {
+        lines.push(renderIndex(td.tableName, idx));
+      }
+      for (const name of td.droppedIndexes) {
+        lines.push(`-- (review) DROP INDEX IF EXISTS ${quoteIdent(name)};`);
+      }
+      for (const colName of td.droppedColumns) {
+        lines.push(
+          `-- DESTRUCTIVE: ALTER TABLE ${quoteIdent(td.tableName)} DROP COLUMN ${quoteIdent(colName)};  -- uncomment + ensure backup`,
+        );
+      }
+      lines.push("");
+    }
+  }
+
+  if (diff.droppedTables.length > 0) {
+    lines.push("-- === Dropped tables ===");
+    for (const name of diff.droppedTables) {
+      lines.push(
+        `-- DESTRUCTIVE: DROP TABLE IF EXISTS ${quoteIdent(name)};  -- uncomment + ensure backup + run during maintenance window`,
+      );
+    }
+    lines.push("");
+  }
+
+  if (
+    diff.newTables.length === 0 &&
+    diff.changedTables.length === 0 &&
+    diff.droppedTables.length === 0
+  ) {
+    lines.push("-- No schema changes detected.");
+  }
+
+  return lines.join("\n");
+}
+
+// --- High-level entry point --------------------------------------------
+
+export type GenerateMigrationInput = {
+  readonly metas: readonly EntityTableMeta[];
+  readonly prevSnapshot: Snapshot | null;
+  readonly name: string;
+  readonly sequenceNumber: number;
+};
+
+export type GenerateMigrationOutput = {
+  readonly filename: string;
+  readonly sqlContent: string;
+  readonly snapshot: Snapshot;
+  readonly diff: SchemaDiff;
+};
+
+export function generateMigration(input: GenerateMigrationInput): GenerateMigrationOutput {
+  const nextSnapshot = snapshotFromMetas(input.metas);
+  const diff = diffSnapshots(input.prevSnapshot, nextSnapshot);
+  const sqlContent = renderMigrationSql(diff, {
+    name: input.name,
+    sequenceNumber: input.sequenceNumber,
+  });
+  const seq = input.sequenceNumber.toString().padStart(4, "0");
+  return {
+    filename: `${seq}_${input.name}.sql`,
+    sqlContent,
+    snapshot: nextSnapshot,
+    diff,
+  };
+}

package/src/db/migrate-runner.ts

@@ -0,0 +1,206 @@
+// Migrate-Runner: applied checked-in SQL-Files gegen eine DB.
+// Ersatz für `drizzle-kit migrate` als Runtime-Komponente.
+//
+// **NO-MAGIC-ON-DATA Kernprinzip** (siehe drizzle-replacement.md):
+//   - Runner liest NUR checked-in `<dir>/*.sql` Files
+//   - Kein Reach-back zu EntityDefinition zur Runtime
+//   - Kein Auto-Apply-on-App-Boot — Deploy-Skript oder Init-Container ruft
+//     `kumiko migrate apply` als eigenen Schritt
+//   - Schema-Drift wird durch Checksum-Mismatch fail-loud detektiert
+//
+// Tracking-Table `_kumiko_migrations(id, applied_at, checksum)`. id = filename
+// ohne .sql-Endung. Checksum = sha256 vom File-Content beim Apply. Wenn ein
+// schon-appliedes File nachträglich editiert wird, schlägt der nächste Apply
+// fehl mit klarer Fehlermeldung (production-DBs haben das alte SQL drin —
+// edit nachträglich = production-state inkonsistent mit committed-state).
+
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { DbConnection, DbRunner } from "./connection";
+
+// Adapter: extract raw postgres-js client from drizzle DbConnection,
+// or use Bun.sql instance directly. Either way `.unsafe()` is the
+// runtime call.
+function rawClient(db: DbRunner): {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly Record<string, unknown>[]>;
+  begin: <T>(fn: (tx: unknown) => Promise<T>) => Promise<T>;
+} {
+  const dbAny = db as unknown as Record<string, unknown>;
+  if (typeof dbAny["unsafe"] === "function" && typeof dbAny["begin"] === "function") {
+    return dbAny as never;
+  }
+  const $client = dbAny["$client"];
+  if ($client && typeof ($client as Record<string, unknown>)["unsafe"] === "function") {
+    return $client as never;
+  }
+  const session = dbAny["session"] as Record<string, unknown> | undefined;
+  const sessionClient = session?.["client"];
+  if (sessionClient && typeof (sessionClient as Record<string, unknown>)["unsafe"] === "function") {
+    return sessionClient as never;
+  }
+  throw new Error(
+    "migrate-runner: db argument has no .unsafe() (need Bun.SQL or drizzle DbConnection)",
+  );
+}
+
+export type Migration = {
+  readonly id: string; // filename ohne .sql
+  readonly checksum: string; // sha256-hex vom File-Content
+  readonly statements: readonly string[];
+};
+
+export type AppliedMigration = {
+  readonly id: string;
+  readonly checksum: string;
+};
+
+export type ApplyResult = {
+  readonly applied: readonly string[];
+  readonly skipped: readonly string[];
+};
+
+// Advisory-lock key (random 32-bit int, stable). Verhindert dass zwei
+// gleichzeitig bootende Pods beide migrate apply laufen lassen (zweiter
+// blockiert bis erster fertig).
+const ADVISORY_LOCK_KEY = 0x6b756d69; // "kumi" in ASCII
+
+const MIGRATIONS_TABLE_DDL = `
+CREATE TABLE IF NOT EXISTS "_kumiko_migrations" (
+  "id" text PRIMARY KEY NOT NULL,
+  "checksum" text NOT NULL,
+  "applied_at" timestamptz NOT NULL DEFAULT now()
+)
+`.trim();
+
+// Splittet SQL-File-Text in einzelne Statements. Pragma: simpler `;`-Split,
+// reicht weil unsere generierten SQL-Files keine eingebetteten `;` in String-
+// Literalen haben. App-Author der hand-editiert + tricky SQL einfügt sollte
+// das wissen — sonst pg-Parser einziehen.
+export function splitSqlStatements(sqlText: string): readonly string[] {
+  return sqlText
+    .split(";")
+    .map((s) => s.replace(/--[^\n]*/g, "").trim())
+    .filter((s) => s.length > 0)
+    .map((s) => `${s};`);
+}
+
+function sha256Hex(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+// Liest <dir>/*.sql, sortiert lex (z.B. 0001_init.sql, 0002_add_locale.sql),
+// returnt Migration[] mit id + checksum + statements.
+export function loadMigrationsFromDir(dir: string): readonly Migration[] {
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith(".sql"))
+    .sort();
+  return files.map((file) => {
+    const content = readFileSync(join(dir, file), "utf8");
+    return {
+      id: file.replace(/\.sql$/, ""),
+      checksum: sha256Hex(content),
+      statements: splitSqlStatements(content),
+    };
+  });
+}
+
+// Raw-SQL via postgres-js or Bun.sql .unsafe() — same shape for both.
+async function executeRaw(db: DbRunner, sqlText: string): Promise<void> {
+  await rawClient(db).unsafe(sqlText);
+}
+
+async function fetchAppliedMigrations(db: DbConnection): Promise<readonly AppliedMigration[]> {
+  const result = await rawClient(db).unsafe(
+    `SELECT id, checksum FROM "_kumiko_migrations" ORDER BY id`,
+  );
+  const rows = Array.isArray(result) ? result : [];
+  const applied: AppliedMigration[] = [];
+  for (const row of rows) {
+    if (
+      typeof row === "object" &&
+      row !== null &&
+      typeof (row as { id?: unknown }).id === "string" &&
+      typeof (row as { checksum?: unknown }).checksum === "string"
+    ) {
+      applied.push({
+        id: (row as { id: string }).id,
+        checksum: (row as { checksum: string }).checksum,
+      });
+    }
+  }
+  return applied;
+}
+
+export class MigrationChecksumMismatchError extends Error {
+  constructor(
+    public readonly migrationId: string,
+    public readonly expected: string,
+    public readonly actual: string,
+  ) {
+    super(
+      `Migration "${migrationId}" was edited after being applied. ` +
+        `DB has checksum ${expected.slice(0, 12)}…, file has ${actual.slice(0, 12)}…. ` +
+        `Production-DBs already ran the original SQL — editing applied migrations ` +
+        `causes schema-drift. Write a NEW migration file instead (NNNN+1_<change>.sql).`,
+    );
+    this.name = "MigrationChecksumMismatchError";
+  }
+}
+
+// Apply pending migrations. Idempotent: schon applied migrations werden via
+// _kumiko_migrations-Lookup übersprungen. Checksum-Mismatch wirft fail-loud.
+// Advisory-Lock verhindert concurrent-apply-races.
+export async function runMigrations(
+  db: DbConnection,
+  migrations: readonly Migration[],
+): Promise<ApplyResult> {
+  await executeRaw(db, MIGRATIONS_TABLE_DDL);
+  await executeRaw(db, `SELECT pg_advisory_lock(${ADVISORY_LOCK_KEY})`);
+  try {
+    const applied = new Map(
+      (await fetchAppliedMigrations(db)).map((a) => [a.id, a.checksum] as const),
+    );
+
+    const appliedIds: string[] = [];
+    const skippedIds: string[] = [];
+
+    for (const m of migrations) {
+      const prevChecksum = applied.get(m.id);
+      if (prevChecksum !== undefined) {
+        if (prevChecksum !== m.checksum) {
+          throw new MigrationChecksumMismatchError(m.id, prevChecksum, m.checksum);
+        }
+        skippedIds.push(m.id);
+        continue;
+      }
+      // Apply file content + INSERT tracking-row in einer TX. Wenn ein
+      // Statement bricht, Rollback inkl. Tracking-Row → kein partial-apply
+      // stuck in den books.
+      const client = rawClient(db);
+      await client.begin(async (tx) => {
+        const txClient = tx as { unsafe: (s: string, p?: readonly unknown[]) => Promise<unknown> };
+        for (const stmt of m.statements) {
+          await txClient.unsafe(stmt);
+        }
+        await txClient.unsafe(
+          `INSERT INTO "_kumiko_migrations" ("id", "checksum") VALUES ($1, $2)`,
+          [m.id, m.checksum],
+        );
+      });
+      appliedIds.push(m.id);
+    }
+
+    return { applied: appliedIds, skipped: skippedIds };
+  } finally {
+    await executeRaw(db, `SELECT pg_advisory_unlock(${ADVISORY_LOCK_KEY})`);
+  }
+}
+
+// Convenience: load + run in einem Call. Wird vom `kumiko migrate apply`
+// CLI-Command + von Test-Setup-Helfern verwendet.
+export async function runMigrationsFromDir(db: DbConnection, dir: string): Promise<ApplyResult> {
+  const migrations = loadMigrationsFromDir(dir);
+  return runMigrations(db, migrations);
+}

package/src/db/postgres-provider.ts

@@ -0,0 +1,25 @@
+// PostgreSQL Provider: postgres-js.
+// Standard-Provider — stabil, keine bekannten Protocol-Level-Bugs.
+// `asRawClient(db)` wrappt .unsafe und .begin transparent.
+
+import postgres from "postgres";
+import type { DbConnection, DbConnectionOptions } from "./api";
+
+export function createPgConnection(url: string, options: DbConnectionOptions = {}): DbConnection {
+  const pgOptions: Parameters<typeof postgres>[1] = {};
+  if (options.maxConnections !== undefined) pgOptions.max = options.maxConnections;
+  if (options.idleTimeoutSeconds !== undefined) pgOptions.idle_timeout = options.idleTimeoutSeconds;
+  if (options.connectTimeoutSeconds !== undefined) {
+    pgOptions.connect_timeout = options.connectTimeoutSeconds;
+  }
+
+  const client = postgres(url, pgOptions);
+
+  return {
+    db: client,
+    client,
+    close: async () => {
+      await client.end();
+    },
+  };
+}

package/src/db/queries/entity-read.ts

@@ -0,0 +1,15 @@
+import type { AnyDb } from "../query";
+import { executeRawQuery } from "./raw-sql";
+import { quoteTableIdent } from "./table-ops";
+
+export async function selectRowForUpdateById(
+  db: AnyDb,
+  tableName: string,
+  id: string | number,
+): Promise<readonly Record<string, unknown>[]> {
+  return executeRawQuery(
+    db,
+    `SELECT * FROM ${quoteTableIdent(tableName)} WHERE "id" = $1 FOR UPDATE`,
+    [id],
+  );
+}

package/src/db/queries/es-ops.ts

@@ -0,0 +1,17 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+/** Stabiler Lock-Key für pg_advisory_xact_lock — multi-replica seed boots. */
+export const ES_OPS_ADVISORY_LOCK_KEY = 0x65_73_6f_70; // 'esop'
+
+export async function acquireEsOpsAdvisoryLock(db: AnyDb): Promise<void> {
+  await asRawClient(db).unsafe(`SELECT pg_advisory_xact_lock($1)`, [ES_OPS_ADVISORY_LOCK_KEY]);
+}
+
+export async function esOperationExists(db: AnyDb, operationId: string): Promise<boolean> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT 1 FROM "kumiko_es_operations" WHERE id = $1 LIMIT 1`,
+    [operationId],
+  )) as readonly unknown[];
+  return rows.length > 0;
+}