Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 16 additions & 32 deletions docs/backlog.md
Original file line number Diff line number Diff line change
@@ -1,55 +1,39 @@
# ZeroAlloc.StateMachine — Backlog

Items not in v1. Implement once the core is stable and real-world usage patterns are understood.
The original post-v1 graduation backlog (B1–B5) has fully shipped. New items can be added below as real-world friction surfaces.

---

## B1 — Hierarchical / nested states
## B1 — Hierarchical / nested states — ✅ shipped (PR #25)

Sub-machines embedded within a parent state. When entering a composite state, the sub-machine starts at its own initial state. When exiting, the sub-machine is reset.

**Scope:**
- `[CompositeState<TState>(State = X, SubMachine = typeof(SubFsm))]` attribute
- Generator: when entering composite state, delegate TryFire to sub-machine first
- Sub-machine exit propagates trigger back to parent
**Shipped:** sub-machines embedded within a parent state via `[CompositeState<TState>(State = X, SubMachine = typeof(SubFsm))]`. When entering a composite state, the generator delegates `TryFire` to the sub-machine first; sub-machine exit propagates the trigger back to the parent. See `CompositeStateAttribute.cs`, `CompositeStateModel.cs`, and `CompositeStateTests.cs`.

---

## B2 — History states

Re-enter the last active sub-state when re-entering a composite state (shallow history).
## B2 — History states — ✅ shipped (PR #25)

**Scope:**
- `[HistoryState<TState>(State = X)]` attribute
- Generator stores last active sub-state before exit; restores on re-entry
**Shipped:** shallow-history support via `[HistoryState<TState>(State = X)]`. The generator stores the last active sub-state before exit and restores it on re-entry. See `HistoryStateAttribute.cs` and `HistoryStateModel.cs`.

---

## B3 — Timeout transitions
## B3 — Timeout transitions — ✅ shipped (PR #27)

Automatically fire a trigger after a configurable duration without external `TryFire`.

**Scope:**
- `[Transition<S,T>(From = X, On = Y, To = Z, AfterMs = 5000)]`
- Generator emits a `System.Threading.Timer` field, started on `OnEnter{State}`, cancelled on `OnExit{State}`
- Timer callback calls `TryFire` — concurrent-safe
**Shipped:** automatic trigger firing after a configurable duration via `[Transition<S,T>(From = X, On = Y, To = Z, AfterMs = 5000)]`. The generator emits a race-safe `System.Threading.Timer` field with `Interlocked.CompareExchange` lazy init, started on `OnEnter{State}`, cancelled on `OnExit{State}`. See `TimedTransitionTests.cs` for coverage including concurrent firing and disposal semantics.

---

## B4 — Visual diagram export

Generate a Mermaid or PlantUML state diagram from the declared transitions as part of the build.
## B4 — Visual diagram export — ✅ shipped (PR #29)

**Scope:**
- Additional generator output: `{TypeName}.mermaid` alongside `.g.cs`
- Opt-in via `[StateMachine(Diagram = true)]`
**Shipped:** Mermaid state diagram emitted alongside `.g.cs` as `{TypeName}.mermaid`, opt-in via `[StateMachine(Diagram = true)]`. The companion fix in the same PR closed an initial-state arm gap (initial state's `OnEnter` arm now runs on construction). See `MermaidDiagramWriter.cs` and `InitialStateArmTests.cs`.

---

## B5 — Per-trigger granularity for concurrent mode
## B5 — Per-trigger granularity for concurrent mode — ✅ shipped (PR #27)

**Shipped:** multiple independent state variables within one machine via `[StateMachineGroup]` + `[StateMachinePart]`. The generator emits one `long` field per part with independent CAS loops, each carrying its own transition table. See `StateMachineGroupAttribute.cs`, `StateMachinePartAttribute.cs`, `StateMachineGroupWriter.cs`, and `StateMachineGroupTests.cs`.

---

Support multiple independent state variables within one machine (e.g., a component with both an operational state and a connection state that evolve concurrently).
## Out of scope (for now)

**Scope:**
- `[StateMachineGroup]` containing multiple `[StateMachinePart]` fields
- Generator emits one `long` field per part with independent CAS loops
The original B1–B5 set covered the immediate post-v1 graduation candidates. Future entries graduate from this section once real-world friction surfaces a concrete value/cost tradeoff. Speculative additions are deliberately omitted — file a new backlog item with the friction narrative when one emerges.
Loading