@cosmicdrift/kumiko-framework 0.364.0 → 0.365.1

package/dist/db/apply-entity-event.js

@@ -44,7 +44,10 @@
 //   - "skipped" → Event ist kein Auto-Verb (Domain-Event auf demselben
 //     Aggregate). Caller no-op.
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { requestContext } from "../api/request-context.js";
 import { collectLookupableFields, computeBlindIndexValues } from "../crypto/blind-index.js";
+import { configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../crypto/pii-field-encryption.js";
+import { collectPiiFileReferenceFields } from "../crypto/subject-resolver.js";
 import { deleteMany, insertOne, updateMany } from "../db/query.js";
 import { InternalError } from "../errors/index.js";
 const AUTO_VERBS = ["created", "updated", "deleted", "restored", "forgotten"];
@@ -57,6 +60,27 @@ export function parseAutoVerb(event) {
     const verb = event.type.slice(prefix.length);
     return isOneOf(AUTO_VERBS, verb) ? verb : null;
 }
+// Events written by the old PII backfill can hold ciphertext in file/image uuid
+// columns. Replay restores the plain fileRef id; an erased subject yields null.
+async function decryptFileReferenceCiphertext(entity, values) {
+    const ciphertextFields = collectPiiFileReferenceFields(entity).filter((name) => isPiiCiphertext(values[name]));
+    if (ciphertextFields.length === 0)
+        return values;
+    const kms = configuredPiiSubjectKms();
+    if (kms === undefined) {
+        throw new InternalError({
+            message: `applyEntityEvent: file field(s) ${ciphertextFields.join(", ")} hold PII ciphertext but no subject KMS is configured; configure the KMS before replaying.`,
+        });
+    }
+    const decrypted = await decryptPiiFieldValues(values, ciphertextFields, kms, {
+        requestId: requestContext.get()?.requestId ?? "apply-entity-event",
+    });
+    for (const name of ciphertextFields) {
+        if (decrypted[name] === PII_ERASED_SENTINEL)
+            decrypted[name] = null;
+    }
+    return decrypted;
+}
 /** Idempotente Anwendung eines Auto-Events auf die Entity-Tabelle.
  *  Wird sowohl beim Live-Append (innerhalb der Write-TX) als auch beim
  *  Rebuild (innerhalb der Rebuild-TX) gerufen — identische Logik. */
@@ -92,7 +116,7 @@ export async function applyEntityEvent(event, table, entity, tx) {
                 });
             }
             const row = await insertOne(tx, table, {
-                ...event.payload,
+                ...(await decryptFileReferenceCiphertext(entity, event.payload)),
                 // Blind-Index-Spalten aus dem Payload-Wert (ciphertext → decrypt →
                 // HMAC, plaintext → HMAC, erased → NULL). Hier statt im Executor,
                 // damit Live-Write und Rebuild denselben Wert produzieren und der
@@ -110,7 +134,7 @@ export async function applyEntityEvent(event, table, entity, tx) {
             // payload-Shape: { changes, previous } — siehe event-store-executor.ts.
             const rawChanges = (event.payload["changes"] ?? {}); // @cast-boundary engine-payload
             const changes = {};
-            for (const [key, value] of Object.entries(rawChanges)) {
+            for (const [key, value] of Object.entries(await decryptFileReferenceCiphertext(entity, rawChanges))) {
                 const field = entity.fields[key];
                 // Historical events can carry fields since removed from the entity; the
                 // tolerance lives here (not in updateMany) so a live typo still throws.

package/dist/db/blind-index-cleanup.js

@@ -15,6 +15,7 @@ import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-p
 import { isSelfPiiField } from "../crypto/is-self-pii-field.js";
 import { toSnakeCase } from "../utils/case.js";
 import { resolveTableName } from "./entity-table-meta.js";
+import { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 import { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
 import { columnNamesOf, tableExists } from "./schema-inspection.js";
 export async function nullBlindIndexesForSubject(db, features, subjectKey) {
@@ -55,7 +56,7 @@ export async function nullBlindIndexesForSubject(db, features, subjectKey) {
 async function existingTableNames(db, tableNames) {
     if (tableNames.length === 0)
         return new Set();
-    const rows = await executeRawQueryRead(db, `SELECT t.name FROM unnest($1::text[]) AS t(name) WHERE to_regclass('public.' || quote_ident(t.name)) IS NOT NULL`, [tableNames]);
+    const rows = await executeRawQueryRead(db, `SELECT t.name FROM unnest($1::text[]) AS t(name) WHERE to_regclass('public.' || quote_ident(t.name)) IS NOT NULL`, [toPostgresArrayLiteral(tableNames)]);
     return new Set(rows.map((r) => r.name));
 }
 // Tenant-scope oracle for crypto-shredding's forget-subject (mh#349): a

package/dist/db/bun-provider.js

@@ -1,12 +1,11 @@
-// Bun.SQL Provider — experimentell.
-// Default: postgres-js. Dieser Provider nur aktiv wenn DB_PROVIDER=bun.
-// Bekannter Bug: Extended-Query-Protocol Caching verursacht
-// PostgresError "bind message has 11 result formats but query has 1 columns"
-// bei sequentiellen Queries mit unterschiedlicher Spaltenzahl innerhalb
-// derselben Connection.
+// Bun.SQL provider, opt-in via DB_PROVIDER=bun; postgres-js stays the default.
+// Known bug (Bun <= 1.4.3, oven-sh/bun#29484): a cached plan is not re-prepared
+// after DDL, so e.g. `SELECT *` after ADD COLUMN fails on that connection with
+// 0A000 "cached plan must not change result type". prepare:false is no fix,
+// it changes how jsonb params are bound.
 //
-// Bun.SQL hat kein LISTEN — postgres-js-Peer für event-dispatcher.
-import postgres from "postgres";
+// LISTEN runs on Bun.SQL's own dedicated connection, which is exempt from the
+// pool's idleTimeout and maxLifetime and re-LISTENs after a drop.
 import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS, } from "./api.js";
 export function createBunConnection(url, options = {}) {
     const bunOpts = {};
@@ -17,21 +16,13 @@ export function createBunConnection(url, options = {}) {
     if (options.connectTimeoutSeconds !== undefined)
         bunOpts.connectionTimeout = options.connectTimeoutSeconds;
     const db = new Bun.SQL(url, bunOpts);
-    // LISTEN peer — 1 connection reicht für NOTIFY-Wakeups
-    const pgOpts = { max: 1 };
-    if (options.idleTimeoutSeconds !== undefined)
-        pgOpts.idle_timeout = options.idleTimeoutSeconds;
-    if (options.connectTimeoutSeconds !== undefined)
-        pgOpts.connect_timeout = options.connectTimeoutSeconds;
-    const listenClient = postgres(url, pgOpts);
     const closeTimeout = options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS;
     return {
         db,
-        client: listenClient,
-        listenClient,
+        client: db,
+        listenClient: db,
         close: async () => {
             await db.end({ timeout: closeTimeout });
-            await listenClient.end({ timeout: closeTimeout });
         },
     };
 }

package/dist/db/dialect.d.ts

@@ -54,7 +54,7 @@ export declare function instant(name: string, opts?: {
 }): ColumnBuilder<Temporal.Instant>;
 export declare function plainDate(name: string): ColumnBuilder<Temporal.PlainDate>;
 export declare const decimalColumn: (name: string, precision: number, scale: number) => ColumnBuilder<number>;
-export declare const moneyAmount: (name: string) => ColumnBuilder<number>;
+export declare const moneyAmount: (name: string) => ColumnBuilder<bigint>;
 export type IndexBuilder = {
     readonly __index: true;
     on(...cols: ColumnHandle[]): IndexBuilderWithCols;

package/dist/db/dialect.js

@@ -58,6 +58,8 @@ export function pgTypeToSqlType(pgType) {
 function _toSnakeCase(name) {
     return name.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`).replace(/^_/, "");
 }
+// TValue is never inferred from the factory's declared return type, so a factory that forgets its
+// type argument fails to compile instead of silently typing the column from its own annotation.
 function buildColumn(sqlName, pgType, opts) {
     let notNull = false;
     let primaryKey = false;

package/dist/db/eagerload.js

@@ -26,6 +26,7 @@ import { parseRefTargetEntityName } from "../engine/parse-ref-target.js";
 import { isUuid, SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { collectEncryptedFieldNames, decryptEntityFieldValues, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
 import { buildParentRefClause } from "./parent-ref-clause.js";
+import { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 import { executeRawQueryRead } from "./queries/raw-sql.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
@@ -77,7 +78,7 @@ async function resolveRefAccessScope(refEntity, refTable, refTableName, ids, db,
     // No read path exists for non-uuid ids, so nothing can be access-checked.
     if (refEntity.idType !== undefined && refEntity.idType !== "uuid")
         return { kind: "none" };
-    const params = [ids];
+    const params = [toPostgresArrayLiteral(ids)];
     let tenantClause = "";
     if (refTable["tenantId"] !== undefined && db.mode === "tenant") {
         params.push(db.tenantId, SYSTEM_TENANT_ID);

package/dist/db/event-store-executor-context.d.ts

@@ -62,6 +62,7 @@ export type ExecutorContext = {
         subjectSource?: Record<string, unknown>;
         keyTenantId?: TenantId | undefined;
         ownerFallback?: Record<string, unknown>;
+        onErasedSubject?: "sentinel";
     }) => Promise<Record<string, unknown>>;
     readonly decryptForRead: (row: Record<string, unknown>, opts?: DecryptForReadOptions) => Promise<Record<string, unknown>>;
     readonly ownerTransitionRekeys: (previous: Record<string, unknown>, mergedNew: Record<string, unknown>, submittedChanges: Record<string, unknown>) => Record<string, unknown>;

package/dist/db/event-store-executor-context.js

@@ -215,6 +215,7 @@ export function buildExecutorContext(table, entity, options) {
                     ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
                     ...(opts?.subjectSource !== undefined && { subjectSource: opts.subjectSource }),
                     ...(opts?.ownerFallback !== undefined && { ownerFallback: opts.ownerFallback }),
+                    ...(opts?.onErasedSubject !== undefined && { onErasedSubject: opts.onErasedSubject }),
                 });
             }
             catch (e) {

package/dist/db/event-store-executor-write.d.ts

@@ -1,3 +1,3 @@
-import type { EventStoreExecutor } from "./event-store-executor.js";
+import { type EventStoreExecutor } from "./event-store-executor.js";
 import { type ExecutorContext } from "./event-store-executor-context.js";
 export declare function createWriteVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor, "create" | "update" | "delete" | "forget" | "restore">;

package/dist/db/event-store-executor-write.js

@@ -2,14 +2,15 @@ import { checkWriteFieldOwnership } from "../engine/field-access.js";
 import { instructionFieldNames } from "../engine/instruction-fields.js";
 import { userCanCreateFieldRow, userCanWriteFieldRow } from "../engine/ownership.js";
 import { buildInsertSchema, buildUpdateSchema } from "../engine/schema-builder.js";
-import { findUnavailableSelectOptions, isRecordLocked, } from "../engine/screen-helpers.js";
-import { AccessDeniedError, VersionConflictError as FrameworkVersionConflict, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RecordLockedError, UnprocessableError, writeFailure, } from "../errors/index.js";
+import { findUnavailableSelectOptions, isRecordLocked, isUnchangedValue, } from "../engine/screen-helpers.js";
+import { AccessDeniedError, VersionConflictError as FrameworkVersionConflict, IdempotentReplayError, InternalError, isSubjectErasedConflict, NotFoundError, PreconditionFailedError, RecordLockedError, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { append, IdempotentAppendConflictError as EventStoreIdempotentAppendConflict, VersionConflictError as EventStoreVersionConflict, getStreamVersion, } from "../event-store/index.js";
 import { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "../pipeline/irreversible-operation-gate.js";
 import { hasLiveProjectionsForEvent, runProjectionsForEvent, } from "../pipeline/projections-runner.js";
 import { generateId } from "../utils/index.js";
 import { applyEntityEvent } from "./apply-entity-event.js";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
+import { WritePurposes, } from "./event-store-executor.js";
 import { buildEventMetadata, entityEventName, isForeignTenantOnGlobalEntity, ownershipSubject, tryMapUniqueViolation, } from "./event-store-executor-context.js";
 import { isFrameworkSystemUser, isLockGuardBypassed } from "./lock-guard.js";
 import { projectionRegistryOf } from "./projection-registry-binding.js";
@@ -34,19 +35,6 @@ async function projectEntityEvent(db, runner, event) {
 // behavior-preserving relocation, not a redesign: every closure below is
 // unchanged from the original, just relocated behind an explicit
 // ExecutorContext instead of capturing the factory's local scope directly.
-// updateOptions.skipUnchanged (#464) — opt-in: a resubmitted-but-identical
-// key is dropped before encryption so pii/encrypted fields don't get a fresh
-// AEAD ciphertext (new nonce) for no real change, and the event's `changes`
-// don't carry a phantom diff. Opt-in, not the executor's default, because
-// direct executor.update() callers rely on the current behavior to FORCE a
-// re-encrypt of an unchanged plaintext — KEK-rotation (auth-mfa reencrypt.job)
-// and the user-data-rights #494 backfill both resubmit the current value on
-// purpose to land a fresh event/ciphertext. Only the generic entity update
-// handler (entity-handlers.ts) sets this flag; those two call their own
-// executor directly and never see it.
-function isUnchangedValue(a, b) {
-    return JSON.stringify(a) === JSON.stringify(b);
-}
 function selectOptionNotAvailableFailure(entries) {
     const [first] = entries;
     if (!first)
@@ -125,6 +113,11 @@ export function createWriteVerbs(ctx) {
         }
         return writeFailure(new RecordLockedError({ entityName, entityId: id }));
     }
+    // Erasure writes run after the subject key is gone; they store the erased
+    // sentinel for that subject's fields instead of failing on re-encrypt.
+    function erasureSentinelOption(options) {
+        return options?.writePurpose === WritePurposes.erasure ? { onErasedSubject: "sentinel" } : {};
+    }
     const eventVersion = entity.eventVersion ?? 1;
     let insertSchema;
     let updateSchema;
@@ -149,6 +142,55 @@ export function createWriteVerbs(ctx) {
         }
         return { row: row };
     }
+    // A forgotten subject has no key any more: restore re-encrypts the stored row and reports
+    // that as a failure result like any other write conflict instead of throwing.
+    async function appendRestoredEvent(runner, user, id, previousPlain, streamTenantId, currentVersion) {
+        try {
+            const previous = await encryptForStorage(previousPlain, user, {
+                keyTenantId: streamTenantId,
+            });
+            const event = await runInSavepointIfSupported(runner, (sp) => append(sp, {
+                aggregateId: String(id),
+                aggregateType: entityName,
+                tenantId: streamTenantFor(user, streamTenantId),
+                expectedVersion: currentVersion,
+                type: entityEventName(entityName, "restored"),
+                eventVersion,
+                payload: { previous },
+                metadata: buildEventMetadata(user),
+            }));
+            return { event };
+        }
+        catch (e) {
+            if (isSubjectErasedConflict(e))
+                return { failure: writeFailure(e) };
+            if (e instanceof EventStoreVersionConflict) {
+                return {
+                    failure: writeFailure(new FrameworkVersionConflict({
+                        entityId: id,
+                        expectedVersion: currentVersion,
+                        currentVersion: await versionAfterConflict(runner, String(id), streamTenantFor(user, streamTenantId)),
+                    })),
+                };
+            }
+            if (e instanceof EventStoreIdempotentAppendConflict) {
+                return {
+                    failure: writeFailure(new IdempotentReplayError({ idempotencyKey: e.idempotencyKey })),
+                };
+            }
+            throw e;
+        }
+    }
+    // After a lost append race the stream version read before the append is stale;
+    // report the actual one. -1 when the lookup itself fails.
+    async function versionAfterConflict(runner, aggregateId, tenantId) {
+        try {
+            return await getStreamVersion(runner, aggregateId, tenantId);
+        }
+        catch {
+            return -1;
+        }
+    }
     async function expectedStreamVersion(db, id, streamTenant, expect) {
         const snapshot = await loadExpectSnapshot(db, id, streamTenant, Object.keys(expect));
         const row = snapshot.row;
@@ -266,13 +308,7 @@ export function createWriteVerbs(ctx) {
             }
             catch (e) {
                 if (e instanceof EventStoreVersionConflict) {
-                    let currentVersion = -1;
-                    try {
-                        currentVersion = await getStreamVersion(runner, aggregateId, streamTenantFor(user, streamTenantId));
-                    }
-                    catch {
-                        // Lookup failure — keep the sentinel.
-                    }
+                    const currentVersion = await versionAfterConflict(runner, aggregateId, streamTenantFor(user, streamTenantId));
                     return writeFailure(new FrameworkVersionConflict({
                         entityId: aggregateId,
                         expectedVersion: 0,
@@ -415,7 +451,12 @@ export function createWriteVerbs(ctx) {
             const lockedUpdate = recordLockedFailure(previous, payload.id, user, updateOptions);
             if (lockedUpdate)
                 return lockedUpdate;
-            const unavailableOnUpdate = selectOptionNotAvailableFailure(findUnavailableSelectOptions(entity.fields, mergedNew, previous));
+            // Statutory retention/erasure writes may change a condition field (e.g. null a PII
+            // reference) and must not be blocked by the select rule — same exemption as the lock.
+            const isStatutorySystemWrite = updateOptions?.writePurpose !== undefined && isFrameworkSystemUser(user);
+            const unavailableOnUpdate = isStatutorySystemWrite
+                ? undefined
+                : selectOptionNotAvailableFailure(findUnavailableSelectOptions(entity.fields, mergedNew, previous));
             if (unavailableOnUpdate)
                 return unavailableOnUpdate;
             const streamTenant = streamTenantFor(user, streamTenantId);
@@ -454,6 +495,9 @@ export function createWriteVerbs(ctx) {
                 // Compound-Types Auto-Convert (alle in einem Pass).
                 // subjectSource: partial changes may carry a pii field without its
                 // ownerField — the merged row still names the subject.
+                // skipUnchanged (#464) is opt-in: an identical resubmitted key is dropped before
+                // encryption so pii/encrypted fields get no fresh ciphertext for no real change.
+                // Direct callers (KEK rotation, #494 backfill) rely on the default to force a re-encrypt.
                 const submittedChanges = updateOptions?.skipUnchanged
                     ? Object.fromEntries(Object.entries(changes).filter(([key, value]) => !isUnchangedValue(value, previous[key])))
                     : changes;
@@ -469,6 +513,7 @@ export function createWriteVerbs(ctx) {
                     onlyKeys: Object.keys(changesToPersist),
                     subjectSource: mergedNew,
                     keyTenantId: streamTenantId,
+                    ...erasureSentinelOption(updateOptions),
                 });
                 // The event payload carries BOTH `changes` (what the user asked for) AND
                 // `previous` (the pre-update row). Cross-aggregate projections need the
@@ -484,6 +529,7 @@ export function createWriteVerbs(ctx) {
                 const encryptedPrevious = await encryptForStorage(previous, user, {
                     keyTenantId: streamTenantId,
                     ownerFallback: submittedChanges,
+                    ...erasureSentinelOption(updateOptions),
                 });
                 // Savepoint-scoped — see the create() append() above for why:
                 // confines a losing writer's unique-violation to a nested scope
@@ -561,7 +607,7 @@ export function createWriteVerbs(ctx) {
                     return writeFailure(new FrameworkVersionConflict({
                         entityId: payload.id,
                         expectedVersion: payload.version ?? 0,
-                        currentVersion,
+                        currentVersion: await versionAfterConflict(runner, String(payload.id), streamTenant),
                     }));
                 }
                 if (e instanceof EventStoreIdempotentAppendConflict) {
@@ -620,7 +666,10 @@ export function createWriteVerbs(ctx) {
                     type: entityEventName(entityName, "deleted"),
                     eventVersion,
                     payload: {
-                        previous: await encryptForStorage(existing, user, { keyTenantId: streamTenantId }),
+                        previous: await encryptForStorage(existing, user, {
+                            keyTenantId: streamTenantId,
+                            ...erasureSentinelOption(options),
+                        }),
                     },
                     metadata: buildEventMetadata(user),
                 }));
@@ -630,7 +679,7 @@ export function createWriteVerbs(ctx) {
                     return writeFailure(new FrameworkVersionConflict({
                         entityId: payload.id,
                         expectedVersion: currentVersion,
-                        currentVersion: -1,
+                        currentVersion: await versionAfterConflict(runner, String(payload.id), streamTenantFor(user, streamTenantId)),
                     }));
                 }
                 if (e instanceof EventStoreIdempotentAppendConflict) {
@@ -702,7 +751,10 @@ export function createWriteVerbs(ctx) {
                     // Re-encrypt like delete(): `existing` came decrypted from loadById —
                     // plaintext must not land in the immutable log, least of all on forget.
                     payload: {
-                        previous: await encryptForStorage(existing, user, { keyTenantId: streamTenantId }),
+                        previous: await encryptForStorage(existing, user, {
+                            keyTenantId: streamTenantId,
+                            onErasedSubject: "sentinel",
+                        }),
                     },
                     metadata: buildEventMetadata(user),
                 }));
@@ -712,7 +764,7 @@ export function createWriteVerbs(ctx) {
                     return writeFailure(new FrameworkVersionConflict({
                         entityId: payload.id,
                         expectedVersion: currentVersion,
-                        currentVersion: -1,
+                        currentVersion: await versionAfterConflict(runner, String(payload.id), streamTenantFor(user, streamTenantId)),
                     }));
                 }
                 if (e instanceof EventStoreIdempotentAppendConflict) {
@@ -777,36 +829,11 @@ export function createWriteVerbs(ctx) {
             // table. Rows predating the subject-KMS rollout may still hold plaintext
             // pii, and envelope encryption is not idempotent: decrypt, then
             // re-encrypt as delete does.
-            const previousPlain = await decryptForRead(data);
-            const previousForStorage = await encryptForStorage(previousPlain, user, {
-                keyTenantId: streamTenantId,
-            });
-            let event;
-            try {
-                event = await runInSavepointIfSupported(runner, (sp) => append(sp, {
-                    aggregateId: String(payload.id),
-                    aggregateType: entityName,
-                    tenantId: streamTenantFor(user, streamTenantId),
-                    expectedVersion: currentVersion,
-                    type: entityEventName(entityName, "restored"),
-                    eventVersion,
-                    payload: { previous: previousForStorage },
-                    metadata: buildEventMetadata(user),
-                }));
-            }
-            catch (e) {
-                if (e instanceof EventStoreVersionConflict) {
-                    return writeFailure(new FrameworkVersionConflict({
-                        entityId: payload.id,
-                        expectedVersion: currentVersion,
-                        currentVersion: -1,
-                    }));
-                }
-                if (e instanceof EventStoreIdempotentAppendConflict) {
-                    return writeFailure(new IdempotentReplayError({ idempotencyKey: e.idempotencyKey }));
-                }
-                throw e;
-            }
+            const previousPlain = await decryptForRead(rehydrateCompoundTypes(data, entity));
+            const appended = await appendRestoredEvent(runner, user, payload.id, previousPlain, streamTenantId, currentVersion);
+            if ("failure" in appended)
+                return appended.failure;
+            const event = appended.event;
             // Live==Rebuild via applyEntityEvent. Restore only writes isDeleted=false
             // plus the version bump, so there is no sensitive-field drift and no
             // payload override is needed.

package/dist/db/index.d.ts

@@ -24,6 +24,7 @@ export { type AppliedMigration, type ApplyResult, type BaselineResult, baselineM
 export { flattenMoney, type MoneyRead, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";
 export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, type PgErrorInfo, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
+export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
 export type { SelectOptions, WhereObject, WhereValue } from "./query-api.js";
 export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "./query-api.js";

package/dist/db/index.js

@@ -18,6 +18,7 @@ export { baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, Migr
 export { flattenMoney, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";
 export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
+export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
 export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "./query-api.js";
 export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from "./rebuild-marker.js";

package/dist/db/migrate-runner.d.ts

@@ -12,6 +12,7 @@ export type ApplyResult = {
     readonly applied: readonly string[];
     readonly skipped: readonly string[];
 };
+export declare const MIGRATION_ADVISORY_LOCK_KEY = 1802857833;
 export declare function splitSqlStatements(sqlText: string): readonly string[];
 export declare function loadMigrationsFromDir(dir: string, preprocess?: (sql: string) => string): readonly Migration[];
 export declare function readMigrationSqlTexts(dir: string): readonly string[];

package/dist/db/migrate-runner.js

@@ -17,11 +17,11 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
-import { asRawClient, hasBegin } from "../bun-db/query.js";
+import { asRawClient, hasBegin, } from "../bun-db/query.js";
 // 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
+export const MIGRATION_ADVISORY_LOCK_KEY = 0x6b756d69; // "kumi" in ASCII
 const MIGRATIONS_TABLE_DDL = `
 CREATE TABLE IF NOT EXISTS "_kumiko_migrations" (
   "id" text PRIMARY KEY NOT NULL,
@@ -186,8 +186,18 @@ function migrationClient(db) {
 async function executeRaw(db, sqlText) {
     await migrationClient(db).unsafe(sqlText);
 }
+async function reserveConnection(db) {
+    const client = migrationClient(db);
+    if (typeof client.reserve !== "function") {
+        throw new Error("migrate-runner: db argument has no .reserve() (need Bun.SQL or postgres-js Sql)");
+    }
+    return client.reserve();
+}
 export async function fetchAppliedMigrations(db) {
-    const result = await migrationClient(db).unsafe(`SELECT id, checksum FROM "_kumiko_migrations" ORDER BY id`);
+    return fetchAppliedFrom(migrationClient(db));
+}
+async function fetchAppliedFrom(client) {
+    const result = await client.unsafe(`SELECT id, checksum FROM "_kumiko_migrations" ORDER BY id`);
     const rows = Array.isArray(result) ? result : [];
     const applied = [];
     for (const row of rows) {
@@ -216,40 +226,55 @@ export class MigrationChecksumMismatchError extends Error {
 // _kumiko_migrations-Lookup übersprungen. Checksum-Mismatch wirft fail-loud.
 // Advisory-Lock verhindert concurrent-apply-races.
 export async function runMigrations(db, migrations) {
-    await executeRaw(db, MIGRATIONS_TABLE_DDL);
-    await executeRaw(db, `SELECT pg_advisory_lock(${ADVISORY_LOCK_KEY})`);
+    // Session-level advisory lock and per-migration BEGIN/COMMIT must share one
+    // session. Pool calls may land on different connections (Bun.SQL round-robins),
+    // which would leave the lock held on a session nobody unlocks.
+    const conn = await reserveConnection(db);
     try {
-        const applied = new Map((await fetchAppliedMigrations(db)).map((a) => [a.id, a.checksum]));
-        const appliedIds = [];
-        const skippedIds = [];
-        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);
+        await conn.unsafe(MIGRATIONS_TABLE_DDL);
+        await conn.unsafe(`SELECT pg_advisory_lock(${MIGRATION_ADVISORY_LOCK_KEY})`);
+        try {
+            const applied = new Map((await fetchAppliedFrom(conn)).map((a) => [a.id, a.checksum]));
+            const appliedIds = [];
+            const skippedIds = [];
+            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;
                 }
-                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 = migrationClient(db);
-            await client.begin(async (tx) => {
-                for (const stmt of m.statements) {
-                    await tx.unsafe(stmt);
+                // Apply file content + INSERT tracking-row in einer TX. Wenn ein
+                // Statement bricht, Rollback inkl. Tracking-Row → kein partial-apply
+                // stuck in den books.
+                await conn.unsafe("BEGIN");
+                try {
+                    for (const stmt of m.statements) {
+                        await conn.unsafe(stmt);
+                    }
+                    await conn.unsafe(`INSERT INTO "_kumiko_migrations" ("id", "checksum") VALUES ($1, $2)`, [
+                        m.id,
+                        m.checksum,
+                    ]);
+                    await conn.unsafe("COMMIT");
+                }
+                catch (e) {
+                    // A failed ROLLBACK means the session is gone (its lock and tx with it); keep the migration error.
+                    await conn.unsafe("ROLLBACK").catch(() => undefined);
+                    throw e;
                 }
-                await tx.unsafe(`INSERT INTO "_kumiko_migrations" ("id", "checksum") VALUES ($1, $2)`, [
-                    m.id,
-                    m.checksum,
-                ]);
-            });
-            appliedIds.push(m.id);
+                appliedIds.push(m.id);
+            }
+            return { applied: appliedIds, skipped: skippedIds };
+        }
+        finally {
+            await conn.unsafe(`SELECT pg_advisory_unlock(${MIGRATION_ADVISORY_LOCK_KEY})`);
         }
-        return { applied: appliedIds, skipped: skippedIds };
     }
     finally {
-        await executeRaw(db, `SELECT pg_advisory_unlock(${ADVISORY_LOCK_KEY})`);
+        await conn.release();
     }
 }
 // Convenience: load + run in einem Call. Wird vom `kumiko migrate apply`