@cosmicdrift/kumiko-samples 0.338.0

package/samples/recipes/timezones/README.md

@@ -0,0 +1,97 @@
+# Timezones
+
+Every time-aware field type on one entity, plus the `ctx.tz` handler API. The
+recipe ships a `delivery` entity that carries four different kinds of time and
+two feature-level queries that reach for `ctx.tz` directly.
+
+Dates are the field type people get wrong most often — "10:00" means nothing
+without a zone, a birthday has no time at all, and "now" is a single instant
+seen differently around the world. The framework gives each of those its own
+field type so the ambiguity is gone at the schema, not patched in handlers.
+
+## What it shows
+
+- **Four time field types**, each for a distinct shape of time:
+  - `createLocatedTimestampField()` — a **wall-clock time at a place**
+    (`pickup`). One schema field becomes two columns (`pickup_utc` +
+    `pickup_tz`) and three read fields (`{ at, tz, utc }`). Write `{ at, tz }`
+    and the framework computes the UTC instant; read it back and you get the
+    original wall-clock, the zone, **and** the UTC instant.
+  - `createDateField()` — a **calendar date** with no time and no zone
+    (`dropoffOn`). A birthday, a due date.
+  - `createTimestampField()` — a **UTC instant**, a single point on the
+    timeline (`bookedAt`). When something happened.
+  - `createTzField()` — a bare **IANA zone name** (`homeZone`), e.g.
+    `"Europe/Berlin"`.
+- **IANA validation at the write boundary** — an invalid zone name (in a `tz`
+  field or in a located field's `tz`) is rejected with a `validation_error`
+  before it ever reaches the database, via `Intl.supportedValuesOf`.
+- **`ctx.tz` in handlers** — the time API feature code uses instead of
+  `new Date()`:
+  - `ctx.tz.todayRange(zone)` / `ctx.tz.today(zone)` — the `day-window` query
+    returns today's UTC range for a zone, ready to drop into a `BETWEEN` over
+    the `pickup_utc` column. It crosses DST and the date line correctly.
+  - `ctx.tz.fromCoordinates(coords)` — the `zone-at` query resolves lat/lng to
+    an IANA zone through an injected `GeoTzProvider`.
+
+## The located field, end to end
+
+```
+write   { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" }
+stored  pickup_utc = 2026-04-15T09:00:00Z   pickup_tz = "Europe/Lisbon"
+read    { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon", utc: "2026-04-15T09:00:00Z" }
+```
+
+Lisbon is on summer time (UTC+1) on that date, so 10:00 local is 09:00 UTC —
+and the recipe's integration test pins exactly that, proving the conversion is
+DST-aware rather than a fixed offset. The wall-clock you wrote comes back
+unchanged; the `utc` field is there when you need to sort or range-query.
+
+The renderer pairs this field with a date-time + zone picker out of the box, so
+a form binding to `pickup` gets the combined control with no extra wiring — see
+the `use-all-bundled` sample app for the live picker.
+
+## The GeoTzProvider seam
+
+`ctx.tz.fromCoordinates` / `ctx.tz.fromAddress` delegate to an optional
+provider you inject via the app context — there is no built-in geocoder, so v1
+ships nothing that phones home:
+
+```ts illustration
+runProdApp({ /* … */, extraContext: { geoTzProvider: myProvider } })
+// or buildServer({ context: { geoTzProvider: myProvider } })
+```
+
+`fromCoordinates` is the primary method because offline geo-tz libraries
+resolve **lat/lng**, not postal addresses; `fromAddress` is optional, for
+geocoding-API providers. With no provider configured, both throw a clear,
+actionable error. The recipe's test injects a tiny fake provider to exercise
+the seam end to end.
+
+## Flow
+
+1. Define the entity with `createEntity({ fields: { … } })` mixing the four
+   time field types.
+2. Register CRUD via `defineEntity*Handler` — create/update accept the located
+   field as `{ at, tz }`; the write boundary computes UTC.
+3. Add feature-level queries with `r.queryHandler` that call `ctx.tz` —
+   `day-window` (todayRange) and `zone-at` (fromCoordinates). Their names carry
+   no entity prefix, so they return their own shape instead of being filtered
+   against the entity's fields.
+
+## Tests
+
+```bash
+bun kumiko test integration samples/timezones
+```
+
+Integration tests under `src/__tests__/` prove the located round-trip with
+DST-aware UTC, all four field types preserved, IANA rejection at the write
+boundary, the `todayRange` day-window, and the `fromCoordinates` provider seam.
+
+## Related samples
+
+- [basic-entity](/en/samples/recipes-basic-entity/) — the CRUD baseline these
+  time fields sit on top of.
+- [custom-handlers](/en/samples/recipes-custom-handlers/) — more on
+  `r.writeHandler` / `r.queryHandler` with business logic.

package/samples/recipes/timezones/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-timezones",
+  "description": "Every time-aware field type on one entity, plus the ctx.tz handler API.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/timezones/src/feature.ts

@@ -0,0 +1,72 @@
+import {
+  createDateField,
+  createEntity,
+  createLocatedTimestampField,
+  createTextField,
+  createTimestampField,
+  createTzField,
+  defineEntityDeleteHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
+import { z } from "zod";
+
+export const deliveryEntity = createEntity({
+  table: "read_sample_deliveries",
+  fields: {
+    label: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    pickup: createLocatedTimestampField({ required: true }),
+    dropoffOn: createDateField(),
+    bookedAt: createTimestampField(),
+    homeZone: createTzField(),
+  },
+  softDelete: true,
+});
+
+const write = { access: { roles: ["Admin", "User"] } } as const;
+const adminWrite = { access: { roles: ["Admin"] } } as const;
+const openRead = {
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may list deliveries and query the timezone helpers below; " +
+        "writes are still gated by the roles above",
+    },
+  },
+} as const;
+
+export const timezonesFeature = defineFeature("timezones", (r) => {
+  r.crud("delivery", deliveryEntity, {
+    write,
+    read: openRead,
+    verbs: { delete: false, restore: false },
+  });
+  r.writeHandler(defineEntityDeleteHandler("delivery", deliveryEntity, adminWrite));
+
+  r.queryHandler(
+    "day-window",
+    z.object({
+      zone: z.string().refine(isValidIanaTimeZone, { message: "Invalid IANA timezone" }),
+    }),
+    async (query, ctx) => {
+      const { start, end } = ctx.tz.todayRange(query.payload.zone);
+      return {
+        zone: query.payload.zone,
+        date: ctx.tz.today(query.payload.zone).toString(),
+        start: start.toString(),
+        end: end.toString(),
+      };
+    },
+    openRead,
+  );
+
+  r.queryHandler(
+    "zone-at",
+    z.object({ latitude: z.number(), longitude: z.number() }),
+    async (query, ctx) => {
+      const zone = await ctx.tz.fromCoordinates(query.payload);
+      return { zone };
+    },
+    openRead,
+  );
+});

