@cosmicdrift/kumiko-framework 0.403.0 → 0.404.1

package/agents/examples/documents.md

@@ -4,6 +4,34 @@
 
 A document register on top of existing records: captured files, expiry dates and per-record visibility.
 
+## README
+
+# Documents
+
+A document register on top of existing records: captured files with a category, linked to records, visible only to whoever may read those records.
+
+## What it shows
+
+- `createDocumentsFeature` (`@cosmicdrift/kumiko-bundled-features/documents`) with `categories`, `linkTargets` and `access` roles.
+- A `capture` rule turns a file field into a document source without the entity knowing about the documents feature: every saved `contract.file` is filed as a document of category `contract`, titled from the row, and linked to the contract's property.
+- Visibility follows the linked records: a document is visible to users who may read the linked records and the contract that owns the file. The `documents:query:for-record` query returns the documents of one record; a property reader sees none for the property because they may not read the contract that owns the file.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+```ts file=<rootDir>/_samples/recipes-documents/src/feature.ts
+```
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/documents
+bun test
+```
+
 ## Source files
 
 ### src/__tests__/feature.integration.test.ts

package/agents/examples/encrypted-tenant-config.md

@@ -18,10 +18,10 @@ the platform operator being able to read the plaintext from the DB.
 import { access, createTenantConfig } from "@cosmicdrift/kumiko-framework/engine";
 
 createTenantConfig("text", {
-  encrypted: true,        // ← ciphertext in the DB
-  write: access.admin,    // ← the tenant admin writes their own
-  read: access.admin,     // ← nobody else sees it
-  mask: { title: "billing.stripe-api-key", order: 1 },  // ← derives the edit screen + nav
+  encrypted: true, // ← ciphertext in the DB
+  write: access.admin, // ← the tenant admin writes their own
+  read: access.admin, // ← nobody else sees it
+  mask: { title: "billing.stripe-api-key", order: 1 }, // ← derives the edit screen + nav
 });
 ```
 
@@ -47,10 +47,10 @@ i18n key of the field label, `mask.order` its position.
 
 ## Vs. `r.secret` / `samples/recipes/secrets-demo`
 
-| Pattern | Scope | Use case |
-|---|---|---|
-| **`r.secret`** (envelope encryption, KEK rotation) | App-global | Platform-owned secrets (e.g. the master Stripe key that bills ALL customers). |
-| **`encrypted: true` config key** (this recipe) | Per-tenant | Customer-owned secrets. Customer sets, rotates, and never sees another customer's. Same envelope encryption + KEK keyring under the hood. |
+| Pattern                                            | Scope      | Use case                                                                                                                                  |
+| -------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **`r.secret`** (envelope encryption, KEK rotation) | App-global | Platform-owned secrets (e.g. the master Stripe key that bills ALL customers).                                                             |
+| **`encrypted: true` config key** (this recipe)     | Per-tenant | Customer-owned secrets. Customer sets, rotates, and never sees another customer's. Same envelope encryption + KEK keyring under the hood. |
 
 Combinable: the platform uses `r.secret` for its internal secrets,
 and in parallel customers have their tenant-owned `encrypted: true`

package/agents/examples/env-composition.md

@@ -29,16 +29,16 @@ instead of keeping a hand-written copy of every feature's variables.
 
 ## Blocks
 
