@typeonce/effect-machine 0.3.0 → 0.4.0

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

@@ -0,0 +1,322 @@
+/**
+ * Finite hierarchical, parallel, history, choice, and automatic-transition
+ * statechart models used by the public testing module.
+ *
+ * This module intentionally compiles through the public Machine API. It must
+ * not share planner helpers with the implementation that later reference
+ * models are expected to check.
+ *
+ * @internal
+ */
+import { FastCheck } from "effect/testing";
+import * as Machine from "../../../Machine.js";
+/**
+ * An atomic state in a finite generated model.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteAtomicState {
+    readonly _tag: "Atomic";
+    readonly key: string;
+    /** Deterministic payload accepted by this state's generated schema. */
+    readonly value: number;
+}
+/**
+ * A final state in a finite generated model.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteFinalState {
+    readonly _tag: "Final";
+    readonly key: string;
+    /** Deterministic payload accepted by this state's generated schema. */
+    readonly value: number;
+    /** Deterministic value returned by this state's output handler. */
+    readonly output: string;
+}
+/**
+ * A compound state in a finite generated model.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteCompoundState {
+    readonly _tag: "Compound";
+    readonly key: string;
+    /** Deterministic payload accepted by this state's generated schema. */
+    readonly value: number;
+    /** Key of the direct child entered by default. */
+    readonly initial: string;
+    readonly states: ReadonlyArray<FiniteState>;
+}
+/**
+ * A parallel state in a finite generated model.
+ *
+ * Every direct child is an orthogonal region and is active whenever the
+ * parallel state is active. The output is deterministic so completion can be
+ * compared without sharing executable callbacks with the reference model.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteParallelState {
+    readonly _tag: "Parallel";
+    readonly key: string;
+    /** Deterministic payload accepted by this state's generated schema. */
+    readonly value: number;
+    /** Deterministic value returned after every region completes. */
+    readonly output: string;
+    /** Between two and three orthogonal region nodes. */
+    readonly states: ReadonlyArray<FiniteState>;
+}
+/**
+ * A shallow or deep history pseudo-state in a finite generated model.
+ *
+ * History states never carry values, become active, or act as transition
+ * sources. `fallback` is a concrete descendant of the direct compound or
+ * parallel owner and is used only before that history register is captured.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteHistoryState {
+    readonly _tag: "History";
+    readonly key: string;
+    readonly history: "shallow" | "deep";
+    readonly fallback: string;
+}
+/** A deterministic transient choice pseudo-state in a finite model. */
+export interface FiniteChoiceState {
+    readonly _tag: "Choice";
+    readonly key: string;
+    readonly targets: ReadonlyArray<string>;
+    readonly selected: string;
+}
+/**
+ * A finite model state.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type FiniteState = FiniteAtomicState | FiniteFinalState | FiniteCompoundState | FiniteParallelState | FiniteHistoryState | FiniteChoiceState;
+/**
+ * The single trigger representation used by generated and hand-authored finite
+ * transitions. Event, always, and completion registrations therefore share the
+ * same validation, compilation, and reference interpretation path.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type FiniteTransitionTrigger = {
+    readonly type: "event";
+    readonly event: string;
+} | {
+    readonly type: "always";
+} | {
+    readonly type: "done";
+};
+/**
+ * One deterministic transition in a finite generated model.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+interface FiniteTransitionBase {
+    readonly source: string;
+    /** Omission represents a targetless transition. */
+    readonly target?: string;
+    /** Optional schema-valid value supplied for the declared target state. */
+    readonly targetValue?: number;
+}
+/**
+ * A public event transition may explicitly request source reentry.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type FiniteEventTransition = FiniteTransitionBase & {
+    readonly trigger: Extract<FiniteTransitionTrigger, {
+        readonly type: "event";
+    }>;
+    readonly reenter: boolean;
+};
+/**
+ * An always or completion transition. Automatic transitions deliberately omit
+ * the event-only reentry option.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type FiniteAutomaticTransition = FiniteTransitionBase & {
+    readonly trigger: Exclude<FiniteTransitionTrigger, {
+        readonly type: "event";
+    }>;
+};
+/**
+ * One deterministic event or automatic transition in a finite model.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type FiniteTransition = FiniteEventTransition | FiniteAutomaticTransition;
+/**
+ * The exact generated transition that changes a value before history capture.
+ *
+ * The source and target are the same active atomic state. `value` is distinct
+ * from that state's generated default value.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteHistoryMutation {
+    readonly source: string;
+    readonly event: string;
+    readonly target: string;
+    readonly value: number;
+}
+/**
+ * One exact transition in a generated history witness.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteHistoryTransfer {
+    readonly source: string;
+    readonly event: string;
+    readonly target: string;
+}
+/**
+ * A replayable value-mutation, capture, and restoration witness generated for
+ * one history pseudo-state.
+ *
+ * `events` is exactly `[mutation.event, leave.event, resume.event]`. Replaying
+ * it changes a schema-valid atomic value, exits the history owner through its
+ * root, and restores the remembered non-default value through `history`.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteHistoryScenario {
+    readonly history: string;
+    readonly owner: string;
+    readonly historyType: "shallow" | "deep";
+    readonly mutation: FiniteHistoryMutation;
+    readonly leave: FiniteHistoryTransfer;
+    readonly resume: FiniteHistoryTransfer;
+    readonly events: readonly [mutation: string, leave: string, resume: string];
+}
+/**
+ * A small immutable statechart model suitable for generation and shrinking.
+ *
+ * State paths use dot-separated state keys. Transitions are unique by
+ * source/event pair. A transition may target any state under its source root,
+ * or a different root as a complete configuration.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteModel {
+    readonly roots: ReadonlyArray<FiniteState>;
+    /** Key of the root entered during startup. */
+    readonly initial: string;
+    readonly events: ReadonlyArray<string>;
+    readonly transitions: ReadonlyArray<FiniteTransition>;
+    /** Exact value-sensitive history witnesses attached by `finiteModels`. */
+    readonly historyScenarios?: ReadonlyArray<FiniteHistoryScenario>;
+}
+/**
+ * Limits controlling finite model generation.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteModelOptions {
+    /** Maximum number of root states. Always between one and three. */
+    readonly maxRoots?: 1 | 2 | 3;
+    /** Maximum state-tree depth, counting a root as depth one. */
+    readonly maxDepth?: number;
+    /** Maximum number of direct children in a compound state. */
+    readonly maxChildren?: number;
+    /** Maximum number of regions in a parallel state. Always two or three. */
+    readonly maxParallelRegions?: 2 | 3;
+    /** Maximum number of distinct public event tags. */
+    readonly maxEvents?: number;
+    /** Maximum number of source/event transition registrations. */
+    readonly maxTransitions?: number;
+    /** Maximum number of history pseudo-states added to one generated model. */
+    readonly maxHistoryStates?: number;
+    /** Maximum number of deterministic choice witnesses added to a generated model. */
+    readonly maxChoiceStates?: number;
+}
+/**
+ * Resolved limits and structural guarantees for a finite model arbitrary.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteModelDiagnostics {
+    readonly limits: {
+        readonly maxRoots: 1 | 2 | 3;
+        readonly maxDepth: number;
+        readonly maxChildren: number;
+        readonly maxParallelRegions: 2 | 3;
+        readonly maxEvents: number;
+        readonly maxTransitions: number;
+        readonly maxHistoryStates: number;
+        readonly maxChoiceStates: number;
+    };
+    readonly guarantees: {
+        readonly compoundOnly: false;
+        readonly parallelStates: true;
+        readonly historyStates: true;
+        readonly historyLeaveResumeSequences: true;
+        readonly historyValueScenarios: true;
+        readonly choiceStates: true;
+        readonly choiceInitialWitnesses: true;
+        readonly structurallyValid: true;
+        readonly shrinkPreservesValidity: true;
+        readonly eventlessTransitions: true;
+        readonly acyclicAutomaticTransitions: true;
+    };
+}
+/**
+ * A finite model arbitrary and the exact limits used to construct it.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface FiniteModels {
+    readonly arbitrary: FastCheck.Arbitrary<FiniteModel>;
+    readonly diagnostics: FiniteModelDiagnostics;
+}
+/**
+ * Generates bounded, structurally valid hierarchical statechart
+ * models.
+ *
+ * Generation is composed from shrinkable topology, initial-state, event, and
+ * transition decisions. Paths and transition candidates are rebuilt after a
+ * topology shrink, so a shrink can never retain a dangling source or target.
+ * Generated automatic transitions are acyclic by construction: `always`
+ * transitions leave atomic sources and completion transitions leave compound
+ * or parallel sources. Separate focused witnesses cover cyclic stabilization.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const finiteModels: (options?: FiniteModelOptions) => FiniteModels;
+/**
+ * Compiles a finite model into a real machine using only public definition,
+ * construction, and handler APIs.
+ *
+ * Hand-authored models are validated before compilation. This compiler is a
+ * testing adapter, not the independent reference interpreter used by later
+ * conformance stages.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const compileModel: (model: FiniteModel) => Machine.Machine.Any;
+export {};
+//# sourceMappingURL=finiteModel.d.ts.map

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

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