@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/event-sourcing.md

@@ -0,0 +1,1287 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/event-sourcing. Do not edit. -->
+
+# event-sourcing
+
+Production-pattern ES sample: r.defineEvent (versioned + migrations) + ctx.appendEvent + r.projection + r.multiStreamProjection + ctx.loadAggregate (asOf) + ctx.archiveStream + ctx.queryProjection.
+
+## README
+
+# Event Sourcing Showcase
+
+Production-pattern sample showing every Sprint-E Marten-gold-standard
+API in one feature. Serves as a reference for all the ES building
+blocks Kumiko provides.
+
+## What the sample shows
+
+| API | Purpose |
+|---|---|
+| `r.defineEvent(name, schema, { version, migrations })` | Event schema with version number + upcaster chain |
+| `ctx.appendEvent({ aggregateId, aggregateType, type, payload })` | Domain event on aggregate stream |
+| `r.projection(...)` | Single-stream read model, inline in the write TX |
+| `r.multiStreamProjection(...)` | Cross-aggregate read model, async via dispatcher |
+| `ctx.loadAggregate(id, { asOf })` | Live aggregation with point-in-time |
+| `ctx.archiveStream(id, { aggregateType })` | Archive a stream (Marten `ArchiveStream`) |
+| `ctx.queryProjection(name)` | Tenant-scoped read-model query |
+
+## Domain
+
+Invoices flow through `draft` → `approved` → `paid` → (optional)
+`archived`. Two read models:
+
+- **`invoice-detail`** (single-stream, inline): one row per invoice,
+  reacts to `created`, `approved`, `paid`.
+- **`customer-revenue`** (multi-stream, async): one row per customer,
+  sums up paid invoices.
+
+The `approved` event is at schema version 2 — v1 stored `amount` as a
+string, v2 uses `amountCents` as an integer. The migration shows how
+old events are transparently upcast on read.
+
+## Flow
+
+```
+HTTP POST /api/write { type: "showcase:write:invoice:create", ... }
+         ↓
+  writeHandler("invoice:create")
+         ↓ TX begin
+         invoiceExecutor.create(...)            ← auto event: showcaseInvoice.created
+         r.projection("invoice-detail")         ← inline, writes detail row
+         ↓ TX commit
+
+HTTP POST /api/write { type: "showcase:write:invoice:approve", ... }
+         ↓
+  writeHandler("invoice:approve")
+         ↓ TX begin
+         ctx.appendEvent({ type: "showcase:event:invoice-approved", ... })
+         r.projection("invoice-detail")         ← updates status = "approved"
+         ↓ TX commit
+         (async)
+         eventDispatcher.runOnce()
+         ↓
+         r.multiStreamProjection("customer-revenue")  ← skips (only on paid)
+```
+
+## Test
+
+```bash
+bun kumiko test integration samples/recipes/event-sourcing
+```
+
+Six integration tests pin everything at once:
+
+1. Walk-through `create → approve → pay` with the inline projection
+2. Async MSP accumulates across multiple paid invoices
+3. `asOf` returns the state before payment
+4. v1 event on disk reaches the reducer as v2 (upcaster)
+5. `archiveStream` hides events from `loadAggregate`; ops bypass via `{ includeArchived }`
+6. `queryProjection` automatically filters by `tenant_id`
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Event Sourcing Showcase — Integration Test
+//
+// Exercises every Sprint-E Marten gold-standard API end-to-end:
+//   - r.defineEvent with version + migrations (sync + async upcaster)
+//   - ctx.appendEvent onto the aggregate stream (incl. headers metadata)
+//   - r.projection (single-stream, inline)
+//   - r.multiStreamProjection (async)
+//   - ctx.loadAggregate with { asOf }
+//   - ctx.archiveStream
+//   - ctx.queryProjection
+//   - streamAllEventsByType (memory-bounded ops iteration)
+//   - getAllProjectionProgress (projection lag for ops dashboards)
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbTx } from "@cosmicdrift/kumiko-framework/db";
+import {
+  append,
+  loadAggregate as loadAggregateRaw,
+  makeUpcastCtx,
+  streamAllEventsByType,
+  upcastStoredEvent,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import { getAllProjectionProgress } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createTestUser,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  approverDirectoryTable,
+  invoiceDetailTable,
+  invoiceEntity,
+  invoiceFeature,
+} from "../feature";
+
+let stack: TestStack;
+const admin = createTestUser({ roles: ["Admin"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [invoiceFeature], systemHooks: [] });
+  await unsafeCreateEntityTable(stack.db, invoiceEntity, "showcase-invoice");
+  await unsafePushTables(stack.db, { read_showcase_approver_directory: approverDirectoryTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetEventStore(stack, [
+    "read_showcase_invoices",
+    "read_showcase_invoice_detail",
+    "read_showcase_customer_revenue",
+    "read_showcase_approver_directory",
+  ]);
+  // Reset Redis namespace too — invoice:pay declares a per-user
+  // rate limit, so leftover bucket state from a previous test would
+  // throttle the next test's pay-calls.
+  await stack.redis.flushNamespace();
+  await stack.eventDispatcher?.ensureRegistered();
+});
+
+describe("Event Sourcing Showcase", () => {
+  test("create → approve → pay: inline projection reflects each step", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "Acme" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id, amountCents: 2500, approvedBy: "cfo" },
+      admin,
+    );
+    await stack.http.writeOk("showcase:write:invoice:pay", { id, amountCents: 2500 }, admin);
+
+    const [row] = await selectMany(stack.db, invoiceDetailTable, { invoiceId: id });
+    expect(row).toMatchObject({
+      customer: "Acme",
+      status: "paid",
+      amountCents: 2500,
+    });
+  });
+
+  test("async MSP: customer-revenue accumulates across paid invoices", async () => {
+    const inv1 = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "Acme" },
+      admin,
+    );
+    const inv2 = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "Acme" },
+      admin,
+    );
+    const inv3 = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "Globex" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id: inv1.id, amountCents: 1000, approvedBy: "a" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:pay",
+      { id: inv1.id, amountCents: 1000 },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id: inv2.id, amountCents: 500, approvedBy: "a" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:pay",
+      { id: inv2.id, amountCents: 500 },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id: inv3.id, amountCents: 300, approvedBy: "a" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:pay",
+      { id: inv3.id, amountCents: 300 },
+      admin,
+    );
+
+    await stack.eventDispatcher?.runOnce();
+
+    const revenue = await stack.http.queryOk<
+      Array<{ customer: string; paidInvoices: number; totalCents: number }>
+    >("showcase:query:revenue:list", {}, admin);
+
+    const byCustomer = new Map(revenue.map((r) => [r.customer, r]));
+    expect(byCustomer.get("Acme")).toMatchObject({ paidInvoices: 2, totalCents: 1500 });
+    expect(byCustomer.get("Globex")).toMatchObject({ paidInvoices: 1, totalCents: 300 });
+  });
+
+  test("asOf point-in-time read: invoice state before the pay event", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "TimeTraveler" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id, amountCents: 900, approvedBy: "cfo" },
+      admin,
+    );
+    // Cutoff from DB event timestamp — host Date() drifts vs Postgres now()
+    // under Docker and excluded the approve event (fw#2425).
+    const beforePay = await loadAggregateRaw(stack.db, id, admin.tenantId);
+    expect(beforePay).toHaveLength(2);
+    const cutoff = beforePay.at(-1)!.createdAt;
+    await new Promise((r) => setTimeout(r, 10));
+    await stack.http.writeOk("showcase:write:invoice:pay", { id, amountCents: 900 }, admin);
+
+    const now = await stack.http.queryOk<{ status: string; paid: boolean }>(
+      "showcase:query:invoice:state",
+      { id },
+      admin,
+    );
+    expect(now.status).toBe("paid");
+    expect(now.paid).toBe(true);
+
+    const past = await stack.http.queryOk<{ status: string; paid: boolean }>(
+      "showcase:query:invoice:state",
+      { id, asOf: cutoff.toString() },
+      admin,
+    );
+    expect(past.status).toBe("approved");
+    expect(past.paid).toBe(false);
+  });
+
+  test("upcaster: v1 approved event on disk reaches the reducer as v2", async () => {
+    // Simulate a pre-migration event shape by appending directly at
+    // eventVersion=1. This is what stored v1 approval events look like
+    // on disk today — the upcaster walks them to v2 on read.
+    const invoiceId = "00000000-0000-4000-8000-00000000f001";
+    await stack.db.begin(async (tx: DbTx) => {
+      await insertOne(tx, invoiceDetailTable, {
+        invoiceId,
+        tenantId: admin.tenantId,
+        customer: "Legacy Co",
+        status: "draft",
+        amountCents: 0,
+      });
+      await append(tx, {
+        aggregateId: invoiceId,
+        aggregateType: "showcase-invoice",
+        tenantId: admin.tenantId,
+        expectedVersion: 0,
+        type: "showcase-invoice.created",
+        payload: { id: invoiceId, customer: "Legacy Co", status: "draft" },
+        metadata: { userId: admin.id },
+      });
+      await append(tx, {
+        aggregateId: invoiceId,
+        aggregateType: "showcase-invoice",
+        tenantId: admin.tenantId,
+        expectedVersion: 1,
+        type: "showcase:event:invoice-approved",
+        eventVersion: 1,
+        payload: { amount: "15.50", approvedBy: "legacy-cfo" },
+        metadata: { userId: admin.id },
+      });
+    });
+
+    const state = await stack.http.queryOk<{
+      status: string;
+      amountCents: number;
+      approvedBy: string | null;
+    }>("showcase:query:invoice:state", { id: invoiceId }, admin);
+
+    // v1 payload { amount: "15.50" } upcasts to v2 { amountCents: 1550 }
+    expect(state.status).toBe("approved");
+    expect(state.amountCents).toBe(1550);
+    expect(state.approvedBy).toBe("legacy-cfo");
+
+    // On-disk row is untouched — upcaster is read-time only.
+    const raw = await loadAggregateRaw(stack.db, invoiceId, admin.tenantId);
+    const rawApproved = raw.find((e) => e.type === "showcase:event:invoice-approved");
+    expect(rawApproved?.eventVersion).toBe(1);
+    expect(rawApproved?.payload).toEqual({ amount: "15.50", approvedBy: "legacy-cfo" });
+  });
+
+  test("archiveStream: loadAggregate returns empty after archive, ops bypass surfaces events", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "ArchivePal" },
+      admin,
+    );
+    await stack.http.writeOk("showcase:write:invoice:archive", { id }, admin);
+
+    const state = await stack.http.queryOk<{ status: string }>(
+      "showcase:query:invoice:state",
+      { id },
+      admin,
+    );
+    expect(state.status).toBe("missing"); // loadAggregate returned [] → reducer starts clean
+
+    const raw = await loadAggregateRaw(stack.db, id, admin.tenantId, {
+      includeArchived: true,
+    });
+    expect(raw.length).toBeGreaterThan(0); // events are still on disk for ops
+  });
+
+  test("snapshot: fast-state uses the snapshot + upcaster-wrapped delta replay", async () => {
+    // Seed a full invoice lifecycle so there are three events on the
+    // stream (created, approved, paid).
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "Snapco" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id, amountCents: 3300, approvedBy: "cfo" },
+      admin,
+    );
+    await stack.http.writeOk("showcase:write:invoice:pay", { id, amountCents: 3300 }, admin);
+
+    // Without a snapshot: fast-state still returns the correct state
+    // (falls back to full replay, snapshotHit=false).
+    const beforeSnapshot = await stack.http.queryOk<{
+      state: { status: string; amountCents: number };
+      version: number;
+      snapshotHit: boolean;
+    }>("showcase:query:invoice:fast-state", { id }, admin);
+    expect(beforeSnapshot.snapshotHit).toBe(false);
+    expect(beforeSnapshot.state.status).toBe("paid");
+    expect(beforeSnapshot.state.amountCents).toBe(3300);
+
+    // Take a snapshot after the pay event. ctx.snapshotAggregate writes
+    // kumiko_snapshots with the committed state + version.
+    const snapResult = await stack.http.writeOk<{ id: string; snapshotVersion: number }>(
+      "showcase:write:invoice:take-snapshot",
+      { id },
+      admin,
+    );
+    expect(snapResult.snapshotVersion).toBe(3);
+
+    // After the snapshot: fast-state sees the cache (snapshotHit=true) and
+    // no delta events beyond it. Same final state.
+    const afterSnapshot = await stack.http.queryOk<{
+      state: { status: string; amountCents: number };
+      version: number;
+      snapshotHit: boolean;
+    }>("showcase:query:invoice:fast-state", { id }, admin);
+    expect(afterSnapshot.snapshotHit).toBe(true);
+    expect(afterSnapshot.state.status).toBe("paid");
+    expect(afterSnapshot.state.amountCents).toBe(3300);
+  });
+
+  test("snapshot: upcaster runs on delta events past the snapshot", async () => {
+    // Seed only v1-shaped events directly to prove upcasting walks delta.
+    const invoiceId = "00000000-0000-4000-8000-00000000f002";
+    await stack.db.begin(async (tx: DbTx) => {
+      await insertOne(tx, invoiceDetailTable, {
+        invoiceId,
+        tenantId: admin.tenantId,
+        customer: "Upcast Co",
+        status: "draft",
+        amountCents: 0,
+      });
+      await append(tx, {
+        aggregateId: invoiceId,
+        aggregateType: "showcase-invoice",
+        tenantId: admin.tenantId,
+        expectedVersion: 0,
+        type: "showcase-invoice.created",
+        payload: { id: invoiceId, customer: "Upcast Co", status: "draft" },
+        metadata: { userId: admin.id },
+      });
+    });
+
+    // Snapshot the "just-created" state at v1 — before any v1-shaped
+    // approval event lands on the stream.
+    await stack.http.writeOk("showcase:write:invoice:take-snapshot", { id: invoiceId }, admin);
+
+    // Now append a v1-shape approval event (raw) — this becomes a delta
+    // past the snapshot. fast-state must upcast it before the reducer.
+    await stack.db.begin(async (tx: DbTx) => {
+      await append(tx, {
+        aggregateId: invoiceId,
+        aggregateType: "showcase-invoice",
+        tenantId: admin.tenantId,
+        expectedVersion: 1,
+        type: "showcase:event:invoice-approved",
+        eventVersion: 1,
+        payload: { amount: "27.50", approvedBy: "legacy-cfo" },
+        metadata: { userId: admin.id },
+      });
+    });
+
+    const state = await stack.http.queryOk<{
+      state: { status: string; amountCents: number; approvedBy: string | null };
+      snapshotHit: boolean;
+    }>("showcase:query:invoice:fast-state", { id: invoiceId }, admin);
+
+    expect(state.snapshotHit).toBe(true);
+    expect(state.state.status).toBe("approved");
+    // v1 { amount: "27.50" } upcasted → v2 { amountCents: 2750 }
+    expect(state.state.amountCents).toBe(2750);
+    expect(state.state.approvedBy).toBe("legacy-cfo");
+  });
+
+  test("tenant isolation: queryProjection auto-filters by tenant_id", async () => {
+    const otherAdmin = createTestUser({
+      id: 99,
+      roles: ["Admin"],
+      tenantId: "00000000-0000-4000-8000-000000000042",
+    });
+
+    const mine = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "Mine" },
+      admin,
+    );
+    const theirs = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "Theirs" },
+      otherAdmin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id: mine.id, amountCents: 100, approvedBy: "a" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:pay",
+      { id: mine.id, amountCents: 100 },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id: theirs.id, amountCents: 200, approvedBy: "b" },
+      otherAdmin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:pay",
+      { id: theirs.id, amountCents: 200 },
+      otherAdmin,
+    );
+    await stack.eventDispatcher?.runOnce();
+
+    const adminView = await stack.http.queryOk<Array<{ customer: string; totalCents: number }>>(
+      "showcase:query:revenue:list",
+      {},
+      admin,
+    );
+    expect(adminView.map((r) => r.customer)).toEqual(["Mine"]);
+    expect(adminView[0]?.totalCents).toBe(100);
+
+    const otherView = await stack.http.queryOk<Array<{ customer: string; totalCents: number }>>(
+      "showcase:query:revenue:list",
+      {},
+      otherAdmin,
+    );
+    expect(otherView.map((r) => r.customer)).toEqual(["Theirs"]);
+    expect(otherView[0]?.totalCents).toBe(200);
+  });
+
+  test("ctx.appendEvent with headers: Marten free key/value metadata lands in stored event", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "MetaCo" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id, amountCents: 700, approvedBy: "cfo", geoRegion: "EU", abTestBucket: "B" },
+      admin,
+    );
+
+    const events = await loadAggregateRaw(stack.db, id, admin.tenantId);
+    const approved = events.find((e) => e.type === "showcase:event:invoice-approved");
+    expect(approved?.metadata.headers).toEqual({ geoRegion: "EU", abTestBucket: "B" });
+
+    // Headers stay opt-in: omitting them keeps the field absent (no empty
+    // object surface). Verifies we don't pollute every event with a {}.
+    const { id: bareId } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "BareCo" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id: bareId, amountCents: 100, approvedBy: "cfo" },
+      admin,
+    );
+    const bareEvents = await loadAggregateRaw(stack.db, bareId, admin.tenantId);
+    const bareApproved = bareEvents.find((e) => e.type === "showcase:event:invoice-approved");
+    expect(bareApproved?.metadata.headers).toBeUndefined();
+  });
+
+  test("async upcaster: invoice-acknowledged v1 enriches via directory DB lookup at read time", async () => {
+    // Seed the directory so the async upcaster can find a name.
+    await insertOne(stack.db, approverDirectoryTable, {
+      approverId: "u-42",
+      displayName: "Quincy Acknowledger",
+    });
+
+    // Append a v1 acknowledged event directly to simulate a pre-migration
+    // payload on disk. ctx.appendEvent always writes the current version,
+    // so the only way to test the read-time upcaster is to write the older
+    // shape via the raw event-store.
+    const invoiceId = "00000000-0000-4000-8000-00000000ac01";
+    await stack.db.begin(async (tx: DbTx) => {
+      await insertOne(tx, invoiceDetailTable, {
+        invoiceId,
+        tenantId: admin.tenantId,
+        customer: "AckCo",
+        status: "draft",
+        amountCents: 0,
+      });
+      await append(tx, {
+        aggregateId: invoiceId,
+        aggregateType: "showcase-invoice",
+        tenantId: admin.tenantId,
+        expectedVersion: 0,
+        type: "showcase-invoice.created",
+        payload: { id: invoiceId, customer: "AckCo", status: "draft" },
+        metadata: { userId: admin.id },
+      });
+      await append(tx, {
+        aggregateId: invoiceId,
+        aggregateType: "showcase-invoice",
+        tenantId: admin.tenantId,
+        expectedVersion: 1,
+        type: "showcase:event:invoice-acknowledged",
+        eventVersion: 1,
+        payload: { approverId: "u-42" },
+        metadata: { userId: admin.id },
+      });
+    });
+
+    // Raw on-disk row keeps the v1 shape — upcasters never rewrite history.
+    const rawEvents = await loadAggregateRaw(stack.db, invoiceId, admin.tenantId);
+    const rawAck = rawEvents.find((e) => e.type === "showcase:event:invoice-acknowledged");
+    expect(rawAck?.eventVersion).toBe(1);
+    expect(rawAck?.payload).toEqual({ approverId: "u-42" });
+
+    // The actual proof: run the v1 row through the upcaster chain and
+    // verify the async DB lookup populated approverDisplayName. This is
+    // exactly what dispatcher.loadAggregate / projection-rebuild do
+    // internally — calling the primitive directly here lets the sample
+    // assert the read-path enrichment without an extra wrapper handler.
+    if (!rawAck) throw new Error("seed failed");
+    const enriched = await upcastStoredEvent(
+      rawAck,
+      stack.registry.getEventUpcasters(),
+      makeUpcastCtx(stack.db, admin.tenantId),
+    );
+    expect(enriched.eventVersion).toBe(2);
+    expect(enriched.payload).toMatchObject({
+      approverId: "u-42",
+      approverDisplayName: "Quincy Acknowledger",
+    });
+
+    // Sanity check the ctx.appendEvent path too: it writes the current
+    // shape directly (handler resolved displayName synchronously), so
+    // the upcaster is a no-op on these events.
+    const { id: liveId } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "AckCo2" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:acknowledge",
+      { id: liveId, approverId: "u-42" },
+      admin,
+    );
+    const liveEvents = await loadAggregateRaw(stack.db, liveId, admin.tenantId);
+    const liveAck = liveEvents.find((e) => e.type === "showcase:event:invoice-acknowledged");
+    expect(liveAck?.eventVersion).toBe(2);
+    expect(liveAck?.payload).toMatchObject({
+      approverId: "u-42",
+      approverDisplayName: "Quincy Acknowledger",
+    });
+  });
+
+  test("streamAllEventsByType: ops iteration walks all events without buffering", async () => {
+    // Seed 25 invoices with create + approve = 50 events across the
+    // showcaseInvoice aggregate type.
+    for (let i = 0; i < 25; i++) {
+      const { id } = await stack.http.writeOk<{ id: string }>(
+        "showcase:write:invoice:create",
+        { customer: `C${i}` },
+        admin,
+      );
+      await stack.http.writeOk(
+        "showcase:write:invoice:approve",
+        { id, amountCents: 100 + i, approvedBy: "cfo" },
+        admin,
+      );
+    }
+
+    // batchSize=10 forces 5 batches (10+10+10+10+10) — proves cursor
+    // advance across multiple round-trips, not just a single load.
+    let count = 0;
+    const types = new Set<string>();
+    for await (const evt of streamAllEventsByType(stack.db, "showcase-invoice", 10)) {
+      count++;
+      types.add(evt.type);
+    }
+    expect(count).toBe(50);
+    expect([...types].sort()).toEqual([
+      "showcase-invoice.created",
+      "showcase:event:invoice-approved",
+    ]);
+  });
+
+  test("getAllProjectionProgress: HWM advances with the event log", async () => {
+    // Inline projections (r.projection) don't track a cursor in
+    // kumiko_projections — the row only gets written by ops-rebuild.
+    // So getAllProjectionProgress mainly surfaces HWM + the cursor
+    // remembered from the last rebuild. Useful as a "is anyone behind?"
+    // dashboard once you actually run rebuilds. This test pins the HWM
+    // advance and the never-rebuilt baseline so a regression in either
+    // surfaces cleanly.
+    const before = await getAllProjectionProgress(stack.db, stack.registry);
+    const detail = before.find((p) => p.name === "showcase:projection:invoice-detail");
+    expect(detail?.status).toBe("never-rebuilt");
+    expect(detail?.highWaterMark).toBe(0n);
+    expect(detail?.lastProcessedEventId).toBe(0n);
+    expect(detail?.lag).toBe(0n);
+
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "LagCheck" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id, amountCents: 200, approvedBy: "cfo" },
+      admin,
+    );
+
+    const after = await getAllProjectionProgress(stack.db, stack.registry);
+    const detailAfter = after.find((p) => p.name === "showcase:projection:invoice-detail");
+    expect(detailAfter?.highWaterMark).toBe(2n);
+    expect(detailAfter?.lastProcessedEventId).toBe(0n);
+    expect(detailAfter?.lag).toBe(2n);
+  });
+
+  test("AllConsumerProgress: MSP cursor catches up to HWM after dispatcher run", async () => {
+    const { getAllConsumerProgress } = await import("@cosmicdrift/kumiko-framework/pipeline");
+    const consumerName = "showcase:projection:customer-revenue";
+
+    const baseline = await getAllConsumerProgress(stack.db, [consumerName]);
+    expect(baseline[0]?.lag).toBe(0n);
+
+    // Drive a full create→approve→pay → 1 event log entry per write,
+    // plus the inline projection writes = 3 events on the stream.
+    // The MSP only reacts to invoice-paid, but its cursor still has
+    // to catch up to the latest events.id to be "current".
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "ConsumerLag" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id, amountCents: 400, approvedBy: "cfo" },
+      admin,
+    );
+    await stack.http.writeOk("showcase:write:invoice:pay", { id, amountCents: 400 }, admin);
+
+    // Before runOnce: events on the log, MSP cursor untouched → lag > 0.
+    const lagged = await getAllConsumerProgress(stack.db, [consumerName]);
+    expect(lagged[0]?.highWaterMark).toBeGreaterThan(0n);
+    expect(lagged[0]?.lag).toBe(lagged[0]?.highWaterMark);
+
+    // runOnce drains the dispatcher → cursor advances to HWM → lag = 0.
+    await stack.eventDispatcher?.runOnce();
+    const caughtUp = await getAllConsumerProgress(stack.db, [consumerName]);
+    expect(caughtUp[0]?.lag).toBe(0n);
+    expect(caughtUp[0]?.lastProcessedEventId).toBe(caughtUp[0]?.highWaterMark);
+  });
+
+  test("ctx.signal: long-running query handler honors abort from HTTP client", async () => {
+    // 50 chunks × 10ms = ~500ms total. Abort after ~80ms — handler
+    // should observe signal.aborted via throwIfAborted() inside the
+    // loop, throw, and the response surfaces an error. Without the
+    // signal honour, the handler would run all 500ms regardless.
+    const token = await stack.jwt.sign(admin);
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 80);
+
+    const start = Date.now();
+    let outcome: "completed" | "aborted" | "error-response" = "completed";
+    try {
+      const res = await stack.app.request(
+        new Request("http://test.local/api/query", {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+          },
+          body: JSON.stringify({
+            type: "showcase:query:ops:slow-export",
+            payload: { chunks: 50 },
+          }),
+          signal: controller.signal,
+        }),
+      );
+      // If the server completed before abort landed, status is 200.
+      // If the handler observed abort and threw, the dispatcher wraps
+      // it as an internal error response.
+      if (res.status >= 400) outcome = "error-response";
+    } catch (e) {
+      // Outer fetch may surface AbortError when abort is observed at
+      // the transport layer.
+      if (e instanceof Error && e.name === "AbortError") outcome = "aborted";
+      else throw e;
+    }
+    const elapsed = Date.now() - start;
+
+    // Either way, we should be done well before the full 500ms — proves
+    // the handler did NOT run all 50 chunks. A handler ignoring signal
+    // would always take ≥500ms.
+    expect(elapsed).toBeLessThan(400);
+    expect(outcome).not.toBe("completed");
+  });
+
+  test("rate limit: invoice:pay caps at 5 per user per window, 6th returns 429", async () => {
+    // The handler declares `rateLimit: { per: "user", limit: 5, windowSeconds: 60 }`.
+    // Five calls within the window go through; the sixth surfaces a
+    // 429-shaped error response without running the handler body
+    // (and therefore without touching the event store).
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "RateLimited" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "showcase:write:invoice:approve",
+      { id, amountCents: 100, approvedBy: "cfo" },
+      admin,
+    );
+
+    for (let i = 0; i < 5; i++) {
+      await stack.http.writeOk("showcase:write:invoice:pay", { id, amountCents: 100 }, admin);
+    }
+
+    // 6th call hits the cap. queryOk/writeOk would throw on a non-2xx
+    // response, hiding the wire body — go through `write` directly so
+    // we can assert the 429 + RateLimitError shape.
+    const blocked = await stack.http.write(
+      "showcase:write:invoice:pay",
+      { id, amountCents: 100 },
+      admin,
+    );
+    expect(blocked.status).toBe(429);
+    const body = (await blocked.json()) as {
+      error: { code: string; details?: { bucket?: string; limit?: number } };
+    };
+    expect(body.error.code).toBe("rate_limited");
+    expect(body.error.details?.limit).toBe(5);
+    expect(body.error.details?.bucket).toBe("user");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Event Sourcing Showcase
+//
+// Production-pattern sample that exercises every Sprint-E Marten gold-
+// standard API in one place:
+//
+//   - r.defineEvent with { version, migrations } — evolving event shapes +
+//     upcast older payloads on read (declarative + sync/async transforms)
+//   - ctx.appendEvent — write domain events onto the aggregate stream
+//   - ctx.appendEvent with headers — Marten free key/value metadata
+//   - r.projection — single-stream read model (inline in the write TX)
+//   - r.multiStreamProjection — cross-aggregate async read model
+//   - ctx.loadAggregate with { asOf } — point-in-time aggregate state
+//   - ctx.archiveStream / ctx.restoreStream — Marten ArchiveStream
+//   - ctx.queryProjection — tenant-scoped read of a projection table
+//   - ctx.snapshotAggregate + ctx.loadAggregateWithSnapshot — perf path
+//     for aggregates with long event tails (O(1) vs O(N) reduce), incl.
+//     the auto-snapshot policy ({ snapshotEvery, snapshotVersion })
+//   - streamAllEventsByType — memory-bounded iteration for ops/export jobs
+//   - getAllProjectionProgress — projection lag for ops dashboards
+
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  defineProjectionQueryHandler,
+  typedPayload,
+} from "@app/define";
+import {
+  fetchOne,
+  incrementCounter,
+  insertOne,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  integer,
+  table,
+  text,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+import { z } from "zod";
+
+// --- Reducer: shared by live + snapshot-aware query handlers ---
+
+type InvoiceState = {
+  id: string | null;
+  customer: string | null;
+  status: string;
+  amountCents: number;
+  approvedBy: string | null;
+  paid: boolean;
+};
+
+// Record<string,unknown>-compatible alias — the snapshot reducer generic
+// constrains state to that shape, so we hand it this view instead of the
+// narrower InvoiceState to satisfy the bound without changing semantics.
+type InvoiceStateRecord = Record<string, unknown> & InvoiceState;
+
+const initialInvoiceState: InvoiceState = {
+  id: null,
+  customer: null,
+  status: "missing",
+  amountCents: 0,
+  approvedBy: null,
+  paid: false,
+};
+
+function reduceInvoice(state: InvoiceState, evt: { type: string; payload: unknown }): void {
+  if (evt.type === "showcase-invoice.created") {
+    const p = evt.payload as { id: string; customer: string; status: string };
+    state.id = p.id;
+    state.customer = p.customer;
+    state.status = p.status;
+  } else if (evt.type.endsWith(":event:invoice-approved")) {
+    const p = evt.payload as { amountCents: number; approvedBy: string };
+    state.status = "approved";
+    state.amountCents = p.amountCents;
+    state.approvedBy = p.approvedBy;
+  } else if (evt.type.endsWith(":event:invoice-paid")) {
+    state.status = "paid";
+    state.paid = true;
+  }
+}
+
+// --- Aggregate entity: invoice, stored as events only ---
+
+export const invoiceEntity = createEntity({
+  table: "read_showcase_invoices",
+  fields: {
+    customer: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    status: createTextField({ personal: false, reason: "is_business_data", required: true }), // "draft" | "approved" | "paid" | "closed"
+  },
+});
+
+const invoiceTable = buildEntityTable("showcase-invoice", invoiceEntity);
+
+// --- Projection 1: per-invoice detail (single-stream, inline) ---
+
+export const invoiceDetailTable = table("read_showcase_invoice_detail", {
+  invoiceId: uuid("invoice_id").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  customer: text("customer").notNull(),
+  status: text("status").notNull(),
+  amountCents: integer("amount_cents").notNull().default(0),
+});
+
+// --- Projection 2: per-customer revenue (multi-stream, async) ---
+
+export const customerRevenueTable = table("read_showcase_customer_revenue", {
+  customer: text("customer").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  paidInvoices: integer("paid_invoices").notNull().default(0),
+  totalCents: integer("total_cents").notNull().default(0),
+});
+
+// --- Reference data: approver display-name directory ---
+// The async upcaster (invoice-acknowledged v1 → v2) reads from this table
+// to enrich legacy events with a human-readable name. In production this
+// would be a domain-owned read model; here it's a flat lookup table.
+export const approverDirectoryTable = table("read_showcase_approver_directory", {
+  approverId: text("approver_id").primaryKey(),
+  displayName: text("display_name").notNull(),
+});
+
+// --- Feature ---
+
+export const invoiceFeature = defineFeature("showcase", (r) => {
+  r.entity("showcase-invoice", invoiceEntity);
+
+  // Two domain events. "approved" is versioned — v1 stored `amount` as
+  // string, v2 uses `amountCents` integer. The DECLARATIVE migration form
+  // covers rename/default/map without an imperative function; the chain
+  // walks the upcast on read.
+  const approved = r.defineEvent(
+    "invoice-approved",
+    z.object({ amountCents: z.number().int(), approvedBy: z.string() }),
+    {
+      piiFields: "none",
+      version: 2,
+      migrations: [
+        {
+          fromVersion: 1,
+          toVersion: 2,
+          transform: {
+            rename: { amount: "amountCents" },
+            map: { amountCents: (v) => Math.round(Number.parseFloat(String(v)) * 100) },
+          },
+        },
+      ],
+    },
+  );
+
+  const paid = r.defineEvent("invoice-paid", z.object({ amountCents: z.number().int() }), {
+    piiFields: "none",
+  });
+
+  // Acknowledged event with an ASYNC upcaster: v1 had only the approverId,
+  // v2 carries the human-readable display name too. The migration looks the
+  // name up from the directory table at read time. This is Marten's
+  // AsyncOnlyEventUpcaster pattern — DB enrichment without rewriting the
+  // event log.
+  const acknowledged = r.defineEvent(
+    "invoice-acknowledged",
+    z.object({ approverId: z.string(), approverDisplayName: z.string() }),
+    {
+      piiFields: { approverDisplayName: { subjectField: "approverId" } },
+      version: 2,
+      migrations: [
+        {
+          fromVersion: 1,
+          toVersion: 2,
+          transform: async (payload, ctx) => {
+            const p = payload as { approverId: string };
+            const row = await fetchOne<{ displayName: string }>(ctx.db, approverDirectoryTable, {
+              approverId: p.approverId,
+            });
+            return {
+              approverId: p.approverId,
+              approverDisplayName: row?.displayName ?? `unknown:${p.approverId}`,
+            };
+          },
+        },
+      ],
+    },
+  );
+
+  // Single-stream projection: one row per invoice, reacts to the auto
+  // CRUD event + both domain events. Runs INLINE in the write TX.
+  r.projection({
+    name: "invoice-detail",
+    source: "showcase-invoice",
+    table: invoiceDetailTable,
+    apply: {
+      "showcase-invoice.created": async (event, tx) => {
+        const p = event.payload as { customer: string; status: string };
+        await insertOne(tx, invoiceDetailTable, {
+          invoiceId: event.aggregateId,
+          tenantId: event.tenantId,
+          customer: p.customer,
+          status: p.status,
+          amountCents: 0,
+        });
+      },
+      [approved.name]: async (event, tx) => {
+        const p = typedPayload(event, approved);
+        await updateMany(
+          tx,
+          invoiceDetailTable,
+          { status: "approved", amountCents: p.amountCents },
+          { invoiceId: event.aggregateId },
+        );
+      },
+      [paid.name]: async (event, tx) => {
+        await updateMany(
+          tx,
+          invoiceDetailTable,
+          { status: "paid" },
+          { invoiceId: event.aggregateId },
+        );
+      },
+    },
+  });
+
+  // Multi-stream projection: one row per customer. Fires ASYNC via the
+  // event-dispatcher (runOnce in tests, NOTIFY/LISTEN in production).
+  r.multiStreamProjection({
+    name: "customer-revenue",
+    table: customerRevenueTable,
+    apply: {
+      [paid.name]: async (event, tx) => {
+        // Resolve the customer: pull it from the invoice-detail projection
+        // that the inline projection just populated. Cross-projection reads
+        // are fine inside apply() — we're at the read model layer.
+        const detail = await fetchOne<{ customer: string }>(tx, invoiceDetailTable, {
+          invoiceId: event.aggregateId,
+        });
+        if (!detail) return;
+        const p = typedPayload(event, paid);
+        await incrementCounter(
+          tx,
+          customerRevenueTable,
+          {
+            customer: detail.customer,
+            tenantId: event.tenantId,
+            paidInvoices: 1,
+            totalCents: p.amountCents,
+          },
+          { paidInvoices: 1, totalCents: p.amountCents },
+          { conflictKeys: ["customer"] },
+        );
+      },
+    },
+  });
+
+  const invoiceExecutor = createEventStoreExecutor(invoiceTable, invoiceEntity, {
+    entityName: "showcase-invoice",
+  });
+
+  // --- Write handlers ---
+
+  r.writeHandler(
+    "invoice:create",
+    z.object({ customer: z.string() }),
+    async (event, ctx) =>
+      invoiceExecutor.create(
+        { customer: event.payload.customer, status: "draft" },
+        event.user,
+        ctx.db,
+      ),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "invoice:approve",
+    z.object({
+      id: z.uuid(),
+      amountCents: z.number().int(),
+      approvedBy: z.string(),
+      // Optional ops metadata that the caller wants threaded into the
+      // event for later filtering/auditing without bloating the payload.
+      geoRegion: z.string().optional(),
+      abTestBucket: z.string().optional(),
+    }),
+    async (event, ctx) => {
+      const headers: Record<string, string> = {};
+      if (event.payload.geoRegion) headers["geoRegion"] = event.payload.geoRegion;
+      if (event.payload.abTestBucket) headers["abTestBucket"] = event.payload.abTestBucket;
+      await ctx.appendEvent({
+        aggregateId: event.payload.id,
+        aggregateType: "showcase-invoice",
+        type: approved.name,
+        payload: { amountCents: event.payload.amountCents, approvedBy: event.payload.approvedBy },
+        ...(Object.keys(headers).length > 0 ? { headers } : {}),
+      });
+      return { isSuccess: true as const, data: { id: event.payload.id } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "invoice:acknowledge",
+    z.object({ id: z.uuid(), approverId: z.string() }),
+    async (event, ctx) => {
+      const row = await fetchOne<{ displayName: string }>(ctx.db, approverDirectoryTable, {
+        approverId: event.payload.approverId,
+      });
+      const approverDisplayName: string = row?.displayName ?? `unknown:${event.payload.approverId}`;
+      await ctx.appendEvent({
+        aggregateId: event.payload.id,
+        aggregateType: "showcase-invoice",
+        type: acknowledged.name,
+        payload: { approverId: event.payload.approverId, approverDisplayName },
+      });
+      return { isSuccess: true as const, data: { id: event.payload.id } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "invoice:pay",
+    z.object({ id: z.uuid(), amountCents: z.number().int() }),
+    async (event, ctx) => {
+      await ctx.appendEvent({
+        aggregateId: event.payload.id,
+        aggregateType: "showcase-invoice",
+        type: paid.name,
+        payload: { amountCents: event.payload.amountCents },
+      });
+      return { isSuccess: true as const, data: { id: event.payload.id } };
+    },
+    {
+      access: { roles: ["Admin"] },
+      // Per-user cap: a single admin shouldn't fire more than 5 pay
+      // operations per minute. Real production caps would be per
+      // tenant + handler ("tenant+handler") to keep one admin from
+      // monopolising the tenant's quota — kept simple here for the
+      // sample. Demonstrates the fourth dispatcher gate (rate-limit
+      // → access → validation → handler).
+      rateLimit: { per: "user", limit: 5, windowSeconds: 60 },
+    },
+  );
+
+  r.writeHandler(
+    "invoice:archive",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => {
+      await ctx.archiveStream(event.payload.id, { aggregateType: "showcase-invoice" });
+      return { isSuccess: true as const, data: { id: event.payload.id } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Persist a snapshot of the current state. In practice, features schedule
+  // this from a lifecycle hook (every N events, every M minutes) — here it's
+  // an explicit write-handler so the integration test can drive it.
+  r.writeHandler(
+    "invoice:take-snapshot",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => {
+      // Rebuild the state from the current stream so the snapshot reflects
+      // the committed event log, not an in-memory guess. Use the upcaster-
+      // aware ctx.loadAggregate to stay consistent with read-time semantics.
+      const events = await ctx.loadAggregate(event.payload.id);
+      const state: InvoiceState = { ...initialInvoiceState };
+      for (const evt of events) {
+        reduceInvoice(state, evt);
+      }
+      const version = events.length > 0 ? (events[events.length - 1]?.version ?? 0) : 0;
+      await ctx.snapshotAggregate({
+        aggregateId: event.payload.id,
+        aggregateType: "showcase-invoice",
+        version,
+        state: state as unknown as Record<string, unknown>,
+      });
+      return { isSuccess: true as const, data: { id: event.payload.id, snapshotVersion: version } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // --- Query handlers ---
+
+  // Live aggregation via ctx.loadAggregate — reduces events into a state
+  // snapshot. Supports asOf for point-in-time reads.
+  r.queryHandler(
+    "invoice:state",
+    z.object({ id: z.uuid(), asOf: z.iso.datetime().optional() }),
+    async (query, ctx) => {
+      const events = await ctx.loadAggregate(query.payload.id, {
+        ...(query.payload.asOf ? { asOf: Temporal.Instant.from(query.payload.asOf) } : {}),
+      });
+      const state: InvoiceState = { ...initialInvoiceState };
+      for (const evt of events) {
+        reduceInvoice(state, evt);
+      }
+      return state;
+    },
+    {
+      access: {
+        openToAll: {
+          reason:
+            "demo recipe: any signed-in user may read the event-sourced invoice state; " +
+            "there is no per-user invoice ownership in this sample",
+        },
+      },
+    },
+  );
+
+  // Snapshot-aware fast path. Uses the latest snapshot if available and
+  // only replays delta events past it. Identical state shape to
+  // invoice:state — the two are interchangeable modulo the perf profile.
+  r.queryHandler(
+    "invoice:fast-state",
+    z.object({ id: z.uuid() }),
+    async (query, ctx) => {
+      const result = await ctx.loadAggregateWithSnapshot<InvoiceStateRecord>(
+        query.payload.id,
+        (state, evt) => {
+          const next: InvoiceStateRecord = { ...state };
+          reduceInvoice(next as unknown as InvoiceState, evt);
+          return next;
+        },
+        { ...initialInvoiceState } as InvoiceStateRecord,
+        // Auto-snapshot policy: once 100+ delta events pile up past the last
+        // snapshot, the read path persists a fresh one (best-effort). Bump
+        // snapshotVersion whenever the reducer's state SHAPE changes — a
+        // stale-shape snapshot is then ignored and rebuilt from the log.
+        { snapshotEvery: 100, snapshotVersion: 1 },
+      );
+      return {
+        state: result.state,
+        version: result.version,
+        snapshotHit: result.snapshotHit,
+      };
+    },
+    {
+      access: {
+        openToAll: {
+          reason:
+            "demo recipe: any signed-in user may read the snapshot-accelerated invoice " +
+            "state; there is no per-user invoice ownership in this sample",
+        },
+      },
+    },
+  );
+
+  // Read-model query via ctx.queryProjection — auto-tenant-scoped. The
+  // helper collapses the zero-argument "return this projection" pattern
+  // into a single call; returns { rows } so the response shape stays
+  // consistent with other list handlers.
+  r.queryHandler(
+    defineProjectionQueryHandler("revenue:list", "showcase:projection:customer-revenue", {
+      access: {
+        openToAll: {
+          reason:
+            "demo recipe: any signed-in user may read the customer-revenue projection; " +
+            "there is no per-user restriction in this sample",
+        },
+      },
+    }),
+  );
+
+  // Slow synthetic export — demonstrates ctx.signal honouring inside a
+  // long-running handler loop. Real-world equivalents: PDF batch export,
+  // bulk CSV download, multi-stream audit walk. Mobile clients that
+  // navigate away mid-export should NOT keep the server busy producing
+  // bytes nobody will read. The handler checks ctx.signal at every
+  // iteration; on abort, throws and the dispatcher returns an error to
+  // the (already-disconnected) client.
+  r.queryHandler(
+    "ops:slow-export",
+    z.object({ chunks: z.number().int().min(1).max(1000) }),
+    async (query, ctx) => {
+      const accumulated: number[] = [];
+      for (let i = 0; i < query.payload.chunks; i++) {
+        ctx.signal?.throwIfAborted();
+        // Fake "work per chunk". Realistic handler would assemble a row,
+        // hit a remote service, etc.
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        accumulated.push(i);
+      }
+      return { processed: accumulated.length };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+```