@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/db/migrate-runner.js

@@ -17,7 +17,9 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { applyRowLevelSecurityScope } from "./queries/rls-scope.js";
 import { asRawClient, hasBegin, } from "./query.js";
+import { SYSTEM_ROW_LEVEL_SECURITY_SCOPE } from "./row-level-security-scope.js";
 // Advisory-lock key (random 32-bit integer, stable). Prevents two Pods
 // booting at the same time from both running migrate apply (the second
 // blocks until the first finishes).
@@ -188,16 +190,16 @@ function migrationClient(db) {
         if (hasBegin(client))
             return client;
     }
-    throw new Error("migrate-runner: db argument has no .unsafe() and .begin() (need a postgres-js Sql or drizzle DbConnection)");
+    throw new Error("migrate-runner: db argument has no .unsafe() and .begin() (need a Bun.SQL pool or a DbConnection)");
 }
-// Raw-SQL via postgres-js .unsafe().
+// Raw-SQL via Bun.SQL .unsafe().
 async function executeRaw(db, sqlText) {
     await migrationClient(db).unsafe(sqlText);
 }
 async function reserveConnection(db) {
     const client = migrationClient(db);
     if (typeof client.reserve !== "function") {
-        throw new Error("migrate-runner: db argument has no .reserve() (need a postgres-js Sql)");
+        throw new Error("migrate-runner: db argument has no .reserve() (need a Bun.SQL pool)");
     }
     return client.reserve();
 }
