@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

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

@@ -15,7 +15,7 @@ function hasFilterableFields(feature, entityName) {
     const entity = entities[entityName];
     if (!entity)
         return false;
-    return Object.values(entity.fields).some((raw) => raw.filterable === true);
+    return Object.values(entity.fields).some((raw) => "filterable" in raw && raw.filterable === true);
 }
 function hasEntityEditDetail(feature, entityName) {
     return Object.values(feature.screens).some((s) => s.type === "entityEdit" && s.entity === entityName);
@@ -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];

package/dist/engine/boot-validator/handler-field-references.js

@@ -1,4 +1,4 @@
-import { handlerFieldReference } from "../handler-field-references.js";
+import { readHandlerFieldReference } from "../handler-field-references.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { getZodObjectShape } from "./zod-shape.js";
 function validateHandlerGroup(feature, featureMap, handlers, handlerNoun) {
@@ -7,15 +7,25 @@ function validateHandlerGroup(feature, featureMap, handlers, handlerNoun) {
         if (shape === undefined)
             continue;
         for (const fieldName of Object.keys(shape)) {
-            const reference = handlerFieldReference(def.schema, fieldName);
-            if (reference === undefined)
+            const where = `Input field "${fieldName}" of ${handlerNoun} "${handlerName}"`;
+            const reading = readHandlerFieldReference(def.schema, fieldName);
+            if (reading.kind === "none")
                 continue;
-            const target = parseRefTarget(reference, feature.name);
-            const targetEntities = featureMap.get(target.featureName)?.entities;
-            if (targetEntities?.[target.entityName] !== undefined)
-                continue;
-            throw new Error(`[Feature ${feature.name}] Input field "${fieldName}" of ${handlerNoun} "${handlerName}" has meta references: "${reference}", ` +
-                `which is not a registered entity. Use "<entity>" for this feature or "<feature>:<entity>" for another one.`);
+            if (reading.kind === "invalid") {
+                throw new Error(`[Feature ${feature.name}] ${where} has an invalid meta references value ${JSON.stringify(reading.raw)}. ` +
+                    `Use "<entity>", "<feature>:<entity>" or { entity, by? }.`);
+            }
+            const { entity, by } = reading.reference;
+            const target = parseRefTarget(entity, feature.name);
+            const targetEntity = featureMap.get(target.featureName)?.entities?.[target.entityName];
+            if (targetEntity === undefined) {
+                throw new Error(`[Feature ${feature.name}] ${where} has meta references: "${entity}", ` +
+                    `which is not a registered entity. Use "<entity>" for this feature or "<feature>:<entity>" for another one.`);
+            }
+            if (by !== undefined && targetEntity.fields[by] === undefined) {
+                throw new Error(`[Feature ${feature.name}] ${where} references entity "${entity}" by "${by}", ` +
+                    `but that entity has no field "${by}". Use an existing field of that entity for "by".`);
+            }
         }
     }
 }

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

@@ -76,13 +76,13 @@ export function validateI18nSurfaceKeys(features) {
             if (isFrameworkOwnedI18nKey(key))
                 continue;
             if (!hasDefinedTranslation(defined, key)) {
-                throw new Error(`[i18n] Feature "${feature.name}": required translation key missing: "${key}"`);
+                throw new Error(`[i18n] Feature "${feature.name}": required translation key missing: "${key}". Add it via r.translations(...) in this feature.`);
             }
         }
     }
     for (const key of requiredKeysFromGeneratedConfigHub(generatedConfigHub)) {
         if (!hasDefinedTranslation(defined, key)) {
-            throw new Error(`[i18n] Settings-Hub: required translation key missing: "${key}"`);
+            throw new Error(`[i18n] Settings-Hub: required translation key missing: "${key}". Add it via r.translations(...) in the owning feature.`);
         }
     }
 }

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

