@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/AGENTS.md

@@ -208,7 +208,12 @@ produces code that compiles and then fails in production.
   one page (default 50, `limit` at most 200). Pass
   `filter: { field, op, value }` (`eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`)
   so the database filters, and `totalCount: true` to get `total` over all
-  matching rows; `limit: 1, totalCount: true` is a count query.
+  matching rows; `limit: 1, totalCount: true` is a count query. Groups and
+  sums are the same: pass `aggregate: { groupBy?, measures: [{ field, kind }] }`
+  (`kind` is `sum`, `avg`, `count`, `min` or `max`) and the list answers with
+  `{ groups: [{ key, label?, count, measures }] }` over the same filters,
+  search and ownership, at most 200 groups (`truncated: true` beyond that).
+  Custom handlers call `executor.aggregate(...)` or `answerListAggregate`.
 - Never change an event schema in place once it has been emitted. Version it
   (see `agents/examples/event-sourcing.md`).
 - Never read or write another tenant's data. `ctx.db` is tenant scoped on

package/agents/examples/anonymous-access.md

@@ -60,7 +60,7 @@ import {
 
 const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
 
-// Unique per test: the tenant is fixed, so rows are told apart by value, not by reset.
+// Each value is written by exactly one test; the tenant is fixed, so rows are told apart by value, not by reset.
 const PRODUCT_NAME = "Espresso Beans (anonymous read)";
 const GUEST_EMAIL = "guest-checkout@example.com";
 

package/agents/examples/apex-landing.md

@@ -41,6 +41,210 @@ bun run screenshot  # → screenshots/landing.png + lightbox.png
 
 ## Source files
 
+### e2e/header-layout.spec.ts
+
+```ts
+// Regression for issue #2038: below the 1120px .container breakpoint, the
+// header's `<div class="container nav">` lost its horizontal padding because
+// `.nav`'s `padding` shorthand (same specificity, declared later) zeroed out
+// the inline padding `.container` set. Verified against a real narrow
+// viewport, not derived from source — matches how the bug was first found.
+
+import { expect, boundaryGuardedTest as test } from "@cosmicdrift/kumiko-testing/e2e";
+import { renderLanding, SAMPLE_PLANS } from "../src/feature";
+
+test("header keeps the page's horizontal padding below 1120px (#2038)", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.setContent(renderLanding({ plans: SAMPLE_PLANS }), {
+    waitUntil: "domcontentloaded",
+    url: "http://localhost/",
+  });
+
+  const headerContainer = page.locator("header .container.nav");
+  const footerContainer = page.locator("footer .container");
+
+  const [headerPadding, footerPadding] = await Promise.all([
+    headerContainer.evaluate((el) => {
+      const s = getComputedStyle(el);
+      return { left: s.paddingLeft, right: s.paddingRight };
+    }),
+    footerContainer.evaluate((el) => {
+      const s = getComputedStyle(el);
+      return { left: s.paddingLeft, right: s.paddingRight };
+    }),
+  ]);
+
+  // The header is indented exactly like the rest of the page — not 0.
+  expect(headerPadding.left).not.toBe("0px");
+  expect(headerPadding).toEqual(footerPadding);
+
+  // The nav's rightmost action stays inside the viewport, not clipped at the edge.
+  const actionBox = await page.locator("header .nav-actions a").last().boundingBox();
+  expect(actionBox).not.toBeNull();
+  expect(actionBox!.x + actionBox!.width).toBeLessThanOrEqual(390);
+});
+```
+
+### e2e/screenshot.spec.ts
+
+```ts
+// E2E screenshot renderer for the Apex landing example. Renders the sample page
+// to HTML, paints it in a real browser and shoots a full-page PNG. The output is
+// what the docs guide embeds — regenerate with `bun run screenshot`, never hand-
+// captured, so it can't drift from the renderer.
+//
+// SCREENSHOT_DIR overrides the output dir (CI writes straight into the docs repo).
+
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, boundaryGuardedTest as test } from "@cosmicdrift/kumiko-testing/e2e";
+import type { Page } from "@playwright/test";
+import { HERO_SCREENSHOT } from "../src/constants";
+import { renderLanding, SAMPLE_PLANS } from "../src/feature";
+
+const OUT_DIR = process.env["SCREENSHOT_DIR"] ?? resolve(import.meta.dirname, "../screenshots");
+const HERO_APP_PNG = resolve(OUT_DIR, "hero-app.png");
+const LANDING_PNG = resolve(OUT_DIR, "landing.png");
+const LIGHTBOX_PNG = resolve(OUT_DIR, "lightbox.png");
+
+/** Minimal in-app board mock — hero frame shows product UI, not the full landing PNG. */
+const HERO_APP_HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <style>
+    body { margin: 0; background: #f4f4f5; font-family: system-ui, sans-serif; }
+    #board {
+      width: 720px; padding: 16px; background: #fff; border-radius: 12px;
+      border: 1px solid #e4e4e7; box-sizing: border-box;
+    }
+    .top { display: flex; justify-content: space-between; margin-bottom: 16px; font-weight: 600; }
+    .cols { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
+    .col { background: #fafafa; border-radius: 8px; padding: 10px; min-height: 140px; }
+    .label { font-size: 11px; color: #71717a; margin-bottom: 8px; }
+    .card {
+      background: #fff; border: 1px solid #e4e4e7; border-radius: 6px;
+      padding: 8px; margin-bottom: 8px; font-size: 13px;
+    }
+    .tag {
+      display: inline-block; font-size: 10px; padding: 2px 6px; border-radius: 4px;
+      background: #ede9fe; color: #5b21b6; margin-left: 4px;
+    }
+  </style>
+</head>
+<body>
+  <div id="board">
+    <div class="top"><span>Tasklane — Q3 roadmap</span><span style="color:#71717a;font-weight:400">3 projects</span></div>
+    <div class="cols">
+      <div class="col">
+        <div class="label">Backlog</div>
+        <div class="card">Auth hardening<span class="tag">P1</span></div>
+        <div class="card">Export CSV</div>
+      </div>
+      <div class="col">
+        <div class="label">In progress</div>
+        <div class="card">Board filters</div>
+        <div class="card">Invite flow</div>
+      </div>
+      <div class="col">
+        <div class="label">Done</div>
+        <div class="card">Dark mode</div>
+      </div>
+    </div>
+  </div>
+</body>
+</html>`;
+
+function heroForMount(): typeof HERO_SCREENSHOT {
+  const b64 = readFileSync(HERO_APP_PNG).toString("base64");
+  return { ...HERO_SCREENSHOT, src: `data:image/png;base64,${b64}` };
+}
+
+async function assertHeroImageLoaded(page: Page): Promise<void> {
+  const img = page.locator(".shot-frame img");
+  await expect(img).toBeVisible();
+  await expect
+    .poll(async () => img.evaluate((el) => (el as HTMLImageElement).naturalWidth))
+    .toBeGreaterThan(0);
+}
+
+/** setContent does not reliably fetch routed /screenshots/* — inline data: URL instead. */
+async function mountLanding(page: Page): Promise<void> {
+  if (!existsSync(HERO_APP_PNG)) {
+    throw new Error("hero-app.png missing — run hero-app test first (serial suite)");
+  }
+  await page.setContent(renderLanding({ plans: SAMPLE_PLANS, heroScreenshot: heroForMount() }), {
+    waitUntil: "networkidle",
+    url: "http://localhost/",
+  });
+  await assertHeroImageLoaded(page);
+}
+
+test.describe.configure({ mode: "serial" });
+
+test("hero-app — product screenshot asset", async ({ page }) => {
+  mkdirSync(OUT_DIR, { recursive: true });
+  await page.setContent(HERO_APP_HTML, { waitUntil: "networkidle" });
+  await page.locator("#board").screenshot({ path: HERO_APP_PNG });
+  expect(statSync(HERO_APP_PNG).size).toBeGreaterThan(5 * 1024);
+});
+
+test("apex landing — full page", async ({ page }) => {
+  await mountLanding(page);
+  await page.screenshot({ path: LANDING_PNG, fullPage: true });
+  expect(statSync(LANDING_PNG).size).toBeGreaterThan(5 * 1024);
+});
+
+test("apex lightbox — open (screenshot)", async ({ page }) => {
+  await mountLanding(page);
+  await page.locator(".shot-frame img").click();
+  await expect(page.locator("#apex-lightbox")).toBeVisible();
+  await expect
+    .poll(async () =>
+      page.locator("#apex-lightbox img").evaluate((el) => (el as HTMLImageElement).naturalWidth),
+    )
+    .toBeGreaterThan(0);
+  await page.screenshot({ path: LIGHTBOX_PNG });
+  expect(statSync(LIGHTBOX_PNG).size).toBeGreaterThan(5 * 1024);
+});
+
+test("apex lightbox — closes on button", async ({ page }) => {
+  await mountLanding(page);
+  await page.locator(".shot-frame img").click();
+  await expect(page.locator("#apex-lightbox")).toBeVisible();
+  await page.locator(".apex-lightbox__close").click();
+  await expect(page.locator("#apex-lightbox")).not.toBeVisible();
+});
+```
+
+### playwright.config.ts
+
+```ts
+import { defineConfig, devices } from "@playwright/test";
+
+// No webServer: the Apex renderer is a pure function, so the runner feeds its
+// HTML straight into the page via setContent — nothing to boot.
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: false,
+  forbidOnly: !!process.env["CI"],
+  retries: 0,
+  workers: 1,
+  reporter: [["list"]],
+  timeout: 60_000,
+  use: {
+    viewport: { width: 1920, height: 1080 },
+    deviceScaleFactor: 2,
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"], viewport: { width: 1920, height: 1080 } },
+    },
+  ],
+});
+```
+
 ### src/__tests__/landing.test.ts
 
 ```ts

