@cosmicdrift/kumiko-framework 0.360.0 → 0.361.0

package/dist/db/queries/backfill-pii.js

@@ -8,7 +8,7 @@
 //   - entity lifecycle events (<entity>.created/updated/deleted/forgotten/
 //     restored) for every entity with PII subject annotations — generic over
 //     subject kind (user/tenant/record, fw#2790), since it goes through the
-//     same collectPiiSubjectFields/resolveSubjectForField the live write
+//     same collectPiiEncryptedFields/resolveSubjectForField the live write
 //     path uses
 //   - custom events from the event-PII catalog (r.defineEvent piiFields) —
 //     user/tenant/self subjects, via the same resolveEventSubject the live
@@ -41,6 +41,9 @@
 //      unresolvable (hard-deleted aggregate, no projection) → PII_ERASED_SENTINEL.
 //   Stages 2 and 3 are opt-in and off by default; without them an
 //   unresolvable subject still fails loud into `failures`, as before.
+//   4. owner re-key ({@link PiiBackfillOptions.rekeyTenantKeyedOwnerFields}) —
+//   tenant-keyed ciphertext of a userOwned field moves under the user the
+//   strict chain (stages 1+2, never whenAbsent) names.
 //
 // Snapshots of touched aggregates are dropped per batch (they may cache
 // plaintext); the next snapshotting load recreates them. AFTER a run, rebuild the
@@ -50,8 +53,8 @@ import { asRawClient } from "../../bun-db/index.js";
 import { quoteIdent } from "../../crypto/ciphertext-pattern.js";
 import { configuredEventPiiCatalog } from "../../crypto/event-pii.js";
 import { isLocalKeyKmsAdapter, KeyErasedError, KeyNotFoundError, } from "../../crypto/kms-adapter.js";
