@cosmicdrift/kumiko-framework 0.363.0 → 0.364.0

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

@@ -15,3 +15,20 @@ export function tenantDbRunner(tenantDb) {
     }
     return runner;
 }
+const writesDeniedReasons = new WeakMap();
+export function denyTenantDbWrites(tenantDb, reason) {
+    writesDeniedReasons.set(tenantDb, reason);
+}
+export function tenantDbWritesDeniedError(operation, reason) {
+    return new InternalError({
+        message: `${operation}: writes are not available ${reason}; run the write through ctx.write so it gets its own transaction`,
+    });
+}
+// For framework code that writes through the raw runner (executor verbs, event appends, projection steps):
+// the TenantDb's own write methods are denied via TenantDbGrants, this closes the runner-based door.
+export function tenantDbWriteRunner(tenantDb, operation) {
+    const reason = writesDeniedReasons.get(tenantDb);
+    if (reason !== undefined)
+        throw tenantDbWritesDeniedError(operation, reason);
+    return tenantDbRunner(tenantDb);
+}

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

@@ -16,6 +16,7 @@ export declare function unsafeRawForDeclaredStep(holder: TenantDb | UncheckedSys
 export declare function withSystemDbUnsafeRawGrant(systemDb: UncheckedSystemDb, grant: EscapeHatchDeclaration | undefined, deniedCallerLabel: string): UncheckedSystemDb;
 export declare function createUncheckedSystemDb(db: TenantDb, dbOutsideTransaction?: TenantDb, report?: EscapeHatchReporter): UncheckedSystemDb;
 export declare function createSystemDbView(db: TenantDb, dbOutsideTransaction?: TenantDb, report?: EscapeHatchReporter): UncheckedSystemDb;
+export declare function scopeTenantDbToTenant(db: TenantDb, tenantId: TenantId): TenantDb;
 export declare function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[];
 export { tableNameOf };
 export declare function hasTenantColumn(table: Table | EntityTableMeta): boolean;
@@ -26,6 +27,7 @@ export type TenantDbGrants = {
     readonly memberReadOnly?: boolean;
     readonly personalDataGate?: PersonalDataGate;
     readonly projectionRegistry?: Registry;
+    readonly writesDeniedReason?: string;
 };
 export type PersonalDataGate = (tableName: string, keys: readonly string[], entity?: EntityDefinition) => void;
 export declare function withUnsafeRawGrant(tenantDb: TenantDb, grant: EscapeHatchDeclaration | undefined): TenantDb;

package/dist/db/tenant-db.js

@@ -5,7 +5,7 @@ import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } fro
 import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
 import { bindProjectionRegistry, projectionRegistryOf } from "./projection-registry-binding.js";
 import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
-import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner.js";
+import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, } from "./tenant-db-runner.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
@@ -220,6 +220,12 @@ export function createUncheckedSystemDb(db, dbOutsideTransaction, report = fallb
 export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEscapeHatchReporter(db.tenantId)) {
     return buildUncheckedSystemDb(db, dbOutsideTransaction, report, { kind: "source-tenant-db" });
 }
+// Narrows a (possibly "system"-mode) TenantDb to a "tenant"-mode handle for one tenant on the
+// 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(tenantDbRunner(db), tenantId, "tenant");
+}
 // @cast-boundary tenant-db-row
 export function castTenantRows(rows) {
     return rows;
@@ -390,6 +396,10 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             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);
+    }
     function globalWriteReason() {
         return grants?.globalWrites?.reason ?? "";
     }
