@cosmicdrift/kumiko-framework 0.401.0 → 0.402.0

package/AGENTS.md

@@ -15,6 +15,7 @@ not exist in your version:
 | `agents/api/<entry>.md` | Signatures of one entry point; options and screen types as property lists |
 | `agents/api/types.md` | Types the entry points use but do not export, such as nested option shapes |
 | `agents/widgets.md` | Every value export of `@cosmicdrift/kumiko-renderer/web` with its short description |
+| `agents/boot-rules.md` | Every boot rule by id: summary, fix and source file; a boot violation links its entry |
 | `agents/examples.md` | Index of the worked examples, one per concept |
 | `agents/examples/<name>.md` | One tested sample app: README plus every source and test file |
 
@@ -33,7 +34,7 @@ Order of work for a new feature:
    `agents/api.md` instead of `dist/*.d.ts`.
 4. Build the feature with the declarative building blocks below.
 5. Write an integration test against the real stack.
-6. Run boot validation and the tests. Boot errors name the fix; apply it.
+6. Run boot validation and the tests. Boot errors name the fix; apply it. Each violation carries a rule id whose entry is in `agents/boot-rules.md`.
 
 ## Mental model
 
@@ -293,7 +294,8 @@ produces code that compiles and then fails in production.
   unknown field in a column, a nav pointing at a missing screen, an
   encrypted field marked searchable. The message names the
   feature, the place and the fix. Apply the fix the message names instead
-  of working around the check.
+  of working around the check. Each violation shows a rule id and, for
+  classified rules, a `Rule:` link to its entry in `agents/boot-rules.md`.
 
 ## I need X, use Y
 

package/agents/api/framework-engine.md

