@cosmicdrift/kumiko-framework 0.153.0 → 0.154.1

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -114,7 +114,7 @@ function stripLocations(value: unknown): unknown {
         out[k] = { raw: normalizeBodyRaw((v as { raw: string }).raw) };
         continue;
       }
-      if (k === "opaqueProps" && v && typeof v === "object") {
+      if ((k === "opaqueProps" || k === "migrations") && v && typeof v === "object") {
         const op: Record<string, unknown> = {};
         for (const [pk, pv] of Object.entries(v as Record<string, unknown>)) {
           if (pv && typeof pv === "object" && "raw" in pv) {
@@ -400,3 +400,39 @@ describe("render → parse roundtrip — r.screen({ nav }) inline sugar", () =>
     }
   });
 });
+
+const DEFINE_EVENT_WITH_MIGRATIONS_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("billing", (r) => {
+  r.defineEvent("invoicePaid", z.object({ totalCents: z.number() }), {
+    version: 2,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        transform: (payload) => ({ totalCents: Math.round(payload.total * 100) }),
+      },
+    ],
+  });
+});
+`;
+
+describe("render → parse roundtrip — r.defineEvent({ migrations }) fold", () => {
+  test("migrations array survives parse → render → parse unchanged", () => {
+    const initial = parse(DEFINE_EVENT_WITH_MIGRATIONS_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+
+    const eventPattern = reparsed.patterns.find((p) => p.kind === "defineEvent");
+    expect(eventPattern?.kind).toBe("defineEvent");
+    if (eventPattern?.kind === "defineEvent") {
+      expect(eventPattern.version).toBe(2);
+      expect(Object.keys(eventPattern.migrations ?? {})).toEqual(["1"]);
+    }
+  });
+});

package/src/engine/feature-ast/extractors/index.ts

@@ -30,7 +30,6 @@ export {
   extractAuthClaims,
   extractDefineEvent,
   extractEntityHook,
-  extractEventMigration,
   extractHook,
   extractHttpRoute,
   extractJob,

package/src/engine/feature-ast/extractors/round4.ts

@@ -11,7 +11,6 @@ import type {
   AuthClaimsPattern,
   DefineEventPattern,
   EntityHookPattern,
-  EventMigrationPattern,
   HookPattern,
   HttpRoutePattern,
   JobPattern,
@@ -805,6 +804,74 @@ export function extractHttpRoute(
   });
 }
 
+// Reads defineEvent's `migrations` option — either the array-of-steps shape
+// used by hand-authored calls (`[{ fromVersion, toVersion, transform }]`,
+// toVersion is redundant on-disk since it is always fromVersion + 1) or the
+// keyed-object canonical shape the Designer renders (`{ "1": transform }`).
+// Keyed by fromVersion (as a string) → the transform closure's location.
+// Skips malformed entries rather than failing the whole defineEvent extract
+// — same "best-effort, degrade gracefully" posture as readDataLiteralNode.
+function extractEventMigrationsFromArray(
+  arr: Node,
+  sourceFile: SourceFile,
+): Record<string, SourceLocation> {
+  const result: Record<string, SourceLocation> = {};
+  const arrLit = arr.asKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+  for (const el of arrLit.getElements()) {
+    const obj = el.asKind(SyntaxKind.ObjectLiteralExpression);
+    if (!obj) continue;
+    const fromInit = obj
+      .getProperty("fromVersion")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    const fromVersion = fromInit ? readDataLiteralNode(fromInit) : undefined;
+    if (typeof fromVersion !== "number") continue;
+    const transformInit = obj
+      .getProperty("transform")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    const fn = transformInit ? findFunctionLiteral(transformInit) : undefined;
+    if (!fn) continue;
+    result[String(fromVersion)] = sourceLocationFromNode(fn, sourceFile);
+  }
+  return result;
+}
+
+function extractEventMigrationsFromKeyedObject(
+  objLit: Node,
+  sourceFile: SourceFile,
+): Record<string, SourceLocation> {
+  const result: Record<string, SourceLocation> = {};
+  const obj = objLit.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+  for (const prop of obj.getProperties()) {
+    const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
+    const initializer = propAssign?.getInitializer();
+    const fn = initializer ? findFunctionLiteral(initializer) : undefined;
+    if (!propAssign || !fn) continue;
+    result[readPropertyKey(propAssign)] = sourceLocationFromNode(fn, sourceFile);
+  }
+  return result;
+}
+
+// Reads defineEvent's `migrations` option — either the array-of-steps shape
+// used by hand-authored calls (`[{ fromVersion, toVersion, transform }]`,
+// toVersion is redundant on-disk since it is always fromVersion + 1) or the
+// keyed-object canonical shape the Designer renders (`{ "1": transform }`).
+// Keyed by fromVersion (as a string) → the transform closure's location.
+// Skips malformed entries rather than failing the whole defineEvent extract
+// — same "best-effort, degrade gracefully" posture as readDataLiteralNode.
+function extractEventMigrationsField(
+  node: Node,
+  sourceFile: SourceFile,
+): Readonly<Record<string, SourceLocation>> | undefined {
+  const result = node.asKind(SyntaxKind.ArrayLiteralExpression)
+    ? extractEventMigrationsFromArray(node, sourceFile)
+    : node.asKind(SyntaxKind.ObjectLiteralExpression)
+      ? extractEventMigrationsFromKeyedObject(node, sourceFile)
+      : undefined;
+  return result && Object.keys(result).length > 0 ? result : undefined;
+}
+
 export function extractDefineEvent(
   call: CallExpression,
   sourceFile: SourceFile,
@@ -853,12 +920,20 @@ export function extractDefineEvent(
       const v = readDataLiteralNode(versionInit);
       if (typeof v === "number") version = v;
     }
+    const migrationsInit = obj
+      .getProperty("migrations")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    const migrations = migrationsInit
+      ? extractEventMigrationsField(migrationsInit, sourceFile)
+      : undefined;
     return ok({
       kind: "defineEvent",
       source: sourceLocationFromNode(call, sourceFile),
       eventName: nameInit.getLiteralValue(),
       schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
       ...(version !== undefined && { version }),
+      ...(migrations !== undefined && { migrations }),
     });
   }
 
@@ -879,152 +954,33 @@ export function extractDefineEvent(
     );
   }
   let version: number | undefined;
+  let migrations: Readonly<Record<string, SourceLocation>> | undefined;
   const optionsArg = args[2];
-  if (optionsArg) {
-    const options = readDataLiteralNode(optionsArg);
-    if (isPlainObject(options) && typeof options["version"] === "number") {
-      version = options["version"];
-    }
-  }
-  return ok({
-    kind: "defineEvent",
-    source: sourceLocationFromNode(call, sourceFile),
-    eventName: nameArg.getLiteralValue(),
-    schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
-    ...(version !== undefined && { version }),
-  });
-}
-
-export function extractEventMigration(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<EventMigrationPattern> {
-  const args = call.getArguments();
-  const first = args[0];
-  if (!first) {
-    return fail(
-      "eventMigration",
-      sourceLocationFromNode(call, sourceFile),
-      "expected at least one argument",
-    );
-  }
-
-  const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (obj && args.length === 1) {
-    const eventInit = obj
-      .getProperty("event")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer()
-      ?.asKind(SyntaxKind.StringLiteral);
-    if (!eventInit) {
-      return fail(
-        "eventMigration",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a string-literal `event` property",
-      );
-    }
-    const fromInit = obj
-      .getProperty("fromVersion")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    const fromVersion = fromInit ? readDataLiteralNode(fromInit) : undefined;
-    if (typeof fromVersion !== "number") {
-      return fail(
-        "eventMigration",
-        sourceLocationFromNode(call, sourceFile),
-        "fromVersion must be a numeric literal",
-      );
-    }
-    const toInit = obj
-      .getProperty("toVersion")
+  const optionsObj = optionsArg?.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (optionsObj) {
+    const versionInit = optionsObj
+      .getProperty("version")
       ?.asKind(SyntaxKind.PropertyAssignment)
       ?.getInitializer();
-    const toVersion = toInit ? readDataLiteralNode(toInit) : undefined;
-    if (typeof toVersion !== "number") {
-      return fail(
-        "eventMigration",
-        sourceLocationFromNode(call, sourceFile),
-        "toVersion must be a numeric literal",
-      );
+    if (versionInit) {
+      const v = readDataLiteralNode(versionInit);
+      if (typeof v === "number") version = v;
     }
-    const transformInit = obj
-      .getProperty("transform")
+    const migrationsInit = optionsObj
+      .getProperty("migrations")
       ?.asKind(SyntaxKind.PropertyAssignment)
       ?.getInitializer();
-    if (!transformInit) {
-      return fail(
-        "eventMigration",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a `transform` property",
-      );
+    if (migrationsInit) {
+      migrations = extractEventMigrationsField(migrationsInit, sourceFile);
     }
-    const fn = findFunctionLiteral(transformInit);
-    if (!fn) {
-      return fail(
-        "eventMigration",
-        sourceLocationFromNode(call, sourceFile),
-        "transform must be an inline arrow function or function expression",
-      );
-    }
-    return ok({
-      kind: "eventMigration",
-      source: sourceLocationFromNode(call, sourceFile),
-      eventName: eventInit.getLiteralValue(),
-      fromVersion,
-      toVersion,
-      transformBody: sourceLocationFromNode(fn, sourceFile),
-    });
-  }
-
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
-    return fail(
-      "eventMigration",
-      sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal event name (or use the object form)",
-    );
-  }
-  const fromArg = args[1];
-  const fromVersion = fromArg ? readDataLiteralNode(fromArg) : undefined;
-  if (typeof fromVersion !== "number") {
-    return fail(
-      "eventMigration",
-      sourceLocationFromNode(call, sourceFile),
-      "fromVersion must be a numeric literal",
-    );
-  }
-  const toArg = args[2];
-  const toVersion = toArg ? readDataLiteralNode(toArg) : undefined;
-  if (typeof toVersion !== "number") {
-    return fail(
-      "eventMigration",
-      sourceLocationFromNode(call, sourceFile),
-      "toVersion must be a numeric literal",
-    );
-  }
-  const transformArg = args[3];
-  if (!transformArg) {
-    return fail(
-      "eventMigration",
-      sourceLocationFromNode(call, sourceFile),
-      "expected a transform function as fourth argument",
-    );
-  }
-  const fn = findFunctionLiteral(transformArg);
-  if (!fn) {
-    return fail(
-      "eventMigration",
-      sourceLocationFromNode(call, sourceFile),
-      "transform must be an inline arrow function or function expression",
-    );
   }
   return ok({
-    kind: "eventMigration",
+    kind: "defineEvent",
     source: sourceLocationFromNode(call, sourceFile),
     eventName: nameArg.getLiteralValue(),
-    fromVersion,
-    toVersion,
-    transformBody: sourceLocationFromNode(fn, sourceFile),
+    schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
+    ...(version !== undefined && { version }),
+    ...(migrations !== undefined && { migrations }),
   });
 }
 

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

@@ -28,7 +28,6 @@ export type {
   AddDefineEventArgs,
   AddEntityArgs,
   AddEntityHookArgs,
-  AddEventMigrationArgs,
   AddHookArgs,
   AddHttpRouteArgs,
   AddJobArgs,
@@ -62,7 +61,6 @@ export type {
   EntityHookPattern,
   // Static patterns
   EntityPattern,
-  EventMigrationPattern,
   ExtendsRegistrarPattern,
   FeaturePattern,
   FeaturePatternKind,

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

@@ -40,7 +40,6 @@ import {
   extractEntity,
   extractEntityHook,
   extractEnvSchema,
-  extractEventMigration,
   extractExposesApi,
   extractExtendsRegistrar,
   extractHook,
@@ -457,8 +456,6 @@ function dispatchExtractor(
       return extractHttpRoute(call, sourceFile);
     case "defineEvent":
       return extractDefineEvent(call, sourceFile);
-    case "eventMigration":
-      return extractEventMigration(call, sourceFile);
     case "notification":
       return extractNotification(call, sourceFile);
     case "projection":

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

@@ -66,12 +66,6 @@ export type PatternId =
   | { readonly kind: "projection"; readonly name: string }
   | { readonly kind: "multiStreamProjection"; readonly name: string }
   | { readonly kind: "defineEvent"; readonly eventName: string }
-  | {
-      readonly kind: "eventMigration";
-      readonly eventName: string;
-      readonly fromVersion: number;
-      readonly toVersion: number;
-    }
   | { readonly kind: "extendsRegistrar"; readonly extensionName: string }
   // Singleton patterns — only one per feature, kind alone identifies them.
   | { readonly kind: "requires" }
@@ -419,20 +413,6 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
       return (
         matchFirstArgString(call, id.eventName) || matchObjectProperty(call, "name", id.eventName)
       );
-    case "eventMigration": {
-      // Positional: r.eventMigration(name, from, to, fn)
-      if (matchFirstArgString(call, id.eventName)) {
-        const from = numericArg(call, 1);
-        const to = numericArg(call, 2);
-        return from === id.fromVersion && to === id.toVersion;
-      }
-      // Object: { event, fromVersion, toVersion }
-      return (
-        matchObjectProperty(call, "event", id.eventName) &&
-        matchObjectNumericProperty(call, "fromVersion", id.fromVersion) &&
-        matchObjectNumericProperty(call, "toVersion", id.toVersion)
-      );
-    }
     case "extendsRegistrar":
       return matchFirstArgString(call, id.extensionName);
     default: {
@@ -459,27 +439,6 @@ function matchObjectProperty(call: CallExpression, propName: string, expected: s
   return init?.getLiteralValue() === expected;
 }
 
-function matchObjectNumericProperty(
-  call: CallExpression,
-  propName: string,
-  expected: number,
-): boolean {
-  const obj = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (!obj) return false;
-  const init = obj
-    .getProperty(propName)
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.NumericLiteral);
-  return init !== undefined && Number(init.getText()) === expected;
-}
-
-function numericArg(call: CallExpression, idx: number): number | undefined {
-  const lit = call.getArguments()[idx]?.asKind(SyntaxKind.NumericLiteral);
-  if (!lit) return undefined;
-  return Number(lit.getText());
-}
-
 // =============================================================================
 // Format helpers — line boundaries / blank-line collapse
 // (indent / PATTERN_INDENT live in render.ts and are imported above.)

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");
 }