@cosmicdrift/kumiko-framework 0.154.0 → 0.154.2

package/src/engine/types/feature.ts

@@ -298,7 +298,7 @@ export type FeatureDefinition = {
   readonly referenceData: readonly ReferenceDataDef[];
   readonly notifications: Readonly<Record<string, NotificationDefinition>>;
   readonly events: Readonly<Record<string, EventDef>>;
-  // Event schema migrations declared via r.eventMigration(). Keyed by event
+  // Event schema migrations declared via defineEvent's `migrations` option. Keyed by event
   // short-name; each entry carries the step transforms (fromVersion →
   // toVersion). The registry stitches these with the defineEvent-declared
   // current version and exposes a per-qualified-name upcaster chain.
@@ -381,6 +381,12 @@ export type FeatureDefinition = {
 // --- Feature Registrar (the "r" object in defineFeature) ---
 
 type RefOrRefs = NameOrRef | readonly NameOrRef[];
+// Entity-wide hook target — "all query/write handlers of this entity",
+// same reach r.entityHook() used to have. Only valid for postSave/
+// preDelete/postDelete/postQuery (the same 4 types entityHook covered);
+// hook() throws at registration time if used with validation/preSave/
+// preQuery.
+type HookTarget = RefOrRefs | { readonly allOf: NameOrRef };
 
 /**
  * `TFeature` is the literal feature-name from `defineFeature("foo", ...)` —
@@ -399,11 +405,16 @@ type RefOrRefs = NameOrRef | readonly NameOrRef[];
  * steps are allowed to write via `r.step.unsafeProjectionUpsert`.
  * Hard-required for any unsafeProjection-* step usage (see Q10).
  */
-export type RequiresApi = ((...featureNames: string[]) => void) & {
-  readonly projection: (tableName: string) => void;
-  // Tier-2 step opt-in (Q9). Tier-1 implicit, Tier-2 must be declared.
-  readonly step: (stepKind: string) => void;
-};
+export type RequiresApi = ((...featureNames: string[]) => void) &
+  // Object-Form — the shape the feature-ast renderer (`render.ts`) emits
+  // for Designer/AI-generated code. A single object argument with named
+  // fields is easier to generate correctly than positional args whose
+  // count/order vary per registrar method.
+  ((options: { readonly features: readonly string[] }) => void) & {
+    readonly projection: (tableName: string) => void;
+    // Tier-2 step opt-in (Q9). Tier-1 implicit, Tier-2 must be declared.
+    readonly step: (stepKind: string) => void;
+  };
 
 export type FeatureRegistrar<TFeature extends string = string> = {
   systemScope(): void;
@@ -412,6 +423,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   describe(text: string): void;
   requires: RequiresApi;
   optionalRequires(...featureNames: string[]): void;
+  optionalRequires(options: { readonly features: readonly string[] }): void;
   // Declare the feature as operator-togglable. `default` is the effective
   // state when no global-toggle row exists. Must be called at most once per
   // feature; calling on an always-on feature (e.g. auth/tenant/user) is a
@@ -425,6 +437,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     definition: EntityDefinition,
     options?: { readonly table?: unknown },
   ): EntityRef;
+  entity(definition: { readonly name: string } & EntityDefinition): EntityRef;
 
   // One-call CRUD for an event-sourced entity — delegates to registerEntityCrud():
   // r.entity + create/update/delete/restore/list/detail handlers per verb flag.
@@ -452,45 +465,39 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   ): HandlerRef;
 
   relation(entity: NameOrRef, relationName: string, definition: RelationDefinition): void;
+  // TDef inferred from the literal — keeps the excess-property check
+  // resolved against the matching RelationDefinition union member instead
+  // of distributing across all three (which spuriously rejects valid
+  // combinations when checked directly against the raw union).
+  relation<TDef extends RelationDefinition>(
+    definition: { readonly entity: NameOrRef; readonly name: string } & TDef,
+  ): void;
 
   hook(type: "validation", target: RefOrRefs, fn: ValidationHookFn): void;
   hook(type: "preSave", target: RefOrRefs, fn: PreSaveHookFn): void;
+  // postSave/preDelete/postDelete/postQuery accept `{ allOf: entityRef }` —
+  // fires for every write/query handler of that entity, replacing the old
+  // r.entityHook(type, entity, fn). postQuery's entity-wide form fires for
+  // ALL query-handlers of the entity (e.g. customFields-bundle merging
+  // custom-fields-jsonb into every read); no phase semantics there
+  // (synchronous after handler-execute, before field-access-filter).
   hook(
     type: "postSave",
-    target: RefOrRefs,
+    target: HookTarget,
     fn: PostSaveHookFn,
     options?: { phase?: HookPhase },
   ): void;
   // preDelete always runs in-transaction (it guards the delete — there is no
   // meaningful "after" for a pre-hook). No phase option.
-  hook(type: "preDelete", target: RefOrRefs, fn: PreDeleteHookFn): void;
+  hook(type: "preDelete", target: HookTarget, fn: PreDeleteHookFn): void;
   hook(
     type: "postDelete",
-    target: RefOrRefs,
+    target: HookTarget,
     fn: PostDeleteHookFn,
     options?: { phase?: HookPhase },
   ): void;
   hook(type: "preQuery", target: RefOrRefs, fn: PreQueryHookFn): void;
-  hook(type: "postQuery", target: RefOrRefs, fn: PostQueryHookFn): void;
-
-  entityHook(
-    type: "postSave",
-    entity: NameOrRef,
-    fn: PostSaveHookFn,
-    options?: { phase?: HookPhase },
-  ): void;
-  entityHook(type: "preDelete", entity: NameOrRef, fn: PreDeleteHookFn): void;
-  entityHook(
-    type: "postDelete",
-    entity: NameOrRef,
-    fn: PostDeleteHookFn,
-    options?: { phase?: HookPhase },
-  ): void;
-  // postQuery-entityHook: fires for ALL query-handlers of this entity (e.g.,
-  // for customFields-bundle to merge custom-fields-jsonb into every read).
-  // No phase semantics (synchronous after handler-execute, before field-
-  // access-filter).
-  entityHook(type: "postQuery", entity: NameOrRef, fn: PostQueryHookFn): void;
+  hook(type: "postQuery", target: HookTarget, fn: PostQueryHookFn): void;
 
   // F3 — Search-Payload-Extension: contributor function adds flat fields to
   // an entity's search-index document. Fires synchronously during
@@ -514,6 +521,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> };
 
   job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
