@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/db/postgres-provider.js

@@ -0,0 +1,21 @@
+// PostgreSQL Provider: postgres-js.
+// Standard-Provider — stabil, keine bekannten Protocol-Level-Bugs.
+// `asRawClient(db)` wrappt .unsafe und .begin transparent.
+import postgres from "postgres";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS, } from "./api.js";
+export function createPgConnection(url, options = {}) {
+    const pgOptions = {};
+    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: () => client.end({ timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS }),
+    };
+}

package/dist/db/queries/advisory-lock.d.ts

@@ -0,0 +1,3 @@
+import type { AnyDb } from "../query.js";
+/** pg_advisory_xact_lock keyed on namespace+key hash — xact-scoped, auto-released at commit/rollback. */
+export declare function acquireNamespacedAdvisoryLock(db: AnyDb, namespace: number, key: string): Promise<void>;

package/dist/db/queries/advisory-lock.js

@@ -0,0 +1,5 @@
+import { asRawClient } from "../query.js";
+/** pg_advisory_xact_lock keyed on namespace+key hash — xact-scoped, auto-released at commit/rollback. */
+export async function acquireNamespacedAdvisoryLock(db, namespace, key) {
+    await asRawClient(db).unsafe(`SELECT pg_advisory_xact_lock($1, hashtext($2))`, [namespace, key]);
+}

package/dist/db/queries/backfill-pii.d.ts

@@ -0,0 +1,38 @@
+import type { Registry } from "../../engine/types/index.js";
+import type { DbRunner } from "../connection.js";
+export type PiiBackfillFailure = {
+    readonly eventId: string;
+    readonly reason: string;
+};
+export type PiiBackfillResult = {
+    readonly scannedEvents: number;
+    readonly updatedEvents: number;
+    readonly encryptedFields: number;
+    readonly erasedFields: number;
+    readonly ownerFromProjection: number;
+    readonly erasedUnresolvable: number;
+    readonly deletedSnapshots: number;
+    readonly failures: readonly PiiBackfillFailure[];
+};
+export type PiiBackfillScanCache = {
+    forgottenAggregates?: ReadonlySet<string>;
+};
+export type PiiBackfillBatchResult = PiiBackfillResult & {
+    readonly lastEventId: string | null;
+    readonly scannedAll: boolean;
+    readonly firstFailedEventId: string | null;
+    readonly touchedAggregateTypes: readonly string[];
+    readonly touchedEventTypes: readonly string[];
+};
+export type PiiBackfillOptions = {
+    readonly batchSize?: number;
+    readonly dryRun?: boolean;
+    readonly resolveOwnerFromProjection?: boolean;
+    readonly eraseUnresolvableSubjects?: boolean;
+};
+export type PiiBackfillBatchOptions = PiiBackfillOptions & {
+    readonly afterEventId?: bigint | string;
+    readonly scanCache?: PiiBackfillScanCache;
+};
+export declare function backfillEventPiiEncryption(db: DbRunner, registry: Registry, options?: PiiBackfillOptions): Promise<PiiBackfillResult>;
+export declare function backfillEventPiiEncryptionBatch(db: DbRunner, registry: Registry, options?: PiiBackfillBatchOptions): Promise<PiiBackfillBatchResult>;

package/dist/db/queries/backfill-pii.js

