@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/db/tenant-db-statement-runner.js

@@ -0,0 +1,48 @@
+import { emitDbQuery } from "../observability/standard-metrics.js";
+import { runInRowLevelSecurityScope, tenantDbRowLevelSecurityScope, } from "./row-level-security-scope.js";
+import { tableNameOf } from "./table-introspection.js";
+export function createTenantDbStatementRunner({ tracer, meter, signal, mode, reason, tenantId, }) {
+    return function withDbSpan(operation, table, runner) {
+        signal?.throwIfAborted();
+        const scope = tenantDbRowLevelSecurityScope(mode === "system" ? { mode, reason } : { mode }, tenantId, table);
+        const scopedRunner = () => runInRowLevelSecurityScope(scope, runner);
+        if (!tracer && !meter)
+            return scopedRunner();
+        const tableName = tableNameOf(table);
+        const start = performance.now();
+        const emitMetric = () => {
+            if (meter) {
+                emitDbQuery(meter, { operation, table: tableName }, (performance.now() - start) / 1000);
+            }
+        };
+        if (!tracer) {
+            return (async () => {
+                try {
+                    return await scopedRunner();
+                }
+                finally {
+                    emitMetric();
+                }
+            })();
+        }
+        return tracer.withSpan("db.query", {
+            kind: "client",
+            attributes: {
+                "db.system": "postgresql",
+                "db.operation": operation,
+                "db.table": tableName,
+            },
+        }, async (span) => {
+            try {
+                const result = await scopedRunner();
+                if (Array.isArray(result)) {
+                    span.setAttribute("db.row_count", result.length);
+                }
+                return result;
+            }
+            finally {
+                emitMetric();
+            }
+        });
+    };
+}

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.d.ts

@@ -1,13 +1,13 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
 import type { ExecutorManagedRunner } from "@cosmicdrift/kumiko-types/executor-brand";
