@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/db/row-level-security-connection.js

@@ -0,0 +1,213 @@
+import { InternalError } from "../errors/index.js";
+import { applyRowLevelSecurityScope, buildRowLevelSecurityScopeQuery, } from "./queries/rls-scope.js";
+import { activeRowLevelSecurityScope, innerOfScopedRunner, rowLevelSecurityScopeKey, runInCapturedRowLevelSecurityScope, } from "./row-level-security-scope.js";
+import { registerRunnerProxyTarget } from "./transaction-serialization.js";
+const enforcedHandles = new WeakSet();
+// Differs from every scope key, so the next statement always re-applies its scope.
+const UNKNOWN_SCOPE_KEY = "unknown";
+const noop = () => { };
+function isHandle(value) {
+    return (typeof value === "object" || typeof value === "function") && value !== null;
+}
+export function rowLevelSecurityModeOf(db) {
+    let current = db;
+    while (isHandle(current)) {
+        if (enforcedHandles.has(current))
+            return "on";
+        current = innerOfScopedRunner(current);
+    }
+    return "off";
+}
+function callMethod(target, name, args) {
+    return Reflect.apply(Reflect.get(target, name, target), target, args);
+}
+// Tagged-template calls need the real driver object as `this`.
+function applyOnTarget(target, args) {
+    if (typeof target !== "function") {
+        throw new TypeError("row-level-security proxy applied on a non-callable handle");
+    }
+    return Reflect.apply(target, target, args);
+}
+function isTaggedTemplateCall(args) {
+    const first = args[0];
+    return Array.isArray(first) && "raw" in first;
+}
+// Sql methods that send statements on a connection this wrapper cannot align per statement.
+const UNSUPPORTED_ON_ENFORCED_HANDLE = new Set([
+    "reserve",
+    "beginDistributed",
+    "commitDistributed",
+    "rollbackDistributed",
+]);
+function enqueue(state, unit) {
+    const result = state.tail.then(unit);
+    state.tail = result.then(noop, noop);
+    return result;
+}
+// The driver may run the callback outside the caller's async context, so the captured scope is re-entered.
+function withCapturedCallback(args, wrap) {
+    const callback = args[args.length - 1];
+    if (typeof callback !== "function")
+        return [...args];
+    const captured = activeRowLevelSecurityScope();
+    return [
+        ...args.slice(0, -1),
+        (handle) => runInCapturedRowLevelSecurityScope(captured, () => callback(wrap(handle))),
+    ];
+}
+function alignedStatement(target, state, run) {
+    const desired = activeRowLevelSecurityScope();
+    return enqueue(state, async () => {
+        await alignScope(target, state, desired);
+        return run();
+    });
+}
+function transactionHandleProxy(handle, state) {
+    const proxy = new Proxy(handle, {
+        apply(target, _thisArg, args) {
+            // Helper calls such as sql(rows) or sql("ident") build fragments and send nothing.
+            if (!isTaggedTemplateCall(args))
+                return applyOnTarget(target, args);
+            return alignedStatement(target, state, () => applyOnTarget(target, args));
+        },
+        get(target, prop) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== "function")
+                return value;
+            if (UNSUPPORTED_ON_ENFORCED_HANDLE.has(prop)) {
+                return () => {
+                    throw new InternalError({
+                        message: `row-level security: ${String(prop)} is not supported on an enforced transaction handle`,
+                    });
+                };
+            }
+            if (prop === "unsafe" || prop === "file") {
+                return (...args) => alignedStatement(target, state, () => callMethod(target, prop, args));
+            }
+            if (prop === "savepoint") {
+                // A released or rolled-back savepoint reverts the transaction-local settings made inside it.
+                return async (...args) => {
+                    try {
+                        return await callMethod(target, "savepoint", withCapturedCallback(args, (spHandle) => transactionHandleProxy(spHandle, state)));
+                    }
+                    finally {
+                        state.applied = UNKNOWN_SCOPE_KEY;
+                    }
+                };
+            }
+            return value.bind(target);
+        },
+    });
+    enforcedHandles.add(proxy);
+    registerRunnerProxyTarget(proxy, handle);
+    return proxy;
+}
+async function alignScope(handle, state, desired) {
+    const key = rowLevelSecurityScopeKey(desired);
+    // skip: scope already applied on this connection
+    if (key === state.applied)
+        return;
+    state.applied = UNKNOWN_SCOPE_KEY;
+    await applyRowLevelSecurityScope(handle, desired);
+    state.applied = key;
+}
+function newTransactionState() {
+    return { applied: rowLevelSecurityScopeKey(undefined), tail: Promise.resolve() };
+}
+const templateOf = (strings) => strings;
+// Tagged-template statements pipeline behind each other; unsafe() without parameters is sent as a
+// simple query that waits for its own result first (measured 4.1 vs 2.4 roundtrips).
+const BEGIN_TEMPLATE = templateOf `BEGIN`;
+const COMMIT_TEMPLATE = templateOf `COMMIT`;
+// Bun queries are lazy: they go out when started, so each one is started explicitly, in order,
+// to pipeline BEGIN, the scope and the statement on one connection.
+function startQuery(build) {
+    try {
+        const query = build();
+        if (isHandle(query) && typeof Reflect.get(query, "execute") === "function") {
+            callMethod(query, "execute", []);
+        }
+        return Promise.resolve(query);
+    }
+    catch (error) {
+        // A statement that cannot be built must not stop COMMIT from being queued behind BEGIN.
+        return Promise.reject(error);
+    }
+}
+// COMMIT is always queued and the connection is released only after all four settled, so it never
+// returns to the pool inside an open transaction; COMMIT after a failed statement rolls back.
+async function pipelinedScopedTransaction(pool, scope, run) {
+    const conn = await callMethod(pool, "reserve", []);
+    if (!isHandle(conn)) {
+        throw new InternalError({
+            message: "row-level security: pool.reserve() returned no connection",
+        });
+    }
+    try {
+        const begin = startQuery(() => applyOnTarget(conn, [BEGIN_TEMPLATE]));
+        const setScope = startQuery(() => buildRowLevelSecurityScopeQuery(conn, scope));
+        const statement = startQuery(() => run(conn));
+        const commit = startQuery(() => applyOnTarget(conn, [COMMIT_TEMPLATE]));
+        const [beginResult, scopeResult, statementResult, commitResult] = await Promise.allSettled([
+            begin,
+            setScope,
+            statement,
+            commit,
+        ]);
+        // Without BEGIN or the scope the statement ran unscoped (fails closed) but is not a success.
+        if (beginResult.status === "rejected")
+            throw beginResult.reason;
+        if (scopeResult.status === "rejected")
+            throw scopeResult.reason;
+        if (statementResult.status === "rejected")
+            throw statementResult.reason;
+        if (commitResult.status === "rejected")
+            throw commitResult.reason;
+        return statementResult.value;
+    }
+    finally {
+        callMethod(conn, "release", []);
+    }
+}
+// A pool statement under a scope runs as its own short transaction; without a scope it passes
+// through and the policies see no tenant (fail closed), so DDL like CONCURRENTLY keeps working.
+export function enforceRowLevelSecurity(pool) {
+    const inScopedTransaction = (run) => pipelinedScopedTransaction(pool, activeRowLevelSecurityScope(), run);
+    const proxy = new Proxy(pool, {
+        apply(target, _thisArg, args) {
+            if (!isTaggedTemplateCall(args) || activeRowLevelSecurityScope() === undefined) {
+                return applyOnTarget(target, args);
+            }
+            return inScopedTransaction((conn) => applyOnTarget(conn, args));
+        },
+        get(target, prop) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== "function")
+                return value;
+            if (prop === "unsafe" || prop === "file") {
+                return (...args) => {
+                    if (activeRowLevelSecurityScope() === undefined)
+                        return callMethod(target, prop, args);
+                    if (prop === "file") {
+                        // Bun sends file() only after its async file read, i.e. after the pipelined COMMIT.
+                        const scope = activeRowLevelSecurityScope();
+                        return callMethod(target, "begin", [
+                            async (tx) => {
+                                await applyRowLevelSecurityScope(tx, scope);
+                                return callMethod(tx, "file", args);
+                            },
+                        ]);
+                    }
+                    return inScopedTransaction((conn) => callMethod(conn, prop, args));
+                };
+            }
+            if (prop === "begin" || prop === "transaction") {
+                return (...args) => callMethod(target, prop, withCapturedCallback(args, (tx) => transactionHandleProxy(tx, newTransactionState())));
+            }
+            return value.bind(target);
+        },
+    });
+    enforcedHandles.add(proxy);
+    registerRunnerProxyTarget(proxy, pool);
+    return proxy;
+}

