@cosmicdrift/kumiko-framework 0.402.0 → 0.403.0

package/agents/api/framework-engine.md

@@ -35,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;
@@ -137,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[];
@@ -564,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.
@@ -628,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`).
@@ -1351,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

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` | 419 |
+| `@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

@@ -28,6 +28,7 @@
 | <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
 
@@ -52,6 +53,17 @@
 | --- | --- | --- | --- |
 | <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 |

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/engine/boot-validator/boot-phases-app.js

@@ -5,6 +5,7 @@ import { validateProjectionAllowlist } from "../validate-projection-allowlist.js
 import { runFeatureBootCheck } from "./boot-check.js";
 import { validateCardMetaOverflow } from "./card-meta-overflow.js";
 import { validateConfigReads } from "./config-deps.js";
+import { validateDashboardStatNavigate } from "./dashboard-stat-navigate.js";
 import { validateExtensionPreSaveWiring } from "./entity-handler.js";
 import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
@@ -45,6 +46,10 @@ const APP_CHECKS_AFTER_I18N = [
         check: "validateProjectionListScreens",
         run: (c) => validateProjectionListScreens(c.features),
     },
+    {
+        check: "validateDashboardStatNavigate",
+        run: (c) => validateDashboardStatNavigate(c.features),
+    },
     {
         check: "validateRelatedListSectionQueries",
         run: (c) => validateRelatedListSectionQueries(c.features),

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

@@ -131,11 +131,47 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
         readonly summary: "A list whose entity has a detail screen offers a navigate row action.";
         readonly fix: 'Add a navigate rowAction with id "view" or "edit".';
     };
+    readonly unknownNamedFilter: {
+        readonly id: "entity-list/unknown-named-filter";
+        readonly summary: "Every screen namedFilters id is declared in the entity's namedFilters.";
+        readonly fix: "Declare the rule in EntityDefinition.namedFilters or remove the id from the screen.";
+    };
     readonly unknownColumn: {
         readonly id: "entity-list/unknown-column";
         readonly summary: "Every column without a label names an entity field, derived field or row-meta column.";
         readonly fix: "Fix the column field name or give the column a label.";
     };
+}, {
+    readonly projectionQueryAcceptsNamedFilter: {
+        readonly id: "named-filter/projection-query-accepts-named-filter";
+        readonly summary: "A projectionList with namedFilters binds a query whose schema has a namedFilter key.";
+        readonly fix: "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.";
+    };
+    readonly statNavigateTarget: {
+        readonly id: "named-filter/stat-navigate-target";
+        readonly summary: "A stat navigate.screen resolves to an entityList or projectionList screen.";
+        readonly fix: "Point navigate.screen at a registered list screen.";
+    };
+    readonly statNavigateFilterDeclared: {
+        readonly id: "named-filter/stat-navigate-filter-declared";
+        readonly summary: "A stat navigate.namedFilter is declared in the target screen's namedFilters.";
+        readonly fix: "Add { id, label } to namedFilters of the target screen.";
+    };
+    readonly statNavigateSameQuery: {
+        readonly id: "named-filter/stat-navigate-same-query";
+        readonly summary: "A stat with navigate counts with the target list's own query.";
+        readonly fix: "Set the stat query to the target list's query.";
+    };
+    readonly statNavigateSameNamedFilter: {
+        readonly id: "named-filter/stat-navigate-same-named-filter";
+        readonly summary: "A stat's params.namedFilter equals navigate.namedFilter.";
+        readonly fix: "Set params.namedFilter to the same id as navigate.namedFilter.";
+    };
+    readonly statNavigateStaticFilter: {
+        readonly id: "named-filter/stat-navigate-static-filter";
+        readonly summary: "A stat repeats the target screen's static filter in params.filter.";
+        readonly fix: "Set params.filter to the target screen's filter.";
+    };
 }, {
     readonly missingFeatureKey: {
         readonly id: "i18n/missing-feature-key";

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

@@ -3,11 +3,13 @@ import { BOOT_CHECK_RULES } from "./boot-check-rules.js";
 import { CARD_META_OVERFLOW_RULES } from "./card-meta-overflow-rules.js";
 import { ENTITY_LIST_RULES } from "./entity-list-screens-rules.js";
 import { I18N_RULES } from "./i18n-keys-rules.js";
+import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
 import { PII_RULES } from "./pii-retention-rules.js";
 import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
 export const FRAMEWORK_BOOT_RULE_TABLES = [
     PII_RULES,
     ENTITY_LIST_RULES,
+    NAMED_FILTER_RULES,
     I18N_RULES,
     CARD_META_OVERFLOW_RULES,
     SCREEN_ACTION_RULES,

package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "../types/index.ts";
+export declare function validateDashboardStatNavigate(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/dashboard-stat-navigate.js

@@ -0,0 +1,77 @@
+import { isDeepStrictEqual } from "node:util";
+import { toKebab } from "../qualified-name.js";
+import { bootRuleError } from "./boot-rule.js";
+import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
+import { resolveScreenTargetQn } from "./screens-actions.js";
+function entityListQueryName(feature, screen) {
+    return `${toKebab(feature.name)}:query:${toKebab(screen.entity)}:list`;
+}
+function listQueryOf(target) {
+    return target.screen.type === "entityList"
+        ? entityListQueryName(target.feature, target.screen)
+        : target.screen.query;
+}
+function declaredNamedFilterIds(target) {
+    return new Set((target.screen.namedFilters ?? []).map((ref) => ref.id));
+}
+function resolveListTarget(featureName, screenRef, featureMap) {
+    const qn = resolveScreenTargetQn(featureName, screenRef);
+    const [targetFeatureName = "", , targetShortId = ""] = qn.split(":");
+    const feature = featureMap.get(targetFeatureName);
+    const screen = feature?.screens[targetShortId];
+    if (feature === undefined || screen === undefined)
+        return { qn };
+    if (screen.type !== "entityList" && screen.type !== "projectionList")
+        return { qn };
+    return { feature, screen };
+}
+function validateStatNavigate(context, featureName, stat, featureMap) {
+    const navigate = stat.navigate;
+    // skip: stat has no navigate target to validate
+    if (navigate === undefined)
+        return;
+    const target = resolveListTarget(featureName, navigate.screen, featureMap);
+    if ("qn" in target) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateTarget, {
+            message: `${context} navigate.screen "${navigate.screen}" does not resolve to a registered entityList or projectionList screen (checked "${target.qn}").`,
+        });
+    }
+    if (navigate.namedFilter !== undefined &&
+        !declaredNamedFilterIds(target).has(navigate.namedFilter)) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateFilterDeclared, {
+            message: `${context} navigate.namedFilter "${navigate.namedFilter}" is not declared in namedFilters of screen "${target.screen.id}". Add { id, label } to that screen.`,
+        });
+    }
+    const listQuery = listQueryOf(target);
+    if (stat.query !== listQuery) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateSameQuery, {
+            message: `${context} navigate targets screen "${target.screen.id}" whose list query is "${listQuery}", but the stat counts with query "${stat.query}". Count with the list's own query so tile and list cannot drift.`,
+        });
+    }
+    if (stat.params?.["namedFilter"] !== navigate.namedFilter) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateSameNamedFilter, {
+            message: `${context} params.namedFilter (${JSON.stringify(stat.params?.["namedFilter"])}) must equal navigate.namedFilter (${JSON.stringify(navigate.namedFilter)}), otherwise the tile counts other rows than the list shows.`,
+        });
+    }
+    const staticFilter = target.screen.filter;
+    if (staticFilter !== undefined && !isDeepStrictEqual(stat.params?.["filter"], staticFilter)) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateStaticFilter, {
+            message: `${context} target screen "${target.screen.id}" has a static filter the tile does not apply. Set params.filter to the same filter on the stat.`,
+        });
+    }
+}
+export function validateDashboardStatNavigate(features) {
+    const featureMap = new Map(features.map((f) => [f.name, f]));
+    for (const feature of features) {
+        for (const screen of Object.values(feature.screens)) {
+            if (screen.type !== "dashboard")
+                continue;
+            for (const panel of screen.panels) {
+                const stats = panel.kind === "stat" ? [panel] : panel.kind === "stat-group" ? panel.stats : [];
+                for (const stat of stats) {
+                    validateStatNavigate(`[Feature ${feature.name}] Screen "${screen.id}" (dashboard) stat "${stat.id}"`, feature.name, stat, featureMap);
+                }
+            }
+        }
+    }
+}

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

