@cosmicdrift/kumiko-framework 0.401.0 → 0.402.0

package/dist/engine/boot-validator/pii-retention-rules.d.ts

@@ -0,0 +1,107 @@
+export declare const PII_RULES: {
+    readonly multipleSubjectAnnotations: {
+        readonly id: "pii/multiple-subject-annotations";
+        readonly summary: "A field carries at most one subject-key annotation.";
+        readonly fix: "Keep a single personal annotation on the field.";
+    };
+    readonly textWithoutPersonalStance: {
+        readonly id: "pii/text-without-personal-stance";
+        readonly summary: "Every text and longText field declares whether it holds personal data.";
+        readonly fix: "Declare a personal stance, or personal: false with a reason stating why the value is not personal data.";
+    };
+    readonly plaintextUserReference: {
+        readonly id: "pii/plaintext-user-reference";
+        readonly summary: "A reference to the user entity is never plaintext.";
+        readonly fix: 'Use the default reference field or personal: "ref" instead of personal: false.';
+    };
+    readonly lookupableNonText: {
+        readonly id: "pii/lookupable-non-text";
+        readonly summary: "Blind-index lookups apply to text fields only.";
+        readonly fix: 'Use a text field or set find: "none".';
+    };
+    readonly lookupableWithoutSubject: {
+        readonly id: "pii/lookupable-without-subject";
+        readonly summary: "A blind-index lookup requires a subject annotation on the field.";
+        readonly fix: 'Add a personal annotation or set find: "none".';
+    };
+    readonly sensitiveWithoutCiphertext: {
+        readonly id: "pii/sensitive-without-ciphertext";
+        readonly summary: "A sensitive field is stored as ciphertext at rest.";
+        readonly fix: "Add a subject annotation or encrypted: true.";
+    };
+    readonly writeOnlyEmbeddedSubField: {
+        readonly id: "pii/write-only-embedded-sub-field";
+        readonly summary: "writeOnly is only supported on top-level text fields, not on embedded sub-fields.";
+        readonly fix: "Remove writeOnly from the sub-field or declare it on a top-level text field.";
+    };
+    readonly writeOnlyNonText: {
+        readonly id: "pii/write-only-non-text";
+        readonly summary: "writeOnly applies to text fields only.";
+        readonly fix: "Use a text field or remove writeOnly.";
+    };
+    readonly writeOnlyWithoutSensitive: {
+        readonly id: "pii/write-only-without-sensitive";
+        readonly summary: "A writeOnly field is also sensitive.";
+        readonly fix: 'Declare the field with find: "secret".';
+    };
+    readonly writeOnlyConflictingFlag: {
+        readonly id: "pii/write-only-conflicting-flag";
+        readonly summary: "A writeOnly field cannot be defaulted, searched, sorted, filtered or looked up.";
+        readonly fix: "Remove either writeOnly or the conflicting flag.";
+    };
+    readonly subjectKeySortable: {
+        readonly id: "pii/subject-key-sortable";
+        readonly summary: "A field with a subject-key annotation is not sortable, its column is ciphertext.";
+        readonly fix: 'Drop sortable, use find: "exact" for equality lookups, or keep the field plaintext.';
+    };
+    readonly sensitiveSearchable: {
+        readonly id: "pii/sensitive-searchable";
+        readonly summary: "A sensitive field is never searchable.";
+        readonly fix: "Drop searchable, or add writeOnly to never return the value.";
+    };
+    readonly personalJsonbFlag: {
+        readonly id: "pii/personal-jsonb-flag";
+        readonly summary: "A personal jsonb field cannot be sortable, filterable, searchable or lookupable, its value is a ciphertext string.";
+        readonly fix: "Remove the flag or the personal annotation.";
+    };
+    readonly personalJsonbIndex: {
+        readonly id: "pii/personal-jsonb-index";
+        readonly summary: "A personal jsonb field is not part of an entity index.";
+        readonly fix: "Drop the index or the personal annotation.";
+    };
+    readonly personalJsonbCustomFields: {
+        readonly id: "pii/personal-jsonb-custom-fields";
+        readonly summary: "The custom-fields jsonb column cannot carry a personal annotation.";
+        readonly fix: "Drop the personal annotation.";
+    };
+    readonly personalOfMissingOwnerName: {
+        readonly id: "pii/personal-of-missing-owner-name";
+        readonly summary: "personal: { of } names the owner field.";
+        readonly fix: 'Pass the name of the owner field: personal: { of: "<ownerField>" }.';
+    };
+    readonly personalOfUnknownOwner: {
+        readonly id: "pii/personal-of-unknown-owner";
+        readonly summary: "The owner field named by personal: { of } exists on the entity.";
+        readonly fix: "Point personal.of at an existing field of the entity.";
+    };
+    readonly personalOfOwnerType: {
+        readonly id: "pii/personal-of-owner-type";
+        readonly summary: "The owner field named by personal: { of } is a reference or text field.";
+        readonly fix: "Use a reference or text field as owner.";
+    };
+    readonly personalOfInvalidWhenAbsent: {
+        readonly id: "pii/personal-of-invalid-when-absent";
+        readonly summary: 'personal.whenAbsent is either "tenant" or "self".';
+        readonly fix: 'Remove whenAbsent or set it to "tenant" or "self".';
+    };
+    readonly personalOfOptionalOwner: {
+        readonly id: "pii/personal-of-optional-owner";
+        readonly summary: "An optional owner field of personal: { of } declares a whenAbsent fallback.";
+        readonly fix: 'Set whenAbsent to "tenant" or "self", or make the owner field required.';
+    };
+    readonly retentionUnknownReference: {
+        readonly id: "retention/unknown-reference";
+        readonly summary: "retention.reference names an existing field or a framework timestamp.";
+        readonly fix: "Point retention.reference at an existing field or a framework-managed timestamp.";
+    };
+};

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