package/dist/db/row-level-security-scope.d.ts

@@ -0,0 +1,33 @@
+import type { TenantId } from "../engine/types/identifiers.ts";
+import type { RowLevelSecurityMode } from "./render-rls-ddl.ts";
+export type RowLevelSecurityScope = {
+    readonly kind: "tenant";
+    readonly tenantId: TenantId;
+} | {
+    readonly kind: "system";
+    readonly reason: string;
+};
+export declare const SYSTEM_ROW_LEVEL_SECURITY_SCOPE: RowLevelSecurityScope;
+export declare function tenantRowLevelSecurityScope(tenantId: TenantId): RowLevelSecurityScope;
+export declare function activeRowLevelSecurityScope(): RowLevelSecurityScope | undefined;
+export declare function runInRowLevelSecurityScope<T>(scope: RowLevelSecurityScope, fn: () => T): T;
+export declare function runInSystemRowLevelSecurityScope<T>(reason: string, fn: () => T): T;
+export declare function runInCapturedRowLevelSecurityScope<T>(captured: RowLevelSecurityScope | undefined, fn: () => T): T;
+export declare function outsideRowLevelSecurityScope<T>(fn: () => T): T;
+export declare function rowLevelSecurityScopeKey(scope: RowLevelSecurityScope | undefined): string;
+export type TenantDbModeOptions = {
+    readonly mode: "tenant";
+    readonly reason?: undefined;
+} | {
+    readonly mode: "system";
+    readonly reason: string;
+};
+export declare function systemModeOptions(reason: string | undefined): TenantDbModeOptions;
+export declare function tenantDbRowLevelSecurityScope(options: TenantDbModeOptions, tenantId: TenantId, table?: unknown): RowLevelSecurityScope;
+export declare function assertNoActiveRowLevelSecurityScope(startingWhat: string): void;
+export declare function unscopedRunnerOf<T extends object>(runner: T): T;
+export declare function innerOfScopedRunner(runner: unknown): object | undefined;
+export declare function withRowLevelSecurityScope<T extends object>(runner: T, scope: RowLevelSecurityScope): T;
+export declare function systemScopedRunner<T extends object>(runner: T, reason: string): T;
+export declare function appHookScopedRunner<T extends object>(runner: T, mode: RowLevelSecurityMode): T;
+export declare function unsafeRawScopedRunner<T extends object>(runner: T): T;

