@cosmicdrift/kumiko-framework 0.402.0 → 0.404.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`).
@@ -968,6 +971,9 @@ type JobTrigger =
     cron: string;
     tz?: string;
   }
+  | {
+    maintenance: true;
+  }
   | {
     manual: true;
   }
@@ -1351,6 +1357,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.
@@ -338,6 +338,7 @@ type CreateEventSourceLiveEventsOptions = {
   url?: string; // URL of the SSE endpoint.
   onSessionEnded?: () => void; // Fires once per connection when the session ended: the server refused the SSE handshake, or opened the stream with a `session-ended` frame (stale auth cookie downgraded to anonymous).
   timers?: LiveEventTimers; // Reconnect-timer seam; defaults to the global setTimeout/clearTimeout.
+  stallTimers?: LiveEventTimers; // Stall-watchdog timer seam; defaults to the global setTimeout/clearTimeout.
   random?: () => number; // Jitter source in [0, 1); defaults to Math.random.
   now?: () => number; // Clock for synthetic resync events; defaults to Date.now.
 };

package/agents/api/types.md

@@ -1247,6 +1247,7 @@ type JobQueuedMeta = {
 type JobRunner = {
   start(): Promise<void>;
   stop(): Promise<void>;
+  stopConsuming?(): Promise<void>;
   dispatch(jobName: string, payload?: Record<string, unknown>, meta?: JobMeta): Promise<string>;
   handleEvent(eventName: string, payload: Record<string, unknown>, user?: SessionUser, triggerEvent?: JobTriggerEvent): Promise<void>;
   handleCatchUpEvent(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
@@ -1259,6 +1260,8 @@ type JobRunnerOptions = {
   redisUrl: string;
   consumerLane?: JobRunIn | undefined;
   queueNamePrefix?: string | undefined;
+  redisNamespace?: Pick<RedisNamespace, "keyPrefix" | "bullmqPrefix"> | undefined;
+  maintenanceWindow?: MaintenanceWindow | undefined;
   bootRedisTimeoutMs?: number | undefined;
   schedulerSeenRefreshMs?: number | undefined;
   jobRetention?: { completedAgeSec?: number | undefined; failedAgeSec?: number | undefined; } | undefined;
@@ -1272,6 +1275,15 @@ type JobRunnerOptions = {
 };
 ```
 
+## packages/framework/src/jobs/maintenance-window.ts
+
+```ts
+type MaintenanceWindow = {
+  hour: number;
+  minute: number;
+};
+```
+
 ## packages/framework/src/lifecycle/lifecycle.ts
 
 ```ts
@@ -1436,6 +1448,17 @@ type SystemHooks = {
 };
 ```
 
