@cosmicdrift/kumiko-framework 0.377.0 → 0.379.0

package/dist/files/create-file-ref.js

@@ -3,6 +3,7 @@ import { runInOwnTransaction } from "../db/tenant-db.js";
 import { isFileField, } from "../engine/types/index.js";
 import { InternalError } from "../errors/index.js";
 import { generateId } from "../utils/index.js";
+import { isActionFormScreenQn, resolveActionFormFileField } from "./action-form-upload.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
 import { resolveContentType } from "./resolve-content-type.js";
@@ -23,6 +24,7 @@ export function getFileRefExecutor() {
     fileRefExecutor ??= buildFileRefExecutor();
     return fileRefExecutor;
 }
+const ACTION_FORM_STORAGE_SEGMENT = "action-form";
 const SAFE_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
 // entityType/fieldName drive the GDPR-forget decision downstream
 // (fileRefDeleteHook resolves the field's PII annotation from exactly this
@@ -39,6 +41,33 @@ export function resolveAttachedField(registry, entityType, fieldName) {
         return { kind: "unresolvable" };
     return { kind: "resolved", fieldDef };
 }
+function resolveUploadField(registry, input) {
+    const { entityType, entityId, fieldName, actionForm } = input;
+    if (actionForm === undefined)
+        return resolveAttachedField(registry, entityType, fieldName);
+    if (entityType !== undefined || entityId !== undefined) {
+        return {
+            kind: "rejected",
+            error: "invalid_action_form: actionForm cannot be combined with entityType/entityId",
+        };
+    }
+    if (!isActionFormScreenQn(actionForm)) {
+        return {
+            kind: "rejected",
+            error: "invalid_action_form: expected a screen QN like <feature>:screen:<id>",
+        };
+    }
+    const fieldDef = fieldName !== undefined
+        ? resolveActionFormFileField(registry, actionForm, fieldName)
+        : undefined;
+    if (fieldDef === undefined) {
+        return {
+            kind: "rejected",
+            error: "unresolvable_field: actionForm and fieldName must name a files/image field of a registered actionForm screen",
+        };
+    }
+    return { kind: "resolved", fieldDef };
+}
 function acceptFile(deps, input) {
     const { fileName, declaredMimeType, data, entityType, entityId, fieldName } = input;
     const rejected = (error) => ({ kind: "rejected", error });
@@ -54,18 +83,15 @@ function acceptFile(deps, input) {
             return rejected(`invalid_${field}: must match /^[A-Za-z0-9_-]+$/`);
         }
     }