package/dist/db/row-level-security-scope.js

@@ -0,0 +1,127 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { InternalError } from "../errors/index.js";
+import { asEntityTableMeta } from "./table-introspection.js";
+import { registerRunnerProxyTarget } from "./transaction-serialization.js";
+function systemRowLevelSecurityScope(reason) {
+    if (reason.trim() === "") {
+        throw new InternalError({
+            message: "A system row-level-security scope requires a non-empty reason.",
+        });
+    }
+    return { kind: "system", reason };
+}
+export const SYSTEM_ROW_LEVEL_SECURITY_SCOPE = systemRowLevelSecurityScope("framework-internal cross-tenant access");
+function describeRowLevelSecurityScope(scope) {
+    return scope.kind === "system"
+        ? `system (reason: ${scope.reason})`
+        : rowLevelSecurityScopeKey(scope);
+}
+export function tenantRowLevelSecurityScope(tenantId) {
+    return { kind: "tenant", tenantId };
+}
+const storage = new AsyncLocalStorage();
+export function activeRowLevelSecurityScope() {
+    return storage.getStore();
+}
+export function runInRowLevelSecurityScope(scope, fn) {
+    return storage.run(scope, fn);
+}
+export function runInSystemRowLevelSecurityScope(reason, fn) {
+    return storage.run(systemRowLevelSecurityScope(reason), fn);
+}
+// Drivers may invoke callbacks outside the caller's async context; undefined re-enters "no scope".
+export function runInCapturedRowLevelSecurityScope(captured, fn) {
+    return captured === undefined ? storage.exit(fn) : storage.run(captured, fn);
+}
+// DDL such as CREATE INDEX CONCURRENTLY cannot run in the per-statement transaction an enforced pool opens under a scope.
+export function outsideRowLevelSecurityScope(fn) {
+    return storage.exit(fn);
+}
+export function rowLevelSecurityScopeKey(scope) {
+    if (scope === undefined)
+        return "none";
+    return scope.kind === "system" ? "system" : `tenant:${scope.tenantId}`;
+}
+// Untyped JS callers can still omit the reason; fail at construction, not on the first query.
+export function systemModeOptions(reason) {
+    systemRowLevelSecurityScope(reason ?? "");
+    return { mode: "system", reason: reason ?? "" };
+}
+// Global tables carry SYSTEM_TENANT_ID rows; the app layer rejects tenant writes and filters reads.
+export function tenantDbRowLevelSecurityScope(options, tenantId, table) {
+    if (options.mode === "system")
+        return systemRowLevelSecurityScope(options.reason);
+    if (asEntityTableMeta(table)?.tenancy === "global")
+        return SYSTEM_ROW_LEVEL_SECURITY_SCOPE;
+    return tenantRowLevelSecurityScope(tenantId);
+}
+// A server or loop that inherits an ambient scope would run every later request fail-open.
+export function assertNoActiveRowLevelSecurityScope(startingWhat) {
+    const active = activeRowLevelSecurityScope();
+    // skip: no active scope, nothing leaked
+    if (active === undefined)
+        return;
+    throw new InternalError({
+        message: `${startingWhat} was started inside an active row-level-security scope (${describeRowLevelSecurityScope(active)}); long-lived loops must start outside any scope.`,
+    });
+}
+const scopedRunnerInners = new WeakMap();
+export function unscopedRunnerOf(runner) {
+    return scopedRunnerInners.get(runner) ?? runner;
+}
+export function innerOfScopedRunner(runner) {
+    if (typeof runner !== "object" && typeof runner !== "function")
+        return undefined;
+    return runner === null ? undefined : scopedRunnerInners.get(runner);
+}
+const SCOPED_METHODS = new Set([
+    "unsafe",
+    "begin",
+    "transaction",
+    "savepoint",
+]);
+export function withRowLevelSecurityScope(runner, scope) {
+    // Innermost scope wins: re-scoping unwraps instead of stacking proxies.
+    const inner = scopedRunnerInners.get(runner) ?? runner;
+    const proxy = new Proxy(inner, {
+        apply(target, _thisArg, args) {
+            if (typeof target !== "function") {
+                throw new TypeError("row-level-security scope proxy applied on a non-callable runner");
+            }
+            return runInRowLevelSecurityScope(scope, () => Reflect.apply(target, target, args));
+        },
+        get(target, prop) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== "function")
+                return value;
+            if (prop === "reserve") {
+                return async (...args) => {
+                    const reserved = await Reflect.apply(value, target, args);
+                    if (typeof reserved !== "object" || reserved === null)
+                        return reserved;
+                    return withRowLevelSecurityScope(reserved, scope);
+                };
+            }
+            if (SCOPED_METHODS.has(prop)) {
+                return (...args) => runInRowLevelSecurityScope(scope, () => Reflect.apply(value, target, args));
+            }
+            return value.bind(target);
+        },
+    });
+    scopedRunnerInners.set(proxy, inner);
+    registerRunnerProxyTarget(proxy, inner);
+    return proxy;
+}
+export function systemScopedRunner(runner, reason) {
+    return withRowLevelSecurityScope(runner, systemRowLevelSecurityScope(reason));
+}
+// Boot and tenant-resolution hooks run before any tenant is established, so the enforcing pool
+// would return zero rows; prod, dev and the test stack all hand them this same system scope.
+export function appHookScopedRunner(runner, mode) {
+    return mode === "on"
+        ? systemScopedRunner(runner, "app boot and tenant-resolution hooks run before any tenant is established")
+        : runner;
+}
+export function unsafeRawScopedRunner(runner) {
+    return systemScopedRunner(runner, "granted unsafeRaw bypasses the tenant filter by declaration");
+}