@@ -83,7 +83,7 @@ export function validateNavCycles(allNavQns) {
     const stack = new Set();
     function visit(qualified, path) {
         if (stack.has(qualified)) {
-            throw new Error(`[Kumiko Nav] Nav entry parent cycle detected: ${[...path, qualified].join(" → ")}`);
+            throw new Error(`[Kumiko Nav] Nav entry parent cycle detected: ${[...path, qualified].join(" → ")}. Change or remove the parent of one entry in the cycle.`);
         }
         // skip: already visited — cycle-detection only needs to traverse each
         // node once, and the `stack` check above catches any actual cycles

package/dist/engine/boot-validator/pii-retention.js

@@ -48,9 +48,9 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
     const where = `[Feature ${featureName}] Field "${fieldName}" on entity "${entityName}"`;
     if (field.type === "embedded") {
         for (const [subName, subField] of Object.entries(field.schema)) {
-            if (subField.writeOnly === true) {
+            if ("writeOnly" in subField && subField.writeOnly === true) {
                 // @cast-boundary schema-walk
-                throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields.`);
+                throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields. Remove writeOnly from the sub-field or declare it on a top-level text field.`);
             }
         }
         // skip: embedded fields carry no writeOnly of their own; sub-fields are checked above
@@ -61,7 +61,7 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
     if (flags.writeOnly !== true)
         return;
     if (field.type !== "text") {
-        throw new Error(`${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields.`);
+        throw new Error(`${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields. Use a text field or remove writeOnly.`);
     }
     if (field.sensitive !== true) {
         throw new Error(`${where} declares { writeOnly: true } without { sensitive: true } — add find: "secret" (ciphertext at rest, stripped from event echoes).`);
@@ -69,7 +69,7 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
     for (const flag of WRITE_ONLY_FORBIDDEN_FLAGS) {
         const value = flags[flag];
         if (value !== undefined && value !== false) {
-            throw new Error(`${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up.`);
+            throw new Error(`${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up. Remove either writeOnly or the conflicting flag.`);
         }
     }
 }
@@ -89,7 +89,7 @@ function validatePersonalJsonbField(featureName, entityName, entity, fieldName,
     const flags = field; // @cast-boundary schema-walk
     for (const flag of JSONB_PERSONAL_FORBIDDEN_FLAGS) {
         if (flags[flag] !== undefined && flags[flag] !== false) {
-            throw new Error(`${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}.`);
+            throw new Error(`${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}. Remove the ${flag} flag or the personal annotation.`);
         }
     }
     const index = entity.indexes?.find((def) => def.columns.includes(fieldName));
@@ -151,7 +151,7 @@ export function validatePiiAndRetention(feature) {
             // zweite (deterministische!) Kopie ohne Nutzen.
             if (annot.lookupable === true) {
                 if (field.type !== "text") {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") but has type "${field.type}" — blind-index equality lookups only apply to text fields.`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") but has type "${field.type}" — blind-index equality lookups only apply to text fields. Use a text field or set find: "none".`);
                 }
                 if (annotCount === 0) {
                     throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") without a subject annotation (personal: "self" / "tenant" / { of: "<field>" }). Plaintext fields don't need a blind index — add personal or set find: "none".`);
@@ -188,7 +188,7 @@ export function validatePiiAndRetention(feature) {
             if (annot.userOwned) {
                 const ownerName = annot.userOwned.ownerField;
                 if (!ownerName || typeof ownerName !== "string") {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has personal: { of: ... } without an owner field name`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has personal: { of: ... } without an owner field name. Pass the name of the owner field: personal: { of: "<ownerField>" }.`);
                 }
                 const ownerField = fieldsByName[ownerName];
                 if (!ownerField) {
@@ -205,7 +205,7 @@ export function validatePiiAndRetention(feature) {
                 }
                 const { whenAbsent } = annot.userOwned;
                 if (whenAbsent !== undefined && whenAbsent !== "tenant") {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" (no plaintext fallback for stored PII).`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant".`);
                 }
                 if (ownerField.required !== true && whenAbsent === undefined) {
                     throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" is personal: { of: "${ownerName}" }, but "${ownerName}" is not required — rows without an owner would fail to encrypt (SubjectResolutionError, HTTP 500) on update, delete and forget. Declare { personal: { of: "${ownerName}", whenAbsent: "tenant" } } to encrypt those rows under the tenant key, or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`);
@@ -259,7 +259,7 @@ export function validatePiiAndRetention(feature) {
         if (retention) {
             if (!KEEP_FOR_PATTERN.test(retention.keepFor)) {
                 // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                console.warn(`[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.keepFor="${retention.keepFor}" hat ungueltiges Format. Erwartet: <Zahl><h|d|w|m|y> (z.B. "30d", "10y", "6m"). Cleanup-Job (Sprint 2) wird das nicht parsen koennen.`);
+                console.warn(`[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.keepFor="${retention.keepFor}" has an invalid format. Expected: <number><h|d|w|m|y> (e.g. "30d", "10y", "6m"). The cleanup job cannot parse anything else; fix keepFor.`);
             }
             if (retention.reference !== undefined) {
                 const refName = retention.reference;

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

@@ -32,7 +32,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers) {
     const prefix = `[projectionList] Feature "${feature.name}" screen "${screen.id}"`;
     const schema = queryHandlers.get(screen.query)?.schema;
     if (screen.searchable === true && !schemaAccepts(schema, "search")) {
-        throw new Error(`${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema`);
+        throw new Error(`${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema. Add a "search" field to the query schema or remove searchable: true.`);
     }
     if (screen.searchable === false &&
         schemaAccepts(schema, "search") &&
@@ -52,7 +52,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers) {
     const searchActive = screen.searchable !== false && schemaAccepts(schema, "search");
     const sortActive = schemaAccepts(schema, "sort");
     if ((searchActive || sortActive) && screen.defaultSort === undefined) {
-        throw new Error(`${prefix}: defaultSort required when search or sort is active`);
+        throw new Error(`${prefix}: defaultSort required when search or sort is active. Set defaultSort: { field, direction }.`);
     }
     validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
     validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
@@ -97,7 +97,7 @@ function validateProjectionListDateRangeFacets(prefix, screen, schema) {
             continue;
         if (facet.params.from === facet.params.to) {
             throw new Error(`${prefix}: dateRange facet on "${facet.field}" names the same param ` +
-                `"${facet.params.from}" for both bounds.`);
+                `"${facet.params.from}" for both bounds. Use two different param names for from and to.`);
         }
         for (const param of [facet.params.from, facet.params.to]) {
             if (RESERVED_LIST_PAYLOAD_KEYS.has(param)) {
@@ -106,7 +106,7 @@ function validateProjectionListDateRangeFacets(prefix, screen, schema) {
             }
             if (usedParams.has(param)) {
                 throw new Error(`${prefix}: dateRange facet on "${facet.field}" names "${param}" which another dateRange ` +
-                    `facet on this screen already uses — the facets would overwrite each other's bound.`);
+                    `facet on this screen already uses — the facets would overwrite each other's bound. Give each dateRange facet its own param names.`);
             }
             usedParams.add(param);
             if (schemaAccepts(schema, param))
@@ -144,7 +144,7 @@ function validateRelatedListSearchable(prefix, section, schema) {
     // skip: not searchable, or the schema already accepts search — nothing to reject.
     if (section.searchable !== true || schemaAccepts(schema, "search"))
         return;
-    throw new Error(`${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema`);
+    throw new Error(`${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema. Add a "search" field to the query schema or remove searchable: true.`);
 }
 function validateRelatedListFacets(prefix, section, schema) {
     // skip: no facets declared — nothing to reject.

package/dist/engine/boot-validator/query-output-columns.js

@@ -73,7 +73,7 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
     const prefix = `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`;
     // @wrapper-known semantic-alias
     const checkHeaderField = (part, field) => {
-        checkFieldExists(recordShape, field, () => `${prefix} header.${part} references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+        checkFieldExists(recordShape, field, () => `${prefix} header.${part} references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     };
     if (screen.header !== undefined) {
         checkHeaderField("title", screen.header.title);
@@ -103,11 +103,11 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
     }
     if (screen.recordTitleField !== undefined) {
         const field = screen.recordTitleField;
-        checkFieldExists(recordShape, field, () => `${prefix} recordTitleField references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+        checkFieldExists(recordShape, field, () => `${prefix} recordTitleField references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     }
     for (const metric of screen.metrics ?? []) {
         const field = metricField(metric);
-        checkFieldExists(recordShape, field, () => `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+        checkFieldExists(recordShape, field, () => `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     }
     checkDetailSectionFields(recordShape, prefix, screen);
     checkRelatedListToolbarActionFields(recordShape, featureName, screenId, screen);
@@ -119,13 +119,13 @@ function checkDetailSectionFields(recordShape, prefix, screen) {
     for (const section of screen.layout.sections) {
         const countField = "countField" in section ? section.countField : undefined;
         if (countField !== undefined) {
-            checkFieldExists(recordShape, countField, () => `${prefix} section "${section.title ?? "(untitled)"}" countField references field "${countField}" which is not present in query "${screen.query}"'s outputSchema.`);
+            checkFieldExists(recordShape, countField, () => `${prefix} section "${section.title ?? "(untitled)"}" countField references field "${countField}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
         }
         if (section.kind !== undefined && section.kind !== "fields")
             continue;
         for (const entry of sectionFieldSpecs(section)) {
             const field = typeof entry === "string" ? entry : entry.field;
-            checkFieldExists(recordShape, field, () => `${prefix} section "${section.title ?? section.id ?? "(untitled)"}" references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+            checkFieldExists(recordShape, field, () => `${prefix} section "${section.title ?? section.id ?? "(untitled)"}" references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
         }
     }
 }
@@ -158,7 +158,7 @@ function checkDashboardStatPanelFields(queryHandlers, featureName, screenId, pan
         // skip: this stat-panel field slot is optional and wasn't declared — nothing to validate
         if (field === undefined)
             return;
-        checkFieldExists(recordShape, field, () => `${prefix} ${part} references field "${field}" which is not present in query "${panel.query}"'s outputSchema.`);
+        checkFieldExists(recordShape, field, () => `${prefix} ${part} references field "${field}" which is not present in query "${panel.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     };
     checkPanelField("valueField", panel.valueField);
     checkPanelField("subField", panel.subField);
@@ -174,7 +174,7 @@ function checkVisibleWhenField(queryHandlers, visibleWhen, owner) {
     if (visibleWhen === undefined)
         return;
     const { query, field } = visibleWhen;
-    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `${owner} visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema.`);
+    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `${owner} visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
 }
 function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen) {
     for (const panel of screen.panels) {

package/dist/engine/boot-validator/screens.d.ts

@@ -1,6 +1,6 @@
 import type { IconKey } from "@cosmicdrift/kumiko-types/nav-icon";
 import type { ConfigKeyDefinition, FeatureDefinition } from "../types/index.js";
-import type { DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, ToolbarAction } from "../types/screen.js";
+import type { ActionFormScreenDefinition, DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction } from "../types/screen.js";
 export declare function rowFieldExtractorKeys(params: RowFieldExtractor): readonly string[];
 export declare function readsNavigateParamsAsFormPrefill(target: ScreenDefinition, explicitEntityId: string | undefined, sourceScreenEntity: string | undefined): boolean;
 export declare function validateActionHasIcon(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit" | "entityList" | "projectionList", context: string, action: {
@@ -13,6 +13,7 @@ export declare function validateScreenShortIdCollisions(screensByShortId: Readon
     readonly screen: ScreenDefinition;
 }>>): void;
 export declare function resolveScreenTargetQn(featureName: string, target: string): string;
+export declare function validateDrawerPrefillKeys(where: string, targetLabel: "drawer-target" | "navigate-target", targetScreenId: string, target: ActionFormScreenDefinition | SecretMintScreenDefinition, params: RowFieldExtractor): void;
 export declare function validateScreens(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, allWriteHandlerQns: ReadonlySet<string>, allScreenQns: ReadonlySet<string>, configKeyDefsByQn: ReadonlyMap<string, ConfigKeyDefinition>, screensByShortId: ReadonlyMap<string, ReadonlyArray<{
     readonly featureName: string;
     readonly screen: ScreenDefinition;