@cosmicdrift/kumiko-framework 0.153.0 → 0.154.1

package/src/engine/feature-config-events-jobs.ts

@@ -93,6 +93,64 @@ export function buildConfigEventsJobsMethods<TName extends string>(
     return typeof arg1 === "string" ? handles[arg1] : handles; // @cast-boundary engine-bridge — overload impl signature widens to unknown, narrowed by the two public overloads above
   }
 
+  // piiFields misconfiguration is a boot-time error, not a silent
+  // plaintext leak: both the pii field and its subjectField must exist
+  // on the payload schema (checkable when the schema is a ZodObject).
+  function validateEventPiiFields(
+    eventName: string,
+    schema: ZodType,
+    piiFields: EventPiiFields,
+  ): void {
+    const shape = schema instanceof ZodObject ? schema.shape : undefined;
+    for (const [field, spec] of Object.entries(piiFields)) {
+      if (field === spec.subjectField) {
+        throw new Error(
+          `[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" cannot use itself as subjectField — the subject id is a plaintext pseudonymous fk, the pii field is the value it owns.`,
+        );
+      }
+      for (const required of [field, spec.subjectField]) {
+        if (shape && !(required in shape)) {
+          throw new Error(
+            `[Feature ${name}] defineEvent("${eventName}"): piiFields references "${required}" which is not a field of the payload schema.`,
+          );
+        }
+      }
+    }
+  }
+
+  // Shared by defineEvent's `migrations` option — each entry registers a
+  // single upcast step, same validation/dedup as the old standalone
+  // r.eventMigration() call (folded into defineEvent, #1082 step 8).
+  function registerEventMigration(
+    eventName: string,
+    fromVersion: number,
+    toVersion: number,
+    transform: EventUpcastFn | DeclarativeEventMigration,
+  ): void {
+    if (toVersion !== fromVersion + 1) {
+      throw new Error(
+        `[Feature ${name}] defineEvent("${eventName}") migrations: only single-step migrations are allowed — toVersion must be fromVersion + 1 (got ${fromVersion} -> ${toVersion}). ` +
+          `Chain larger jumps by declaring each step separately.`,
+      );
+    }
+    if (!Number.isInteger(fromVersion) || fromVersion < 1) {
+      throw new Error(
+        `[Feature ${name}] defineEvent("${eventName}") migrations: fromVersion must be >= 1, got ${String(fromVersion)}`,
+      );
+    }
+    const qualified = qn(toKebab(name), "event", toKebab(eventName));
+    const list = state.eventMigrations[eventName] ?? [];
+    if (list.some((m) => m.fromVersion === fromVersion)) {
+      throw new Error(
+        `[Feature ${name}] defineEvent("${eventName}") migrations: a migration from v${fromVersion} is already declared. Each step may only be declared once.`,
+      );
+    }
+    const transformFn =
+      typeof transform === "function" ? transform : compileEventMigration(transform);
+    list.push({ eventName: qualified, fromVersion, toVersion, transform: transformFn });
+    state.eventMigrations[eventName] = list;
+  }
+
   return {
     config,
     job(
@@ -136,7 +194,20 @@ export function buildConfigEventsJobsMethods<TName extends string>(
     defineEvent: <const TInner extends string, TPayload>(
       eventName: TInner,
       schema: ZodType<TPayload>,
-      options?: { readonly version?: number; readonly piiFields?: EventPiiFields },
+      options?: {
+        readonly version?: number;
+        readonly piiFields?: EventPiiFields;
+        // Step-wise upcast chain for this event, folded in from the former
+        // standalone r.eventMigration() call (#1082 step 8) — an event and
+        // its schema evolution are one lifecycle, not two registrar
+        // concepts. Each entry's fromVersion must be unique and the chain
+        // from 1 to `version` must be gap-free (same validation as before).
+        readonly migrations?: readonly {
+          readonly fromVersion: number;
+          readonly toVersion: number;
+          readonly transform: EventUpcastFn | DeclarativeEventMigration;
+        }[];
+      },
     ): EventDef<TPayload, QualifiedEventName<TName, TInner>> => {
       // Return the fully-qualified event name so callers can pass it
       // straight to ctx.appendEvent without hand-building the
@@ -155,26 +226,9 @@ export function buildConfigEventsJobsMethods<TName extends string>(
           `[Feature ${name}] defineEvent("${eventName}"): version must be a positive integer, got ${String(version)}`,
         );
       }
-      // piiFields misconfiguration is a boot-time error, not a silent
-      // plaintext leak: both the pii field and its subjectField must exist
-      // on the payload schema (checkable when the schema is a ZodObject).
       const piiFields = options?.piiFields;
       if (piiFields) {
-        const shape = schema instanceof ZodObject ? schema.shape : undefined;
-        for (const [field, spec] of Object.entries(piiFields)) {
-          if (field === spec.subjectField) {
-            throw new Error(
-              `[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" cannot use itself as subjectField — the subject id is a plaintext pseudonymous fk, the pii field is the value it owns.`,
-            );
-          }
-          for (const required of [field, spec.subjectField]) {
-            if (shape && !(required in shape)) {
-              throw new Error(
-                `[Feature ${name}] defineEvent("${eventName}"): piiFields references "${required}" which is not a field of the payload schema.`,
-              );
-            }
-          }
-        }
+        validateEventPiiFields(eventName, schema, piiFields);
       }
       // @cast-boundary engine-bridge — runtime-string mirrors the
       // template-literal-type via QualifiedEventName + toKebab. Both
@@ -187,38 +241,10 @@ export function buildConfigEventsJobsMethods<TName extends string>(
         ...(piiFields !== undefined && { piiFields }),
       };
       state.events[eventName] = def;
-      return def;
-    },
-    eventMigration(
-      eventName: string,
-      fromVersion: number,
-      toVersion: number,
-      transform: EventUpcastFn | DeclarativeEventMigration,
-    ): void {
-      if (toVersion !== fromVersion + 1) {
-        throw new Error(
-          `[Feature ${name}] eventMigration("${eventName}", ${fromVersion}, ${toVersion}): ` +
-            `only single-step migrations are allowed — toVersion must be fromVersion + 1. ` +
-            `Chain larger jumps by registering each step separately.`,
-        );
+      for (const m of options?.migrations ?? []) {
+        registerEventMigration(eventName, m.fromVersion, m.toVersion, m.transform);
       }
-      if (!Number.isInteger(fromVersion) || fromVersion < 1) {
-        throw new Error(
-          `[Feature ${name}] eventMigration("${eventName}", ...): fromVersion must be >= 1, got ${String(fromVersion)}`,
-        );
-      }
-      const qualified = qn(toKebab(name), "event", toKebab(eventName));
-      const list = state.eventMigrations[eventName] ?? [];
-      if (list.some((m) => m.fromVersion === fromVersion)) {
-        throw new Error(
-          `[Feature ${name}] eventMigration("${eventName}", ${fromVersion}, ${toVersion}): ` +
-            `a migration from v${fromVersion} is already registered. Each step may only be declared once.`,
-        );
-      }
-      const transformFn =
-        typeof transform === "function" ? transform : compileEventMigration(transform);
-      list.push({ eventName: qualified, fromVersion, toVersion, transform: transformFn });
-      state.eventMigrations[eventName] = list;
+      return def;
     },
     readsConfig(...qualifiedKeys: string[]): void {
       state.configReads.push(...qualifiedKeys);
@@ -296,7 +322,7 @@ function compileEventMigration(spec: DeclarativeEventMigration): EventUpcastFn {
   // Registration-time (not replay-time) check: two rename sources mapping to
   // the same target would silently drop one value on every future replay —
   // event migrations run against the full production event history, so a
-  // typo here must fail loud at r.eventMigration() call time, not at replay.
+  // typo here must fail loud at defineEvent() registration time, not at replay.
   const renameTargets = new Map<string, string>();
   for (const [from, to] of Object.entries(spec.rename ?? {})) {
     const existing = renameTargets.get(to);

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -55,7 +55,6 @@ const ALL_KINDS: FeaturePatternKind[] = [
   "projection",
   "multiStreamProjection",
   "defineEvent",
-  "eventMigration",
   "extendsRegistrar",
   "usesApi",
   "exposesApi",
@@ -332,15 +331,6 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
         eventName: "x",
         schemaSource: PLACEHOLDER_BODY_LOC,
       };
-    case "eventMigration":
-      return {
-        kind,
-        source: PLACEHOLDER_LOC,
-        eventName: "x",
-        fromVersion: 1,
-        toVersion: 2,
-        transformBody: PLACEHOLDER_BODY_LOC,
-      };
     case "extendsRegistrar":
       return {
         kind,

package/src/engine/pattern-library/library.ts

@@ -18,7 +18,6 @@ import {
   authClaimsSchema,
   defineEventSchema,
   entityHookSchema,
-  eventMigrationSchema,
   hookSchema,
   httpRouteSchema,
   jobSchema,
@@ -90,7 +89,6 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   projection: projectionSchema,
   multiStreamProjection: multiStreamProjectionSchema,
   defineEvent: defineEventSchema,
-  eventMigration: eventMigrationSchema,
   extendsRegistrar: extendsRegistrarSchema,
   usesApi: usesApiSchema,
   exposesApi: exposesApiSchema,

package/src/engine/pattern-library/mixed-schemas.ts

@@ -443,42 +443,15 @@ export const defineEventSchema: PatternFormSchema = {
       input: "number",
       min: 1,
     },
-  ],
-};
-
-export const eventMigrationSchema: PatternFormSchema = {
-  kind: "eventMigration",
-  label: { en: "Event migration", de: "Event-Migration" },
-  summary: { en: "Step-wise transform between event versions." },
-  category: "data",
-  editability: "mixed",
-  fields: [
     {
-      path: "eventName",
-      label: { en: "Event", de: "Event" },
-      input: "text",
-      required: true,
-    },
-    {
-      path: "fromVersion",
-      label: { en: "From version", de: "Von Version" },
-      input: "number",
-      min: 1,
-      required: true,
-    },
-    {
-      path: "toVersion",
-      label: { en: "To version", de: "Auf Version" },
-      input: "number",
-      min: 2,
-      required: true,
-    },
-    {
-      path: "transformBody",
-      label: { en: "Transform (source)", de: "Transform (Source)" },
-      input: "code-block",
-      language: "typescript",
-      readOnly: true,
+      path: "migrations",
+      label: {
+        en: "Migrations (fromVersion → transform)",
+        de: "Migrationen (fromVersion → Transform)",
+      },
+      input: "key-value-map",
+      keyPlaceholder: "1",
+      valueInput: "code-block",
     },
   ],
 };

package/src/engine/registry-validate.ts

@@ -314,23 +314,23 @@ export function validateEventMigrationVersions(
   features: readonly FeatureDefinition[],
 ): void {
   // Build + validate event upcaster chains. Run AFTER all features are
-  // ingested so r.eventMigration calls can reference events from any
-  // feature (same feature in practice, but the check stays lax for future
-  // cross-feature event packs).
+  // ingested so defineEvent's `migrations` option can reference events from
+  // any feature (same feature in practice, but the check stays lax for
+  // future cross-feature event packs).
   for (const feature of features) {
     for (const [shortName, migrations] of Object.entries(feature.eventMigrations ?? {})) {
       const qualified = qualify(feature.name, "event", shortName);
       const eventDef = state.eventMap.get(qualified);
       if (!eventDef) {
         throw new Error(
-          `Feature "${feature.name}" registered r.eventMigration for "${shortName}" ` +
+          `Feature "${feature.name}" has migrations declared for event "${shortName}" ` +
             `but no r.defineEvent exists for that name. Register the event first.`,
         );
       }
       for (const m of migrations) {
         if (m.toVersion > eventDef.version) {
           throw new Error(
-            `Feature "${feature.name}" has r.eventMigration("${shortName}", ${m.fromVersion}, ${m.toVersion}) ` +
+            `Feature "${feature.name}" declares a migration for event "${shortName}" from v${m.fromVersion} to v${m.toVersion} ` +
               `but r.defineEvent declares only version ${eventDef.version}. ` +
               `Bump the version in defineEvent to at least ${m.toVersion}, or remove the migration.`,
           );
@@ -364,7 +364,7 @@ export function buildEventUpcasterChains(
         if (!chainMap.has(v)) {
           throw new Error(
             `Event "${qualified}" declares version ${eventDef.version} but no migration ` +
-              `covers the step v${v} → v${v + 1}. Register r.eventMigration("${qualified.split(":").pop() ?? qualified}", ${v}, ${v + 1}, transform) ` +
+              `covers the step v${v} → v${v + 1}. Add { fromVersion: ${v}, toVersion: ${v + 1}, transform } to r.defineEvent("${qualified.split(":").pop() ?? qualified}", ...)'s migrations array ` +
               `so stored v${v} payloads can be upcast on read.`,
           );
         }

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.
@@ -532,9 +532,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,21 +547,17 @@ 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;
 
   referenceData(

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/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/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/stack/redis.ts

@@ -3,6 +3,13 @@ import { requireEnv } from "./db";
 
 export type TestRedis = {
   redis: import("ioredis").default;
+  // The exact REDIS_URL used to build `redis` above — for a second, unrelated
+  // connection (e.g. the test-stack's JobRunner) that needs its own client
+  // rather than sharing this one's keyPrefix. Reconstructing a URL from
+  // `redis.options` loses password/username/tls/path (pr-review
+  // kumiko-framework #1036/2) — callers needing a fresh connection should use
+  // this raw string, not rebuild one from parsed options.
+  redisUrl: string;
   /** Delete every key this test created (prefix-scoped). Replaces the old
    *  `redis.flushdb()` — that wiped other parallel tests' BullMQ state. */
   flushNamespace: () => Promise<void>;
@@ -35,6 +42,7 @@ export async function createTestRedis(): Promise<TestRedis> {
 
   return {
     redis,
+    redisUrl,
     flushNamespace,
     cleanup: async () => {
       await flushNamespace();