@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/db/tenant-db.js

@@ -10,7 +10,8 @@ import { bindProjectionRegistry, projectionRegistryOf } from "./projection-regis
 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";
+import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, tenantDbWritesDeniedReason, } from "./tenant-db-runner.js";
+import { upsertTableDenied, upsertTenantRow } from "./tenant-db-upsert.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 const declaredUnsafeRawRunners = new WeakMap();
 // The CRUD executor writes through tenantDbRunner, not insertOne, so it asks the
@@ -36,7 +37,7 @@ function boundRunner(runner, gate, projectionRegistry, executorManagedWrites) {
             if (typeof value !== "function")
                 return value;
             if (prop === "reserve") {
-                // postgres-js hands back a raw connection; re-wrap it so the gate survives.
+                // The driver hands 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, executorManagedWrites);
@@ -105,9 +106,7 @@ export function assertPersonalDataWrite(db, tableName, keys, entity) {
 }
 // Framework-private (not re-exported from db/index.ts): same grant check + audit as unsafeRaw, for engine forwarding.
 export function unsafeRawForDeclaredStep(holder, reason) {
-    if (reason.trim().length === 0) {
-        throw new Error("unsafeRawForDeclaredStep requires a non-empty reason");
-    }
+    assertReason("unsafeRawForDeclaredStep", reason);
     const runner = declaredUnsafeRawRunners.get(holder);
     if (!runner) {
         throw new InternalError({
@@ -257,7 +256,13 @@ export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEs
 // same connection/transaction. For code that must run caller-supplied callbacks (e.g. config
 // validators) without handing them a cross-tenant view.
 export function scopeTenantDbToTenant(db, tenantId) {
-    return createTenantDb({ db: tenantDbRunner(db), tenantId, mode: "tenant" });
+    const writesDeniedReason = tenantDbWritesDeniedReason(db);
+    return createTenantDb({
+        db: tenantDbRunner(db),
+        tenantId,
+        mode: "tenant",
+        ...(writesDeniedReason !== undefined && { grants: { writesDeniedReason } }),
+    });
 }
 // @cast-boundary tenant-db-row
 export function castTenantRows(rows) {
@@ -268,6 +273,18 @@ export { tableNameOf };
 function hasGrant(decl) {
     return decl !== undefined && decl.reason.trim().length > 0;
 }
+// Tenant ids left over when the caller excludes some via ne/notIn; undefined for other operator forms.
+function tenantIdsAfterExclusion(requested, allowed) {
+    if (!isPlainObject(requested))
+        return undefined;
+    if ("ne" in requested)
+        return allowed.filter((t) => t !== requested["ne"]);
+    if (Array.isArray(requested["notIn"])) {
+        const excluded = requested["notIn"];
+        return allowed.filter((t) => !excluded.includes(t));
+    }
+    return undefined;
+}
 // Tenant ids a where.tenantId filter asks for; undefined for operator forms
 // that cannot narrow to a tenant list (ne, like, ...).
 export function requestedTenantIds(requested) {
@@ -429,7 +446,13 @@ function buildTenantDb(options) {
         const allowed = [tenantId, SYSTEM_TENANT_ID];
         const requested = where?.["tenantId"];
         if (requested !== undefined) {
-            const requestedList = requestedTenantIds(requested) ?? [];
+            const requestedList = requestedTenantIds(requested);
+            // An explicit exclusion or empty list must keep excluding, never widen to the full scope.
+            if (requestedList === undefined) {
+                return { ...where, tenantId: tenantIdsAfterExclusion(requested, allowed) ?? allowed };
+            }
+            if (requestedList.length === 0)
+                return { ...where, tenantId: [] };
             const narrowed = requestedList.filter((t) => typeof t === "string" && allowed.includes(t));
             return { ...where, tenantId: narrowed.length > 0 ? narrowed : allowed };
         }
@@ -464,6 +487,14 @@ function buildTenantDb(options) {
     function globalWriteReason() {
         return grants?.globalWrites?.reason ?? "";
     }
+    // The table is the audit target: process-level dedup would otherwise collapse a cron's
+    // writes to several global tables into one audit entry.
+    function reportGlobalWrite(table) {
+        report("global-write", globalWriteReason(), {
+            id: tableNameOf(table),
+            tenantId: tenantId ?? SYSTEM_TENANT_ID,
+        });
+    }
     function personalDataDenied(table, keys) {
         if (!personalDataGate)
             return undefined;
@@ -535,7 +566,7 @@ function buildTenantDb(options) {
                     personalDataDenied(table, Object.keys(values));
                 if (denied)
                     return Promise.reject(denied);
-                report("global-write", globalWriteReason());
+                reportGlobalWrite(table);
                 return withDbSpan("insert", table, async () => insertRow(table, values));
             },
             updateMany(set, where) {
@@ -549,7 +580,7 @@ function buildTenantDb(options) {
                 if (!where || Object.keys(where).length === 0) {
                     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());
+                reportGlobalWrite(table);
                 return withDbSpan("update", table, async () => updateRows(table, set, where));
             },
             deleteMany(where) {
@@ -561,7 +592,7 @@ function buildTenantDb(options) {
                 if (!where || Object.keys(where).length === 0) {
                     return Promise.reject(new Error("db.global().deleteMany without where would mass-delete every tenant's rows. Pass at least one where condition."));
                 }
-                report("global-write", globalWriteReason());
+                reportGlobalWrite(table);
                 return withDbSpan("delete", table, async () => {
                     await deleteRows(table, where);
                 });
@@ -632,6 +663,15 @@ function buildTenantDb(options) {
             const data = insertValues(table, values);
             return withDbSpan("insert", table, async () => insertRow(table, data));
         },
+        upsert(table, values, options) {
+            const denied = writesDenied("ctx.db.upsert") ??
+                upsertTableDenied(table, mode) ??
+                personalDataDenied(table, [...Object.keys(values), ...Object.keys(options.update ?? {})]);
+            if (denied)
+                return Promise.reject(denied);
+            const data = insertValues(table, values);
+            return withDbSpan("insert", table, () => upsertTenantRow(db, table, data, options));
+        },
         updateMany(table, set, where) {
             const writeDenied = writesDenied("ctx.db.updateMany");
             if (writeDenied)

package/dist/db/where-clause.d.ts

@@ -0,0 +1,6 @@
+import type { WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
+import type { TableInfo } from "./table-info.ts";
+export declare function buildWhereClause(info: TableInfo, where: WhereObject, startIndex: number, qualifier?: string): {
+    sqlText: string;
+    values: unknown[];
+};

package/dist/db/where-clause.js

@@ -0,0 +1,236 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
+import { quoteIdent } from "../crypto/ciphertext-pattern.js";
+import { prepareJsonbValue, prepareValue } from "./driver-value-preparation.js";
+function isJsonTextMatchList(value) {
+    return Array.isArray(value);
+}
+function isWhereOperator(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return false;
+    // Don't false-positive on Date / Temporal / other domain-objects.
+    // WhereOperator is plain object literal with at most these keys.
+    const keys = Object.keys(v);
+    if (keys.length === 0)
+        return false;
+    return keys.every((key) => Object.hasOwn(OPERATOR_EMITTERS, key));
+}
+function isJsonbScalar(value) {
+    return value !== null && typeof value !== "object";
+}
+function valueList(target, values) {
+    return values
+        .map((v) => {
+        const p = prepareValue(v, target.pgType);
+        return p.kind === "literal" ? p.literal : `${target.bind(p.bound)}${p.sql}`;
+    })
+        .join(", ");
+}
+// multiSelect (and any other jsonb-array-of-scalars column) stores an
+// array — a filter value is one option, not the whole array, so eq/ne/in
+// must check array containment (`@>`) instead of scalar `=`/`<>`/`IN`
+// against the jsonb column, which Postgres rejects outright.
+// Mirrors applyMultiSelectFilter in event-store-executor-read-filter.ts — keep in lock-step.
+function jsonbContainsAny(target, candidates) {
+    const { column, ref, bind } = target;
+    if (candidates.length === 0)
+        return "FALSE";
+    const parts = [];
+    for (const v of candidates) {
+        const p = prepareJsonbValue([v]);
+        // prepareJsonbValue never returns kind:"literal" (only prepareValue's
+        // isSqlExpression branch does) — narrow anyway, PreparedValue is a union.
+        if (p && p.kind === "param") {
+            parts.push(`${ref(column)} @> ${bind(p.bound)}${p.sql}`);
+        }
+        // A jsonb column holding the scalar itself is never `@>` an array of it.
+        if (isJsonbScalar(v)) {
+            parts.push(`${ref(column)} = ${bind(JSON.stringify(v))}::text::jsonb`);
+        }
+    }
+    return parts.length > 0 ? `(${parts.join(" OR ")})` : "FALSE";
+}
+function isValidJsonTextMatch(match) {
+    if (match === null || typeof match !== "object")
+        return false;
+    const keys = propertyOf(match, "keys");
+    return (Array.isArray(keys) &&
+        keys.length > 0 &&
+        keys.every((k) => typeof k === "string") &&
+        typeof propertyOf(match, "eq") === "string");
+}
+function jsonTextMatchCondition(target, match) {
+    const { column, ref, bind } = target;
+    if (!isValidJsonTextMatch(match)) {
+        throw new Error(`where: jsonText on column "${column}" needs non-empty string keys and a string eq`);
+    }
+    const lookups = match.keys.map((key) => `${ref(column)}->>${bind(key)}::text`);
+    const lhs = lookups.length === 1 ? lookups[0] : `COALESCE(${lookups.join(", ")})`;
+    return `(${lhs} = ${bind(match.eq)})`;
+}
+function emitJsonText(target, operator) {
+    const { column, pgType } = target;
+    const operand = operator.jsonText;
+    if (operand === undefined)
+        return undefined;
+    if (Object.keys(operator).length > 1) {
+        throw new Error(`where: jsonText on column "${column}" cannot be combined with other operators`);
+    }
+    if (pgType !== "jsonb") {
+        throw new Error(`where: jsonText requires a jsonb column, "${column}" is ${pgType}`);
+    }
+    const matches = isJsonTextMatchList(operand) ? operand : [operand];
+    if (matches.length === 0)
+        return "FALSE";
+    return matches.map((match) => jsonTextMatchCondition(target, match)).join(" AND ");
+}
+function comparisonCondition(target, symbol, operand) {
+    const { column, pgType, ref, bind } = target;
+    const p = prepareValue(operand, pgType);
+    return p.kind === "literal"
+        ? `${ref(column)} ${symbol} ${p.literal}`
+        : `${ref(column)} ${symbol} ${bind(p.bound)}${p.sql}`;
+}
+function comparisonEmitter(key, symbol) {
+    return (target, operator) => {
+        const operand = operator[key];
+        if (operand === undefined)
+            return undefined;
+        // Mirrors applyMultiSelectFilter: ordering/pattern ops have no meaning on a jsonb
+        // option array (`like` would crash as `jsonb ~~ jsonb`), so match nothing.
+        if (target.pgType === "jsonb")
+            return "FALSE";
+        return comparisonCondition(target, symbol, operand);
+    };
+}
+// Mirrors applyMultiSelectFilter: an array `ne` means "does not contain all of these".
+function jsonbNotEqualCondition(target, operand) {
+    const { column, ref, bind } = target;
+    if (Array.isArray(operand)) {
+        if (operand.length === 0)
+            return "FALSE";
+        const p = prepareJsonbValue(operand);
+        if (p && p.kind === "param") {
+            return `(${ref(column)} IS NULL OR NOT (${ref(column)} @> ${bind(p.bound)}${p.sql}))`;
+        }
+    }
+    if (isJsonbScalar(operand)) {
+        const p = prepareJsonbValue([operand]);
+        if (p && p.kind === "param") {
+            return `(${ref(column)} IS NULL OR NOT (${ref(column)} @> ${bind(p.bound)}${p.sql} OR ${ref(column)} = ${bind(JSON.stringify(operand))}::text::jsonb))`;
+        }
+    }
+    return undefined;
+}
+function emitNotEqual(target, operator) {
+    const operand = operator.ne;
+    if (operand === undefined)
+        return undefined;
+    if (operand === null && Object.keys(operator).length === 1) {
+        return `${target.ref(target.column)} IS NOT NULL`;
+    }
+    if (target.pgType === "jsonb") {
+        const jsonbCondition = jsonbNotEqualCondition(target, operand);
+        if (jsonbCondition !== undefined)
+            return jsonbCondition;
+    }
+    return comparisonCondition(target, "<>", operand);
+}
+function emitIn(target, operator) {
+    const operand = operator.in;
+    if (!Array.isArray(operand))
+        return undefined;
+    if (target.pgType === "jsonb")
+        return jsonbContainsAny(target, operand);
+    if (operand.length === 0)
+        return "FALSE";
+    return `${target.ref(target.column)} IN (${valueList(target, operand)})`;
+}
+function emitNotIn(target, operator) {
+    const operand = operator.notIn;
+    if (!Array.isArray(operand))
+        return undefined;
+    if (target.pgType === "jsonb") {
+        throw new Error(`where: notIn is not supported on jsonb column "${target.column}"`);
+    }
+    if (operand.length === 0)
+        return "TRUE";
+    return `${target.ref(target.column)} NOT IN (${valueList(target, operand)})`;
+}
+// Insertion order is the SQL emission order. jsonText comes first so its "cannot be combined" error wins over any other
+// operator's error; the rest keep the historical order gt, gte, lt, lte, ne, like, in, notIn.
+const OPERATOR_EMITTERS = {
+    jsonText: emitJsonText,
+    gt: comparisonEmitter("gt", ">"),
+    gte: comparisonEmitter("gte", ">="),
+    lt: comparisonEmitter("lt", "<"),
+    lte: comparisonEmitter("lte", "<="),
+    ne: emitNotEqual,
+    like: comparisonEmitter("like", "LIKE"),
+    in: emitIn,
+    notIn: emitNotIn,
+};
+function operatorConditions(target, operator) {
+    const conditions = [];
+    for (const emit of Object.values(OPERATOR_EMITTERS)) {
+        const condition = emit(target, operator);
+        if (condition !== undefined)
+            conditions.push(condition);
+    }
+    return conditions;
+}
+// Blind-index OR rewrite: if the column has a bidx
+// counterpart (suffix convention `<col>_bidx`, framework-reserved)
+// and a key is configured, equality matches both arms —
+// plaintext legacy rows via the plaintext arm, encrypted rows
+// via the HMAC. The `kumiko-pii:` prefix on ciphertexts makes
+// a random match on the plaintext arm practically impossible.
+function equalityCondition(target, value) {
+    const { info, column, pgType, ref, bind } = target;
+    const p = prepareValue(value, pgType);
+    if (p.kind === "literal")
+        return `${ref(column)} = ${p.literal}`;
+    const bidxKey = configuredBlindIndexKey();
+    const bidxCol = `${column}_bidx`;
+    if (bidxKey !== undefined &&
+        typeof value === "string" &&
+        !column.endsWith("_bidx") &&
+        info.hasColumn(bidxCol)) {
+        return `(${ref(column)} = ${bind(p.bound)} OR ${ref(bidxCol)} = ${bind(computeBlindIndex(bidxKey, value))})`;
+    }
+    return `${ref(column)} = ${bind(p.bound)}${p.sql}`;
+}
+function arrayCondition(target, values) {
+    if (values.length === 0)
+        return "FALSE";
+    if (target.pgType === "jsonb")
+        return jsonbContainsAny(target, values);
+    return `${target.ref(target.column)} IN (${valueList(target, values)})`;
+}
+function conditionsForValue(target, value) {
+    if (value === null)
+        return [`${target.ref(target.column)} IS NULL`];
+    if (Array.isArray(value))
+        return [arrayCondition(target, value)];
+    if (isWhereOperator(value))
+        return operatorConditions(target, value);
+    if (target.pgType === "jsonb" && isJsonbScalar(value)) {
+        return [jsonbContainsAny(target, [value])];
+    }
+    return [equalityCondition(target, value)];
+}
+export function buildWhereClause(info, where, startIndex, qualifier) {
+    const values = [];
+    // Single place that renders a column reference, so a join qualifier reaches
+    // every arm (blind index, jsonb containment, IS NULL, jsonText) alike.
+    const ref = (column) => qualifier === undefined ? quoteIdent(column) : `${quoteIdent(qualifier)}.${quoteIdent(column)}`;
+    const bind = (value) => {
+        values.push(value);
+        return `$${startIndex + values.length - 1}`;
+    };
+    const conditions = Object.entries(where).flatMap(([field, value]) => {
+        const column = info.columnOf(field);
+        return conditionsForValue({ info, column, pgType: info.pgTypeOf(column), ref, bind }, value);
+    });
+    return { sqlText: conditions.join(" AND "), values };
+}

package/dist/derivatives/delete-stored-file.js

@@ -56,6 +56,7 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
         ...(await listDerivativeKeys(originalKey, store, errorContext)),
     ];
     const failedKeys = [];
+    const log = createFallbackLogger(errorContext);
     for (const key of keysToDelete) {
         try {
             assertSafeStorageKey(key);
@@ -63,7 +64,7 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
         }
         catch (err) {
             failedKeys.push(key);
-            createFallbackLogger(errorContext).warn("storage delete failed", {
+            log.warn("storage delete failed", {
                 key,
                 error: err instanceof Error ? err.message : String(err),
             });

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

@@ -13,7 +13,7 @@ export function validateFeatureBootChecks(features) {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}. Fix the condition this check reports.`);
+                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
             }
         }
     }

package/dist/engine/boot-validator/bundled-lists-table.d.ts

@@ -0,0 +1,2 @@
+export declare const BUNDLED_LISTS_OPTION_KEYS: readonly ["table", "pinFirstColumn"];
+export declare function validateBundledListsOptions(options: unknown): void;

package/dist/engine/boot-validator/bundled-lists-table.js

@@ -0,0 +1,36 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { LIST_TABLE_OPTION_KEYS } from "../types/screen.js";
+import { validateListTableOptions } from "./list-table-options.js";
+export const BUNDLED_LISTS_OPTION_KEYS = ["table", "pinFirstColumn"];
+// grouping and totals name fields of one list, so they cannot be shared across lists
+const SCREEN_ONLY_TABLE_KEYS = ["grouping", "totals"];
+export function validateBundledListsOptions(options) {
+    if (!isPlainObject(options)) {
+        throw new Error("bundledLists must be an object like { table: { columnPicker: true } }.");
+    }
+    const unknownKeys = Object.keys(options).filter((key) => !BUNDLED_LISTS_OPTION_KEYS.some((allowed) => allowed === key));
+    if (unknownKeys.length > 0) {
+        throw new Error(`bundledLists has unknown key(s) ${unknownKeys.map((k) => `"${k}"`).join(", ")}. ` +
+            `Allowed keys: ${BUNDLED_LISTS_OPTION_KEYS.join(", ")}.`);
+    }
+    const table = options["table"];
+    if (!isPlainObject(table)) {
+        const allowed = LIST_TABLE_OPTION_KEYS.filter((key) => !SCREEN_ONLY_TABLE_KEYS.some((screenOnly) => screenOnly === key));
+        throw new Error(`bundledLists.table must be an object like { columnPicker: true }. ` +
+            `Allowed keys: ${allowed.join(", ")}.`);
+    }
+    for (const key of SCREEN_ONLY_TABLE_KEYS) {
+        if (table[key] !== undefined) {
+            throw new Error(`bundledLists.table.${key} is not allowed: ${key} depends on the fields of one list. ` +
+                `Set it in the table block of that screen.`);
+        }
+    }
+    validateListTableOptions("bundledLists", table, [], true);
+    const pinFirstColumn = options["pinFirstColumn"];
+    if (pinFirstColumn !== undefined && typeof pinFirstColumn !== "boolean") {
+        throw new Error("bundledLists.pinFirstColumn must be a boolean.");
+    }
+    if (pinFirstColumn === true && table["pinning"] !== true) {
+        throw new Error("bundledLists.pinFirstColumn needs bundledLists.table.pinning: true.");
+    }
+}

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

@@ -1,8 +1,8 @@
 import { qualifyEntityName } from "../qualified-name.js";
-import { findEntityFeature } from "./screens.js";
+import { findEntityFeature } from "./screens-kind-shared.js";
 // Entity name → the one screen that declares detailFor: "<entity>". Built
 // once, up front (before the per-feature validateScreens loop) so both this
-// module's own uniqueness check AND rowAction entity-targets (in screens.ts)
+// module's own uniqueness check AND rowAction entity-targets (in screens-actions.ts)
 // resolve against the same map instead of re-walking every feature's
 // screens twice.
 export function collectDetailForScreens(features, featureMap) {

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -9,6 +9,7 @@ export declare function validateHandlerAccess(feature: FeatureDefinition): void;
 export declare function validateAdditionalRateLimits(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validatePerCommandTransaction(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateTenantlessAnonymous(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
+export declare function validateRateLimitCost(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateRateLimitDisabledReason(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
 export declare function validateRateLimitBucketList(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
 export declare function validateNoAllRoleInHandlerAccess(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>): void;

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

@@ -139,6 +139,7 @@ export function validateHandlerAccess(feature) {
     for (const [name, handler] of Object.entries(feature.writeHandlers)) {
         validateTenantlessAnonymous(feature.name, name, handler);
         validateAdditionalRateLimits(feature.name, name, handler);
+        validateRateLimitCost(feature.name, name, handler);
         validatePerCommandTransaction(feature.name, name, handler);
     }
 }
@@ -235,6 +236,22 @@ export function validateTenantlessAnonymous(featureName, handlerName, handler) {
             `tenant/user bucket, so one caller could exhaust it for all. Use ${IP_SCOPED_RATE_LIMIT_PER.map((allowed) => `"${allowed}"`).join(" or ")}.`);
     }
 }
+export function validateRateLimitCost(featureName, handlerName, handler) {
+    // skip: no payload-derived cost declared
+    if (!handler.rateLimitCost)
+        return;
+    if (handler.rateLimit === undefined || isRateLimitDisabled(handler.rateLimit)) {
+        throw new Error(`write handler "${featureName}:write:${handlerName}" declares rateLimitCost without an active rateLimit — ` +
+            `the cost is booked on the rateLimit buckets, so declare rateLimit or drop rateLimitCost.`);
+    }
+    const isAnonymous = "roles" in handler.access && handler.access.roles.includes("anonymous");
+    const hasIpBucket = declaredRateLimitOptions(handler.rateLimit).some(({ per }) => IP_SCOPED_RATE_LIMIT_PER.includes(per));
+    if (isAnonymous || hasIpBucket) {
+        throw new Error(`write handler "${featureName}:write:${handlerName}" declares rateLimitCost on an anonymous or ip-limited handler — ` +
+            `rateLimitCost books after the parse, so such a handler would lose its pre-parse protection against junk floods. ` +
+            `Bulk handlers are authenticated: use a user/tenant bucket and drop "anonymous", or drop rateLimitCost.`);
+    }
+}
 export function validateRateLimitDisabledReason(featureName, kind, handlerName, rateLimit) {
     // skip: rate limit isn't disabled, so no reason is required
     if (!isRateLimitDisabled(rateLimit))

package/dist/engine/boot-validator/entity-list-aggregate-options.d.ts

@@ -0,0 +1,3 @@
+import type { EntityDefinition } from "../types/index.ts";
+import type { EntityListScreenDefinition } from "../types/screen.ts";
+export declare function validateEntityListAggregateOptions(where: string, screen: EntityListScreenDefinition, entity: EntityDefinition): void;

package/dist/engine/boot-validator/entity-list-aggregate-options.js

@@ -0,0 +1,23 @@
+import { isListFilterAllowed } from "../../db/entity-field-encryption.js";
+import { isFieldFilterable } from "../screen-filter-ops.js";
+import { entityAggregateFieldLookup, validateListTableAggregateFieldTypes, } from "./list-table-aggregate-options.js";
+const RANGE_FACET_TYPES = ["number", "decimal", "money", "bigInt"];
+function validateRangeFacets(where, facets, entity) {
+    for (const [field, config] of Object.entries(facets ?? {})) {
+        if (config === false || config.display !== "range")
+            continue;
+        const def = Object.hasOwn(entity.fields, field) ? entity.fields[field] : undefined;
+        if (def === undefined || !RANGE_FACET_TYPES.includes(def.type)) {
+            throw new Error(`${where} facets.${field}: display "range" needs a number, decimal, money or bigInt field.`);
+        }
+        if (!isFieldFilterable(def) || !isListFilterAllowed(entity, field, { op: "gte", value: 0 })) {
+            throw new Error(`${where} facets.${field}: display "range" needs filterable: true on a field that is not encrypted, personal or secret.`);
+        }
+    }
+}
+export function validateEntityListAggregateOptions(where, screen, entity) {
+    if (screen.table !== undefined) {
+        validateListTableAggregateFieldTypes(where, screen.table, entityAggregateFieldLookup(entity), true);
+    }
+    validateRangeFacets(where, screen.facets, entity);
+}

package/dist/engine/boot-validator/form-derivations.js

@@ -3,15 +3,46 @@ import { parseQn } from "../qualified-name.js";
 import { formDerivationsOfSchema } from "../with-form-derivations.js";
 const NUMERIC_FORM_FIELD_TYPES = ["money", "number", "decimal"];
 const NUMERIC_SUB_FIELD_TYPES = ["money", "number", "decimal"];
+function isMoneyType(type) {
+    return type === "money";
+}
+// Money operands are computed in minor units, number/decimal in major units: mixing them
+// silently scales the result by 100 or 10000.
+function validateUnitCompatibility({ prefix, screen, target }, derivation) {
+    const targetIsMoney = isMoneyType(screen.fields[target]?.type);
+    const moneyFlags = derivation.from.map((source) => isMoneyType(screen.fields[source]?.type));
+    const moneyCount = moneyFlags.filter(Boolean).length;
+    if (derivation.op === "sum" || derivation.op === "subtract") {
+        if (moneyCount !== 0 && moneyCount !== moneyFlags.length) {
+            throw new Error(`${prefix}.${target}: "${derivation.op}" sources must be all money or all number/decimal.`);
+        }
+        if (moneyCount > 0 !== targetIsMoney) {
+            throw new Error(`${prefix}.${target}: a "${derivation.op}" over ${moneyCount > 0 ? "money" : "number/decimal"} sources needs a ${moneyCount > 0 ? "money" : "number/decimal"} target.`);
+        }
+        // skip: sum/subtract fully validated above.
+        return;
+    }
+    if (moneyCount > 1 || (derivation.op === "percent" && moneyFlags[1] === true)) {
+        throw new Error(`${prefix}.${target}: "${derivation.op}" takes at most one money source${derivation.op === "percent" ? " (the base, not the rate)" : ""}.`);
+    }
+    if ((moneyCount === 1) !== targetIsMoney) {
+        throw new Error(`${prefix}.${target}: the target must be money exactly when a "${derivation.op}" source is money.`);
+    }
+}
 function validateFromList({ prefix, screen, target }, derivation) {
     if (derivation.op === "percent" && derivation.from.length !== 2) {
         throw new Error(`${prefix}.${target}: "percent" needs exactly two sources (base, rate).`);
     }
     for (const source of derivation.from) {
-        if (!(source in screen.fields)) {
+        const sourceField = screen.fields[source];
+        if (sourceField === undefined) {
             throw new Error(`${prefix}.${target}: unknown source field "${source}". Name a field of this screen.`);
         }
+        if (!NUMERIC_FORM_FIELD_TYPES.includes(sourceField.type)) {
+            throw new Error(`${prefix}.${target}: source "${source}" must be money, number or decimal, not "${sourceField.type}".`);
+        }
     }
+    validateUnitCompatibility({ prefix, screen, target }, derivation);
 }
 function validateListSum(check, derivation) {
     const { prefix, screen, target } = check;
@@ -26,6 +57,9 @@ function validateListSum(check, derivation) {
     if (cellType === undefined || !NUMERIC_SUB_FIELD_TYPES.includes(cellType)) {
         throw new Error(`${prefix}.${target}: "${derivation.cell}" must be a money, number or decimal sub-field of "${derivation.list}".`);
     }
+    if (isMoneyType(cellType) !== isMoneyType(screen.fields[target]?.type)) {
+        throw new Error(`${prefix}.${target}: a listSum of a ${isMoneyType(cellType) ? "money" : "number/decimal"} cell needs a ${isMoneyType(cellType) ? "money" : "number/decimal"} target.`);
+    }
     const { whenEmpty } = derivation;
     // skip: whenEmpty is optional
     if (whenEmpty === undefined)

package/dist/engine/boot-validator/i18n-keys.js

@@ -94,9 +94,11 @@ export function validateTranslationLocaleConsistency(features) {
     }
 }
 export function validateRequiredLocales(features, requiredLocales) {
-    const gaps = findRequiredLocaleGaps(features, requiredLocales ?? []);
-    if (gaps.length > 0) {
+    const gaps = requiredLocales === undefined || requiredLocales.length === 0
+        ? []
+        : findRequiredLocaleGaps(features, requiredLocales);
+    if (requiredLocales !== undefined && gaps.length > 0) {
         const lines = gaps.map((gap) => `[i18n] Feature "${gap.featureName}": translation key "${gap.key}" is missing required locale(s) ${gap.missingLocales.join(", ")}.`);
-        throw new Error(`${lines.join("\n")}\nThe app requires locales [${(requiredLocales ?? []).join(", ")}] for every translation key; load the matching locale package or add the missing translations.`);
+        throw new Error(`${lines.join("\n")}\nThe app requires locales [${requiredLocales.join(", ")}] for every translation key; load the matching locale package or add the missing translations.`);
     }
 }

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

@@ -2,6 +2,7 @@ import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-en
 import { dedupeFeatures } from "../dedupe-features.js";
 import { FILE_STORAGE_PROVIDER_ENV } from "../extension-names.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
+import { validateProjectionAllowlist } from "../validate-projection-allowlist.js";
 import { validateAccessDeclarations } from "./access-declarations.js";
 import { warnOnUniqueAccessRoles } from "./access-roles.js";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring.js";
@@ -238,6 +239,7 @@ export function validateBoot(rawFeatures, options) {
     validateGdprStoragePersistence(features);
     validateGlobalTenancyEntities(features);
     validateFeatureBootChecks(features);
+    validateProjectionAllowlist(features);
     if (hasEncryptedFields) {
         // Availability check, not env-presence: eagerly building the keyring
         // catches malformed keys (wrong length, bad base64) at boot instead of

package/dist/engine/boot-validator/list-bulk-actions.d.ts

@@ -0,0 +1,3 @@
+import { type RowAction } from "../types/screen.ts";
+/** `where` is the full message prefix, e.g. `[Feature x] Screen "y" (entityList)`. */
+export declare function validateListBulkActions(where: string, bulkActions: unknown, rowActions: readonly RowAction[] | undefined): void;