@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/agents/examples/lifecycle-hooks.md

@@ -35,6 +35,10 @@ back.
 - **`r.hook({ type: "postDelete", target: { allOf: entityRef }, handler })`** — fires after commit.
   External side effects (logs, notifications) belong here because
   failures cannot roll the delete back.
+- **`ctx.scheduleAfterRollback(fn)`** — the counterpart of `scheduleAfterCommit`: runs `fn` when
+  the handler transaction (or the enclosing savepoint of a nested `ctx.write`) does not commit.
+  Use it to give back something reserved outside the transaction, like the slot in
+  `article:reserve-slot`. A failed COMMIT triggers it too, so write the callback idempotent.
 
 ## When to reach for it
 
@@ -71,7 +75,7 @@ import {
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-testing/stack";
-import { articleEntity, articlesFeature, hookLog } from "../feature";
+import { articleEntity, articlesFeature, hookLog, reservedSlots } from "../feature";
 
 let stack: TestStack;
 
@@ -90,6 +94,7 @@ afterAll(async () => {
 beforeEach(() => {
   stack.events.reset();
   hookLog.length = 0;
+  reservedSlots.clear();
 });
 
 describe("validation hook: single handler", () => {
@@ -256,6 +261,29 @@ describe("preDelete + postDelete entity hooks", () => {
     expect(hookLog.map((e) => e.type)).toEqual(["deleted"]);
   });
 });
+
+describe("scheduleAfterRollback", () => {
+  test("keeps the outside-transaction reservation when the write commits", async () => {
+    await stack.http.writeOk(
+      "blog:write:article:reserve-slot",
+      { slot: "kept", reject: false },
+      editor,
+    );
+
+    expect(reservedSlots.has("kept")).toBe(true);
+  });
+
+  test("gives the reservation back when the write rolls back", async () => {
+    const error = await stack.http.writeErr(
+      "blog:write:article:reserve-slot",
+      { slot: "released", reject: true },
+      editor,
+    );
+
+    expectErrorIncludes(error, "slot_rejected");
+    expect(reservedSlots.has("released")).toBe(false);
+  });
+});
 ```
 
 ### src/feature.ts
@@ -276,7 +304,12 @@ import {
   defineFeature,
   type SaveContext,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  ConflictError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
 
 export const articleEntity = createEntity({
   table: "read_sample_articles",
@@ -298,6 +331,9 @@ export const articleEntity = createEntity({
 // Collect hook events for testing
 export const hookLog: { type: string; data: Record<string, unknown> }[] = [];
 
+// Stands in for a quota held in an external system, outside the handler transaction.
+export const reservedSlots = new Set<string>();
+
 const editorWrite = { access: { roles: ["Admin", "Editor"] } } as const;
 
 export const articlesFeature = defineFeature("blog", (r) => {
@@ -311,6 +347,23 @@ export const articlesFeature = defineFeature("blog", (r) => {
   );
   r.writeHandler(defineEntityDeleteHandler("article", articleEntity, editorWrite));
 
+  // --- scheduleAfterRollback: give back a reservation made outside the transaction when it does
+  // not commit. The callback must be idempotent: a failed COMMIT also triggers it.
+  r.writeHandler({
+    name: "article:reserve-slot",
+    schema: z.object({ slot: z.string(), reject: z.boolean() }),
+    access: editorWrite.access,
+    handler: async (event, ctx) => {
+      const { slot, reject } = event.payload;
+      reservedSlots.add(slot);
+      ctx.scheduleAfterRollback?.(async () => {
+        reservedSlots.delete(slot);
+      });
+      if (reject) return writeFailure(new UnprocessableError("slot_rejected"));
+      return { isSuccess: true as const, data: {} };
+    },
+  });
+
   // --- Validation hook on create: reject banned words + length ---
   r.hook({
     type: "validation",

package/agents/examples/list-table-options.md

@@ -0,0 +1,466 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/list-table-options. Do not edit. -->
+
+# list-table-options
+
+Opt-in table behaviour of a list: remembered search/sort/filters, one reset button, column picker with hidden columns, row density, server-side groups with sums, a totals row and a number range facet.
+
+## README
+
+# List table options
+
+Opt-in table behaviour for entity, projection and related lists. A list without
+the `table` block renders and behaves as before.
+
+## What it shows
+
+- `table.rememberState`: search, sort, page size, facets and date range survive
+  leaving and re-entering the list within the browser session.
+- `table.resetAll`: one button resets everything that differs from the defaults.
+- `table.columnPicker`: the view menu lets the user hide and reorder columns;
+  `hidden: true` on a column starts it hidden.
+- `table.density`: row density default and an optional user choice.
+- `table.pinning`: the user pins columns left or right in the view menu;
+  `pinned: "left"` on a column starts it pinned.
+- `table.resizing`: columns can be resized (table-layout fixed); `width` and
+  `minWidth` on a column are start values in px.
+- `table.keyboardNavigation`: rows are one tab stop, arrow keys move between rows,
+  Space selects the focused row.
+- `table.export`: an Export button downloads the whole filtered list as an XLSX
+  file; `maxRows` lowers the default limit of 10000 rows.
+  Reference columns export their label and timestamps use the browser time zone.
+- `bulkActions`: row checkboxes and a selection bar. "Delete" runs the delete
+  row action once per selected row; done tasks are skipped.
+- `table.grouping`: the server groups the list by status; each header shows the
+  group's count and estimate sum, "done" starts collapsed and the view menu
+  offers grouping by priority or none.
+- `table.totals`: a footer row with the estimate sum over the filtered list.
+- `facets.estimateHours: { display: "range" }`: from/to inputs for a number field.
+- The same block on a `projectionList`, and `task:workload`, a hand-written list
+  query that keeps grouping and totals by accepting `aggregate`
+  (`entityListSchema`) and answering it with `answerListAggregate`.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/list-table-options
+bun test
+```
+
+The test boots the feature through the boot validator and checks that a
+misspelled key, a hidden column without the picker, an unknown density, a pinned column
+without `pinning`, a width without `resizing` and a bulk action on a navigate
+row action are rejected.
+`workload.integration.test.ts` runs the hand-written query over HTTP and checks
+the grouped sums and the filtered total.
+
+## Source files
+
+### src/__tests__/feature.test.ts
+
+```ts
+import { describe, expect, test } from "bun:test";
+import {
+  createRegistry,
+  defineFeature,
+  validateBoot as validateBootRaw,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { ListTableOptions } from "@cosmicdrift/kumiko-framework/ui-types";
+import { withBootValidatorFixture } from "@cosmicdrift/kumiko-testing/helpers";
+import { createTaskBoardFeature, openAccess, taskEntity } from "../feature";
+
+// The boot validator is the net for blocks the type system never sees (JS, generated features).
+function featureWithBlock(block: object) {
+  return createTaskBoardFeature(block as ListTableOptions);
+}
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+describe("list-table-options recipe", () => {
+  test("the full table block boots and reaches the registered screen", () => {
+    const feature = createTaskBoardFeature();
+    expect(() => validateBoot([feature])).not.toThrow();
+    const screen = createRegistry([feature]).getScreen("task-board:screen:task-list");
+    expect(screen?.type === "entityList" ? screen.table : undefined).toEqual({
+      rememberState: true,
+      resetAll: true,
+      columnPicker: true,
+      density: { default: "comfortable", userChoice: true },
+      pinning: true,
+      resizing: true,
+      keyboardNavigation: true,
+      export: { xlsx: true, maxRows: 5000 },
+      grouping: { field: "status", collapsedWhen: "done", userChoice: true, fields: ["priority"] },
+      totals: [{ field: "estimateHours", kind: "sum" }],
+    });
+  });
+
+  test("the bulk action resolves to the delete row action", () => {
+    const screen = createRegistry([createTaskBoardFeature()]).getScreen(
+      "task-board:screen:task-list",
+    );
+    expect(screen?.type === "entityList" ? screen.bulkActions : undefined).toEqual([
+      { id: "delete", rowAction: "delete" },
+    ]);
+  });
+
+  test("a bulk action that points at a navigate row action is rejected", () => {
+    const feature = defineFeature("bulk-on-navigate", (r) => {
+      r.crud("task", taskEntity, { write: openAccess, read: openAccess });
+      r.screen({
+        id: "task-list",
+        type: "entityList",
+        entity: "task",
+        columns: ["title"],
+        rowActions: [{ kind: "navigate", id: "open", label: "Open", screen: "task-list" }],
+        bulkActions: [{ id: "open", rowAction: "open" }],
+        access: openAccess.access,
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /bulk action "open" points at rowAction "open" of kind "navigate"/,
+    );
+  });
+
+  test("a pinned column needs table.pinning", () => {
+    expect(() => validateBoot([featureWithBlock({ columnPicker: true, resizing: true })])).toThrow(
+      /column "title" is pinned but table\.pinning is not enabled/,
+    );
+  });
+
+  test("width and minWidth need table.resizing", () => {
+    expect(() => validateBoot([featureWithBlock({ columnPicker: true, pinning: true })])).toThrow(
+      /column "title" sets width but table\.resizing is not enabled/,
+    );
+  });
+
+  test("a misspelled table key is rejected with the allowed keys", () => {
+    expect(() => validateBoot([featureWithBlock({ rememberStatee: true })])).toThrow(
+      /unknown key\(s\) "rememberStatee"\. Allowed keys: rememberState, resetAll, columnPicker, density, pinning, resizing, keyboardNavigation, export/,
+    );
+  });
+
+  test("a hidden column needs the column picker", () => {
+    expect(() => validateBoot([featureWithBlock({ rememberState: true, resetAll: true })])).toThrow(
+      /column "estimateHours" is hidden but table\.columnPicker is not enabled/,
+    );
+  });
+
+  test("a density outside the union is rejected", () => {
+    expect(() =>
+      validateBoot([featureWithBlock({ columnPicker: true, density: { default: "tight" } })]),
+    ).toThrow(/table\.density\.default is "tight"/);
+  });
+
+  test("an export row limit above the hard cap is rejected", () => {
+    expect(() =>
+      validateBoot([
+        featureWithBlock({ columnPicker: true, export: { xlsx: true, maxRows: 100001 } }),
+      ]),
+    ).toThrow(/table\.export\.maxRows is 100001 .* at most 100000/);
+  });
+});
+```
+
+### src/__tests__/workload.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
+import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
+import { createTaskBoardFeature } from "../feature";
+
+type ListAggregateResult = {
+  readonly groups: readonly { key: unknown; count: number; measures: readonly unknown[] }[];
+};
+
+let stack: TestStack;
+const user = createTestUser({ roles: ["User"], tenantId: testTenantId(1) });
+
+const TASKS = [
+  { title: "Quarterly VAT filing", assignee: "Ines", estimateHours: 6 },
+  { title: "Prepare audit", assignee: "Ines", estimateHours: 24 },
+  { title: "Plan offsite", assignee: "Mara", estimateHours: 7 },
+] as const;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [createTaskBoardFeature()], systemHooks: [] });
+  for (const task of TASKS) {
+    await stack.http.writeOk("task-board:write:task:create", task, user);
+  }
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("hand-written list query with aggregate", () => {
+  test("groups by assignee with the server count and estimate sum", async () => {
+    const result = await stack.http.queryOk<ListAggregateResult>(
+      "task-board:query:task:workload",
+      { aggregate: { groupBy: "assignee", measures: [{ field: "estimateHours", kind: "sum" }] } },
+      user,
+    );
+    expect(result.groups.map(({ key, count, measures }) => ({ key, count, measures }))).toEqual([
+      { key: "Ines", count: 2, measures: [30] },
+      { key: "Mara", count: 1, measures: [7] },
+    ]);
+  });
+
+  test("the totals answer follows the list filter", async () => {
+    const result = await stack.http.queryOk<ListAggregateResult>(
+      "task-board:query:task:workload",
+      {
+        filters: [{ field: "estimateHours", op: "lte", value: 7 }],
+        aggregate: { measures: [{ field: "estimateHours", kind: "sum" }] },
+      },
+      user,
+    );
+    expect(result.groups.map((group) => group.measures)).toEqual([[13]]);
+  });
+
+  test("without aggregate the same query lists rows", async () => {
+    const list = await stack.http.queryOk<{ rows: { title: string }[] }>(
+      "task-board:query:task:workload",
+      { sort: "title" },
+      user,
+    );
+    expect(list.rows.map((row) => row.title)).toEqual([
+      "Plan offsite",
+      "Prepare audit",
+      "Quarterly VAT filing",
+    ]);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import {
+  answerListAggregate,
+  buildEntityTable,
+  createEventStoreExecutor,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createDateField,
+  createEntity,
+  createNumberField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+  entityListSchema,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { ListTableOptions } from "@cosmicdrift/kumiko-framework/ui-types";
+import { z } from "zod";
+
+export const taskEntity = createEntity({
+  table: "read_list_table_tasks",
+  fields: {
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      searchable: true,
+      sortable: true,
+    }),
+    status: createSelectField({
+      options: ["open", "inProgress", "blocked", "done"] as const,
+      default: "open",
+      sortable: true,
+      filterable: true,
+    }),
+    priority: createSelectField({
+      options: ["low", "medium", "high"] as const,
+      default: "medium",
+      sortable: true,
+      filterable: true,
+    }),
+    dueDate: createDateField({ sortable: true }),
+    assignee: createTextField({ personal: false, reason: "is_business_data", sortable: true }),
+    estimateHours: createNumberField({ sortable: true, filterable: true }),
+  },
+});
+
+export const openAccess = {
+  access: {
+    openToAll: { reason: "recipe: any signed-in user manages the tasks; no per-user ownership" },
+  },
+} as const;
+
+// Overridable so a test can feed the boot validator a block that must be rejected.
+export function createTaskBoardFeature(
+  taskTable: ListTableOptions = {
+    rememberState: true,
+    resetAll: true,
+    columnPicker: true,
+    density: { default: "comfortable", userChoice: true },
+    pinning: true,
+    resizing: true,
+    keyboardNavigation: true,
+    export: { xlsx: true, maxRows: 5000 },
+    grouping: { field: "status", collapsedWhen: "done", userChoice: true, fields: ["priority"] },
+    totals: [{ field: "estimateHours", kind: "sum" }],
+  },
+): FeatureDefinition {
+  return defineFeature("task-board", (r) => {
+    r.crud("task", taskEntity, { write: openAccess, read: openAccess });
+
+    r.screen({
+      id: "task-list",
+      type: "entityList",
+      entity: "task",
+      columns: [
+        // Starts pinned left; width and minWidth are start values for resizing.
+        { field: "title", pinned: "left", width: 280, minWidth: 160 },
+        "status",
+        "priority",
+        { field: "dueDate", hideOnNarrow: true },
+        { field: "assignee", hideOnNarrow: true },
+        // Starts hidden; the user can add it back in the view menu.
+        { field: "estimateHours", hidden: true, hideOnNarrow: true },
+      ],
+      facets: { status: { display: "chips" }, priority: {}, estimateHours: { display: "range" } },
+      defaultSort: { field: "dueDate", dir: "asc" },
+      searchable: true,
+      table: taskTable,
+      rowActions: [
+        { kind: "navigate", id: "open", label: "Open", screen: "task-edit", rowClick: true },
+        {
+          kind: "writeHandler",
+          id: "delete",
+          label: "Delete",
+          handler: "task-board:write:task:delete",
+          style: "danger",
+          // Done tasks are skipped by the bulk run and counted as skipped.
+          visible: { field: "status", ne: "done" },
+        },
+      ],
+      // Row checkboxes and a selection bar; each selected row gets its own delete write.
+      bulkActions: [{ id: "delete", rowAction: "delete" }],
+      access: openAccess.access,
+    });
+
+    r.screen({
+      id: "task-edit",
+      type: "entityEdit",
+      entity: "task",
+      dormant: true,
+      listScreenId: "task-list",
+      layout: {
+        sections: [
+          {
+            columns: 2,
+            fields: ["title", "assignee", "status", "priority", "dueDate", "estimateHours"],
+          },
+        ],
+      },
+    });
+
+    // The same block works on a list over any query.
+    r.queryHandler({
+      name: "task:overdue",
+      schema: z.object({}),
+      handler: async () => ({
+        rows: [{ id: "t1", title: "Quarterly VAT filing", assignee: "Ines", daysLate: 3 }],
+        nextCursor: null,
+      }),
+      access: openAccess.access,
+      outputSchema: z.object({
+        rows: z.array(
+          z.object({
+            id: z.string(),
+            title: z.string(),
+            assignee: z.string(),
+            daysLate: z.number(),
+          }),
+        ),
+        nextCursor: z.string().nullable(),
+      }),
+    });
+
+    r.screen({
+      id: "task-overdue",
+      type: "projectionList",
+      query: "task-board:query:task:overdue",
+      columns: ["title", "assignee", "daysLate"],
+      table: { rememberState: true, density: { userChoice: true } },
+    });
+
+    // A hand-written list query keeps grouping and totals when it accepts
+    // `aggregate` (entityListSchema carries it) and answers it on the server.
+    const taskExecutor = createEventStoreExecutor(
+      buildEntityTable("task", taskEntity),
+      taskEntity,
+      {
+        entityName: "task",
+      },
+    );
+    r.queryHandler({
+      name: "task:workload",
+      schema: entityListSchema,
+      handler: async (query, ctx) => {
+        const parentVisibility = { entities: ctx.registry.getAllEntities() };
+        const listPayload = query.payload;
+        if (listPayload.aggregate !== undefined) {
+          return answerListAggregate(
+            taskExecutor,
+            { ...listPayload, aggregate: listPayload.aggregate },
+            query.user,
+            ctx.db,
+            { parentVisibility },
+            {
+              entity: taskEntity,
+              resolveEntity: (name) => ctx.registry.getEntity(name),
+              viewer: { user: query.user, parentVisibility },
+            },
+          );
+        }
+        return taskExecutor.list(listPayload, query.user, ctx.db, { parentVisibility });
+      },
+      access: openAccess.access,
+    });
+
+    r.screen({
+      id: "task-workload",
+      type: "projectionList",
+      query: "task-board:query:task:workload",
+      columns: ["title", "assignee", "status", "estimateHours"],
+      defaultSort: { field: "title", dir: "asc" },
+      table: {
+        grouping: { field: "assignee" },
+        totals: [{ field: "estimateHours", kind: "sum" }],
+      },
+    });
+
+    r.nav({ id: "tasks", label: "task-board:nav.tasks", icon: "list", order: 10 });
+    r.nav({
+      id: "task-list",
+      label: "task-board:nav.list",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-list",
+      order: 10,
+    });
+    r.nav({
+      id: "task-overdue",
+      label: "task-board:nav.overdue",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-overdue",
+      order: 20,
+    });
+    r.nav({
+      id: "task-workload",
+      label: "task-board:nav.workload",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-workload",
+      order: 30,
+    });
+  });
+}
+```

package/agents/examples/pdf-audit-export.md

@@ -42,6 +42,7 @@ bun test
 // and its text contains exactly the inspections of the requested period.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createFilesFeature,
   createInMemoryFileProvider,
@@ -150,7 +151,7 @@ describe("export-audit", () => {
 
   test("a period with more inspections than the export holds is rejected instead of cut off", async () => {
     const assetName = "Großanlage";
-    for (let day = 0; day < 101; day += 1) {
+    for (let day = 0; day < MAX_LIST_LIMIT; day += 1) {
       const inspectedOn = new Date(Date.UTC(2025, 0, 1 + day)).toISOString().slice(0, 10);
       await addInspection(inspectedOn, "ok", `Prüfer-${day}`, assetName);
     }
@@ -185,6 +186,7 @@ import {
   createTextField,
   defineFeature,
   defineWriteHandler,
+  MAX_LIST_LIMIT,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import {
@@ -221,7 +223,7 @@ function toFileNameSegment(text: string): string {
 }
 
 // One row above the limit tells "exactly full" from "cut off"; entity lists cap at 200 rows.
-const AUDIT_ROW_LIMIT = 100;
+const AUDIT_ROW_LIMIT = MAX_LIST_LIMIT - 1;
 
 const access = { access: { roles: ["Admin", "User"] } } as const;
 

package/agents/examples/prod-boot-options.md

@@ -57,6 +57,22 @@ bun test samples/recipes/prod-boot-options
 
 ## Source files
 
+### bin/server.ts
+
+```ts
+import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import { appFeatures, bootOptions } from "../src/app";
+
+const features = appFeatures();
+
+await runProdApp({
+  features,
+  envSchema: composeEnvSchema({ features }),
+  ...bootOptions(process.env),
+});
+```
+
 ### src/__tests__/boot-options.test.ts
 
 ```ts

package/agents/examples/rate-limiting.md

@@ -36,6 +36,24 @@ exhausted) and no bucket is charged. Each `per` may appear once; an empty list f
 An anonymous handler needs every bucket to be ip-keyed, and `{ disabled: true, reason }`
 stays a single declaration.
 
+## Cost per payload element
+
+A bulk handler books one token per item instead of one per request. Declare `rateLimitCost`
+next to `rateLimit`:
+
+```ts illustration
+r.writeHandler({
+  // ...
+  rateLimit: { per: "tenant+handler", limit: 20, windowSeconds: 600 },
+  rateLimitCost: (payload) => payload.files.length,
+});
+```
+
+The cost is computed from the validated payload and booked on every declared bucket, so an
+invalid payload costs nothing and a rejected request consumes nothing. Results below 1 count
+as 1. Because it books after the parse, boot rejects `rateLimitCost` on anonymous or ip-limited
+handlers.
+
 ## Per-payload limits
 
 A public write handler that mails an address typed by the caller is also limited per
@@ -229,6 +247,24 @@ describe("L2 — auth-endpoints middleware (tighter cap on /api/auth/*)", () =>
     expect(body.error.details.bucket).toBe("l2");
   });
 });