-| Block | Where it lives | Registered by |
-| --- | --- | --- |
-| `kmsEnvSchema` | `crypto-shredding` | `createCryptoShreddingFeature()` |
-| `smtpEnvSchema` | `channel-email` | `createChannelEmailFeature()` |
-| `s3EnvSchema`, `createS3EnvSchema({ prefix })` | `file-provider-s3` | `createFileProviderS3Feature({ fromEnv: true })` |
-| `stripeEnvSchema({ prices })` | `subscription-stripe` | app (`extend`); the feature registers the bridge keys |
-| `paddleEnvSchema({ prices })` | `subscription-paddle` | app (`extend`); the feature registers the bridge keys |
-| `mfaTokenSecretsEnvSchema` | `auth-mfa` | `createAuthMfaFeature()` |
-| `buildInfoEnvSchema`, `demoAdminEnvSchema` | `foundation-shared` | app (`extend`) |
-| `prometheusMetricsEnvSchema` | `framework/observability` | app (`extend`) |
+| Block                                          | Where it lives            | Registered by                                         |
+| ---------------------------------------------- | ------------------------- | ----------------------------------------------------- |
+| `kmsEnvSchema`                                 | `crypto-shredding`        | `createCryptoShreddingFeature()`                      |
+| `smtpEnvSchema`                                | `channel-email`           | `createChannelEmailFeature()`                         |
+| `s3EnvSchema`, `createS3EnvSchema({ prefix })` | `file-provider-s3`        | `createFileProviderS3Feature({ fromEnv: true })`      |
+| `stripeEnvSchema({ prices })`                  | `subscription-stripe`     | app (`extend`); the feature registers the bridge keys |
+| `paddleEnvSchema({ prices })`                  | `subscription-paddle`     | app (`extend`); the feature registers the bridge keys |
+| `mfaTokenSecretsEnvSchema`                     | `auth-mfa`                | `createAuthMfaFeature()`                              |
+| `buildInfoEnvSchema`, `demoAdminEnvSchema`     | `foundation-shared`       | app (`extend`)                                        |
+| `prometheusMetricsEnvSchema`                   | `framework/observability` | app (`extend`)                                        |
 
 ## When to reach for it
 

package/agents/examples/error-contract.md

@@ -22,15 +22,15 @@ Every Kumiko error class in a real handler context. A single feature `orders-lit
 
 ## The classes — when do I use which?
 
-| Class | HTTP | Use in handler |
-|---|---|---|
-| `ValidationError` | 400 | Automatic from Zod. Never throw manually, only for validation-hook errors. |
-| `AccessDeniedError` | 403 | "You're not allowed" — ownership, role check, field lock. |
-| `NotFoundError` | 404 | Entity doesn't exist. Automatic via `failNotFound(entity, id)`. |
-| `ConflictError` | 409 | State collision without a version (e.g. "paid orders can't be cancelled"). |
-| `VersionConflictError` | 409 | Optimistic lock — comes out of CrudExecutor automatically. You never throw it. |
-| `UnprocessableError` | 422 | Business rule violated. The reason string describes what. |
-| `InternalError` | 500 | You **don't throw it yourself**. The framework wraps unexpected throws automatically. |
+| Class                  | HTTP | Use in handler                                                                        |
+| ---------------------- | ---- | ------------------------------------------------------------------------------------- |
+| `ValidationError`      | 400  | Automatic from Zod. Never throw manually, only for validation-hook errors.            |
+| `AccessDeniedError`    | 403  | "You're not allowed" — ownership, role check, field lock.                             |
+| `NotFoundError`        | 404  | Entity doesn't exist. Automatic via `failNotFound(entity, id)`.                       |
+| `ConflictError`        | 409  | State collision without a version (e.g. "paid orders can't be cancelled").            |
+| `VersionConflictError` | 409  | Optimistic lock — comes out of CrudExecutor automatically. You never throw it.        |
+| `UnprocessableError`   | 422  | Business rule violated. The reason string describes what.                             |
+| `InternalError`        | 500  | You **don't throw it yourself**. The framework wraps unexpected throws automatically. |
 
 ## Convenience helpers
 

package/agents/examples/event-sourcing.md

@@ -14,15 +14,15 @@ blocks Kumiko provides.
 
 ## What the sample shows
 
-| API | Purpose |
-|---|---|
-| `r.defineEvent(name, schema, { version, migrations })` | Event schema with version number + upcaster chain |
-| `ctx.events.append({ aggregateId, aggregateType, type, payload })` | Domain event on aggregate stream |
-| `r.projection(...)` | Single-stream read model, inline in the write TX |
-| `r.multiStreamProjection(...)` | Cross-aggregate read model, async via dispatcher |
-| `ctx.events.load(id, { asOf })` | Live aggregation with point-in-time |
-| `ctx.events.archive(id, { aggregateType })` | Archive a stream (Marten `ArchiveStream`) |
-| `ctx.dispatch.queryProjection(name)` | Tenant-scoped read-model query |
+| API                                                                | Purpose                                           |
+| ------------------------------------------------------------------ | ------------------------------------------------- |
+| `r.defineEvent(name, schema, { version, migrations })`             | Event schema with version number + upcaster chain |
+| `ctx.events.append({ aggregateId, aggregateType, type, payload })` | Domain event on aggregate stream                  |
+| `r.projection(...)`                                                | Single-stream read model, inline in the write TX  |
+| `r.multiStreamProjection(...)`                                     | Cross-aggregate read model, async via dispatcher  |
+| `ctx.events.load(id, { asOf })`                                    | Live aggregation with point-in-time               |
+| `ctx.events.archive(id, { aggregateType })`                        | Archive a stream (Marten `ArchiveStream`)         |
+| `ctx.dispatch.queryProjection(name)`                               | Tenant-scoped read-model query                    |
 
 ## Domain
 

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

@@ -46,12 +46,12 @@ invoicingFlow …`):
 Both recipes use the same primitive — accounts + balanced transactions — but
 record different things:
 
