@cosmicdrift/kumiko-framework 0.401.0 → 0.403.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;
@@ -33,7 +35,7 @@ function createDecimalField<R extends true | false = false>(config: { precision:
 function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef; // Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`), never persisted.
 function createEmbeddedField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef;
 function createEmbeddedListField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef & { multiple: true; };
-function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
+function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; namedFilters?: EntityDefinition["namedFilters"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
 function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): { table: EntityTable; executor: EventStoreExecutor<EntityRow<E>>; };
 function createFileField(overrides?: Partial<Omit<FileFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FileFieldDef;
 function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
@@ -135,6 +137,7 @@ function referenceGroupLabels(ctx: HandlerContext, user: SessionUser, sourceTabl
 function requireTierResolverPlugin(usage: RegistrarExtensionRegistration): TierResolverPlugin;
 function resolveAgentExposure(def: { description?: string; agent?: AgentHandlerHints; }, kind: "query" | "write"): AgentExposure; // Fail-closed: a handler without a `description` stays invisible to the agent unless it opts in explicitly.
 function resolveEntityTransferAdjacency(entities: ReadonlyMap<string, EntityDefinition>, rootEntityType?: string): TransferAdjacency;
+function resolveNamedListFilters(ctx: HandlerContext, user: SessionUser, entityName: string, name: string): Promise<NamedListFilterCondition[]>;
 function runPipeline<TPayload, TData, TMap extends object = KumikoEventTypeMap>(pipelineDef: PipelineDef<TPayload, TData>, event: WriteEvent<TPayload>, handlerCtx: HandlerContext<TMap>, workflow?: PipelineCtx["workflow"], resumeFrom?: number): Promise<WriteResult<TData>>;
 function runStepList<TPayload, TMap extends object = KumikoEventTypeMap>(steps: StepInstance[], event: WriteEvent<TPayload>, handlerCtx: HandlerContext<TMap>, stepsAcc: Record<string, unknown>, scopeAcc: Record<string, unknown>, workflow?: PipelineCtx["workflow"], resumeFrom?: number): Promise<StepListOutcome>; // Walk a step-list.
 function sectionFieldSpecs(section: FieldsOrGroupsSection): EditFieldSpec[];
@@ -225,6 +228,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 +326,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 +451,7 @@ type ContentCollectionDefinition = {
   variableSchema?: Readonly<Record<string, string>>;
   nav: {
     label: string;
+    entryLabel?: string;
     icon?: NavIconKey;
     parent?: string;
     order?: number;
@@ -540,6 +565,7 @@ type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy =
   readGate?: ReadGateDef; // Declarative read gate for rows readable only through other rows (a link to a visible host, a file whose owner is readable).
   retention?: RetentionDef; // Default retention policy for this entity.
   derivedFields?: DerivedFieldsMap; // Read-time computed fields, keyed by name.
+  namedFilters?: Readonly<Record<string, NamedListFilterDef>>; // Named work-queue rules keyed by id, selected via `namedFilter`; function-valued, never in the client schema.
   description?: string; // Optional free-text semantics for the AI agent manifest — see TextFieldDef.description.
   transferable?: boolean; // Opts the rows into `tenant-handover`, a grant-legitimated move from an anonymous tenant to the signed-up account's tenant.
   attachedFileAccess?: "record-only"; // Attached files are readable only through the record's detail query: the files feature's privilegedRoles do not bypass it, the uploader check stays.
@@ -604,6 +630,7 @@ type EntityListScreenDefinition = {
   defaultSort?: ListSortSpec;
   defaultFilters?: Readonly<Record<string, string[] | boolean>>; // Initial facet selection, per filterable field: option values (string facets) or a boolean.
   facets?: Readonly<Record<string, EntityListFacetConfig | false>>; // Per-facet display options for the entity's `filterable` fields, keyed by field name.
+  namedFilters?: NamedListFilterRef[]; // Named work-queue rules offered on this list: ids declared in `EntityDefinition.namedFilters`, `label` an i18n key.
   emptyState?: ListEmptyStateSpec; // Replaces the default empty-list title/hint; the create button stays when the list can create.
   createLabel?: string; // i18n key for the primary create button label (default `kumiko.actions.create`).
   searchPlaceholder?: string; // i18n key for the search field placeholder (default `kumiko.list.search-placeholder`).
@@ -1327,6 +1354,7 @@ type ProjectionListScreenDefinition = {
   paginated?: boolean; // Derived by buildAppSchema from the query handler's Zod schema (`cursor` or `offset` param present).
   filter?: ScreenFilter; // Server-side filter, fixed on the screen — see `ScreenFilter` doc above (entityList).
   facets?: ListFacetSpec[]; // User-toggleable facet dropdowns — see `ListFacetSpec` doc.
+  namedFilters?: NamedListFilterRef[]; // Named work-queue rules the bound query understands: its Zod schema must have a `namedFilter` key (boot-checked) and is sent the selected id in every list and count query.
   slots?: ScreenSlots;
   access?: AccessRule;
 };

package/agents/api/framework-ui-types.md

@@ -252,6 +252,10 @@ type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & {
   deltaToneField?: string;
   icon?: PlatformComponent; // Static icon next to the label.
   accentColor?: string; // Static CSS color value (e.g. "var(--color-debt)") for the icon chip, passed straight to the tile without a registry lookup.
+  navigate?: {
+    screen: string;
+    namedFilter?: string;
+  }; // Makes the tile a link to a list screen (qualified screen id).
 };
 type DashboardText = string | DashboardI18nText; // Plain string is displayed as-is; DashboardI18nText is translated by the renderer.
 type DashboardTextBlock =

package/agents/api/renderer-web.md

@@ -85,7 +85,7 @@ function SidebarProvider(props: React.ComponentProps<"div"> & { defaultOpen?: bo
 function SidebarUser(props: SidebarUserProps): ReactNode;
 function Sparkline(props: { points: number[]; className?: string; }): ReactNode;
 function Stack(props: StackProps): ReactNode;
-function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?: string; tone?: StatTone; accentColor?: string; delta?: StatDelta; trend?: string; spark?: number[]; testId?: string; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
+function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?: string; tone?: StatTone; accentColor?: string; delta?: StatDelta; trend?: string; spark?: number[]; testId?: string; link?: StatLink; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
 function StatusBadge(props: { tone: StatusBadgeTone; children: ReactNode; className?: string; testId?: string; }): ReactNode; // Pill badge with a status dot.
 function StatusBarChart(props: { entries: StatusBarEntry[]; ariaLabel: string; startLabel?: string; endLabel?: string; highlightLast?: boolean; dense?: boolean; testId?: string; }): ReactNode; // Status bar strip (e.g. 90-day uptime): variable-height bars with gradient fade + tick line on top; the last entry gets a "now" accent stripe.
 function StepBar(props: { steps: string[]; currentIndex: number; compactLabel: string; onStepSelect?: (index: number) => void; doneSteps?: boolean[]; selectableSteps?: "done" | "all"; narrowLayout?: "label" | "steps"; orientation?: "horizontal" | "vertical"; heading?: string; description?: string; subtitles?: (string | undefined)[]; upNext?: { heading: string; title: string; subtitle?: string; }; testId?: string; compactTestId?: string; }): ReactNode; // Wizard step overview — numbered chips with a connector line between them.

package/agents/api/types.md

@@ -2676,6 +2676,15 @@ interface ResultTableFooterRow {
 }
 ```
 
+## packages/renderer/src/web/widgets/stat.tsx
+
+```ts
+type StatLink = { // Makes a tile a link; `onPress` is the SPA navigation, `href` serves modified clicks and a11y.
+  href: string;
+  onPress: () => void;
+};
+```
+
 ## packages/testing/src/bundled-injection.ts
 
 ```ts
@@ -4377,6 +4386,30 @@ type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
 };
 ```
 
+## packages/types/src/named-list-filters.ts
+
+```ts
+type NamedListFilterCondition = {
+  field: string;
+  op: NamedListFilterOp;
+  value: unknown;
+};
+type NamedListFilterDef = { // A work-queue rule defined once on the entity: the list and every count query resolve the same conditions.
+  access?: AccessRule;
+  filters: (scope: NamedListFilterScope) => NamedListFilterCondition[] | Promise<NamedListFilterCondition[]>;
+};
+type NamedListFilterOp = "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+type NamedListFilterRef = { // Screen-side reference to an entity-defined named filter; `label` is an i18n key.
+  id: string;
+  label: string;
+};
+type NamedListFilterScope = {
+  ctx: HandlerContext;
+  user: SessionUser;
+  now: Temporal.Instant;
+};
+```
+
 ## packages/types/src/nav.ts
 
 ```ts
@@ -4783,6 +4816,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` | 420 |
 | `@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,110 @@
+<!-- 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` |
+| <a id="entity-list-unknown-named-filter"></a>`entity-list/unknown-named-filter` | Every screen namedFilters id is declared in the entity's namedFilters. | Declare the rule in EntityDefinition.namedFilters or remove the id from the screen. | `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` |
+
+## named-filter
+
+| Rule | Summary | Fix | Source |
+| --- | --- | --- | --- |
+| <a id="named-filter-projection-query-accepts-named-filter"></a>`named-filter/projection-query-accepts-named-filter` | A projectionList with namedFilters binds a query whose schema has a namedFilter key. | Add namedFilter: z.string().optional() to the query schema, resolve it with resolveNamedListFilters and pass the conditions into executor.list filters, the only path that applies field-read and PII guards. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
+| <a id="named-filter-stat-navigate-filter-declared"></a>`named-filter/stat-navigate-filter-declared` | A stat navigate.namedFilter is declared in the target screen's namedFilters. | Add { id, label } to namedFilters of the target screen. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
+| <a id="named-filter-stat-navigate-same-named-filter"></a>`named-filter/stat-navigate-same-named-filter` | A stat's params.namedFilter equals navigate.namedFilter. | Set params.namedFilter to the same id as navigate.namedFilter. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
+| <a id="named-filter-stat-navigate-same-query"></a>`named-filter/stat-navigate-same-query` | A stat with navigate counts with the target list's own query. | Set the stat query to the target list's query. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
+| <a id="named-filter-stat-navigate-static-filter"></a>`named-filter/stat-navigate-static-filter` | A stat repeats the target screen's static filter in params.filter. | Set params.filter to the target screen's filter. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
+| <a id="named-filter-stat-navigate-target"></a>`named-filter/stat-navigate-target` | A stat navigate.screen resolves to an entityList or projectionList screen. | Point navigate.screen at a registered list screen. | `packages/framework/src/engine/boot-validator/named-filter-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/dashboard-stats.md

@@ -36,6 +36,11 @@ query and the fields to read, the query does the counting.
 - **Fallback by reason**: `fallback: { forbidden, notFound }` renders a screen on
   403/404 of the gate query; other reasons get the default notice or an error
   banner with retry.
+- **Named filter shared by tile and list**: the entity declares `namedFilters`,
+  the `ticket-queue` entityList lists the id in `namedFilters`, and the
+  `open-work` stat counts through the list's own query with `params.namedFilter`
+  and `navigate`. A click opens the queue filtered by the same rule, so tile and
+  list cannot drift.
 
 ## When to reach for it
 
@@ -73,6 +78,7 @@ import {
 } from "@cosmicdrift/kumiko-testing/stack";
 import {
   TICKET_CAPABILITIES_QUERY,
+  TICKET_LIST_QUERY,
   TICKET_STATS_QUERY,
   ticketEntity,
   ticketFeature,
@@ -100,11 +106,11 @@ describe("dashboard screen", () => {
     const stats = screen.panels.flatMap((panel) =>
       panel.kind === "stat-group" ? panel.stats : panel.kind === "stat" ? [panel] : [],
     );
-    expect(stats.map((s) => s.valueField)).toEqual(["open", "closed", "total"]);
-    for (const stat of stats) expect(stat.query).toBe(TICKET_STATS_QUERY);
+    expect(stats.map((s) => s.valueField)).toEqual(["open", "closed", "total", "total"]);
+    const statsQueryStats = stats.filter((s) => s.query === TICKET_STATS_QUERY);
 
     const result = await stack.http.queryOk<Record<string, unknown>>(TICKET_STATS_QUERY, {}, admin);
-    for (const stat of stats) expect(result).toHaveProperty(stat.valueField);
+    for (const stat of statsQueryStats) expect(result).toHaveProperty(stat.valueField);
   });
 });
 
@@ -165,6 +171,28 @@ describe("record-bound dashboard with a gated detail panel", () => {
     });
   });
 });
+
+describe("named filter shared by the dashboard tile and the list", () => {
+  test("the tile total equals the filtered list total over HTTP", async () => {
+    const dashboard = ticketFeature.screens["ticket-dashboard"];
+    if (dashboard?.type !== "dashboard") throw new Error("ticket-dashboard missing");
+    const tile = dashboard.panels.find(
+      (panel) => panel.kind === "stat" && panel.id === "open-work",
+    );
+    if (tile?.kind !== "stat") throw new Error("open-work tile missing");
+    expect(tile.navigate).toEqual({ screen: "ticket-queue", namedFilter: "open-work" });
+
+    const counted = await stack.http.queryOk<{ total: number }>(tile.query, tile.params, admin);
+    const listed = await stack.http.queryOk<{ rows: unknown[]; total: number }>(
+      TICKET_LIST_QUERY,
+      { namedFilter: "open-work", totalCount: true, limit: 50 },
+      admin,
+    );
+    expect(counted.total).toBe(listed.total);
+    expect(listed.rows).toHaveLength(listed.total);
+    expect(listed.total).toBeGreaterThan(0);
+  });
+});
 ```
 
 ### src/feature.ts
@@ -193,10 +221,15 @@ export const ticketEntity = createEntity({
     title: createTextField({ personal: false, reason: "is_business_data", required: true }),
     status: createSelectField({ options: TICKET_STATUSES, default: "open", required: true }),
   },
+  // Defined once: the queue list and the dashboard tile both read it.
+  namedFilters: {
+    "open-work": { filters: () => [{ field: "status", op: "eq", value: "open" }] },
+  },
 });
 
 export const TICKET_STATS_QUERY = "tickets:query:ticket:stats";
 export const TICKET_CAPABILITIES_QUERY = "tickets:query:ticket:capabilities";
+export const TICKET_LIST_QUERY = "tickets:query:ticket:list";
 
 const readerRoles = { roles: ["Admin", "User"] } as const;
 
@@ -281,6 +314,9 @@ export const ticketFeature = defineFeature("tickets", (r) => {
       "tickets.dashboard.open": { en: "Open" },
       "tickets.dashboard.closed": { en: "Closed" },
       "tickets.dashboard.total": { en: "All tickets" },
+      "tickets.dashboard.open-work": { en: "Open work" },
+      "tickets.filter.open-work": { en: "Open work" },
+      "screen:ticket-queue.title": { en: "Ticket queue" },
     },
   });
 
@@ -316,6 +352,16 @@ export const ticketFeature = defineFeature("tickets", (r) => {
         query: TICKET_STATS_QUERY,
         valueField: "total",
       },
+      // Counts through the list's own query with the same named filter, then links to that list.
+      {
+        kind: "stat",
+        id: "open-work",
+        label: "tickets.dashboard.open-work",
+        query: TICKET_LIST_QUERY,
+        valueField: "total",
+        params: { namedFilter: "open-work", limit: 1, totalCount: true },
+        navigate: { screen: "ticket-queue", namedFilter: "open-work" },
+      },
     ],
     access: readerRoles,
   });
@@ -324,6 +370,15 @@ export const ticketFeature = defineFeature("tickets", (r) => {
   // button, and a fallback chosen by reason.
   const gate = { query: TICKET_CAPABILITIES_QUERY, field: "canClose", eq: true } as const;
 
+  r.screen({
+    id: "ticket-queue",
+    type: "entityList",
+    entity: "ticket",
+    columns: ["title", "status"],
+    namedFilters: [{ id: "open-work", label: "tickets.filter.open-work" }],
+    access: readerRoles,
+  });
+
   // The list doubles as the fallback target: it has no visibleWhen of its own.
   r.screen({
     id: "ticket-list",

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