@cosmicdrift/kumiko-framework 0.400.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
 
@@ -113,8 +114,9 @@ the field types reject a text field without that stance.
 `personal: false, reason: "is_business_data"` (a snake_case reason) for
 business data. For personal data name the subject, `personal: "self"`,
 `personal: { of: "<ownerField>" }` or `personal: "tenant"`, plus
-`find: "exact" | "fuzzy" | "none" | "secret"`. A plain foreign key to a user
-is `personal: "ref"`. `personal: "self"` is for the row that is the user.
+`find: "exact" | "fuzzy" | "none" | "secret"`. A foreign key to a user
+is `createReferenceField({ entity: "user:user" })`, which defaults to
+`personal: "ref"`; `personal: false` on it fails at boot. `personal: "self"` is for the row that is the user.
 When the record itself is the person, such as a contact or a customer that
 is not a user, use `personal: { of: "id" }`; the entity then needs a uuid
 `id`. The framework encrypts personal fields per subject and
@@ -292,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
 
@@ -306,7 +309,7 @@ as bundled features.
 | Business logic beyond CRUD | `r.writeHandler` / `r.queryHandler` with `createEntityExecutor` | `agents/examples/custom-handlers.md` |
 | Filtered lists and counts | Executor `list` with `filter` and `totalCount` | `agents/examples/custom-handlers.md` |
 | Key figures on a dashboard | `dashboard` screen with `stat` / `stat-group` panels and a query handler | `agents/examples/dashboard-stats.md` |
-| Relations between entities | `r.relation(entity, name, { type, target, foreignKey, onDelete })` | `agents/examples/relations.md` |
+| Relations between entities | `createReferenceField({ entity })` for the foreign key (user ids: `entity: "user:user"`), `r.relation(entity, name, { type, target, foreignKey, onDelete })` | `agents/examples/relations.md` |
 | Structured sub-objects in a field | Embedded fields | `agents/examples/embedded.md` |
 | List, edit, custom screens and navs | `r.screen`, `r.nav` | `agents/examples/screens-nav.md` |
 | A record page with header, metrics, tabs | `projectionDetail` with `header`, `metrics`, `layout.mode: "tabs"` | `agents/examples/record-detail-layout.md` |

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;
@@ -45,6 +47,7 @@ function createLongTextField<R extends true | false = false>(overrides: Partial<
 function createMoneyField<R extends true | false = false>(overrides?: Partial<Omit<MoneyFieldDef, "type" | "required">> & { required?: R; }): MoneyFieldDef & { required: R; };
 function createMultiSelectField<const TOptions extends string[]>(opts: { options: TOptions; } & Partial<Omit<MultiSelectFieldDef<TOptions>, "type" | "options" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): MultiSelectFieldDef<TOptions>; // Multi-select field — N values from a fixed option list.
 function createNumberField<R extends true | false = false>(overrides?: Partial<Omit<NumberFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): NumberFieldDef & { required: R; }; // Numeric field — `double precision` column by default (fractional values allowed end to end).
+function createReferenceField<R extends true | false = false>(opts: { entity: string; } & Partial<Omit<ReferenceFieldDef, "type" | "entity" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): ReferenceFieldDef & { required: R; }; // Foreign key to another entity (`"customer"` or `"feature:entity"`), stored as a UUID.
 function createRegistry(rawFeatures: FeatureDefinition[]): Registry;
 function createSeed(opts: CreateSeedOptions): ConfigSeedDef;
 function createSelectField<const TOptions extends string[], R extends true | false = false>(opts: { options: TOptions; } & Partial<Omit<SelectFieldDef<NoInfer<TOptions>>, "type" | "options" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): SelectFieldDef<TOptions> & { required: R; };
@@ -60,14 +63,14 @@ function createUserConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOpti
 function declareEscapeHatch(declaration: EscapeHatchDeclaration): void;
 function dedupeFeatures(features: FeatureDefinition[]): FeatureDefinition[];
 function defineApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, table: ProjectionTable) => Promise<void>): SingleStreamApplyFn;
-function defineEntityCreateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
-function defineEntityDeleteHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
+function defineEntityCreateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): EntityWriteHandlerDef;
+function defineEntityDeleteHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): EntityWriteHandlerDef;
 function defineEntityDetailHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
 function defineEntityListHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
 function defineEntityQueryHandler(name: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
-function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
-function defineEntityUpdateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
-function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
+function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): EntityWriteHandlerDef;
+function defineEntityUpdateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): EntityWriteHandlerDef;
+function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): EntityWriteHandlerDef;
 function defineFeature<const TName extends string, TExports = undefined>(name: TName, setup: (r: FeatureRegistrar<TName>) => TExports, settings?: DefineFeatureSettings): FeatureDefinition & { exports: TExports; };
 function defineMspApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, ctx: MultiStreamApplyContext) => Promise<void>): MultiStreamApplyFn;
 function definePagedQueryHandler<const TName extends string, TSchema extends ZodType, TRow = unknown, TMap extends object = KumikoEventTypeMap>(def: QueryHandlerDefinition<TName, TSchema, CursorResult<TRow>, TMap>, ..._noSecretInResponse: true extends ContainsSecret<CursorResult<TRow>> ? [ secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field." ] : [ ]): PagedQueryHandlerDefinition<TName, TSchema, TRow, TMap>;
@@ -224,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);
 }