-| | [ledger-banking](../ledger-banking/) | ledger-invoicing |
-|---|---|---|
-| Accounts | all `asset` (bank accounts) | `asset` + `income` + `liability` |
-| A transaction is… | a transfer (cash moves) | an obligation (invoice) or its settlement |
-| Revenue recognised | n/a | at invoice time (accrual) |
-| Reports surfaced | balances | balances + P&L |
+|                    | [ledger-banking](../ledger-banking/) | ledger-invoicing                          |
+| ------------------ | ------------------------------------ | ----------------------------------------- |
+| Accounts           | all `asset` (bank accounts)          | `asset` + `income` + `liability`          |
+| A transaction is…  | a transfer (cash moves)              | an obligation (invoice) or its settlement |
+| Revenue recognised | n/a                                  | at invoice time (accrual)                 |
+| Reports surfaced   | balances                             | balances + P&L                            |
 
 ## Run
 

package/agents/examples/legal-pages.md

@@ -170,12 +170,12 @@ page in `createLegalPagesLayout({ siteName })`.
 
 After the seed these URLs are immediately live:
 
-| URL | Content |
-|---|---|
-| `https://your-app.example/legal/impressum` | Impressum (DE) |
-| `https://your-app.example/legal/datenschutz` | Datenschutzerklärung (DE) |
-| `https://your-app.example/legal/imprint` | Imprint (EN, if seeded) |
-| `https://your-app.example/legal/privacy` | Privacy Policy (EN, if seeded) |
+| URL                                          | Content                        |
+| -------------------------------------------- | ------------------------------ |
+| `https://your-app.example/legal/impressum`   | Impressum (DE)                 |
+| `https://your-app.example/legal/datenschutz` | Datenschutzerklärung (DE)      |
+| `https://your-app.example/legal/imprint`     | Imprint (EN, if seeded)        |
+| `https://your-app.example/legal/privacy`     | Privacy Policy (EN, if seeded) |
 
 → Footer links are set per app (legal-pages does not ship a footer
 component — deliberately, every app has its own layout).
@@ -203,22 +203,22 @@ ACL: `["TenantAdmin", "SystemAdmin"]`. Cache header `public, max-age=300`
 When the required blocks (`imprint/de` + `privacy/de`) are missing
 from SYSTEM_TENANT:
 
