@cosmicdrift/kumiko-framework 0.363.0 → 0.364.0

package/agents/examples/cross-feature-events.md

@@ -0,0 +1,317 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/cross-feature-events. Do not edit. -->
+
+# cross-feature-events
+
+Feature appends a typed domain event via ctx.appendEvent; a r.multiStreamProjection reacts asynchronously.
+
+## README
+
+# Cross-Feature Reactions
+
+A handler emits a typed domain event onto the aggregate stream, and an
+async MultiStreamProjection reacts. Since Sprint E this is the
+Marten-gold-standard path for cross-feature reactions — the old
+`ctx.emit` + `r.postEvent` branch was removed in E.2.
+
+## What the sample shows
+
+Three building blocks:
+
+- **`r.defineEvent("name", zodSchema)`** declares the name and payload.
+  The qualified name (e.g. `pubsub-orders:event:order-placed`) comes
+  back as `.name` — pass it directly to `ctx.appendEvent`. Events that
+  aren't registered are rejected by `ctx.appendEvent` at the emit site.
+
+- **`ctx.appendEvent({ aggregateId, aggregateType, type, payload })`**
+  appends the event onto the aggregate stream within the same TX.
+  Version lineage is continued automatically — no synthetic
+  `"pubsub"` stream anymore, the event truly lives on the aggregate.
+
+- **`r.multiStreamProjection({ name, apply })`** declares a consumer.
+  The event dispatcher walks the `events` table via cursor and
+  delivers **at-least-once** in event-ID order. `table` can be omitted
+  — the MSP then becomes a pure side effect (send mail, webhook,
+  external system). With `table`, the apply materializes a persistent
+  read model.
+
+## Flow
+
+```
+HTTP → writeHandler
+         ↓ TX begin
+         orderExecutor.create(...)     ← business row + auto-event (pubsubOrder.created, v1)
+         ctx.appendEvent({...})        ← domain event (pubsub-orders:event:order-placed, v2)
+         ↓ TX commit
+         (async, post-commit)
+         event-dispatcher runOnce
+         ↓ per-consumer cursor advance
+         MSP apply → capture side effect
+```
+
+## Migration note
+
+`r.postEvent` was removed in Sprint E.2. `ctx.appendEvent` +
+`r.multiStreamProjection` is the unified Marten API for CRUD events,
+domain events, and cross-feature reactions.
+
+## Test
+
+The integration test pins three guarantees:
+
+1. **TX atomicity** — after commit the event row sits in the `events`
+   table on the aggregate stream (not on a synthetic `"pubsub"`
+   stream).
+2. **MSP delivery** — `runOnce()` delivers the event to the handler
+   with the correct `tenantId` + payload.
+3. **Rollback safety** — when the write fails, neither the business
+   row nor the event row nor the MSP side effect exists.
+
+```bash
+bun kumiko test integration samples/cross-feature-events
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Cross-Feature Reactions Sample — Integration Test
+//
+// Proves:
+//   1. ctx.appendEvent persists the domain event into the events-table
+//      inside the same TX as the business write, on the aggregate's own
+//      stream (aggregateType = "pubsub-order", not the legacy "pubsub").
+//   2. The event-dispatcher picks it up and invokes the
+//      r.multiStreamProjection handler at-least-once, with event.tenantId
+//      + payload intact.
+//   3. The handler is a regular async function — no timers, no magic
+//      callbacks. runOnce() drains deterministically.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { capturedEvents, orderEntity, pubsubOrderFeature } from "../feature";
+
+let stack: TestStack;
+
+const customer = createTestUser({ roles: ["Customer"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [pubsubOrderFeature] });
+  await unsafeCreateEntityTable(stack.db, orderEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  capturedEvents.length = 0;
+  stack.events.reset();
+  // Reset events + consumer cursors so each test starts from a clean log.
+  await resetEventStore(stack, ["read_sample_pubsub_orders"]);
+});
+
+describe("cross-feature reactions via ctx.appendEvent + r.multiStreamProjection", () => {
+  test("write commits → event on aggregate stream → MSP handler receives it", async () => {
+    const data = await stack.http.writeOk(
+      "pubsub-orders:write:order:place",
+      { customer: "Alice", product: "Widget" },
+      customer,
+    );
+    const orderId = String(data["id"]);
+
+    // The event row is committed alongside the order row. It lives on the
+    // order's OWN stream now — aggregateType "pubsub-order", version 2
+    // (auto "created" is v1, domain "order-placed" is v2).
+    const domainEvents = await selectMany(stack.db, eventsTable, {
+      aggregateType: "pubsub-order",
+      type: "pubsub-orders:event:order-placed",
+    });
+    expect(domainEvents).toHaveLength(1);
+    expect(domainEvents[0]?.aggregateId).toBe(orderId);
+    expect(domainEvents[0]?.version).toBeGreaterThan(1);
+    expect(domainEvents[0]?.payload).toMatchObject({
+      id: orderId,
+      customer: "Alice",
+      product: "Widget",
+    });
+    expect(domainEvents[0]?.tenantId).toBe(customer.tenantId);
+
+    // The dispatcher is built but not started in tests. runOnce drains
+    // deterministically — no timer-induced flakiness.
+    await stack.eventDispatcher?.runOnce();
+
+    expect(capturedEvents).toHaveLength(1);
+    expect(capturedEvents[0]).toMatchObject({
+      type: "pubsub-orders:event:order-placed",
+      payload: { id: orderId, customer: "Alice", product: "Widget" },
+      tenantId: customer.tenantId,
+    });
+  });
+
+  test("MSP is not invoked when the write rolls back (no half-emitted events)", async () => {
+    // An invalid write (missing required fields) fails Zod validation
+    // before any DB mutation. No event row, no MSP invocation — the
+    // appendEvent would have run in the same TX, so the rollback takes
+    // it with.
+    await stack.http.writeErr("pubsub-orders:write:order:place", { customer: "" }, customer);
+
+    const domainEvents = await selectMany(stack.db, eventsTable, {
+      type: "pubsub-orders:event:order-placed",
+    });
+    expect(domainEvents).toHaveLength(0);
+
+    await stack.eventDispatcher?.runOnce();
+    expect(capturedEvents).toHaveLength(0);
+  });
+
+  test("multiple appendEvents → events delivered in id-order, at-least-once", async () => {
+    for (const name of ["Bob", "Carol", "Dave"]) {
+      await stack.http.writeOk(
+        "pubsub-orders:write:order:place",
+        { customer: name, product: "X" },
+        customer,
+      );
+    }
+
+    await stack.eventDispatcher?.runOnce();
+
+    expect(capturedEvents.map((e) => e.payload.customer)).toEqual(["Bob", "Carol", "Dave"]);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Cross-Feature Reactions Sample (Marten gold-standard path)
+//
+// Demonstrates the Sprint-E pattern for reacting to events across features:
+// a writeHandler emits a DOMAIN event via `ctx.appendEvent(...)` onto the
+// aggregate's own stream, and a `r.multiStreamProjection` picks it up
+// asynchronously through the event-dispatcher.
+//
+// Three moving pieces:
+//
+//   1. `r.defineEvent("short-name", zodSchema)` declares the event shape.
+//      Returns a def whose `.name` is the fully-qualified event name —
+//      pass that straight to `ctx.appendEvent` so there's no string to
+//      hand-type (and no way to emit an unregistered event: appendEvent
+//      rejects at the emit site).
+//
+//   2. `ctx.appendEvent({ aggregateId, aggregateType, type, payload })`
+//      writes the event onto the aggregate's own stream inside the same
+//      transaction as the business write. Commit both or roll back both —
+//      no lost events, no orphan events. The event carries real
+//      aggregate/version lineage (Marten-aligned).
+//
+//   3. `r.multiStreamProjection({ name, apply })` declares an async
+//      consumer. The event-dispatcher walks the events-table via a
+//      persistent cursor and invokes the matching apply() handler
+//      at-least-once in events.id order.
+//
+// With `table` omitted the MSP is a pure side-effect consumer —
+// send notifications, post webhooks, sync external systems. The tx
+// argument is still live for the apply() if you need it.
+
+import {
+  createEntity,
+  createEntityExecutor,
+  createTextField,
+  defineFeature,
+  emitEvent,
+  typedPayload,
+} from "@app/define";
+import { z } from "zod";
+
+// --- Entity ---
+
+export const orderEntity = createEntity({
+  table: "read_sample_pubsub_orders",
+  fields: {
+    customer: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    product: createTextField({ personal: false, reason: "is_business_data", required: true }),
+  },
+});
+
+// --- Subscriber capture (for the integration test) ---
+//
+// Real consumers would write to a downstream store or call an external
+// service. Here we capture in-memory so the test can assert the roundtrip.
+// Exported so the test can import + reset between cases.
+
+export type CapturedEvent = {
+  readonly type: string;
+  readonly payload: { readonly id: unknown; readonly customer: string };
+  readonly tenantId: string;
+};
+export const capturedEvents: CapturedEvent[] = [];
+
+// --- Feature ---
+
+export const pubsubOrderFeature = defineFeature("pubsubOrders", (r) => {
+  r.entity("pubsub-order", orderEntity);
+
+  // Define the event shape once. The returned `.name` is the qualified
+  // name ("pubsub-orders:event:order-placed") — pass it to ctx.appendEvent.
+  const orderPlaced = r.defineEvent(
+    "order-placed",
+    z.object({ id: z.string(), customer: z.string(), product: z.string() }),
+    { piiFields: "none" },
+  );
+
+  const { executor: orderExecutor } = createEntityExecutor("pubsub-order", orderEntity);
+
+  r.writeHandler(
+    "order:place",
+    z.object({ customer: z.string().min(1), product: z.string().min(1) }),
+    async (event, ctx) => {
+      const result = await orderExecutor.create(event.payload, event.user, ctx.db);
+      if (result.isSuccess) {
+        // emitEvent runs inside the executor's TX and is typed against
+        // the orderPlaced event-def — a wrong payload shape is a compile
+        // error, not a runtime Zod reject. The event lands on the order's
+        // OWN stream (aggregateType "pubsub-order"), with the correct
+        // version bumped automatically. Schema validation still runs at
+        // append-time; a mismatch rolls back the whole write.
+        await emitEvent(ctx, orderPlaced, {
+          aggregateId: String(result.data.id),
+          aggregateType: "pubsub-order",
+          payload: {
+            id: String(result.data.id),
+            customer: event.payload.customer,
+            product: event.payload.product,
+          },
+        });
+      }
+      return result;
+    },
+    { access: { roles: ["Admin", "Customer"] } },
+  );
+
+  // Async consumer — Marten-style. Fires after commit, via the event-
+  // dispatcher. No `table` means this MSP is pure side-effect (no state
+  // persisted). Delivery is at-least-once and ordered per consumer.
+  r.multiStreamProjection({
+    name: "record-order-placed",
+    apply: {
+      [orderPlaced.name]: async (event) => {
+        const payload = typedPayload(event, orderPlaced);
+        capturedEvents.push({
+          type: event.type,
+          payload,
+          tenantId: event.tenantId,
+        });
+      },
+    },
+  });
+});
+```

