@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/AGENTS.md

@@ -0,0 +1,307 @@
+# Kumiko for coding agents
+
+This file ships inside `@cosmicdrift/kumiko-framework`. It always matches the
+installed version. Read it before you add or change a feature in a Kumiko app.
+
+Next to it, under `agents/`, are generated files. They are rebuilt from the
+framework source on every release, so they never describe an API that does
+not exist in your version:
+
+| File | What it holds |
+| --- | --- |
+| `agents/features.md` | Every bundled feature: name, purpose, config keys, dependencies |
+| `agents/widgets.md` | Every value export of `@cosmicdrift/kumiko-renderer-web` with its short description |
+| `agents/examples.md` | Index of the worked examples, one per concept |
+| `agents/examples/<name>.md` | One tested sample app: README plus every source and test file |
+
+The paths are relative to this file. From an app root they live under
+`node_modules/@cosmicdrift/kumiko-framework/`. Type signatures are in
+`dist/*.d.ts` of each package; this file does not repeat them.
+
+Order of work for a new feature:
+
+1. Search `agents/features.md` for a bundled feature that already does it.
+2. Find the closest example in `agents/examples.md` and read it fully.
+3. Build the feature with the declarative building blocks below.
+4. Write an integration test against the real stack.
+5. Run boot validation and the tests. Boot errors name the fix; apply it.
+
+## Mental model
+
+A Kumiko app is a list of features. Everything a feature does is registered
+on the `r` registrar inside `defineFeature(name, (r) => { ... })`. There is no
+router, controller or ORM to wire by hand. The framework reads the
+registrations, validates them at boot, and builds HTTP endpoints, database
+tables, events, screens and navigation from them.
+
+**Feature.** A named unit (`defineFeature("tasks", ...)`). It owns entities,
+handlers, screens, navs, translations, config and events. Features talk to
+each other through events, declared APIs and extensions, never through
+imports of each other's internals. An app mounts features in
+`src/run-config.ts` (`APP_FEATURES`).
+
+**Entity.** A typed record built with `createEntity({ fields })` and field
+factories such as `createTextField`, `createNumberField`,
+`createBooleanField`. An entity is event sourced: every write appends an
+event, and the table you query is a projection of those events. You never
+write the table yourself.
+
+**Handler.** The only way in. A write handler changes state, a query handler
+reads it. Both have a qualified name (QN), a Zod payload schema and an access
+rule. `r.crud(name, entity, options)` registers the entity plus create,
+update, delete, restore, list and detail handlers in one call. Turn single
+verbs off with `verbs: { delete: false }` and register them yourself when
+they need different access or logic. Custom logic goes into
+`r.writeHandler(qn, schema, fn, { access })` and
+`r.queryHandler(qn, schema, fn, { access })`; inside, use the entity
+executor from `createEntityExecutor(name, entity)`.
+
+**Screen.** A declarative page: `r.screen({ id, type, ... })`. Types include
+`entityList`, `entityEdit`, `projectionList`, `projectionDetail`,
+`actionForm`, `dashboard` and `custom`. The renderer builds the UI from the
+declaration. Columns, sections, row actions, tabs, wizard steps and
+conditional fields are data, not JSX.
+
+**Nav.** A sidebar entry: `r.nav({ id, label, screen, parent, order })`.
+Parents may belong to another feature; refer to them by QN.
+
+**Events.** Declare a domain event with `r.defineEvent(name, zodSchema)`.
+Emit it inside a write handler with `emitEvent(ctx, def, { ... })` or
+`ctx.appendEvent(...)`; it commits in the same transaction as the write.
+React to it with `r.projection(...)` (state on the same stream) or
+`r.multiStreamProjection({ name, apply })` (async consumer across streams,
+at least once, ordered).
+
+**Tenant scoping.** Every request runs for one tenant. `ctx.db`, executors
+and queries are already filtered to that tenant. You do not pass a
+`tenantId` around and you do not add tenant filters yourself. A feature
+that holds global data calls `r.systemScope()`.
+
+**Access.** Default deny. Every handler states who may call it:
+`{ access: { roles: ["Admin", "User"] } }`, or
+`{ access: { openToAll: { reason: "<why every signed-in user may>" } } }`.
+Screens and nav entries can narrow visibility further with their own
+`access`. Anonymous endpoints use the `anonymous` role. Field level and row
+level rules exist as well (see the table below).
+
+**Personal data.** Every text field says whether it holds personal data;
+the field types reject a text field without that stance.
+`personal: false, reason: "is_business_data"` (a snake_case reason) for
+business data. For personal data name the subject, `personal: "self"`,
+`personal: { of: "<ownerField>" }` or `personal: "tenant"`, plus
+`find: "exact" | "fuzzy" | "none" | "secret"`. A plain foreign key to a user
+is `personal: "ref"`. The framework encrypts personal fields per subject and
+can erase them on request.
+
+**Client.** The web side of a feature is a `ClientFeatureDefinition` in the
+feature's `web/index.ts` (name, translations, custom screen components). It
+is mounted in `src/client.tsx`. Declarative screens need no client code.
+
+## Qualified names
+
+Names are built from the feature name, a kind and an id. Use the QN wherever
+another feature or a test refers to something.
+
+| Thing | Pattern | Example from the scaffolded demo feature |
+| --- | --- | --- |
+| Write handler | `<feature>:write:<entity>:<verb>` | `tasks:write:task:create` |
+| Query handler | `<feature>:query:<entity>:<verb>` | `tasks:query:task:list` |
+| Screen | `<feature>:screen:<id>` | `tasks:screen:task-list` |
+| Nav entry | `<feature>:nav:<id>` | `tasks:nav:tasks` |
+| Translation key | `<feature>:<path>` | `tasks:nav.tasks` |
+| Entity field label | `<feature>:entity:<entity>:field:<field>` | `tasks:entity:task:field:title` |
+
+Inside one feature, a screen id without prefix (`screen: "task-edit"`) refers
+to a screen of the same feature.
+
+## Where things live in an app
+
+The scaffold (`bun create kumiko-app <name>`) produces this layout. Keep it.
+
+| Path | Content |
+| --- | --- |
+| `src/run-config.ts` | `APP_FEATURES`, the mounted feature list |
+| `src/features/<name>/feature.ts` | `defineFeature(...)` with entities, handlers, screens, navs |
+| `src/features/<name>/index.ts` | Public exports of the feature |
+| `src/features/<name>/web/index.ts` | Client feature definition |
+| `src/client.tsx` | Web entry, mounts the client features |
+| `src/__tests__/*.test.ts` | Unit tests, no services |
+| `src/__tests__/*.integration.test.ts` | Integration tests against Postgres and Redis |
+| `e2e/*.spec.ts` | Playwright tests against a booted app |
+| `kumiko/schema.ts`, `kumiko/migrations/` | Database schema and generated migrations |
+
+The scaffolded `src/features/tasks/feature.ts` and
+`src/__tests__/tasks.integration.test.ts` are the smallest complete pair of
+feature and test. Start from them.
+
+## Commands in an app
+
+| Goal | Command |
+| --- | --- |
+| Run the app with demo data | `bun dev` |
+| Boot validation without serving | `bun run boot` |
+| Types | `bun run typecheck` |
+| Lint | `bun run lint` |
+| Unit tests | `bun run test` |
+| Integration tests (needs `docker compose up -d`) | `bun run test:integration` |
+| Browser tests | `bun run e2e` |
+| New migration after an entity change | `bun run schema:generate` |
+| Apply migrations | `bun run schema:apply` |
+
+## Rules: never this, do that
+
+These rules are enforced by boot validation, guards or review. Breaking them
+produces code that compiles and then fails in production.
+
+### Data and events
+
+- Never `INSERT`, `UPDATE` or `DELETE` on an entity table or the events
+  table, and never call a raw database client for it. Write through a
+  handler: `r.crud`, the `defineEntity*Handler` helpers, the executor from
+  `createEntityExecutor`, or `emitEvent` / `ctx.appendEvent`.
+- Never store a value that can be computed. Derive it in a query or a
+  projection.
+- Never hand-write SQL for reads that an executor `list` or `detail` covers.
+  Use `r.queryHandler` with the executor, or a projection with
+  `ctx.queryProjection`.
+- Never change an event schema in place once it has been emitted. Version it
+  (see `agents/examples/event-sourcing.md`).
+- Never read or write another tenant's data. `ctx.db` is tenant scoped on
+  purpose. Cross-tenant work belongs in system features with explicit
+  system access.
+
+### Handlers and access
+
+- Never register a handler without `access`. Use roles, or `openToAll` with
+  a concrete `reason`.
+- Never throw plain `Error` for an expected domain failure. Return a typed
+  failure from `@cosmicdrift/kumiko-framework/errors` (for example
+  `failNotFound(entity, id)`); it reaches the client as a structured error
+  with a reason and, where documented, a `docsUrl`.
+- Never parse request input by hand. The Zod schema of the handler is the
+  boundary; inside the handler the payload is typed.
+- Read-modify-write updates pass the `version` they read, so concurrent
+  writes fail with `version_conflict` instead of overwriting each other.
+
+### Types
+
+- Never use `any`. Validate external data once at the boundary (Zod), then
+  work with the inferred type.
+- Never use `as` to force a type except at a real system boundary. Narrow
+  unions with a discriminant and `unknown` with a type guard.
+- Never write a magic string where a union type or a QN exists.
+
+### UI
+
+- Never write your own JSX for a list, form, detail page or dashboard.
+  Declare a screen. Use `type: "custom"` only when no screen type fits.
+- Inside a custom screen, never build your own card, table, badge, button or
+  chart. Use the widgets from `@cosmicdrift/kumiko-renderer-web`
+  (`agents/widgets.md`) and the primitives from `usePrimitives()`.
+- Never fetch data with `useEffect` plus `fetch`. Use `useQuery`
+  (`live: true` for server-sent updates) and `useMutation`.
+- Never use inline styles, hex colors or Tailwind palette classes. Use the
+  theme tokens (`bg-primary`, `text-status-ok`, ...).
+- Never put user-facing text in code. Use translation keys and `t("...")`;
+  register the texts with `r.translations` and the client translations.
+
+### Tests
+
+- Integration tests run against the real stack over real HTTP. In an app:
+  `setupAppTestStack([feature])` plus `seedTenant(stack)` from
+  `@cosmicdrift/kumiko-testing`, then `tenant.api.writeOk` and
+  `tenant.api.queryOk`. Never assemble a dispatcher yourself
+  (`createTestDispatcher` or similar); it skips the production wiring.
+- Every test seeds its own tenant. No shared tenant, no global fixtures.
+- Assert behavior through handlers and their results, not internal tables.
+- A red or flaky test gets diagnosed. Never fix it with a longer timeout, a
+  retry, `serial` or fewer workers.
+- Tests that call real external providers end in `.real.test.ts` and run
+  only via `bun run test:real`, never in CI.
+
+### Boot errors
+
+- Boot validation stops the app when a declaration is inconsistent: an
+  unknown field in a column, a nav pointing at a missing screen, an
+  encrypted field marked searchable. The message names the
+  feature, the place and the fix. Apply the fix the message names instead
+  of working around the check.
+
+## I need X, use Y
+
+Before building anything here, search `agents/features.md`: auth, tenants,
+mail, files, jobs, billing, audit, notifications and GDPR flows already exist
+as bundled features.
+
+| I need | Use | Read |
+| --- | --- | --- |
+| A CRUD entity with list and edit | `createEntity` + `r.crud` + `entityList` / `entityEdit` screens | `agents/examples/basic-entity.md` |
+| Business logic beyond CRUD | `r.writeHandler` / `r.queryHandler` with `createEntityExecutor` | `agents/examples/custom-handlers.md` |
+| Relations between entities | `r.relation(entity, name, { type, target, foreignKey, onDelete })` | `agents/examples/relations.md` |
+| Structured sub-objects in a field | Embedded fields | `agents/examples/embedded.md` |
+| List, edit, custom screens and navs | `r.screen`, `r.nav` | `agents/examples/screens-nav.md` |
+| A record page with header, metrics, tabs | `projectionDetail` with `header`, `metrics`, `layout.mode: "tabs"` | `agents/examples/record-detail-layout.md` |
+| A multi-step form | `layout.mode: "wizard"` | `agents/examples/wizard-form.md` |
+| A form inside a drawer | `RenderEdit` in a `Drawer` | `agents/examples/embedded-entity-form.md` |
+| Role-based access | `access: { roles }`, `openToAll` | `agents/examples/access-control.md` |
+| Field-level access | Field access rules | `agents/examples/field-access.md` |
+| Row ownership | Ownership rules | `agents/examples/ownership.md` |
+| Tenant separation | Built in; see what it guarantees | `agents/examples/tenant-isolation.md` |
+| Public or anonymous endpoints | `anonymous` role | `agents/examples/anonymous-access.md` |
+| Allowed state changes | Entity transitions | `agents/examples/state-machine.md` |
+| React to a write in another feature | `r.defineEvent` + `emitEvent` + `r.multiStreamProjection` | `agents/examples/cross-feature-events.md` |
+| Projections, event versions, history | `r.projection`, `ctx.loadAggregate`, `ctx.queryProjection` | `agents/examples/event-sourcing.md` |
+| Before or after save logic | Lifecycle hooks | `agents/examples/lifecycle-hooks.md` |
+| Typed errors with reasons | `@cosmicdrift/kumiko-framework/errors` | `agents/examples/error-contract.md` |
+| Translations | `r.translations` + client translations | `agents/examples/i18n.md` |
+| Config per tenant or system | Managed config | `agents/examples/managed-config.md` |
+| Tenant defaults (currency, locale) | Tenant settings | `agents/examples/tenant-settings.md` |
+| Secrets such as API keys | Secrets with envelope encryption | `agents/examples/secrets-demo.md` |
+| Personal data and erasure | `personal` / `find` annotations, crypto shredding | `agents/examples/crypto-shredding-hr.md` |
+| GDPR export and forget for my data | `user-data-rights` extension | `agents/examples/user-data-rights.md` |
+| Full-text search | Search feature | `agents/examples/search.md` |
+| Live updates in the browser | Server-sent events, `useQuery({ live: true })` | `agents/examples/realtime-sse.md` |
+| Feature toggles | Toggleable features | `agents/examples/feature-toggles.md` |
+| Rate limits | Rate limiting | `agents/examples/rate-limiting.md` |
+| Idempotent writes | Request id dedupe | `agents/examples/idempotency.md` |
+| File variants and images | File fields, derivatives | `agents/examples/files-post-processing.md` |
+| Money fields | Currency fields | `agents/examples/currencies-per-tenant.md` |
+| Dates, times, time zones | Time-aware field types, `ctx.tz` | `agents/examples/timezones.md` |
+| Tags or notes on any entity | Tags, notes history | `agents/examples/tags-basic.md`, `agents/examples/notes-history-basic.md` |
+| Tenant-defined extra fields | Custom fields | `agents/examples/custom-fields-basic.md` |
+| Lookup tables and seeds | Upsert seeds | `agents/examples/reference-data.md` |
+| Multi-step background flows | Workflow engine | `agents/examples/workflow-engine.md` |
+| A mount invariant for my feature | `r.bootCheck` | `agents/examples/boot-check.md` |
+| A widget for a custom screen | Search by concern | `agents/widgets.md` |
+| A bundled feature and its config | Search by name or purpose | `agents/features.md` |
+
+## Reading an example
+
+Each `agents/examples/<name>.md` starts with the sample's README, then every
+source file with its path. `src/feature.ts` holds the feature;
+`src/__tests__/*.integration.test.ts` shows how it is tested. Samples inside
+the framework repo set up their stack with `setupTestStack` from
+`@cosmicdrift/kumiko-framework/stack` and create tables in the test. In an
+app, `setupAppTestStack` and `seedTenant` do that for you; keep the
+assertions, take the setup from your scaffolded integration test.
+
+Some samples import from `@app/define`. That alias points at the generated
+`.kumiko/define.ts`, which re-exports the engine with event types narrowed to
+the app's own `r.defineEvent` declarations. `bun dev` and `bun run build`
+regenerate it; never edit it. Without it, import the same names from
+`@cosmicdrift/kumiko-framework/engine`.
+
+## Package entry points
+
+Import only from these subpaths of `@cosmicdrift/kumiko-framework`. Deep
+imports into `src/` or `dist/` break on the next release.
+
+| Subpath | Use it for |
+| --- | --- |
+| `/engine` | `defineFeature`, `createEntity`, field factories, handler helpers, executors, events |
+| `/errors` | Typed failures and error helpers |
+| `/stack` | Test stack, `TestUsers`, `createTestUser` |
+| `/testing` | Assertion helpers such as `expectErrorIncludes` |
+| `/ui-types` | Screen definition types (`EntityListScreenDefinition`, ...) |
+| `/db` | `buildEntityTable` and database helpers for tests and migrations |
+| `/event-store` | Event store helpers |

