@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

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/golden-path/src/feature.ts

@@ -7,7 +7,7 @@ import {
   emitEvent,
   setFields,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 
 export const ticketEntity = createEntity({
@@ -43,6 +43,7 @@ export const helpdeskFeature = defineFeature("helpdesk", (r) => {
       if (!ticket) {
         return failNotFound("ticket", event.payload.id);
       }
+      if (ticket["isClosed"]) return failUnprocessable("ticket_already_closed");
       await emitEvent(ctx, ticketClosed, {
         aggregateId: event.payload.id,
         aggregateType: "ticket",

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,6 +27,10 @@ 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.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.
 
 ## When to reach for it
 

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

@@ -13,7 +13,12 @@ import {
   defineFeature,
   type SaveContext,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  ConflictError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
 
 export const articleEntity = createEntity({
   table: "read_sample_articles",
@@ -35,6 +40,9 @@ export const articleEntity = createEntity({
 // Collect hook events for testing
 export const hookLog: { type: string; data: Record<string, unknown> }[] = [];
 
+// Stands in for a quota held in an external system, outside the handler transaction.
+export const reservedSlots = new Set<string>();
+
 const editorWrite = { access: { roles: ["Admin", "Editor"] } } as const;
 
 export const articlesFeature = defineFeature("blog", (r) => {
@@ -48,6 +56,23 @@ export const articlesFeature = defineFeature("blog", (r) => {
   );
   r.writeHandler(defineEntityDeleteHandler("article", articleEntity, editorWrite));
 
+  // --- scheduleAfterRollback: give back a reservation made outside the transaction when it does
+  // not commit. The callback must be idempotent: a failed COMMIT also triggers it.
+  r.writeHandler({
+    name: "article:reserve-slot",
+    schema: z.object({ slot: z.string(), reject: z.boolean() }),
+    access: editorWrite.access,
+    handler: async (event, ctx) => {
+      const { slot, reject } = event.payload;
+      reservedSlots.add(slot);
+      ctx.lifecycle.afterRollback?.(async () => {
+        reservedSlots.delete(slot);
+      });
+      if (reject) return writeFailure(new UnprocessableError("slot_rejected"));
+      return { isSuccess: true as const, data: {} };
+    },
+  });
+
   // --- Validation hook on create: reject banned words + length ---
   r.hook({
     type: "validation",

package/samples/recipes/list-table-options/README.md

@@ -0,0 +1,50 @@
+# List table options
+
+Opt-in table behaviour for entity, projection and related lists. A list without
+the `table` block renders and behaves as before.
+
+## What it shows
+
+- `table.rememberState`: search, sort, page size, facets and date range survive
+  leaving and re-entering the list within the browser session.
+- `table.resetAll`: one button resets everything that differs from the defaults.
+- `table.columnPicker`: the view menu lets the user hide and reorder columns;
+  `hidden: true` on a column starts it hidden.
+- `table.density`: row density default and an optional user choice.
+- `table.pinning`: the user pins columns left or right in the view menu;
+  `pinned: "left"` on a column starts it pinned.
+- `table.resizing`: columns can be resized (table-layout fixed); `width` and
+  `minWidth` on a column are start values in px.
+- `table.keyboardNavigation`: rows are one tab stop, arrow keys move between rows,
+  Space selects the focused row.
+- `table.export`: an Export button downloads the whole filtered list as an XLSX
+  file; `maxRows` lowers the default limit of 10000 rows.
+  Reference columns export their label and timestamps use the browser time zone.
+- `bulkActions`: row checkboxes and a selection bar. "Delete" runs the delete
+  row action once per selected row; done tasks are skipped.
+- `table.grouping`: the server groups the list by status; each header shows the
+  group's count and estimate sum, "done" starts collapsed and the view menu
+  offers grouping by priority or none.
+- `table.totals`: a footer row with the estimate sum over the filtered list.
+- `facets.estimateHours: { display: "range" }`: from/to inputs for a number field.
+- The same block on a `projectionList`, and `task:workload`, a hand-written list
+  query that keeps grouping and totals by accepting `aggregate`
+  (`entityListSchema`) and answering it with `answerListAggregate`.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/list-table-options
+bun test
+```
+
+The test boots the feature through the boot validator and checks that a
+misspelled key, a hidden column without the picker, an unknown density, a pinned column
+without `pinning`, a width without `resizing` and a bulk action on a navigate
+row action are rejected.
+`workload.integration.test.ts` runs the hand-written query over HTTP and checks
+the grouped sums and the filtered total.

package/samples/recipes/list-table-options/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-list-table-options",
+  "description": "Opt-in table behaviour of a list: remembered search/sort/filters, one reset button, column picker with hidden columns, row density, server-side groups with sums, a totals row and a number range facet.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
+  }
+}

package/samples/recipes/list-table-options/src/feature.ts

@@ -0,0 +1,221 @@
+import {
+  answerListAggregate,
+  buildEntityTable,
+  createEventStoreExecutor,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createDateField,
+  createEntity,
+  createNumberField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+  entityListSchema,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { ListTableOptions } from "@cosmicdrift/kumiko-framework/ui-types";
+import { z } from "zod";
+
+export const taskEntity = createEntity({
+  table: "read_list_table_tasks",
+  fields: {
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      searchable: true,
+      sortable: true,
+    }),
+    status: createSelectField({
+      options: ["open", "inProgress", "blocked", "done"] as const,
+      default: "open",
+      sortable: true,
+      filterable: true,
+    }),
+    priority: createSelectField({
+      options: ["low", "medium", "high"] as const,
+      default: "medium",
+      sortable: true,
+      filterable: true,
+    }),
+    dueDate: createDateField({ sortable: true }),
+    assignee: createTextField({ personal: false, reason: "is_business_data", sortable: true }),
+    estimateHours: createNumberField({ sortable: true, filterable: true }),
+  },
+});
+
+export const openAccess = {
+  access: {
+    openToAll: { reason: "recipe: any signed-in user manages the tasks; no per-user ownership" },
+  },
+} as const;
+
+// Overridable so a test can feed the boot validator a block that must be rejected.
+export function createTaskBoardFeature(
+  taskTable: ListTableOptions = {
+    rememberState: true,
+    resetAll: true,
+    columnPicker: true,
+    density: { default: "comfortable", userChoice: true },
+    pinning: true,
+    resizing: true,
+    keyboardNavigation: true,
+    export: { xlsx: true, maxRows: 5000 },
+    grouping: { field: "status", collapsedWhen: "done", userChoice: true, fields: ["priority"] },
+    totals: [{ field: "estimateHours", kind: "sum" }],
+  },
+): FeatureDefinition {
+  return defineFeature("task-board", (r) => {
+    r.crud("task", taskEntity, { write: openAccess, read: openAccess });
+
+    r.screen({
+      id: "task-list",
+      type: "entityList",
+      entity: "task",
+      columns: [
+        // Starts pinned left; width and minWidth are start values for resizing.
+        { field: "title", pinned: "left", width: 280, minWidth: 160 },
+        "status",
+        "priority",
+        { field: "dueDate", hideOnNarrow: true },
+        { field: "assignee", hideOnNarrow: true },
+        // Starts hidden; the user can add it back in the view menu.
+        { field: "estimateHours", hidden: true, hideOnNarrow: true },
+      ],
+      facets: { status: { display: "chips" }, priority: {}, estimateHours: { display: "range" } },
+      defaultSort: { field: "dueDate", dir: "asc" },
+      searchable: true,
+      table: taskTable,
+      rowActions: [
+        { kind: "navigate", id: "open", label: "Open", screen: "task-edit", rowClick: true },
+        {
+          kind: "writeHandler",
+          id: "delete",
+          label: "Delete",
+          handler: "task-board:write:task:delete",
+          style: "danger",
+          // Done tasks are skipped by the bulk run and counted as skipped.
+          visible: { field: "status", ne: "done" },
+        },
+      ],
+      // Row checkboxes and a selection bar; each selected row gets its own delete write.
+      bulkActions: [{ id: "delete", rowAction: "delete" }],
+      access: openAccess.access,
+    });
+
+    r.screen({
+      id: "task-edit",
+      type: "entityEdit",
+      entity: "task",
+      dormant: true,
+      listScreenId: "task-list",
+      layout: {
+        sections: [
+          {
+            columns: 2,
+            fields: ["title", "assignee", "status", "priority", "dueDate", "estimateHours"],
+          },
+        ],
+      },
+    });
+
+    // The same block works on a list over any query.
+    r.queryHandler({
+      name: "task:overdue",
+      schema: z.object({}),
+      handler: async () => ({
+        rows: [{ id: "t1", title: "Quarterly VAT filing", assignee: "Ines", daysLate: 3 }],
+        nextCursor: null,
+      }),
+      access: openAccess.access,
+      outputSchema: z.object({
+        rows: z.array(
+          z.object({
+            id: z.string(),
+            title: z.string(),
+            assignee: z.string(),
+            daysLate: z.number(),
+          }),
+        ),
+        nextCursor: z.string().nullable(),
+      }),
+    });
+
+    r.screen({
+      id: "task-overdue",
+      type: "projectionList",
+      query: "task-board:query:task:overdue",
+      columns: ["title", "assignee", "daysLate"],
+      table: { rememberState: true, density: { userChoice: true } },
+    });
+
+    // A hand-written list query keeps grouping and totals when it accepts
+    // `aggregate` (entityListSchema carries it) and answers it on the server.
+    const taskExecutor = createEventStoreExecutor(
+      buildEntityTable("task", taskEntity),
+      taskEntity,
+      {
+        entityName: "task",
+      },
+    );
+    r.queryHandler({
+      name: "task:workload",
+      schema: entityListSchema,
+      handler: async (query, ctx) => {
+        const parentVisibility = { entities: ctx.registry.getAllEntities() };
+        const listPayload = query.payload;
+        if (listPayload.aggregate !== undefined) {
+          return answerListAggregate(
+            taskExecutor,
+            { ...listPayload, aggregate: listPayload.aggregate },
+            query.user,
+            ctx.db,
+            { parentVisibility },
+            {
+              entity: taskEntity,
+              resolveEntity: (name) => ctx.registry.getEntity(name),
+              viewer: { user: query.user, parentVisibility },
+            },
+          );
+        }
+        return taskExecutor.list(listPayload, query.user, ctx.db, { parentVisibility });
+      },
+      access: openAccess.access,
+    });
+
+    r.screen({
+      id: "task-workload",
+      type: "projectionList",
+      query: "task-board:query:task:workload",
+      columns: ["title", "assignee", "status", "estimateHours"],
+      defaultSort: { field: "title", dir: "asc" },
+      table: {
+        grouping: { field: "assignee" },
+        totals: [{ field: "estimateHours", kind: "sum" }],
+      },
+    });
+
+    r.nav({ id: "tasks", label: "task-board:nav.tasks", icon: "list", order: 10 });
+    r.nav({
+      id: "task-list",
+      label: "task-board:nav.list",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-list",
+      order: 10,
+    });
+    r.nav({
+      id: "task-overdue",
+      label: "task-board:nav.overdue",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-overdue",
+      order: 20,
+    });
+    r.nav({
+      id: "task-workload",
+      label: "task-board:nav.workload",
+      parent: "task-board:nav:tasks",
+      screen: "task-board:screen:task-workload",
+      order: 30,
+    });
+  });
+}

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/pdf-audit-export/src/feature.ts

@@ -15,6 +15,7 @@ import {
   createTextField,
   defineFeature,
   defineWriteHandler,
+  MAX_LIST_LIMIT,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import {
@@ -51,7 +52,7 @@ function toFileNameSegment(text: string): string {
 }
 
 // One row above the limit tells "exactly full" from "cut off"; entity lists cap at 200 rows.
-const AUDIT_ROW_LIMIT = 100;
+const AUDIT_ROW_LIMIT = MAX_LIST_LIMIT - 1;
 
 const access = { access: { roles: ["Admin", "User"] } } as const;
 

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.