-import type { EscapeHatchDeclaration, EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
+import type { EscapeHatchDeclaration, EscapeHatchReporter, EscapeHatchTarget, HandlerDb } from "@cosmicdrift/kumiko-types/handlers";
+import type { Meter, Tracer } from "@cosmicdrift/kumiko-types/observability";
 import type { SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
-import { type ExecutorManagedTenantDb, type TenantDb, type TenantDbMode, type UncheckedSystemDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { type ExecutorManagedTenantDb, type TenantDb, type UncheckedSystemDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { asRawClient } from "../db/query.ts";
 import type { EntityDefinition } from "../engine/types/fields.ts";
 import { type TenantId } from "../engine/types/identifiers.ts";
 import type { Registry } from "../engine/types/index.ts";
-import { type Meter, type Tracer } from "../observability/index.ts";
 import type { DbRunner } from "./connection.ts";
 import { tableNameOf } from "./table-introspection.ts";
 type Table = SchemaTable;
@@ -19,10 +19,9 @@ export declare function unsafeRawForDeclaredStep(holder: TenantDb | UncheckedSys
 export declare function withSystemDbUnsafeRawGrant<T extends object>(systemDb: T, grant: EscapeHatchDeclaration | undefined, deniedCallerLabel: string): T | UncheckedSystemDb;
 export declare function createUncheckedSystemDb(db: TenantDb, dbOutsideTransaction?: TenantDb, report?: EscapeHatchReporter): UncheckedSystemDb;
 export declare function createSystemDbView(db: TenantDb, dbOutsideTransaction?: TenantDb, report?: EscapeHatchReporter): UncheckedSystemDb;
-export declare function scopeTenantDbToTenant(db: TenantDb, tenantId: TenantId): TenantDb;
 export declare function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[];
+export { requestedTenantIds } from "./tenant-id-filter.ts";
 export { tableNameOf };
-export declare function requestedTenantIds(requested: unknown): readonly unknown[] | undefined;
 export declare function hasTenantColumn(table: Table | EntityTableMeta): boolean;
 export type TenantDbGrants = {
     readonly globalWrites?: EscapeHatchDeclaration;
@@ -40,26 +39,32 @@ export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, rea
 }): TenantDb;
 export declare function reportConventionCrossTenantUse(acknowledged: TenantDb, target?: EscapeHatchTarget): void;
 export type OutsideTransactionContext = {
-    readonly dbOutsideTransaction: TenantDb | undefined;
+    readonly db: Pick<HandlerDb, "outsideTransaction">;
 };
-export declare function hasOutsideTransactionDb(ctx: OutsideTransactionContext): ctx is OutsideTransactionContext & {
-    readonly dbOutsideTransaction: TenantDb;
+export declare function hasOutsideTransactionDb(ctx: OutsideTransactionContext): ctx is {
+    readonly db: {
+        readonly outsideTransaction: TenantDb;
+    };
 };
 export declare function requireOutsideTransactionDb(ctx: OutsideTransactionContext): TenantDb;
-export declare function runInOwnTransaction<T>(tenantDb: TenantDb, fn: (txDb: TenantDb) => Promise<T>): Promise<T>;
 export type CreateTenantDbOptions = {
     readonly db: DbRunner;
     readonly tenantId: TenantId;
-    readonly mode?: TenantDbMode;
     readonly tracer?: Tracer;
     readonly meter?: Meter;
     readonly signal?: AbortSignal;
     readonly grants?: TenantDbGrants;
-};
+} & ({
+    readonly mode?: "tenant";
+    readonly reason?: undefined;
+} | {
+    readonly mode: "system";
+    readonly reason: string;
+});
 export declare function createTenantDb(options: CreateTenantDbOptions & {
     readonly db: ExecutorManagedRunner;
 }): ExecutorManagedTenantDb;
 export declare function createTenantDb(options: CreateTenantDbOptions): TenantDb;
-export declare function createTenantDataDestroyDb(options: Omit<CreateTenantDbOptions, "mode">): ExecutorManagedTenantDb;
+export declare function createTenantDataDestroyDb(options: Omit<CreateTenantDbOptions, "mode" | "reason">): ExecutorManagedTenantDb;
 export declare function createProjectingTenantDb(db: DbRunner, tenantId: TenantId, projectionRegistry: Registry | undefined): TenantDb;
 export { asRawClient };

package/dist/db/tenant-db.js

@@ -1,16 +1,23 @@
 import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, runInNewTransaction, } from "../db/query.js";
+import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, } from "../db/query.js";
 import { assertReason } from "../engine/escape-hatch-reason.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
-import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
-import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
+import { AccessDeniedError, InternalError } from "../errors/index.js";
+import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.js";
+import { fallbackEscapeHatchReporter } from "../observability/escape-hatch-report.js";
+import { registerStandardMetrics } from "../observability/standard-metrics.js";
 import { assertWritableTable, executorManagedWriteDenied, hasExecutorManagedWriteCapability, registerExecutorManagedWriteRunner, } from "./executor-managed-tables.js";
 import { bindProjectionRegistry, projectionRegistryOf } from "./projection-registry-binding.js";
 import { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 import { queryDatabaseNow } from "./queries/database-now.js";
+import { systemModeOptions, unsafeRawScopedRunner, unscopedRunnerOf, } from "./row-level-security-scope.js";
 import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
-import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, tenantDbWritesDeniedReason, } from "./tenant-db-runner.js";
+import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, } from "./tenant-db-runner.js";
+import { registerScopedRebinder } from "./tenant-db-scoped-rebind.js";
+import { createTenantDbStatementRunner } from "./tenant-db-statement-runner.js";
+import { upsertTableDenied, upsertTenantRow } from "./tenant-db-upsert.js";
+import { isForeignTenantId, requestedTenantIds, tenantIdsAfterExclusion, } from "./tenant-id-filter.js";
+import { registerRunnerProxyTarget } from "./transaction-serialization.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 +43,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);
@@ -66,6 +73,7 @@ function boundRunner(runner, gate, projectionRegistry, executorManagedWrites) {
             return value.bind(target);
         },
     });
+    registerRunnerProxyTarget(proxy, runner);
     if (gate)
         runnerPersonalDataGates.set(proxy, gate);
     if (projectionRegistry)
@@ -165,9 +173,10 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
                     `${gate.deniedCallerLabel} to allow unsafeRaw.`,
             });
         }
+        // A granted unsafeRaw is a declared, audited bypass of the TenantDb filter, so row-level security does not narrow it either.
         // Engine-forwarded steps carry their own declared reason; a caller-supplied one never reaches the audit trail.
         report("unsafe-raw", forwardedDeclaredStep ? reason : (gate?.grant?.reason ?? reason));