@@ -24,6 +24,11 @@ export declare const ENTITY_LIST_RULES: {
         readonly summary: "A list whose entity has a detail screen offers a navigate row action.";
         readonly fix: 'Add a navigate rowAction with id "view" or "edit".';
     };
+    readonly unknownNamedFilter: {
+        readonly id: "entity-list/unknown-named-filter";
+        readonly summary: "Every screen namedFilters id is declared in the entity's namedFilters.";
+        readonly fix: "Declare the rule in EntityDefinition.namedFilters or remove the id from the screen.";
+    };
     readonly unknownColumn: {
         readonly id: "entity-list/unknown-column";
         readonly summary: "Every column without a label names an entity field, derived field or row-meta column.";

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

@@ -24,6 +24,11 @@ export const ENTITY_LIST_RULES = {
         summary: "A list whose entity has a detail screen offers a navigate row action.",
         fix: 'Add a navigate rowAction with id "view" or "edit".',
     },
+    unknownNamedFilter: {
+        id: "entity-list/unknown-named-filter",
+        summary: "Every screen namedFilters id is declared in the entity's namedFilters.",
+        fix: "Declare the rule in EntityDefinition.namedFilters or remove the id from the screen.",
+    },
     unknownColumn: {
         id: "entity-list/unknown-column",
         summary: "Every column without a label names an entity field, derived field or row-meta column.",

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

@@ -95,12 +95,24 @@ function checkColumns(feature, screen) {
         }
     });
 }
