flan/spec-conditions.md

# Spec 2 — Conditions and restarts, operational semantics

Status: **frozen** for the six hard cases below. Everything not listed here is
still open, but nothing in the implementation may depend on the unlisted parts.

Four operators: `handler-bind`, `handler-case`, `restart-case`, `invoke-restart`.
No condition class hierarchy — condition types are structs, matching is by type
plus an optional predicate.

## 1. `signal` returns `()`

`(signal c)` has type `()`, always. When every applicable handler returns
normally without transferring, `signal` returns `()` and the signalling
function simply carries on. This is the accumulation case.

The alternative — `signal` producing a value supplied by the handler — was
rejected: it forces every signal site to declare a default value and a result
type, which is a much heavier language for one convenience.

The consequence is visible in the syntax. A `restart-case` in value position
must produce its type on the *fall-through* path too:

```
(defn load-texture [path string] (Handle Texture)
  (if (file-exists? path)
    (rl/load-texture path)
    (restart-case
      (do (signal (AssetMissing {.path path}))
          (abort "unhandled AssetMissing"))   ; fall-through must not return
      (use-placeholder [] placeholder-texture)
      (retry []          (load-texture path)))))
```

`abort` has type `Never`, which unifies with anything. Any expression of type
`Never` (a `return`, a call to a diverging function) is equally acceptable there.

## 2. No handler

`signal` with no matching handler on the handler stack is a **no-op** that
returns `()`. It does not abort, does not print, does not enter a break loop.
`(error c)` is the diverging variant: same lookup, but with type `Never` and, if
nothing handles it, it enters the dev-build break loop or aborts in release.

The cost when unused is the intended one: `handler-bind` is a couple of stores
onto a stack-allocated linked-list frame, and `signal` with an empty stack is a
null check.

## 3. Restart signatures

```
(restart-case BODY
  (name [p1 T1  p2 T2] BODY-1)
  ...)
```

- Parameters are annotated inline, like any other binding form.
- **Every clause body and the `restart-case` body must have the same type**, and
  that is the type of the whole form.
- `(invoke-restart 'name arg ...)` has type `Never` — it never returns to the
  invoking handler. Control resumes at the `restart-case`, which yields the
  clause's value to *its* continuation.
