@mmapp/player-core 0.1.0-alpha.1

package/src/dsl/ir-migration.ts

@@ -0,0 +1,221 @@
+/**
+ * IR Migration — forward-compatibility layer for workflow definitions.
+ *
+ * Handles differences between IR versions so that older compiled definitions
+ * continue to work with newer runtimes. Each migration transforms from
+ * one version to the next; they chain automatically.
+ *
+ * Version history:
+ * - v1.0: Original format (states use state_type, actions use action_type)
+ * - v1.1: Normalized format (states use type, actions use type, fields use type)
+ * - v1.2: Added extensions, during actions, on_event at workflow level
+ *
+ * The current version is always the latest. Older definitions are migrated
+ * transparently by normalizeDefinition().
+ */
+
+import type { IRWorkflowDefinition } from './ir-types';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export const CURRENT_IR_VERSION = '1.2';
+
+export interface MigrationResult {
+  /** The migrated definition. */
+  definition: IRWorkflowDefinition;
+  /** Original IR version detected. */
+  fromVersion: string;
+  /** Target IR version after migration. */
+  toVersion: string;
+  /** Whether any migration was applied. */
+  migrated: boolean;
+  /** Migrations applied (in order). */
+  appliedMigrations: string[];
+}
+
+// =============================================================================
+// Version Detection
+// =============================================================================
+
+/**
+ * Detect the IR version of a definition.
+ * Uses heuristics based on field naming conventions.
+ */
+export function detectIRVersion(def: Record<string, unknown>): string {
+  // Check explicit ir_version field
+  if (typeof def.ir_version === 'string') return def.ir_version;
+
+  // v1.2: has extensions or workflow-level on_event
+  if (def.extensions || (def.on_event && Array.isArray(def.on_event))) {
+    return '1.2';
+  }
+
+  // v1.0 detection: uses state_type/action_type/field_type naming
+  const states = def.states as Array<Record<string, unknown>> | undefined;
+  const fields = def.fields as Array<Record<string, unknown>> | undefined;
+
+  if (states && states.length > 0 && states[0].state_type) return '1.0';
+  if (fields && fields.length > 0 && fields[0].field_type && !fields[0].type) return '1.0';
+
+  // v1.1: uses normalized type naming
+  if (states && states.length > 0 && states[0].type) return '1.1';
+
+  return '1.0'; // Default to oldest version
+}
+
+// =============================================================================
+// Migrations
+// =============================================================================
+
+type MigrationFn = (def: Record<string, unknown>) => Record<string, unknown>;
+
+/**
+ * v1.0 → v1.1: Normalize field names (state_type → type, etc.)
+ */
+function migrateV10ToV11(def: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...def };
+
+  // Normalize states: state_type → type
+  if (Array.isArray(result.states)) {
+    result.states = (result.states as Array<Record<string, unknown>>).map(state => {
+      const normalized: Record<string, unknown> = { ...state };
+      if ('state_type' in normalized && !('type' in normalized)) {
+        normalized.type = normalized.state_type;
+        delete normalized.state_type;
+      }
+
+      // Normalize actions within states
+      if (Array.isArray(normalized.on_enter)) {
+        normalized.on_enter = normalizeActions(normalized.on_enter as Array<Record<string, unknown>>);
+      }
+      if (Array.isArray(normalized.on_exit)) {
+        normalized.on_exit = normalizeActions(normalized.on_exit as Array<Record<string, unknown>>);
+      }
+      if (Array.isArray(normalized.during)) {
+        normalized.during = (normalized.during as Array<Record<string, unknown>>).map(d => {
+          if (Array.isArray(d.actions)) {
+            return { ...d, actions: normalizeActions(d.actions as Array<Record<string, unknown>>) };
+          }
+          return d;
+        });
+      }
+
+      return normalized;
+    });
+  }
+
+  // Normalize fields: field_type → type
+  if (Array.isArray(result.fields)) {
+    result.fields = (result.fields as Array<Record<string, unknown>>).map(field => {
+      const normalized: Record<string, unknown> = { ...field };
+      if ('field_type' in normalized && !('type' in normalized)) {
+        normalized.type = normalized.field_type;
+        delete normalized.field_type;
+      }
+      return normalized;
+    });
+  }
+
+  // Normalize transition actions
+  if (Array.isArray(result.transitions)) {
+    result.transitions = (result.transitions as Array<Record<string, unknown>>).map(t => {
+      if (Array.isArray(t.actions)) {
+        return { ...t, actions: normalizeActions(t.actions as Array<Record<string, unknown>>) };
+      }
+      return t;
+    });
+  }
+
+  return result;
+}
+
+/**
+ * v1.1 → v1.2: Add extensions, during, on_event defaults
+ */
+function migrateV11ToV12(def: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...def };
+
+  // Ensure extensions field exists
+  if (!result.extensions) {
+    result.extensions = {};
+  }
+
+  // Ensure states have during and on_event arrays
+  if (Array.isArray(result.states)) {
+    result.states = (result.states as Array<Record<string, unknown>>).map(state => ({
+      ...state,
+      during: state.during ?? [],
+      on_event: state.on_event ?? [],
+    }));
+  }
+
+  return result;
+}
+
+function normalizeActions(actions: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
+  return actions.map(action => {
+    const normalized: Record<string, unknown> = { ...action };
+    if ('action_type' in normalized && !('type' in normalized)) {
+      normalized.type = normalized.action_type;
+      delete normalized.action_type;
+    }
+    return normalized;
+  });
+}
+
+// =============================================================================
+// Migration Chain
+// =============================================================================
+
+const MIGRATIONS: Array<{ from: string; to: string; fn: MigrationFn }> = [
+  { from: '1.0', to: '1.1', fn: migrateV10ToV11 },
+  { from: '1.1', to: '1.2', fn: migrateV11ToV12 },
+];
+
+/**
+ * Normalize a definition to the current IR version.
+ * Applies all necessary migrations in sequence.
+ */
+export function normalizeDefinition(def: Record<string, unknown>): MigrationResult {
+  let currentVersion = detectIRVersion(def);
+  let current = def;
+  const applied: string[] = [];
+
+  if (currentVersion === CURRENT_IR_VERSION) {
+    return {
+      definition: current as unknown as IRWorkflowDefinition,
+      fromVersion: currentVersion,
+      toVersion: CURRENT_IR_VERSION,
+      migrated: false,
+      appliedMigrations: [],
+    };
+  }
+
+  const fromVersion = currentVersion;
+
+  // Apply migrations in order
+  for (const migration of MIGRATIONS) {
+    if (currentVersion === migration.from) {
+      current = migration.fn(current);
+      currentVersion = migration.to;
+      applied.push(`${migration.from} → ${migration.to}`);
+    }
+  }
+
+  return {
+    definition: current as unknown as IRWorkflowDefinition,
+    fromVersion,
+    toVersion: currentVersion,
+    migrated: applied.length > 0,
+    appliedMigrations: applied,
+  };
+}
+
+/**
+ * Check if a definition needs migration.
+ */
+export function needsMigration(def: Record<string, unknown>): boolean {
+  return detectIRVersion(def) !== CURRENT_IR_VERSION;
+}

