@cosmicdrift/kumiko-framework 0.378.0 → 0.379.0

package/dist/db/query.js

@@ -24,6 +24,7 @@ import { InternalError } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/index.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
 import { SQL_EXPR_BRAND } from "./dialect.js";
+import { executorManagedWriteDenied } from "./executor-managed-tables.js";
 import { extractPgError } from "./pg-error.js";
 import { toSnakeCase } from "./table-builder.js";
 import { asEntityTableMeta, requireEntityTableMeta } from "./table-introspection.js";
@@ -987,6 +988,9 @@ export async function insertMany(db, table, rows) {
     if (rows.length === 0)
         return [];
     assertNotTenantScoped(db, "insertMany");
+    const managedDenied = executorManagedWriteDenied(db, table, "insertMany");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     // Use the column-set from the first row; assume all rows share keys.
     const firstRow = rows[0];
@@ -1028,6 +1032,9 @@ export async function insertOne(db, table, values) {
     if (scoped) {
         return scoped.insertOne(table, values);
     }
+    const managedDenied = executorManagedWriteDenied(db, table, "insertOne");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const entries = Object.entries(values)
         .filter(([k]) => info.hasColumn(k))
@@ -1064,6 +1071,9 @@ export async function updateMany(db, table, set, where) {
     if (scoped) {
         return scoped.updateMany(table, set, where);
     }
+    const managedDenied = executorManagedWriteDenied(db, table, "updateMany");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const setEntries = Object.entries(set).map(([k, v]) => {
         const col = info.columnOf(k);
@@ -1103,6 +1113,9 @@ export async function deleteMany(db, table, where) {
     if (scoped) {
         return scoped.deleteMany(table, where);
     }
+    const managedDenied = executorManagedWriteDenied(db, table, "deleteMany");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const w = buildWhereClause(info, where, 1);
     let sqlText = `DELETE FROM ${quoteIdent(info.name)}`;
@@ -1280,6 +1293,9 @@ export async function aggregateWhere(db, table, spec, where = {}) {
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function upsertOnConflict(db, table, values, options) {
     assertNotTenantScoped(db, "upsertOnConflict");
+    const managedDenied = executorManagedWriteDenied(db, table, "upsertOnConflict");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const entries = insertEntries(info, values);
     const conflictCols = resolveConflictColumns(table, info, options.conflictKeys);
@@ -1323,6 +1339,9 @@ export async function upsertOnConflict(db, table, values, options) {
 }
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function upsertByPk(db, table, values, updateOnConflict) {
+    const managedDenied = executorManagedWriteDenied(db, table, "upsertByPk");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const conflictKeys = resolveConflictColumns(table, info, undefined);
     const fieldKeys = conflictKeys.map((col) => info.fieldOf(col));
@@ -1334,6 +1353,9 @@ export async function upsertByPk(db, table, values, updateOnConflict) {
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function insertOnConflictDoNothing(db, table, values, options) {
     assertNotTenantScoped(db, "insertOnConflictDoNothing");
+    const managedDenied = executorManagedWriteDenied(db, table, "insertOnConflictDoNothing");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const entries = insertEntries(info, values);
     const conflictCols = resolveConflictColumns(table, info, options?.conflictKeys);
@@ -1352,6 +1374,9 @@ export async function insertOnConflictDoNothing(db, table, values, options) {
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function incrementCounter(db, table, values, increments, options = {}) {
     assertNotTenantScoped(db, "incrementCounter");
+    const managedDenied = executorManagedWriteDenied(db, table, "incrementCounter");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const entries = insertEntries(info, values);
     const conflictCols = resolveConflictColumns(table, info, options.conflictKeys);
@@ -1402,6 +1427,9 @@ export async function incrementCounter(db, table, values, increments, options =
     return coerceRow(first, info);
 }
 export async function deleteManyBatched(db, table, where, options) {
+    const managedDenied = executorManagedWriteDenied(db, table, "deleteManyBatched");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const w = buildWhereClause(info, where, 1);
     if (!w.sqlText) {

package/dist/db/reference-data.d.ts

@@ -1,14 +1,15 @@
+import type { Registry } from "../engine/index.ts";
 import type { ReferenceDataDef } from "../engine/types/index.ts";
 import type { DbConnection } from "./connection.ts";
-import type { TableColumns } from "./dialect.ts";
-type Table = TableColumns<any>;
 /**
  * Seed reference data at boot time.
  * For each ReferenceDataDef: upsert rows (insert missing, update changed, never delete).
  * Upsert key defaults to the first field in the data object.
+ *
+ * Rows go through the entity's event-store executor as the system user in the
+ * SYSTEM_TENANT_ID stream, so the seed is replayable on a projection rebuild.
  */
-export declare function seedReferenceData(defs: readonly ReferenceDataDef[], tables: ReadonlyMap<string, Table>, db: DbConnection): Promise<{
+export declare function seedReferenceData(defs: readonly ReferenceDataDef[], registry: Registry, db: DbConnection): Promise<{
     inserted: number;
     updated: number;
 }>;
-export {};

package/dist/db/reference-data.js

@@ -1,21 +1,26 @@
-import { fetchOne, insertOne, updateMany } from "../db/query.js";
+import { fetchOne } from "../db/query.js";
+import { createSystemUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
-import { tableColumnsOf } from "./table-introspection.js";
-function hasColumn(table, field) {
-    const cols = tableColumnsOf(table);
-    return cols !== undefined && field in cols;
-}
+import { reraiseAsKumikoError } from "../errors/index.js";
+import { entityTableFromRegistry } from "./entity-table-from-registry.js";
+import { createEventStoreExecutor } from "./event-store-executor.js";
+import { createTenantDb } from "./tenant-db.js";
 /**
  * Seed reference data at boot time.
  * For each ReferenceDataDef: upsert rows (insert missing, update changed, never delete).
  * Upsert key defaults to the first field in the data object.
+ *
+ * Rows go through the entity's event-store executor as the system user in the
+ * SYSTEM_TENANT_ID stream, so the seed is replayable on a projection rebuild.
  */
-export async function seedReferenceData(defs, tables, db) {
+export async function seedReferenceData(defs, registry, db) {
     let inserted = 0;
     let updated = 0;
+    const by = createSystemUser(SYSTEM_TENANT_ID);
+    const tdb = createTenantDb({ db, tenantId: SYSTEM_TENANT_ID, mode: "system" });
     for (const def of defs) {
-        const table = tables.get(def.entityName);
-        if (!table)
+        const entity = registry.getEntity(def.entityName);
+        if (!entity)
             continue;
         if (def.data.length === 0)
             continue;
@@ -26,11 +31,13 @@ export async function seedReferenceData(defs, tables, db) {
         if (!firstKey)
             continue;
         const upsertKey = def.upsertKey ?? firstKey;
+        const table = entityTableFromRegistry(registry, def.entityName, entity);
+        const executor = createEventStoreExecutor(table, entity, { entityName: def.entityName });
         for (const row of def.data) {
             const keyValue = row[upsertKey];
             if (keyValue === undefined)
                 continue;
-            const existing = (await fetchOne(db, table, { [upsertKey]: keyValue }));
+            const existing = await fetchOne(db, table, { [upsertKey]: keyValue });
             if (existing) {
                 const changes = {};
                 for (const [field, value] of Object.entries(row)) {
@@ -41,21 +48,16 @@ export async function seedReferenceData(defs, tables, db) {
                     }
                 }
                 if (Object.keys(changes).length > 0) {
-                    await updateMany(db, table, changes, { [upsertKey]: keyValue });
+                    const result = await executor.update({ id: existing.id, version: existing.version, changes }, by, tdb);
+                    if (!result.isSuccess)
+                        throw reraiseAsKumikoError(result.error);
                     updated++;
                 }
             }
             else {
-                // Only add framework columns if the table actually has them.
-                // Drizzle used to filter extra fields silently; bunInsertOne doesn't.
-                const values = { ...row };
-                if (hasColumn(table, "tenantId"))
-                    values["tenantId"] = SYSTEM_TENANT_ID;
-                if (hasColumn(table, "version"))
-                    values["version"] = 1;
-                if (hasColumn(table, "insertedAt"))
-                    values["insertedAt"] = Temporal.Now.instant();
-                await insertOne(db, table, values);
+                const result = await executor.create({ ...row, tenantId: SYSTEM_TENANT_ID }, by, tdb);
+                if (!result.isSuccess)
+                    throw reraiseAsKumikoError(result.error);
                 inserted++;
             }
         }

package/dist/db/table-builder.js

@@ -1,6 +1,7 @@
 import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { toSnakeCase } from "../utils/case.js";
 import { assertUnreachable } from "../utils/index.js";
+import { markExecutorManagedTable } from "./executor-managed-tables.js";
 import { columnHandleName } from "./table-introspection.js";
 export { toSnakeCase } from "../utils/case.js";
 import { bigint, boolean, decimalColumn, doublePrecision, index, instant, integer, isSqlExpression, jsonb, moneyAmount, table as pgTable, plainDate, serial, sql, text, uniqueIndex, uuid, } from "./dialect.js";
@@ -420,5 +421,6 @@ export function buildEntityTable(entityName, entity, options) {
         return indexes;
     });
     stampEntityTableMeta(built, entity);
+    markExecutorManagedTable(built);
     return built;
 }

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

@@ -1,6 +1,8 @@
 import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { InternalError } from "../errors/index.ts";
 import type { DbRunner } from "./connection.ts";
+export declare function isBoundTenantDb(value: unknown): value is TenantDb;
+export declare function isDbRunner(value: unknown): value is DbRunner;
 export declare function bindTenantDbRunner(tenantDb: TenantDb, runner: DbRunner): void;
 export declare function tenantDbRunner(tenantDb: TenantDb): DbRunner;
 export declare function denyTenantDbWrites(tenantDb: TenantDb, reason: string): void;

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

@@ -1,5 +1,12 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { InternalError } from "../errors/index.js";
 const tenantDbRunners = new WeakMap();
+export function isBoundTenantDb(value) {
+    return typeof value === "object" && value !== null && tenantDbRunners.has(value);
+}
+export function isDbRunner(value) {
+    return typeof propertyOf(value, "unsafe") === "function";
+}
 export function bindTenantDbRunner(tenantDb, runner) {
     tenantDbRunners.set(tenantDb, runner);
 }

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

@@ -11,6 +11,8 @@ import type { DbRunner } from "./connection.ts";
 import { tableNameOf } from "./table-introspection.ts";
 type Table = SchemaTable;
 export { SYSTEM_SCOPE_CHECK_BRAND, type TenantDb, type TenantDbMode, type UncheckedSystemDb, } from "@cosmicdrift/kumiko-types/tenant-db-types";
+export declare function withExecutorManagedWrites(runner: DbRunner): DbRunner;
+export declare function withoutExecutorManagedWrites(runner: DbRunner): DbRunner;
 export declare function assertPersonalDataWrite(db: TenantDb, tableName: string, keys: readonly string[], entity: EntityDefinition): void;
 export declare function unsafeRawForDeclaredStep(holder: TenantDb | UncheckedSystemDb, reason: string): DbRunner;
 export declare function withSystemDbUnsafeRawGrant(systemDb: UncheckedSystemDb, grant: EscapeHatchDeclaration | undefined, deniedCallerLabel: string): UncheckedSystemDb;
@@ -54,5 +56,6 @@ export type CreateTenantDbOptions = {
     readonly grants?: TenantDbGrants;
 };
 export declare function createTenantDb(options: CreateTenantDbOptions): TenantDb;
+export declare function createTenantDataDestroyDb(options: Omit<CreateTenantDbOptions, "mode">): TenantDb;
 export declare function createProjectingTenantDb(db: DbRunner, tenantId: TenantId, projectionRegistry: Registry | undefined): TenantDb;
 export { asRawClient };

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 { executorManagedWriteDenied, 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,30 @@ 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 (capableRunnerInners.has(runner))
+        return runner;
+    const cached = capableRunnerByInner.get(runner);
+    if (cached)
+        return cached;
+    const capable = boundRunner(runner, runnerPersonalDataGates.get(runner), projectionRegistryOf(runner), true);
+    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 +158,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 +351,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 buildTenantDb({ ...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 +452,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);
@@ -485,7 +505,7 @@ 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)
@@ -496,7 +516,7 @@ function buildTenantDb(options) {
             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)
@@ -510,7 +530,7 @@ function buildTenantDb(options) {
             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) {
@@ -537,7 +557,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 +579,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,6 +601,9 @@ 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));
         },
@@ -594,6 +620,9 @@ 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));
         },
@@ -607,6 +636,9 @@ 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));
         },

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/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/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