- Argument count and types are checked at **runtime** in the first
  implementation, because restarts are dynamically scoped and named. A statically
  tracked restart set (Zig's error-set model) remains a nice-to-have.

**Open: a clause should carry a report string.** `use-placeholder` is an
identifier, which is what `invoke-restart` needs and not what a person reading a
break loop's list needs — "carry on with a blank asset" is. SBCL's restart
struct has a `report-function` for exactly this prompt, and an
`interactive-function` for the parameters §3 already has. Nothing here mentions
either, and the break loop today shows names because names are all there are.
The cost is a string constant per clause, a field beside the name in the restart
frame, and one accessor: it is not hard, it is simply not written. It should be
settled before restarts with parameters, which is the feature that makes a bare
name least sufficient.

## 4. Name shadowing

Restart lookup walks the dynamic restart stack from innermost outward and takes
the **first** frame offering the name. An inner `restart-case` therefore shadows
an outer one with the same name for the duration of its body. This is what makes
"restarts go at the resync point" composable: an inner parser's `skip-form` is
found before an outer one's.

`(find-restart 'name)` returns `(Option Restart)` so a handler can test before
committing; `(compute-restarts)` lists the visible frames for the debugger.

**A debugger identifies a restart by its position, not by its name.** The rule
above is what a handler wants — an inner `skip-form` should win — and it is
exactly wrong for a human being shown a list: a shadowed frame is on that list
and by name is unreachable, so offering it and resolving by name means taking a
different restart than the one that was pointed at. So the break loop numbers
its list, innermost first, and a choice is a position. `invoke-restart` is
unchanged and stays by name. This is why SBCL's debugger is positional too.

A position only means something against a stack that is holding still, which
the stopped thread's is not — the break loop runs evaluations, and each one
pushes and pops this list. The list a debugger shows is therefore a **snapshot**
taken when the break was entered, and the positions are positions in it.

**Not every visible restart is reachable.** Transfer is lowered explicitly (§6),
so it cannot cross a frame that does not carry the channel. An evaluation run
into a stopped program is called through such a frame, and a restart below it
must be refused with the reason rather than accepted and dropped.

## 5. Cleanup during a transfer

Invoking a restart transfers control outward past zero or more frames.

- `defer` forms in every frame between the `invoke-restart` and the target
  `restart-case` **do run**, innermost first, before the clause body starts.
- `errdefer` forms **do not run**. `errdefer` is bound to the `Result` failure
  path (`try` returning `Err`) only. A restart transfer is not a failure — it is
  a chosen recovery, and the recovery may well want the resource.
- The condition object lives on the *signalling* frame's stack. Nothing has
  unwound when a handler runs, so it is valid there; but once a transfer starts,
  the signalling frame dies. Anything a handler keeps must be copied out
  (conditions are value structs, so `(push errors c)` copies).

**A restart is not a transaction.** The list above is the whole of what a
transfer does: it runs `defer`s and it moves control. It does not undo. Control
resumes at the `restart-case` and runs forward from there, so a `retry` re-runs
every effect between the restart and the target — a global the frame already
assigned stays assigned, and is assigned again. This is not a gap to be closed
later. Common Lisp has exactly this property and offers no help either; rollback
would mean journalling every store, which is a different language.

What follows is a discipline rather than a mechanism: **the author chooses where
the retry boundary is.** A `restart-case` at the top of a frame re-runs
everything, mutations included; one placed after the mutations re-runs only what
follows them. So either put the restart before anything mutates, make the
retried section idempotent, or snapshot what will be re-applied.

It matters more here than in most Lisps because of the intended use. A game loop
means to skip a frame and carry on rather than die, and a failed bounds check
signalling `BoundsError` rather than ending the process makes abandoning and
retrying a frame an ordinary thing to do — which is precisely the case where a
non-idempotent mutation bites. §3's rule that every clause body and the body
share a type places the restart syntactically; nothing places it *semantically*,
and that choice is the author's.

## 6. Crossing compiler-generated frames

Transfer is lowered **explicitly** — result propagation plus branch targets — not
via platform unwinding. Three reasons, none of them about dev builds:

- **wasm32 cannot unwind** without the exceptions proposal, so a release export
  would not work at all.
- **Native unwinding is not cheaper and is much less legible.** Every call
  becomes an `invoke` with a landing pad, plus a personality function and an
  exception table; a `cmp`/`jne` after a call reads like ordinary code and that
  matters once there is a disassembler.
- **One mechanism is one thing to get right.** The acceptance table runs the
  same programs on both targets and compares a hash, and that hash is the only
  tripwire two implementations would have.

That means
every function on the path between the invoke and the target must be
transfer-aware: it carries a "normal / transferring to frame N" channel, checks
it after each call, and forwards.

**The channel is an out-parameter**, a `ptr` appended to the signature, and not
a discriminated return value. The return type then stays what the source says,
which keeps a function's disassembly readable as the release one plus a guard;
a discriminated return would repack every `ret`, turn an aggregate return into
an `sret` call, and nest awkwardly inside the discriminated return `(Option T)`
already is. One pointer threads down the whole chain, so a callee writes the
target into its caller's own slot and each frame only has to check and return
early — which reuses the existing `return` path, and therefore §5's defers, for
free.

A single global slot would be more legible still — no signature change at all —
but it is not re-entrant: §5 runs defers *during* a transfer, so a defer that
signals and invokes a restart would start a second transfer over the first. A
per-frame slot nests correctly with no threads involved.

- **Every function carries the channel, and that is the ABI.** Uniformity is
  what keeps an indirect call and a hot-reload cell safe: a cell holds a bare
  pointer, so the honest answer to "what can this call?" is "anything", and a
  signature that depended on the answer could not be reloaded into. An earlier
  draft had escape analysis decide which functions are transfer-transparent;
  that is now an *optimisation over what a function does with the channel* —
  a function that provably cannot transfer need not check it after a call, and
  can pass the pointer straight through. It may not drop the parameter. See
  plan.org, Hot reload.
- **Foreign frames cannot be crossed.** A restart transfer whose path passes
  through a C frame (a raylib callback, an `extern` function calling back into
  Flan) is a runtime error, not undefined behaviour. Handlers installed across an
  FFI boundary must therefore either return normally or use `handler-case`
  installed inside the callback.
- With the async state-machine transform, the handler and restart stacks live in
  the **task** state, not thread-local, so a handler established before an
  `await` is still in scope after resumption.

## What this does not settle

Condition inheritance/predicate-matching details, the break-loop UI, restart
interaction with threads, and whether `handler-case` should be a macro over
`handler-bind` + a transfer. None of these block milestone 5.