@@ -11,6 +11,7 @@ function assertNotificationVariables(registry: Pick<Registry, "getAllNotificatio
 function assignableAppRolesFromUsages(usages: { entityName: string; options?: Record<string, unknown> | undefined; }[]): AssignableAppRoles;
 function assignableAppRolesOf(registry: Pick<Registry, "getExtensionUsages">): AssignableAppRoles;
 function attachOutsideTransaction<T extends object, O extends object | undefined>(db: T, outsideTransaction: O): T & { outsideTransaction: O; };
+function bootRuleError(rule: BootRule, details: { message: string; }): BootRuleViolation;
 function bridgeStub(opts?: { user?: SessionUser; log?: HandlerObservability["log"]; dispatch?: Partial<HandlerDispatch>; services?: Partial<ContextServices>; }): Pick<HandlerContext, "dispatch" | "events" | "auth" | "obs" | "hasFeature" | "tz" | "locale" | "user" | "services" | "lifecycle" | "tenants">;
 function buildAppSchema(registry: Registry, options?: BuildAppSchemaOptions): AppSchema;
 function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchema;
@@ -20,6 +21,7 @@ function buildPipelineSteps<TPayload, TAwaits extends Record<string, AwaitedEven
 function buildSessionRoles(globalRoles: string[], membershipRoles: string[]): string[];
 function buildUpdateSchema(entity: EntityDefinition, currencies?: string[], excludedFields?: string[]): z.ZodObject<Record<string, z.ZodTypeAny>>;
 function canActorAssignRole(actorRoles: string[], role: string, assignableAppRoles?: AssignableAppRoles): boolean;
+function collectBootRuleViolations<T>(items: Iterable<T>, run: (item: T) => void): void;
 function collectCardMetaOverflow(features: FeatureDefinition[]): CardMetaOverflow[];
 function collectWriteHandlerQns(features: FeatureDefinition[]): Set<string>;
 function compareVersions(a: string, b: string): number;
@@ -225,6 +227,14 @@ const templateVariable: { text; link; richText; money; date; percent; images; li
 ## Classes
 
 ```ts
+class BootRuleViolation extends Error {
+  constructor(rule: BootRule, message: string);
+  name: unknown;
+}
+class BootValidationError extends Error {
+  constructor(violations: BootViolation[]);
+  name: unknown;
+}
 class ProbeFailure extends Error {
   constructor(text: ProbeText);
 }
@@ -315,6 +325,19 @@ type BeforeTransactionResult<TPrepared = unknown> = // Outcome of a write handle
   | WriteFailure
 ;
 type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "rateLimit"; // runProdApp options a stack can depend on; runProdApp checks the set at boot.
+type BootRule = {
+  id: string;
+  summary: string;
+  fix: string;
+};
+type BootRuleTable = Readonly<Record<string, BootRule>>;
+type BootViolation = {
+  ruleId: string;
+  check: string;
+  feature?: string;
+  message: string;
+  fix?: string;
+};
 type BundledListsOptions = { // One `table` block for every entityList, projectionList and relatedList of the bundled features.
   table: ListTableOptions;
   pinFirstColumn?: boolean; // Pins the first column left on every bundled list where no column is pinned.
@@ -427,6 +450,7 @@ type ContentCollectionDefinition = {
   variableSchema?: Readonly<Record<string, string>>;
   nav: {
     label: string;
+    entryLabel?: string;
     icon?: NavIconKey;
     parent?: string;
     order?: number;

package/agents/api/types.md

@@ -4783,6 +4783,7 @@ type MetricSpec = {
   navigate?: MetricNavigate;
   tone?: DashboardStatTone; // Tile color as on dashboard stat panels; not applied while the value is 0.
   icon?: NavIconKey; // Icon chip of the tile; only drawn with `metricsStyle: "tiles"`.
+  format?: FormatSpec; // Formats the displayed value (e.g. `date`, `enumOption`); the tone still resolves on the raw value.
 };
 type RecordHeaderSpec = {
   title: string;

package/agents/api.md

@@ -8,7 +8,7 @@ Format: one line per function or constant, object and options types as property
 
 | Import path | File | Exports |
 | --- | --- | --- |
-| `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 412 |
+| `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 419 |
 | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 25 |
 | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 154 |
 | `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 150 |

package/agents/boot-rules.md

@@ -0,0 +1,98 @@
+<!-- Generated by `bun run gen:agent-docs` from boot rule tables (`*-rules.ts`, `boot-rules.ts`). Do not edit. -->
+
+# Boot rules
+
+`validateBoot` reports every violation as `- [<id>] <message>`, followed by a `Fix:` and a `Rule:` line that links the entry below. Violations with an `unclassified/<check>` id have no entry yet. `kumiko-schema validate --json` returns the same ids.
+
+## api
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="api-provider-not-mounted"></a>`api/provider-not-mounted` | The feature exposing a used API is part of the app's feature list. | Register the provider feature in the app's feature list. | `packages/framework/src/engine/boot-validator/api-ext-rules.ts` |
+| <a id="api-provider-not-required"></a>`api/provider-not-required` | A feature using an API lists the exposing feature in requires or optionalRequires. | Add the exposing feature via r.requires({ features: [...] }). | `packages/framework/src/engine/boot-validator/api-ext-rules.ts` |
+| <a id="api-unknown-api"></a>`api/unknown-api` | Every r.usesApi name is exposed by some mounted feature. | Mount the feature that exposes the API or fix the API name. | `packages/framework/src/engine/boot-validator/api-ext-rules.ts` |
+
+## boot-check
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="boot-check-failed"></a>`boot-check/failed` | A feature's r.bootCheck invariant holds for the mounted feature set. | Satisfy the invariant named in the message or unmount the feature that declares it. | `packages/framework/src/engine/boot-validator/boot-check-rules.ts` |
+
+## entity-list
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="entity-list-default-sort-not-listed"></a>`entity-list/default-sort-not-listed` | defaultSort.field is one of the listed columns. | Pick a field from columns or add it there. | `packages/framework/src/engine/boot-validator/entity-list-screens-rules.ts` |
+| <a id="entity-list-default-sort-not-sortable"></a>`entity-list/default-sort-not-sortable` | The defaultSort column is sortable. | Mark the field sortable or pick another defaultSort field. | `packages/framework/src/engine/boot-validator/entity-list-screens-rules.ts` |
+| <a id="entity-list-default-sort-required"></a>`entity-list/default-sort-required` | A list with active search or filterable fields declares a defaultSort. | Set defaultSort: { field, direction } on the screen. | `packages/framework/src/engine/boot-validator/entity-list-screens-rules.ts` |
+| <a id="entity-list-detail-without-navigate"></a>`entity-list/detail-without-navigate` | A list whose entity has a detail screen offers a navigate row action. | Add a navigate rowAction with id "view" or "edit". | `packages/framework/src/engine/boot-validator/entity-list-screens-rules.ts` |
+| <a id="entity-list-searchable-false"></a>`entity-list/searchable-false` | Operator lists are searchable unless they are on the searchable-false whitelist. | Set searchable: true or add the screen id to the whitelist. | `packages/framework/src/engine/boot-validator/entity-list-screens-rules.ts` |
+| <a id="entity-list-unknown-column"></a>`entity-list/unknown-column` | Every column without a label names an entity field, derived field or row-meta column. | Fix the column field name or give the column a label. | `packages/framework/src/engine/boot-validator/entity-list-screens-rules.ts` |
+
+## extension
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="extension-provider-not-required"></a>`extension/provider-not-required` | A feature using an extension lists the defining feature in requires or optionalRequires. | Add the defining feature via r.requires({ features: [...] }). | `packages/framework/src/engine/boot-validator/api-ext-rules.ts` |
+| <a id="extension-unknown-extension"></a>`extension/unknown-extension` | Every extension a feature uses is defined by some mounted feature. | Register the feature that defines the extension or fix the extension name. | `packages/framework/src/engine/boot-validator/api-ext-rules.ts` |
+
+## i18n
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="i18n-locale-inconsistent"></a>`i18n/locale-inconsistent` | Every locale a feature uses is maintained for every one of its translation keys. | Add the missing locale to the key, or move that locale into a locale package. | `packages/framework/src/engine/boot-validator/i18n-keys-rules.ts` |
+| <a id="i18n-missing-feature-key"></a>`i18n/missing-feature-key` | Every translation key a feature surface requires is defined. | Add the key via r.translations(...) in the feature. | `packages/framework/src/engine/boot-validator/i18n-keys-rules.ts` |
+| <a id="i18n-missing-field-value-translation"></a>`i18n/missing-field-value-translation` | With requireFieldValueTranslations, select options and embedded cells are translated. | Add the keys via r.translations(...) in the owning feature. | `packages/framework/src/engine/boot-validator/i18n-keys-rules.ts` |
+| <a id="i18n-missing-required-locale"></a>`i18n/missing-required-locale` | Every translation key exists in every locale the app requires. | Load the matching locale package or add the missing translations. | `packages/framework/src/engine/boot-validator/i18n-keys-rules.ts` |
+| <a id="i18n-missing-settings-hub-key"></a>`i18n/missing-settings-hub-key` | Every translation key the generated settings hub requires is defined. | Add the key via r.translations(...) in the owning feature. | `packages/framework/src/engine/boot-validator/i18n-keys-rules.ts` |
+
+## list
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="list-card-meta-overflow"></a>`list/card-meta-overflow` | A card list shows at most the maximum number of meta columns. | Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true. | `packages/framework/src/engine/boot-validator/card-meta-overflow-rules.ts` |
+
+## pii
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="pii-lookupable-non-text"></a>`pii/lookupable-non-text` | Blind-index lookups apply to text fields only. | Use a text field or set find: "none". | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-lookupable-without-subject"></a>`pii/lookupable-without-subject` | A blind-index lookup requires a subject annotation on the field. | Add a personal annotation or set find: "none". | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-multiple-subject-annotations"></a>`pii/multiple-subject-annotations` | A field carries at most one subject-key annotation. | Keep a single personal annotation on the field. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-personal-jsonb-custom-fields"></a>`pii/personal-jsonb-custom-fields` | The custom-fields jsonb column cannot carry a personal annotation. | Drop the personal annotation. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-personal-jsonb-flag"></a>`pii/personal-jsonb-flag` | A personal jsonb field cannot be sortable, filterable, searchable or lookupable, its value is a ciphertext string. | Remove the flag or the personal annotation. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-personal-jsonb-index"></a>`pii/personal-jsonb-index` | A personal jsonb field is not part of an entity index. | Drop the index or the personal annotation. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-personal-of-invalid-when-absent"></a>`pii/personal-of-invalid-when-absent` | personal.whenAbsent is either "tenant" or "self". | Remove whenAbsent or set it to "tenant" or "self". | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-personal-of-missing-owner-name"></a>`pii/personal-of-missing-owner-name` | personal: { of } names the owner field. | Pass the name of the owner field: personal: { of: "<ownerField>" }. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-personal-of-optional-owner"></a>`pii/personal-of-optional-owner` | An optional owner field of personal: { of } declares a whenAbsent fallback. | Set whenAbsent to "tenant" or "self", or make the owner field required. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-personal-of-owner-type"></a>`pii/personal-of-owner-type` | The owner field named by personal: { of } is a reference or text field. | Use a reference or text field as owner. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-personal-of-unknown-owner"></a>`pii/personal-of-unknown-owner` | The owner field named by personal: { of } exists on the entity. | Point personal.of at an existing field of the entity. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-plaintext-user-reference"></a>`pii/plaintext-user-reference` | A reference to the user entity is never plaintext. | Use the default reference field or personal: "ref" instead of personal: false. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-sensitive-searchable"></a>`pii/sensitive-searchable` | A sensitive field is never searchable. | Drop searchable, or add writeOnly to never return the value. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-sensitive-without-ciphertext"></a>`pii/sensitive-without-ciphertext` | A sensitive field is stored as ciphertext at rest. | Add a subject annotation or encrypted: true. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-subject-key-sortable"></a>`pii/subject-key-sortable` | A field with a subject-key annotation is not sortable, its column is ciphertext. | Drop sortable, use find: "exact" for equality lookups, or keep the field plaintext. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-text-without-personal-stance"></a>`pii/text-without-personal-stance` | Every text and longText field declares whether it holds personal data. | Declare a personal stance, or personal: false with a reason stating why the value is not personal data. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-write-only-conflicting-flag"></a>`pii/write-only-conflicting-flag` | A writeOnly field cannot be defaulted, searched, sorted, filtered or looked up. | Remove either writeOnly or the conflicting flag. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-write-only-embedded-sub-field"></a>`pii/write-only-embedded-sub-field` | writeOnly is only supported on top-level text fields, not on embedded sub-fields. | Remove writeOnly from the sub-field or declare it on a top-level text field. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-write-only-non-text"></a>`pii/write-only-non-text` | writeOnly applies to text fields only. | Use a text field or remove writeOnly. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+| <a id="pii-write-only-without-sensitive"></a>`pii/write-only-without-sensitive` | A writeOnly field is also sensitive. | Declare the field with find: "secret". | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+
+## retention
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="retention-unknown-reference"></a>`retention/unknown-reference` | retention.reference names an existing field or a framework timestamp. | Point retention.reference at an existing field or a framework-managed timestamp. | `packages/framework/src/engine/boot-validator/pii-retention-rules.ts` |
+
+## screen
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="screen-action-icon"></a>`screen/action-icon` | Every screen action resolves to a registered icon. | Set icon to a registered NAV_ICONS key or use an action id that resolves one via the default icon map. | `packages/framework/src/engine/boot-validator/screens-actions-rules.ts` |
+
+## user-data-rights
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="user-data-rights-empty-hook"></a>`user-data-rights/empty-hook` | An EXT_USER_DATA registration declares at least one of an export or a delete hook. | Register at least one hook. | `packages/bundled-features/src/user-data-rights/boot-rules.ts` |
+| <a id="user-data-rights-export-without-delete"></a>`user-data-rights/export-without-delete` | An entity exported via EXT_USER_DATA also registers a delete hook. | Add a delete hook, or a documented no-op delete if erasure is handled elsewhere. | `packages/bundled-features/src/user-data-rights/boot-rules.ts` |
+| <a id="user-data-rights-missing-hook"></a>`user-data-rights/missing-hook` | An entity with user-subject fields registers an EXT_USER_DATA hook. | Register r.useExtension(EXT_USER_DATA, ...) for the entity, or a documented no-op hook if it is covered elsewhere. | `packages/bundled-features/src/user-data-rights/boot-rules.ts` |

package/dist/db/replay-migration-sql.js

@@ -151,7 +151,7 @@ function applyStatement(schema, statement, context) {
         // skip: DO block fully handled above
         return;
     }
-    const createAs = statement.match(new RegExp(`^CREATE\\s+(?:UNLOGGED\\s+)?TABLE\\s+(IF NOT EXISTS\\s+)?${IDENT}\\s*(?:\\(([^)]*)\\)\\s*)?AS\\b([\\s\\S]*)$`, "i"));
+    const createAs = statement.match(new RegExp(`^CREATE\\s+(?:UNLOGGED\\s+)?TABLE\\s+(IF NOT EXISTS\\s+)?${IDENT}(?:\\s*\\(([^)]*)\\)\\s*|\\s+)AS\\b([\\s\\S]*)$`, "i"));
     if (createAs?.[2] !== undefined && createAs[4] !== undefined) {
         if (!(createAs[1] !== undefined && schema.has(createAs[2]))) {
             const explicitColumns = createAs[3] === undefined ? undefined : parseColumnNames(createAs[3]);

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

@@ -0,0 +1,27 @@
+export declare const API_EXT_RULES: {
+    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: [...] }).";
+    };
+};

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

@@ -0,0 +1,27 @@
+export const API_EXT_RULES = {
+    unknownApi: {
+        id: "api/unknown-api",
+        summary: "Every r.usesApi name is exposed by some mounted feature.",
+        fix: "Mount the feature that exposes the API or fix the API name.",
+    },
+    providerNotRequired: {
+        id: "api/provider-not-required",
+        summary: "A feature using an API lists the exposing feature in requires or optionalRequires.",
+        fix: "Add the exposing feature via r.requires({ features: [...] }).",
+    },
+    providerNotMounted: {
+        id: "api/provider-not-mounted",
+        summary: "The feature exposing a used API is part of the app's feature list.",
+        fix: "Register the provider feature in the app's feature list.",
+    },
+    unknownExtension: {
+        id: "extension/unknown-extension",
+        summary: "Every extension a feature uses is defined by some mounted feature.",
+        fix: "Register the feature that defines the extension or fix the extension name.",
+    },
+    extensionProviderNotRequired: {
+        id: "extension/provider-not-required",
+        summary: "A feature using an extension lists the defining feature in requires or optionalRequires.",
+        fix: "Add the defining feature via r.requires({ features: [...] }).",
+    },
+};

package/dist/engine/boot-validator/api-ext.js

@@ -1,4 +1,7 @@
 import { createFallbackLogger } from "../../logging/utils.js";
+import { API_EXT_RULES } from "./api-ext-rules.js";
+import { collectBootRuleViolations } from "./boot-report.js";
+import { bootRuleError } from "./boot-rule.js";
 const log = createFallbackLogger("kumiko:boot");
 // --- Cross-feature API exposure / usage matching ---
 //
@@ -13,42 +16,52 @@ const log = createFallbackLogger("kumiko:boot");
 // apiNames must be globally unique across features; validateBoot() checks
 // this before the per-feature walk.
 export function validateApiExposureMatching(feature, allExposedApis, featureMap) {
-    for (const apiName of feature.usedApis) {
+    collectBootRuleViolations(feature.usedApis, (apiName) => {
         const providerFeature = allExposedApis.get(apiName);
         if (!providerFeature) {
             const known = [...allExposedApis.keys()].sort().join(", ") || "(none)";
-            throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") but no feature exposes that API. Known exposed APIs: ${known}`);
+            throw bootRuleError(API_EXT_RULES.unknownApi, {
+                message: `[Feature ${feature.name}] r.usesApi("${apiName}") but no feature exposes that API. Known exposed APIs: ${known}`,
+            });
         }
         if (providerFeature === feature.name) {
             log.warn(`[Feature ${feature.name}] r.usesApi("${apiName}") on its own r.exposesApi — typically a refactor leftover. Call the impl directly instead.`);
-            continue;
+            return;
         }
         const allDeps = [...feature.requires, ...feature.optionalRequires];
         if (!allDeps.includes(providerFeature)) {
-            throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires({ features: ["${providerFeature}"] }).`);
+            throw bootRuleError(API_EXT_RULES.providerNotRequired, {
+                message: `[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires({ features: ["${providerFeature}"] }).`,
+            });
         }
         // Sanity: the provider feature must exist in this app's feature set.
         // This should always hold when allExposedApis was built from `features`,
         // but remains defensive for unclear constructor paths.
         if (!featureMap.has(providerFeature)) {
-            throw new Error(`[Feature ${feature.name}] internal: r.usesApi("${apiName}") points to provider "${providerFeature}" which is not in feature map. Register the provider feature in the app's feature list.`);
+            throw bootRuleError(API_EXT_RULES.providerNotMounted, {
+                message: `[Feature ${feature.name}] internal: r.usesApi("${apiName}") points to provider "${providerFeature}" which is not in feature map. Register the provider feature in the app's feature list.`,
+            });
         }
-    }
+    });
 }
 // --- Extension usage validation ---
 export function validateExtensionUsages(feature, extensionProviders) {
-    for (const usage of feature.extensionUsages) {
+    collectBootRuleViolations(feature.extensionUsages, (usage) => {
         const providerFeature = extensionProviders.get(usage.extensionName);
         if (!providerFeature) {
-            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" on entity "${usage.entityName}" but no feature defines that extension. Register the feature that defines it or fix the extension name.`);
+            throw bootRuleError(API_EXT_RULES.unknownExtension, {
+                message: `Feature "${feature.name}" uses extension "${usage.extensionName}" on entity "${usage.entityName}" but no feature defines that extension. Register the feature that defines it or fix the extension name.`,
+            });
         }
-        // self-extension is legitimate: requires(self) would be circular.
         if (providerFeature === feature.name) {
-            continue;
+            // skip: self-extension is legitimate, requires(self) would be circular
+            return;
         }
         const allDeps = [...feature.requires, ...feature.optionalRequires];
         if (!allDeps.includes(providerFeature)) {
-            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}"). Add r.requires({ features: ["${providerFeature}"] }).`);
+            throw bootRuleError(API_EXT_RULES.extensionProviderNotRequired, {
+                message: `Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}"). Add r.requires({ features: ["${providerFeature}"] }).`,
+            });
         }
-    }
+    });
 }

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

@@ -0,0 +1,7 @@
+export declare const BOOT_CHECK_RULES: {
+    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.";
+    };
+};

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

