@cosmicdrift/kumiko-samples 0.365.1 → 0.367.0

package/samples/recipes/lane-routing/src/feature.ts

@@ -39,18 +39,18 @@ const orderEntity = createEntity({
 
 export function createLaneRoutingFeature(): FeatureDefinition {
   return defineFeature("orders", (r) => {
-    r.entity("order", orderEntity);
+    r.entity({ name: "order", ...orderEntity });
 
     // Write handler — runs in the API process (or wherever the command
     // lands). Event "orders:write:order:create" is the auto-generated
     // write-event both jobs trigger on.
-    r.writeHandler(
-      "order:create",
-      z.object({
+    r.writeHandler({
+      name: "order:create",
+      schema: z.object({
         customerName: z.string().min(1),
         amount: z.number().positive(),
       }),
-      async (event) => ({
+      handler: async (event) => ({
         isSuccess: true as const,
         data: {
           id: 1,
@@ -58,15 +58,13 @@ export function createLaneRoutingFeature(): FeatureDefinition {
           amount: event.payload.amount,
         },
       }),
-      {
-        access: {
-          openToAll: {
-            reason:
-              "demo recipe: any signed-in user may place an order; the handler is a stub with no persistence",
-          },
+      access: {
+        openToAll: {
+          reason:
+            "demo recipe: any signed-in user may place an order; the handler is a stub with no persistence",
         },
       },
-    );
+    });
 
     // Receipt-rendering: heavy CPU work. Pinned to `worker` so the
     // BullMQ consumer on the API process never picks it up — even if the

package/samples/recipes/legal-pages/src/feature.ts

@@ -41,7 +41,7 @@ import {
 import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 
 // Beide Features aktivieren — template-resolver ist Foundation, legal-pages
-// requires sie. r.requires("template-resolver") greift automatisch im
+// requires sie. r.requires({ features: ["template-resolver"] }) greift automatisch im
 // legal-pages-Feature.
 export const templateResolverFeature = createTemplateResolverFeature();
 export const legalPagesFeature = createLegalPagesFeature();

package/samples/recipes/lifecycle-hooks/README.md

@@ -12,19 +12,19 @@ back.
 
 ## What it shows
 
-- **`r.hook("validation", handlerRef, fn)`** — runs before the
+- **`r.hook({ type: "validation", target: handlerRef, handler })`** — runs before the
   handler body executes. Returns either `null` (pass) or an array of
   `{ field, error }` objects (fail). Used here to reject titles
   containing the word "spam" and titles longer than 200 characters.
-- **`r.hook("postSave", { allOf: entityRef }, fn)`** — fires after every
+- **`r.hook({ type: "postSave", target: { allOf: entityRef }, handler })`** — fires after every
   successful save (create or update) in the same transaction.
   `result.isNew` distinguishes create from update; `result.changes`
   carries the changed fields only.
-- **`r.hook("preDelete", { allOf: entityRef }, fn)`** — fires inside the
+- **`r.hook({ type: "preDelete", target: { allOf: entityRef }, handler })`** — fires inside the
   delete transaction. Throws on invariant violations (here: "published
   articles cannot be deleted") to roll the delete back. The handler
   receives the full row snapshot — no extra load needed.
-- **`r.hook("postDelete", { allOf: entityRef }, fn)`** — fires after commit.
+- **`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.
 

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

@@ -38,7 +38,7 @@ export const hookLog: { type: string; data: Record<string, unknown> }[] = [];
 const editorWrite = { access: { roles: ["Admin", "Editor"] } } as const;
 
 export const articlesFeature = defineFeature("blog", (r) => {
-  const article = r.entity("article", articleEntity);
+  const article = r.entity({ name: "article", ...articleEntity });
 
   const articleCreate = r.writeHandler(
     defineEntityCreateHandler("article", articleEntity, editorWrite),
@@ -49,33 +49,45 @@ export const articlesFeature = defineFeature("blog", (r) => {
   r.writeHandler(defineEntityDeleteHandler("article", articleEntity, editorWrite));
 
   // --- Validation hook on create: reject banned words + length ---
-  r.hook("validation", articleCreate, (data) => {
-    const title = data["title"] as string;
-    if (title.toLowerCase().includes("spam")) {
-      return [{ field: "title", error: "title_contains_banned_word" }];
-    }
-    if (title.length > 200) {
-      return [{ field: "title", error: "title_too_long" }];
-    }
-    return null;
+  r.hook({
+    type: "validation",
+    target: articleCreate,
+    handler: (data) => {
+      const title = data["title"] as string;
+      if (title.toLowerCase().includes("spam")) {
+        return [{ field: "title", error: "title_contains_banned_word" }];
+      }
+      if (title.length > 200) {
+        return [{ field: "title", error: "title_too_long" }];
+      }
+      return null;
+    },
   });
 
   // --- Validation hook on update: length check on title changes ---
-  r.hook("validation", articleUpdate, (data) => {
-    const changes = data["changes"] as Record<string, unknown> | undefined;
-    const title = changes?.["title"] as string | undefined;
-    if (title && title.length > 200) {
-      return [{ field: "title", error: "title_too_long" }];
-    }
-    return null;
+  r.hook({
+    type: "validation",
+    target: articleUpdate,
+    handler: (data) => {
+      const changes = data["changes"] as Record<string, unknown> | undefined;
+      const title = changes?.["title"] as string | undefined;
+      if (title && title.length > 200) {
+        return [{ field: "title", error: "title_too_long" }];
+      }
+      return null;
+    },
   });
 
   // --- postSave entity hook: log all saves ---
-  r.hook("postSave", { allOf: article }, async (result: SaveContext) => {
-    hookLog.push({
-      type: result.isNew ? "created" : "updated",
-      data: { id: result.id, changes: result.changes },
-    });
+  r.hook({
+    type: "postSave",
+    target: { allOf: article },
+    handler: async (result: SaveContext) => {
+      hookLog.push({
+        type: result.isNew ? "created" : "updated",
+        data: { id: result.id, changes: result.changes },
+      });
+    },
   });
 
   // --- preDelete entity hook: block delete when the article is still published.
@@ -83,22 +95,30 @@ export const articlesFeature = defineFeature("blog", (r) => {
   // the delete rolls back before any projection or event is written. The
   // payload.data carries the full row snapshot taken just before delete —
   // no extra load needed.
-  r.hook("preDelete", { allOf: article }, async (payload) => {
-    if (payload.data["isPublished"] === true) {
-      throw new ConflictError({
-        message: `article ${payload.id} is still published`,
-        i18nKey: "errors.publishedArticleCannotBeDeleted",
-        details: { reason: "published_article_cannot_be_deleted", entityId: payload.id },
-      });
-    }
+  r.hook({
+    type: "preDelete",
+    target: { allOf: article },
+    handler: async (payload) => {
+      if (payload.data["isPublished"] === true) {
+        throw new ConflictError({
+          message: `article ${payload.id} is still published`,
+          i18nKey: "errors.publishedArticleCannotBeDeleted",
+          details: { reason: "published_article_cannot_be_deleted", entityId: payload.id },
+        });
+      }
+    },
   });
 
   // --- postDelete entity hook: log deletions after the transaction commits.
   // Default phase is afterCommit so failures here can't roll back the delete.
-  r.hook("postDelete", { allOf: article }, async (payload) => {
-    hookLog.push({
-      type: "deleted",
-      data: { id: payload.id },
-    });
+  r.hook({
+    type: "postDelete",
+    target: { allOf: article },
+    handler: async (payload) => {
+      hookLog.push({
+        type: "deleted",
+        data: { id: payload.id },
+      });
+    },
   });
 });

package/samples/recipes/managed-config/src/feature.ts

@@ -36,12 +36,12 @@ export const smtpHostHandle: ConfigKeyHandle<"text"> = {
 };
 
 export const integrationsFeature = defineFeature(FEATURE, (r) => {
-  r.requires("config");
+  r.requires({ features: ["config"] });
   // backing:"secrets" stores payment-api-key in the secrets envelope, which
   // the secrets feature provisions — declare the dependency so registry-build
   // enforces it instead of leaving a consumer to discover the missing
   // tenant_secrets table at runtime.
-  r.requires("secrets");
+  r.requires({ features: ["secrets"] });
 
   r.config({
     keys: {
@@ -68,15 +68,15 @@ export const integrationsFeature = defineFeature(FEATURE, (r) => {
 
   // Internal-read probe: the owning feature reads its own secrets-backed key
   // via ctx.config and receives the revealed plaintext, never the mask.
-  r.queryHandler(
-    "peek-payment-key",
-    z.object({}),
-    async (_query, ctx) => {
+  r.queryHandler({
+    name: "peek-payment-key",
+    schema: z.object({}),
+    handler: async (_query, ctx) => {
       if (!ctx.config) throw new Error("ctx.config not wired");
       return { value: await ctx.config(paymentApiKeyHandle) };
     },
-    { access: { roles: ["SystemAdmin"] } },
-  );
+    access: { roles: ["SystemAdmin"] },
+  });
 
   r.translations({
     keys: {

package/samples/recipes/managed-pages/src/feature.ts

@@ -5,7 +5,7 @@ import {
 } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 
-// managed-pages declares `r.requires("config")` for its branding keys — the
+// managed-pages declares `r.requires({ features: ["config"] })` for its branding keys — the
 // config feature must be in the stack (runProdApp auto-mounts it; setupTestStack
 // does not, so the recipe lists it explicitly).
 export const configFeature = createConfigFeature();

package/samples/recipes/notes-history-basic/README.md

@@ -68,7 +68,7 @@ The component itself is `notes-history/web/notes-section.tsx`
 ```
 notes-history    → core bundle: note-entry entity, add-note handler, list query
 task-management  → our feature: a plain `task` entity. Declares
-                   r.requires("notes-history") only so the bundle is
+                   r.requires({ features: ["notes-history"] }) only so the bundle is
                    mounted — the task itself is completely notes-agnostic.
 ```
 

package/samples/recipes/notes-history-basic/src/feature.ts

@@ -48,9 +48,9 @@ export const taskFeature = defineFeature("task-management", (r) => {
   // notes-history is non-optional for this recipe: the demo notes tasks.
   // The task feature itself stays completely notes-agnostic — it only
   // declares the dependency so the bundle is mounted.
-  r.requires("notes-history");
+  r.requires({ features: ["notes-history"] });
 
-  r.entity("task", taskEntity);
+  r.entity({ name: "task", ...taskEntity });
 
   r.writeHandler({
     name: "task:create",

package/samples/recipes/pdf-audit-export/src/feature.ts

@@ -56,20 +56,20 @@ const AUDIT_ROW_LIMIT = 100;
 const access = { access: { roles: ["Admin", "User"] } } as const;
 
 export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
-  r.entity("inspection", inspectionEntity);
+  r.entity({ name: "inspection", ...inspectionEntity });
   const { executor: inspectionExecutor } = createEntityExecutor("inspection", inspectionEntity);
 
-  r.writeHandler(
-    "inspection:create",
-    z.object({
+  r.writeHandler({
+    name: "inspection:create",
+    schema: z.object({
       assetName: z.string().min(1),
       inspectedOn: z.iso.date(),
       result: z.enum(INSPECTION_RESULTS),
       inspector: z.string().optional(),
     }),
-    async (event, ctx) => inspectionExecutor.create(event.payload, event.user, ctx.db),
-    access,
-  );
+    handler: async (event, ctx) => inspectionExecutor.create(event.payload, event.user, ctx.db),
+    ...access,
+  });
 
   r.writeHandler(
     defineWriteHandler({

package/samples/recipes/pipeline-basics/README.md

@@ -39,7 +39,7 @@ and why the combination is the production-realistic shape (not just
 an API tour).
 
 If you've only ever seen the free-form handler signature
-(`r.writeHandler(name, schema, async fn, opts)`), compare:
+(`r.writeHandler({ name, schema, handler, access })`), compare:
 
 - `samples/recipes/custom-handlers/src/feature.ts` — a similar
   domain, written in the free-form style.

package/samples/recipes/pipeline-basics/src/feature.ts

@@ -72,7 +72,7 @@ const productExecutor = createEventStoreExecutor(productTable, productEntity, {
 });
 
 export const inventoryFeature = defineFeature("inventory", (r) => {
-  r.entity("product", productEntity);
+  r.entity({ name: "product", ...productEntity });
   r.requires.projection("read_inventory_low_stock_alerts");
 
   // Domain-events on the product stream (alongside the auto-CRUD
@@ -412,13 +412,13 @@ export const inventoryFeature = defineFeature("inventory", (r) => {
   // only; queries get the existing handler signature. The list
   // below is what the integration test reads against.
   // -------------------------------------------------------------
-  r.queryHandler(
-    "low-stock-alerts:list",
-    z.object({}),
-    async (_query, ctx) => {
+  r.queryHandler({
+    name: "low-stock-alerts:list",
+    schema: z.object({}),
+    handler: async (_query, ctx) => {
       const rows = await selectMany(ctx.db, lowStockAlertsTable);
       return { rows };
     },
-    { access: { roles: ["Admin"] } },
-  );
+    access: { roles: ["Admin"] },
+  });
 });

package/samples/recipes/public-share-token/src/feature.ts

@@ -190,7 +190,7 @@ export const shareByTokenQuery = defineQueryHandler({
 });
 
 export const publicShareTokenFeature = defineFeature("public-share", (r) => {
-  r.entity("share-link", shareLinkEntity);
+  r.entity({ name: "share-link", ...shareLinkEntity });
   r.writeHandler(shareLinkCreateWrite);
   r.writeHandler(shareLinkRevokeWrite);
   r.queryHandler(shareByTokenQuery);

package/samples/recipes/rate-limiting/src/feature.ts

@@ -13,14 +13,12 @@ export function createRateLimitShowcaseFeature(): FeatureDefinition {
     // Per-user budget. Real apps tune `limit` to actual handler cost — a
     // search call against a sharded index might warrant 5/min, a full
     // export 1/min. The bucket is `user:<userId>` (see rate-limit/bucket.ts).
-    r.queryHandler(
-      "expensive-search",
-      z.object({ q: z.string().min(1) }),
-      async ({ payload }) => ({ q: payload.q, hits: 0 }),
-      {
-        access: { roles: ["Admin", "User"] },
-        rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
-      },
-    );
+    r.queryHandler({
+      name: "expensive-search",
+      schema: z.object({ q: z.string().min(1) }),
+      handler: async ({ payload }) => ({ q: payload.q, hits: 0 }),
+      access: { roles: ["Admin", "User"] },
+      rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
+    });
   });
 }

package/samples/recipes/record-detail-layout/src/feature.ts

@@ -27,10 +27,10 @@ export function createOrderDeskFeature(): FeatureDefinition {
   return defineFeature("order-desk", (r) => {
     r.systemScope();
 
-    r.queryHandler(
-      "order:detail",
-      rowIdSchema,
-      async (query) => ({
+    r.queryHandler({
+      name: "order:detail",
+      schema: rowIdSchema,
+      handler: async (query) => ({
         id: query.payload.id,
         customerName: "Aiko Tanaka",
         orderNumber: "SO-10482",
@@ -43,33 +43,33 @@ export function createOrderDeskFeature(): FeatureDefinition {
         billingAddress: "Karl-Marx-Straße 12, 12043 Berlin",
         salesRep: "Jonas Weber",
       }),
-      { access: { roles: ["Support", "Admin"] } },
-    );
+      access: { roles: ["Support", "Admin"] },
+    });
 
-    r.queryHandler(
-      "order:items",
-      rowIdSchema,
-      async () => ({
+    r.queryHandler({
+      name: "order:items",
+      schema: rowIdSchema,
+      handler: async () => ({
         rows: [
           { sku: "KB-100", description: "Mechanical keyboard", quantity: 1, unitPrice: 148 },
           { sku: "MS-220", description: "Wireless mouse", quantity: 2, unitPrice: 45 },
           { sku: "PAD-01", description: "Desk mat", quantity: 1, unitPrice: 22 },
         ],
       }),
-      { access: { roles: ["Support", "Admin"] } },
-    );
+      access: { roles: ["Support", "Admin"] },
+    });
 
-    r.queryHandler(
-      "order:payments",
-      rowIdSchema,
-      async () => ({
+    r.queryHandler({
+      name: "order:payments",
+      schema: rowIdSchema,
+      handler: async () => ({
         rows: [
           { paidAt: "2026-08-21", amount: 936, method: "card", status: "settled" },
           { paidAt: "2026-08-25", amount: 312, method: "invoice", status: "pending" },
         ],
       }),
-      { access: { roles: ["Support", "Admin"] } },
-    );
+      access: { roles: ["Support", "Admin"] },
+    });
 
     r.screen({
       id: "order-detail",

package/samples/recipes/reference-data/src/feature.ts

@@ -21,7 +21,7 @@ export const categoryTable = table("read_sample_categories", {
 });
 
 export const categoryFeature = defineFeature("catalog", (r) => {
-  r.entity("category", categoryEntity);
+  r.entity({ name: "category", ...categoryEntity });
 
   // Static reference data — seeded on boot, upserted on changes
   r.referenceData(

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

@@ -46,8 +46,8 @@ const createOnly = {
 } as const;
 
 export const relationsFeature = defineFeature("org", (r) => {
-  const team = r.entity("team", teamEntity);
-  const member = r.entity("member", memberEntity);
+  const team = r.entity({ name: "team", ...teamEntity });
+  const member = r.entity({ name: "member", ...memberEntity });
 
   r.relation(team, "members", {
     type: "hasMany",

package/samples/recipes/screens-nav/src/feature.ts

@@ -46,7 +46,7 @@ export const bookEntity = createEntity({
 export function createBookshopFeature(): FeatureDefinition {
   return defineFeature("bookshop", (r) => {
     r.systemScope();
-    r.entity("book", bookEntity);
+    r.entity({ name: "book", ...bookEntity });
 
     // entityList — columns carry string shorthand and the object form
     // side by side; the framework normalizes both through

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

@@ -26,47 +26,45 @@ export const productEntity = createEntity({
 const productTable = buildEntityTable("product", productEntity);
 
 export const productFeature = defineFeature("shop", (r) => {
-  r.entity("product", productEntity);
+  r.entity({ name: "product", ...productEntity });
 
-  r.writeHandler(
-    "product:create",
-    z.object({
+  r.writeHandler({
+    name: "product:create",
+    schema: z.object({
       name: z.string().min(1),
       brand: z.string().optional(),
       sku: z.string().min(1),
       category: z.string().optional(),
     }),
-    async (event, ctx) => {
+    handler: async (event, ctx) => {
       const crud = createEventStoreExecutor(productTable, productEntity, {
         searchAdapter: ctx.searchAdapter,
         entityName: "product",
       });
       return crud.create(event.payload, event.user, ctx.db);
     },
-    { access: { roles: ["Admin"] } },
-  );
+    access: { roles: ["Admin"] },
+  });
 
-  r.queryHandler(
-    "product:list",
-    z.object({
+  r.queryHandler({
+    name: "product:list",
+    schema: z.object({
       search: z.string().optional(),
       limit: z.number().optional(),
     }),
-    async (query, ctx) => {
+    handler: async (query, ctx) => {
       const crud = createEventStoreExecutor(productTable, productEntity, {
         searchAdapter: ctx.searchAdapter,
         entityName: "product",
       });
       return crud.list(query.payload, query.user, ctx.db);
     },
-    {
-      access: {
-        openToAll: {
-          reason:
-            "any signed-in user may search and list products in this recipe; creating " +
-            "a product still requires the Admin role above",
-        },
+    access: {
+      openToAll: {
+        reason:
+          "any signed-in user may search and list products in this recipe; creating " +
+          "a product still requires the Admin role above",
       },
     },
-  );
+  });
 });

package/samples/recipes/security-baseline/README.md

@@ -25,7 +25,7 @@ used to be silent; now the boot validator warns at `NODE_ENV=production`.
 ## Feature composition
 
 ```
-config            → tenant's r.requires("config") dependency
+config            → tenant's r.requires({ features: ["config"] }) dependency
 user              → cross-tenant identity (sessions' r.requires target)
 tenant            → memberships (audit's r.requires target)
 auth-foundation   → tokenVerifier extension point (sessions' r.requires target)

package/samples/recipes/state-machine/src/feature.ts

@@ -39,7 +39,7 @@ import type { InvoiceStatus } from "./reducer";
 export { invoiceEntity } from "./entities/invoice";
 
 export const stateMachineFeature = defineFeature("billing", (r) => {
-  r.entity("invoice", invoiceEntity);
+  r.entity({ name: "invoice", ...invoiceEntity });
 
   // Domain events — one per intent. Names live in events.ts so the reducer
   // and the projection stay in sync. The auto "invoice.created" event from

package/samples/recipes/tags-basic/README.md

@@ -77,7 +77,7 @@ See the [tags feature reference](/en/bundled-features/tags/) for the full set.
 tags             → core bundle: tag + tag-assignment entities,
                    create/assign/remove handlers, list queries
 note-management  → our feature: a plain `note` entity. Declares
-                   r.requires("tags") only so the bundle is mounted —
+                   r.requires({ features: ["tags"] }) only so the bundle is mounted —
                    the note itself is completely tag-agnostic.
 ```
 

package/samples/recipes/tags-basic/src/feature.ts

@@ -47,9 +47,9 @@ export const noteFeature = defineFeature("note-management", (r) => {
   // tags is non-optional for this recipe: the demo tags notes. The note
   // feature itself stays completely tag-agnostic — it only declares the
   // dependency so the bundle is mounted.
-  r.requires("tags");
+  r.requires({ features: ["tags"] });
 
-  r.entity("note", noteEntity);
+  r.entity({ name: "note", ...noteEntity });
 
   r.writeHandler({
     name: "note:create",

package/samples/recipes/tenant-settings/README.md

@@ -27,7 +27,7 @@ export const invoiceEntity = createEntity({
 });
 
 export const invoiceFeature = defineFeature("invoice", (r) => {
-  r.entity("invoice", invoiceEntity);
+  r.entity({ name: "invoice", ...invoiceEntity });
   r.writeHandler(
     defineCreateWithTenantDefaults("invoice", invoiceEntity, {
       access: { roles: ["Admin"] },

package/samples/recipes/tenant-settings/src/feature.ts

@@ -24,7 +24,7 @@ export const invoiceEntity = createEntity({
 const ACCESS = { roles: ["Admin"] } as const;
 
 export const invoiceFeature = defineFeature("invoice", (r) => {
-  r.entity("invoice", invoiceEntity);
+  r.entity({ name: "invoice", ...invoiceEntity });
   r.writeHandler(
     defineCreateWithTenantDefaults("invoice", invoiceEntity, {
       access: ACCESS,

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

@@ -43,12 +43,12 @@ export const timezonesFeature = defineFeature("timezones", (r) => {
   });
   r.writeHandler(defineEntityDeleteHandler("delivery", deliveryEntity, adminWrite));
 
-  r.queryHandler(
-    "day-window",
-    z.object({
+  r.queryHandler({
+    name: "day-window",
+    schema: z.object({
       zone: z.string().refine(isValidIanaTimeZone, { message: "Invalid IANA timezone" }),
     }),
-    async (query, ctx) => {
+    handler: async (query, ctx) => {
       const { start, end } = ctx.tz.todayRange(query.payload.zone);
       return {
         zone: query.payload.zone,
@@ -57,16 +57,16 @@ export const timezonesFeature = defineFeature("timezones", (r) => {
         end: end.toString(),
       };
     },
-    openRead,
-  );
+    ...openRead,
+  });
 
-  r.queryHandler(
-    "zone-at",
-    z.object({ latitude: z.number(), longitude: z.number() }),
-    async (query, ctx) => {
+  r.queryHandler({
+    name: "zone-at",
+    schema: z.object({ latitude: z.number(), longitude: z.number() }),
+    handler: async (query, ctx) => {
       const zone = await ctx.tz.fromCoordinates(query.payload);
       return { zone };
     },
-    openRead,
-  );
+    ...openRead,
+  });
 });