-| Mode | Behavior |
-|---|---|
+| Mode                  | Behavior                                                    |
+| --------------------- | ----------------------------------------------------------- |
 | `NODE_ENV=production` | App boot throws an error with a slug list — container exits |
-| otherwise (dev/test) | `console.warn` with a slug list, app starts anyway |
+| otherwise (dev/test)  | `console.warn` with a slug list, app starts anyway          |
 
 → Safety net: no production deploy without populated legal pages.
 
 ## Troubleshooting
 
-| Symptom | Cause | Fix |
-|---|---|---|
-| Route returns `503 legal page unavailable` | `anonymousAccess` not configured in `runProdApp` | Set `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` |
-| Boot check throws `ctx.templateResolver missing` | `extraContext.templateResolver` not wired | Set `extraContext: ({ db, registry }) => ({ templateResolver: createTemplateResolverApi(db, registry) })` |
-| Route returns `404 not configured` | Required block doesn't exist or has `content=null` | `seedTextBlock` with a content string |
-| Multi-tenant app: tenant subdomain shows an empty page | (Bug regression?) Routes should ALWAYS show SYSTEM_TENANT texts | The `legal-pages.integration.test.ts` test "SYSTEM_TENANT routing" covers this — should be green |
-| `<script>` tags in a Markdown body land 1:1 in the HTML | Deliberately accepted right now — see [legal-pages/README.md XSS section](../../../packages/bundled-features/src/legal-pages/README.md#xss--currently-not-secured-by-design) | DOMPurify is a Phase 2 once a multi-author setup arrives |
+| Symptom                                                 | Cause                                                                                                                                                                        | Fix                                                                                                       |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Route returns `503 legal page unavailable`              | `anonymousAccess` not configured in `runProdApp`                                                                                                                             | Set `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }`                                              |
+| Boot check throws `ctx.templateResolver missing`        | `extraContext.templateResolver` not wired                                                                                                                                    | Set `extraContext: ({ db, registry }) => ({ templateResolver: createTemplateResolverApi(db, registry) })` |
+| Route returns `404 not configured`                      | Required block doesn't exist or has `content=null`                                                                                                                           | `seedTextBlock` with a content string                                                                     |
+| Multi-tenant app: tenant subdomain shows an empty page  | (Bug regression?) Routes should ALWAYS show SYSTEM_TENANT texts                                                                                                              | The `legal-pages.integration.test.ts` test "SYSTEM_TENANT routing" covers this — should be green          |
+| `<script>` tags in a Markdown body land 1:1 in the HTML | Deliberately accepted right now — see [legal-pages/README.md XSS section](../../../packages/bundled-features/src/legal-pages/README.md#xss--currently-not-secured-by-design) | DOMPurify is a Phase 2 once a multi-author setup arrives                                                  |
 
 ## Cross-refs
 

package/agents/examples/managed-config.md

@@ -14,15 +14,19 @@ backings and two scopes, without a hand-written screen, nav, or env-wiring map.
 
 Two keys, deliberately different:
 
-| Key | Scope | Backing | Story |
-|---|---|---|---|
+| Key               | Scope    | Backing   | Story                                                                                                                                                                                      |
+| ----------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `payment-api-key` | `system` | `secrets` | Platform-owned secret (one Stripe key bills all tenants). Stored envelope-encrypted in the secrets store, masked in every query, revealed only for the owning feature's `ctx.config` read. |
-| `smtp-host` | `tenant` | config | Platform default that a tenant admin overrides. Cascade resolves `tenant-row → system-row → default`; one tenant's override never leaks to another. |
+| `smtp-host`       | `tenant` | config    | Platform default that a tenant admin overrides. Cascade resolves `tenant-row → system-row → default`; one tenant's override never leaks to another.                                        |
 
 ## Pattern
 
 ```ts illustration
-import { access, createSystemConfig, createTenantConfig } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  access,
+  createSystemConfig,
+  createTenantConfig,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 r.config({
   keys: {
@@ -56,7 +60,7 @@ r.config({
   valid for `scope: "system"` — secrets are flat per `(tenant, key)` with no
   cascade, so a tenant override would be incoherent and is rejected at boot.
 - **`env: "SMTP_HOST"`** — at boot (`runProdApp`) the env var seeds the key's
-  default as an app-override, below any `system-row`. The env var *is* the
+  default as an app-override, below any `system-row`. The env var _is_ the
   default; no manual `AppConfigOverrides` map, no re-typing in the admin UI.
 - **`mask`** — the key surfaces automatically in the self-populating settings
   hub: `buildConfigFeatureSchema` derives a `configEdit` screen + a child nav
@@ -94,14 +98,14 @@ the config backing only needs the `ctx.services.secrets` context shown above.
 
 ## Vs. the neighbouring recipes
 
-| Pattern | Storage | Cascade | Use case |
-|---|---|---|---|
-| **`encrypted: true` config key** (`encrypted-tenant-config`) | `config_values`, AES ciphertext | system → tenant | Per-tenant customer secret, no KEK rotation/audit. |
-| **`backing: "secrets"` config key** (this recipe) | secrets envelope, system tenant | none (system-only) | Platform-owned secret needing rotation + audit-on-read, declared as a config key. |
-| **`r.secret`** (`secrets-demo`) | secrets envelope | none | Same storage, but addressed directly — no config key, no settings-hub entry. |
+| Pattern                                                      | Storage                         | Cascade            | Use case                                                                          |
+| ------------------------------------------------------------ | ------------------------------- | ------------------ | --------------------------------------------------------------------------------- |
+| **`encrypted: true` config key** (`encrypted-tenant-config`) | `config_values`, AES ciphertext | system → tenant    | Per-tenant customer secret, no KEK rotation/audit.                                |
+| **`backing: "secrets"` config key** (this recipe)            | secrets envelope, system tenant | none (system-only) | Platform-owned secret needing rotation + audit-on-read, declared as a config key. |
+| **`r.secret`** (`secrets-demo`)                              | secrets envelope                | none               | Same storage, but addressed directly — no config key, no settings-hub entry.      |
 
 `backing: "secrets"` is the bridge: you get the secrets store's guarantees
-*and* the config feature's declarative surface (masking, settings hub, the same
+_and_ the config feature's declarative surface (masking, settings hub, the same
 `config:write:set` write path).
 
 ## Flow

package/agents/examples/managed-pages.md

@@ -147,14 +147,14 @@ exact same helpers.
 
 ## Security posture
 
-| Threat | Mitigation |
-|---|---|
-| `<script>`/raw HTML in a page body | `renderSafeMarkdown` escapes raw HTML (Markdown-only) |
-| Cross-tenant content on a shared CDN | `Vary: Host` + per-tenant `resolveApexTenant` |
-| Draft leak to anonymous visitors | published-only; drafts → 404 |
+| Threat                                                    | Mitigation                                                          |
+| --------------------------------------------------------- | ------------------------------------------------------------------- |
+| `<script>`/raw HTML in a page body                        | `renderSafeMarkdown` escapes raw HTML (Markdown-only)               |
+| Cross-tenant content on a shared CDN                      | `Vary: Host` + per-tenant `resolveApexTenant`                       |
+| Draft leak to anonymous visitors                          | published-only; drafts → 404                                        |
 | `@import`/`url()`/`expression()`/`</style>` in custom CSS | allowlist-by-construction sanitizer (rebuilt from validated tokens) |
-| Scope-escape / overlay onto host chrome | scope-prefix + `position`/`isolation`/`overflow` containment |
-| Untrusted tenant abusing CSS | tier-gate (`managed-pages-css`) + `allowCustomCss` opt-in |
+| Scope-escape / overlay onto host chrome                   | scope-prefix + `position`/`isolation`/`overflow` containment        |
+| Untrusted tenant abusing CSS                              | tier-gate (`managed-pages-css`) + `allowCustomCss` opt-in           |
 
 Custom-CSS sanitization for untrusted tenants is **best-effort defense-in-depth**:
 a tenant can still restyle its **own** page area within the clip. Keep it

package/agents/examples/pipeline-basics.md

@@ -15,18 +15,18 @@ behaves end-to-end against the worktree's framework source.
 
 ## What's inside
 
-| Step | Where it shows up |
-|---|---|
-| `r.step.aggregate.create` | `product:create` |
-| `r.step.aggregate.update` | `product:rename`, `product:adjust-stock`, `product:bulk-adjust` |
-| `r.step.aggregate.appendEvent` | `product:adjust-stock`, `product:archive`, `report:archive-low-stock-products` |
-| `r.step.read.findOne` | `product:rename`, `product:adjust-stock`, `product:bulk-adjust` |
-| `r.step.read.findMany` | `report:archive-low-stock-products` |
-| `r.step.compute` | `product:adjust-stock`, `product:bulk-adjust` |
-| `r.step.branch` | `product:rename`, `product:adjust-stock` |
-| `r.step.forEach` | `product:bulk-adjust`, `report:archive-low-stock-products` |
-| `r.step.return` | every handler |
-| `r.step.unsafeProjectionUpsert` | `product:adjust-stock` |
+| Step                            | Where it shows up                                                              |
+| ------------------------------- | ------------------------------------------------------------------------------ |
+| `r.step.aggregate.create`       | `product:create`                                                               |
+| `r.step.aggregate.update`       | `product:rename`, `product:adjust-stock`, `product:bulk-adjust`                |
+| `r.step.aggregate.appendEvent`  | `product:adjust-stock`, `product:archive`, `report:archive-low-stock-products` |
+| `r.step.read.findOne`           | `product:rename`, `product:adjust-stock`, `product:bulk-adjust`                |
+| `r.step.read.findMany`          | `report:archive-low-stock-products`                                            |
+| `r.step.compute`                | `product:adjust-stock`, `product:bulk-adjust`                                  |
+| `r.step.branch`                 | `product:rename`, `product:adjust-stock`                                       |
+| `r.step.forEach`                | `product:bulk-adjust`, `report:archive-low-stock-products`                     |
+| `r.step.return`                 | every handler                                                                  |
+| `r.step.unsafeProjectionUpsert` | `product:adjust-stock`                                                         |
 | `r.step.unsafeProjectionDelete` | `product:adjust-stock`, `product:archive`, `report:archive-low-stock-products` |
 
 ## Domain
@@ -92,7 +92,7 @@ engine APIs land in a published release.
   in the pure event-sourcing shape — it appends a domain event
   (`product-stock-adjusted`) and lets the inline
   `product-stock-counter` projection update `currentStock`. The
-  alternative (calling `aggregate.update` *and* `appendEvent` in
+  alternative (calling `aggregate.update` _and_ `appendEvent` in
   one handler) inflates the stream-version mid-handler and trips
   optimistic-locking on the next call. The other handlers
   (`rename`, `bulk-adjust`) use `aggregate.update` directly

package/agents/examples/public-share-token.md

@@ -28,11 +28,11 @@ the URL carries a share token).
 
 ## Handlers
 
-| QN | Access |
-|---|---|
+| QN                                     | Access                      |
+| -------------------------------------- | --------------------------- |
 | `public-share:write:share-link:create` | authenticated (`openToAll`) |
-| `public-share:write:share-link:revoke` | owner |
-| `public-share:query:share-by-token` | anonymous + authenticated |
+| `public-share:write:share-link:revoke` | owner                       |
+| `public-share:query:share-by-token`    | anonymous + authenticated   |
 
 ## Run tests
 

package/agents/examples/security-baseline.md

@@ -53,7 +53,10 @@ mounts `sessions` as part of its own require-chain. Combine both directly;
 `dedupeFeatures()` collapses the two identical `sessions` instances at boot:
 
 ```ts illustration
-import { composeGdprStack, composeSecurityStack } from "@cosmicdrift/kumiko-dev-server/compose-stacks";
+import {
+  composeGdprStack,
+  composeSecurityStack,
+} from "@cosmicdrift/kumiko-dev-server/compose-stacks";
 
 export const APP_FEATURES = [
   // ...config, user, tenant, auth-foundation...

package/agents/examples/session-revocation.md

@@ -33,7 +33,7 @@ const server = buildServer({
     }),
     // ... other features
   ]),
-  context: { db, /* ... */ },
+  context: { db /* ... */ },
   jwtSecret: process.env.JWT_SECRET,
   auth: {
     membershipQuery: "tenant:query:memberships",

package/agents/examples/tenant-settings.md

@@ -64,12 +64,12 @@ role vocabulary overrides those instead of forking the feature.
 
 ## Why the schema needs a special case
 
-`buildInsertSchema` always makes `currency` required *inside* a money field's
+`buildInsertSchema` always makes `currency` required _inside_ a money field's
 value object, even when the field itself is optional — a caller literally
 cannot submit `{ amount: 1000 }` against the plain `defineEntityCreateHandler`.
 `defineCreateWithTenantDefaults` swaps in its own schema (`.extend()` over the
 same `buildInsertSchema` output, with just the declared `currencyFields`
-relaxed) so the caller *can* omit `currency`, then fills it from
+relaxed) so the caller _can_ omit `currency`, then fills it from
 `ctx.config(TenantSettingsConfig.currency)` before delegating to the same
 `executor.create()` the generic factory uses.
 
@@ -82,13 +82,13 @@ changes them from **Settings → Tenant → Default Currency / Default Locale**.
 
 ## Flow
 
-1. No tenant override yet → a new invoice gets the *feature's own* default
+1. No tenant override yet → a new invoice gets the _feature's own_ default
    (`"EUR"`/`"en"`, set via `createTenantSettingsFeature()`'s own defaults).
 2. Tenant sets `currency` to `"CHF"` and `locale` to `"de"` via the
    Settings-Hub (or `config:write:set` directly).
 3. A new invoice that doesn't specify `amount.currency`/`language` picks up
    `"CHF"`/`"de"` — no entity code changed, no second migration.
-4. A caller that *does* specify `amount.currency` still wins — the tenant
+4. A caller that _does_ specify `amount.currency` still wins — the tenant
    setting only fills gaps, it never overrides an explicit value.
 
 ## Tests

package/agents/examples/tier-admin.md

@@ -17,7 +17,7 @@ toggleable features unlock in the same request.
 ## What it shows
 
 - **`tier-engine:write:set-tenant-tier`** — a SystemAdmin assigns a tier
-  to *any* tenant, cross-tenant. Stamps `source: "manual"` so a future
+  to _any_ tenant, cross-tenant. Stamps `source: "manual"` so a future
   Stripe → tier sync won't overwrite the grant.
 - **`tier-engine:query:get-tenant-tier`** — SystemAdmin reads back which
   tier a tenant is on plus its source (`"manual"` vs `"billing"`).
@@ -58,7 +58,7 @@ notes-export → r.toggleable() domain feature unlocked by pro tier
 path bypasses the `postSave` entity-hook the resolver normally uses to
 invalidate the cache after a tier-assignment change. Without an explicit
 cache update the grant would persist (next request would see it) but
-*this* request still sees the old tier — surprising for an operator who
+_this_ request still sees the old tier — surprising for an operator who
 just clicked "set tier to pro".
 
 The feature wires `onAssigned` into `createSetTenantTierWrite` for

package/agents/examples/user-data-rights.md

@@ -25,13 +25,13 @@ defineFeature("notes", (r) => {
   r.useExtension(EXT_USER_DATA, "note", {
     export: async (ctx) => ({
       entity: "note",
-      rows: await ctx.db.select().from(notesTable)
-        .where(and(eq(notesTable.tenantId, ctx.tenantId),
-                   eq(notesTable.authorId, ctx.userId))),
+      rows: await ctx.db
+        .select()
+        .from(notesTable)
+        .where(and(eq(notesTable.tenantId, ctx.tenantId), eq(notesTable.authorId, ctx.userId))),
     }),
     delete: async (ctx, strategy) => {
-      const where = and(eq(notesTable.tenantId, ctx.tenantId),
-                        eq(notesTable.authorId, ctx.userId));
+      const where = and(eq(notesTable.tenantId, ctx.tenantId), eq(notesTable.authorId, ctx.userId));
       if (strategy === "anonymize") {
         await ctx.db.update(notesTable).set({ authorId: null }).where(where);
       } else {
@@ -44,21 +44,21 @@ defineFeature("notes", (r) => {
 
 ## What runs automatically
 
-| Article | What happens | Trigger |
-|---|---|---|
+| Article      | What happens                                   | Trigger                                |
+| ------------ | ---------------------------------------------- | -------------------------------------- |
 | Art. 15 + 20 | Notes snippet in export ZIP + magic-link email | `runUserExport` (via `request-export`) |
-| Art. 17 | Notes deleted or anonymized after grace | `runForgetCleanup` cron |
-| Art. 18 | Restriction blocks login while active | Auth middleware |
-| Operator | Brute-force detection on magic-link endpoint | Edge rate-limit + audit log |
+| Art. 17      | Notes deleted or anonymized after grace        | `runForgetCleanup` cron                |
+| Art. 18      | Restriction blocks login while active          | Auth middleware                        |
+| Operator     | Brute-force detection on magic-link endpoint   | Edge rate-limit + audit log            |
 
 ## Strategy-aware delete
 
 `retention.policyFor("note")` resolves per entity:
 
-| Profile | Strategy | Effect |
-|---|---|---|
-| `eu-dsgvo` (default) | `delete` | Notes hard-deleted |
-| `de-hr-dsgvo-hgb` | `anonymize` for HR entities | `authorId=null`, row kept for multi-user refs |
+| Profile              | Strategy                    | Effect                                        |
+| -------------------- | --------------------------- | --------------------------------------------- |
+| `eu-dsgvo` (default) | `delete`                    | Notes hard-deleted                            |
+| `de-hr-dsgvo-hgb`    | `anonymize` for HR entities | `authorId=null`, row kept for multi-user refs |
 
 The integration test pins both paths.
 
@@ -99,7 +99,9 @@ const result = await runRetentionCleanup({
   registry: stack.registry,
   tenantId,
   preloadedTenantPreset: null,
-  now: getTemporal().Now.instant().add({ hours: 31 * 24 }), // keepFor 30d + 1 day
+  now: getTemporal()
+    .Now.instant()
+    .add({ hours: 31 * 24 }), // keepFor 30d + 1 day
   files: createFileContext(() => Promise.resolve(provider)), // the stack's storage provider
 });
 // result.hardDeleted === 1, bytes and file_refs row gone
@@ -107,10 +109,10 @@ const result = await runRetentionCleanup({
 
 ## Full app vs this recipe
 
-| | This recipe | [user-data-rights-demo](/en/samples/apps-user-data-rights-demo/) |
-|---|---|---|
-| Scope | One hook pattern | Runnable app + todos + files |
-| Boot | Integration test only | `bun dev` on port 4291 |
+|       | This recipe           | [user-data-rights-demo](/en/samples/apps-user-data-rights-demo/) |
+| ----- | --------------------- | ---------------------------------------------------------------- |
+| Scope | One hook pattern      | Runnable app + todos + files                                     |
+| Boot  | Integration test only | `bun dev` on port 4291                                           |
 
 ## Dependencies
 

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