API.md

FAULTLINE API reference

The package root exports everything below. Import from faultline-sim.

runScenarioMatrix

function runScenarioMatrix<TState, TPlan, TResult, TFault = unknown>(
  options: RunScenarioMatrixOptions<TState, TPlan, TResult, TFault>
): SimulationReport<TState, TPlan, TResult>;

Options

initialState: TState

The seed state. FAULTLINE clones it for the baseline and clones it again for every valid scenario. It is never handed to applyFault or simulateInSandbox.

plan: TPlan

The same plan is supplied to every sandbox. The plan is not cloned. Treat it as immutable.

cloneState: (state: TState) => TState

Must return an independent value. For object or array state, returning the original reference throws StateCloningError. Clone failures are wrapped in StateCloningError.

simulateInSandbox: (state, plan, context) => TResult

Runs the proposed plan against a private state clone and returns a simulation result.

context contains:

• scenario: the current fault scenario, or null for the baseline,
• isBaseline: boolean,
• baseline: for scenario runs, the baseline outcome and result; otherwise null.

evaluateOutcome: (result, context) => OutcomeEvaluation

Returns the calculated pass/fail decision. The return value is normalized and validated:

interface OutcomeEvaluation {
  passed: boolean;
  summary?: string;
  violations?: readonly string[];
  metrics?: Readonly<Record<string, string | number | boolean | null>>;
}

A non-boolean passed or non-finite metric is treated as an error rather than a pass.

scenarios: readonly FaultScenario<TState, TFault>[]

Each scenario must provide:

interface FaultScenario<TState, TFault> {
  id: string;
  name: string;
  description?: string;
  faultType: string;
  fault: TFault;
  validate?: (fault: TFault, state: TState) => readonly string[] | void;
  applyFault: (draftState: TState, fault: TFault) => void;
}

validate receives the original state for read-only inspection. It must not mutate it. applyFault receives the isolated draft and may mutate it.

Return value

interface SimulationReport<TState, TPlan, TResult> {
  schemaVersion: 1;
  baseline: {
    status: "passed" | "failed";
    state: TState;
    plan: TPlan;
    result: TResult;
    outcome: ScenarioOutcome;
  };
  scenarios: ScenarioResult<TState, TPlan, TResult>[];
  summary: {
    total: number;
    passed: number;
    failed: number;
    errors: number;
    invalid: number;
    overallStatus: "passed" | "failed" | "incomplete";
  };
  isolation: {
    clonedStateForBaseline: true;
    clonedStatePerScenario: true;
    originalStatePassedToCallbacks: false;
    note: string;
  };
}

overallStatus is:

• "passed" when the baseline and every scenario passed,
• "failed" when the baseline or any scenario failed and there are no errors/invalid entries,
• "incomplete" when any scenario errored or was invalid.

Status semantics

Status	Meaning
passed	Fault applied, simulation completed and evaluator returned passed: true.
failed	Fault applied, simulation completed and evaluator returned passed: false.
error	Cloning, fault application, simulation or evaluation threw, or evaluation was malformed.
invalid	Scenario definition failed validation and was never simulated.

Errors

FaultlineInputError

Thrown for invalid root options. Contains .issues: string[].

StateCloningError

Thrown when the baseline/scenario clone throws or returns the original object/array reference. For a scenario clone failure, the scenario is recorded as status: "error" instead of rejecting the matrix.

SimulationExecutionError

Thrown only when the baseline cannot be simulated or evaluated. The matrix cannot produce a trustworthy comparison without a baseline. Scenario exceptions do not throw this error; they are captured in the report.

Helper exports

• structuredCloneState(state) — calls platform structuredClone.
• safelyCloneState(state, clone) — applies the reference-reuse guard.
• normalizeOutcome(evaluation) — validates and fills a normalized outcome.
• summarizeScenarioResults(results, baselinePassed) — builds summary counts.