@@ -437,7 +447,8 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                 return withDbSpan("select", table, async () => bunFetchOne(db, table, where));
             },
             insertOne(values) {
-                const denied = missingEscapeHatch(table) ??
+                const denied = writesDenied("ctx.db.global().insertOne") ??
+                    missingEscapeHatch(table) ??
                     executorManagedWriteDenied(table) ??
                     foreignTenantOnGlobalWrite(table, values["tenantId"]) ??
                     personalDataDenied(table, Object.keys(values));
@@ -447,7 +458,8 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                 return withDbSpan("insert", table, async () => bunInsertOne(db, table, values));
             },
             updateMany(set, where) {
-                const denied = missingEscapeHatch(table) ??
+                const denied = writesDenied("ctx.db.global().updateMany") ??
+                    missingEscapeHatch(table) ??
                     executorManagedWriteDenied(table) ??
                     foreignTenantOnGlobalWrite(table, set["tenantId"]) ??
                     personalDataDenied(table, Object.keys(set));
@@ -460,7 +472,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                 return withDbSpan("update", table, async () => bunUpdateMany(db, table, set, where));
             },
             deleteMany(where) {
-                const denied = missingEscapeHatch(table) ?? executorManagedWriteDenied(table);
+                const denied = writesDenied("ctx.db.global().deleteMany") ??
+                    missingEscapeHatch(table) ??
+                    executorManagedWriteDenied(table);
                 if (denied)
                     return Promise.reject(denied);
                 if (!where || Object.keys(where).length === 0) {
@@ -509,6 +523,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             return withDbSpan("select", table, async () => bunAggregateWhere(db, table, spec, filter));
         },
         insertOne(table, values) {
+            const writeDenied = writesDenied("ctx.db.insertOne");
+            if (writeDenied)
+                return Promise.reject(writeDenied);
             if (mode === "tenant" &&
                 hasTenantColumn(table) &&
                 asEntityTableMeta(table)?.tenancy === "global") {
@@ -524,6 +541,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             return withDbSpan("insert", table, async () => bunInsertOne(db, table, data));
         },
         updateMany(table, set, where) {
+            const writeDenied = writesDenied("ctx.db.updateMany");
+            if (writeDenied)
+                return Promise.reject(writeDenied);
             if (!where || Object.keys(where).length === 0) {
                 return Promise.reject(new Error("TenantDb.updateMany without where would mass-update all tenant rows. Pass at least one where condition."));
             }
@@ -537,6 +557,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             return withDbSpan("update", table, async () => bunUpdateMany(db, table, set, filter));
         },
         deleteMany(table, where) {
+            const writeDenied = writesDenied("ctx.db.deleteMany");
+            if (writeDenied)
+                return Promise.reject(writeDenied);
             if (!where || Object.keys(where).length === 0) {
                 return Promise.reject(new Error("TenantDb.deleteMany without where would mass-delete all tenant rows. Pass at least one where condition."));
             }
@@ -573,6 +596,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         return runInNewTransaction(db, (tx) => fn(createTenantDb(tx, tenantId, mode, tracer, meter, signal, txGrants)));
     });
     bindTenantDbRunner(tenantDb, db);
+    if (grants?.writesDeniedReason !== undefined) {
+        denyTenantDbWrites(tenantDb, grants.writesDeniedReason);
+    }
     if (personalDataGate)
         personalDataGates.set(tenantDb, personalDataGate);
     if (projectionRegistry)

package/dist/derivatives/derivatives-context.js

@@ -181,7 +181,7 @@ export function createDerivativesContext(deps) {
             // Resolves qr dataTokens to concrete values BEFORE the spec is hashed
             // — see resolveOverlaySpec.
             const resolvedSpec = await resolveOverlaySpec(spec, row, deps.registry, deps.tenantId);
-            const src = deps.files.ref(row.storageKey);
+            const src = deps.files.refFromFileRef(row);
             // ponytail: derived key keeps the source extension regardless of the
             // spec's format — widen deriveKey if a storage backend ever routes on
             // extension.

package/dist/engine/boot-validator/access-declarations.js

@@ -83,7 +83,7 @@ function validatePersonalDataSupportedForKind(feature, kind, handlerName, access
         ? 'only access.personalData: "public-intake" applies to query handlers, which write ' +
             "personal data through nested writes of an anonymous request."
         : "it only applies to write handlers, whose input is checked for personal-data fields.";
-    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ${property} — ${onlyAllowed}`);
+    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ${property} — ${onlyAllowed} Remove the personalData declaration from this handler.`);
 }
 function validatePersonalDataValue(feature, kind, handlerName, access) {
     const declared = declaredPersonalData(access);
@@ -107,7 +107,7 @@ function validatePersonalDataValue(feature, kind, handlerName, access) {
     throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
         'access.personalData: "public-intake" but its roles do not include ' +
         `"${ANONYMOUS_ROLE}" — personalData: "public-intake" only applies to handlers ` +
-        "that allow anonymous callers.");
+        "that allow anonymous callers. Add the anonymous role to access.roles or remove personalData.");
 }
 function handlerInputKeys(feature, handlerName, handler) {
     try {

package/dist/engine/boot-validator/api-ext.js

@@ -31,7 +31,7 @@ export function validateApiExposureMatching(feature, allExposedApis, featureMap)
         // Should always be true if allExposedApis was built from `features`,
         // aber defensiv für unklare Constructor-Pfade.
         if (!featureMap.has(providerFeature)) {
-            throw new Error(`[Feature ${feature.name}] internal: r.usesApi("${apiName}") points to provider "${providerFeature}" which is not in feature map`);
+            throw new Error(`[Feature ${feature.name}] internal: r.usesApi("${apiName}") points to provider "${providerFeature}" which is not in feature map. Register the provider feature in the app's feature list.`);
         }
     }
 }
