@cosmicdrift/kumiko-samples 0.365.1 → 0.366.0

package/samples/recipes/error-contract/src/feature.ts

@@ -74,17 +74,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" },
@@ -92,8 +92,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:
@@ -103,10 +103,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
@@ -153,16 +153,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);
 
@@ -192,18 +192,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) {
@@ -233,6 +233,6 @@ export const ordersLiteFeature = defineFeature("orders-lite", (r) => {
         },
       };
     },
-    { access: { roles: ["User", "Admin"] } },
-  );
+    access: { roles: ["User", "Admin"] },
+  });
 });

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

@@ -126,7 +126,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
@@ -259,21 +259,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(),
@@ -282,7 +282,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;
@@ -295,13 +295,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,
       });
@@ -314,13 +314,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",
@@ -329,35 +329,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.
@@ -375,17 +373,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) } : {}),
       });
@@ -395,24 +393,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) => {
@@ -433,16 +429,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
@@ -467,10 +461,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();
@@ -481,6 +475,6 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
       }
       return { processed: accumulated.length };
     },
-    { access: { roles: ["Admin"] } },
-  );
+    access: { roles: ["Admin"] },
+  });
 });

package/samples/recipes/feature-toggles/src/feature.ts

@@ -47,11 +47,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?",
@@ -62,8 +62,8 @@ export function createProductFeature(): FeatureDefinition {
         );
         return productCrud.create(event.payload, event.user, db);
       },
-      { access: { roles: ["SystemAdmin"] } },
-    );
+      access: { roles: ["SystemAdmin"] },
+    });
   });
 }
 
@@ -92,20 +92,28 @@ export function createProductAuditFeature(): FeatureDefinition {
   return defineFeature("product-audit", (r) => {
     r.systemScope();
     r.toggleable({ default: true });
-    r.entity("product-audit", productAuditEntity);
+    r.entity({ name: "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.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/samples/recipes/files-post-processing/src/feature.ts

@@ -59,8 +59,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.
@@ -71,9 +71,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
@@ -87,7 +87,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?" }),
@@ -107,36 +107,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

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

@@ -19,32 +19,30 @@ export const orderEntity = createEntity({
 
 const orderTable = buildEntityTable("order", orderEntity);
 export const orderFeature = defineFeature("orders", (r) => {
-  r.entity("order", orderEntity);
+  r.entity({ name: "order", ...orderEntity });
 
   const orderExecutor = createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" });
 
-  r.writeHandler(
-    "order:place",
-    z.object({
+  r.writeHandler({
+    name: "order:place",
+    schema: z.object({
       customerName: z.string().min(1),
       product: z.string().min(1),
     }),
-    async (event, ctx) =>
+    handler: async (event, ctx) =>
       orderExecutor.create({ ...event.payload, status: "pending" }, event.user, ctx.db),
-    { access: { roles: ["Admin", "Customer"] } },
-  );
+    access: { roles: ["Admin", "Customer"] },
+  });
 
-  r.queryHandler(
-    "order:list",
-    z.object({ limit: z.number().optional() }),
-    async (query, ctx) => orderExecutor.list(query.payload, query.user, ctx.db),
-    {
-      access: {
-        openToAll: {
-          reason:
-            "any signed-in user may list orders in this recipe; placing an order still requires a role above",
-        },
+  r.queryHandler({
+    name: "order:list",
+    schema: z.object({ limit: z.number().optional() }),
+    handler: async (query, ctx) => orderExecutor.list(query.payload, query.user, ctx.db),
+    access: {
+      openToAll: {
+        reason:
+          "any signed-in user may list orders in this recipe; placing an order still requires a role above",
       },
     },
-  );
+  });
 });

package/samples/recipes/inbound-mail-triage/src/feature.ts

@@ -40,7 +40,7 @@ export function createMailTriageFeature(): FeatureDefinition {
     r.describe(
       "Sample consumer for inbound-mail-foundation: a worker-lane job triggered by the ingest-message write-handler turns every inbound mail into a triage item.",
     );
-    r.requires("inbound-mail-foundation");
+    r.requires({ features: ["inbound-mail-foundation"] });
 
     // The job receives the dispatcher-validated ingest payload — i.e.
     // the PLAINTEXT normalized mail (PII encryption happens inside the

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.