AILang/docs/specs/0033-llm-surface-discipline.md

# LLM-Surface Discipline — Design-Principles Spec

**Date:** 2026-05-17
**Status:** Principles distillation — the meta-principle is ratified
orchestrator guidance; the candidate decisions in §6 are NOT
ratified and each still requires the normal `brainstorm` +
Feature-acceptance gate before it touches `DESIGN.md` or is
implemented.
**Authors:** Brummel (orchestrator) + Claude

## What this spec is

A distillation of one design session that walked from "what are
effects" down through input, world-passing, statefulness,
closures, recursion, and content-addressing. It is **not** a
milestone spec: no feature is being proposed for implementation
here. It records (a) one meta-principle that recurred five times
and is now treated as standing orchestrator guidance, (b) a
separability analysis that re-aims the project's cost/benefit
scrutiny, and (c) a list of open forks with their epistemic
status so a later `brainstorm` can pick them up without
re-deriving the reasoning.

## What this spec is NOT

It does not ratify `loop`/`recur`, closure-private state, the
removal of `mut`, `argv`-into-`main`, or any change to the cycle
/ content-addressing commitments. Those are §6 candidates. It
does not relitigate Decision 10. It carries no implementation
plan.

## 1. The meta-principle (ratified guidance)

> **The LLM author writes intent in a disciplined surface form.
> The raw, mechanical, invariant-threatening transformation stays
> in the compiler / IR, where the author never hand-manages it.
> Exposing the raw mechanism to the author is the consistently
> wrong move for this audience.**

This is the operational reading of DESIGN.md's
Feature-acceptance criterion and the "machine readability over
human ergonomics" goal, specialised to control/state/effect
constructs. It is not "hide complexity"; it is "the author
asserts *what*, the compiler bears the *mechanical invariant*,
and a violated invariant surfaces as a compile error rather than
as a silent deep-input failure."

## 2. Evidence — the five instances

Each row: the disciplined surface AILang keeps (or should keep)
vs. the raw mechanism it must NOT push onto the author.

1. **Effects.** Surface: an effect label on the signature, the
   checker reconciles it. Raw: the author hand-threads a `World`
   token through every call (world-passing). — World-passing is
   sound under Decision 10's uniqueness machinery, but it
   relocates the bookkeeping onto the author. Effect label kept.
2. **Stateful closures.** Surface: a closure that simply *is* a
   stateful value, its cell born in its own env. Raw: the author
   manages capture + escape + the `mut`→move transport. Closure-
   private state needs no cycles, no weak refs, no linearity-pass
   extension; it is the simplest of the three options examined.
3. **Move-capture.** Surface: state declared where it is used.
   Raw: a `move`-list, a linearity-pass scope expansion,
   use-after-move diagnostics, per-var-vs-per-block residence.
   Move-capture exists only to *transport* state from an
   enclosing owner to a closure; if the state has no reason to
   exist anywhere but the closure, the transport problem
   dissolves and so does the machinery.
4. **Iteration / recursion.** Surface: recursion (LLM-natural for
   structural descent) and a single iteration construct. Raw:
   the author hand-compiles a naturally-recursive algorithm into
   an explicit-stack worklist loop. Stack-safety of non-tail
   recursion is the *compiler's* job (cf. the existing
   `(drop-iterative)` escape hatch for the drop cascade), not an
   author obligation discharged by banning recursion.
5. **Jump.** Surface: `loop`/`recur` — re-iteration is the only
   thing `recur` can mean, the jump is structural. Raw: either
   the author-asserted `tail` flag on `tail-app` (a forgotten
   flag silently degrades to a stack-growing call: correct on
   small inputs, overflow on deep ones — a hallucination-shaped
   failure), or a raw labeled `goto` (kills local reasoning,
   forces mutable loop state, breaks the expression model and
   the structured-AST hash).

Five-for-five, the right answer was "disciplined surface,
mechanism stays in the compiler." This is the through-line.

## 3. The robustness corollary

For this audience an invariant guaranteed **by construction /
structurally** strictly dominates one **asserted by the author
via a flag or annotation**. Rationale: the failure mode of a
forgotten assertion is silent, input-size-dependent, and
indistinguishable from correct code in a small test — exactly
the hallucination-shaped failure the language exists to prevent.
Canonical anti-example: the `tail-app` `tail: true` flag.
Canonical positive: `recur`, which has no non-tail spelling.

## 4. The separability analysis (re-aims cost scrutiny)

`DESIGN.md` bundles three logically distinct commitments as if
they were one. They are separable:

1. **Content-address definitions.** Needs only a canonical
   serialisation + a hash of a finite definition AST. Cheap.
   Delivers the audience-specific wins (verify a symbol without
   spending context; semantic def-diff; trust a signature
   without transitive reading). **Worth it. Keep.**
