@cosmicdrift/kumiko-samples 0.388.0 → 0.389.0

package/samples/apps/use-all-bundled/bin/main.ts

@@ -8,6 +8,7 @@ import { InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
 import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import { BUNDLED_LISTS } from "../src/bundled-lists";
 import {
   APP_FEATURES,
   AUTH_COMPOSE_OPTIONS,
@@ -27,6 +28,7 @@ await runProdApp({
   featureToggles: true,
   envSchema,
   validateBootOptions: VALIDATE_BOOT_OPTIONS,
+  bundledLists: BUNDLED_LISTS,
   // Smoke-only: exercises the hard PII boot gate + blind-index gate with
   // every bundled feature mounted. Real apps wire createPgKmsAdapter(...).
   kms: new InMemoryKmsAdapter(),

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -71,6 +71,7 @@
       "name": "audit",
       "description": "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection — the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`, and reads the events of every tenant (system tenant excluded) through `audit:query:list-all-tenants` and the `audit-log-all-tenants` screen. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant",
         "user",
@@ -232,6 +233,7 @@
           "validated": false,
           "options": [
             "optional",
+            "systemAdmins",
             "admins",
             "all"
           ],
@@ -339,6 +341,7 @@
       "name": "cap-counter",
       "description": "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -362,6 +365,7 @@
       "name": "cap-overview",
       "description": "Read-only visibility into per-tenant tier assignment and cap usage. SystemAdmin gets a platform-wide tenant list with usage bars; tenant admins (or the roles in `usageVisibleTo`) get their own tenant's usage as dashboard cards. Reads tier-engine, billing-foundation, and tenant data plus app-owned usage tables via caller-supplied CapSpec callbacks — never writes.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant",
         "tier-engine",
@@ -744,6 +748,7 @@
       "name": "delivery",
       "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (the `runProdApp` and `runDevApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. An app serving its own (e.g. legacy) unsubscribe links renders the same result page with `renderUnsubscribeResultPage({ kind, locale })`. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant"
       ],
@@ -895,6 +900,7 @@
       "name": "feature-toggles",
       "description": "Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: \"shared\"` syncs the snapshot across instances whenever a `toggle-set` event is appended.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -1372,6 +1378,7 @@
       "name": "inbound-mail-foundation",
       "description": "Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant-lifecycle"
       ],
@@ -1464,6 +1471,7 @@
       "name": "jobs",
       "description": "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079). A job that declares `tenantVisibleRun` also keeps its run state per tenant and subject in `store_tenant_job_runs` (queued, running, plus the latest completed or failed run, no payload, error text or logs), which the tenant reads through `jobs:query:tenant-runs` (fw#3616); the stale-run sweep fails its stuck `running` rows and drops `queued` rows older than `retentionDays`.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -1759,6 +1767,7 @@
       "name": "managed-pages",
       "description": "Tenant-editable, server-rendered public pages with per-tenant branding. Stores one Markdown `page` per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Also exposes `managed-pages:query:by-tenant-published` (anonymous, SQL-filtered on `published`) for sitemap/discovery consumers such as the `seo` feature. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset,custom-css}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "config"
       ],
@@ -2088,6 +2097,7 @@
       "name": "personal-access-tokens",
       "description": "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `store_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — registered as an auth-foundation tokenVerifier provider, resolved generically by the middleware. Pass { toggleable: { default: false } } to tier-gate the whole feature.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "user",
         "tenant",
@@ -2417,6 +2427,7 @@
       "name": "sessions",
       "description": "Tracks signed-in clients in the `store_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the same callbacks are also registered as an auth-foundation sessionStore provider, resolvable generically via `resolveSessionStore()`. The feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "user",
         "auth-foundation"
@@ -2711,6 +2722,7 @@
       "name": "tags",
       "description": "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`, with optional `color` and `scope`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Catalog screens are declarative (`entityList` + `entityEdit`) and use convention QNs `tag:{create,update,delete}`; TagManager/TagPicker keep `create-tag`/`update-tag`/`delete-tag`. Also: `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. A tag with empty `scope` is global; a `scope` of an entityType restricts it to that type in the picker. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: { reason } } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -2826,6 +2838,7 @@
       "name": "tenant",
       "description": "Registers the three core multi-tenancy entities — `tenant`, `tenant-membership`, and `tenant-invitation` (DB tables `read_tenants`, `read_tenant_memberships`, and `read_tenant_invitations`) — along with write handlers for create/update/disable/enable/addMember/removeMember/updateMemberRoles and the matching queries. It also declares a set of per-tenant config keys (companyName, timezone, locale, SMTP credentials) and system-only keys (priceModel, maxUsers) via `r.config({ keys: { ... } })`. Use this feature in every multi-tenant app; membership resolution and invitation flows depend on it, and `auth-email-password` requires it.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "config"
       ],
