@cosmicdrift/kumiko-framework 0.389.0 → 0.390.0

package/AGENTS.md

@@ -76,7 +76,7 @@ Parents may belong to another feature; refer to them by QN.
 
 **Events.** Declare a domain event with `r.defineEvent(name, zodSchema)`.
 Emit it inside a write handler with `emitEvent(ctx, def, { ... })` or
-`ctx.appendEvent(...)`; it commits in the same transaction as the write.
+`ctx.events.append(...)`; it commits in the same transaction as the write.
 React to it with `r.projection(...)` (state on the same stream) or
 `r.multiStreamProjection({ name, apply })` (async consumer across streams,
 at least once, ordered).
@@ -195,7 +195,7 @@ produces code that compiles and then fails in production.
 - Never `INSERT`, `UPDATE` or `DELETE` on an entity table or the events
   table, and never call a raw database client for it. Write through a
   handler: `r.crud`, the `defineEntity*Handler` helpers, the executor from
-  `createEntityExecutor`, or `emitEvent` / `ctx.appendEvent`. The query
+  `createEntityExecutor`, or `emitEvent` / `ctx.events.append`. The query
   helpers and `ctx.db` throw `AccessDeniedError` on such a write, also
   through `ctx.db.unsafeRaw()`. Test seeds use `seedRow` / `deleteRows` from
   `@cosmicdrift/kumiko-testing`.
@@ -203,7 +203,12 @@ produces code that compiles and then fails in production.
   projection.
 - Never hand-write SQL for reads that an executor `list` or `detail` covers.
   Use `r.queryHandler` with the executor, or a projection with
-  `ctx.queryProjection`.
+  `ctx.dispatch.queryProjection`.
+- Never pass a JS array as a parameter to `.unsafe(sql, [...])`. Bun.SQL
+  binds it as `"a,b"` on Linux (CI) and passes on macOS, so `ANY($n)` only
+  fails in CI. Pass `toPostgresArrayLiteral(values)` from
+  `@cosmicdrift/kumiko-framework/db` and cast the placeholder (`$1::text[]`);
+  the Unsafe Array Param guard warns about array literals.
 - Never filter or count the rows of one `list` page in code. `list` returns
   one page (default 50, `limit` at most 200). Pass
   `filter: { field, op, value }` (`eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`)
@@ -305,7 +310,7 @@ as bundled features.
 | Public or anonymous endpoints | `anonymous` role | `agents/examples/anonymous-access.md` |
 | Allowed state changes | Entity transitions | `agents/examples/state-machine.md` |
 | React to a write in another feature | `r.defineEvent` + `emitEvent` + `r.multiStreamProjection` | `agents/examples/cross-feature-events.md` |
-| Projections, event versions, history | `r.projection`, `ctx.loadAggregate`, `ctx.queryProjection` | `agents/examples/event-sourcing.md` |
+| Projections, event versions, history | `r.projection`, `ctx.events.load`, `ctx.dispatch.queryProjection` | `agents/examples/event-sourcing.md` |
 | Before or after save logic | Lifecycle hooks | `agents/examples/lifecycle-hooks.md` |
 | Typed errors with reasons | `@cosmicdrift/kumiko-framework/errors` | `agents/examples/error-contract.md` |
 | Translations | `r.translations` + client translations | `agents/examples/i18n.md` |

package/README.md