package/agents/examples/api-worker-split.md

@@ -85,6 +85,70 @@ before the worker picks up the job and writes the fulfillment back.
 
 ## Source files
 
+### bin/api.ts
+
+```ts
+// API process — `runSingleInstance: false` makes this process API-only:
+// HTTP + event writes + BullMQ ENQUEUE, no worker-lane consumption, no
+// multiStreamProjection application. A dedicated worker MUST run next to
+// it (bin/worker.ts) or the read-side stays empty.
+import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
+import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import { createApiWorkerSplitFeature } from "../src/feature";
+
+const features = [createApiWorkerSplitFeature()];
+
+await runProdApp({
+  features,
+  envSchema: composeEnvSchema({ core: frameworkCoreEnvSchema, features }),
+  runSingleInstance: false,
+  // worker-lane queue prefix; must match bin/worker.ts.
+  jobs: { queueNamePrefix: "api-worker-split" },
+});
+```
+
+### bin/kumiko.ts
+
+```ts
+#!/usr/bin/env bun
+// Schema CLI for the sample: creates the framework infra tables
+// (idempotent) and applies kumiko/migrations. Requires DATABASE_URL.
+import { runStandaloneSchemaCli } from "@cosmicdrift/kumiko-dev-server/schema-apply";
+import { createApiWorkerSplitFeature } from "../src/feature";
+
+await runStandaloneSchemaCli({ features: [createApiWorkerSplitFeature()] });
+```
+
+### bin/worker.ts
+
+```ts
+// Worker process — consumes the worker-lane BullMQ queue and applies the
+// multiStreamProjections the API skipped. No HTTP surface.
+//
+// wireComponents runs after the entrypoint is up and hands over
+// `dispatchSystemWrite` — a dispatcher-scoped system write. The job's
+// write-bridge is wired here (fw#1717): JobContext has no write/query, so
+// background components persist through this dispatcher instead.
+//
+// ponytail: BullMQ may pop jobs between entrypoint.start() and this hook —
+// those hits throw "no fulfill-write bridge wired" and rely on BullMQ retry
+// until the bridge is set. Upgrade: defer job registration until after wire,
+// or hold fulfillWrite behind a deferred Promise.
+import { runWorkerApp } from "@cosmicdrift/kumiko-server-runtime";
+import { createApiWorkerSplitFeature, setOrderFulfillWrite } from "../src/feature";
+
+await runWorkerApp({
+  features: [createApiWorkerSplitFeature()],
+  jobs: { queueNamePrefix: "api-worker-split" },
+  wireComponents: async ({ dispatchSystemWrite }) => {
+    setOrderFulfillWrite(({ handlerQn, payload, tenantId }) =>
+      dispatchSystemWrite({ handlerQn, payload, tenantId }),
+    );
+  },
+});
+```
+
 ### src/__tests__/feature.integration.test.ts
 
 ```ts

package/agents/examples/app-config.md

@@ -37,6 +37,20 @@ for the files around it.
 
 ## Source files
 
+### kumiko.config.ts
+
+```ts
+import { defineAppConfig } from "@cosmicdrift/kumiko-framework/config";
+import { auditExportFeature, notesFeature } from "./src/feature";
+
+export default defineAppConfig({
+  features: [notesFeature],
+  prodFeatures: [auditExportFeature],
+  client: { entries: ["src/client.tsx"] },
+  ports: { dev: 4510, e2e: 4511, infra: { postgres: 15510 } },
+});
+```
+
 ### src/__tests__/app-config.test.ts
 
 ```ts