package/agents/examples/access-control.md

@@ -0,0 +1,355 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/access-control. Do not edit. -->
+
+# access-control
+
+Default-deny access rules, openToAll vs. role-based handlers, and auto-indices for foreign keys.
+
+## README
+
+# Access Control
+
+Default-deny access rules and FK indices via relations.
+
+## What it shows
+
+- Handler `access` roles as the default-deny gate
+- Relation-declared FK indices for join-friendly schemas
+
+## 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/access-control
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import {
+  accessControlFeature,
+  projectEntity,
+  projectTable,
+  taskEntity,
+  taskTable,
+} from "../feature";
+
+let stack: TestStack;
+const admin = TestUsers.admin; // { id: 1, tenantId: 1, roles: ["Admin"] }
+const user = TestUsers.user; // { id: 2, tenantId: 1, roles: ["User"] }
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [accessControlFeature] });
+  await unsafeCreateEntityTable(stack.db, projectEntity);
+  await unsafeCreateEntityTable(stack.db, taskEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack?.cleanup();
+});
+
+describe("default-deny: refuses handlers without access", () => {
+  test("throws at registration when a handler lacks an access rule", () => {
+    // `access` is required since fw#2855 — the registrar throws before validateBoot ever runs.
+    expect(() =>
+      defineFeature("broken-feature", (r) => {
+        // @ts-expect-error — No { access: ... }: registration must reject this.
+        r.writeHandler("forgotAccess", z.object({ name: z.string() }), async () => ({
+          isSuccess: true as const,
+          data: {},
+        }));
+      }),
+    ).toThrow(/requires schema \+ handler \+ options\.access/);
+  });
+});
+
+describe("role-based vs openToAll", () => {
+  test("Admin-only handler rejects a User caller with access_denied", async () => {
+    const raw = await stack.http.write(
+      "access-control:write:project:create",
+      { name: "Rejected", ownerId: "11111111-0000-4000-8000-000000000001" },
+      user,
+    );
+    const body = (await raw.json()) as { isSuccess: boolean; error?: { code: string } };
+    expect(body.isSuccess).toBe(false);
+    expect(body.error?.code).toBe("access_denied");
+  });
+
+  test("Admin-only handler accepts an Admin caller", async () => {
+    await stack.http.writeOk(
+      "access-control:write:project:create",
+      { name: "Alpha", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+  });
+
+  test("openToAll handler accepts any authenticated user", async () => {
+    const proj = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:project:create",
+      { name: "Shared", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "access-control:write:task:create",
+      { title: "User's task", projectId: proj.data.id },
+      user,
+    );
+  });
+});
+
+describe("auto-indices from relations", () => {
+  test("task table has an index on project_id because of the belongsTo relation", () => {
+    const names = taskTable.indexes.map((i) => i.name);
+
+    expect(names).toContain("read_ac_tasks_tenant_id_idx");
+    expect(names).toContain("read_ac_tasks_project_id_idx");
+  });
+
+  test("project table has only the tenant_id index (no belongsTo relations)", () => {
+    expect(projectTable.indexes.map((i) => i.name)).toEqual(["read_ac_projects_tenant_id_idx"]);
+  });
+});
+
+describe("optimistic locking: version required in update schema", () => {
+  test("update without version fails schema validation before reaching the crud executor", async () => {
+    const proj = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:project:create",
+      { name: "VersionedProject", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+    const created = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:task:create",
+      { title: "Needs version", projectId: proj.data.id },
+      user,
+    );
+
+    const raw = await stack.http.write(
+      "access-control:write:task:update",
+      // Missing `version` — schema rejects before any DB call.
+      { id: created.data.id, changes: { title: "Updated" } },
+      user,
+    );
+    const body = (await raw.json()) as { isSuccess: boolean; error?: { code: string } };
+    expect(body.isSuccess).toBe(false);
+    expect(body.error?.code).toBe("validation_error");
+  });
+
+  test("update with correct version succeeds", async () => {
+    const proj = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:project:create",
+      { name: "VersionedOk", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+    const created = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:task:create",
+      { title: "Task v1", projectId: proj.data.id },
+      user,
+    );
+
+    await stack.http.writeOk(
+      "access-control:write:task:update",
+      { id: created.data.id, version: 1, changes: { title: "Task v2" } },
+      user,
+    );
+  });
+});
+
+// Ensures this sample is wired through the full stack — if any of its
+// handlers regress to missing access or broken schemas, boot or this list
+// query will fail loudly.
+describe("end-to-end", () => {
+  test("list returns seeded tasks across users", async () => {
+    const proj = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:project:create",
+      { name: "ListTarget", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+
+    await stack.http.writeOk(
+      "access-control:write:task:create",
+      { title: "t1", projectId: proj.data.id },
+      user,
+    );
+    await stack.http.writeOk(
+      "access-control:write:task:create",
+      { title: "t2", projectId: proj.data.id },
+      admin,
+    );
+
+    const list = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "access-control:query:task:list",
+      {},
+      user,
+    );
+    expect(list.rows.length).toBeGreaterThanOrEqual(2);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Access Control + FK-Indices Sample
+//
+// Demonstrates the framework's security + performance defaults:
+//
+//  1. Default-deny: every handler must declare an access rule. Boot fails
+//     loudly when one is missing. Two shapes:
+//       { roles: ["Admin", ...] }          — role allowlist
+//       { openToAll: { reason: "..." } }   — any authenticated user, with a required reason
+//
+//  2. Foreign-key relations declared via r.relation() become indexed columns
+//     automatically — no manual CREATE INDEX. Inspect the Drizzle table
+//     config in tests to verify.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineFeature,
+  defineRoles,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// Typed role registry — `defineRoles` returns an object keyed by role name
+// so access rules can reference `AccessControlRoles.Admin` instead of the
+// magic string "Admin". Typos become compile errors, renames refactor.
+export const AccessControlRoles = defineRoles(["Admin"] as const);
+
+export const projectEntity = createEntity({
+  table: "read_ac_projects",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    ownerId: createTextField({ personal: "ref", required: true }),
+  },
+});
+
+export const taskEntity = createEntity({
+  table: "read_ac_tasks",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    assigneeId: createTextField({ personal: "ref" }),
+    projectId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+  },
+});
+
+// The "owner" relation points at a hypothetical external `user` entity — in
+// a real app this would be @cosmicdrift/kumiko-bundled-features/user. For the sample we
+// keep it internal: projectRelations only holds FK metadata (no cross-entity
+// resolution) so the sample stays self-contained.
+export const projectRelations = {} as const;
+
+export const taskRelations = {
+  project: { type: "belongsTo", target: "project", foreignKey: "projectId" },
+} as const;
+
+// Relations flow into buildEntityTable — every belongsTo FK gets its own
+// index on this table.
+export const projectTable = buildEntityTable("project", projectEntity, {
+  relations: projectRelations,
+});
+export const taskTable = buildEntityTable("task", taskEntity, {
+  relations: taskRelations,
+});
+
+export const accessControlFeature = defineFeature("access-control", (r) => {
+  r.entity("project", projectEntity);
+  r.entity("task", taskEntity);
+  r.relation("task", "project", taskRelations.project);
+
+  // Admin-only: standard create — no business logic, helper handles schema +
+  // executor + handler-body.
+  r.writeHandler(
+    defineEntityCreateHandler("project", projectEntity, {
+      access: { roles: [AccessControlRoles.Admin] },
+    }),
+  );
+
+  // Custom create: assigneeId defaults to the caller when omitted, so we
+  // hand-write this handler instead of using the helper. The framework helpers
+  // are deliberately scope-limited — opt out the moment you need defaults.
+  const taskExecutor = createEventStoreExecutor(taskTable, taskEntity, { entityName: "task" });
+  r.writeHandler(
+    "task:create",
+    z.object({
+      title: z.string().min(1),
+      projectId: z.uuid(),
+      assigneeId: z.uuid().optional(),
+    }),
+    async (event, ctx) =>
+      taskExecutor.create(
+        {
+          ...event.payload,
+          assigneeId: event.payload.assigneeId ?? event.user.id,
+        },
+        event.user,
+        ctx.db,
+      ),
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in tenant user may create a task; assigneeId defaults to the caller when omitted",
+        },
+      },
+    },
+  );
+
+  // Update requires version — optimistic locking is the default and this
+  // narrowed schema (only title + assigneeId mutable) is stricter than the
+  // helper's generic update schema, so we keep it hand-written.
+  r.writeHandler(
+    "task:update",
+    z.object({
+      id: z.uuid(),
+      version: z.number(),
+      changes: z.object({
+        title: z.string().min(1).optional(),
+        assigneeId: z.uuid().optional(),
+      }),
+    }),
+    async (event, ctx) => taskExecutor.update(event.payload, event.user, ctx.db),
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in tenant user may update a task; optimistic locking (version) " +
+            "guards against concurrent overwrites, not caller identity",
+        },
+      },
+    },
+  );
+
+  // Self-service list — no custom logic.
+  r.queryHandler(
+    defineEntityListHandler("task", taskEntity, {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in tenant user may list tasks; there is no per-user filter in this recipe",
+        },
+      },
+    }),
+  );
+});
+```