@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/agents/examples/workflow-engine.md

@@ -325,7 +325,7 @@ describe("workflow-engine", () => {
   });
 
   it("webhook-delivery completes with exactly one dispatch request", async () => {
-    const ctx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const ctx = { events: { unsafeAppend: mock().mockResolvedValue(undefined) } };
 
     const result = await startAndRunWorkflow({
       runId: "wf-webhook-delivery-1",
@@ -339,7 +339,7 @@ describe("workflow-engine", () => {
     });
 
     expect(result.outcome).toBe("completed");
-    const dispatchRequests = ctx.unsafeAppendEvent.mock.calls
+    const dispatchRequests = ctx.events.unsafeAppend.mock.calls
       .map(([event]) => event as { type: string; payload: Record<string, unknown> })
       .filter((event) => event.type === STEP_DISPATCH_REQUESTED_TYPE);
     expect(dispatchRequests).toHaveLength(1);
@@ -367,7 +367,7 @@ describe("workflow-engine", () => {
 
 describe("workflow-runner", () => {
   function makeAppendOnlyCtx() {
-    return { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    return { events: { unsafeAppend: mock().mockResolvedValue(undefined) } };
   }
 
   it("startAndRunWorkflow writes run.started with Q7 snapshot fingerprint, then runs the pipeline to completion when no suspension", async () => {
@@ -386,15 +386,15 @@ describe("workflow-runner", () => {
     });
 
     expect(result.outcome).toBe("completed");
-    expect(ctx.unsafeAppendEvent).toHaveBeenCalledTimes(2);
-    const started = ctx.unsafeAppendEvent.mock.calls[0]![0] as {
+    expect(ctx.events.unsafeAppend).toHaveBeenCalledTimes(2);
+    const started = ctx.events.unsafeAppend.mock.calls[0]![0] as {
       type: string;
       payload: Record<string, unknown>;
     };
     expect(started.type).toBe("kumiko:system:workflow.run-started");
     expect(started.payload["definitionFingerprint"]).toBe(computeDefinitionFingerprint(workflow));
     expect(started.payload["triggerEventType"]).toBe("demo.fired");
-    const completed = ctx.unsafeAppendEvent.mock.calls[1]![0] as { type: string };
+    const completed = ctx.events.unsafeAppend.mock.calls[1]![0] as { type: string };
     expect(completed.type).toBe("kumiko:system:workflow.run-completed");
   });
 
@@ -418,8 +418,8 @@ describe("workflow-runner", () => {
 
     expect(result.outcome).toBe("suspended");
     // run.started + workflow.step.waiting — no run-completed yet
-    expect(ctx.unsafeAppendEvent).toHaveBeenCalledTimes(2);
-    const waiting = ctx.unsafeAppendEvent.mock.calls[1]![0] as {
+    expect(ctx.events.unsafeAppend).toHaveBeenCalledTimes(2);
+    const waiting = ctx.events.unsafeAppend.mock.calls[1]![0] as {
       type: string;
       payload: Record<string, unknown>;
     };
@@ -444,14 +444,16 @@ describe("workflow-runner", () => {
       handlerCtx: ctx as never,
     });
 
-    const started = ctx.unsafeAppendEvent.mock.calls[0]![0] as { payload: Record<string, unknown> };
+    const started = ctx.events.unsafeAppend.mock.calls[0]![0] as {
+      payload: Record<string, unknown>;
+    };
     expect(started.payload["idempotencyKey"]).toBe("id:abc");
   });
 });
 
 describe("userOnboardingWorkflow (end-to-end, in-memory)", () => {
   it("suspends on the first wait, then resume-loop runs it through to completion", async () => {
-    const ctx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const ctx = { events: { unsafeAppend: mock().mockResolvedValue(undefined) } };
     const trigger = {
       aggregateId: "agg_user_42",
       type: "user.signed-up",
@@ -469,16 +471,16 @@ describe("userOnboardingWorkflow (end-to-end, in-memory)", () => {
 
     expect(result.outcome).toBe("suspended");
     // Calls: run.started, mail.send dispatch-requested, workflow.step.waiting
-    expect(ctx.unsafeAppendEvent).toHaveBeenCalledTimes(3);
-    const startedCall = ctx.unsafeAppendEvent.mock.calls[0]![0] as {
+    expect(ctx.events.unsafeAppend).toHaveBeenCalledTimes(3);
+    const startedCall = ctx.events.unsafeAppend.mock.calls[0]![0] as {
       type: string;
       payload: Record<string, unknown>;
     };
-    const mailCall = ctx.unsafeAppendEvent.mock.calls[1]![0] as {
+    const mailCall = ctx.events.unsafeAppend.mock.calls[1]![0] as {
       type: string;
       payload: Record<string, unknown>;
     };
-    const waitingCall = ctx.unsafeAppendEvent.mock.calls[2]![0] as {
+    const waitingCall = ctx.events.unsafeAppend.mock.calls[2]![0] as {
       type: string;
       payload: Record<string, unknown>;
     };
@@ -514,7 +516,7 @@ describe("userOnboardingWorkflow (end-to-end, in-memory)", () => {
       definitionFingerprint: waitingCall.payload["definitionFingerprint"] as string,
     };
 
-    const resumeCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const resumeCtx = { events: { unsafeAppend: mock().mockResolvedValue(undefined) } };
     const count = await runResumeLoop(
       createInMemorySuspendedRunFetcher([suspendedRun]),
       resumeCtx as never,
@@ -525,7 +527,7 @@ describe("userOnboardingWorkflow (end-to-end, in-memory)", () => {
     // because userId starts with "active-"), second WAITING for P7D.
     // The run is suspended again before the webhook, so no RUN_COMPLETED
     // yet — this is one resume-cycle, not the whole workflow.
-    const resumeTypes = resumeCtx.unsafeAppendEvent.mock.calls.map(
+    const resumeTypes = resumeCtx.events.unsafeAppend.mock.calls.map(
       (c) => (c[0] as { type: string }).type,
     );
     expect(resumeTypes).toEqual([
@@ -533,14 +535,14 @@ describe("userOnboardingWorkflow (end-to-end, in-memory)", () => {
       "kumiko:system:step.dispatch-requested",
       "kumiko:system:workflow.step.waiting",
     ]);
-    const tipsMail = resumeCtx.unsafeAppendEvent.mock.calls[1]![0] as {
+    const tipsMail = resumeCtx.events.unsafeAppend.mock.calls[1]![0] as {
       payload: { subject: string };
     };
     expect(tipsMail.payload.subject).toBe("Engagement tips");
   });
 
   it("not-engaged path picks the reminder branch", async () => {
-    const ctx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const ctx = { events: { unsafeAppend: mock().mockResolvedValue(undefined) } };
     const trigger = {
       aggregateId: "agg_user_cold",
       type: "user.signed-up",
@@ -553,7 +555,9 @@ describe("userOnboardingWorkflow (end-to-end, in-memory)", () => {
       triggerEventRef: { eventId: "2", aggregateId: trigger.aggregateId, version: 1 },
       handlerCtx: ctx as never,
     });
-    const waiting = ctx.unsafeAppendEvent.mock.calls[2]![0] as { payload: Record<string, unknown> };
+    const waiting = ctx.events.unsafeAppend.mock.calls[2]![0] as {
+      payload: Record<string, unknown>;
+    };
     const suspendedRun: SuspendableRun = {
       runId: "wf-onboarding-cold-1",
       workflowName: "user-onboarding",
@@ -564,10 +568,10 @@ describe("userOnboardingWorkflow (end-to-end, in-memory)", () => {
       triggerEvent: trigger as never,
       definitionFingerprint: waiting.payload["definitionFingerprint"] as string,
     };
-    const resumeCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const resumeCtx = { events: { unsafeAppend: mock().mockResolvedValue(undefined) } };
     await runResumeLoop(createInMemorySuspendedRunFetcher([suspendedRun]), resumeCtx as never);
 
-    const reminderMail = resumeCtx.unsafeAppendEvent.mock.calls[1]![0] as {
+    const reminderMail = resumeCtx.events.unsafeAppend.mock.calls[1]![0] as {
       payload: { subject: string };
     };
     expect(reminderMail.payload.subject).toBe("Getting started");
@@ -696,7 +700,7 @@ describe("cron-scheduler", () => {
       steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
     });
 
-    const handlerCtx = { unsafeAppendEvent: mock() };
+    const handlerCtx = { events: { unsafeAppend: mock() } };
     const lastRuns = new Map<string, Temporal.Instant>();
     const now = Temporal.Instant.from("2025-06-01T08:00:00Z");
 
@@ -708,7 +712,7 @@ describe("cron-scheduler", () => {
     );
 
     expect(count).toBe(0);
-    expect(handlerCtx.unsafeAppendEvent).not.toHaveBeenCalled();
+    expect(handlerCtx.events.unsafeAppend).not.toHaveBeenCalled();
   });
 
   it("runDueCronWorkflows runs due workflows through the full start path", async () => {
@@ -718,7 +722,7 @@ describe("cron-scheduler", () => {
       steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
     });
 
-    const handlerCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const handlerCtx = { events: { unsafeAppend: mock().mockResolvedValue(undefined) } };
     const lastRuns = new Map<string, Temporal.Instant>();
     const lastRun = Temporal.Instant.from("2025-05-31T08:00:00Z");
     lastRuns.set("test-daily", lastRun);
@@ -733,10 +737,10 @@ describe("cron-scheduler", () => {
 
     expect(count).toBe(1);
     // run.started + run-completed (no suspension, pipeline returns immediately).
-    expect(handlerCtx.unsafeAppendEvent).toHaveBeenCalledTimes(2);
-    const started = handlerCtx.unsafeAppendEvent.mock.calls[0]![0] as Record<string, unknown>;
+    expect(handlerCtx.events.unsafeAppend).toHaveBeenCalledTimes(2);
+    const started = handlerCtx.events.unsafeAppend.mock.calls[0]![0] as Record<string, unknown>;
     expect(started["type"]).toBe("kumiko:system:workflow.run-started");
-    const completed = handlerCtx.unsafeAppendEvent.mock.calls[1]![0] as Record<string, unknown>;
+    const completed = handlerCtx.events.unsafeAppend.mock.calls[1]![0] as Record<string, unknown>;
     expect(completed["type"]).toBe("kumiko:system:workflow.run-completed");
   });
 });
@@ -744,12 +748,12 @@ describe("cron-scheduler", () => {
 describe("resume-loop", () => {
   it("returns 0 when no suspended runs exist", async () => {
     const fetchRuns = createInMemorySuspendedRunFetcher([]);
-    const handlerCtx = { unsafeAppendEvent: mock() };
+    const handlerCtx = { events: { unsafeAppend: mock() } };
 
     const count = await runResumeLoop(fetchRuns, handlerCtx as never);
 
     expect(count).toBe(0);
-    expect(handlerCtx.unsafeAppendEvent).not.toHaveBeenCalled();
+    expect(handlerCtx.events.unsafeAppend).not.toHaveBeenCalled();
   });
 
   it("resumes a suspended run", async () => {
@@ -766,19 +770,19 @@ describe("resume-loop", () => {
     };
 
     const fetchRuns = createInMemorySuspendedRunFetcher([suspendedRun]);
-    const handlerCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const handlerCtx = { events: { unsafeAppend: mock().mockResolvedValue(undefined) } };
 
     const count = await runResumeLoop(fetchRuns, handlerCtx as never);
 
     expect(count).toBe(1);
-    expect(handlerCtx.unsafeAppendEvent).toHaveBeenCalledTimes(2);
-    expect(handlerCtx.unsafeAppendEvent).toHaveBeenNthCalledWith(1, {
+    expect(handlerCtx.events.unsafeAppend).toHaveBeenCalledTimes(2);
+    expect(handlerCtx.events.unsafeAppend).toHaveBeenNthCalledWith(1, {
       aggregateId: "wf-test-run_123",
       aggregateType: "workflow-run",
       type: "kumiko:system:workflow.step.resumed",
       payload: { stepIndex: 0, retryAttempt: undefined },
     });
-    expect(handlerCtx.unsafeAppendEvent).toHaveBeenNthCalledWith(2, {
+    expect(handlerCtx.events.unsafeAppend).toHaveBeenNthCalledWith(2, {
       aggregateId: "wf-test-run_123",
       aggregateType: "workflow-run",
       type: "kumiko:system:workflow.run-completed",
@@ -800,13 +804,13 @@ describe("resume-loop", () => {
     };
 
     const fetchRuns = createInMemorySuspendedRunFetcher([suspendedRun]);
-    const handlerCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const handlerCtx = { events: { unsafeAppend: mock().mockResolvedValue(undefined) } };
 
     const count = await runResumeLoop(fetchRuns, handlerCtx as never);
 
     expect(count).toBe(0);
-    expect(handlerCtx.unsafeAppendEvent).toHaveBeenCalledTimes(1);
-    const failed = handlerCtx.unsafeAppendEvent.mock.calls[0]![0] as {
+    expect(handlerCtx.events.unsafeAppend).toHaveBeenCalledTimes(1);
+    const failed = handlerCtx.events.unsafeAppend.mock.calls[0]![0] as {
       type: string;
       payload: Record<string, unknown>;
     };
@@ -830,16 +834,18 @@ describe("resume-loop", () => {
 
     const fetchRuns = createInMemorySuspendedRunFetcher([suspendedRun]);
     const handlerCtx = {
-      unsafeAppendEvent: mock()
-        .mockRejectedValueOnce(new VersionConflictError("wf-conflict-run", 1))
-        .mockResolvedValue(undefined),
+      events: {
+        unsafeAppend: mock()
+          .mockRejectedValueOnce(new VersionConflictError("wf-conflict-run", 1))
+          .mockResolvedValue(undefined),
+      },
     };
 
     const count = await runResumeLoop(fetchRuns, handlerCtx as never);
 
     expect(count).toBe(0);
-    expect(handlerCtx.unsafeAppendEvent).toHaveBeenCalledTimes(1);
-    expect((handlerCtx.unsafeAppendEvent.mock.calls[0]![0] as { type: string }).type).toBe(
+    expect(handlerCtx.events.unsafeAppend).toHaveBeenCalledTimes(1);
+    expect((handlerCtx.events.unsafeAppend.mock.calls[0]![0] as { type: string }).type).toBe(
       "kumiko:system:workflow.step.resumed",
     );
   });
@@ -1509,7 +1515,7 @@ export async function runResumeLoop(
     if (run.definitionFingerprint !== undefined) {
       const currentFingerprint = computeDefinitionFingerprint(run.workflow);
       if (currentFingerprint !== run.definitionFingerprint) {
-        await handlerCtx.unsafeAppendEvent({
+        await handlerCtx.events.unsafeAppend({
           aggregateId: run.runId,
           aggregateType: WORKFLOW_AGGREGATE_TYPE,
           type: WORKFLOW_RUN_FAILED_TYPE,
@@ -1537,7 +1543,7 @@ export async function runResumeLoop(
     // no FAILED-event. Stale WAITING-rows in the fetcher result also
     // hit this branch on the second poll-tick.
     try {
-      await handlerCtx.unsafeAppendEvent({
+      await handlerCtx.events.unsafeAppend({
         aggregateId: run.runId,
         aggregateType: WORKFLOW_AGGREGATE_TYPE,
         type: WORKFLOW_RESUMED_TYPE,
@@ -1589,7 +1595,7 @@ export async function runResumeLoop(
       // returned. A second suspension (e.g. `wait` further down the
       // pipeline) leaves the run pending for the next resume-loop tick.
       if (outcome.kind !== "suspended") {
-        await handlerCtx.unsafeAppendEvent({
+        await handlerCtx.events.unsafeAppend({
           aggregateId: run.runId,
           aggregateType: WORKFLOW_AGGREGATE_TYPE,
           type: WORKFLOW_RUN_COMPLETED_TYPE,
@@ -1606,7 +1612,7 @@ export async function runResumeLoop(
         stepIndex: run.stepIndex,
         error: String(error),
       });
-      await handlerCtx.unsafeAppendEvent({
+      await handlerCtx.events.unsafeAppend({
         aggregateId: run.runId,
         aggregateType: WORKFLOW_AGGREGATE_TYPE,
         type: WORKFLOW_RUN_FAILED_TYPE,
@@ -1697,7 +1703,7 @@ export async function startAndRunWorkflow(args: {
     ...(args.idempotencyKey && { idempotencyKey: args.idempotencyKey }),
   };
 
-  await args.handlerCtx.unsafeAppendEvent({
+  await args.handlerCtx.events.unsafeAppend({
     aggregateId: args.runId,
     aggregateType: WORKFLOW_AGGREGATE_TYPE,
     type: WORKFLOW_RUN_STARTED_TYPE,
@@ -1724,7 +1730,7 @@ export async function startAndRunWorkflow(args: {
     return { outcome: "suspended" };
   }
 
-  await args.handlerCtx.unsafeAppendEvent({
+  await args.handlerCtx.events.unsafeAppend({
     aggregateId: args.runId,
     aggregateType: WORKFLOW_AGGREGATE_TYPE,
     type: WORKFLOW_RUN_COMPLETED_TYPE,

package/agents/examples.md

@@ -19,7 +19,7 @@
 | `chat-channels` | Chat channels. Delivery notifications to Slack, minus the browser tab. | `examples/chat-channels.md` |
 | `compliance-profiles-demo` | Two-tenant demo: EU + Swiss compliance profiles deliver different authority contacts, languages, and grace periods through the same App-code. | `examples/compliance-profiles-demo.md` |
 | `compose-stacks` | compose*Stack helpers for auth, security, GDPR and SaaS billing, and the runProdApp check that names a stack whose boot option is missing. | `examples/compose-stacks.md` |
-| `cross-feature-events` | Feature appends a typed domain event via ctx.appendEvent; a r.multiStreamProjection reacts asynchronously. | `examples/cross-feature-events.md` |
+| `cross-feature-events` | Feature appends a typed domain event via ctx.events.append; a r.multiStreamProjection reacts asynchronously. | `examples/cross-feature-events.md` |
 | `crypto-shredding-hr` | Crypto-shredding: PII fields encrypted per subject key; forgetting the subject erases the key and every field it protected. | `examples/crypto-shredding-hr.md` |
 | `currencies-global` | Shared money fields across tenants. Commas still matter. | `examples/currencies-global.md` |
 | `currencies-per-tenant` | Tenant-scoped money fields. Commas matter. | `examples/currencies-per-tenant.md` |
@@ -34,20 +34,21 @@
 | `encrypted-tenant-config` | Per-tenant secrets via config-key encryption — Stripe-API-key pattern. | `examples/encrypted-tenant-config.md` |
 | `env-composition` | Typed app env from the env blocks bundled features register, plus app-level blocks in extend. | `examples/env-composition.md` |
 | `error-contract` | Typed errors on the wire. With snake_case reasons, because we care. | `examples/error-contract.md` |
-| `event-sourcing` | Production-pattern ES sample: r.defineEvent (versioned + migrations) + ctx.appendEvent + r.projection + r.multiStreamProjection + ctx.loadAggregate (asOf) + ctx.archiveStream + ctx.queryProjection. | `examples/event-sourcing.md` |
+| `event-sourcing` | Production-pattern ES sample: r.defineEvent (versioned + migrations) + ctx.events.append + r.projection + r.multiStreamProjection + ctx.events.load (asOf) + ctx.events.archive + ctx.dispatch.queryProjection. | `examples/event-sourcing.md` |
 | `feature-toggles` | Runtime feature-toggle flip — two toggleable features, one registers a cross-feature hook on the other; disabling either has the documented effect without reboot. | `examples/feature-toggles.md` |
 | `field-access` | Field-level access control. When entity-level roles aren't granular enough. | `examples/field-access.md` |
-| `files-post-processing` | The three ways to generate an image variant: declarative field variants, imperative ctx.derivatives.variant() with region-blur, and the public route behind a default-deny predicate. | `examples/files-post-processing.md` |
+| `files-post-processing` | The three ways to generate an image variant: declarative field variants, imperative ctx.services.derivatives.variant() with region-blur, and the public route behind a default-deny predicate. | `examples/files-post-processing.md` |
 | `golden-path` | The smallest complete feature: entity, write handler, event, projection, screen and an integration test. | `examples/golden-path.md` |
 | `host-routing` | createHostRoutingFeature + createHostDispatch — tenant per subdomain, per-host HTML and CSP, locale redirect, shared by runProdApp and the dev server. | `examples/host-routing.md` |
 | `i18n` | Feature-scoped translations. 'Hallo' and 'Hello' in the same app. | `examples/i18n.md` |
 | `idempotency` | Same request, same result. Dedupes on request ID. | `examples/idempotency.md` |
 | `inbound-mail-triage` | Inbound-mail consumer pattern: inbound-mail-foundation + in-memory provider, a worker-lane triage job attached to the ingest handler, verified end-to-end through createAllInOneEntrypoint. | `examples/inbound-mail-triage.md` |
-| `lane-routing` | runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.appendEvent, verified end-to-end through createAllInOneEntrypoint. | `examples/lane-routing.md` |
+| `lane-routing` | runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.events.append, verified end-to-end through createAllInOneEntrypoint. | `examples/lane-routing.md` |
 | `ledger-banking` | Bank accounts + transfers on the ledger primitive — balances are pure queries, never stored. | `examples/ledger-banking.md` |
 | `ledger-invoicing` | Accrual invoicing on the ledger primitive — revenue at invoice time, VAT as a liability, receivable cleared on payment. | `examples/ledger-invoicing.md` |
 | `legal-pages` | Auto-rendered Impressum + Datenschutzerklärung pages — template-resolver + legal-pages bundled features wired up with anonymousAccess for DACH-compliance. | `examples/legal-pages.md` |
 | `lifecycle-hooks` | preSave, postSave, and the rest. Your logic, our plumbing. | `examples/lifecycle-hooks.md` |
+| `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. | `examples/list-table-options.md` |
 | `managed-config` | Managed config: one declaration provisions storage + masking + settings-hub, across backings (secrets vs config) and scopes (system vs tenant). | `examples/managed-config.md` |
 | `managed-pages` | Tenant-editable, server-rendered public pages with per-tenant branding + tier-gated sanitized custom CSS — managed-pages wired up with config + anonymousAccess. | `examples/managed-pages.md` |
 | `notes-history-basic` | Append-only note history — who wrote what, when — attached to any entity without changing it. | `examples/notes-history-basic.md` |

package/agents/features.md

@@ -257,7 +257,7 @@ Category: operations
 
 ## file-derivatives
 
-Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: "ip"`) depends on the server's `trustedProxyHops` matching the deployment's actual reverse-proxy count — at the default 0 it ignores `x-forwarded-for` entirely, so every caller shares one bucket until that's configured. `publicTenantResolution: "fileRef"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.
+Declares the `derivativeRenderer` extension point. `ctx.services.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: "ip"`) depends on the server's `trustedProxyHops` matching the deployment's actual reverse-proxy count — at the default 0 it ignores `x-forwarded-for` entirely, so every caller shares one bucket until that's configured. `publicTenantResolution: "fileRef"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.
 
 Category: storage
 

package/agents/widgets.md

@@ -143,6 +143,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `buildFileUploadFormData` |  |
 | `buildNavRegistrySlice` |  |
 | `buildNavRegistrySliceForApp` |  |
+| `clearRememberedListState` | Forgets all remembered list state and the identity marker. |
 | `cn` | Standard shadcn helper: `clsx` combines conditional classes, while `tailwind-merge` resolves conflicts (for example, `px-2 px-4` → `px-4`). |
 | `createBrowserDraftStorage` | Default DraftStorage when createKumikoApp boots without one. |
 | `createBrowserLocaleResolver` | Default resolver when createKumikoApp is booted without a `locale` option. |

package/dist/api/api-constants.d.ts

@@ -8,6 +8,7 @@ export declare const Routes: {
     readonly command: "/command";
     readonly sse: "/sse";
     readonly stream: "/stream";
+    readonly exportXlsx: "/export/xlsx";
     readonly auth: "/auth";
     readonly authLogin: "/auth/login";
     readonly authMfaVerify: "/auth/mfa/verify";

package/dist/api/api-constants.js

@@ -10,6 +10,7 @@ export const Routes = {
     command: "/command",
     sse: "/sse",
     stream: "/stream",
+    exportXlsx: "/export/xlsx",
     auth: "/auth",
     authLogin: "/auth/login",
     authMfaVerify: "/auth/mfa/verify",
@@ -76,6 +77,7 @@ export const NON_PUBLIC_API_PATHS = new Set([
     `/api${Routes.command}`,
     `/api${Routes.sse}`,
     `/api${Routes.stream}`,
+    `/api${Routes.exportXlsx}`,
     // Namespace prefix used only for body-limit registration
     // (`/api/auth/*` in route-registrars.ts) — never dispatched as its own
     // route, so it carries no auth bypass either way. Classified non-public

package/dist/api/auth-middleware.js

@@ -5,7 +5,7 @@ import { createAnonymousUser } from "../engine/system-user.js";
 import { parseTenantId, SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { isSessionRequiredApiPath, TENANT_HEADER_NAME } from "./api-constants.js";
 import { isForeignCookieOrigin } from "./origin-middleware.js";
-import { setRequestIdentity } from "./request-context.js";
+import { setRequestIdentity } from "./request-context-internals.js";
 import { clearSessionCookies, getSessionCookies, hasDuplicateSessionCookie, } from "./session-cookies.js";
 const USER_KEY = "pipelineUser";
 const AUTH_TRANSPORT_KEY = "authTransport";

package/dist/api/auth-routes-invite.js

@@ -1,7 +1,8 @@
 import * as z from "zod";
 import { createAnonymousUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
-import { toKumikoError, toWriteErrorInfo } from "../errors/index.js";
+import { toKumikoError } from "../errors/to-kumiko-error.js";
+import { toWriteErrorInfo } from "../errors/write-error-info.js";
 import { Routes } from "./api-constants.js";
 import { getUser } from "./auth-middleware.js";
 import { pendingMfaStepResponse } from "./auth-routes-shared.js";

package/dist/api/auth-routes-shared.d.ts

@@ -8,6 +8,7 @@ export declare const SignupRequestBody: z.ZodObject<{
         entityType: z.ZodString;
         token: z.ZodString;
     }, z.core.$strip>>;
+    returnTo: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
 export declare function isUnknownHandlerError(e: unknown): boolean;
 export type PendingMfaStep = {
@@ -29,5 +30,6 @@ export declare function registerTokenRequestRoute(opts: {
 }): void;
 declare const RequestTokenBody: z.ZodObject<{
     email: z.ZodEmail;
+    returnTo: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
 export {};

package/dist/api/auth-routes-shared.js

@@ -4,6 +4,9 @@ import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
 import { NotFoundError } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
 const log = createFallbackLogger("kumiko");
+// Content is checked where the mail link is built (bundled-features knows the path rules); a bad
+// value must never void the whole body, or the request would silently send no mail.
+const returnToField = z.string().max(2048).optional().catch(undefined);
 // Cross-device try-first handover: an optional tenant-handover grant the signup-request
 // route forwards to the handler for server-side verification and binding —
 // the grant itself never appears anywhere else (URL, mail, log, response).
@@ -15,6 +18,7 @@ export const SignupRequestBody = z.object({
         token: z.string().min(1).max(4096),
     })
         .optional(),
+    returnTo: returnToField,
 });
 // Shape guard for "handler not registered" — the only legitimate reason to
 // fall back to a single-tenant reply on /auth/tenants or /auth/switch-tenant.
@@ -82,4 +86,5 @@ export function registerTokenRequestRoute(opts) {
 // gains optional fields (locale, deviceId, …).
 const RequestTokenBody = z.object({
     email: z.email(),
+    returnTo: returnToField,
 });

package/dist/api/client-error-route.js

@@ -73,6 +73,8 @@ export function createClientErrorRoute(options) {
     const app = new Hono();
     const logger = createFallbackLogger("client-errors");
     const routePath = `/api${Routes.clientErrors}`;
+    // Always on: the shared limiter fails open when Redis is down, this per-process window is the floor.
+    app.post(Routes.clientErrors, inMemoryIpRateLimit(options.clientIpResolver, options.now ?? Date.now));
     if (options.resolver) {
         app.post(Routes.clientErrors, httpRouteRateLimit({
             resolver: options.resolver,
@@ -82,9 +84,6 @@ export function createClientErrorRoute(options) {
             ...(options.meter && { meter: options.meter }),
         }));
     }
-    else {
-        app.post(Routes.clientErrors, inMemoryIpRateLimit(options.clientIpResolver, options.now ?? Date.now));
-    }
     app.post(Routes.clientErrors, bodyLimit({
         maxSize: MAX_BODY_BYTES,
         onError: (c) => c.json({ error: { code: "payload_too_large" } }, 413),

package/dist/api/entity-read-access.d.ts

@@ -1,2 +1,5 @@
-import type { AccessRule, Registry } from "../engine/types/index.ts";
+import type { AccessRule } from "@cosmicdrift/kumiko-types/handlers";
+import type { OwnershipMap } from "@cosmicdrift/kumiko-types/ownership";
+import type { Registry } from "../engine/types/index.ts";
 export declare function collectEntityReadAccess(registry: Registry): ReadonlyMap<string, readonly AccessRule[]>;
+export declare function collectEntityRowReadMaps(registry: Registry): ReadonlyMap<string, OwnershipMap>;

package/dist/api/entity-read-access.js

@@ -25,3 +25,17 @@ export function collectEntityReadAccess(registry) {
     }
     return rulesByEntity;
 }
+// Entities whose own access.read narrows rows per role (e.g. Driver sees only assigned rows).
+// A signal for such an entity must not name ids to a role that does not read every row.
+export function collectEntityRowReadMaps(registry) {
+    const mapsByEntity = new Map();
+    for (const [entityName, entity] of registry.getAllEntities()) {
+        const readMap = entity.access?.read;
+        if (readMap === undefined || Object.keys(readMap).length === 0)
+            continue;
+        for (const aggregateType of new Set([entityName, toKebabCase(entityName)])) {
+            mapsByEntity.set(aggregateType, readMap);
+        }
+    }
+    return mapsByEntity;
+}

package/dist/api/export/export-cells-reference.d.ts

@@ -0,0 +1,9 @@
+import type { Cell } from "write-excel-file/node";
+import type { ExportRow } from "./export-rows.ts";
+export type ReferenceCellKind = {
+    readonly kind: "reference";
+    readonly labelField: string;
+    readonly multiple: boolean;
+};
+/** Labels come from the list row's eager-loaded `_refs`; a missing target shows its raw id. */
+export declare function referenceCell(cell: ReferenceCellKind, field: string, row: ExportRow): Cell;

package/dist/api/export/export-cells-reference.js

@@ -0,0 +1,21 @@
+import { isPlainObject } from "../../utils/is-plain-object.js";
+function labelOf(ref, labelField) {
+    if (!isPlainObject(ref))
+        return undefined;
+    const label = ref[labelField];
+    return typeof label === "string" ? label : undefined;
+}
+function refsOf(row, field) {
+    const refs = row["_refs"];
+    return isPlainObject(refs) ? refs[field] : undefined;
+}
+/** Labels come from the list row's eager-loaded `_refs`; a missing target shows its raw id. */
+export function referenceCell(cell, field, row) {
+    const ids = cell.multiple && Array.isArray(row[field]) ? row[field] : [row[field]];
+    const ref = refsOf(row, field);
+    const labels = ids.map((id) => {
+        const target = Array.isArray(ref) ? ref.find((r) => isPlainObject(r) && r["id"] === id) : ref;
+        return labelOf(target, cell.labelField) ?? String(id);
+    });
+    return { value: labels.join(", "), type: String };
+}

package/dist/api/export/export-cells.d.ts

@@ -0,0 +1,11 @@
+import type { Cell } from "write-excel-file/node";
+import type { ExportColumn } from "./export-columns.ts";
+import type { ExportRow } from "./export-rows.ts";
+export type Translate = (key: string) => string;
+export type ExportCellContext = {
+    readonly row: ExportRow;
+    readonly translate: Translate;
+    readonly timeZone: string;
+};
+/** Never emits a formula cell and never reinterprets strings: text always stays text. */
+export declare function toExportCell(column: ExportColumn, context: ExportCellContext): Cell;