@@ -108,7 +108,7 @@ export const taskFeature = defineFeature("tasks", (r) => {
 - **Event-sourced by default.** Every write goes through `createEventStoreExecutor`
   and appends a domain event to the aggregate stream. Auto-generated CRUD
   events (`<entity>.created/updated/deleted/restored`) for record writes,
-  explicit `ctx.appendEvent` for domain events with intent. Projections feed
+  explicit `ctx.events.append` for domain events with intent. Projections feed
   off the stream for same-TX read-after-write consistency.
 - **Async side-effects via cursor.** SSE broadcast, search indexing, and
   feature-registered `r.multiStreamProjection` consumers run on a single

package/agents/examples/apex-surface-auth.md

@@ -141,7 +141,7 @@ import type { SendDeletionVerificationEmailFn } from "@cosmicdrift/kumiko-bundle
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
-import { resetTestTables, seedRow } from "@cosmicdrift/kumiko-testing/helpers";
+import { resetTestTables, seedRowViaEventStore } from "@cosmicdrift/kumiko-testing/helpers";
 import {
   setupTestStack,
   type TestStack,
@@ -186,9 +186,8 @@ afterAll(async () => {
 beforeEach(async () => {
   verifyCalls.length = 0;
   await resetTestTables(stack.db, [userTable, tenantComplianceProfileTable, eventsTable]);
-  await seedRow(stack.db, userTable, {
+  await seedRowViaEventStore(stack.db, userTable, {
     id: user.id,
-    tenantId: tenant,
     email: EMAIL,
     passwordHash: "hashed",
     displayName: "User",

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

@@ -68,7 +68,8 @@ row and the `read_fulfillments` row appear.
 is re-run after `ms` on the same queue job: no retry attempt is used, no failure is logged
 or recorded, and the run log shows only the runs that actually executed. `maxDefers`
 (default 100) bounds it; beyond that the run fails. It needs a queued run: an inline boot
-gate throws.
+gate throws. `context.canDefer` is false in both cases, so the job checks it and calls the
+carrier anyway instead of failing.
 
 ## Test
 
@@ -257,6 +258,7 @@ describe("api-worker-split", () => {
   test("API-only: write lands, but the worker-applied read side stays empty", async () => {
     const prefix = uniquePrefix();
     const api = createApiEntrypoint({
+      rowLevelSecurity: "off",
       registry: createRegistry([createApiWorkerSplitFeature()]),
       context: { db: testDb.db, redis: testRedis.redis },
       jwtSecret: JWT,
@@ -288,12 +290,14 @@ describe("api-worker-split", () => {
   test("worker joins: consumes the job, applies the projection, writes the result back", async () => {
     const prefix = uniquePrefix();
     const api = createApiEntrypoint({
+      rowLevelSecurity: "off",
       registry: createRegistry([createApiWorkerSplitFeature()]),
       context: { db: testDb.db, redis: testRedis.redis },
       jwtSecret: JWT,
       jobs: { redisUrl: redisUrl(), queueNamePrefix: prefix },
     });
     const worker = createWorkerEntrypoint({
+      rowLevelSecurity: "off",
       registry: createRegistry([createApiWorkerSplitFeature()]),
       context: { db: testDb.db, redis: testRedis.redis },
       jwtSecret: JWT,
@@ -335,12 +339,14 @@ describe("api-worker-split", () => {
   test("a busy carrier defers the job without failing it, then the fulfillment lands", async () => {
     const prefix = uniquePrefix();
     const api = createApiEntrypoint({
+      rowLevelSecurity: "off",
       registry: createRegistry([createApiWorkerSplitFeature()]),
       context: { db: testDb.db, redis: testRedis.redis },
       jwtSecret: JWT,
       jobs: { redisUrl: redisUrl(), queueNamePrefix: prefix },
     });
     const worker = createWorkerEntrypoint({
+      rowLevelSecurity: "off",
       registry: createRegistry([createApiWorkerSplitFeature()]),
       context: { db: testDb.db, redis: testRedis.redis },
       jwtSecret: JWT,
@@ -508,8 +514,9 @@ export function createApiWorkerSplitFeature() {
         }
         const { customerName } = processOrderPayloadSchema.parse(payload);
         // Busy is not a failure: ctx.defer re-runs the job later without burning a retry.
+        // Once the defer budget is used up (or the run is inline), try anyway and let a failure retry.
         const retryAfterMs = carrierRetryAfterMs();
-        if (retryAfterMs > 0) return context.defer(retryAfterMs);
+        if (retryAfterMs > 0 && context.canDefer) return context.defer(retryAfterMs);
         const result = await fulfillWrite({
           handlerQn: "orders:write:fulfillment:create",
           payload: {

package/agents/examples/auth-claims.md

@@ -91,7 +91,7 @@ beforeEach(() => {
 });
 
 // The resolver needs an AuthClaimsContext per hook run. This sample doesn't
-// exercise ctx.db or ctx.queryAs — real features would, and that's the
+// exercise ctx.db or ctx.dispatch.queryAs — real features would, and that's the
 // point of the fresh TenantDb the dispatcher builds. A stub is fine here.
 const stubContext: AuthClaimsContext = {
   db: {} as AuthClaimsContext["db"],

package/agents/examples/cross-feature-events.md

@@ -2,7 +2,7 @@
 
 # cross-feature-events
 
-Feature appends a typed domain event via ctx.appendEvent; a r.multiStreamProjection reacts asynchronously.
+Feature appends a typed domain event via ctx.events.append; a r.multiStreamProjection reacts asynchronously.
 
 ## README
 
@@ -19,10 +19,10 @@ Three building blocks:
 
 - **`r.defineEvent("name", zodSchema)`** declares the name and payload.
   The qualified name (e.g. `pubsub-orders:event:order-placed`) comes
-  back as `.name` — pass it directly to `ctx.appendEvent`. Events that
-  aren't registered are rejected by `ctx.appendEvent` at the emit site.
+  back as `.name` — pass it directly to `ctx.events.append`. Events that
+  aren't registered are rejected by `ctx.events.append` at the emit site.
 
-- **`ctx.appendEvent({ aggregateId, aggregateType, type, payload })`**
+- **`ctx.events.append({ aggregateId, aggregateType, type, payload })`**
   appends the event onto the aggregate stream within the same TX.
   Version lineage is continued automatically — no synthetic
   `"pubsub"` stream anymore, the event truly lives on the aggregate.
@@ -40,7 +40,7 @@ Three building blocks:
 HTTP → writeHandler
          ↓ TX begin
          orderExecutor.create(...)     ← business row + auto-event (pubsubOrder.created, v1)
-         ctx.appendEvent({...})        ← domain event (pubsub-orders:event:order-placed, v2)
+         ctx.events.append({...})        ← domain event (pubsub-orders:event:order-placed, v2)
          ↓ TX commit
          (async, post-commit)
          event-dispatcher runOnce
@@ -50,7 +50,7 @@ HTTP → writeHandler
 
 ## Migration note
 
-`r.postEvent` was removed in Sprint E.2. `ctx.appendEvent` +
+`r.postEvent` was removed in Sprint E.2. `ctx.events.append` +
 `r.multiStreamProjection` is the unified Marten API for CRUD events,
 domain events, and cross-feature reactions.
 
@@ -78,7 +78,7 @@ bun kumiko test integration samples/cross-feature-events
 // Cross-Feature Reactions Sample — Integration Test
 //
 // Proves:
-//   1. ctx.appendEvent persists the domain event into the events-table
+//   1. ctx.events.append persists the domain event into the events-table
 //      inside the same TX as the business write, on the aggregate's own
 //      stream (aggregateType = "pubsub-order", not the legacy "pubsub").
 //   2. The event-dispatcher picks it up and invokes the
@@ -119,7 +119,7 @@ beforeEach(async () => {
   await resetEventStore(stack, ["read_sample_pubsub_orders"]);
 });
 
-describe("cross-feature reactions via ctx.appendEvent + r.multiStreamProjection", () => {
+describe("cross-feature reactions via ctx.events.append + r.multiStreamProjection", () => {
   test("write commits → event on aggregate stream → MSP handler receives it", async () => {
     const data = await stack.http.writeOk(
       "pubsub-orders:write:order:place",
@@ -195,7 +195,7 @@ describe("cross-feature reactions via ctx.appendEvent + r.multiStreamProjection"
 // Cross-Feature Reactions Sample (Marten gold-standard path)
 //
 // Demonstrates the Sprint-E pattern for reacting to events across features:
-// a writeHandler emits a DOMAIN event via `ctx.appendEvent(...)` onto the
+// a writeHandler emits a DOMAIN event via `ctx.events.append(...)` onto the
 // aggregate's own stream, and a `r.multiStreamProjection` picks it up
 // asynchronously through the event-dispatcher.
 //
@@ -203,11 +203,11 @@ describe("cross-feature reactions via ctx.appendEvent + r.multiStreamProjection"
 //
 //   1. `r.defineEvent("short-name", zodSchema)` declares the event shape.
 //      Returns a def whose `.name` is the fully-qualified event name —
-//      pass that straight to `ctx.appendEvent` so there's no string to
+//      pass that straight to `ctx.events.append` so there's no string to
 //      hand-type (and no way to emit an unregistered event: appendEvent
 //      rejects at the emit site).
 //
-//   2. `ctx.appendEvent({ aggregateId, aggregateType, type, payload })`
+//   2. `ctx.events.append({ aggregateId, aggregateType, type, payload })`
 //      writes the event onto the aggregate's own stream inside the same
 //      transaction as the business write. Commit both or roll back both —
 //      no lost events, no orphan events. The event carries real
@@ -261,7 +261,7 @@ export const pubsubOrderFeature = defineFeature("pubsubOrders", (r) => {
   r.entity({ name: "pubsub-order", ...orderEntity });
 
   // Define the event shape once. The returned `.name` is the qualified
-  // name ("pubsub-orders:event:order-placed") — pass it to ctx.appendEvent.
+  // name ("pubsub-orders:event:order-placed") — pass it to ctx.events.append.
   const orderPlaced = r.defineEvent(
     "order-placed",
     z.object({ id: z.string(), customer: z.string(), product: z.string() }),

package/agents/examples/crypto-shredding-hr.md

@@ -108,7 +108,7 @@ import {
   nullBlindIndexesForSubject,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
-import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import {
   resetBlindIndexKeyForTests,
@@ -144,7 +144,7 @@ beforeEach(async () => {
   // Fresh adapter per test = fresh key universe. Rows from earlier tests
   // would name subjects this adapter never minted (fail-loud KeyNotFound),
   // so the tables reset alongside the KMS.
-  await resetTestTables(stack.db, ["read_hr_employees", "read_hr_comments"]);
+  await resetTestTables(stack.db, ["read_hr_employees", "read_hr_comments", eventsTable]);
   kms = new InMemoryKmsAdapter();
   configurePiiSubjectKms(kms);
   // Blind-index key: what runProdApp({ blindIndexKey }) wires in production.

package/agents/examples/encrypted-tenant-config.md

@@ -181,7 +181,7 @@ beforeAll(async () => {
     extraContext: ({ registry }) => ({
       configResolver: resolver,
       configEncryption: encryption,
-      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      configAccessorFactory: createConfigAccessorFactory(registry, resolver),
     }),
   });
   await unsafePushTables(stack.db, { configValuesTable });

package/agents/examples/error-contract.md

@@ -119,7 +119,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createTestUser, TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
-import { updateRows } from "@cosmicdrift/kumiko-testing/helpers";
+import { updateRowViaEventStore } from "@cosmicdrift/kumiko-testing/helpers";
 import {
   setupTestStack,
   type TestStack,
@@ -139,7 +139,7 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, orderEntity);
   await createEventsTable(stack.db);
 });
-afterAll(async () => stack.cleanup());
+afterAll(async () => stack?.cleanup());
 
 // --- 1) Zod validation error via schema: empty cart rejected ---
 
@@ -222,11 +222,16 @@ describe("ConflictError → 409", () => {
       { totalCents: 100 },
       alice,
     );
-    // Force the row into `paid` via direct DB update. The sample feature
-    // doesn't expose a "place" action, so we can't walk the state machine —
-    // the point of this test is ConflictError semantics, not the transition
-    // path itself.
-    await updateRows(stack.db, orderTable, { status: "paid" }, { id: order.id });
+    // The sample feature doesn't expose a "place" action, so we can't walk the
+    // state machine — the point of this test is ConflictError semantics, not the
+    // transition path itself.
+    await updateRowViaEventStore(
+      stack.db,
+      { table: orderTable, entity: orderEntity, entityName: "order" },
+      { id: order.id },
+      { status: "paid" },
+      { tenantId: alice.tenantId },
+    );
 
     const error = await stack.http.writeErr(
       "orders-lite:write:order:cancel",

package/agents/examples/event-sourcing.md

@@ -2,7 +2,7 @@
 
 # event-sourcing
 
-Production-pattern ES sample: r.defineEvent (versioned + migrations) + ctx.appendEvent + r.projection + r.multiStreamProjection + ctx.loadAggregate (asOf) + ctx.archiveStream + ctx.queryProjection.
+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.
 
 ## README
 
@@ -17,12 +17,12 @@ blocks Kumiko provides.
 | API | Purpose |
 |---|---|
 | `r.defineEvent(name, schema, { version, migrations })` | Event schema with version number + upcaster chain |
-| `ctx.appendEvent({ aggregateId, aggregateType, type, payload })` | Domain event on aggregate stream |
+| `ctx.events.append({ aggregateId, aggregateType, type, payload })` | Domain event on aggregate stream |
 | `r.projection(...)` | Single-stream read model, inline in the write TX |
 | `r.multiStreamProjection(...)` | Cross-aggregate read model, async via dispatcher |
-| `ctx.loadAggregate(id, { asOf })` | Live aggregation with point-in-time |
-| `ctx.archiveStream(id, { aggregateType })` | Archive a stream (Marten `ArchiveStream`) |
-| `ctx.queryProjection(name)` | Tenant-scoped read-model query |
+| `ctx.events.load(id, { asOf })` | Live aggregation with point-in-time |
+| `ctx.events.archive(id, { aggregateType })` | Archive a stream (Marten `ArchiveStream`) |
+| `ctx.dispatch.queryProjection(name)` | Tenant-scoped read-model query |
 
 ## Domain
 
@@ -53,7 +53,7 @@ HTTP POST /api/write { type: "showcase:write:invoice:approve", ... }
          ↓
   writeHandler("invoice:approve")
          ↓ TX begin
-         ctx.appendEvent({ type: "showcase:event:invoice-approved", ... })
+         ctx.events.append({ type: "showcase:event:invoice-approved", ... })
          r.projection("invoice-detail")         ← updates status = "approved"
          ↓ TX commit
          (async)
@@ -86,12 +86,12 @@ Six integration tests pin everything at once:
 //
 // Exercises every Sprint-E Marten gold-standard API end-to-end:
 //   - r.defineEvent with version + migrations (sync + async upcaster)
-//   - ctx.appendEvent onto the aggregate stream (incl. headers metadata)
+//   - ctx.events.append onto the aggregate stream (incl. headers metadata)
 //   - r.projection (single-stream, inline)
 //   - r.multiStreamProjection (async)
-//   - ctx.loadAggregate with { asOf }
-//   - ctx.archiveStream
-//   - ctx.queryProjection
+//   - ctx.events.load with { asOf }
+//   - ctx.events.archive
+//   - ctx.dispatch.queryProjection
 //   - streamAllEventsByType (memory-bounded ops iteration)
 //   - getAllProjectionProgress (projection lag for ops dashboards)
 
@@ -364,7 +364,7 @@ describe("Event Sourcing Showcase", () => {
     expect(beforeSnapshot.state.status).toBe("paid");
     expect(beforeSnapshot.state.amountCents).toBe(3300);
 
-    // Take a snapshot after the pay event. ctx.snapshotAggregate writes
+    // Take a snapshot after the pay event. ctx.events.snapshot writes
     // kumiko_snapshots with the committed state + version.
     const snapResult = await stack.http.writeOk<{ id: string; snapshotVersion: number }>(
       "showcase:write:invoice:take-snapshot",
@@ -494,7 +494,7 @@ describe("Event Sourcing Showcase", () => {
     expect(otherView[0]?.totalCents).toBe(200);
   });
 
-  test("ctx.appendEvent with headers: Marten free key/value metadata lands in stored event", async () => {
+  test("ctx.events.append with headers: Marten free key/value metadata lands in stored event", async () => {
     const { id } = await stack.http.writeOk<{ id: string }>(
       "showcase:write:invoice:create",
       { customer: "MetaCo" },
@@ -535,7 +535,7 @@ describe("Event Sourcing Showcase", () => {
     });
 
     // Append a v1 acknowledged event directly to simulate a pre-migration
-    // payload on disk. ctx.appendEvent always writes the current version,
+    // payload on disk. ctx.events.append always writes the current version,
     // so the only way to test the read-time upcaster is to write the older
     // shape via the raw event-store.
     const invoiceId = "00000000-0000-4000-8000-00000000ac01";
@@ -591,7 +591,7 @@ describe("Event Sourcing Showcase", () => {
       approverDisplayName: "Quincy Acknowledger",
     });
 
-    // Sanity check the ctx.appendEvent path too: it writes the current
+    // Sanity check the ctx.events.append path too: it writes the current
     // shape directly (handler resolved displayName synchronously), so
     // the upcaster is a no-op on these events.
     const { id: liveId } = await stack.http.writeOk<{ id: string }>(
@@ -836,10 +836,10 @@ describe("role-restricted write handlers", () => {
 //   - emitEvent with headers — Marten free key/value metadata
 //   - r.projection — single-stream read model (inline in the write TX)
 //   - r.multiStreamProjection — cross-aggregate async read model
-//   - ctx.loadAggregate with { asOf } — point-in-time aggregate state
-//   - ctx.archiveStream / ctx.restoreStream — Marten ArchiveStream
-//   - ctx.queryProjection — tenant-scoped read of a projection table
-//   - ctx.snapshotAggregate + ctx.loadAggregateWithSnapshot — perf path
+//   - ctx.events.load with { asOf } — point-in-time aggregate state
+//   - ctx.events.archive / ctx.events.restore — Marten ArchiveStream
+//   - ctx.dispatch.queryProjection — tenant-scoped read of a projection table
+//   - ctx.events.snapshot + ctx.events.loadWithSnapshot — perf path
 //     for aggregates with long event tails (O(1) vs O(N) reduce), incl.
 //     the auto-snapshot policy ({ snapshotEvery, snapshotVersion })
 //   - streamAllEventsByType — memory-bounded iteration for ops/export jobs
@@ -1166,7 +1166,7 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
     name: "invoice:archive",
     schema: z.object({ id: z.uuid() }),
     handler: async (event, ctx) => {
-      await ctx.archiveStream(event.payload.id, { aggregateType: "showcase-invoice" });
+      await ctx.events.archive(event.payload.id, { aggregateType: "showcase-invoice" });
       return { isSuccess: true as const, data: { id: event.payload.id } };
     },
     access: { roles: ["Admin"] },
@@ -1181,14 +1181,14 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
     handler: async (event, ctx) => {
       // Rebuild the state from the current stream so the snapshot reflects
       // the committed event log, not an in-memory guess. Use the upcaster-
-      // aware ctx.loadAggregate to stay consistent with read-time semantics.
-      const events = await ctx.loadAggregate(event.payload.id);
+      // aware ctx.events.load to stay consistent with read-time semantics.
+      const events = await ctx.events.load(event.payload.id);
       const state: InvoiceState = { ...initialInvoiceState };
       for (const evt of events) {
         reduceInvoice(state, evt);
       }
       const version = events.length > 0 ? (events[events.length - 1]?.version ?? 0) : 0;
-      await ctx.snapshotAggregate({
+      await ctx.events.snapshot({
         aggregateId: event.payload.id,
         aggregateType: "showcase-invoice",
         version,
@@ -1201,13 +1201,13 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
 
   // --- Query handlers ---
 
-  // Live aggregation via ctx.loadAggregate — reduces events into a state
+  // Live aggregation via ctx.events.load — reduces events into a state
   // snapshot. Supports asOf for point-in-time reads.
   r.queryHandler({
     name: "invoice:state",
     schema: z.object({ id: z.uuid(), asOf: z.iso.datetime().optional() }),
     handler: async (query, ctx) => {
-      const events = await ctx.loadAggregate(query.payload.id, {
+      const events = await ctx.events.load(query.payload.id, {
         ...(query.payload.asOf ? { asOf: Temporal.Instant.from(query.payload.asOf) } : {}),
       });
       const state: InvoiceState = { ...initialInvoiceState };
@@ -1232,7 +1232,7 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
     name: "invoice:fast-state",
     schema: z.object({ id: z.uuid() }),
     handler: async (query, ctx) => {
-      const result = await ctx.loadAggregateWithSnapshot<InvoiceStateRecord>(
+      const result = await ctx.events.loadWithSnapshot<InvoiceStateRecord>(
         query.payload.id,
         (state, evt) => {
           const next: InvoiceStateRecord = { ...state };
@@ -1261,7 +1261,7 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
     },
   });
 
-  // Read-model query via ctx.queryProjection — auto-tenant-scoped. The
+  // Read-model query via ctx.dispatch.queryProjection — auto-tenant-scoped. The
   // helper collapses the zero-argument "return this projection" pattern
   // into a single call; returns { rows } so the response shape stays
   // consistent with other list handlers.
@@ -1277,11 +1277,11 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
     }),
   );
 
-  // Slow synthetic export — demonstrates ctx.signal honouring inside a
+  // Slow synthetic export — demonstrates ctx.lifecycle.signal honouring inside a
   // long-running handler loop. Real-world equivalents: PDF batch export,
   // bulk CSV download, multi-stream audit walk. Mobile clients that
   // navigate away mid-export should NOT keep the server busy producing
-  // bytes nobody will read. The handler checks ctx.signal at every
+  // bytes nobody will read. The handler checks ctx.lifecycle.signal at every
   // iteration; on abort, throws and the dispatcher returns an error to
   // the (already-disconnected) client.
   r.queryHandler({
@@ -1290,7 +1290,7 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
     handler: async (query, ctx) => {
       const accumulated: number[] = [];
       for (let i = 0; i < query.payload.chunks; i++) {
-        ctx.signal?.throwIfAborted();
+        ctx.lifecycle.signal?.throwIfAborted();
         // Fake "work per chunk". Realistic handler would assemble a row,
         // hit a remote service, etc.
         await new Promise((resolve) => setTimeout(resolve, 10));

package/agents/examples/files-post-processing.md

@@ -2,7 +2,7 @@
 
 # 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.
+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.
 
 ## README
 
@@ -13,7 +13,7 @@ File upload plus post-processing hooks.
 ## What it shows
 
 - Declarative `variants` on `createImageField` (file-derivatives)
-- Imperative `ctx.derivatives.variant()` path and the public variant route (`EXT_DERIVATIVE_PUBLIC_PREDICATE`)
+- Imperative `ctx.services.derivatives.variant()` path and the public variant route (`EXT_DERIVATIVE_PUBLIC_PREDICATE`)
 
 ## Source
 
@@ -41,7 +41,7 @@ bun test
 //   1. declarative — GET /api/files/:id/variant/:name resolves a field's
 //      declared variant.
 //   2. imperative — the `set-cover` write-handler calls
-//      ctx.derivatives.variant() directly, with a region-blur.
+//      ctx.services.derivatives.variant() directly, with a region-blur.
 //   3. public route — GET /media/:fileRefId/:variant, default-deny until a
 //      photo is explicitly published.
 
@@ -178,7 +178,7 @@ describe("entry point 1 — declarative field variant", () => {
   });
 });
 
-describe("entry point 2 — imperative ctx.derivatives.variant() with region-blur", () => {
+describe("entry point 2 — imperative ctx.services.derivatives.variant() with region-blur", () => {
   test("set-cover derives a variant with no field declaration involved, and tracks order", async () => {
     const fileId = await uploadPhoto(null);
 
@@ -292,7 +292,7 @@ describe("event emission contract", () => {
 //      resolves + caches the variant behind the auth-gated
 //      `GET /api/files/:id/variant/:name` route, no handler code needed.
 //   2. Imperative — the `set-cover` write-handler calls
-//      `ctx.derivatives.variant()` directly. This is for apps that track
+//      `ctx.services.derivatives.variant()` directly. This is for apps that track
 //      images as their own records (ordering, a chosen cover image) and for
 //      region-blur, whose coordinates are runtime data that can't live in a
 //      static field declaration.
@@ -371,13 +371,15 @@ export const filesPostProcessingFeature = defineFeature("files-post-processing",
         .optional(),
     }),
     handler: async (event, ctx) => {
-      if (!ctx.derivatives) {
+      if (!ctx.services.derivatives) {
         return writeFailure(
-          new InternalError({ message: "ctx.derivatives missing — is file-derivatives mounted?" }),
+          new InternalError({
+            message: "ctx.services.derivatives missing — is file-derivatives mounted?",
+          }),
         );
       }
       const { fileRefId, blurRegion } = event.payload;
-      const result = await ctx.derivatives.variant(
+      const result = await ctx.services.derivatives.variant(
         fileRefId,
         {
           maxEdge: 800,

package/agents/examples/inbound-mail-triage.md

@@ -153,6 +153,7 @@ describe("inbound-mail triage sample", () => {
     ]);
     const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
     const entry = createAllInOneEntrypoint({
+      rowLevelSecurity: "off",
       registry,
       context: { db: testDb.db, redis: testRedis.redis },
       jwtSecret: JWT,

package/agents/examples/lane-routing.md

@@ -2,7 +2,7 @@
 
 # lane-routing
 
-runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.appendEvent, verified end-to-end through createAllInOneEntrypoint.
+runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.events.append, verified end-to-end through createAllInOneEntrypoint.
 
 ## README
 
@@ -94,6 +94,7 @@ describe("lane-routing sample", () => {
     const registry = createRegistry([createLaneRoutingFeature()]);
     const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
     const entry = createAllInOneEntrypoint({
+      rowLevelSecurity: "off",
       registry,
       context: { db: testDb.db, redis: testRedis.redis },
       jwtSecret: JWT,

package/agents/examples/legal-pages.md

@@ -108,9 +108,9 @@ A one-shot setup routine that runs on first boot or via the CLI:
 // bin/seed-legal.ts
 import { seedTextBlock } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
-import { createDb } from "@cosmicdrift/kumiko-framework/db";
+import { createDbConnection } from "@cosmicdrift/kumiko-framework/db";
 
-const db = createDb(process.env.DATABASE_URL!);
+const { db } = createDbConnection({ url: process.env.DATABASE_URL! });
 
 await seedTextBlock(db, {
   tenantId: SYSTEM_TENANT_ID,

package/agents/examples/lifecycle-hooks.md

@@ -35,8 +35,8 @@ back.
 - **`r.hook({ type: "postDelete", target: { allOf: entityRef }, handler })`** — fires after commit.
   External side effects (logs, notifications) belong here because
   failures cannot roll the delete back.
-- **`ctx.scheduleAfterRollback(fn)`** — the counterpart of `scheduleAfterCommit`: runs `fn` when
-  the handler transaction (or the enclosing savepoint of a nested `ctx.write`) does not commit.
+- **`ctx.lifecycle.afterRollback(fn)`** — the counterpart of `ctx.lifecycle.afterCommit`: runs `fn` when
+  the handler transaction (or the enclosing savepoint of a nested `ctx.dispatch.write`) does not commit.
   Use it to give back something reserved outside the transaction, like the slot in
   `article:reserve-slot`. A failed COMMIT triggers it too, so write the callback idempotent.
 
@@ -356,7 +356,7 @@ export const articlesFeature = defineFeature("blog", (r) => {
     handler: async (event, ctx) => {
       const { slot, reject } = event.payload;
       reservedSlots.add(slot);
-      ctx.scheduleAfterRollback?.(async () => {
+      ctx.lifecycle.afterRollback?.(async () => {
         reservedSlots.delete(slot);
       });
       if (reject) return writeFailure(new UnprocessableError("slot_rejected"));

package/agents/examples/managed-config.md

@@ -51,7 +51,7 @@ r.config({
 
 - **`backing: "secrets"`** — the value lives in the secrets store (envelope
   encryption, KEK rotation, audit-on-read) instead of `config_values`. Set/read/
-  reset dispatch through `ctx.secrets`; the query handlers mask the value while
+  reset dispatch through `ctx.services.secrets`; the query handlers mask the value while
   the owning feature still reads the revealed plaintext via `ctx.config`. Only
   valid for `scope: "system"` — secrets are flat per `(tenant, key)` with no
   cascade, so a tenant override would be incoherent and is rejected at boot.
@@ -80,7 +80,7 @@ await runProdApp({
   envSchema, // composeEnvSchema({ core: frameworkCoreEnvSchema, features })
   extraContext: ({ db, registry }) => ({
     configResolver: resolver,
-    _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    configAccessorFactory: createConfigAccessorFactory(registry, resolver),
     // Required whenever a key declares backing:"secrets" — without it the set
     // and read paths fail loud, never silently miss.
     secrets: createSecretsContext({ db, masterKeyProvider, registry }),
@@ -90,7 +90,7 @@ await runProdApp({
 ```
 
 Register the `secrets` feature too so its `tenant_secrets` table is migrated;
-the config backing only needs the `ctx.secrets` context shown above.
+the config backing only needs the `ctx.services.secrets` context shown above.
 
 ## Vs. the neighbouring recipes
 
@@ -211,7 +211,7 @@ beforeAll(async () => {
       const resolver = createConfigResolver();
       return {
         configResolver: resolver,
-        _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+        configAccessorFactory: createConfigAccessorFactory(registry, resolver),
         secrets: createSecretsContext({ db, masterKeyProvider, registry }),
       };
     },