@@ -3192,6 +3205,7 @@
       "name": "user",
       "description": "Manages the cross-tenant user identity: the `read_users` table holds each user's email, `displayName`, global `roles`, `emailVerified` flag, and lifecycle `status` (active / restricted / deletionRequested / deleted). Because users exist above any individual tenant, the feature runs with `r.systemScope()` — membership and tenant-specific roles live in the `tenant` feature instead. Add this feature whenever your app needs a persistent, tenant-agnostic user record that auth and GDPR pipelines can reference.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -3219,6 +3233,7 @@
       "name": "user-data-rights",
       "description": "Implements GDPR Art. 15 (access / `my-audit-log` query), Art. 17 (erasure / `request-deletion` + `cancel-deletion`, plus the anonymous email-verified `request-deletion-by-email` + `confirm-deletion-by-token` flow for lockout-safe self-service, + cron cleanup with grace period), Art. 18 (restriction / `restrict-account` + `lift-restriction`), and Art. 20 (portability / async `request-export` → ZIP via `file-foundation`, Magic-Link download) as first-class HTTP handlers and cron jobs. Each domain feature opts in by calling `r.useExtension(EXT_USER_DATA, \"<entity>\", { export, delete })` — the feature then orchestrates the export and forget pipelines across all registered hooks automatically. When `mail-foundation` and a `mail-transport-*` are mounted, it also sends the four GDPR notifications (export ready/failed, deletion requested/executed) itself with no app callback code, rendered in each recipient’s locale. Requires `user`, `data-retention`, `compliance-profiles`, and `sessions`.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "user",
         "data-retention",
@@ -3386,6 +3401,7 @@
       "name": "waitlist",
       "description": "Public waitlist: an anonymous, rate-limited `submit` handler collects name, email and optional company, portfolio and message (a honeypot field and per-email dedupe keep bots and repeat submits out, and the response body is identical whether or not an address was already listed), and mails the submitter a confirmation. SystemAdmins review entries in a list screen and invite or reject them; an invite creates the entrant's own tenant (or joins one shared tenant) and mails an accept link with the configured membership role, never a global role. Entries are platform-wide, their personal data is crypto-shredding-ready, and the EXT_USER_DATA hooks export and erase entries matching a user's email.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant",
         "auth-email-password",

package/samples/apps/use-all-bundled/kumiko/schema.ts

@@ -11,6 +11,7 @@
 import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
+import { BUNDLED_LISTS } from "../src/bundled-lists";
 import { APP_FEATURES, AUTH_COMPOSE_OPTIONS, VALIDATE_BOOT_OPTIONS } from "../src/run-config";
 
 export { VALIDATE_BOOT_OPTIONS };
@@ -18,6 +19,7 @@ export { VALIDATE_BOOT_OPTIONS };
 export const FEATURES: readonly FeatureDefinition[] = composeFeatures(APP_FEATURES, {
   includeBundled: true,
   authOptions: AUTH_COMPOSE_OPTIONS,
+  bundledLists: BUNDLED_LISTS,
 });
 
 // collectTableMetas erfasst neben entities auch

package/samples/apps/use-all-bundled/kumiko.config.ts

@@ -12,11 +12,13 @@ import {
 } from "@cosmicdrift/kumiko-server-runtime/compose-features";
 import { notesFeature } from "./src/app/notes-feature";
 import { appScreensFeature } from "./src/app/screens-feature";