@@ -0,0 +1,7 @@
+export const BOOT_CHECK_RULES = {
+    failed: {
+        id: "boot-check/failed",
+        summary: "A feature's r.bootCheck invariant holds for the mounted feature set.",
+        fix: "Satisfy the invariant named in the message or unmount the feature that declares it.",
+    },
+};

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

@@ -1,16 +1,28 @@
+import { BOOT_CHECK_RULES } from "./boot-check-rules.js";
+import { BootRuleFailures, BootRuleViolation, bootRuleError } from "./boot-rule.js";
 // r.bootCheck(fn) lets a feature declare its own mount-invariant instead of
 // relying on framework-internal knowledge (the gdpr-storage.ts guards are
 // the framework-owned version of this same idea). Each registered fn gets
 // the full mounted-feature set and throws to fail the boot; we wrap the
 // message with the owning feature's name so the error text points back at
 // the feature that declared the check.
+function prefixFailure(failure, prefix) {
+    const rule = failure instanceof BootRuleViolation ? failure.rule : BOOT_CHECK_RULES.failed;
+    return new BootRuleViolation(rule, prefix + failure.message);
+}
 export function runFeatureBootCheck(feature, check, features) {
     const ctx = { features };
+    const prefix = `[Feature ${feature.name}] r.bootCheck failed: `;
     try {
         check(ctx);
     }
     catch (err) {
+        if (err instanceof BootRuleViolation)
+            throw prefixFailure(err, prefix);
+        if (err instanceof BootRuleFailures) {
+            throw new BootRuleFailures(err.failures.map((failure) => prefixFailure(failure, prefix)));
+        }
         const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
+        throw bootRuleError(BOOT_CHECK_RULES.failed, { message: prefix + message });
     }
 }

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

