@cosmicdrift/kumiko-framework 0.401.0 → 0.402.0

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

@@ -0,0 +1,210 @@
+import type { BootRule } from "./boot-rule.ts";
+export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
+    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.";
+    };
+}, {
+    readonly searchableFalse: {
+        readonly id: "entity-list/searchable-false";
+        readonly summary: "Operator lists are searchable unless they are on the searchable-false whitelist.";
+        readonly fix: "Set searchable: true or add the screen id to the whitelist.";
+    };
+    readonly defaultSortRequired: {
+        readonly id: "entity-list/default-sort-required";
+        readonly summary: "A list with active search or filterable fields declares a defaultSort.";
+        readonly fix: "Set defaultSort: { field, direction } on the screen.";
+    };
+    readonly defaultSortNotListed: {
+        readonly id: "entity-list/default-sort-not-listed";
+        readonly summary: "defaultSort.field is one of the listed columns.";
+        readonly fix: "Pick a field from columns or add it there.";
+    };
+    readonly defaultSortNotSortable: {
+        readonly id: "entity-list/default-sort-not-sortable";
+        readonly summary: "The defaultSort column is sortable.";
+        readonly fix: "Mark the field sortable or pick another defaultSort field.";
+    };
+    readonly detailWithoutNavigate: {
+        readonly id: "entity-list/detail-without-navigate";
+        readonly summary: "A list whose entity has a detail screen offers a navigate row action.";
+        readonly fix: 'Add a navigate rowAction with id "view" or "edit".';
+    };
+    readonly unknownColumn: {
+        readonly id: "entity-list/unknown-column";
+        readonly summary: "Every column without a label names an entity field, derived field or row-meta column.";
+        readonly fix: "Fix the column field name or give the column a label.";
+    };
+}, {
+    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.";
+    };
+}, {
+    readonly overflow: {
+        readonly id: "list/card-meta-overflow";
+        readonly summary: "A card list shows at most the maximum number of meta columns.";
+        readonly fix: "Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true.";
+    };
+}, {
+    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.";
+    };
+}, {
+    readonly unknownApi: {
+        readonly id: "api/unknown-api";
+        readonly summary: "Every r.usesApi name is exposed by some mounted feature.";
+        readonly fix: "Mount the feature that exposes the API or fix the API name.";
+    };
+    readonly providerNotRequired: {
+        readonly id: "api/provider-not-required";
+        readonly summary: "A feature using an API lists the exposing feature in requires or optionalRequires.";
+        readonly fix: "Add the exposing feature via r.requires({ features: [...] }).";
+    };
+    readonly providerNotMounted: {
+        readonly id: "api/provider-not-mounted";
+        readonly summary: "The feature exposing a used API is part of the app's feature list.";
+        readonly fix: "Register the provider feature in the app's feature list.";
+    };
+    readonly unknownExtension: {
+        readonly id: "extension/unknown-extension";
+        readonly summary: "Every extension a feature uses is defined by some mounted feature.";
+        readonly fix: "Register the feature that defines the extension or fix the extension name.";
+    };
+    readonly extensionProviderNotRequired: {
+        readonly id: "extension/provider-not-required";
+        readonly summary: "A feature using an extension lists the defining feature in requires or optionalRequires.";
+        readonly fix: "Add the defining feature via r.requires({ features: [...] }).";
+    };
+}, {
+    readonly failed: {
+        readonly id: "boot-check/failed";
+        readonly summary: "A feature's r.bootCheck invariant holds for the mounted feature set.";
+        readonly fix: "Satisfy the invariant named in the message or unmount the feature that declares it.";
+    };
+}];
+export declare const FRAMEWORK_BOOT_RULES: readonly BootRule[];

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

@@ -0,0 +1,17 @@
+import { API_EXT_RULES } from "./api-ext-rules.js";
+import { BOOT_CHECK_RULES } from "./boot-check-rules.js";
+import { CARD_META_OVERFLOW_RULES } from "./card-meta-overflow-rules.js";
+import { ENTITY_LIST_RULES } from "./entity-list-screens-rules.js";
+import { I18N_RULES } from "./i18n-keys-rules.js";
+import { PII_RULES } from "./pii-retention-rules.js";
+import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
+export const FRAMEWORK_BOOT_RULE_TABLES = [
+    PII_RULES,
+    ENTITY_LIST_RULES,
+    I18N_RULES,
+    CARD_META_OVERFLOW_RULES,
+    SCREEN_ACTION_RULES,
+    API_EXT_RULES,
+    BOOT_CHECK_RULES,
+];
+export const FRAMEWORK_BOOT_RULES = FRAMEWORK_BOOT_RULE_TABLES.flatMap((table) => Object.values(table));

package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts

@@ -0,0 +1,7 @@
+export declare const CARD_META_OVERFLOW_RULES: {
+    readonly overflow: {
+        readonly id: "list/card-meta-overflow";
+        readonly summary: "A card list shows at most the maximum number of meta columns.";
+        readonly fix: "Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true.";
+    };
+};

package/dist/engine/boot-validator/card-meta-overflow-rules.js