+function checkNamedFilters(feature, screen) {
+    const declared = feature.entities?.[screen.entity]?.namedFilters ?? {};
+    collectBootRuleViolations(screen.namedFilters ?? [], (ref) => {
+        // skip: id is declared on the entity
+        if (Object.hasOwn(declared, ref.id))
+            return;
+        throw bootRuleError(ENTITY_LIST_RULES.unknownNamedFilter, {
+            message: `${screenPrefix(feature, screen)}: namedFilters id "${ref.id}" is not declared in entity "${screen.entity}" namedFilters. Known: ${Object.keys(declared).sort().join(", ") || "(none)"}.`,
+        });
+    });
+}
 const ENTITY_LIST_CHECKS = [
     checkSearchable,
     checkDefaultSortRequired,
     checkDefaultSortColumn,
     checkDetailNavigate,
     checkColumns,
+    checkNamedFilters,
 ];
 export function validateEntityListScreens(features) {
     const screens = features.flatMap((feature) => Object.values(feature.screens).flatMap((screen) => screen.type === "entityList" ? [{ feature, screen }] : []));

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

@@ -0,0 +1,32 @@
+export declare const NAMED_FILTER_RULES: {
+    readonly projectionQueryAcceptsNamedFilter: {
+        readonly id: "named-filter/projection-query-accepts-named-filter";
+        readonly summary: "A projectionList with namedFilters binds a query whose schema has a namedFilter key.";
+        readonly fix: "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.";
+    };
+    readonly statNavigateTarget: {
+        readonly id: "named-filter/stat-navigate-target";
+        readonly summary: "A stat navigate.screen resolves to an entityList or projectionList screen.";
+        readonly fix: "Point navigate.screen at a registered list screen.";
+    };
+    readonly statNavigateFilterDeclared: {
+        readonly id: "named-filter/stat-navigate-filter-declared";
+        readonly summary: "A stat navigate.namedFilter is declared in the target screen's namedFilters.";
+        readonly fix: "Add { id, label } to namedFilters of the target screen.";
+    };
+    readonly statNavigateSameQuery: {
+        readonly id: "named-filter/stat-navigate-same-query";
+        readonly summary: "A stat with navigate counts with the target list's own query.";
+        readonly fix: "Set the stat query to the target list's query.";
+    };
+    readonly statNavigateSameNamedFilter: {
+        readonly id: "named-filter/stat-navigate-same-named-filter";
+        readonly summary: "A stat's params.namedFilter equals navigate.namedFilter.";
+        readonly fix: "Set params.namedFilter to the same id as navigate.namedFilter.";
+    };
+    readonly statNavigateStaticFilter: {
+        readonly id: "named-filter/stat-navigate-static-filter";
+        readonly summary: "A stat repeats the target screen's static filter in params.filter.";
+        readonly fix: "Set params.filter to the target screen's filter.";
+    };
+};

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

@@ -0,0 +1,32 @@
+export const NAMED_FILTER_RULES = {
+    projectionQueryAcceptsNamedFilter: {
+        id: "named-filter/projection-query-accepts-named-filter",
+        summary: "A projectionList with namedFilters binds a query whose schema has a namedFilter key.",
+        fix: "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.",
+    },
+    statNavigateTarget: {
+        id: "named-filter/stat-navigate-target",
+        summary: "A stat navigate.screen resolves to an entityList or projectionList screen.",
+        fix: "Point navigate.screen at a registered list screen.",
+    },
+    statNavigateFilterDeclared: {
+        id: "named-filter/stat-navigate-filter-declared",
+        summary: "A stat navigate.namedFilter is declared in the target screen's namedFilters.",
+        fix: "Add { id, label } to namedFilters of the target screen.",
+    },
+    statNavigateSameQuery: {
+        id: "named-filter/stat-navigate-same-query",
+        summary: "A stat with navigate counts with the target list's own query.",
+        fix: "Set the stat query to the target list's query.",
+    },
+    statNavigateSameNamedFilter: {
+        id: "named-filter/stat-navigate-same-named-filter",
+        summary: "A stat's params.namedFilter equals navigate.namedFilter.",
+        fix: "Set params.namedFilter to the same id as navigate.namedFilter.",
+    },
+    statNavigateStaticFilter: {
+        id: "named-filter/stat-navigate-static-filter",
+        summary: "A stat repeats the target screen's static filter in params.filter.",
+        fix: "Set params.filter to the target screen's filter.",
+    },
+};

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

@@ -1,8 +1,10 @@
 import { isListQueryWithoutSearchableFields, resolveEntityBehindListQuery, } from "../entity-list-searchability.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
+import { bootRuleError } from "./boot-rule.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
 import { validateListTableAggregateQuery } from "./list-table-aggregate-query.js";
+import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
 import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
 // Sibling to entity-list-screens.ts rather than an extension of it:
@@ -66,6 +68,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers, feature
     }
     validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
     validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
