@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

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
@@ -217,12 +235,11 @@ export function buildServer(options) {
     // Master for the payload-bucket HMAC: the current signing secret (the
     // keyring's signKid for rotation setups). buildServer always has one, so
     // the digest is available whenever a handler declares additionalRateLimits.
-    const payloadDigest = createPayloadDigest(typeof options.jwtSecret === "string"
-        ? options.jwtSecret
-        : (options.jwtSecret.keys[options.jwtSecret.signKid] ?? ""));
+    const payloadDigest = createPayloadDigest(payloadDigestMasterSecret(options.jwtSecret));
     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.
@@ -698,9 +715,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 } : {}),
@@ -836,9 +851,7 @@ export function buildServer(options) {
                 dispatchSystemQuery,
                 clientIpResolver,
             });
-            mountHonoRoute(app, route.method, route.path, honoHandler, route.entry === ExtraRouteEntries.signature
-                ? bodyLimitForRoutePath(route.path, options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES)
-                : []);
+            mountHonoRoute(app, route.method, route.path, honoHandler, bodyLimitForRoutePath(route.path, options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES));
         }
     }
     // /version-Default registriert NACH feature-routes — Hono "first match
@@ -949,6 +962,13 @@ c, dispatcher, clientIpResolver) {
 export function makeDispatchSystemWrite(dispatcher) {
     return ({ handlerQn, payload, tenantId }) => dispatcher.write(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
 }
+// Privilege-scope: the system user gets exactly the roles the caller names —
+// no implicit SystemAdmin — so a seed can write data gated on app roles.
+// Same trust requirement as makeDispatchSystemWrite: never expose to a raw
+// request, only to code that already proved its own authenticity.
+export function makeDispatchWriteAs(dispatcher) {
+    return ({ handlerQn, payload, tenantId, roles }) => dispatcher.write(handlerQn, payload, createSystemUser(tenantId, roles));
+}
 export function makeDispatchSystemQuery(dispatcher) {
     return ({ handlerQn, payload, tenantId }) => dispatcher.query(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
 }
@@ -1199,3 +1219,12 @@ function entitiesWithSearchableScreen(registry) {
     }
     return [...entities];
 }
+function payloadDigestMasterSecret(jwtSecret) {
+    if (typeof jwtSecret === "string")
+        return jwtSecret;
+    const signingSecret = jwtSecret.keys[jwtSecret.signKid];
+    if (signingSecret === undefined) {
+        throw new Error(`[kumiko] jwtSecret.signKid "${jwtSecret.signKid}" not found in jwtSecret.keys`);
+    }
+    return signingSecret;
+}

package/dist/api/session-cookies.d.ts

@@ -19,5 +19,6 @@ export declare function hostOnlyDeleteOptions(name: string): {
     path: "/";
     secure?: true;
 };
+export declare function expireLegacySessionCookieVariants(c: Context, cookies: ResolvedSessionCookies): void;
 export declare function clearSessionCookies(c: Context, cookies: ResolvedSessionCookies): void;
 export declare function hasDuplicateSessionCookie(c: Context, names: SessionCookieNames): boolean;

package/dist/api/session-cookies.js

@@ -1,4 +1,4 @@
-import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, isHostPrefixedCookieName, resolveSessionCookieNames, } from "@cosmicdrift/kumiko-types/session-cookies";
+import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, isHostPrefixedCookieName, resolveSessionCookieNames, sessionCookieName, } from "@cosmicdrift/kumiko-types/session-cookies";
 import { deleteCookie } from "hono/cookie";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, sessionCookieName, TENANT_COOKIE_BASE, } from "@cosmicdrift/kumiko-types/session-cookies";
 const SESSION_COOKIES_KEY = "sessionCookies";