+
+describe("L3 — cost per payload element (bulk-upload)", () => {
+  const bulkUpload = "rl-showcase:write:bulk-upload";
+  const files = (count: number): { files: string[] } => ({
+    files: Array.from({ length: count }, (_, index) => `file-${index}.pdf`),
+  });
+
+  test("a request books one token per file; a request over the remaining budget is rejected", async () => {
+    expect((await stack.http.write(bulkUpload, files(10), admin)).status).toBe(200);
+    expect((await stack.http.write(bulkUpload, files(15), admin)).status).toBe(429);
+    // The rejected request consumed nothing: 10 more still fit.
+    expect((await stack.http.write(bulkUpload, files(10), admin)).status).toBe(200);
+    const blocked = await stack.http.write(bulkUpload, files(1), admin);
+    expect(blocked.status).toBe(429);
+    const body = (await blocked.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("rate_limited");
+  });
+});
 ```
 
 ### src/feature.ts
@@ -269,6 +305,18 @@ export function createRateLimitShowcaseFeature(): FeatureDefinition {
         { per: "tenant+handler", limit: 3, windowSeconds: 3600 },
       ],
     });
+
+    // Bulk upload: a request books one token per item instead of one per request. The cost
+    // comes from the validated payload, so a schema-invalid request costs nothing; a request
+    // that would exceed the remaining budget is rejected and consumes nothing.
+    r.writeHandler({
+      name: "bulk-upload",
+      schema: z.object({ files: z.array(z.string()).min(1).max(20) }),
+      handler: async () => ({ isSuccess: true as const, data: {} }),
+      access: { roles: ["Admin", "User"] },
+      rateLimit: { per: "tenant+handler", limit: 20, windowSeconds: 600 },
+      rateLimitCost: (payload) => payload.files.length,
+    });
   });
 }
 ```