+    validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schema);
     validateListTableAggregateQuery({ prefix, ...screen, handler, featureMap });
 }
 // filter sends `payload.filter` — same 422 footgun as facets below
@@ -78,6 +81,16 @@ function validateProjectionListFilterSchemaAcceptance(prefix, screen, schema) {
         `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
         `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
 }
+// namedFilters send `payload.namedFilter` — same 422 footgun as filter/facets.
+function validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schema) {
+    // skip: no named filters declared, or the schema already accepts the key — nothing to reject.
+    if (screen.namedFilters === undefined || schemaAccepts(schema, "namedFilter"))
+        return;
+    throw bootRuleError(NAMED_FILTER_RULES.projectionQueryAcceptsNamedFilter, {
+        message: `${prefix}: declares namedFilters but query "${screen.query}" has no "namedFilter" parameter in its ` +
+            `Zod schema — add namedFilter: z.string().optional() to the handler's schema and resolve it with resolveNamedListFilters.`,
+    });
+}
 // facets send `payload.filters` — same failure mode as search/sort:
 // definePagedQueryHandler doesn't auto-merge params into the
 // handler's own Zod schema, so a declared facet would 422 on every query

package/dist/engine/entity-handlers.d.ts

@@ -45,6 +45,7 @@ export declare const entityListSchema: z.ZodObject<{
         }>;
         value: z.ZodUnknown;
     }, z.core.$strip>>>;
+    namedFilter: z.ZodOptional<z.ZodString>;
     aggregate: z.ZodOptional<z.ZodObject<{
         groupBy: z.ZodOptional<z.ZodString>;
         measures: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/engine/entity-handlers.js

@@ -15,6 +15,7 @@ import { entityListRuntime, parentVisibilityFor } from "./entity-list-runtime-op
 import { assertReason } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
+import { resolveNamedListFilters } from "./resolve-named-list-filters.js";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
 import { parseTenantId } from "./types/identifiers.js";
 // Convention-based handler factories for event-sourced aggregates.
@@ -109,6 +110,8 @@ export const entityListSchema = z.object({
         value: z.unknown(),
     }))
         .optional(),
