Spec: Fix Invocation Error Propagation

Status: done Priority: P2 Created: 2026-02-08 Completed: 2026-02-09 Owner: invocation-bug-fixer

Context

In invocation/statechart.cljc:29-37, when a statechart is not found during invocation, the function sends an :error.platform event and logs an error, but always returns true (success). Callers cannot distinguish success from failure.

Additionally, invocation/future.clj:44 has a potential race condition between stop-invocation! calling future-cancel and the future's finally block cleaning up active-futures.

Requirements

1. Review return value contract for start-invocation! across all InvocationProcessor implementations
2. Document whether return value is meaningful
3. If return value should indicate success, fix statechart invocation to return false on failure
4. Review future invocation cleanup for race conditions
5. Add tests for invocation failure scenarios

Affected Modules

• src/main/com/fulcrologic/statecharts/invocation/statechart.cljc - Error return value
• src/main/com/fulcrologic/statecharts/invocation/future.clj - Race condition
• src/main/com/fulcrologic/statecharts/protocols.cljc - Document contract

Verification

1. [x] Return value contract documented in InvocationProcessor protocol
2. [x] Invocation failure returns correct value
3. [x] Tests cover missing-chart scenario
4. [x] Tests cover future cancellation race condition

Implementation Notes

Bug Fixes Applied

1. future.clj - Error Return Value Bug (Fixed)

   • Original code always returned true regardless of success/failure
   • Fixed to return false when src is not a function

2. future.clj - Race Condition (Fixed)

   • Original code could have the future complete before it was added to active-futures
   • Fixed by using a promise to block the future body until registration completes

3. future.clj - Exception Handling (Added)

   • Added catch Throwable to log exceptions in the future body

4. statechart.cljc - Already correctly returned false on error

Test Results

• StatechartInvocationProcessor: 30 assertions passing
• FutureInvocationProcessor: 29 assertions passing
• Total: 59 assertions, 0 failures