stop-machine

A deterministic three-state stop controller. Once RED, nothing runs.

Why This Exists

AI systems need a real stop button, not a suggestion. Stop conditions in most systems are afterthoughts — flags checked late, states that can be bypassed, or halts that leave the system in an undefined residual state.

This primitive makes stopping a mechanical, fail-closed property of the system. Three states. One direction. No reversal. No configuration can override a terminal RED. No runtime condition can reset it. If your system needs a provably terminal stop, this is the brick.

States

  ┌───────┐   advance()   ┌───────┐   advance()   ┌─────────────┐
  │       │  ──────────►  │       │  ──────────►  │             │
  │ GREEN │               │ AMBER │               │  RED        │
  │       │               │       │               │  (terminal) │
  └───────┘               └───────┘               └─────────────┘
                                                         │
                                                  advance() raises
                                                  TerminalStateError

RED is terminal. No implicit transitions. No global state. Fail-closed: invalid transitions raise, they do not silently proceed.

Quick Start

git clone https://github.com/LalaSkye/stop-machine.git
cd stop-machine
python -c "
from stop_machine import StopMachine, State

m = StopMachine()
print(m.state)        # State.GREEN
m.advance()
print(m.state)        # State.AMBER
m.advance()
print(m.state)        # State.RED
"

Expected output:

State.GREEN
State.AMBER
State.RED

Usage

Basic advancement

from stop_machine import StopMachine, State

m = StopMachine()          # starts GREEN
m.advance()                # -> AMBER
m.advance()                # -> RED (terminal)
m.advance()                # raises TerminalStateError

Explicit transitions

m = StopMachine()
m.transition_to(State.AMBER)   # ok
m.transition_to(State.GREEN)   # raises InvalidTransitionError

Reset

m = StopMachine()
m.advance()                        # -> AMBER
m.reset()                          # -> GREEN

m = StopMachine(State.RED)
m.reset()                          # raises TerminalStateError

Checking state before acting

m = StopMachine()

if m.state == State.GREEN:
    # safe to proceed
    do_work()
    m.advance()            # move to AMBER after first signal

if m.state == State.AMBER:
    # proceed with caution
    do_cautious_work()
    m.advance()            # -> RED, terminal

Run Tests

pytest test_stop_machine.py -v

Example output:

test_stop_machine.py::test_initial_state PASSED
test_stop_machine.py::test_advance_green_to_amber PASSED
test_stop_machine.py::test_advance_amber_to_red PASSED
test_stop_machine.py::test_terminal_raises PASSED
test_stop_machine.py::test_explicit_transition_ok PASSED
test_stop_machine.py::test_invalid_transition_raises PASSED
test_stop_machine.py::test_reset_from_red PASSED
...

Constraints

• Deterministic behaviour only
• No global state
• < 200 LOC implementation
• All transitions explicit
• RED is terminal
• Fail-closed control: undefined transitions are errors, not silent passes

Docs

• Geometry Export Spec v0.1 — log schema, artefact paths, and determinism rules for Geometry Layer v0 (experimental, analysis-only)

Part of the Execution Boundary Series

Repo	Layer	What It Does
interpretation-boundary-lab	Upstream boundary	10-rule admissibility gate for interpretations
dual-boundary-admissibility-lab	Full corridor	Dual-boundary model with pressure monitoring and C-sector rotation
execution-boundary-lab	Execution boundary	Demonstrates cascading failures without upstream governance
stop-machine	Control primitive	Deterministic three-state stop controller
constraint-workshop	Control primitives	Authority gate, invariant litmus, stop machine
csgr-lab	Measurement	Contracted stability and drift measurement
invariant-lock	Drift prevention	Refuse execution unless version increments
policy-lint	Policy validation	Deterministic linter for governance statements
deterministic-lexicon	Vocabulary	Fixed terms, exact matches, no inference

License

MIT

---

Authorship & Rights

All architecture, methods, and system designs in this repository are the original work of Ricky Dean Jones unless otherwise stated. No rights to use, reproduce, or implement are granted without explicit permission beyond the terms of the repository licence.

Author: Ricky Dean Jones Repository owner: LalaSkye Status: Active research / architecture work Part of: Execution Boundary Series — TrinityOS / AlvianTech