@@ -261,6 +263,8 @@ export async function runMigrations(db, migrations) {
                 // apply remains stuck in the books.
                 await conn.unsafe("BEGIN");
                 try {
+                    // Transaction-local, so the next migration's BEGIN starts clean; migrations rewrite every tenant's rows.
+                    await applyRowLevelSecurityScope(conn, SYSTEM_ROW_LEVEL_SECURITY_SCOPE);
                     for (const stmt of m.statements) {
                         await conn.unsafe(stmt);
                     }

package/dist/db/money.d.ts

@@ -1,5 +1,5 @@
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import { toMinorUnits } from "../engine/minor-units.ts";
-import type { EntityDefinition } from "../engine/types/index.ts";
 export { toMinorUnits };
 export declare function moneyPayloadToMinorUnits(raw: unknown): number | undefined;
 export declare function flattenMoney(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;

package/dist/db/money.js

@@ -8,6 +8,7 @@
 //               MINOR_UNIT_SCALE units for callers that need scale-exact
 //               comparisons (e.g. invoice sums) instead of round-tripping the
 //               float amount through /100·*100.
+import { DEFAULT_CURRENCIES } from "../engine/field-helpers.js";
 //                `amountMinor` stays as a @deprecated alias of the same
 //               value until the remaining consumers
 //               (renderer/web/primitives/index.tsx,
@@ -31,7 +32,6 @@
 // amount column (legacy DB convention for money — `SUM(buying_price)` remains
 // idiomatic). `<name>Currency` is the additional column.
 import { MINOR_UNIT_SCALE, toMinorUnits } from "../engine/minor-units.js";
-import { DEFAULT_CURRENCIES } from "../engine/types/index.js";
 const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
 export { toMinorUnits };
 function toMajorUnits(amountScaled) {

package/dist/db/parent-ref-clause.d.ts

@@ -1,6 +1,7 @@
 import type { ParentVisibilityOption } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import { type OwnershipClause } from "../engine/ownership.ts";
-import type { EntityDefinition, SessionUser } from "../engine/types/index.ts";
+import type { SessionUser } from "../engine/types/index.ts";
 import type { Table } from "./event-store-executor-context.ts";
 import type { TenantDb } from "./tenant-db.ts";
 export type { ParentVisibilityOption } from "@cosmicdrift/kumiko-types/event-store-executor-types";

package/dist/db/pg-error.d.ts

@@ -3,8 +3,10 @@ export type PgErrorInfo = {
     readonly constraint_name: string | undefined;
 };
 export declare function extractPgError(e: unknown): PgErrorInfo | null;
+export declare function isInvalidDateTimeValue(e: unknown): boolean;
 export declare function isUniqueViolation(e: unknown): boolean;
 export declare function isTableAlreadyExists(e: unknown): boolean;
 export declare function isLockNotAvailable(e: unknown): boolean;
 export declare function isUndefinedTable(e: unknown): boolean;
+export declare function isRowLevelSecurityViolation(e: unknown): boolean;
 export declare function constraintOf(e: unknown): string | undefined;

package/dist/db/pg-error.js

@@ -1,31 +1,43 @@
-// Drizzle wraps postgres-js errors in `DrizzleQueryError`; the original PG
-// error (with SQLSTATE `code` and `constraint_name`) lives in `.cause`. We
-// unwrap both layers so callers don't have to know which layer produced the
-// error. Used by the event-store to distinguish a unique-violation on the
-// aggregate-version index (optimistic-concurrency conflict) from the one on
-// the idempotency-key index (caller-side replay signal).
+// Bun.SQL server errors carry the SQLSTATE in `errno` and the constraint in
+// `constraint` (`code` is the generic ERR_POSTGRES_SERVER_ERROR). Client-side
+// failures have no `errno`, so their `code` (e.g. ERR_POSTGRES_CONNECTION_CLOSED)
+// is returned instead. The `.cause` chain is walked so wrapped errors resolve too.
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 const MAX_CAUSE_DEPTH = 8;
+function stringOrUndefined(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function infoOfLayer(layer) {
+    const sqlState = stringOrUndefined(propertyOf(layer, "errno"));
+    if (sqlState !== undefined) {
+        return {
+            code: sqlState,
+            constraint_name: stringOrUndefined(propertyOf(layer, "constraint")),
+        };
+    }
+    const code = stringOrUndefined(propertyOf(layer, "code"));
+    return code === undefined ? null : { code, constraint_name: undefined };
+}
 export function extractPgError(e) {
-    if (typeof e !== "object" || e === null)
-        return null;
-    const layers = [];
     let current = e;
     // Depth cap doubles as cycle protection for self-referential causes.
-    while (typeof current === "object" && current !== null && layers.length < MAX_CAUSE_DEPTH) {
-        layers.push(current);
-        // @cast-boundary error-details — DrizzleQueryError wraps PG-error in .cause
-        current = current.cause;
-    }
-    for (const layer of layers) {
-        // @cast-boundary error-details — postgres-js error shape (code, constraint_name)
-        const code = layer.code;
-        const constraintName = layer.constraint_name; // @cast-boundary error-details
-        if (code !== undefined || constraintName !== undefined) {
-            return { code, constraint_name: constraintName };
-        }
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
+        if (typeof current !== "object" || current === null)
+            return null;
+        const info = infoOfLayer(current);
+        if (info !== null)
+            return info;
+        current = propertyOf(current, "cause");
     }
     return null;
 }
+// PG SQLSTATE 22007 invalid_datetime_format and 22008 datetime_field_overflow: the
+// column type rejects the value ("not-a-date", or "2026-02-30" for a date column).
+const INVALID_DATETIME_VALUE_CODES = new Set(["22007", "22008"]);
+export function isInvalidDateTimeValue(e) {
+    const code = extractPgError(e)?.code;
+    return code !== undefined && INVALID_DATETIME_VALUE_CODES.has(code);
+}
 export function isUniqueViolation(e) {
     return extractPgError(e)?.code === "23505";
 }
@@ -50,6 +62,10 @@ export function isLockNotAvailable(e) {
 export function isUndefinedTable(e) {
     return extractPgError(e)?.code === "42P01";
 }
+// PG SQLSTATE 42501 insufficient_privilege: a row failing a row-level-security WITH CHECK policy.
+export function isRowLevelSecurityViolation(e) {
+    return extractPgError(e)?.code === "42501";
+}
 export function constraintOf(e) {
     return extractPgError(e)?.constraint_name;
 }

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

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

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

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

package/dist/db/queries/ddl.d.ts

@@ -1,4 +1,7 @@
+import type { DbConnection } from "../connection.ts";
+import type { EntityTableMeta } from "../entity-table-meta.ts";
 import type { AnyDb } from "../query.ts";
 export declare function executeDdlStatement(db: AnyDb, sqlText: string): Promise<void>;
 export declare function alterTableAddColumn(db: AnyDb, tableName: string, columnName: string, columnType: string, defaultClause: string, notNull: string, ifNotExists?: boolean): Promise<void>;
 export declare function createIndexIfNotExists(db: AnyDb, indexKind: "UNIQUE INDEX" | "INDEX", indexName: string, tableName: string, columnList: string, whereSql?: string): Promise<void>;
+export declare function applyTableRowLevelSecurity(db: DbConnection, meta: EntityTableMeta): Promise<void>;

package/dist/db/queries/ddl.js

@@ -1,4 +1,7 @@
-import { asRawClient } from "../query.js";
+import { asRawClient, transaction } from "../query.js";
+import { renderTableRowLevelSecurityDdl, tenantRowLevelSecurityFor } from "../render-rls-ddl.js";
+import { quoteIdent } from "../sql-identifier.js";
+import { readRowLevelSecurityShape } from "./rls-shape.js";
 import { quoteTableIdent } from "./table-ops.js";
 // Generic DDL helpers used on the prod-boot path (db/table-push.ts's
 // unsafePushTables, event-consumer-state.ts's multi-instance backfill) —
@@ -20,3 +23,33 @@ export async function createIndexIfNotExists(db, indexKind, indexName, tableName
     const where = whereSql !== undefined ? ` WHERE ${whereSql}` : "";
     await asRawClient(db).unsafe(`CREATE ${indexKind} IF NOT EXISTS ${quoteTableIdent(indexName)} ON ${quoteTableIdent(tableName)} (${columnList})${where}`);
 }
+// Policy texts are not compared: a hand-edited kumiko policy is the operator's to keep, and the
+// catalog check of the boot path reports it. Foreign policies are ignored.
+function hasKumikoRowLevelSecurity(state, meta) {
+    const spec = tenantRowLevelSecurityFor(meta);
+    if (state === undefined || spec === undefined || !state.enabled || !state.forced)
+        return false;
+    return spec.policies.every((expected) => state.policies.some((actual) => actual.name === expected.name &&
+        actual.kind === expected.kind &&
+        actual.command === expected.command));
+}
+export async function applyTableRowLevelSecurity(db, meta) {
+    const statements = renderTableRowLevelSecurityDdl(meta);
+    // skip: no tenant_id column, nothing to enforce
+    if (statements.length === 0)
+        return;
+    // skip: already applied, so a repeated push takes no lock and runs no DDL
+    if (hasKumikoRowLevelSecurity(await readRowLevelSecurityShape(db, meta.tableName), meta)) {
+        return;
+    }
+    await transaction(db, async (tx) => {
+        // Self-conflicting lock: parallel pushes queue up instead of failing CREATE POLICY with duplicate_object.
+        await tx.unsafe(`LOCK TABLE ${quoteIdent(meta.tableName)} IN SHARE ROW EXCLUSIVE MODE`);
+        // skip: a parallel push applied it while this one waited for the lock
+        if (hasKumikoRowLevelSecurity(await readRowLevelSecurityShape(tx, meta.tableName), meta)) {
+            return;
+        }
+        for (const statement of statements)
+            await tx.unsafe(statement);
+    });
+}

package/dist/db/queries/event-store.js

@@ -1,6 +1,7 @@
 import { createFallbackLogger } from "../../logging/utils.js";
 import { constraintOf, isLockNotAvailable, isTableAlreadyExists, isUniqueViolation, } from "../pg-error.js";
 import { asRawClient, runInNewTransaction, runnerCanBeginTransaction, unsafeReadRetrying, } from "../query.js";
+import { innerOfScopedRunner, outsideRowLevelSecurityScope } from "../row-level-security-scope.js";
 import { withoutStatementTimeout } from "../statement-timeout.js";
 import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 const log = createFallbackLogger("event-store");
@@ -51,8 +52,9 @@ async function indexValidity(client, indexName = IDEMPOTENCY_INDEX_NAME) {
         `WHERE c.relname = $1 AND i.indrelid = '"kumiko_events"'::regclass`, [indexName]);
     return rows[0]?.indisvalid;
 }
+// Index DDL carries no tenant data and CONCURRENTLY cannot run in a transaction, so both the pinned runner and the ambient scope are left.
 export function ensureIdempotencyKeyIndex(db) {
-    return withoutStatementTimeout(db, buildIdempotencyKeyIndex);
+    return outsideRowLevelSecurityScope(() => withoutStatementTimeout(innerOfScopedRunner(db) ?? db, buildIdempotencyKeyIndex));
 }
 async function buildIdempotencyKeyIndex(db) {
     const client = asRawClient(db);
@@ -96,7 +98,7 @@ async function buildIdempotencyKeyIndex(db) {
 // tenant), which no other index covers: without this it scans every event.
 // Same CONCURRENTLY + INVALID-rebuild handling as the idempotency index.
 export function ensureMembershipPayloadTenantIndex(db) {
-    return withoutStatementTimeout(db, buildMembershipPayloadTenantIndex);
+    return outsideRowLevelSecurityScope(() => withoutStatementTimeout(innerOfScopedRunner(db) ?? db, buildMembershipPayloadTenantIndex));
 }
 async function buildMembershipPayloadTenantIndex(db) {
     const client = asRawClient(db);

package/dist/db/queries/event-tenants.d.ts

@@ -0,0 +1,2 @@
+import type { AnyDb } from "../query.ts";
+export declare function listEventTenantIds(db: AnyDb): Promise<readonly string[]>;

package/dist/db/queries/event-tenants.js

@@ -0,0 +1,17 @@
+import { unsafeReadRetrying } from "../query.js";
+// Every tenant_id that owns at least one event. Loose index scan: one probe on
+// events_tenant_type_idx (leading column tenant_id) per distinct value, so the cost follows the
+// number of tenants, not the number of events.
+export async function listEventTenantIds(db) {
+    const rows = await unsafeReadRetrying(db, `WITH RECURSIVE tenants AS (
+       (SELECT "tenant_id" FROM "kumiko_events" ORDER BY "tenant_id" LIMIT 1)
+       UNION ALL
+       SELECT (SELECT e."tenant_id" FROM "kumiko_events" e
+                WHERE e."tenant_id" > tenants."tenant_id"
+                ORDER BY e."tenant_id" LIMIT 1)
+         FROM tenants
+        WHERE tenants."tenant_id" IS NOT NULL
+     )
+     SELECT "tenant_id"::text AS tenant_id FROM tenants WHERE "tenant_id" IS NOT NULL`, []);
+    return rows.map((row) => row.tenant_id);
+}

package/dist/db/queries/rebuild-rls-guard.d.ts

@@ -0,0 +1,2 @@
+import { type AnyDb } from "../query.ts";
+export declare function assertRebuildableRowLevelSecurity(tx: AnyDb, tableName: string): Promise<void>;

package/dist/db/queries/rebuild-rls-guard.js

@@ -0,0 +1,29 @@
+// First statement of a rebuild tx. The rebuild runs in system scope, which the tenant isolation
+// policy admits for every row; a table whose policies differ from the framework's shape could hide
+// rows from the guards and let the swap drop them, so it is refused before anything is read.
+import { asRawClient } from "../query.js";
+import { TENANT_ISOLATION_POLICY } from "../render-rls-ddl.js";
+import { readRowLevelSecurityShape } from "./rls-shape.js";
+import { quoteTableIdent } from "./table-ops.js";
+export async function assertRebuildableRowLevelSecurity(tx, tableName) {
+    // SHARE UPDATE EXCLUSIVE conflicts with CREATE/ALTER/DROP POLICY and ENABLE/FORCE (ACCESS EXCLUSIVE) but not with readers, and with itself: a second rebuild waits instead of both holding a shared lock and deadlocking on the swap's ACCESS EXCLUSIVE.
+    await asRawClient(tx).unsafe(`LOCK TABLE public.${quoteTableIdent(tableName)} IN SHARE UPDATE EXCLUSIVE MODE`);
+    const state = await readRowLevelSecurityShape(tx, tableName);
+    // skip: table has no row-level security, nothing to verify
+    if (state === undefined || !state.enabled)
+        return;
+    const isolation = state.policies.find((policy) => policy.name === TENANT_ISOLATION_POLICY);
+    const hasRestrictive = state.policies.some((policy) => policy.kind === "RESTRICTIVE");
+    const isolationIntact = isolation !== undefined &&
+        isolation.kind === "PERMISSIVE" &&
+        isolation.command === "ALL" &&
+        isolation.appliesToPublic;
+    // skip: framework policy intact, rebuild reads are safe
+    if (isolationIntact && !hasRestrictive)
+        return;
+    const listed = state.policies
+        .map((policy) => `${policy.name} (${policy.kind} ${policy.command})`)
+        .join(", ");
+    throw new Error(`rebuild: public.${tableName} has row level security that a system scope rebuild cannot rely on ` +
+        `(needs a PERMISSIVE ALL ${TENANT_ISOLATION_POLICY} policy for PUBLIC and no RESTRICTIVE policy); policies: ${listed || "(none)"}`);
+}

package/dist/db/queries/rls-boot-catalog.d.ts

@@ -0,0 +1,16 @@
+import type { AnyDb } from "../query.ts";
+export type ConnectedRoleAttributes = {
+    readonly roleName: string;
+    readonly superuser: boolean;
+    readonly bypassRowLevelSecurity: boolean;
+};
+export type TenantTableRowLevelSecurity = {
+    readonly tableName: string;
+    readonly enabled: boolean;
+    readonly forced: boolean;
+    readonly hasIsolationPolicy: boolean;
+    readonly hasSystemReadPolicy: boolean;
+};
+export declare function readConnectedRoleAttributes(db: AnyDb): Promise<ConnectedRoleAttributes | undefined>;
+export declare function readTenantTablesRowLevelSecurity(db: AnyDb): Promise<readonly TenantTableRowLevelSecurity[]>;
+export declare function readTablesWithRowLevelSecurityEnabled(db: AnyDb): Promise<readonly string[]>;

package/dist/db/queries/rls-boot-catalog.js

@@ -0,0 +1,39 @@
+import { asRawClient } from "../query.js";
+import { SYSTEM_TENANT_READ_POLICY, TENANT_ISOLATION_POLICY } from "../render-rls-ddl.js";
+export async function readConnectedRoleAttributes(db) {
+    const rows = await asRawClient(db).unsafe(`SELECT rolname, rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user`);
+    const row = rows[0];
+    if (row === undefined)
+        return undefined;
+    return {
+        roleName: row.rolname,
+        superuser: row.rolsuper,
+        bypassRowLevelSecurity: row.rolbypassrls,
+    };
+}
+export async function readTenantTablesRowLevelSecurity(db) {
+    const rows = await asRawClient(db).unsafe(`SELECT c.relname, c.relrowsecurity, c.relforcerowsecurity,
+       EXISTS (SELECT 1 FROM pg_policies p
+         WHERE p.schemaname = 'public' AND p.tablename = c.relname AND p.policyname = $1) AS has_isolation,
+       EXISTS (SELECT 1 FROM pg_policies p
+         WHERE p.schemaname = 'public' AND p.tablename = c.relname AND p.policyname = $2) AS has_system_read
+     FROM pg_class c
+     JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p')
+       AND EXISTS (SELECT 1 FROM pg_attribute a
+         WHERE a.attrelid = c.oid AND a.attname = 'tenant_id' AND a.attnum > 0 AND NOT a.attisdropped)
+     ORDER BY c.relname COLLATE "C"`, [TENANT_ISOLATION_POLICY, SYSTEM_TENANT_READ_POLICY]);
+    return rows.map((row) => ({
+        tableName: row.relname,
+        enabled: row.relrowsecurity,
+        forced: row.relforcerowsecurity,
+        hasIsolationPolicy: row.has_isolation,
+        hasSystemReadPolicy: row.has_system_read,
+    }));
+}
+export async function readTablesWithRowLevelSecurityEnabled(db) {
+    const rows = await asRawClient(db).unsafe(`SELECT c.relname FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p') AND c.relrowsecurity
+     ORDER BY c.relname COLLATE "C"`);
+    return rows.map((row) => row.relname);
+}

package/dist/db/queries/rls-catalog.d.ts

@@ -0,0 +1,6 @@
+import { type AnyDb } from "../query.ts";
+import { type RowLevelSecurityFlags, type TableRowLevelSecurity } from "../render-rls-ddl.ts";
+export type RowLevelSecurityState = RowLevelSecurityFlags & TableRowLevelSecurity;
+export declare function readRowLevelSecurityState(db: AnyDb, schemaName: string, tableName: string): Promise<RowLevelSecurityState | undefined>;
+export declare function describeRowLevelSecurityDifference(expected: RowLevelSecurityState, actual: RowLevelSecurityState | undefined): string | undefined;
+export declare function restoreRowLevelSecurityState(tx: AnyDb, tableName: string, expected: RowLevelSecurityState): Promise<void>;

package/dist/db/queries/rls-catalog.js

@@ -0,0 +1,82 @@
+// Reads and restores a table's row level security state from the Postgres catalog.
+// The shadow swap rebuilds a table from EntityTableMeta, which carries no policies:
+// the live state is read before the swap and re-applied (then verified) afterwards.
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { asRawClient } from "../query.js";
+import { POLICY_COMMANDS, POLICY_KINDS, renderCreatePolicy, } from "../render-rls-ddl.js";
+import { quoteTableIdent } from "./table-ops.js";
+function toPolicy(row) {
+    if (!isOneOf(POLICY_COMMANDS, row.cmd) || !isOneOf(POLICY_KINDS, row.permissive)) {
+        throw new Error(`row level security: policy "${row.policyname}" has unsupported command "${row.cmd}" or kind "${row.permissive}"`);
+    }
+    return {
+        name: row.policyname,
+        command: row.cmd,
+        kind: row.permissive,
+        rolesSql: row.roles_sql,
+        ...(row.qual !== null && { using: row.qual }),
+        ...(row.with_check !== null && { withCheck: row.with_check }),
+    };
+}
+export async function readRowLevelSecurityState(db, schemaName, tableName) {
+    const raw = asRawClient(db);
+    const flagRows = await raw.unsafe(`SELECT c.relrowsecurity, c.relforcerowsecurity
+     FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = $1 AND c.relname = $2`, [schemaName, tableName]);
+    const flags = flagRows[0];
+    if (flags === undefined)
+        return undefined;
+    const policyRows = await raw.unsafe(`SELECT policyname, permissive, cmd, qual, with_check,
+       array_to_string(ARRAY(SELECT CASE WHEN r = 'public' THEN 'PUBLIC' ELSE quote_ident(r) END
+         FROM unnest(roles) AS r ORDER BY r::text COLLATE "C"), ', ') AS roles_sql
+     FROM pg_policies WHERE schemaname = $1 AND tablename = $2
+     ORDER BY policyname COLLATE "C"`, [schemaName, tableName]);
+    return {
+        enabled: flags.relrowsecurity,
+        forced: flags.relforcerowsecurity,
+        policies: policyRows.map(toPolicy),
+    };
+}
+function describePolicyDifference(expected, actual) {
+    if (actual === undefined)
+        return `policy ${expected.name} missing`;
+    const fields = ["command", "kind", "rolesSql", "using", "withCheck"];
+    const differing = fields.filter((field) => expected[field] !== actual[field]);
+    return differing.length > 0
+        ? `policy ${expected.name} differs in ${differing.join(", ")}`
+        : undefined;
+}
+export function describeRowLevelSecurityDifference(expected, actual) {
+    if (actual === undefined)
+        return "table missing";
+    const differences = [];
+    if (expected.enabled !== actual.enabled)
+        differences.push(`enabled ${expected.enabled} -> ${actual.enabled}`);
+    if (expected.forced !== actual.forced)
+        differences.push(`forced ${expected.forced} -> ${actual.forced}`);
+    const actualByName = new Map(actual.policies.map((policy) => [policy.name, policy]));
+    for (const policy of expected.policies) {
+        const difference = describePolicyDifference(policy, actualByName.get(policy.name));
+        if (difference !== undefined)
+            differences.push(difference);
+    }
+    const expectedNames = new Set(expected.policies.map((policy) => policy.name));
+    for (const policy of actual.policies) {
+        if (!expectedNames.has(policy.name))
+            differences.push(`unexpected policy ${policy.name}`);
+    }
+    return differences.length > 0 ? differences.join("; ") : undefined;
+}
+export async function restoreRowLevelSecurityState(tx, tableName, expected) {
+    const raw = asRawClient(tx);
+    const tableSql = `public.${quoteTableIdent(tableName)}`;
+    for (const policy of expected.policies) {
+        await raw.unsafe(renderCreatePolicy(tableSql, policy));
+    }
+    // One ALTER TABLE for both flags: each ALTER TABLE is a separate DDL command (and event-trigger firing) on the swap's critical path.
+    await raw.unsafe(`ALTER TABLE ${tableSql} ${expected.enabled ? "ENABLE" : "DISABLE"} ROW LEVEL SECURITY, ${expected.forced ? "FORCE" : "NO FORCE"} ROW LEVEL SECURITY`);
+    const difference = describeRowLevelSecurityDifference(expected, await readRowLevelSecurityState(tx, "public", tableName));
+    if (difference !== undefined) {
+        throw new Error(`shadow swap: row level security of public.${tableName} differs after the swap: ${difference}`);
+    }
+}

package/dist/db/queries/rls-scope.d.ts

@@ -0,0 +1,3 @@
+import type { RowLevelSecurityScope } from "../row-level-security-scope.ts";
+export declare function buildRowLevelSecurityScopeQuery(runner: unknown, scope: RowLevelSecurityScope | undefined): PromiseLike<unknown>;
+export declare function applyRowLevelSecurityScope(runner: unknown, scope: RowLevelSecurityScope | undefined): Promise<void>;

package/dist/db/queries/rls-scope.js

@@ -0,0 +1,17 @@
+import { asRawClient } from "../query.js";
+import { SCOPE_SETTING, SYSTEM_SCOPE, TENANT_ID_SETTING } from "../render-rls-ddl.js";
+function scopeSettings(scope) {
+    const tenantId = scope?.kind === "tenant" ? scope.tenantId : "";
+    const systemScope = scope?.kind === "system" ? SYSTEM_SCOPE : "";
+    return [TENANT_ID_SETTING, tenantId, SCOPE_SETTING, systemScope];
+}
+const SET_SCOPE_SQL = `SELECT set_config($1, $2, true), set_config($3, $4, true)`;
+// Returns the lazy driver query without sending it, so a caller can pipeline it right behind BEGIN;
+// the caller must start it itself and in order.
+export function buildRowLevelSecurityScopeQuery(runner, scope) {
+    return asRawClient(runner).unsafe(SET_SCOPE_SQL, [...scopeSettings(scope)]);
+}
+// set_config(..., true) is transaction-local; undefined clears both settings to ''.
+export async function applyRowLevelSecurityScope(runner, scope) {
+    await asRawClient(runner).unsafe(SET_SCOPE_SQL, [...scopeSettings(scope)]);
+}

package/dist/db/queries/rls-shape.d.ts

@@ -0,0 +1,10 @@
+import { type AnyDb } from "../query.ts";
+import type { RowLevelSecurityPolicy } from "../render-rls-ddl.ts";
+export type RowLevelSecurityShape = {
+    readonly enabled: boolean;
+    readonly forced: boolean;
+    readonly policies: readonly (Pick<RowLevelSecurityPolicy, "name" | "kind" | "command"> & {
+        readonly appliesToPublic: boolean;
+    })[];
+};
+export declare function readRowLevelSecurityShape(db: AnyDb, tableName: string): Promise<RowLevelSecurityShape | undefined>;

package/dist/db/queries/rls-shape.js

@@ -0,0 +1,42 @@
+// Flags plus policy name, kind and command of a table, read from the catalogs without deparsing
+// policy expressions. pg_get_expr (behind the pg_policies view) opens the table with ACCESS SHARE,
+// which queues behind a pending ACCESS EXCLUSIVE; this read never touches the table itself.
+import { asRawClient } from "../query.js";
+const COMMAND_BY_CODE = {
+    "*": "ALL",
+    r: "SELECT",
+    a: "INSERT",
+    w: "UPDATE",
+    d: "DELETE",
+};
+function commandOf(code) {
+    const command = Object.entries(COMMAND_BY_CODE).find(([key]) => key === code)?.[1];
+    // Fail closed: a policy command this check does not know cannot be judged harmless.
+    if (command === undefined)
+        throw new Error(`unknown pg_policy.polcmd code "${code}"`);
+    return command;
+}
+export async function readRowLevelSecurityShape(db, tableName) {
+    const rows = await asRawClient(db).unsafe(`SELECT c.relrowsecurity, c.relforcerowsecurity, p.polname, p.polpermissive, p.polcmd::text AS polcmd, (p.polroles = '{0}'::oid[]) AS polpublic
+     FROM pg_class c
+     JOIN pg_namespace n ON n.oid = c.relnamespace
+     LEFT JOIN pg_policy p ON p.polrelid = c.oid
+     WHERE n.nspname = 'public' AND c.relname = $1`, [tableName]);
+    const first = rows[0];
+    if (first === undefined)
+        return undefined;
+    const policies = rows.flatMap((row) => {
+        if (row.polname === null || row.polcmd === null)
+            return [];
+        const command = commandOf(row.polcmd);
+        return [
+            {
+                name: row.polname,
+                kind: row.polpermissive ? "PERMISSIVE" : "RESTRICTIVE",
+                command,
+                appliesToPublic: row.polpublic === true,
+            },
+        ];
+    });
+    return { enabled: first.relrowsecurity, forced: first.relforcerowsecurity, policies };
+}

package/dist/db/queries/session-advisory-lock.d.ts

@@ -0,0 +1,2 @@
+import type { AnyDb } from "../query.ts";
+export declare function withSessionAdvisoryLock<T>(db: AnyDb, key: number, fn: () => Promise<T>): Promise<T>;

package/dist/db/queries/session-advisory-lock.js

@@ -0,0 +1,23 @@
+import { asRawClient } from "../query.js";
+// Blocks until the lock is free. The lock is session-scoped, so lock, work and
+// unlock share one reserved connection; pool calls may land on different sessions.
+export async function withSessionAdvisoryLock(db, key, fn) {
+    const client = asRawClient(db);
+    if (typeof client.reserve !== "function") {
+        throw new Error("withSessionAdvisoryLock: db has no .reserve() (need a Bun.SQL pool)");
+    }
+    const conn = await client.reserve();
+    try {
+        await conn.unsafe(`SELECT pg_advisory_lock($1)`, [key]);
+        try {
+            return await fn();
+        }
+        finally {
+            // A dropped session already released its lock; failing here would mask fn's outcome.
+            await conn.unsafe(`SELECT pg_advisory_unlock($1)`, [key]).catch(() => undefined);
+        }
+    }
+    finally {
+        await conn.release();
+    }
+}

package/dist/db/queries/shadow-swap.d.ts

@@ -6,7 +6,6 @@ export declare const PROJECTION_REBUILD_SCHEMA = "kumiko_rebuild";
 export declare function ensureRebuildSchema(db: AnyDb): Promise<void>;
 export declare function rebuildMetaOrThrow(table: unknown, projectionName: string): EntityTableMeta;
 export declare function assertLiveColumnsMatchMeta(db: DbConnection | DbTx, meta: EntityTableMeta, projectionName: string): Promise<void>;
-export declare function assertLiveTableHasNoRowLevelSecurity(tx: AnyDb, tableName: string, projectionName?: string): Promise<void>;
 export declare function buildShadowTable(tx: AnyDb, meta: EntityTableMeta): Promise<void>;
 export declare function fenceLiveTable(tx: AnyDb, tableName: string, lockTimeoutMs: number): Promise<void>;
 export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[], derivedRowIds?: Readonly<Record<string, ProjectionRowIdOf>>, derivedRowIdBatchSize?: number): Promise<void>;
@@ -16,4 +15,4 @@ export type ColumnDriftResult = {
     readonly sample: readonly string[];
 };
 export declare function countColumnDrift(tx: AnyDb, tableName: string, meta: EntityTableMeta): Promise<ColumnDriftResult>;
-export declare function swapShadowIntoLive(tx: AnyDb, tableName: string): Promise<void>;
+export declare function swapShadowIntoLive(tx: DbTx, tableName: string): Promise<void>;