@cosmicdrift/kumiko-framework 0.389.0 → 0.390.1

package/agents/examples/managed-pages.md

@@ -212,7 +212,7 @@ beforeAll(async () => {
     // Wire ctx.config() so the branding query resolves the tenant's cascade.
     extraContext: ({ registry }) => ({
       configResolver: resolver,
-      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      configAccessorFactory: createConfigAccessorFactory(registry, resolver),
     }),
   });
   await unsafeCreateEntityTable(stack.db, pageEntity);

package/agents/examples/relations.md

@@ -38,7 +38,12 @@ bun test
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  attachOutsideTransaction,
+  bridgeStub,
+  type HandlerContext,
+  type SaveContext,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createCascadeDeleteHook } from "@cosmicdrift/kumiko-framework/pipeline";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
@@ -77,6 +82,16 @@ beforeEach(() => {
   stack.events.reset();
 });
 
+// The cascade hook runs against the same tenant-scoped db a dispatcher would hand it.
+function hookContext(): HandlerContext {
+  const db = createTenantDb({ db: stack.db, tenantId: admin.tenantId });
+  return {
+    ...bridgeStub({ user: admin }),
+    registry: stack.registry,
+    db: attachOutsideTransaction(db, undefined),
+  };
+}
+
 describe("restrict: team cannot be deleted with members", () => {
   test("delete team with members fails", async () => {
     const team = await stack.http.writeOk<SaveContext>(
@@ -105,7 +120,7 @@ describe("restrict: team cannot be deleted with members", () => {
           entityName: "team",
           event: createTestStoredEvent(),
         },
-        { db: stack.db },
+        hookContext(),
       ),
     ).rejects.toMatchObject({ code: "conflict", details: { reason: "delete_restricted" } });
   });
@@ -128,7 +143,7 @@ describe("restrict: team cannot be deleted with members", () => {
           entityName: "team",
           event: createTestStoredEvent(),
         },
-        { db: stack.db },
+        hookContext(),
       ),
     ).resolves.toBeUndefined();
   });
@@ -178,7 +193,7 @@ describe("cascade: deleting member removes tasks", () => {
         entityName: "member",
         event: createTestStoredEvent(),
       },
-      { db: createTenantDb({ db: stack.db, tenantId: admin.tenantId }) },
+      hookContext(),
     );
 
     // Tasks should be gone

package/agents/examples/search.md

@@ -13,7 +13,7 @@ Tenant-scoped full-text search (Meilisearch / in-memory adapter).
 ## What it shows
 
 - `searchable` / `searchWeight` on fields
-- Handler reads via `ctx.searchAdapter`
+- Handler reads via `ctx.services.searchAdapter`
 
 ## Source
 
