Tracking: 2026-08 architecture review follow-up

[camcima]

Index of everything left open by the 2026-08 architecture review. The non-breaking fixes landed in #52; these are the items deliberately deferred there, plus the improvement opportunities the review raised but did not act on.

Breaking — batched for v5

Grouped so the ecosystem takes one major bump rather than five.

• Freeze Event and register event commands at build time #53 — Freeze Event and register event commands at build time (also removes the cross-machine observer-sharing hazard, and the Observer.update(subject, …) misnomer)
• Replace the onEnter event-name convention with first-class state entry hooks #54 — Replace the onEnter event-name convention with first-class state entry hooks
• Return Promise<boolean> from Statemachine.releaseLock() #55 — Return Promise<boolean> from Statemachine.releaseLock()
• Rename TransitionFrame.machineName to processName #56 — Rename TransitionFrame.machineName to processName
• Remove the deprecated Dispatcher interfaces and Event.getInvokeArgs() #57 — Remove the deprecated Dispatcher interfaces and Event.getInvokeArgs()

#53 and #54 are the two with real design content; the rest are mechanical once a major is being cut.

Non-breaking

• Verify Mermaid state-description quoting against a real renderer #58 — Verify Mermaid state-description quoting against a real renderer (needs a rendered diagram before any code change; output is pinned by tests and docs)
• Close the post-await re-entrancy detection gap with AsyncLocalStorage #59 — Close the post-await re-entrancy detection gap with AsyncLocalStorage
• Expose queue depth and runner state for observability #60 — Expose queue depth and runner state for observability
• Provide a scheduler helper for Timeout-driven transitions #61 — Provide a scheduler helper for Timeout-driven transitions
• Add an are-the-types-wrong check to CI #62 — Add an are-the-types-wrong check to CI
• OperationQueue.dequeue() is O(n) per operation #63 — OperationQueue.dequeue() is O(n) (low priority; likely wontfix)

Suggested order

1. Close the post-await re-entrancy detection gap with AsyncLocalStorage #59 — it is the only open item whose failure mode is a silent permanent deadlock, which is the same class of problem fix: address architecture review findings #52 fixed for whenIdle().
2. Add an are-the-types-wrong check to CI #62, then Verify Mermaid state-description quoting against a real renderer #58 — small, self-contained, and both protect user-facing output.
3. Expose queue depth and runner state for observability #60, Provide a scheduler helper for Timeout-driven transitions #61 — ergonomics that make existing features usable in production.
4. The v5 batch, led by the Freeze Event and register event commands at build time #53/Replace the onEnter event-name convention with first-class state entry hooks #54 design decisions.
5. OperationQueue.dequeue() is O(n) per operation #63 only if a profile ever justifies it.

Context

• Review document: ARCHITECTURE_REVIEW.md
• Fixes already landed: fix: address architecture review findings #52 (two reproduced bugs, four API-consistency gaps, docs)
• Previous review cycle for comparison: CODE_REVIEW.md (June 2026, all ten findings since fixed)