@cosmicdrift/kumiko-samples 0.403.0 → 0.404.1

package/samples/recipes/apex-landing/package.json

@@ -12,6 +12,6 @@
   },
   "devDependencies": {
     "@cosmicdrift/kumiko-testing": "workspace:*",
-    "@playwright/test": "^1.62.1"
+    "@playwright/test": "^1.64.1"
   }
 }

package/samples/recipes/apex-surface-auth/README.md

@@ -28,11 +28,15 @@ A typical app has two mounts sharing locale and primitives:
 
 ```tsx illustration
 import {
-  ForgotPasswordScreen, SignupScreen, createLoginRoute,
-  AuthShellProvider, emailPasswordClient,
+  ForgotPasswordScreen,
+  SignupScreen,
+  createLoginRoute,
+  AuthShellProvider,
+  emailPasswordClient,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
 import {
-  RequestAccountDeletionScreen, ConfirmAccountDeletionScreen,
+  RequestAccountDeletionScreen,
+  ConfirmAccountDeletionScreen,
 } from "@cosmicdrift/kumiko-bundled-features/user-data-rights/web";
 import { createPublicSurface } from "@cosmicdrift/kumiko-renderer/web";
 
@@ -43,7 +47,7 @@ import { createPublicSurface } from "@cosmicdrift/kumiko-renderer/web";
 const LoginRoute = createLoginRoute({ loginScreenProps: { signupHref: "/signup" } });
 
 createPublicSurface({
-  clientFeatures: [emailPasswordClient()],   // SessionProvider + i18n
+  clientFeatures: [emailPasswordClient()], // SessionProvider + i18n
   shell: ({ children }) => (
     <MarketingChrome>
       <AuthShellProvider shell={(card) => <div className="py-12 flex justify-center">{card}</div>}>
@@ -52,10 +56,10 @@ createPublicSurface({
     </MarketingChrome>
   ),
   routes: [
-    { path: "/login",           component: <LoginRoute /> },
-    { path: "/signup",          component: <SignupScreen loginHref="/login" /> },
+    { path: "/login", component: <LoginRoute /> },
+    { path: "/signup", component: <SignupScreen loginHref="/login" /> },
     { path: "/forgot-password", component: <ForgotPasswordScreen loginHref="/login" /> },
-    { path: "/delete-account",         component: <RequestAccountDeletionScreen /> },
+    { path: "/delete-account", component: <RequestAccountDeletionScreen /> },
     { path: "/delete-account/confirm", component: <ConfirmAccountDeletionScreen /> },
   ],
   fallback: <LoginRoute />,
@@ -90,8 +94,8 @@ runProdApp({
 
 GDPR Art. 17 applies when the user **cannot log in** (lockout). The flow is
 email-verified (magic link), not login-gated. The HMAC token carries `userId`
-+ expiry (no DB table); purpose `"deletion-request"` blocks replay on other
-token endpoints. Second confirm is idempotent (`user_not_in_active_state`).
+- expiry (no DB table); purpose `"deletion-request"` blocks replay on other
+  token endpoints. Second confirm is idempotent (`user_not_in_active_state`).
 
 ## Tests
 

package/samples/recipes/auth-mfa/README.md

@@ -22,9 +22,7 @@ const mfaFeature = createAuthMfaFeature({
   issuer: "Your App",
 });
 const sessionCallbacks = createSessionCallbacks({ db });
-bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(
-  sessionCallbacks.sessionRevokeAllOthers,
-);
+bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(sessionCallbacks.sessionRevokeAllOthers);
 
 const server = buildServer({
   registry: buildRegistry([
@@ -37,7 +35,7 @@ const server = buildServer({
     mfaFeature,
     // ... other features
   ]),
-  context: { db, /* ... */ },
+  context: { db /* ... */ },
   jwtSecret: process.env.JWT_SECRET,
   auth: {
     membershipQuery: "tenant:query:memberships",

package/samples/recipes/auth-mfa/package.json

@@ -6,10 +6,10 @@
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*",
     "@cosmicdrift/kumiko-renderer": "workspace:*",
-    "react": "^19.2.6"
+    "react": "^19.3.1"
   },
   "devDependencies": {
     "@cosmicdrift/kumiko-testing": "workspace:*",
-    "@types/react": "^19.2.14"
+    "@types/react": "^19.3.0"
   }
 }

package/samples/recipes/boot-check/README.md

@@ -12,7 +12,7 @@ never mounted, and nothing caught it — until now.
   ctx exposing every mounted feature. Throw to fail the boot with a clear,
   feature-prefixed message.
 - **Conditional invariants `r.requires` can't express** — the check only
-  fails when *this* feature's own shape demands it (has a PII field), not
+  fails when _this_ feature's own shape demands it (has a PII field), not
   unconditionally. A plain `r.requires({ features: ["user-data-hook"] })` would fail even
   for a prompt-store variant with no PII fields at all.
 - **`validateBoot`** — the framework's boot-time validator, run directly
@@ -38,7 +38,7 @@ user-data-hook → companion feature the check requires when PII is present
 
 ## When to reach for it
 
-You're writing a feature whose validity depends on *another* feature being
+You're writing a feature whose validity depends on _another_ feature being
 mounted, but only under a condition your feature alone can evaluate (e.g.
 "only if I have PII fields", "only if I expose more than N screens"). If the
 requirement is unconditional, `r.requires`/`r.optionalRequires` is simpler

package/samples/recipes/compliance-profiles-demo/README.md

@@ -8,11 +8,11 @@ branches in your domain handlers.
 How a multi-tenant platform uses `compliance-profiles` to deliver different
 regulatory behaviour per tenant:
 
-| Tenant | Profile | Supervisory authority | Languages | Tenant-destroy grace |
-|---|---|---|---|---|
-| **A** (DACH) | `eu-dsgvo` | BlnBDI Berlin | de / en | 30 days |
-| **B** (Switzerland) | `swiss-dsg` | EDÖB Bern | de / fr / it / en | 30 days |
-| **C** (DACH-HR) | `de-hr-dsgvo-hgb` | State DPA | de | 60 days (HR override) |
+| Tenant              | Profile           | Supervisory authority | Languages         | Tenant-destroy grace  |
+| ------------------- | ----------------- | --------------------- | ----------------- | --------------------- |
+| **A** (DACH)        | `eu-dsgvo`        | BlnBDI Berlin         | de / en           | 30 days               |
+| **B** (Switzerland) | `swiss-dsg`       | EDÖB Bern             | de / fr / it / en | 30 days               |
+| **C** (DACH-HR)     | `de-hr-dsgvo-hgb` | State DPA             | de                | 60 days (HR override) |
 
 Plus tenant B with an override (`gracePeriod: { days: 90 }`) extending
 user-rights grace without losing other profile fields — deep-merge on the

package/samples/recipes/compose-stacks/README.md

@@ -28,14 +28,14 @@ the option.
 
 ## Boot requirements
 
-| Stack | Boot option | Also satisfied by |
-| --- | --- | --- |
-| `composeMailStack` | `mail` | a mounted `channel-email` |
-| `composeFileStack` without providers | `fileStorage` | a mounted file provider |
-| `composeGdprStack` | `kmsMode` | `kms` or `allowPlaintextPii` |
-| `composeGdprStack({ selfService })`, `composeUserDataRightsStack` | `mail` | a mounted `channel-email` |
-| `composeSecurityStack` | `kmsMode`, `rateLimit` not `false` | `kms` or `allowPlaintextPii` |
-| `composeSaasStack({ billing: "stripe" })` | `billing` (warning only) | a mounted subscription provider |
+| Stack                                                             | Boot option                        | Also satisfied by               |
+| ----------------------------------------------------------------- | ---------------------------------- | ------------------------------- |
+| `composeMailStack`                                                | `mail`                             | a mounted `channel-email`       |
+| `composeFileStack` without providers                              | `fileStorage`                      | a mounted file provider         |
+| `composeGdprStack`                                                | `kmsMode`                          | `kms` or `allowPlaintextPii`    |
+| `composeGdprStack({ selfService })`, `composeUserDataRightsStack` | `mail`                             | a mounted `channel-email`       |
+| `composeSecurityStack`                                            | `kmsMode`, `rateLimit` not `false` | `kms` or `allowPlaintextPii`    |
+| `composeSaasStack({ billing: "stripe" })`                         | `billing` (warning only)           | a mounted subscription provider |
 
 A missing option fails the boot with:
 

package/samples/recipes/cross-feature-events/README.md

@@ -68,6 +68,7 @@ The integration test pins three guarantees:
 ```bash
 bun kumiko test integration samples/cross-feature-events
 ```
+
 4. **Catch-up job** — `catch-up-job.integration.test.ts` places orders
    before the first dispatcher pass and checks that the `catchUp` job
    invoices each of them exactly once.

package/samples/recipes/crypto-shredding-hr/README.md

@@ -7,7 +7,7 @@ unreadable forever, and reads render the `[[erased]]` sentinel.
 
 The recipe ships a mini HR feature: an `employee` entity whose name and email
 are the employee's own PII, and an `hr-comment` entity whose body is
-encrypted under the key of the employee the comment is *about* — so a
+encrypted under the key of the employee the comment is _about_ — so a
 manager's comment dies with the employee's key, not the manager's.
 
 ## What it shows
@@ -41,7 +41,7 @@ manager's comment dies with the employee's key, not the manager's.
   than an alphabetically paginated one — not a plaintext sort column beside
   the encrypted one, which would survive the key erase and quietly undo the
   shredding.
-- **Forget = `kms.eraseKey(subject)`** — afterwards detail *and* list render
+- **Forget = `kms.eraseKey(subject)`** — afterwards detail _and_ list render
   `[[erased]]` for every protected field while the stored ciphertext bytes
   stay untouched.
 
@@ -62,7 +62,7 @@ deletion grace period.
 
 1. Create an employee → the executor creates a subject key on first insert
    and stores `displayName`/`email` as ciphertext.
-2. A comment about the employee is encrypted under the *employee's* key via
+2. A comment about the employee is encrypted under the _employee's_ key via
    `userOwned: { ownerField: "employeeId" }`.
 3. `kms.eraseKey({ kind: "user", userId })` — idempotent, tombstone stays
    for the audit trail.

package/samples/recipes/custom-fields-basic/README.md

@@ -3,7 +3,7 @@
 Let a tenant add their own fields to your entity at runtime — without
 writing a migration, without rebuilding your handler, without a code
 change. The recipe wires a `property` entity into the `custom-fields`
-bundle and drives a full *define → set → read* roundtrip.
+bundle and drives a full _define → set → read_ roundtrip.
 
 The result: the tenant defines `internalNumber: text`, sets it on a
 property, and reads it back flattened onto the row — looking exactly

package/samples/recipes/documents/README.md

@@ -0,0 +1,25 @@
+# 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
+```