@@ -4,3 +4,4 @@ export type BootReport = {
     finish(): void;
 };
 export declare function createBootReport(): BootReport;
+export declare function collectBootRuleViolations<T>(items: Iterable<T>, run: (item: T) => void): void;

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

@@ -1,4 +1,4 @@
-import { BootValidationError } from "./boot-rule.js";
+import { BootRuleFailures, BootRuleViolation, BootValidationError, } from "./boot-rule.js";
 // A runtime crash is a bug in a validator (or in the input it assumed), not a
 // rule violation: it must surface as itself instead of masquerading as a finding.
 function isRuntimeCrash(thrown) {
@@ -10,6 +10,33 @@ function isRuntimeCrash(thrown) {
         thrown instanceof EvalError ||
         thrown instanceof URIError);
 }
+function violationsOf(failure, checkName, feature) {
+    if (failure instanceof BootRuleFailures) {
+        return failure.failures.flatMap((nested) => violationsOf(nested, checkName, feature));
+    }
+    if (failure instanceof BootValidationError)
+        return failure.violations;
+    const featurePart = feature === undefined ? {} : { feature };
+    if (failure instanceof BootRuleViolation) {
+        return [
+            {
+                ruleId: failure.rule.id,
+                check: checkName,
+                ...featurePart,
+                message: failure.message,
+                fix: failure.rule.fix,
+            },
+        ];
+    }
+    return [
+        {
+            ruleId: `unclassified/${checkName}`,
+            check: checkName,
+            ...featurePart,
+            message: failure.message,
+        },
+    ];
+}
 export function createBootReport() {
     const violations = [];
     let firstCrash;
@@ -31,12 +58,7 @@ export function createBootReport() {
                     firstCrash ??= { thrown };
                 }
                 else if (thrown instanceof Error) {
-                    violations.push({
-                        ruleId: `unclassified/${checkName}`,
-                        check: checkName,
-                        ...(feature === undefined ? {} : { feature }),
-                        message: thrown.message,
-                    });
+                    violations.push(...violationsOf(thrown, checkName, feature));
                 }
                 return false;
             }
