# LOGIC branch — Terminal app for state-machine validation

When the user's question is about **behavior**, the prototype is a
single terminal app that the user runs and watches. The output prints
every state transition so the user can FEEL whether the logic works,
not just reason about it.

## When this branch fires

Question types that route here:

- "Does this state machine work?"
- "Does this control flow handle edge case X?"
- "Can this protocol handle out-of-order messages?"
- "What does the worker pool do under back-pressure?"
- "Does this retry policy actually converge?"

Question types that DO NOT route here (use UI branch instead):

- "Does this UI shape feel right?"
- "Is this flow discoverable?"
- "Does this layout work on mobile?"

## File shape

ONE file. Pick the project's primary runtime (TypeScript via `tsx`,
JavaScript via `node`, Python via `python3`, etc.). The shape:

```
// THROWAWAY PROTOTYPE — do not merge, do not extend, do not test.
// Question: "{verbatim question from user}"
// Decision criterion: "{what does 'yes' look like? what does 'no' look like?}"

// --- State machine model ---
// {Declare states, transitions, and any guards.}

// --- Transition driver ---
// {A function that takes (currentState, event) and returns nextState,
//  PRINTING every transition so the user can see what's happening.}

// --- Scripted run ---
// {5-10 sequential transitions that exercise the interesting paths.}
```

## Single-command invocation

The prototype runs with ONE command. Examples:

- `node prototype.mjs` — no transpile, no build, no install
- `pnpm dlx tsx prototype.ts` — uses dlx so no dependency added to the project
- `python3 prototype.py` — no virtualenv setup

If your prototype needs any of: webpack, vite, esbuild, a database
connection, an environment variable — you are prototyping the wrong
question. Re-scope to the BEHAVIOR question; the infrastructure is a
separate concern.

## Surface-state-transparently — concrete examples

A terminal app prints state transitions inline:

```
[T+0]  state=IDLE
[T+1]  event=user.click.submit → state=SUBMITTING
[T+2]  event=network.timeout → state=RETRYING (attempt 1)
[T+3]  event=network.timeout → state=RETRYING (attempt 2)
[T+4]  event=network.timeout → state=FAILED (exceeded retries)
```

The user reads this output and either says "yes that's what I wanted"
or "no, the retry policy needs jitter" — and the question is answered
in 30 seconds of looking, not 3 hours of staring at a flowchart.

If the state machine has parallel regions or hierarchical states, print
the full state vector at each transition, not just the leaf state.

## When the scripted run isn't enough

If the user needs to drive the state machine interactively (the
question is "what happens when I hit submit twice quickly?"), add a
tiny REPL loop:

```
> submit
[T+1] event=user.click.submit → state=SUBMITTING
> submit
[T+2] event=user.click.submit (REJECTED — already submitting)
[T+2] state=SUBMITTING
> timeout
[T+3] event=network.timeout → state=RETRYING (attempt 1)
```

Keep the REPL parser dumb (split on space, no quoting, no escape
handling). The user isn't testing your parser; they're testing the
state machine.

## Throwaway discipline reminder

When the question is answered, delete the prototype file. Do not let it
linger as "documentation of the design decision" — that's what
`apt-tools adr write` or `.aperant/context/notes/` are for.