@@ -40,7 +40,7 @@ export function validateExtensionUsages(feature, extensionProviders) {
     for (const usage of feature.extensionUsages) {
         const providerFeature = extensionProviders.get(usage.extensionName);
         if (!providerFeature) {
-            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" on entity "${usage.entityName}" but no feature defines that extension`);
+            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" on entity "${usage.entityName}" but no feature defines that extension. Register the feature that defines it or fix the extension name.`);
         }
         // self-extension is legitimate: requires(self) would be circular.
         if (providerFeature === feature.name) {
@@ -48,7 +48,7 @@ export function validateExtensionUsages(feature, extensionProviders) {
         }
         const allDeps = [...feature.requires, ...feature.optionalRequires];
         if (!allDeps.includes(providerFeature)) {
-            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}")`);
+            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}"). Add r.requires("${providerFeature}").`);
         }
     }
 }

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}`);
+                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}. Fix the condition this check reports.`);
             }
         }
     }

package/dist/engine/boot-validator/config-deps.js

@@ -38,15 +38,15 @@ export function validateConfigKeyBounds(feature) {
         }
         const { min, max } = bounds;
         if (min !== undefined && max !== undefined && min > max) {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has bounds.min (${min}) > bounds.max (${max})`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has bounds.min (${min}) > bounds.max (${max}). Set bounds.min to a value at or below bounds.max.`);
         }
         if (keyDef.default !== undefined) {
             const defaultNum = keyDef.default; // @cast-boundary engine-payload
             if (min !== undefined && defaultNum < min) {
-                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is below bounds.min (${min})`);
+                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is below bounds.min (${min}). Raise the default or lower bounds.min.`);
             }
             if (max !== undefined && defaultNum > max) {
-                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is above bounds.max (${max})`);
+                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is above bounds.max (${max}). Lower the default or raise bounds.max.`);
             }
         }
     }
@@ -61,7 +61,7 @@ export function validateConfigKeyComputed(feature) {
         // cascade doesn't know which one to prefer on write. Rejecting at boot
         // is cheaper than surprising behaviour at runtime.
         if (isEncryptedAtRest(keyDef)) {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has both encrypted/backing="secrets" and a computed resolver — these are mutually exclusive paradigms`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has both encrypted/backing="secrets" and a computed resolver — these are mutually exclusive paradigms. Use either encrypted/backing="secrets" or a computed resolver on one key.`);
         }
     }
 }
@@ -92,7 +92,7 @@ export function validateConfigKeyAllowPerRequest(feature) {
         // anyway, but declaring allowPerRequest on a text key is a
         // misconfiguration that should fail loudly at boot.
         if (keyDef.type === "text") {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but type="text" — text keys are permanently ineligible for per-request overrides (XSS/injection risk)`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but type="text" — text keys are permanently ineligible for per-request overrides (XSS/injection risk). Remove allowPerRequest or change the key type.`);
         }
         // encrypted + per-request would expose a cipher-text interpretation
         // to query-strings. The secret-value shouldn't be transported this
