@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

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

@@ -2,20 +2,21 @@ 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 { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.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";
 import { runInSavepointIfSupported } from "./query.js";
 import { assertPersonalDataWrite, tableNameOf } from "./tenant-db.js";
-import { tenantDbRunner } from "./tenant-db-runner.js";
+import { tenantDbWriteRunner } from "./tenant-db-runner.js";
 // Custom projections for a write that did not go through the dispatcher (hook or
 // job writing a second aggregate). Savepoint like applyEntityEvent: a throwing
 // projection fails the write and the caller's transaction rolls it back.
@@ -29,30 +30,11 @@ async function projectEntityEvent(db, runner, event) {
         return;
     await runInSavepointIfSupported(runner, (sp) => runProjectionsForEvent(event, registry, sp));
 }
-// Art. 17 erasure runs as the framework operator, not as a row owner; a
-// per-role ownership map can never cover it, and a silent deny means the
-// erasure never happened.
-function isFrameworkSystemUser(user) {
-    return user.id === SYSTEM_USER_ID && user.roles.includes(SYSTEM_ROLE);
-}
 // The five write verbs (create/update/delete/forget/restore) of the event-
 // store-executor. Split out of event-store-executor.ts (#1005, Welle 2) —
 // 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)
@@ -126,13 +108,16 @@ export function createWriteVerbs(ctx) {
     // statutory deletion must reach locked rows, and forget (Art. 17) never checks the lock
     // at all. The options are server-code only; no request field is ever copied into them.
     function recordLockedFailure(row, id, user, options) {
-        if (options?.unsafeSkipLockGuard === true ||
-            (options?.writePurpose !== undefined && isFrameworkSystemUser(user)) ||
-            !isRecordLocked(entity.lockedWhen, row)) {
+        if (isLockGuardBypassed(user, options) || !isRecordLocked(entity.lockedWhen, row)) {
             return undefined;
         }
         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;
@@ -157,6 +142,45 @@ 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: -1,
+                    })),
+                };
+            }
+            if (e instanceof EventStoreIdempotentAppendConflict) {
+                return {
+                    failure: writeFailure(new IdempotentReplayError({ idempotencyKey: e.idempotencyKey })),
+                };
+            }
+            throw e;
+        }
+    }
     async function expectedStreamVersion(db, id, streamTenant, expect) {
         const snapshot = await loadExpectSnapshot(db, id, streamTenant, Object.keys(expect));
         const row = snapshot.row;
@@ -180,7 +204,7 @@ export function createWriteVerbs(ctx) {
             const streamTenantMismatch = streamTenantCreateFailure(db, payload, streamTenantId);
             if (streamTenantMismatch)
                 return streamTenantMismatch;
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor create");
             // Respect an explicit id in the payload (seed pattern, SCIM import). Without
             // one the framework mints a fresh UUIDv7 via generateId. Strip it out of the
             // event payload so defaults + downstream consumers don't see a redundant id field.
@@ -349,7 +373,7 @@ export function createWriteVerbs(ctx) {
             };
         },
         async update(payload, user, db, updateOptions) {
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor update");
             if (isForeignTenantOnGlobalEntity(entity, payload.changes["tenantId"])) {
                 throw new AccessDeniedError({
                     message: `${entityName}.update: entity is tenancy: "global" — payload.changes.tenantId must ` +
@@ -423,7 +447,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);
@@ -462,6 +491,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;
@@ -477,6 +509,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
@@ -492,6 +525,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
@@ -582,7 +616,7 @@ export function createWriteVerbs(ctx) {
             if (isIrreversibleEntityVerb("delete", entity)) {
                 assertIrreversibleOperationAllowed(`${entityName}.delete (entity has no softDelete)`);
             }
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor delete");
             const existing = await loadById(payload.id, db);
             if (!existing)
                 return writeFailure(new NotFoundError(entityName, payload.id));
@@ -628,7 +662,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),
                 }));
@@ -664,6 +701,7 @@ export function createWriteVerbs(ctx) {
                     data: existing,
                     entityName,
                     event: echoEvent,
+                    ...(isLockGuardBypassed(user, options) && { lockGuardBypassed: true }),
                 },
             };
         },
@@ -673,7 +711,7 @@ export function createWriteVerbs(ctx) {
         // without the isDeleted filter so trashed (soft-deleted) rows are erased too.
         async forget(payload, user, db, options) {
             assertIrreversibleOperationAllowed(`${entityName}.forget`);
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor forget");
             const raw = await db.fetchOne(table, { id: payload.id });
             if (!raw)
                 return writeFailure(new NotFoundError(entityName, payload.id));
@@ -709,7 +747,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),
                 }));
@@ -744,6 +785,7 @@ export function createWriteVerbs(ctx) {
                     data: existing,
                     entityName,
                     event: echoEvent,
+                    lockGuardBypassed: true,
                 },
             };
         },
@@ -753,7 +795,7 @@ export function createWriteVerbs(ctx) {
                     i18nKey: "errors.softDeleteNotEnabled",
                 }));
             }
