@cosmicdrift/kumiko-framework 0.365.1 → 0.366.0

package/agents/examples/designer-demo.md

@@ -42,7 +42,8 @@ import { z } from "zod";
 defineFeature("designerDemo", (r) => {
   r.optionalRequires("analytics");
 
-  r.entity("task", {
+  r.entity({
+    name: "task",
     fields: {
       title: { type: "text", required: true },
       done: { type: "boolean", default: false },

package/agents/examples/embedded-entity-form.md

@@ -384,7 +384,7 @@ export const prospectsFeature = defineFeature("prospects", (r) => {
     read: openRead,
     verbs: { update: false },
   });
-  r.entity("prospect", prospectEntity);
+  r.entity({ name: "prospect", ...prospectEntity });
 
   const { executor: suggestionExecutor } = createEntityExecutor("suggestion", suggestionEntity);
   const { executor: prospectExecutor } = createEntityExecutor("prospect", prospectEntity);
@@ -393,10 +393,10 @@ export const prospectsFeature = defineFeature("prospects", (r) => {
   // edited (RenderEdit's onChange `changes`, same delta the controlled mode
   // reports) — the handler owns merging that onto the suggestion it already
   // has, so an untouched field never has to round-trip through the browser.
-  r.writeHandler(
-    "prospect:accept",
-    z.object({ suggestionId: z.uuid(), changes: acceptChangesSchema }),
-    async (event, ctx) => {
+  r.writeHandler({
+    name: "prospect:accept",
+    schema: z.object({ suggestionId: z.uuid(), changes: acceptChangesSchema }),
+    handler: async (event, ctx) => {
       const suggestion = await suggestionExecutor.detail(
         { id: event.payload.suggestionId },
         event.user,
@@ -437,15 +437,15 @@ export const prospectsFeature = defineFeature("prospects", (r) => {
       if (!flipped.isSuccess) return flipped;
       return created;
     },
-    adminWrite,
-  );
+    ...adminWrite,
+  });
 
-  r.queryHandler(
-    "prospect:detail",
-    z.object({ id: z.uuid() }),
-    async (query, ctx) => prospectExecutor.detail(query.payload, query.user, ctx.db),
-    openRead,
-  );
+  r.queryHandler({
+    name: "prospect:detail",
+    schema: z.object({ id: z.uuid() }),
+    handler: async (query, ctx) => prospectExecutor.detail(query.payload, query.user, ctx.db),
+    ...openRead,
+  });
 });
 ```
 

package/agents/examples/embedded.md

@@ -554,7 +554,7 @@ const openRead = {
 } as const;
 
 export const embeddedFeature = defineFeature("contacts", (r) => {
-  r.entity("contact", contactEntity);
+  r.entity({ name: "contact", ...contactEntity });
 
   r.writeHandler(contactCreate);
   r.queryHandler(contactDetail);

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

@@ -393,7 +393,7 @@ const chargeHandler = defineWriteHandler({
 });
 
 export const billingFeature = defineFeature(FEATURE, (r) => {
-  r.requires("config");
+  r.requires({ features: ["config"] });
   r.config("stripe-api-key", stripeApiKeyDef);
   r.writeHandler(chargeHandler);
   // Kein r.screen/r.nav: der `mask`-Eintrag auf dem Key lässt

package/agents/examples/error-contract.md

@@ -370,17 +370,17 @@ export const orderEntity = createEntity({
 const orderTable = buildEntityTable("order", orderEntity);
 
 export const ordersLiteFeature = defineFeature("orders-lite", (r) => {
-  r.entity("order", orderEntity);
+  r.entity({ name: "order", ...orderEntity });
 
   // 1) Create — standard path. Zod schema rejects an empty cart; the
   //    dispatcher converts the ZodIssue into a ValidationError with
   //    details.fields[] (no handler code needed).
-  r.writeHandler(
-    "order:create",
-    z.object({
+  r.writeHandler({
+    name: "order:create",
+    schema: z.object({
       totalCents: z.number().int().min(1, "cart_is_empty"),
     }),
-    async (event, ctx) => {
+    handler: async (event, ctx) => {
       const crud = createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" });
       return crud.create(
         { ...event.payload, ownerId: event.user.id, status: "draft" },
@@ -388,8 +388,8 @@ export const ordersLiteFeature = defineFeature("orders-lite", (r) => {
         ctx.db,
       );
     },
-    { access: { roles: ["User", "Admin"] } },
-  );
+    access: { roles: ["User", "Admin"] },
+  });
 
   // 2) Pay — business rule: only placed orders can be paid. Shows three
   //    different failure shapes in a single handler:
@@ -399,10 +399,10 @@ export const ordersLiteFeature = defineFeature("orders-lite", (r) => {
   //      - UnprocessableError with reason from OrdersLiteReasons
   //      - Framework-generated UnprocessableError with reason
   //        FrameworkReasons.invalidTransition via guardTransition
-  r.writeHandler(
-    "order:pay",
-    z.object({ id: z.uuid() }),
-    async (event, ctx) => {
+  r.writeHandler({
+    name: "order:pay",
+    schema: z.object({ id: z.uuid() }),
+    handler: async (event, ctx) => {
       const [current] = await ctx.db.selectMany(orderTable, { id: event.payload.id });
 
       // NotFoundError — automatic reason = "order_not_found" via snake-case
@@ -449,16 +449,16 @@ export const ordersLiteFeature = defineFeature("orders-lite", (r) => {
         ctx.db,
       );
     },
-    { access: { roles: ["User", "Admin"] } },
-  );
+    access: { roles: ["User", "Admin"] },
+  });
 
   // 3) Cancel — shows ConflictError for a business conflict that isn't a
   //    transition or a stale write. E.g. a refund window expired; the row
   //    is fine but the action is no longer allowed.
-  r.writeHandler(
-    "order:cancel",
-    z.object({ id: z.uuid() }),
-    async (event, ctx) => {
+  r.writeHandler({
+    name: "order:cancel",
+    schema: z.object({ id: z.uuid() }),
+    handler: async (event, ctx) => {
       const [current] = await ctx.db.selectMany(orderTable, { id: event.payload.id });
       if (!current) return failNotFound("order", event.payload.id);
 
@@ -488,18 +488,18 @@ export const ordersLiteFeature = defineFeature("orders-lite", (r) => {
         ctx.db,
       );
     },
-    { access: { roles: ["User", "Admin"] } },
-  );
+    access: { roles: ["User", "Admin"] },
+  });
 
   // 4) Update — demonstrates the throw-based path (KumikoError raised
   //    directly, not via writeFailure return). The dispatcher catches it
   //    and wraps it in a WriteErrorInfo the same as the return path.
   //    Use this style when a helper deep in the call tree needs to abort
   //    without threading a WriteResult back up.
-  r.writeHandler(
-    "order:rename",
-    z.object({ id: z.uuid(), nickname: z.string().min(1) }),
-    async (event, ctx) => {
+  r.writeHandler({
+    name: "order:rename",
+    schema: z.object({ id: z.uuid(), nickname: z.string().min(1) }),
+    handler: async (event, ctx) => {
       const [current] = await ctx.db.selectMany(orderTable, { id: event.payload.id });
 
       if (!current) {
@@ -529,7 +529,7 @@ export const ordersLiteFeature = defineFeature("orders-lite", (r) => {
         },
       };
     },
-    { access: { roles: ["User", "Admin"] } },
-  );
+    access: { roles: ["User", "Admin"] },
+  });
 });
 ```

package/agents/examples/event-sourcing.md

@@ -793,6 +793,32 @@ describe("Event Sourcing Showcase", () => {
     expect(body.error.details?.bucket).toBe("user");
   });
 });
+
+describe("role-restricted write handlers", () => {
+  const viewer = createTestUser({ id: 2, roles: ["Viewer"] });
+
+  test("a caller without the Admin role is rejected on acknowledge and take-snapshot", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      "showcase:write:invoice:create",
+      { customer: "Acme" },
+      admin,
+    );
+
+    const acknowledgeError = await stack.http.writeErr(
+      "showcase:write:invoice:acknowledge",
+      { id, approverId: "u-42" },
+      viewer,
+    );
+    const snapshotError = await stack.http.writeErr(
+      "showcase:write:invoice:take-snapshot",
+      { id },
+      viewer,
+    );
+
+    expect(acknowledgeError.code).toBe("access_denied");
+    expect(snapshotError.code).toBe("access_denied");
+  });
+});
 ```
 
 ### src/feature.ts
@@ -926,7 +952,7 @@ export const approverDirectoryTable = table("read_showcase_approver_directory",
 // --- Feature ---
 
 export const invoiceFeature = defineFeature("showcase", (r) => {
-  r.entity("showcase-invoice", invoiceEntity);
+  r.entity({ name: "showcase-invoice", ...invoiceEntity });
 
   // Two domain events. "approved" is versioned — v1 stored `amount` as
   // string, v2 uses `amountCents` integer. The DECLARATIVE migration form
@@ -1059,21 +1085,21 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
 
   // --- Write handlers ---
 
-  r.writeHandler(
-    "invoice:create",
-    z.object({ customer: z.string() }),
-    async (event, ctx) =>
+  r.writeHandler({
+    name: "invoice:create",
+    schema: z.object({ customer: z.string() }),
+    handler: async (event, ctx) =>
       invoiceExecutor.create(
         { customer: event.payload.customer, status: "draft" },
         event.user,
         ctx.db,
       ),
-    { access: { roles: ["Admin"] } },
-  );
+    access: { roles: ["Admin"] },
+  });
 
-  r.writeHandler(
-    "invoice:approve",
-    z.object({
+  r.writeHandler({
+    name: "invoice:approve",
+    schema: z.object({
       id: z.uuid(),
       amountCents: z.number().int(),
       approvedBy: z.string(),
@@ -1082,7 +1108,7 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
       geoRegion: z.string().optional(),
       abTestBucket: z.string().optional(),
     }),
-    async (event, ctx) => {
+    handler: async (event, ctx) => {
       const headers: Record<string, string> = {};
       if (event.payload.geoRegion) headers["geoRegion"] = event.payload.geoRegion;
       if (event.payload.abTestBucket) headers["abTestBucket"] = event.payload.abTestBucket;
@@ -1095,13 +1121,13 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
       });
       return { isSuccess: true as const, data: { id: event.payload.id } };
     },
-    { access: { roles: ["Admin"] } },
-  );
+    access: { roles: ["Admin"] },
+  });
 
-  r.writeHandler(
-    "invoice:acknowledge",
-    z.object({ id: z.uuid(), approverId: z.string() }),
-    async (event, ctx) => {
+  r.writeHandler({
+    name: "invoice:acknowledge",
+    schema: z.object({ id: z.uuid(), approverId: z.string() }),
+    handler: async (event, ctx) => {
       const row = await fetchOne<{ displayName: string }>(ctx.db, approverDirectoryTable, {
         approverId: event.payload.approverId,
       });
@@ -1114,13 +1140,13 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
       });
       return { isSuccess: true as const, data: { id: event.payload.id } };
     },
-    { access: { roles: ["Admin"] } },
-  );
+    access: { roles: ["Admin"] },
+  });
 
-  r.writeHandler(
-    "invoice:pay",
-    z.object({ id: z.uuid(), amountCents: z.number().int() }),
-    async (event, ctx) => {
+  r.writeHandler({
+    name: "invoice:pay",
+    schema: z.object({ id: z.uuid(), amountCents: z.number().int() }),
+    handler: async (event, ctx) => {
       await ctx.appendEvent({
         aggregateId: event.payload.id,
         aggregateType: "showcase-invoice",
@@ -1129,35 +1155,33 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
       });
       return { isSuccess: true as const, data: { id: event.payload.id } };
     },
-    {
-      access: { roles: ["Admin"] },
-      // Per-user cap: a single admin shouldn't fire more than 5 pay
-      // operations per minute. Real production caps would be per
-      // tenant + handler ("tenant+handler") to keep one admin from
-      // monopolising the tenant's quota — kept simple here for the
-      // sample. Demonstrates the fourth dispatcher gate (rate-limit
-      // → access → validation → handler).
-      rateLimit: { per: "user", limit: 5, windowSeconds: 60 },
-    },
-  );
+    access: { roles: ["Admin"] },
+    // Per-user cap: a single admin shouldn't fire more than 5 pay
+    // operations per minute. Real production caps would be per
+    // tenant + handler ("tenant+handler") to keep one admin from
+    // monopolising the tenant's quota — kept simple here for the
+    // sample. Demonstrates the fourth dispatcher gate (rate-limit
+    // → access → validation → handler).
+    rateLimit: { per: "user", limit: 5, windowSeconds: 60 },
+  });
 
-  r.writeHandler(
-    "invoice:archive",
-    z.object({ id: z.uuid() }),
-    async (event, ctx) => {
+  r.writeHandler({
+    name: "invoice:archive",
+    schema: z.object({ id: z.uuid() }),
+    handler: async (event, ctx) => {
       await ctx.archiveStream(event.payload.id, { aggregateType: "showcase-invoice" });
       return { isSuccess: true as const, data: { id: event.payload.id } };
     },
-    { access: { roles: ["Admin"] } },
-  );
+    access: { roles: ["Admin"] },
+  });
 
   // Persist a snapshot of the current state. In practice, features schedule
   // this from a lifecycle hook (every N events, every M minutes) — here it's
   // an explicit write-handler so the integration test can drive it.
-  r.writeHandler(
-    "invoice:take-snapshot",
-    z.object({ id: z.uuid() }),
-    async (event, ctx) => {
+  r.writeHandler({
+    name: "invoice:take-snapshot",
+    schema: z.object({ id: z.uuid() }),
+    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.
@@ -1175,17 +1199,17 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
       });
       return { isSuccess: true as const, data: { id: event.payload.id, snapshotVersion: version } };
     },
-    { access: { roles: ["Admin"] } },
-  );
+    access: { roles: ["Admin"] },
+  });
 
   // --- Query handlers ---
 
   // Live aggregation via ctx.loadAggregate — reduces events into a state
   // snapshot. Supports asOf for point-in-time reads.
-  r.queryHandler(
-    "invoice:state",
-    z.object({ id: z.uuid(), asOf: z.iso.datetime().optional() }),
-    async (query, ctx) => {
+  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, {
         ...(query.payload.asOf ? { asOf: Temporal.Instant.from(query.payload.asOf) } : {}),
       });
@@ -1195,24 +1219,22 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
       }
       return state;
     },
-    {
-      access: {
-        openToAll: {
-          reason:
-            "demo recipe: any signed-in user may read the event-sourced invoice state; " +
-            "there is no per-user invoice ownership in this sample",
-        },
+    access: {
+      openToAll: {
+        reason:
+          "demo recipe: any signed-in user may read the event-sourced invoice state; " +
+          "there is no per-user invoice ownership in this sample",
       },
     },
-  );
+  });
 
   // Snapshot-aware fast path. Uses the latest snapshot if available and
   // only replays delta events past it. Identical state shape to
   // invoice:state — the two are interchangeable modulo the perf profile.
-  r.queryHandler(
-    "invoice:fast-state",
-    z.object({ id: z.uuid() }),
-    async (query, ctx) => {
+  r.queryHandler({
+    name: "invoice:fast-state",
+    schema: z.object({ id: z.uuid() }),
+    handler: async (query, ctx) => {
       const result = await ctx.loadAggregateWithSnapshot<InvoiceStateRecord>(
         query.payload.id,
         (state, evt) => {
@@ -1233,16 +1255,14 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
         snapshotHit: result.snapshotHit,
       };
     },
-    {
-      access: {
-        openToAll: {
-          reason:
-            "demo recipe: any signed-in user may read the snapshot-accelerated invoice " +
-            "state; there is no per-user invoice ownership in this sample",
-        },
+    access: {
+      openToAll: {
+        reason:
+          "demo recipe: any signed-in user may read the snapshot-accelerated invoice " +
+          "state; there is no per-user invoice ownership in this sample",
       },
     },
-  );
+  });
 
   // Read-model query via ctx.queryProjection — auto-tenant-scoped. The
   // helper collapses the zero-argument "return this projection" pattern
@@ -1267,10 +1287,10 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
   // bytes nobody will read. The handler checks ctx.signal at every
   // iteration; on abort, throws and the dispatcher returns an error to
   // the (already-disconnected) client.
-  r.queryHandler(
-    "ops:slow-export",
-    z.object({ chunks: z.number().int().min(1).max(1000) }),
-    async (query, ctx) => {
+  r.queryHandler({
+    name: "ops:slow-export",
+    schema: z.object({ chunks: z.number().int().min(1).max(1000) }),
+    handler: async (query, ctx) => {
       const accumulated: number[] = [];
       for (let i = 0; i < query.payload.chunks; i++) {
         ctx.signal?.throwIfAborted();
@@ -1281,7 +1301,7 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
       }
       return { processed: accumulated.length };
     },
-    { access: { roles: ["Admin"] } },
-  );
+    access: { roles: ["Admin"] },
+  });
 });
 ```

package/agents/examples/feature-toggles.md

@@ -209,11 +209,11 @@ export function createProductFeature(): FeatureDefinition {
   return defineFeature("product", (r) => {
     r.systemScope();
     r.toggleable({ default: true });
-    r.entity("product", productEntity);
-    r.writeHandler(
-      "product:create",
-      z.object({ name: z.string().min(1).max(100) }),
-      async (event, ctx) => {
+    r.entity({ name: "product", ...productEntity });
+    r.writeHandler({
+      name: "product:create",
+      schema: z.object({ name: z.string().min(1).max(100) }),
+      handler: async (event, ctx) => {
         if (!ctx.systemDb) {
           throw new InternalError({
             message: "product:create requires ctx.systemDb — is r.systemScope() still set?",
@@ -224,8 +224,8 @@ export function createProductFeature(): FeatureDefinition {
         );
         return productCrud.create(event.payload, event.user, db);
       },
-      { access: { roles: ["SystemAdmin"] } },
-    );
+      access: { roles: ["SystemAdmin"] },
+    });
   });
 }
 
@@ -254,20 +254,28 @@ export function createProductAuditFeature(): FeatureDefinition {
   return defineFeature("product-audit", (r) => {
     r.systemScope();
     r.toggleable({ default: true });
-    r.entity("product-audit", productAuditEntity);
-
-    r.hook("postSave", { allOf: "product" }, async (result, ctx) => {
-      if (result.kind !== "save" || !result.isNew) return;
-      if (!ctx.systemDb) return;
-      const name = (result.changes as Record<string, unknown>)["name"] as string | undefined;
-      if (!name) return;
-      const db = ctx.systemDb.acknowledgeCrossTenant(
-        "audit sink is system-wide, mirrors the system-wide product catalog",
-      );
-      // Cross-feature audit sink is itself an r.entity projection — write it via
-      // the executor (system actor, no human caller) so the row is event-backed
-      // and survives a rebuild, not a direct method-form insert.
-      await productAuditCrud.create({ productName: name }, createSystemUser(SYSTEM_TENANT_ID), db);
+    r.entity({ name: "product-audit", ...productAuditEntity });
+
+    r.hook({
+      type: "postSave",
+      target: { allOf: "product" },
+      handler: async (result, ctx) => {
+        if (result.kind !== "save" || !result.isNew) return;
+        if (!ctx.systemDb) return;
+        const name = (result.changes as Record<string, unknown>)["name"] as string | undefined;
+        if (!name) return;
+        const db = ctx.systemDb.acknowledgeCrossTenant(
+          "audit sink is system-wide, mirrors the system-wide product catalog",
+        );
+        // Cross-feature audit sink is itself an r.entity projection — write it via
+        // the executor (system actor, no human caller) so the row is event-backed
+        // and survives a rebuild, not a direct method-form insert.
+        await productAuditCrud.create(
+          { productName: name },
+          createSystemUser(SYSTEM_TENANT_ID),
+          db,
+        );
+      },
     });
   });
 }

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

@@ -343,8 +343,8 @@ export const publishedPhotoIds = new Set<string>();
 export const coverOrder: string[] = [];
 
 export const filesPostProcessingFeature = defineFeature("files-post-processing", (r) => {
-  r.requires("file-derivatives");
-  r.entity("photo", photoEntity);
+  r.requires({ features: ["file-derivatives"] });
+  r.entity({ name: "photo", ...photoEntity });
 
   // Uploading a file to a photo's field needs the same rights as saving the
   // photo, so the photo must exist and the uploader needs update access.
@@ -355,9 +355,9 @@ export const filesPostProcessingFeature = defineFeature("files-post-processing",
 
   // Entry point 2 — imperative. A real app would gate this behind real
   // roles; `openToAll` keeps the recipe's HTTP wiring to one line.
-  r.writeHandler(
-    "set-cover",
-    z.object({
+  r.writeHandler({
+    name: "set-cover",
+    schema: z.object({
       fileRefId: z.string(),
       // Relative to the ORIGINAL image's pixels, clamped before resize —
       // runtime data (e.g. a detected face box), which is exactly why this
@@ -371,7 +371,7 @@ export const filesPostProcessingFeature = defineFeature("files-post-processing",
         })
         .optional(),
     }),
-    async (event, ctx) => {
+    handler: async (event, ctx) => {
       if (!ctx.derivatives) {
         return writeFailure(
           new InternalError({ message: "ctx.derivatives missing — is file-derivatives mounted?" }),
@@ -391,36 +391,32 @@ export const filesPostProcessingFeature = defineFeature("files-post-processing",
       coverOrder.push(fileRefId);
       return { isSuccess: true as const, data: { fileRefId, storageKey: result.storageKey } };
     },
-    {
-      access: {
-        openToAll: {
-          reason:
-            "demo recipe: any signed-in user may generate a cover-image derivative for " +
-            "a file; there is no per-user file ownership check in this sample",
-        },
+    access: {
+      openToAll: {
+        reason:
+          "demo recipe: any signed-in user may generate a cover-image derivative for " +
+          "a file; there is no per-user file ownership check in this sample",
       },
     },
-  );
+  });
 
   // A real app would gate this behind real roles; `openToAll` keeps the
   // recipe's HTTP wiring to one line.
-  r.writeHandler(
-    "publish",
-    z.object({ entityId: z.string() }),
-    async (event) => {
+  r.writeHandler({
+    name: "publish",
+    schema: z.object({ entityId: z.string() }),
+    handler: async (event) => {
       publishedPhotoIds.add(`${event.user.tenantId}:${event.payload.entityId}`);
       return { isSuccess: true as const, data: { entityId: event.payload.entityId } };
     },
-    {
-      access: {
-        openToAll: {
-          reason:
-            "demo recipe: any signed-in user may mark a photo entity published; a real " +
-            "app would replace this with a role check as noted above",
-        },
+    access: {
+      openToAll: {
+        reason:
+          "demo recipe: any signed-in user may mark a photo entity published; a real " +
+          "app would replace this with a role check as noted above",
       },
     },
-  );
+  });
 
   // Entry point 3 — default-deny. No registration here means every entityId
   // 404s; a registration that returns false does the same. Only an explicit