@mmapp/react 0.1.0-alpha.1 → 0.1.0-alpha.4

package/src/testing.ts

@@ -1,995 +0,0 @@
-/**
- * @mindmatrix/react/testing — Testing utilities for workflow models.
- *
- * Provides static analysis, BDD-style test harnesses, and pretty-printing
- * for models defined with `defineModel()`.
- *
- * @example
- * ```typescript
- * import { validateModel, testModel, describeModel, assertModelValid } from '@mindmatrix/react/testing';
- * import authModel from '../models/authentication';
- *
- * // Static analysis
- * const issues = validateModel(authModel);
- *
- * // Throws if any errors
- * assertModelValid(authModel);
- *
- * // BDD-style test chain
- * testModel(authModel)
- *   .given()
- *   .when('login', { email: 'a@b.com', password: 'secret' })
- *   .thenState('authenticating')
- *   .when('login_success')
- *   .thenState('authenticated');
- *
- * // Human-readable summary
- * console.log(describeModel(authModel));
- * ```
- */
-
-import type {
-  ModelDefinition,
-  TransitionDescriptor,
-  TransitionCondition,
-  ActionDefinition,
-} from './config/defineModel';
-
-// =============================================================================
-// Validation
-// =============================================================================
-
-/**
- * A single issue found by `validateModel()`.
- *
- * @example
- * ```typescript
- * const issues = validateModel(myModel);
- * const errors = issues.filter(i => i.severity === 'error');
- * if (errors.length > 0) {
- *   throw new Error(`Model has ${errors.length} error(s)`);
- * }
- * ```
- */
-export interface ValidationIssue {
-  /** How severe the issue is. `'error'` blocks usage, `'warning'` is advisory, `'info'` is informational. */
-  severity: 'error' | 'warning' | 'info';
-  /** Dot-separated path to the problematic definition element, e.g. `'transitions.login.from'`. */
-  path: string;
-  /** Human-readable description of the problem. */
-  message: string;
-  /** Machine-readable issue code, e.g. `'UNREACHABLE_STATE'`. */
-  code: string;
-}
-
-/**
- * Statically analyse a `ModelDefinition` for common errors.
- *
- * Performs 12 categories of checks including state-machine integrity,
- * reachability, transition validity, required-field existence, and role
- * consistency.
- *
- * @param def - The model definition to validate.
- * @returns An array of `ValidationIssue` objects (empty if the model is clean).
- *
- * @example
- * ```typescript
- * import { defineModel } from '@mindmatrix/react';
- * import { validateModel } from '@mindmatrix/react/testing';
- *
- * const model = defineModel({
- *   slug: 'order',
- *   fields: { total: { type: 'number', default: 0 } },
- *   states: {
- *     draft: { type: 'initial' },
- *     placed: {},
- *   },
- *   transitions: {
- *     place: { from: 'draft', to: 'placed' },
- *   },
- * });
- *
- * const issues = validateModel(model);
- * // issues[0].code === 'NO_TERMINAL_STATE'
- * ```
- */
-export function validateModel(def: ModelDefinition): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  const stateNames = Object.keys(def.states);
-  const transitionNames = Object.keys(def.transitions);
-
-  // --- Helper: normalise `from` to an array ---
-  const fromArray = (t: TransitionDescriptor): string[] =>
-    Array.isArray(t.from) ? [...t.from] : [t.from as string];
-
-  // -------------------------------------------------------------------------
-  // 1. Exactly one initial state
-  // -------------------------------------------------------------------------
-  const initialStates = stateNames.filter(s => def.states[s].type === 'initial');
-  if (initialStates.length === 0) {
-    issues.push({
-      severity: 'error',
-      path: 'states',
-      message: 'No state with type "initial" found. Exactly one initial state is required.',
-      code: 'NO_INITIAL_STATE',
-    });
-  } else if (initialStates.length > 1) {
-    issues.push({
-      severity: 'error',
-      path: 'states',
-      message: `Multiple initial states found: ${initialStates.join(', ')}. Exactly one is required.`,
-      code: 'MULTIPLE_INITIAL_STATES',
-    });
-  }
-
-  // -------------------------------------------------------------------------
-  // 2. At least one terminal state (end or cancelled)
-  // -------------------------------------------------------------------------
-  const terminalStates = stateNames.filter(
-    s => def.states[s].type === 'end' || def.states[s].type === 'cancelled',
-  );
-  if (terminalStates.length === 0) {
-    issues.push({
-      severity: 'warning',
-      path: 'states',
-      message: 'No terminal state (type "end" or "cancelled") found. The model may run indefinitely.',
-      code: 'NO_TERMINAL_STATE',
-    });
-  }
-
-  // -------------------------------------------------------------------------
-  // 3 & 4. All transition from/to states exist
-  // -------------------------------------------------------------------------
-  for (const tName of transitionNames) {
-    const t = def.transitions[tName];
-    const froms = fromArray(t);
-
-    for (const f of froms) {
-      if (!stateNames.includes(f)) {
-        issues.push({
-          severity: 'error',
-          path: `transitions.${tName}.from`,
-          message: `Transition "${tName}" references non-existent source state "${f}".`,
-          code: 'INVALID_FROM_STATE',
-        });
-      }
-    }
-
-    if (!stateNames.includes(t.to)) {
-      issues.push({
-        severity: 'error',
-        path: `transitions.${tName}.to`,
-        message: `Transition "${tName}" references non-existent target state "${t.to}".`,
-        code: 'INVALID_TO_STATE',
-      });
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // 5. No transitions FROM end/cancelled states
-  // -------------------------------------------------------------------------
-  const terminalSet = new Set(terminalStates);
-  for (const tName of transitionNames) {
-    const froms = fromArray(def.transitions[tName]);
-    for (const f of froms) {
-      if (terminalSet.has(f)) {
-        issues.push({
-          severity: 'error',
-          path: `transitions.${tName}.from`,
-          message: `Transition "${tName}" originates from terminal state "${f}" (type "${def.states[f]?.type}"). Terminal states must not have outgoing transitions.`,
-          code: 'TRANSITION_FROM_TERMINAL',
-        });
-      }
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // 6. All states reachable from initial state (graph walk)
-  // -------------------------------------------------------------------------
-  if (initialStates.length === 1) {
-    const reachable = new Set<string>();
-    const queue: string[] = [initialStates[0]];
-    while (queue.length > 0) {
-      const current = queue.pop()!;
-      if (reachable.has(current)) continue;
-      reachable.add(current);
-      // Find all states reachable via transitions from `current`
-      for (const tName of transitionNames) {
-        const t = def.transitions[tName];
-        const froms = fromArray(t);
-        if (froms.includes(current) && !reachable.has(t.to)) {
-          queue.push(t.to);
-        }
-      }
-    }
-
-    for (const s of stateNames) {
-      if (!reachable.has(s)) {
-        issues.push({
-          severity: 'warning',
-          path: `states.${s}`,
-          message: `State "${s}" is not reachable from the initial state "${initialStates[0]}".`,
-          code: 'UNREACHABLE_STATE',
-        });
-      }
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // 7. All non-terminal states have at least one outgoing transition
-  // -------------------------------------------------------------------------
-  const statesWithOutgoing = new Set<string>();
-  for (const tName of transitionNames) {
-    const froms = fromArray(def.transitions[tName]);
-    for (const f of froms) {
-      statesWithOutgoing.add(f);
-    }
-  }
-  for (const s of stateNames) {
-    if (!terminalSet.has(s) && !statesWithOutgoing.has(s)) {
-      issues.push({
-        severity: 'warning',
-        path: `states.${s}`,
-        message: `Non-terminal state "${s}" has no outgoing transitions and will be a dead end.`,
-        code: 'DEAD_END_STATE',
-      });
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // 8. Auto transitions should have at least one condition
-  // -------------------------------------------------------------------------
-  for (const tName of transitionNames) {
-    const t = def.transitions[tName];
-    if (t.auto && (!t.conditions || t.conditions.length === 0)) {
-      issues.push({
-        severity: 'warning',
-        path: `transitions.${tName}`,
-        message: `Auto transition "${tName}" has no conditions. It will fire unconditionally on state entry, which may cause an infinite loop.`,
-        code: 'UNCONDITIONAL_AUTO_TRANSITION',
-      });
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // 9. Required fields referenced in requiredFields exist in fields
-  // -------------------------------------------------------------------------
-  const fieldNames = Object.keys(def.fields);
-  for (const tName of transitionNames) {
-    const t = def.transitions[tName];
-    const reqFields = t.requiredFields ?? t.required_fields;
-    if (reqFields) {
-      for (const rf of reqFields) {
-        if (!fieldNames.includes(rf)) {
-          issues.push({
-            severity: 'error',
-            path: `transitions.${tName}.requiredFields`,
-            message: `Transition "${tName}" requires field "${rf}" which does not exist in the model's fields.`,
-            code: 'MISSING_REQUIRED_FIELD',
-          });
-        }
-      }
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // 10. Roles referenced in transition roles exist in model roles
-  // -------------------------------------------------------------------------
-  if (def.roles) {
-    const roleNames = Object.keys(def.roles);
-    for (const tName of transitionNames) {
-      const t = def.transitions[tName];
-      if (t.roles) {
-        for (const r of t.roles) {
-          if (!roleNames.includes(r)) {
-            issues.push({
-              severity: 'error',
-              path: `transitions.${tName}.roles`,
-              message: `Transition "${tName}" references role "${r}" which is not defined in the model's roles.`,
-              code: 'UNDEFINED_ROLE',
-            });
-          }
-        }
-      }
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // 11. Duplicate transition names
-  // -------------------------------------------------------------------------
-  const seen = new Set<string>();
-  for (const tName of transitionNames) {
-    if (seen.has(tName)) {
-      issues.push({
-        severity: 'error',
-        path: `transitions.${tName}`,
-        message: `Duplicate transition name "${tName}".`,
-        code: 'DUPLICATE_TRANSITION',
-      });
-    }
-    seen.add(tName);
-  }
-
-  // -------------------------------------------------------------------------
-  // 12. Self-transitions (from === to) — informational
-  // -------------------------------------------------------------------------
-  for (const tName of transitionNames) {
-    const t = def.transitions[tName];
-    const froms = fromArray(t);
-    for (const f of froms) {
-      if (f === t.to) {
-        issues.push({
-          severity: 'info',
-          path: `transitions.${tName}`,
-          message: `Transition "${tName}" is a self-transition on state "${f}" (from and to are the same).`,
-          code: 'SELF_TRANSITION',
-        });
-      }
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Assert that a model definition has no validation errors.
- *
- * Calls `validateModel()` internally and throws an `Error` if any issue
- * with severity `'error'` is found. Warnings and info issues are ignored.
- *
- * Useful in test setup or CI pipelines where you want a hard failure on
- * invalid models.
- *
- * @param def - The model definition to assert.
- * @throws {Error} If any validation error is found, with a message listing all errors.
- *
- * @example
- * ```typescript
- * import { assertModelValid } from '@mindmatrix/react/testing';
- * import orderModel from '../models/order';
- *
- * // In a test file
- * describe('order model', () => {
- *   it('is structurally valid', () => {
- *     assertModelValid(orderModel); // throws if invalid
- *   });
- * });
- * ```
- */
-export function assertModelValid(def: ModelDefinition): void {
-  const issues = validateModel(def);
-  const errors = issues.filter(i => i.severity === 'error');
-  if (errors.length > 0) {
-    const lines = errors.map(e => `  [${e.code}] ${e.path}: ${e.message}`);
-    throw new Error(
-      `Model "${def.slug}" has ${errors.length} validation error(s):\n${lines.join('\n')}`,
-    );
-  }
-}
-
-// =============================================================================
-// BDD Test Harness
-// =============================================================================
-
-/**
- * Snapshot of the model's runtime state during a test chain.
- *
- * @example
- * ```typescript
- * testModel(model)
- *   .given({ fields: { total: 100 } })
- *   .when('approve')
- *   .then(ctx => {
- *     expect(ctx.state).toBe('approved');
- *     expect(ctx.fields.total).toBe(100);
- *     expect(ctx.history).toHaveLength(1);
- *   });
- * ```
- */
-export interface ModelTestContext {
-  /** Current field values. */
-  fields: Record<string, unknown>;
-  /** Current state name. */
-  state: string;
-  /** History of transitions that have been executed. */
-  history: Array<{
-    from: string;
-    to: string;
-    transition: string;
-    input?: Record<string, unknown>;
-  }>;
-}
-
-/**
- * A single step in a BDD test chain. Provides assertions after a `when()` call.
- */
-export interface TestStep {
-  /**
-   * Assert arbitrary properties of the test context.
-   *
-   * @param assertion - A function that receives the current `ModelTestContext`.
-   *                    Throw inside the function to signal a failure.
-   * @returns The test chain for further chaining.
-   *
-   * @example
-   * ```typescript
-   * .then(ctx => {
-   *   expect(ctx.state).toBe('sent');
-   *   expect(ctx.fields.timestamp).toBeGreaterThan(0);
-   * })
-   * ```
-   */
-  then(assertion: (ctx: ModelTestContext) => void): TestChain;
-
-  /**
-   * Assert that the current state matches the expected state name.
-   *
-   * @param expectedState - The expected state name after the transition.
-   * @returns The test chain for further chaining.
-   *
-   * @example
-   * ```typescript
-   * .when('login', { email: 'a@b.com', password: 'pw' })
-   * .thenState('authenticating')
-   * ```
-   */
-  thenState(expectedState: string): TestChain;
-
-  /**
-   * Assert that a specific field has the expected value.
-   *
-   * @param field - The field name to check.
-   * @param expected - The expected value (compared with strict equality).
-   * @returns The test chain for further chaining.
-   *
-   * @example
-   * ```typescript
-   * .when('send', { content: 'hello' })
-   * .thenField('content', 'hello')
-   * ```
-   */
-  thenField(field: string, expected: unknown): TestChain;
-
-  /**
-   * Assert that the transition would be rejected (wrong source state,
-   * failed condition, or missing required fields).
-   *
-   * @returns The test chain for further chaining.
-   *
-   * @example
-   * ```typescript
-   * testModel(model)
-   *   .given({ state: 'authenticated' })
-   *   .when('login')
-   *   .thenFails()
-   * ```
-   */
-  thenFails(): TestChain;
-}
-
-/**
- * A chainable test sequence combining `when()` triggers with assertions.
- */
-export interface TestChain extends TestStep {
-  /**
-   * Simulate firing a transition with optional input data.
-   *
-   * @param transition - The transition name to fire.
-   * @param input - Optional input data passed to the transition (available as `input.*` in expressions).
-   * @returns A `TestStep` for asserting the outcome.
-   *
-   * @example
-   * ```typescript
-   * testModel(authModel)
-   *   .given()
-   *   .when('login', { email: 'a@b.com', password: 'secret' })
-   *   .thenState('authenticating')
-   *   .when('login_success')
-   *   .thenState('authenticated')
-   * ```
-   */
-  when(transition: string, input?: Record<string, unknown>): TestStep;
-}
-
-/**
- * Create a BDD-style test harness for a model definition.
- *
- * The harness simulates state-machine transitions in-memory. It verifies
- * source-state guards, evaluates simple field conditions, applies
- * `set_field`/`set_fields` actions, and tracks transition history.
- *
- * Complex expression conditions (those referencing `context.*`, `input.*`,
- * or calling functions like `LEN()`) are skipped during evaluation --
- * only simple field comparisons are evaluated.
- *
- * @param def - The model definition to test.
- * @returns An object with a `given()` method to start the test chain.
- *
- * @example
- * ```typescript
- * import { testModel } from '@mindmatrix/react/testing';
- * import messageModel from '../models/message';
- *
- * testModel(messageModel)
- *   .given()
- *   .when('send', { content: 'hello', channelId: 'ch-1' })
- *   .thenState('sent')
- *   .when('deliver')
- *   .thenState('delivered')
- *   .when('mark_read')
- *   .thenState('read')
- *   .when('delete')
- *   .thenState('deleted');
- * ```
- */
-export function testModel(def: ModelDefinition): {
-  /**
-   * Set the initial context for the test chain.
-   *
-   * @param overrides - Optional state and field overrides.
-   *   If `state` is omitted, the initial state is used.
-   *   If `fields` is omitted, default values from field descriptors are used.
-   * @returns A `TestChain` for chaining `when()` and assertions.
-   *
-   * @example
-   * ```typescript
-   * testModel(model)
-   *   .given({ state: 'review', fields: { amount: 500 } })
-   *   .when('approve')
-   *   .thenState('approved');
-   * ```
-   */
-  given(overrides?: { state?: string; fields?: Record<string, unknown> }): TestChain;
-} {
-  return {
-    given(overrides?: { state?: string; fields?: Record<string, unknown> }): TestChain {
-      // Resolve initial state
-      const initialState = Object.keys(def.states).find(s => def.states[s].type === 'initial');
-      const startState = overrides?.state ?? initialState ?? Object.keys(def.states)[0];
-
-      // Build default field values
-      const defaultFields: Record<string, unknown> = {};
-      for (const [name, fd] of Object.entries(def.fields)) {
-        if (fd.default !== undefined) {
-          // Deep-clone arrays/objects to avoid shared references
-          defaultFields[name] =
-            typeof fd.default === 'object' && fd.default !== null
-              ? JSON.parse(JSON.stringify(fd.default))
-              : fd.default;
-        }
-      }
-
-      const ctx: ModelTestContext = {
-        state: startState,
-        fields: { ...defaultFields, ...overrides?.fields },
-        history: [],
-      };
-
-      return createChain(def, ctx);
-    },
-  };
-}
-
-// --- Internal helpers for the test harness ---
-
-/** Try to evaluate a simple field-based condition. Returns `null` if it cannot evaluate. */
-function evaluateCondition(
-  cond: TransitionCondition | string,
-  ctx: ModelTestContext,
-  _input?: Record<string, unknown>,
-): boolean | null {
-  // String shorthand — we can't evaluate arbitrary expressions
-  if (typeof cond === 'string') {
-    return null;
-  }
-
-  // Field-based condition
-  if (cond.type === 'field' && cond.field && cond.operator !== undefined) {
-    const fieldValue = ctx.fields[cond.field];
-    switch (cond.operator) {
-      case 'eq':
-        return fieldValue === cond.value;
-      case 'ne':
-        return fieldValue !== cond.value;
-      case 'gt':
-        return (fieldValue as number) > (cond.value as number);
-      case 'gte':
-        return (fieldValue as number) >= (cond.value as number);
-      case 'lt':
-        return (fieldValue as number) < (cond.value as number);
-      case 'lte':
-        return (fieldValue as number) <= (cond.value as number);
-      case 'is_set':
-        return fieldValue != null && fieldValue !== '';
-      case 'is_empty':
-        return fieldValue == null || fieldValue === '';
-      case 'in':
-        return Array.isArray(cond.value) && (cond.value as unknown[]).includes(fieldValue);
-      case 'not_in':
-        return Array.isArray(cond.value) && !(cond.value as unknown[]).includes(fieldValue);
-      case 'contains':
-        return typeof fieldValue === 'string' && fieldValue.includes(cond.value as string);
-      default:
-        return null;
-    }
-  }
-
-  // Role-based condition — we skip these (no runtime role info)
-  if (cond.type === 'role') {
-    return null;
-  }
-
-  // Expression condition — we skip complex expressions
-  if (cond.type === 'expression') {
-    return null;
-  }
-
-  // OR combinator
-  if (cond.OR) {
-    let anyTrue = false;
-    let allSkipped = true;
-    for (const sub of cond.OR) {
-      const result = evaluateCondition(sub, ctx, _input);
-      if (result !== null) {
-        allSkipped = false;
-        if (result) {
-          anyTrue = true;
-          break;
-        }
-      }
-    }
-    return allSkipped ? null : anyTrue;
-  }
-
-  // AND combinator
-  if (cond.AND) {
-    let allTrue = true;
-    let allSkipped = true;
-    for (const sub of cond.AND) {
-      const result = evaluateCondition(sub, ctx, _input);
-      if (result !== null) {
-        allSkipped = false;
-        if (!result) {
-          allTrue = false;
-          break;
-        }
-      }
-    }
-    return allSkipped ? null : allTrue;
-  }
-
-  return null;
-}
-
-/** Apply set_field / set_fields actions (only simple literal values from input). */
-function applyActions(
-  actions: readonly ActionDefinition[] | undefined,
-  ctx: ModelTestContext,
-  input?: Record<string, unknown>,
-): void {
-  if (!actions) return;
-
-  for (const action of actions) {
-    if (action.type === 'set_field' && action.config) {
-      const field = action.config.field as string | undefined;
-      const expression = action.config.expression as string | undefined;
-      if (field && expression) {
-        // Try to resolve simple input references: 'input.foo'
-        const inputMatch = expression.match(/^input\.(\w+)$/);
-        if (inputMatch && input && inputMatch[1] in input) {
-          ctx.fields[field] = input[inputMatch[1]];
-        }
-        // Simple string literal: '"some string"'
-        const strMatch = expression.match(/^"(.*)"$/);
-        if (strMatch) {
-          ctx.fields[field] = strMatch[1];
-        }
-        // Simple number literal
-        const numMatch = expression.match(/^(\d+(?:\.\d+)?)$/);
-        if (numMatch) {
-          ctx.fields[field] = Number(numMatch[1]);
-        }
-        // Boolean literals
-        if (expression === 'true') ctx.fields[field] = true;
-        if (expression === 'false') ctx.fields[field] = false;
-        if (expression === 'null') ctx.fields[field] = null;
-      }
-    }
-
-    if (action.type === 'set_fields' && action.config?.fields) {
-      const fieldMap = action.config.fields as Record<string, { expression: string }>;
-      for (const [field, spec] of Object.entries(fieldMap)) {
-        const expression = spec.expression;
-        if (!expression) continue;
-
-        const inputMatch = expression.match(/^input\.(\w+)$/);
-        if (inputMatch && input && inputMatch[1] in input) {
-          ctx.fields[field] = input[inputMatch[1]];
-          continue;
-        }
-        const strMatch = expression.match(/^"(.*)"$/);
-        if (strMatch) {
-          ctx.fields[field] = strMatch[1];
-          continue;
-        }
-        const numMatch = expression.match(/^(\d+(?:\.\d+)?)$/);
-        if (numMatch) {
-          ctx.fields[field] = Number(numMatch[1]);
-          continue;
-        }
-        if (expression === 'true') ctx.fields[field] = true;
-        else if (expression === 'false') ctx.fields[field] = false;
-        else if (expression === 'null') ctx.fields[field] = null;
-      }
-    }
-  }
-}
-
-/** Try to execute a transition. Returns `{ ok: true }` or `{ ok: false, reason: string }`. */
-function tryTransition(
-  def: ModelDefinition,
-  ctx: ModelTestContext,
-  transitionName: string,
-  input?: Record<string, unknown>,
-): { ok: boolean; reason?: string } {
-  const t = def.transitions[transitionName];
-  if (!t) {
-    return { ok: false, reason: `Transition "${transitionName}" does not exist.` };
-  }
-
-  // Check source state
-  const froms = Array.isArray(t.from) ? [...t.from] : [t.from as string];
-  if (!froms.includes(ctx.state)) {
-    return {
-      ok: false,
-      reason: `Current state "${ctx.state}" is not a valid source for transition "${transitionName}" (valid: ${froms.join(', ')}).`,
-    };
-  }
-
-  // Check required fields
-  const reqFields = t.requiredFields ?? t.required_fields;
-  if (reqFields) {
-    for (const rf of reqFields) {
-      const val = ctx.fields[rf];
-      if (val === undefined || val === null || val === '') {
-        return {
-          ok: false,
-          reason: `Required field "${rf}" is empty for transition "${transitionName}".`,
-        };
-      }
-    }
-  }
-
-  // Evaluate conditions (only simple ones — skip complex expressions)
-  if (t.conditions) {
-    for (const cond of t.conditions) {
-      const result = evaluateCondition(cond, ctx, input);
-      // Only reject if a condition explicitly evaluates to false
-      if (result === false) {
-        return {
-          ok: false,
-          reason: `Condition failed for transition "${transitionName}".`,
-        };
-      }
-    }
-  }
-
-  // Transition succeeds — apply actions and move state
-  const prevState = ctx.state;
-  applyActions(t.actions, ctx, input);
-  ctx.state = t.to;
-  ctx.history.push({ from: prevState, to: t.to, transition: transitionName, input });
-
-  return { ok: true };
-}
-
-/** Create a TestChain backed by a mutable context. */
-function createChain(def: ModelDefinition, ctx: ModelTestContext): TestChain {
-  // Track the result of the last `when()` call for `thenFails()`
-  let lastResult: { ok: boolean; reason?: string } | null = null;
-
-  const chain: TestChain = {
-    when(transition: string, input?: Record<string, unknown>): TestStep {
-      // Save a snapshot so thenFails() works correctly
-      const snapshot = {
-        state: ctx.state,
-        fields: { ...ctx.fields },
-        historyLen: ctx.history.length,
-      };
-
-      lastResult = tryTransition(def, ctx, transition, input);
-
-      // If the transition failed, revert context for thenFails()
-      if (!lastResult.ok) {
-        ctx.state = snapshot.state;
-        ctx.fields = snapshot.fields;
-        // Remove any history entries added (shouldn't be any, but safety)
-        ctx.history.length = snapshot.historyLen;
-      }
-
-      return chain;
-    },
-
-    then(assertion: (c: ModelTestContext) => void): TestChain {
-      if (lastResult && !lastResult.ok) {
-        throw new Error(
-          `Cannot assert with then() — the last transition failed: ${lastResult.reason}`,
-        );
-      }
-      assertion(ctx);
-      return chain;
-    },
-
-    thenState(expectedState: string): TestChain {
-      if (lastResult && !lastResult.ok) {
-        throw new Error(
-          `Expected state "${expectedState}" but the last transition failed: ${lastResult.reason}`,
-        );
-      }
-      if (ctx.state !== expectedState) {
-        throw new Error(
-          `Expected state "${expectedState}" but got "${ctx.state}".`,
-        );
-      }
-      return chain;
-    },
-
-    thenField(field: string, expected: unknown): TestChain {
-      if (lastResult && !lastResult.ok) {
-        throw new Error(
-          `Cannot assert field "${field}" — the last transition failed: ${lastResult.reason}`,
-        );
-      }
-      const actual = ctx.fields[field];
-      if (actual !== expected) {
-        throw new Error(
-          `Expected field "${field}" to be ${JSON.stringify(expected)} but got ${JSON.stringify(actual)}.`,
-        );
-      }
-      return chain;
-    },
-
-    thenFails(): TestChain {
-      if (!lastResult) {
-        throw new Error('thenFails() called without a preceding when() call.');
-      }
-      if (lastResult.ok) {
-        throw new Error(
-          `Expected the transition to fail, but it succeeded. State is now "${ctx.state}".`,
-        );
-      }
-      // Reset lastResult so the chain can continue
-      lastResult = null;
-      return chain;
-    },
-  };
-
-  return chain;
-}
-
-// =============================================================================
-// Describe
-// =============================================================================
-
-/**
- * Generate a human-readable summary of a model definition.
- *
- * Useful for documentation, debugging, and quick inspection of a model's
- * structure without reading the raw definition object.
- *
- * @param def - The model definition to describe.
- * @returns A multi-line string summarising the model's fields, states,
- *          transitions, and roles.
- *
- * @example
- * ```typescript
- * import { describeModel } from '@mindmatrix/react/testing';
- * import authModel from '../models/authentication';
- *
- * console.log(describeModel(authModel));
- * // Model: mod-authentication (v2.0.0, module)
- * //
- * // Fields (6):
- * //   appName: string = ''
- * //   layout: string = 'card' [card, split, minimal]
- * //   ...
- * //
- * // States (4):
- * //   * unauthenticated (initial)
- * //   - authenticating
- * //   - authenticated
- * //   - error
- * //
- * // Transitions (8):
- * //   login: unauthenticated -> authenticating [conditions: 2, actions: 1]
- * //   ...
- * //
- * // Roles (0): none defined
- * ```
- */
-export function describeModel(def: ModelDefinition): string {
-  const lines: string[] = [];
-
-  // --- Header ---
-  const versionStr = def.version ? `v${def.version}` : 'unversioned';
-  const categoryStr = Array.isArray(def.category)
-    ? def.category.join(', ')
-    : def.category ?? 'model';
-  lines.push(`Model: ${def.slug} (${versionStr}, ${categoryStr})`);
-
-  // --- Fields ---
-  const fieldEntries = Object.entries(def.fields);
-  lines.push('');
-  lines.push(`Fields (${fieldEntries.length}):`);
-  if (fieldEntries.length === 0) {
-    lines.push('  (none)');
-  } else {
-    for (const [name, fd] of fieldEntries) {
-      let line = `  ${name}: ${fd.type}`;
-      if (fd.default !== undefined) {
-        line += ` = ${JSON.stringify(fd.default)}`;
-      }
-      if (fd.required) {
-        line += ' (required)';
-      }
-      if (fd.enum && fd.enum.length > 0) {
-        line += ` [${fd.enum.join(', ')}]`;
-      }
-      if (fd.computed) {
-        line += ' (computed)';
-      }
-      lines.push(line);
-    }
-  }
-
-  // --- States ---
-  const stateEntries = Object.entries(def.states);
-  lines.push('');
-  lines.push(`States (${stateEntries.length}):`);
-  for (const [name, sd] of stateEntries) {
-    const typeLabel = sd.type ? ` (${sd.type})` : '';
-    const marker = sd.type === 'initial' ? '*' : sd.type === 'end' || sd.type === 'cancelled' ? 'x' : '-';
-    lines.push(`  ${marker} ${name}${typeLabel}`);
-  }
-
-  // --- Transitions ---
-  const transitionEntries = Object.entries(def.transitions);
-  lines.push('');
-  lines.push(`Transitions (${transitionEntries.length}):`);
-  for (const [name, td] of transitionEntries) {
-    const fromStr = Array.isArray(td.from) ? (td.from as readonly string[]).join(' | ') : td.from;
-    const parts: string[] = [];
-    if (td.conditions && td.conditions.length > 0) {
-      parts.push(`conditions: ${td.conditions.length}`);
-    }
-    if (td.actions && td.actions.length > 0) {
-      parts.push(`actions: ${td.actions.length}`);
-    }
-    if (td.roles && td.roles.length > 0) {
-      parts.push(`roles: ${td.roles.join(', ')}`);
-    }
-    if (td.auto) {
-      parts.push('auto');
-    }
-    const suffix = parts.length > 0 ? ` [${parts.join(', ')}]` : '';
-    lines.push(`  ${name}: ${fromStr} -> ${td.to}${suffix}`);
-  }
-
-  // --- Roles ---
-  const roleEntries = def.roles ? Object.entries(def.roles) : [];
-  lines.push('');
-  if (roleEntries.length === 0) {
-    lines.push('Roles (0): none defined');
-  } else {
-    lines.push(`Roles (${roleEntries.length}):`);
-    for (const [name, rd] of roleEntries) {
-      const desc = rd.description ? ` - ${rd.description}` : '';
-      const perms = rd.permissions && rd.permissions.length > 0
-        ? ` [${rd.permissions.join(', ')}]`
-        : '';
-      lines.push(`  ${name}${desc}${perms}`);
-    }
-  }
-
-  return lines.join('\n');
-}