+import { BUNDLED_LISTS } from "./src/bundled-lists";
 import { APP_FEATURES, AUTH_COMPOSE_OPTIONS } from "./src/run-config";
 
 export default {
   features: composeFeatures([...APP_FEATURES, appScreensFeature, notesFeature], {
     includeBundled: true,
+    bundledLists: BUNDLED_LISTS,
     ...(buildComposeAuthOptions(AUTH_COMPOSE_OPTIONS) !== undefined && {
       authOptions: buildComposeAuthOptions(AUTH_COMPOSE_OPTIONS),
     }),

package/samples/apps/use-all-bundled/package.json

@@ -33,6 +33,7 @@
     "@cosmicdrift/kumiko-locale-it": "workspace:*"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "workspace:*"
+    "@cosmicdrift/kumiko-testing": "workspace:*",
+    "fflate": "^0.8.2"
   }
 }

package/samples/apps/use-all-bundled/src/app/dev-app-options.ts

@@ -13,6 +13,7 @@
 import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import type { RunDevAppOptions } from "@cosmicdrift/kumiko-dev-server";
 import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { BUNDLED_LISTS } from "../bundled-lists";
 import { AUTH_COMPOSE_OPTIONS, BOOT_FEATURES, VALIDATE_BOOT_OPTIONS } from "../run-config";
 import { ADMIN_EMAIL, ADMIN_PASSWORD, BETA_TENANT_ID, DEV_TENANT_ID } from "./auth-constants";
 import { invoiceReportsFeature } from "./invoice-reports-feature";
@@ -31,6 +32,7 @@ export const devAppOptions = {
   features: [...BOOT_FEATURES, appScreensFeature, notesFeature, invoiceReportsFeature],
   featureToggles: true,
   validateBootOptions: VALIDATE_BOOT_OPTIONS,
+  bundledLists: BUNDLED_LISTS,
   port: Number.parseInt(process.env["PORT"] ?? "4186", 10),
   clientEntry: "./src/app/client.tsx",
   htmlPath: "./public/index.html",

package/samples/apps/use-all-bundled/src/app/notes-feature.ts

@@ -45,6 +45,7 @@ export const noteEntity = createEntity({
       required: true,
       maxLength: 200,
       sortable: true,
+      searchable: true,
     }),
     customFields: customFieldsField(),
   },
@@ -65,6 +66,7 @@ const noteListScreen: EntityListScreenDefinition = {
     },
   ],
   searchable: true,