-            const runner = tenantDbRunner(db);
+            const runner = tenantDbWriteRunner(db, "ctx.db executor restore");
             const streamTenantId = options?.streamTenantId;
             const target = await loadSoftDeletedRow(db, payload.id, streamTenantId);
             if ("failure" in target)
@@ -780,34 +822,14 @@ export function createWriteVerbs(ctx) {
             // Restore carries the soft-deleted snapshot as `previous` — mirror of
             // delete for symmetry. Projections that decremented on delete use
             // `previous` to re-increment on restore without re-querying the entity
-            // table. `data` is the raw stored row — pii/encrypted fields are
-            // already ciphertext, no re-encrypt needed.
-            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: data },
-                    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;
-            }
+            // 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 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.
@@ -835,7 +857,6 @@ export function createWriteVerbs(ctx) {
             // same as every other executor method — `data`/`restored` are raw rows
             // (db.fetchOne / applyEntityEvent), never decrypted before this point.
             const restoredHydrated = await decryptForRead(rehydrateCompoundTypes(restored, entity));
-            const previousPlain = await decryptForRead(data);
             const echoEvent = { ...event, payload: { previous: stripSensitive(previousPlain) } };
             await projectEntityEvent(db, runner, echoEvent);
             return {

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";
@@ -35,4 +36,4 @@ export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFramework
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
 export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db.js";
-export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, } from "./tenant-db.js";
+export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.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";
@@ -27,4 +28,4 @@ export { diffReplayAgainstSnapshot, replayMigrationsDir, } from "./replay-migrat
 export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
-export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, } from "./tenant-db.js";
+export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";

package/dist/db/lock-guard.d.ts

@@ -0,0 +1,4 @@
+import type { SessionUser } from "../engine/types/index.js";
+import type { LockGuardOption } from "./event-store-executor.js";
+export declare function isFrameworkSystemUser(user: SessionUser): boolean;
+export declare function isLockGuardBypassed(user: SessionUser, options: LockGuardOption | undefined): boolean;

package/dist/db/lock-guard.js

@@ -0,0 +1,14 @@
+import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
+// Art. 17 erasure runs as the framework operator, not as a row owner; a
+// per-role ownership map can never cover it, and a silent deny means the
+// erasure never happened.
+export function isFrameworkSystemUser(user) {
+    return user.id === SYSTEM_USER_ID && user.roles.includes(SYSTEM_ROLE);
+}
+// Framework system writes that name a writePurpose (retention, erasure) are exempt:
+// statutory deletion must reach locked rows. The options are server-code only; no
+// request field is ever copied into them.
+export function isLockGuardBypassed(user, options) {
+    return (options?.unsafeSkipLockGuard === true ||
+        (options?.writePurpose !== undefined && isFrameworkSystemUser(user)));
+}

package/dist/db/migrate-generator.js

@@ -437,7 +437,7 @@ export function assertUniqueTableNames(metas) {
     const duplicates = [...counts].filter(([, count]) => count > 1);
     if (duplicates.length > 0) {
         throw new Error(duplicates
-            .map(([tableName, count]) => `ENTITY_METAS lists table "${tableName}" ${count} times — the migration diff would silently use only one definition. collectTableMetas(features) already includes every table a feature registers (r.storeTable, entities, projections); remove the hand-added meta for "${tableName}".`)
+            .map(([tableName, count]) => `ENTITY_METAS lists table "${tableName}" ${count} times — the migration diff would silently use only one definition. collectTableMetas(features) already includes every table a feature registers (r.storeTable, entities, projections); remove the duplicate entry for "${tableName}" (a hand-added meta, or two features registering the same table).`)
             .join("\n"));
     }
 }

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 } 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,
@@ -169,24 +169,35 @@ export function readMigrationSqlTexts(dir) {
 // without it fall through to the drizzle wrappers and otherwise fail here,
 // before any SQL runs, with the migrate-runner message.
 function migrationClient(db) {
-    const hasDirectClient = typeof propertyOf(db, "unsafe") === "function" && typeof propertyOf(db, "begin") === "function";
-    if (hasDirectClient)
-        return asRawClient(db);
-    for (const wrapped of [
+    for (const candidate of [
+        db,
         propertyOf(db, "$client"),
         propertyOf(propertyOf(db, "session"), "client"),
     ]) {
-        if (typeof propertyOf(wrapped, "unsafe") === "function")
-            return asRawClient(wrapped);
+        if (typeof propertyOf(candidate, "unsafe") !== "function")
+            continue;
+        const client = asRawClient(candidate);
+        if (hasBegin(client))
+            return client;
     }
-    throw new Error("migrate-runner: db argument has no .unsafe() (need Bun.SQL or drizzle DbConnection)");
+    throw new Error("migrate-runner: db argument has no .unsafe() and .begin() (need Bun.SQL or drizzle DbConnection)");
 }
 // Raw-SQL via postgres-js or Bun.sql .unsafe() — same shape for both.
 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) {
@@ -215,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`