package/src/dsl/ir-types.ts

@@ -0,0 +1,416 @@
+/**
+ * IR Types — the complete Intermediate Representation contract.
+ *
+ * These types mirror the MM-IR Reference (0-MM-IR-REFERENCE.md).
+ * Standalone — no imports from backend/frontend packages.
+ * The compiler transforms AST nodes into these shapes.
+ */
+
+// =============================================================================
+// Enums & Primitives
+// =============================================================================
+
+export type IRStateType = 'START' | 'REGULAR' | 'END' | 'CANCELLED';
+export type IRActionMode = 'auto' | 'manual';
+
+/**
+ * Field type is an open string slug referencing an Element definition.
+ *
+ * Canonical seed types: text, rich_text, number, boolean, date, datetime,
+ * select, multi_select, url, email, phone, currency, percentage, rating,
+ * duration, color, file, image, link_to_one, link_to_many, formula, rollup,
+ * count, lookup, created_at, updated_at, created_by, auto_number, barcode.
+ *
+ * User-defined types use slugs like 'my-org/custom-address'.
+ * The 14 original types remain valid — this is backward compatible.
+ */
+export type IRWorkflowFieldType = string;
+
+export type RuntimeProfile = 'backend' | 'collaborative' | 'p2p' | 'local' | 'ephemeral' | 'edge';
+
+export interface IRStateHome {
+  scope: 'ephemeral' | 'route' | 'instance' | 'global';
+  persistence: 'none' | 'local' | 'durable';
+  sync: 'none' | 'tenant' | 'p2p';
+}
+
+// =============================================================================
+// Action Definitions
+// =============================================================================
+
+export interface IRActionDefinition {
+  id: string;
+  type: string;
+  mode: IRActionMode;
+  config: Record<string, unknown>;
+  condition?: string;
+}
+
+// =============================================================================
+// During Actions (scheduled/recurring while in state)
+// =============================================================================
+
+export interface IRDuringAction {
+  id: string;
+  type: 'interval' | 'timeout' | 'poll' | 'once' | 'cron';
+  interval_ms?: number;
+  cron?: string;
+  delay_ms?: number;
+  actions: IRActionDefinition[];
+  condition?: string;
+}
+
+// =============================================================================
+// On-Event Subscriptions (cross-instance)
+// =============================================================================
+
+export interface IROnEventAction {
+  type: 'set_field' | 'set_memory' | 'log_event' | 'create_instance';
+  field?: string;
+  expression?: string;
+  key?: string;
+  message?: string;
+  config?: Record<string, unknown>;
+  conditions?: string[];
+}
+
+export interface IROnEventSubscription {
+  match: string;
+  description?: string;
+  conditions?: string[];
+  actions: IROnEventAction[];
+}
+
+// =============================================================================
+// State Definition
+// =============================================================================
+
+export interface IRStateDefinition {
+  name: string;
+  description?: string;
+  type: IRStateType;
+  on_enter: IRActionDefinition[];
+  during: IRDuringAction[];
+  on_exit: IRActionDefinition[];
+  on_event?: IROnEventSubscription[];
+}
+
+// =============================================================================
+// Condition Definition
+// =============================================================================
+
+export interface IRConditionDefinition {
+  type?: string;
+  field?: string;
+  operator?: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'contains' | 'is_set' | 'is_empty';
+  value?: unknown;
+  expression?: string;
+  OR?: IRConditionDefinition[];
+  AND?: IRConditionDefinition[];
+}
+
+// =============================================================================
+// Transition Definition
+// =============================================================================
+
+export interface IRTransitionDefinition {
+  name: string;
+  description?: string;
+  from: string[];
+  to: string;
+  conditions?: IRConditionDefinition[];
+  actions: IRActionDefinition[];
+  roles?: string[];
+  auto?: boolean;
+  required_fields?: string[];
+}
+
+// =============================================================================
+// Field Definition
+// =============================================================================
+
+export interface IRFieldValidation {
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  options?: string[];
+  rules?: Array<{
+    expression: string;
+    message: string;
+    severity: 'error' | 'warning';
+  }>;
+}
+
+export interface IRFieldDefinition {
+  name: string;
+  type: IRWorkflowFieldType;
+  /** Version pin: { type, typeVersion } is canonical storage/API form */
+  typeVersion?: string;
+  /** Structural inheritance: storage + widget + primitive intrinsics from base type */
+  baseType?: string;
+  label?: string;
+  required?: boolean;
+  default_value?: unknown;
+  validation?: IRFieldValidation;
+  computed?: string;
+  computed_deps?: string[];
+  // Field-level ACL (matching backend WorkflowFieldDefinition)
+  visible_in_states?: string[];
+  editable_in_states?: string[];
+  visible_to_roles?: string[];
+  editable_by_roles?: string[];
+  visible_when?: string;
+  editable_when?: string;
+  // State home (scope/persistence/sync)
+  state_home?: IRStateHome;
+}
+
+// =============================================================================
+// Role Definition
+// =============================================================================
+
+export interface IRRoleDefinition {
+  name: string;
+  description?: string;
+  permissions: string[];
+}
+
+// =============================================================================
+// Workflow Definition
+// =============================================================================
+
+export interface IRWorkflowDefinition {
+  slug: string;
+  name: string;
+  version: string;
+  description?: string;
+  category: string | string[];
+  states: IRStateDefinition[];
+  transitions: IRTransitionDefinition[];
+  fields: IRFieldDefinition[];
+  roles: IRRoleDefinition[];
+  tags?: Array<{ tag_name: string }>;
+  metadata?: Record<string, unknown>;
+  on_event?: IROnEventSubscription[];
+  extensions?: Record<string, IRGrammarIsland[]>;
+}
+
+// =============================================================================
+// Grammar Islands
+// =============================================================================
+
+export interface IRGrammarIsland {
+  slug: string;
+  contextTag: string;
+  rawSource: string;
+  parsed?: unknown;
+}
+
+// =============================================================================
+// Experience Node
+// =============================================================================
+
+export interface IRExperienceNode {
+  id: string;
+  /** User-assigned display name for authoring UIs (e.g., "Hero Section", "Login Form") */
+  displayName?: string;
+  /** Reference to a registered experience definition (prefab instantiation) */
+  experienceId?: string;
+  component?: string;
+  /** Slot placeholder — rendered by collecting contributions from sub-workflows */
+  slot?: string;
+  children?: IRExperienceNode[];
+  dataSources?: IRDataSource[];
+  dataScope?: string;
+  layout?: string;
+  /** CSS class on the wrapper div */
+  className?: string;
+  /** Style IR — structured cross-platform styling (opaque to player-core) */
+  style?: Record<string, unknown>;
+  config?: Record<string, unknown>;
+  bindings?: Record<string, string>;
+  /** Overrides for a referenced experience's defaults */
+  overrides?: Record<string, unknown>;
+  visible_when?: string;
+}
+
+// =============================================================================
+// Data Sources (discriminated union)
+// =============================================================================
+
+export interface IRWorkflowDataSource {
+  type: 'workflow';
+  name: string;
+  slug?: string;
+  query: 'latest' | 'list' | 'count';
+  /** Fetch a specific instance by ID. Supports template interpolation: "{{entity_id}}" */
+  instanceId?: string;
+  /** Entity scope for the query (null = no filtering, omitted = inherited) */
+  entity?: { type: string; id: string } | null;
+  paginated?: boolean;
+  pageSize?: number;
+  /** Static filters always applied (e.g., { current_state: 'todo' }) */
+  filter?: Record<string, string>;
+  /** Dynamic filters with bind expressions */
+  filters?: Record<string, string | { bind: string }>;
+  sort?: string;
+  search?: string;
+  searchFields?: string[];
+  facets?: string[];
+  /** Range filters: { field: { min?, max? } } */
+  range?: Record<string, { min?: unknown; max?: unknown }>;
+  /** Aggregate functions: "field:fn,field:fn" */
+  aggregate?: string;
+  groupBy?: string;
+  parentInstanceId?: string;
+  autoStart?: boolean;
+  initialData?: Record<string, unknown>;
+  includeDefinition?: boolean;
+}
+
+export interface IRApiDataSource {
+  type: 'api';
+  name: string;
+  endpoint: string;
+  method?: 'GET' | 'POST';
+  /** Map API response to InstanceData shape */
+  mapping?: {
+    id?: string;
+    state?: string;
+    data?: string;
+    items?: string;
+    total?: string;
+  };
+  staleTime?: number;
+}
+
+export interface IRRefDataSource {
+  type: 'ref';
+  name: string;
+  expression: string;
+}
+
+export interface IRStaticDataSource {
+  type: 'static';
+  name: string;
+  data: Record<string, unknown> | Record<string, unknown>[];
+}
+
+export type IRDataSource =
+  | IRWorkflowDataSource
+  | IRApiDataSource
+  | IRRefDataSource
+  | IRStaticDataSource;
+
+// =============================================================================
+// Experience Definition
+// =============================================================================
+
+export interface IRExperienceDefinition {
+  slug: string;
+  version: string;
+  name: string;
+  description?: string;
+  category: string | string[];
+  view_definition: IRExperienceNode;
+  workflows: string[];
+  children: string[];
+  data_bindings: unknown[];
+  is_default: boolean;
+}
+
+// =============================================================================
+// Blueprint Manifest
+// =============================================================================
+
+export interface IRBlueprintManifest {
+  workflows: Array<{
+    slug: string;
+    role: 'primary' | 'child' | 'derived' | 'utility';
+  }>;
+  experience_id: string;
+  routes?: Array<{
+    path: string;
+    node: string;
+    entityType?: string;
+    entityIdSource?: 'user' | 'param';
+  }>;
+}
+
+// =============================================================================
+// Canonical Tree (Pure Form per 041 protocol)
+// =============================================================================
+
+/**
+ * Canonical workflow tree per spec 041 §1.1.
+ * This is the universal type: { slug, category, parts, metadata }.
+ *
+ * Category invariants (INV-1):
+ *   category.length >= 1
+ *   category[0] = primary (dispatch target, must be IDENT)
+ *   category[1..] = tags (sorted bytewise UTF-8, unique, primary not in tags)
+ */
+export interface PureFormWorkflow {
+  slug: string;
+  category: string[];
+  parts?: PureFormWorkflow[];
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Compiled output: canonical tree (truth) + lowered IR (cache).
+ * Per spec 048 §1.2: canonical tree IS the storage format,
+ * IR is a derivable runtime cache.
+ */
+export interface CompiledOutput {
+  canonical: PureFormWorkflow;
+  ir: IRWorkflowDefinition;
+}
+
+/**
+ * Normalizes a category array to satisfy INV-1:
+ * - category[0] = primary (unchanged)
+ * - category[1..] = sorted bytewise UTF-8, unique, primary excluded
+ */
+export function normalizeCategory(primary: string, ...tags: string[]): string[] {
+  const uniqueTags = [...new Set(tags.filter(t => t !== primary))];
+  uniqueTags.sort();
+  return [primary, ...uniqueTags];
+}
+
+// =============================================================================
+// Compilation Output
+// =============================================================================
+
+export type CompilerErrorCode =
+  | 'MISSING_STARTS_AT'
+  | 'UNKNOWN_TARGET_STATE'
+  | 'DUPLICATE_FIELD'
+  | 'DUPLICATE_STATE'
+  | 'UNKNOWN_FIELD_TYPE'
+  | 'INVALID_EXPRESSION'
+  | 'UNKNOWN_FRAGMENT'
+  | 'EMPTY_WORKFLOW'
+  | 'STRICT_USE_EFFECT'
+  | 'STRICT_USE_REF'
+  | 'STRICT_USE_MEMO'
+  | 'STRICT_USE_CALLBACK'
+  | 'STRICT_USE_LAYOUT_EFFECT'
+  | 'STRICT_FORBIDDEN_IMPORT'
+  | 'INFER_RAW_JSX';
+
+export interface CompilerError {
+  code: CompilerErrorCode;
+  message: string;
+  lineNumber?: number;
+  severity: 'error' | 'warning';
+}
+
+export interface CompilationResult {
+  workflows: IRWorkflowDefinition[];
+  experiences: IRExperienceDefinition[];
+  manifest?: IRBlueprintManifest;
+  errors: CompilerError[];
+  warnings: CompilerError[];
+}