@@ -107,16 +107,16 @@ export function validateConfigKeyOptionsQuery(feature) {
     for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
         const prefix = `[Feature ${feature.name}] Config key "${keyName}"`;
         if ("conditionalOptions" in keyDef) {
-            throw new Error(`${prefix} declares conditionalOptions — conditionalOptions is only supported on entity select fields (enforced by the entity write path)`);
+            throw new Error(`${prefix} declares conditionalOptions — conditionalOptions is only supported on entity select fields (enforced by the entity write path). Remove conditionalOptions from the config key.`);
         }
         if (keyDef.optionsQuery === undefined) {
             if (keyDef.optionsQueryPayload !== undefined) {
-                throw new Error(`${prefix} has optionsQueryPayload without optionsQuery`);
+                throw new Error(`${prefix} has optionsQueryPayload without optionsQuery. Set optionsQuery or remove optionsQueryPayload.`);
             }
             continue;
         }
         if (keyDef.optionsQuery.length === 0) {
-            throw new Error(`${prefix} has an empty optionsQuery`);
+            throw new Error(`${prefix} has an empty optionsQuery. Set it to a query name or remove it.`);
         }
         if (keyDef.type !== "select") {
             throw new Error(`${prefix} has optionsQuery but type="${keyDef.type}" — optionsQuery is only valid on select keys`);
@@ -134,7 +134,7 @@ function validateOptionsQueryKeyRefs(feature, keyName, keyDef) {
     const prefix = `[Feature ${feature.name}] Config key "${keyName}"`;
     for (const ref of optionsQueryFieldRefs(keyDef.optionsQueryPayload)) {
         if (ref === keyName) {
-            throw new Error(`${prefix} optionsQueryPayload references itself ({ field: "${ref}" })`);
+            throw new Error(`${prefix} optionsQueryPayload references itself ({ field: "${ref}" }). Reference a different config key.`);
         }
         if (feature.configKeys[ref] === undefined) {
             throw new Error(`${prefix} optionsQueryPayload references unknown config key "${ref}" of feature "${feature.name}"`);
@@ -166,12 +166,12 @@ export function validateConfigKeyPiiEncrypted(feature) {
         if (!keyDef.piiEncrypted)
             continue;
         if (keyDef.type !== "text") {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but type="${keyDef.type}" — piiEncrypted only applies to text keys`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but type="${keyDef.type}" — piiEncrypted only applies to text keys. Use type="text" or remove piiEncrypted.`);
         }
         // system scope has no subject (no tenant, no user) for the subject-KMS
         // to encrypt under.
         if (keyDef.scope === "system") {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but scope="system" — system-scope has no subject (tenant/user) for the subject-KMS to encrypt under`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but scope="system" — system-scope has no subject (tenant/user) for the subject-KMS to encrypt under. Use scope="tenant" or "user", or remove piiEncrypted.`);
         }
         // Mutually exclusive with the shared-cipher path: a config value is
         // either subject-keyed (piiEncrypted) or master-key-keyed (encrypted/
@@ -190,7 +190,7 @@ export function validateConfigReads(features, allConfigKeys) {
     for (const feature of features) {
         for (const key of feature.configReads) {
             if (!allConfigKeys.has(key)) {
-                throw new Error(`Feature "${feature.name}" reads config "${key}" but no feature defines that key`);
+                throw new Error(`Feature "${feature.name}" reads config "${key}" but no feature defines that key. Declare the key via r.config(...) in a feature, or fix the key name.`);
             }
         }
     }
@@ -201,7 +201,7 @@ export function validateCircularDeps(featureName, featureMap) {
     const stack = new Set();
     function visit(name, path) {
         if (stack.has(name)) {
-            throw new Error(`Circular dependency: ${[...path, name].join(" → ")}`);
+            throw new Error(`Circular dependency: ${[...path, name].join(" → ")}. Break the cycle by removing one requires() link.`);
         }
         // skip: node already visited in DFS traversal
         if (visited.has(name))

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

@@ -22,7 +22,7 @@ export function collectDetailForScreens(features, featureMap) {
             screenQnByEntity.set(detailFor, qualified);
             if (findEntityFeature(detailFor, featureMap) === undefined) {
                 throw new Error(`[detailFor] Screen "${qualified}" declares detailFor: "${detailFor}", ` +
-                    `but no feature registers an entity with that name.`);
+                    `but no feature registers an entity with that name. Set detailFor to a registered entity name or remove it.`);
             }
             result.set(detailFor, { featureName: feature.name, screen });
         }

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

@@ -7,6 +7,7 @@ export declare const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string>;
 export declare function validateExtensionPreSaveWiring(features: readonly FeatureDefinition[]): void;
 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 validateRateLimitDisabledReason(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

@@ -140,6 +140,7 @@ export function validateHandlerAccess(feature) {
     for (const [name, handler] of Object.entries(feature.writeHandlers)) {
         validateTenantlessAnonymous(feature.name, name, handler);
         validateAdditionalRateLimits(feature.name, name, handler);
+        validatePerCommandTransaction(feature.name, name, handler);
     }
 }
 const IP_BUCKETED_RATE_LIMIT_PER = new Set(["ip", "ip+handler"]);
@@ -172,7 +173,7 @@ function validateAnonymousHasIpBucket(where, handler) {
         IP_BUCKETED_RATE_LIMIT_PER.has(rateLimit.per);
     if (!hasIpBucket) {
         throw new Error(`${where} and allows anonymous callers, but has no ip-keyed rateLimit ` +
-            `(per: "ip" or "ip+handler", not disabled). Payload buckets only complement the IP bucket.`);
+            `(per: "ip" or "ip+handler", not disabled). Payload buckets only complement the IP bucket. Set rateLimit: { per: "ip", ... } on the handler.`);
     }
 }
 function validatePayloadBucket(where, shape, entry) {
@@ -188,6 +189,23 @@ function validatePayloadBucket(where, shape, entry) {
         throw new Error(`${where} for "${field}" with windowSeconds ${entry.windowSeconds} — must be a positive integer.`);
     }
 }
+function perCommandConflict(handler) {
+    if (handler.transaction !== "perCommand")
+        return undefined;
+    if (handler.beforeTransaction)
+        return "beforeTransaction";
+    if (handler.reserveBeforeTransaction)
+        return "reserveBeforeTransaction";
+    return undefined;
+}
+export function validatePerCommandTransaction(featureName, handlerName, handler) {
+    const conflicting = perCommandConflict(handler);
+    if (conflicting !== undefined) {
+        throw new Error(`write handler "${featureName}:write:${handlerName}" declares transaction: "perCommand" together with ${conflicting} — ` +
+            "a perCommand handler holds no transaction, so move the phase into the commands it issues via ctx.write.");
+    }
+}
+const IP_SCOPED_RATE_LIMIT_PER = ["ip", "ip+handler"];
 export function validateTenantlessAnonymous(featureName, handlerName, handler) {
     // skip: handler does not opt into tenantless anonymous calls
     if (!handler.tenantlessAnonymous)
@@ -197,12 +215,16 @@ export function validateTenantlessAnonymous(featureName, handlerName, handler) {
     const isAnonymousOnly = "roles" in access && access.roles.length === 1 && access.roles[0] === "anonymous";
     if (!isAnonymousOnly) {
         throw new Error(`${where} but its access is not exactly { roles: ["anonymous"] } — a tenantless request ` +
-            `carries no principal beyond the anonymous visitor.`);
+            `carries no principal beyond the anonymous visitor. Set access to { roles: ["anonymous"] } or remove tenantlessAnonymous.`);
     }
     if (!handler.rateLimit || isRateLimitDisabled(handler.rateLimit)) {
         throw new Error(`${where} without a rateLimit — a handler reachable on hosts that resolve no tenant ` +
             `needs a real upper bound (rateLimit: { per: "ip", ... }); { disabled: true } does not count.`);
     }
+    if (!IP_SCOPED_RATE_LIMIT_PER.includes(handler.rateLimit.per)) {
+        throw new Error(`${where} with rateLimit.per "${handler.rateLimit.per}" — every anonymous visitor shares the same ` +
+            `tenant/user bucket, so one caller could exhaust it for all. Use ${IP_SCOPED_RATE_LIMIT_PER.map((per) => `"${per}"`).join(" or ")}.`);
+    }
 }
 export function validateRateLimitDisabledReason(featureName, kind, handlerName, rateLimit) {
     // skip: rate limit isn't disabled, so no reason is required
@@ -393,17 +415,17 @@ export function validateEncryptedFields(feature) {
             found = true;
             if (field.type === "text") {
                 if (field.searchable) {
-                    throw new Error(`Field "${fieldName}" on entity "${entityName}" cannot be both encrypted and searchable`);
+                    throw new Error(`Field "${fieldName}" on entity "${entityName}" cannot be both encrypted and searchable. Drop searchable: true or remove the encryption.`);
                 }
                 if (field.sortable) {
-                    throw new Error(`Field "${fieldName}" on entity "${entityName}" cannot be both encrypted and sortable`);
+                    throw new Error(`Field "${fieldName}" on entity "${entityName}" cannot be both encrypted and sortable. Drop sortable: true or remove the encryption.`);
                 }
                 // AES-GCM draws a fresh random IV per call, so the ciphertext is
                 // non-deterministic — an equality filter on it never matches, even
                 // against the identical plaintext.
                 if (field.filterable) {
                     throw new Error(`Field "${fieldName}" on entity "${entityName}" cannot be both encrypted and filterable ` +
-                        `— non-deterministic ciphertext never matches an equality filter.`);
+                        `— non-deterministic ciphertext never matches an equality filter. Drop filterable: true or remove the encryption.`);
                 }
             }
         }
@@ -537,7 +559,7 @@ export function validateEmbeddedFields(feature, featureMap, queryHandlers) {
             if (field.type !== "embedded")
                 continue;
             if (!field.schema || Object.keys(field.schema).length === 0) {
-                throw new Error(`Embedded field "${fieldName}" on entity "${entityName}" in feature "${feature.name}" has an empty schema`);
+                throw new Error(`Embedded field "${fieldName}" on entity "${entityName}" in feature "${feature.name}" has an empty schema. Declare at least one sub-field in the embedded schema.`);
             }
             for (const [subName, subField] of Object.entries(field.schema)) {
                 if (!VALID_EMBEDDED_SUB_TYPES.has(subField.type)) {
@@ -547,7 +569,7 @@ export function validateEmbeddedFields(feature, featureMap, queryHandlers) {
                     throw new Error(`Embedded field "${fieldName}.${subName}" on entity "${entityName}" has invalid scale ${subField.scale}. Must be an integer between 0 and 15.`);
                 }
                 if (subField.type === "select" && subField.options.length === 0) {
-                    throw new Error(`Embedded field "${fieldName}.${subName}" on entity "${entityName}" has empty options`);
+                    throw new Error(`Embedded field "${fieldName}.${subName}" on entity "${entityName}" has empty options. Add at least one option.`);
                 }
                 // Reference sub-fields get the same target/labelField/query-handler
                 // checks as a top-level reference field — same failure mode
@@ -571,7 +593,7 @@ function validateEmbeddedListBounds(fieldName, entityName, field) {
     if (field.minItems !== undefined &&
         field.maxItems !== undefined &&
         field.minItems > field.maxItems) {
-        throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has minItems ${field.minItems} greater than maxItems ${field.maxItems}.`);
+        throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has minItems ${field.minItems} greater than maxItems ${field.maxItems}. Set minItems at or below maxItems.`);
     }
     // required:true means "at least one row" (schema-builder.ts falls back to
     // minItems:1 for that); an explicit minItems:0 would silently win over
@@ -587,14 +609,14 @@ function validateEmbeddedDerivedCells(fieldName, entityName, field) {
         return;
     for (const [derivedName, derivedDef] of Object.entries(field.derived)) {
         if (!(derivedName in field.schema)) {
-            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" that is not a sub-field in its schema.`);
+            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" that is not a sub-field in its schema. Add the sub-field to the schema or remove the derived cell.`);
         }
         for (const sourceName of derivedDef.from) {
             if (!(sourceName in field.schema)) {
-                throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading unknown sub-field "${sourceName}".`);
+                throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading unknown sub-field "${sourceName}". Read only sub-fields that exist in the schema.`);
             }
             if (sourceName in field.derived) {
-                throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading derived sub-field "${sourceName}".`);
+                throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading derived sub-field "${sourceName}". Read only stored sub-fields, not other derived cells.`);
             }
         }
     }
@@ -606,7 +628,7 @@ function validateEmbeddedTotalsColumns(fieldName, entityName, field) {
     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.`);
+            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.`);
         }
     }
 }
@@ -617,11 +639,11 @@ function validateEmbeddedTotalsMatch(fieldName, entityName, field, entity) {
     for (const [subFieldName, siblingFieldName] of Object.entries(field.totalsMatch)) {
         const subField = field.schema[subFieldName];
         if (subField?.type !== "money") {
-            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a totalsMatch entry for "${subFieldName}", which is not a money sub-field in its schema.`);
+            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a totalsMatch entry for "${subFieldName}", which is not a money sub-field in its schema. Use a money sub-field as the totalsMatch key.`);
         }
         const siblingField = entity.fields[siblingFieldName];
         if (siblingField?.type !== "money") {
-            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a totalsMatch entry mapping "${subFieldName}" to sibling field "${siblingFieldName}", which is not a money field on entity "${entityName}".`);
+            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a totalsMatch entry mapping "${subFieldName}" to sibling field "${siblingFieldName}", which is not a money field on entity "${entityName}". Map it to a money field of the entity.`);
         }
     }
 }
@@ -723,6 +745,15 @@ export function validateEntitySelectAvailabilityQuery(feature, queryHandlers) {
         }
     }
 }
+function conditionComparisonValues(when) {
+    if ("eq" in when)
+        return [when.eq];
+    if ("ne" in when)
+        return [when.ne];
+    if ("in" in when)
+        return when.in;
+    return when.notIn;
+}
 export function validateEntitySelectConditionalOptions(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
         for (const [fieldName, field] of Object.entries(entity.fields)) {
@@ -730,7 +761,7 @@ export function validateEntitySelectConditionalOptions(feature) {
                 continue;
             const where = `[Feature ${feature.name}] Select field "${fieldName}" on entity "${entityName}"`;
             if (field.optionsQuery !== undefined) {
-                throw new Error(`${where} combines conditionalOptions with optionsQuery — conditionalOptions filters the static options only.`);
+                throw new Error(`${where} combines conditionalOptions with optionsQuery — conditionalOptions filters the static options only. Remove either conditionalOptions or optionsQuery.`);
             }
             const knownOptions = new Set(field.options);
             const ruleOfOption = new Map();
@@ -745,7 +776,7 @@ export function validateEntitySelectConditionalOptions(feature) {
                     }
                     const otherRule = ruleOfOption.get(option);
                     if (otherRule !== undefined) {
-                        throw new Error(`${where} lists "${option}" in conditionalOptions[${otherRule}] and ${ruleLabel} — an option may belong to one rule only.`);
+                        throw new Error(`${where} lists "${option}" in conditionalOptions[${otherRule}] and ${ruleLabel} — an option may belong to one rule only. Remove the option from one of the rules.`);
                     }
                     ruleOfOption.set(option, ruleIndex);
                     if (option === field.default) {
@@ -754,10 +785,19 @@ export function validateEntitySelectConditionalOptions(feature) {
                 }
                 const conditionField = rule.when.field;
                 if (conditionField === fieldName) {
-                    throw new Error(`${where} has ${ruleLabel}.when on its own field.`);
+                    throw new Error(`${where} has ${ruleLabel}.when on its own field. Make the condition depend on a different field.`);
                 }
                 if (!(conditionField in entity.fields)) {
-                    throw new Error(`${where} has ${ruleLabel}.when.field "${conditionField}" which is not a field of the entity.`);
+                    throw new Error(`${where} has ${ruleLabel}.when.field "${conditionField}" which is not a field of the entity. Use an existing field of the entity in when.field.`);
+                }
+                const conditionFieldDef = entity.fields[conditionField];
+                if (conditionFieldDef?.type === "select" || conditionFieldDef?.type === "multiSelect") {
+                    const conditionOptions = conditionFieldDef.options;
+                    for (const value of conditionComparisonValues(rule.when)) {
+                        if (typeof value !== "string" || !conditionOptions.includes(value)) {
+                            throw new Error(`${where} has ${ruleLabel}.when value "${String(value)}" which is not an option of "${conditionField}" (${conditionOptions.join(", ")}).`);
+                        }
+                    }
                 }
             });
         }
@@ -769,7 +809,7 @@ export function validateMultiSelectFields(feature) {
             if (field.type !== "multiSelect")
                 continue;
             if (field.options.length === 0) {
-                throw new Error(`MultiSelect field "${fieldName}" on entity "${entityName}" in feature "${feature.name}" has empty options`);
+                throw new Error(`MultiSelect field "${fieldName}" on entity "${entityName}" in feature "${feature.name}" has empty options. Add at least one option.`);
             }
             if (field.default !== undefined) {
                 const validOptions = new Set(field.options);
@@ -933,7 +973,7 @@ export function validateExtendSchemaCollisions(feature) {
             const extraFields = ext.extendSchema(entityName);
             for (const fieldName of Object.keys(extraFields)) {
                 if (existingFields.has(fieldName)) {
-                    throw new Error(`extendSchema column "${fieldName}" conflicts with existing field on entity "${entityName}"`);
+                    throw new Error(`extendSchema column "${fieldName}" conflicts with existing field on entity "${entityName}". Rename the extension column or the entity field.`);
                 }
             }
         }
@@ -954,7 +994,7 @@ export function validateDerivedFieldCollisions(feature) {
         for (const derivedName of Object.keys(entity.derivedFields)) {
             if (fieldNames.has(derivedName)) {
                 throw new Error(`Entity "${entityName}": derivedFields key "${derivedName}" conflicts with a stored ` +
-                    `field of the same name — the derived value would silently overwrite the real one on every read.`);
+                    `field of the same name — the derived value would silently overwrite the real one on every read. Rename the derivedFields key or the stored field.`);
             }
         }
     }
@@ -964,24 +1004,33 @@ export function validateDerivedFieldCollisions(feature) {
 // searchable field and `filterReadFields` only strips the response afterwards.
 // A role that cannot read the field could still guess its value from match
 // counts, so the combination is rejected until the index can filter per role.
+function isUnrestrictedReadAccess(access) {
+    const readAccess = access?.read;
+    if (readAccess === undefined)
+        return true;
+    return Array.isArray(readAccess) ? readAccess.length === 0 : Object.keys(readAccess).length === 0;
+}
+function throwSearchableRestricted(subject, entityName) {
+    throw new Error(`${subject} on entity "${entityName}" cannot be searchable with a restricted ` +
+        "access.read — the search index is not filtered per role, so search matches would leak " +
+        'the value to roles that cannot read it. Drop `searchable`/`find: "fuzzy"` or `access.read`.');
+}
 export function validateSearchableFieldReadAccess(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
         for (const [fieldName, field] of Object.entries(entity.fields)) {
-            if (field.type !== "text")
-                continue;
-            if (!field.searchable)
-                continue;
-            const readAccess = field.access?.read;
-            if (readAccess === undefined)
-                continue;
-            const isUnrestricted = Array.isArray(readAccess)
-                ? readAccess.length === 0
-                : Object.keys(readAccess).length === 0;
-            if (isUnrestricted)
+            if (field.type === "text" && field.searchable && !isUnrestrictedReadAccess(field.access)) {
+                throwSearchableRestricted(`Field "${fieldName}"`, entityName);
+            }
+            if (field.type !== "embedded")
                 continue;
-            throw new Error(`Field "${fieldName}" on entity "${entityName}" cannot be searchable with a restricted ` +
-                "access.read — the search index is not filtered per role, so search matches would leak " +
-                'the value to roles that cannot read it. Drop `searchable`/`find: "fuzzy"` or `access.read`.');
+            for (const [subName, subField] of Object.entries(field.schema)) {
+                if (subField.searchable !== true)
+                    continue;
+                if (isUnrestrictedReadAccess(field.access) && isUnrestrictedReadAccess(subField.access)) {
+                    continue;
+                }
+                throwSearchableRestricted(`Field "${fieldName}.${subName}"`, entityName);
+            }
         }
     }
 }

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

@@ -28,13 +28,13 @@ function validateOneEntityListScreen(feature, screen) {
     const filtersActive = hasFilterableFields(feature, screen.entity);
     const searchable = screen.searchable !== false;
     if ((searchable || filtersActive) && screen.defaultSort === undefined) {
-        throw new Error(`${prefix}: defaultSort required when searchable or filterable fields are active`);
+        throw new Error(`${prefix}: defaultSort required when searchable or filterable fields are active. Set defaultSort: { field, direction } on the screen.`);
     }
     if (screen.defaultSort !== undefined) {
         const sortField = screen.defaultSort.field;
         const col = screen.columns.find((c) => normalizeListColumn(c).field === sortField);
         if (col === undefined) {
-            throw new Error(`${prefix}: defaultSort.field "${sortField}" is not a listed column`);
+            throw new Error(`${prefix}: defaultSort.field "${sortField}" is not a listed column. Pick a field from columns or add it there.`);
         }
         const entityDef = feature.entities?.[screen.entity];
         const fieldDef = entityDef?.fields[sortField];