@mmapp/player-core 0.1.0-alpha.1

package/src/state-machine/types.ts

@@ -0,0 +1,89 @@
+/**
+ * State Machine Types — browser-side workflow interpretation.
+ *
+ * Mirrors the backend PureWorkflowDefinition/Instance structure
+ * but stripped to only what the browser engine needs.
+ */
+
+import type { ExpressionContext } from '../expression/types';
+
+/** State type in the workflow */
+export type StateType = 'START' | 'REGULAR' | 'END' | 'CANCELLED';
+
+/** Action that runs during on_event handling */
+export interface PlayerAction {
+  type: string;
+  config: Record<string, unknown>;
+  condition?: string;
+}
+
+/** On-event subscription for browser-side processing */
+export interface PlayerOnEventSubscription {
+  match: string; // Topic pattern with wildcards
+  conditions?: string[];
+  actions: PlayerAction[];
+}
+
+/** State definition for the browser engine */
+export interface PlayerStateDefinition {
+  name: string;
+  type: StateType;
+  on_enter?: PlayerAction[];
+  on_exit?: PlayerAction[];
+  on_event?: PlayerOnEventSubscription[];
+}
+
+/** Transition definition */
+export interface PlayerTransitionDefinition {
+  name: string;
+  from: string[];
+  to: string;
+  conditions?: string[];
+  auto?: boolean;
+  actions?: PlayerAction[];
+}
+
+/** Workflow definition for the browser engine */
+export interface PlayerWorkflowDefinition {
+  id: string;
+  slug: string;
+  states: PlayerStateDefinition[];
+  transitions: PlayerTransitionDefinition[];
+}
+
+/** Runtime instance state */
+export interface PlayerInstance {
+  definition: PlayerWorkflowDefinition;
+  current_state: string;
+  state_data: Record<string, unknown>;
+  memory: Record<string, unknown>;
+  status: 'ACTIVE' | 'COMPLETED' | 'CANCELLED';
+}
+
+/** Transition result from the state machine */
+export interface TransitionResult {
+  success: boolean;
+  from_state: string;
+  to_state: string;
+  actions_executed: PlayerAction[];
+  error?: string;
+}
+
+/** State machine event listener */
+export type StateMachineListener = (event: StateMachineEvent) => void;
+
+/** Events emitted by the state machine */
+export interface StateMachineEvent {
+  type: 'transition' | 'state_enter' | 'state_exit' | 'action_executed' | 'error';
+  instance_id: string;
+  from_state?: string;
+  to_state?: string;
+  action?: PlayerAction;
+  error?: string;
+}
+
+/** Action handler registered with the state machine */
+export type ActionHandler = (
+  action: PlayerAction,
+  context: ExpressionContext,
+) => void | Promise<void>;

package/src/testing/action-trace.ts

