@typeonce/effect-machine-devtools 0.24.0 → 0.26.0

package/src/DevToolsProtocol.ts

@@ -144,288 +144,3 @@ export const RegistrySnapshot = Schema.Struct({
  * @since 0.23.0
  */
 export type RegistrySnapshot = Schema.Schema.Type<typeof RegistrySnapshot>
-
-/**
- * JSON-safe representation of a persisted machine snapshot.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const EncodedSnapshot = Schema.Struct({
-  _tag: Schema.Literal("MachineSnapshot"),
-  active: Schema.Array(Schema.Struct({
-    path: Schema.String,
-    value: Schema.optionalKey(Schema.Json)
-  })),
-  completed: Schema.optionalKey(Schema.Array(Schema.Struct({
-    path: Schema.String,
-    output: Schema.optionalKey(Schema.Json)
-  }))),
-  history: Schema.optionalKey(Schema.Record(
-    Schema.String,
-    Schema.Struct({
-      mode: Schema.Literals(["shallow", "deep"]),
-      active: Schema.Array(Schema.String),
-      values: Schema.Record(Schema.String, Schema.Json)
-    })
-  ))
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type EncodedSnapshot = Schema.Schema.Type<typeof EncodedSnapshot>
-
-const SimulationRequestFields = {
-  protocolVersion: Schema.Literal(protocolVersion),
-  key: Schema.String,
-  revision: Schema.Natural,
-  source: MachineDocument.Source
-}
-
-/**
- * Starts an isolated planner session. Omitting `input` calls a machine that
- * declares no input; otherwise the JSON value is decoded by its input schema.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const StartSimulation = Schema.Struct({
-  ...SimulationRequestFields,
-  _tag: Schema.tag("StartSimulation"),
-  input: Schema.optionalKey(Schema.Json)
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type StartSimulation = Schema.Schema.Type<typeof StartSimulation>
-
-/**
- * Plans one JSON event from an encoded session snapshot.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const SendSimulationEvent = Schema.Struct({
-  ...SimulationRequestFields,
-  _tag: Schema.tag("SendSimulationEvent"),
-  step: Schema.Natural,
-  snapshot: EncodedSnapshot,
-  event: Schema.Json
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type SendSimulationEvent = Schema.Schema.Type<typeof SendSimulationEvent>
-
-/**
- * Request accepted by the isolated machine planner.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const SimulationRequest = Schema.Union([StartSimulation, SendSimulationEvent])
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type SimulationRequest = Schema.Schema.Type<typeof SimulationRequest>
-
-/**
- * A compact view of one logical machine snapshot.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const SimulationSnapshot = Schema.Struct({
-  activePaths: Schema.Array(Schema.String),
-  candidateEvents: Schema.Array(Schema.String)
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type SimulationSnapshot = Schema.Schema.Type<typeof SimulationSnapshot>
-
-/**
- * Transition selected by the planner after hierarchy and conflict resolution.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const PlannedTransition = Schema.Struct({
-  source: Schema.String,
-  trigger: MachineDocument.Trigger,
-  reenter: Schema.Boolean,
-  branchIndex: Schema.Natural,
-  branchKey: Schema.NullOr(Schema.String),
-  target: Schema.NullOr(Schema.String),
-  resolvedTarget: Schema.NullOr(Schema.String),
-  updates: Schema.Array(Schema.String)
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type PlannedTransition = Schema.Schema.Type<typeof PlannedTransition>
-
-/**
- * Closed command produced by planning. Commands are displayed but never
- * committed by the visualizer.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const PlannedCommand = Schema.Union([
-  Schema.Struct({
-    _tag: Schema.tag("SendTo"),
-    target: Schema.String,
-    event: Schema.Json
-  }),
-  Schema.Struct({
-    _tag: Schema.tag("Stop"),
-    target: Schema.String
-  })
-])
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type PlannedCommand = Schema.Schema.Type<typeof PlannedCommand>
-
-/**
- * One statechart microstep retained in a planned macrostep.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const SimulationMicrostep = Schema.Struct({
-  index: Schema.Natural,
-  event: Schema.Json,
-  transitions: Schema.Array(PlannedTransition),
-  raisedEvents: Schema.Array(Schema.Json),
-  emittedEvents: Schema.Array(Schema.Json),
-  commands: Schema.Array(PlannedCommand),
-  exitPaths: Schema.Array(Schema.String),
-  entryPaths: Schema.Array(Schema.String),
-  activePaths: Schema.Array(Schema.String),
-  changed: Schema.Boolean
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type SimulationMicrostep = Schema.Schema.Type<typeof SimulationMicrostep>
-
-/**
- * Structured trace for an initial plan or one received event.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const SimulationFrame = Schema.Struct({
-  step: Schema.Natural,
-  trigger: Schema.Union([
-    Schema.Struct({ _tag: Schema.tag("Initial"), input: Schema.optionalKey(Schema.Json) }),
-    Schema.Struct({ _tag: Schema.tag("Event"), event: Schema.Json })
-  ]),
-  before: SimulationSnapshot,
-  after: SimulationSnapshot,
-  microsteps: Schema.Array(SimulationMicrostep),
-  commands: Schema.Array(PlannedCommand),
-  emittedEvents: Schema.Array(Schema.Json),
-  done: Schema.Boolean,
-  output: Schema.optionalKey(Schema.Json)
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type SimulationFrame = Schema.Schema.Type<typeof SimulationFrame>
-
-/**
- * Successful planner response containing the next portable session state.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const SimulationReady = Schema.Struct({
-  protocolVersion: Schema.Literal(protocolVersion),
-  _tag: Schema.tag("SimulationReady"),
-  key: Schema.String,
-  revision: Schema.Natural,
-  step: Schema.Natural,
-  snapshot: EncodedSnapshot,
-  current: SimulationSnapshot,
-  frame: SimulationFrame
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type SimulationReady = Schema.Schema.Type<typeof SimulationReady>
-
-/**
- * One authoritative Effect Schema issue associated with a machine or event
- * input path.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const InputIssue = Schema.Struct({
-  path: Schema.Array(Schema.Union([Schema.String, Schema.Number])),
-  message: Schema.String
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type InputIssue = Schema.Schema.Type<typeof InputIssue>
-
-/**
- * Recoverable failure produced while loading, decoding, or planning a session.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const SimulationFailed = Schema.Struct({
-  protocolVersion: Schema.Literal(protocolVersion),
-  _tag: Schema.tag("SimulationFailed"),
-  key: Schema.String,
-  revision: Schema.Natural,
-  diagnostics: Schema.Array(Diagnostic),
-  inputIssues: Schema.Array(InputIssue)
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type SimulationFailed = Schema.Schema.Type<typeof SimulationFailed>
-
-/**
- * Result returned by the isolated machine planner.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const SimulationResult = Schema.Union([SimulationReady, SimulationFailed])
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type SimulationResult = Schema.Schema.Type<typeof SimulationResult>

package/src/MachineDocument.ts

@@ -13,7 +13,7 @@ import * as internal from "./internal/machineDocument.js"
  * @category models
  * @since 0.23.0
  */
-export const schemaVersion = 2 as const
+export const schemaVersion = 3 as const
 
 /**
  * Source module and export that produced a machine.
@@ -65,6 +65,24 @@ export const Initial = Schema.Struct({
  */
 export type Initial = Schema.Schema.Type<typeof Initial>
 
+/**
+ * Canonical JSON Schema retained for machine contracts.
+ *
+ * @category schemas
+ * @since 0.24.0
+ */
+export const InputSchema = Schema.Struct({
+  dialect: Schema.Literal("draft-2020-12"),
+  schema: Schema.Json,
+  definitions: Schema.Record(Schema.String, Schema.Json)
+})
+
+/**
+ * @category models
+ * @since 0.24.0
+ */
+export type InputSchema = Schema.Schema.Type<typeof InputSchema>
+
 /**
  * @category schemas
  * @since 0.23.0
@@ -81,6 +99,8 @@ export const State = Schema.Struct({
   parent: Schema.NullOr(Schema.String),
   children: Schema.Array(Schema.String),
   initial: Schema.NullOr(Schema.String),
+  valueSchema: Schema.NullOr(InputSchema),
+  outputSchema: Schema.NullOr(InputSchema),
   transitionIds: Schema.Array(Schema.String),
   activityIds: Schema.Array(Schema.String)
 })
@@ -216,24 +236,6 @@ export const Snapshot = Schema.Struct({
  */
 export type Snapshot = Schema.Schema.Type<typeof Snapshot>
 
-/**
- * Canonical JSON Schema used to render one machine input form.
- *
- * @category schemas
- * @since 0.24.0
- */
-export const InputSchema = Schema.Struct({
-  dialect: Schema.Literal("draft-2020-12"),
-  schema: Schema.Json,
-  definitions: Schema.Record(Schema.String, Schema.Json)
-})
-
-/**
- * @category models
- * @since 0.24.0
- */
-export type InputSchema = Schema.Schema.Type<typeof InputSchema>
-
 /**
  * Public event input paired with the schema for its payload.
  *

package/src/MachineWalkthrough.ts

@@ -0,0 +1,199 @@
+/**
+ * Side-effect-free topology walkthroughs over machine documents.
+ *
+ * @since 0.25.0
+ */
+import { dual } from "effect/Function"
+import * as Result from "effect/Result"
+import * as Schema from "effect/Schema"
+import * as internal from "./internal/machineWalkthrough.js"
+import type * as MachineDocument from "./MachineDocument.js"
+
+const TypeId = internal.SessionTypeId
+
+/**
+ * An immutable walkthrough session. Its timeline can be inspected and its
+ * cursor can move without evaluating machine callbacks.
+ *
+ * @category models
+ * @since 0.25.0
+ */
+export interface Session {
+  readonly [TypeId]: typeof TypeId
+}
+
+/**
+ * Why taking a documented branch requires an explicit human decision.
+ *
+ * @category models
+ * @since 0.25.0
+ */
+export type Decision =
+  | "conditional-branch"
+  | "declinable-transition"
+  | "automatic-trigger"
+  | "invoke-outcome"
+
+/**
+ * Why a documented branch cannot advance topology without runtime data.
+ *
+ * @category models
+ * @since 0.25.0
+ */
+export type UnavailableReason = "history-unavailable" | "runtime-target"
+
+/**
+ * One branch that can be explored from the current active configuration.
+ *
+ * @category models
+ * @since 0.25.0
+ */
+export interface Choice {
+  readonly id: string
+  readonly transitionId: string
+  readonly branchId: string
+  readonly branchIndex: number
+  readonly branchKey: string | null
+  readonly title: string | null
+  readonly source: string
+  readonly trigger: MachineDocument.Trigger
+  readonly target: string | null
+  readonly selection: MachineDocument.Selection
+  readonly updates: ReadonlyArray<string>
+  readonly decisions: ReadonlyArray<Decision>
+  readonly unavailableReason: UnavailableReason | null
+  readonly input: MachineDocument.InputSchema | null
+}
+
+/**
+ * The active state paths at one point in a walkthrough.
+ *
+ * @category models
+ * @since 0.25.0
+ */
+export interface Snapshot {
+  readonly activePaths: ReadonlyArray<string>
+}
+
+/**
+ * One initial or manually selected topology step.
+ *
+ * @category models
+ * @since 0.25.0
+ */
+export interface Frame {
+  readonly step: number
+  readonly choice: Choice | null
+  readonly before: Snapshot
+  readonly after: Snapshot
+  readonly exitPaths: ReadonlyArray<string>
+  readonly entryPaths: ReadonlyArray<string>
+  readonly changed: boolean
+}
+
+/**
+ * A requested choice is not available from the cursor's configuration.
+ *
+ * @category errors
+ * @since 0.25.0
+ */
+export class ChoiceNotFound extends Schema.Error<ChoiceNotFound>(
+  "@typeonce/effect-machine-devtools/MachineWalkthrough/ChoiceNotFound"
+)({
+  _tag: Schema.tag("ChoiceNotFound"),
+  choiceId: Schema.String
+}) {}
+
+/**
+ * A choice depends on runtime information absent from the machine document.
+ *
+ * @category errors
+ * @since 0.25.0
+ */
+export class ChoiceUnavailable extends Schema.Error<ChoiceUnavailable>(
+  "@typeonce/effect-machine-devtools/MachineWalkthrough/ChoiceUnavailable"
+)({
+  _tag: Schema.tag("ChoiceUnavailable"),
+  choiceId: Schema.String,
+  reason: Schema.Literals(["history-unavailable", "runtime-target"])
+}) {}
+
+/**
+ * A requested timeline step does not exist.
+ *
+ * @category errors
+ * @since 0.25.0
+ */
+export class StepNotFound extends Schema.Error<StepNotFound>(
+  "@typeonce/effect-machine-devtools/MachineWalkthrough/StepNotFound"
+)({
+  _tag: Schema.tag("StepNotFound"),
+  step: Schema.Number
+}) {}
+
+const api = { ChoiceNotFound, ChoiceUnavailable, StepNotFound }
+
+/**
+ * Starts at the document's captured snapshot when present, otherwise at its
+ * statically declared initial configuration.
+ *
+ * @category constructors
+ * @since 0.25.0
+ */
+export const start: (document: MachineDocument.MachineDocument) => Session = internal.start
+
+/**
+ * Returns the frame selected by the session cursor.
+ *
+ * @category getters
+ * @since 0.25.0
+ */
+export const current: (self: Session) => Frame = internal.current
+
+/**
+ * Returns every retained frame, including frames after the current cursor.
+ *
+ * @category getters
+ * @since 0.25.0
+ */
+export const timeline: (self: Session) => ReadonlyArray<Frame> = internal.timeline
+
+/**
+ * Returns the current zero-based timeline position.
+ *
+ * @category getters
+ * @since 0.25.0
+ */
+export const cursor: (self: Session) => number = internal.cursor
+
+/**
+ * Lists documented branches whose sources are active at the current cursor.
+ * Runtime-dependent choices remain visible with an unavailable reason.
+ *
+ * @category getters
+ * @since 0.25.0
+ */
+export const choices: (self: Session) => ReadonlyArray<Choice> = internal.choices
+
+/**
+ * Takes one documented branch. Taking a branch from the past truncates the
+ * future timeline before appending the new frame.
+ *
+ * @category combinators
+ * @since 0.25.0
+ */
+export const take: {
+  (choiceId: string): (self: Session) => Result.Result<Session, ChoiceNotFound | ChoiceUnavailable>
+  (self: Session, choiceId: string): Result.Result<Session, ChoiceNotFound | ChoiceUnavailable>
+} = dual(2, internal.take(api))
+
+/**
+ * Moves the cursor to an existing frame without changing the timeline.
+ *
+ * @category combinators
+ * @since 0.25.0
+ */
+export const seek: {
+  (step: number): (self: Session) => Result.Result<Session, StepNotFound>
+  (self: Session, step: number): Result.Result<Session, StepNotFound>
+} = dual(2, internal.seek(api))

package/src/ProjectInspector.ts

@@ -92,11 +92,6 @@ export class ProjectInspector extends Context.Service<ProjectInspector, {
   readonly inspect: (
     options: InspectOptions
   ) => Effect.Effect<ReadonlyArray<DevToolsProtocol.MachineResult>, DiscoveryError | EvaluationError>
-  /** @internal */
-  readonly simulate: (
-    request: DevToolsProtocol.SimulationRequest,
-    options: Pick<InspectOptions, "root">
-  ) => Effect.Effect<DevToolsProtocol.SimulationResult, EvaluationError>
 }>()("@typeonce/effect-machine-devtools/ProjectInspector") {}
 
 /**

package/src/index.ts

@@ -15,6 +15,6 @@ export * as DevToolsProtocol from "./DevToolsProtocol.js"
 export * as MachineDocument from "./MachineDocument.js"
 
 /**
- * @since 0.23.0
+ * @since 0.25.0
  */
-export * as MachineSimulator from "./MachineSimulator.js"
+export * as MachineWalkthrough from "./MachineWalkthrough.js"