@@ -160,7 +160,7 @@ describe("search indexing", () => {
 ```ts
 // Search Sample
 // Shows: searchable fields, searchWeight, search via InMemory SearchAdapter.
-// Each handler builds its executor inline so `ctx.searchAdapter` is read fresh
+// Each handler builds its executor inline so `ctx.services.searchAdapter` is read fresh
 // per call — tests swap the adapter between runs.
 
 import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
@@ -198,7 +198,7 @@ export const productFeature = defineFeature("shop", (r) => {
     }),
     handler: async (event, ctx) => {
       const crud = createEventStoreExecutor(productTable, productEntity, {
-        searchAdapter: ctx.searchAdapter,
+        searchAdapter: ctx.services.searchAdapter,
         entityName: "product",
       });
       return crud.create(event.payload, event.user, ctx.db);
@@ -214,7 +214,7 @@ export const productFeature = defineFeature("shop", (r) => {
     }),
     handler: async (query, ctx) => {
       const crud = createEventStoreExecutor(productTable, productEntity, {
-        searchAdapter: ctx.searchAdapter,
+        searchAdapter: ctx.services.searchAdapter,
         entityName: "product",
       });
       return crud.list(query.payload, query.user, ctx.db);

package/agents/examples/secrets-demo.md

@@ -12,7 +12,7 @@ Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation.
 
 ## What it shows
 
-- `r.secret` + `ctx.secrets.get` (audited reads)
+- `r.secret` + `ctx.services.secrets.get` (audited reads)
 - Charge-style handler that never returns the plaintext key
 
 ## Source
@@ -39,7 +39,7 @@ bun test
 // function calls into framework internals):
 //   1. A TenantAdmin sets a secret over HTTP → DB holds only an envelope.
 //   2. list handler returns a redacted preview, never plaintext.
-//   3. Feature code (ctx.secrets.get) decrypts through the audited wrapper.
+//   3. Feature code (ctx.services.secrets.get) decrypts through the audited wrapper.
 //      Every read writes a tenantSecretRead event to the events-table.
 //   4. The response-guard catches accidental Secret<> leaks: a handler
 //      that tries to return the branded value triggers a 500 at the
@@ -129,7 +129,7 @@ beforeAll(async () => {
     features: [createJobsFeature(), createSecretsFeature(), createBillingFeature(), leakyFeature],
     // Typed masterKeyProvider option: lands in AppContext as a typed field,
     // no Record<string, unknown>-via-extraContext. The rotation job reads
-    // it from ctx.masterKeyProvider directly.
+    // it from ctx.services.masterKeyProvider directly.
     masterKeyProvider: providerRef,
     extraContext: ({ db, registry }) => ({
       // SecretsContext sees the mutable ref — any replace() flips what
@@ -299,7 +299,7 @@ describe("5. KEK rotation via the core job + real BullMQ dispatch", () => {
 
   test("subsequent ctx.secrets.get after rotation still returns the original plaintext", async () => {
     // Goes through the whole real stack: HTTP → dispatcher → billing
-    // handler → ctx.secrets.get → cached DEK-unwrap with V2 → decrypt.
+    // handler → ctx.services.secrets.get → cached DEK-unwrap with V2 → decrypt.
     // If rotation broke anything, fingerprint would differ or the call
     // would throw.
     const result = await stack.http.writeOk<{ keyFingerprint: string }>(
@@ -328,7 +328,7 @@ describe("5. KEK rotation via the core job + real BullMQ dispatch", () => {
 ### src/feature.ts
 
 ```ts
-// A miniature "billing" feature that reads a Stripe API key from ctx.secrets
+// A miniature "billing" feature that reads a Stripe API key from ctx.services.secrets
 // and simulates a charge. The point is to show how feature code uses the
 // plaintext secret without ever exposing it to clients — the charge endpoint
 // returns { chargeId } but never the apiKey.
@@ -357,7 +357,10 @@ const chargeWrite = defineWriteHandler({
   }),
   access: { roles: ["TenantAdmin", "User"] },
   handler: async (event, ctx) => {
-    const secrets = requireSecretsContext(ctx, "billing:write:charge");
+    const secrets = requireSecretsContext(
+      { secrets: ctx.services.secrets, user: ctx.user },
+      "billing:write:charge",
+    );
     // requireSecretsContext returned a wrapper that auto-fills the audit
     // context (userId + "billing:write:charge") on every .get — the read
     // lands in tenant_secret_reads without the handler having to remember.

package/agents/examples/state-machine.md

@@ -510,7 +510,7 @@ export const INVOICE_EVENTS = {
 // Qualifier used by the reducer to match events from the stream.
 // `<const TShort>` preserves the literal-string at the call-site, so
 // `eventName(INVOICE_EVENTS.sent)` carries `"billing:event:invoice-sent"`
-// as a literal type. That literal is what `ctx.appendEvent({ type, ... })`
+// as a literal type. That literal is what `ctx.events.append({ type, ... })`
 // strict-checks against the augmented `KumikoEventTypeMap`.
 export function eventName<const TShort extends string>(
   short: TShort,
@@ -927,7 +927,7 @@ export async function loadInvoiceState(
   ctx: HandlerContext,
   id: string,
 ): Promise<InvoiceState | null> {
-  const events = await ctx.loadAggregate(id);
+  const events = await ctx.events.load(id);
   if (events.length === 0) return null;
   const state: InvoiceState = { ...initialInvoiceState };
   for (const evt of events) reduceInvoice(state, evt);

package/agents/examples/tenant-settings.md

@@ -158,7 +158,7 @@ beforeAll(async () => {
     features: [createConfigFeature(), createTenantSettingsFeature(), invoiceFeature],
     extraContext: ({ registry }) => ({
       configResolver: resolver,
-      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      configAccessorFactory: createConfigAccessorFactory(registry, resolver),
     }),
   });
   await unsafePushTables(stack.db, { configValuesTable });

package/agents/examples/user-data-rights.md

@@ -173,7 +173,7 @@ import {
 import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
-import { seedRow } from "@cosmicdrift/kumiko-testing/helpers";
+import { seedRowViaEventStore } from "@cosmicdrift/kumiko-testing/helpers";
 import {
   setupTestStack,
   type TestStack,
@@ -183,8 +183,6 @@ import { noteEntity, notesFeature, notesTable } from "../feature";
 
 let stack: TestStack;
 
-const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
-
 // Each test gets its own tenant and user, so rows from other tests never show up.
 let testNumber = 0;
 let TENANT_A = "";
@@ -231,9 +229,8 @@ function noteId(index: number): string {
 }
 
 async function seedAlice(opts: { gracePeriodEnd?: Instant; status?: string } = {}): Promise<void> {
-  await seedRow(stack.db, userTable, {
+  await seedRowViaEventStore(stack.db, userTable, {
     id: ALICE_ID,
-    tenantId: TENANT_SYSTEM,
     email: ALICE_EMAIL,
     passwordHash: "h",
     displayName: "Alice",
@@ -243,7 +240,7 @@ async function seedAlice(opts: { gracePeriodEnd?: Instant; status?: string } = {
     status: opts.status ?? USER_STATUS.Active,
     gracePeriodEnd: opts.gracePeriodEnd ?? null,
   });
-  await seedRow(stack.db, tenantMembershipsTable, {
+  await seedRowViaEventStore(stack.db, tenantMembershipsTable, {
     tenantId: TENANT_A,
     userId: ALICE_ID,
     roles: '["Member"]',

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,16 +34,16 @@
 | `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` |

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/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/entity-read-access.d.ts

@@ -1,3 +1,5 @@
-import type { AccessRule, OwnershipMap, 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/export/export-columns.d.ts

@@ -1,4 +1,6 @@
-import type { EntityDefinition, ListColumnSpec, SessionUser } from "../../engine/types/index.ts";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import type { ListColumnSpec } from "@cosmicdrift/kumiko-types/screen";
+import type { SessionUser } from "../../engine/types/index.ts";
 import type { ReferenceCellKind } from "./export-cells-reference.ts";
 export type SimpleCellKind = "text" | "number" | "decimal" | "bigInt" | "money" | "date" | "timestamp" | "locatedTimestamp" | "boolean" | "auto";
 export type ExportCellKind = {