@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

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

@@ -1,16 +1,17 @@
+import { createFallbackLogger } from "../../logging/utils.js";
 import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./entity-handler.js";
-// Framework-managed Timestamp-Spalten — dürfen als retention.reference
-// genutzt werden auch wenn nicht in entity.fields deklariert.
+const log = createFallbackLogger("kumiko:boot");
+// Framework-managed timestamp fields may be used as retention.reference
+// even when they are not declared in entity.fields.
 const FRAMEWORK_TIMESTAMP_FIELDS = new Set([
     "createdAt",
     "updatedAt",
     "lastSeenAt",
     "deletedAt",
 ]);
-// Erlaubtes Format fuer retention.keepFor — Zahlen + Suffix (h/d/w/m/y).
-// Echtes Parsen kommt mit dem Cleanup-Job in Sprint 2; Boot-Validator
-// macht nur den Sanity-Check damit Tippfehler ("30days") frueh sichtbar
-// werden statt erst beim ersten Cleanup-Run.
+// Allowed format for retention.keepFor: a number followed by a suffix (h/d/w/m/y).
+// The cleanup job performs the actual parsing; the boot validator only checks
+// the format so typos ("30days") become visible before the first cleanup run.
 const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
 const FILE_FIELD_TYPES = new Set([
     "file",
@@ -19,7 +20,7 @@ const FILE_FIELD_TYPES = new Set([
     "images",
 ]);
 // Excludes subjectRef: its `personal: "ref"` union member structurally
-// forbids `anonymize` (packages/types/src/fields.ts) — #2336.
+// forbids `anonymize` (packages/types/src/fields.ts).
 function hasAnonymizableSubjectField(annot) {
     return Boolean(annot.pii || annot.userOwned || annot.tenantOwned || annot.recordOwned);
 }
@@ -42,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) {
@@ -81,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) {
@@ -100,188 +106,253 @@ function validatePersonalJsonbField(featureName, entityName, entity, fieldName,
 }
 // --- PII / Subject-Key Annotations + Retention validation ---
 //
-// Drei Klassen von Checks:
+// Four classes of checks:
 //
-// 1. Mutual exclusion: pro Field nur EINE der drei Subject-Annotations
-//    (pii / userOwned / tenantOwned). Mehr ist semantisch widersprüchlich
-//    weil pro Field genau ein Subject-Key gehört.
+// 1. Mutual exclusion: each field may have only ONE subject annotation
+//    (pii / userOwned / tenantOwned). Multiple annotations are semantically
+//    contradictory because each field belongs to exactly one subject key.
 //
-// 2. Reference-Integrity: userOwned.ownerField muss auf ein existierendes
-//    reference-Field zeigen (das auf user-Entity zeigen sollte). Erkennt
-//    Tippfehler und Drop-Refactorings beim Boot statt beim ersten
-//    Encrypt-Aufruf.
+// 2. Reference integrity: userOwned.ownerField must refer to an existing
+//    reference field that should target the user entity. This catches typos
+//    and refactors that removed a field during boot instead of at encryption.
 //
-// 3. Heuristik-Warnings: Field-Namen die typischerweise PII enthalten
-//    (email, name, phone, body, etc.) ohne Annotation → Boot-Warning.
-//    Mit `{ personal: false, reason: "<reason>" }` unterdrückbar (geht in Audit).
+// 3. Heuristic warnings: field names that typically contain PII
+//    (email, name, phone, body, etc.) without an annotation produce a boot
+//    warning. `{ personal: false, reason: "<reason>" }` suppresses it and
+//    records the reason in the audit.
 //
-// 4. Retention-Integrity: retention.reference (wenn gesetzt) muss auf
-//    ein bestehendes Field zeigen (oder Framework-Timestamp). retention.
-//    strategy="blockDelete" ohne anonymize-Felder ist sinnlos — User-
-//    Forget kann nichts machen, Warning.
+// 4. Retention integrity: retention.reference, when set, must refer to an
+//    existing field or a framework timestamp. retention.strategy="blockDelete"
+//    without anonymizable fields is ineffective because user forget cannot
+//    remove anything, so it produces a warning.
 //
-// Encrypt/Decrypt-Mechanik landet in Sprint 3 (crypto-shredding); diese
-// Validation greift schon ab Sprint 0 damit Schema-Drift früh auffällt.
+// Encryption and decryption are handled elsewhere; this validation runs early
+// 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 (#818): nur text + nur MIT Subject-Annotation. Ohne
-            // Subject bleibt der Wert eh Klartext — der Blind-Index wäre eine
-            // 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. 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-Felder liegen seit #967 als Tabellen-Ciphertext im Event-
-            // Log — ohne ciphertext-at-rest würde der Append Klartext in die
-            // immutable History schreiben.
-            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 has
-            // been allowed since #1610: 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).`);
-                }
-                // Soft-Warning wenn das reference-target nicht offensichtlich user
-                // ist — custom subject-entities (HR-Mitarbeiter, Patient) sind
-                // erlaubt, müssen aber bewusste Wahl sein.
-                if (ownerField.type === "reference") {
-                    const refTarget = ownerField.entity;
-                    const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
-                    if (targetEntity !== "user") {
-                        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                        console.warn(`[kumiko:boot] [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-Heuristik: nur wenn keine Annotation gesetzt UND kein
-            // allowPlaintext-Marker. Ergibt false positives auf Geschäftsdaten
-            // mit personenartigem Namen (z.B. company.legalName) — Author
-            // unterdrückt mit { 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)) {
-                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                    console.warn(`[kumiko:boot] [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)) {
-                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                    console.warn(`[kumiko:boot] [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)) {
-                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                    console.warn(`[kumiko:boot] [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)) {
-                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                    console.warn(`[kumiko:boot] [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)) {
-                // 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}" 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 (#1622, #2336).
-                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) {
-                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                    console.warn(`[kumiko:boot] [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.js

@@ -10,7 +10,7 @@ import { getZodObjectShape } from "./zod-shape.js";
 // reaches into feature.entities[screen.entity] — a projectionList has no
 // entity, so sharing the function would mean threading a discriminated
 // union through every entity-bound helper it calls.
-// Exported for query-refs.ts (fw#2178) — one source for the QN-derivation
+// Exported for query-refs.ts — one source for the QN-derivation
 // logic instead of duplicating it in both boot-validators.
 export function buildQueryHandlerMap(features) {
     const out = new Map();
@@ -29,7 +29,7 @@ function schemaAccepts(schema, key) {
     return shape !== undefined && key in shape;
 }
 // sortable/paginated are derived by buildAppSchema from the query's Zod
-// schema (fw#2165) — there is no separate wire type from the author-facing
+// schema — there is no separate wire type from the author-facing
 // ProjectionListScreenDefinition, so hand-authoring them would otherwise be
 // silently overwritten with no signal to the author. Reject outright.
 function rejectHandAuthoredDerivedFlags(prefix, screen) {
@@ -67,7 +67,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers, feature
     validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
     validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
 }
-// filter (fw#2224) sends `payload.filter` — same 422 footgun as facets below
+// filter sends `payload.filter` — same 422 footgun as facets below
 // if the handler's schema doesn't accept it.
 function validateProjectionListFilterSchemaAcceptance(prefix, screen, schema) {
     // skip: no filter declared, or the schema already accepts it — nothing to reject.
@@ -77,11 +77,11 @@ function validateProjectionListFilterSchemaAcceptance(prefix, screen, schema) {
         `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
         `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
 }
-// facets (fw#2224) send `payload.filters` — same failure mode as search/sort
-// (fw#2165): definePagedQueryHandler doesn't auto-merge params into the
+// facets send `payload.filters` — same failure mode as search/sort:
+// definePagedQueryHandler doesn't auto-merge params into the
 // handler's own Zod schema, so a declared facet would 422 on every query
 // unless the author added `filters` themselves.
-// A dateRange facet (fw#3104) sends its two bounds as the top-level payload
+// A dateRange facet sends its two bounds as the top-level payload
 // keys it names in `params`, not as a `filters` entry — so the query has to
 // accept exactly those keys. Catches the facet pointed at a field the query
 // can't narrow by, which would otherwise 422 on the first date the user picks.
@@ -203,7 +203,7 @@ function validateRelatedListGroupBy(prefix, section) {
 }
 // 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 (fw#2165/#2224), so an
+// auto-merge params into the handler's own Zod schema, so an
 // undeclared param would fail every query instead of failing at boot.
 // Reachable on projectionDetail only (screens.ts rejects relatedList
 // elsewhere), but the layout walk stays uniform so lifting that restriction

package/dist/engine/boot-validator/query-refs.js

@@ -25,7 +25,7 @@ function checkVisibleWhenQueryRef(queryHandlers, query, buildPrefix) {
         "Make the query's input fields optional or use a query without required input.");
 }
 // relatedList is currently only reachable on projectionDetail — screens.ts
-// rejects it outright on entityEdit/actionForm/configEdit (fw#2166). Walking
+// rejects it outright on entityEdit/actionForm/configEdit. Walking
 // the shared EditLayout uniformly here (instead of excluding those three
 // types) keeps this collector correct if that restriction is ever lifted.
 function checkEditLayoutQueryRefs(queryHandlers, featureName, screenId, screenType, layout) {

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 {};