@typeonce/effect-machine 0.4.0 → 0.5.1

package/dist/testing/MachineTest.d.ts

@@ -1,7 +1,7 @@
 /**
  * Property-based scenario generation and planner trace utilities.
  *
- * @since 4.0.0
+ * @since 0.4.0
  */
 import type * as Effect from "effect/Effect";
 import type * as Graph from "effect/Graph";
@@ -11,9 +11,10 @@ import type { EnsureExecutable } from "../internal/machine/readiness.js";
 import type { SchemaArbitraryReport } from "../internal/testing/machine/arbitrary.js";
 import type { FiniteModel } from "../internal/testing/machine/finiteModel.js";
 import type * as ReferenceModel from "../internal/testing/machine/referenceModel.js";
+import * as internal from "../internal/testing/machine/verification.js";
 import type { VerificationError } from "../internal/testing/machine/verification.js";
 import type * as Machine from "../Machine.js";
-export { advanceCommand, checkpointCommand, formatRuntimeTranscript, runRuntimeCommands, type RuntimeAssertionContext, type RuntimeCommand, type RuntimeCommandActual, RuntimeCommandFailure, type RuntimeCommandRecord, type RuntimeCommandResult, type RuntimeCommands, runtimeCommands, type RuntimeCommandsDiagnostics, type RuntimeCommandsOptions, type RuntimeInspectionContext, type RuntimeModelOptions, type RuntimeModelStep, RuntimeObservationError, RuntimeSynchronization, type RuntimeTranscript, sendCommand, stopCommand } from "../internal/testing/machine/verification.js";
+export { advanceCommand, type CausalRuntimeAssertionContext, type CausalRuntimeCommandActual, CausalRuntimeCommandFailure, type CausalRuntimeCommandRecord, type CausalRuntimeCommandResult, type CausalRuntimeInspectionContext, type CausalRuntimeModelOptions, type CausalRuntimeModelStep, type CausalRuntimeTranscript, type CausalVerificationAwaitContext, type CausalVerificationOptions, type CausalVerificationTranscript, checkpointCommand, type EnqueuedRuntimeAssertionContext, type EnqueuedRuntimeCommandActual, type EnqueuedRuntimeCommandRecord, type EnqueuedRuntimeInspectionContext, type EnqueuedRuntimeModelOptions, type EnqueuedRuntimeModelStep, type EnqueuedRuntimeTranscript, formatCausalTranscript, formatEnqueuedTranscript, formatRuntimeTranscript, runCausalCommands, runEnqueuedCommands, runRuntimeCommands, type RuntimeAssertionContext, type RuntimeAwait, type RuntimeCommand, type RuntimeCommandActual, RuntimeCommandFailure, type RuntimeCommandRecord, type RuntimeCommandResult, type RuntimeCommands, runtimeCommands, type RuntimeCommandsDiagnostics, type RuntimeCommandsOptions, type RuntimeInspectionContext, type RuntimeModelOptions, type RuntimeModelStep, RuntimeObservationError, RuntimeSynchronization, type RuntimeTranscript, sendCommand, stopCommand, verifyCausalCommands } from "../internal/testing/machine/verification.js";
 export type { SchemaArbitraryOpaqueFilterWarning, SchemaArbitraryReport, SchemaArbitraryWarning } from "../internal/testing/machine/verification.js";
 export { compileModel, type FiniteAtomicState, type FiniteAutomaticTransition, type FiniteCompoundState, type FiniteEventTransition, type FiniteFinalState, type FiniteHistoryMutation, type FiniteHistoryScenario, type FiniteHistoryState, type FiniteHistoryTransfer, type FiniteModel, type FiniteModelDiagnostics, type FiniteModelOptions, type FiniteModels, finiteModels, type FiniteParallelState, type FiniteState, type FiniteTransition, type FiniteTransitionTrigger } from "../internal/testing/machine/verification.js";
 export { ModelVerificationError, type ModelVerificationField, type ModelVerificationLocation, type ModelVerificationMismatch, type ReferenceCompletion, type ReferenceHistoryRecord, type ReferenceInitialStep, type ReferenceMicrostep, type ReferenceState, type ReferenceStateValue, type ReferenceStep, type ReferenceTrace, type ReferenceTransition } from "../internal/testing/machine/verification.js";