2. **Total equational purity of every runtime value.** The
   commitment that forbids the LLM-natural stateful closure.
   Expensive.
3. **RC without a cycle collector.** Requires acyclic runtime
   values. Expensive.

The cost this session repeatedly hit belongs to (2)+(3), not to
(1). AILang already content-addresses only structure /
definitions, never live runtime values, so (1) does not require
the no-cycle memory model — (2) and (3) do. The productive
question for any future brainstorm is therefore **not** "is
content-addressing worth it" (it is, and it is cheap) but
"must value-purity be *total*, or does the weaker line
**acyclic + unaliased** suffice?" Closure-private state sits
exactly on that weaker line: not equationally pure, but acyclic
and unaliased — it keeps (1) and (3) intact while unblocking the
construct the LLM reaches for.

## 5. Concrete surface anchors

These pin the *shape* the principles imply. They are
illustrative, not ratified syntax.

Single iteration construct (`loop`/`recur` as pure tail-recursion
sugar; loop state is rebound parameters, not mutation):

```
(fn sum_to
  (type (fn-type (params (con Int)) (ret (con Int))))
  (params n)
  (body
    (loop (acc (con Int) 0) (i (con Int) 1)
      (if (app > i n)
          acc
          (recur (app + acc i) (app + i 1))))))
```

Closure-private state (state born in the closure; no enclosing
`mut`, no `move`, no transport):

```
(fn make_counter
  (type (fn-type (params) (ret (fn-type (params) (ret (con Int))))))
  (params)
  (body
    (lam (state (var counter Int 0)) (params) (ret (con Int))
      (body (seq (assign counter (app + counter 1)) counter)))))
```

Cheapest usefulness move (`argv` into `main`; `main(args)` stays
pure, the impurity stays at the trampoline C-ABI seam — no
effect, no Decision touched):

```
(fn main
  (type (fn-type (params (con List (con Str))) (ret (con Int))))
  (params args)
  (body ...))
```

## 6. Open forks — candidate decisions, NOT ratified

Each needs `brainstorm` + the Feature-acceptance gate before it
becomes DESIGN.md or a plan. Priority order reflects usefulness
per cost.

1. **`argv` into `main` (highest usefulness per cost).** Moves
   the language out of the closed-program vacuum. Touches no
   Decision; `main(args)` is a pure function, impurity confined
   to the trampoline. One real implementation cost: the
   trampoline must build an RC-correct `List<Str>` (Str slabs +
   cons cells with valid refcount headers) — the in-the-small
   form of the marshalling-into-RC-heap problem. Bounded, local,
   no language-semantics change.
2. **`loop`/`recur` as the single iteration surface.** Re-attempt
   of the reverted Iteration-discipline centrepiece, but
   **standalone** — de-bundled from the structural-guardedness
   checker and the `Diverge` effect that entangled and sank the
   original milestone. Honest cost to spec explicitly: retiring
   `tail-app` wholesale loses general proper-tail-calls (mutual
   recursion, tail-call into a different fn) with a stack
   guarantee. State the cost in the spec; do not retire it
   silently.
3. **Closure-private mutable state, possibly replacing `mut`.**
   Sealed scalar `mut` without loop and without capture is
   largely redundant with `let`/`if`/`match`; its only on-record
   justification is the narrow ergonomic mut-local fieldtest
   finding. Removing a shipped, fieldtested feature requires the
   project's own empirical gate: re-author the mut-local
   fieldtest tasks with closure-private state + plain `let`; if
   the reported hallucination friction does not return, `mut` is
   scaffolding and can fall, and the move-capture milestone is
   then unnecessary (it solved a transport problem that only
   existed because `mut` births state in the wrong place).
4. **Cycles / content-addressing (deepest; deliberately not
   opened).** Allowing cycles to get "real" closures negates
   Decision 10 and transitively Decision 1/2. Per §4 it is the
   wrong target anyway — the cheap, high-value commitment
   (content-address definitions) is not the expensive one. Named
   here as the deepest fork so it is not stumbled into; a
   near-term milestone must not open it.

## Cross-references

- `docs/DESIGN.md` — Decision 1/2 (source = data, content-
  addressed), Decision 3 (pure core + effects), Decision 8
  (verified tail calls), Decision 9/10 (RC + uniqueness, no
  collector), Feature-acceptance criterion.
- `docs/specs/0029-mut-local.md` — the sealed-mut milestone
  whose redundancy §6.3 questions.
- `docs/specs/0032-iteration-discipline-revert.md` — why
  the bundled loop/recur milestone was backed out; §6.2 is the
  de-bundled re-attempt.