@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

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

@@ -43,8 +43,9 @@ const WRITE_ONLY_FORBIDDEN_FLAGS = [
     "filterable",
     "lookupable",
 ];
-function validateWriteOnlyField(featureName, entityName, fieldName, field) {
-    const where = `[Feature ${featureName}] Field "${fieldName}" on entity "${entityName}"`;
+function validateWriteOnlyField(input) {
+    const { field } = input;
+    const where = fieldLocation(input);
     if (field.type === "embedded") {
         for (const [subName, subField] of Object.entries(field.schema)) {
             if ("writeOnly" in subField && subField.writeOnly === true) {
@@ -82,8 +83,12 @@ const JSONB_PERSONAL_FORBIDDEN_FLAGS = [
     "lookupable",
 ];
 const CUSTOM_FIELDS_COLUMN = "customFields";
-function validatePersonalJsonbField(featureName, entityName, entity, fieldName, field) {
-    const where = `[Feature ${featureName}] Field "${fieldName}" on entity "${entityName}"`;
+function validatePersonalJsonbField(input) {
+    const { entity, fieldName, field } = input;
+    // skip: only personal jsonb fields are stored as a ciphertext scalar
+    if (field.type !== "jsonb" || input.subjectAnnotationCount === 0)
+        return;
+    const where = fieldLocation(input);
     const reason = "a personal jsonb field is stored as a ciphertext string, so nothing inside it can be indexed, filtered, sorted, searched or merged";
     const flags = field; // @cast-boundary schema-walk
     for (const flag of JSONB_PERSONAL_FORBIDDEN_FLAGS) {
@@ -125,156 +130,229 @@ function validatePersonalJsonbField(featureName, entityName, entity, fieldName,
 // so schema drift is detected during boot.
 export function validatePiiAndRetention(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-        const fieldsByName = entity.fields;
-        const personalOfOwnerFieldNames = ownerFieldNamesReferencedByPersonalOf(fieldsByName);
-        for (const [fieldName, field] of Object.entries(fieldsByName)) {
-            // ResolvedPiiFlags properties are type-level optional. On field defs
-            // not extended via "& ResolvedPiiFlags" (Boolean, Money, Reference,
-            // Embedded), property access returns undefined at runtime. TS
-            // compile-time validation already rejected that case elsewhere →
-            // the cast is safe.
-            const annot = field; // @cast-boundary schema-walk
-            const hasPii = Boolean(annot.pii);
-            const hasUserOwned = Boolean(annot.userOwned);
-            const hasTenantOwned = Boolean(annot.tenantOwned);
-            const hasRecordOwned = Boolean(annot.recordOwned);
-            const annotCount = (hasPii ? 1 : 0) +
-                (hasUserOwned ? 1 : 0) +
-                (hasTenantOwned ? 1 : 0) +
-                (hasRecordOwned ? 1 : 0);
-            if (annotCount > 1) {
-                throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has multiple subject-key annotations (personal: "self" / "tenant" / { of: "<field>" }). Pick one — each field belongs to exactly one subject.`);
-            }
-            if ((field.type === "text" || field.type === "longText") &&
-                annotCount === 0 &&
-                !annot.allowPlaintext &&
-                !annot.subjectRef) {
-                throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" (type "${field.type}") declares no personal stance. Build it with createTextField / createLongTextField and { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false }; false additionally needs { reason: "..." } stating why the value is not personal data.`);
-            }
-            // lookupable: only text fields with a subject annotation are supported. Without
-            // a subject, the value remains plaintext, so a blind index would be a
-            // second deterministic copy without any benefit.
-            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. 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".`);
-                }
-            }
-            // Sensitive fields are stored as table ciphertext in the event log; without
-            // ciphertext at rest, appending the event would write plaintext to the
-            // immutable history.
-            const sensitiveFlags = field; // @cast-boundary schema-walk
-            if (sensitiveFlags.sensitive === true &&
-                annotCount === 0 &&
-                sensitiveFlags.encrypted !== true) {
-                throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { sensitive: true } without ciphertext-at-rest. Since #967 the event log stores sensitive fields as table ciphertext — add a subject annotation (personal: "self" / "tenant" / { of: "<field>" }) or { encrypted: true }.`);
-            }
-            validateWriteOnlyField(feature.name, entityName, fieldName, field);
-            // Sorting reads the projection column — that stays ciphertext, so
-            // sortable + subject annotation stays a boot-fail. searchable is allowed:
-            // the search consumer decrypts into the derived index and forget purges
-            // those docs (see createSearchEventConsumer). sensitive + searchable stays
-            // forbidden (never searchable).
-            {
-                const flags = field; // @cast-boundary schema-walk
-                if (annotCount > 0 && flags.sortable === true) {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation with { sortable: true } — sorting reads the projection column, which is ciphertext at rest. For equality lookups use find: "exact"; drop sortable or keep the field plaintext (personal: false).`);
-                }
-                if (flags.sensitive === true && flags.searchable === true) {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines { sensitive: true } with { searchable: true } — sensitive means ciphertext at rest, never searchable, stripped from event echoes — authorized readers can still read it back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not. To never return the value at all, add { writeOnly: true }.`);
-                }
-            }
-            if (field.type === "jsonb" && annotCount > 0) {
-                validatePersonalJsonbField(feature.name, entityName, entity, fieldName, field);
-            }
-            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. Pass the name of the owner field: personal: { of: "<ownerField>" }.`);
-                }
-                const ownerField = fieldsByName[ownerName];
-                if (!ownerField) {
-                    const known = Object.keys(fieldsByName).sort().join(", ");
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" references personal.of "${ownerName}" but no such field exists. Known fields: ${known}`);
-                }
-                // Text is accepted alongside reference: the ES-framework carries
-                // user ids as plain text columns throughout the bundled features
-                // (user-session.userId, invitation.invitedBy) — there is no
-                // relational FK to point a reference at. Self-referencing
-                // ownerField (the field's own value IS the owner id) rides on this.
-                if (ownerField.type !== "reference" && ownerField.type !== "text") {
-                    throw new Error(`[Feature ${feature.name}] personal.of "${ownerName}" on entity "${entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`);
-                }
-                const { whenAbsent } = annot.userOwned;
-                if (whenAbsent !== undefined && whenAbsent !== "tenant" && whenAbsent !== "self") {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" or "self" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant" (tenant key) or "self" (the row's own record key).`);
-                }
-                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, whenAbsent: "self" to encrypt them under the row's own record key (shreddable per record), or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`);
-                }
-                // Warn when the reference target is not obviously a user. Custom subject
-                // entities (such as HR employees or patients) are allowed but should
-                // be an intentional choice.
-                if (ownerField.type === "reference") {
-                    const refTarget = ownerField.entity;
-                    const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
-                    if (targetEntity !== "user") {
-                        log.warn(`[Feature ${feature.name}] personal.of "${ownerName}" on entity "${entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`);
-                    }
-                }
-            }
-            // PII heuristic: only when no annotation or allowPlaintext marker is set.
-            // Business data with person-like names (for example, company.legalName)
-            // can produce false positives; authors can suppress them with
-            // { personal: false, reason: "is_business_data" }.
-            const noAnnotation = annotCount === 0 && !annot.allowPlaintext;
-            if (noAnnotation) {
-                const lower = fieldName.toLowerCase();
-                if (FILE_FIELD_TYPES.has(field.type)) {
-                    log.warn(`[Feature ${feature.name}] File field "${fieldName}" on entity "${entityName}" has no personal annotation. A forget with strategy "delete" then only severs the uploader link and keeps the binary. If the file holds personal data, mark it { personal: "self" } or { personal: { of: "<ownerField>" } }. If it is business data, set { personal: false, reason: "is_business_data" } to silence.`);
-                }
-                else if (PII_DIRECT_NAME_HINTS.has(lower)) {
-                    log.warn(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a PII-typical name but no personal annotation. If this is PII, mark it { personal: "self", find: ... }. If business data, set { personal: false, reason: "is_business_data" } to silence.`);
-                }
-                else if (PII_USER_OWNED_NAME_HINTS.has(lower)) {
-                    log.warn(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-content-typical name but no personal annotation. If this contains user-generated content, mark it { personal: { of: "<authorIdField>" }, find: ... }. If business data, set { personal: false, reason: "..." } to silence.`);
-                }
-                else if (PII_USER_REFERENCE_NAME_HINTS.has(lower) &&
-                    !annot.subjectRef &&
-                    !personalOfOwnerFieldNames.has(fieldName)) {
-                    log.warn(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`);
-                }
-            }
-        }
-        // --- Entity-level retention ---
-        const retention = entity.retention;
-        if (retention) {
-            if (!KEEP_FOR_PATTERN.test(retention.keepFor)) {
-                log.warn(`[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;
-                if (!fieldsByName[refName] && !FRAMEWORK_TIMESTAMP_FIELDS.has(refName)) {
-                    const known = Object.keys(fieldsByName).sort().join(", ");
-                    const framework = [...FRAMEWORK_TIMESTAMP_FIELDS].sort().join(", ");
-                    throw new Error(`[Feature ${feature.name}] Entity "${entityName}" retention.reference "${refName}" does not exist. Known fields: ${known} — framework-managed timestamps also accepted: ${framework}`);
-                }
-            }
-            if (retention.strategy === "blockDelete") {
-                // blockDelete with no field that can carry `anonymize` is fine;
-                // subjectRef-only entities are covered by the V3 EXT_USER_DATA guard
-                // instead.
-                const entityHasAnonymizableField = entityHasAnonymizableSubjectField(fieldsByName);
-                const hasAnonymize = Object.values(fieldsByName).some((f) => {
-                    const a = f; // @cast-boundary schema-walk
-                    return Boolean(a.anonymize);
-                });
-                if (entityHasAnonymizableField && !hasAnonymize) {
-                    log.warn(`[Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. Once keepFor expires, the data-retention cron anonymizes nothing and the row keeps its PII. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`);
-                }
-            }
-        }
+        validateFieldAnnotations(feature.name, entityName, entity);
+        validateEntityRetention(feature.name, entityName, entity);
+    }
+}
+// Order matters: the first failing rule decides the boot error, and warnings
+// are emitted in this order.
+const FIELD_RULES = [
+    rejectMultipleSubjectAnnotations,
+    rejectTextWithoutPersonalStance,
+    rejectInvalidLookupable,
+    rejectSensitiveWithoutCiphertextAtRest,
+    validateWriteOnlyField,
+    rejectCiphertextSortOrSensitiveSearch,
+    validatePersonalJsonbField,
+    validatePersonalOfOwner,
+    warnOnUnannotatedPersonalName,
+];
+function validateFieldAnnotations(featureName, entityName, entity) {
+    const personalOfOwnerFieldNames = ownerFieldNamesReferencedByPersonalOf(entity.fields);
+    for (const [fieldName, field] of Object.entries(entity.fields)) {
+        const flags = field; // @cast-boundary schema-walk
+        const input = {
+            featureName,
+            entityName,
+            entity,
+            fieldName,
+            field,
+            flags,
+            subjectAnnotationCount: countSubjectAnnotations(flags),
+            personalOfOwnerFieldNames,
+        };
+        for (const rule of FIELD_RULES)
+            rule(input);
+    }
+}
+function countSubjectAnnotations(flags) {
+    return [flags.pii, flags.userOwned, flags.tenantOwned, flags.recordOwned].filter(Boolean).length;
+}
+function fieldLocation(input) {
+    return `[Feature ${input.featureName}] Field "${input.fieldName}" on entity "${input.entityName}"`;
+}
+function rejectMultipleSubjectAnnotations(input) {
+    if (input.subjectAnnotationCount > 1) {
+        throw new Error(`${fieldLocation(input)} has multiple subject-key annotations (personal: "self" / "tenant" / { of: "<field>" }). Pick one — each field belongs to exactly one subject.`);
+    }
+}
+function rejectTextWithoutPersonalStance(input) {
+    const { field, flags } = input;
+    if ((field.type === "text" || field.type === "longText") &&
+        input.subjectAnnotationCount === 0 &&
+        !flags.allowPlaintext &&
+        !flags.subjectRef) {
+        throw new Error(`${fieldLocation(input)} (type "${field.type}") declares no personal stance. Build it with createTextField / createLongTextField and { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false }; false additionally needs { reason: "..." } stating why the value is not personal data.`);
+    }
+}
+// lookupable: only text fields with a subject annotation are supported. Without
+// a subject, the value remains plaintext, so a blind index would be a
+// second deterministic copy without any benefit.
+function rejectInvalidLookupable(input) {
+    // skip: only lookupable fields carry a blind index to validate
+    if (input.flags.lookupable !== true)
+        return;
+    if (input.field.type !== "text") {
+        throw new Error(`${fieldLocation(input)} declares find: "exact" (or "fuzzy") but has type "${input.field.type}" — blind-index equality lookups only apply to text fields. Use a text field or set find: "none".`);
+    }
+    if (input.subjectAnnotationCount === 0) {
+        throw new Error(`${fieldLocation(input)} 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".`);
+    }
+}
+// Sensitive fields are stored as table ciphertext in the event log; without
+// ciphertext at rest, appending the event would write plaintext to the
+// immutable history.
+function rejectSensitiveWithoutCiphertextAtRest(input) {
+    const { flags } = input;
+    if (flags.sensitive === true && input.subjectAnnotationCount === 0 && flags.encrypted !== true) {
+        throw new Error(`${fieldLocation(input)} declares { sensitive: true } without ciphertext-at-rest. Since #967 the event log stores sensitive fields as table ciphertext — add a subject annotation (personal: "self" / "tenant" / { of: "<field>" }) or { encrypted: true }.`);
+    }
+}
+// Sorting reads the projection column — that stays ciphertext, so
+// sortable + subject annotation stays a boot-fail. searchable is allowed:
+// the search consumer decrypts into the derived index and forget purges
+// those docs (see createSearchEventConsumer). sensitive + searchable stays
+// forbidden (never searchable).
+function rejectCiphertextSortOrSensitiveSearch(input) {
+    const { flags } = input;
+    if (input.subjectAnnotationCount > 0 && flags.sortable === true) {
+        throw new Error(`${fieldLocation(input)} combines a subject-key annotation with { sortable: true } — sorting reads the projection column, which is ciphertext at rest. For equality lookups use find: "exact"; drop sortable or keep the field plaintext (personal: false).`);
+    }
+    if (flags.sensitive === true && flags.searchable === true) {
+        throw new Error(`${fieldLocation(input)} combines { sensitive: true } with { searchable: true } — sensitive means ciphertext at rest, never searchable, stripped from event echoes — authorized readers can still read it back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not. To never return the value at all, add { writeOnly: true }.`);
+    }
+}
+function validatePersonalOfOwner(input) {
+    const personalOf = input.flags.userOwned;
+    // skip: only personal: { of } fields reference an owner field
+    if (!personalOf)
+        return;
+    const ownerName = personalOf.ownerField;
+    if (!ownerName || typeof ownerName !== "string") {
+        throw new Error(`${fieldLocation(input)} has personal: { of: ... } without an owner field name. Pass the name of the owner field: personal: { of: "<ownerField>" }.`);
+    }
+    const ownerField = requireOwnerField(input, ownerName);
+    rejectOwnerWithoutRowFallback(input, ownerName, ownerField, personalOf);
+    warnOnNonUserOwnerReference(input, ownerName, ownerField);
+}
+function requireOwnerField(input, ownerName) {
+    const fieldsByName = input.entity.fields;
+    const ownerField = fieldsByName[ownerName];
+    if (!ownerField) {
+        const known = Object.keys(fieldsByName).sort().join(", ");
+        throw new Error(`${fieldLocation(input)} references personal.of "${ownerName}" but no such field exists. Known fields: ${known}`);
+    }
+    // Text is accepted alongside reference: the ES-framework carries
+    // user ids as plain text columns throughout the bundled features
+    // (user-session.userId, invitation.invitedBy) — there is no
+    // relational FK to point a reference at. Self-referencing
+    // ownerField (the field's own value IS the owner id) rides on this.
+    if (ownerField.type !== "reference" && ownerField.type !== "text") {
+        throw new Error(`[Feature ${input.featureName}] personal.of "${ownerName}" on entity "${input.entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`);
+    }
+    return ownerField;
+}
+function rejectOwnerWithoutRowFallback(input, ownerName, ownerField, personalOf) {
+    const { whenAbsent } = personalOf;
+    if (whenAbsent !== undefined && whenAbsent !== "tenant" && whenAbsent !== "self") {
+        throw new Error(`${fieldLocation(input)} declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" or "self" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant" (tenant key) or "self" (the row's own record key).`);
+    }
+    if (ownerField.required !== true && whenAbsent === undefined) {
+        throw new Error(`${fieldLocation(input)} 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, whenAbsent: "self" to encrypt them under the row's own record key (shreddable per record), or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`);
+    }
+}
+// Custom subject entities (such as HR employees or patients) are allowed but
+// should be an intentional choice.
+function warnOnNonUserOwnerReference(input, ownerName, ownerField) {
+    // skip: text owner fields carry a user id by convention, there is no target to check
+    if (ownerField.type !== "reference")
+        return;
+    const refTarget = ownerField.entity;
+    const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
+    if (targetEntity !== "user") {
+        log.warn(`[Feature ${input.featureName}] personal.of "${ownerName}" on entity "${input.entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`);
+    }
+}
+// First match wins. Business data with person-like names (for example,
+// company.legalName) can produce false positives; authors can suppress them
+// with { personal: false, reason: "is_business_data" }.
+const UNANNOTATED_NAME_WARNINGS = [
+    {
+        applies: (input) => FILE_FIELD_TYPES.has(input.field.type),
+        message: (input) => `[Feature ${input.featureName}] File field "${input.fieldName}" on entity "${input.entityName}" has no personal annotation. A forget with strategy "delete" then only severs the uploader link and keeps the binary. If the file holds personal data, mark it { personal: "self" } or { personal: { of: "<ownerField>" } }. If it is business data, set { personal: false, reason: "is_business_data" } to silence.`,
+    },
+    {
+        applies: (_input, lowerName) => PII_DIRECT_NAME_HINTS.has(lowerName),
+        message: (input) => `${fieldLocation(input)} has a PII-typical name but no personal annotation. If this is PII, mark it { personal: "self", find: ... }. If business data, set { personal: false, reason: "is_business_data" } to silence.`,
+    },
+    {
+        applies: (_input, lowerName) => PII_USER_OWNED_NAME_HINTS.has(lowerName),
+        message: (input) => `${fieldLocation(input)} has a user-content-typical name but no personal annotation. If this contains user-generated content, mark it { personal: { of: "<authorIdField>" }, find: ... }. If business data, set { personal: false, reason: "..." } to silence.`,
+    },
+    {
+        applies: (input, lowerName) => PII_USER_REFERENCE_NAME_HINTS.has(lowerName) &&
+            !input.flags.subjectRef &&
+            !input.personalOfOwnerFieldNames.has(input.fieldName),
+        message: (input) => `${fieldLocation(input)} has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${input.entityName}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${input.fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`,
+    },
+];
+function warnOnUnannotatedPersonalName(input) {
+    // skip: an annotation or an explicit plaintext reason already states the field's stance
+    if (input.subjectAnnotationCount > 0 || input.flags.allowPlaintext)
+        return;
+    const lowerName = input.fieldName.toLowerCase();
+    const warning = UNANNOTATED_NAME_WARNINGS.find((candidate) => candidate.applies(input, lowerName));
+    if (warning)
+        log.warn(warning.message(input));
+}
+const RETENTION_RULES = [
+    warnOnInvalidKeepFor,
+    rejectUnknownRetentionReference,
+    warnOnBlockDeleteWithoutAnonymize,
+];
+function validateEntityRetention(featureName, entityName, entity) {
+    const { retention } = entity;
+    // skip: entities without a retention policy have nothing to validate
+    if (!retention)
+        return;
+    const input = {
+        featureName,
+        entityName,
+        fieldsByName: entity.fields,
+        retention,
+    };
+    for (const rule of RETENTION_RULES)
+        rule(input);
+}
+function warnOnInvalidKeepFor({ featureName, entityName, retention }) {
+    if (!KEEP_FOR_PATTERN.test(retention.keepFor)) {
+        log.warn(`[Feature ${featureName}] 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.`);
+    }
+}
+function rejectUnknownRetentionReference(input) {
+    const { featureName, entityName, fieldsByName } = input;
+    const refName = input.retention.reference;
+    // skip: no explicit retention.reference to resolve
+    if (refName === undefined)
+        return;
+    if (!fieldsByName[refName] && !FRAMEWORK_TIMESTAMP_FIELDS.has(refName)) {
+        const known = Object.keys(fieldsByName).sort().join(", ");
+        const framework = [...FRAMEWORK_TIMESTAMP_FIELDS].sort().join(", ");
+        throw new Error(`[Feature ${featureName}] Entity "${entityName}" retention.reference "${refName}" does not exist. Known fields: ${known} — framework-managed timestamps also accepted: ${framework}`);
+    }
+}
+// blockDelete with no field that can carry `anonymize` is fine;
+// subjectRef-only entities are covered by the V3 EXT_USER_DATA guard instead.
+function warnOnBlockDeleteWithoutAnonymize(input) {
+    const { featureName, entityName, fieldsByName } = input;
+    // skip: only blockDelete relies on anonymize once keepFor expires
+    if (input.retention.strategy !== "blockDelete")
+        return;
+    const hasAnonymize = Object.values(fieldsByName).some((f) => {
+        const a = f; // @cast-boundary schema-walk
+        return Boolean(a.anonymize);
+    });
+    if (entityHasAnonymizableSubjectField(fieldsByName) && !hasAnonymize) {
+        log.warn(`[Feature ${featureName}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. Once keepFor expires, the data-retention cron anonymizes nothing and the row keeps its PII. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`);
     }
 }

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

@@ -1,4 +1,4 @@
-import { type FeatureDefinition, type QueryHandlerDef } from "../types/index.ts";
+import type { FeatureDefinition, QueryHandlerDef } from "../types/index.ts";
 export declare function buildQueryHandlerMap(features: readonly FeatureDefinition[]): ReadonlyMap<string, QueryHandlerDef>;
 export declare function validateProjectionListScreens(features: readonly FeatureDefinition[]): void;
 export declare function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void;

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

@@ -1,8 +1,8 @@
 import { isListQueryWithoutSearchableFields, resolveEntityBehindListQuery, } from "../entity-list-searchability.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
-import { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../types/index.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
+import { validateListTableAggregateQuery } from "./list-table-aggregate-query.js";
 import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
 // Sibling to entity-list-screens.ts rather than an extension of it:
@@ -66,6 +66,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers, feature
     }
     validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
     validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
+    validateListTableAggregateQuery({ prefix, ...screen, handler, featureMap });
 }
 // filter sends `payload.filter` — same 422 footgun as facets below
 // if the handler's schema doesn't accept it.
@@ -190,17 +191,6 @@ function validateRelatedListParentFilter(prefix, section, schema, handler, featu
             `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`);
     }
 }
-// A collapsed group without a header has no toggle, so its rows could never be opened.
-function validateRelatedListGroupBy(prefix, section) {
-    const groupBy = section.groupBy;
-    const collapsedKey = groupBy?.collapsedWhen === undefined ? undefined : relatedListGroupKey(groupBy.collapsedWhen);
-    if (groupBy !== undefined &&
-        collapsedKey !== undefined &&
-        relatedListGroupHeaderLabel(groupBy, collapsedKey) === undefined) {
-        throw new Error(`${prefix}: groupBy.collapsedWhen "${collapsedKey}" names a group without a header; ` +
-            `set groupBy.label or groupBy.labels["${collapsedKey}"], or drop collapsedWhen.`);
-    }
-}
 // relatedList sections declare search/facets the same way a projectionList
 // screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
 // auto-merge params into the handler's own Zod schema, so an
@@ -217,7 +207,7 @@ export function validateRelatedListSectionQueries(features) {
         validateRelatedListSearchable(prefix, section, schema);
         validateRelatedListFacets(prefix, section, schema);
         validateRelatedListParentFilter(prefix, section, schema, handler, featureMap);
-        validateRelatedListGroupBy(prefix, section);
+        validateListTableAggregateQuery({ prefix, ...section, handler, featureMap });
     };
     for (const feature of features) {
         for (const screen of Object.values(feature.screens)) {

package/dist/engine/boot-validator/related-list-table-rules.d.ts

@@ -0,0 +1,4 @@
+/** Grouping rules of a relatedList section or entityList.expandableRow, before the shared table checks. */
+export declare function validateRelatedListGroupingRules(prefix: string, section: {
+    readonly table?: unknown;
+}, isExpandableRow: boolean): void;

package/dist/engine/boot-validator/related-list-table-rules.js

@@ -0,0 +1,42 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+const EXPANDABLE_ROW_TABLE_KEYS = new Set(["grouping"]);
+const EXPANDABLE_ROW_REJECTED_GROUPING_KEYS = ["userChoice", "fields"];
+// `groupBy` grouped the loaded page on the client; it is gone, and a screen
+// still carrying it fails at boot instead of silently losing its groups.
+function rejectRemovedGroupBy(prefix, section) {
+    if (Object.hasOwn(section, "groupBy")) {
+        throw new Error(`${prefix} uses groupBy, which was removed. Use table.grouping: { field, label?, labels?, collapsedWhen? }; ` +
+            `groups and counts come from the server, so the bound query must accept aggregate.`);
+    }
+}
+function rejectExpandableRowTableOptions(prefix, table) {
+    if (isPlainObject(table)) {
+        rejectUnsupportedTableKeys(prefix, table);
+        rejectGroupingChoice(prefix, table["grouping"]);
+    }
+}
+function rejectUnsupportedTableKeys(prefix, table) {
+    const unsupported = Object.keys(table).filter((key) => !EXPANDABLE_ROW_TABLE_KEYS.has(key));
+    if (unsupported.length > 0) {
+        throw new Error(`${prefix} supports only table.grouping, not table.${unsupported.join(", table.")}. ` +
+            `Put the other table options on the entityList screen itself.`);
+    }
+}
+function rejectGroupingChoice(prefix, grouping) {
+    const choiceKey = isPlainObject(grouping)
+        ? EXPANDABLE_ROW_REJECTED_GROUPING_KEYS.find((key) => Object.hasOwn(grouping, key))
+        : undefined;
+    if (choiceKey !== undefined) {
+        throw new Error(`${prefix} does not support table.grouping.${choiceKey}: an expanded row has no view menu. ` +
+            `Set a fixed table.grouping.field.`);
+    }
+}
+/** Grouping rules of a relatedList section or entityList.expandableRow, before the shared table checks. */
+export function validateRelatedListGroupingRules(prefix, section, isExpandableRow) {
+    rejectRemovedGroupBy(prefix, section);
+    if (isExpandableRow && Object.hasOwn(section, "bulkActions")) {
+        throw new Error(`${prefix} does not support bulkActions. Put bulkActions on the entityList screen itself.`);
+    }
+    if (isExpandableRow)
+        rejectExpandableRowTableOptions(prefix, section.table);
+}

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

@@ -64,4 +64,5 @@ export type NavigateTargetLookups = {
     }>;
 };
 export declare function validateNavigateActionTab(featureName: string, screenId: string, screenType: NavigateSourceScreenType, actionLabel: string, action: RowAction, lookups: NavigateTargetLookups): void;
+export declare function assertWriteHandlerRegistered(featureName: string, subject: string, handler: string, allWriteHandlerQns: ReadonlySet<string>): void;
 export {};

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

@@ -202,7 +202,7 @@ export function validateScreenNavTarget(featureName, screenId, screenKind, field
 }
 // kind:"drawer" resolves same-feature only — unlike navigate/redirect,
 // which the runtime router resolves app-wide (see the comment on
-// validateScreens below), the drawer mounts the target inline using this
+// buildScreenValidationContext in screens.ts), the drawer mounts the target inline using this
 // feature's schema, so a cross-feature reference could never actually
 // render. Two distinct failure messages: dangling reference vs. wrong
 // screen type. Shared by ToolbarAction and RowAction drawer variants —
@@ -485,3 +485,10 @@ export function validateNavigateActionTab(featureName, screenId, screenType, act
         return;
     resolveRowActionNavigateTarget(featureName, screenId, screenType, actionLabel, action, lookups.allScreenQns, lookups.navTargetShortIds, lookups.screensByShortId, lookups.detailForScreens);
 }
+export function assertWriteHandlerRegistered(featureName, subject, handler, allWriteHandlerQns) {
+    if (!allWriteHandlerQns.has(handler)) {
+        throw new Error(`[Feature ${featureName}] ${subject} handler "${handler}" ` +
+            `is not a registered write-handler. Check the QN spelling (expected ` +
+            `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+    }
+}

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

@@ -1,6 +1,6 @@
 import { DASHBOARD_MIN_REFRESH_SECONDS } from "@cosmicdrift/kumiko-types/screen";
 import { normalizeListColumn } from "../screen-helpers.js";
-import { isRowClickAction, resolveRowActionNavigateTarget, resolveScreenTargetQn, validateActionHasIcon, validateClientActionName, validateRowActionNavigateParams, } from "./screens-actions.js";
+import { assertWriteHandlerRegistered, isRowClickAction, resolveRowActionNavigateTarget, resolveScreenTargetQn, validateActionHasIcon, validateClientActionName, validateRowActionNavigateParams, } from "./screens-actions.js";
 import { assertRefTargetRegistered, validateColumnRendererForm } from "./screens-lists.js";
 // Panel-driven, no entity — structural checks (unique panel ids, non-empty
 // queries/columns/valueField); the query contracts (stat record, points
@@ -68,10 +68,7 @@ export function validateDashboardActions(featureName, screenId, screen, allWrite
                 throw new Error(`${where} sets redirect — a dashboard action stays on the dashboard and refetches ` +
                     `after success. Remove redirect.`);
             }
-            if (!allWriteHandlerQns.has(action.handler)) {
-                throw new Error(`${where} handler "${action.handler}" is not a registered write-handler. Check the QN ` +
-                    `spelling (expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
-            }
+            assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (dashboard) action "${action.id}"`, action.handler, allWriteHandlerQns);
         }
     }
 }

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

@@ -2,7 +2,7 @@ import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs } from "@cosmicdrift/kumik
 import { isKebabSegment } from "../qualified-name.js";
 import { isExtensionEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
 import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
-import { isSensitiveOrPasswordField, validateIdlessSuccessLink, validateRedirectTarget, validateScreenNavTarget, } from "./screens-actions.js";
+import { assertWriteHandlerRegistered, isSensitiveOrPasswordField, validateIdlessSuccessLink, validateRedirectTarget, validateScreenNavTarget, } from "./screens-actions.js";
 // A field type in NO_WIDGET_FIELD_TYPES renders read-only on the auto-wired
 // entityEdit path — a required field the user can never fill would
 // block every save. Only the statically-resolvable case is caught here: a
@@ -208,11 +208,7 @@ function validateWriteHandlerRegistered(featureName, screenId, context, handler,
     if (!handler || typeof handler !== "string") {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) has empty or non-string handler. Set handler to a non-empty handler name.`);
     }
-    if (!allWriteHandlerQns.has(handler)) {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) handler "${handler}" ` +
-            `is not a registered write-handler. Check the QN spelling (expected ` +
-            `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
-    }
+    assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (${context})`, handler, allWriteHandlerQns);
 }
 // Every field entry must carry a `type` discriminator. An author typo
 // (`title: { required: true }` without a type) would otherwise let

package/dist/engine/boot-validator/screens-kind-config-edit.d.ts

@@ -0,0 +1,3 @@
+import type { ConfigEditScreenDefinition } from "../types/screen.ts";
+import { type ScreenValidationContext } from "./screens-kind-shared.ts";
+export declare function validateConfigEditScreen(ctx: ScreenValidationContext, screenId: string, screen: ConfigEditScreenDefinition): void;