@cosmicdrift/kumiko-framework 0.378.0 → 0.380.0

package/dist/db/tenant-db.js

@@ -4,8 +4,10 @@ import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, co
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
+import { assertWritableTable, executorManagedWriteDenied, hasExecutorManagedWriteCapability, registerExecutorManagedWriteRunner, } from "./executor-managed-tables.js";
 import { bindProjectionRegistry, projectionRegistryOf } from "./projection-registry-binding.js";
 import { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
+import { queryDatabaseNow } from "./queries/database-now.js";
 import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
 import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
@@ -17,8 +19,8 @@ const personalDataGates = new WeakMap();
 // Lets createTenantDb(ctx.db.unsafeRaw(), ...) inherit the gate and the projection registry.
 // Keyed by a per-grant proxy, never the shared pool/tx: tagging that would leak onto every sibling TenantDb.
 const runnerPersonalDataGates = new WeakMap();
-function boundRunner(runner, gate, projectionRegistry) {
-    if (!gate && !projectionRegistry)
+function boundRunner(runner, gate, projectionRegistry, executorManagedWrites) {
+    if (!gate && !projectionRegistry && !executorManagedWrites)
         return runner;
     const proxy = new Proxy(runner, {
         // Tagged-template calls need the real driver object as `this`.
@@ -33,7 +35,7 @@ function boundRunner(runner, gate, projectionRegistry) {
                 // Bun.SQL and postgres.js hand back a raw connection; re-wrap it so the gate survives.
                 return async (...args) => {
                     const reserved = await Reflect.apply(value, target, args);
-                    return boundRunner(reserved, gate, projectionRegistry);
+                    return boundRunner(reserved, gate, projectionRegistry, executorManagedWrites);
                 };
             }
             if (prop === "begin" ||
@@ -48,7 +50,7 @@ function boundRunner(runner, gate, projectionRegistry) {
                     }
                     const gatedArgs = [
                         ...args.slice(0, -1),
-                        (tx) => callback(boundRunner(tx, gate, projectionRegistry)),
+                        (tx) => callback(boundRunner(tx, gate, projectionRegistry, executorManagedWrites)),
                     ];
                     return Reflect.apply(value, target, gatedArgs);
                 };
@@ -60,8 +62,35 @@ function boundRunner(runner, gate, projectionRegistry) {
         runnerPersonalDataGates.set(proxy, gate);
     if (projectionRegistry)
         bindProjectionRegistry(proxy, projectionRegistry);
+    if (executorManagedWrites) {
+        registerExecutorManagedWriteRunner(proxy);
+        capableRunnerInners.set(proxy, runner);
+    }
     return proxy;
 }
+const capableRunnerInners = new WeakMap();
+const capableRunnerByInner = new WeakMap();
+// Framework-private (not re-exported from db/index.ts): the only way to obtain a runner that may
+// write executor-managed tables. Only the framework's own event-apply paths call it.
+export function withExecutorManagedWrites(runner) {
+    if (hasExecutorManagedWriteCapability(runner))
+        return runner;
+    const cached = capableRunnerByInner.get(runner);
+    if (cached)
+        return cached;
+    const capable = boundRunner(runner, runnerPersonalDataGates.get(runner), projectionRegistryOf(runner), true);
+    if (!hasExecutorManagedWriteCapability(capable)) {
+        throw new InternalError({
+            message: "boundRunner did not register the executor write capability",
+        });
+    }
+    capableRunnerByInner.set(runner, capable);
+    return capable;
+}
+// unsafeRaw must not hand out the executor-only write capability, even from a capable runner.
+export function withoutExecutorManagedWrites(runner) {
+    return capableRunnerInners.get(runner) ?? runner;
+}
 // The executor passes its entity so the check does not depend on the table-name lookup.
 export function assertPersonalDataWrite(db, tableName, keys, entity) {
     personalDataGates.get(db)?.(tableName, keys, entity);
@@ -134,8 +163,8 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
         }
         // Engine-forwarded steps carry their own declared reason; a caller-supplied one never reaches the audit trail.
         report("unsafe-raw", forwardedDeclaredStep ? reason : (gate?.grant?.reason ?? reason));
-        const runner = tenantDbRunner(db);
-        return boundRunner(runner, personalDataGates.get(db), projectionRegistryOf(db));
+        const runner = withoutExecutorManagedWrites(tenantDbRunner(db));
+        return boundRunner(runner, personalDataGates.get(db), projectionRegistryOf(db), false);
     }
     const uncheckedSystemDb = {
         [SYSTEM_SCOPE_CHECK_BRAND]: true,
@@ -327,6 +356,10 @@ export async function runInOwnTransaction(tenantDb, fn) {
 export function createTenantDb(options) {
     return buildTenantDb(options);
 }
+// Tenant-destroy hooks purge their own tenant's event-fed rows; the pinned tenant is the only reach and unsafeRaw stays without the write capability.
+export function createTenantDataDestroyDb(options) {
+    return createTenantDb({ ...options, db: withExecutorManagedWrites(options.db), mode: "tenant" });
+}
 // Untyped JS callers or an `as` cast can still hand in undefined; a scoped handle
 // without a tenant would bind `tenant_id = NULL` instead of failing loudly.
 function buildTenantDb(options) {
@@ -424,14 +457,6 @@ function buildTenantDb(options) {
                 "writes through db.global().",
         });
     }
-    // The ExecutorOnly brand is type-only; a type-erased table must still not reach the read model without an event.
-    function executorManagedWriteDenied(table) {
-        if (asEntityTableMeta(table)?.source === "unmanaged")
-            return undefined;
-        return new AccessDeniedError({
-            message: `db.global(${tableNameOf(table)}): writes on executor-managed entity tables must go through the entity executor`,
-        });
-    }
     function writesDenied(operation) {
         const reason = grants?.writesDeniedReason;
         return reason === undefined ? undefined : tenantDbWritesDeniedError(operation, reason);
@@ -468,6 +493,26 @@ function buildTenantDb(options) {
                 "use db.global(table) with escapeHatch instead.",
         });
     }
+    // Callers ran executorManagedWriteDenied first: either db holds the capability or the table is
+    // unmanaged. The split only proves to the compiler which overload of the free writers applies.
+    function insertRow(table, values) {
+        if (hasExecutorManagedWriteCapability(db))
+            return bunInsertOne(db, table, values);
+        assertWritableTable(table);
+        return bunInsertOne(db, table, values);
+    }
+    function updateRows(table, set, where) {
+        if (hasExecutorManagedWriteCapability(db))
+            return bunUpdateMany(db, table, set, where);
+        assertWritableTable(table);
+        return bunUpdateMany(db, table, set, where);
+    }
+    function deleteRows(table, where) {
+        if (hasExecutorManagedWriteCapability(db))
+            return bunDeleteMany(db, table, where);
+        assertWritableTable(table);
+        return bunDeleteMany(db, table, where);
+    }
     function globalTable(table) {
         const meta = asEntityTableMeta(table);
         if (meta?.tenancy !== "global") {
@@ -485,18 +530,18 @@ function buildTenantDb(options) {
             insertOne(values) {
                 const denied = writesDenied("ctx.db.global().insertOne") ??
                     missingEscapeHatch(table) ??
-                    executorManagedWriteDenied(table) ??
+                    executorManagedWriteDenied(db, table, "db.global().insertOne") ??
                     foreignTenantOnGlobalWrite(table, values["tenantId"]) ??
                     personalDataDenied(table, Object.keys(values));
                 if (denied)
                     return Promise.reject(denied);
                 report("global-write", globalWriteReason());
-                return withDbSpan("insert", table, async () => bunInsertOne(db, table, values));
+                return withDbSpan("insert", table, async () => insertRow(table, values));
             },
             updateMany(set, where) {
                 const denied = writesDenied("ctx.db.global().updateMany") ??
                     missingEscapeHatch(table) ??
-                    executorManagedWriteDenied(table) ??
+                    executorManagedWriteDenied(db, table, "db.global().updateMany") ??
                     foreignTenantOnGlobalWrite(table, set["tenantId"]) ??
                     personalDataDenied(table, Object.keys(set));
                 if (denied)
@@ -505,12 +550,12 @@ function buildTenantDb(options) {
                     return Promise.reject(new Error("db.global().updateMany without where would mass-update every tenant's rows. Pass at least one where condition."));
                 }
                 report("global-write", globalWriteReason());
-                return withDbSpan("update", table, async () => bunUpdateMany(db, table, set, where));
+                return withDbSpan("update", table, async () => updateRows(table, set, where));
             },
             deleteMany(where) {
                 const denied = writesDenied("ctx.db.global().deleteMany") ??
                     missingEscapeHatch(table) ??
-                    executorManagedWriteDenied(table);
+                    executorManagedWriteDenied(db, table, "db.global().deleteMany");
                 if (denied)
                     return Promise.reject(denied);
                 if (!where || Object.keys(where).length === 0) {
@@ -518,10 +563,10 @@ function buildTenantDb(options) {
                 }
                 report("global-write", globalWriteReason());
                 return withDbSpan("delete", table, async () => {
-                    await bunDeleteMany(db, table, where);
+                    await deleteRows(table, where);
                 });
             },
-            // @cast-boundary phantom-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
+            // @cast-boundary phantom-brand — GlobalWrites is only present in the type when TTable carries Writable; the object above always carries the methods.
         };
     }
     function grantedUnsafeRawRunner(declaredStepReason) {
@@ -537,7 +582,7 @@ function buildTenantDb(options) {
         }
         // Engine-forwarded steps carry their own declared reason; otherwise the grant's reason is audited.
         report("unsafe-raw", declaredStepReason ?? grants?.unsafeRaw?.reason ?? "");
-        return boundRunner(db, personalDataGate, projectionRegistry);
+        return boundRunner(withoutExecutorManagedWrites(db), personalDataGate, projectionRegistry, false);
     }
     const tenantDb = {
         tenantId,
@@ -559,6 +604,9 @@ function buildTenantDb(options) {
         advisoryXactLock(namespace, key) {
             return acquireNamespacedAdvisoryLock(db, namespace, `${tenantId}:${key}`);
         },
+        databaseNow() {
+            return queryDatabaseNow(db);
+        },
         aggregate(table, spec, where) {
             const filter = readWhere(table, where);
             return withDbSpan("select", table, async () => bunAggregateWhere(db, table, spec, filter));
@@ -578,8 +626,11 @@ function buildTenantDb(options) {
             const personalDenied = personalDataDenied(table, Object.keys(values));
             if (personalDenied)
                 return Promise.reject(personalDenied);
+            const managedDenied = executorManagedWriteDenied(db, table, "ctx.db.insertOne");
+            if (managedDenied)
+                return Promise.reject(managedDenied);
             const data = insertValues(table, values);
-            return withDbSpan("insert", table, async () => bunInsertOne(db, table, data));
+            return withDbSpan("insert", table, async () => insertRow(table, data));
         },
         updateMany(table, set, where) {
             const writeDenied = writesDenied("ctx.db.updateMany");
@@ -594,8 +645,11 @@ function buildTenantDb(options) {
             const personalDenied = personalDataDenied(table, Object.keys(set));
             if (personalDenied)
                 return Promise.reject(personalDenied);
+            const managedDenied = executorManagedWriteDenied(db, table, "ctx.db.updateMany");
+            if (managedDenied)
+                return Promise.reject(managedDenied);
             const filter = writeWhere(table, where);
-            return withDbSpan("update", table, async () => bunUpdateMany(db, table, set, filter));
+            return withDbSpan("update", table, async () => updateRows(table, set, filter));
         },
         deleteMany(table, where) {
             const writeDenied = writesDenied("ctx.db.deleteMany");
@@ -607,8 +661,11 @@ function buildTenantDb(options) {
             const globalDenied = tenantWriteOnGlobalTable(table, "deleteMany");
             if (globalDenied)
                 return Promise.reject(globalDenied);
+            const managedDenied = executorManagedWriteDenied(db, table, "ctx.db.deleteMany");
+            if (managedDenied)
+                return Promise.reject(managedDenied);
             const filter = writeWhere(table, where);
-            return withDbSpan("delete", table, async () => bunDeleteMany(db, table, filter));
+            return withDbSpan("delete", table, async () => deleteRows(table, filter));
         },
     };
     declaredUnsafeRawRunners.set(tenantDb, grantedUnsafeRawRunner);

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

@@ -659,10 +659,15 @@ function validateEmbeddedTotalsColumns(fieldName, entityName, field) {
     // skip: no totals columns declared — nothing to validate
     if (field.totals === undefined)
         return;
-    for (const totalName of field.totals) {
-        const totalSubField = field.schema[totalName];
-        if (!totalSubField || !NUMERIC_EMBEDDED_SUB_TYPES.has(totalSubField.type)) {
-            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" lists "${totalName}" in totals, but it is not a number/money/decimal sub-field. List only number, money or decimal sub-fields in totals.`);
+    for (const total of field.totals) {
+        if (typeof total !== "string" && total.from.length === 0) {
+            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a totals entry "${total.label}" with an empty "from". List at least one number, money or decimal sub-field.`);
+        }
+        for (const totalName of typeof total === "string" ? [total] : total.from) {
+            const totalSubField = field.schema[totalName];
+            if (!totalSubField || !NUMERIC_EMBEDDED_SUB_TYPES.has(totalSubField.type)) {
+                throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" lists "${totalName}" in totals, but it is not a number/money/decimal sub-field. List only number, money or decimal sub-fields in totals.`);
+            }
         }
     }
 }

package/dist/engine/boot-validator/query-refs.js

@@ -86,6 +86,14 @@ function checkEditFormScreenQueryRefs(queryHandlers, featureName, screenId, scre
     checkEditLayoutQueryRefs(queryHandlers, featureName, screenId, screen.type, screen.layout);
     if (screen.type === "actionForm" && screen.load !== undefined) {
         checkQueryRef(queryHandlers, screen.load.query, () => `[Feature ${featureName}] Screen "${screenId}" (actionForm) load`);
+        // A singleton load sends no id, so a query that requires input would fail on every open.
+        const loadHandler = queryHandlers.get(screen.load.query);
+        if (screen.load.singleton === true &&
+            loadHandler !== undefined &&
+            !loadHandler.schema.safeParse({}).success) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (actionForm) load.singleton query "${screen.load.query}" ` +
+                "requires input; a singleton load runs with an empty payload. Make the query's input fields optional.");
+        }
     }
     if (screen.type !== "entityEdit") {
         checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screen.type, screen.fields);

package/dist/engine/boot-validator/screens.js

@@ -183,21 +183,25 @@ function validateRowActionNavigateParams(featureName, screenId, screenType, scre
         return;
     if (target.screen.type === "dashboard") {
         const targetDescriptor = action.screen !== undefined ? `"${action.screen}"` : `entity "${action.entity}"`;
-        const filter = target.screen.filter;
-        if (filter === undefined) {
+        const { filter, record, timeRange } = target.screen;
+        const readIds = [filter?.id, record?.param, timeRange?.id].filter((id) => id !== undefined);
+        if (readIds.length === 0) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
                 `params on navigate-target ${targetDescriptor} (dashboard) — target dashboard declares no ` +
-                `filter — params would be a no-op. Remove the params extractor, or add a \`filter\` to the ` +
+                `filter, time range or record binding — params would be a no-op. Remove the params extractor, or add a \`filter\` (or a \`record\` binding) to the ` +
                 `target dashboard so it has somewhere to read the value from.`);
         }
         const extractedKeys = rowFieldExtractorKeys(action.params);
-        if (!extractedKeys.includes(filter.id)) {
+        if (!readIds.some((id) => extractedKeys.includes(id))) {
+            const readDescriptor = filter !== undefined && readIds.length === 1
+                ? `filter id is "${filter.id}"`
+                : `URL params are [${readIds.join(", ")}]`;
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
                 `params [${extractedKeys.join(", ")}] on navigate-target ${targetDescriptor} (dashboard) whose ` +
-                `filter id is "${filter.id}" — none of the extracted keys match, so the filter would stay ` +
-                `unset. Fix the params extractor to produce a "${filter.id}" key, or remove it.`);
+                `${readDescriptor} — none of the extracted keys match, so the value would stay ` +
+                `unset. Fix the params extractor to produce one of these keys, or remove it.`);
         }
-        // skip: filter present and the extractor's keys cover it — valid dashboard deep-link.
+        // skip: a read id is present and the extractor's keys cover it — valid dashboard deep-link.
         return;
     }
     if (!readsNavigateParamsAsFormPrefill(target.screen, action.entityId, screenEntity)) {
@@ -950,6 +954,13 @@ function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandl
         validateFormDerivations(feature.name, screenId, screen);
         validateFormDerivationsEnforced(feature.name, screenId, screen, featureMap);
     }
+    if (screen.type === "actionForm" &&
+        screen.load?.singleton === true &&
+        screen.load.idParam !== undefined) {
+        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both load.singleton: true ` +
+            `and load.idParam — singleton means the query picks the row from the caller's context, so ` +
+            `there is no record id to send under idParam. Remove idParam.`);
+    }
     validateInlineFormNavTargets(feature, screenId, screen, kind, lookups);
 }
 // SecretMintConfirmStep (fw#2838): an optional proof-of-receipt form rendered
@@ -2079,7 +2090,7 @@ function validateDashboardScreen(featureName, screenId, screen, featureMap) {
             validateDashboardScreenPanel(featureName, screenId, panel, featureMap);
         }
         else if (panel.kind === "text") {
-            validateDashboardTextPanel(featureName, screenId, panel);
+            validateDashboardTextPanel(featureName, screenId, panel, featureMap);
         }
         else {
             validateDashboardQueryPanel(featureName, screenId, panel, featureMap);
@@ -2263,7 +2274,7 @@ export function validateDashboardScreenPanel(featureName, screenId, panel, featu
         throw new Error(`${context} fallback "${panel.fallback}" has its own visibleWhen; a fallback must always render.`);
     }
 }
-function validateDashboardTextPanel(featureName, screenId, panel) {
+function validateDashboardTextPanel(featureName, screenId, panel, featureMap) {
     const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) text-panel "${panel.id}"`;
     if (panel.blocks.length === 0) {
         throw new Error(`${context} has an empty blocks list. Add at least one block.`);
@@ -2274,6 +2285,20 @@ function validateDashboardTextPanel(featureName, screenId, panel) {
         if (block.kind === "list" && block.items.length === 0) {
             throw new Error(`${context} has a list block without items. Add items or remove the block.`);
         }
+        if (block.kind === "link")
+            validateDashboardTextLinkBlock(context, block, featureName, featureMap);
+    }
+}
+function validateDashboardTextLinkBlock(context, block, featureName, featureMap) {
+    const targetQn = resolveScreenTargetQn(featureName, block.screen);
+    const [targetFeatureName = "", , targetShortId = ""] = targetQn.split(":");
+    if (featureMap.get(targetFeatureName)?.screens[targetShortId] === undefined) {
+        throw new Error(`${context} link block screen "${block.screen}" does not resolve to a registered screen ` +
+            `(checked "${targetQn}"). Use a same-feature short id or a cross-feature QN "<feature>:screen:<id>".`);
+    }
+    if (block.roles?.length === 0) {
+        throw new Error(`${context} link block "${block.screen}" has an empty roles list, which would hide it from everyone. ` +
+            `List the roles or omit roles.`);
     }
 }
 function validateDashboardPanelVisibleWhen(context, visibleWhen) {

package/dist/engine/extensions/tenant-data.d.ts

@@ -1,9 +1,9 @@
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
-import type { TenantDb } from "../../db/tenant-db.ts";
+import type { ExecutorManagedTenantDb } from "../../db/tenant-db.ts";
 import type { Registry, TenantId } from "../types/index.ts";
 import type { TenantDestroyHookResult } from "./tenant-resource.ts";
 export interface TenantDataHookCtx {
-    readonly db: TenantDb;
+    readonly db: ExecutorManagedTenantDb;
     readonly registry: Registry;
     readonly tenantId: TenantId;
     readonly deadlineAt?: number;

package/dist/engine/feature-ui-extensions.js

@@ -1,6 +1,7 @@
 import { escapeHatchGrantsProblem } from "@cosmicdrift/kumiko-types/handlers";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, } from "@cosmicdrift/kumiko-types/websocket-route";
+import { markExecutorManagedTable } from "../db/executor-managed-tables.js";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
 import { LifecycleHookTypes } from "./constants.js";
 import { resolveName } from "./handler-helpers.js";
@@ -298,6 +299,9 @@ export function buildUiExtensionsMethods(state, name) {
                 throw new Error(`[Feature ${name}] Projection "${definition.name}" already registered. ` +
                     `Projection names must be unique per feature.`);
             }
+            if (typeof definition.table === "object" && definition.table !== null) {
+                markExecutorManagedTable(definition.table);
+            }
             state.projections[definition.name] = definition;
         },
         multiStreamProjection(definition) {

package/dist/engine/projection-helpers.d.ts

@@ -1,7 +1,7 @@
-import type { DbRunner } from "../db/connection.ts";
+import type { ExecutorManagedRunner } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { StoredEvent } from "../event-store/event-store.ts";
 import type { MultiStreamApplyContext } from "../pipeline/multi-stream-apply-context.ts";
 import type { MultiStreamApplyFn, ProjectionTable, SingleStreamApplyFn } from "./types/projection.ts";
-export declare function defineApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: DbRunner, table: ProjectionTable) => Promise<void>): SingleStreamApplyFn;
-export declare function defineMspApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: DbRunner, ctx: MultiStreamApplyContext) => Promise<void>): MultiStreamApplyFn;
+export declare function defineApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, table: ProjectionTable) => Promise<void>): SingleStreamApplyFn;
+export declare function defineMspApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, ctx: MultiStreamApplyContext) => Promise<void>): MultiStreamApplyFn;
 export declare function setFields(table: ProjectionTable, fields: Record<string, unknown> | ((event: Parameters<SingleStreamApplyFn>[0]) => Record<string, unknown>)): SingleStreamApplyFn;

package/dist/engine/registry-state.js

@@ -1,5 +1,6 @@
 import { applyEntityEvent } from "../db/apply-entity-event.js";
 import { assertBackingTableSuperset, deriveEntityTableMeta } from "../db/entity-table-meta.js";
+import { markExecutorManagedTable } from "../db/executor-managed-tables.js";
 import { asEntityTableMeta } from "../db/query.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { qualifyEntityName } from "./qualified-name.js";
@@ -20,6 +21,7 @@ export function buildImplicitProjection(featureName, entityName, entity, qualify
     const drizzleTable = backingTable !== undefined
         ? resolveBackingTable(entityName, entity, backingTable)
         : buildEntityTable(entityName, entity);
+    markExecutorManagedTable(drizzleTable);
     // applyEntityEvent gibt ApplyResult zurück; SingleStreamApplyFn erwartet
     // Promise<void>. Im rebuild-Pfad ist die Row irrelevant — wir discarden.
     const handler = async (event, tx) => {

package/dist/engine/registry-validate.js

@@ -476,8 +476,11 @@ export function validateProjectionApplyKeys(state) {
         //      or `jobRun` (BullMQ-callback-driven lifecycle, no executor).
         //      A "Shape-Anchor"-entity is no longer needed for this case.
         const isEventsOnlySource = !sources.every((src) => state.entityMap.has(src));
+        // An extension source may be a stream whose events the executor writes under a
+        // name that is no registered entity (document-extract); its auto-verbs count.
+        const extensionSources = projDef.extraSources ?? [];
         for (const src of rebuildSources) {
-            if (state.entityMap.has(src)) {
+            if (state.entityMap.has(src) || extensionSources.includes(src)) {
                 for (const verb of ENTITY_LIFECYCLE_VERBS)
                     validEventTypes.add(`${src}.${verb}`);
             }

package/dist/engine/schema-builder.js

@@ -236,12 +236,26 @@ export function fieldToZod(field, currencies, opts = {}) {
             // whether the key may be omitted at all is decided by buildInsertSchema
             // off the same flag. `minItems` overrides that default when set.
             let list = z.array(row);
-            const min = field.minItems ?? (field.required === true ? 1 : undefined);
-            if (min !== undefined)
-                list = list.min(min);
             if (field.maxItems !== undefined)
                 list = list.max(field.maxItems);
-            return list;
+            const min = field.minItems ?? (field.required === true ? 1 : undefined);
+            if (min === undefined)
+                return list;
+            // A custom issue rather than min(): other arrays (multiSelect) share zod's
+            // too_small and must not read "rows"; the bridge honours params.i18nKey.
+            return list.superRefine((rows, ctx) => {
+                // skip: the minimum is met, nothing to report
+                if (rows.length >= min)
+                    return;
+                ctx.addIssue({
+                    code: "custom",
+                    input: rows,
+                    params: {
+                        i18nKey: `errors.validation.list_min_rows.${min === 1 ? "one" : "other"}`,
+                        minimum: min,
+                    },
+                });
+            });
         }
         case "jsonb": {
             // Free-form jsonb — keys sind tenant-/runtime-defined. Validation

package/dist/engine/screen-helpers.d.ts

@@ -1,5 +1,6 @@
 import type { FieldDefinition, SelectFieldDef } from "./types/fields.ts";
 import type { ActionFormScreenDefinition, ConfigEditScreenDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, FieldCondition, FormatSpec, ListColumnSpec, ProjectionDetailScreenDefinition, ScreenDefinition, SecretMintScreenDefinition } from "./types/screen.ts";
+export declare const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
 export declare function explicitListScreenId(screen: ScreenDefinition): string | undefined;
 export declare function resolveNavParentScreen(screens: readonly ScreenDefinition[], detail: ScreenDefinition, getId: (screen: ScreenDefinition) => string): ScreenDefinition | undefined;
 export type EditLayoutScreen = ProjectionDetailScreenDefinition | EntityEditScreenDefinition | ActionFormScreenDefinition | ConfigEditScreenDefinition | SecretMintScreenDefinition;

package/dist/engine/screen-helpers.js

@@ -1,3 +1,6 @@
+// Entity name the renderer gives the synthesized entity of an actionForm, secretMint or confirm
+// step. It is not registered, so nothing server-side may treat it as a real entity.
+export const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
 // Every screen type carrying `listScreenId` declares it identically; centralizing
 // here keeps the switch the only place that grows for a new screen type.
 export function explicitListScreenId(screen) {

package/dist/engine/soft-delete-cleanup.js

@@ -5,16 +5,18 @@
 // true buys an entity restore + trash (ctx.includeDeleted) + this cleanup, with
 // no feature to wire.
 //
-// Hard-deleting the projection row leaves the event stream intact (source of
-// truth) — a full projection rebuild would replay created+deleted and
-// resurrect the row as isDeleted=true. That's acceptable: cleanup bounds LIVE
-// table growth; irreversible event-log purging is data-retention's job
-// (pruneEvents), a separate, consumer-lag-guarded path.
-import { asEntityTableMeta, deleteMany } from "../db/query.js";
+// Each expired row is purged through the executor's forget verb: the `<entity>.forgotten`
+// event replays on a projection rebuild, so the purged row stays gone. The earlier events stay
+// in the log; irreversible event-log purging is data-retention's job (pruneEvents), a separate,
+// consumer-lag-guarded path.
+import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { asEntityTableMeta, selectMany } from "../db/query.js";
 import { hasFieldProperty } from "../db/table-introspection.js";
+import { reraiseAsKumikoError } from "../errors/index.js";
 import { purgeExpiredFileRefsWithBytes } from "../files/purge-expired-file-ref-bytes.js";
 import { FILE_REF_ENTITY_NAME } from "../files/types.js";
-import { SYSTEM_USER_ID } from "./system-user.js";
+import { createSystemUser, SYSTEM_USER_ID } from "./system-user.js";
+import { SYSTEM_TENANT_ID } from "./types/identifiers.js";
 // qualifyEntityName convention (feature:type:kebab-name) with a reserved
 // "soft-delete" owner — no real feature owns these; the framework synthesizes
 // them. The job-runner keys cron scheduling off the name, the config-resolver
@@ -46,6 +48,10 @@ export function isSystemScopedSoftDeleteTable(table, entity) {
 function isGlobalTenancyTable(table) {
     return asEntityTableMeta(table)?.tenancy === "global";
 }
+async function resolveGraceDays(ctx, tenantId, db) {
+    const resolved = await ctx.configResolver?.get(SOFT_DELETE_GRACE_DAYS_KEY, softDeleteGraceDaysConfig, tenantId, SYSTEM_USER_ID, db);
+    return typeof resolved === "number" && resolved >= 1 ? resolved : DEFAULT_GRACE_DAYS;
+}
 export const softDeleteCleanupJob = async (_payload, ctx) => {
     const { db, registry } = ctx;
     if (!db || !registry) {
@@ -61,10 +67,7 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
         // skip: cron fired without a perTenant fan-out tenant — nothing scoped to purge
         return;
     }
-    const resolved = ctx.configResolver
-        ? await ctx.configResolver.get(SOFT_DELETE_GRACE_DAYS_KEY, softDeleteGraceDaysConfig, tenantId, SYSTEM_USER_ID, db)
-        : undefined;
-    const graceDays = typeof resolved === "number" && resolved >= 1 ? resolved : DEFAULT_GRACE_DAYS;
+    const graceDays = await resolveGraceDays(ctx, tenantId, db);
     const cutoff = Temporal.Now.instant().subtract({ hours: graceDays * 24 });
     for (const proj of registry.getAllProjections().values()) {
         if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
@@ -80,23 +83,49 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
         if (isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff }, tenantId };
-        await purgeExpiredRows(db, proj.source, proj.table, where, cutoff, ctx);
+        const executor = createEventStoreExecutor(proj.table, entity, { entityName: proj.source });
+        await purgeExpiredRows({ db, executor, user: ctx.systemUser ?? createSystemUser(tenantId) }, proj.source, proj.table, where, cutoff, ctx);
     }
 };
-async function purgeExpiredRows(db, source, table, where, cutoff, ctx) {
+const PURGE_PAGE_SIZE = 500;
+async function forgetRow(writer, id) {
+    // ponytail: one append per expired row, batch when purge volume needs it
+    const result = await writer.executor.forget({ id }, writer.user, writer.db);
+    if (!result.isSuccess)
+        throw reraiseAsKumikoError(result.error);
+}
+async function purgeExpiredRows(writer, source, table, where, cutoff, ctx, readDb = writer.db) {
     if (source === FILE_REF_ENTITY_NAME) {
         // The row is the only record of the storageKey, so its bytes go first.
-        await purgeExpiredFileRefsWithBytes({
-            db,
+        return await purgeExpiredFileRefsWithBytes({
+            db: writer.db,
             table,
             where,
             expiredBefore: cutoff,
             files: ctx.files,
             log: ctx.log,
+            forgetRow: (id) => forgetRow(writer, id),
         });
     }
-    else {
-        await deleteMany(db, table, where);
+    await forgetExpiredPages(writer, source, table, where, ctx, readDb);
+}
+// Keyset on id: a row whose forget fails is logged and skipped, it must not hide the rows behind it.
+async function forgetExpiredPages(writer, source, table, where, ctx, readDb) {
+    let afterId;
+    for (;;) {
+        const page = await selectMany(readDb, table, { ...where, ...(afterId === undefined ? {} : { id: { gt: afterId } }) }, { orderBy: { col: "id", direction: "asc" }, limit: PURGE_PAGE_SIZE });
+        const last = page[page.length - 1];
+        if (last === undefined)
+            break;
+        for (const row of page) {
+            try {
+                await forgetRow(writer, row.id);
+            }
+            catch (err) {
+                ctx.log?.warn(`[soft-delete-cleanup] ${source} ${row.id} not purged: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        afterId = last.id;
     }
 }
 // System-global soft-deleted entities (tenancy "global" or no tenantId column) can't take a
@@ -119,13 +148,13 @@ export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
         if (!isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff } };
-        if (isGlobalTenancyTable(proj.table)) {
-            // db.global() rejects writes on executor-managed tables; a retention purge has no event to append.
-            await deleteMany(db.unsafeRaw(), proj.table, where);
-        }
-        else {
-            await deleteMany(db, proj.table, where);
-        }
+        const writer = {
+            db,
+            executor: createEventStoreExecutor(proj.table, entity, { entityName: proj.source }),
+            user: ctx.systemUser ?? createSystemUser(SYSTEM_TENANT_ID),
+        };
+        // A global-tenancy table is invisible to a tenant-mode ctx.db, so its candidates are read unscoped.
+        await purgeExpiredRows(writer, proj.source, proj.table, where, cutoff, ctx, isGlobalTenancyTable(proj.table) ? db.unsafeRaw() : db);
     }
 };
 export function buildSoftDeleteCleanupJob() {

package/dist/engine/steps/unsafe-projection-delete.js

@@ -16,6 +16,8 @@
 // must commit in the same TX as the aggregate-mutation that triggered
 // it (stronger consistency than an async projection). Reviewer judges.
 import { deleteMany } from "../../db/query.js";
+import { requireEntityTableMeta } from "../../db/table-introspection.js";
+import { withExecutorManagedWrites } from "../../db/tenant-db.js";
 import { tenantDbWriteRunner } from "../../db/tenant-db-runner.js";
 import { defineStep } from "../define-step.js";
 import { resolveRequired } from "./_resolver-utils.js";
@@ -26,8 +28,8 @@ defineStep({
         const where = resolveRequired(args.where, ctx);
         // The `unsafe*`-step IS the sanctioned direct projection write — it exists
         // to bypass the executor deliberately (boot-validated allowlist + reviewer
-        // gate). The brand-strip cast makes that explicit at the one blessed seam.
-        await deleteMany(tenantDbWriteRunner(ctx.db, "unsafe projection delete"), args.table, where);
+        // gate).
+        await deleteMany(withExecutorManagedWrites(tenantDbWriteRunner(ctx.db, "unsafe projection delete")), requireEntityTableMeta(args.table, "unsafeProjectionDelete"), where);
     },
 });
 export function buildUnsafeProjectionDeleteStep(args) {