+  table: { export: { xlsx: true } },
   defaultSort: { field: "title", dir: "asc" },
   slots: { header: { react: { __component: TAGS_FILTER_EXTENSION_NAME } } },
   rowActions: [

package/samples/apps/use-all-bundled/src/bundled-lists.ts

@@ -0,0 +1,15 @@
+import type { BundledListsOptions } from "@cosmicdrift/kumiko-framework/engine";
+
+export const BUNDLED_LISTS = {
+  table: {
+    rememberState: true,
+    resetAll: true,
+    columnPicker: true,
+    density: { userChoice: true },
+    pinning: true,
+    resizing: true,
+    keyboardNavigation: true,
+    export: { xlsx: true },
+  },
+  pinFirstColumn: true,
+} as const satisfies BundledListsOptions;

package/samples/recipes/golden-path/src/feature.ts

@@ -7,7 +7,7 @@ import {
   emitEvent,
   setFields,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 
 export const ticketEntity = createEntity({
@@ -43,6 +43,7 @@ export const helpdeskFeature = defineFeature("helpdesk", (r) => {
       if (!ticket) {
         return failNotFound("ticket", event.payload.id);
       }
+      if (ticket["isClosed"]) return failUnprocessable("ticket_already_closed");
       await emitEvent(ctx, ticketClosed, {
         aggregateId: event.payload.id,
         aggregateType: "ticket",

package/samples/recipes/lifecycle-hooks/README.md

@@ -27,6 +27,10 @@ back.
 - **`r.hook({ type: "postDelete", target: { allOf: entityRef }, handler })`** — fires after commit.
   External side effects (logs, notifications) belong here because
   failures cannot roll the delete back.
+- **`ctx.scheduleAfterRollback(fn)`** — the counterpart of `scheduleAfterCommit`: runs `fn` when
+  the handler transaction (or the enclosing savepoint of a nested `ctx.write`) does not commit.
+  Use it to give back something reserved outside the transaction, like the slot in
+  `article:reserve-slot`. A failed COMMIT triggers it too, so write the callback idempotent.
 
 ## When to reach for it
 

package/samples/recipes/lifecycle-hooks/src/feature.ts

@@ -13,7 +13,12 @@ import {
   defineFeature,
   type SaveContext,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  ConflictError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
 
 export const articleEntity = createEntity({
   table: "read_sample_articles",
@@ -35,6 +40,9 @@ export const articleEntity = createEntity({
 // Collect hook events for testing
 export const hookLog: { type: string; data: Record<string, unknown> }[] = [];
 
+// Stands in for a quota held in an external system, outside the handler transaction.
+export const reservedSlots = new Set<string>();
+
 const editorWrite = { access: { roles: ["Admin", "Editor"] } } as const;
 
 export const articlesFeature = defineFeature("blog", (r) => {
@@ -48,6 +56,23 @@ export const articlesFeature = defineFeature("blog", (r) => {
   );
   r.writeHandler(defineEntityDeleteHandler("article", articleEntity, editorWrite));
 
+  // --- scheduleAfterRollback: give back a reservation made outside the transaction when it does
+  // not commit. The callback must be idempotent: a failed COMMIT also triggers it.
+  r.writeHandler({
+    name: "article:reserve-slot",
+    schema: z.object({ slot: z.string(), reject: z.boolean() }),
+    access: editorWrite.access,
+    handler: async (event, ctx) => {
+      const { slot, reject } = event.payload;
+      reservedSlots.add(slot);
+      ctx.scheduleAfterRollback?.(async () => {
+        reservedSlots.delete(slot);
+      });
+      if (reject) return writeFailure(new UnprocessableError("slot_rejected"));
+      return { isSuccess: true as const, data: {} };
+    },
+  });
+
   // --- Validation hook on create: reject banned words + length ---
   r.hook({
     type: "validation",

package/samples/recipes/list-table-options/README.md

@@ -0,0 +1,50 @@
+# List table options
+
+Opt-in table behaviour for entity, projection and related lists. A list without
+the `table` block renders and behaves as before.
+
+## What it shows
+
+- `table.rememberState`: search, sort, page size, facets and date range survive
+  leaving and re-entering the list within the browser session.
+- `table.resetAll`: one button resets everything that differs from the defaults.
+- `table.columnPicker`: the view menu lets the user hide and reorder columns;
+  `hidden: true` on a column starts it hidden.
+- `table.density`: row density default and an optional user choice.
+- `table.pinning`: the user pins columns left or right in the view menu;
+  `pinned: "left"` on a column starts it pinned.
+- `table.resizing`: columns can be resized (table-layout fixed); `width` and
+  `minWidth` on a column are start values in px.
+- `table.keyboardNavigation`: rows are one tab stop, arrow keys move between rows,
+  Space selects the focused row.
+- `table.export`: an Export button downloads the whole filtered list as an XLSX
+  file; `maxRows` lowers the default limit of 10000 rows.
+  Reference columns export their label and timestamps use the browser time zone.
+- `bulkActions`: row checkboxes and a selection bar. "Delete" runs the delete
+  row action once per selected row; done tasks are skipped.
+- `table.grouping`: the server groups the list by status; each header shows the
+  group's count and estimate sum, "done" starts collapsed and the view menu
+  offers grouping by priority or none.
+- `table.totals`: a footer row with the estimate sum over the filtered list.
+- `facets.estimateHours: { display: "range" }`: from/to inputs for a number field.
+- The same block on a `projectionList`, and `task:workload`, a hand-written list
+  query that keeps grouping and totals by accepting `aggregate`
+  (`entityListSchema`) and answering it with `answerListAggregate`.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/list-table-options
+bun test
+```
+
+The test boots the feature through the boot validator and checks that a
+misspelled key, a hidden column without the picker, an unknown density, a pinned column
+without `pinning`, a width without `resizing` and a bulk action on a navigate
+row action are rejected.
+`workload.integration.test.ts` runs the hand-written query over HTTP and checks
+the grouped sums and the filtered total.

package/samples/recipes/list-table-options/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-list-table-options",
+  "description": "Opt-in table behaviour of a list: remembered search/sort/filters, one reset button, column picker with hidden columns, row density, server-side groups with sums, a totals row and a number range facet.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
+  }
+}

package/samples/recipes/list-table-options/src/feature.ts

@@ -0,0 +1,221 @@
+import {
+  answerListAggregate,
+  buildEntityTable,
+  createEventStoreExecutor,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createDateField,
+  createEntity,
+  createNumberField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+  entityListSchema,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { ListTableOptions } from "@cosmicdrift/kumiko-framework/ui-types";
+import { z } from "zod";
+
+export const taskEntity = createEntity({
+  table: "read_list_table_tasks",
+  fields: {
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      searchable: true,
+      sortable: true,
+    }),
+    status: createSelectField({
+      options: ["open", "inProgress", "blocked", "done"] as const,
+      default: "open",
+      sortable: true,
+      filterable: true,
+    }),
+    priority: createSelectField({
+      options: ["low", "medium", "high"] as const,
+      default: "medium",
+      sortable: true,
+      filterable: true,
+    }),
+    dueDate: createDateField({ sortable: true }),
+    assignee: createTextField({ personal: false, reason: "is_business_data", sortable: true }),
+    estimateHours: createNumberField({ sortable: true, filterable: true }),
+  },
+});
+
+export const openAccess = {
+  access: {
+    openToAll: { reason: "recipe: any signed-in user manages the tasks; no per-user ownership" },
+  },
+} as const;
+
+// Overridable so a test can feed the boot validator a block that must be rejected.
+export function createTaskBoardFeature(
+  taskTable: ListTableOptions = {
+    rememberState: true,
+    resetAll: true,
+    columnPicker: true,
+    density: { default: "comfortable", userChoice: true },
+    pinning: true,
+    resizing: true,
+    keyboardNavigation: true,
+    export: { xlsx: true, maxRows: 5000 },
+    grouping: { field: "status", collapsedWhen: "done", userChoice: true, fields: ["priority"] },
+    totals: [{ field: "estimateHours", kind: "sum" }],
+  },
+): FeatureDefinition {
+  return defineFeature("task-board", (r) => {
+    r.crud("task", taskEntity, { write: openAccess, read: openAccess });
+
+    r.screen({
+      id: "task-list",
+      type: "entityList",
+      entity: "task",
+      columns: [
+        // Starts pinned left; width and minWidth are start values for resizing.
+        { field: "title", pinned: "left", width: 280, minWidth: 160 },
+        "status",
+        "priority",
+        { field: "dueDate", hideOnNarrow: true },
+        { field: "assignee", hideOnNarrow: true },
+        // Starts hidden; the user can add it back in the view menu.
+        { field: "estimateHours", hidden: true, hideOnNarrow: true },
+      ],
+      facets: { status: { display: "chips" }, priority: {}, estimateHours: { display: "range" } },
+      defaultSort: { field: "dueDate", dir: "asc" },
+      searchable: true,
+      table: taskTable,
+      rowActions: [
+        { kind: "navigate", id: "open", label: "Open", screen: "task-edit", rowClick: true },
+        {
+          kind: "writeHandler",
+          id: "delete",
+          label: "Delete",
+          handler: "task-board:write:task:delete",
+          style: "danger",
+          // Done tasks are skipped by the bulk run and counted as skipped.
+          visible: { field: "status", ne: "done" },
+        },
+      ],
+      // Row checkboxes and a selection bar; each selected row gets its own delete write.
+      bulkActions: [{ id: "delete", rowAction: "delete" }],
+      access: openAccess.access,
+    });
+
+    r.screen({
+      id: "task-edit",
+      type: "entityEdit",
+      entity: "task",
+      dormant: true,
+      listScreenId: "task-list",
+      layout: {
+        sections: [
+          {
+            columns: 2,
+            fields: ["title", "assignee", "status", "priority", "dueDate", "estimateHours"],
+          },
+        ],
+      },
+    });
+
+    // The same block works on a list over any query.
+    r.queryHandler({
+      name: "task:overdue",
+      schema: z.object({}),
+      handler: async () => ({
+        rows: [{ id: "t1", title: "Quarterly VAT filing", assignee: "Ines", daysLate: 3 }],
+        nextCursor: null,
+      }),
+      access: openAccess.access,
+      outputSchema: z.object({
+        rows: z.array(
+          z.object({
+            id: z.string(),
+            title: z.string(),
+            assignee: z.string(),
+            daysLate: z.number(),
+          }),
+        ),
+        nextCursor: z.string().nullable(),
+      }),
+    });
+
+    r.screen({
+      id: "task-overdue",
+      type: "projectionList",
+      query: "task-board:query:task:overdue",
+      columns: ["title", "assignee", "daysLate"],
+      table: { rememberState: true, density: { userChoice: true } },
+    });
+
+    // A hand-written list query keeps grouping and totals when it accepts
+    // `aggregate` (entityListSchema carries it) and answers it on the server.
+    const taskExecutor = createEventStoreExecutor(
+      buildEntityTable("task", taskEntity),
+      taskEntity,
+      {
+        entityName: "task",
+      },
+    );
+    r.queryHandler({
+      name: "task:workload",
+      schema: entityListSchema,
+      handler: async (query, ctx) => {
+        const parentVisibility = { entities: ctx.registry.getAllEntities() };
+        const listPayload = query.payload;
+        if (listPayload.aggregate !== undefined) {
+          return answerListAggregate(
+            taskExecutor,
+            { ...listPayload, aggregate: listPayload.aggregate },
+            query.user,
+            ctx.db,
+            { parentVisibility },
+            {
+              entity: taskEntity,
+              resolveEntity: (name) => ctx.registry.getEntity(name),
+              viewer: { user: query.user, parentVisibility },
+            },
+          );
+        }
+        return taskExecutor.list(listPayload, query.user, ctx.db, { parentVisibility });
+      },
+      access: openAccess.access,
+    });
+
+    r.screen({
+      id: "task-workload",
+      type: "projectionList",
+      query: "task-board:query:task:workload",
+      columns: ["title", "assignee", "status", "estimateHours"],
+      defaultSort: { field: "title", dir: "asc" },
+      table: {
+        grouping: { field: "assignee" },
+        totals: [{ field: "estimateHours", kind: "sum" }],
+      },
+    });
+
+    r.nav({ id: "tasks", label: "task-board:nav.tasks", icon: "list", order: 10 });
+    r.nav({
+      id: "task-list",
+      label: "task-board:nav.list",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-list",
+      order: 10,
+    });
+    r.nav({
+      id: "task-overdue",
+      label: "task-board:nav.overdue",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-overdue",
+      order: 20,
+    });
+    r.nav({
+      id: "task-workload",
+      label: "task-board:nav.workload",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-workload",
+      order: 30,
+    });
+  });
+}

package/samples/recipes/pdf-audit-export/src/feature.ts

@@ -15,6 +15,7 @@ import {
   createTextField,
   defineFeature,
   defineWriteHandler,
+  MAX_LIST_LIMIT,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import {
@@ -51,7 +52,7 @@ function toFileNameSegment(text: string): string {
 }
 
 // One row above the limit tells "exactly full" from "cut off"; entity lists cap at 200 rows.
-const AUDIT_ROW_LIMIT = 100;
+const AUDIT_ROW_LIMIT = MAX_LIST_LIMIT - 1;
 
 const access = { access: { roles: ["Admin", "User"] } } as const;
 

package/samples/recipes/state-machine/src/events.ts

@@ -5,6 +5,7 @@
 
 import type { EventDef } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { INVOICE_STATES } from "./entities/invoice.ts";
 
 export const FEATURE_NAME = "billing";
 export const ENTITY_NAME = "invoice";
@@ -36,8 +37,8 @@ export const INVOICE_CREATED_EVENT = `${ENTITY_NAME}.created` as const;
 
 export const emptyEventPayload = z.object({});
 export const statusForcedPayload = z.object({
-  newStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
-  fromStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
+  newStatus: z.enum(INVOICE_STATES),
+  fromStatus: z.enum(INVOICE_STATES),
 });
 
 // The EventDefs r.defineEvent returns inside the feature setup. Handlers receive them so that

package/samples/recipes/tenant-isolation/README.md

@@ -5,6 +5,7 @@ Multi-tenant data isolation by default.
 ## What it shows
 
 - Tenant filter on ordinary handlers
+- `ctx.db.upsert`: insert-or-update on a tenant-scoped, non-event-sourced table. `conflictTarget` must contain `tenantId` and match a declared unique index (here `tenant_id, key`); event-fed tables are rejected
 - What breaks if you forget tenancy (and how the framework prevents it)
 
 ## Source