+## packages/framework/src/redis/client.ts
+
+```ts
+type RedisNamespace = {
+  keyPrefix: string; // ioredis keyPrefix for every non-BullMQ key; "" when unnamespaced.
+  bullmqPrefix: string; // BullMQ `prefix` option ("bull" is BullMQ's own default).
+  channelPrefix: string; // Prepended to every Pub/Sub channel (ioredis keyPrefix does not apply to Pub/Sub).
+  channelSubscribePattern: string | undefined; // Set only with KUMIKO_REDIS_PREFIX.
+};
+```
+
 ## packages/framework/src/secrets/dek-cache.ts
 
 ```ts
@@ -2676,6 +2699,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 +4409,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/agents/examples/lane-routing.md

@@ -13,6 +13,7 @@ Pin jobs to deploy lanes (`api` | `worker`) with event-triggered fan-out.
 ## What it shows
 
 - `r.job({ runIn: "worker" })` after an HTTP write
+- `trigger: { maintenance: true }` for a daily housekeeping job in the app's maintenance window (`KUMIKO_MAINTENANCE_WINDOW`)
 - End-to-end verification via `createAllInOneEntrypoint`
 
 ## Source
@@ -65,7 +66,12 @@ import {
   type TestDb,
   type TestRedis,
 } from "@cosmicdrift/kumiko-testing/stack";
-import { createLaneRoutingFeature, renderedReceipts, sentConfirmations } from "../feature";
+import {
+  createLaneRoutingFeature,
+  pruneRuns,
+  renderedReceipts,
+  sentConfirmations,
+} from "../feature";
 
 const JWT = "lane-routing-sample-secret-minimum-32-chars!";
 const adminUser = TestUsers.admin;
@@ -87,6 +93,7 @@ afterAll(async () => {
 afterEach(() => {
   renderedReceipts.length = 0;
   sentConfirmations.length = 0;
+  pruneRuns.length = 0;
 });
 
 describe("lane-routing sample", () => {
@@ -132,6 +139,30 @@ describe("lane-routing sample", () => {
       await entry.stop();
     }
   });
+
+  test("a maintenance job is registered for the daily window and runs on the worker lane", async () => {
+    const registry = createRegistry([createLaneRoutingFeature()]);
+    expect(registry.getJob("orders:job:prune-old-receipts")?.trigger).toEqual({
+      maintenance: true,
+    });
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const entry = createAllInOneEntrypoint({
+      rowLevelSecurity: "off",
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: `lane-routing-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      maintenanceWindow: { hour: 5, minute: 30 },
+    });
+    await entry.start();
+    try {
+      await entry.jobRunner.dispatch("orders:job:prune-old-receipts", {});
+      await waitFor(() => expect(pruneRuns).toHaveLength(1));
+    } finally {
+      await entry.stop();
+    }
+  });
 });
 ```
 
@@ -163,6 +194,7 @@ import { z } from "zod";
 // opaque to the framework.
 export const renderedReceipts: Array<{ customerName: string; amount: number }> = [];
 export const sentConfirmations: Array<{ customerName: string; amount: number }> = [];
+export const pruneRuns: number[] = [];
 
 // The entity declaration secures the qualified-name prefix "orders:write:order:create"
 // for the write handler below and thereby the job trigger on this event.
@@ -240,6 +272,13 @@ export function createLaneRoutingFeature(): FeatureDefinition {
         });
       },
     );
+
+    // Housekeeping: `maintenance` runs once a day in the app's maintenance window
+    // (KUMIKO_MAINTENANCE_WINDOW, UTC, default 03:00) instead of a cron time of its own, so a
+    // sleeping app wakes once a day for all its cleanup jobs.
+    r.job("prune-old-receipts", { trigger: { maintenance: true }, runIn: "worker" }, async () => {
+      pruneRuns.push(Date.now());
+    });
   });
 }
 ```

package/dist/api/redis-sse-broker.d.ts

@@ -4,6 +4,7 @@ export type RedisSseBrokerOptions = {
     readonly redisUrl: string;
     readonly clientOptions?: RedisClientOptions;
     readonly channelPrefix?: string;
+    readonly channelSubscribePattern?: string;
 };
 export type RedisSseBroker = SseBroker & {
     readonly kind: "redis";

package/dist/api/redis-sse-broker.js

@@ -1,6 +1,6 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { createFallbackLogger } from "../logging/utils.js";
-import { redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "../redis/client.js";
+import { redisClientOptionsFromEnv, redisNamespaceFromEnv, } from "../redis/client.js";
 import { createRedisPubSubSignal } from "../redis/pubsub-signal.js";
 import { createSseBroker, readNonEmptyStringArray, } from "./sse-broker.js";
 const log = createFallbackLogger("kumiko:sse-broker");
@@ -28,11 +28,13 @@ export function isRedisSseBroker(broker) {
 // REDIS_URL-based default never ran.
 export function createDefaultSseBroker(env = process.env) {
     const redisUrl = env["REDIS_URL"];
+    const { channelPrefix, channelSubscribePattern } = redisNamespaceFromEnv(env);
     const ownedRedisSseBroker = redisUrl
         ? createRedisSseBroker({
             redisUrl,
             clientOptions: redisClientOptionsFromEnv(env),
-            channelPrefix: redisChannelPrefixFromEnv(env),
+            channelPrefix,
+            ...(channelSubscribePattern !== undefined && { channelSubscribePattern }),
         })
         : undefined;
     return { sseBroker: ownedRedisSseBroker ?? createSseBroker(), ownedRedisSseBroker };
@@ -104,7 +106,7 @@ export function createRedisSseBroker(opts) {
     const invalidationPrefix = `${opts.channelPrefix ?? ""}${INVALIDATION_PREFIX}`;
     const signal = createRedisPubSubSignal({
         redisUrl: opts.redisUrl,
-        channelPattern: `${opts.channelPrefix ?? ""}${PSUBSCRIBE_SUFFIX}`,
+        channelPattern: opts.channelSubscribePattern ?? `${opts.channelPrefix ?? ""}${PSUBSCRIBE_SUFFIX}`,
         label: "sse-broker",
         ...(opts.clientOptions ? { clientOptions: opts.clientOptions } : {}),
     });

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.";