@@ -41,6 +41,24 @@ export function getSessionCookies(c, fallback) {
 export function hostOnlyDeleteOptions(name) {
     return isHostPrefixedCookieName(name) ? { path: "/", secure: true } : { path: "/" };
 }
+// Expires the name variant the current config does not write, in both
+// directions: unprefixed leftovers when names are `__Host-` prefixed, and the
+// `__Host-` cookies when a later cookieDomain or secureCookies:false resolves
+// to unprefixed names. Browsers prefer the prefixed csrf cookie when reading
+// the token, so a leftover one would 403 every write until it expires.
+export function expireLegacySessionCookieVariants(c, cookies) {
+    if (isHostPrefixedCookieName(cookies.names.auth)) {
+        deleteCookie(c, AUTH_COOKIE_BASE, { path: "/" });
+        deleteCookie(c, CSRF_COOKIE_BASE, { path: "/" });
+        // skip: the unprefixed names are the only legacy variant when the config writes __Host- names.
+        return;
+    }
+    if (cookies.secure) {
+        deleteCookie(c, sessionCookieName(AUTH_COOKIE_BASE, { secure: true }), hostPrefixedDelete);
+        deleteCookie(c, sessionCookieName(CSRF_COOKIE_BASE, { secure: true }), hostPrefixedDelete);
+    }
+}
+const hostPrefixedDelete = { path: "/", secure: true };
 // Expire every variant: the Domain cookie (current) and the host-only one
 // (from before cookieDomain), otherwise a cookie left over from an earlier
 // config keeps the session alive after logout. With __Host- names the
@@ -50,10 +68,7 @@ export function clearSessionCookies(c, cookies) {
     const { names, domain } = cookies;
     deleteCookie(c, names.auth, hostOnlyDeleteOptions(names.auth));
     deleteCookie(c, names.csrf, hostOnlyDeleteOptions(names.csrf));
-    if (isHostPrefixedCookieName(names.auth)) {
-        deleteCookie(c, AUTH_COOKIE_BASE, { path: "/" });
-        deleteCookie(c, CSRF_COOKIE_BASE, { path: "/" });
-    }
+    expireLegacySessionCookieVariants(c, cookies);
     if (domain !== undefined) {
         deleteCookie(c, AUTH_COOKIE_BASE, { path: "/", domain });
         deleteCookie(c, CSRF_COOKIE_BASE, { path: "/", domain });

package/dist/api/sse-route.js

@@ -3,7 +3,8 @@ import { streamSSE } from "hono/streaming";
 import { tenantChannel } from "../engine/constants.js";
 import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { Routes } from "./api-constants.js";
-import { getAuthTokenExpiry, getUser } from "./auth-middleware.js";
+import { getAuthTokenExpiry, getStaleCredentialCode, getUser } from "./auth-middleware.js";
+import { clearSessionCookies, getSessionCookies } from "./session-cookies.js";
 import { accessInvalidationCredentialFor } from "./sse-broker.js";
 import { scheduleTokenExpiry } from "./token-expiry-timer.js";
 /**
@@ -35,6 +36,10 @@ export const SSE_HEARTBEAT_INTERVAL_MS = 15_000;
 function isEntityEventData(data) {
     return typeof data["aggregateType"] === "string";
 }
+// First frame on a stream that was downgraded to anonymous because the browser's auth
+// cookie is stale. A downgraded stream answers 200, so EventSource never reports the
+// session end by itself.
+const SESSION_ENDED_SSE_EVENT = "session-ended";
 // Whitelist, never a spread: the wire frame is a signal without field
 // values even if a broker or pusher put a payload into event.data.
 function toEntitySignalWire(event, data) {
@@ -92,7 +97,17 @@ export function createSseRoute(broker, options) {
         // JWT expiry raises no access-invalidation event, so the stream must end
         // itself when the token it was opened with expires.
         const tokenExpiresAtSec = getAuthTokenExpiry(c);
+        const staleCredentialCode = getStaleCredentialCode(c);
+        // JS cannot remove the HttpOnly auth cookie, so the response does.
+        if (staleCredentialCode !== undefined)
+            clearSessionCookies(c, getSessionCookies(c));
         return streamSSE(c, async (stream) => {
+            if (staleCredentialCode !== undefined) {
+                await stream.writeSSE({
+                    event: SESSION_ENDED_SSE_EVENT,
+                    data: JSON.stringify({ code: staleCredentialCode }),
+                });
+            }
             let resolveEnded;
             const ended = new Promise((resolve) => {
                 resolveEnded = resolve;

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, 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, 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,13 +7,23 @@ 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 };
-type RawClient = {
+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>;
+    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"]>;
 };
+export declare function hasBegin(client: RawClient): client is RawClientWithBegin;
 export declare function asRawClient(db: unknown): RawClient;
+export declare function runnerCanBeginTransaction(db: unknown): boolean;
 export declare function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T>;
 export declare function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
 export type AnyDb = BunDbRunner | unknown;
@@ -28,7 +39,8 @@ export type TableInfo = {
     readonly hasColumn: (fieldOrColumn: string) => boolean;
 };
 export declare function extractTableInfo(table: TableLike): TableInfo;
-export declare function coerceRow<T>(row: T, info: TableInfo): T;
+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

@@ -21,7 +21,7 @@
 // Static import (not getTemporal()): coercion works without an installed
 // global and returns the same Temporal classes as the rest of the repo (#1480).
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { isOneOf, isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { isOneOf, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { requestContext } from "../api/request-context.js";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
 import { isPiiCiphertext } from "../crypto/pii-ciphertext-format.js";
@@ -50,6 +50,10 @@ function snakeToCamel(key) {
 // would overwrite the matching meta key — reading the meta from the symbol is
 // the only collision-safe path.
 export { asEntityTableMeta, requireEntityTableMeta };
+export function hasBegin(client) {
+    // 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";
 }
@@ -77,6 +81,9 @@ export function asRawClient(db) {
         return sessionClient;
     throw new Error("bun-db: db argument has no .unsafe() — pass Bun.SQL, postgres-js Sql, or a transaction handle.");
 }
+export function runnerCanBeginTransaction(db) {
+    return hasBegin(asRawClient(db));
+}
 // postgres.js / Bun.SQL reject the WHOLE begin() when any statement inside
 // it errored — even if the JS error was caught (the driver tracks per-block
 // query failures). Error confinement therefore must go through the driver's
@@ -107,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,
             });
         }
@@ -210,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
@@ -266,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 &&
@@ -329,8 +342,10 @@ function plainDateFromDriver(value, column) {
 //
 // Unknown columns (computed/aliased) pass through unchanged.
 export function coerceRow(row, info) {
-    if (!isPlainObject(row))
-        return row;
+    // @cast-boundary db-row — the driver row (raw column names/types) becomes the caller's entity row shape here, and only here
+    return coerceDriverRow(row, info);
+}
+function coerceDriverRow(row, info) {
     const out = {};
     let changed = false;
     for (const key of Object.keys(row)) {
@@ -400,7 +415,7 @@ export function coerceRow(row, info) {
             changed = true;
         out[fieldName] = coerced;
     }
-    return (changed ? out : row);
+    return changed ? out : row;
 }
 function coerceRows(rows, info) {
     return rows.map((r) => coerceRow(r, info));
@@ -451,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 };
@@ -465,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)
@@ -547,8 +587,14 @@ function buildWhereClause(info, where, startIndex, qualifier) {
                     throw new Error(`where: jsonText requires a jsonb column, "${col}" is ${pgType}`);
                 }
                 const matches = isJsonTextMatchList(value.jsonText) ? value.jsonText : [value.jsonText];
+                if (matches.length === 0) {
+                    conditions.push("FALSE");
+                    continue;
+                }
                 for (const match of matches) {
-                    if (!Array.isArray(match.keys) ||
+                    if (match === null ||
+                        typeof match !== "object" ||
+                        !Array.isArray(match.keys) ||
                         match.keys.length === 0 ||
                         !match.keys.every((k) => typeof k === "string") ||
                         typeof match.eq !== "string") {
@@ -1376,12 +1422,18 @@ export async function deleteManyBatched(db, table, where, options) {
     return { deleted, batches };
 }
 export async function transaction(db, fn) {
-    return asRawClient(db).begin(fn);
+    const raw = asRawClient(db);
+    if (!hasBegin(raw)) {
+        throw new InternalError({
+            message: "transaction: runner has no begin() — already inside a transaction or savepoint.",
+        });
+    }
+    return raw.begin(fn);
 }
 // A tx/savepoint handle has no begin(); fail closed instead of nesting silently or TypeError-ing.
 export async function runInNewTransaction(db, fn) {
     const raw = asRawClient(db);
-    if (typeof raw.begin !== "function") {
+    if (!hasBegin(raw)) {
         throw new InternalError({
             message: "runInNewTransaction: runner has no begin() — already inside a transaction or savepoint.",
         });

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/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>;
 };

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.