package/agents/examples/auth-mfa.md

@@ -83,11 +83,16 @@ features: [..., createSessionsFeature(), mfaFeature, createAccountSecurityFeatur
 5. **MFA state changes revoke every OTHER live session** (stolen-session defense) — never the session that made the change.
 6. **Enforcement is opt-in.** Without a tenant enabling `auth-mfa:config:required`, users choose for themselves whether to enroll.
 
+## Confirmation code input
+
+`src/web/confirmation-code-step.tsx` shows the `Input kind="code"` renderer primitive outside the MFA screen, for example an e-mail or invite confirmation code. Pass `length` (here 6), `autoFocus` and `onComplete`. The input accepts digits only, so pasting "123 456" yields `123456`, and `onComplete` fires once when the value reaches `length`. `autoComplete` defaults to `one-time-code`, so mobile keyboards offer the code from the SMS or mail. After a wrong code the step clears the value and bumps a `key`, which remounts the input and returns focus to it.
+
 ## Tests
 
 - **Baseline:** a user without MFA enrolled still gets a JWT straight from `/auth/login`.
 - **End-to-end:** enroll via `enable-start`/`enable-confirm`, log in (gets a challenge, no JWT), complete via `/auth/mfa/verify` (gets a JWT) — copies the `buildServer({ auth: ... })` block from the sample comment verbatim.
 - **Account security:** the composed screen boot-validates next to `auth-mfa` and `sessions` and shows a sidebar entry once `nav` is set.
+- **Confirmation code step:** typing or pasting six digits calls `onConfirm` once; a rejected code shows the error, clears the field and refocuses it.
 
 ## Source files
 
@@ -388,3 +393,113 @@ export {
 } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 export { currentTotpCode } from "@cosmicdrift/kumiko-bundled-features/auth-mfa/testing";
 ```
+
+### src/web/__tests__/confirmation-code-step.test.tsx
+
+```tsx
+import { describe, expect, mock, test } from "bun:test";
+import { PrimitivesProvider } from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer/web";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { ConfirmationCodeStep } from "../confirmation-code-step.tsx";
+
+function renderStep(onConfirm: (code: string) => Promise<boolean>): void {
+  render(
+    <PrimitivesProvider value={defaultPrimitives}>
+      <ConfirmationCodeStep onConfirm={onConfirm} />
+    </PrimitivesProvider>,
+  );
+}
+
+function type(value: string): void {
+  fireEvent.change(screen.getByTestId("confirmation-code"), { target: { value } });
+}
+
+describe("ConfirmationCodeStep", () => {
+  test("focuses the input on mount", () => {
+    renderStep(async () => true);
+    expect(document.activeElement).toBe(screen.getByTestId("confirmation-code"));
+  });
+
+  test("does not confirm before six digits", () => {
+    const onConfirm = mock(async (_code: string) => true);
+    renderStep(onConfirm);
+    type("12345");
+    expect(onConfirm).not.toHaveBeenCalled();
+  });
+
+  test("pasted '123 456' confirms once with 123456", async () => {
+    const onConfirm = mock(async (_code: string) => true);
+    renderStep(onConfirm);
+    type("123 456");
+    await waitFor(() => expect(onConfirm).toHaveBeenCalledTimes(1));
+    expect(onConfirm).toHaveBeenCalledWith("123456");
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
+  test("a rejected code shows the error, clears the field and refocuses", async () => {
+    const onConfirm = mock(async (_code: string) => false);
+    renderStep(onConfirm);
+    type("123456");
+    await waitFor(() => expect(screen.getByRole("alert")).toBeTruthy());
+    const input = screen.getByTestId("confirmation-code");
+    expect(input).toHaveProperty("value", "");
+    await waitFor(() => expect(document.activeElement).toBe(input));
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### src/web/confirmation-code-step.tsx
+
+```tsx
+import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+
+const CONFIRMATION_CODE_LENGTH = 6;
+
+export type ConfirmationCodeStepProps = {
+  /** Resolves true when the server accepted the code. */
+  readonly onConfirm: (code: string) => Promise<boolean>;
+};
+
+export function ConfirmationCodeStep({ onConfirm }: ConfirmationCodeStepProps): ReactNode {
+  const { Input, Banner } = usePrimitives();
+  const [code, setCode] = useState("");
+  const [attempt, setAttempt] = useState(0);
+  const [pending, setPending] = useState(false);
+  const [rejected, setRejected] = useState(false);
+
+  const confirm = async (submittedCode: string): Promise<void> => {
+    if (pending) return;
+    setPending(true);
+    setRejected(false);
+    const accepted = await onConfirm(submittedCode).finally(() => setPending(false));
+    if (accepted) return;
+    setRejected(true);
+    setCode("");
+    // The input was disabled while pending and lost focus; remounting restores autoFocus.
+    setAttempt((n) => n + 1);
+  };
+
+  return (
+    <>
+      <Input
+        key={attempt}
+        kind="code"
+        length={CONFIRMATION_CODE_LENGTH}
+        id="confirmation-code"
+        name="confirmation-code"
+        testId="confirmation-code"
+        value={code}
+        onChange={setCode}
+        onComplete={(next) => void confirm(next)}
+        disabled={pending}
+        hasError={rejected}
+        autoFocus
+      />
+      {rejected ? <Banner variant="error">That code is not valid. Try again.</Banner> : null}
+    </>
+  );
+}
+```

package/agents/examples/env-composition.md

@@ -18,7 +18,8 @@ instead of keeping a hand-written copy of every feature's variables.
   `kmsEnvSchema` and `s3EnvSchema`. `composeEnvSchema` collects them and
   records which feature declared each variable.
 - **App-level blocks in `extend`**: `buildInfoEnvSchema`, `demoAdminEnvSchema`,
-  `stripeEnvSchema({ prices })` and `createS3EnvSchema({ prefix })` for a
+  `stripeEnvSchema({ prices })`, `dodoEnvSchema({ prices })` and
+  `createS3EnvSchema({ prefix })` for a
   second bucket. These belong to no mounted feature, so the app adds them.
 - **Typed result**: `parseEnv(composed.schema, …)` returns the merged type,
   so `parsed.S3_BUCKET` is `string | undefined` and `parsed.APP_PUBLIC_URL` is
@@ -34,6 +35,7 @@ instead of keeping a hand-written copy of every feature's variables.
 | `smtpEnvSchema` | `channel-email` | `createChannelEmailFeature()` |
 | `s3EnvSchema`, `createS3EnvSchema({ prefix })` | `file-provider-s3` | `createFileProviderS3Feature({ fromEnv: true })` |
 | `stripeEnvSchema({ prices })` | `subscription-stripe` | app (`extend`); the feature registers the bridge keys |
+| `dodoEnvSchema({ prices })` | `subscription-dodo` | app (`extend`); the feature registers the bridge keys |
 | `mfaTokenSecretsEnvSchema` | `auth-mfa` | `createAuthMfaFeature()` |
 | `buildInfoEnvSchema`, `demoAdminEnvSchema` | `foundation-shared` | app (`extend`) |
 | `prometheusMetricsEnvSchema` | `framework/observability` | app (`extend`) |
@@ -45,6 +47,26 @@ Every app that boots with `runProdApp`. Pass the composed schema as
 
 ## Source files
 
+### bin/server.ts
+
+```ts
+// Production entrypoint. The env schema covers the same feature list that
+// runProdApp mounts, so `KUMIKO_DRY_RUN_ENV=boot bun bin/server.ts` lists
+// every variable of this app without connecting anywhere.
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import { composeAppEnv, createEnvCompositionFeatures } from "../src/env";
+
+const features = createEnvCompositionFeatures();
+
+await runProdApp({
+  features: [...features],
+  envSchema: composeAppEnv(features),
+  // The recipe declares no PII fields; crypto-shredding is mounted only for
+  // its env block.
+  allowPlaintextPii: "env-composition recipe has no PII fields",
+});
+```
+
 ### src/__tests__/dry-run-boot.test.ts
 
 ```ts
@@ -175,6 +197,7 @@ describe("env composition", () => {
     expect(sources["S3_BUCKET"]).toBe("file-provider-s3-env");
     expect(sources["RELEASES_S3_BUCKET"]).toBe("app");
     expect(sources["STRIPE_PRICE_PRO"]).toBe("app");
+    expect(sources["DODO_PRODUCT_PRO"]).toBe("app");
   });
 
   test("parses into a typed env", () => {
@@ -183,6 +206,7 @@ describe("env composition", () => {
       ...minimalValidValues,
       S3_BUCKET: "uploads",
       STRIPE_PRICE_PRO: "price_pro",
+      DODO_PRODUCT_PRO: "pdt_pro",
     });
 
     const bucket: string | undefined = parsed.S3_BUCKET;
@@ -190,6 +214,7 @@ describe("env composition", () => {
     expect(bucket).toBe("uploads");
     expect(publicUrl).toBe("https://app.example.com");
     expect(parsed.KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION).toBe("1");
+    expect(parsed.DODO_PRODUCT_PRO).toBe("pdt_pro");
   });
 
   test("reports every missing required variable with its source", () => {
@@ -245,6 +270,7 @@ import {
   demoAdminEnvSchema,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { dodoEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
 import { stripeEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
 import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
@@ -266,6 +292,7 @@ const appEnvSchema = z.object({
   ...buildInfoEnvSchema.shape,
   ...demoAdminEnvSchema.shape,
   ...stripeEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
+  ...dodoEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
   ...createS3EnvSchema({ prefix: "RELEASES_S3_" }).shape,
   APP_PUBLIC_URL: z.url().describe("Public origin of the app, used in mail links."),
 });

package/agents/examples/legal-pages.md

@@ -80,7 +80,7 @@ await runProdApp({
   // Required (1): routes run anonymous, need tenant resolution
   anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
   // Required (2): boot check + internal lookup use ctx.templateResolver
-  extraContext: ({ db }) => ({
+  extraContext: ({ db, registry }) => ({
     templateResolver: createTemplateResolverApi(db, registry),
   }),
 });

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,
+    });
   });
 }
 ```