@@ -0,0 +1,433 @@
+// One-time backfill for pre-KMS plaintext PII in kumiko_events (#799).
+//
+// Crypto-shredding (#724/#818) only covers NEW writes — events appended
+// before a KMS was configured still carry plaintext (user.created email,
+// delivery attempt recipientAddress, job payloads). This tool re-encrypts
+// them in place, per field, under the owning subject's DEK:
+//
+//   - entity lifecycle events (<entity>.created/updated/deleted/forgotten/
+//     restored) for every entity with PII subject annotations — generic over
+//     subject kind (user/tenant/record, fw#2790), since it goes through the
+//     same collectPiiSubjectFields/resolveSubjectForField the live write
+//     path uses
+//   - custom events from the event-PII catalog (r.defineEvent piiFields) —
+//     user/tenant/self subjects, via the same resolveEventSubject the live
+//     append path uses (fw#2801)
+//
+// Already-forgotten subjects must NOT get a fresh key minted for their old
+// plaintext — three erased-detection layers write [[erased]] instead:
+//   1. KeyErasedError from the KMS (subject forgotten in the KMS era)
+//   2. the event's own aggregate has a *.forgotten event (pre-KMS forget)
+//   3. the resolved user subject's id has a *.forgotten event (custom
+//      events referencing a pre-KMS-forgotten user)
+//
+// Idempotent: ciphertext and sentinel values pass through untouched — a
+// second run reports 0 updates. One failing event does not abort the run;
+// failures are collected and reported (fail-loud at the caller).
+//
+// Owner resolution for entity-lifecycle events (backfill-only — the live
+// write path in event-store-executor-write.ts / subject-resolver.ts stays
+// fail-closed and is untouched by this):
+//   1. payload — the event section itself names the owner field.
+//   2. projection ({@link PiiBackfillOptions.resolveOwnerFromProjection}) —
+//      pre-owner-field-addition events don't carry it; read it from the
+//      entity's current projection row instead.
+//   3. erase ({@link PiiBackfillOptions.eraseUnresolvableSubjects}) — still
+//      unresolvable (hard-deleted aggregate, no projection) → PII_ERASED_SENTINEL.
+//   Both stages are opt-in and off by default; without them an unresolvable
+//   subject still fails loud into `failures`, as before.
+//
+// Snapshots of touched aggregates are dropped per batch (they may cache
+// plaintext); the next snapshotting load recreates them. AFTER a run, rebuild the
+// affected projections — applyEntityEvent materializes ciphertext AND the
+// blind-index columns, which keeps equality lookups (login by email) alive.
+import { asRawClient } from "../../bun-db/index.js";
+import { quoteIdent } from "../../crypto/ciphertext-pattern.js";
+import { configuredEventPiiCatalog } from "../../crypto/event-pii.js";
+import { isLocalKeyKmsAdapter, KeyErasedError, KeyNotFoundError, } from "../../crypto/kms-adapter.js";
+import { configuredPiiSubjectKms, encryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../../crypto/pii-field-encryption.js";
+import { collectPiiSubjectFields, resolveEventSubject, resolveSubjectForField, SubjectResolutionError, } from "../../crypto/subject-resolver.js";
+import { resolveTableName } from "../entity-table-meta.js";
+import { tableExists } from "../schema-inspection.js";
+import { toSnakeCase } from "../table-builder.js";
+const LIFECYCLE_VERBS = ["created", "updated", "deleted", "restored", "forgotten"];
+function collectPiiTargets(registry) {
+    const entityTargets = new Map();
+    for (const [name, entity] of registry.getAllEntities()) {
+        const piiFields = collectPiiSubjectFields(entity);
+        if (piiFields.length > 0)
+            entityTargets.set(name, { entity, piiFields });
+    }
+    return { entityTargets, eventCatalog: configuredEventPiiCatalog() };
+}
+function requireLocalKeySubjectKms(caller) {
+    const kms = configuredPiiSubjectKms();
+    if (!kms) {
+        throw new Error(`${caller} requires a configured subject KMS — boot with ` +
+            "runProdApp({ kms }) / configurePiiSubjectKms(adapter) before running the backfill.");
+    }
+    if (!isLocalKeyKmsAdapter(kms)) {
+        throw new Error(`${caller} requires a local-key KMS adapter`);
+    }
+    return kms;
+}
+export async function backfillEventPiiEncryption(db, registry, options = {}) {
+    requireLocalKeySubjectKms("backfillEventPiiEncryption");
+    const total = {
+        scannedEvents: 0,
+        updatedEvents: 0,
+        encryptedFields: 0,
+        erasedFields: 0,
+        ownerFromProjection: 0,
+        erasedUnresolvable: 0,
+        deletedSnapshots: 0,
+    };
+    const failures = [];
+    const scanCache = {};
+    let afterEventId = "0";
+    for (;;) {
+        const batch = await backfillEventPiiEncryptionBatch(db, registry, {
+            ...options,
+            afterEventId,
+            scanCache,
+        });
+        total.scannedEvents += batch.scannedEvents;
+        total.updatedEvents += batch.updatedEvents;
+        total.encryptedFields += batch.encryptedFields;
+        total.erasedFields += batch.erasedFields;
+        total.ownerFromProjection += batch.ownerFromProjection;
+        total.erasedUnresolvable += batch.erasedUnresolvable;
+        total.deletedSnapshots += batch.deletedSnapshots;
+        failures.push(...batch.failures);
+        if (batch.lastEventId === null || batch.scannedAll)
+            break;
+        afterEventId = batch.lastEventId;
+    }
+    return { ...total, failures };
+}
+// Processes exactly one batch. Snapshots of the batch's touched aggregates are
+// dropped inside the same call so an abort between batches never leaves a
+// snapshot that caches plaintext for an already-encrypted stream.
+export async function backfillEventPiiEncryptionBatch(db, registry, options = {}) {
+    const subjectKms = requireLocalKeySubjectKms("backfillEventPiiEncryptionBatch");
+    const batchSize = options.batchSize ?? 500;
+    const raw = asRawClient(db);
+    const kmsCtx = { requestId: "pii-backfill" };
+    const scanCache = options.scanCache ?? {};
+    const { entityTargets, eventCatalog } = collectPiiTargets(registry);
+    const aggregateTypes = [...entityTargets.keys()];
+    const catalogTypes = [...eventCatalog.keys()];
+    const result = {
+        scannedEvents: 0,
+        updatedEvents: 0,
+        encryptedFields: 0,
+        erasedFields: 0,
+        ownerFromProjection: 0,
+        erasedUnresolvable: 0,
+        deletedSnapshots: 0,
+        failures: [],
+    };
+    const emptyBatch = () => ({
+        ...result,
+        lastEventId: null,
+        scannedAll: true,
+        firstFailedEventId: null,
+        touchedAggregateTypes: [],
+        touchedEventTypes: [],
+    });
+    if (aggregateTypes.length === 0 && catalogTypes.length === 0)
+        return emptyBatch();
+    const rows = (await raw.unsafe(`SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
+       FROM "kumiko_events"
+      WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" > $3::bigint
+      ORDER BY "id" ASC
+      LIMIT $4`, [aggregateTypes, catalogTypes, String(options.afterEventId ?? 0), batchSize]));
+    const last = rows[rows.length - 1];
+    if (last === undefined)
+        return emptyBatch();
+    const projectionOwnersByType = await loadProjectionOwners(rows);
+    const touchedAggregates = new Set();
+    const touchedAggregateTypes = new Set();
+    const touchedEventTypes = new Set();
+    let firstFailedEventId = null;
+    for (const row of rows) {
+        result.scannedEvents++;
+        try {
+            const outcome = await transformEvent(row, projectionOwnersByType.get(row.aggregate_type));
+            if (outcome === null)
+                continue;
+            result.encryptedFields += outcome.encrypted;
+            result.erasedFields += outcome.erased;
+            result.ownerFromProjection += outcome.ownerFromProjection;
+            result.erasedUnresolvable += outcome.erasedUnresolvable;
+            if (!options.dryRun) {
+                await raw.unsafe(`UPDATE "kumiko_events" SET "payload" = $1::jsonb WHERE "id" = $2`, [
+                    outcome.payload,
+                    row.id,
+                ]);
+            }
+            result.updatedEvents++;
+            touchedAggregates.add(row.aggregate_id);
+            touchedAggregateTypes.add(row.aggregate_type);
+            touchedEventTypes.add(row.type);
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            firstFailedEventId ??= String(row.id);
+            result.failures.push({
+                eventId: String(row.id),
+                reason: e instanceof SubjectResolutionError
+                    ? `${reason} (retry with { resolveOwnerFromProjection: true } to resolve the owner ` +
+                        "from the entity's projection table, and/or { eraseUnresolvableSubjects: true } to " +
+                        "erase fields whose subject stays unresolvable)"
+                    : reason,
+            });
+        }
+    }
+    // Snapshots may cache the plaintext state of touched aggregates.
+    if (!options.dryRun && touchedAggregates.size > 0) {
+        const deleted = (await raw.unsafe(`DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = ANY($1::uuid[]) RETURNING "aggregate_id"`, [[...touchedAggregates]]));
+        result.deletedSnapshots = deleted.length;
+    }
+    return {
+        ...result,
+        lastEventId: String(last.id),
+        scannedAll: rows.length < batchSize,
+        firstFailedEventId,
+        touchedAggregateTypes: [...touchedAggregateTypes],
+        touchedEventTypes: [...touchedEventTypes],
+    };
+    // Full-scan of the store — only paid once a plaintext field actually needs
+    // encrypting, so a catch-up run over already-encrypted events never runs it.
+    async function loadForgottenAggregates() {
+        if (scanCache.forgottenAggregates)
+            return scanCache.forgottenAggregates;
+        // Pre-KMS forgets left no key tombstone — the *.forgotten event on the
+        // stream is the only durable marker. aggregate_id doubles as the user id
+        // for user-subject lookups.
+        const forgottenRows = (await raw.unsafe(`SELECT DISTINCT "aggregate_id" FROM "kumiko_events" WHERE "type" LIKE '%.forgotten'`));
+        scanCache.forgottenAggregates = new Set(forgottenRows.map((r) => r.aggregate_id));
+        return scanCache.forgottenAggregates;
+    }
+    async function loadProjectionOwners(rows) {
+        const byType = new Map();
+        if (!options.resolveOwnerFromProjection)
+            return byType;
+        const idsByType = new Map();
+        for (const row of rows) {
+            if (!entityTargets.has(row.aggregate_type))
+                continue;
+            const ids = idsByType.get(row.aggregate_type) ?? new Set();
+            ids.add(row.aggregate_id);
+            idsByType.set(row.aggregate_type, ids);
+        }
+        for (const [aggregateType, ids] of idsByType) {
+            const target = entityTargets.get(aggregateType);
+            if (!target)
+                continue;
+            const tableName = resolveTableName(aggregateType, target.entity, undefined);
+            const ownersById = new Map();
+            // Existence check instead of catching undefined_table: a caught SQL error
+            // aborts the surrounding transaction (25P02). Entity never mounted/rebuilt
+            // → stage 3 still gets a chance; this batch just contributes no owners.
+            if (await tableExists(db, `public.${tableName}`)) {
+                const projectionRows = (await raw.unsafe(`SELECT * FROM ${quoteIdent(tableName)} WHERE "id" = ANY($1::uuid[])`, [[...ids]]));
+                for (const projectionRow of projectionRows) {
+                    const id = projectionRow["id"];
+                    if (typeof id === "string") {
+                        ownersById.set(id, projectionRowToCamel(target.entity, projectionRow));
+                    }
+                }
+            }
+            byType.set(aggregateType, ownersById);
+        }
+        return byType;
+    }
+    async function transformEvent(row, projectionOwners) {
+        const counters = { encrypted: 0, erased: 0, ownerFromProjection: 0, erasedUnresolvable: 0 };
+        const payload = structuredClone(row.payload);
+        const catalogFields = eventCatalog.get(row.type);
+        if (catalogFields) {
+            for (const [field, spec] of Object.entries(catalogFields)) {
+                const subject = resolveEventSubject(field, spec, payload, {
+                    tenantId: row.tenant_id, // @cast-boundary db-read — tenant_id column is the branded TenantId
+                    aggregateType: row.aggregate_type,
+                    aggregateId: row.aggregate_id,
+                });
+                if (subject === null)
+                    continue;
+                const outcome = await encryptField(payload, field, subject);
+                bump(outcome);
+            }
+        }
+        else {
+            const target = entityTargets.get(row.aggregate_type);
+            if (!target || !isLifecycleEventOf(row.type, row.aggregate_type))
+                return null;
+            await applyEntityLifecycleFields(target, projectionOwners?.get(row.aggregate_id));
+        }
+        if (counters.encrypted === 0 && counters.erased === 0)
+            return null;
+        return { payload, ...counters };
+        function bump(outcome) {
+            if (outcome === "encrypted")
+                counters.encrypted++;
+            if (outcome === "erased")
+                counters.erased++;
+        }
+        async function applyEntityLifecycleFields(target, projectionOwnerRow) {
+            const sections = lifecycleSections(payload);
+            for (const section of sections) {
+                // Update-changes may carry a pii field without its owner field —
+                // resolve subjects from the merged view; aggregate_id backs the
+                // self-subject when a section lacks the id column.
+                const subjectSource = {
+                    id: row.aggregate_id,
+                    ...Object.assign({}, ...sections),
+                    ...section,
+                };
+                for (const field of target.piiFields) {
+                    const value = section[field];
+                    if (value === null || value === undefined)
+                        continue;
+                    if (typeof value !== "string")
+                        continue;
+                    // Already-ciphertext/sentinel fields must never enter owner
+                    // resolution — an unresolvable owner on an already-handled field
+                    // must stay untouched, not get erased by stage 3.
+                    if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL)
+                        continue;
+                    const resolution = resolveOwnerSubject(target.entity, field, subjectSource, projectionOwnerRow, 
+                    // @cast-boundary db-read — tenant_id column is the branded TenantId
+                    row.tenant_id, row.aggregate_type);
+                    if (resolution.kind === "unannotated")
+                        continue;
+                    if (resolution.kind === "unresolved") {
+                        if (options.eraseUnresolvableSubjects) {
+                            section[field] = PII_ERASED_SENTINEL;
+                            counters.erased++;
+                            counters.erasedUnresolvable++;
+                            continue;
+                        }
+                        throw resolution.error;
+                    }
+                    if (resolution.viaProjection)
+                        counters.ownerFromProjection++;
+                    const outcome = await encryptField(section, field, resolution.subject);
+                    bump(outcome);
+                }
+            }
+        }
+        async function encryptField(section, field, subject) {
+            const value = section[field];
+            if (value === null || value === undefined)
+                return "unchanged";
+            if (typeof value !== "string")
+                return "unchanged";
+            if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL)
+                return "unchanged";
+            if (await isForgottenSubject(subject, row.aggregate_id)) {
+                section[field] = PII_ERASED_SENTINEL;
+                return "erased";
+            }
+            if (options.dryRun)
+                return predictEncryptOutcome(subject);
+            try {
+                section[field] = await encryptPiiValueForSubject(subjectKms, subject, value, kmsCtx, field);
+                return "encrypted";
+            }
+            catch (e) {
+                if (e instanceof KeyErasedError) {
+                    section[field] = PII_ERASED_SENTINEL;
+                    return "erased";
+                }
+                throw e;
+            }
+        }
+        // getKey alone never mints (unlike getOrCreateDek → createKey on the real
+        // path) — a real run's outcome is fully determined by whether a key
+        // already exists, so probing it read-only predicts the outcome without
+        // writing to the subject-keys store.
+        async function predictEncryptOutcome(subject) {
+            try {
+                await subjectKms.getKey(subject, kmsCtx);
+                return "encrypted";
+            }
+            catch (e) {
+                if (e instanceof KeyErasedError)
+                    return "erased";
+                if (e instanceof KeyNotFoundError)
+                    return "encrypted";
+                throw e;
+            }
+        }
+    }
+    async function isForgottenSubject(subject, aggregateId) {
+        const forgottenAggregates = await loadForgottenAggregates();
+        if (forgottenAggregates.has(aggregateId))
+            return true;
+        return subject.kind === "user" && forgottenAggregates.has(subject.userId);
+    }
+}
+// Stage 1 (payload) then stage 2 (projection row, when supplied) — stage 3
+// (erase) is the caller's call, made from the "unresolved" outcome.
+function resolveOwnerSubject(entity, field, subjectSource, projectionOwnerRow, tenantId, entityName) {
+    try {
+        const subject = resolveSubjectForField(entity, field, subjectSource, { tenantId, entityName });
+        return subject === null
+            ? { kind: "unannotated" }
+            : { kind: "resolved", subject, viaProjection: false };
+    }
+    catch (e) {
+        if (!(e instanceof SubjectResolutionError))
+            throw e;
+        if (projectionOwnerRow) {
+            try {
+                const augmented = { ...subjectSource, ...projectionOwnerRow };
+                const subject = resolveSubjectForField(entity, field, augmented, { tenantId, entityName });
+                if (subject !== null)
+                    return { kind: "resolved", subject, viaProjection: true };
+            }
+            catch (e2) {
+                if (!(e2 instanceof SubjectResolutionError))
+                    throw e2;
+            }
+        }
+        return { kind: "unresolved", error: e };
+    }
+}
+// Projection columns are snake_case (author_id); event-payload/subject
+// fields are camelCase (authorId) — forward-map from entity.fields like
+// reindexEntity's rowToState, so any owner field resolves generically
+// instead of hand-listing column names per entity.
+function projectionRowToCamel(entity, row) {
+    const camel = {};
+    for (const fieldName of Object.keys(entity.fields)) {
+        const snake = toSnakeCase(fieldName);
+        if (Object.hasOwn(row, snake))
+            camel[fieldName] = row[snake];
+    }
+    return camel;
+}
+function isLifecycleEventOf(eventType, aggregateType) {
+    if (!eventType.startsWith(`${aggregateType}.`))
+        return false;
+    const verb = eventType.slice(aggregateType.length + 1);
+    return LIFECYCLE_VERBS.includes(verb);
+}
+// created events carry the fields flat; updated carries { changes, previous };
+// deleted/forgotten/restored carry { previous }. Returned sections are the
+// mutable objects INSIDE the payload clone — encryptField writes in place.
+function lifecycleSections(payload) {
+    const sections = [];
+    if (isRecord(payload["changes"]))
+        sections.push(payload["changes"]);
+    if (isRecord(payload["previous"]))
+        sections.push(payload["previous"]);
+    if (sections.length === 0)
+        sections.push(payload);
+    return sections;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/db/queries/ddl.d.ts

@@ -0,0 +1,4 @@
+import type { AnyDb } from "../query.js";
+export declare function executeDdlStatement(db: AnyDb, sqlText: string): Promise<void>;
+export declare function alterTableAddColumn(db: AnyDb, tableName: string, columnName: string, columnType: string, defaultClause: string, notNull: string, ifNotExists?: boolean): Promise<void>;
+export declare function createIndexIfNotExists(db: AnyDb, indexKind: "UNIQUE INDEX" | "INDEX", indexName: string, tableName: string, columnList: string, whereSql?: string): Promise<void>;

package/dist/db/queries/ddl.js

@@ -0,0 +1,22 @@
+import { asRawClient } from "../query.js";
+import { quoteTableIdent } from "./table-ops.js";
+// Generic DDL helpers used on the prod-boot path (stack/table-helpers.ts's
+// unsafePushTables, event-consumer-state.ts's multi-instance backfill) —
+// split out of queries/test-stack.ts so a prod-boot import doesn't point at
+// a module named for test-only concerns (truncate/create/drop-database).
+export async function executeDdlStatement(db, sqlText) {
+    await asRawClient(db).unsafe(sqlText);
+}
+export async function alterTableAddColumn(db, tableName, columnName, columnType, defaultClause, notNull, 
+// table-helpers.ts's unmanaged-table sync relies on the plain form
+// throwing when a column already exists with a different shape than
+// EntityTableMeta expects — that's how it surfaces drift. Callers that
+// just need an idempotent, race-safe backfill (e.g. event-consumer-state's
+// multi-instance boot path, #1362) opt in explicitly.
+ifNotExists = false) {
+    await asRawClient(db).unsafe(`ALTER TABLE ${quoteTableIdent(tableName)} ADD COLUMN ${ifNotExists ? "IF NOT EXISTS " : ""}${quoteTableIdent(columnName)} ${columnType}${defaultClause}${notNull}`);
+}
+export async function createIndexIfNotExists(db, indexKind, indexName, tableName, columnList, whereSql) {
+    const where = whereSql !== undefined ? ` WHERE ${whereSql}` : "";
+    await asRawClient(db).unsafe(`CREATE ${indexKind} IF NOT EXISTS ${quoteTableIdent(indexName)} ON ${quoteTableIdent(tableName)} (${columnList})${where}`);
+}

package/dist/db/queries/entity-read.d.ts

@@ -0,0 +1,2 @@
+import type { AnyDb } from "../query.js";
+export declare function selectRowForUpdateById(db: AnyDb, tableName: string, id: string | number): Promise<readonly Record<string, unknown>[]>;

package/dist/db/queries/entity-read.js

@@ -0,0 +1,5 @@
+import { executeRawQuery } from "./raw-sql.js";
+import { quoteTableIdent } from "./table-ops.js";
+export async function selectRowForUpdateById(db, tableName, id) {
+    return executeRawQuery(db, `SELECT * FROM ${quoteTableIdent(tableName)} WHERE "id" = $1 FOR UPDATE`, [id]);
+}

package/dist/db/queries/es-ops.d.ts

@@ -0,0 +1,5 @@
+import type { AnyDb } from "../query.js";
+/** Stabiler Lock-Key für pg_advisory_xact_lock — multi-replica seed boots. */
+export declare const ES_OPS_ADVISORY_LOCK_KEY = 1702063984;
+export declare function acquireEsOpsAdvisoryLock(db: AnyDb): Promise<void>;
+export declare function esOperationExists(db: AnyDb, operationId: string): Promise<boolean>;

package/dist/db/queries/es-ops.js

@@ -0,0 +1,10 @@
+import { asRawClient } from "../query.js";
+/** 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) {
+    await asRawClient(db).unsafe(`SELECT pg_advisory_xact_lock($1)`, [ES_OPS_ADVISORY_LOCK_KEY]);
+}
+export async function esOperationExists(db, operationId) {
+    const rows = (await asRawClient(db).unsafe(`SELECT 1 FROM "kumiko_es_operations" WHERE id = $1 LIMIT 1`, [operationId]));
+    return rows.length > 0;
+}

package/dist/db/queries/event-consumer.d.ts

@@ -0,0 +1,36 @@
+import type { PendingGapEntry } from "../../pipeline/event-consumer-state.js";
+import type { AnyDb } from "../query.js";
+export declare function selectSnapshotXmin(db: AnyDb): Promise<string>;
+export declare function selectSnapshotXmax(db: AnyDb): Promise<string>;
+/** Serialise against consumer-bootstrap INSERTs during event retention prune. */
+export declare function lockEventConsumersShareMode(db: AnyDb): Promise<void>;
+export declare function selectEventIdHorizonWithMissingRanges(db: AnyDb): Promise<{
+    readonly horizon: bigint;
+    readonly gaps: PendingGapEntry[];
+}>;
+export declare function insertConsumerIfAbsent(db: AnyDb, name: string, instanceId: string, startFrom?: "beginning" | "now"): Promise<void>;
+export declare function deleteOrphanedPerInstanceConsumerRows(db: AnyDb, consumerNames: readonly string[], sharedInstanceSentinel: string): Promise<void>;
+export declare function selectProvablyIdleConsumerPairs(db: AnyDb, names: readonly string[], instanceIds: readonly string[], deadStatus: string): Promise<ReadonlyArray<{
+    readonly name: string;
+    readonly instanceId: string;
+}>>;
+export declare function selectConsumerForUpdateSkipLocked(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
+export declare function markConsumerProcessing(db: AnyDb, name: string, instanceId: string): Promise<void>;
+export declare function recordConsumerPassFailure(db: AnyDb, name: string, instanceId: string, errorMessage: string): Promise<void>;
+export type ConsumerDeliveryOutcome = {
+    readonly cursor: bigint;
+    readonly attempts: number;
+    readonly lastError: string | null;
+    readonly deadLettered: boolean;
+    readonly processed: number;
+    readonly pendingGaps: readonly PendingGapEntry[];
+};
+export declare function updateConsumerDeliveryOutcome(db: AnyDb, name: string, instanceId: string, outcome: ConsumerDeliveryOutcome): Promise<void>;
+export declare function updateConsumerStatusReturning(db: AnyDb, name: string, instanceId: string, status: "idle" | "disabled"): Promise<Record<string, unknown> | undefined>;
+export declare function advanceConsumerPastEventReturning(db: AnyDb, name: string, instanceId: string, eventId: bigint): Promise<Record<string, unknown> | undefined>;
+export declare function resetConsumerForMspRebuild(db: AnyDb, name: string, instanceId: string): Promise<void>;
+export declare function selectConsumerForUpdate(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
+export declare function updateConsumerRebuildCursor(db: AnyDb, name: string, instanceId: string, lastProcessedEventId: bigint, pendingGaps: readonly PendingGapEntry[]): Promise<void>;
+export declare function markConsumerRebuildFailed(db: AnyDb, name: string, instanceId: string, errorMessage: string): Promise<void>;
+export declare function rearmDeadConsumer(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
+export declare function removePendingGapReturning(db: AnyDb, name: string, instanceId: string, newPendingGaps: readonly PendingGapEntry[]): Promise<Record<string, unknown> | undefined>;