@cosmicdrift/kumiko-framework 0.154.0 → 0.154.1

package/src/engine/feature-ast/patcher.ts

@@ -144,13 +144,10 @@ export type AddDefineEventArgs = {
   readonly name: string;
   readonly schemaSource: string;
   readonly version?: number;
-};
-
-export type AddEventMigrationArgs = {
-  readonly event: string;
-  readonly fromVersion: number;
-  readonly toVersion: number;
-  readonly transformSource: string;
+  // Keyed by fromVersion (as a string) → the transform source text for the
+  // fromVersion -> fromVersion+1 step. Folded in from the former
+  // addEventMigration (#1082 step 8).
+  readonly migrations?: Readonly<Record<string, string>>;
 };
 
 export type AddProjectionArgs = {
@@ -249,7 +246,6 @@ export type FeaturePatcher = {
   readonly addProjection: (args: AddProjectionArgs) => void;
   readonly addMultiStreamProjection: (args: AddMultiStreamProjectionArgs) => void;
   readonly addDefineEvent: (args: AddDefineEventArgs) => void;
-  readonly addEventMigration: (args: AddEventMigrationArgs) => void;
   // --- Symmetric ops (id-driven) ---
   readonly replace: (id: PatternId, pattern: FeaturePattern) => void;
   readonly remove: (id: PatternId) => void;
@@ -495,24 +491,22 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       });
     },
 
-    addDefineEvent({ name, schemaSource, version }) {
+    addDefineEvent({ name, schemaSource, version, migrations }) {
+      const migrationLocs = migrations
+        ? Object.fromEntries(
+            Object.entries(migrations).map(([fromVersion, source]) => [
+              fromVersion,
+              rawLoc(source),
+            ]),
+          )
+        : undefined;
       add({
         kind: "defineEvent",
         source: SYNTHETIC_LOC,
         eventName: name,
         schemaSource: rawLoc(schemaSource),
         ...(version !== undefined && { version }),
-      });
-    },
-
-    addEventMigration({ event, fromVersion, toVersion, transformSource }) {
-      add({
-        kind: "eventMigration",
-        source: SYNTHETIC_LOC,
-        eventName: event,
-        fromVersion,
-        toVersion,
-        transformBody: rawLoc(transformSource),
+        ...(migrationLocs !== undefined && { migrations: migrationLocs }),
       });
     },
 

package/src/engine/feature-ast/patterns.ts

@@ -501,29 +501,22 @@ export type MultiStreamProjectionPattern = {
 // `r.defineEvent(name, schema, options?)` — registers an event payload
 // shape and returns the qualified `EventDef`, so callers pass `.name` to
 // `ctx.appendEvent` instead of hand-building `<feature>:event:<short>`.
-// `options.version` declares the CURRENT schema generation (default 1);
-// bump it together with an `r.eventMigration` step — the framework refuses
-// to boot if the chain from 1 to the current version has gaps.
+// `options.version` declares the CURRENT schema generation (default 1).
+// `options.migrations` is a step-wise upcast chain — keyed by fromVersion
+// (toVersion is always fromVersion + 1, enforced at registration, so it is
+// not stored separately); the framework refuses to boot if the chain from
+// 1 to `version` has gaps. Formerly a separate `r.eventMigration()` call
+// per step, folded in here (#1082 step 8) — an event and its schema
+// evolution are one lifecycle, not two registrar concepts.
 export type DefineEventPattern = {
   readonly kind: "defineEvent";
   readonly source: SourceLocation;
   readonly eventName: string;
   readonly schemaSource: SourceLocation;
   readonly version?: number;
-};
-
-// `r.eventMigration(eventName, fromVersion, toVersion, transform)` —
-// registers a step-wise payload upcast for event-schema evolution.
-// `toVersion` must be `fromVersion + 1`; chain larger jumps step by step.
-// Transforms are pure old-payload-in/new-payload-out functions and run once
-// per READ, not once per event persisted — keep them cheap.
-export type EventMigrationPattern = {
-  readonly kind: "eventMigration";
-  readonly source: SourceLocation;
-  readonly eventName: string;
-  readonly fromVersion: number;
-  readonly toVersion: number;
-  readonly transformBody: SourceLocation;
+  // Map fromVersion (as string, e.g. "1") → SourceLocation of the transform
+  // closure for the fromVersion → fromVersion+1 step.
+  readonly migrations?: Readonly<Record<string, SourceLocation>>;
 };
 
 // `r.extendsRegistrar(extensionName, def)` — declares a named, globally
@@ -618,7 +611,6 @@ export type FeaturePattern =
   | ProjectionPattern
   | MultiStreamProjectionPattern
   | DefineEventPattern
-  | EventMigrationPattern
   | ExtendsRegistrarPattern
   | EnvSchemaPattern
   // Catch-all
@@ -674,7 +666,6 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "projection":
     case "multiStreamProjection":
     case "defineEvent":
-    case "eventMigration":
       return "mixed";
     case "authClaims":
     case "extendsRegistrar":

package/src/engine/feature-ast/render.ts

@@ -26,7 +26,6 @@ import type {
   EntityHookPattern,
   EntityPattern,
   EnvSchemaPattern,
-  EventMigrationPattern,
   ExposesApiPattern,
   ExtendsRegistrarPattern,
   FeaturePattern,
@@ -129,8 +128,6 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderMultiStreamProjection(pattern);
     case "defineEvent":
       return renderDefineEvent(pattern);
-    case "eventMigration":
-      return renderEventMigration(pattern);
     case "extendsRegistrar":
       return renderExtendsRegistrar(pattern);
     case "usesApi":
@@ -505,16 +502,16 @@ function renderDefineEvent(p: DefineEventPattern): string {
   lines.push(`  name: ${JSON.stringify(p.eventName)},`);
   lines.push(`  schema: ${p.schemaSource.raw},`);
   if (p.version !== undefined) lines.push(`  version: ${p.version},`);
-  lines.push("});");
-  return lines.join("\n");
-}
-
-function renderEventMigration(p: EventMigrationPattern): string {
-  const lines: string[] = ["r.eventMigration({"];
-  lines.push(`  event: ${JSON.stringify(p.eventName)},`);
-  lines.push(`  fromVersion: ${p.fromVersion},`);
-  lines.push(`  toVersion: ${p.toVersion},`);
-  lines.push(`  transform: ${p.transformBody.raw},`);
+  if (p.migrations !== undefined) {
+    const entries = Object.entries(p.migrations);
+    if (entries.length > 0) {
+      lines.push("  migrations: {");
+      for (const [fromVersion, transformBody] of entries) {
+        lines.push(`    "${fromVersion}": ${transformBody.raw},`);
+      }
+      lines.push("  },");
+    }
+  }
   lines.push("});");
   return lines.join("\n");
 }

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;