-        const runner = withoutExecutorManagedWrites(tenantDbRunner(db));
+        const runner = unsafeRawScopedRunner(withoutExecutorManagedWrites(tenantDbRunner(db)));
         return boundRunner(runner, personalDataGates.get(db), projectionRegistryOf(db), false);
     }
     const uncheckedSystemDb = {
@@ -233,10 +242,9 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
 // own tenantId, never a foreign one.
 //
 // dbOutsideTransaction is optional so every existing single-arg call site
-// (jobs/job-runner.ts, tests) keeps compiling — those callers have no
-// outside-tx source to hand in and never needed one. Only
-// buildHandlerContext passes it, which is also the only place `.outsideTransaction`
-// is reachable through `ctx.systemDb`.
+// (jobs/job-runner.ts, tests) keeps compiling — those callers have no outside-tx
+// source to hand in. Only buildHandlerContext passes it, which is also the only
+// place `.outsideTransaction` is reachable through `ctx.systemDb`.
 //
 // Ungated here (the handler's own systemScope() is the grant); a hook's own
 // escapeHatch is layered on afterwards via withSystemDbUnsafeRawGrant. Public
@@ -251,55 +259,16 @@ export function createUncheckedSystemDb(db, dbOutsideTransaction, report = fallb
 export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEscapeHatchReporter(db.tenantId)) {
     return buildUncheckedSystemDb(db, dbOutsideTransaction, report, { kind: "source-tenant-db" });
 }
-// Narrows a (possibly "system"-mode) TenantDb to a "tenant"-mode handle for one tenant on the
-// same connection/transaction. For code that must run caller-supplied callbacks (e.g. config
-// validators) without handing them a cross-tenant view.
-export function scopeTenantDbToTenant(db, tenantId) {
-    const writesDeniedReason = tenantDbWritesDeniedReason(db);
-    return createTenantDb({
-        db: tenantDbRunner(db),
-        tenantId,
-        mode: "tenant",
-        ...(writesDeniedReason !== undefined && { grants: { writesDeniedReason } }),
-    });
-}
 // @cast-boundary tenant-db-row
 export function castTenantRows(rows) {
     return rows;
 }
+export { requestedTenantIds } from "./tenant-id-filter.js";
 export { tableNameOf };
 // A grant is only real when its reason is non-empty — `{ reason: "" }` must not silently unlock it.
 function hasGrant(decl) {
     return decl !== undefined && decl.reason.trim().length > 0;
 }
-// Tenant ids left over when the caller excludes some via ne/notIn; undefined for other operator forms.
-function tenantIdsAfterExclusion(requested, allowed) {
-    if (!isPlainObject(requested))
-        return undefined;
-    if ("ne" in requested)
-        return allowed.filter((t) => t !== requested["ne"]);
-    if (Array.isArray(requested["notIn"])) {
-        const excluded = requested["notIn"];
-        return allowed.filter((t) => !excluded.includes(t));
-    }
-    return undefined;
-}
-// Tenant ids a where.tenantId filter asks for; undefined for operator forms
-// that cannot narrow to a tenant list (ne, like, ...).
-export function requestedTenantIds(requested) {
-    if (Array.isArray(requested))
-        return requested;
-    if (!isPlainObject(requested))
-        return [requested];
-    if (Array.isArray(requested["in"]))
-        return requested["in"];
-    if ("eq" in requested)
-        return [requested["eq"]];
-    return undefined;
-}
-function isForeignTenantId(tenantIdValue) {
-    return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
-}
 // Checks the canonical EntityTableMeta (branded EntityTable's KUMIKO_META_SYMBOL
 // or a plain deriveEntityTableMeta/defineUnmanagedTable result), not a direct
 // `table.tenantId` property read — the latter only exists on branded EntityTables
@@ -346,28 +315,16 @@ export function reportConventionCrossTenantUse(acknowledged, target) {
     }
     reporter(target);
 }
