# 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 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.