Add typed history states

Author: SandroMaglione

.changeset/bright-machines-remember.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine": minor
+---
+
+Add fully typed shallow and deep history states. History targets restore schema-validated state values, support typed defaults before the first capture, require only the initializers needed by shallow restoration, preserve parallel configurations, and round-trip through snapshot encoding and decoding.

README.md

@@ -147,7 +147,7 @@ masquerade as an internal result.
 
 ## Statechart structure
 
-`Machine.defineStates` accepts atomic, compound, parallel, and final state
+`Machine.defineStates` accepts atomic, compound, parallel, final, and history
 nodes:
 
 ```ts
@@ -205,6 +205,70 @@ Put data on the narrowest state where it is valid. If several sibling phases
 share data, prefer storing it on their compound parent instead of copying it
 into every child state.
 
+### History states
+
+A history pseudo-state remembers the last active configuration of its parent.
+It has no value schema and never appears in an active snapshot. History is
+shallow by default; use `history: "deep"` to retain the complete descendant
+configuration and its validated values:
+
+```ts
+const States = Machine.defineStates({
+  checkout: {
+    schema: Checkout,
+    initial: "shipping",
+    states: {
+      shipping: Shipping,
+      payment: {
+        schema: Payment,
+        initial: "cardEntry",
+        states: {
+          cardEntry: CardEntry,
+          verifying: Verifying
+        }
+      },
+      resume: { type: "history", history: "deep" }
+    }
+  },
+  support: Support
+})
+```
+
+Implement a typed default for the first transition before any configuration
+has been remembered, then target history without supplying a state value:
+
+```ts
+machine.handle({
+  checkout: {
+    history: {
+      resume: {
+        default: () => initialCheckoutSnapshot
+      }
+    }
+  },
+  support: {
+    on: {
+      Resume: ({ target }) => target.history.checkout.resume()
+    }
+  }
+})
+```
+
+Deep history restores every remembered descendant value. Shallow history
+restores the parent and direct-child values, then follows normal initial paths.
+Only compound or parallel states that shallow restoration can enter implicitly
+need an `initial` handler to construct those new child values:
+
+```ts
+payment: {
+  initial: ({ state }) => new CardEntry({ attempt: state.attempt, cardNumber: "" })
+}
+```
+
+Execution APIs remain unavailable until required history defaults and shallow
+initializers have been implemented. History records are part of logical
+snapshots and are schema-validated by `encodeSnapshot` and `decodeSnapshot`.
+
 Transition between structurally related tagged states with `Machine.retag`.
 The source `_tag` is discarded, compatible fields are reused, and missing or
 incompatible required fields must be supplied:
@@ -215,13 +279,14 @@ const saving = Machine.retag(State.cases.Saving, editing)
 
 ## Choosing a target builder
 
-Transition contexts expose three typed target builders:
+Transition contexts expose four typed target builders:
 
-| Builder         | Destination                                       | Configuration behavior                                                                         |
-| --------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `target.local`  | Inside the source's nearest compound scope        | Keeps the compound value, active ancestors, and unrelated parallel regions                     |
-| `target.branch` | Anywhere under the source's active top-level root | Replaces the selected branch while keeping omitted active ancestor values and parallel regions |
-| `target.full`   | Any top-level root                                | Builds a complete active snapshot for the selected root                                        |
+| Builder          | Destination                                       | Configuration behavior                                                                         |
+| ---------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `target.local`   | Inside the source's nearest compound scope        | Keeps the compound value, active ancestors, and unrelated parallel regions                     |
+| `target.branch`  | Anywhere under the source's active top-level root | Replaces the selected branch while keeping omitted active ancestor values and parallel regions |
+| `target.full`    | Any top-level root                                | Builds a complete active snapshot for the selected root                                        |
+| `target.history` | A declared history pseudo-state                   | Restores its parent's remembered configuration or runs its typed default                       |
 
 When `target.local` or `target.branch` enters an inactive nested parallel
 state, its callback must select every region, just like `initial` and
@@ -404,9 +469,9 @@ restrictions and delivery guarantees are documented on that API.
 
 ## Current limits
 
-History states and declarative first-class guards are not part of the current
-API. Ordinary TypeScript conditions implement guards. Use `Machine.after` for a
-cancellable state-scoped delayed event.
+Declarative first-class guards are not part of the current API. Ordinary
+TypeScript conditions implement guards. Use `Machine.after` for a cancellable
+state-scoped delayed event.
 
 ## Guidance for agents and contributors
 

docs/agent-guide.md

@@ -104,7 +104,7 @@ its extra control is required:
   the same operation with a returned transition value, not a separate action
   API.
 
-## Atomic, compound, and parallel states
+## Atomic, compound, parallel, and history states
 
 Use an atomic state when no child phase can be active beneath it.
 
@@ -201,13 +201,74 @@ const machine = Machine.make({
 Do not repeat `type: "final"` in `handle`. Execution APIs reject a machine
 until every declared output schema has an implementation.
 
+Declare a history pseudo-state below the active parent whose configuration it
+should remember. It has no schema, is excluded from active state identifiers,
+and is addressed only through `target.history`:
+
+```ts
+const States = Machine.defineStates({
+  checkout: {
+    schema: Checkout,
+    initial: "shipping",
+    states: {
+      shipping: Shipping,
+      payment: {
+        schema: Payment,
+        initial: "cardEntry",
+        states: {
+          cardEntry: CardEntry,
+          verifying: Verifying
+        }
+      },
+      recent: { type: "history" },
+      exact: { type: "history", history: "deep" }
+    }
+  },
+  support: Support
+})
+```
+
+Every history node needs a default parent snapshot for the first use:
+
+```ts
+checkout: {
+  history: {
+    recent: { default: () => initialCheckoutSnapshot },
+    exact: { default: () => initialCheckoutSnapshot }
+  }
+}
+```
+
+Target it without a value:
+
+```ts
+Resume: ({ target }) => target.history.checkout.exact()
+```
+
+Deep history restores the complete remembered subtree and its decoded values.
+Shallow history restores only parent and direct-child values. If the remembered
+child is compound, its configured initial child needs a freshly constructed
+value, so implement `initial` only on paths required by shallow history:
+
+```ts
+payment: {
+  initial: ({ state }) => new CardEntry({ attempt: state.attempt, cardNumber: "" })
+}
+```
+
+The machine's readiness type tracks missing defaults and shallow initializers.
+History is an overwriteable register, not a stack: restoration does not consume
+it, and the next parent exit replaces it. Entry actions and invokes run again;
+prior effects, actors, and timers are not rewound.
+
 ## Choosing a target
 
-| Builder         | Use it when                                                                | What it preserves                                                                 |
-| --------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `target.local`  | The destination is inside the nearest compound scope containing the source | The compound value, active ancestors, and unrelated parallel regions              |
-| `target.branch` | The destination is elsewhere under the active top-level root               | Omitted current ancestor values and parallel regions                              |
-| `target.full`   | The destination may be under any top-level root                            | Nothing is inferred for a newly selected root; build its complete active snapshot |
+| Builder          | Use it when                                                                | What it preserves                                                                 |
+| ---------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `target.local`   | The destination is inside the nearest compound scope containing the source | The compound value, active ancestors, and unrelated parallel regions              |
+| `target.branch`  | The destination is elsewhere under the active top-level root               | Omitted current ancestor values and parallel regions                              |
+| `target.full`    | The destination may be under any top-level root                            | Nothing is inferred for a newly selected root; build its complete active snapshot |
+| `target.history` | The destination is a declared history pseudo-state                         | Its parent's remembered configuration, or its default before the first capture    |
 
 Entering an inactive parallel state through `target.local` or `target.branch`
 requires a complete callback with one selection per region. A parallel state
@@ -611,10 +672,9 @@ a deeper statechart instead of casting away the diagnostic.
 
 The current API does not include:
 
-- history states;
 - declarative first-class guards;
 - a complete inspectable graph for arbitrary transition Effects.
 
 Use ordinary TypeScript conditions for guards and `Machine.after` for
 state-scoped timers. Do not invent undocumented state-node properties such as
-`guard` or `history`.
+`guard`.