@cosmicdrift/kumiko-framework 0.389.0 → 0.390.1

package/dist/db/table-builder.js

@@ -368,6 +368,6 @@ export function buildEntityTable(entityName, entity, options) {
         return indexes;
     });
     stampEntityTableMeta(built, entity);
-    markExecutorManagedTable(built);
+    markExecutorManagedTable(built, { entityName, entity });
     return built;
 }

package/dist/db/table-info.js

@@ -1,4 +1,4 @@
-import { camelCase as envCamelCase } from "../env/index.js";
+import { camelCase as envCamelCase } from "../env/internals.js";
 import { toSnakeCase } from "./table-builder.js";
 import { asEntityTableMeta } from "./table-introspection.js";
 // Idempotent snake_case → camelCase. `env.camelCase` always lowercases first

package/dist/db/table-push.d.ts

@@ -1,6 +1,7 @@
-import type { EntityDefinition } from "../engine/types/index.ts";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import type { DbConnection } from "./connection.ts";
 import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta.ts";
+import type { RowLevelSecurityMode } from "./render-rls-ddl.ts";
 /**
  * Bypass: creates an entity-table directly without going through the
  * full registry. Reserved for framework-internal meta-tables and
@@ -13,6 +14,12 @@ export declare function tableToMeta(table: unknown): EntityTableMeta;
 export declare function addMissingColumns(db: DbConnection, tableName: string, columns: readonly ColumnMeta[]): Promise<void>;
 /** CREATE [UNIQUE] INDEX IF NOT EXISTS for exactly the given indexes. */
 export declare function addMissingIndexes(db: DbConnection, tableName: string, indexes: readonly IndexMeta[]): Promise<void>;
+/**
+ * Re-applies the row-level security DDL on a table that already exists. The create functions of
+ * framework tables skip the push for existing tables, so databases created before row-level
+ * security was switched on would never get the policies. Idempotent; no-op unless the mode is "on".
+ */
+export declare function ensureTableRowLevelSecurity(db: DbConnection, table: unknown): Promise<void>;
 /**
  * Bypass: pushes table definitions to the database directly. Produces
  * CREATE TABLE IF NOT EXISTS + CREATE INDEX statements via renderTableDdl
@@ -21,4 +28,6 @@ export declare function addMissingIndexes(db: DbConnection, tableName: string, i
  * Reserved for framework-internal meta-tables + test setup. App-defined
  * entities go through `kumiko schema apply` (committed SQL files).
  */
-export declare function unsafePushTables(db: DbConnection, tables: Record<string, unknown>, prevTables?: Record<string, unknown>): Promise<void>;
+export declare function unsafePushTables(db: DbConnection, tables: Record<string, unknown>, prevTables?: Record<string, unknown>, options?: {
+    readonly rowLevelSecurity?: RowLevelSecurityMode;
+}): Promise<void>;

package/dist/db/table-push.js

@@ -1,6 +1,7 @@
 import { pgTypeToSqlType } from "./dialect.js";
-import { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement } from "./queries/ddl.js";
+import { alterTableAddColumn, applyTableRowLevelSecurity, createIndexIfNotExists, executeDdlStatement, } from "./queries/ddl.js";
 import { renderTableDdl } from "./render-ddl.js";
+import { rowLevelSecurityModeOf } from "./row-level-security-connection.js";
 import { tableExists } from "./schema-inspection.js";
 import { buildEntityTable, toTableName } from "./table-builder.js";
 import { asEntityTableMeta } from "./table-introspection.js";
@@ -46,6 +47,15 @@ export async function addMissingIndexes(db, tableName, indexes) {
         await createIndexIfNotExists(db, kind, idx.name, tableName, colList, idx.whereSql);
     }
 }
+/**
+ * Re-applies the row-level security DDL on a table that already exists. The create functions of
+ * framework tables skip the push for existing tables, so databases created before row-level
+ * security was switched on would never get the policies. Idempotent; no-op unless the mode is "on".
+ */
+export async function ensureTableRowLevelSecurity(db, table) {
+    if (rowLevelSecurityModeOf(db) === "on")
+        await applyTableRowLevelSecurity(db, tableToMeta(table));
+}
 /**
  * Bypass: pushes table definitions to the database directly. Produces
  * CREATE TABLE IF NOT EXISTS + CREATE INDEX statements via renderTableDdl
@@ -54,7 +64,8 @@ export async function addMissingIndexes(db, tableName, indexes) {
  * Reserved for framework-internal meta-tables + test setup. App-defined
  * entities go through `kumiko schema apply` (committed SQL files).
  */