@@ -0,0 +1,209 @@
+/**
+ * Action Trace — records all workflow actions during execution.
+ *
+ * Captures a chronological trace of every transition, action, timer,
+ * and query that occurs during a workflow session. This enables:
+ *
+ * 1. Replay debugging (step through recorded actions)
+ * 2. Test assertions on action sequences
+ * 3. Performance profiling (timing of each tick)
+ * 4. Compliance auditing (complete action log)
+ *
+ * Usage:
+ *   const recorder = createActionRecorder();
+ *   // ... hook into workflow runtime ...
+ *   const trace = recorder.getTrace();
+ *   expect(trace.ticks).toHaveLength(3);
+ *   expect(trace.ticks[0].kind).toBe('transition');
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * A complete action trace for a workflow session.
+ */
+export interface ActionTrace {
+  /** Trace format version. */
+  version: 1;
+  /** Workflow definition slug. */
+  workflowSlug: string;
+  /** Instance ID (if tracking a specific instance). */
+  instanceId?: string;
+  /** When the trace started. */
+  startedAt: string;
+  /** When the trace ended (if finalized). */
+  endedAt?: string;
+  /** Ordered list of action ticks. */
+  ticks: ActionTick[];
+}
+
+/**
+ * A single action tick in the trace.
+ */
+export interface ActionTick {
+  /** Monotonically increasing tick number. */
+  tick: number;
+  /** ISO timestamp of the tick. */
+  timestamp: string;
+  /** Kind of action. */
+  kind: 'transition' | 'action' | 'timer' | 'query' | 'mutation' | 'event' | 'error';
+  /** Name/identifier of the action. */
+  name: string;
+  /** Duration in milliseconds (if measurable). */
+  durationMs?: number;
+  /** Workflow state before this tick. */
+  fromState?: string;
+  /** Workflow state after this tick. */
+  toState?: string;
+  /** Detailed information about the tick. */
+  detail: Record<string, unknown>;
+}
+
+// =============================================================================
+// Recorder
+// =============================================================================
+
+/**
+ * Action recorder — accumulates ticks into a trace.
+ */
+export interface ActionRecorder {
+  /** Record a transition. */
+  recordTransition: (name: string, fromState: string, toState: string, detail?: Record<string, unknown>) => void;
+  /** Record an action execution. */
+  recordAction: (name: string, detail?: Record<string, unknown>) => void;
+  /** Record a timer event. */
+  recordTimer: (name: string, detail?: Record<string, unknown>) => void;
+  /** Record a data query. */
+  recordQuery: (name: string, detail?: Record<string, unknown>) => void;
+  /** Record a mutation. */
+  recordMutation: (name: string, detail?: Record<string, unknown>) => void;
+  /** Record an event. */
+  recordEvent: (name: string, detail?: Record<string, unknown>) => void;
+  /** Record an error. */
+  recordError: (name: string, detail?: Record<string, unknown>) => void;
+  /** Get the current trace. */
+  getTrace: () => ActionTrace;
+  /** Finalize the trace (sets endedAt). */
+  finalize: () => ActionTrace;
+  /** Reset the recorder. */
+  reset: () => void;
+}
+
+/**
+ * Creates a new action recorder.
+ */
+export function createActionRecorder(
+  workflowSlug: string,
+  instanceId?: string
+): ActionRecorder {
+  let tickCounter = 0;
+  let ticks: ActionTick[] = [];
+  let startedAt = new Date().toISOString();
+  let endedAt: string | undefined;
+
+  function recordTick(kind: ActionTick['kind'], name: string, extra?: {
+    fromState?: string;
+    toState?: string;
+    durationMs?: number;
+    detail?: Record<string, unknown>;
+  }): void {
+    ticks.push({
+      tick: tickCounter++,
+      timestamp: new Date().toISOString(),
+      kind,
+      name,
+      fromState: extra?.fromState,
+      toState: extra?.toState,
+      durationMs: extra?.durationMs,
+      detail: extra?.detail || {},
+    });
+  }
+
+  return {
+    recordTransition(name, fromState, toState, detail) {
+      recordTick('transition', name, { fromState, toState, detail });
+    },
+    recordAction(name, detail) {
+      recordTick('action', name, { detail });
+    },
+    recordTimer(name, detail) {
+      recordTick('timer', name, { detail });
+    },
+    recordQuery(name, detail) {
+      recordTick('query', name, { detail });
+    },
+    recordMutation(name, detail) {
+      recordTick('mutation', name, { detail });
+    },
+    recordEvent(name, detail) {
+      recordTick('event', name, { detail });
+    },
+    recordError(name, detail) {
+      recordTick('error', name, { detail });
+    },
+    getTrace() {
+      return {
+        version: 1,
+        workflowSlug,
+        instanceId,
+        startedAt,
+        endedAt,
+        ticks: [...ticks],
+      };
+    },
+    finalize() {
+      endedAt = new Date().toISOString();
+      return this.getTrace();
+    },
+    reset() {
+      tickCounter = 0;
+      ticks = [];
+      startedAt = new Date().toISOString();
+      endedAt = undefined;
+    },
+  };
+}
+
+// =============================================================================
+// Analysis utilities
+// =============================================================================
+
+/**
+ * Filters a trace to only transition ticks.
+ */
+export function getTransitionPath(trace: ActionTrace): string[] {
+  return trace.ticks
+    .filter((t) => t.kind === 'transition')
+    .map((t) => `${t.fromState} → ${t.toState}`);
+}
+
+/**
+ * Gets the final state from a trace.
+ */
+export function getFinalState(trace: ActionTrace): string | undefined {
+  const transitions = trace.ticks.filter((t) => t.kind === 'transition');
+  if (transitions.length === 0) return undefined;
+  return transitions[transitions.length - 1].toState;
+}
+
+/**
+ * Counts ticks by kind.
+ */
+export function countByKind(trace: ActionTrace): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const tick of trace.ticks) {
+    counts[tick.kind] = (counts[tick.kind] || 0) + 1;
+  }
+  return counts;
+}
+
+/**
+ * Checks if a trace contains a specific transition.
+ */
+export function hasTransition(trace: ActionTrace, from: string, to: string): boolean {
+  return trace.ticks.some(
+    (t) => t.kind === 'transition' && t.fromState === from && t.toState === to
+  );
+}