@@ -314,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.
@@ -426,6 +450,7 @@ type ContentCollectionDefinition = {
   variableSchema?: Readonly<Record<string, string>>;
   nav: {
     label: string;
+    entryLabel?: string;
     icon?: NavIconKey;
     parent?: string;
     order?: number;
@@ -1713,6 +1738,7 @@ type ValidateBootOptions = {
   env?: Readonly<Record<string, string | undefined>>; // Env the encrypted-field master-key probe reads.
   entityFieldCipher?: EnvelopeCipher; // The cipher the runner injects after validation (built from the app's `masterKey` or the env keyring).
   requiredLocales?: string[]; // Locales every translation key must carry across all mounted features (locale packages count).
+  requireFieldValueTranslations?: boolean; // Require translations for the values that entityList columns and entityEdit fields display: select/multiSelect option labels and the column headers and select options of embedded lists.
 };
 type ValidationError = {
   field: string;

package/agents/api/testing-stack.md

@@ -13,6 +13,7 @@ function createRequestHelper(app: Hono, jwt: JwtHelper, options?: RequestHelperO
 function createTestDb(arg?: string | CreateTestDbOptions): Promise<TestDb>;
 function createTestRedis(opts?: CreateTestRedisOptions): Promise<TestRedis>;
 function drainEventConsumers(stack: Pick<TestStack, "db" | "eventDispatcher">, consumerNames: [ string, ...string[] ], options?: { maxPasses?: number; }): Promise<void>;
+function dropTestDb(baseUrl: string, dbName: string): Promise<void>;
 function pushEntityProjectionTables(stack: DbHolder, registry: Registry): Promise<void>; // Push all implicit-projection tables — one per `r.entity()` — that the registry knows about.
 function resetEventStore(stack: { db: unknown; eventDispatcher?: EventDispatcher; }, extraTables?: (unknown | string)[]): Promise<void>; // Wipes event store + framework-state + the given feature read-models in one TRUNCATE, then re-registers the event-consumer state rows.
 function setupTestStack(options: TestStackOptions): Promise<TestStack>;

package/agents/api/types.md

@@ -903,6 +903,16 @@ type WorkflowTrigger = // Trigger configuration for a workflow.
 type NumericDerivedOp = Exclude<EmbeddedDerivedCellDef["op"], "inRange">;
 ```
 
+## packages/framework/src/engine/entity-handlers.ts
+
+```ts
+type EntityWriteHandlerDef = WriteHandlerDef & { // The phase slots are always unset on entity handlers, so a consumer can spread one into its own handler and add typed phases without inheriting the slot types.
+  reserveBeforeTransaction?: undefined;
+  beforeTransaction?: undefined;
+  beforeTransactionWhenNested?: undefined;
+};
+```
+
 ## packages/framework/src/engine/event-helpers.ts
 
 ```ts
@@ -3162,10 +3172,14 @@ type ReadGateDef = {
     entity: string;
     field: string;
   }; // Row readable only if at least one live row of `entity` with `field` = row.id is readable through that entity's own parentRef gate (host visibility).
+  allLinks?: {
+    entity: string;
+    field: string;
+  }; // Like `anyLink`, but every live link row must be readable, and there must be at least one.
   fileOwner?: {
     field: string;
   }; // Row readable only if the file_ref in `field` is live and readable through its owner: owner row readable (ownership, parentRef, handler gate) and the field read access on the file_ref's fieldName passes.
-  linkExemptRoles?: string[]; // Roles that skip `anyLink` (they also see unlinked rows).
+  linkExemptRoles?: string[]; // Roles that skip `anyLink` / `allLinks` (they also see unlinked rows).
 };
 ```
 
@@ -4769,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,13 +8,13 @@ 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` | 411 |
+| `@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 |
 | `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 38 |
 | `@cosmicdrift/kumiko-framework/seeding` | `api/framework-seeding.md` | 6 |
 | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 298 |
-| `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 21 |
+| `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 22 |
 | `@cosmicdrift/kumiko-testing/helpers` | `api/testing-helpers.md` | 71 |
 | `@cosmicdrift/kumiko-dev-server/testing` | `api/dev-server-testing.md` | 5 |

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/agents/examples/relations.md

@@ -217,7 +217,12 @@ describe("cascade: deleting member removes tasks", () => {
 
 ```ts
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createReferenceField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 export const teamEntity = createEntity({
   table: "read_sample_teams",
@@ -230,7 +235,12 @@ export const memberEntity = createEntity({
   table: "read_sample_members",
   fields: {
     name: createTextField({ personal: { of: "id" }, find: "none", required: true }),
-    teamId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+    teamId: createReferenceField({
+      entity: "team",
+      personal: false,
+      reason: "is_system_identifier",
+      required: true,
+    }),
     role: createTextField({ personal: false, reason: "is_business_data" }),
   },
 });
@@ -239,7 +249,7 @@ export const taskEntity = createEntity({
   table: "read_sample_member_tasks",
   fields: {
     title: createTextField({ personal: false, reason: "is_business_data", required: true }),
-    memberId: createTextField({ personal: "ref", required: true }),
+    memberId: createReferenceField({ entity: "member", personal: "ref", required: true }),
   },
 });
 

package/dist/config/index.d.ts

@@ -20,7 +20,7 @@ export type AppPorts = {
     readonly infra?: AppInfraPorts;
 };
 /** The boot-validator options an app owns; `env` and the cipher are injected by the runners. */
-export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "requiredLocales" | "warnOnUniqueAccessRoles">;
+export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "requiredLocales" | "requireFieldValueTranslations" | "warnOnUniqueAccessRoles">;
 export type AppConfig = {
     /** Features mounted in every environment: dev, tests, prod. */
     readonly features: readonly FeatureDefinition[];

package/dist/db/read-gate-clause.js

@@ -42,7 +42,9 @@ function liveRowSql(entity, table, alias) {
 function isRoleExempt(gate, user) {
     return user.roles.some((role) => gate.linkExemptRoles?.includes(role) === true);
 }
-function anyLinkClause(input, link) {
+// "any": one readable live link suffices. "all": additionally no live link may be unreadable;
+// COALESCE keeps a NULL from the ownership SQL from counting as readable.
+function linkClause(input, link, mode) {
     const { option, user, db, tableName } = input;
     const linkEntity = option.entities.get(link.entity);
     if (linkEntity?.parentRef === undefined)
@@ -56,18 +58,24 @@ function anyLinkClause(input, link) {
     if (linkOwnership.kind === "empty")
         return EMPTY;
     const sql = new GateSql();
-    const conditions = [
+    const linkRowsOfThisRow = () => [
         `"${LINK_ALIAS}"."${physicalColumnName(linkTable, link.field)}"::text = "${tableName}"."${physicalColumnName(input.table, "id")}"::text`,
         ...tenantScopeSql(sql, db, linkTable, LINK_ALIAS),
         ...liveRowSql(linkEntity, linkTable, LINK_ALIAS),
     ];
+    const existsLink = (conditions) => `EXISTS (SELECT 1 FROM "${linkTableName}" AS "${LINK_ALIAS}" WHERE ${conditions.join(" AND ")})`;
+    const readable = linkRowsOfThisRow();
     if (linkOwnership.kind === "sql")
-        conditions.push(sql.embed(linkOwnership));
-    return {
-        kind: "sql",
-        sqlText: `EXISTS (SELECT 1 FROM "${linkTableName}" AS "${LINK_ALIAS}" WHERE ${conditions.join(" AND ")})`,
-        params: sql.params,
-    };
+        readable.push(sql.embed(linkOwnership));
+    let sqlText = existsLink(readable);
+    if (mode === "all" && linkOwnership.kind === "sql") {
+        const unreadable = [
+            ...linkRowsOfThisRow(),
+            `NOT COALESCE((${sql.embed(linkOwnership)}), FALSE)`,
+        ];
+        sqlText = `(${sqlText} AND NOT ${existsLink(unreadable)})`;
+    }
+    return { kind: "sql", sqlText, params: sql.params };
 }
 // Every registered entity with a file field can own a file. Join rows and gated entities
 // are left out: their readability is not resolvable without recursion.
@@ -178,8 +186,13 @@ export function buildReadGateClause(entity, table, tableName, user, db, option)
         return EMPTY;
     const input = { entity, table, tableName, user, db, option };
     let clause = PASS;
-    if (gate.anyLink !== undefined && !isRoleExempt(gate, user)) {
-        clause = combineClauses(clause, anyLinkClause(input, gate.anyLink));
+    if (!isRoleExempt(gate, user)) {
+        if (gate.anyLink !== undefined) {
+            clause = combineClauses(clause, linkClause(input, gate.anyLink, "any"));
+        }
+        if (gate.allLinks !== undefined) {
+            clause = combineClauses(clause, linkClause(input, gate.allLinks, "all"));
+        }
     }
     if (gate.fileOwner !== undefined) {
         clause = combineClauses(clause, fileOwnerClause(input, gate.fileOwner.field));

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