@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/managed-pages.md

@@ -0,0 +1,353 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/managed-pages. Do not edit. -->
+
+# managed-pages
+
+Tenant-editable, server-rendered public pages with per-tenant branding + tier-gated sanitized custom CSS — managed-pages wired up with config + anonymousAccess.
+
+## README
+
+# Recipe: managed-pages
+
+Tenant-editable, server-rendered public pages with per-tenant branding and
+opt-in, tier-gated **custom CSS** — the framework generalization of the
+`legal-pages`/`wrapLayout` render pattern, hardened for untrusted tenant input.
+
+**What the recipe demonstrates:**
+- Compose `managed-pages` (+ its `config` dependency and the `managed-pages-css`
+  companion toggle) in `runProdApp({ features: [...] })`
+- Required wirings: `anonymousAccess` + `extraContext` config plumbing
+- Single-tenant `resolveApexTenant` (multi-tenant resolves from the Host)
+- The render boundary: published-only, Markdown raw-HTML escaped, per-tenant
+  branding applied as scoped `:root` vars, custom CSS allowlist-sanitized and
+  contained in a `<style data-tenant-css>` block
+- 6 integration tests proving end-to-end behavior
+
+## Layout
+
+```
+samples/recipes/managed-pages/
+├── package.json                # workspace deps
+├── README.md                   # this file
+└── src/
+    ├── feature.ts              # the composed features re-exported for tests
+    └── __tests__/
+        └── feature.integration.test.ts  # 6 tests: render + branding + CSS
+```
+
+## Run tests
+
+```bash
+# From the repo root:
+bun kumiko test all samples/recipes/managed-pages/
+```
+
+When the tests are green:
+- A published page is reachable via `stack.app.request("/p/about")`; a draft is `404`
+- Per-tenant content is cache-isolated (`Vary: Host`)
+- Raw HTML in a Markdown body is escaped (no `<script>` execution)
+- Branding writes (`config:write:set`) roundtrip into the rendered HTML
+- Attack CSS (`position:fixed`, `@import`, `url()`) is neutralized at render
+
+## Integration into a real app
+
+### 1. Compose the features
+
+```typescript illustration
+// bin/main.ts
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import {
+  createManagedPagesFeature,
+  createManagedPagesCssFeature,
+} from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+
+await runProdApp({
+  features: [
+    createManagedPagesFeature({
+      // Host → tenantId. Single-tenant returns a constant; multi-tenant maps
+      // the subdomain / custom domain. NULL → 404 (no tenant for this host).
+      resolveApexTenant: (host) => resolveTenantForHost(host),
+      // Opt-in custom CSS (default false, fail-closed). The render-time
+      // sanitizer is the safety boundary; gate per tier with the companion.
+      allowCustomCss: true,
+    }),
+    createManagedPagesCssFeature(),
+    /* ... your other features */
+  ],
+  // routes run anonymous; multi-tenant honors the per-page X-Tenant header
+  anonymousAccess: { tenantExists: async (id) => /* validate */ true },
+});
+```
+
+`config` is auto-mounted by `runProdApp`. In `setupTestStack` it is **not**, so
+the recipe lists `createConfigFeature()` explicitly (see `src/feature.ts`).
+
+> **anonymousAccess:** a fixed `defaultTenantId` locks single-tenant and rejects
+> the per-page `X-Tenant` with `400 tenant_mismatch` unless it equals the
+> default. Multi-tenant apps wire `tenantExists` (or a `tenantResolver`) and let
+> the route's `X-Tenant` win.
+
+### 2. Create the table
+
+```bash
+bun kumiko-schema generate <name>    # detects the `page` entity → SQL migration
+bun kumiko-schema apply
+```
+
+### 3. Authoring + branding
+
+- Pages: TenantAdmin/SystemAdmin author via the `entityList`/`entityEdit`
+  screens (`managed-pages:screen:page-list`); wire nav/workspace onto them.
+- Branding: the `configEdit` screen (`managed-pages:screen:branding-settings`)
+  or `config:write:set` against the `BRANDING_QN.*` keys
+  (`managed-pages:config:branding-{title,accent-color,...,custom-css}`).
+
+### 4. Per-tenant CSS gating
+
+`createManagedPagesCssFeature()` is `r.toggleable({ default: false })`. To gate
+custom CSS per tier, wire `feature-toggles`/`tier-engine` so the
+`managed-pages-css` toggle is on only for entitled tenants. **Without a toggle
+runtime, `ctx.hasFeature` fails open** — the capability stays on. The fail-closed
+anchor is `allowCustomCss` (app-level opt-in); the toggle is the commercial gate.
+
+## Custom wrapLayout (your own marketing chrome)
+
+A custom `wrapLayout` receives `branding` RAW and untrusted: `title`/
+`description` are length-capped at write but **not** HTML-escaped, and
+`customCss` is unsanitized. Emit every tenant value through the exported
+boundary helpers — never interpolate `branding.title` yourself (stored XSS):
+
+```typescript illustration
+import {
+  brandingHeaderHtml,
+  brandingStyleBlock,
+  tenantStyleBlock,
+  TENANT_CONTENT_ATTR,
+} from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+
+const wrapLayout = (o) => `<!doctype html>
+<html lang="${o.lang}">
+<head>
+  <title>${o.title}</title>
+  ${/* your layout CSS */ ""}
+  ${brandingStyleBlock(o.branding)}            <!-- escaped :root theme vars -->
+  ${tenantStyleBlock(o.branding.customCss)}    <!-- scoped + sanitized + contained -->
+</head>
+<body>
+  ${brandingHeaderHtml(o.branding)}            <!-- escaped logo + title header -->
+  <main ${TENANT_CONTENT_ATTR}>${o.bodyHtml}</main>
+</body>
+</html>`;
+```
+
+`brandingHeaderHtml`/`brandingStyleBlock` escape + re-validate (hex/https) the
+branding tokens; `tenantStyleBlock` bakes in the scope selector so callers can't
+mis-scope and lose containment. The default skeleton (`wrapInLayout`) uses the
+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 |
+| `@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 |
+
+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
+tier-gated.
+
+## Cross-refs
+
+- [packages/bundled-features/src/managed-pages](../../../packages/bundled-features/src/managed-pages) — the feature
+- [packages/bundled-features/src/page-render/css-sanitize.ts](../../../packages/bundled-features/src/page-render/css-sanitize.ts) — the allowlist sanitizer
+- [samples/recipes/legal-pages](../legal-pages) — the simpler, static sibling
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  configValuesTable,
+  createConfigAccessorFactory,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { BRANDING_QN, pageEntity } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+import { seedPage } from "@cosmicdrift/kumiko-bundled-features/managed-pages/seeding";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { configFeature, managedPagesCssFeature, managedPagesFeature } from "../feature";
+
+// Branding writes are tenant-scoped — the admin's tenantId must equal the
+// rendered tenant (SYSTEM_TENANT_ID here), or the config row lands in the wrong
+// bucket and the render reads the default.
+const admin = createTestUser({ id: 1, roles: ["TenantAdmin"], tenantId: SYSTEM_TENANT_ID });
+
+let stack: TestStack;
+
+const render = async (path: string): Promise<string> => {
+  const res = await stack.app.request(`http://acme.example.com${path}`);
+  return res.text();
+};
+
+beforeAll(async () => {
+  const resolver = createConfigResolver();
+  stack = await setupTestStack({
+    features: [configFeature, managedPagesFeature, managedPagesCssFeature],
+    // Single-tenant: resolveApexTenant returns SYSTEM_TENANT_ID, so the route's
+    // X-Tenant header matches this defaultTenantId — no tenant_mismatch.
+    anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
+    // Wire ctx.config() so the branding query resolves the tenant's cascade.
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    }),
+  });
+  await unsafeCreateEntityTable(stack.db, pageEntity);
+  await unsafePushTables(stack.db, { configValuesTable });
+  await createEventsTable(stack.db);
+
+  await seedPage(stack.db, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug: "about",
+    lang: "en",
+    title: "About Acme",
+    body: "# Hello from **Acme**",
+    published: true,
+  });
+  await seedPage(stack.db, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug: "draft",
+    lang: "en",
+    title: "Draft",
+    body: "not live yet",
+    published: false,
+  });
+  await seedPage(stack.db, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug: "xss",
+    lang: "en",
+    title: "XSS probe",
+    body: "intro\n\n<script>alert('pwned')</script>\n\nfin",
+    published: true,
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("recipe :: managed-pages render", () => {
+  test("published page → 200 with rendered Markdown + Vary: Host", async () => {
+    const res = await stack.app.request("http://acme.example.com/p/about");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(res.headers.get("vary")).toBe("Host");
+    const html = await res.text();
+    expect(html).toContain("About Acme");
+    expect(html).toContain("<strong>Acme</strong>");
+  });
+
+  test("unpublished draft → 404 for anonymous visitors", async () => {
+    const res = await stack.app.request("http://acme.example.com/p/draft");
+    expect(res.status).toBe(404);
+  });
+
+  test("raw HTML in a Markdown body is escaped, never executed", async () => {
+    const html = await render("/p/xss");
+    expect(html).not.toContain("<script>alert");
+    expect(html).toContain("&lt;script&gt;");
+  });
+});
+
+describe("recipe :: branding (config self-service)", () => {
+  test("accent color + title roundtrip into the render", async () => {
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: BRANDING_QN.accentColor, value: "#ff0066" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: BRANDING_QN.title, value: "Acme Inc" },
+      admin,
+    );
+    const html = await render("/p/about");
+    expect(html).toContain("#ff0066");
+    expect(html).toContain("Acme Inc");
+  });
+});
+
+describe("recipe :: custom CSS (allowCustomCss, sanitized)", () => {
+  test("safe rule renders scoped + contained in <style data-tenant-css>", async () => {
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: BRANDING_QN.customCss, value: ".note { color: rebeccapurple; }" },
+      admin,
+    );
+    const html = await render("/p/about");
+    expect(html).toContain("<style data-tenant-css>");
+    expect(html).toContain("[data-tenant-content] .note");
+    expect(html).toContain("color: rebeccapurple");
+    expect(html).toContain("<main data-tenant-content>");
+    expect(html).toContain("[data-tenant-content]{overflow:hidden}");
+  });
+
+  test("attack CSS is neutralized at render; the one safe rule survives scoped", async () => {
+    const attack =
+      ".evil { position: fixed; top: 0; } .ok { color: red; } @import url('http://evil.test');";
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: BRANDING_QN.customCss, value: attack },
+      admin,
+    );
+    const html = await render("/p/about");
+    expect(html).not.toContain("position: fixed");
+    expect(html).not.toContain("@import");
+    expect(html).not.toContain("evil.test");
+    expect(html).toContain("[data-tenant-content] .ok");
+    expect(html).toContain("color: red");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  createManagedPagesCssFeature,
+  createManagedPagesFeature,
+} from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+// managed-pages declares `r.requires("config")` for its branding keys — the
+// config feature must be in the stack (runProdApp auto-mounts it; setupTestStack
+// does not, so the recipe lists it explicitly).
+export const configFeature = createConfigFeature();
+
+// Single-tenant apex: every request maps to the one system tenant. A multi-
+// tenant app resolves the tenant from the request Host (subdomain / custom
+// domain) and returns the matching tenantId instead — see README.
+export const managedPagesFeature = createManagedPagesFeature({
+  resolveApexTenant: () => SYSTEM_TENANT_ID,
+  allowCustomCss: true,
+});
+
+// Companion per-tenant toggle for the CSS-inject capability. Compose it and wire
+// feature-toggles to gate custom CSS per tier; without a toggle runtime,
+// `ctx.hasFeature` fails open and CSS stays on (the render-time sanitizer is the
+// safety boundary regardless).
+export const managedPagesCssFeature = createManagedPagesCssFeature();
+```

package/agents/examples/notes-history-basic.md

@@ -0,0 +1,345 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/notes-history-basic. Do not edit. -->
+
+# notes-history-basic
+
+Append-only note history — who wrote what, when — attached to any entity without changing it.
+
+## README
+
+# Notes History
+
+Attach an append-only note history to **any** entity — without adding a
+column to it, writing a migration, or touching its feature. The recipe
+creates a plain `task` entity that knows nothing about notes, then notes
+tasks through the `notes-history` bundle alone.
+
+The result: a task can carry any number of notes, each with an author and
+timestamp, in the order they were written — and the `task` row stays exactly
+`{ id, title }`.
+
+## What it shows
+
+- **Zero host changes** — `task` has no notes column, no notes-specific
+  wiring, no awareness of notes at all. Note-taking works anyway, because
+  the notes-history feature owns its own table.
+- **`notes-history:write:add-note`** — appends a `note-entry`
+  (`read_note_entries`) keyed by `{ entityType, entityId, body }`. The author
+  is never client-supplied: the write always attributes to the authenticated
+  caller, and `insertedAt` (a framework base column) is the timestamp.
+- **Strictly append-only** — there is no update or delete handler. A
+  correction is a new entry, not an edit, so who wrote what and when stays
+  reconstructable — the entire reason this bundle exists (a single
+  overwritable textarea can't do that).
+- **Read-layer composition, no JOIN** — "this task's note history" lists
+  `note-entry` filtered by `entityId`, sorted by `insertedAt`. The app reads
+  and sorts; there is no relational pivot.
+
+## Using it — the notes flow
+
+You use the bundle by dispatching its handlers; nothing is wired into the
+noted entity. A host needs just two calls — `write` and `query` — which any
+app dispatcher provides. The flow below is embedded from `usage.ts` and is
+run end-to-end against the real dispatcher + DB by this recipe's integration
+test (`the documented notesFlow appends two notes, newest first`):
+
+```ts file=<rootDir>/_samples/recipes-notes-history-basic/src/usage.ts
+```
+
+## Web UI — the drop-in `<NotesSection>`
+
+You don't have to hand-build a notes UI. The feature ships one from its
+client subpath `@cosmicdrift/kumiko-bundled-features/notes-history/web`:
+`<NotesSection>` takes an `entityName` + `entityId`, shows that entity's note
+history newest-first, and lets the user append a new one — calling the same
+handler as above. Register `notesHistoryClient()` once (for its component +
+i18n), then mount it either way:
+
+```tsx illustration
+import { createKumikoApp } from "@cosmicdrift/kumiko-renderer-web";
+import { notesHistoryClient, NotesSection, NOTES_SECTION_EXTENSION_NAME } from "@cosmicdrift/kumiko-bundled-features/notes-history/web";
+
+// once, at app boot — required even for standalone use (registers i18n):
+createKumikoApp({ clientFeatures: [notesHistoryClient()] });
+
+// standalone — drop it into any screen, no entityEdit screen needed:
+<NotesSection entityName="task" entityId={taskId} />
+
+// or as an extension section in an entityEdit screen schema:
+{ kind: "extension", title: "Notes", component: { react: { __component: NOTES_SECTION_EXTENSION_NAME } } }
+```
+
+The component itself is `notes-history/web/notes-section.tsx`
+([source](https://github.com/CosmicDriftGameStudio/kumiko-framework/blob/main/packages/bundled-features/src/notes-history/web/notes-section.tsx)).
+
+## Feature composition
+
+```
+notes-history    → core bundle: note-entry entity, add-note handler, list query
+task-management  → our feature: a plain `task` entity. Declares
+                   r.requires("notes-history") only so the bundle is
+                   mounted — the task itself is completely notes-agnostic.
+```
+
+## Why it's event-sourced, not a pivot table
+
+Kumiko is event-sourced: there are no relational pivots queried by JOIN. The
+`note-entry` entity is a feature-owned, event-sourced row keyed by
+`(entityType, entityId)`, and the framework projects it into
+`read_note_entries` from its own create events. Unlike a join-table pattern
+with a deterministic id (see the `tags` bundle), there is no dedup key here —
+an entity legitimately carries many notes, so every `add-note` is an ordinary
+random-id stream. Cross-entity reads (a task's note history) are assembled by
+reading that projection and filtering in the app — never by joining across
+aggregates.
+
+## Run
+
+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
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Notes History Basic — integration test.
+//
+// Proves the host-agnostic note-history flow via the real dispatcher + DB:
+//   1. a plain `task` is created (the task feature knows nothing about notes)
+//   2. two notes are appended by (entityType, entityId)
+//   3. "this task's note history" reads from note-entry — read-layer
+//      composition, no JOIN, no column on `task`
+//
+// This is the smallest evidence that an entity needs zero notes-wiring.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  noteEntryEntity,
+  noteMentionEntity,
+  notesHistoryFeature,
+} from "@cosmicdrift/kumiko-bundled-features/notes-history";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { taskEntity, taskFeature } from "../feature";
+import { type NotesClient, notesFlow } from "../usage";
+
+const admin = createTestUser({ roles: ["TenantAdmin"] });
+
+// Adapt the test stack to the host-facing NotesClient the docs embed uses.
+const notesClient: NotesClient = {
+  write: <T>(type: string, payload: unknown) => stack.http.writeOk<T>(type, payload, admin),
+  query: <T>(type: string, payload: unknown) => stack.http.queryOk<T>(type, payload, admin),
+};
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [notesHistoryFeature, taskFeature] });
+  await unsafeCreateEntityTable(stack.db, noteEntryEntity);
+  await unsafeCreateEntityTable(stack.db, noteMentionEntity);
+  await unsafeCreateEntityTable(stack.db, taskEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_sample_notes_history_tasks");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_note_entries");
+});
+
+async function createTask(id: string, title: string) {
+  return stack.http.writeOk("task-management:write:task:create", { id, title }, admin);
+}
+
+describe("notes-history-basic recipe — append + compose", () => {
+  // Exercises the exact code embedded on the docs page (usage.ts → notesFlow).
+  test("the documented notesFlow appends two notes, newest first", async () => {
+    const taskId = "55555555-5555-4000-8000-000000000005";
+    await createTask(taskId, "Documented flow");
+
+    const result = await notesFlow(notesClient, taskId);
+
+    expect(result.entries).toHaveLength(2);
+    expect(result.entries[0]?.body).toBe("Client confirmed the scope.");
+    expect(result.entries[1]?.body).toBe("Kick-off call scheduled for Monday.");
+    expect(result.entries[0]?.authorId).toBe(admin.id);
+  });
+
+  test("a task carries its note history without any notes-column on the task", async () => {
+    const taskId = "11111111-1111-4000-8000-000000000001";
+    await createTask(taskId, "Quarterly review");
+
+    await notesClient.write("notes-history:write:add-note", {
+      entityType: "task",
+      entityId: taskId,
+      body: "Reviewed budget.",
+    });
+
+    const tasks = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+      "task-management:query:task:list",
+      {},
+      admin,
+    );
+    const task = tasks.rows.find((r) => r["id"] === taskId);
+    expect(task?.["title"]).toBe("Quarterly review");
+    expect(task).not.toHaveProperty("body");
+  });
+
+  test("notes are scoped per entity — a second task starts with an empty history", async () => {
+    const taskA = "22222222-2222-4000-8000-000000000002";
+    const taskB = "33333333-3333-4000-8000-000000000003";
+    await createTask(taskA, "Task A");
+    await createTask(taskB, "Task B");
+    await notesClient.write("notes-history:write:add-note", {
+      entityType: "task",
+      entityId: taskA,
+      body: "Only on A",
+    });
+
+    const ofB = await notesClient.query<{ rows: unknown[] }>(
+      "notes-history:query:note-entry:list",
+      {
+        filter: { field: "entityId", op: "eq", value: taskB },
+      },
+    );
+    expect(ofB.rows).toHaveLength(0);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// kumiko-feature-version: 1
+// Notes History Basic Sample
+//
+// Shows the whole point of the `notes-history` bundle: attaching a note
+// history to an entity needs ZERO changes to that entity. The `task` entity
+// below has no notes column, no note-specific wiring, no awareness of notes
+// at all — yet tasks can carry a chronological, authored note history,
+// because the notes-history feature owns its own table (read_note_entries)
+// and keys entries by (entityType, entityId).
+//
+// Flow (see the integration test):
+//   1. App-author defines a plain `task` entity — nothing note-specific.
+//   2. A user appends a note via `notes-history:write:add-note` with
+//      { entityType: "task", entityId: <taskId>, body }.
+//   3. "What notes does this task have?" is a read-layer composition: list
+//      `note-entry` filtered by entityId — no JOIN, no column on `task`.
+//   4. The author is never client-supplied — the write-handler always
+//      attributes the note to the authenticated caller.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// --- Entity ---
+//
+// A plain entity. Note there is NOTHING here that mentions notes — that is
+// the feature's promise: any entity can carry a note history as-is.
+
+export const taskEntity = createEntity({
+  table: "read_sample_notes_history_tasks",
+  fields: {
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 200,
+    }),
+  },
+});
+
+const taskTable = buildEntityTable("task", taskEntity);
+
+const taskExecutor = createEventStoreExecutor(taskTable, taskEntity, { entityName: "task" });
+
+// --- Feature ---
+
+export const taskFeature = defineFeature("task-management", (r) => {
+  // notes-history is non-optional for this recipe: the demo notes tasks.
+  // The task feature itself stays completely notes-agnostic — it only
+  // declares the dependency so the bundle is mounted.
+  r.requires("notes-history");
+
+  r.entity("task", taskEntity);
+
+  r.writeHandler({
+    name: "task:create",
+    schema: z.object({ id: z.string(), title: z.string() }),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (event, ctx) =>
+      taskExecutor.create({ id: event.payload.id, title: event.payload.title }, event.user, ctx.db),
+  });
+
+  r.queryHandler({
+    name: "task:list",
+    schema: z.object({}),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (_query, ctx) => {
+      const rows = await ctx.db.selectMany(taskTable);
+      return { rows };
+    },
+  });
+});
+```
+
+### src/usage.ts
+
+```ts
+// Notes History Basic — using the bundle.
+//
+// The notes-history feature is driven entirely by dispatching its handlers;
+// nothing is wired into the noted entity. A host needs exactly two calls —
+// write and query — which any app dispatcher provides. This recipe's
+// integration test runs `notesFlow` below against the real dispatcher + DB.
+
+// The minimal surface the notes flow needs from a host dispatcher. An app's
+// client satisfies this; the integration test adapts the test stack to it.
+export type NotesClient = {
+  write: <T>(type: string, payload: unknown) => Promise<T>;
+  query: <T>(type: string, payload: unknown) => Promise<T>;
+};
+
+// Append two notes to a task, then read its history back.
+export async function notesFlow(client: NotesClient, taskId: string) {
+  // 1. Append a note to ANY entity by (type, id) — no column on that entity.
+  //    The author is never passed in: the server always attributes the note
+  //    to the authenticated caller.
+  await client.write("notes-history:write:add-note", {
+    entityType: "task",
+    entityId: taskId,
+    body: "Kick-off call scheduled for Monday.",
+  });
+  await client.write("notes-history:write:add-note", {
+    entityType: "task",
+    entityId: taskId,
+    body: "Client confirmed the scope.",
+  });
+
+  // 2. "What notes does this task have?" — filter note-entry by entityId,
+  //    newest first.
+  const history = await client.query<{
+    rows: Array<{ body: string; authorId: string; insertedAt: string }>;
+  }>("notes-history:query:note-entry:list", {
+    filter: { field: "entityId", op: "eq", value: taskId },
+    sort: "insertedAt",
+    sortDirection: "desc",
+  });
+
+  return { entries: history.rows };
+}
+```