-const ownTransactionRebinders = new WeakMap();
 export function hasOutsideTransactionDb(ctx) {
-    return ctx.dbOutsideTransaction !== undefined;
+    return ctx.db.outsideTransaction !== undefined;
 }
 export function requireOutsideTransactionDb(ctx) {
     if (!hasOutsideTransactionDb(ctx)) {
         throw new InternalError({
-            message: "ctx.dbOutsideTransaction is not available in this dispatch phase (member-resolution, before-transaction denial) or metering tenant mode.",
+            message: "ctx.db.outsideTransaction is not available in this dispatch phase (member-resolution, before-transaction denial) or metering tenant mode.",
         });
     }
-    return ctx.dbOutsideTransaction;
-}
-export async function runInOwnTransaction(tenantDb, fn) {
-    const rebind = ownTransactionRebinders.get(tenantDb);
-    if (!rebind) {
-        throw new InternalError({
-            message: "runInOwnTransaction received a TenantDb without a transaction rebinder: either it was not " +
-                "built by createTenantDb, or it is the fail-closed ctx.db/ctx.dbOutsideTransaction of an " +
-                "r.systemScope() handler (use ctx.systemDb.outsideTransaction there).",
-        });
-    }
-    return rebind(fn);
+    return ctx.db.outsideTransaction;
 }
 export function createTenantDb(options) {
     return buildTenantDb(options);
@@ -379,7 +336,9 @@ export function createTenantDataDestroyDb(options) {
 // Untyped JS callers or an `as` cast can still hand in undefined; a scoped handle
 // without a tenant would bind `tenant_id = NULL` instead of failing loudly.
 function buildTenantDb(options) {
-    const { db, tenantId, mode = "tenant", tracer, meter, signal, grants } = options;
+    const { db: givenDb, tenantId, mode = "tenant", reason: systemReason, tracer, meter, signal, grants, } = options;
+    const modeOptions = mode === "system" ? systemModeOptions(systemReason) : { mode: "tenant" };
+    const db = mode === "system" ? givenDb : unscopedRunnerOf(givenDb);
     if (tenantId === undefined) {
         throw new InternalError({ message: "createTenantDb: tenantId is required" });
     }
@@ -392,47 +351,13 @@ function buildTenantDb(options) {
     const rebindGrants = projectionRegistry && grants?.projectionRegistry === undefined
         ? { ...grants, projectionRegistry }
         : grants;
-    function withDbSpan(operation, table, runner) {
-        signal?.throwIfAborted();
-        if (!tracer && !meter)
-            return runner();
-        const tableName = tableNameOf(table);
-        const start = performance.now();
-        const emitMetric = () => {
-            if (meter) {
-                emitDbQuery(meter, { operation, table: tableName }, (performance.now() - start) / 1000);
-            }
-        };
-        if (!tracer) {
-            return (async () => {
-                try {
-                    return await runner();
-                }
-                finally {
-                    emitMetric();
-                }
-            })();
-        }
-        return tracer.withSpan("db.query", {
-            kind: "client",
-            attributes: {
-                "db.system": "postgresql",
-                "db.operation": operation,
-                "db.table": tableName,
-            },
-        }, async (span) => {
-            try {
-                const result = await runner();
-                if (Array.isArray(result)) {
-                    span.setAttribute("db.row_count", result.length);
-                }
-                return result;
-            }
-            finally {
-                emitMetric();
-            }
-        });
-    }
+    const withDbSpan = createTenantDbStatementRunner({
+        tracer,
+        meter,
+        signal,
+        ...modeOptions,
+        tenantId,
+    });
     // Reads see own-tenant rows + reference data (tenantId === SYSTEM_TENANT_ID).
     // Writes never touch reference rows — those are system-mode only.
     // A caller-supplied `where.tenantId` may only NARROW the enforced scope
@@ -612,7 +537,7 @@ function buildTenantDb(options) {
         }
         // Engine-forwarded steps carry their own declared reason; otherwise the grant's reason is audited.
         report("unsafe-raw", declaredStepReason ?? grants?.unsafeRaw?.reason ?? "");
-        return boundRunner(withoutExecutorManagedWrites(db), personalDataGate, projectionRegistry, false);
+        return boundRunner(unsafeRawScopedRunner(withoutExecutorManagedWrites(db)), personalDataGate, projectionRegistry, false);
     }
     const tenantDb = {
         tenantId,
@@ -662,6 +587,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)
@@ -702,7 +636,7 @@ function buildTenantDb(options) {
     unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb({
         db,
         tenantId,
-        mode,
+        ...modeOptions,
         tracer,
         meter,
         signal,
@@ -720,6 +654,7 @@ function buildTenantDb(options) {
             db,
             tenantId,
             mode: "system",
+            reason,
             tracer,
             meter,
             signal,
@@ -728,18 +663,22 @@ function buildTenantDb(options) {
         crossTenantUseReporters.set(acknowledged, (target) => report("acknowledge-cross-tenant", reason, target));
         return acknowledged;
     });
-    ownTransactionRebinders.set(tenantDb, async (fn) => {
-        if (grants?.memberReadOnly) {
-            throw new InternalError({
-                message: "runInOwnTransaction: memberReadOnly TenantDb — a fresh transaction would escape " +
-                    "the enforced read-only scope.",
-            });
-        }
-        // Carries a runner-bound gate (grants.personalDataGate unset, resolved via the fallback above) forward explicitly, since the fresh tx-handle isn't itself registered in runnerPersonalDataGates.
-        const txGrants = personalDataGate ? { ...rebindGrants, personalDataGate } : rebindGrants;
-        return runInNewTransaction(db, (tx) => fn(createTenantDb({ db: tx, tenantId, mode, tracer, meter, signal, grants: txGrants })));
+    // Carries a runner-bound gate (grants.personalDataGate unset, resolved via the fallback above) forward explicitly, since a fresh tx-handle isn't itself registered in runnerPersonalDataGates.
+    const scopedGrants = personalDataGate ? { ...rebindGrants, personalDataGate } : rebindGrants;
+    registerScopedRebinder(tenantDb, {
+        memberReadOnly: grants?.memberReadOnly === true,
+        rebind: (runner) => createTenantDb({
+            db: runner,
+            tenantId,
+            ...modeOptions,
+            tracer,
+            meter,
+            signal,
+            grants: scopedGrants,
+        }),
     });
-    bindTenantDbRunner(tenantDb, db);
+    // Framework code reading through the raw runner (executor list/detail) must follow the db's own mode, not the ambient scope.
+    bindTenantDbRunner(tenantDb, db, modeOptions, tenantId);
     if (grants?.writesDeniedReason !== undefined) {
         denyTenantDbWrites(tenantDb, grants.writesDeniedReason);
     }

package/dist/db/tenant-id-filter.d.ts

@@ -0,0 +1,3 @@
+export declare function tenantIdsAfterExclusion(requested: unknown, allowed: readonly unknown[]): readonly unknown[] | undefined;
+export declare function requestedTenantIds(requested: unknown): readonly unknown[] | undefined;
+export declare function isForeignTenantId(tenantIdValue: unknown): boolean;

package/dist/db/tenant-id-filter.js

@@ -0,0 +1,30 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
+// Tenant ids left over when the caller excludes some via ne/notIn; undefined for other operator forms.
+export function tenantIdsAfterExclusion(requested, allowed) {
+    if (!isPlainObject(requested))
+        return undefined;
+    if ("ne" in requested)
+        return allowed.filter((t) => t !== requested["ne"]);
+    if (Array.isArray(requested["notIn"])) {
+        const excluded = requested["notIn"];
+        return allowed.filter((t) => !excluded.includes(t));
+    }
+    return undefined;
+}
+// Tenant ids a where.tenantId filter asks for; undefined for operator forms
+// that cannot narrow to a tenant list (ne, like, ...).
+export function requestedTenantIds(requested) {
+    if (Array.isArray(requested))
+        return requested;
+    if (!isPlainObject(requested))
+        return [requested];
+    if (Array.isArray(requested["in"]))
+        return requested["in"];
+    if ("eq" in requested)
+        return [requested["eq"]];
+    return undefined;
+}
+export function isForeignTenantId(tenantIdValue) {
+    return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
+}

package/dist/db/transaction-serialization.d.ts

@@ -0,0 +1,6 @@
+type HandleKey = object;
+export declare function registerRunnerProxyTarget(proxy: HandleKey, target: HandleKey): void;
+export declare function openSerializedSavepoint<T>(transactionHandle: HandleKey & {
+    savepoint: <R>(fn: (sp: unknown) => Promise<R>) => Promise<R>;
+}, fn: (sp: unknown) => Promise<T>): Promise<T>;
+export {};

package/dist/db/transaction-serialization.js

@@ -0,0 +1,60 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const runnerProxyTargets = new WeakMap();
+const savepointTransactionKeys = new WeakMap();
+const rootChains = new WeakMap();
+const nestedChainsInScope = new AsyncLocalStorage();
+function isHandleKey(value) {
+    return typeof value === "function" || (typeof value === "object" && value !== null);
+}
+export function registerRunnerProxyTarget(proxy, target) {
+    runnerProxyTargets.set(proxy, target);
+}
+function driverHandleOf(handle) {
+    let current = handle;
+    let target = runnerProxyTargets.get(current);
+    while (target) {
+        current = target;
+        target = runnerProxyTargets.get(current);
+    }
+    return current;
+}
+function transactionKeyOf(handle) {
+    const driverHandle = driverHandleOf(handle);
+    return savepointTransactionKeys.get(driverHandle) ?? driverHandle;
+}
+function chainFor(transactionKey) {
+    const nested = nestedChainsInScope.getStore()?.get(transactionKey);
+    if (nested)
+        return nested;
+    const root = rootChains.get(transactionKey);
+    if (root)
+        return root;
+    const created = { tail: Promise.resolve() };
+    rootChains.set(transactionKey, created);
+    return created;
+}
+async function runOnChain(transactionKey, work) {
+    const chain = chainFor(transactionKey);
+    const previous = chain.tail;
+    let release = () => { };
+    chain.tail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        const scope = new Map(nestedChainsInScope.getStore());
+        scope.set(transactionKey, { tail: Promise.resolve() });
+        return await nestedChainsInScope.run(scope, work);
+    }
+    finally {
+        release();
+    }
+}
+export function openSerializedSavepoint(transactionHandle, fn) {
+    const transactionKey = transactionKeyOf(transactionHandle);
+    return runOnChain(transactionKey, () => transactionHandle.savepoint((sp) => {
+        if (isHandleKey(sp))
+            savepointTransactionKeys.set(driverHandleOf(sp), transactionKey);
+        return fn(sp);
+    }));
+}

package/dist/derivatives/delete-stored-file.js

@@ -72,7 +72,7 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
     }
     return failedKeys;
 }
-// deleteStoredFileAndDerivatives through ctx.files for a key read from a tenant-filtered fileRef
+// deleteStoredFileAndDerivatives through ctx.services.files for a key read from a tenant-filtered fileRef
 // row. After a tenant handover the key keeps the previous tenant's prefix, which ref() and list()
 // reject; every key the helper deletes is the original or one of its derivatives.
 export function deleteFileRefBytes(files, row, errorContext) {

package/dist/derivatives/index.d.ts

@@ -1,6 +1,3 @@
-export type { StoredFileStore } from "./delete-stored-file.ts";
-export { deleteFileRefBytes, deleteStoredFileAndDerivatives, listDerivativeKeys, } from "./delete-stored-file.ts";
-export type { DerivativesContextDeps } from "./derivatives-context.ts";
-export { createDerivativesContext, resolveRenderer } from "./derivatives-context.ts";
+export { deleteFileRefBytes, deleteStoredFileAndDerivatives, } from "./delete-stored-file.ts";
 export { resolveFieldVariant } from "./field-variants.ts";
-export { canonicalJson, derivativeListPrefix, isDerivativeKeyOf, parseDerivativeKey, specHash, VARIANT_NAME_PATTERN, variantSuffix, } from "./variant-key.ts";
+export { derivativeListPrefix, parseDerivativeKey, variantSuffix, } from "./variant-key.ts";

package/dist/derivatives/index.js

@@ -1,4 +1,3 @@
-export { deleteFileRefBytes, deleteStoredFileAndDerivatives, listDerivativeKeys, } from "./delete-stored-file.js";
-export { createDerivativesContext, resolveRenderer } from "./derivatives-context.js";
+export { deleteFileRefBytes, deleteStoredFileAndDerivatives, } from "./delete-stored-file.js";
 export { resolveFieldVariant } from "./field-variants.js";
-export { canonicalJson, derivativeListPrefix, isDerivativeKeyOf, parseDerivativeKey, specHash, VARIANT_NAME_PATTERN, variantSuffix, } from "./variant-key.js";
+export { derivativeListPrefix, parseDerivativeKey, variantSuffix, } from "./variant-key.js";