package/samples/recipes/embedded-entity-form/package.json

@@ -5,10 +5,10 @@
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*",
     "@cosmicdrift/kumiko-renderer": "workspace:*",
-    "react": "^19.2.6"
+    "react": "^19.3.1"
   },
   "devDependencies": {
     "@cosmicdrift/kumiko-testing": "workspace:*",
-    "@types/react": "^19.2.14"
+    "@types/react": "^19.3.0"
   }
 }

package/samples/recipes/encrypted-tenant-config/README.md

@@ -10,10 +10,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
 });
 ```
 
@@ -39,10 +39,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/samples/recipes/env-composition/README.md

@@ -21,16 +21,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/samples/recipes/error-contract/README.md

@@ -14,15 +14,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/samples/recipes/event-sourcing/README.md

@@ -6,15 +6,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/samples/recipes/lane-routing/README.md

@@ -5,6 +5,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

package/samples/recipes/lane-routing/src/feature.ts

@@ -23,6 +23,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.
@@ -100,5 +101,12 @@ 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/samples/recipes/ledger-invoicing/README.md

@@ -38,12 +38,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/samples/recipes/legal-pages/README.md

@@ -162,12 +162,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).
@@ -195,22 +195,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/samples/recipes/managed-config/README.md

@@ -6,15 +6,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: {
@@ -48,7 +52,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
@@ -86,14 +90,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/samples/recipes/managed-pages/README.md

@@ -139,14 +139,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/samples/recipes/pdf-audit-export/package.json

@@ -8,6 +8,6 @@
   },
   "devDependencies": {
     "@cosmicdrift/kumiko-testing": "workspace:*",
-    "unpdf": "^1.8.1"
+    "unpdf": "^1.9.1"
   }
 }

package/samples/recipes/pipeline-basics/README.md

@@ -7,18 +7,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
@@ -84,7 +84,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/samples/recipes/public-share-token/README.md

@@ -20,11 +20,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