package/src/testing/blueprint-test-runner.ts

@@ -0,0 +1,214 @@
+/**
+ * Blueprint Test Runner — executes test programs AS Blueprints on a Player.
+ *
+ * The test orchestrator IS a Player. This runner:
+ * 1. Compiles TestProgram → PlayerWorkflowDefinition (Blueprint)
+ * 2. Creates a StateMachine (Player) with the compiled Blueprint
+ * 3. Registers test action handlers (in-process or API)
+ * 4. Drives the StateMachine through transitions: next, next, next...
+ * 5. Collects results from the action handler state
+ *
+ * The compiled Blueprint can also be extracted, stored, and executed
+ * independently on any Player (browser, iOS, server).
+ *
+ * Exports:
+ * - runBlueprintTestProgram(): Full program execution
+ * - runBlueprintScenario(): Single scenario execution
+ * - Supports both in-process and API modes via action handler factory
+ */
+
+import { StateMachine } from '../state-machine/interpreter';
+import { createEvaluator, WEB_FAILURE_POLICIES } from '../expression';
+import { compileTestScenario } from './test-compiler';
+import { createInProcessTestActions, createApiTestActions } from './test-actions';
+import type { TestActionState } from './test-actions';
+import type { PlayerWorkflowDefinition, ActionHandler } from '../state-machine/types';
+import type {
+  TestProgram,
+  TestScenario,
+  TestProgramResult,
+  ScenarioResult,
+  StepResult,
+  ApiTestAdapter,
+} from './types';
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+interface BlueprintTestConfig {
+  onStepComplete?: (scenarioIdx: number, step: StepResult) => void;
+  onScenarioComplete?: (result: ScenarioResult) => void;
+  abortSignal?: AbortSignal;
+}
+
+interface InProcessConfig extends BlueprintTestConfig {
+  mode: 'in-process';
+}
+
+interface ApiConfig extends BlueprintTestConfig {
+  mode: 'api';
+  adapter: ApiTestAdapter;
+  settleDelayMs?: number;
+  cleanupInstances?: boolean;
+}
+
+export type BlueprintRunnerConfig = InProcessConfig | ApiConfig;
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Execute a complete test program using the Blueprint runner.
+ *
+ * The test program is compiled to Blueprints and executed on a Player
+ * (StateMachine) with the appropriate action handlers for the mode.
+ */
+export async function runBlueprintTestProgram(
+  program: TestProgram,
+  config: BlueprintRunnerConfig,
+): Promise<TestProgramResult> {
+  const start = performance.now();
+  const scenarioResults: ScenarioResult[] = [];
+  let allPassed = true;
+
+  for (let i = 0; i < program.scenarios.length; i++) {
+    if (config.abortSignal?.aborted) break;
+
+    const result = await runBlueprintScenario(
+      program.scenarios[i],
+      program.definitions,
+      i,
+      config,
+    );
+    scenarioResults.push(result);
+    if (!result.passed) allPassed = false;
+    config.onScenarioComplete?.(result);
+  }
+
+  return {
+    passed: allPassed,
+    scenarioResults,
+    durationMs: performance.now() - start,
+  };
+}
+
+/**
+ * Execute a single scenario as a Blueprint on a Player.
+ */
+export async function runBlueprintScenario(
+  scenario: TestScenario,
+  definitions: Record<string, PlayerWorkflowDefinition>,
+  scenarioIndex: number,
+  config: BlueprintRunnerConfig,
+): Promise<ScenarioResult> {
+  const start = performance.now();
+
+  try {
+    // 1. Compile the scenario to a Blueprint
+    const blueprint = compileTestScenario(scenario, definitions, scenarioIndex);
+
+    // 2. Create action handlers based on execution mode
+    const { handlers, state: testState } = createActionHandlers(definitions, config);
+
+    // 3. Create the Player (StateMachine) with the compiled Blueprint
+    const evaluator = createEvaluator({
+      functions: [],
+      failurePolicy: WEB_FAILURE_POLICIES.EVENT_REACTION,
+    });
+
+    const sm = new StateMachine(blueprint, {}, { evaluator, actionHandlers: handlers });
+
+    // Bind the orchestrator reference so handlers can set fields
+    testState.setOrchestratorField = (field: string, value: unknown) => {
+      sm.setField(field, value);
+    };
+
+    // 4. Drive the Player through the test steps
+    //    SM starts in __idle. Transition 'setup' → __setup (creates instances).
+    //    Then 'next' for each step.
+    const stepCount = scenario.steps.length;
+
+    // Setup: __idle → __setup (fires on_enter which creates test instances)
+    const setupResult = await sm.transition('setup');
+    if (!setupResult.success) {
+      return {
+        scenarioName: scenario.name,
+        passed: false,
+        stepResults: [],
+        durationMs: performance.now() - start,
+        error: `Setup failed: ${setupResult.error}`,
+      };
+    }
+
+    for (let i = 0; i < stepCount; i++) {
+      if (config.abortSignal?.aborted) break;
+
+      const result = await sm.transition('next');
+      if (!result.success) {
+        // Transition itself failed — record as step error
+        testState.stepResults.push({
+          stepName: scenario.steps[i]?.name ?? `step_${i}`,
+          passed: false,
+          assertionResults: [],
+          durationMs: 0,
+          error: `Blueprint transition failed: ${result.error}`,
+        });
+        testState.failed = true;
+        break;
+      }
+
+      // Report step completion
+      const lastStep = testState.stepResults[testState.stepResults.length - 1];
+      if (lastStep) {
+        config.onStepComplete?.(scenarioIndex, lastStep);
+      }
+
+      // Check if step failed
+      if (sm.stateData.__test_step_failed) {
+        await sm.transition('abort');
+        break;
+      }
+    }
+
+    // 5. Advance to terminal state if all steps passed
+    if (!testState.failed && !config.abortSignal?.aborted) {
+      await sm.transition('next'); // → __pass
+    }
+
+    const passed = !testState.failed;
+
+    return {
+      scenarioName: scenario.name,
+      passed,
+      stepResults: testState.stepResults,
+      durationMs: performance.now() - start,
+    };
+  } catch (error) {
+    return {
+      scenarioName: scenario.name,
+      passed: false,
+      stepResults: [],
+      durationMs: performance.now() - start,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+// =============================================================================
+// Internals
+// =============================================================================
+
+function createActionHandlers(
+  definitions: Record<string, PlayerWorkflowDefinition>,
+  config: BlueprintRunnerConfig,
+): { handlers: Map<string, ActionHandler>; state: TestActionState } {
+  if (config.mode === 'api') {
+    return createApiTestActions(config.adapter, {
+      settleDelayMs: config.settleDelayMs,
+    });
+  }
+
+  return createInProcessTestActions(definitions);
+}