-    let maxSize = deps.defaultMaxUploadSize;
-    let accept;
-    const attachedField = resolveAttachedField(deps.registry, entityType, fieldName);
-    if (attachedField.kind === "unresolvable") {
+    const field = resolveUploadField(deps.registry, input);
+    if (field.kind === "rejected")
+        return field;
+    if (field.kind === "unresolvable") {
         return rejected("unresolvable_field: entityType/fieldName must resolve to a registered file field, or both must be omitted for an unattached upload");
     }
-    if (attachedField.kind === "resolved") {
-        if (attachedField.fieldDef.maxSize)
-            maxSize = attachedField.fieldDef.maxSize;
-        if (attachedField.fieldDef.accept)
-            accept = attachedField.fieldDef.accept;
-    }
+    const fieldDef = field.kind === "resolved" ? field.fieldDef : undefined;
+    const maxSize = fieldDef?.maxSize || deps.defaultMaxUploadSize;
+    const accept = fieldDef?.accept;
     const validationError = validateFile({ fileName, mimeType: declaredMimeType, size: data.byteLength }, { maxSize, accept });
     if (validationError)
         return rejected(validationError);
@@ -98,12 +124,14 @@ function acceptFile(deps, input) {
 // Upload step: validates and writes the binary. Outside any transaction on purpose — network/disk
 // I/O doesn't belong inside a PG connection's tx window.
 export async function writeAcceptedFileBytes(deps, input) {
-    const { fileName, data, entityType, entityId, fieldName } = input;
+    const { fileName, data, entityType, entityId, fieldName, actionForm } = input;
     const accepted = acceptFile(deps, input);
     if (accepted.kind === "rejected")
         return accepted;
     const { mimeType, extension } = accepted;
-    const storageKey = buildStorageKey(deps.user.tenantId, entityType ?? "unattached", entityId, fieldName ?? "file", fileName, generateId(), extension);
+    const storageKey = buildStorageKey(deps.user.tenantId, 
+    // The screen QN stays out of the key: a fixed segment keeps it a plain path part.
+    actionForm !== undefined ? ACTION_FORM_STORAGE_SEGMENT : (entityType ?? "unattached"), entityId, fieldName ?? "file", fileName, generateId(), extension);
     await deps.writeBytes(storageKey, data, mimeType);
     return {
         kind: "uploaded",
@@ -112,7 +140,7 @@ export async function writeAcceptedFileBytes(deps, input) {
             fileName,
             mimeType,
             size: data.byteLength,
-            entityType,
+            entityType: actionForm ?? entityType,
             entityId,
             fieldName,
         },

package/dist/files/file-routes.js

@@ -6,8 +6,9 @@ import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues
 import { selectMany } from "../db/query.js";
 import { createProjectingTenantDb } from "../db/tenant-db.js";
 import { createDerivativesContext, resolveFieldVariant, resolveRenderer, } from "../derivatives/index.js";
-import { SYSTEM_USER_ID } from "../engine/system-user.js";
+import { isAnonymousSessionUser, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { isFileField, isUuid, } from "../engine/types/index.js";
+import { listActionFormFileFields, mayUseActionForm } from "./action-form-upload.js";
 import { buildContentDispositionHeader } from "./content-disposition.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
 import { createFileContext } from "./file-handle.js";
@@ -70,6 +71,10 @@ export function resolveMaxUploadBodyBytes(options) {
             }
         }
     }
+    for (const { fieldDef } of listActionFormFileFields(options.registry)) {
+        if (fieldDef.maxSize)
+            maxBytes = Math.max(maxBytes, parseMaxSize(fieldDef.maxSize));
+    }
     return maxBytes + MULTIPART_OVERHEAD_MARGIN_BYTES;
 }
 // Upload-route policy carried by createFilesFeature(opts?) — read from the
@@ -148,6 +153,20 @@ export function createFileRoutes(options) {
         // store it in the text entityId column.
         const entityId = typeof body["entityId"] === "string" ? body["entityId"] : undefined;
         const fieldName = typeof body["fieldName"] === "string" ? body["fieldName"] : undefined;
+        const actionForm = typeof body["actionForm"] === "string" ? body["actionForm"] : undefined;
+        // Ahead of the record check below, which would answer 404/403 for the entity half.
+        if (actionForm !== undefined && (entityType !== undefined || entityId !== undefined)) {
+            return c.json({ error: "invalid_action_form: actionForm cannot be combined with entityType or entityId" }, 400);
+        }
+        // Before any bytes are written, like the record check below. An unresolvable screen falls
+        // through to storeFileAsFileRef, which answers 400; a known one must be submittable by the
+        // caller. Anonymous callers cannot bind pending uploads, so they get no upload either.
+        if (actionForm !== undefined &&
+            options.registry !== undefined &&
+            options.registry.getScreen(actionForm)?.type === "actionForm" &&
+            (isAnonymousSessionUser(user) || !mayUseActionForm(options.registry, actionForm, user))) {
+            return c.json({ error: "forbidden: no access to this form" }, 403);
+        }
         if (entityId !== undefined) {
             if (entityType === undefined) {
                 return c.json({ error: "missing_entity_type: entityId requires entityType" }, 400);
@@ -184,7 +203,15 @@ export function createFileRoutes(options) {
                 await storageProvider.write(key, bytes, mimeType);
             },
             deleteBytes: (key) => storageProvider.delete(key),
-        }, { fileName: file.name, declaredMimeType: file.type, data, entityType, entityId, fieldName });
+        }, {
+            fileName: file.name,
+            declaredMimeType: file.type,
+            data,
+            entityType,
+            entityId,
+            fieldName,
+            actionForm,
+        });
         if (outcome.kind === "rejected")
             return c.json({ error: outcome.error }, 400);
         if (outcome.kind === "failed")

package/dist/files/index.d.ts

@@ -1,4 +1,5 @@
-export type { BindPendingFileRefOutcome, PendingFileRef } from "./bind-pending-file-refs.ts";
+export { listActionFormFileFields, resolveActionFormFileField } from "./action-form-upload.ts";
+export type { BindPendingFileRefOutcome, PendingFileRef, PendingFileRefBindTarget, } from "./bind-pending-file-refs.ts";
 export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.ts";
 export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, UploadedFileBytes, UploadFileBytesContext, } from "./create-file-ref-from-bytes.ts";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.ts";

