@cosmicdrift/kumiko-framework 0.364.0 → 0.365.1

package/dist/api/auth-routes.js

@@ -61,7 +61,7 @@ function normalizeCookieDomain(domain) {
 }
 // A malformed entry would corrupt the Set-Cookie header; an entry equal to the
 // current cookieDomain would make login delete the cookie it just sets.
-export function assertRetiredCookieDomains(retiredCookieDomains, cookieDomain) {
+function assertRetiredCookieDomains(retiredCookieDomains, cookieDomain) {
     const current = cookieDomain === undefined ? undefined : normalizeCookieDomain(cookieDomain);
     for (const entry of retiredCookieDomains ?? []) {
         if (entry === "" || normalizeCookieDomain(entry) === "") {
@@ -322,6 +322,10 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         retiredCookieDomains: config.retiredCookieDomains,
     });
     assertRetiredCookieDomains(config.retiredCookieDomains, cookieDomain);
+    if (config.mfaVerifyHandler && !config.switchTenantMfaGateHandler) {
+        throw new Error("createAuthRoutes: mfaVerifyHandler is set but switchTenantMfaGateHandler is not; " +
+            "POST /auth/switch-tenant would mint admin sessions without the second factor");
+    }
     const retiredCookieDomains = config.retiredCookieDomains ?? [];
     // Single hop-count-aware IP getter for every rate-limit call site below —
     // see AuthRoutesConfig.trustedProxyHops and client-ip.ts's resolveClientIp
@@ -330,19 +334,45 @@ export function createAuthRoutes(dispatcher, jwt, config) {
     // shared "unknown" bucket.
     const clientIpResolver = config.resolver ?? createClientIpResolver(config.trustedProxyHops ?? 0, "createAuthRoutes");
     const getClientIp = (c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
-    async function switchTenantMfaGateResponse(c, user, targetTenantId) {
+    // undefined = no gate wired (setup without MFA). "clearedRoles" are the roles the gate decided on,
+    // so the minted session cannot differ from what the gate checked.
+    async function switchTenantMfaGate(c, user, targetTenantId) {
         if (!config.switchTenantMfaGateHandler)
             return undefined;
         const gate = await dispatcher.write(config.switchTenantMfaGateHandler, { userId: user.id, tenantId: targetTenantId }, createSystemUser(user.tenantId));
         if (!gate.isSuccess) {
             const status = gate.error.httpStatus; // @cast-boundary engine-payload
-            return c.json({ isSuccess: false, error: gate.error }, status);
+            return { response: c.json({ isSuccess: false, error: gate.error }, status) };
         }
         // @cast-boundary engine-payload — the gate handler's three-shape result
         const gateData = gate.data;
         if (gateData.kind === "mfa-gate-clear")
-            return undefined;
-        return pendingMfaStepResponse(c, gateData);
+            return { clearedRoles: gateData.roles };
+        return { response: pendingMfaStepResponse(c, gateData) };
+    }
+    // Global roles (SystemAdmin etc.) come from the user feature when userQuery is wired, so they survive
+    // the tenant switch. buildSessionRoles calls stripForbiddenMembershipRoles on the membership side only — a backstop
+    // for a role a projection rebuild resurrected past command-time validation (engine/membership-roles).
+    async function resolveSwitchTenantRoles(user, membership) {
+        let globalRoles = [];
+        if (config.userQuery) {
+            try {
+                // @cast-boundary engine-payload — dispatcher.query returnt unknown,
+                // Per the AuthUserRow contract, userQuery returns a row with a roles column.
+                const userRow = (await dispatcher.query(config.userQuery, { id: user.id }, createSystemUser(user.tenantId)));
+                // roles is jsonb string[] (multiSelect); parseRoles also accepts legacy
+                // JSON-encoded text from pre-0.217.0 rows.
+                globalRoles = parseRoles(userRow?.roles ?? null);
+            }
+            catch (e) {
+                // Non-fatal: when global roles cannot be resolved the switch continues with tenant roles
+                // only. A server error carrying just the cause would hurt the UX more than a switch without
+                // SystemAdmin, which the user notices and reports.
+                if (!isUnknownHandlerError(e))
+                    throw e;
+            }
+        }
+        return buildSessionRoles(globalRoles, membership.roles);
     }
     // Shared tail of every route that ends a request logged-in: create the
     // session record (if wired), sign the JWT, set the auth+csrf cookies. Was
@@ -711,13 +741,13 @@ export function createAuthRoutes(dispatcher, jwt, config) {
             }
             // Session creation + JWT sign + cookies — see mintSessionAndRespond.
             const token = await mintSessionAndRespond(c, data.session);
-            const landingPath = landingPathFragment({
-                flow: "signup",
+            const signupOutcome = {
                 roles: data.session.roles,
                 tenantId: data.session.tenantId,
                 tenantKey: data.tenantKey,
                 ...(data.handover !== undefined && { handover: data.handover }),
-            });
+            };
+            const landingPath = landingPathFragment({ flow: "signup", ...signupOutcome });
             return c.json({
                 isSuccess: true,
                 token,
@@ -962,49 +992,20 @@ export function createAuthRoutes(dispatcher, jwt, config) {
             return switchTenantRejectionResponse(c, activeMembership.reason);
         }
         const membership = activeMembership.membership;
-        // Globale Rollen aus user-feature lesen wenn userQuery wired —
-        // tenant-unabhängige Rollen (SystemAdmin etc.) überleben so den
-        // tenant-switch. `parseRoles` liegt utils-side, hier inline-deserialize
-        // damit das Framework keine bundled-features-Imports kriegt.
-        let globalRoles = [];
-        if (config.userQuery) {
-            try {
-                // @cast-boundary engine-payload — dispatcher.query returnt unknown,
-                // userQuery liefert per AuthUserRow-Contract eine row mit roles-spalte.
-                const userRow = (await dispatcher.query(config.userQuery, { id: user.id }, createSystemUser(user.tenantId)));
-                // roles is jsonb string[] (multiSelect); parseRoles also accepts legacy
-                // JSON-encoded text from pre-0.217.0 rows.
-                globalRoles = parseRoles(userRow?.roles ?? null);
-            }
-            catch (e) {
-                // Non-fatal: globale Rollen kann nicht aufgelöst werden → switch
-                // läuft weiter mit nur tenant-rollen. Server-error mit nur dem
-                // Cause ohne Stack hochwerfen wäre für die UX schlimmer als ein
-                // Tenant-Switch ohne SystemAdmin (User merkt's und meldet's). Log
-                // it via the dispatcher so Ops sieht's.
-                if (!isUnknownHandlerError(e))
-                    throw e;
-            }
-        }
+        const gate = await switchTenantMfaGate(c, user, targetTenantId);
+        if (gate !== undefined && "response" in gate)
+            return gate.response;
+        const sessionRoles = gate !== undefined ? gate.clearedRoles : await resolveSwitchTenantRoles(user, membership);
         // Issue new JWT with the target tenant and its roles. Claims MUST be
         // recomputed for the new tenant — stale claims from the previous
         // tenant would leak identity facts across tenancies (e.g. teamId from
         // tenant A accidentally surviving into tenant B's session). The
         // resolver runs each feature's r.authClaims() hook under the new
         // TenantDb scope.
-        // buildSessionRoles calls stripForbiddenMembershipRoles internally and
-        // strips reserved roles from the membership side only — globalRoles
-        // (where SystemAdmin legitimately lives) is never filtered. Backstop for a
-        // membership role that a projection rebuild resurrected past command-time
-        // validation (see engine/membership-roles).
-        const mergedRoles = buildSessionRoles(globalRoles, membership.roles);
-        const pendingMfaStep = await switchTenantMfaGateResponse(c, user, targetTenantId);
-        if (pendingMfaStep !== undefined)
-            return pendingMfaStep;
         const targetSession = {
             id: user.id,
             tenantId: targetTenantId,
-            roles: mergedRoles,
+            roles: sessionRoles,
             // Tenant-independent prefs must survive the switch (fw#2343).
             ...tenantIndependentPrefs(user),
         };
@@ -1023,7 +1024,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         // fresh csrfToken is minted (inside the helper) so a compromised csrf-
         // value can't cross a tenant boundary.
         const newToken = await mintSessionAndRespond(c, sessionForJwt);
-        return c.json({ token: newToken, tenantId: targetTenantId, roles: mergedRoles });
+        return c.json({ token: newToken, tenantId: targetTenantId, roles: sessionRoles });
     });
     return api;
 }

package/dist/api/index.d.ts

@@ -26,7 +26,7 @@ export type { MetricsRouteOptions } from "./route-registrars.js";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
 export type { KumikoServer, ServerOptions } from "./server.js";
-export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, } from "./server.js";
+export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.js";
 export type { ResolvedSessionCookies, SessionCookieBase, SessionCookieNames, } from "./session-cookies.js";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.js";
 export type { SseBroker, SseClient, SseEvent } from "./sse-broker.js";

package/dist/api/index.js

@@ -15,7 +15,7 @@ export { readonlyRequestContext as requestContext, } from "./request-context.js"
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
-export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, } from "./server.js";
+export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.js";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.js";
 export { createSseBroker } from "./sse-broker.js";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";

package/dist/api/server.d.ts

@@ -1,6 +1,6 @@
 import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import { Hono } from "hono";
-import type { PgClient } from "../db/connection.js";
+import type { PgListenClient } from "../db/connection.js";
 import { type AppContext, type Registry, type RunIn, type WriteResult } from "../engine/types/index.js";
 import type { ErrorDocsConfig } from "../errors/docs-url.js";
 import type { Lifecycle } from "../lifecycle/index.js";
@@ -43,7 +43,7 @@ export type ServerOptions = {
             jobTrigger?: boolean;
             accessInvalidation?: boolean;
         };
-        pgClient?: PgClient;
+        pgClient?: PgListenClient;
     };
     observability?: ObservabilityProvider;
     observabilityOptions?: ObservabilityOptions;

package/dist/api/server.js

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import { ROLES } from "../auth/roles.js";
-import { createTenantDb } from "../db/tenant-db.js";
+import { createProjectingTenantDb } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { buildAppSchema } from "../engine/build-app-schema.js";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
@@ -69,6 +69,24 @@ export function withFileProviderResolver(registry, context, cacheSync) {
         }),
     };
 }
