@typeonce/effect-machine 0.3.0 → 0.5.0

package/dist/internal/testing/machine/referenceModel.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Independent hierarchical, parallel, history, choice, and automatic-
+ * transition statechart semantics for finite test models.
+ *
+ * This module deliberately knows nothing about `Machine`, its snapshots, the
+ * finite-model compiler, target builders, or planner internals. The actual
+ * planner trace is treated as opaque data and projected structurally only at
+ * the comparison boundary.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import type { FiniteModel } from "./finiteModel.js";
+/**
+ * The deterministic value assigned to one active finite-model state.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceStateValue {
+    readonly _tag: string;
+    readonly value: number;
+}
+/**
+ * One output retained for an actively completed state.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceCompletion {
+    readonly path: string;
+    readonly output: string;
+}
+/**
+ * One independently captured shallow or deep history register.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceHistoryRecord {
+    readonly mode: "shallow" | "deep";
+    readonly active: ReadonlyArray<string>;
+    readonly values: Readonly<Record<string, ReferenceStateValue>>;
+}
+/**
+ * An independently interpreted finite-model configuration.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceState {
+    /** Active ancestors and leaf in state-definition order. */
+    readonly activePaths: ReadonlyArray<string>;
+    /** Deterministic state values keyed by active state path. */
+    readonly values: Readonly<Record<string, ReferenceStateValue>>;
+    /** Completed final and compound paths in completion order. */
+    readonly completions: ReadonlyArray<ReferenceCompletion>;
+    /** Logical history registers keyed by history pseudo-state path. */
+    readonly history: Readonly<Record<string, ReferenceHistoryRecord>>;
+    readonly status: "active" | "done";
+    readonly output: string | undefined;
+}
+/**
+ * One transition retained by the independent reference step.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceTransition {
+    readonly source: string;
+    readonly trigger: {
+        readonly type: "event";
+        readonly event: string;
+    } | {
+        readonly type: "always";
+    } | {
+        readonly type: "done";
+    } | {
+        readonly type: "choice";
+    };
+    readonly reenter: boolean;
+    readonly target: string | undefined;
+    readonly resolvedTarget: string | undefined;
+}
+/**
+ * The independently calculated planner microstep for one selected event.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceMicrostep {
+    readonly next: ReferenceState;
+    readonly event: string;
+    readonly transitions: ReadonlyArray<ReferenceTransition>;
+    readonly exitPaths: ReadonlyArray<string>;
+    readonly entryPaths: ReadonlyArray<string>;
+    readonly changed: boolean;
+}
+/**
+ * Startup semantics calculated without executing the real machine.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceInitialStep {
+    readonly startingState: ReferenceState;
+    readonly initialEntryPaths: ReadonlyArray<string>;
+    readonly state: ReferenceState;
+    readonly microsteps: ReadonlyArray<ReferenceMicrostep>;
+    readonly done: boolean;
+    readonly output: string | undefined;
+}
+/**
+ * One public event interpreted against a reference configuration.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceStep {
+    readonly index: number;
+    readonly event: string;
+    readonly before: ReferenceState;
+    readonly microsteps: ReadonlyArray<ReferenceMicrostep>;
+    readonly after: ReferenceState;
+    readonly done: boolean;
+    readonly output: string | undefined;
+}
+/**
+ * A complete, pure interpretation of a finite model and event sequence.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceTrace {
+    readonly events: ReadonlyArray<string>;
+    readonly initial: ReferenceInitialStep;
+    readonly steps: ReadonlyArray<ReferenceStep>;
+    readonly final: ReferenceState;
+}
+/**
+ * Location of one planner/reference disagreement.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ModelVerificationLocation {
+    readonly phase: "initial" | "event" | "final";
+    readonly eventIndex?: number;
+    readonly microstepIndex?: number;
+}
+type ModelStateField = "initial.startingState" | "initial.plan.startingState" | "initial.plan.state" | "step.before" | "microstep.next" | "step.plan.next" | "step.after" | "trace.final";
+/**
+ * Stable semantic observation compared by the finite-model oracle.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export type ModelVerificationField = `${ModelStateField}.${"activePaths" | "values" | "completions" | "history"}` | "event.tag" | "initial.startingConfiguration" | "initial.initialEntryPaths" | "initial.plan.initialEntryPaths" | "initial.configuration" | "initial.plan.microsteps" | "initial.plan.done" | "initial.plan.output" | "trace.steps.length" | "step.index" | "step.event" | "step.beforeConfiguration" | "step.plan.microsteps.length" | "microstep.event" | "microstep.transitions" | "microstep.exitPaths" | "microstep.entryPaths" | "microstep.changed" | "step.afterConfiguration" | "step.plan.done" | "step.plan.output" | "trace.finalConfiguration";
+/**
+ * One structured semantic disagreement with the independent interpreter.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ModelVerificationMismatch {
+    readonly location: ModelVerificationLocation;
+    /** Stable dotted field identifying the compared observation. */
+    readonly field: ModelVerificationField;
+    readonly expected: unknown;
+    readonly actual: unknown;
+    readonly message: string;
+}
+declare const ModelVerificationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "MachineTestModelVerificationError";
+} & Readonly<A>;
+/**
+ * All semantic disagreements found for one finite-model trace.
+ *
+ * @category errors
+ * @since 0.4.0
+ */
+export declare class ModelVerificationError extends ModelVerificationError_base<{
+    readonly mismatches: ReadonlyArray<ModelVerificationMismatch>;
+}> {
+}
+/**
+ * Purely interprets a hierarchical finite model without compiling or
+ * executing a `Machine`.
+ *
+ * @category verification
+ * @since 0.4.0
+ */
+export declare const interpretModel: (model: FiniteModel, events: ReadonlyArray<string>) => ReferenceTrace;
+/**
+ * Compares an opaque executable planner trace with the independent finite
+ * reference interpreter. The function accumulates every mismatch so shrunk
+ * counterexamples preserve the full semantic difference.
+ *
+ * @internal The public wrapper narrows `actualTrace` to `MachineTest.Trace`.
+ */
+export declare const verifyModelTrace: (model: FiniteModel, actualTrace: unknown) => Effect.Effect<void, ModelVerificationError>;
+export {};
+//# sourceMappingURL=referenceModel.d.ts.map

package/dist/internal/testing/machine/referenceModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referenceModel.d.ts","sourceRoot":"","sources":["../../../../src/internal/testing/machine/referenceModel.ts"],"names":[],"mappings":"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"}