package/agents/examples/crypto-shredding-hr.md

@@ -0,0 +1,314 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/crypto-shredding-hr. Do not edit. -->
+
+# crypto-shredding-hr
+
+Crypto-shredding: PII fields encrypted per subject key; forgetting the subject erases the key and every field it protected.
+
+## README
+
+# Crypto-shredding (mini HR)
+
+Make GDPR forget a key-erase instead of a data-hunt. Fields annotated as PII
+are encrypted under a per-subject key (DEK); forgetting the subject erases
+that key in the KMS — the ciphertext stays in rows and events but is
+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
+manager's comment dies with the employee's key, not the manager's.
+
+## What it shows
+
+- **`pii: true` on a field** — encrypted under the subject key of its own
+  row (`user:<row.id>`). At rest the column holds a
+  `kumiko-pii:v2:<subjectKey>:<ciphertext>` envelope; the API returns
+  plaintext as long as the key exists.
+- **`userOwned: { ownerField }`** — encrypted under the key of the user
+  another field points at. Erasing that user's key makes every row about
+  them unreadable, with no per-row cleanup hunt.
+- **Plain fields stay queryable** — `department` is not personal data, so it
+  remains plaintext, sortable and searchable.
+- **`lookupable: true` on an encrypted field** — the framework maintains an
+  HMAC blind-index column (`email_bidx`), so equality lookups (login, dedup
+  checks) keep working on ciphertext: the query compiler rewrites
+  `email = $1` to `(email = $1 OR email_bidx = hmac($1))`. Needs
+  `runProdApp({ blindIndexKey })` (a dedicated 32-byte key, NOT the KEK).
+  Sorting stays impossible by design — the boot validator rejects
+  `sortable` on subject-annotated fields, because sorting reads the
+  projection column and that stays ciphertext.
+- **`searchable: true` on an encrypted field** (#1610) — substring search
+  works: the search consumer decrypts into a derived Meilisearch index, while
+  events and projection keep the ciphertext. `search/purge-subject.ts` drops
+  those documents when the subject key is erased, so the derived index does
+  not outlive the forget. `sensitive: true` + `searchable` still throws —
+  those values may never be read back at all.
+
+  Encrypting a field is not a reason to make it unfindable. If a list needs
+  ordering over an encrypted name, the way out is a search-driven list rather
+  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
+  `[[erased]]` for every protected field while the stored ciphertext bytes
+  stay untouched.
+
+## Feature composition
+
+```
+hr → employee (displayName/email pii) + hr-comment (body userOwned)
+```
+
+Requires a KMS adapter: `runProdApp({ kms: createPgKmsAdapter(...) })` in
+production, `configurePiiSubjectKms(new InMemoryKmsAdapter())` in tests.
+Without one, fields are stored in plaintext and a boot warning is logged.
+The `crypto-shredding` bundled feature ships the operator `forget-subject`
+command; `user-data-rights` erases user keys automatically after the
+deletion grace period.
+
+## Flow
+
+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
+   `userOwned: { ownerField: "employeeId" }`.
+3. `kms.eraseKey({ kind: "user", userId })` — idempotent, tombstone stays
+   for the audit trail.
+4. Detail responses (list, too, for `employee`) now show `[[erased]]` for every field the key
+   protected; events and rows keep their original (unreadable) bytes.
+5. Lookups by email stop matching after the forget: the pipeline nulls the
+   blind index immediately (`nullBlindIndexesForSubject`), and every
+   projection rebuild recomputes it from the (now undecryptable) ciphertext
+   to `NULL`.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Crypto-Shredding Sample — Integration Test
+// Proves: PII ciphertext at rest + plaintext over the API, userOwned
+// cross-row encryption, and forget-as-key-erase ([[erased]] everywhere the
+// subject's key was used, events untouched).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient, fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  PII_CIPHERTEXT_PREFIX,
+  PII_ERASED_SENTINEL,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { buildEntityTable, nullBlindIndexesForSubject } from "@cosmicdrift/kumiko-framework/db";
+import type { SaveContext } 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 {
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+  resetTestTables,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { employeeEntity, hrCommentEntity, hrFeature } from "../feature";
+
+let stack: TestStack;
+let kms: InMemoryKmsAdapter;
+
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [hrFeature] });
+  await unsafeCreateEntityTable(stack.db, employeeEntity);
+  await unsafeCreateEntityTable(stack.db, hrCommentEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+beforeEach(async () => {
+  // Fresh adapter per test = fresh key universe. Rows from earlier tests
+  // would name subjects this adapter never minted (fail-loud KeyNotFound),
+  // so the tables reset alongside the KMS.
+  await resetTestTables(stack.db, ["read_hr_employees", "read_hr_comments"]);
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+  // Blind-index key: what runProdApp({ blindIndexKey }) wires in production.
+  configureBlindIndexKey(Buffer.alloc(32, 7).toString("base64"));
+});
+
+async function rawEmployeeRow(id: string): Promise<{ display_name: string; email: string }> {
+  const result = await asRawClient(stack.db).unsafe(
+    "SELECT display_name, email FROM read_hr_employees WHERE id = $1",
+    [id],
+  );
+  // biome-ignore lint/suspicious/noExplicitAny: raw sql result shape
+  const rows = ((result as any).rows ?? result) as Array<{ display_name: string; email: string }>;
+  const row = rows[0];
+  if (!row) throw new Error(`no employee row ${id}`);
+  return row;
+}
+
+async function createEmployee(): Promise<string> {
+  const created = await stack.http.writeOk<SaveContext>(
+    "hr:write:employee:create",
+    { displayName: "Grace Hopper", email: "grace@example.com", department: "Engineering" },
+    admin,
+  );
+  return String(created.id);
+}
+
+describe("crypto-shredding-hr", () => {
+  test("PII is ciphertext at rest, plaintext over the API", async () => {
+    const employeeId = await createEmployee();
+
+    const raw = await rawEmployeeRow(employeeId);
+    expect(raw.display_name).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${employeeId}:`);
+    expect(raw.email).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${employeeId}:`);
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "hr:query:employee:detail",
+      { id: employeeId },
+      admin,
+    );
+    expect(detail["displayName"]).toBe("Grace Hopper");
+    expect(detail["email"]).toBe("grace@example.com");
+    // Non-PII field stays plaintext at rest and readable.
+    expect(detail["department"]).toBe("Engineering");
+  });
+
+  test("userOwned comment is encrypted under the employee's key", async () => {
+    const employeeId = await createEmployee();
+
+    const comment = await stack.http.writeOk<SaveContext>(
+      "hr:write:hr-comment:create",
+      { employeeId, body: "was on sick leave in March", authorName: "Manager X" },
+      admin,
+    );
+
+    const result = await asRawClient(stack.db).unsafe(
+      "SELECT body FROM read_hr_comments WHERE id = $1",
+      [String(comment.id)],
+    );
+    // biome-ignore lint/suspicious/noExplicitAny: raw sql result shape
+    const rows = ((result as any).rows ?? result) as Array<{ body: string }>;
+    // The comment row's ciphertext names the EMPLOYEE as subject, not the row.
+    expect(rows[0]?.body).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${employeeId}:`);
+  });
+
+  test("forget: eraseKey renders [[erased]] for the employee AND comments about them", async () => {
+    const employeeId = await createEmployee();
+    await stack.http.writeOk<SaveContext>(
+      "hr:write:hr-comment:create",
+      { employeeId, body: "was on sick leave in March", authorName: "Manager X" },
+      admin,
+    );
+
+    // What user-data-rights does after the grace period — or a DPO via the
+    // crypto-shredding feature's forget-subject command.
+    await kms.eraseKey({ kind: "user", userId: employeeId });
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "hr:query:employee:detail",
+      { id: employeeId },
+      admin,
+    );
+    expect(detail["displayName"]).toBe(PII_ERASED_SENTINEL);
+    expect(detail["email"]).toBe(PII_ERASED_SENTINEL);
+    expect(detail["department"]).toBe("Engineering");
+
+    const list = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+      "hr:query:employee:list",
+      {},
+      admin,
+    );
+    const listed = list.rows.find((i) => String(i["id"]) === employeeId);
+    expect(listed?.["displayName"]).toBe(PII_ERASED_SENTINEL);
+
+    // The ciphertext itself is untouched — rows and events keep their bytes,
+    // they just can never be decrypted again.
+    const raw = await rawEmployeeRow(employeeId);
+    expect(raw.email).toStartWith(`${PII_CIPHERTEXT_PREFIX}user:${employeeId}:`);
+  });
+});
+
+describe("crypto-shredding-hr — blind-index lookups (#818)", () => {
+  const employeeTable = buildEntityTable("employee", employeeEntity);
+
+  test("equality lookup by email works on the encrypted column — until the key is erased", async () => {
+    const employeeId = await createEmployee();
+
+    // The email column holds ciphertext, yet an equality lookup — what a
+    // login or dedup check does — still finds the row: the query compiler
+    // rewrites `email = $1` to `(email = $1 OR email_bidx = hmac($1))`.
+    const hit = await fetchOne<Record<string, unknown>>(stack.db, employeeTable, {
+      email: "grace@example.com",
+    });
+    expect(String(hit?.["id"])).toBe(employeeId);
+
+    // Forget: erase the key AND null the blind index (user-data-rights does
+    // both automatically after the grace period).
+    await kms.eraseKey({ kind: "user", userId: employeeId });
+    await nullBlindIndexesForSubject(
+      stack.db,
+      new Map([["hr", hrFeature]]),
+      subjectIdToKey({ kind: "user", userId: employeeId }),
+    );
+
+    // The lookup value is gone with the key — no row matches anymore.
+    expect(await fetchOne(stack.db, employeeTable, { email: "grace@example.com" })).toBeUndefined();
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const employeeEntity = createEntity({
+  table: "read_hr_employees",
+  fields: {
+    displayName: createTextField({ required: true, personal: "self", find: "none" }),
+    email: createTextField({ required: true, format: "email", personal: "self", find: "exact" }),
+    department: createTextField({ personal: false, reason: "is_business_data", sortable: true }),
+  },
+  softDelete: true,
+});
+
+export const hrCommentEntity = createEntity({
+  table: "read_hr_comments",
+  fields: {
+    employeeId: createTextField({ personal: "ref", required: true }),
+    body: createTextField({ required: true, personal: { of: "employeeId" }, find: "none" }),
+    authorName: createTextField({ personal: { of: "id" }, find: "none" }),
+  },
+  softDelete: true,
+});
+
+const hrWrite = { access: { roles: ["Admin"] } } as const;
+const hrRead = { access: { roles: ["Admin"] } } as const;
+
+export const hrFeature = defineFeature("hr", (r) => {
+  r.crud("employee", employeeEntity, {
+    write: hrWrite,
+    read: hrRead,
+    verbs: { update: false, delete: false, restore: false },
+  });
+
+  r.crud("hr-comment", hrCommentEntity, {
+    write: hrWrite,
+    read: hrRead,
+    verbs: { update: false, delete: false, restore: false, list: false },
+  });
+});
+```