-export async function unsafePushTables(db, tables, prevTables) {
+export async function unsafePushTables(db, tables, prevTables, options = {}) {
+    const rowLevelSecurity = options.rowLevelSecurity ?? rowLevelSecurityModeOf(db);
     const prevMetas = new Map();
     if (prevTables) {
         for (const [key, table] of Object.entries(prevTables)) {
@@ -78,6 +89,8 @@ export async function unsafePushTables(db, tables, prevTables) {
                 await executeDdlStatement(db, stmt);
             }
         }
+        if (rowLevelSecurity === "on")
+            await applyTableRowLevelSecurity(db, meta);
     }
 }
 // @wrapper-known semantic-alias

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

@@ -1,9 +1,11 @@
 import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { TenantId } from "../engine/types/identifiers.ts";
 import { InternalError } from "../errors/index.ts";
 import type { DbRunner } from "./connection.ts";
+import { type TenantDbModeOptions } from "./row-level-security-scope.ts";
 export declare function isBoundTenantDb(value: unknown): value is TenantDb;
 export declare function isDbRunner(value: unknown): value is DbRunner;
-export declare function bindTenantDbRunner(tenantDb: TenantDb, runner: DbRunner): void;
+export declare function bindTenantDbRunner(tenantDb: TenantDb, runner: DbRunner, modeOptions: TenantDbModeOptions, tenantId: TenantId): void;
 export declare function tenantDbRunner(tenantDb: TenantDb): DbRunner;
 export declare function denyTenantDbWrites(tenantDb: TenantDb, reason: string): void;
 export declare function tenantDbWritesDeniedReason(tenantDb: TenantDb): string | undefined;

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

@@ -1,5 +1,6 @@
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { InternalError } from "../errors/index.js";
+import { tenantDbRowLevelSecurityScope, withRowLevelSecurityScope, } from "./row-level-security-scope.js";
 const tenantDbRunners = new WeakMap();
 export function isBoundTenantDb(value) {
     return typeof value === "object" && value !== null && tenantDbRunners.has(value);
@@ -7,8 +8,8 @@ export function isBoundTenantDb(value) {
 export function isDbRunner(value) {
     return typeof propertyOf(value, "unsafe") === "function";
 }
-export function bindTenantDbRunner(tenantDb, runner) {
-    tenantDbRunners.set(tenantDb, runner);
+export function bindTenantDbRunner(tenantDb, runner, modeOptions, tenantId) {
+    tenantDbRunners.set(tenantDb, withRowLevelSecurityScope(runner, tenantDbRowLevelSecurityScope(modeOptions, tenantId)));
 }
 // WeakMap.get never reads a property off tenantDb — safe even when tenantDb is a
 // throwing systemScope guard Proxy that rejects every property access.
@@ -31,7 +32,7 @@ export function tenantDbWritesDeniedReason(tenantDb) {
 }
 export function tenantDbWritesDeniedError(operation, reason) {
     return new InternalError({
-        message: `${operation}: writes are not available ${reason}; run the write through ctx.write so it gets its own transaction`,
+        message: `${operation}: writes are not available ${reason}; run the write through ctx.dispatch.write so it gets its own transaction`,
     });
 }
 // For framework code that writes through the raw runner (executor verbs, event appends, projection steps):

package/dist/db/tenant-db-scoped-rebind.d.ts

@@ -0,0 +1,10 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { DbRunner } from "./connection.ts";
+type ScopedRebinder = {
+    readonly memberReadOnly: boolean;
+    readonly rebind: (runner: DbRunner) => TenantDb;
+};
+export declare function registerScopedRebinder(tenantDb: TenantDb, scoped: ScopedRebinder): void;
+export declare function runInOwnTransaction<T>(tenantDb: TenantDb, fn: (txDb: TenantDb) => Promise<T>): Promise<T>;
+export declare function runInOwnSavepoint<T>(tenantDb: TenantDb, fn: (savepointDb: TenantDb) => Promise<T>): Promise<T>;
+export {};

package/dist/db/tenant-db-scoped-rebind.js

@@ -0,0 +1,33 @@
+import { InternalError } from "../errors/index.js";
+import { runInNewTransaction, runInSavepointIfSupported } from "./query.js";
+import { tenantDbRunner } from "./tenant-db-runner.js";
+const scopedRebinders = new WeakMap();
+export function registerScopedRebinder(tenantDb, scoped) {
+    scopedRebinders.set(tenantDb, scoped);
+}
+function requireScopedRebinder(tenantDb, caller) {
+    const scoped = scopedRebinders.get(tenantDb);
+    if (!scoped) {
+        throw new InternalError({
+            message: `${caller} received a TenantDb without a transaction rebinder: either it was not ` +
+                "built by createTenantDb, or it is the fail-closed ctx.db/ctx.db.outsideTransaction of an " +
+                "r.systemScope() handler (use ctx.systemDb.outsideTransaction there).",
+        });
+    }
+    return scoped;
+}
+export async function runInOwnTransaction(tenantDb, fn) {
+    const scoped = requireScopedRebinder(tenantDb, "runInOwnTransaction");
+    if (scoped.memberReadOnly) {
+        throw new InternalError({
+            message: "runInOwnTransaction: memberReadOnly TenantDb — a fresh transaction would escape " +
+                "the enforced read-only scope.",
+        });
+    }
+    return runInNewTransaction(tenantDbRunner(tenantDb), (tx) => fn(scoped.rebind(tx)));
+}
+// A throw inside fn rolls back only fn's statements; the caller's transaction stays usable.
+export async function runInOwnSavepoint(tenantDb, fn) {
+    const scoped = requireScopedRebinder(tenantDb, "runInOwnSavepoint");
+    return runInSavepointIfSupported(tenantDbRunner(tenantDb), (sp) => fn(scoped.rebind(sp)));
+}

package/dist/db/tenant-db-statement-runner.d.ts

@@ -0,0 +1,13 @@
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
+import type { Meter, Tracer } from "@cosmicdrift/kumiko-types/observability";
+import type { SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type { TenantId } from "../engine/types/identifiers.ts";
+import { type TenantDbModeOptions } from "./row-level-security-scope.ts";
+export type TenantDbStatementRunnerOptions = {
+    readonly tracer?: Tracer | undefined;
+    readonly meter?: Meter | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly tenantId: TenantId;
+} & TenantDbModeOptions;
+export type TenantDbOperation = "select" | "insert" | "update" | "delete";
+export declare function createTenantDbStatementRunner({ tracer, meter, signal, mode, reason, tenantId, }: TenantDbStatementRunnerOptions): <T>(operation: TenantDbOperation, table: SchemaTable | EntityTableMeta, runner: () => Promise<T>) => Promise<T>;

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.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,17 +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
@@ -67,6 +73,7 @@ function boundRunner(runner, gate, projectionRegistry, executorManagedWrites) {
             return value.bind(target);
         },
     });
+    registerRunnerProxyTarget(proxy, runner);
     if (gate)
         runnerPersonalDataGates.set(proxy, gate);
     if (projectionRegistry)
@@ -166,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 = {
@@ -234,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
@@ -252,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
@@ -347,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.",
-        });
-    }
-    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).",
+            message: "ctx.db.outsideTransaction is not available in this dispatch phase (member-resolution, before-transaction denial) or metering tenant mode.",
         });
     }
-    return rebind(fn);
+    return ctx.db.outsideTransaction;
 }
 export function createTenantDb(options) {
     return buildTenantDb(options);
@@ -380,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" });
     }
@@ -393,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
@@ -613,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,
@@ -712,7 +636,7 @@ function buildTenantDb(options) {
     unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb({
         db,
         tenantId,
-        mode,
+        ...modeOptions,
         tracer,
         meter,
         signal,
@@ -730,6 +654,7 @@ function buildTenantDb(options) {
             db,
             tenantId,
             mode: "system",
+            reason,
             tracer,
             meter,
             signal,
@@ -738,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 {};