@cosmicdrift/kumiko-framework 0.389.0 → 0.390.1

package/dist/db/replay-rls.js

@@ -0,0 +1,156 @@
+// Row level security part of the migration replay: tracks ENABLE/FORCE flags and
+// policy definitions per table so they can be compared against the snapshot.
+import { renderCreatePolicy } from "./render-rls-ddl.js";
+import { quoteIdent } from "./sql-identifier.js";
+// Identifiers in hand-written migrations aren't always quoted (the generator
+// always quotes, but the header explicitly invites hand-editing) — optional
+// quotes so `CREATE TABLE foo (...)` parses the same as `CREATE TABLE "foo" (...)`.
+export const IDENT = `"?([^"\\s(;,.]+)"?`;
+export const TABLE_REF = `(?:"?public"?\\.)?${IDENT}`;
+const ALTER_TABLE_RE = new RegExp(`^ALTER\\s+TABLE\\s+(?:IF\\s+EXISTS\\s+)?(?:ONLY\\s+)?${TABLE_REF}\\s+([\\s\\S]*?);?\\s*$`, "i");
+const FLAG_CLAUSE_RE = /\b(ENABLE|DISABLE|NO\s+FORCE|FORCE)\s+ROW\s+LEVEL\s+SECURITY\b/gi;
+const CREATE_POLICY_RE = new RegExp(`^CREATE\\s+POLICY\\s+${IDENT}\\s+ON\\s+${TABLE_REF}(?=[\\s;]|$)([\\s\\S]*)$`, "i");
+const DROP_POLICY_RE = new RegExp(`^DROP\\s+POLICY\\s+(IF\\s+EXISTS\\s+)?${IDENT}\\s+ON\\s+${TABLE_REF}(?=[\\s;]|$)`, "i");
+const ALTER_POLICY_RE = new RegExp(`^ALTER\\s+POLICY\\s+${IDENT}\\s+ON\\s+${TABLE_REF}(?=[\\s;]|$)([\\s\\S]*)$`, "i");
+const RENAME_POLICY_RE = new RegExp(`^\\s*RENAME\\s+TO\\s+${IDENT}\\s*;?\\s*$`, "i");
+const POLICY_OR_RLS_RE = /\bPOLICY\b|ROW\s+LEVEL\s+SECURITY/i;
+const ANY_POLICY_STATEMENT_RE = /^(CREATE|ALTER|DROP)\s+POLICY\b/i;
+function stateOf(table) {
+    table.rowLevelSecurity ??= {
+        enabled: false,
+        forced: false,
+        policies: new Map(),
+    };
+    return table.rowLevelSecurity;
+}
+function applyFlagClauses(table, alterBody) {
+    for (const [, clause] of alterBody.matchAll(FLAG_CLAUSE_RE)) {
+        const state = stateOf(table);
+        switch (clause?.toUpperCase().replace(/\s+/g, " ")) {
+            case "ENABLE":
+                state.enabled = true;
+                break;
+            case "DISABLE":
+                state.enabled = false;
+                break;
+            case "FORCE":
+                state.forced = true;
+                break;
+            case "NO FORCE":
+                state.forced = false;
+                break;
+        }
+    }
+}
+function normalizePolicyDefinition(text) {
+    return text.replace(/\s+/g, " ").replace(/;\s*$/, "").trim();
+}
+function applyAlterPolicy(table, policyName, alterBody) {
+    const { policies } = stateOf(table);
+    const newName = alterBody.match(RENAME_POLICY_RE)?.[1];
+    if (newName === undefined) {
+        if (policies.has(policyName))
+            policies.set(policyName, undefined);
+        // skip: body is not a rename, the altered-flag above is all that is tracked
+        return;
+    }
+    // skip: policy not tracked, nothing to rename
+    if (!policies.has(policyName))
+        return;
+    policies.set(newName, policies.get(policyName));
+    policies.delete(policyName);
+}
+function failUnparsedPolicy(statement, file) {
+    const prefix = statement.slice(0, 200).replace(/\s+/g, " ").trim();
+    throw new Error(`replayMigrationsDir: unparsed policy statement in ${file} — expected CREATE POLICY <name> ON <table>, ` +
+        `DROP POLICY [IF EXISTS] <name> ON <table> or ALTER POLICY <name> ON <table>. Statement: ${prefix}${statement.length > 200 ? "…" : ""}`);
+}
+function tryApplyAlterTable(tables, statement) {
+    const alter = statement.match(ALTER_TABLE_RE);
+    if (alter?.[1] === undefined || alter[2] === undefined)
+        return false;
+    const table = tables.get(alter[1]);
+    if (table)
+        applyFlagClauses(table, alter[2]);
+    return true;
+}
+function tryApplyCreatePolicy(tables, statement) {
+    const created = statement.match(CREATE_POLICY_RE);
+    if (created?.[1] === undefined || created[2] === undefined)
+        return false;
+    const table = tables.get(created[2]);
+    if (table) {
+        stateOf(table).policies.set(created[1], normalizePolicyDefinition(created[3] ?? ""));
+    }
+    return true;
+}
+function tryApplyDropPolicy(tables, statement, context) {
+    const dropped = statement.match(DROP_POLICY_RE);
+    if (dropped?.[2] === undefined || dropped[3] === undefined)
+        return false;
+    const table = tables.get(dropped[3]);
+    if (!table)
+        return true;
+    const removed = stateOf(table).policies.delete(dropped[2]);
+    if (!removed && dropped[1] === undefined) {
+        throw new Error(`replayMigrationsDir: ${context.file} drops policy "${dropped[2]}" on "${dropped[3]}" which no earlier migration created`);
+    }
+    return true;
+}
+function tryApplyAlterPolicy(tables, statement) {
+    const altered = statement.match(ALTER_POLICY_RE);
+    if (altered?.[1] === undefined || altered[2] === undefined || altered[3] === undefined) {
+        return false;
+    }
+    const table = tables.get(altered[2]);
+    if (table)
+        applyAlterPolicy(table, altered[1], altered[3]);
+    return true;
+}
+export function applyRowLevelSecurityStatement(tables, statement, context) {
+    if (/^DO\b/i.test(statement) && POLICY_OR_RLS_RE.test(statement)) {
+        throw new Error(`replayMigrationsDir: ${context.file} changes policies or row level security inside a DO block, which the replay cannot evaluate — write the statements at top level`);
+    }
+    const handled = tryApplyAlterTable(tables, statement) ||
+        tryApplyCreatePolicy(tables, statement) ||
+        tryApplyDropPolicy(tables, statement, context) ||
+        tryApplyAlterPolicy(tables, statement);
+    if (!handled && ANY_POLICY_STATEMENT_RE.test(statement)) {
+        failUnparsedPolicy(statement, context.file);
+    }
+}
+function expectedPolicyDefinition(tableName, policy) {
+    const rendered = renderCreatePolicy(quoteIdent(tableName), policy);
+    const definition = rendered.match(CREATE_POLICY_RE)?.[3];
+    if (definition === undefined) {
+        throw new Error(`rendered policy "${policy.name}" is not a CREATE POLICY statement`);
+    }
+    return normalizePolicyDefinition(definition);
+}
+export function rowLevelSecurityDrift(replayed, tableName, expected) {
+    const parts = [];
+    if (replayed?.enabled !== true)
+        parts.push("ROW LEVEL SECURITY is not enabled");
+    if (replayed?.forced !== true)
+        parts.push("ROW LEVEL SECURITY is not forced");
+    const actual = replayed?.policies ?? new Map();
+    const expectedNames = new Set(expected.policies.map((policy) => policy.name));
+    for (const policy of expected.policies) {
+        if (!actual.has(policy.name)) {
+            parts.push(`missing policy: ${policy.name}`);
+        }
+        else if (actual.get(policy.name) !== expectedPolicyDefinition(tableName, policy)) {
+            parts.push(`policy ${policy.name} deviates from the generated definition (hand-edited or altered)`);
+        }
+    }
+    const unexpected = [...actual.keys()].filter((name) => !expectedNames.has(name));
+    if (unexpected.length > 0)
+        parts.push(`unexpected policies: ${unexpected.join(", ")}`);
+    return parts.length > 0 ? parts.join("; ") : undefined;
+}
+export function replayedOnlyRowLevelSecurityDrift(replayed) {
+    const hasRowLevelSecurity = replayed !== undefined && (replayed.enabled || replayed.forced || replayed.policies.size > 0);
+    return hasRowLevelSecurity
+        ? "migrations enable row level security or create policies but .snapshot.json has no row level security spec for this table"
+        : undefined;
+}

