State machines builtins

5 builtins of Soma 3.2.4 in the category State machines, with their exact signatures, as soma describe --builtins --json prints them.

• next_id
• transition
• get_status
• has_state
• valid_transitions

next_id

next_id() -> Int

Monotonic per-cell counter, in its own table (persistent under run/serve; per test cell in tests); journaled — a refused request burns no id; the ids drawn inside a try that fails are kept (they may have escaped into a local), so ids are unique, not always dense. Exhaustion at 2^63 - 1 raises range; a malformed or negative stored counter raises storage. Legacy migration is confined to the current cell.

deterministic · replay: pure

Used in verified programs:

• agents/approval_gate, line 36: let id = to_string(next_id())
• agents/bounded_retry, line 25: let id = to_string(next_id())
• agents/budget_guard, line 30: let id = to_string(next_id())
• agents/guarded_agent, line 40: let id = to_string(next_id())

transition

transition(id, target_state: String) -> {id, from, to} | transition(id, from_state: String, to_state: String) -> {id, from, to}

Move instance id to target_state (read the new state with get_status(id)); raises kind "invalid_transition" with the valid targets, or "guard_failed". With three arguments the handler declares the source: soma check verifies the edge exists and the call fails (invalid_transition) when the instance is elsewhere, even if some edge into the target exists from there. Rolled back if the handler later fails.

deterministic · replay: pure

Used in verified programs:

• aerospace/autopilot_authority, line 47: let r = try { transition(id, "engaged") }
• aerospace/cabin_pressurization, line 51: let r = try { transition(id, target) }
• aerospace/cargo_door, line 54: let r = try { transition(id, target) }
• aerospace/docking_approach, line 50: let r = try { transition(id, "corridor") }

get_status

get_status(id) -> String

Current state of instance id. For an id never transitioned: () in edition 2027, the INITIAL state in edition 2026 — get_status(id) ?? "initial" reads the same in both (has_state(id) tells a fresh id from one that moved).

deterministic · replay: pure

Used in verified programs:

• aerospace/autopilot_authority, line 50: return map("ok", true, "authority", get_status(id))
• aerospace/cabin_pressurization, line 53: return map("ok", true, "phase", get_status(id))
• aerospace/cargo_door, line 56: return map("ok", true, "door", get_status(id))
• aerospace/docking_approach, line 52: return map("ok", true, "phase", get_status(id))

has_state

has_state(id) -> Bool

True when instance id was transitioned at least once (a recorded state exists). get_status(id) alone cannot distinguish an unknown id from a fresh one.

deterministic · replay: pure

valid_transitions

valid_transitions(id) -> List<String>

States reachable from instance id's current state.

deterministic · replay: pure

Used in verified programs:

• state_machines/media_player, line 35: on next(id: String) { return valid_transitions(id) }
• state_machines/support_ticket, line 34: on next(id: String) { return valid_transitions(id) }
• state_machines/traffic_interlock, line 43: on next(id: String) { return valid_transitions(id) }