@cosmicdrift/kumiko-framework 0.388.0 → 0.389.0

package/dist/db/executor-managed-tables.js

@@ -20,7 +20,7 @@ export function registerExecutorManagedWriteRunner(runner) {
     executorManagedWriteRunners.add(runner);
 }
 // WeakSet.has never reads a property off runner, so a fail-closed guard Proxy stays untouched.
-// postgres.js clients are callable (tagged templates), so a runner can be a function.
+// Bun.SQL clients are callable (tagged templates), so a runner can be a function.
 export function hasExecutorManagedWriteCapability(runner) {
     if (typeof runner !== "object" && typeof runner !== "function")
         return false;

package/dist/db/index.d.ts

@@ -26,7 +26,7 @@ export { flattenLocatedTimestamp, type LocatedTimestampRead, rehydrateLocatedTim
 export { assertUniqueTableNames, assertValidMigrationName, diffSnapshots, type GenerateMigrationInput, type GenerateMigrationOutput, generateMigration, loadSnapshotJson, renderMigrationSql, type SchemaDiff, type Snapshot, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.ts";
 export { type AppliedMigration, type ApplyResult, type BaselineResult, baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, type Migration, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.ts";
 export { flattenMoney, type MoneyRead, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.ts";
-export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, type PgErrorInfo, } from "./pg-error.ts";
+export { constraintOf, extractPgError, isTableAlreadyExists, isUndefinedTable, isUniqueViolation, type PgErrorInfo, } from "./pg-error.ts";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.ts";
 export { readDatabaseNow } from "./queries/database-now.ts";
 export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.ts";

package/dist/db/index.js

@@ -20,7 +20,7 @@ export { flattenLocatedTimestamp, rehydrateLocatedTimestamp, } from "./located-t
 export { assertUniqueTableNames, assertValidMigrationName, diffSnapshots, generateMigration, loadSnapshotJson, renderMigrationSql, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.js";
 export { baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
 export { flattenMoney, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";
-export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, } from "./pg-error.js";
+export { constraintOf, extractPgError, isTableAlreadyExists, isUndefinedTable, isUniqueViolation, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 export { readDatabaseNow } from "./queries/database-now.js";
 export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";

package/dist/db/migrate-runner.js

@@ -188,16 +188,16 @@ function migrationClient(db) {
         if (hasBegin(client))
             return client;
     }
-    throw new Error("migrate-runner: db argument has no .unsafe() and .begin() (need a postgres-js Sql or drizzle DbConnection)");
+    throw new Error("migrate-runner: db argument has no .unsafe() and .begin() (need a Bun.SQL pool or a DbConnection)");
 }
-// Raw-SQL via postgres-js .unsafe().
+// Raw-SQL via Bun.SQL .unsafe().
 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 a postgres-js Sql)");
+        throw new Error("migrate-runner: db argument has no .reserve() (need a Bun.SQL pool)");
     }
     return client.reserve();
 }

package/dist/db/pg-error.js

@@ -1,28 +1,33 @@
-// Drizzle wraps postgres-js errors in `DrizzleQueryError`; the original PG
-// error (with SQLSTATE `code` and `constraint_name`) lives in `.cause`. We
-// unwrap both layers so callers don't have to know which layer produced the
-// error. Used by the event-store to distinguish a unique-violation on the
-// aggregate-version index (optimistic-concurrency conflict) from the one on
-// the idempotency-key index (caller-side replay signal).
+// Bun.SQL server errors carry the SQLSTATE in `errno` and the constraint in
+// `constraint` (`code` is the generic ERR_POSTGRES_SERVER_ERROR). Client-side
+// failures have no `errno`, so their `code` (e.g. ERR_POSTGRES_CONNECTION_CLOSED)
+// is returned instead. The `.cause` chain is walked so wrapped errors resolve too.
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 const MAX_CAUSE_DEPTH = 8;
+function stringOrUndefined(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function infoOfLayer(layer) {
+    const sqlState = stringOrUndefined(propertyOf(layer, "errno"));
+    if (sqlState !== undefined) {
+        return {
+            code: sqlState,
+            constraint_name: stringOrUndefined(propertyOf(layer, "constraint")),
+        };
+    }
+    const code = stringOrUndefined(propertyOf(layer, "code"));
+    return code === undefined ? null : { code, constraint_name: undefined };
+}
 export function extractPgError(e) {
-    if (typeof e !== "object" || e === null)
-        return null;
-    const layers = [];
     let current = e;
     // Depth cap doubles as cycle protection for self-referential causes.
-    while (typeof current === "object" && current !== null && layers.length < MAX_CAUSE_DEPTH) {
-        layers.push(current);
-        // @cast-boundary error-details — DrizzleQueryError wraps PG-error in .cause
-        current = current.cause;
-    }
-    for (const layer of layers) {
-        // @cast-boundary error-details — postgres-js error shape (code, constraint_name)
-        const code = layer.code;
-        const constraintName = layer.constraint_name; // @cast-boundary error-details
-        if (code !== undefined || constraintName !== undefined) {
-            return { code, constraint_name: constraintName };
-        }
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
+        if (typeof current !== "object" || current === null)
+            return null;
+        const info = infoOfLayer(current);
+        if (info !== null)
+            return info;
+        current = propertyOf(current, "cause");
     }
     return null;
 }

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

@@ -499,7 +499,7 @@ async function rekeyTenantKeyedValue(deps, target) {
     const userSubject = keyedUnder?.kind === "tenant" && keyedUnder.tenantId === target.tenantId
         ? rekeyTargetOfTenantKeyedValue(target)
         : keyedUnder?.kind === "user"
-            ? currentProjectionOwnerIfOther(target, keyedUnder.userId)
+            ? currentProjectionOwnerIfOther(target, fieldDef.userOwned.ownerField, keyedUnder.userId)
             : null;
     if (userSubject === null)
         return { kind: "unchanged" };
@@ -536,11 +536,8 @@ function rekeyTargetOfTenantKeyedValue(target) {
 // A value keyed under a previous owner moves to the owner the row has now. The
 // projection of the event's own tenant is authoritative here: the payload of
 // an old created event still names the owner the row had back then.
-function currentProjectionOwnerIfOther(target, keyedUserId) {
-    const fieldDef = target.entity.fields[target.field];
-    if (fieldDef === undefined || !("userOwned" in fieldDef) || !fieldDef.userOwned)
-        return null;
-    const owner = nonEmptyString(target.projectionOwnerRow?.[fieldDef.userOwned.ownerField]);
+function currentProjectionOwnerIfOther(target, ownerField, keyedUserId) {
+    const owner = nonEmptyString(target.projectionOwnerRow?.[ownerField]);
     return owner === null || owner === keyedUserId ? null : { kind: "user", userId: owner };
 }
 // Only the row's own tenant key or a user key counts: another tenant's key is

package/dist/db/queries/database-now.js

@@ -1,7 +1,8 @@
 import { executeRawQueryRead } from "./raw-sql.js";
 // Called by createTenantDb with its inner runner; keeps raw SQL out of consumers.
+// timestamptz(3): events.created_at has millisecond precision, a microsecond now() would compare later.
 export async function queryDatabaseNow(runner) {
-    const [row] = await executeRawQueryRead(runner, "SELECT now() AS now");
+    const [row] = await executeRawQueryRead(runner, "SELECT now()::timestamptz(3) AS now");
     if (!row)
         throw new Error("SELECT now() returned no row");
     return row.now;

package/dist/db/queries/shadow-swap.js

@@ -19,6 +19,7 @@
 // partial index whose WHERE the renderer can't express is rejected up-front.
 import { isUuid, parseTenantId } from "@cosmicdrift/kumiko-types/identifiers";
 import { configuredBlindIndexKey } from "../../crypto/index.js";
+import { extractPgError } from "../pg-error.js";
 import { asEntityTableMeta, asRawClient } from "../query.js";
 import { renderTableDdl } from "../render-ddl.js";
 import { columnNamesOf, tableExists } from "../schema-inspection.js";
@@ -27,9 +28,7 @@ import { quoteTableIdent } from "./table-ops.js";
 export const PROJECTION_REBUILD_SCHEMA = "kumiko_rebuild";
 const SCHEMA_IDENT = quoteTableIdent(PROJECTION_REBUILD_SCHEMA);
 function isDuplicateSchemaError(e) {
-    if (typeof e !== "object" || e === null || !("code" in e))
-        return false;
-    const { code } = e;
+    const code = extractPgError(e)?.code;
     // 42P06 duplicate_schema, 23505 unique_violation on pg_namespace — both
     // surface from the well-known CREATE SCHEMA IF NOT EXISTS race.
     return code === "42P06" || code === "23505";

package/dist/db/query.d.ts

@@ -2,6 +2,8 @@ import type { AggregateRow, AggregateSpec } from "@cosmicdrift/kumiko-types/aggr
 import type { DbRunner, DbTx } from "@cosmicdrift/kumiko-types/db-connection";
 import type { ExecutorManagedRunner, ExecutorManagedWriteCapability, WritableTable } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { SelectOptions, WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
+import { type ClosedConnectionContext } from "./closed-connection.ts";
+import { type PreparedValue } from "./driver-value-preparation.ts";
 import type { EntityTableMeta } from "./entity-table-meta.ts";
 import { type TableInfo } from "./table-info.ts";
 import { asEntityTableMeta, requireEntityTableMeta } from "./table-introspection.ts";
@@ -32,6 +34,7 @@ type AnyRow = any;
 export type { JsonTextMatch, OrderByClause, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "@cosmicdrift/kumiko-types/where-clause-types";
 export type TableLike = EntityTableMeta | any;
 export declare function coerceRow<TOut = Record<string, unknown>>(row: Record<string, unknown>, info: TableInfo): TOut;
+export declare function unsafeLoggingClosedConnection<TRow = unknown>(db: AnyDb, sqlText: string, params: readonly unknown[], context: ClosedConnectionContext): Promise<readonly TRow[]>;
 export declare function unsafeReadRetrying<TRow>(db: AnyDb, sqlText: string, params: readonly unknown[]): Promise<readonly TRow[]>;
 export declare function selectMany<TRow = AnyRow>(db: AnyDb, table: TableLike, where?: WhereObject, options?: SelectOptions): Promise<readonly TRow[]>;
 export declare function fetchOne<TRow = AnyRow>(db: AnyDb, table: TableLike, where: WhereObject): Promise<TRow | undefined>;
@@ -63,7 +66,18 @@ export declare function updateMany<TRow = AnyRow>(db: AnyDb, table: WritableTabl
 export declare function updateMany<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, set: Record<string, unknown>, where: WhereObject): Promise<readonly TRow[]>;
 export declare function deleteMany(db: AnyDb, table: WritableTable, where: WhereObject): Promise<number>;
 export declare function deleteMany(db: ExecutorManagedWriteCapability, table: EntityTableMeta, where: WhereObject): Promise<number>;
+export type InsertEntry = {
+    readonly field: string;
+    readonly col: string;
+    readonly prepared: PreparedValue;
+};
+export declare function insertEntries(info: TableInfo, values: Record<string, unknown>): InsertEntry[];
 export declare function resolveConflictColumns(table: TableLike, info: TableInfo, conflictKeys: readonly string[] | undefined): readonly string[];
+export declare function conflictUpdateParts(info: TableInfo, entries: readonly InsertEntry[], update: Record<string, unknown> | undefined, skipCols: ReadonlySet<string>, params: unknown[]): string[];
+export declare function buildInsertSql(info: TableInfo, entries: readonly InsertEntry[]): {
+    sqlPrefix: string;
+    params: unknown[];
+};
 export type UpsertOnConflictOptions = {
     readonly conflictKeys: readonly string[];
     /** Columns to set on conflict. Default: EXCLUDED for every inserted non-key column. */

package/dist/db/query.js

@@ -1,4 +1,4 @@
-// Typed query helpers over the postgres-js driver: EntityTableMeta in, rows out.
+// Typed query helpers over the Bun.SQL driver: EntityTableMeta in, rows out.
 //
 // API:
 //   selectMany<T>(db, table, where?, opts?) → readonly T[]
@@ -39,9 +39,9 @@ function isRawClient(value) {
     return typeof propertyOf(value, "unsafe") === "function";
 }
 export function asRawClient(db) {
-    // Direct: postgres-js Sql / TransactionSql. Both
-    // expose `.unsafe`; only Sql has `.begin` — TransactionSql uses
-    // `.savepoint` for nested-tx. We only require `.unsafe` here; callers that
+    // Direct: Bun.SQL pool / transaction handle. Both
+    // expose `.unsafe`; only the pool starts a transaction — a transaction handle uses
+    // `.savepoint` for nesting. We only require `.unsafe` here; callers that
     // need `.begin` (e.g. `transaction()`) verify it themselves.
     if (isRawClient(db))
         return db;
@@ -52,15 +52,15 @@ export function asRawClient(db) {
             "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw() with escapeHatch: " +
             "{ reason } on the handler/hook (r.systemScope() features: ctx.systemDb.unsafeRaw(reason)).");
     }
-    // Wrapper handle: $client = postgres-js Sql.
+    // Wrapper handle: $client = Bun.SQL pool.
     const $client = propertyOf(db, "$client");
     if (isRawClient($client))
         return $client;
-    // Wrapper transaction handle: session.client = postgres-js Sql.
+    // Wrapper transaction handle: session.client = Bun.SQL pool.
     const sessionClient = propertyOf(propertyOf(db, "session"), "client");
     if (isRawClient(sessionClient))
         return sessionClient;
-    throw new Error("asRawClient: db argument has no .unsafe() — pass a postgres-js Sql or a transaction handle.");
+    throw new Error("asRawClient: db argument has no .unsafe() — pass a Bun.SQL pool or a transaction handle.");
 }
 export function runnerCanBeginTransaction(db) {
     return hasBegin(asRawClient(db));
@@ -72,10 +72,31 @@ function savepointRunnerOf(sp) {
 export async function runInSavepoint(tx, fn) {
     const raw = asRawClient(tx);
     if (typeof raw.savepoint !== "function") {
-        throw new Error("runInSavepoint: transaction handle has no savepoint() — pass the driver tx (postgres.js TransactionSql).");
+        throw new Error("runInSavepoint: transaction handle has no savepoint() — pass the driver tx (Bun.SQL TransactionSQL).");
     }
     return raw.savepoint((sp) => fn(savepointRunnerOf(sp)));
 }
+// Same error-confinement as runInSavepoint, but for call sites that don't
+// know whether `db` is a bare pool connection or an active transaction
+// (e.g. the CRUD executor, invoked both from a dispatcher tx and directly
+// against the pool by seeds/tests). A pool connection has no savepoint() —
+// and doesn't need one, since each statement there is its own auto-committed
+// unit and a failed statement can't poison anything downstream.
+//
+// `.savepoint` being present isn't proof the transaction is still open: a
+// committed transaction handle still exposes `.savepoint`, and calling it
+// fails (Bun.SQL: ERR_POSTGRES_INVALID_TRANSACTION_STATE, Postgres: 25P01)
+// since there's no BEGIN left to nest into. That is now a programming error, not something
+// to paper over by re-running `fn` without the savepoint's isolation.
+const CONNECTION_CLOSED_CODE = "ERR_POSTGRES_CONNECTION_CLOSED";
+const SAVEPOINT_ON_COMMITTED_CODES = new Set([
+    "25P01",
+    "ERR_POSTGRES_INVALID_TRANSACTION_STATE",
+]);
+function isSavepointOnDeadTransactionCode(code) {
+    return (code !== undefined &&
+        (code === CONNECTION_CLOSED_CODE || SAVEPOINT_ON_COMMITTED_CODES.has(code)));
+}
 export async function runInSavepointIfSupported(db, fn) {
     const raw = asRawClient(db);
     if (typeof raw.savepoint !== "function")
@@ -90,17 +111,17 @@ export async function runInSavepointIfSupported(db, fn) {
     }
     catch (e) {
         const code = extractPgError(e)?.code;
-        if (!fnStarted && (code === "25P01" || code === "ERR_POSTGRES_CONNECTION_CLOSED")) {
+        if (!fnStarted && isSavepointOnDeadTransactionCode(code)) {
             throw new InternalError({
-                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 " +
+                message: code === CONNECTION_CLOSED_CODE
+                    ? "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.",
+                        "for writes that must roll back with the trigger, or ctx.dbOutsideTransaction for work that must survive a rollback."
+                    : "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.",
                 cause: e instanceof Error ? e : undefined,
             });
         }
@@ -131,7 +152,8 @@ function assertNotTenantScoped(db, fnName) {
     if (tenantDbDelegate(db) !== undefined) {
         throw new Error(`${fnName}: received a tenant-scoped db but this helper does not apply the tenant filter. ` +
             "Pass ctx.db.unsafeRaw() (with escapeHatch: { reason } on the handler/hook) for an " +
-            "explicit cross-tenant op, or use a scoped TenantDb method.");
+            "explicit cross-tenant op, or use a scoped TenantDb method " +
+            "(for an upsert: ctx.db.upsert(table, values, { conflictTarget })).");
     }
 }
 export function coerceRow(row, info) {
@@ -143,7 +165,7 @@ function coerceRows(rows, info) {
 }
 // Write and other non-retried paths: log when a closed-connection error leaves
 // the db layer, rethrow unchanged.
-async function unsafeLoggingClosedConnection(db, sqlText, params, context) {
+export async function unsafeLoggingClosedConnection(db, sqlText, params, context) {
     const raw = asRawClient(db);
     try {
         return await raw.unsafe(sqlText, params);
@@ -453,14 +475,14 @@ export async function deleteMany(db, table, where) {
         operation: "deleteMany",
         table: info.name,
     });
-    // postgres-js reports the affected-row count of a DELETE on the result, no RETURNING needed.
+    // Bun.SQL reports the affected-row count of a DELETE on the result, no RETURNING needed.
     const count = propertyOf(result, "count");
     if (typeof count !== "number") {
         throw new Error(`deleteMany(${info.name}): the driver result carries no affected-row count`);
     }
     return count;
 }
-function insertEntries(info, values) {
+export function insertEntries(info, values) {
     return Object.entries(values)
         .filter(([k]) => info.hasColumn(k))
         .map(([k, v]) => {
@@ -486,7 +508,31 @@ export function resolveConflictColumns(table, info, conflictKeys) {
         return [info.columnOf("id")];
     throw new Error("upsert: cannot infer conflict keys — pass conflictKeys explicitly");
 }
-function buildInsertSql(info, entries) {
+// Appends bound values to `params`; `skipCols` only applies to the default EXCLUDED set.
+export function conflictUpdateParts(info, entries, update, skipCols, params) {
+    const parts = [];
+    if (update === undefined) {
+        for (const e of entries) {
+            if (skipCols.has(e.col))
+                continue;
+            parts.push(`${quoteIdent(e.col)} = EXCLUDED.${quoteIdent(e.col)}`);
+        }
+        return parts;
+    }
+    for (const [field, value] of Object.entries(update)) {
+        const col = info.columnOf(field);
+        const p = prepareValue(value, info.pgTypeOf(col));
+        if (p.kind === "literal") {
+            parts.push(`${quoteIdent(col)} = ${p.literal}`);
+        }
+        else {
+            params.push(p.bound);
+            parts.push(`${quoteIdent(col)} = $${params.length}${p.sql}`);
+        }
+    }
+    return parts;
+}
+export function buildInsertSql(info, entries) {
     if (entries.length === 0)
         throw new Error("insert: empty values object");
     const cols = entries.map((e) => quoteIdent(e.col)).join(", ");
@@ -556,28 +602,7 @@ async function upsertOnConflictChecked(db, table, values, options) {
     const conflictCols = resolveConflictColumns(table, info, options.conflictKeys);
     const conflictSet = new Set(conflictCols);
     const { sqlPrefix, params } = buildInsertSql(info, entries);
-    const updateParts = [];
-    let idx = params.length + 1;
-    if (options.update !== undefined) {
-        for (const [field, value] of Object.entries(options.update)) {
-            const col = info.columnOf(field);
-            const p = prepareValue(value, info.pgTypeOf(col));
-            if (p.kind === "literal") {
-                updateParts.push(`${quoteIdent(col)} = ${p.literal}`);
-            }
-            else {
-                updateParts.push(`${quoteIdent(col)} = $${idx++}${p.sql}`);
-                params.push(p.bound);
-            }
-        }
-    }
-    else {
-        for (const e of entries) {
-            if (conflictSet.has(e.col))
-                continue;
-            updateParts.push(`${quoteIdent(e.col)} = EXCLUDED.${quoteIdent(e.col)}`);
-        }
-    }
+    const updateParts = conflictUpdateParts(info, entries, options.update, conflictSet, params);
     if (updateParts.length === 0) {
         throw new Error("upsertOnConflict: nothing to update on conflict");
     }

package/dist/db/reference-data.js

@@ -2,8 +2,10 @@ import { fetchOne } from "../db/query.js";
 import { createSystemUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
 import { reraiseAsKumikoError } from "../errors/index.js";
+import { getStreamVersion } from "../event-store/event-store.js";
 import { entityTableFromRegistry } from "./entity-table-from-registry.js";
 import { createEventStoreExecutor } from "./event-store-executor.js";
+import { deleteRowsWithoutReplayableStream } from "./queries/event-store-orphan-rows.js";
 import { createTenantDb } from "./tenant-db.js";
 /**
  * Seed reference data at boot time.
@@ -38,11 +40,21 @@ export async function seedReferenceData(defs, registry, db) {
             if (keyValue === undefined)
                 continue;
             // Soft-deleted rows are invisible to executor.update, so treat them as missing and re-create.
-            const existing = await fetchOne(db, table, {
+            const existingRow = await fetchOne(db, table, {
                 [upsertKey]: keyValue,
                 tenantId: SYSTEM_TENANT_ID,
                 ...(entity.softDelete && { isDeleted: false }),
             });
+            // Rows seeded before reference data went through the executor have no events: update would
+            // hit a stream-version conflict and a rebuild would drop them. Drop the row and re-create
+            // it under the same id so its stream starts now.
+            let existing = existingRow;
+            let recreateId;
+            if (existingRow && (await getStreamVersion(db, existingRow.id, SYSTEM_TENANT_ID)) === 0) {
+                await deleteRowsWithoutReplayableStream(tdb, { table, ids: [existingRow.id] });
+                existing = undefined;
+                recreateId = existingRow.id;
+            }
             if (existing) {
                 const changes = {};
                 for (const [field, value] of Object.entries(row)) {
@@ -60,7 +72,7 @@ export async function seedReferenceData(defs, registry, db) {
                 }
             }
             else {
-                const result = await executor.create({ ...row, tenantId: SYSTEM_TENANT_ID }, by, tdb);
+                const result = await executor.create({ ...row, ...(recreateId && { id: recreateId }), tenantId: SYSTEM_TENANT_ID }, by, tdb);
                 if (!result.isSuccess)
                     throw reraiseAsKumikoError(result.error);
                 inserted++;

package/dist/db/statement-timeout.js

@@ -4,7 +4,8 @@ const UNBOUNDED_POOL_CLOSE_TIMEOUT_SECONDS = 5;
 // PII backfill and projection rebuilds legitimately run longer. The cap is a connect-time session
 // setting, so the run gets its own short-lived pool with the same options minus the cap: one shared
 // connection would deadlock code that holds a lock in a tx while its DDL runs on another connection.
-// Handles not created by createDbConnection (tx, savepoint, siblings) are passed through.
+// Handles not created by createDbConnection (tx, savepoint, siblings, gated runner proxies) are passed through
+// unchanged and keep the cap; a caller holding such a runner lifts it itself (SET LOCAL in its own transaction).
 export async function withoutStatementTimeout(db, run) {
     const unbounded = openUnboundedSiblingPool(db);
     if (unbounded === undefined)

package/dist/db/tenant-db-upsert.d.ts

@@ -0,0 +1,5 @@
+import type { TenantDbMode, TenantDbUpsertOptions } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { AccessDeniedError } from "../errors/index.ts";
+import { type AnyDb, type TableLike } from "./query.ts";
+export declare function upsertTableDenied(table: TableLike, mode: TenantDbMode): AccessDeniedError | undefined;
+export declare function upsertTenantRow<TRow>(db: AnyDb, table: TableLike, values: Record<string, unknown>, options: TenantDbUpsertOptions): Promise<TRow | undefined>;

package/dist/db/tenant-db-upsert.js

@@ -0,0 +1,91 @@
+import { quoteIdent } from "../crypto/ciphertext-pattern.js";
+import { AccessDeniedError } from "../errors/index.js";
+import { isExecutorManagedTable } from "./executor-managed-tables.js";
+import { buildInsertSql, coerceRow, conflictUpdateParts, insertEntries, unsafeLoggingClosedConnection, } from "./query.js";
+import { extractTableInfo } from "./table-info.js";
+import { asEntityTableMeta, tableNameOf } from "./table-introspection.js";
+const TENANT_COLUMN = "tenant_id";
+// Upsert is never allowed on event-fed tables (even with the write capability) and has no tenant-mode meaning for "global" ones.
+export function upsertTableDenied(table, mode) {
+    if (isExecutorManagedTable(table)) {
+        return new AccessDeniedError({
+            message: `ctx.db.upsert(${tableNameOf(table)}): table is fed by events; upsert is not supported on it.`,
+        });
+    }
+    if (mode === "tenant" && asEntityTableMeta(table)?.tenancy === "global") {
+        return new AccessDeniedError({
+            message: `ctx.db.upsert(${tableNameOf(table)}): "global" table rows must carry SYSTEM_TENANT_ID; ` +
+                "use db.global(table) with escapeHatch instead.",
+        });
+    }
+    return undefined;
+}
+function sameColumnSet(a, b) {
+    return a.length === b.length && new Set(a).size === a.length && a.every((c) => b.includes(c));
+}
+function declaredUniqueColumnSets(meta) {
+    const sets = meta.indexes
+        .filter((i) => i.unique === true && i.whereSql === undefined && i.needsManualWhere !== true)
+        .map((i) => i.columns);
+    if (meta.compositePrimaryKey)
+        sets.push(meta.compositePrimaryKey.columns);
+    const primaryKeyColumns = meta.columns.filter((c) => c.primaryKey).map((c) => c.name);
+    if (primaryKeyColumns.length > 0)
+        sets.push(primaryKeyColumns);
+    return sets;
+}
+function primaryKeyColumnsOf(meta) {
+    return [
+        ...meta.columns.filter((c) => c.primaryKey).map((c) => c.name),
+        ...(meta.compositePrimaryKey?.columns ?? []),
+    ];
+}
+function assertTenantSafeConflictTarget(tableName, meta, conflictCols) {
+    if (conflictCols.length === 0 || !conflictCols.includes(TENANT_COLUMN)) {
+        throw new Error(`tenantDb.upsert(${tableName}): conflictTarget must include "tenantId" — a target without it ` +
+            "could match, and overwrite, another tenant's row.");
+    }
+    if (!declaredUniqueColumnSets(meta).some((set) => sameColumnSet(set, conflictCols))) {
+        throw new Error(`tenantDb.upsert(${tableName}): conflictTarget (${conflictCols.join(", ")}) matches no ` +
+            "declared unique index (without a WHERE clause) or primary key.");
+    }
+}
+// Handles a tenant's own row only: values carry the tenant already, and the DO UPDATE guard
+// compares against the tenant being inserted, so a conflict on another tenant's row updates nothing.
+export async function upsertTenantRow(db, table, values, options) {
+    const info = extractTableInfo(table);
+    const meta = asEntityTableMeta(table);
+    if (!info.hasColumn("tenantId")) {
+        throw new Error(`tenantDb.upsert(${info.name}): table has no tenant column — use the free upsertOnConflict ` +
+            "helper on an unsafeRaw runner instead.");
+    }
+    if (!meta) {
+        throw new Error(`tenantDb.upsert(${info.name}): needs an EntityTableMeta table (declared unique indexes and primary key), got a table without meta.`);
+    }
+    const conflictCols = options.conflictTarget.map((field) => info.columnOf(field));
+    assertTenantSafeConflictTarget(info.name, meta, conflictCols);
+    if (options.update &&
+        Object.keys(options.update).some((f) => info.columnOf(f) === TENANT_COLUMN)) {
+        throw new Error(`tenantDb.upsert(${info.name}): update must not set "tenantId" — it would move the row into another tenant.`);
+    }
+    const entries = insertEntries(info, values);
+    if (!entries.some((e) => e.col === TENANT_COLUMN)) {
+        throw new Error(`tenantDb.upsert(${info.name}): values carry no tenantId.`);
+    }
+    const { sqlPrefix, params } = buildInsertSql(info, entries);
+    const skipCols = new Set([...conflictCols, ...primaryKeyColumnsOf(meta), TENANT_COLUMN]);
+    const setParts = conflictUpdateParts(info, entries, options.update, skipCols, params);
+    if (setParts.length === 0) {
+        throw new Error(`tenantDb.upsert(${info.name}): nothing to update on conflict`);
+    }
+    const tenantRef = quoteIdent(TENANT_COLUMN);
+    const sqlText = `${sqlPrefix} ON CONFLICT (${conflictCols.map((c) => quoteIdent(c)).join(", ")}) ` +
+        `DO UPDATE SET ${setParts.join(", ")} ` +
+        `WHERE ${quoteIdent(info.name)}.${tenantRef} = EXCLUDED.${tenantRef} RETURNING *`;
+    const rows = await unsafeLoggingClosedConnection(db, sqlText, params, {
+        operation: "tenantDb.upsert",
+        table: info.name,
+    });
+    const first = rows[0];
+    return first ? coerceRow(first, info) : undefined;
+}

package/dist/db/tenant-db.js

@@ -11,6 +11,7 @@ import { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 import { queryDatabaseNow } from "./queries/database-now.js";
 import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
 import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, tenantDbWritesDeniedReason, } from "./tenant-db-runner.js";
+import { upsertTableDenied, upsertTenantRow } from "./tenant-db-upsert.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 const declaredUnsafeRawRunners = new WeakMap();
 // The CRUD executor writes through tenantDbRunner, not insertOne, so it asks the
@@ -36,7 +37,7 @@ function boundRunner(runner, gate, projectionRegistry, executorManagedWrites) {
             if (typeof value !== "function")
                 return value;
             if (prop === "reserve") {
-                // postgres-js hands back a raw connection; re-wrap it so the gate survives.
+                // The driver hands back a raw connection; re-wrap it so the gate survives.
                 return async (...args) => {
                     const reserved = await Reflect.apply(value, target, args);
                     return boundRunner(reserved, gate, projectionRegistry, executorManagedWrites);
@@ -662,6 +663,15 @@ function buildTenantDb(options) {
             const data = insertValues(table, values);
             return withDbSpan("insert", table, async () => insertRow(table, data));
         },
+        upsert(table, values, options) {
+            const denied = writesDenied("ctx.db.upsert") ??
+                upsertTableDenied(table, mode) ??
+                personalDataDenied(table, [...Object.keys(values), ...Object.keys(options.update ?? {})]);
+            if (denied)
+                return Promise.reject(denied);
+            const data = insertValues(table, values);
+            return withDbSpan("insert", table, () => upsertTenantRow(db, table, data, options));
+        },
         updateMany(table, set, where) {
             const writeDenied = writesDenied("ctx.db.updateMany");
             if (writeDenied)

package/dist/engine/boot-validator/bundled-lists-table.d.ts

@@ -0,0 +1,2 @@
+export declare const BUNDLED_LISTS_OPTION_KEYS: readonly ["table", "pinFirstColumn"];
+export declare function validateBundledListsOptions(options: unknown): void;

package/dist/engine/boot-validator/bundled-lists-table.js

@@ -0,0 +1,36 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { LIST_TABLE_OPTION_KEYS } from "../types/screen.js";
+import { validateListTableOptions } from "./list-table-options.js";
+export const BUNDLED_LISTS_OPTION_KEYS = ["table", "pinFirstColumn"];
+// grouping and totals name fields of one list, so they cannot be shared across lists
+const SCREEN_ONLY_TABLE_KEYS = ["grouping", "totals"];
+export function validateBundledListsOptions(options) {
+    if (!isPlainObject(options)) {
+        throw new Error("bundledLists must be an object like { table: { columnPicker: true } }.");
+    }
+    const unknownKeys = Object.keys(options).filter((key) => !BUNDLED_LISTS_OPTION_KEYS.some((allowed) => allowed === key));
+    if (unknownKeys.length > 0) {
+        throw new Error(`bundledLists has unknown key(s) ${unknownKeys.map((k) => `"${k}"`).join(", ")}. ` +
+            `Allowed keys: ${BUNDLED_LISTS_OPTION_KEYS.join(", ")}.`);
+    }
+    const table = options["table"];
+    if (!isPlainObject(table)) {
+        const allowed = LIST_TABLE_OPTION_KEYS.filter((key) => !SCREEN_ONLY_TABLE_KEYS.some((screenOnly) => screenOnly === key));
+        throw new Error(`bundledLists.table must be an object like { columnPicker: true }. ` +
+            `Allowed keys: ${allowed.join(", ")}.`);
+    }
+    for (const key of SCREEN_ONLY_TABLE_KEYS) {
+        if (table[key] !== undefined) {
+            throw new Error(`bundledLists.table.${key} is not allowed: ${key} depends on the fields of one list. ` +
+                `Set it in the table block of that screen.`);
+        }
+    }
+    validateListTableOptions("bundledLists", table, [], true);
+    const pinFirstColumn = options["pinFirstColumn"];
+    if (pinFirstColumn !== undefined && typeof pinFirstColumn !== "boolean") {
+        throw new Error("bundledLists.pinFirstColumn must be a boolean.");
+    }
+    if (pinFirstColumn === true && table["pinning"] !== true) {
+        throw new Error("bundledLists.pinFirstColumn needs bundledLists.table.pinning: true.");
+    }
+}

package/dist/engine/boot-validator/entity-list-aggregate-options.d.ts

@@ -0,0 +1,3 @@
+import type { EntityDefinition } from "../types/index.ts";
+import type { EntityListScreenDefinition } from "../types/screen.ts";
+export declare function validateEntityListAggregateOptions(where: string, screen: EntityListScreenDefinition, entity: EntityDefinition): void;