@@ -22,7 +23,7 @@ export { ModelVerificationError, type ModelVerificationField, type ModelVerifica
  * machine.
  *
  * @category verification
- * @since 4.0.0
+ * @since 0.4.0
  */
 export declare const interpretModel: (model: FiniteModel, events: ReadonlyArray<string>) => ReferenceModel.ReferenceTrace;
 type AnyMachine = Machine.Machine.Any;
@@ -38,7 +39,7 @@ type ReadyMachine<M extends AnyMachine> = M & EnsureExecutable<Machine.Machine.S
  * exact decoded type. Events use only the public input protocol.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type Scenario<M extends AnyMachine> = Machine.Machine.Input<M> extends typeof Schema.Void ? {
     readonly events: ReadonlyArray<Machine.Machine.InputEvent<M>>;
@@ -53,7 +54,7 @@ export type Scenario<M extends AnyMachine> = Machine.Machine.Input<M> extends ty
  * value. An events override therefore owns its own length distribution.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type ScenarioOptions<M extends AnyMachine> = {
     readonly minEvents?: number;
@@ -68,7 +69,7 @@ export type ScenarioOptions<M extends AnyMachine> = {
  * Diagnostics for one schema-derived arbitrary.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface SchemaArbitraryDiagnostic {
     readonly boundary: "input" | "event";
@@ -79,7 +80,7 @@ export interface SchemaArbitraryDiagnostic {
  * Diagnostics describing how a scenario arbitrary was assembled.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface ScenarioDiagnostics {
     readonly input: "none" | "schema" | "override";
@@ -90,7 +91,7 @@ export interface ScenarioDiagnostics {
  * A scenario arbitrary together with schema-derivation diagnostics.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface Scenarios<M extends AnyMachine> {
     readonly arbitrary: FastCheck.Arbitrary<Scenario<M>>;
@@ -102,15 +103,34 @@ export interface Scenarios<M extends AnyMachine> {
  * Unsupported schema derivations fail immediately through `Schema.toArbitrary`.
  * Non-fatal derivation warnings are returned instead of being hidden.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ * import { MachineTest } from "@typeonce/effect-machine/testing"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * class Reset extends Schema.TaggedClass<Reset>("Reset")("Reset", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [Reset],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: { on: { Reset: () => States.initial.Idle.from() } } })
+ *
+ * const generated = MachineTest.scenarios(machine, { maxEvents: 5 })
+ * ```
+ *
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
 export declare const scenarios: <M extends AnyMachine>(machine: M, options?: ScenarioOptions<M>) => Scenarios<M>;
 /**
  * Completion information retained by an initial or event plan.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type PlanCompletion<M extends AnyMachine> = {
     readonly done: true;
@@ -123,7 +143,7 @@ export type PlanCompletion<M extends AnyMachine> = {
  * One public planned microstep, including retained post-conflict transitions.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface Microstep<M extends AnyMachine, Requirements = Machine.Machine.Services<M>> {
     readonly next: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
@@ -140,7 +160,7 @@ export interface Microstep<M extends AnyMachine, Requirements = Machine.Machine.
  * The complete data returned while planning machine startup.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type InitialPlan<M extends AnyMachine> = {
     readonly startingState: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
@@ -154,7 +174,7 @@ export type InitialPlan<M extends AnyMachine> = {
  * The complete data returned while planning one public event.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type EventPlan<M extends AnyMachine> = {
     readonly next: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
@@ -166,7 +186,7 @@ export type EventPlan<M extends AnyMachine> = {
  * Startup portion of an executable planner trace.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface InitialTrace<M extends AnyMachine> {
     readonly plan: InitialPlan<M>;
@@ -179,7 +199,7 @@ export interface InitialTrace<M extends AnyMachine> {
  * One event portion of an executable planner trace.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface TraceStep<M extends AnyMachine> {
     readonly index: number;
@@ -194,7 +214,7 @@ export interface TraceStep<M extends AnyMachine> {
  * A scenario and every plan produced by executing it without running actions.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface Trace<M extends AnyMachine> {
     readonly scenario: Scenario<M>;
@@ -203,6 +223,908 @@ export interface Trace<M extends AnyMachine> {
     readonly final: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
     readonly finalConfiguration: ReadonlyArray<StatePath<M>>;
 }
+/**
+ * One runtime microstep retained by the execution strategy used by a probe.
+ *
+ * Transition-definition metadata is intentionally not reconstructed here:
+ * optimized runtimes retain execution evidence, while `run` and `plan` remain
+ * the APIs for complete diagnostic transition metadata.
+ *
+ * @category runtime testing
+ * @since 0.4.0
+ */
+export type ProbeMicrostep<M extends AnyMachine> = Omit<Microstep<M>, "transitions">;
+/**
+ * Runtime plan evidence associated with one acknowledged public event.
+ *
+ * @category runtime testing
+ * @since 0.4.0
+ */
+export type ProbePlan<M extends AnyMachine> = {
+    readonly next: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
+    readonly commands: ReadonlyArray<Machine.Command>;
+    readonly emittedEvents: ReadonlyArray<Machine.Machine.Emit<M>>;
+    readonly microsteps: ReadonlyArray<ProbeMicrostep<M>>;
+} & PlanCompletion<M>;
+/**
+ * Causal evidence produced after one event has completed its managed runtime
+ * macrostep.
+ *
+ * `handled` distinguishes an ignored event from a retained transition that
+ * deliberately leaves the logical state unchanged. `configurationChanged`
+ * reports whether any microstep changed or reentered the active statechart
+ * configuration; compare `before` and `after` for state-value assertions.
+ *
+ * @category runtime testing
+ * @since 0.4.0
+ */
+export interface ProbeStep<M extends AnyMachine> {
+    readonly event: Machine.Machine.InputEvent<M>;
+    readonly before: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
+    readonly plan: ProbePlan<M>;
+    readonly after: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
+    readonly handled: boolean;
+    readonly configurationChanged: boolean;
+}
+/**
+ * Testing-only causal access to a managed statechart reference.
+ *
+ * A probe does not change ordinary machine scheduling. `sendAndAwait` uses an
+ * acknowledged mailbox delivery so an ignored event can be proven processed
+ * without waiting for a snapshot that will never be published.
+ *
+ * @category runtime testing
+ * @since 0.4.0
+ */
+export interface Probe<M extends AnyMachine, Error = never, Output = never> {
+    readonly machine: M;
+    readonly ref: Machine.MachineRef<Machine.Machine.Snapshot<Machine.Machine.States<M>>, Machine.Machine.InputEvent<M>, Error, Output>;
+    readonly sendAndAwait: (event: Machine.Machine.InputEvent<M>) => Effect.Effect<ProbeStep<M>, Error | Machine.StoppedError>;
+    /** Constructors for asynchronous observation after a causal command. */
+    readonly await: {
+        readonly none: internal.RuntimeAwait<Machine.Machine.Snapshot<Machine.Machine.States<M>>, Error, Output>;
+        readonly until: (predicate: (snapshot: Machine.RuntimeSnapshot<Machine.Machine.Snapshot<Machine.Machine.States<M>>, Error, Output>) => boolean) => internal.RuntimeAwait<Machine.Machine.Snapshot<Machine.Machine.States<M>>, Error, Output>;
+    };
+}
+/**
+ * Raised when `probe` receives a reference that is not backed by the managed
+ * statechart runtime.
+ *
+ * @category errors
+ * @since 0.4.0
+ */
+export { ProbeUnavailableError } from "../internal/testing/machine/verification.js";
+/**
+ * Attaches testing-only causal event delivery to a running statechart.
+ *
+ * The returned probe exposes `sendAndAwait`; ordinary production sends remain
+ * available exclusively through `MachineRef.send` and retain their
+ * asynchronous enqueue-only semantics.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ * import { MachineTest } from "@typeonce/effect-machine/testing"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: {} })
+ *
+ * const program = Effect.gen(function*() {
+ *   const ref = yield* Machine.start(machine)
+ *   return yield* MachineTest.probe(machine, ref)
+ * })
+ * ```
+ *
+ * @category runtime testing
+ * @since 0.4.0
+ */
+export declare const probe: <M extends AnyMachine, Error, Output>(machine: ReadyMachine<M>, ref: Machine.MachineRef<Machine.Machine.Snapshot<Machine.Machine.States<M>>, Machine.Machine.InputEvent<M>, Error, Output>) => Effect.Effect<Probe<M, Error, Output>, internal.ProbeUnavailableError>;
+/**
+ * The runtime error channel exposed by a managed reference for a machine.
+ *
+ * @category utility types
+ * @since 0.4.0
+ */
+export type RuntimeInvariantErrorChannel<M extends AnyMachine> = Machine.Machine.Error<M> | Machine.ActionError<Machine.Machine.Services<M>> | Machine.InfiniteTransitionError | Machine.MachineSchemaDecodeError | Machine.StoppedError;
+/**
+ * A causal command record projected independently of a reference model.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface CausalRuntimeEvidenceRecord<M extends AnyMachine, Error, Output> {
+    readonly index: number;
+    readonly command: internal.RuntimeCommand<Machine.Machine.InputEvent<M>>;
+    readonly actual: internal.CausalRuntimeCommandActual<M, Error, Output, unknown>;
+}
+/**
+ * The model-independent evidence shared by causal command transcripts.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface CausalRuntimeEvidence<M extends AnyMachine, Error, Output> {
+    readonly commands: ReadonlyArray<internal.RuntimeCommand<Machine.Machine.InputEvent<M>>>;
+    readonly initial: Machine.RuntimeSnapshot<Machine.Machine.Snapshot<Machine.Machine.States<M>>, Error, Output>;
+    readonly records: ReadonlyArray<CausalRuntimeEvidenceRecord<M, Error, Output>>;
+    readonly final: Machine.RuntimeSnapshot<Machine.Machine.Snapshot<Machine.Machine.States<M>>, Error, Output>;
+}
+/**
+ * The runtime snapshots selected by one snapshot invariant.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type RuntimeSnapshotObservationMode = "settled" | "awaited" | "all" | "final";
+/**
+ * The semantic location of one retained runtime snapshot.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type RuntimeSnapshotObservation = "initial" | "command" | "awaited" | "final";
+/**
+ * A model-independent command record supplied to runtime laws.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeInvariantRecord<M extends AnyMachine> {
+    readonly index: number;
+    readonly command: internal.RuntimeCommand<Machine.Machine.InputEvent<M>>;
+    readonly result: internal.CausalRuntimeCommandResult<M>;
+    readonly snapshot: Machine.RuntimeSnapshot<Machine.Machine.Snapshot<Machine.Machine.States<M>>, RuntimeInvariantErrorChannel<M>, Machine.Machine.Output<M>>;
+    readonly awaited: ReadonlyArray<Machine.RuntimeSnapshot<Machine.Machine.Snapshot<Machine.Machine.States<M>>, RuntimeInvariantErrorChannel<M>, Machine.Machine.Output<M>>>;
+}
+/**
+ * A model-independent causal transcript supplied to runtime laws.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeInvariantTranscript<M extends AnyMachine> {
+    readonly commands: ReadonlyArray<internal.RuntimeCommand<Machine.Machine.InputEvent<M>>>;
+    readonly initial: Machine.RuntimeSnapshot<Machine.Machine.Snapshot<Machine.Machine.States<M>>, RuntimeInvariantErrorChannel<M>, Machine.Machine.Output<M>>;
+    readonly records: ReadonlyArray<RuntimeInvariantRecord<M>>;
+    readonly final: Machine.RuntimeSnapshot<Machine.Machine.Snapshot<Machine.Machine.States<M>>, RuntimeInvariantErrorChannel<M>, Machine.Machine.Output<M>>;
+}
+/**
+ * Evidence passed to a runtime snapshot invariant.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeSnapshotInvariantContext<M extends AnyMachine> {
+    readonly machine: M;
+    readonly transcript: RuntimeInvariantTranscript<M>;
+    readonly snapshot: RuntimeInvariantTranscript<M>["initial"];
+    readonly observationIndex: number;
+    readonly phase: RuntimeSnapshotObservation;
+    readonly commandIndex: number | undefined;
+    readonly awaitedIndex: number | undefined;
+    readonly command: internal.RuntimeCommand<Machine.Machine.InputEvent<M>> | undefined;
+    readonly result: internal.CausalRuntimeCommandResult<M> | undefined;
+}
+/**
+ * Evidence passed to an invariant for one completed causal command.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeCommandInvariantContext<M extends AnyMachine> {
+    readonly machine: M;
+    readonly transcript: RuntimeInvariantTranscript<M>;
+    readonly record: RuntimeInvariantRecord<M>;
+    readonly previous: RuntimeInvariantRecord<M> | undefined;
+    readonly index: number;
+    readonly command: internal.RuntimeCommand<Machine.Machine.InputEvent<M>>;
+    readonly result: internal.CausalRuntimeCommandResult<M>;
+    readonly snapshot: RuntimeInvariantRecord<M>["snapshot"];
+    readonly awaited: RuntimeInvariantRecord<M>["awaited"];
+}
+/**
+ * Evidence passed to a whole-runtime-transcript invariant.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeTranscriptInvariantContext<M extends AnyMachine> {
+    readonly machine: M;
+    readonly transcript: RuntimeInvariantTranscript<M>;
+}
+/**
+ * Options for a runtime snapshot invariant.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeSnapshotInvariantOptions<M extends AnyMachine> extends InvariantOptions<RuntimeSnapshotInvariantContext<M>> {
+    readonly observe?: RuntimeSnapshotObservationMode;
+}
+/**
+ * A semantic property checked against selected live runtime snapshots.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface RuntimeSnapshotInvariant<M extends AnyMachine> extends InvariantOptions<RuntimeSnapshotInvariantContext<M>> {
+    readonly _tag: "RuntimeSnapshotInvariant";
+    readonly name: string;
+    readonly observe: RuntimeSnapshotObservationMode;
+    readonly check: (context: RuntimeSnapshotInvariantContext<M>) => InvariantOutcome;
+}
+/**
+ * A semantic property checked after every completed causal command.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface RuntimeCommandInvariant<M extends AnyMachine> extends InvariantOptions<RuntimeCommandInvariantContext<M>> {
+    readonly _tag: "RuntimeCommandInvariant";
+    readonly name: string;
+    readonly check: (context: RuntimeCommandInvariantContext<M>) => InvariantOutcome;
+}
+/**
+ * A semantic property checked once against a complete causal transcript.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface RuntimeTranscriptInvariant<M extends AnyMachine> extends InvariantOptions<RuntimeTranscriptInvariantContext<M>> {
+    readonly _tag: "RuntimeTranscriptInvariant";
+    readonly name: string;
+    readonly check: (context: RuntimeTranscriptInvariantContext<M>) => InvariantOutcome;
+}
+/**
+ * A user-defined semantic property over retained live runtime evidence.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type RuntimeInvariant<M extends AnyMachine> = RuntimeSnapshotInvariant<M> | RuntimeCommandInvariant<M> | RuntimeTranscriptInvariant<M>;
+/**
+ * Machine-bound runtime invariant constructors with exact event inference.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeInvariantBuilder<M extends AnyMachine> {
+    readonly snapshot: (name: string, check: (context: RuntimeSnapshotInvariantContext<M>) => InvariantOutcome, options?: RuntimeSnapshotInvariantOptions<M>) => RuntimeSnapshotInvariant<M>;
+    readonly command: (name: string, check: (context: RuntimeCommandInvariantContext<M>) => InvariantOutcome, options?: InvariantOptions<RuntimeCommandInvariantContext<M>>) => RuntimeCommandInvariant<M>;
+    readonly transcript: (name: string, check: (context: RuntimeTranscriptInvariantContext<M>) => InvariantOutcome, options?: InvariantOptions<RuntimeTranscriptInvariantContext<M>>) => RuntimeTranscriptInvariant<M>;
+}
+/**
+ * Creates reusable semantic laws for causal runtime evidence.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export declare const runtimeInvariants: <M extends AnyMachine>(machine: M) => RuntimeInvariantBuilder<M>;
+/**
+ * Scope of a runtime invariant.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type RuntimeInvariantScope = "snapshot" | "command" | "transcript";
+/**
+ * Aggregate result for one runtime invariant.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeInvariantCheckResult {
+    readonly invariant: string;
+    readonly scope: RuntimeInvariantScope;
+    readonly status: InvariantStatus;
+    readonly observations: number;
+    readonly failures: number;
+}
+/**
+ * Aggregate result for all checked runtime invariants.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeInvariantReport {
+    readonly checks: ReadonlyArray<RuntimeInvariantCheckResult>;
+}
+/**
+ * One runtime invariant violation and its exact retained location.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface RuntimeInvariantViolation<M extends AnyMachine = AnyMachine> {
+    readonly invariant: string;
+    readonly scope: RuntimeInvariantScope;
+    readonly kind: "predicate" | "observations";
+    readonly observationIndex?: number;
+    readonly commandIndex: number | undefined;
+    readonly awaitedIndex?: number;
+    readonly phase?: RuntimeSnapshotObservation;
+    readonly command?: internal.RuntimeCommand<Machine.Machine.InputEvent<M>>;
+    readonly message: string;
+}
+/**
+ * All violations found in one causal runtime transcript.
+ *
+ * @category errors
+ * @since 0.4.0
+ */
+export { RuntimeInvariantError } from "../internal/testing/machine/verification.js";
+/**
+ * Checks runtime invariants and returns their complete non-vacuity report.
+ *
+ * @category verification
+ * @since 0.4.0
+ */
+export declare const checkRuntimeInvariants: <M extends AnyMachine, Error, Output>(machine: M, transcript: CausalRuntimeEvidence<M, Error, Output>, invariants: ReadonlyArray<RuntimeInvariant<M>>) => Effect.Effect<RuntimeInvariantReport, internal.RuntimeInvariantError<M>>;
+/**
+ * Asserts runtime invariants against an existing causal transcript.
+ *
+ * @category verification
+ * @since 0.4.0
+ */
+export declare const assertRuntimeInvariants: <M extends AnyMachine, Error, Output>(machine: M, transcript: CausalRuntimeEvidence<M, Error, Output>, invariants: ReadonlyArray<RuntimeInvariant<M>>) => Effect.Effect<void, internal.RuntimeInvariantError<M>>;
+/**
+ * One disagreement between pure planning and a causally processed send.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface PlannerRuntimeAgreementViolation<M extends AnyMachine = AnyMachine> {
+    readonly commandIndex: number;
+    readonly command: internal.RuntimeCommand<Machine.Machine.InputEvent<M>>;
+    readonly field: "planning" | "handled" | "configurationChanged" | "planNext" | "after" | "completion" | "commands" | "emittedEvents" | "microsteps";
+    readonly message: string;
+}
+/**
+ * Raised when live causal evidence disagrees with a fresh pure plan.
+ *
+ * @category errors
+ * @since 0.4.0
+ */
+export { PlannerRuntimeAgreementError } from "../internal/testing/machine/verification.js";
+/**
+ * Checks that every processed public send agrees with a fresh pure plan.
+ *
+ * @category verification
+ * @since 0.4.0
+ */
+export declare const assertPlannerRuntimeAgreement: <M extends AnyMachine, Error, Output>(machine: ReadyMachine<M>, transcript: CausalRuntimeEvidence<M, Error, Output>) => Effect.Effect<void, internal.PlannerRuntimeAgreementError<M>, RunServices<M>>;
+/**
+ * The result of evaluating one semantic invariant.
+ *
+ * `true` passes, `false` produces a default failure message, and a string
+ * fails with that string as its counterexample explanation.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type InvariantOutcome = boolean | string;
+/**
+ * The portions of a trace that a state invariant may observe.
+ *
+ * - `settled` observes startup and the state after every public event.
+ * - `microsteps` observes every internal microstep.
+ * - `all` observes both settled states and microsteps.
+ * - `final` observes only the final state.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type StateObservationMode = "settled" | "microsteps" | "all" | "final";
+/**
+ * The semantic location of one state observation.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type StateObservation = "initial" | "event" | "microstep" | "final";
+/**
+ * Evidence passed to a state invariant.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface StateInvariantContext<M extends AnyMachine> {
+    readonly machine: M;
+    readonly trace: Trace<M>;
+    readonly snapshot: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
+    readonly configuration: ReadonlyArray<StatePath<M>>;
+    readonly observationIndex: number;
+    readonly phase: StateObservation;
+    readonly eventIndex: number | undefined;
+    readonly microstepIndex: number | undefined;
+    readonly event: Machine.Machine.Event<M> | Machine.InitialEvent | undefined;
+}
+/**
+ * Evidence passed to an invariant for one public event step.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface StepInvariantContext<M extends AnyMachine> {
+    readonly machine: M;
+    readonly trace: Trace<M>;
+    readonly step: TraceStep<M>;
+    readonly index: number;
+    readonly before: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
+    readonly beforeConfiguration: ReadonlyArray<StatePath<M>>;
+    readonly event: Machine.Machine.InputEvent<M>;
+    readonly plan: EventPlan<M>;
+    readonly after: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
+    readonly afterConfiguration: ReadonlyArray<StatePath<M>>;
+}
+/**
+ * Evidence passed to a whole-trace invariant.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface TraceInvariantContext<M extends AnyMachine> {
+    readonly machine: M;
+    readonly trace: Trace<M>;
+}
+/**
+ * Controls conditional invariant evaluation and optional non-vacuity checks.
+ *
+ * A condition that never matches is reported as `untested`. Set
+ * `require.minObservations` when that must fail the check instead.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface InvariantOptions<Context> {
+    readonly when?: (context: Context) => boolean;
+    readonly require?: {
+        readonly minObservations: number;
+    };
+}
+/**
+ * Options for a state invariant.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface StateInvariantOptions<M extends AnyMachine> extends InvariantOptions<StateInvariantContext<M>> {
+    readonly observe?: StateObservationMode;
+}
+/**
+ * A semantic property checked against selected state observations.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface StateInvariant<M extends AnyMachine> extends InvariantOptions<StateInvariantContext<M>> {
+    readonly _tag: "StateInvariant";
+    readonly name: string;
+    readonly observe: StateObservationMode;
+    readonly check: (context: StateInvariantContext<M>) => InvariantOutcome;
+}
+/**
+ * A semantic property checked after every public event.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface StepInvariant<M extends AnyMachine> extends InvariantOptions<StepInvariantContext<M>> {
+    readonly _tag: "StepInvariant";
+    readonly name: string;
+    readonly check: (context: StepInvariantContext<M>) => InvariantOutcome;
+}
+/**
+ * A semantic property checked once against a complete trace.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface TraceInvariant<M extends AnyMachine> extends InvariantOptions<TraceInvariantContext<M>> {
+    readonly _tag: "TraceInvariant";
+    readonly name: string;
+    readonly check: (context: TraceInvariantContext<M>) => InvariantOutcome;
+}
+/**
+ * A user-defined semantic property over a planner trace.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type Invariant<M extends AnyMachine> = StateInvariant<M> | StepInvariant<M> | TraceInvariant<M>;
+/**
+ * Machine-bound invariant constructors with complete contextual inference.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface InvariantBuilder<M extends AnyMachine> {
+    readonly state: (name: string, check: (context: StateInvariantContext<M>) => InvariantOutcome, options?: StateInvariantOptions<M>) => StateInvariant<M>;
+    readonly step: (name: string, check: (context: StepInvariantContext<M>) => InvariantOutcome, options?: InvariantOptions<StepInvariantContext<M>>) => StepInvariant<M>;
+    readonly trace: (name: string, check: (context: TraceInvariantContext<M>) => InvariantOutcome, options?: InvariantOptions<TraceInvariantContext<M>>) => TraceInvariant<M>;
+}
+/**
+ * Direct invariant constructors. Prefer `invariants(machine)` when contextual
+ * machine types should be inferred without an explicit type argument.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export declare const Invariant: {
+    readonly state: <M extends AnyMachine>(name: string, check: (context: StateInvariantContext<M>) => InvariantOutcome, options?: StateInvariantOptions<M>) => StateInvariant<M>;
+    readonly step: <M extends AnyMachine>(name: string, check: (context: StepInvariantContext<M>) => InvariantOutcome, options?: InvariantOptions<StepInvariantContext<M>>) => StepInvariant<M>;
+    readonly trace: <M extends AnyMachine>(name: string, check: (context: TraceInvariantContext<M>) => InvariantOutcome, options?: InvariantOptions<TraceInvariantContext<M>>) => TraceInvariant<M>;
+};
+/**
+ * Creates invariant constructors bound to a machine's exact state and event
+ * types. The machine is used only for inference; invariant evaluation remains
+ * pure and reusable across traces from that machine.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ * import { MachineTest } from "@typeonce/effect-machine/testing"
+ *
+ * class Count extends Schema.TaggedClass<Count>("Count")("Count", {
+ *   value: Schema.Number
+ * }) {}
+ * const States = Machine.defineStates({ Count })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Count(new Count({ value: 0 }))
+ * }).handle({ Count: {} })
+ *
+ * const nonNegative = MachineTest.invariants(machine).state(
+ *   "count is non-negative",
+ *   ({ snapshot }) => snapshot.value.value >= 0
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export declare const invariants: <M extends AnyMachine>(machine: M) => InvariantBuilder<M>;
+/**
+ * The scope of a semantic invariant.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type InvariantScope = "state" | "step" | "trace";
+/**
+ * Result status for one invariant.
+ *
+ * `untested` is non-failing unless the invariant declares a minimum number of
+ * observations, in which case it becomes `insufficient`.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export type InvariantStatus = "passed" | "failed" | "untested" | "insufficient";
+/**
+ * Aggregate result for one invariant.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface InvariantCheckResult {
+    readonly invariant: string;
+    readonly scope: InvariantScope;
+    readonly status: InvariantStatus;
+    readonly observations: number;
+    readonly failures: number;
+}
+/**
+ * Aggregate result for all checked invariants.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface InvariantReport {
+    readonly checks: ReadonlyArray<InvariantCheckResult>;
+}
+/**
+ * One semantic invariant violation with its precise trace location.
+ *
+ * @category invariants
+ * @since 0.4.0
+ */
+export interface InvariantViolation<M extends AnyMachine = AnyMachine> {
+    readonly invariant: string;
+    readonly scope: InvariantScope;
+    readonly kind: "predicate" | "observations";
+    readonly observationIndex?: number;
+    readonly eventIndex: number | undefined;
+    readonly microstepIndex?: number;
+    readonly phase?: StateObservation;
+    readonly configuration?: ReadonlyArray<StatePath<M>>;
+    readonly event?: Machine.Machine.Event<M> | Machine.InitialEvent;
+    readonly message: string;
+}
+/**
+ * All semantic violations found in one trace, together with the complete
+ * counterexample and aggregate report.
+ *
+ * @category errors
+ * @since 0.4.0
+ */
+export { InvariantError } from "../internal/testing/machine/verification.js";
+/**
+ * Checks user-defined semantic invariants against an existing planner trace.
+ *
+ * Every invariant and matching observation is evaluated so one failure
+ * contains all relevant evidence. Combine this with `scenarios` and `run` in
+ * an Effect property test to retain FastCheck shrinking.
+ *
+ * @category verification
+ * @since 0.4.0
+ */
+export declare const checkInvariants: <M extends AnyMachine>(machine: M, trace: Trace<M>, invariants: ReadonlyArray<Invariant<M>>) => Effect.Effect<InvariantReport, internal.InvariantError<M>>;
+/**
+ * Asserts user-defined semantic invariants and discards the success report.
+ *
+ * This is the property-test-oriented form of `checkInvariants`: its `void`
+ * success works directly with `it.effect.prop`, while failures retain the
+ * same complete report and trace evidence.
+ *
+ * @category verification
+ * @since 0.4.0
+ */
+export declare const assertInvariants: <M extends AnyMachine>(machine: M, trace: Trace<M>, invariants: ReadonlyArray<Invariant<M>>) => Effect.Effect<void, internal.InvariantError<M>>;
+/**
+ * User-defined identity for a logical exploration state.
+ *
+ * Equal keys deliberately collapse snapshots into one explored state. The key
+ * therefore defines both finiteness and the semantic precision of an
+ * exploration.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export type ExplorationKey = PropertyKey;
+/**
+ * Hard bounds for one exploration.
+ *
+ * Defaults are 20 public events, 1,000 states, and 10,000 planned
+ * transitions. A limit never makes an incomplete result appear exhaustive.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export interface ExplorationLimits {
+    readonly maxDepth?: number;
+    readonly maxStates?: number;
+    readonly maxTransitions?: number;
+}
+/**
+ * Resolved bounds retained by an exploration result.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export interface ResolvedExplorationLimits {
+    readonly maxDepth: number;
+    readonly maxStates: number;
+    readonly maxTransitions: number;
+}
+/**
+ * Evidence available while assigning a state key.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export interface ExplorationStateContext<M extends AnyMachine> {
+    readonly machine: M;
+    readonly snapshot: Machine.Machine.Snapshot<Machine.Machine.States<M>>;
+    readonly configuration: ReadonlyArray<StatePath<M>>;
+    readonly depth: number;
+    readonly trace: Trace<M>;
+}
+/**
+ * One logical state discovered by breadth-first exploration.
+ *
+ * `trace` is the first, and therefore shortest, trace that reached `key`.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export interface ExplorationNode<M extends AnyMachine, Key extends ExplorationKey = ExplorationKey> extends ExplorationStateContext<M> {
+    readonly key: Key;
+}
+/**
+ * One concretely planned public event in the exploration graph.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export interface ExplorationEdge<M extends AnyMachine> {
+    readonly event: Machine.Machine.InputEvent<M>;
+    readonly step: TraceStep<M>;
+    readonly discovered: boolean;
+}
+/**
+ * One boundary that could not be explored because a hard limit was reached.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export type ExplorationFrontier<M extends AnyMachine, Key extends ExplorationKey = ExplorationKey> = {
+    readonly _tag: "DepthLimit";
+    readonly source: Key;
+    readonly trace: Trace<M>;
+    readonly event: Machine.Machine.InputEvent<M>;
+} | {
+    readonly _tag: "StateLimit";
+    readonly source: Key;
+    readonly trace: Trace<M>;
+    readonly event: Machine.Machine.InputEvent<M>;
+    readonly target: Key;
+    readonly targetTrace: Trace<M>;
+} | {
+    readonly _tag: "TransitionLimit";
+    readonly source: Key;
+    readonly trace: Trace<M>;
+    readonly event: Machine.Machine.InputEvent<M>;
+};
+/**
+ * Honest completeness status for the supplied event representatives and state
+ * key abstraction.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export type ExplorationCompleteness<M extends AnyMachine, Key extends ExplorationKey = ExplorationKey> = {
+    readonly _tag: "Complete";
+} | {
+    readonly _tag: "Truncated";
+    readonly reasons: ReadonlyArray<"depth" | "states" | "transitions">;
+    readonly frontier: ReadonlyArray<ExplorationFrontier<M, Key>>;
+};
+/**
+ * Deterministic breadth-first exploration counts.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export interface ExplorationStats {
+    readonly states: number;
+    readonly plannedTransitions: number;
+    readonly retainedEdges: number;
+    readonly maxDepth: number;
+}
+/**
+ * A bounded logical state graph and its shortest-path evidence.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export interface Exploration<M extends AnyMachine, Key extends ExplorationKey = ExplorationKey> {
+    readonly graph: Graph.DirectedGraph<ExplorationNode<M, Key>, ExplorationEdge<M>>;
+    readonly nodes: ReadonlyArray<ExplorationNode<M, Key>>;
+    readonly nodesByKey: ReadonlyMap<Key, Graph.NodeIndex>;
+    readonly start: Graph.NodeIndex;
+    readonly limits: ResolvedExplorationLimits;
+    readonly stats: ExplorationStats;
+    readonly completeness: ExplorationCompleteness<M, Key>;
+}
+interface ExploreOptionsBase<M extends AnyMachine, Key extends ExplorationKey> {
+    readonly events: (context: ExplorationStateContext<M>) => ReadonlyArray<Machine.Machine.InputEvent<M>>;
+    readonly stateKey: (context: ExplorationStateContext<M>) => Key;
+    readonly limits?: ExplorationLimits;
+    readonly invariants?: ReadonlyArray<Invariant<M>>;
+}
+/**
+ * Configuration for bounded planner exploration.
+ *
+ * Event representatives may depend on the current state. Exploration is
+ * exhaustive only relative to those representatives and the equivalence
+ * relation defined by `stateKey`.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export type ExploreOptions<M extends AnyMachine, Key extends ExplorationKey = ExplorationKey> = ExploreOptionsBase<M, Key> & (Machine.Machine.Input<M> extends typeof Schema.Void ? {
+    readonly input?: never;
+} : {
+    readonly input: InputValue<M>;
+});
+/**
+ * Explores the bounded logical state graph in breadth-first order.
+ *
+ * Invariants are checked against startup and every concretely planned edge,
+ * so a failure retains a shortest discovered counterexample. Staged actions
+ * and runtime activities are not executed.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ * import { MachineTest } from "@typeonce/effect-machine/testing"
+ *
+ * class Count extends Schema.TaggedClass<Count>("Count")("Count", {
+ *   value: Schema.Number
+ * }) {}
+ * class Increment extends Schema.TaggedClass<Increment>("Increment")("Increment", {}) {}
+ * const States = Machine.defineStates({ Count })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [Increment],
+ *   initial: () => States.initial.Count(new Count({ value: 0 }))
+ * }).handle({
+ *   Count: { on: { Increment: ({ state }) =>
+ *     States.initial.Count(new Count({ value: state.value + 1 })) } }
+ * })
+ *
+ * const explored = MachineTest.explore(machine, {
+ *   events: ({ snapshot }) => snapshot.value.value < 2 ? [new Increment({})] : [],
+ *   stateKey: ({ snapshot }) => snapshot.value.value
+ * })
+ * ```
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export declare const explore: <M extends AnyMachine, Key extends ExplorationKey>(machine: ReadyMachine<M>, options: ExploreOptions<M, Key>) => Effect.Effect<Exploration<M, Key>, RunFailure<RunError<M>, M> | internal.InvariantError<M>, RunServices<M>>;
+/**
+ * A predicate over one explored logical state.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export type ExplorationPredicate<M extends AnyMachine, Key extends ExplorationKey = ExplorationKey> = (node: ExplorationNode<M, Key>) => boolean;
+/**
+ * Why a reachability assertion failed.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export type ReachabilityFailure = "NotFound" | "UnexpectedMatch" | "Inconclusive";
+/**
+ * A failed or inconclusive reachability assertion.
+ *
+ * @category errors
+ * @since 0.4.0
+ */
+export { ReachabilityError } from "../internal/testing/machine/verification.js";
+/**
+ * Finds the first, and therefore shortest, explored state matching a
+ * predicate.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export declare const findShortest: <M extends AnyMachine, Key extends ExplorationKey>(exploration: Exploration<M, Key>, predicate: ExplorationPredicate<M, Key>) => ExplorationNode<M, Key> | undefined;
+/**
+ * Requires a matching state and returns its shortest witness.
+ *
+ * A truncated exploration without a witness fails as inconclusive rather than
+ * claiming the state is unreachable.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export declare const assertReachable: <M extends AnyMachine, Key extends ExplorationKey>(exploration: Exploration<M, Key>, name: string, predicate: ExplorationPredicate<M, Key>) => Effect.Effect<ExplorationNode<M, Key>, internal.ReachabilityError<M, Key>>;
+/**
+ * Requires that no explored state matches a predicate.
+ *
+ * This assertion succeeds only for a complete exploration. A truncated
+ * result without a witness fails as inconclusive.
+ *
+ * @category exploration
+ * @since 0.4.0
+ */
+export declare const assertUnreachable: <M extends AnyMachine, Key extends ExplorationKey>(exploration: Exploration<M, Key>, name: string, predicate: ExplorationPredicate<M, Key>) => Effect.Effect<void, internal.ReachabilityError<M, Key>>;
 /**
  * Checks a real planner trace against the independent finite statechart model
  * interpreter.
@@ -212,7 +1134,7 @@ export interface Trace<M extends AnyMachine> {
  * and accumulates every disagreement in one structured error.
  *
  * @category verification
- * @since 4.0.0
+ * @since 0.4.0
  */
 export declare const verifyModel: <M extends AnyMachine>(model: FiniteModel, actualTrace: Trace<M>) => Effect.Effect<void, ReferenceModel.ModelVerificationError>;
 /**
@@ -220,7 +1142,7 @@ export declare const verifyModel: <M extends AnyMachine>(model: FiniteModel, act
  * segment preceding it.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type RunFailure<Cause, M extends AnyMachine = AnyMachine> = {
     readonly _tag: "MachineTestRunFailure";
@@ -245,7 +1167,7 @@ export type RunFailure<Cause, M extends AnyMachine = AnyMachine> = {
  * Errors that can be produced while planning a complete scenario.
  *
  * @category errors
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type RunError<M extends AnyMachine> = Machine.Machine.InitialError<M> | Machine.Machine.Error<M> | Machine.InfiniteTransitionError | Machine.MachineSchemaDecodeError | Machine.StartupError;
 /**
@@ -256,7 +1178,7 @@ export type RunError<M extends AnyMachine> = Machine.Machine.InitialError<M> | M
  * later execution, not synchronous planning.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type RunServices<M extends AnyMachine> = IsAny<Machine.PlanningServices<Machine.Machine.InitialServices<M> | Machine.Machine.Services<M>>> extends true ? Machine.PlanningServices<Machine.Machine.InitialServices<M> | Machine.Machine.Services<M>> : never;
 /**
@@ -267,15 +1189,33 @@ export type RunServices<M extends AnyMachine> = IsAny<Machine.PlanningServices<M
  * Typed planning errors retain the scenario and successfully completed prefix
  * in a `RunFailure`.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ * import { MachineTest } from "@typeonce/effect-machine/testing"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: {} })
+ *
+ * const trace = MachineTest.run(machine, { events: [] })
+ * ```
+ *
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
 export declare const run: <M extends AnyMachine>(machine: ReadyMachine<M>, scenario: Scenario<M>) => Effect.Effect<Trace<M>, RunFailure<RunError<M>, M>, RunServices<M>>;
 /**
  * A deterministic hit/miss summary for a finite set declared by a machine.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface CoverageSummary<Item> {
     readonly total: number;
@@ -288,7 +1228,7 @@ export interface CoverageSummary<Item> {
  * One active (non-history) state node in a state coverage summary.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface StateCoverageItem<Path extends string = string> {
     readonly path: Path;
@@ -298,7 +1238,7 @@ export interface StateCoverageItem<Path extends string = string> {
  * State activation and lifecycle coverage.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface StateCoverage<Path extends string = string> {
     readonly activation: CoverageSummary<StateCoverageItem<Path>>;
@@ -309,7 +1249,7 @@ export interface StateCoverage<Path extends string = string> {
  * One stable transition-definition identity in definition order.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface TransitionCoverageItem<SourcePath extends string = string, EventTag extends PropertyKey = PropertyKey, TargetPath extends string = SourcePath> {
     readonly id: string;
@@ -323,7 +1263,7 @@ export interface TransitionCoverageItem<SourcePath extends string = string, Even
  * One public event tag declared by the machine.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface EventCoverageItem<Tag extends PropertyKey = PropertyKey> {
     readonly tag: Tag;
@@ -333,7 +1273,7 @@ export interface EventCoverageItem<Tag extends PropertyKey = PropertyKey> {
  * Public event coverage, including events that no transition retained.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type EventCoverage<Tag extends PropertyKey = PropertyKey> = {
     readonly available: true;
@@ -361,7 +1301,7 @@ export type EventCoverage<Tag extends PropertyKey = PropertyKey> = {
  * Trace-derived scenario counts. There is no finite declared scenario space.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface ScenarioCoverage {
     readonly traces: number;
@@ -372,7 +1312,7 @@ export interface ScenarioCoverage {
  * Trace-derived logical configuration counts. There is no claimed exhaustive total.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface LogicalConfigurationCoverage {
     readonly observations: number;
@@ -383,7 +1323,7 @@ export interface LogicalConfigurationCoverage {
  * Directly observed startup and microstep evidence.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface MicrostepCoverageEvidence {
     readonly total: number;
@@ -400,7 +1340,7 @@ export interface MicrostepCoverageEvidence {
  * Directly observed completion evidence.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface CompletionCoverageEvidence<Path extends string = string> {
     readonly donePlans: number;
@@ -411,7 +1351,7 @@ export interface CompletionCoverageEvidence<Path extends string = string> {
  * Directly observed history records and history-target transitions.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface HistoryCoverageEvidence<Path extends string = string> {
     readonly recordObservations: number;
@@ -426,7 +1366,7 @@ export interface HistoryCoverageEvidence<Path extends string = string> {
  * Coverage computed only from observable machine definitions and planner traces.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface Coverage<M extends AnyMachine> {
     readonly states: StateCoverage<StatePath<M>>;
@@ -448,15 +1388,36 @@ export interface Coverage<M extends AnyMachine> {
  * configurations report observations only because their complete spaces are
  * generally infinite.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ * import { MachineTest } from "@typeonce/effect-machine/testing"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: {} })
+ *
+ * const report = Effect.map(
+ *   MachineTest.run(machine, { events: [] }),
+ *   (trace) => MachineTest.coverage(machine, trace)
+ * )
+ * ```
+ *
  * @category verification
- * @since 4.0.0
+ * @since 0.4.0
  */
 export declare const coverage: <M extends AnyMachine>(machine: M, traceOrTraces: Trace<M> | ReadonlyArray<Trace<M>>) => Coverage<M>;
 /**
  * The observation roles summarized for one logical graph node.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface ObservedGraphNodeObservations {
     readonly total: number;
@@ -468,7 +1429,7 @@ export interface ObservedGraphNodeObservations {
  * One full encoded logical snapshot stored in the observed Effect graph.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface ObservedGraphNode<M extends AnyMachine> {
     readonly id: string;
@@ -481,7 +1442,7 @@ export interface ObservedGraphNode<M extends AnyMachine> {
  * Retained evidence for one microstep inside an observed graph edge.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface ObservedGraphMicrostep<M extends AnyMachine> {
     readonly next: string;
@@ -497,7 +1458,7 @@ export interface ObservedGraphMicrostep<M extends AnyMachine> {
  * A startup or public-event macrostep retained by the observed graph.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type ObservedGraphEdge<M extends AnyMachine> = {
     readonly _tag: "Startup";
@@ -516,7 +1477,7 @@ export type ObservedGraphEdge<M extends AnyMachine> = {
  * An Effect directed graph plus stable indexes useful to graph algorithms.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface ObservedGraph<M extends AnyMachine> {
     readonly graph: Graph.DirectedGraph<ObservedGraphNode<M>, ObservedGraphEdge<M>>;
@@ -533,28 +1494,28 @@ export interface ObservedGraph<M extends AnyMachine> {
  * claim to be a static or exhaustive graph of the machine.
  *
  * @category verification
- * @since 4.0.0
+ * @since 0.4.0
  */
 export declare const observedGraph: <M extends AnyMachine>(machine: M, traceOrTraces: Trace<M> | ReadonlyArray<Trace<M>>) => Effect.Effect<ObservedGraph<M>, Machine.MachineSchemaEncodeError, Machine.Machine.SnapshotEncodingServices<Machine.Machine.States<M>>>;
 /**
  * Independently checked families of planner laws.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type VerificationLawGroup = "configuration" | "microsteps" | "completion" | "history" | "targetBounds";
 /**
  * Stable identifiers for individual planner laws.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export type VerificationLaw = "configuration.shape" | "configuration.path" | "configuration.schema" | "configuration.hierarchy" | "configuration.compound" | "configuration.parallel" | "configuration.duplicate" | "configuration.trace" | "microsteps.unique" | "microsteps.order" | "microsteps.activeBefore" | "microsteps.activeAfter" | "microsteps.changed" | "microsteps.continuity" | "microsteps.reentry" | "completion.record" | "completion.output" | "completion.done" | "history.record" | "history.mode" | "history.path" | "history.value" | "history.shallow" | "history.deep" | "targetBounds.definition" | "targetBounds.target";
 /**
  * One independently observed violation in a planner trace.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface VerificationViolation {
     readonly law: VerificationLaw;
@@ -568,14 +1529,14 @@ export interface VerificationViolation {
  * All violations found while checking one trace.
  *
  * @category errors
- * @since 4.0.0
+ * @since 0.4.0
  */
 export { VerificationError } from "../internal/testing/machine/verification.js";
 /**
  * Selects law families for the single canonical verifier. All run by default.
  *
  * @category models
- * @since 4.0.0
+ * @since 0.4.0
  */
 export interface VerifyOptions {
     readonly laws?: ReadonlyArray<VerificationLawGroup>;
@@ -588,8 +1549,29 @@ export interface VerifyOptions {
  * Every selected law is evaluated and returned in one structured error so a
  * shrunk property-test counterexample retains all relevant evidence.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ * import { MachineTest } from "@typeonce/effect-machine/testing"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: {} })
+ *
+ * const checked = Effect.gen(function*() {
+ *   const trace = yield* MachineTest.run(machine, { events: [] })
+ *   yield* MachineTest.verify(machine, trace)
+ * })
+ * ```
+ *
  * @category verification
- * @since 4.0.0
+ * @since 0.4.0
  */
 export declare const verify: <M extends AnyMachine>(machine: M, trace: Trace<M>, options?: VerifyOptions) => Effect.Effect<void, VerificationError>;
 /**
@@ -600,7 +1582,7 @@ export declare const verify: <M extends AnyMachine>(machine: M, trace: Trace<M>,
  * Failures include their original cause and every available successful prefix.
  *
  * @category formatting
- * @since 4.0.0
+ * @since 0.4.0
  */
 export declare const formatTrace: <M extends AnyMachine, Cause>(trace: Trace<M> | RunFailure<Cause, M>) => string;
 //# sourceMappingURL=MachineTest.d.ts.map