package/dist/db/scope-tenant-db-to-tenant.d.ts

@@ -0,0 +1,3 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { TenantId } from "../engine/types/identifiers.ts";
+export declare function scopeTenantDbToTenant(db: TenantDb, tenantId: TenantId): TenantDb;

package/dist/db/scope-tenant-db-to-tenant.js

@@ -0,0 +1,14 @@
+import { createTenantDb } from "./tenant-db.js";
+import { tenantDbRunner, tenantDbWritesDeniedReason } from "./tenant-db-runner.js";
+// 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 } }),
+    });
+}

package/dist/db/sql-identifier.d.ts

@@ -0,0 +1 @@
+export declare function quoteIdent(name: string): string;

package/dist/db/sql-identifier.js

@@ -0,0 +1,3 @@
+export function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}

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/table-builder.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
+import type { EntityDefinition, FieldDefinition, FieldsMap } from "@cosmicdrift/kumiko-types/fields";
+import type { EntityRelations } from "@cosmicdrift/kumiko-types/relations";
 import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
-import type { EntityDefinition, EntityRelations, FieldDefinition, FieldsMap } from "../engine/types/index.ts";
 import type { Table } from "./event-store-executor-context.ts";
 import type { LocatedTimestampRead } from "./located-timestamp.ts";
 import type { MoneyRead } from "./money.ts";

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