+    // Entity-defined work-queue rule (EntityDefinition.namedFilters); its conditions are appended to `filters`.
+    namedFilter: z.string().min(1).max(100).optional(),
     aggregate: listAggregatePayloadSchema.optional(),
 });
 function parseHandlerName(name, validVerbs) {
@@ -398,7 +401,16 @@ export function defineEntityQueryHandler(name, entity, options) {
                 // against Meilisearch/InMem at runtime (remote combobox search). The
                 // executor is built at definition time and cannot know the adapter, so the
                 // runtime override supplies it.
-                const listPayload = query.payload; // @cast-boundary engine-payload
+                const requestPayload = query.payload; // @cast-boundary engine-payload
+                const listPayload = requestPayload.namedFilter === undefined
+                    ? requestPayload
+                    : {
+                        ...requestPayload,
+                        filters: [
+                            ...(requestPayload.filters ?? []),
+                            ...(await resolveNamedListFilters(ctx, query.user, entityName, requestPayload.namedFilter)),
+                        ],
+                    };
                 const db = dbFor(ctx);
                 const { runtimeOptions, eagerLoadViewer, resolveEntity } = entityListRuntime(ctx, entityName, query.user);
                 if (listPayload.aggregate !== undefined) {

package/dist/engine/factories.d.ts

@@ -208,6 +208,8 @@ export declare function createEntity<const F, const T extends EntityTenancy = "t
     readonly readGate?: EntityDefinition["readGate"];
     readonly retention?: RetentionDef;
     readonly derivedFields?: EntityDefinition["derivedFields"];
+    /** See EntityDefinition.namedFilters. */
+    readonly namedFilters?: EntityDefinition["namedFilters"];
     readonly tenancy?: T;
     /** See EntityDefinition.transferable. */
     readonly transferable?: boolean;

package/dist/engine/index.d.ts

@@ -80,6 +80,7 @@ export { defineApply, defineMspApply, setFields } from "./projection-helpers.ts"
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.ts";
 export { readClaim } from "./read-claim.ts";
 export { createRegistry } from "./registry.ts";
+export { resolveNamedListFilters } from "./resolve-named-list-filters.ts";
 export type { AssignableAppRoles } from "./role-assignment.ts";
 export { assignableAppRolesFromUsages, assignableAppRolesOf, BUILT_IN_MEMBERSHIP_ROLES, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.ts";
 export { runPipeline, runStepList } from "./run-pipeline.ts";

package/dist/engine/index.js

@@ -64,6 +64,7 @@ export { defineApply, defineMspApply, setFields } from "./projection-helpers.js"
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.js";
 export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
+export { resolveNamedListFilters } from "./resolve-named-list-filters.js";
 export { assignableAppRolesFromUsages, assignableAppRolesOf, BUILT_IN_MEMBERSHIP_ROLES, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod, SYSTEM_ONLY_JSON_SCHEMA_KEY, } from "./schema-builder.js";

package/dist/engine/resolve-named-list-filters.d.ts

@@ -0,0 +1,3 @@
+import type { NamedListFilterCondition } from "@cosmicdrift/kumiko-types/named-list-filters";
+import type { HandlerContext, SessionUser } from "./types/index.ts";
+export declare function resolveNamedListFilters(ctx: HandlerContext, user: SessionUser, entityName: string, name: string): Promise<readonly NamedListFilterCondition[]>;

package/dist/engine/resolve-named-list-filters.js

@@ -0,0 +1,30 @@
+import { AccessDeniedError, ValidationError } from "../errors/index.js";
+import { hasAccess } from "./access.js";
+export async function resolveNamedListFilters(ctx, user, entityName, name) {
+    const registered = ctx.registry.getEntity(entityName)?.namedFilters ?? {};
+    const def = Object.hasOwn(registered, name) ? registered[name] : undefined;
+    if (def === undefined) {
+        throw new ValidationError({
+            fields: [
+                {
+                    path: "namedFilter",
+                    code: "unknown_named_filter",
+                    i18nKey: "errors.validation.invalid_value",
+                    params: { entity: entityName, namedFilter: name },
+                },
+            ],
+        });
+    }
+    if (def.access !== undefined && !hasAccess(user, def.access)) {
+        throw new AccessDeniedError();
+    }
+    const conditions = await def.filters({ ctx, user, now: ctx.tz.now() });
+    const entityFields = ctx.registry.getEntity(entityName)?.fields ?? {};
+    for (const condition of conditions) {
+        // Fail closed: a condition on a non-column is dropped by the list filter and would widen the queue.
+        if (condition.field !== "id" && !Object.hasOwn(entityFields, condition.field)) {
+            throw new Error(`Named filter "${name}" of entity "${entityName}" filters on unknown field "${condition.field}".`);
+        }
+    }
+    return conditions;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.402.0",
+  "version": "0.403.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.402.0",
+    "@cosmicdrift/kumiko-types": "0.403.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.14",
     "i18next": "^26.1.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.402.0",
+    "@cosmicdrift/kumiko-testing": "0.403.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.403.0",
+    "type": "improvement",
+    "title": "Entities define named list filters",
+    "detail": "createEntity takes namedFilters, a record of { access?, filters(scope) } where filters returns ListFilter conditions (sync or async). The default list query accepts namedFilter and appends the resolved conditions to filters, on the row path and the aggregate path. An unknown name is a validation error on namedFilter, a failed access rule is access_denied. resolveNamedListFilters is exported from the engine entry. The definition is function-valued and never reaches the client schema."
+  },
   {
     "version": "0.402.0",
     "type": "improvement",