@typeonce/effect-machine 0.7.0 → 0.9.0

package/src/internal/machine/planner.ts

@@ -18,7 +18,6 @@ import {
   configurationFromHistoryRecord,
   getActiveLeafPathFrom,
   getActiveLeafPaths,
-  getActiveValue,
   getHistoryRecord,
   getInitialEntryPaths,
   getLeafPath,
@@ -39,6 +38,7 @@ import {
   validateInitialConfiguration
 } from "./configuration.js"
 import { InfiniteTransitionError, MachineSchemaDecodeError, StartupError } from "./errors.js"
+import * as InvocationEvent from "./invocationEvent.js"
 import { decodeEventSync, decodeInputSync, decodeStateValueSync } from "./protocol.js"
 import { InitialEventTypeId } from "./symbols.js"
 import {
@@ -201,66 +201,76 @@ const completeHistoryConfiguration = (
         if (node.initial === undefined) {
           throw new Error(`Machine shallow history expected compound state "${path}" to have an initial child`)
         }
-        const initializer = machine.handlers[path]?.initial
-        if (initializer === undefined) {
-          throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
-        }
+        const child = getNode(machine, node.initial)
         const current = {
           active,
           values,
           outputs: configuration.outputs,
           history: configuration.history
         } as ActiveConfiguration
-        const initialized = collectStateInitializer(machine, initializer, {
-          state: getActiveValue(current, path),
-          parent: getParentValue(machine, current, path),
-          parents: getParentValues(machine, current, path),
-          event
-        })
-        const child = getNode(machine, node.initial)
         active.add(child.path)
-        values.set(child.path, decodeStateValueSync(machine, child, initialized.value))
-        commands.push(...initialized.commands)
-        raisedEvents.push(...initialized.raisedEvents)
-        emittedEvents.push(...initialized.emittedEvents)
+        if (child.schema !== undefined) {
+          const initializer = machine.handlers[path]?.initial
+          if (initializer === undefined) {
+            throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
+          }
+          const initialized = collectStateInitializer(machine, initializer, {
+            state: current.values.get(path),
+            parent: getParentValue(machine, current, path),
+            parents: getParentValues(machine, current, path),
+            event
+          })
+          values.set(child.path, decodeStateValueSync(machine, child, initialized.value))
+          commands.push(...initialized.commands)
+          raisedEvents.push(...initialized.raisedEvents)
+          emittedEvents.push(...initialized.emittedEvents)
+        }
         changed = true
       }
       if (node.type === "parallel") {
         const missing = node.children.filter((childPath) => !active.has(childPath))
         if (missing.length > 0) {
-          const initializer = machine.handlers[path]?.initial
-          if (initializer === undefined) {
-            throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
-          }
+          const valuedMissing = missing.filter((childPath) => getNode(machine, childPath).schema !== undefined)
           const current = {
             active,
             values,
             outputs: configuration.outputs,
             history: configuration.history
           } as ActiveConfiguration
-          const initialized = collectStateInitializer(machine, initializer, {
-            state: getActiveValue(current, path),
+          const initializer = valuedMissing.length === 0 ? undefined : machine.handlers[path]?.initial
+          if (valuedMissing.length > 0 && initializer === undefined) {
+            throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
+          }
+          const initialized = initializer === undefined ? undefined : collectStateInitializer(machine, initializer, {
+            state: current.values.get(path),
             parent: getParentValue(machine, current, path),
             parents: getParentValues(machine, current, path),
             event
           })
-          if (typeof initialized.value !== "object" || initialized.value === null) {
+          if (initialized !== undefined && (typeof initialized.value !== "object" || initialized.value === null)) {
             throw new Error(`Machine parallel state initializer for "${path}" must return its region values`)
           }
           for (const childPath of missing) {
             const child = getNode(machine, childPath)
-            if (!Object.prototype.hasOwnProperty.call(initialized.value, child.key)) {
-              throw new Error(`Machine parallel state initializer for "${path}" must return region "${child.key}"`)
-            }
             active.add(child.path)
-            values.set(
-              child.path,
-              decodeStateValueSync(machine, child, (initialized.value as Record<string, unknown>)[child.key])
-            )
+            if (child.schema !== undefined) {
+              if (
+                initialized === undefined ||
+                !Object.prototype.hasOwnProperty.call(initialized.value as object, child.key)
+              ) {
+                throw new Error(`Machine parallel state initializer for "${path}" must return region "${child.key}"`)
+              }
+              values.set(
+                child.path,
+                decodeStateValueSync(machine, child, (initialized.value as Record<string, unknown>)[child.key])
+              )
+            }
+          }
+          if (initialized !== undefined) {
+            commands.push(...initialized.commands)
+            raisedEvents.push(...initialized.raisedEvents)
+            emittedEvents.push(...initialized.emittedEvents)
           }
-          commands.push(...initialized.commands)
-          raisedEvents.push(...initialized.raisedEvents)
-          emittedEvents.push(...initialized.emittedEvents)
           changed = true
         }
       }
@@ -495,7 +505,7 @@ const makeStateActionContext = <
   path: string,
   event: Machine.LifecycleEvent<Events>
 ): Machine.StateActionContext<States, Events, Emits, StateId> => ({
-  state: getActiveValue(configuration, path) as Machine.StateByIdentifier<States, StateId>,
+  state: configuration.values.get(path) as Machine.StateByIdentifier<States, StateId>,
   parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
   parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
   event
@@ -514,7 +524,7 @@ const makeTransitionContext = <
   event: Machine.EventByTag<Events, EventTag>,
   snapshot: Machine.Snapshot<States>
 ): Machine.HandlerContext<States, Events, Emits, StateId, EventTag, any, any> => ({
-  state: getActiveValue(configuration, path) as Machine.StateByIdentifier<States, StateId>,
+  state: configuration.values.get(path) as Machine.StateByIdentifier<States, StateId>,
   parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
   parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
   event,
@@ -535,7 +545,7 @@ const makeDoneContext = <
   output: unknown,
   snapshot: Machine.Snapshot<States>
 ): Machine.DoneContext<States, Events, Emits, StateId> => ({
-  state: getActiveValue(configuration, path) as Machine.StateByIdentifier<States, StateId>,
+  state: configuration.values.get(path) as Machine.StateByIdentifier<States, StateId>,
   parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
   parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
   event,
@@ -629,7 +639,7 @@ const selectAlwaysTransitions = <
               Machine.AlwaysContext<States, Events, Emits, Machine.StateIdentifier<States>>
             >,
             context: {
-              state: getActiveValue(configuration, path) as Machine.StateByIdentifier<
+              state: configuration.values.get(path) as Machine.StateByIdentifier<
                 States,
                 Machine.StateIdentifier<States>
               >,
@@ -789,6 +799,54 @@ const selectEventTransitions = <
   return selected
 }
 
+const selectInvocationTransition = <
+  const States extends Machine.StateSchemas,
+  const Events extends ReadonlyArray<Machine.TaggedSchema>,
+  const Emits extends ReadonlyArray<Machine.TaggedSchema>,
+  E,
+  R
+>(
+  machine: Machine.Any,
+  configuration: ActiveConfiguration,
+  event: InvocationEvent.InvocationEvent
+): ReadonlyArray<SelectedTransition<States, E, R, any>> => {
+  if (!configuration.active.has(event.path)) return []
+  const config = machine.handlers[event.path] as Machine.AnyStateConfig | undefined
+  const invoke = InvocationEvent.definitions(config?.invoke).find((definition) => {
+    const id = "child" in definition ? definition.child?.id : definition.id
+    return String(id) === event.id
+  })
+  if (invoke === undefined) return []
+  const handler = event.type === "done"
+    ? invoke.onDone
+    : event.type === "failure"
+    ? invoke.onFailure
+    : invoke.onSnapshot
+  const transition = normalizeTransition(handler)
+  if (transition === undefined) return []
+  const snapshot = snapshotFromConfiguration<States>(machine, configuration)
+  const context = {
+    state: configuration.values.get(event.path),
+    parent: getParentValue(machine, configuration, event.path),
+    parents: getParentValues(machine, configuration, event.path),
+    snapshot,
+    target: getTargetBuilder(machine, event.path),
+    id: event.id,
+    ...(event.type === "done"
+      ? { output: event.output }
+      : event.type === "failure"
+      ? { error: event.error }
+      : { snapshot: event.snapshot })
+  }
+  return [{
+    sourcePath: event.path,
+    leafPath: getActiveLeafPathFrom(machine, configuration, event.path),
+    trigger: { type: "invoke", id: event.id, outcome: event.type },
+    transition: transition as unknown as MicrostepTransition<States, E, R, any>,
+    context
+  }]
+}
+
 export const getTargetNodePath = <const States extends Machine.StateSchemas>(
   target:
     | Machine.Snapshot<States>
@@ -919,7 +977,9 @@ const choicesFromTarget = (
       return
     }
     if (typeof current !== "object" || current === null || !("path" in current) || !("value" in current)) return
-    values[String(current.path)] = current.value
+    if (current.value !== undefined) {
+      values[String(current.path)] = current.value
+    }
     if ("state" in current) visit(current.state)
     if ("states" in current && typeof current.states === "object" && current.states !== null) {
       for (const state of Object.values(current.states)) visit(state)
@@ -1801,11 +1861,11 @@ const macrostepConfiguration = <
 >(
   machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>,
   configuration: ActiveConfiguration,
-  event: Machine.EventOf<Events>
+  event: Machine.EventOf<Events> | InvocationEvent.InvocationEvent
 ) => {
-  const decodedEvent = decodeEventSync<Events>(machine, event)
+  const decodedEvent = InvocationEvent.isInvocationEvent(event) ? event : decodeEventSync<Events>(machine, event)
   if (isActiveFinalConfiguration(machine, configuration)) {
-    const completed = completeConfigurationSync(machine, configuration, decodedEvent)
+    const completed = completeConfigurationSync(machine, configuration, decodedEvent as any)
     const root = getRootPath(machine, completed.configuration)
     if (!completed.configuration.outputs.has(root)) {
       throw new Error("Machine reached a terminal configuration without a completed root output")
@@ -1820,11 +1880,13 @@ const macrostepConfiguration = <
     }
   }
 
-  const selections = selectEventTransitions<States, Events, Emits, E, R>(
-    machine,
-    configuration,
-    decodedEvent as Machine.EventByTag<Events, Machine.TagOf<Events[number]>>
-  )
+  const selections = InvocationEvent.isInvocationEvent(decodedEvent)
+    ? selectInvocationTransition<States, Events, Emits, E, R>(machine, configuration, decodedEvent)
+    : selectEventTransitions<States, Events, Emits, E, R>(
+      machine,
+      configuration,
+      decodedEvent as Machine.EventByTag<Events, Machine.TagOf<Events[number]>>
+    )
   if (selections.length === 0) {
     return {
       next: configuration,
@@ -1838,14 +1900,14 @@ const macrostepConfiguration = <
   const step = microstep(
     machine,
     configuration,
-    decodedEvent,
+    decodedEvent as any,
     selections
   )
   const commands = [...step.commands]
   const raisedEvents = [...step.raisedEvents]
   const emittedEvents = [...step.emittedEvents]
   const microsteps = [step]
-  return settle(machine, step.next, decodedEvent, commands, raisedEvents, emittedEvents, microsteps)
+  return settle(machine, step.next, decodedEvent as any, commands, raisedEvents, emittedEvents, microsteps)
 }
 
 const snapshotMacrostep = <

package/src/internal/machine/protocol.ts

@@ -9,6 +9,7 @@ import * as Effect from "effect/Effect"
 import { hasProperty } from "effect/Predicate"
 import * as Result from "effect/Result"
 import * as Schema from "effect/Schema"
+import * as SchemaAST from "effect/SchemaAST"
 import type { Machine } from "../../Machine.js"
 import { MachineSchemaDecodeError } from "./errors.js"
 import { getStateNodeSchema, isStateInput } from "./topology.js"
@@ -26,6 +27,15 @@ interface MachineProtocolSchemas {
   readonly trustedEvents: WeakSet<object>
 }
 
+export const EventConstructionTypeId: unique symbol = Symbol("effect/Machine/EventConstruction")
+
+interface EventConstruction {
+  readonly [EventConstructionTypeId]: typeof EventConstructionTypeId
+  readonly _tag: PropertyKey
+  readonly schema: Machine.TaggedSchema
+  readonly input: unknown
+}
+
 type BoundaryDecoder = (value: unknown) => Effect.Effect<unknown, Schema.SchemaError, unknown>
 
 type BoundaryResultDecoder = (value: unknown) => Result.Result<unknown, Schema.SchemaError>
@@ -111,6 +121,88 @@ export const copyProtocol = (source: Machine.Any, target: Machine.Any): void =>
 export const getEventName = (event: unknown): string | undefined =>
   hasProperty(event, "_tag") ? String(event._tag) : undefined
 
+const makeEventConstruction = (
+  schema: Machine.TaggedSchema,
+  tag: PropertyKey,
+  input: unknown
+): EventConstruction => ({
+  [EventConstructionTypeId]: EventConstructionTypeId,
+  _tag: tag,
+  schema,
+  input
+})
+
+const isEventConstruction = (value: unknown): value is EventConstruction => hasProperty(value, EventConstructionTypeId)
+
+export const eventConstructors = (
+  schemas: ReadonlyArray<Machine.TaggedSchema>
+): Readonly<Record<PropertyKey, (...args: ReadonlyArray<unknown>) => EventConstruction>> => {
+  const leaves: Array<Machine.TaggedSchema> = []
+  const collect = (schema: Machine.TaggedSchema): void => {
+    if (hasProperty(schema, "cases") && typeof schema.cases === "object" && schema.cases !== null) {
+      for (const candidate of Reflect.ownKeys(schema.cases)) {
+        collect(Reflect.get(schema.cases, candidate) as Machine.TaggedSchema)
+      }
+      return
+    }
+    if (hasProperty(schema, "members") && Array.isArray(schema.members)) {
+      for (const member of schema.members) collect(member as Machine.TaggedSchema)
+      return
+    }
+    leaves.push(schema)
+  }
+  for (const schema of schemas) collect(schema)
+  const constructors = Object.create(null) as Record<
+    PropertyKey,
+    (...args: ReadonlyArray<unknown>) => EventConstruction
+  >
+  const tags = (ast: SchemaAST.AST): ReadonlyArray<PropertyKey> => {
+    if (SchemaAST.isLiteral(ast)) {
+      return typeof ast.literal === "string" || typeof ast.literal === "number" ? [ast.literal] : []
+    }
+    if (SchemaAST.isUniqueSymbol(ast)) return [ast.symbol]
+    if (SchemaAST.isEnum(ast)) return ast.enums.map(([, value]) => value)
+    if (SchemaAST.isUnion(ast)) return ast.types.flatMap(tags)
+    if (SchemaAST.isSuspend(ast)) return tags(ast.thunk())
+    return []
+  }
+  const schemaTags = (schema: Machine.TaggedSchema): ReadonlyArray<PropertyKey> => {
+    const ast = SchemaAST.toType(schema.ast)
+    if (SchemaAST.isObjects(ast)) {
+      const tag = ast.propertySignatures.find(({ name }) => name === "_tag")
+      const discriminants = tag === undefined ? [] : tags(tag.type)
+      if (discriminants.length > 0) return discriminants
+    }
+    try {
+      return Schema.Union([schema]).pipe(Schema.toTaggedUnion("_tag")).discriminants
+    } catch {
+      return []
+    }
+  }
+  for (const schema of leaves) {
+    const discriminants = schemaTags(schema)
+    if (discriminants.length === 0) {
+      throw new Error("Machine event constructors require finite literal or unique symbol event tags")
+    }
+    for (const tag of discriminants) {
+      if (hasProperty(constructors, tag)) {
+        throw new Error(`Duplicate machine event constructor tag: ${String(tag)}`)
+      }
+      Object.defineProperty(constructors, tag, {
+        value: (...args: ReadonlyArray<unknown>) => {
+          const fields = args.length === 0 ? {} : args[0]
+          const input = typeof fields === "object" && fields !== null
+            ? { ...fields, _tag: tag }
+            : { _tag: tag }
+          return makeEventConstruction(schema, tag, input)
+        },
+        enumerable: true
+      })
+    }
+  }
+  return constructors
+}
+
 export const decodeBoundary = <A>(
   machine: Machine.Any,
   schema: Schema.Top,
@@ -195,6 +287,54 @@ export const makeEvent = <Schema extends Machine.TaggedSchema>(
   return event
 }
 
+const eventConstructionProtocolError = (
+  machine: Machine.Any,
+  construction: EventConstruction
+): MachineSchemaDecodeError =>
+  new MachineSchemaDecodeError({
+    machineId: machine.id,
+    boundary: "event",
+    event: String(construction._tag),
+    cause: Cause.die(new Error("Constructed event schema does not belong to the machine event protocol"))
+  })
+
+const decodeEventConstruction = (
+  machine: Machine.Any,
+  protocol: MachineProtocolSchemas,
+  construction: EventConstruction
+): Effect.Effect<unknown, MachineSchemaDecodeError> => {
+  if (!protocol.eventConstructors.has(construction.schema as object)) {
+    return Effect.fail(eventConstructionProtocolError(machine, construction))
+  }
+  return construction.schema.makeEffect(construction.input as never).pipe(
+    Effect.mapError((cause) =>
+      new MachineSchemaDecodeError({
+        machineId: machine.id,
+        boundary: "event",
+        event: String(construction._tag),
+        cause: new Schema.SchemaError(cause)
+      })
+    ),
+    Effect.tap((event) => Effect.sync(() => protocol.trustedEvents.add(event as object)))
+  )
+}
+
+const decodeEventConstructionSync = (
+  machine: Machine.Any,
+  protocol: MachineProtocolSchemas,
+  construction: EventConstruction
+): unknown => {
+  if (!protocol.eventConstructors.has(construction.schema as object)) {
+    throw eventConstructionProtocolError(machine, construction)
+  }
+  const event = makeBoundarySync(machine, construction.schema, construction.input, {
+    boundary: "event",
+    event: String(construction._tag)
+  })
+  protocol.trustedEvents.add(event as object)
+  return event
+}
+
 const isTrustedEvent = (protocol: MachineProtocolSchemas, event: unknown): boolean =>
   typeof event === "object" && event !== null && protocol.trustedEvents.has(event)
 
@@ -210,6 +350,12 @@ export const decodeEvent = <const Events extends ReadonlyArray<Machine.TaggedSch
   event: unknown
 ): Effect.Effect<Machine.EventOf<Events>, MachineSchemaDecodeError> => {
   const protocol = getProtocolSchemas(machine)
+  if (isEventConstruction(event)) {
+    return decodeEventConstruction(machine, protocol, event) as Effect.Effect<
+      Machine.EventOf<Events>,
+      MachineSchemaDecodeError
+    >
+  }
   if (isTrustedEvent(protocol, event)) {
     return Effect.succeed(event as Machine.EventOf<Events>)
   }
@@ -227,6 +373,9 @@ export const decodeEventSync = <const Events extends ReadonlyArray<Machine.Tagge
   event: unknown
 ): Machine.EventOf<Events> => {
   const protocol = getProtocolSchemas(machine)
+  if (isEventConstruction(event)) {
+    return decodeEventConstructionSync(machine, protocol, event) as Machine.EventOf<Events>
+  }
   if (isTrustedEvent(protocol, event)) {
     return event as Machine.EventOf<Events>
   }

package/src/internal/machine/serialization.ts

@@ -31,7 +31,7 @@ const EncodedSnapshotSchema = Schema.Struct({
   _tag: Schema.Literal("MachineSnapshot"),
   active: Schema.Array(Schema.Struct({
     path: Schema.String,
-    value: Schema.Unknown
+    value: Schema.optional(Schema.Unknown)
   })),
   completed: Schema.optional(Schema.Array(Schema.Struct({
     path: Schema.String,
@@ -220,13 +220,17 @@ export const encodeSnapshot = (
       const path of Array.from(configuration.active).sort((left, right) => compareDocumentOrder(machine, left, right))
     ) {
       const node = getNode(machine, path)
-      active.push({
-        path,
-        value: yield* encodeBoundary(machine, getStateNodeSchema(node), getActiveValue(configuration, path), {
-          boundary: "state",
-          state: path
+      if (node.schema === undefined) {
+        active.push({ path })
+      } else {
+        active.push({
+          path,
+          value: yield* encodeBoundary(machine, getStateNodeSchema(node), getActiveValue(configuration, path), {
+            boundary: "state",
+            state: path
+          })
         })
-      })
+      }
     }
 
     const completed: Array<Machine.EncodedSnapshotCompletion> = []
@@ -290,7 +294,6 @@ export const encodeSnapshot = (
         const stateNode = machine.stateNodes.byPath.get(path)
         if (
           stateNode === undefined || stateNode.type === "history" || stateNode.type === "choice" ||
-          !record.values.has(path) ||
           !(isPathInSubtree(path, record.parent) || getPathToRoot(machine, record.parent).includes(path))
         ) {
           return yield* Effect.fail(
@@ -302,14 +305,23 @@ export const encodeSnapshot = (
             })
           )
         }
-        encodedValues[path] = yield* encodeBoundary(
-          machine,
-          getStateNodeSchema(stateNode),
-          record.values.get(path),
-          { boundary: "history", state: path }
-        )
+        if (stateNode.schema === undefined) {
+          if (record.values.has(path)) {
+            throw new Error(`Machine history record contains a value for structural state "${path}"`)
+          }
+        } else {
+          if (!record.values.has(path)) {
+            throw new Error(`Machine history record omits value for "${path}"`)
+          }
+          encodedValues[path] = yield* encodeBoundary(
+            machine,
+            getStateNodeSchema(stateNode),
+            record.values.get(path),
+            { boundary: "history", state: path }
+          )
+        }
       }
-      if (record.values.size !== record.active.size) {
+      if (Object.keys(encodedValues).length !== record.values.size) {
         return yield* Effect.fail(
           new MachineSchemaEncodeError({
             machineId: machine.id,
@@ -356,13 +368,19 @@ export const decodeSnapshot = (
       }
       const node = getNode(machine, entry.path)
       active.add(entry.path)
-      values.set(
-        entry.path,
-        yield* decodeEncodedBoundary(machine, getStateNodeSchema(node), entry.value, {
-          boundary: "state",
-          state: entry.path
-        })
-      )
+      const hasValue = Object.prototype.hasOwnProperty.call(entry, "value")
+      if (node.schema === undefined) {
+        if (hasValue) throw new Error(`Machine encoded snapshot contains a value for structural state "${entry.path}"`)
+      } else {
+        if (!hasValue) throw new Error(`Machine encoded snapshot omits value for state "${entry.path}"`)
+        values.set(
+          entry.path,
+          yield* decodeEncodedBoundary(machine, getStateNodeSchema(node), entry.value, {
+            boundary: "state",
+            state: entry.path
+          })
+        )
+      }
     }
 
     const history = new Map<string, HistoryRecord>()
@@ -397,7 +415,6 @@ export const decodeSnapshot = (
         const stateNode = machine.stateNodes.byPath.get(path)
         if (
           stateNode === undefined || stateNode.type === "history" || stateNode.type === "choice" ||
-          !Object.prototype.hasOwnProperty.call(encodedRecord.values, path) ||
           !(isPathInSubtree(path, historyNode.parent) || getPathToRoot(machine, historyNode.parent).includes(path))
         ) {
           return yield* Effect.fail(
@@ -410,15 +427,23 @@ export const decodeSnapshot = (
           )
         }
         rememberedActive.add(path)
-        rememberedValues.set(
-          path,
-          yield* decodeEncodedBoundary(machine, getStateNodeSchema(stateNode), encodedRecord.values[path], {
-            boundary: "history",
-            state: path
-          })
-        )
+        const hasValue = Object.prototype.hasOwnProperty.call(encodedRecord.values, path)
+        if (stateNode.schema === undefined) {
+          if (hasValue) {
+            throw new Error(`Machine encoded history contains a value for structural state "${path}"`)
+          }
+        } else {
+          if (!hasValue) throw new Error(`Machine encoded history omits value for state "${path}"`)
+          rememberedValues.set(
+            path,
+            yield* decodeEncodedBoundary(machine, getStateNodeSchema(stateNode), encodedRecord.values[path], {
+              boundary: "history",
+              state: path
+            })
+          )
+        }
       }
-      if (Object.keys(encodedRecord.values).length !== rememberedActive.size) {
+      if (Object.keys(encodedRecord.values).length !== rememberedValues.size) {
         return yield* Effect.fail(
           new MachineSchemaDecodeError({
             machineId: machine.id,

package/src/internal/machine/stateDefinition.ts

@@ -2,10 +2,10 @@ import * as Schema from "effect/Schema"
 import * as SchemaAST from "effect/SchemaAST"
 
 export const StateNodePropertyPolicy = {
-  atomic: ["schema", "type"],
-  final: ["schema", "type", "output"],
-  compound: ["schema", "type", "initial", "states"],
-  parallel: ["schema", "type", "output", "states"],
+  atomic: ["schema", "type", "annotations"],
+  final: ["schema", "type", "output", "annotations"],
+  compound: ["schema", "type", "initial", "states", "annotations"],
+  parallel: ["schema", "type", "output", "states", "annotations"],
   history: ["type", "history", "annotations"],
   choice: ["type", "annotations"]
 } as const
@@ -152,18 +152,22 @@ const assertAllowedProperties = (
   }
 }
 
-const validatePseudoAnnotations = (
+const validateSchemaLessAnnotations = (
   boundary: StateDefinitionBoundary,
   path: string,
   annotations: unknown
 ): void => {
-  assertPlainRecord(boundary, `${path}.annotations`, annotations, "pseudo-state annotations")
+  assertPlainRecord(boundary, `${path}.annotations`, annotations, "schema-less state annotations")
   for (const property of Reflect.ownKeys(annotations)) {
     if (!(PseudoStateAnnotationProperties as ReadonlyArray<PropertyKey>).includes(property)) {
-      fail(boundary, `${path}.annotations`, `pseudo-state annotations cannot declare property "${String(property)}"`)
+      fail(
+        boundary,
+        `${path}.annotations`,
+        `schema-less state annotations cannot declare property "${String(property)}"`
+      )
     }
     if (typeof annotations[property] !== "string") {
-      fail(boundary, `${path}.annotations.${String(property)}`, "pseudo-state annotation values must be strings")
+      fail(boundary, `${path}.annotations.${String(property)}`, "schema-less state annotation values must be strings")
     }
   }
 }
@@ -211,7 +215,7 @@ const validateStateTree = (
         fail(boundary, path, `${kind} states must be declared below an active parent state`)
       }
       if (hasOwn(node, "annotations")) {
-        validatePseudoAnnotations(boundary, path, node.annotations)
+        validateSchemaLessAnnotations(boundary, path, node.annotations)
       }
       if (kind === "history" && hasOwn(node, "history") && node.history !== "shallow" && node.history !== "deep") {
         fail(boundary, `${path}.history`, "history must be \"shallow\" or \"deep\"")
@@ -219,8 +223,15 @@ const validateStateTree = (
       continue
     }
 
-    if (!hasOwn(node, "schema") || !isTaggedSchema(node.schema)) {
-      fail(boundary, `${path}.schema`, "active states must declare an Effect Schema with a required PropertyKey _tag")
+    const valued = hasOwn(node, "schema")
+    if (valued && !isTaggedSchema(node.schema)) {
+      fail(boundary, `${path}.schema`, "state schemas must decode to an object with a required PropertyKey _tag")
+    }
+    if (valued && hasOwn(node, "annotations")) {
+      fail(boundary, `${path}.annotations`, "schema-backed states must declare annotations on their schema")
+    }
+    if (!valued && hasOwn(node, "annotations")) {
+      validateSchemaLessAnnotations(boundary, path, node.annotations)
     }
     if (kind === "atomic" && hasOwn(node, "type") && node.type !== "active") {
       fail(boundary, `${path}.type`, "atomic state type must be \"active\"")