@cosmicdrift/kumiko-framework 0.389.0 → 0.390.0

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

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

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

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

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

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

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

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

package/dist/db/tenant-db.js

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

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

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

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

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

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

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

package/dist/db/transaction-serialization.js

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

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

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

package/dist/derivatives/index.d.ts

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

package/dist/derivatives/index.js

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

package/dist/engine/access.d.ts

@@ -1,2 +1,3 @@
-import type { AccessRule, SessionUser } from "./types/index.ts";
+import type { AccessRule } from "@cosmicdrift/kumiko-types/handlers";
+import type { SessionUser } from "./types/index.ts";
 export declare function hasAccess(user: Pick<SessionUser, "roles">, access: AccessRule | undefined): boolean;

package/dist/engine/access.js

@@ -1,5 +1,5 @@
+import { isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";
 import { ANONYMOUS_ROLE } from "./system-user.js";
-import { isOpenToAllGranted } from "./types/index.js";
 // Default-deny: a handler without an explicit AccessRule is unreachable. To
 // grant access a handler must either list allowed roles or opt into
 // openToAll. Leaving access undefined now returns false (previously true) —

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -1,4 +1,5 @@
-import type { FeatureDefinition, QueryHandlerDef } from "../types/index.ts";
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare const FILE_FIELD_TYPES: Set<string>;
 export declare const PII_DIRECT_NAME_HINTS: ReadonlySet<string>;
 export declare const PII_USER_OWNED_NAME_HINTS: ReadonlySet<string>;

package/dist/engine/boot-validator/entity-handler.js

@@ -209,7 +209,7 @@ export function validatePerCommandTransaction(featureName, handlerName, handler)
     const conflicting = perCommandConflict(handler);
     if (conflicting !== undefined) {
         throw new Error(`write handler "${featureName}:write:${handlerName}" declares transaction: "perCommand" together with ${conflicting} — ` +
-            "a perCommand handler holds no transaction, so move the phase into the commands it issues via ctx.write.");
+            "a perCommand handler holds no transaction, so move the phase into the commands it issues via ctx.dispatch.write.");
     }
 }
 const IP_SCOPED_RATE_LIMIT_PER = ["ip", "ip+handler"];

package/dist/engine/boot-validator/entity-list-aggregate-options.d.ts

@@ -1,3 +1,3 @@
-import type { EntityDefinition } from "../types/index.ts";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import type { EntityListScreenDefinition } from "../types/screen.ts";
 export declare function validateEntityListAggregateOptions(where: string, screen: EntityListScreenDefinition, entity: EntityDefinition): void;

package/dist/engine/boot-validator/list-table-aggregate-options.d.ts

@@ -1,4 +1,4 @@
-import type { EntityDefinition, FieldDefinition } from "../types/index.ts";
+import type { EntityDefinition, FieldDefinition } from "@cosmicdrift/kumiko-types/fields";
 import { type ListColumnSpec, type ListTableGrouping, type ListTableTotal } from "../types/screen.ts";
 type FieldType = FieldDefinition["type"];
 export type AggregateFieldInfo = {

package/dist/engine/boot-validator/list-table-aggregate-query.d.ts

@@ -1,4 +1,5 @@
-import type { FeatureDefinition, QueryHandlerDef } from "../types/index.ts";
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
+import type { FeatureDefinition } from "../types/index.ts";
 import type { ListColumnSpec, ListTableOptions } from "../types/screen.ts";
 export declare function validateListTableAggregateQuery(args: {
     readonly prefix: string;

package/dist/engine/boot-validator/nav.d.ts

@@ -1,4 +1,6 @@
-import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types/index.ts";
+import type { NavDefinition } from "@cosmicdrift/kumiko-types/nav";
+import type { WorkspaceDefinition } from "@cosmicdrift/kumiko-types/workspace";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string>;
 export declare function collectNavQns(features: readonly FeatureDefinition[]): Map<string, NavDefinition & {
     readonly featureName: string;