Finding #11 of the 2026-08 architecture review. Deferred from #52.
Problem
TransitionFrame.machineName (src/interfaces/TransitionFrameInterface.ts:26) is populated from this.process.getName() (src/Statemachine.ts:437). It is the process name, not a machine identity: every machine built from the same process reports the identical value.
That matters because the field looks exactly like the thing observers need and do not have. An observer handling transitions from many machines — the Factory pattern, one machine per order — will reach for machineName to tell them apart, and get a constant. TransitionLogger already sidesteps this by omitting the subject from its log context and telling callers to attach their own observer if they need identity.
Secondary defect: the field is typed string | null but is never null, so every consumer writes a null check that can't fire.
Proposed direction
- Rename to
processName and type it string.
- If a per-machine identifier is wanted, add it as a separate, explicitly optional field (e.g. an
id from StatemachineOptions) rather than overloading this one. frame.subject already exists for subject identity, so this may not be needed at all.
Acceptance criteria
Finding #11 of the 2026-08 architecture review. Deferred from #52.
Problem
TransitionFrame.machineName(src/interfaces/TransitionFrameInterface.ts:26) is populated fromthis.process.getName()(src/Statemachine.ts:437). It is the process name, not a machine identity: every machine built from the same process reports the identical value.That matters because the field looks exactly like the thing observers need and do not have. An observer handling transitions from many machines — the
Factorypattern, one machine per order — will reach formachineNameto tell them apart, and get a constant.TransitionLoggeralready sidesteps this by omitting the subject from its log context and telling callers to attach their own observer if they need identity.Secondary defect: the field is typed
string | nullbut is nevernull, so every consumer writes a null check that can't fire.Proposed direction
processNameand type itstring.idfromStatemachineOptions) rather than overloading this one.frame.subjectalready exists for subject identity, so this may not be needed at all.Acceptance criteria
TransitionLoggerand docs (docs/core.md,docs/observers.md,docs/interfaces.md) updated.docs/migration/.