@cosmicdrift/kumiko-framework 0.378.0 → 0.380.0

package/dist/files/storage-tracking.d.ts

@@ -7,7 +7,7 @@ export declare function fileRefStorageDelta(event: {
     readonly bytes: number;
     readonly files: number;
 } | null;
-export declare const tenantStorageUsageTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const tenantStorageUsageTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare const filesStorageTrackingFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;
 };

package/dist/files/upload-ledger.d.ts

@@ -1,10 +1,10 @@
+import type { WritableTable } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { FileProviderResolver, FileUploadLedger } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-types/file-storage-provider-types";
 import type { TenantId } from "@cosmicdrift/kumiko-types/identifiers";
 import type { DbConnection } from "../db/connection.ts";
-import { type EntityTableMeta } from "../db/entity-table-meta.ts";
 import { type TenantDb } from "../db/tenant-db.ts";
-export declare const fileUploadLedgerTable: EntityTableMeta;
+export declare const fileUploadLedgerTable: WritableTable;
 export declare function createFileUploadLedger(db: DbConnection | TenantDb, tenantId: TenantId): FileUploadLedger;
 export declare function withUploadLedger(resolver: (tenantId: TenantId) => Promise<FileStorageProvider>, db: DbConnection | TenantDb): FileProviderResolver;
 export declare function takeUploadLedgerEntry(txDb: TenantDb, storageKey: string): Promise<boolean>;

package/dist/internal/testing.d.ts

@@ -1,4 +1,11 @@
+import type { DbRunner } from "@cosmicdrift/kumiko-types/db-connection";
+import type { ExecutorManagedRunner } from "@cosmicdrift/kumiko-types/executor-brand";
+import type { AnyDb } from "../db/query.ts";
+import { type ExecutorManagedTenantDb, type TenantDb } from "../db/tenant-db.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: TenantDb): ExecutorManagedTenantDb;
+export declare function withExecutorManagedWritesForTests(db: DbRunner): ExecutorManagedRunner;
+export declare function withExecutorManagedWritesForTests(db: AnyDb): ExecutorManagedTenantDb | ExecutorManagedRunner;

package/dist/internal/testing.js

@@ -1,5 +1,18 @@
-// @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";
+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/pending-rebuilds.d.ts

@@ -3,7 +3,7 @@ import type { Registry } from "../engine/types/index.ts";
 import type { JobRunner } from "../jobs/index.ts";
 import type { Logger } from "../logging/types.ts";
 import { type RebuildResult } from "../pipeline/index.ts";