package/dist/files/index.js

@@ -1,3 +1,4 @@
+export { listActionFormFileFields, resolveActionFormFileField } from "./action-form-upload.js";
 export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.js";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature, FILES_FEATURE } from "./feature.js";

package/dist/files/purge-expired-file-ref-bytes.d.ts

@@ -1,10 +1,10 @@
 import type { FileContext } from "@cosmicdrift/kumiko-types/file-handle-types";
 import type { Logger } from "@cosmicdrift/kumiko-types/logger";
-import { deleteMany, type WhereObject } from "../db/query.ts";
+import { selectMany, type WhereObject } from "../db/query.ts";
 import type { TenantDb } from "../db/tenant-db.ts";
 export declare const EXPIRED_FILE_REF_PURGE_BATCH = 500;
 type PurgeLog = Pick<Logger, "warn"> | undefined;
-type PurgeTable = Parameters<typeof deleteMany>[1];
+type PurgeTable = Parameters<typeof selectMany>[1];
 export declare function purgeExpiredFileRefsWithBytes(args: {
     readonly db: TenantDb;
     readonly table: PurgeTable;
@@ -12,6 +12,7 @@ export declare function purgeExpiredFileRefsWithBytes(args: {
     readonly expiredBefore: Temporal.Instant;
     readonly files: FileContext | undefined;
     readonly log: PurgeLog;
+    readonly forgetRow: (id: string) => Promise<void>;
     readonly pageSize?: number;
 }): Promise<void>;
 export {};

package/dist/files/purge-expired-file-ref-bytes.js

@@ -1,4 +1,4 @@
-import { deleteMany, selectMany } from "../db/query.js";
+import { selectMany } from "../db/query.js";
 import { deleteFileRefBytes } from "../derivatives/delete-stored-file.js";
 export const EXPIRED_FILE_REF_PURGE_BATCH = 500;
 const PAGE_ORDER = [
@@ -20,12 +20,12 @@ async function selectNextPage(args) {
     return [...sameInstant, ...later];
 }
 // Deletes the bytes (original + derivatives) of expired soft-deleted fileRef rows, then the
-// rows. Bytes first and fail-closed: once the row is gone nobody knows the storageKey, so a
+// rows (forgotten through the executor, so a rebuild keeps them gone). Bytes first and fail-closed: once the row is gone nobody knows the storageKey, so a
 // row whose bytes could not be removed stays and the next run retries it. A run walks the
 // expired rows page by page along (deletedAt, id), so rows that keep failing cannot hide the
 // rows behind them; the run ends on the first empty page.
 export async function purgeExpiredFileRefsWithBytes(args) {
-    const { db, table, where, expiredBefore, files, log } = args;
+    const { db, table, where, expiredBefore, files, log, forgetRow } = args;
     const pageSize = args.pageSize ?? EXPIRED_FILE_REF_PURGE_BATCH;
     if (!files) {
         log?.warn("[soft-delete-cleanup] no file storage available, expired fileRef rows kept");
@@ -53,7 +53,13 @@ export async function purgeExpiredFileRefsWithBytes(args) {
                 log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not deleted, row kept: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        if (purgedIds.length > 0)
-            await deleteMany(db, table, { ...where, id: { in: purgedIds } });
+        for (const id of purgedIds) {
+            try {
+                await forgetRow(id);
+            }
+            catch (err) {
+                log?.warn(`[soft-delete-cleanup] fileRef ${id} bytes deleted but row not forgotten: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
     }
 }

package/dist/i18n/settings-hub-keys.js

@@ -19,6 +19,7 @@ export const SETTINGS_HUB_I18N = {
         en: "Choose a provider. Its settings appear below and are saved together with it.",
     },
     "config.settings.provider": { en: "Provider" },
+    "config.settings.provider.platformDefault": { en: "Platform default" },
     "config.settings.audience.system": {
         en: "Applies to every tenant unless a tenant sets its own value.",
     },

package/dist/internal/testing.d.ts

@@ -1,4 +1,6 @@
+import type { AnyDb } from "../db/query.ts";
 export { resetBlindIndexKeyForTests } from "../crypto/blind-index.ts";
 export { resetEventPiiCatalogForTests } from "../crypto/event-pii.ts";
 export { resetPiiSubjectKmsForTests } from "../crypto/pii-field-encryption.ts";
 export { resetEntityFieldEncryptionCacheForTests } from "../db/entity-field-encryption.ts";
+export declare function withExecutorManagedWritesForTests(db: AnyDb): AnyDb;

package/dist/internal/testing.js

@@ -1,5 +1,19 @@
-// @runtime test
+import { createTenantDb, withExecutorManagedWrites } from "../db/tenant-db.js";
+import { isBoundTenantDb, isDbRunner, tenantDbRunner } from "../db/tenant-db-runner.js";
 export { resetBlindIndexKeyForTests } from "../crypto/blind-index.js";
 export { resetEventPiiCatalogForTests } from "../crypto/event-pii.js";
 export { resetPiiSubjectKmsForTests } from "../crypto/pii-field-encryption.js";
 export { resetEntityFieldEncryptionCacheForTests } from "../db/entity-field-encryption.js";
+// Seeds and teardown write read-model rows without events; the capability is the sanctioned test seam.
+export function withExecutorManagedWritesForTests(db) {
+    if (isBoundTenantDb(db)) {
+        return createTenantDb({
+            db: withExecutorManagedWrites(tenantDbRunner(db)),
+            tenantId: db.tenantId,
+            mode: db.mode,
+        });
+    }
+    if (isDbRunner(db))
+        return withExecutorManagedWrites(db);
+    throw new Error("withExecutorManagedWritesForTests: expected a TenantDb or a postgres-js runner");
+}

package/dist/migrations/pii-event-backfill.js

@@ -37,13 +37,20 @@ export const piiBackfillStateTable = pgTable("kumiko_pii_backfill_state", {
     completedAt: instant("completed_at", { precision: 3 }),
     updatedAt: instant("updated_at", { precision: 3 }).notNull().default(sql `now()`),
 });
+const PII_EVENT_BACKFILL_DDL_LOCK_KEY = "pii-event-backfill:ddl";
+// CREATE and the follow-up ALTER are not atomic: without the lock a peer that sees the
+// freshly created table skips its own bootstrap and reads before the column exists.
+// The lock holder's transaction only carries the lock; the DDL runs on `db` itself.
 export async function createPiiBackfillStateTable(db) {
-    if (!(await tableExists(db, "public.kumiko_pii_backfill_state"))) {
-        await unsafePushTables(db, { kumikoPiiBackfillState: piiBackfillStateTable });
-    }
-    // Added after the table's first deploy; IF NOT EXISTS keeps concurrent replica boots safe.
-    await alterTableAddColumn(db, "kumiko_pii_backfill_state", "failed_event_ids", "bigint[]", " DEFAULT '{}'::bigint[]", " NOT NULL", 
-    /* ifNotExists */ true);
+    await db.begin(async (lockTx) => {
+        await acquireNamespacedAdvisoryLock(lockTx, PII_EVENT_BACKFILL_LOCK_NAMESPACE, PII_EVENT_BACKFILL_DDL_LOCK_KEY);
+        if (!(await tableExists(db, "public.kumiko_pii_backfill_state"))) {
+            await unsafePushTables(db, { kumikoPiiBackfillState: piiBackfillStateTable });
+        }
+        // Added after the table's first deploy; IF NOT EXISTS keeps older deployments upgradable.
+        await alterTableAddColumn(db, "kumiko_pii_backfill_state", "failed_event_ids", "bigint[]", " DEFAULT '{}'::bigint[]", " NOT NULL", 
+        /* ifNotExists */ true);
+    });
 }
 // Replicas boot concurrently: two of them can both pass the tableExists gate and
 // one CREATE then fails. The table existing afterwards means the other won.
@@ -71,7 +78,7 @@ export function piiAnnotationEntries(registry) {
 // Bump when the backfill gains a transform stage: completed states keyed by the
 // old fingerprint must run one more full pass. Kept out of piiAnnotationEntries,
 // whose emptiness gates no_pii.
-const PII_BACKFILL_TRANSFORM_VERSION = "owner-rekey-v2";
+const PII_BACKFILL_TRANSFORM_VERSION = "jsonb-objects-v3";
 export function piiAnnotationFingerprint(registry) {
     return createHash("sha256")
         .update([...piiAnnotationEntries(registry), PII_BACKFILL_TRANSFORM_VERSION].join("\n"))

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

@@ -3,7 +3,7 @@ import type { Logger } from "../logging/types.ts";
 import type { Meter } from "./types/index.ts";
 export declare const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
 export type EscapeHatchReportWindow = {
-    shouldReport(key: string, nowMs: number): boolean;
+    shouldReport(key: string, nowMs: number, windowMs?: number): boolean;
 };
 export declare function createEscapeHatchReportWindow(opts?: {
     readonly windowMs?: number;

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

@@ -11,12 +11,12 @@ export function createEscapeHatchReportWindow(opts) {
     // Map insertion order doubles as recency order: a re-set moves the key to the end.
     const entries = new Map();
     return {
-        shouldReport(key, nowMs) {
+        shouldReport(key, nowMs, keyWindowMs = windowMs) {
             const expiresAt = entries.get(key);
             if (expiresAt !== undefined && expiresAt > nowMs)
                 return false;
             entries.delete(key);
-            entries.set(key, nowMs + windowMs);
+            entries.set(key, nowMs + keyWindowMs);
             while (entries.size > maxEntries) {
                 const oldestKey = entries.keys().next().value;
                 if (oldestKey === undefined)
@@ -27,6 +27,16 @@ export function createEscapeHatchReportWindow(opts) {
         },
     };
 }
+// Cross-tenant reads without a target (every reference lookup of a SystemAdmin list is one)
+// repeat on each page load. One event per actor and hour keeps the trace that a SystemAdmin read
+// other tenants without flooding the audit view; the in-memory window means one event per
+// instance with several instances, which is acceptable. Writes, identity switches and anything
+// aimed at a target keep the short window.
+const READ_WINDOW_MS = 60 * 60 * 1000;
+const READ_WINDOW_KINDS = new Set([
+    "acknowledge-cross-tenant",
+    "cross-tenant-read",
+]);
 // 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;
@@ -165,8 +175,9 @@ export function createEscapeHatchReporter(opts) {
             target?.id ?? null,
             target?.tenantId ?? null,
         ]);
+        const isTargetlessRead = READ_WINDOW_KINDS.has(kind) && target === undefined;
         // skip: same (handler, kind, reason, target) already reported within the window — dedup
-        if (!window.shouldReport(key, now()))
+        if (!window.shouldReport(key, now(), isTargetlessRead ? READ_WINDOW_MS : undefined))
             return;
         reportEscapeHatchUse(eventFor(kind, reason, target), deps);
     };

package/dist/pipeline/cascade-handler.js

@@ -1,7 +1,13 @@
-import { deleteMany, fetchOne, selectMany, updateMany } from "../db/query.js";
+import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { fetchOne, selectMany } from "../db/query.js";
+import { isBoundTenantDb } from "../db/tenant-db-runner.js";
 import { OnDeleteStrategies, SystemHookNames, SystemHookPriorities } from "../engine/constants.js";
 import { isRecordLocked } from "../engine/screen-helpers.js";
-import { ConflictError, FrameworkReasons, RecordLockedError } from "../errors/index.js";
+import { createSystemUser } from "../engine/system-user.js";
+import { ConflictError, FrameworkReasons, InternalError, RecordLockedError, reraiseAsKumikoError, } from "../errors/index.js";
+// The cascade is a consequence of the parent delete the caller was already authorized for, so the
+// children are written as the framework system user and the lock decision is taken once, up front.
+const CASCADE_CHILD_WRITE_OPTIONS = { unsafeSkipLockGuard: true };
 export function createCascadeDeleteHook(registry, tables) {
     return {
         name: SystemHookNames.cascadeDelete,
@@ -15,6 +21,41 @@ export function createCascadeDeleteHook(registry, tables) {
                 ctx.log?.debug(`cascadeDelete: skipping — ${!entityName ? "no entityName" : "no db"} on payload ${payload.id}`);
                 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);
+            };
             // 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
@@ -33,6 +74,13 @@ export function createCascadeDeleteHook(registry, tables) {
                     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) {
@@ -48,11 +96,10 @@ export function createCascadeDeleteHook(registry, tables) {
                             });
                         }
                     }
-                    // The raw delete/update below bypasses the executor, so a locked child must
-                    // block the parent delete here instead of changing with it. The error names
+                    // 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 childEntity = registry.getEntity(relation.target);
                         const childLock = childEntity?.lockedWhen;
                         if (childLock !== undefined && payload.lockGuardBypassed !== true) {
                             // A soft-deleted child is invisible to the caller and must not block.
@@ -65,11 +112,24 @@ export function createCascadeDeleteHook(registry, tables) {
                             }
                         }
                     }
-                    if (strategy === OnDeleteStrategies.cascade) {
-                        await deleteMany(db, targetTable, { [relation.foreignKey]: 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) {
-                        await updateMany(db, targetTable, { [relation.foreignKey]: null }, { [relation.foreignKey]: payload.id });
+                    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) {
@@ -94,7 +154,16 @@ export function createCascadeDeleteHook(registry, tables) {
                         }
                     }
                     if (strategy === OnDeleteStrategies.cascade) {
-                        await deleteMany(db, throughTable, { [sourceKey]: payload.id });
+                        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));
+                        }
                     }
                 }
             }

package/dist/pipeline/dispatch-shared.js

@@ -1,7 +1,7 @@
 import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { requestContext, runWithOrigin } from "../api/request-context.js";
 import { runInSavepoint, selectMany } from "../db/query.js";
-import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, runInOwnTransaction, } from "../db/tenant-db.js";
+import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { mayOverrideTenant } from "../engine/cross-tenant.js";
 import { createSystemUser } from "../engine/system-user.js";
@@ -166,7 +166,6 @@ export function applyMemberResolutionReadOnly(handlerContext) {
         // `db` stays open — executeQuery runs the whole handler in a Postgres READ ONLY
         // transaction, and its `memberReadOnly` grant denies every raw-runner handout.
         dbOutsideTransaction: undefined,
-        outsideTransaction: undefined,
         write: denyMemberResolutionWrite,
         writeAs: denyMemberResolutionWrite,
         // A resolved member cannot switch identity either — the target would get a normal, writable context.
@@ -253,7 +252,6 @@ export function applyBeforeTransactionReadOnly(handlerContext) {
     return {
         ...denyTransactionBoundSurfaces(handlerContext),
         dbOutsideTransaction: undefined,
-        outsideTransaction: undefined,
     };
 }
 export async function buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, includeDeleted, transactionScope = tx ? "inTransaction" : "withoutTransaction", 
@@ -341,11 +339,6 @@ readOnlyForTenant = false) {
         ? createSystemScopedDbGuard(type, "dbOutsideTransaction", "ctx.systemDb.outsideTransaction.assertTenantMatch(...) or " +
             "ctx.systemDb.outsideTransaction.acknowledgeCrossTenant(...)")
         : rawDbOutsideTransaction;
-    // Not offered to r.systemScope() handlers: the raw outside-tx db is unfiltered in
-    // system mode, so fn would hand them the same cross-tenant door the guards above close.
-    const outsideTransaction = !isSystem && rawDbOutsideTransaction
-        ? (fn) => runInOwnTransaction(rawDbOutsideTransaction, fn)
-        : undefined;
     const log = context.log?.child({
         handler: type,
         tenantId: user.tenantId,
@@ -861,7 +854,6 @@ readOnlyForTenant = false) {
         registry,
         db: exposedDb,
         dbOutsideTransaction,
-        ...(outsideTransaction && { outsideTransaction }),
         ...(systemDb && { systemDb }),
         log,
         notify,

package/dist/pipeline/msp-rebuild.js

@@ -1,6 +1,7 @@
 import { markConsumerRebuildFailed, resetConsumerForMspRebuild, selectConsumerForUpdate, selectEventIdHorizonWithMissingRanges, selectSnapshotXmax, updateConsumerRebuildCursor, } from "../db/queries/event-consumer.js";
 import { assertLiveColumnsMatchMeta, assertLiveTableHasNoRowLevelSecurity, buildShadowTable, ensureRebuildSchema, rebuildMetaOrThrow, swapShadowIntoLive, } from "../db/queries/shadow-swap.js";
 import { runInSavepoint, selectMany } from "../db/query.js";
+import { withExecutorManagedWrites } from "../db/tenant-db.js";
 import { InternalError } from "../errors/index.js";
 import { loadAggregate, loadAggregateAsOf } from "../event-store/event-store.js";
 import { eventsTable, upcastStoredEvent } from "../event-store/index.js";
@@ -70,6 +71,7 @@ export async function rebuildMultiStreamProjection(mspName, deps) {
                 // paths from ever double-applying the same event.
                 const events = await selectMany(tx, eventsTable, { type: [...subscribedTypes], id: { lte: horizon } }, { orderBy: { col: "id", direction: "asc" } });
                 const upcasters = registry.getEventUpcasters();
+                const applyTx = withExecutorManagedWrites(tx);
                 for (const row of events) {
                     deps.signal?.throwIfAborted();
                     const raw = {
@@ -99,7 +101,7 @@ export async function rebuildMultiStreamProjection(mspName, deps) {
                         // reject the whole begin() even after a caught error. Apply +
                         // ctx run on the savepoint-scoped handle.
                         try {
-                            await runInSavepoint(tx, async (sp) => {
+                            await runInSavepoint(applyTx, async (sp) => {
                                 const rebuildCtx = createRebuildCtx(registry, sp, row.tenantId);
                                 await applyFn(storedEvent, sp, rebuildCtx);
                             });
@@ -109,8 +111,8 @@ export async function rebuildMultiStreamProjection(mspName, deps) {
                         }
                     }
                     else {
-                        const rebuildCtx = createRebuildCtx(registry, tx, row.tenantId);
-                        await applyFn(storedEvent, tx, rebuildCtx);
+                        const rebuildCtx = createRebuildCtx(registry, applyTx, row.tenantId);
+                        await applyFn(storedEvent, applyTx, rebuildCtx);
                     }
                     eventsProcessed++;
                     lastProcessedEventId = row.id;

package/dist/pipeline/projection-rebuild.js

@@ -1,6 +1,7 @@
 import { countSubscribedEvents, finalizeProjectionRebuild, markProjectionRebuildFailed, markProjectionRebuilding, selectEventsForProjectionRebuildBatch, } from "../db/queries/projection-rebuild.js";
 import { assertLiveColumnsMatchMeta, assertLiveTableHasNoRowLevelSecurity, assertNoBlindIndexLoss, assertNoUnreachableLiveRows, buildShadowTable, countColumnDrift, ensureRebuildSchema, fenceLiveTable, rebuildMetaOrThrow, swapShadowIntoLive, } from "../db/queries/shadow-swap.js";
 import { coerceRow, extractTableInfo, runInSavepoint, selectMany } from "../db/query.js";
+import { withExecutorManagedWrites } from "../db/tenant-db.js";
 import { eventsTable, getEventsHighWaterMark, upcastStoredEvent, } from "../event-store/index.js";
 import { createRebuildDeadLetterTable, recordRebuildDeadLetters, } from "../event-store/rebuild-dead-letter.js";
 import { emitProjectionRebuild } from "../observability/standard-metrics.js";
@@ -74,6 +75,7 @@ export async function rebuildProjection(projectionName, deps) {
     // (a short batch = no more currently-committed events).
     const drainBatch = async (tx) => {
         const rawEvents = await selectEventsForProjectionRebuildBatch(tx, sourcesList, subscribedList, lastProcessedEventId, REBUILD_BATCH_SIZE);
+        const applyTx = withExecutorManagedWrites(tx);
         for (const r of rawEvents) {
             deps.signal?.throwIfAborted();
             const row = coerceRow(r, eventsInfo);
@@ -92,7 +94,7 @@ export async function rebuildProjection(projectionName, deps) {
                 // begin() even after a caught error. The apply runs on the
                 // savepoint-scoped handle so its statements are confined.
                 try {
-                    await runInSavepoint(tx, async (sp) => {
+                    await runInSavepoint(applyTx, async (sp) => {
                         await applyFn(storedEvent, sp, projection.table);
                     });
                 }
@@ -101,7 +103,7 @@ export async function rebuildProjection(projectionName, deps) {
                 }
             }
             else {
-                await applyFn(storedEvent, tx, projection.table);
+                await applyFn(storedEvent, applyTx, projection.table);
             }
             eventsProcessed++;
             lastProcessedEventId = row.id;

package/dist/pipeline/projections-runner.js

@@ -1,3 +1,4 @@
+import { withExecutorManagedWrites } from "../db/tenant-db.js";
 import { InternalError } from "../errors/index.js";
 // Run custom projections for a save or delete result. Lives INSIDE the
 // transaction that appended the event — a throw from apply() rolls the event
@@ -59,7 +60,7 @@ export async function runProjectionsForEvent(event, registry, tx) {
     for (const proj of liveProjectionsForEvent(event, registry)) {
         const applyFn = proj.apply[event.type];
         if (applyFn)
-            await applyFn(event, tx, proj.table);
+            await applyFn(event, withExecutorManagedWrites(tx), proj.table);
     }
     projectedEvents.add(event);
 }

package/dist/rate-limit/index.d.ts

@@ -1,4 +1,4 @@
 export { type BucketContext, type BucketResult, buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.ts";
-export { type AuthEndpointRateLimitOptions, authEndpointRateLimit, type GlobalIpRateLimitOptions, globalIpRateLimit, type HttpRouteRateLimitOptions, httpRouteRateLimit, } from "./middleware.ts";
+export { type AuthEndpointRateLimitOptions, authEndpointRateLimit, DEFAULT_GLOBAL_RATE_LIMIT, type GlobalIpRateLimitOptions, globalIpRateLimit, type HttpRouteRateLimitOptions, httpRouteRateLimit, } from "./middleware.ts";
 export { createRateLimitResolver, type RateLimitBucketRequest, type RateLimitConfig, type RateLimitDecision, type RateLimitResolver, type RateLimitResolverOptions, } from "./resolver.ts";
 export { createUnlimitedRateLimitResolver } from "./unlimited-resolver.ts";