@@ -0,0 +1,107 @@
+export const PII_RULES = {
+    multipleSubjectAnnotations: {
+        id: "pii/multiple-subject-annotations",
+        summary: "A field carries at most one subject-key annotation.",
+        fix: "Keep a single personal annotation on the field.",
+    },
+    textWithoutPersonalStance: {
+        id: "pii/text-without-personal-stance",
+        summary: "Every text and longText field declares whether it holds personal data.",
+        fix: "Declare a personal stance, or personal: false with a reason stating why the value is not personal data.",
+    },
+    plaintextUserReference: {
+        id: "pii/plaintext-user-reference",
+        summary: "A reference to the user entity is never plaintext.",
+        fix: 'Use the default reference field or personal: "ref" instead of personal: false.',
+    },
+    lookupableNonText: {
+        id: "pii/lookupable-non-text",
+        summary: "Blind-index lookups apply to text fields only.",
+        fix: 'Use a text field or set find: "none".',
+    },
+    lookupableWithoutSubject: {
+        id: "pii/lookupable-without-subject",
+        summary: "A blind-index lookup requires a subject annotation on the field.",
+        fix: 'Add a personal annotation or set find: "none".',
+    },
+    sensitiveWithoutCiphertext: {
+        id: "pii/sensitive-without-ciphertext",
+        summary: "A sensitive field is stored as ciphertext at rest.",
+        fix: "Add a subject annotation or encrypted: true.",
+    },
+    writeOnlyEmbeddedSubField: {
+        id: "pii/write-only-embedded-sub-field",
+        summary: "writeOnly is only supported on top-level text fields, not on embedded sub-fields.",
+        fix: "Remove writeOnly from the sub-field or declare it on a top-level text field.",
+    },
+    writeOnlyNonText: {
+        id: "pii/write-only-non-text",
+        summary: "writeOnly applies to text fields only.",
+        fix: "Use a text field or remove writeOnly.",
+    },
+    writeOnlyWithoutSensitive: {
+        id: "pii/write-only-without-sensitive",
+        summary: "A writeOnly field is also sensitive.",
+        fix: 'Declare the field with find: "secret".',
+    },
+    writeOnlyConflictingFlag: {
+        id: "pii/write-only-conflicting-flag",
+        summary: "A writeOnly field cannot be defaulted, searched, sorted, filtered or looked up.",
+        fix: "Remove either writeOnly or the conflicting flag.",
+    },
+    subjectKeySortable: {
+        id: "pii/subject-key-sortable",
+        summary: "A field with a subject-key annotation is not sortable, its column is ciphertext.",
+        fix: 'Drop sortable, use find: "exact" for equality lookups, or keep the field plaintext.',
+    },
+    sensitiveSearchable: {
+        id: "pii/sensitive-searchable",
+        summary: "A sensitive field is never searchable.",
+        fix: "Drop searchable, or add writeOnly to never return the value.",
+    },
+    personalJsonbFlag: {
+        id: "pii/personal-jsonb-flag",
+        summary: "A personal jsonb field cannot be sortable, filterable, searchable or lookupable, its value is a ciphertext string.",
+        fix: "Remove the flag or the personal annotation.",
+    },
+    personalJsonbIndex: {
+        id: "pii/personal-jsonb-index",
+        summary: "A personal jsonb field is not part of an entity index.",
+        fix: "Drop the index or the personal annotation.",
+    },
+    personalJsonbCustomFields: {
+        id: "pii/personal-jsonb-custom-fields",
+        summary: "The custom-fields jsonb column cannot carry a personal annotation.",
+        fix: "Drop the personal annotation.",
+    },
+    personalOfMissingOwnerName: {
+        id: "pii/personal-of-missing-owner-name",
+        summary: "personal: { of } names the owner field.",
+        fix: 'Pass the name of the owner field: personal: { of: "<ownerField>" }.',
+    },
+    personalOfUnknownOwner: {
+        id: "pii/personal-of-unknown-owner",
+        summary: "The owner field named by personal: { of } exists on the entity.",
+        fix: "Point personal.of at an existing field of the entity.",
+    },
+    personalOfOwnerType: {
+        id: "pii/personal-of-owner-type",
+        summary: "The owner field named by personal: { of } is a reference or text field.",
+        fix: "Use a reference or text field as owner.",
+    },
+    personalOfInvalidWhenAbsent: {
+        id: "pii/personal-of-invalid-when-absent",
+        summary: 'personal.whenAbsent is either "tenant" or "self".',
+        fix: 'Remove whenAbsent or set it to "tenant" or "self".',
+    },
+    personalOfOptionalOwner: {
+        id: "pii/personal-of-optional-owner",
+        summary: "An optional owner field of personal: { of } declares a whenAbsent fallback.",
+        fix: 'Set whenAbsent to "tenant" or "self", or make the owner field required.',
+    },
+    retentionUnknownReference: {
+        id: "retention/unknown-reference",
+        summary: "retention.reference names an existing field or a framework timestamp.",
+        fix: "Point retention.reference at an existing field or a framework-managed timestamp.",
+    },
+};

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