package/dist/db/row-level-security-boot-check.d.ts

@@ -0,0 +1,6 @@
+import { type KnownTables } from "./known-table-names.ts";
+import type { AnyDb } from "./query.ts";
+import type { RowLevelSecurityMode } from "./render-rls-ddl.ts";
+export type RowLevelSecurityCheckScope = "database" | "declared tables";
+export declare function assertRowLevelSecurityTableState(db: AnyDb, mode: RowLevelSecurityMode, knownTables: KnownTables, scope?: RowLevelSecurityCheckScope): Promise<void>;
+export declare function assertRowLevelSecurityBootState(db: AnyDb, mode: RowLevelSecurityMode, knownTables: KnownTables): Promise<void>;

package/dist/db/row-level-security-boot-check.js

@@ -0,0 +1,86 @@
+import { InternalError } from "../errors/index.js";
+import { isLiveFrameworkTable } from "./known-table-names.js";
+import { readConnectedRoleAttributes, readTablesWithRowLevelSecurityEnabled, readTenantTablesRowLevelSecurity, } from "./queries/rls-boot-catalog.js";
+function missingPartsOf(table) {
+    return [
+        ...(table.enabled ? [] : ["ENABLE ROW LEVEL SECURITY"]),
+        ...(table.forced ? [] : ["FORCE ROW LEVEL SECURITY"]),
+        ...(table.hasIsolationPolicy ? [] : ["policy kumiko_tenant_isolation"]),
+        ...(table.hasSystemReadPolicy ? [] : ["policy kumiko_system_tenant_read"]),
+    ];
+}
+async function assertEnforcingRole(db) {
+    const role = await readConnectedRoleAttributes(db);
+    if (role === undefined) {
+        throw new InternalError({ message: "row-level security boot check: current role not found." });
+    }
+    const bypassing = [
+        ...(role.superuser ? ["SUPERUSER"] : []),
+        ...(role.bypassRowLevelSecurity ? ["BYPASSRLS"] : []),
+    ];
+    // skip: every role enforces row-level security
+    if (bypassing.length === 0)
+        return;
+    throw new InternalError({
+        message: `rowLevelSecurity is "on" but the database role "${role.roleName}" has ${bypassing.join(" and ")}, which makes Postgres skip every policy. Connect as a role with NOSUPERUSER NOBYPASSRLS.`,
+    });
+}
+function listingOf(entries) {
+    return entries.map((entry) => `${entry.table} (${entry.missing.join(", ")})`).join("; ");
+}
+async function assertAllTenantTablesProtected(db, knownTables, scope) {
+    const incomplete = (await readTenantTablesRowLevelSecurity(db))
+        .filter((table) => scope === "database" || knownTables.has(table.tableName))
+        .map((table) => ({ table: table.tableName, missing: missingPartsOf(table) }))
+        .filter((entry) => entry.missing.length > 0);
+    // skip: every tenant table is protected
+    if (incomplete.length === 0)
+        return;
+    const frameworkTables = incomplete.filter((entry) => isLiveFrameworkTable(entry.table));
+    const known = incomplete.filter((entry) => !isLiveFrameworkTable(entry.table) && knownTables.has(entry.table));
+    const orphaned = incomplete.filter((entry) => !knownTables.has(entry.table));
+    const sections = [
+        ...(frameworkTables.length > 0
+            ? [
+                `framework tables without it: ${listingOf(frameworkTables)}. Run \`kumiko schema apply\`: it adds the missing policies to the framework tables (\`kumiko schema generate\` reports no changes for them).`,
+            ]
+            : []),
+        ...(known.length > 0
+            ? [
+                `tables of this app without it: ${listingOf(known)}. Run \`kumiko schema generate\` and apply the migration.`,
+            ]
+            : []),
+        ...(orphaned.length > 0
+            ? [
+                `tables no feature declares anymore: ${listingOf(orphaned)}. No feature declares them: add a migration with DROP TABLE (enable the commented \`-- DESTRUCTIVE\` DROP that \`kumiko schema generate\` emitted; see \`kumiko schema status\`).`,
+            ]
+            : []),
+    ];
+    throw new InternalError({
+        message: `rowLevelSecurity is "on" but tenant tables lack row-level security. ${sections.join(" ")}`,
+    });
+}
+async function assertNoLiveRowLevelSecurity(db, knownTables, scope) {
+    const tables = (await readTablesWithRowLevelSecurityEnabled(db)).filter((table) => scope === "database" || knownTables.has(table));
+    // skip: no live row-level security to disable
+    if (tables.length === 0)
+        return;
+    throw new InternalError({
+        message: `rowLevelSecurity is "off" but row-level security is still enabled on: ${tables.join(", ")}. Without a tenant scope every statement would see zero rows. Run \`kumiko schema generate\` with rowLevelSecurity off to produce the DISABLE ROW LEVEL SECURITY migration and apply it.`,
+    });
+}
+// Table state only, no role check: the role is a runtime property of the boot connection, so tools
+// that connect with another role (CI, `schema validate`) use this one.
+export async function assertRowLevelSecurityTableState(db, mode, knownTables, scope = "database") {
+    if (mode === "off") {
+        await assertNoLiveRowLevelSecurity(db, knownTables, scope);
+        // skip: off-mode check done
+        return;
+    }
+    await assertAllTenantTablesProtected(db, knownTables, scope);
+}
+export async function assertRowLevelSecurityBootState(db, mode, knownTables) {
+    if (mode === "on")
+        await assertEnforcingRole(db);
+    await assertRowLevelSecurityTableState(db, mode, knownTables);
+}

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

@@ -0,0 +1,3 @@
+import type { RowLevelSecurityMode } from "./render-rls-ddl.ts";
+export declare function rowLevelSecurityModeOf(db: unknown): RowLevelSecurityMode;
+export declare function enforceRowLevelSecurity<T extends object>(pool: T): T;

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