package/samples/recipes/tsconfig.base.json

@@ -0,0 +1,23 @@
+{
+  "_comment": "Single source of truth \u2014 check-app-tsc reads this template and overlays the @app/define branch for codegen recipes. Paths are relative to samples/recipes/<name>/.",
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "paths": {
+      "@cosmicdrift/kumiko-framework/*": [
+        "../../../packages/framework/src/*/index.ts"
+      ],
+      "@cosmicdrift/kumiko-bundled-features/*": [
+        "../../../packages/bundled-features/src/*/index.ts"
+      ],
+      "@cosmicdrift/kumiko-dev-server": [
+        "../../../packages/dev-server/src/index.ts"
+      ],
+      "@cosmicdrift/kumiko-dev-server/*": ["../../../packages/dev-server/src/*"]
+    },
+    "noEmit": true,
+    "rootDir": "../../..",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "types": ["bun-types"]
+  },
+  "include": ["./src"]
+}

package/samples/recipes/user-data-rights/README.md

@@ -0,0 +1,100 @@
+# user-data-rights
+
+GDPR-compliant domain wiring in ~5 lines: `r.useExtension(EXT_USER_DATA, …)`
+hooks any entity into the forget cron, export ZIP, and magic-link pipeline.
+You write two hooks per entity — the framework runs the rest.
+
+## What it shows
+
+A minimal notes domain with GDPR Art. 15+17+20 integrated without hand-written
+forget logic:
+
+```ts illustration
+defineFeature("notes", (r) => {
+  r.requires("user-data-rights");
+  r.entity("note", noteEntity);
+
+  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))),
+    }),
+    delete: async (ctx, strategy) => {
+      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 {
+        await ctx.db.delete(notesTable).where(where);
+      }
+    },
+  });
+});
+```
+
+## What runs automatically
+
+| 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 |
+
+## 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 |
+
+The integration test pins both paths.
+
+## Flow
+
+1. User creates notes → rows stored with `authorId`.
+2. `request-export` queues job → `runUserExport` bundles user + note rows.
+3. `request-deletion` → grace period from compliance profile.
+4. `runForgetCleanup` calls your `delete` hook with resolved strategy.
+
+## 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
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Step-by-step proof:
+
+1. Alice creates 2 notes → export bundle includes note snippet
+2. Deletion + expired grace → `runForgetCleanup` removes all notes
+3. Strategy `anonymize` → `authorId=null`, title/body remain
+
+## 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 |
+
+## Dependencies
+
+```ts illustration
+import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
+import { createUserDataRightsDefaultsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights-defaults";
+import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
+import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+
+export const features = [
+  createDataRetentionFeature(),
+  createComplianceProfilesFeature(),
+  createUserDataRightsFeature(),
+  createUserDataRightsDefaultsFeature(),
+  notesFeature,
+];
+```