+  job(definition: JobDefinition): void;
 
   notification(
     name: string,
@@ -524,6 +532,13 @@ export type FeatureRegistrar<TFeature extends string = string> = {
       readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
     },
   ): void;
+  notification(definition: {
+    readonly name: string;
+    readonly trigger: { readonly on: NameOrRef };
+    readonly recipient: NotificationRecipientFn;
+    readonly data: NotificationDataFn;
+    readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+  }): void;
 
   translations(def: TranslationsDef): void;
 
@@ -532,9 +547,14 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // "<feature>:event:<short>" string.
   //
   // `options.version` declares the CURRENT schema generation. Defaults to 1
-  // on first registration. When you bump the payload shape, raise version
-  // AND register r.eventMigration(shortName, N, N+1, transform) — the
-  // framework refuses to boot if the chain from 1 → version has gaps.
+  // on first registration. When you bump the payload shape, add a step to
+  // `options.migrations` covering N -> N+1 — the framework refuses to boot
+  // if the chain from 1 to `version` has gaps. Migrations were formerly a
+  // separate r.eventMigration() call; folded in here because an event and
+  // its schema evolution are one lifecycle, not two registrar concepts
+  // (#1082 step 8) — transforms are pure functions (old payload in, new
+  // payload out) and run once per read, not once per event persisted, so
+  // keep them cheap.
   //
   // `options.piiFields` declares PII payload fields encrypted under the DEK
   // of the user named by `subjectField` (crypto-shredding, #799). append()