@@ -0,0 +1,7 @@
+export const CARD_META_OVERFLOW_RULES = {
+    overflow: {
+        id: "list/card-meta-overflow",
+        summary: "A card list shows at most the maximum number of meta columns.",
+        fix: "Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true.",
+    },
+};

package/dist/engine/boot-validator/card-meta-overflow.js

@@ -2,6 +2,8 @@ import { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind, } from "../../ui-t
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { normalizeListColumn } from "../screen-helpers.js";
+import { bootRuleError } from "./boot-rule.js";
+import { CARD_META_OVERFLOW_RULES } from "./card-meta-overflow-rules.js";
 // Mirrors the type resolution of headless computeListViewModel; only the
 // "select" outcome matters for the card status role.
 function resolveColumnType(spec, storedType, entity) {
@@ -94,5 +96,7 @@ export function validateCardMetaOverflow(features) {
     if (overflows.length === 0)
         return;
     const lines = overflows.map((o) => `  - Feature "${o.feature}" screen "${o.screen}"${o.location !== undefined ? ` ${o.location}` : ""}: ${o.count} meta columns (${o.fields.join(", ")})`);
-    throw new Error(`List cards show at most ${CARD_META_MAX} meta columns (all columns except title, status select and hideOnNarrow ones); more would be cut off on narrow screens:\n${lines.join("\n")}\nReduce each to ${CARD_META_MAX} columns or mark the others hideOnNarrow: true.`);
+    throw bootRuleError(CARD_META_OVERFLOW_RULES.overflow, {
+        message: `List cards show at most ${CARD_META_MAX} meta columns (all columns except title, status select and hideOnNarrow ones); more would be cut off on narrow screens:\n${lines.join("\n")}\nReduce each to ${CARD_META_MAX} columns or mark the others hideOnNarrow: true.`,
+    });
 }

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

@@ -0,0 +1,32 @@
+export declare const ENTITY_LIST_RULES: {
+    readonly searchableFalse: {
+        readonly id: "entity-list/searchable-false";
+        readonly summary: "Operator lists are searchable unless they are on the searchable-false whitelist.";
+        readonly fix: "Set searchable: true or add the screen id to the whitelist.";
+    };
+    readonly defaultSortRequired: {
+        readonly id: "entity-list/default-sort-required";
+        readonly summary: "A list with active search or filterable fields declares a defaultSort.";
+        readonly fix: "Set defaultSort: { field, direction } on the screen.";
+    };
+    readonly defaultSortNotListed: {
+        readonly id: "entity-list/default-sort-not-listed";
+        readonly summary: "defaultSort.field is one of the listed columns.";
+        readonly fix: "Pick a field from columns or add it there.";
+    };
+    readonly defaultSortNotSortable: {
+        readonly id: "entity-list/default-sort-not-sortable";
+        readonly summary: "The defaultSort column is sortable.";
+        readonly fix: "Mark the field sortable or pick another defaultSort field.";
+    };
+    readonly detailWithoutNavigate: {
+        readonly id: "entity-list/detail-without-navigate";
+        readonly summary: "A list whose entity has a detail screen offers a navigate row action.";
+        readonly fix: 'Add a navigate rowAction with id "view" or "edit".';
+    };
+    readonly unknownColumn: {
+        readonly id: "entity-list/unknown-column";
+        readonly summary: "Every column without a label names an entity field, derived field or row-meta column.";
+        readonly fix: "Fix the column field name or give the column a label.";
+    };
+};

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

@@ -0,0 +1,32 @@
+export const ENTITY_LIST_RULES = {
+    searchableFalse: {
+        id: "entity-list/searchable-false",
+        summary: "Operator lists are searchable unless they are on the searchable-false whitelist.",
+        fix: "Set searchable: true or add the screen id to the whitelist.",
+    },
+    defaultSortRequired: {
+        id: "entity-list/default-sort-required",
+        summary: "A list with active search or filterable fields declares a defaultSort.",
+        fix: "Set defaultSort: { field, direction } on the screen.",
+    },
+    defaultSortNotListed: {
+        id: "entity-list/default-sort-not-listed",
+        summary: "defaultSort.field is one of the listed columns.",
+        fix: "Pick a field from columns or add it there.",
+    },
+    defaultSortNotSortable: {
+        id: "entity-list/default-sort-not-sortable",
+        summary: "The defaultSort column is sortable.",
+        fix: "Mark the field sortable or pick another defaultSort field.",
+    },
+    detailWithoutNavigate: {
+        id: "entity-list/detail-without-navigate",
+        summary: "A list whose entity has a detail screen offers a navigate row action.",
+        fix: 'Add a navigate rowAction with id "view" or "edit".',
+    },
+    unknownColumn: {
+        id: "entity-list/unknown-column",
+        summary: "Every column without a label names an entity field, derived field or row-meta column.",
+        fix: "Fix the column field name or give the column a label.",
+    },
+};

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/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.js

@@ -1,6 +1,9 @@
 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,7 +104,9 @@ 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) {
@@ -113,6 +122,8 @@ export function validateFieldValueTranslations(features, enabled) {
         }
     }
     if (missing.length > 0) {
-        throw new Error(`[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.`);
+        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.`,
+        });
     }
 }