package/samples/recipes/user-data-rights/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-user-data-rights",
+  "description": "DSGVO-compliant in 5 LOC: r.useExtension(EXT_USER_DATA, ...) haengt eine Domain an Forget+Export-Pipeline. Forget-Cron, Export-ZIP, Magic-Link kommen alle aus user-data-rights.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/user-data-rights/src/feature.ts

@@ -0,0 +1,97 @@
+// User-Data-Rights — Recipe
+//
+// Wie eine App-Domain DSGVO-Pipeline integriert: pro Entity einen
+// (export, delete)-Hook ueber EXT_USER_DATA. Forget-Cron, Export-ZIP-Bau
+// und Magic-Link-Versand kommen vollstaendig aus user-data-rights —
+// App-Author schreibt nur die zwei Hooks pro Entity.
+//
+// Demo-Domain: minimaler Note-Service. Note hat (id, tenantId, authorId,
+// title, body). Pinst:
+//   1. Hook export liefert Note-Rows als JSON-Snippet ins Export-Bundle.
+//   2. Hook delete entfernt Note-Rows beim Forget-Cleanup-Cron.
+//
+// Was nicht im Recipe ist (siehe samples/apps/user-data-rights-demo
+// fuer eine vollstaendige App):
+//   - Strategy-aware delete (anonymize vs hardDelete)
+//   - HTTP-Endpoints fuer create/list
+//   - Compliance-Profile-Wiring + Cron-Scheduling
+
+import { deleteMany, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  EXT_USER_DATA,
+  type UserDataDeleteHook,
+  type UserDataExportHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const noteEntity = createEntity({
+  table: "store_notes",
+  idType: "uuid",
+  fields: {
+    authorId: createTextField({ personal: "ref" }),
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 200,
+    }),
+    // Plaintext on purpose: store_notes is an unmanaged direct-write store, so the
+    // PII executor never encrypts it. Art. 17 runs through the EXT_USER_DATA
+    // hook below instead (deletes the author's rows, or unlinks them on anonymize).
+    body: createTextField({
+      personal: false,
+      reason: "covered_by_user_data_hook",
+      maxLength: 4000,
+    }),
+  },
+});
+
+// Plain EntityTableMeta, NOT a branded EntityTable: store_notes is a deliberate
+// unmanaged direct-write store (r.storeTable below), so the forget hook may
+// updateMany/deleteMany it directly — the meta carries no executor-only brand.
+export const notesTable = deriveEntityTableMeta("note", noteEntity, { source: "unmanaged" });
+
+export const notesFeature = defineFeature("notes", (r) => {
+  r.requires("user-data-rights");
+  // store_notes is a direct-write store: the forget hook below `updateMany`/
+  // `deleteMany`s rows WITHOUT emitting lifecycle events. r.entity would make
+  // it a rebuildable implicit projection whose replay finds zero note events
+  // and wipes the table (or un-forgets anonymized rows) on the next rebuild
+  // (#498). r.storeTable keeps the DDL, opts out of implicit rebuild.
+  r.storeTable(notesTable, {
+    reason: "read_side.notes_direct_write",
+  });
+
+  const exportNotes: UserDataExportHook = async (ctx) => {
+    const rows = await selectMany(ctx.db, notesTable, {
+      tenantId: ctx.tenantId,
+      authorId: ctx.userId,
+    });
+    if (rows.length === 0) return null;
+    return {
+      entity: "note",
+      rows: rows.map((row) => ({
+        id: String(row.id),
+        title: row.title ?? "",
+        body: row.body ?? "",
+      })),
+    };
+  };
+
+  const deleteNotes: UserDataDeleteHook = async (ctx, strategy) => {
+    const where = { tenantId: ctx.tenantId, authorId: ctx.userId };
+    if (strategy === "anonymize") {
+      await updateMany(ctx.db, notesTable, { authorId: null }, where);
+    } else {
+      await deleteMany(ctx.db, notesTable, where);
+    }
+  };
+
+  r.useExtension(EXT_USER_DATA, "note", {
+    export: exportNotes,
+    delete: deleteNotes,
+  });
+});