@@ -542,32 +562,37 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   defineEvent<const TInner extends string, TPayload>(
     name: TInner,
     schema: ZodType<TPayload>,
-    options?: { readonly version?: number; readonly piiFields?: EventPiiFields },
+    options?: {
+      readonly version?: number;
+      readonly piiFields?: EventPiiFields;
+      readonly migrations?: readonly {
+        readonly fromVersion: number;
+        readonly toVersion: number;
+        readonly transform: EventUpcastFn | DeclarativeEventMigration;
+      }[];
+    },
   ): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
 
-  // Register a step-wise payload transform for event-schema evolution.
-  // `eventName` is the SHORT name (same as defineEvent). `toVersion` must
-  // be `fromVersion + 1` — chain larger jumps by registering each step.
-  // Transforms are pure functions: old payload in, new payload out. They
-  // run once per read (not once per event persisted), so keep them cheap.
-  eventMigration(
-    eventName: string,
-    fromVersion: number,
-    toVersion: number,
-    transform: EventUpcastFn | DeclarativeEventMigration,
-  ): void;
-
   readsConfig(...qualifiedKeys: string[]): void;
+  readsConfig(options: { readonly keys: readonly string[] }): void;
 
   referenceData(
     entity: NameOrRef,
     data: readonly Record<string, unknown>[],
     options?: { upsertKey?: string },
   ): void;
+  referenceData(definition: {
+    readonly entity: NameOrRef;
+    readonly data: readonly Record<string, unknown>[];
+    readonly upsertKey?: string;
+  }): void;
 
   extendsRegistrar(name: string, def: RegistrarExtensionDef): void;
 
   useExtension(extensionName: string, entity: NameOrRef, options?: Record<string, unknown>): void;
