Typesafe Carousel State Machine

TypesafeCarouselStateMachine<E> provides the repository's state-machine engine for branching and looping automation. E requires an enum. The builder requires a workflow ID, lifecycle owner, initial state, and exactly one handler for every enum constant. Missing handlers, duplicate handlers, a missing owner, or a missing initial state fail during build().

enum State { CHECK, ACT }

TypesafeCarouselStateMachine<State> machine =
    TypesafeCarouselStateMachine.builder(State.class, "example.workflow")
        .owner(this)
        .initial(State.CHECK)
        .on(State.CHECK, context -> ready()
            ? CarouselResult.transitionTo(State.ACT, "ready", "Ready to act")
            : CarouselResult.stay("waiting", "Waiting for prerequisites"))
        .on(State.ACT, context -> actionComplete()
            ? CarouselResult.complete("complete", "Action complete")
            : CarouselResult.stay("acting", "Action in progress"))
        .build();

Call pulse(clientTick) at most once per game tick. A duplicate tick returns a stay result with reason duplicate_tick without executing the handler. Each handler returns one of:

• CarouselResult.stay(reason, detail) to retain the current state;
• transitionTo(target, reason, detail) to select another enum state;
• complete(reason, detail) to retain successful terminal telemetry; or
• fail(reason, detail) to retain failed terminal telemetry.

Use machine.getContext() for workflow-owned scratch values and tick deadlines. Use snapshot() for immutable status and bounded transition history. Call cancel(reason, detail) for cooperative cancellation and reset() before reusing a terminal machine. Reset clears context, history, and registry ownership.

For a caller-owned runtime, wrap the machine with AutomationLoop.fromStateMachine(config, machine). Domain builders including BankWorkflowBuilder, CombatWorkflowBuilder, ProductionWorkflowBuilder, EnchantingWorkflowBuilder, PouchWorkflowBuilder, and SpellbookWorkflowBuilder return configured Carousel machines from typed plan objects. Their current plan fields and state enums live in the owning Java sources. See Workflow Builders & Plans.

---

State Machine Pulse & Lifecycle Logic Flow