@typeonce/effect-machine 0.1.0 → 0.3.0

package/dist/internal/machineModel.js

@@ -10,7 +10,169 @@ import { hasProperty } from "effect/Predicate";
 import * as Schema from "effect/Schema";
 import { MachineSchemaDecodeError, MachineSchemaEncodeError } from "./machineErrors.js";
 export const TargetTypeId = "~effect/Machine/Target";
+export const TargetSnapshotTypeId = Symbol("effect/Machine/TargetSnapshot");
+export const StateInputTypeId = Symbol("effect/Machine/StateInput");
+export const StateConstructionTypeId = Symbol("effect/Machine/StateConstruction");
+export const HistoryTargetTypeId = Symbol("effect/Machine/HistoryTarget");
+const validateHistoryRecordControl = (machine, record) => {
+    const ancestry = new Set(getPathToRoot(machine, record.parent));
+    const visit = (path) => {
+        const node = getNode(machine, path);
+        if (node.type === "compound") {
+            const children = node.children.filter((child) => record.active.has(child));
+            if (children.length !== 1) {
+                throw new Error(`Machine history expected compound state "${path}" to retain one active child`);
+            }
+            if (record.mode === "deep")
+                visit(children[0]);
+            return;
+        }
+        if (node.type === "parallel") {
+            for (const child of node.children) {
+                if (!record.active.has(child)) {
+                    throw new Error(`Machine history expected parallel state "${path}" to retain region "${child}"`);
+                }
+                if (record.mode === "deep")
+                    visit(child);
+            }
+        }
+    };
+    visit(record.parent);
+    for (const path of record.active) {
+        if (!ancestry.has(path) && !isPathInSubtree(path, record.parent)) {
+            throw new Error(`Machine history contains state "${path}" outside parent "${record.parent}"`);
+        }
+        if (record.mode === "shallow" && isDescendantOf(path, record.parent) &&
+            getNode(machine, path).parent !== record.parent) {
+            throw new Error(`Machine shallow history contains deep descendant "${path}"`);
+        }
+    }
+};
+const historyFromSnapshot = (machine, snapshot) => {
+    const history = new Map();
+    for (const [path, entry] of Object.entries(snapshot.history ?? {})) {
+        const historyNode = getNode(machine, path);
+        if (historyNode.type !== "history" || historyNode.parent === undefined || historyNode.history !== entry.mode) {
+            throw new Error(`Machine snapshot contains invalid history record "${path}"`);
+        }
+        const active = new Set();
+        const values = new Map();
+        for (const activePath of entry.active) {
+            if (active.has(activePath) || !Object.prototype.hasOwnProperty.call(entry.values, activePath)) {
+                throw new Error(`Machine snapshot contains invalid remembered state "${activePath}"`);
+            }
+            const node = getNode(machine, activePath);
+            if (node.type === "history" ||
+                !(isPathInSubtree(activePath, historyNode.parent) ||
+                    getPathToRoot(machine, historyNode.parent).includes(activePath)) ||
+                !Schema.is(getStateNodeSchema(node))(entry.values[activePath])) {
+                throw new Error(`Machine snapshot contains invalid remembered value for "${activePath}"`);
+            }
+            active.add(activePath);
+            values.set(activePath, entry.values[activePath]);
+        }
+        if (!active.has(historyNode.parent) || Object.keys(entry.values).length !== active.size) {
+            throw new Error(`Machine snapshot contains incomplete history record "${path}"`);
+        }
+        history.set(path, {
+            mode: entry.mode,
+            parent: historyNode.parent,
+            active,
+            values
+        });
+        validateHistoryRecordControl(machine, history.get(path));
+    }
+    return history;
+};
+const historyFromSnapshotEffect = Effect.fnUntraced(function* (machine, snapshot) {
+    const history = new Map();
+    for (const [path, entry] of Object.entries(snapshot.history ?? {})) {
+        const historyNode = machine.stateNodes.byPath.get(path);
+        if (historyNode === undefined || historyNode.type !== "history" || historyNode.parent === undefined ||
+            historyNode.history !== entry.mode) {
+            return yield* Effect.fail(new MachineSchemaDecodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: path,
+                cause: Cause.die(new Error(`Machine snapshot contains invalid history record "${path}"`))
+            }));
+        }
+        const active = new Set();
+        const values = new Map();
+        for (const activePath of entry.active) {
+            const node = machine.stateNodes.byPath.get(activePath);
+            if (active.has(activePath) || node === undefined || node.type === "history" ||
+                !Object.prototype.hasOwnProperty.call(entry.values, activePath) ||
+                !(isPathInSubtree(activePath, historyNode.parent) ||
+                    getPathToRoot(machine, historyNode.parent).includes(activePath))) {
+                return yield* Effect.fail(new MachineSchemaDecodeError({
+                    machineId: machine.id,
+                    boundary: "history",
+                    state: activePath,
+                    cause: Cause.die(new Error(`Machine snapshot contains invalid remembered state "${activePath}"`))
+                }));
+            }
+            active.add(activePath);
+            values.set(activePath, yield* decodeBoundary(machine, getStateNodeSchema(node), entry.values[activePath], {
+                boundary: "history",
+                state: activePath
+            }));
+        }
+        if (!active.has(historyNode.parent) || Object.keys(entry.values).length !== active.size) {
+            return yield* Effect.fail(new MachineSchemaDecodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: path,
+                cause: Cause.die(new Error(`Machine snapshot contains incomplete history record "${path}"`))
+            }));
+        }
+        history.set(path, {
+            mode: entry.mode,
+            parent: historyNode.parent,
+            active,
+            values
+        });
+        try {
+            validateHistoryRecordControl(machine, history.get(path));
+        }
+        catch (cause) {
+            return yield* Effect.fail(new MachineSchemaDecodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: path,
+                cause: Cause.die(cause)
+            }));
+        }
+    }
+    return history;
+});
+const historyToSnapshot = (history) => {
+    const entries = {};
+    for (const [path, record] of history) {
+        entries[path] = {
+            mode: record.mode,
+            active: Array.from(record.active),
+            values: Object.fromEntries(record.values)
+        };
+    }
+    return entries;
+};
+export const makeHistoryTarget = (path, parent) => ({
+    [HistoryTargetTypeId]: HistoryTargetTypeId,
+    path,
+    parent
+});
+export const isHistoryTarget = (u) => hasProperty(u, HistoryTargetTypeId);
 export const getStateNodeDefinition = (path, definition) => {
+    if (!Schema.isSchema(definition) && definition.type === "history") {
+        return {
+            schema: undefined,
+            output: undefined,
+            type: "history",
+            initial: undefined,
+            states: undefined
+        };
+    }
     if (Schema.isSchema(definition)) {
         return {
             schema: definition,
@@ -78,11 +240,20 @@ export const compileStateNodes = (states) => {
                 parent,
                 children: [],
                 initial: definition.initial === undefined ? undefined : `${path}.${definition.initial}`,
+                history: definition.type === "history"
+                    ? (tree[key].history === "deep" ? "deep" : "shallow")
+                    : undefined,
                 order
             };
             byPath.set(path, node);
-            paths.push(path);
             order += 1;
+            if (definition.type === "history") {
+                if (parent === undefined) {
+                    throw new Error(`Machine history state "${path}" must belong to a parent state`);
+                }
+                continue;
+            }
+            paths.push(path);
             if (definition.states !== undefined) {
                 const children = compile(definition.states, path);
                 if (node.type === "compound" && (node.initial === undefined || !children.includes(node.initial))) {
@@ -101,32 +272,99 @@ export const compileStateNodes = (states) => {
 };
 export const makeTarget = (path, value, options) => ({
     [TargetTypeId]: TargetTypeId,
+    [TargetSnapshotTypeId]: options?.snapshot,
     path,
     value,
     values: options?.values
 });
 export const isTarget = (u) => hasProperty(u, TargetTypeId);
+export const makeStateInput = (input) => ({
+    [StateInputTypeId]: StateInputTypeId,
+    input
+});
+const isStateInput = (u) => hasProperty(u, StateInputTypeId);
+export const markStateConstruction = (value) => {
+    if ((typeof value === "object" && value !== null) || typeof value === "function") {
+        Object.defineProperty(value, StateConstructionTypeId, {
+            value: StateConstructionTypeId,
+            enumerable: false
+        });
+    }
+    return value;
+};
+export const isStateConstruction = (u) => hasProperty(u, StateConstructionTypeId);
 export const isSnapshot = (u) => hasProperty(u, "path") && hasProperty(u, "value");
+export const getSnapshotByPath = (snapshot, path, parents) => {
+    if (snapshot.path === path) {
+        return Option.some(snapshot);
+    }
+    if (!path.startsWith(`${snapshot.path}.`)) {
+        return Option.none();
+    }
+    if (parents !== undefined) {
+        parents[snapshot.path] = snapshot.value;
+    }
+    if (hasProperty(snapshot, "state") && isSnapshot(snapshot.state)) {
+        return getSnapshotByPath(snapshot.state, path, parents);
+    }
+    if (hasProperty(snapshot, "states") && typeof snapshot.states === "object" && snapshot.states !== null) {
+        for (const child of Object.values(snapshot.states)) {
+            if (isSnapshot(child)) {
+                const result = getSnapshotByPath(child, path, parents);
+                if (Option.isSome(result)) {
+                    return result;
+                }
+            }
+        }
+    }
+    return Option.none();
+};
+const MachineProtocolTypeId = Symbol.for("effect/Machine/protocol");
+const getProtocolSchemas = (machine) => {
+    const protocol = machine[MachineProtocolTypeId];
+    if (protocol === undefined) {
+        throw new Error("Machine protocol is unavailable");
+    }
+    return protocol;
+};
+const setProtocolSchemas = (machine, protocol) => {
+    Object.defineProperty(machine, MachineProtocolTypeId, {
+        value: protocol,
+        enumerable: false
+    });
+};
+export const setProtocol = (machine) => {
+    setProtocolSchemas(machine, {
+        event: Schema.Union([...machine.events, ...machine.internalEvents]),
+        emit: Schema.Union(machine.emits)
+    });
+};
+export const copyProtocol = (source, target) => setProtocolSchemas(target, getProtocolSchemas(source));
 export const getEventName = (event) => hasProperty(event, "_tag") ? String(event._tag) : undefined;
-export const decodeBoundary = Effect.fnUntraced(function* (machine, schema, value, options) {
-    return yield* Schema.decodeUnknownEffect(Schema.toType(schema))(value).pipe(Effect.mapError((cause) => new MachineSchemaDecodeError({
-        machineId: machine.id,
-        boundary: options.boundary,
-        cause,
-        ...(options.state === undefined ? {} : { state: options.state }),
-        ...(options.event === undefined ? {} : { event: options.event })
-    })));
-});
+export const decodeBoundary = (machine, schema, value, options) => Schema.decodeUnknownEffect(Schema.toType(schema))(value).pipe(Effect.mapError((cause) => new MachineSchemaDecodeError({
+    machineId: machine.id,
+    boundary: options.boundary,
+    cause,
+    ...(options.state === undefined ? {} : { state: options.state }),
+    ...(options.event === undefined ? {} : { event: options.event })
+})));
 export const decodeInput = (machine, schema, value) => decodeBoundary(machine, schema, value, { boundary: "input" });
 export const decodeEvent = (machine, event) => {
     const eventName = getEventName(event);
-    return decodeBoundary(machine, Schema.Union(machine.events), event, eventName === undefined ? { boundary: "event" } : { boundary: "event", event: eventName });
+    return decodeBoundary(machine, getProtocolSchemas(machine).event, event, eventName === undefined ? { boundary: "event" } : { boundary: "event", event: eventName });
 };
 export const decodeEmit = (machine, event) => {
     const eventName = getEventName(event);
-    return decodeBoundary(machine, Schema.Union(machine.emits), event, eventName === undefined ? { boundary: "emit" } : { boundary: "emit", event: eventName });
+    return decodeBoundary(machine, getProtocolSchemas(machine).emit, event, eventName === undefined ? { boundary: "emit" } : { boundary: "emit", event: eventName });
 };
-export const decodeStateValue = (machine, node, value) => decodeBoundary(machine, node.schema, value, { boundary: "state", state: node.path });
+export const decodeStateValue = (machine, node, value) => isStateInput(value)
+    ? getStateNodeSchema(node).makeEffect(value.input).pipe(Effect.mapError((cause) => new MachineSchemaDecodeError({
+        machineId: machine.id,
+        boundary: "state",
+        state: node.path,
+        cause
+    })))
+    : decodeBoundary(machine, getStateNodeSchema(node), value, { boundary: "state", state: node.path });
 export const decodeOutputValue = (machine, node, value) => node.output === undefined
     ? Effect.succeed(value)
     : decodeBoundary(machine, node.output, value, { boundary: "output", state: node.path });
@@ -137,6 +375,12 @@ export const getNode = (machine, path) => {
     }
     return node;
 };
+export const getStateNodeSchema = (node) => {
+    if (node.schema === undefined || node.type === "history") {
+        throw new Error(`Machine history state "${node.path}" has no active value schema`);
+    }
+    return node.schema;
+};
 export const hasOwn = (u, key) => Object.prototype.hasOwnProperty.call(u, key);
 export const isDescendantOf = (path, ancestor) => path.startsWith(`${ancestor}.`);
 export const isPathInSubtree = (path, ancestor) => path === ancestor || isDescendantOf(path, ancestor);
@@ -180,7 +424,7 @@ export const getRootPath = (machine, configuration) => {
 };
 export const getActiveValue = (configuration, path) => {
     if (!configuration.values.has(path)) {
-        throw new Error(`Machine expected active state "${path}" to have a value`);
+        throw new Error(`Machine expected active state "${path}" to have a value (available: ${Array.from(configuration.values.keys()).join(", ")})`);
     }
     return configuration.values.get(path);
 };
@@ -193,6 +437,10 @@ export const getParentValues = (machine, configuration, path) => {
     }
     return parents;
 };
+export const getParentValue = (machine, configuration, path) => {
+    const parent = getNode(machine, path).parent;
+    return parent === undefined ? undefined : getActiveValue(configuration, parent);
+};
 export const getInitialEntryPaths = (machine, configuration) => {
     const visit = (path) => {
         if (!configuration.active.has(path)) {
@@ -234,15 +482,25 @@ export const snapshotFromPath = (machine, configuration, path) => {
 };
 export const snapshotFromConfiguration = (machine, configuration) => {
     const snapshot = snapshotFromPath(machine, configuration, getRootPath(machine, configuration));
-    const root = getRootPath(machine, configuration);
-    const retainPartialOutputs = !isActiveFinalNode(machine, configuration, root);
     const completed = Array.from(configuration.outputs)
-        .filter(([path]) => retainPartialOutputs || hasCompletionHandler(machine, path))
         .map(([path, output]) => ({ path, output }));
     if (completed.length > 0) {
         ;
         snapshot.completed = completed;
     }
+    if (configuration.history.size > 0) {
+        Object.assign(snapshot, { history: historyToSnapshot(configuration.history) });
+    }
+    return snapshot;
+};
+/** Creates a targetable subtree snapshot while carrying machine-level history
+ * metadata on that subtree root. This is used when a nested history target
+ * must preserve active ancestors and unaffected parallel regions. */
+export const snapshotFromConfigurationAtPath = (machine, configuration, path) => {
+    const snapshot = snapshotFromPath(machine, configuration, path);
+    if (configuration.history.size > 0) {
+        Object.assign(snapshot, { history: historyToSnapshot(configuration.history) });
+    }
     return snapshot;
 };
 export const configurationFromSnapshot = (machine, snapshot) => {
@@ -251,7 +509,7 @@ export const configurationFromSnapshot = (machine, snapshot) => {
     const snapshotOutputs = snapshot.completed;
     const visit = (current) => {
         const node = getNode(machine, String(current.path));
-        if (!Schema.is(node.schema)(current.value)) {
+        if (!Schema.is(getStateNodeSchema(node))(current.value)) {
             throw new Error(`Machine expected snapshot for "${node.path}" to match its schema`);
         }
         active.add(node.path);
@@ -294,7 +552,7 @@ export const configurationFromSnapshot = (machine, snapshot) => {
             }
         }
     }
-    return { active, values, outputs };
+    return { active, values, outputs, history: historyFromSnapshot(machine, snapshot) };
 };
 export const normalizeConfiguration = (machine, state) => configurationFromSnapshot(machine, state);
 export const configurationFromSnapshotEffect = Effect.fnUntraced(function* (machine, snapshot) {
@@ -344,7 +602,12 @@ export const configurationFromSnapshotEffect = Effect.fnUntraced(function* (mach
             }
         }
     }
-    return { active, values, outputs };
+    return {
+        active,
+        values,
+        outputs,
+        history: yield* historyFromSnapshotEffect(machine, snapshot)
+    };
 });
 export const normalizeConfigurationEffect = (machine, state) => configurationFromSnapshotEffect(machine, state).pipe(Effect.catchCause((cause) => {
     const error = Cause.findErrorOption(cause);
@@ -374,6 +637,85 @@ export const validateInitialConfiguration = (machine, configuration) => {
         }
     }
 };
+/** Capture every history register whose owning parent exits in this microstep.
+ * The control record is deliberately independent from effects/actions: it is
+ * part of the logical snapshot and is therefore preserved by pure planning. */
+export const captureHistory = (machine, current, next, exitPaths) => {
+    if (exitPaths.length === 0) {
+        return next;
+    }
+    const exited = new Set(exitPaths);
+    const history = new Map(next.history);
+    for (const node of machine.stateNodes.byPath.values()) {
+        if (node.type !== "history" || node.parent === undefined || !exited.has(node.parent)) {
+            continue;
+        }
+        const mode = node.history === "deep" ? "deep" : "shallow";
+        const active = new Set();
+        for (const ancestor of getPathToRoot(machine, node.parent)) {
+            if (current.active.has(ancestor)) {
+                active.add(ancestor);
+            }
+        }
+        for (const path of current.active) {
+            if (path === node.parent ||
+                (mode === "deep" && isDescendantOf(path, node.parent)) ||
+                (mode === "shallow" && getNode(machine, path).parent === node.parent)) {
+                active.add(path);
+            }
+        }
+        const values = new Map();
+        for (const path of active) {
+            values.set(path, getActiveValue(current, path));
+        }
+        history.set(node.path, {
+            mode,
+            parent: node.parent,
+            active,
+            values
+        });
+    }
+    return {
+        active: next.active,
+        values: next.values,
+        outputs: next.outputs,
+        history
+    };
+};
+export const getHistoryRecord = (configuration, path) => configuration.history.get(path);
+/** Builds the remembered portion of a configuration. Shallow records are
+ * intentionally incomplete below their direct child; the planner completes
+ * them by invoking only the required typed initializers. */
+export const configurationFromHistoryRecord = (machine, current, record) => {
+    const active = new Set(record.active);
+    const values = new Map(record.values);
+    const outputs = new Map();
+    const ancestors = getPathToRoot(machine, record.parent);
+    const ancestorSet = new Set(ancestors);
+    // A history transition can occur while an ancestor parallel state remains
+    // active. Its unaffected regions retain their current configuration.
+    for (const ancestor of ancestors) {
+        const node = getNode(machine, ancestor);
+        if (node.type !== "parallel") {
+            continue;
+        }
+        for (const child of node.children) {
+            if (ancestorSet.has(child) || record.active.has(child) || !current.active.has(child)) {
+                continue;
+            }
+            for (const path of current.active) {
+                if (isPathInSubtree(path, child)) {
+                    active.add(path);
+                    if (current.values.has(path))
+                        values.set(path, current.values.get(path));
+                    if (current.outputs.has(path))
+                        outputs.set(path, current.outputs.get(path));
+                }
+            }
+        }
+    }
+    return { active, values, outputs, history: current.history };
+};
 export const configurationFromTargetPathEffect = Effect.fnUntraced(function* (machine, current, path, value, providedValues) {
     const node = getNode(machine, path);
     const active = new Set();
@@ -421,20 +763,83 @@ export const configurationFromTargetPathEffect = Effect.fnUntraced(function* (ma
     if (node.type === "compound" || node.type === "parallel") {
         throw new Error(`Machine target "${node.path}" must include an active child state`);
     }
-    return { active, values, outputs };
+    return {
+        active,
+        values,
+        outputs,
+        history: current.history
+    };
+});
+export const configurationFromTargetSnapshotEffect = Effect.fnUntraced(function* (machine, current, snapshot, providedValues) {
+    const subtree = yield* configurationFromSnapshotEffect(machine, snapshot);
+    const active = new Set(subtree.active);
+    const values = new Map(subtree.values);
+    const outputs = new Map(subtree.outputs);
+    const paths = getPathToRoot(machine, String(snapshot.path));
+    const pathSet = new Set(paths);
+    for (const ancestor of paths.slice(0, -1)) {
+        const node = getNode(machine, ancestor);
+        active.add(ancestor);
+        if (providedValues !== undefined && hasOwn(providedValues, ancestor)) {
+            values.set(ancestor, yield* decodeStateValue(machine, node, providedValues[ancestor]));
+        }
+        else if (current.values.has(ancestor)) {
+            values.set(ancestor, current.values.get(ancestor));
+        }
+        else {
+            throw new Error(`Machine target "${snapshot.path}" requires a value for ancestor state "${ancestor}"`);
+        }
+    }
+    for (const ancestor of paths.slice(0, -1)) {
+        const ancestorNode = getNode(machine, ancestor);
+        if (ancestorNode.type === "parallel") {
+            for (const child of ancestorNode.children) {
+                if (pathSet.has(child) || !current.active.has(child)) {
+                    continue;
+                }
+                for (const activePath of current.active) {
+                    if (isPathInSubtree(activePath, child)) {
+                        active.add(activePath);
+                        if (current.values.has(activePath)) {
+                            values.set(activePath, current.values.get(activePath));
+                        }
+                        if (current.outputs.has(activePath)) {
+                            outputs.set(activePath, current.outputs.get(activePath));
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return {
+        active,
+        values,
+        outputs,
+        history: new Map([...current.history, ...subtree.history])
+    };
 });
 export const normalizeTargetConfigurationEffect = (machine, current, target) => {
     if (isTarget(target)) {
+        const snapshot = target[TargetSnapshotTypeId];
+        if (snapshot !== undefined) {
+            if (String(snapshot.path) !== String(target.path)) {
+                throw new Error(`Machine expected target snapshot path to be "${target.path}"`);
+            }
+            return configurationFromTargetSnapshotEffect(machine, current, snapshot, target.values);
+        }
         return configurationFromTargetPathEffect(machine, current, target.path, target.value, target.values);
     }
     if (isSnapshot(target)) {
-        return normalizeConfigurationEffect(machine, target);
+        return normalizeConfigurationEffect(machine, target).pipe(Effect.map((configuration) => ({
+            ...configuration,
+            history: new Map([...current.history, ...configuration.history])
+        })));
     }
     throw new Error("Machine expected transition target to be a snapshot or target builder result");
 };
 export const getStateConfigByPath = (machine, path) => machine.handlers[path];
 export const getActiveChildPath = (machine, configuration, path) => getNode(machine, path).children.find((child) => configuration.active.has(child));
-export const isDirectFinalPath = (machine, path) => getNode(machine, path).type === "final" || getStateConfigByPath(machine, path)?.type === "final";
+export const isDirectFinalPath = (machine, path) => getNode(machine, path).type === "final";
 export const hasCompletionHandler = (machine, path) => getStateConfigByPath(machine, path)?.onDone !== undefined;
 export const isActiveFinalNode = (machine, configuration, path) => {
     if (!configuration.active.has(path)) {
@@ -478,6 +883,7 @@ export const resolveFinalOutputEffect = Effect.fnUntraced(function* (machine, co
     const node = getNode(machine, path);
     const output = getStateConfigByPath(machine, path)?.output?.({
         state: getActiveValue(configuration, path),
+        parent: getParentValue(machine, configuration, path),
         parents: getParentValues(machine, configuration, path),
         event,
         outputs
@@ -488,6 +894,13 @@ export const completeActiveFinalNodeEffect = Effect.fnUntraced(function* (machin
     if (!configuration.active.has(path)) {
         return undefined;
     }
+    if (outputs.has(path)) {
+        return {
+            path,
+            output: outputs.get(path),
+            isNew: false
+        };
+    }
     const node = getNode(machine, path);
     if (node.type === "compound") {
         const child = getActiveChildPath(machine, configuration, path);
@@ -540,7 +953,8 @@ export const completeConfigurationEffect = Effect.fnUntraced(function* (machine,
     const completed = {
         active: configuration.active,
         values: configuration.values,
-        outputs
+        outputs,
+        history: configuration.history
     };
     for (const path of Array.from(completed.active).sort((left, right) => {
         const depth = pathDepth(machine, right) - pathDepth(machine, left);
@@ -559,6 +973,11 @@ const EncodedSnapshotSchema = Schema.Struct({
     completed: Schema.optional(Schema.Array(Schema.Struct({
         path: Schema.String,
         output: Schema.optional(Schema.Unknown)
+    }))),
+    history: Schema.optional(Schema.Record(Schema.String, Schema.Struct({
+        mode: Schema.Literals(["shallow", "deep"]),
+        active: Schema.Array(Schema.String),
+        values: Schema.Record(Schema.String, Schema.Unknown)
     })))
 });
 const encodeBoundary = (machine, schema, value, options) => Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new MachineSchemaEncodeError({
@@ -616,7 +1035,7 @@ const failDecodeCause = (machine, cause) => {
 export const encodeSnapshot = (machine, snapshot) => Effect.gen(function* () {
     const configuration = yield* normalizeConfigurationEffect(machine, snapshot).pipe(Effect.mapError((error) => new MachineSchemaEncodeError({
         machineId: machine.id,
-        boundary: error.boundary === "state" ? "state" : "configuration",
+        boundary: error.boundary === "state" || error.boundary === "history" ? error.boundary : "configuration",
         ...(error.state === undefined ? {} : { state: error.state }),
         cause: error.cause
     })));
@@ -635,7 +1054,7 @@ export const encodeSnapshot = (machine, snapshot) => Effect.gen(function* () {
         const node = getNode(machine, path);
         active.push({
             path,
-            value: yield* encodeBoundary(machine, node.schema, getActiveValue(configuration, path), {
+            value: yield* encodeBoundary(machine, getStateNodeSchema(node), getActiveValue(configuration, path), {
                 boundary: "state",
                 state: path
             })
@@ -655,10 +1074,62 @@ export const encodeSnapshot = (machine, snapshot) => Effect.gen(function* () {
             ...(encodedOutput === undefined ? {} : { output: encodedOutput })
         });
     }
+    const history = {};
+    for (const [historyPath, record] of Array.from(configuration.history).sort(([left], [right]) => left.localeCompare(right))) {
+        const historyNode = machine.stateNodes.byPath.get(historyPath);
+        if (historyNode === undefined || historyNode.type !== "history" || historyNode.parent !== record.parent ||
+            historyNode.history !== record.mode) {
+            return yield* Effect.fail(new MachineSchemaEncodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: historyPath,
+                cause: Cause.die(new Error(`Machine snapshot contains invalid history record "${historyPath}"`))
+            }));
+        }
+        try {
+            validateHistoryRecordControl(machine, record);
+        }
+        catch (cause) {
+            return yield* Effect.fail(new MachineSchemaEncodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: historyPath,
+                cause: Cause.die(cause)
+            }));
+        }
+        const encodedValues = {};
+        for (const path of record.active) {
+            const stateNode = machine.stateNodes.byPath.get(path);
+            if (stateNode === undefined || stateNode.type === "history" || !record.values.has(path) ||
+                !(isPathInSubtree(path, record.parent) || getPathToRoot(machine, record.parent).includes(path))) {
+                return yield* Effect.fail(new MachineSchemaEncodeError({
+                    machineId: machine.id,
+                    boundary: "history",
+                    state: path,
+                    cause: Cause.die(new Error(`Machine snapshot contains invalid remembered state "${path}"`))
+                }));
+            }
+            encodedValues[path] = yield* encodeBoundary(machine, getStateNodeSchema(stateNode), record.values.get(path), { boundary: "history", state: path });
+        }
+        if (record.values.size !== record.active.size) {
+            return yield* Effect.fail(new MachineSchemaEncodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: historyPath,
+                cause: Cause.die(new Error(`Machine history record "${historyPath}" contains values outside its paths`))
+            }));
+        }
+        history[historyPath] = {
+            mode: record.mode,
+            active: Array.from(record.active).sort((left, right) => compareDocumentOrder(machine, left, right)),
+            values: encodedValues
+        };
+    }
     return {
         _tag: "MachineSnapshot",
         active,
-        ...(completed.length === 0 ? {} : { completed })
+        ...(completed.length === 0 ? {} : { completed }),
+        ...(Object.keys(history).length === 0 ? {} : { history })
     };
 }).pipe(Effect.catchCause((cause) => failEncodeCause(machine, cause)));
 export const decodeSnapshot = (machine, encoded) => Effect.gen(function* () {
@@ -675,15 +1146,91 @@ export const decodeSnapshot = (machine, encoded) => Effect.gen(function* () {
         }
         const node = getNode(machine, entry.path);
         active.add(entry.path);
-        values.set(entry.path, yield* decodeEncodedBoundary(machine, node.schema, entry.value, {
+        values.set(entry.path, yield* decodeEncodedBoundary(machine, getStateNodeSchema(node), entry.value, {
             boundary: "state",
             state: entry.path
         }));
     }
+    const history = new Map();
+    for (const [historyPath, encodedRecord] of Object.entries(decoded.history ?? {})) {
+        const historyNode = machine.stateNodes.byPath.get(historyPath);
+        if (historyNode === undefined || historyNode.type !== "history" || historyNode.parent === undefined ||
+            historyNode.history !== encodedRecord.mode) {
+            return yield* Effect.fail(new MachineSchemaDecodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: historyPath,
+                cause: Cause.die(new Error(`Machine encoded snapshot contains invalid history record "${historyPath}"`))
+            }));
+        }
+        const rememberedActive = new Set();
+        const rememberedValues = new Map();
+        for (const path of encodedRecord.active) {
+            if (rememberedActive.has(path)) {
+                return yield* Effect.fail(new MachineSchemaDecodeError({
+                    machineId: machine.id,
+                    boundary: "history",
+                    state: path,
+                    cause: Cause.die(new Error(`Machine encoded history contains duplicate state "${path}"`))
+                }));
+            }
+            const stateNode = machine.stateNodes.byPath.get(path);
+            if (stateNode === undefined || stateNode.type === "history" ||
+                !Object.prototype.hasOwnProperty.call(encodedRecord.values, path) ||
+                !(isPathInSubtree(path, historyNode.parent) || getPathToRoot(machine, historyNode.parent).includes(path))) {
+                return yield* Effect.fail(new MachineSchemaDecodeError({
+                    machineId: machine.id,
+                    boundary: "history",
+                    state: path,
+                    cause: Cause.die(new Error(`Machine encoded snapshot contains invalid remembered state "${path}"`))
+                }));
+            }
+            rememberedActive.add(path);
+            rememberedValues.set(path, yield* decodeEncodedBoundary(machine, getStateNodeSchema(stateNode), encodedRecord.values[path], {
+                boundary: "history",
+                state: path
+            }));
+        }
+        if (Object.keys(encodedRecord.values).length !== rememberedActive.size) {
+            return yield* Effect.fail(new MachineSchemaDecodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: historyPath,
+                cause: Cause.die(new Error(`Machine encoded history "${historyPath}" contains values outside its paths`))
+            }));
+        }
+        if (!rememberedActive.has(historyNode.parent)) {
+            return yield* Effect.fail(new MachineSchemaDecodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: historyPath,
+                cause: Cause.die(new Error(`Machine encoded history "${historyPath}" does not contain its parent state`))
+            }));
+        }
+        const record = {
+            mode: encodedRecord.mode,
+            parent: historyNode.parent,
+            active: rememberedActive,
+            values: rememberedValues
+        };
+        try {
+            validateHistoryRecordControl(machine, record);
+        }
+        catch (cause) {
+            return yield* Effect.fail(new MachineSchemaDecodeError({
+                machineId: machine.id,
+                boundary: "history",
+                state: historyPath,
+                cause: Cause.die(cause)
+            }));
+        }
+        history.set(historyPath, record);
+    }
     const configuration = {
         active,
         values,
-        outputs: new Map()
+        outputs: new Map(),
+        history
     };
     const snapshot = validateEncodedConfiguration(machine, configuration);
     const completions = [];