@typeonce/effect-machine-devtools 0.23.0 → 0.24.0

package/src/DevToolsProtocol.ts

@@ -12,7 +12,7 @@ import * as MachineDocument from "./MachineDocument.js"
  * @category models
  * @since 0.23.0
  */
-export const protocolVersion = 1 as const
+export const protocolVersion = 2 as const
 
 /**
  * @category schemas
@@ -144,3 +144,288 @@ 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 = 1 as const
+export const schemaVersion = 2 as const
 
 /**
  * Source module and export that produced a machine.
@@ -216,6 +216,58 @@ 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.
+ *
+ * @category schemas
+ * @since 0.24.0
+ */
+export const EventInput = Schema.Struct({
+  event: Schema.String,
+  schema: InputSchema
+})
+
+/**
+ * @category models
+ * @since 0.24.0
+ */
+export type EventInput = Schema.Schema.Type<typeof EventInput>
+
+/**
+ * Machine and public event inputs available to devtools forms.
+ *
+ * @category schemas
+ * @since 0.24.0
+ */
+export const Inputs = Schema.Struct({
+  machine: Schema.NullOr(InputSchema),
+  events: Schema.Array(EventInput)
+})
+
+/**
+ * @category models
+ * @since 0.24.0
+ */
+export type Inputs = Schema.Schema.Type<typeof Inputs>
+
 /**
  * Complete, versioned, JSON-safe machine inspection document.
  *
@@ -232,6 +284,7 @@ export const MachineDocument = Schema.Struct({
   states: Schema.Array(State),
   transitions: Schema.Array(Transition),
   activities: Schema.Array(Activity),
+  inputs: Inputs,
   snapshot: Schema.NullOr(Snapshot)
 })
 

package/src/ProjectInspector.ts

@@ -92,6 +92,11 @@ 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") {}
 
 /**