package/samples/recipes/user-profile/README.md

@@ -0,0 +1,86 @@
+# user-profile
+
+Self-service account page as a bundled feature: change password, change email
+(with re-auth + verification reset), and request or cancel account deletion
+(with grace period from `user-data-rights`).
+
+The bundled feature ships the `profile` screen itself (a declarative
+`projectionDetail`, fw#2312) plus handlers and i18n. **Your app** only points
+a nav entry at it and registers the two extension-section components
+(change-password, change-email — re-auth flows a declarative action can't
+express) — this recipe shows the wiring.
+
+## What it shows
+
+- **`user-profile:write:change-email`** — re-authenticated email change;
+  resets `emailVerified` until the user confirms the new address.
+- **`auth-email-password:write:change-password`** — used from the same
+  screen; lives on `auth-email-password`, not duplicated in user-profile.
+- **Account deletion** — `user-data-rights` handlers for request / cancel
+  deletion; grace period comes from the tenant's compliance profile.
+- **App-side nav wiring only** — `r.nav({ screen: "user-profile:screen:profile", ... })`;
+  no `r.screen()` registration needed, the bundled feature owns the screen.
+- **Full require chain** — `user` → `tenant` → `auth-email-password` →
+  `user-data-rights` (which pulls `data-retention`, `compliance-profiles`,
+  `sessions`). `composeAccountApp()` mounts everything boot needs.
+
+## Feature composition
+
+```
+user               → cross-tenant identity (email, roles, status)
+tenant             → memberships + tenant-scoped roles
+auth-email-password → login + change-password handlers
+data-retention     → retention policies (via user-data-rights)
+compliance-profiles → region profiles for grace periods
+sessions           → revocable JWTs (via user-data-rights chain)
+user-data-rights   → deletion request / export pipeline
+user-profile       → declarative `profile` screen + change-email handler
+account            → this recipe: nav wiring only
+```
+
+## Client wiring
+
+Register the two extension-section components once at app boot (the screen
+itself needs no client registration):
+
+```tsx illustration
+import { userProfileClient } from "@cosmicdrift/kumiko-bundled-features/user-profile/web";
+import { emailPasswordClient } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+import { createKumikoApp } from "@cosmicdrift/kumiko-renderer-web";
+
+createKumikoApp({
+  clientFeatures: [emailPasswordClient(), userProfileClient()],
+  // ... schema, nav from server features
+});
+```
+
+## Flow
+
+1. User opens the profile nav entry → renderer loads the declarative `profile`
+   screen.
+2. Password change dispatches `auth-email-password:write:change-password`.
+3. Email change dispatches `user-profile:write:change-email` (re-auth required).
+4. Delete account dispatches `user-data-rights:write:request-deletion`; cancel
+   uses the matching cancel handler during the grace window.
+
+## Tests
+
+Boot validation only — no DB/HTTP in this recipe (HTTP proof lives in the
+bundled-feature integration tests):
+
+```bash
+bun test src/__tests__/feature.test.ts
+```
+
+The test asserts `validateBoot(composeAccountApp())` passes, the profile
+screen/nav are registered, and the documented change-email qualified name
+matches `UserProfileHandlers.changeEmail`.
+
+## Related samples
+
+- [apex-surface-auth](/en/samples/recipes-apex-surface-auth/) — public login/
+  signup on the marketing apex (no admin nav).
+- [user-data-rights](/en/samples/recipes-user-data-rights/) — `EXT_USER_DATA`
+  hooks for export/forget on your domain entities.
+- [apps-user-data-rights-demo](/en/samples/apps-user-data-rights-demo/) —
+  full runnable app with todos + export ZIP.

package/samples/recipes/user-profile/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-user-profile",
+  "description": "user-profile bundled feature — Self-Service-Kontoseite (Passwort/E-Mail ändern, Konto löschen) als App-Screen verdrahten.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/user-profile/src/feature.ts

@@ -0,0 +1,73 @@
+// user-profile Recipe — shows the app-side wiring for the self-service
+// account page: the bundled feature ships the screen itself (fw#2312:
+// declarative `projectionDetail`, id "profile") including handler + i18n;
+// the app only has to navigate to it, no own `r.screen()` registration
+// anymore (unlike before #2312 — see user-data-rights' recipe/demo pattern:
+// `r.nav({ screen: "<feature>:screen:<id>", ... })`).
+//
+// Client-side, the app only registers the two extension-section components
+// (change-password/change-email stay React, re-auth):
+//   import { userProfileClient } from
+//     "@cosmicdrift/kumiko-bundled-features/user-profile/web";
+//   createKumikoApp({
+//     clientFeatures: [emailPasswordClient(), userProfileClient()],
+//   })
+
+import { createAuthEmailPasswordFeature } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
+import { createFilesFeature } from "@cosmicdrift/kumiko-bundled-features/files";
+import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
+import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
+import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
+import { createUserDataRightsDefaultsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights-defaults";
+import { createUserProfileFeature } from "@cosmicdrift/kumiko-bundled-features/user-profile";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+export function createAccountFeature(): FeatureDefinition {
+  return defineFeature("account", (r) => {
+    r.describe(
+      "App-side wiring for the user-profile bundled feature: just the nav " +
+        "entry — user-profile registers the `profile` screen itself " +
+        "(fw#2312 declarative projectionDetail).",
+    );
+    r.requires("user-profile");
+
+    r.nav({
+      id: "profile",
+      label: "account:nav.profile",
+      icon: "user",
+      screen: "user-profile:screen:profile",
+      order: 90,
+    });
+
+    return {};
+  });
+}
+
+/** Volle Feature-Komposition inkl. der user-profile-Require-Kette
+ *  (user-data-rights → data-retention + compliance-profiles + sessions). */
+export function composeAccountApp(): FeatureDefinition[] {
+  return [
+    createConfigFeature(),
+    createUserFeature(),
+    createTenantFeature(),
+    createAuthEmailPasswordFeature(),
+    createDataRetentionFeature(),
+    createComplianceProfilesFeature(),
+    authFoundationFeature,
+    createPersonalAccessTokensFeature({ scopes: {} }),
+    createSessionsFeature(),
+    createFilesFeature(),
+    createUserDataRightsFeature(),
+    // registers the default export/erase hooks for core PII entities (user,
+    // fileRef, folder) so the GDPR boot gate (V3) is satisfied for the stack.
+    createUserDataRightsDefaultsFeature(),
+    createUserProfileFeature(),
+    createAccountFeature(),
+  ];
+}

package/samples/recipes/webhook-step/README.md

@@ -0,0 +1,47 @@
+# Webhook Step
+
+Workflow / pipeline step that calls an HTTP webhook.
+
+## What it shows
+
+- Webhook step registration in a workflow
+- Retry / failure surface for outbound HTTP
+- Authenticated webhooks via a tenant-owned secret (`incident:open-authenticated`)
+
+## Auth secret
+
+`r.step.webhook.send`'s `auth.secret` is a name inside the tenant-owned
+`step-dispatcher:webhook-auth.<name>` namespace of the `secrets` feature —
+never a process-wide env var. The `secrets` feature must be mounted
+(`createSecretsFeature()` + a `MasterKeyProvider`) alongside
+`step-dispatcher`. Set the secret per tenant before dispatching:
+
+```ts
+await stack.http.writeOk(
+  "secrets:write:set",
+  { key: "step-dispatcher:webhook-auth.incident-hook", value: "<token>" },
+  tenantAdmin,
+);
+```
+
+Each tenant's secret is isolated — a tenant with no matching secret (or one
+stored without the `step-dispatcher:webhook-auth.` prefix) gets a generic
+`webhook auth secret is not available` `step.dispatch-failed` event, never
+another tenant's credential.
+
+Never combine `auth.secret` with a caller-controlled `url`: the caller would
+receive the secret as the `Authorization` header. `incident:open-authenticated`
+therefore posts to a fixed URL.
+
+## Source
+
+Feature entry point: `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/webhook-step
+bun test
+```

package/samples/recipes/webhook-step/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-webhook-step",
+  "description": "Tier-2 r.step.webhook.send showcase: deferred webhook dispatch via step-dispatcher subscription, no outbox table, retry from event-stream.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}