@cosmicdrift/kumiko-samples 0.389.0 → 0.390.1

package/samples/apps/cap-billing-demo/src/feature.ts

@@ -40,18 +40,32 @@ import type { EmailMessage } from "@cosmicdrift/kumiko-bundled-features/channel-
 import {
   createMailFoundationFeature,
   createTransportForTenant,
+  type MailTransportContext,
 } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import {
   access,
   createTenantConfig,
   defineFeature,
-  type HandlerContext,
+  type ReservationContext,
   type WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { DEMO_TIER_MAP, TIER_NAMES, type TierName } from "./tier-map";
 
 const FEATURE_NAME = "newsletter";
+
+// The transport factory takes a narrow context (it also runs in the worker), so the handler's
+// secrets live under services and are handed over explicitly.
+function mailContextOf(
+  ctx: Pick<ReservationContext, "config" | "registry" | "services" | "user">,
+): MailTransportContext {
+  return {
+    config: ctx.config,
+    registry: ctx.registry,
+    secrets: ctx.services.secrets,
+    auditUserId: ctx.user.id,
+  };
+}
 const NEWSLETTER_CAP = "newsletters-per-month";
 
 // =============================================================================
@@ -71,7 +85,7 @@ const innerSendHandler: WriteHandlerDef = {
   handler: async (event, ctx) => {
     const payload = event.payload as z.infer<typeof sendSchema>;
     const transport = await createTransportForTenant(
-      ctx,
+      mailContextOf(ctx),
       event.user.tenantId,
       "newsletter:write:send",
     );
@@ -108,7 +122,7 @@ function isValidTierName(value: string): value is TierName {
   return (TIER_NAMES as readonly string[]).includes(value);
 }
 
-async function resolveTier(ctx: HandlerContext): Promise<TierName> {
+async function resolveTier(ctx: ReservationContext): Promise<TierName> {
   const tenantId = ctx.user?.tenantId;
   if (tenantId) {
     const sub = await getSubscriptionForTenant(ctx, tenantId);
@@ -131,10 +145,10 @@ async function resolveTier(ctx: HandlerContext): Promise<TierName> {
 
 /** Notifier-Factory: bauen einen SoftHitNotifier der die Warnung über
  *  dieselbe mail-foundation an den Tenant-Admin schickt. */
-function buildSoftHitNotifier(ctx: HandlerContext): SoftHitNotifier {
+function buildSoftHitNotifier(ctx: ReservationContext): SoftHitNotifier {
   return async (info) => {
     const transport = await createTransportForTenant(
-      ctx,
+      mailContextOf(ctx),
       info.tenantId,
       "newsletter:soft-hit-notifier",
     );

package/samples/apps/config-demo/src/app/server.ts

@@ -26,6 +26,6 @@ await runDevApp({
   watchDirs: ["./src", "../../../packages/*/src"],
   extraContext: ({ registry }) => ({
     configResolver: resolver,
-    _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    configAccessorFactory: createConfigAccessorFactory(registry, resolver),
   }),
 });

package/samples/apps/styleguide/src/app/server.ts

@@ -39,7 +39,7 @@ await runDevApp({
     aiSettingsFeature,
     workboardFeature,
   ],
-  // Aktiviert die Upload-Routes (/api/files) + ctx.files für den Avatar-
+  // Aktiviert die Upload-Routes (/api/files) + ctx.services.files für den Avatar-
   // Stresstest. In-Memory reicht für die Demo (nicht-persistent).
   files: { storageProvider: createInMemoryFileProvider() },
   port: Number.parseInt(process.env["PORT"] ?? "4180", 10),
@@ -49,6 +49,6 @@ await runDevApp({
   seeds: [seedStyleguideItems, seedAiConnections, seedWorkboardTasks],
   extraContext: ({ registry }) => ({
     configResolver,
-    _configAccessorFactory: createConfigAccessorFactory(registry, configResolver),
+    configAccessorFactory: createConfigAccessorFactory(registry, configResolver),
   }),
 });

package/samples/apps/ui-walkthrough/package.json

@@ -18,7 +18,7 @@
     "@cosmicdrift/kumiko-server-runtime": "workspace:*",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "zod": "^4.4.3",
+    "zod": "^4.6.7",
     "@cosmicdrift/kumiko-locale-de": "workspace:*",
     "@cosmicdrift/kumiko-locale-es": "workspace:*"
   },

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -920,7 +920,7 @@
     },
     {
       "name": "file-derivatives",
-      "description": "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.",
+      "description": "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.",
       "toggleableDefault": null,
       "requires": [
         "file-foundation",

package/samples/apps/use-all-bundled/package.json

@@ -26,7 +26,7 @@
     "@cosmicdrift/kumiko-types": "workspace:*",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "zod": "^4.4.3",
+    "zod": "^4.6.7",
     "@cosmicdrift/kumiko-locale-de": "workspace:*",
     "@cosmicdrift/kumiko-locale-es": "workspace:*",
     "@cosmicdrift/kumiko-locale-fr": "workspace:*",

package/samples/apps/use-all-bundled/src/app/seed.ts

@@ -93,7 +93,12 @@ async function seedTierAssignment(
   adminUserId: string,
 ): Promise<void> {
   const by: SessionUser = { ...TestUsers.systemAdmin, tenantId, id: adminUserId };
-  const tdb = createTenantDb({ db, tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId,
+    mode: "system",
+    reason: "demo seed writes tier assignments for the tenant being provisioned",
+  });
   const result = await tierAssignmentExecutor.create(
     { id: tierAssignmentAggregateId(tenantId), tier, source: "manual", tenantId },
     by,
@@ -117,7 +122,12 @@ async function seedTagsAndNotes(
   adminUserId: string,
 ): Promise<void> {
   const by: SessionUser = { ...TestUsers.systemAdmin, tenantId, id: adminUserId };
-  const tdb = createTenantDb({ db, tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId,
+    mode: "system",
+    reason: "demo seed writes tier assignments for the tenant being provisioned",
+  });
 
   const created = async (
     label: string,

package/samples/apps/user-data-rights-demo/README.md

@@ -16,7 +16,7 @@ DSGVO requests work end-to-end:
 
 | Article | Endpoint / Runner | What it does |
 |---------|-----------|----------------|
-| **Art. 15** | `user-data-rights:query:my-audit-log` | User sees own framework events (auth, deletion-request, restriction). Domain entities like todos appear in the **export bundle** (Art. 20), not the audit-log — only handlers using `ctx.appendEvent` show up here. |
+| **Art. 15** | `user-data-rights:query:my-audit-log` | User sees own framework events (auth, deletion-request, restriction). Domain entities like todos appear in the **export bundle** (Art. 20), not the audit-log — only handlers using `ctx.events.append` show up here. |
 | **Art. 15+20** | `user-data-rights:write:request-export` | ZIP with user-profile + fileRefs + todos + signed download magic-link |
 | **Art. 17** | `user-data-rights:write:request-deletion` | Soft-delete with grace period; cron anonymizes user + deletes todos |
 | **Art. 18** | `user-data-rights:write:restrict-account` | Auth-middleware blocks logins until lift-restriction |

package/samples/apps/user-data-rights-demo/package.json

@@ -10,7 +10,7 @@
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-dev-server": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*",
-    "zod": "^4.4.3",
+    "zod": "^4.6.7",
     "@cosmicdrift/kumiko-locale-de": "workspace:*"
   },
   "devDependencies": {

package/samples/apps/user-data-rights-demo/src/feature.ts

@@ -25,6 +25,7 @@
 //   3. todoDeleteHook DELETEt alle Rows mit author_id = userId
 //   4. user wird anonymisiert (display_name="(deleted)", email=null)
 
+import { UserDataRightsScreens } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
 import {
   deleteMany,
   deriveEntityTableMeta,
@@ -182,7 +183,7 @@ export const todosFeature = defineFeature(FEATURE_NAME, (r) => {
     id: "gdpr-export-jobs",
     label: "GDPR · Export Jobs",
     icon: "shield",
-    screen: "user-data-rights:screen:export-job-list",
+    screen: UserDataRightsScreens.exportJobList,
     access: { roles: ["SystemAdmin"] },
     order: 90,
   });
@@ -190,7 +191,7 @@ export const todosFeature = defineFeature(FEATURE_NAME, (r) => {
     id: "gdpr-download-attempts",
     label: "GDPR · Download Attempts",
     icon: "download",
-    screen: "user-data-rights:screen:download-attempt-list",
+    screen: UserDataRightsScreens.downloadAttemptList,
     access: { roles: ["SystemAdmin"] },
     order: 91,
   });

package/samples/recipes/api-worker-split/README.md

@@ -60,7 +60,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
 

package/samples/recipes/api-worker-split/src/feature.ts

@@ -131,8 +131,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/samples/recipes/cross-feature-events/README.md

@@ -11,10 +11,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.
@@ -32,7 +32,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
@@ -42,7 +42,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.
 

package/samples/recipes/cross-feature-events/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-sample-cross-feature-events",
-  "description": "Feature appends a typed domain event via ctx.appendEvent; a r.multiStreamProjection reacts asynchronously.",
+  "description": "Feature appends a typed domain event via ctx.events.append; a r.multiStreamProjection reacts asynchronously.",
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"

package/samples/recipes/cross-feature-events/src/feature.ts

@@ -1,7 +1,7 @@
 // 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.
 //
@@ -9,11 +9,11 @@
 //
 //   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
@@ -67,7 +67,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/samples/recipes/event-sourcing/README.md

@@ -9,12 +9,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
 
@@ -45,7 +45,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)

package/samples/recipes/event-sourcing/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-sample-event-sourcing",
-  "description": "Production-pattern ES sample: r.defineEvent (versioned + migrations) + ctx.appendEvent + r.projection + r.multiStreamProjection + ctx.loadAggregate (asOf) + ctx.archiveStream + ctx.queryProjection.",
+  "description": "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.",
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"

package/samples/recipes/event-sourcing/src/feature.ts

@@ -9,10 +9,10 @@
 //   - 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
@@ -339,7 +339,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"] },
@@ -354,14 +354,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,
@@ -374,13 +374,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 };
@@ -405,7 +405,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 };
@@ -434,7 +434,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.
@@ -450,11 +450,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({
@@ -463,7 +463,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/samples/recipes/files-post-processing/README.md

@@ -5,7 +5,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
 

package/samples/recipes/files-post-processing/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-sample-files-post-processing",
-  "description": "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.",
+  "description": "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.",
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",

package/samples/recipes/files-post-processing/src/feature.ts

@@ -9,7 +9,7 @@
 //      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.
@@ -88,13 +88,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/samples/recipes/lane-routing/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-sample-lane-routing",
-  "description": "runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.appendEvent, verified end-to-end through createAllInOneEntrypoint.",
+  "description": "runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.events.append, verified end-to-end through createAllInOneEntrypoint.",
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"

package/samples/recipes/legal-pages/README.md

@@ -100,9 +100,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/samples/recipes/lifecycle-hooks/README.md

@@ -27,8 +27,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.
 

package/samples/recipes/lifecycle-hooks/src/feature.ts

@@ -65,7 +65,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/samples/recipes/managed-config/README.md

@@ -43,7 +43,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.
@@ -72,7 +72,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 }),
@@ -82,7 +82,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
 

package/samples/recipes/search/README.md

@@ -5,7 +5,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
 

package/samples/recipes/search/src/feature.ts

@@ -1,6 +1,6 @@
 // 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";
@@ -38,7 +38,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);
@@ -54,7 +54,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/samples/recipes/secrets-demo/README.md

@@ -4,7 +4,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

package/samples/recipes/secrets-demo/src/feature.ts

@@ -1,4 +1,4 @@
-// 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.
@@ -27,7 +27,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/samples/recipes/state-machine/src/events.ts

@@ -23,7 +23,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,