-export declare const pendingRebuildsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const pendingRebuildsTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createPendingRebuildsTable(db: DbConnection): Promise<void>;
 /** Liest die rebuild-Marker der frisch applizierten Migrations und queued
  *  die betroffenen Tabellen. Upsert: ein bereits pending-er Tisch behält

package/dist/migrations/pii-event-backfill.d.ts

@@ -2,7 +2,7 @@ import type { DbConnection } from "../db/connection.ts";
 import { type PiiBackfillFailure } from "../db/queries/backfill-pii.ts";
 import type { Registry } from "../engine/types/index.ts";
 import type { Logger } from "../logging/types.ts";
-export declare const piiBackfillStateTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const piiBackfillStateTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createPiiBackfillStateTable(db: DbConnection): Promise<void>;
 export declare function piiAnnotationEntries(registry: Registry): readonly string[];
 export declare function piiAnnotationFingerprint(registry: Registry): string;

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/event-consumer-state.d.ts

@@ -5,7 +5,7 @@ export type PendingGapEntry = {
     readonly to: string;
     readonly xmax: string;
 };
-export declare const eventConsumerStateTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const eventConsumerStateTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare const ConsumerStatuses: {
     readonly idle: "idle";
     readonly processing: "processing";

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/projection-state.d.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "../db/connection.ts";
-export declare const projectionStateTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const projectionStateTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare const ProjectionStatuses: {
     readonly idle: "idle";
     readonly rebuilding: "rebuilding";

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

package/dist/rate-limit/index.js

@@ -1,4 +1,4 @@
 export { buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.js";
-export { authEndpointRateLimit, globalIpRateLimit, httpRouteRateLimit, } from "./middleware.js";
+export { authEndpointRateLimit, DEFAULT_GLOBAL_RATE_LIMIT, globalIpRateLimit, httpRouteRateLimit, } from "./middleware.js";
 export { createRateLimitResolver, } from "./resolver.js";
 export { createUnlimitedRateLimitResolver } from "./unlimited-resolver.js";

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

@@ -11,6 +11,10 @@ export type GlobalIpRateLimitOptions = {
     readonly extractIp?: (c: Context) => string | undefined;
     readonly onFailClosed?: (err: unknown) => void;
 };
+export declare const DEFAULT_GLOBAL_RATE_LIMIT: {
+    readonly limit: 600;
+    readonly windowSeconds: 60;
+};
 export declare function globalIpRateLimit(opts: GlobalIpRateLimitOptions): MiddlewareHandler;
 export type HttpRouteRateLimitOptions = {
     readonly resolver: RateLimitResolver;

package/dist/rate-limit/middleware.js

@@ -3,9 +3,12 @@ import { clientIpSourceFromHonoContext, createClientIpResolver, } from "../api/c
 import { requestContext } from "../api/request-context.js";
 import { RateLimitError, serializeError } from "../errors/index.js";
 import { toPublicBucketName } from "./bucket.js";
+// Shared with runProdApp (server-runtime re-exports it). The auth middleware default stays
+// stricter than runProdApp's auth limit (30): a bare authEndpointRateLimit guards brute force.
+export const DEFAULT_GLOBAL_RATE_LIMIT = { limit: 600, windowSeconds: 60 };
 export function globalIpRateLimit(opts) {
-    const limit = opts.limit ?? 1000;
-    const windowSeconds = opts.windowSeconds ?? 60;
+    const limit = opts.limit ?? DEFAULT_GLOBAL_RATE_LIMIT.limit;
+    const windowSeconds = opts.windowSeconds ?? DEFAULT_GLOBAL_RATE_LIMIT.windowSeconds;
     const clientIpResolver = opts.clientIpResolver ??
         createClientIpResolver(opts.trustedProxyHops ?? 0, "globalIpRateLimit");
     const extractIp = opts.extractIp ?? ((c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c)));

package/dist/ui-types/index.d.ts

@@ -6,7 +6,7 @@ export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperan
 export type { ParsedRefTarget } from "../engine/parse-ref-target.ts";
 export { parseRefTarget } from "../engine/parse-ref-target.ts";
 export type { FieldsOrGroupsSection, UnavailableSelectOption } from "../engine/screen-helpers.ts";
-export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.ts";
+export { ACTION_FORM_PSEUDO_ENTITY, availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.ts";
 export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, SelectFieldDef, SelectOptionTone, TextFieldDef, } from "../engine/types/fields.ts";
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.ts";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.ts";
@@ -22,5 +22,5 @@ export type { CardColumnRoles, CardRoleColumn } from "./card-column-roles.ts";
 export { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind } from "./card-column-roles.ts";
 export { type Formality, formalLocaleTag } from "./formality.ts";
 export type { ListRowMetaColumnType, ListRowMetaReference, ReferenceLookupSource, SystemReferenceLabel, } from "./list-row-meta.ts";
-export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "./list-row-meta.ts";
+export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, UNRESOLVED_REFERENCE_LABEL_KEYS, } from "./list-row-meta.ts";
 export { type PluralForms, resolveTranslationValue, type TranslationValue, translationValueOtherText, } from "./plural.ts";

package/dist/ui-types/index.js

@@ -23,11 +23,11 @@ export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived.js";
 export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperand, } from "../engine/form-derivations.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
-export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
+export { ACTION_FORM_PSEUDO_ENTITY, availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
 export { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind } from "./card-column-roles.js";
 export { formalLocaleTag } from "./formality.js";
-export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "./list-row-meta.js";
+export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, UNRESOLVED_REFERENCE_LABEL_KEYS, } from "./list-row-meta.js";
 export { resolveTranslationValue, translationValueOtherText, } from "./plural.js";

package/dist/ui-types/list-row-meta.d.ts

@@ -13,6 +13,9 @@ export type ReferenceLookupSource = {
 export declare const REFERENCE_LOOKUP_SOURCES: Readonly<Record<string, ReferenceLookupSource>>;
 export type SystemReferenceLabel = {
     readonly id: string;
+    /** Further literals that mean the same system identity (e.g. the "system" createdBy literal). */
+    readonly aliases?: readonly string[];
     readonly labelKey: string;
 };
 export declare const SYSTEM_REFERENCE_LABELS: Readonly<Record<string, SystemReferenceLabel>>;
+export declare const UNRESOLVED_REFERENCE_LABEL_KEYS: Readonly<Record<string, string>>;

package/dist/ui-types/list-row-meta.js

@@ -61,5 +61,16 @@ export const SYSTEM_REFERENCE_LABELS = {
     "tenant:tenant": { id: SYSTEM_TENANT_ID, labelKey: "kumiko.reference.system-tenant" },
     // createdBy on a system write (fw#3103) — SYSTEM_USER_ID is an alias for
     // "no human caller", so read_users never holds a matching row.
-    "user:user": { id: SYSTEM_USER_ID, labelKey: "kumiko.reference.system-user" },
+    "user:user": {
+        id: SYSTEM_USER_ID,
+        aliases: ["system"],
+        labelKey: "kumiko.reference.system-user",
+    },
+};
+// Label for a reference id that is neither a system identity nor has a
+// visible row (deleted user, seed actor, row outside the caller's scope).
+// Without it a reference cell falls back to the raw UUID. Opt-in per entity:
+// for entities whose id is meaningful to the reader the raw id stays.
+export const UNRESOLVED_REFERENCE_LABEL_KEYS = {
+    "user:user": "kumiko.reference.unknown-user",
 };

package/kumiko-es-tables.json

@@ -0,0 +1,6 @@
+[
+  {
+    "module": "files/file-ref-table",
+    "export": "fileRefsTable"
+  }
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.378.0",
+  "version": "0.380.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -199,7 +199,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.378.0",
+    "@cosmicdrift/kumiko-types": "0.380.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.378.0",
+    "@cosmicdrift/kumiko-testing": "0.380.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },
@@ -394,6 +394,7 @@
   },
   "files": [
     "dist",
+    "kumiko-es-tables.json",
     "presets",
     "src/changes.json",
     "src/scripts/codemod",