@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/observability/escape-hatch-report.d.ts

@@ -12,6 +12,9 @@ export declare function createEscapeHatchReportWindow(opts?: {
 export type EscapeHatchProcessDedup = {
     readonly kinds: ReadonlySet<EscapeHatchKind>;
     readonly lastAuditedAt: Map<string, number>;
+    readonly lastSweep: {
+        atMs: number;
+    };
 };
 export declare function createEscapeHatchProcessDedup(kinds: readonly EscapeHatchKind[]): EscapeHatchProcessDedup;
 export declare function withEscapeHatchAuditScope<T>(run: () => Promise<T>): Promise<T>;

package/dist/observability/escape-hatch-report.js

@@ -40,8 +40,24 @@ const READ_WINDOW_KINDS = new Set([
 // A long-lived worker must leave an audit event inside every retention window
 // (90 days), or its crons vanish from the log once the first event is pruned.
 const PROCESS_REAUDIT_INTERVAL_MS = 24 * 60 * 60 * 1000;
+// Declared escape hatches of system crons are audited once per day and process for each
+// (handler, kind, tenant, target): the declaration, the system actor and the reason are
+// identical on every run, so repeats carry no information. The target is part of the
+// key only where it names a table (one run can write several global tables); a row target
+// would add a key and an audit event per touched foreign row.
+const TABLE_TARGET_KINDS = new Set(["global-write"]);
+// Row-level targets add a key per touched row; without a sweep a long-lived worker keeps them all.
+function sweepExpiredProcessDedup(dedup, nowMs) {
+    if (nowMs - dedup.lastSweep.atMs >= PROCESS_REAUDIT_INTERVAL_MS) {
+        dedup.lastSweep.atMs = nowMs;
+        for (const [key, auditedAt] of dedup.lastAuditedAt) {
+            if (nowMs - auditedAt >= PROCESS_REAUDIT_INTERVAL_MS)
+                dedup.lastAuditedAt.delete(key);
+        }
+    }
+}
 export function createEscapeHatchProcessDedup(kinds) {
-    return { kinds: new Set(kinds), lastAuditedAt: new Map() };
+    return { kinds: new Set(kinds), lastAuditedAt: new Map(), lastSweep: { atMs: 0 } };
 }
 // Default window for createEscapeHatchReporter callers that don't pass their own.
 const fallbackReportWindow = createEscapeHatchReportWindow();
@@ -147,12 +163,13 @@ export function createEscapeHatchReporter(opts) {
             emitEscapeHatchUse(opts.meter, opts.handler, kind);
         const { processDedup } = opts;
         if (processDedup?.kinds.has(kind)) {
+            const keyTarget = TABLE_TARGET_KINDS.has(kind) ? target : undefined;
             const processKey = JSON.stringify([
                 opts.handler,
                 kind,
                 opts.tenantId,
-                target?.id ?? null,
-                target?.tenantId ?? null,
+                keyTarget?.id ?? null,
+                keyTarget?.tenantId ?? null,
             ]);
             const nowMs = now();
             const lastAuditedAt = processDedup.lastAuditedAt.get(processKey);
@@ -160,6 +177,7 @@ export function createEscapeHatchReporter(opts) {
             if (lastAuditedAt !== undefined && nowMs - lastAuditedAt < PROCESS_REAUDIT_INTERVAL_MS) {
                 return;
             }
+            sweepExpiredProcessDedup(processDedup, nowMs);
             processDedup.lastAuditedAt.set(processKey, nowMs);
             reportEscapeHatchUse(eventFor(kind, reason, target), deps);
             // skip: audited above, the window dedup below only serves the other kinds

package/dist/pipeline/after-rollback-sink.d.ts

@@ -0,0 +1,6 @@
+import type { createFallbackLogger } from "../logging/utils.ts";
+import type { AfterCommitHook } from "./dispatcher-utils.ts";
+export type AfterRollbackHook = () => Promise<void>;
+export declare function afterRollbackHooksOf(commitSink: AfterCommitHook[]): AfterRollbackHook[];
+export declare function carrySavepointRollbackHooks(innerCommitSink: AfterCommitHook[], outerCommitSink: AfterCommitHook[], savepointRolledBack: boolean): void;
+export declare function flushAfterRollback(commitSink: AfterCommitHook[], logError: Pick<ReturnType<typeof createFallbackLogger>, "error">): Promise<void>;

package/dist/pipeline/after-rollback-sink.js

@@ -0,0 +1,32 @@
+// Side channel keyed by the afterCommit sink array, so executeWrite and friends keep their signatures.
+// Invariant: every registration runs at most once, and only if the work it compensates was discarded.
+const rollbackSinks = new WeakMap();
+export function afterRollbackHooksOf(commitSink) {
+    const existing = rollbackSinks.get(commitSink);
+    if (existing)
+        return existing;
+    const created = [];
+    rollbackSinks.set(commitSink, created);
+    return created;
+}
+// A rolled-back savepoint is not compensated immediately: the compensation could wait on locks of
+// the still-open outer transaction. It runs once after that transaction ends, via the commit sink
+// on commit or the rollback sink on rollback.
+export function carrySavepointRollbackHooks(innerCommitSink, outerCommitSink, savepointRolledBack) {
+    const innerHooks = rollbackSinks.get(innerCommitSink) ?? [];
+    if (innerHooks.length > 0) {
+        if (savepointRolledBack)
+            outerCommitSink.push(...innerHooks);
+        afterRollbackHooksOf(outerCommitSink).push(...innerHooks);
+    }
+}
+export async function flushAfterRollback(commitSink, logError) {
+    const hooks = rollbackSinks.get(commitSink) ?? [];
+    const outcomes = await Promise.allSettled(hooks.map((hook) => hook()));
+    for (const outcome of outcomes) {
+        if (outcome.status === "rejected") {
+            const detail = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+            logError.error("afterRollback hook failed", { error: detail });
+        }
+    }
+}

package/dist/pipeline/cascade-handler.js

@@ -22,151 +22,178 @@ export function createCascadeDeleteHook(registry, tables) {
                 return;
             }
             const writeDb = isBoundTenantDb(db) ? db : undefined;
-            const cascadeUser = createSystemUser(writeDb?.tenantId ?? payload.event.tenantId);
-            const executors = new Map();
-            const executorFor = (name, entity) => {
-                const cached = executors.get(name);
-                if (cached)
-                    return cached;
-                const table = tables.get(name);
-                if (!table) {
-                    throw new InternalError({ message: `cascadeDelete: no table registered for "${name}"` });
-                }
-                const created = createEventStoreExecutor(table, entity, { entityName: name });
-                executors.set(name, created);
-                return created;
-            };
-            const requireWriteDb = () => {
-                if (!writeDb) {
-                    throw new InternalError({
-                        message: "cascadeDelete: a TenantDb is required to write children",
-                    });
-                }
-                return writeDb;
-            };
-            const unwrap = (result) => {
-                if (!result.isSuccess)
-                    throw reraiseAsKumikoError(result.error);
-            };
-            const childIds = async (targetTable, where, entity) => {
-                // A soft-deleted child is already invisible; deleting it again would fail.
-                const rows = await selectMany(db, targetTable, {
-                    ...where,
-                    ...(entity?.softDelete === true && { isDeleted: false }),
-                });
-                return rows.map((row) => row.id);
+            const run = {
+                registry,
+                db,
+                entityName,
+                parentId: payload.id,
+                lockGuardBypassed: payload.lockGuardBypassed === true,
+                cascadeUser: createSystemUser(writeDb?.tenantId ?? payload.event.tenantId),
+                executorFor: createExecutorCache(tables),
+                writeDb,
             };
             // Cascade applies to outgoing hasMany / manyToMany relations only —
             // the parent side of the link is where `onDelete` lives (see
             // relations.ts). Incoming belongsTo edges are covered because their
             // counterpart hasMany declares the strategy.
-            const outgoing = registry.getRelations(entityName);
             // Outgoing: e.g. department.users (hasMany target: user) — users have FK to department
-            for (const [, relation] of Object.entries(outgoing)) {
-                // Only hasMany / manyToMany carry cascade semantics. belongsTo points
-                // at a parent; the parent's onDelete decides what happens to this node.
-                if (relation.type !== "hasMany" && relation.type !== "manyToMany")
-                    continue;
-                const strategy = relation.onDelete ?? OnDeleteStrategies.nothing;
-                if (strategy === OnDeleteStrategies.nothing)
-                    continue;
-                if (relation.type === "hasMany" && relation.foreignKey) {
-                    const targetTable = tables.get(relation.target);
-                    if (!targetTable)
-                        continue;
-                    const childEntity = registry.getEntity(relation.target);
-                    if (!childEntity &&
-                        (strategy === OnDeleteStrategies.cascade || strategy === OnDeleteStrategies.setNull)) {
-                        throw new InternalError({
-                            message: `cascadeDelete: child "${relation.target}" is not an entity; changing its rows needs an executor`,
-                        });
-                    }
-                    if (strategy === OnDeleteStrategies.restrict) {
-                        const row = await fetchOne(db, targetTable, { [relation.foreignKey]: payload.id });
-                        if (row) {
-                            throw new ConflictError({
-                                message: `${relation.target} has records referencing ${entityName}#${payload.id}`,
-                                i18nKey: "errors.deleteRestricted",
-                                details: {
-                                    reason: FrameworkReasons.deleteRestricted,
-                                    blockingEntity: relation.target,
-                                    entity: entityName,
-                                    entityId: payload.id,
-                                },
-                            });
-                        }
-                    }
-                    // The child writes below skip the executor's lock guard (decided here once), so a locked
-                    // child must block the parent delete instead of changing with it. The error names
-                    // the parent only: the caller may delete the parent without reading the child.
-                    if (strategy === OnDeleteStrategies.cascade || strategy === OnDeleteStrategies.setNull) {
-                        const childLock = childEntity?.lockedWhen;
-                        if (childLock !== undefined && payload.lockGuardBypassed !== true) {
-                            // A soft-deleted child is invisible to the caller and must not block.
-                            const children = await selectMany(db, targetTable, {
-                                [relation.foreignKey]: payload.id,
-                                ...(childEntity?.softDelete === true && { isDeleted: false }),
-                            });
-                            if (children.some((child) => isRecordLocked(childLock, child))) {
-                                throw new RecordLockedError({ entityName, entityId: payload.id });
-                            }
-                        }
-                    }
-                    if (strategy === OnDeleteStrategies.cascade && childEntity) {
-                        const executor = executorFor(relation.target, childEntity);
-                        for (const id of await childIds(targetTable, { [relation.foreignKey]: payload.id }, childEntity)) {
-                            unwrap(await executor.delete({ id }, cascadeUser, requireWriteDb(), CASCADE_CHILD_WRITE_OPTIONS));
-                        }
-                    }
-                    if (strategy === OnDeleteStrategies.setNull && childEntity) {
-                        const executor = executorFor(relation.target, childEntity);
-                        const rows = await selectMany(db, targetTable, {
-                            [relation.foreignKey]: payload.id,
-                        });
-                        for (const row of rows) {
-                            unwrap(await executor.update({ id: row.id, changes: { [relation.foreignKey]: null } }, cascadeUser, requireWriteDb(), {
-                                ...CASCADE_CHILD_WRITE_OPTIONS,
-                                skipOptimisticLock: true,
-                                includeDeleted: true,
-                            }));
-                        }
-                    }
-                }
-                if (relation.type === "manyToMany" && relation.through) {
-                    const throughTable = tables.get(relation.through.table);
-                    if (!throughTable)
-                        continue;
-                    // sourceKey points at the owner side (the entity being deleted).
-                    const sourceKey = relation.through.sourceKey;
-                    if (strategy === OnDeleteStrategies.restrict) {
-                        const row = await fetchOne(db, throughTable, { [sourceKey]: payload.id });
-                        if (row) {
-                            throw new ConflictError({
-                                message: `${relation.through.table} has records referencing ${entityName}#${payload.id}`,
-                                i18nKey: "errors.deleteRestricted",
-                                details: {
-                                    reason: FrameworkReasons.deleteRestricted,
-                                    blockingEntity: relation.through.table,
-                                    entity: entityName,
-                                    entityId: payload.id,
-                                },
-                            });
-                        }
-                    }
-                    if (strategy === OnDeleteStrategies.cascade) {
-                        const throughEntity = registry.getEntity(relation.through.table);
-                        if (!throughEntity) {
-                            throw new InternalError({
-                                message: `cascadeDelete: through table "${relation.through.table}" is not an entity; deleting its rows needs an executor`,
-                            });
-                        }
-                        const executor = executorFor(relation.through.table, throughEntity);
-                        for (const id of await childIds(throughTable, { [sourceKey]: payload.id }, throughEntity)) {
-                            unwrap(await executor.delete({ id }, cascadeUser, requireWriteDb(), CASCADE_CHILD_WRITE_OPTIONS));
-                        }
-                    }
-                }
+            for (const relation of Object.values(registry.getRelations(entityName))) {
+                await applyOnDelete(run, tables, relation);
             }
         },
     };
 }
+function createExecutorCache(tables) {
+    const executors = new Map();
+    return (name, entity) => {
+        const cached = executors.get(name);
+        if (cached)
+            return cached;
+        const table = tables.get(name);
+        if (!table) {
+            throw new InternalError({ message: `cascadeDelete: no table registered for "${name}"` });
+        }
+        const created = createEventStoreExecutor(table, entity, { entityName: name });
+        executors.set(name, created);
+        return created;
+    };
+}
+function requireCascadeWriteDb(writeDb) {
+    if (!writeDb) {
+        throw new InternalError({
+            message: "cascadeDelete: a TenantDb is required to write children",
+        });
+    }
+    return writeDb;
+}
+function unwrap(result) {
+    if (!result.isSuccess)
+        throw reraiseAsKumikoError(result.error);
+}
+async function childIds(run, targetTable, where, entity) {
+    // A soft-deleted child is already invisible; deleting it again would fail.
+    const rows = await selectMany(run.db, targetTable, { ...where, ...(entity.softDelete === true && { isDeleted: false }) }, { fields: ["id"] });
+    return rows.map((row) => row.id);
+}
+// Only hasMany / manyToMany carry cascade semantics. belongsTo points
+// at a parent; the parent's onDelete decides what happens to this node.
+async function applyOnDelete(run, tables, relation) {
+    if (relation.type === "hasMany" && relation.foreignKey) {
+        const table = tables.get(relation.target);
+        if (table) {
+            const link = { target: relation.target, foreignKey: relation.foreignKey, table };
+            await HAS_MANY_ON_DELETE[onDeleteStrategyOf(relation)](run, link);
+        }
+    }
+    if (relation.type === "manyToMany" && relation.through) {
+        const table = tables.get(relation.through.table);
+        if (table) {
+            // sourceKey points at the owner side (the entity being deleted).
+            const link = {
+                throughTable: relation.through.table,
+                sourceKey: relation.through.sourceKey,
+                table,
+            };
+            await THROUGH_ON_DELETE[onDeleteStrategyOf(relation)](run, link);
+        }
+    }
+}
+function onDeleteStrategyOf(relation) {
+    return relation.onDelete ?? OnDeleteStrategies.nothing;
+}
+async function leaveChildrenUnchanged() { }
+const HAS_MANY_ON_DELETE = {
+    nothing: leaveChildrenUnchanged,
+    restrict: rejectReferencedParent,
+    cascade: deleteHasManyChildren,
+    setNull: detachHasManyChildren,
+};
+// A link row has no nullable side: setNull on a manyToMany leaves the through rows in place.
+const THROUGH_ON_DELETE = {
+    nothing: leaveChildrenUnchanged,
+    restrict: rejectReferencedThroughRows,
+    cascade: deleteThroughRows,
+    setNull: leaveChildrenUnchanged,
+};
+async function rejectReferencedParent(run, link) {
+    const row = await fetchOne(run.db, link.table, { [link.foreignKey]: run.parentId });
+    if (row)
+        throw deleteRestrictedError(run, link.target);
+}
+async function rejectReferencedThroughRows(run, link) {
+    const row = await fetchOne(run.db, link.table, { [link.sourceKey]: run.parentId });
+    if (row)
+        throw deleteRestrictedError(run, link.throughTable);
+}
+function deleteRestrictedError(run, blockingEntity) {
+    return new ConflictError({
+        message: `${blockingEntity} has records referencing ${run.entityName}#${run.parentId}`,
+        i18nKey: "errors.deleteRestricted",
+        details: {
+            reason: FrameworkReasons.deleteRestricted,
+            blockingEntity,
+            entity: run.entityName,
+            entityId: run.parentId,
+        },
+    });
+}
+// ponytail: one executor call per child inside the parent's transaction, batch when child counts need it
+async function deleteHasManyChildren(run, link) {
+    const childEntity = requireChildEntity(run, link);
+    await rejectLockedChildren(run, link, childEntity);
+    const executor = run.executorFor(link.target, childEntity);
+    for (const id of await childIds(run, link.table, { [link.foreignKey]: run.parentId }, childEntity)) {
+        unwrap(await executor.delete({ id }, run.cascadeUser, requireCascadeWriteDb(run.writeDb), CASCADE_CHILD_WRITE_OPTIONS));
+    }
+}
+async function detachHasManyChildren(run, link) {
+    const childEntity = requireChildEntity(run, link);
+    await rejectLockedChildren(run, link, childEntity);
+    const executor = run.executorFor(link.target, childEntity);
+    const rows = await selectMany(run.db, link.table, { [link.foreignKey]: run.parentId }, { fields: ["id"] });
+    for (const row of rows) {
+        unwrap(await executor.update({ id: row.id, changes: { [link.foreignKey]: null } }, run.cascadeUser, requireCascadeWriteDb(run.writeDb), {
+            ...CASCADE_CHILD_WRITE_OPTIONS,
+            skipOptimisticLock: true,
+            includeDeleted: true,
+        }));
+    }
+}
+function requireChildEntity(run, link) {
+    const childEntity = run.registry.getEntity(link.target);
+    if (!childEntity) {
+        throw new InternalError({
+            message: `cascadeDelete: child "${link.target}" is not an entity; changing its rows needs an executor`,
+        });
+    }
+    return childEntity;
+}
+// The child writes skip the executor's lock guard (decided here once), so a locked
+// child must block the parent delete instead of changing with it. The error names
+// the parent only: the caller may delete the parent without reading the child.
+async function rejectLockedChildren(run, link, childEntity) {
+    const childLock = childEntity.lockedWhen;
+    // skip: an unlockable child or an already bypassed parent delete has nothing to block
+    if (childLock === undefined || run.lockGuardBypassed)
+        return;
+    // A soft-deleted child is invisible to the caller and must not block.
+    const children = await selectMany(run.db, link.table, {
+        [link.foreignKey]: run.parentId,
+        ...(childEntity.softDelete === true && { isDeleted: false }),
+    });
+    if (children.some((child) => isRecordLocked(childLock, child))) {
+        throw new RecordLockedError({ entityName: run.entityName, entityId: run.parentId });
+    }
+}
+async function deleteThroughRows(run, link) {
+    const throughEntity = run.registry.getEntity(link.throughTable);
+    if (!throughEntity) {
+        throw new InternalError({
+            message: `cascadeDelete: through table "${link.throughTable}" is not an entity; deleting its rows needs an executor`,
+        });
+    }
+    const executor = run.executorFor(link.throughTable, throughEntity);
+    for (const id of await childIds(run, link.table, { [link.sourceKey]: run.parentId }, throughEntity)) {
+        unwrap(await executor.delete({ id }, run.cascadeUser, requireCascadeWriteDb(run.writeDb), CASCADE_CHILD_WRITE_OPTIONS));
+    }
+}

package/dist/pipeline/dispatch-batch.js

@@ -3,6 +3,7 @@ import { transaction } from "../db/query.js";
 import { InternalError, toWriteErrorInfo, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
+import { flushAfterRollback } from "./after-rollback-sink.js";
 import { resolveAppPoolDb } from "./dispatch-shared.js";
 import { executeNestedWrite, executeWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
@@ -36,6 +37,9 @@ async function runReservedCommand(scope, cmd, index, tx) {
     rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
     return res;
 }
+function rollbackLogger(scope) {
+    return createFallbackLogger("dispatcher", scope.ctx.appContext.log);
+}
 // Sequential fallback without an outer transaction. A failure result and a throw both end the
 // batch, so both give the reserved capacity back.
 async function runCommandsWithoutTransaction(scope, commands, results) {
@@ -50,12 +54,14 @@ async function runCommandsWithoutTransaction(scope, commands, results) {
                 // No tx means no rollback — but we still drop afterCommit hooks,
                 // matching the semantic "failure = side-effects don't fire".
                 await scope.reservations.releaseAll();
+                await flushAfterRollback(scope.afterCommitHooks, rollbackLogger(scope));
                 return { index: i, error: res.error };
             }
         }
     }
     catch (e) {
         await scope.reservations.releaseAll();
+        await flushAfterRollback(scope.afterCommitHooks, rollbackLogger(scope));
         throw e;
     }
     return undefined;
@@ -208,7 +214,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
         }, reservations.error.httpStatus >= 500);
     }
     // batch() opens its own outer transaction — needs the top-level
-    // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
+    // connection's `.begin()` (a transaction handle cannot begin another one).
     const db = resolveAppPoolDb(ctx);
     if (!db || runsWithoutTransaction) {
         // Without a DB connection (or for a perCommand handler, whose writes open their own transactions)
@@ -250,6 +256,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
         // Rollback or failed COMMIT: the transaction is over, so the reserved capacity goes back.
         // The release is outcome-safe: it only gives back a reservation row the handler tx did not delete.
         await reservations.releaseAll();
+        await flushAfterRollback(afterCommitHooks, createFallbackLogger("dispatcher", context.log));
         if (e instanceof BatchRollback) {
             // Thrown inside the callback, so the tx rolled back. A 4xx is
             // deterministic and stays cached; a 5xx may be transient.

package/dist/pipeline/dispatch-query.js

@@ -1,3 +1,4 @@
+import { isListAggregateResult } from "@cosmicdrift/kumiko-types/list-aggregate-types";
 import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
@@ -58,7 +59,11 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx, outerNoti
 }
 async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user, origin, tx, outerNotifySink) {
     const { registry } = ctx;
-    const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, undefined, includeDeleted, undefined, outerNotifySink);
+    const handlerContext = await buildHandlerContext(ctx, type, user, origin, {
+        tx,
+        includeDeleted,
+        outerNotifySink,
+    });
     let result = await handler.handler({ type, payload, user }, handlerContext);
     // postQuery hooks run BEFORE field-access filtering so they see raw data and can
     // merge custom fields, computed counts, tags, and similar values. Each hook is
@@ -78,7 +83,9 @@ async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user
     const handlerHooks = registry.getPostQueryHooks(type);
     const entityHooks = entityName ? registry.getEntityPostQueryHooks(entityName) : [];
     const postQueryHooks = [...handlerHooks, ...entityHooks];
-    if (postQueryHooks.length > 0 && result && typeof result === "object") {
+    // Aggregate groups are not rows: their values are already read-gated and the hooks are row-shaped.
+    const isAggregate = isListAggregateResult(result);
+    if (!isAggregate && postQueryHooks.length > 0 && result && typeof result === "object") {
         if (Array.isArray(result)) {
             let rows = result; // @cast-boundary engine-payload
             for (const hook of postQueryHooks) {
@@ -115,7 +122,7 @@ async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user
     }
     // Field-level read filter — only applies to entity-bound results.
     const entity = entityName ? registry.getEntity(entityName) : undefined;
-    if (entity && result && typeof result === "object") {
+    if (entity && !isAggregate && result && typeof result === "object") {
         if (Array.isArray(result)) {
             result = result.map((row) => filterReadFields(entity, row, user));
         }

package/dist/pipeline/dispatch-shared.d.ts

@@ -2,12 +2,13 @@ import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import type { SseBroker } from "../api/sse-broker.ts";
 import type { DbConnection, DbTx } from "../db/connection.ts";
 import type { buildEntityTable } from "../db/table-builder.ts";
+import { type TenantDb } from "../db/tenant-db.ts";
 import type { defineTransitions } from "../engine/state-machine.ts";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension.ts";
 import type { TenantId } from "../engine/types/identifiers.ts";
 import type { AppContext, HandlerContext, JobRunnerRef, PayloadRateLimitOption, RateLimitDeclaration, Registry, SessionUser, WriteResult } from "../engine/types/index.ts";
 import { InternalError, type WriteErrorInfo } from "../errors/index.ts";
-import { type EscapeHatchReportWindow, type getFallbackMeter, getFallbackTracer } from "../observability/index.ts";
+import { type EscapeHatchReportWindow, type getFallbackMeter, type getFallbackTracer } from "../observability/index.ts";
 import { type AfterCommitHook } from "./dispatcher-utils.ts";
 import type { IdempotencyGuard } from "./idempotency.ts";
 import type { LifecycleHooks } from "./lifecycle-pipeline.ts";
@@ -53,18 +54,27 @@ export type DispatchContext = {
 export declare const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10000;
 export declare function resolveDbSource(ctx: DispatchContext, tx: DbTx | undefined): DbConnection | DbTx | undefined;
 export declare function resolveAppPoolDb(ctx: DispatchContext): DbConnection | undefined;
+export declare function createSystemScopedDbGuard(handlerType: string, fieldName: "db" | "dbOutsideTransaction", hint: string): TenantDb;
 export declare function isMemberResolutionPrincipal(user: SessionUser): boolean;
 export declare function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext;
 export declare function perCommandNestedDenied(targetType: string): InternalError;
 export declare function denyTransactionBoundSurfaces(handlerContext: HandlerContext): HandlerContext;
 export declare function applyBeforeTransactionReadOnly(handlerContext: HandlerContext): HandlerContext;
 export type HandlerTransactionScope = "inTransaction" | "withoutTransaction" | "postCommit";
-export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, tx?: DbTx, afterCommitHooks?: AfterCommitHook[], includeDeleted?: boolean, transactionScope?: HandlerTransactionScope, outerNotifySink?: AfterCommitHook[], readOnlyForTenant?: boolean): Promise<HandlerContext>;
+export type BuildHandlerContextOptions = {
+    tx?: DbTx;
+    afterCommitHooks?: AfterCommitHook[];
+    includeDeleted?: boolean;
+    transactionScope?: HandlerTransactionScope;
+    outerNotifySink?: AfterCommitHook[];
+    readOnlyForTenant?: boolean;
+};
+export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, options?: BuildHandlerContextOptions): Promise<HandlerContext>;
 export declare function createHandlerBoundDigest(digest: (value: string) => string, handlerName: string): (value: string) => string;
 export declare function runHandlerInstrumented<T>(ctx: DispatchContext, type: string, operation: "query" | "write" | "stream", user: SessionUser, inner: () => Promise<T>): Promise<T>;
 export declare function runStreamInstrumented<T>(ctx: DispatchContext, type: string, user: SessionUser, inner: () => AsyncGenerator<T>): AsyncGenerator<T>;
 export declare function checkFeatureEnabled(ctx: DispatchContext, qualifiedHandler: string, tenantId: TenantId): Promise<import("../errors/index.ts").FeatureDisabledError | undefined>;
 export declare function ensureFeatureEnabled(ctx: DispatchContext, qualifiedHandler: string, tenantId: TenantId): Promise<void>;
-export declare function enforceRateLimit(ctx: DispatchContext, rateLimit: RateLimitDeclaration | undefined, handlerName: string, user: SessionUser, isSystemScope: boolean): Promise<void>;
+export declare function enforceRateLimit(ctx: DispatchContext, rateLimit: RateLimitDeclaration | undefined, handlerName: string, user: SessionUser, isSystemScope: boolean, costOverride?: number): Promise<void>;
 export declare function enforcePayloadRateLimits(ctx: DispatchContext, limits: readonly PayloadRateLimitOption[] | undefined, handlerName: string, user: SessionUser, data: unknown): Promise<void>;
 export declare function resolveAuthClaimsFn(ctx: DispatchContext, user: SessionUser): Promise<Record<string, unknown>>;