+  useExtension(
+    definition: { readonly name: string; readonly entity: NameOrRef } & Record<string, unknown>,
+  ): void;
 
   /**
    * Declares which config key selects the active provider under an
@@ -620,12 +645,14 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // qualifies it on boot. Validation (snake_case + typ-suffix) runs at boot.
   // Usage at runtime: ctx.metrics.inc("created_total", { status: "new" }).
   metric(shortName: string, options: MetricOptions): void;
+  metric(definition: { readonly name: string } & MetricOptions): void;
 
   // Declare a secret key. Qualified name follows "<feature>:secret:<kebab>"
   // via the QN helper. Returns a typed handle so feature code can pass it
   // to ctx.secrets.get without retyping the qualified string — same
   // ergonomics as r.config's handle.
   secret(shortName: string, options: SecretOptions): SecretKeyHandle;
+  secret(definition: { readonly name: string } & SecretOptions): SecretKeyHandle;
 
   // Register a projection driven by events of one or more source entities.
   // The runtime fires projection.apply[event.type] inside the event-store's
@@ -679,6 +706,10 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     shortName: string,
     options: { readonly type: T },
   ): ClaimKeyHandle<T>;
+  claimKey<T extends ClaimKeyType>(definition: {
+    readonly name: string;
+    readonly type: T;
+  }): ClaimKeyHandle<T>;
 
   // Register a screen. The id is the feature-local short name (kebab-case);
   // the registry qualifies to "<feature>:screen:<id>". Boot-validation checks

package/src/engine/types/handlers.ts

@@ -736,9 +736,12 @@ export type AggregateStreamHandle = {
 // ctx-arg, run the lookup via ctx.db, return a Promise. The framework
 // awaits unconditionally — sync transforms return a plain value and pay
 // only the await-microtask overhead. Pattern-match Marten:
-//   r.eventMigration("invoiceCreated", 1, 2, async (payload, ctx) => {
-//     const customer = await ctx.db.select().from(customersTable)...;
-//     return { ...payload, customerSegment: customer.segment };
+//   r.defineEvent("invoiceCreated", schema, {
+//     version: 2,
+//     migrations: [{ fromVersion: 1, toVersion: 2, transform: async (payload, ctx) => {
+//       const customer = await ctx.db.select().from(customersTable)...;
+//       return { ...payload, customerSegment: customer.segment };
+//     } }],
 //   });
 export type EventUpcastCtx = {
   readonly db: import("../../db").DbRunner;

package/src/engine/types/nav.ts

@@ -54,6 +54,10 @@ export type NavDefinition = {
   // Role / openToAll gate. The nav resolver hides entries the user can't
   // reach; leave unset to always show (engine stays un-opinionated about
   // who sees what — apps that need default-deny can set { roles: [] }).
+  // If `screen` is set and `access` is left unset, the client-side nav
+  // builder (buildNavRegistrySliceForApp) fills this in from the target
+  // screen's own `access` — a nav entry never invites a role into a 403.
+  // An explicit `access` here always wins over the screen's.
   readonly access?: AccessRule;
   // Workspace QNs this entry self-assigns to. Merged at boot with any
   // r.workspace({ nav: [...] }) explicit lists. Omit to leave workspace

package/src/event-store/__tests__/upcaster.integration.test.ts

@@ -56,21 +56,32 @@ const orderFeature = defineFeature("upcastshop", (r) => {
   const orderPriced = r.defineEvent(
     "priced",
     z.object({ totalCents: z.number().int(), currency: z.string() }),
-    { version: 3 },
+    {
+      version: 3,
+      migrations: [
+        // v1 → v2: renamed totalEuros → total (kept as string for this step)
+        {
+          fromVersion: 1,
+          toVersion: 2,
+          transform: (payload) => {
+            const p = payload as { totalEuros: string };
+            return { total: p.totalEuros, currency: "EUR" };
+          },
+        },
+        // v2 → v3: parse "total" string into integer cents
+        {
+          fromVersion: 2,
+          toVersion: 3,
+          transform: (payload) => {
+            const p = payload as { total: string; currency: string };
+            const euros = Number.parseFloat(p.total);
+            return { totalCents: Math.round(euros * 100), currency: p.currency };
+          },
+        },
+      ],
+    },
   );
 
-  // v1 → v2: renamed totalEuros → total (kept as string for this step)
-  r.eventMigration("priced", 1, 2, (payload) => {
-    const p = payload as { totalEuros: string };
-    return { total: p.totalEuros, currency: "EUR" };
-  });
-  // v2 → v3: parse "total" string into integer cents
-  r.eventMigration("priced", 2, 3, (payload) => {
-    const p = payload as { total: string; currency: string };
-    const euros = Number.parseFloat(p.total);
-    return { totalCents: Math.round(euros * 100), currency: p.currency };
-  });
-
   r.projection({
     name: "order-summary",
     source: "upcast-order",
@@ -309,18 +320,27 @@ describe("upcaster: async (Marten AsyncOnlyEventUpcaster — DB-Lookups)", () =>
       const placed = r.defineEvent(
         "placed",
         z.object({ customerId: z.string(), segment: z.string() }),
-        { version: 2 },
+        {
+          version: 2,
+          migrations: [
+            {
+              fromVersion: 1,
+              toVersion: 2,
+              transform: async (payload, ctx) => {
+                const p = payload as { customerId: string };
+                const [row] = await selectMany(ctx.db, customerSegments, {
+                  customerId: p.customerId,
+                });
+                return {
+                  customerId: p.customerId,
+                  segment: (row as { segment?: string } | undefined)?.segment ?? "UNKNOWN",
+                };
+              },
+            },
+          ],
+        },
       );
 
-      r.eventMigration("placed", 1, 2, async (payload, ctx) => {
-        const p = payload as { customerId: string };
-        const [row] = await selectMany(ctx.db, customerSegments, { customerId: p.customerId });
-        return {
-          customerId: p.customerId,
-          segment: (row as { segment?: string } | undefined)?.segment ?? "UNKNOWN",
-        };
-      });
-
       r.projection({
         name: "async-summary",
         source: "upcast-async-order",
@@ -385,26 +405,28 @@ describe("upcaster: boot-time validation", () => {
   test("defineEvent with version=N and only partial migrations fails at registry build", () => {
     const incomplete = defineFeature("holes", (r) => {
       r.entity("hole-order", orderEntity);
-      r.defineEvent("bad", z.object({ v3: z.string() }), { version: 3 });
       // Only 1→2 registered — the 2→3 gap must be rejected.
-      r.eventMigration("bad", 1, 2, (p) => p);
+      r.defineEvent("bad", z.object({ v3: z.string() }), {
+        version: 3,
+        migrations: [{ fromVersion: 1, toVersion: 2, transform: (p) => p }],
+      });
     });
     expect(() => createRegistry([incomplete])).toThrow(/v2.*v3|covers the step v2/);
   });
 
-  test("migration declared but no defineEvent → rejected", () => {
-    const orphan = defineFeature("orphans", (r) => {
-      r.entity("orph-order", orderEntity);
-      r.eventMigration("ghost", 1, 2, (p) => p);
-    });
-    expect(() => createRegistry([orphan])).toThrow(/no r\.defineEvent/i);
-  });
+  // "migration declared but no defineEvent" is now structurally impossible:
+  // migrations live in defineEvent's `migrations` option, always scoped to
+  // the event being defined in that same call — there is no longer a
+  // registrar shape that can express a dangling migration for an
+  // undefined event (formerly the "ghost" registry-validate error path).
 
   test("migration toVersion > defineEvent version → rejected", () => {
     const future = defineFeature("future", (r) => {
       r.entity("future-order", orderEntity);
-      r.defineEvent("early", z.object({ x: z.number() }), { version: 1 });
-      r.eventMigration("early", 1, 2, (p) => p);
+      r.defineEvent("early", z.object({ x: z.number() }), {
+        version: 1,
+        migrations: [{ fromVersion: 1, toVersion: 2, transform: (p) => p }],
+      });
     });
     expect(() => createRegistry([future])).toThrow(/declares only version 1/);
   });
@@ -412,34 +434,44 @@ describe("upcaster: boot-time validation", () => {
   test("non-contiguous (1→2 and 3→4 without 2→3) → rejected", () => {
     const gaps = defineFeature("gaps", (r) => {
       r.entity("gap-order", orderEntity);
-      r.defineEvent("jumpy", z.object({ v: z.number() }), { version: 4 });
-      r.eventMigration("jumpy", 1, 2, (p) => p);
-      r.eventMigration("jumpy", 3, 4, (p) => p);
+      r.defineEvent("jumpy", z.object({ v: z.number() }), {
+        version: 4,
+        migrations: [
+          { fromVersion: 1, toVersion: 2, transform: (p) => p },
+          { fromVersion: 3, toVersion: 4, transform: (p) => p },
+        ],
+      });
     });
     expect(() => createRegistry([gaps])).toThrow(/v2.*v3|covers the step v2/);
   });
 });
 
 describe("upcaster: registrar input validation", () => {
-  test("r.eventMigration rejects multi-step jumps", () => {
+  test("defineEvent migrations reject multi-step jumps", () => {
     expect(() =>
       defineFeature("bigstep", (r) => {
         r.entity("bigstep-order", orderEntity);
-        r.defineEvent("biz", z.object({ x: z.number() }), { version: 3 });
-        r.eventMigration("biz", 1, 3, (p) => p);
+        r.defineEvent("biz", z.object({ x: z.number() }), {
+          version: 3,
+          migrations: [{ fromVersion: 1, toVersion: 3, transform: (p) => p }],
+        });
       }),
     ).toThrow(/single-step/);
   });
 
-  test("r.eventMigration rejects duplicate step", () => {
+  test("defineEvent migrations reject duplicate step", () => {
     expect(() =>
       defineFeature("dupestep", (r) => {
         r.entity("dup-order", orderEntity);
-        r.defineEvent("dup", z.object({ x: z.number() }), { version: 2 });
-        r.eventMigration("dup", 1, 2, (p) => p);
-        r.eventMigration("dup", 1, 2, (p) => p);
+        r.defineEvent("dup", z.object({ x: z.number() }), {
+          version: 2,
+          migrations: [
+            { fromVersion: 1, toVersion: 2, transform: (p) => p },
+            { fromVersion: 1, toVersion: 2, transform: (p) => p },
+          ],
+        });
       }),
-    ).toThrow(/already registered/);
+    ).toThrow(/already declared/);
   });
 
   test("r.defineEvent rejects non-positive version", () => {

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -4,7 +4,12 @@ import { createRegistry, defineFeature } from "../../engine";
 import type { AppContext, Registry } from "../../engine/types";
 import { createTestRedis, type TestRedis } from "../../stack";
 import { sleep, waitFor } from "../../testing";
-import { createJobRunner, type JobRunner } from "../job-runner";
+import {
+  createJobRunner,
+  type JobMeta,
+  type JobRunner,
+  type JobRunnerOptions,
+} from "../job-runner";
 
 // --- Shared state ---
 
@@ -104,6 +109,12 @@ const testFeature = defineFeature("test", (r) => {
     throw new Error("intentional failure");
   });
 
+  // perTenant fan-out — used to assert missing getActiveTenantIds fails
+  // the wrapper job without killing the worker.
+  r.job("perTenantFanout", { trigger: { manual: true }, perTenant: true }, async (payload) => {
+    jobLog.push({ name: "test:job:per-tenant-fanout", payload, timestamp: Date.now() });
+  });
+
   // Correlation propagation probe — records the requestContext it sees at
   // handler-time so tests can assert the scheduling request's correlationId
   // made it through BullMQ into the worker process.
@@ -133,6 +144,7 @@ afterAll(async () => {
 // Helper to create a runner, run tests, then stop
 async function withRunner(
   fn: (runner: JobRunner, registry: Registry) => Promise<void>,
+  opts?: Partial<JobRunnerOptions>,
 ): Promise<void> {
   const registry = createRegistry([testFeature]);
   const context: AppContext = {};
@@ -145,6 +157,7 @@ async function withRunner(
     redisUrl,
     consumerLane: "worker",
     queueNamePrefix,
+    ...opts,
   });
 
   try {
@@ -534,6 +547,58 @@ describe("error handling", () => {
       });
     });
   });
+
+  test("onJobFailed receives the handler error on each attempt", async () => {
+    clearLog();
+    const failures: Array<{ jobName: string; error: string }> = [];
+    const starts: JobMeta[] = [];
+    await withRunner(
+      async (runner) => {
+        await runner.dispatch("test:job:failing-job");
+        // retries: 1 → attempts = 2 (initial + one retry)
+        await waitFor(() => {
+          expect(failures.length).toBeGreaterThanOrEqual(2);
+        });
+        expect(failures.every((f) => f.jobName === "test:job:failing-job")).toBe(true);
+        expect(failures.every((f) => f.error === "intentional failure")).toBe(true);
+        expect(starts.map((s) => s.attempt)).toEqual([1, 2]);
+
+        // Worker still alive after exhausted retries
+        await runner.dispatch("test:job:manual-report", { after: "retries" });
+        await waitFor(() => {
+          expect(
+            jobLog.some(
+              (e) => e.name === "test:job:manual-report" && e.payload["after"] === "retries",
+            ),
+          ).toBe(true);
+        });
+      },
+      {
+        onJobStart: (name, _id, meta) => {
+          if (name === "test:job:failing-job") starts.push(meta);
+        },
+        onJobFailed: (jobName, _id, error) => {
+          if (jobName === "test:job:failing-job") failures.push({ jobName, error });
+        },
+      },
+    );
+  });
+
+  test("perTenant without getActiveTenantIds fails wrapper; worker stays alive", async () => {
+    clearLog();
+    await withRunner(async (runner) => {
+      await runner.dispatch("test:job:per-tenant-fanout", { n: 1 });
+      // Wrapper throws before fan-out (and before onJobFailed) — settle, then
+      // prove the worker still consumes.
+      await sleep(300);
+      expect(jobLog.filter((e) => e.name === "test:job:per-tenant-fanout")).toHaveLength(0);
+
+      await runner.dispatch("test:job:manual-report", { after: "perTenant-miss" });
+      await waitFor(() => {
+        expect(jobLog.some((e) => e.name === "test:job:manual-report")).toBe(true);
+      });
+    });
+  });
 });
 
 // --- Registry ---

package/src/pipeline/__tests__/ctx-bridge.integration.test.ts

@@ -131,14 +131,14 @@ const bridgeFeature = defineFeature("ctxbridge", (r) => {
   );
 
   // afterCommit hook on bag — fires once per outer commit.
-  r.entityHook("postSave", bag, async (result) => {
+  r.hook("postSave", { allOf: bag }, async (result) => {
     afterCommitLog.push(`bag:${result.data["label"]}`);
   });
 
   // afterCommit hook on secret — the entity targeted by the nested writeAs.
   // Proves: (a) hook fires exactly once per successful writeAs, (b) hook
   // does NOT fire when the outer transaction rolls back.
-  r.entityHook("postSave", secret, async (result) => {
+  r.hook("postSave", { allOf: secret }, async (result) => {
     afterCommitLog.push(`secret:${result.data["owner"]}`);
   });
 });

package/src/pipeline/__tests__/lifecycle-pipeline.test.ts

@@ -424,7 +424,7 @@ describe("Sprint 8a: per-tenant entity-hook filter", () => {
     });
 
     const featureB = defineFeature("feat-b", (r) => {
-      r.entityHook("postSave", "widget", async (_result, ctx) => {
+      r.hook("postSave", { allOf: "widget" }, async (_result, ctx) => {
         calls.push({ tenant: ctx._tenantId ?? "no-tenant" });
       });
     });

package/src/pipeline/__tests__/load-aggregate-query.integration.test.ts

@@ -45,15 +45,23 @@ const asOfFeature = defineFeature("asoftest", (r) => {
   const approved = r.defineEvent(
     "approved",
     z.object({ amount: z.number().int(), approvedBy: z.string() }),
-    { version: 2 },
+    {
+      version: 2,
+      migrations: [
+        {
+          fromVersion: 1,
+          toVersion: 2,
+          transform: (payload) => {
+            const p = payload as { amount: string; approvedBy: string };
+            return {
+              amount: Math.round(Number.parseFloat(p.amount) * 100),
+              approvedBy: p.approvedBy,
+            };
+          },
+        },
+      ],
+    },
   );
-  r.eventMigration("approved", 1, 2, (payload) => {
-    const p = payload as { amount: string; approvedBy: string };
-    return {
-      amount: Math.round(Number.parseFloat(p.amount) * 100),
-      approvedBy: p.approvedBy,
-    };
-  });
 
   const executor = createEventStoreExecutor(invoiceTable, invoiceEntity, {
     entityName: "asof-invoice",

package/src/pipeline/__tests__/post-query-hook.integration.test.ts

@@ -65,7 +65,7 @@ const postQueryFeature = defineFeature("postquerytest", (r) => {
   r.hook("postQuery", "widget:list", handlerKeyedHook);
 
   // Entity-keyed: fires for ALL query-handlers of widget-entity
-  r.entityHook("postQuery", widget, entityKeyedHook);
+  r.hook("postQuery", { allOf: widget }, entityKeyedHook);
 });
 
 // --- Single-object-result invariant fixtures ---
@@ -93,13 +93,13 @@ const singleObjectFeature = defineFeature("singleobjtest", (r) => {
   r.queryHandler("gadget:get", z.object({}), async () => ({ id: "g1", name: "Gadget" }), {
     access: { openToAll: true },
   });
-  r.entityHook("postQuery", gadget, dropRowHook);
+  r.hook("postQuery", { allOf: gadget }, dropRowHook);
 
   const gizmo = r.entity("gizmo", gizmoEntity);
   r.queryHandler("gizmo:get", z.object({}), async () => ({ id: "z1", name: "Gizmo" }), {
     access: { openToAll: true },
   });
-  r.entityHook("postQuery", gizmo, duplicateRowHook);
+  r.hook("postQuery", { allOf: gizmo }, duplicateRowHook);
 });
 
 // --- Test stack ---