@cosmicdrift/kumiko-framework 0.400.0 → 0.402.0

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

@@ -1,6 +1,9 @@
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
 import { normalizeListColumn } from "../screen-helpers.js";
+import { collectBootRuleViolations } from "./boot-report.js";
+import { bootRuleError } from "./boot-rule.js";
 import { isSortableSqlDerivedField } from "./derived-sql-fields.js";
+import { ENTITY_LIST_RULES } from "./entity-list-screens-rules.js";
 /** Operator lists default searchable; low-cardinality audit trails stay opt-out. */
 export const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list", "cap-list"]);
 // Same set computeListViewModel (headless) can actually render — NOT
@@ -21,57 +24,87 @@ function hasFilterableFields(feature, entityName) {
 function hasEntityEditDetail(feature, entityName) {
     return Object.values(feature.screens).some((s) => s.type === "entityEdit" && s.entity === entityName);
 }
-function validateOneEntityListScreen(feature, screen) {
-    const prefix = `[entityList] Feature "${feature.name}" screen "${screen.id}"`;
+function screenPrefix(feature, screen) {
+    return `[entityList] Feature "${feature.name}" screen "${screen.id}"`;
+}
+function checkSearchable(feature, screen) {
     if (screen.searchable === false && !SEARCHABLE_FALSE_WHITELIST.has(screen.id)) {
-        throw new Error(`${prefix}: searchable defaults to true for operator lists — set searchable: true or add "${screen.id}" to the whitelist`);
+        throw bootRuleError(ENTITY_LIST_RULES.searchableFalse, {
+            message: `${screenPrefix(feature, screen)}: searchable defaults to true for operator lists — set searchable: true or add "${screen.id}" to the whitelist`,
+        });
     }
+}
+function checkDefaultSortRequired(feature, screen) {
     const filtersActive = hasFilterableFields(feature, screen.entity);
     const searchable = screen.searchable !== false;
     if ((searchable || filtersActive) && screen.defaultSort === undefined) {
-        throw new Error(`${prefix}: defaultSort required when searchable or filterable fields are active. Set defaultSort: { field, direction } on the screen.`);
+        throw bootRuleError(ENTITY_LIST_RULES.defaultSortRequired, {
+            message: `${screenPrefix(feature, screen)}: defaultSort required when searchable or filterable fields are active. Set defaultSort: { field, direction } on the screen.`,
+        });
     }
-    if (screen.defaultSort !== undefined) {
-        const sortField = screen.defaultSort.field;
-        const col = screen.columns.find((c) => normalizeListColumn(c).field === sortField);
-        if (col === undefined) {
-            throw new Error(`${prefix}: defaultSort.field "${sortField}" is not a listed column. Pick a field from columns or add it there.`);
-        }
-        const entityDef = feature.entities?.[screen.entity];
-        const fieldDef = entityDef?.fields[sortField];
-        const isSortable = (entityDef !== undefined && isSortableSqlDerivedField(entityDef, sortField)) ||
-            (fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true);
-        if (!isSortable) {
-            throw new Error(`${prefix}: defaultSort column "${sortField}" must be sortable`);
-        }
+}
+function checkDefaultSortColumn(feature, screen) {
+    // skip: a missing defaultSort is reported by checkDefaultSortRequired
+    if (screen.defaultSort === undefined)
+        return;
+    const prefix = screenPrefix(feature, screen);
+    const sortField = screen.defaultSort.field;
+    const col = screen.columns.find((c) => normalizeListColumn(c).field === sortField);
+    if (col === undefined) {
+        throw bootRuleError(ENTITY_LIST_RULES.defaultSortNotListed, {
+            message: `${prefix}: defaultSort.field "${sortField}" is not a listed column. Pick a field from columns or add it there.`,
+        });
     }
-    if (hasEntityEditDetail(feature, screen.entity)) {
-        const hasNavigate = (screen.rowActions ?? []).some((a) => a.kind === "navigate" && (a.id === "view" || a.id === "edit"));
-        if (!hasNavigate) {
-            throw new Error(`${prefix}: detail screen exists — add a navigate rowAction with id "view" or "edit"`);
-        }
+    const entityDef = feature.entities?.[screen.entity];
+    const fieldDef = entityDef?.fields[sortField];
+    const isSortable = (entityDef !== undefined && isSortableSqlDerivedField(entityDef, sortField)) ||
+        (fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true);
+    if (!isSortable) {
+        throw bootRuleError(ENTITY_LIST_RULES.defaultSortNotSortable, {
+            message: `${prefix}: defaultSort column "${sortField}" must be sortable`,
+        });
     }
-    for (const col of screen.columns) {
+}
+function checkDetailNavigate(feature, screen) {
+    // skip: only lists with a detail screen need a navigate row action
+    if (!hasEntityEditDetail(feature, screen.entity))
+        return;
+    const hasNavigate = (screen.rowActions ?? []).some((a) => a.kind === "navigate" && (a.id === "view" || a.id === "edit"));
+    if (!hasNavigate) {
+        throw bootRuleError(ENTITY_LIST_RULES.detailWithoutNavigate, {
+            message: `${screenPrefix(feature, screen)}: detail screen exists — add a navigate rowAction with id "view" or "edit"`,
+        });
+    }
+}
+function checkColumns(feature, screen) {
+    collectBootRuleViolations(screen.columns, (col) => {
         const normalized = normalizeListColumn(col);
-        if (normalized.label === undefined) {
-            const entity = feature.entities?.[screen.entity];
-            const isDerived = entity?.derivedFields?.[normalized.field] !== undefined;
-            // Row-meta column (id/tenantId/version/insertedAt/modifiedAt/...) is a
-            // real base-table column without being a declared entity field — e.g.
-            // a SystemAdmin cross-tenant list exposing tenantId.
-            const isRowMeta = LIST_ROW_META_COLUMN_NAMES.has(normalized.field);
-            if (!entity?.fields[normalized.field] && !isDerived && !isRowMeta) {
-                throw new Error(`${prefix}: unknown column field "${normalized.field}"`);
-            }
+        // skip: a labelled column is free text, not a field reference
+        if (normalized.label !== undefined)
+            return;
+        const entity = feature.entities?.[screen.entity];
+        const isDerived = entity?.derivedFields?.[normalized.field] !== undefined;
+        // Row-meta column (id/tenantId/version/insertedAt/modifiedAt/...) is a
+        // real base-table column without being a declared entity field — e.g.
+        // a SystemAdmin cross-tenant list exposing tenantId.
+        const isRowMeta = LIST_ROW_META_COLUMN_NAMES.has(normalized.field);
+        if (!entity?.fields[normalized.field] && !isDerived && !isRowMeta) {
+            throw bootRuleError(ENTITY_LIST_RULES.unknownColumn, {
+                message: `${screenPrefix(feature, screen)}: unknown column field "${normalized.field}"`,
+            });
         }
-    }
+    });
 }
+const ENTITY_LIST_CHECKS = [
+    checkSearchable,
+    checkDefaultSortRequired,
+    checkDefaultSortColumn,
+    checkDetailNavigate,
+    checkColumns,
+];
 export function validateEntityListScreens(features) {
-    for (const feature of features) {
-        for (const screen of Object.values(feature.screens)) {
-            if (screen.type !== "entityList")
-                continue;
-            validateOneEntityListScreen(feature, screen);
-        }
-    }
+    const screens = features.flatMap((feature) => Object.values(feature.screens).flatMap((screen) => screen.type === "entityList" ? [{ feature, screen }] : []));
+    collectBootRuleViolations(screens, ({ feature, screen }) => {
+        collectBootRuleViolations(ENTITY_LIST_CHECKS, (check) => check(feature, screen));
+    });
 }

package/dist/engine/boot-validator/field-conditions.js

@@ -77,9 +77,19 @@ function assertFileSubField(where, sub) {
             throw new Error(`${where} has invalid maxSize "${sub.maxSize}". Use e.g. "10mb", "500kb".`);
         }
     }
-    if (sub.accept?.some((ext) => ext.length === 0)) {
+    assertAcceptEntries(where, sub.accept);
+}
+// validateFile compares accept entries with the lower-cased last file-name segment, so only
+// bare lower-case extensions can ever match.
+const BARE_EXTENSION = /^[a-z0-9]+$/;
+function assertAcceptEntries(where, accept) {
+    if (accept?.some((ext) => ext.length === 0)) {
         throw new Error(`${where} has an empty entry in accept. List file extensions like "pdf".`);
     }
+    const offender = accept?.find((entry) => !BARE_EXTENSION.test(entry));
+    if (offender !== undefined) {
+        throw new Error(`${where} has accept entry "${offender}", which can never match an uploaded file. accept takes bare lower-case file extensions without dot, MIME type or wildcard: use "pdf" instead of ".pdf" or "application/pdf".`);
+    }
 }
 function assertSelectSubFieldTones(where, sub) {
     // skip: only select sub-fields with declared tones have tones to check
@@ -168,6 +178,14 @@ function assertField(feature, entityName, entity, fieldName, field) {
     }
     if (field.type === "embedded")
         assertEmbeddedField(where, field);
+    if (isFileAcceptField(field))
+        assertAcceptEntries(where, field.accept);
+}
+function isFileAcceptField(field) {
+    return (field.type === "file" ||
+        field.type === "files" ||
+        field.type === "image" ||
+        field.type === "images");
 }
 export function validateFieldConditions(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {

package/dist/engine/boot-validator/i18n-keys-rules.d.ts

@@ -0,0 +1,27 @@
+export declare const I18N_RULES: {
+    readonly missingFeatureKey: {
+        readonly id: "i18n/missing-feature-key";
+        readonly summary: "Every translation key a feature surface requires is defined.";
+        readonly fix: "Add the key via r.translations(...) in the feature.";
+    };
+    readonly missingSettingsHubKey: {
+        readonly id: "i18n/missing-settings-hub-key";
+        readonly summary: "Every translation key the generated settings hub requires is defined.";
+        readonly fix: "Add the key via r.translations(...) in the owning feature.";
+    };
+    readonly localeInconsistent: {
+        readonly id: "i18n/locale-inconsistent";
+        readonly summary: "Every locale a feature uses is maintained for every one of its translation keys.";
+        readonly fix: "Add the missing locale to the key, or move that locale into a locale package.";
+    };
+    readonly missingRequiredLocale: {
+        readonly id: "i18n/missing-required-locale";
+        readonly summary: "Every translation key exists in every locale the app requires.";
+        readonly fix: "Load the matching locale package or add the missing translations.";
+    };
+    readonly missingFieldValueTranslation: {
+        readonly id: "i18n/missing-field-value-translation";
+        readonly summary: "With requireFieldValueTranslations, select options and embedded cells are translated.";
+        readonly fix: "Add the keys via r.translations(...) in the owning feature.";
+    };
+};

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

@@ -0,0 +1,27 @@
+export const I18N_RULES = {
+    missingFeatureKey: {
+        id: "i18n/missing-feature-key",
+        summary: "Every translation key a feature surface requires is defined.",
+        fix: "Add the key via r.translations(...) in the feature.",
+    },
+    missingSettingsHubKey: {
+        id: "i18n/missing-settings-hub-key",
+        summary: "Every translation key the generated settings hub requires is defined.",
+        fix: "Add the key via r.translations(...) in the owning feature.",
+    },
+    localeInconsistent: {
+        id: "i18n/locale-inconsistent",
+        summary: "Every locale a feature uses is maintained for every one of its translation keys.",
+        fix: "Add the missing locale to the key, or move that locale into a locale package.",
+    },
+    missingRequiredLocale: {
+        id: "i18n/missing-required-locale",
+        summary: "Every translation key exists in every locale the app requires.",
+        fix: "Load the matching locale package or add the missing translations.",
+    },
+    missingFieldValueTranslation: {
+        id: "i18n/missing-field-value-translation",
+        summary: "With requireFieldValueTranslations, select options and embedded cells are translated.",
+        fix: "Add the keys via r.translations(...) in the owning feature.",
+    },
+};

package/dist/engine/boot-validator/i18n-keys.d.ts

@@ -2,3 +2,4 @@ import type { FeatureDefinition, Registry } from "../types/index.ts";
 export declare function validateI18nSurfaceKeys(features: readonly FeatureDefinition[], registry: Registry): void;
 export declare function validateTranslationLocaleConsistency(features: readonly FeatureDefinition[]): void;
 export declare function validateRequiredLocales(features: readonly FeatureDefinition[], requiredLocales: readonly string[] | undefined): void;
+export declare function validateFieldValueTranslations(features: readonly FeatureDefinition[], enabled: boolean | undefined): void;

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

@@ -1,6 +1,9 @@
-import { buildEffectiveTranslationKeys, featureHasI18nSurface, findRequiredLocaleGaps, findTranslationLocaleGaps, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
+import { buildEffectiveTranslationKeys, featureHasI18nSurface, fieldValueTranslationKeysFromFeature, findRequiredLocaleGaps, findTranslationLocaleGaps, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
 import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, } from "../build-config-feature-schema.js";
 import { EXTENSION_SELECTOR_HINT_KEY } from "../extension-selector-plugins.js";
+import { collectBootRuleViolations } from "./boot-report.js";
+import { bootRuleError } from "./boot-rule.js";
+import { I18N_RULES } from "./i18n-keys-rules.js";
 function isDormantSecretsScreen(screen) {
     return screen.type === "secretsEdit" && screen.dormant === true;
 }
@@ -67,28 +70,32 @@ export function validateI18nSurfaceKeys(features, registry) {
     // declared secret would fail boot on its own generated keys.
     for (const key of Object.keys(generatedConfigHub.translations ?? {}))
         defined.add(key);
-    for (const feature of features) {
-        if (!featureHasI18nSurface(feature))
-            continue;
-        for (const key of requiredKeysFromFeature(feature)) {
-            if (isFrameworkOwnedI18nKey(key))
-                continue;
-            if (!hasDefinedTranslation(defined, key)) {
-                throw new Error(`[i18n] Feature "${feature.name}": required translation key missing: "${key}". Add it via r.translations(...) in this feature.`);
-            }
+    const featureKeys = features.filter(featureHasI18nSurface).flatMap((feature) => requiredKeysFromFeature(feature)
+        .filter((key) => !isFrameworkOwnedI18nKey(key))
+        .map((key) => ({ featureName: feature.name, key })));
+    const checkFeatureKeys = () => collectBootRuleViolations(featureKeys, ({ featureName, key }) => {
+        if (!hasDefinedTranslation(defined, key)) {
+            throw bootRuleError(I18N_RULES.missingFeatureKey, {
+                message: `[i18n] Feature "${featureName}": required translation key missing: "${key}". Add it via r.translations(...) in this feature.`,
+            });
         }
-    }
-    for (const key of requiredKeysFromGeneratedConfigHub(generatedConfigHub)) {
+    });
+    const checkSettingsHubKeys = () => collectBootRuleViolations(requiredKeysFromGeneratedConfigHub(generatedConfigHub), (key) => {
         if (!hasDefinedTranslation(defined, key)) {
-            throw new Error(`[i18n] Settings-Hub: required translation key missing: "${key}". Add it via r.translations(...) in the owning feature.`);
+            throw bootRuleError(I18N_RULES.missingSettingsHubKey, {
+                message: `[i18n] Settings-Hub: required translation key missing: "${key}". Add it via r.translations(...) in the owning feature.`,
+            });
         }
-    }
+    });
+    collectBootRuleViolations([checkFeatureKeys, checkSettingsHubKeys], (run) => run());
 }
 export function validateTranslationLocaleConsistency(features) {
     const gaps = findTranslationLocaleGaps(features);
     if (gaps.length > 0) {
         const lines = gaps.map((gap) => `[i18n] Feature "${gap.featureName}": translation key "${gap.key}" is missing locale(s) ${gap.missingLocales.join(", ")}.`);
-        throw new Error(`${lines.join("\n")}\nEvery locale a feature uses must be maintained for every one of its translation keys; otherwise move that locale into a locale package.`);
+        throw bootRuleError(I18N_RULES.localeInconsistent, {
+            message: `${lines.join("\n")}\nEvery locale a feature uses must be maintained for every one of its translation keys; otherwise move that locale into a locale package.`,
+        });
     }
 }
 export function validateRequiredLocales(features, requiredLocales) {
@@ -97,6 +104,26 @@ export function validateRequiredLocales(features, requiredLocales) {
         : findRequiredLocaleGaps(features, requiredLocales);
     if (requiredLocales !== undefined && gaps.length > 0) {
         const lines = gaps.map((gap) => `[i18n] Feature "${gap.featureName}": translation key "${gap.key}" is missing required locale(s) ${gap.missingLocales.join(", ")}.`);
-        throw new Error(`${lines.join("\n")}\nThe app requires locales [${requiredLocales.join(", ")}] for every translation key; load the matching locale package or add the missing translations.`);
+        throw bootRuleError(I18N_RULES.missingRequiredLocale, {
+            message: `${lines.join("\n")}\nThe app requires locales [${requiredLocales.join(", ")}] for every translation key; load the matching locale package or add the missing translations.`,
+        });
+    }
+}
+export function validateFieldValueTranslations(features, enabled) {
+    // skip: opt-in rule, off unless the app enables requireFieldValueTranslations
+    if (enabled !== true)
+        return;
+    const defined = buildEffectiveTranslationKeys(features);
+    const missing = [];
+    for (const feature of features) {
+        for (const key of fieldValueTranslationKeysFromFeature(feature)) {
+            if (!hasDefinedTranslation(defined, key))
+                missing.push(`  - ${feature.name}: ${key}`);
+        }
+    }
+    if (missing.length > 0) {
+        throw bootRuleError(I18N_RULES.missingFieldValueTranslation, {
+            message: `[i18n] ${missing.length} select option / embedded-cell translation key(s) missing (requireFieldValueTranslations):\n${missing.join("\n")}\nAdd them via r.translations(...) in the owning feature.`,
+        });
     }
 }

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.",
+    },
+};