+// A payload-bucket handler without a resolver would answer every call with a
+// 500 at request time; fail at boot instead.
+function assertNoPayloadRateLimitsWithoutResolver(registry) {
+    const offenders = [];
+    for (const feature of registry.features.values()) {
+        for (const [name, handler] of Object.entries(feature.writeHandlers)) {
+            if (handler.additionalRateLimits !== undefined) {
+                offenders.push(`${feature.name}:write:${name}`);
+            }
+        }
+    }
+    // skip: every handler's payload buckets are covered by the resolver
+    if (offenders.length === 0)
+        return;
+    throw new Error(`Handlers declare additionalRateLimits but no RateLimitResolver is configured: ${offenders.join(", ")}. ` +
+        "Wire a Redis client on context.redis (or pass context.rateLimit), or drop the payload buckets " +
+        "(for the waitlist: emailRateLimits: []).");
+}
 export function buildServer(options) {
     assertSeedModeNotInProduction();
     // Single effective hop-count for every IP-derived rate-limit + requestMeta
@@ -221,6 +239,7 @@ export function buildServer(options) {
     const rateLimitResolver = options.context.rateLimit ??
         (wrappedRedis && wantsResolver ? createRateLimitResolver({ redis: wrappedRedis }) : undefined);
     if (!rateLimitResolver) {
+        assertNoPayloadRateLimitsWithoutResolver(options.registry);
         // The systemScope default limit only exists once a resolver does, and an app that
         // declared no explicit rateLimit anywhere never gets one auto-wired (wantsL3 stays
         // false) — so its cross-tenant handlers are silently unlimited.
@@ -291,6 +310,13 @@ export function buildServer(options) {
     const searchConsumerEnabled = options.eventDispatcher?.systemConsumers?.search ?? true;
     const jobTriggerConsumerEnabled = options.eventDispatcher?.systemConsumers?.jobTrigger ?? true;
     const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
+    const mspJobs = jobRunnerForTriggers?.dispatch
+        ? {
+            dispatch: async (jobName, payload, dispatchOptions) => {
+                await jobRunnerForTriggers.dispatch?.(jobName, payload, dispatchOptions);
+            },
+        }
+        : undefined;
     const systemConsumers = [];
     if (sseConsumerEnabled) {
         systemConsumers.push(createSseBroadcastEventConsumer(sseBroker));
@@ -372,6 +398,7 @@ export function buildServer(options) {
                 ...(mspOwner && { callerFeature: mspOwner }),
                 ...(mspFiles && { files: mspFiles }),
                 ...(contextWithObservability.secrets && { secrets: contextWithObservability.secrets }),
+                ...(mspJobs && { jobs: mspJobs }),
                 ...(mspFiles && {
                     derivatives: createDerivativesContext({
                         files: mspFiles,
@@ -696,9 +723,7 @@ export function buildServer(options) {
             canWriteRecord: createRecordWriteCheck({
                 registry: options.registry,
                 canReadRecord,
-                tenantDbFor: (tenantId) => createTenantDb(fileDb, tenantId, "tenant", undefined, undefined, undefined, {
-                    projectionRegistry: options.registry,
-                }),
+                tenantDbFor: (tenantId) => createProjectingTenantDb(fileDb, tenantId, options.registry),
             }),
             ...(routeOptions.accessGuard ? { accessGuard: routeOptions.accessGuard } : {}),
             ...(routeOptions.privilegedRoles ? { privilegedRoles: routeOptions.privilegedRoles } : {}),

package/dist/bun-db/connection.js

@@ -3,10 +3,8 @@
 // nach drizzle-removal. Erstellt parallel zum legacy `db/connection.ts`
 // — apps migrieren schritt-für-schritt, alte Datei weg sobald 0 Konsumenten.
 //
-// **postgres-js** bleibt als kleiner Peer NUR für LISTEN/NOTIFY in
-// event-dispatcher.ts. Bun.sql 1.2.20 hat kein listen() (PR oven-sh/bun#25511
-// pending). Nach Landung des Bun-LISTEN-Supports: peer raus.
-import postgres from "postgres";
+// LISTEN for the event dispatcher uses Bun.SQL's listen() on its own
+// dedicated connection, outside the pool's idleTimeout.
 import { readPositiveIntEnv } from "../utils/env-parse.js";
 export function createBunDbConnection(url, options = {}) {
     const bunOpts = {};
@@ -18,22 +16,11 @@ export function createBunDbConnection(url, options = {}) {
         bunOpts.connectionTimeout = options.connectTimeoutSeconds;
     }
     const db = new Bun.SQL(url, bunOpts);
-    // LISTEN-only peer — minimal pool (1 connection reicht), eigener idle/
-    // connect-timeout falls gesetzt. Wenn das wegfällt, läuft event-dispatcher
-    // auf polling-only ohne LISTEN-Wakeup.
-    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);
     return {
         db,
-        listenClient,
+        listenClient: db,
         close: async () => {
             await db.end();
-            await listenClient.end();
         },
     };
 }

package/dist/bun-db/index.d.ts

@@ -1,4 +1,4 @@
 export type { BunDbConnection, BunDbConnectionOptions, BunDbRunner, BunDbTx, PgListenClient, } from "./connection.js";
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection.js";
 export type { InnerJoinRow, InnerJoinSpec, InsertOnConflictDoNothingOptions, JoinColumnPair, JsonTextMatch, SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue, } from "./query.js";
-export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, instantToTimestamptzParam, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/bun-db/index.js

@@ -1,4 +1,4 @@
 // bun-db: Bun.sql-basierte DB-API ohne drizzle.
 // Production-Pfad nach drizzle-removal.
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection.js";
-export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, instantToTimestamptzParam, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/bun-db/query.d.ts

@@ -1,4 +1,5 @@
 import type { AggregateRow, AggregateSpec } from "@cosmicdrift/kumiko-types/aggregate-types";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { SelectOptions, WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
 import type { EntityTableMeta } from "../db/entity-table-meta.js";
 import { type NotExecutorOnly } from "../db/table-builder.js";
@@ -6,11 +7,16 @@ import { asEntityTableMeta, requireEntityTableMeta } from "../db/table-introspec
 import type { DbRunner } from "@cosmicdrift/kumiko-types/db-connection";
 import type { BunDbRunner } from "./connection.js";
 export { asEntityTableMeta, requireEntityTableMeta };
+export type ReservedClient = {
+    unsafe: RawClient["unsafe"];
+    release: () => unknown;
+};
 export type RawClient = {
     unsafe: <TRow = unknown>(sql: string, params?: readonly unknown[]) => Promise<readonly TRow[]>;
     begin?: <T>(fn: (tx: BunDbRunner) => Promise<T>) => Promise<T>;
     savepoint?: <T>(fn: (sp: unknown) => Promise<T>) => Promise<T>;
     release?: unknown;
+    reserve?: () => Promise<ReservedClient>;
 };
 export type RawClientWithBegin = RawClient & {
     begin: NonNullable<RawClient["begin"]>;
@@ -34,6 +40,7 @@ export type TableInfo = {
 };
 export declare function extractTableInfo(table: TableLike): TableInfo;
 export declare function coerceRow<TOut = Record<string, unknown>>(row: Record<string, unknown>, info: TableInfo): TOut;
+export declare function instantToTimestamptzParam(instant: Temporal.Instant): string;
 export declare function isClosedConnectionError(err: unknown): boolean;
 export declare function describeClosedConnectionFailure(raw: unknown, err: unknown, attempts: number): Record<string, unknown> | undefined;
 export declare function unsafeReadRetrying<TRow>(db: AnyDb, sqlText: string, params: readonly unknown[]): Promise<readonly TRow[]>;

package/dist/bun-db/query.js

@@ -51,7 +51,8 @@ function snakeToCamel(key) {
 // the only collision-safe path.
 export { asEntityTableMeta, requireEntityTableMeta };
 export function hasBegin(client) {
-    return typeof client.begin === "function";
+    // Bun.SQL tx/savepoint handles keep a begin() that throws; only savepoint() tells them apart from a pool.
+    return typeof client.begin === "function" && typeof client.savepoint !== "function";
 }
 function isRawClient(value) {
     return typeof propertyOf(value, "unsafe") === "function";
@@ -113,16 +114,27 @@ export async function runInSavepointIfSupported(db, fn) {
     const asRunner = (sp) => sp;
     if (typeof raw.savepoint !== "function")
         return fn(asRunner(db));
+    // An error from inside fn must never be remapped, even if it carries a closed-connection code.
+    let fnStarted = false;
     try {
-        return await raw.savepoint((sp) => fn(asRunner(sp)));
+        return await raw.savepoint((sp) => {
+            fnStarted = true;
+            return fn(asRunner(sp));
+        });
     }
     catch (e) {
-        if (extractPgError(e)?.code === "25P01") {
+        const code = extractPgError(e)?.code;
+        if (!fnStarted && (code === "25P01" || code === "ERR_POSTGRES_CONNECTION_CLOSED")) {
             throw new InternalError({
-                message: "runInSavepointIfSupported: savepoint on a transaction that has already committed — " +
-                    "this is almost always database work in an afterCommit hook. afterCommit is the default " +
-                    "phase of r.hook/postSave/postDelete. Use HookPhases.inTransaction for writes that must " +
-                    "roll back with the trigger, or ctx.dbOutsideTransaction for work that must survive a rollback.",
+                message: code === "25P01"
+                    ? "runInSavepointIfSupported: savepoint on a transaction that has already committed — " +
+                        "this is almost always database work in an afterCommit hook. afterCommit is the default " +
+                        "phase of r.hook/postSave/postDelete. Use HookPhases.inTransaction for writes that must " +
+                        "roll back with the trigger, or ctx.dbOutsideTransaction for work that must survive a rollback."
+                    : "runInSavepointIfSupported: the transaction handle's connection is gone — the transaction " +
+                        "already committed (almost always database work in an afterCommit hook) or the connection dropped. " +
+                        "afterCommit is the default phase of r.hook/postSave/postDelete. Use HookPhases.inTransaction " +
+                        "for writes that must roll back with the trigger, or ctx.dbOutsideTransaction for work that must survive a rollback.",
                 cause: e instanceof Error ? e : undefined,
             });
         }
@@ -216,13 +228,8 @@ function quoteIdent(name) {
 //
 // Symmetric on write: Temporal.Instant doesn't bind directly into postgres-js
 // params — convert to ISO string when the column pgType is timestamptz.
-function toStringTagOf(v) {
-    return typeof v === "object" && v !== null && Symbol.toStringTag in v
-        ? v[Symbol.toStringTag]
-        : undefined;
-}
 function isTemporalInstant(v) {
-    return toStringTagOf(v) === "Temporal.Instant";
+    return propertyOf(v, Symbol.toStringTag) === "Temporal.Instant";
 }
 // Postgres bigint → JS: safe integers become `number` (matches createBigIntField /
 // drizzle mode:"number"); values outside ±2^53 stay `bigint` (money cents, raw
@@ -272,10 +279,10 @@ function instantFromDriver(value) {
     return null;
 }
 function isTemporalPlainDate(v) {
-    return toStringTagOf(v) === "Temporal.PlainDate";
+    return propertyOf(v, Symbol.toStringTag) === "Temporal.PlainDate";
 }
 function isTemporalPlainDateTimeLike(v) {
-    const tag = toStringTagOf(v);
+    const tag = propertyOf(v, Symbol.toStringTag);
     return ((tag === "Temporal.PlainDateTime" || tag === "Temporal.ZonedDateTime") &&
         typeof v === "object" &&
         v !== null &&
@@ -459,6 +466,31 @@ function prepareJsonbValue(value) {
     }
     return { kind: "param", sql: "::jsonb", bound: value };
 }
+const INTEGER_PG_TYPES = new Set([
+    "integer",
+    "int4",
+    "smallint",
+    "int2",
+    "bigint",
+    "int8",
+    "serial",
+    "bigserial",
+]);
+// postgres.js truncates timestamptz params to ms via Date; Bun.SQL sends µs and Postgres
+// rounds into timestamptz(3). Truncating here keeps both drivers storing the same instant.
+export function instantToTimestamptzParam(instant) {
+    return Temporal.Instant.fromEpochMilliseconds(instant.epochMilliseconds).toString();
+}
+function prepareDriverNeutralScalar(value, pgType) {
+    if ((pgType === "timestamptz" || pgType === "timestamptz(3)") && isTemporalInstant(value)) {
+        return { kind: "param", sql: "", bound: instantToTimestamptzParam(value) };
+    }
+    // Bun.SQL binds JS numbers typed, so Postgres would round 3.5 into an integer column; postgres.js sends text and rejects it.
+    if (typeof value === "number" && pgType !== undefined && INTEGER_PG_TYPES.has(pgType)) {
+        return { kind: "param", sql: "", bound: String(value) };
+    }
+    return undefined;
+}
 function prepareValue(value, pgType) {
     if (isSqlExpression(value)) {
         return { kind: "literal", literal: value.text };
@@ -473,9 +505,9 @@ function prepareValue(value, pgType) {
         if (prepared)
             return prepared;
     }
-    if ((pgType === "timestamptz" || pgType === "timestamptz(3)") && isTemporalInstant(value)) {
-        return { kind: "param", sql: "", bound: value.toString() };
-    }
+    const scalar = prepareDriverNeutralScalar(value, pgType);
+    if (scalar)
+        return scalar;
     if (pgType === "date") {
         const prepared = prepareDateValue(value);
         if (prepared)

package/dist/crypto/in-memory-kms-adapter.js

@@ -1,7 +1,8 @@
 import { randomBytes } from "node:crypto";
 import { KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, subjectIdToKey, } from "./kms-adapter.js";
 // Non-persistent adapter for tests and dev mode. Erased entries stay as
-// tombstones so the create-after-erase contract holds within a process.
+// tombstones (also for never-keyed subjects) so the create-after-erase
+// contract holds within a process.
 export class InMemoryKmsAdapter {
     capabilities = { mode: "local-key" };
     keys = new Map();
@@ -20,12 +21,8 @@ export class InMemoryKmsAdapter {
         return entry.key;
     }
     async eraseKey(subject) {
-        const entry = this.keys.get(subjectIdToKey(subject));
-        // skip: eraseKey is contractually idempotent — unknown subject is a no-op
-        if (!entry)
-            return;
-        entry.key = null;
-        entry.erased = true;
+        // A never-keyed subject gets a tombstone too, so createKey cannot mint one later.
+        this.keys.set(subjectIdToKey(subject), { key: null, erased: true });
     }
     async health() {
         return { ok: true, latencyMs: 0 };

package/dist/crypto/owner-transition-rekey.d.ts

@@ -1,2 +1,3 @@
 import type { EntityDefinition } from "../engine/types/fields.js";
+export declare function isPlainUserOwnedField(field: EntityDefinition["fields"][string]): boolean;
 export declare function personalFieldsRekeyedOnOwnerTransition(entity: EntityDefinition, previous: Record<string, unknown>, mergedNew: Record<string, unknown>, submittedChanges: Record<string, unknown>): Record<string, unknown>;

package/dist/crypto/owner-transition-rekey.js

@@ -1,6 +1,12 @@
 import { PII_ERASED_SENTINEL } from "./kms-adapter.js";
 import { isPiiCiphertext } from "./pii-ciphertext-format.js";
 import { nonEmptyString } from "./subject-resolver.js";
+// userOwned and not recordOwned: the value follows the row's current owner.
+export function isPlainUserOwnedField(field) {
+    if (!("userOwned" in field) || field.userOwned === undefined)
+        return false;
+    return !("recordOwned" in field && field.recordOwned === true);
+}
 // Personal fields keep their stored value when an update moves the row to a
 // new owner, so without re-keying they would stay shreddable only by the old
 // owner. Returns the unchanged-by-the-caller values that must be written again
@@ -9,9 +15,7 @@ import { nonEmptyString } from "./subject-resolver.js";
 export function personalFieldsRekeyedOnOwnerTransition(entity, previous, mergedNew, submittedChanges) {
     const rekeyed = {};
     for (const [name, field] of Object.entries(entity.fields)) {
-        if (!("userOwned" in field) || field.userOwned === undefined)
-            continue;
-        if ("recordOwned" in field && field.recordOwned === true)
+        if (!isPlainUserOwnedField(field) || !("userOwned" in field) || !field.userOwned)
             continue;
         if (name in submittedChanges)
             continue;

package/dist/crypto/pg-kms-adapter.js

@@ -107,15 +107,19 @@ export class PgKmsAdapter {
     }
     async eraseKey(subject, ctx) {
         await this.ensureSchema();
-        // Guard on erased_at IS NULL keeps repeat erases from overwriting the
-        // original tombstone audit fields; unknown subjects update zero rows.
+        // Upsert: a never-keyed subject (pre-KMS plaintext) still gets a tombstone,
+        // so a later createKey cannot mint a fresh key and re-encrypt the plaintext.
+        // The erased_at IS NULL guard keeps repeat erases from overwriting the
+        // original tombstone audit fields.
         await this.sql `
-      UPDATE kumiko_subject_keys
+      INSERT INTO kumiko_subject_keys (subject_id, cipher_key, kek_version, erased_at, erased_by, erase_reason)
+      VALUES (${subjectIdToKey(subject)}, NULL, ${this.kekVersion}, now(), ${ctx.userId ?? null}, ${ctx.eraseReason ?? null})
+      ON CONFLICT (subject_id) DO UPDATE
       SET cipher_key = NULL,
           erased_at = now(),
-          erased_by = ${ctx.userId ?? null},
-          erase_reason = ${ctx.eraseReason ?? null}
-      WHERE subject_id = ${subjectIdToKey(subject)} AND erased_at IS NULL`;
+          erased_by = EXCLUDED.erased_by,
+          erase_reason = EXCLUDED.erase_reason
+      WHERE kumiko_subject_keys.erased_at IS NULL`;
     }
     async health() {
         const start = Date.now();

package/dist/crypto/pii-field-encryption.d.ts

@@ -13,6 +13,7 @@ export interface EncryptPiiOptions {
     readonly subjectSource?: Record<string, unknown>;
     readonly entityName: string;
     readonly ownerFallback?: Record<string, unknown>;
+    readonly onErasedSubject?: "sentinel";
 }
 export type PiiEncryptedRow<TRow extends Record<string, unknown>> = {
     [K in keyof TRow]: TRow[K] extends string ? string : TRow[K] | string;

package/dist/crypto/pii-field-encryption.js

@@ -161,8 +161,15 @@ export async function encryptPiiFieldValues(row, entity, piiFields, kms, kmsCtx,
         // skip: collectPiiSubjectFields only yields annotated fields — null is unreachable, kept as a type guard
         if (subject === null)
             continue;
-        const dek = await getOrCreateDek(kms, subject, kmsCtx);
-        out[name] = encryptValue(subject, dek, plaintext, name, isJsonbField);
+        try {
+            const dek = await getOrCreateDek(kms, subject, kmsCtx);
+            out[name] = encryptValue(subject, dek, plaintext, name, isJsonbField);
+        }
+        catch (e) {
+            if (!(e instanceof KeyErasedError) || opts.onErasedSubject !== "sentinel")
+                throw e;
+            out[name] = PII_ERASED_SENTINEL;
+        }
     }
     return out;
 }

package/dist/crypto/subject-resolver.d.ts

@@ -30,5 +30,6 @@ export interface EventSubjectEnvelope {
 export declare function resolveEventSubject(fieldName: string, spec: EventPiiSubject, payload: Record<string, unknown>, envelope: EventSubjectEnvelope): SubjectId | null;
 export declare function collectPiiSubjectFields(entity: EntityDefinition): readonly string[];
 export declare function collectPiiEncryptedFields(entity: EntityDefinition): readonly string[];
+export declare function collectPiiFileReferenceFields(entity: EntityDefinition): readonly string[];
 /** Subject-annotated fields that may be plaintext in the derived search index (#1610). */
 export declare function collectSearchableSubjectFields(entity: EntityDefinition): readonly string[];

package/dist/crypto/subject-resolver.js

@@ -155,6 +155,13 @@ export function collectPiiEncryptedFields(entity) {
         .filter(([, field]) => hasSubjectAnnotation(field) && !isFileReferenceField(field))
         .map(([name]) => name);
 }
+// The annotated file-reference fields: never ciphertext today, but events from the
+// old backfill (which encrypted them) still carry it and must replay.
+export function collectPiiFileReferenceFields(entity) {
+    return Object.entries(entity.fields)
+        .filter(([, field]) => hasSubjectAnnotation(field) && isFileReferenceField(field))
+        .map(([name]) => name);
+}
 /** Subject-annotated fields that may be plaintext in the derived search index (#1610). */
 export function collectSearchableSubjectFields(entity) {
     return Object.entries(entity.fields)

package/dist/db/api.d.ts

@@ -1,3 +1,4 @@
+import type { PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
 export type DbConnectionOptions = {
     readonly maxConnections?: number;
     readonly idleTimeoutSeconds?: number;
@@ -8,10 +9,10 @@ export declare const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;
 export type DbPoolHandle = {
     /** Provider Connection — Calls gehen über asRawClient() oder direkt. */
     readonly db: any;
-    /** Legacy postgres-js Client (für LISTEN peer) */
+    /** Raw driver client (postgres-js or Bun.SQL) */
     readonly client: any;
-    /** Optionaler Bun.SQL LISTEN peer */
-    readonly listenClient?: any;
+    /** LISTEN-capable client; Bun.SQL serves it from its own dedicated connection */
+    readonly listenClient?: PgListenClient;
     /** Pool schliessen */
     close: () => Promise<void>;
 };