@@ -1,7 +1,10 @@
 import { holdsFileRefs } from "../../files/file-field-slots.js";
 import { createFallbackLogger } from "../../logging/utils.js";
 import { isUserEntityReference } from "../user-entity-reference.js";
+import { collectBootRuleViolations } from "./boot-report.js";
+import { bootRuleError } from "./boot-rule.js";
 import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./entity-handler.js";
+import { PII_RULES } from "./pii-retention-rules.js";
 const log = createFallbackLogger("kumiko:boot");
 // Framework-managed timestamp fields may be used as retention.reference
 // even when they are not declared in entity.fields.
@@ -46,7 +49,9 @@ function validateWriteOnlyField(input) {
         for (const [subName, subField] of Object.entries(field.schema)) {
             if ("writeOnly" in subField && subField.writeOnly === true) {
                 // @cast-boundary schema-walk
-                throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields. Remove writeOnly from the sub-field or declare it on a top-level text field.`);
+                throw bootRuleError(PII_RULES.writeOnlyEmbeddedSubField, {
+                    message: `${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields. Remove writeOnly from the sub-field or declare it on a top-level text field.`,
+                });
             }
         }
         // skip: embedded fields carry no writeOnly of their own; sub-fields are checked above
@@ -57,15 +62,21 @@ function validateWriteOnlyField(input) {
     if (flags.writeOnly !== true)
         return;
     if (field.type !== "text") {
-        throw new Error(`${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields. Use a text field or remove writeOnly.`);
+        throw bootRuleError(PII_RULES.writeOnlyNonText, {
+            message: `${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields. Use a text field or remove writeOnly.`,
+        });
     }
     if (field.sensitive !== true) {
-        throw new Error(`${where} declares { writeOnly: true } without { sensitive: true } — add find: "secret" (ciphertext at rest, stripped from event echoes).`);
+        throw bootRuleError(PII_RULES.writeOnlyWithoutSensitive, {
+            message: `${where} declares { writeOnly: true } without { sensitive: true } — add find: "secret" (ciphertext at rest, stripped from event echoes).`,
+        });
     }
     for (const flag of WRITE_ONLY_FORBIDDEN_FLAGS) {
         const value = flags[flag];
         if (value !== undefined && value !== false) {
-            throw new Error(`${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up. Remove either writeOnly or the conflicting flag.`);
+            throw bootRuleError(PII_RULES.writeOnlyConflictingFlag, {
+                message: `${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up. Remove either writeOnly or the conflicting flag.`,
+            });
         }
     }
 }
@@ -89,15 +100,21 @@ function validatePersonalJsonbField(input) {
     const flags = field; // @cast-boundary schema-walk
     for (const flag of JSONB_PERSONAL_FORBIDDEN_FLAGS) {
         if (flags[flag] !== undefined && flags[flag] !== false) {
-            throw new Error(`${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}. Remove the ${flag} flag or the personal annotation.`);
+            throw bootRuleError(PII_RULES.personalJsonbFlag, {
+                message: `${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}. Remove the ${flag} flag or the personal annotation.`,
+            });
         }
     }
     const index = entity.indexes?.find((def) => def.columns.includes(fieldName));
     if (index) {
-        throw new Error(`${where} is a personal jsonb field used in an entity index — ${reason}. Drop the index or the personal annotation.`);
+        throw bootRuleError(PII_RULES.personalJsonbIndex, {
+            message: `${where} is a personal jsonb field used in an entity index — ${reason}. Drop the index or the personal annotation.`,
+        });
     }
     if (fieldName === CUSTOM_FIELDS_COLUMN) {
-        throw new Error(`${where} is the custom-fields jsonb column — its values are merged and searched per key, which ciphertext cannot support. Drop the personal annotation.`);
+        throw bootRuleError(PII_RULES.personalJsonbCustomFields, {
+            message: `${where} is the custom-fields jsonb column — its values are merged and searched per key, which ciphertext cannot support. Drop the personal annotation.`,
+        });
     }
 }
 // --- PII / Subject-Key Annotations + Retention validation ---
@@ -125,13 +142,13 @@ function validatePersonalJsonbField(input) {
 // 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 ?? {})) {
-        validateFieldAnnotations(feature.name, entityName, entity);
-        validateEntityRetention(feature.name, entityName, entity);
-    }
+    collectBootRuleViolations(Object.entries(feature.entities ?? {}), ([entityName, entity]) => {
+        const entityChecks = [validateFieldAnnotations, validateEntityRetention];
+        collectBootRuleViolations(entityChecks, (check) => check(feature.name, entityName, entity));
+    });
 }
-// Order matters: the first failing rule decides the boot error, and warnings
-// are emitted in this order.
+// Every rule runs on every field; order only decides the order of the reported
+// violations and warnings.
 const FIELD_RULES = [
     rejectMultipleSubjectAnnotations,
     rejectTextWithoutPersonalStance,
@@ -146,7 +163,7 @@ const FIELD_RULES = [
 ];
 function validateFieldAnnotations(featureName, entityName, entity) {
     const personalOfOwnerFieldNames = ownerFieldNamesReferencedByPersonalOf(entity.fields);
-    for (const [fieldName, field] of Object.entries(entity.fields)) {
+    collectBootRuleViolations(Object.entries(entity.fields), ([fieldName, field]) => {
         const flags = field; // @cast-boundary schema-walk
         const input = {
             featureName,
@@ -158,9 +175,8 @@ function validateFieldAnnotations(featureName, entityName, entity) {
             subjectAnnotationCount: countSubjectAnnotations(flags),
             personalOfOwnerFieldNames,
         };
-        for (const rule of FIELD_RULES)
-            rule(input);
-    }
+        collectBootRuleViolations(FIELD_RULES, (rule) => rule(input));
+    });
 }
 function countSubjectAnnotations(flags) {
     return [flags.pii, flags.userOwned, flags.tenantOwned, flags.recordOwned].filter(Boolean).length;
@@ -170,7 +186,9 @@ function fieldLocation(input) {
 }
 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.`);
+        throw bootRuleError(PII_RULES.multipleSubjectAnnotations, {
+            message: `${fieldLocation(input)} has multiple subject-key annotations (personal: "self" / "tenant" / { of: "<field>" }). Pick one — each field belongs to exactly one subject.`,
+        });
     }
 }
 function rejectTextWithoutPersonalStance(input) {
@@ -179,7 +197,9 @@ function rejectTextWithoutPersonalStance(input) {
         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.`);
+        throw bootRuleError(PII_RULES.textWithoutPersonalStance, {
+            message: `${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.`,
+        });
     }
 }
 function rejectPlaintextUserReference(input) {
@@ -190,7 +210,9 @@ function rejectPlaintextUserReference(input) {
     // skip: references to other entities may stay plaintext
     if (!isUserEntityReference(field.entity))
         return;
-    throw new Error(`${fieldLocation(input)} references the user entity "${field.entity}" with { personal: false } — a user id is a pseudonym that falls under Art.17 forget. Use createReferenceField({ entity: "${field.entity}" }) or { personal: "ref" }.`);
+    throw bootRuleError(PII_RULES.plaintextUserReference, {
+        message: `${fieldLocation(input)} references the user entity "${field.entity}" with { personal: false } — a user id is a pseudonym that falls under Art.17 forget. Use createReferenceField({ entity: "${field.entity}" }) or { personal: "ref" }.`,
+    });
 }
 // lookupable: only text fields with a subject annotation are supported. Without
 // a subject, the value remains plaintext, so a blind index would be a
@@ -200,10 +222,14 @@ function rejectInvalidLookupable(input) {
     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".`);
+        throw bootRuleError(PII_RULES.lookupableNonText, {
+            message: `${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".`);
+        throw bootRuleError(PII_RULES.lookupableWithoutSubject, {
+            message: `${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
@@ -212,7 +238,9 @@ function rejectInvalidLookupable(input) {
 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 }.`);
+        throw bootRuleError(PII_RULES.sensitiveWithoutCiphertext, {
+            message: `${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
@@ -223,10 +251,14 @@ function rejectSensitiveWithoutCiphertextAtRest(input) {
 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).`);
+        throw bootRuleError(PII_RULES.subjectKeySortable, {
+            message: `${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 }.`);
+        throw bootRuleError(PII_RULES.sensitiveSearchable, {
+            message: `${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) {
@@ -236,7 +268,9 @@ function validatePersonalOfOwner(input) {
         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>" }.`);
+        throw bootRuleError(PII_RULES.personalOfMissingOwnerName, {
+            message: `${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);
@@ -247,7 +281,9 @@ function requireOwnerField(input, ownerName) {
     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}`);
+        throw bootRuleError(PII_RULES.personalOfUnknownOwner, {
+            message: `${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
@@ -255,17 +291,23 @@ function requireOwnerField(input, ownerName) {
     // 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}"`);
+        throw bootRuleError(PII_RULES.personalOfOwnerType, {
+            message: `[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).`);
+        throw bootRuleError(PII_RULES.personalOfInvalidWhenAbsent, {
+            message: `${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).`);
+        throw bootRuleError(PII_RULES.personalOfOptionalOwner, {
+            message: `${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
@@ -327,8 +369,7 @@ function validateEntityRetention(featureName, entityName, entity) {
         fieldsByName: entity.fields,
         retention,
     };
-    for (const rule of RETENTION_RULES)
-        rule(input);
+    collectBootRuleViolations(RETENTION_RULES, (rule) => rule(input));
 }
 function warnOnInvalidKeepFor({ featureName, entityName, retention }) {
     if (!KEEP_FOR_PATTERN.test(retention.keepFor)) {
@@ -344,7 +385,9 @@ function rejectUnknownRetentionReference(input) {
     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}`);
+        throw bootRuleError(PII_RULES.retentionUnknownReference, {
+            message: `[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;

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

@@ -0,0 +1,7 @@
+export declare const SCREEN_ACTION_RULES: {
+    readonly actionIcon: {
+        readonly id: "screen/action-icon";
+        readonly summary: "Every screen action resolves to a registered icon.";
+        readonly fix: "Set icon to a registered NAV_ICONS key or use an action id that resolves one via the default icon map.";
+    };
+};

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

@@ -0,0 +1,7 @@
+export const SCREEN_ACTION_RULES = {
+    actionIcon: {
+        id: "screen/action-icon",
+        summary: "Every screen action resolves to a registered icon.",
+        fix: "Set icon to a registered NAV_ICONS key or use an action id that resolves one via the default icon map.",
+    },
+};

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

@@ -4,6 +4,8 @@ import { fallbackTargets, SCREEN_FALLBACK_REASONS, } from "@cosmicdrift/kumiko-t
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name.js";
 import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
+import { bootRuleError } from "./boot-rule.js";
+import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
 export function isRowClickAction(action) {
     return (action.kind === "navigate" || action.kind === "drawer") && action.rowClick === true;
 }
@@ -117,9 +119,11 @@ function isRegisteredIcon(icon) {
 export function validateActionHasIcon(featureName, screenId, screenType, context, action) {
     const resolved = resolveActionIcon(action.id, action.icon);
     if (resolved === undefined || !isRegisteredIcon(resolved)) {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${context} "${action.id}" has no ` +
-            `resolvable icon — set icon to a key registered in NAV_ICONS, or use an id that resolves one of ` +
-            `its kebab segments via the default icon map (resolveActionIcon).`);
+        throw bootRuleError(SCREEN_ACTION_RULES.actionIcon, {
+            message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${context} "${action.id}" has no ` +
+                `resolvable icon — set icon to a key registered in NAV_ICONS, or use an id that resolves one of ` +
+                `its kebab segments via the default icon map (resolveActionIcon).`,
+        });
     }
 }
 // Pin an action's declarative field references against the entity

package/dist/engine/index.d.ts

@@ -22,6 +22,8 @@ export { handlerFieldLabelKey, handlerTitleKey } from "../i18n/required-surface-
 export { attachOutsideTransaction } from "../pipeline/attach-outside-transaction.ts";
 export { hasAccess } from "./access.ts";
 export type { PrincipalProfile, PrincipalStatus, PrincipalStatusPlugin, TenantLifecycleStatusPlugin, } from "./active-membership.ts";
+export { collectBootRuleViolations } from "./boot-validator/boot-report.ts";
+export { type BootRule, type BootRuleTable, BootRuleViolation, BootValidationError, type BootViolation, bootRuleError, } from "./boot-validator/boot-rule.ts";
 export { validateBundledListsOptions } from "./boot-validator/bundled-lists-table.ts";
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.ts";
 export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.ts";

package/dist/engine/index.js

@@ -4,6 +4,8 @@ export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN,
 export { handlerFieldLabelKey, handlerTitleKey } from "../i18n/required-surface-keys.js";
 export { attachOutsideTransaction } from "../pipeline/attach-outside-transaction.js";
 export { hasAccess } from "./access.js";
+export { collectBootRuleViolations } from "./boot-validator/boot-report.js";
+export { BootRuleViolation, BootValidationError, bootRuleError, } from "./boot-validator/boot-rule.js";
 export { validateBundledListsOptions } from "./boot-validator/bundled-lists-table.js";
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
 export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";

package/dist/i18n/required-surface-keys.js

@@ -480,6 +480,9 @@ export function requiredKeysFromFeature(feature) {
         for (const key of requiredKeysFromNav(nav))
             out.add(key);
     }
+    for (const collection of Object.values(feature.contentCollections ?? {})) {
+        pushKey(out, collection.nav.entryLabel);
+    }
     for (const ws of Object.values(feature.workspaces)) {
         for (const key of requiredKeysFromWorkspace(ws))
             out.add(key);

package/dist/schema-cli/validate-command.js

@@ -4,7 +4,7 @@ import { assertRowLevelSecurityTableState, createDbConnection, generateMigration
 import { isLiveFrameworkTable } from "../db/known-table-names.js";
 import { readMigrationSqlTexts } from "../db/migrate-runner.js";
 import { diffReplayAgainstSnapshot, replayMigrationsDir } from "../db/replay-migration-sql.js";
-import { BootValidationError } from "../engine/boot-validator/boot-rule.js";
+import { BootValidationError, bootRuleDocLink, } from "../engine/boot-validator/boot-rule.js";
 import { validateBoot } from "../engine/boot-validator.js";
 import { describeThrown, loadPreviousSnapshot, loadSchemaModOrReport, nextSequenceNumber, SNAPSHOT_FILENAME, } from "./shared.js";
 import { featureDefinitionsOf, parseValidateBootOptions, withFileStoragePresence, } from "./validate-boot-input.js";
@@ -44,6 +44,9 @@ function reportBootViolations(out, violations) {
         out.err(`  ✗ boot [${v.ruleId}] ${v.message}`);
         if (v.fix !== undefined)
             out.err(`    Fix: ${v.fix}`);
+        const docLink = bootRuleDocLink(v.ruleId);
+        if (docLink !== undefined)
+            out.err(`    Rule: ${docLink}`);
     }
 }
 // 2. Boot validity — needs the composed feature set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.401.0",
+  "version": "0.402.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.401.0",
+    "@cosmicdrift/kumiko-types": "0.402.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.14",
     "i18next": "^26.1.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.401.0",
+    "@cosmicdrift/kumiko-testing": "0.402.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.402.0",
+    "type": "improvement",
+    "title": "Boot violations carry rule ids with a fix and a doc link",
+    "detail": "43 boot rules have an id such as `pii/subject-key-sortable` or `entity-list/default-sort-required`. A violation in `BootValidationError.violations` and in `kumiko-schema validate` (text and `--json`) carries that id instead of `unclassified/<check>`, plus a `Fix:` line and `Rule: agents/boot-rules.md#<id>`. PII field rules, entityList screen rules, missing i18n keys, API and extension usages and user-data-rights hooks now report all violations in one run. Message texts are unchanged. `@cosmicdrift/kumiko-framework/engine` exports `bootRuleError`, `BootRuleViolation`, `BootValidationError`, `collectBootRuleViolations` and the types `BootRule`, `BootRuleTable`, `BootViolation`, so a feature's `r.bootCheck` can throw a classified rule."
+  },
+  {
+    "version": "0.402.0",
+    "type": "fix",
+    "title": "Migration replay keeps tables whose name ends in \"as\"",
+    "detail": "`CREATE TABLE IF NOT EXISTS \"read_themas\" (...)` was parsed as `CREATE TABLE read_them AS ...`, so `kumiko-schema validate` reported content drift for `read_them` and `read_themas`. `AS` now needs a column list or whitespace before it."
+  },
   {
     "version": "0.401.0",
     "type": "improvement",