@@ -45,3 +67,32 @@ export function createBootReport() {
         finish: endPhase,
     };
 }
+// Boundary per item: every item runs, so one boot reports all independent violations
+// instead of only the first. Crashes behave as in endPhase: dropped next to failures.
+export function collectBootRuleViolations(items, run) {
+    const failures = [];
+    let firstCrash;
+    for (const item of items) {
+        try {
+            run(item);
+        }
+        catch (thrown) {
+            if (isRuntimeCrash(thrown)) {
+                firstCrash ??= { thrown };
+            }
+            else if (thrown instanceof BootRuleFailures) {
+                failures.push(...thrown.failures);
+            }
+            else if (thrown instanceof Error) {
+                failures.push(thrown);
+            }
+        }
+    }
+    const [onlyFailure] = failures;
+    if (onlyFailure !== undefined && failures.length === 1)
+        throw onlyFailure;
+    if (failures.length > 1)
+        throw new BootRuleFailures(failures);
+    if (firstCrash !== undefined)
+        throw firstCrash.thrown;
+}

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

@@ -5,6 +5,26 @@ export type BootViolation = {
     readonly message: string;
     readonly fix?: string;
 };
+export type BootRule = {
+    readonly id: string;
+    readonly summary: string;
+    readonly fix: string;
+};
+export type BootRuleTable = Readonly<Record<string, BootRule>>;
+export declare class BootRuleViolation extends Error {
+    readonly rule: BootRule;
+    readonly name = "BootRuleViolation";
+    constructor(rule: BootRule, message: string);
+}
+export declare function bootRuleError(rule: BootRule, details: {
+    readonly message: string;
+}): BootRuleViolation;
+export declare class BootRuleFailures extends Error {
+    readonly failures: readonly Error[];
+    readonly name = "BootRuleFailures";
+    constructor(failures: readonly Error[]);
+}
+export declare function bootRuleDocLink(ruleId: string): string | undefined;
 export declare class BootValidationError extends Error {
     readonly violations: readonly BootViolation[];
     readonly name = "BootValidationError";

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

@@ -1,6 +1,37 @@
+export class BootRuleViolation extends Error {
+    rule;
+    name = "BootRuleViolation";
+    constructor(rule, message) {
+        super(message);
+        this.rule = rule;
+    }
+}
+export function bootRuleError(rule, details) {
+    return new BootRuleViolation(rule, details.message);
+}
+export class BootRuleFailures extends Error {
+    failures;
+    name = "BootRuleFailures";
+    constructor(failures) {
+        super(failures.map((failure) => failure.message).join("\n"));
+        this.failures = failures;
+    }
+}
+const UNCLASSIFIED_RULE_PREFIX = "unclassified/";
+// Must match anchorOf in packages/guards/src/_lib/agent-docs-boot-rules.ts.
+export function bootRuleDocLink(ruleId) {
+    if (ruleId.startsWith(UNCLASSIFIED_RULE_PREFIX))
+        return undefined;
+    return `agents/boot-rules.md#${ruleId.replaceAll("/", "-")}`;
+}
 function describeViolation(violation) {
-    const line = `- [${violation.ruleId}] ${violation.message}`;
-    return violation.fix === undefined ? line : `${line}\n  Fix: ${violation.fix}`;
+    const lines = [`- [${violation.ruleId}] ${violation.message}`];
+    if (violation.fix !== undefined)
+        lines.push(`  Fix: ${violation.fix}`);
+    const docLink = bootRuleDocLink(violation.ruleId);
+    if (docLink !== undefined)
+        lines.push(`  Rule: ${docLink}`);
+    return lines.join("\n");
 }
 export class BootValidationError extends Error {
     violations;