From 448266713e41f466d7840246e868fa6335417609 Mon Sep 17 00:00:00 2001 From: Marcel Roozerkans Date: Sun, 24 May 2026 22:54:03 +0200 Subject: [PATCH] docs(backlog): mark B1-B5 shipped with PR references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The original post-v1 graduation backlog (B1 composite states, B2 shallow history, B3 timeout transitions, B4 Mermaid diagram, B5 concurrent state parts) fully shipped across PRs #25, #27, and #29. The backlog file hadn't been updated to reflect this — now it has. Each entry now carries a brief 'Shipped:' note pointing at the relevant attribute / generator file / test file so a reader can navigate from the backlog item to the implementation. No new backlog items added — future graduation candidates land here when real-world friction surfaces them. --- docs/backlog.md | 48 ++++++++++++++++-------------------------------- 1 file changed, 16 insertions(+), 32 deletions(-) diff --git a/docs/backlog.md b/docs/backlog.md index cc34332..21c95a5 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -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(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(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(State = X)]` attribute -- Generator stores last active sub-state before exit; restores on re-entry +**Shipped:** shallow-history support via `[HistoryState(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(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(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.