-import { configuredPiiSubjectKms, encryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../../crypto/pii-field-encryption.js";
-import { collectPiiSubjectFields, resolveEventSubject, resolveSubjectForField, SubjectResolutionError, } from "../../crypto/subject-resolver.js";
+import { configuredPiiSubjectKms, decryptPiiValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, piiCiphertextSubject, } from "../../crypto/pii-field-encryption.js";
+import { collectPiiEncryptedFields, resolveEventSubject, resolveSubjectForField, SubjectResolutionError, } from "../../crypto/subject-resolver.js";
 import { resolveTableName } from "../entity-table-meta.js";
 import { tableExists } from "../schema-inspection.js";
 import { toSnakeCase } from "../table-builder.js";
@@ -59,7 +62,7 @@ const LIFECYCLE_VERBS = ["created", "updated", "deleted", "restored", "forgotten
 function collectPiiTargets(registry) {
     const entityTargets = new Map();
     for (const [name, entity] of registry.getAllEntities()) {
-        const piiFields = collectPiiSubjectFields(entity);
+        const piiFields = collectPiiEncryptedFields(entity);
         if (piiFields.length > 0)
             entityTargets.set(name, { entity, piiFields });
     }
@@ -83,6 +86,7 @@ export async function backfillEventPiiEncryption(db, registry, options = {}) {
         updatedEvents: 0,
         encryptedFields: 0,
         erasedFields: 0,
+        rekeyedFields: 0,
         ownerFromProjection: 0,
         erasedUnresolvable: 0,
         deletedSnapshots: 0,
@@ -100,6 +104,7 @@ export async function backfillEventPiiEncryption(db, registry, options = {}) {
         total.updatedEvents += batch.updatedEvents;
         total.encryptedFields += batch.encryptedFields;
         total.erasedFields += batch.erasedFields;
+        total.rekeyedFields += batch.rekeyedFields;
         total.ownerFromProjection += batch.ownerFromProjection;
         total.erasedUnresolvable += batch.erasedUnresolvable;
         total.deletedSnapshots += batch.deletedSnapshots;
@@ -127,6 +132,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
         updatedEvents: 0,
         encryptedFields: 0,
         erasedFields: 0,
+        rekeyedFields: 0,
         ownerFromProjection: 0,
         erasedUnresolvable: 0,
         deletedSnapshots: 0,
@@ -168,6 +174,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
                 continue;
             result.encryptedFields += outcome.encrypted;
             result.erasedFields += outcome.erased;
+            result.rekeyedFields += outcome.rekeyed;
             result.ownerFromProjection += outcome.ownerFromProjection;
             result.erasedUnresolvable += outcome.erasedUnresolvable;
             if (!options.dryRun) {
@@ -245,7 +252,11 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
                 for (const projectionRow of projectionRows) {
                     const id = projectionRow["id"];
                     if (typeof id === "string") {
-                        ownersById.set(id, projectionRowToCamel(target.entity, projectionRow));
+                        const rowTenantId = projectionRow["tenant_id"];
+                        ownersById.set(id, {
+                            tenantId: typeof rowTenantId === "string" ? rowTenantId : undefined,
+                            fields: projectionRowToCamel(target.entity, projectionRow),
+                        });
                     }
                 }
             }
@@ -254,15 +265,22 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
         return byType;
     }
     async function transformEvent(row, projectionOwners) {
-        const counters = { encrypted: 0, erased: 0, ownerFromProjection: 0, erasedUnresolvable: 0 };
+        const counters = {
+            encrypted: 0,
+            erased: 0,
+            rekeyed: 0,
+            ownerFromProjection: 0,
+            erasedUnresolvable: 0,
+        };
         const payload = structuredClone(row.payload);
+        const tenantId = row.tenant_id; // @cast-boundary db-read — tenant_id column is the branded TenantId
         const catalogFields = eventCatalog.get(row.type);
         if (catalogFields) {
             for (const [field, spec] of Object.entries(catalogFields)) {
                 let subject;
                 try {
                     subject = resolveEventSubject(field, spec, payload, {
-                        tenantId: row.tenant_id, // @cast-boundary db-read — tenant_id column is the branded TenantId
+                        tenantId,
                         aggregateType: row.aggregate_type,
                         aggregateId: row.aggregate_id,
                     });
@@ -284,9 +302,10 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
             const target = entityTargets.get(row.aggregate_type);
             if (!target || !isLifecycleEventOf(row.type, row.aggregate_type))
                 return null;
-            await applyEntityLifecycleFields(target, projectionOwners?.get(row.aggregate_id));
+            const ownerRow = projectionOwnerRowOfTenant(projectionOwners?.get(row.aggregate_id), row.tenant_id);
+            await applyEntityLifecycleFields(target, ownerRow);
         }
-        if (counters.encrypted === 0 && counters.erased === 0)
+        if (counters.encrypted === 0 && counters.erased === 0 && counters.rekeyed === 0)
             return null;
         return { payload, ...counters };
         function bump(outcome) {
@@ -309,14 +328,18 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
                         continue;
                     if (typeof value !== "string")
                         continue;
-                    // Already-ciphertext/sentinel fields must never enter owner
-                    // resolution — an unresolvable owner on an already-handled field
+                    // Already-ciphertext/sentinel fields must never enter the encrypt/erase
+                    // owner resolution — an unresolvable owner on an already-handled field
                     // must stay untouched, not get erased by stage 3.
-                    if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL)
+                    if (isPiiCiphertext(value)) {
+                        if (options.rekeyTenantKeyedOwnerFields) {
+                            await rekeyField(target.entity, section, field, value, subjectSource, ownerFallback, projectionOwnerRow);
+                        }
+                        continue;
+                    }
+                    if (value === PII_ERASED_SENTINEL)
                         continue;
-                    const resolution = resolveOwnerSubject(target.entity, field, subjectSource, ownerFallback, projectionOwnerRow, 
-                    // @cast-boundary db-read — tenant_id column is the branded TenantId
-                    row.tenant_id, row.aggregate_type);
+                    const resolution = resolveOwnerSubject(target.entity, field, subjectSource, ownerFallback, projectionOwnerRow, tenantId, row.aggregate_type);
                     if (resolution.kind === "unannotated")
                         continue;
                     if (resolution.kind === "unresolved") {
@@ -335,6 +358,32 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
                 }
             }
         }
+        async function rekeyField(entity, section, field, ciphertext, subjectSource, ownerFallback, projectionOwnerRow) {
+            const rekey = await rekeyTenantKeyedValue({
+                subjectKms,
+                kmsCtx,
+                dryRun: options.dryRun === true,
+                isForgottenSubject: (subject) => isForgottenSubject(subject, row.aggregate_id),
+                predictOutcome: predictEncryptOutcome,
+            }, {
+                entity,
+                field,
+                ciphertext,
+                tenantId,
+                aggregateType: row.aggregate_type,
+                subjectSource,
+                ownerFallback,
+                projectionOwnerRow,
+            });
+            if (rekey.kind === "rekeyed") {
+                section[field] = rekey.value;
+                counters.rekeyed++;
+            }
+            else if (rekey.kind === "erased") {
+                section[field] = PII_ERASED_SENTINEL;
+                counters.erased++;
+            }
+        }
         async function encryptField(section, field, subject) {
             const value = section[field];
             if (value === null || value === undefined)
@@ -399,6 +448,62 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
         return scanCache.destroyedTenants;
     }
 }
+// aggregate_id is only unique per tenant: another tenant's projection row must not name the owner.
+function projectionOwnerRowOfTenant(owner, tenantId) {
+    if (owner === undefined)
+        return undefined;
+    return owner.tenantId === undefined || owner.tenantId === tenantId ? owner.fields : undefined;
+}
+function isPlainUserOwnedField(entity, field) {
+    const fieldDef = entity.fields[field];
+    if (fieldDef === undefined || !("userOwned" in fieldDef) || fieldDef.userOwned === undefined) {
+        return false;
+    }
+    return !("recordOwned" in fieldDef && fieldDef.recordOwned === true);
+}
+// Stage 4. In dryRun the "rekeyed" value is the untouched ciphertext (nothing is written).
+async function rekeyTenantKeyedValue(deps, target) {
+    const { entity, field, ciphertext } = target;
+    if (!isPlainUserOwnedField(entity, field) || !isTenantKeyedUnder(ciphertext, target.tenantId)) {
+        return { kind: "unchanged" };
+    }
+    const resolution = resolveOwnerSubject(entity, field, target.subjectSource, target.ownerFallback, target.projectionOwnerRow, target.tenantId, target.aggregateType);
+    if (resolution.kind !== "resolved" || resolution.subject.kind !== "user") {
+        return { kind: "unchanged" };
+    }
+    const userSubject = resolution.subject;
+    if (await deps.isForgottenSubject(userSubject))
+        return { kind: "erased" };
+    if (deps.dryRun) {
+        return (await deps.predictOutcome(userSubject)) === "erased"
+            ? { kind: "erased" }
+            : { kind: "rekeyed", value: ciphertext };
+    }
+    const plaintext = await decryptPiiValueForSubject(deps.subjectKms, ciphertext, deps.kmsCtx, field);
+    if (plaintext === PII_ERASED_SENTINEL)
+        return { kind: "erased" };
+    try {
+        const value = await encryptPiiValueForSubject(deps.subjectKms, userSubject, plaintext, deps.kmsCtx, field);
+        return { kind: "rekeyed", value };
+    }
+    catch (e) {
+        if (e instanceof KeyErasedError)
+            return { kind: "erased" };
+        throw e;
+    }
+}
+// Only the row's own tenant key counts: another tenant's or a user's key is
+// never decrypted here.
+function isTenantKeyedUnder(ciphertext, tenantId) {
+    try {
+        const subject = piiCiphertextSubject(ciphertext);
+        return subject.kind === "tenant" && subject.tenantId === tenantId;
+    }
+    catch {
+        // skip: a malformed ciphertext prefix is not ours to re-key
+        return false;
+    }
+}
 function attemptResolve(entity, field, source, opts) {
     try {
         return { ok: true, subject: resolveSubjectForField(entity, field, source, opts) };

package/dist/db/table-builder.d.ts

@@ -137,7 +137,9 @@ type ColumnsForField<K extends string, F extends FieldDefinition> = F extends {
     readonly [P in K]: NullCol<string>;
 } : F extends {
     type: "files" | "images";
-} ? Record<never, never> : never;
+} ? {
+    readonly [P in K]: Col<readonly string[]>;
+} : never;
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 type ColumnsForEntity<F extends FieldsMap> = UnionToIntersection<{
     [K in keyof F & string]: ColumnsForField<K, F[K]>;

package/dist/db/table-builder.js

@@ -12,7 +12,7 @@ export function physicalColumnName(table, field) {
     return table[field]?.name ?? toSnakeCase(field);
 }
 // Returns column(s) for a field. Most fields return a single entry,
-// money returns two (amount + currency), files/images return none.
+// money returns two (amount + currency).
 //
 // `required: true` auf einem FieldDefinition mappt **immer** auf .notNull()
 // in der DB-Spalte. Die alte Implementation hat das nur für reference-
@@ -173,11 +173,8 @@ function fieldToColumns(name, field, entity) {
         }
         case "files":
         case "images":
-            // Multi file: no column in entity table, resolved via FileRef table
-            // over (entityType, entityId, fieldName). A bridge-table with
-            // CASCADE + sort-order is a later improvement; today plural files
-            // live entirely in fileRefsTable.
-            return {};
+            // Ordered fileRef UUID array, same shape as multiSelect: never null.
+            return { [name]: jsonb(snakeName).default([]).notNull() };
         default:
             assertUnreachable(field, "field type");
     }

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

@@ -23,6 +23,7 @@ export declare function validateEntitySelectAvailabilityQuery(feature: FeatureDe
 export declare function validateEntitySelectConditionalOptions(feature: FeatureDefinition): void;
 export declare function validateMultiSelectFields(feature: FeatureDefinition): void;
 export declare function validateImageVariants(feature: FeatureDefinition): void;
+export declare function validateLockedWhen(feature: FeatureDefinition): void;
 export declare function validateTransitions(feature: FeatureDefinition): void;
 export declare function validateExtendSchemaCollisions(feature: FeatureDefinition): void;
 export declare function validateDerivedFieldCollisions(feature: FeatureDefinition): void;

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

@@ -341,7 +341,7 @@ export function validateEntityIndexes(feature) {
                         field.type === "images" ||
                         (field.type === "reference" && field.multiple === true))) {
                     throw new Error(`${where}: column "${col}" is a multi-value field (${field.type}) — ` +
-                        `these have no DB column to index on. Use a single-value field or remove from the index.`);
+                        `a jsonb array cannot be indexed as a column. Use a single-value field or remove from the index.`);
                 }
                 if (field && field.type === "longText") {
                     // longText ist semantisch "potentially-megabytes content" — ein
@@ -857,6 +857,43 @@ export function validateImageVariants(feature) {
         }
     }
 }
+// --- lockedWhen validation ---
+function isCiphertextAtRest(field) {
+    return (("pii" in field && field.pii === true) ||
+        ("userOwned" in field && field.userOwned !== undefined) ||
+        ("tenantOwned" in field && field.tenantOwned === true) ||
+        ("recordOwned" in field && field.recordOwned === true) ||
+        ("encrypted" in field && field.encrypted === true));
+}
+// Types whose stored value is a plain scalar that the condition's `===` can match.
+// Compound, temporal, array and bigint columns come back in another shape than the
+// literal an author writes, so such a lock would silently never hold.
+const LOCKABLE_FIELD_TYPES = new Set([
+    "text",
+    "longText",
+    "boolean",
+    "select",
+    "number",
+    "reference",
+]);
+export function validateLockedWhen(feature) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+        const { lockedWhen } = entity;
+        if (typeof lockedWhen !== "object")
+            continue;
+        const where = `Entity "${entityName}" in feature "${feature.name}": lockedWhen field "${lockedWhen.field}"`;
+        const field = entity.fields[lockedWhen.field];
+        if (!field) {
+            throw new Error(`${where} is not a field of the entity (known: ${Object.keys(entity.fields).sort().join(", ")}).`);
+        }
+        if (isCiphertextAtRest(field)) {
+            throw new Error(`${where} is personal or encrypted — the lock condition is evaluated on the stored value, which is ciphertext. Use a plaintext field.`);
+        }
+        if (!LOCKABLE_FIELD_TYPES.has(field.type)) {
+            throw new Error(`${where} has type "${field.type}", which does not store a plain scalar the condition can compare. Use a text, select, boolean, number or reference field.`);
+        }
+    }
+}
 // --- Transition validation ---
 export function validateTransitions(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {

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

@@ -10,7 +10,7 @@ import { validateFeatureBootChecks } from "./boot-check.js";
 import { validateCardMetaOverflow } from "./card-meta-overflow.js";
 import { validateCircularDeps, validateConfigKeyAllowPerRequest, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, validateConfigReads, warnOnToggleableDependencies, } from "./config-deps.js";
 import { collectDetailForScreens } from "./detail-screens.js";
-import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectAvailabilityQuery, validateEntitySelectConditionalOptions, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
+import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectAvailabilityQuery, validateEntitySelectConditionalOptions, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateLockedWhen, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
 import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
 import { validateGlobalTenancyEntities } from "./global-tenancy.js";
@@ -181,6 +181,7 @@ export function validateBoot(rawFeatures, options) {
         validateReferenceFields(feature, featureMap, queryHandlerQns);
         validateHandlerFieldReferences(feature, featureMap);
         validateTransitions(feature);
+        validateLockedWhen(feature);
         validateExtensionUsages(feature, extensionProviders);
         validateExtendSchemaCollisions(feature);
         validateDerivedFieldCollisions(feature);

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

@@ -97,6 +97,9 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
         }
         if (screen.header.status !== undefined)
             checkHeaderField("status", screen.header.status);
+        if (screen.header.statusToneField !== undefined) {
+            checkHeaderField("statusToneField", screen.header.statusToneField);
+        }
     }
     if (screen.recordTitleField !== undefined) {
         const field = screen.recordTitleField;

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

@@ -3,7 +3,7 @@ import type { ConfigKeyDefinition, FeatureDefinition } from "../types/index.js";
 import type { DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, 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", context: string, action: {
+export declare function validateActionHasIcon(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit" | "entityList" | "projectionList", context: string, action: {
     readonly id: string;
     readonly icon?: IconKey;
 }): void;

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

@@ -32,6 +32,44 @@ function validateAtMostOneRowClick(featureName, screenId, screenType, rowActions
 // literal `required: true` (screen-spec override or entity-level default).
 // A dynamic FieldCondition depends on runtime form values and can't be
 // evaluated at boot; buildFormSchema() silently skips presence-checking it.
+// `embeddedList` and `prefill` only make sense on field types that support them;
+// a misplaced spec would otherwise be a silent no-op.
+function validateEditFieldExtras(featureName, screenId, entityDef, fieldSpec) {
+    const fieldDef = entityDef.fields[fieldSpec.field];
+    // skip: the field name is not on the entity, other checks report unknown fields
+    if (fieldDef === undefined)
+        return;
+    const where = `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${fieldSpec.field}"`;
+    const listSpec = fieldSpec.embeddedList;
+    if (listSpec !== undefined) {
+        if (fieldDef.type !== "embedded" || fieldDef.multiple !== true) {
+            throw new Error(`${where} sets embeddedList, which only applies to an embedded list ` +
+                `(createEmbeddedListField); the field is type "${fieldDef.type}".`);
+        }
+        for (const cell of listSpec.readOnlyCells ?? []) {
+            if (fieldDef.schema[cell] === undefined) {
+                throw new Error(`${where} embeddedList.readOnlyCells names "${cell}", which is not a sub-field ` +
+                    `(known: ${Object.keys(fieldDef.schema).sort().join(", ")}).`);
+            }
+        }
+    }
+    const prefill = fieldSpec.prefill;
+    // skip: no prefill declared
+    if (prefill === undefined)
+        return;
+    if (prefill.kind === "today") {
+        if (fieldDef.type !== "date") {
+            throw new Error(`${where} prefill "today" needs a date field; the field is type "${fieldDef.type}".`);
+        }
+        // skip: today carries no property, nothing further to check
+        return;
+    }
+    const allowsUserId = fieldDef.type === "text" || fieldDef.type === "reference";
+    if (prefill.property === "id" ? !allowsUserId : fieldDef.type !== "text") {
+        throw new Error(`${where} prefill currentUser.${prefill.property} does not fit a field of type ` +
+            `"${fieldDef.type}" (displayName and email need text; id needs text or a reference).`);
+    }
+}
 function validateNoWidgetRequiredField(featureName, screenId, entityDef, fieldSpec) {
     const fieldDef = entityDef.fields[fieldSpec.field];
     // skip: field doesn't exist or its type already has a widget — nothing to validate.
@@ -648,7 +686,8 @@ function validateFormLayoutSections(featureName, screenId, context, layout, fiel
 // form (fw#2670) carries the same target under `screen` plus the payload
 // field `idFrom`. Shared by actionForm/secretMint (validateInlineFormNavTargets)
 // and entityEdit — same rule, same error message, one place to keep them in sync.
-function validateRedirectTarget(feature, screenId, screenKind, redirect, allScreenQns) {
+function validateRedirectTarget(feature, screenId, screenKind, redirect, lookups) {
+    const { allScreenQns } = lookups;
     const redirectTarget = typeof redirect === "string" ? redirect : redirect.screen;
     if (typeof redirect !== "string" &&
         (typeof redirect.idFrom !== "string" || redirect.idFrom.trim() === "")) {
@@ -674,6 +713,13 @@ function validateRedirectTarget(feature, screenId, screenKind, redirect, allScre
         throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) redirect.idFrom is set but target screen ` +
             `"${redirectTarget}" (${sameFeatureTarget.type}) carries no id — use the plain string form.`);
     }
+    if (typeof redirect !== "string" && redirect.tab !== undefined) {
+        const targetQn = resolveScreenTargetQn(feature.name, redirectTarget);
+        const target = lookups.screensByShortId
+            .get(targetQn.slice(targetQn.lastIndexOf(":") + 1))
+            ?.find((entry) => qualifyEntityName(entry.featureName, "screen", entry.screen.id) === targetQn);
+        validateRowActionNavigateTab(feature.name, screenId, screenKind, "redirect", { kind: "navigate", id: redirectTarget, label: redirectTarget, tab: redirect.tab }, target);
+    }
 }
 // redirect is only honored on record actions; on list/related-list row
 // actions it would be silently dropped, so the author would believe it works.
@@ -686,9 +732,25 @@ function rejectRedirectOnListRowAction(featureName, screenId, screenKind, action
 }
 // A writeHandler record action's redirect (projectionDetail/entityEdit
 // header and section actions) follows the entityEdit.redirect rule.
-function validateRecordActionRedirect(feature, screenId, screenKind, action, allScreenQns) {
+function validateRecordActionRedirect(feature, screenId, screenKind, action, lookups) {
     if (action.kind !== "navigate" && action.kind !== "drawer" && action.redirect !== undefined) {
-        validateRedirectTarget(feature, screenId, screenKind, action.redirect, allScreenQns);
+        validateRedirectTarget(feature, screenId, screenKind, action.redirect, lookups);
+    }
+}
+// "edit" is the default edit action, which only exists when detailFor names
+// the entity; a typo would otherwise silently fall back to the default precedence.
+function validatePrimaryActionTarget(featureName, screenId, screen) {
+    // skip: no declared primaryAction, the default header precedence applies
+    if (screen.primaryAction === undefined)
+        return;
+    const declaredIds = (screen.actions ?? []).map((action) => action.id);
+    const editIsAvailable = screen.detailFor !== undefined;
+    const targetExists = declaredIds.includes(screen.primaryAction) ||
+        (editIsAvailable && screen.primaryAction === "edit");
+    if (!targetExists) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) primaryAction "${screen.primaryAction}" ` +
+            `matches no action — use one of the declared action ids (${declaredIds.join(", ") || "none declared"})` +
+            `${editIsAvailable ? ' or "edit"' : ' ("edit" needs detailFor on this screen)'}.`);
     }
 }
 function validateScreenVisibleWhen(feature, screenId, screen, allScreenQns, featureMap) {
@@ -718,9 +780,10 @@ function validateScreenFallback(feature, screenId, screenType, fallback, allScre
         throw new Error(`${context} fallback "${fallback}" has its own visibleWhen; a fallback must always render.`);
     }
 }
-function validateInlineFormNavTargets(feature, screenId, screen, kind, allScreenQns) {
+function validateInlineFormNavTargets(feature, screenId, screen, kind, lookups) {
+    const { allScreenQns } = lookups;
     if (screen.redirect !== undefined) {
-        validateRedirectTarget(feature, screenId, kind, screen.redirect, allScreenQns);
+        validateRedirectTarget(feature, screenId, kind, screen.redirect, lookups);
     }
     if (typeof screen.cancelTarget === "string") {
         // Same rule as redirect — `false` (no Cancel button) needs no validation.
@@ -729,7 +792,7 @@ function validateInlineFormNavTargets(feature, screenId, screen, kind, allScreen
 }
 // actionForm/secretMint have no entity link, only a write-handler QN +
 // inline fields: checks handler registration, field types, layout refs, and nav targets.
-function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandlerQns, allScreenQns, featureMap) {
+function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandlerQns, lookups, featureMap) {
     validateWriteHandlerRegistered(feature.name, screenId, kind, screen.handler, allWriteHandlerQns);
     // Only a secretMint's own mint step may skip fields/sections entirely
     // (input-less mint, fw#2838) — actionForm always needs at least one field.
@@ -737,7 +800,7 @@ function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandl
     const fieldNames = validateFormFieldsMap(feature.name, screenId, kind, screen.fields, allowEmptyMintForm);
     validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, allowEmptyMintForm && fieldNames.size === 0);
     validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap);
-    validateInlineFormNavTargets(feature, screenId, screen, kind, allScreenQns);
+    validateInlineFormNavTargets(feature, screenId, screen, kind, lookups);
 }
 // SecretMintConfirmStep (fw#2838): an optional proof-of-receipt form rendered
 // on the reveal card in place of the bare acknowledge button (TOTP enrollment:
@@ -965,6 +1028,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
     };
     for (const [screenId, screen] of Object.entries(feature.screens)) {
         validateExplicitListScreenExists(feature.name, screenId, screen, screensByShortId);
+        if ((screen.type === "entityList" || screen.type === "projectionList") &&
+            screen.emptyState?.action !== undefined) {
+            validateActionHasIcon(feature.name, screenId, screen.type, "emptyState action", screen.emptyState.action);
+            validateNavigateActionTab(feature.name, screenId, screen.type, "emptyState action", screen.emptyState.action, navigateLookups);
+        }
         // Output of buildAppSchema, which overwrites it — an authored value would be a silent no-op.
         if ((screen.type === "entityEdit" ||
             screen.type === "actionForm" ||
@@ -1169,7 +1237,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 if (section.actions !== undefined) {
                     for (const action of section.actions) {
                         validateActionHasIcon(feature.name, screenId, "projectionDetail", `section "${sectionLabel}" action`, action);
-                        validateRecordActionRedirect(feature, screenId, "projectionDetail", action, allScreenQns);
+                        validateRecordActionRedirect(feature, screenId, "projectionDetail", action, navigateLookups);
                         validateNavigateActionTab(feature.name, screenId, "projectionDetail", `section "${sectionLabel}" action`, action, navigateLookups);
                     }
                 }
@@ -1277,10 +1345,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             // the row), so the same navigate/writeHandler existence checks as
             // entityList/projectionList apply. `rowClick` is rejected outright —
             // a detail screen has no row to click.
+            validatePrimaryActionTarget(feature.name, screenId, screen);
             if (screen.actions !== undefined) {
                 for (const action of screen.actions) {
                     validateActionHasIcon(feature.name, screenId, "projectionDetail", "action", action);
-                    validateRecordActionRedirect(feature, screenId, "projectionDetail", action, allScreenQns);
+                    validateRecordActionRedirect(feature, screenId, "projectionDetail", action, navigateLookups);
                     if (action.kind === "navigate" && action.rowClick === true) {
                         throw new Error(`[Feature ${feature.name}] Screen "${qualifyEntityName(feature.name, "screen", screenId)}" ` +
                             `(projectionDetail) action "${action.id}" sets rowClick: true — there is no row to ` +
@@ -1381,11 +1450,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             continue;
         }
         if (screen.type === "actionForm") {
-            validateInlineFormScreen(feature, screenId, screen, "actionForm", allWriteHandlerQns, allScreenQns, featureMap);
+            validateInlineFormScreen(feature, screenId, screen, "actionForm", allWriteHandlerQns, navigateLookups, featureMap);
             continue;
         }
         if (screen.type === "secretMint") {
-            validateInlineFormScreen(feature, screenId, screen, "secretMint", allWriteHandlerQns, allScreenQns, featureMap);
+            validateInlineFormScreen(feature, screenId, screen, "secretMint", allWriteHandlerQns, navigateLookups, featureMap);
             if (screen.reveal.fields.length === 0) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (secretMint) has an empty reveal.fields ` +
                     `list — declare at least one field to reveal.`);
@@ -1663,7 +1732,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     const sectionLabel = section.title ?? section.id ?? "(untitled)";
                     for (const action of section.actions) {
                         validateActionHasIcon(feature.name, screenId, "entityEdit", `section "${sectionLabel}" action`, action);
-                        validateRecordActionRedirect(feature, screenId, "entityEdit", action, allScreenQns);
+                        validateRecordActionRedirect(feature, screenId, "entityEdit", action, navigateLookups);
                         validateNavigateActionTab(feature.name, screenId, "entityEdit", `section "${sectionLabel}" action`, action, navigateLookups);
                     }
                 }
@@ -1690,6 +1759,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                         throw new Error(buildUnknownFieldMessage(feature.name, screenId, normalized.field, screen.entity, fieldNames));
                     }
                     validateNoWidgetRequiredField(feature.name, screenId, entityDef, normalized);
+                    validateEditFieldExtras(feature.name, screenId, entityDef, normalized);
                 }
             }
             validateWizardLayout(feature.name, screenId, "entityEdit", screen.layout, featureMap);
@@ -1699,7 +1769,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             // row to click either.
             if (screen.actions !== undefined) {
                 for (const action of screen.actions) {
-                    validateRecordActionRedirect(feature, screenId, "entityEdit", action, allScreenQns);
+                    validateRecordActionRedirect(feature, screenId, "entityEdit", action, navigateLookups);
                     if (action.kind === "navigate" && action.rowClick === true) {
                         throw new Error(`[Feature ${feature.name}] Screen "${qualifyEntityName(feature.name, "screen", screenId)}" ` +
                             `(entityEdit) action "${action.id}" sets rowClick: true — there is no row to click ` +
@@ -1726,8 +1796,13 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     `"${screen.recordTitleField}" is not a field of entity "${screen.entity}" ` +
                     `(known: ${[...fieldNames].sort().join(", ")}).`);
             }
+            if (typeof screen.readOnly === "object" && !fieldNames.has(screen.readOnly.field)) {
+                throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityEdit) readOnly condition field ` +
+                    `"${screen.readOnly.field}" is not a field of entity "${screen.entity}" ` +
+                    `(known: ${[...fieldNames].sort().join(", ")}).`);
+            }
             if (screen.redirect !== undefined) {
-                validateRedirectTarget(feature, screenId, "entityEdit", screen.redirect, allScreenQns);
+                validateRedirectTarget(feature, screenId, "entityEdit", screen.redirect, navigateLookups);
             }
         }
     }

package/dist/engine/define-handler.js

@@ -46,9 +46,7 @@ export function defineWriteHandler(def,
         ...(def.access && { access: def.access }),
         ...(def.description !== undefined && { description: def.description }),
         ...(def.agent && { agent: def.agent }),
-        ...(def.unsafeSkipTransitionGuard && {
-            unsafeSkipTransitionGuard: def.unsafeSkipTransitionGuard,
-        }),
+        ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
         ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),

package/dist/engine/factories.d.ts

@@ -184,6 +184,8 @@ export declare function createEntity<F, const T extends EntityTenancy = "tenant"
     readonly searchWeight?: number;
     readonly defaultCurrency?: string;
     readonly transitions?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+    /** See EntityDefinition.lockedWhen. */
+    readonly lockedWhen?: EntityDefinition["lockedWhen"];
     readonly indexes?: readonly EntityIndexDef[];
     readonly idType?: "serial" | "uuid";
     readonly access?: EntityDefinition["access"];