feat(statechart): migrate HsmMachine to lazily::StateChart + reactive hooks #259

Summary

Replace ledgrrr's hand-rolled HsmMachine (LifecycleState/LifecycleSubstate enum FSM, crates/ledgerr-mcp/src/hsm.rs, ~258 lines) with lazily::StateChart — a full Harel/SCXML statechart backed by reactive cells. Use Effect on StateChart::configuration to drive task/project-management hooks on every transition.

Evaluation: statechart libraries

lazily is recommended because:

• Full Harel statecharts: compound states, orthogonal regions, shallow/deep history, entry/exit/transition actions, named guards
• Backed by Source<BTreeSet<String>> (the active configuration is a reactive cell)
• Any Effect on StateChart::configuration fires on every real transition → perfect for task hooks
• Cross-language (Rust/Python/JS/Go/…) parity — useful if future bindings are needed
• The reactive graph (Context/Cell/Signal/Effect) unifies statechart state with derived tool availability (what tools are visible at each lifecycle state)

Existing statechart code to migrate/harmonize

Migration plan

Phase 1 — Add lazily to workspace (unblocked)

• Add lazily = { version = "0.59", features = ["statechart"] } to Cargo.toml workspace dependencies
• Gate behind a statechart feature flag in ledgerr-mcp

Phase 2 — Migrate HsmMachine

• Define LifecycleChart: ChartDef (the six lifecycle states as lazily statechart nodes)
• Replace HsmMachine internal FSM with StateChart instance
• Register a transition Effect that fires the existing TransitionRecord audit write on each state change
• Keep public API (HsmTransitionRequest/Response, HsmStatusRequest/Response) unchanged — behaviorally transparent migration

Phase 3 — Task/PM hooks

• Add HsmHookRegistry — a set of Effect callbacks registered against the lifecycle chart
• Expose ledgerr_hsm_register_hook MCP tool so agents can subscribe to lifecycle events
• Initial hook implementations: on_ingest, on_validate, on_commit

Phase 4 — kr0ki process execution

• Use lazily::StateChart in kr0ki-core for SysML-v2 ActionUsage process execution: each ActionUsage → a state, each SuccessionFlow → a transition, DecisionNode → a named guard

Design constraints

• Existing HsmTransitionRequest/Response public API must be preserved (backward-compatible)
• All existing hsm_contract.rs, hsm_mcp_e2e.rs, hsm_resume_contract.rs tests must pass after migration
• lazily MSRV 1.88 — verify workspace's rust-version is compatible

Related

• Closes the HsmMachine hand-rolled FSM tech debt
• Enables arch: CLIF (ISO/IEC 24707) AST and interpreter for ledgrrr's process/diagram engine #114 (CLIF/process engine) via kr0ki integration (Phase 4)
• statecharts.dev visual editor can be used to design/document the lifecycle chart before committing to code

🤖 Generated with Claude Code