sx/current/PLAN-MULTIRET.md

PLAN-MULTIRET — bare-paren multi-value returns + named returns

Why

sx already has multi-value returns, but only in a verbose spelling: -> Tuple(A, B) / -> Tuple(x: A, y: B) types and return .(a, b) / return .(x = a, y = b) tuple-literal returns. Destructuring (a, b := f()), named/positional field access (r.x / r.0), and value-carrying failables (Tuple(A, B) !E) all work on top of the existing .tuple TypeId.

The user wants the ergonomic, canonical surface:

a :: () -> () { }                                  // () ≡ void
two :: () -> (i32, bool) { return 42, true; }      // bare-paren type + bare comma return
b :: (f1: i32, f2: i32) -> (sum: i32, good: bool) { // named returns are in-scope locals
    good = true;
    sum = f1 + f2;                                  // implicit return: all named slots set
}
b2 :: (f1: i32, f2: i32) -> (sum: i32, good: bool) {
    return f1 + f2, f2 > 42;                        // bare comma return still works
}
read :: () -> (i32, bool, !) { ... }               // error channel ALWAYS the last slot

Rules (from the user):

• () -> () ≡ () -> void.
• A multi-return signature is NOT a tuple — it just REUSES the tuple machinery. -> (i32, bool) / -> (x: i32, y: bool) mean "this function returns multiple values", a DISTINCT thing from -> Tuple(i32, bool) (which returns one tuple value). The bare-paren form is valid ONLY as a function/closure RETURN signature — x: (A, B) (a variable/param/field annotation) stays REJECTED; Tuple(…) is the spelling for an actual tuple value type.
• Consumption — destructure OR single-bind (REVISED 2026-06-27). A multi-return result may be DESTRUCTURED (s, g := b2()) OR bound to a single name and reached by field (c := b2(); c.sum / c.0). The earlier destructure-only rule (single-bind = error) was REVERSED by the user — single binding is allowed; the bound value behaves like a tuple of the value slots.
  • Failable: the error stays SEPARATE. For -> (sum, good, !), a bound value (c := f() catch … / try) holds ONLY the value slots — the error rides the ! channel and is NEVER part of c (no c.err). This falls out of the existing failable machinery (catch/try strip the error before binding).
• Failable: the error channel is always the LAST slot ((A, B, !)).
• Bare comma return: return v1, v2; maps positionally to the return slots — no .(…) tuple literal needed.
• Named returns are assignable locals. With no explicit return, an implicit return at end-of-body synthesizes the result from the named locals. A named return that is neither assigned on the path nor given a default is a COMPILE ERROR. A named slot may carry a default ((sum: i32 = 0, good: bool)); a defaulted slot needn't be assigned.

Representation (how "not a tuple, reuse machinery" is realized) — AS BUILT

• A dedicated AST node ReturnTypeExpr (field_types + optional field_names, same shape as a tuple) is produced by the parser for a bare-paren result list with ≥2 value slots ((A, B), (x: A, y: B), (A, B, !)). A single-value (T, !) stays a tuple_type_expr (a plain failable, = -> T !). An EMPTY () parses to the void type.
• It resolves (type_resolver internTupleLike, shared with tuple_type_expr) to a reused .tuple TypeId — full ABI / failable / destructure / field-access machinery reuse. Its distinct MEANING lives in the AST node, not the TypeId.
• Position gating: the node is valid only in a return slot. resolveParamType rejects a ReturnTypeExpr parameter annotation ("multi-return is return-only; use Tuple(…)"). Being a distinct node, its mere appearance in a value-type position is categorically an error (no flag to check) — exhaustive switches over node.data were forced to add a .return_type_expr arm (coverage).
• Consumption: destructure (a, b := f()) or single-bind + field access (c := f(); c.sum). No single source of truth needed at call sites — the result is just a tuple value.
• SCOPE: multi-return on name :: (...) -> (…) { } function declarations first. Multi-return CLOSURE-TYPE values (cb: Closure() -> (A, B)) and lambda literals are a later phase.

What already exists (re-use, do NOT rebuild)

• tuple_type_expr → .tuple TypeId with optional names (type_resolver.zig resolveCompound).
• Named + positional tuple field access r.x / r.0 (expr.zig lowerFieldAccessOnType).
• Destructuring a, b := f() (DestructureDecl, stmt.zig).
• Value-carrying failable assembly (T1, …, !) (error.zig lowerFailableSuccessReturn / emitTupleRet) — error in the last slot.
• return .(a, b) / return .(x = a, y = b) tuple-literal returns (stmt.zig lowerReturn).
• Generic inference through a failable/tuple closure return (this session's parser collectGenericNames + generic.zig extractTypeParam tuple arms).

Foundation already landed (uncommitted, suite-green)

• parser.zig — collectGenericNames descends tuple/optional/function nodes (so Closure() -> $R ! binds $R); the bare-paren result-list path builds a failable tuple_type_expr when it ends in ! ((A, B, !) parses).
• generic.zig — extractTypeParam / matchTypeParam[Static] handle the (value, !) tuple so $R infers from a closure ARG's failable return.

Phases (each: implement → lock with an example → zig build test green)

0. () -> () = void (parser). Isolated, unambiguous. An empty () in the paren type path resolves to void. Lock: a :: () -> () { }.

1. Multi-return signatures -> (A, B) / -> (x: A, y: B) / -> (A, B, !) (parser + AST + resolution). Add the multi_return_type AST node; the parser produces it for a bare-paren result list (return position). The return resolver lowers it to a .tuple TypeId and sets Function.multi_return; the general resolver rejects it (return-position only). Returns still use the existing return .(…) literal in this phase (bare comma is Phase 2). Consumption is destructuring a, b := f() (existing machinery). Lock: positional + named + failable multi-return examples, each destructured.

2. Destructure-only enforcement + bare comma return v1, v2 (parser + lowering). (a) Reject using a multi-return call as a single value (r := f(), an arg, an operand) — read Function.multi_return at the binding/use site; only destructuring is allowed. (b) Extend the return statement to parse a comma-separated value list and lower it to the same multi-slot return the .(…) literal produces (error slot stays implicit for failables). Single-value return v unchanged. Lock: -> (i64, bool) { return 7, true; }, a failable variant, and a negative example (r := f() → diagnostic).

3. Named-return locals + must-set rule (sema/lowering). For a named return -> (x: A, y: B), bind each name as an in-scope assignable local (alloca). On a path that reaches end-of-body with NO explicit return, synthesize the implicit return from the named locals. Diagnose loudly if any named slot is neither assigned on that path nor defaulted (no silent zero-fill). Explicit return v1, v2 / return .(…) still override. Lock: the b :: (...) -> (sum, good) { good = true; sum = ... } example + a negative example (unset slot → diagnostic).

4. Named-return defaults (sum: i32 = 0, good: bool). A slot with a default is exempt from the must-set rule; the default fills it at the implicit (or partial explicit) return. Lock: an example mixing a defaulted + a required slot.

Open decisions (Decisions Log)

• D1 — multi-return is NOT a tuple; return-position-only. Chosen (user directive). Realized via a distinct ReturnTypeExpr AST node (the user preferred a dedicated node over a TupleTypeExpr.is_multi_return flag — it makes "not a tuple" true at the AST level and makes position-gating categorical) that resolves to a reused .tuple TypeId. A new .tuple-like TypeInfo variant was rejected — it would ripple through every exhaustive type switch for no ABI benefit. Destructure-only was REVERSED (see Rules): single-binding a multi-return result is allowed (field access on the value slots); the failable error stays on the separate ! channel.
• D2 (Phase 3) — storage for named-return locals. Lean: an alloca per named slot bound in the function scope under its name; the implicit return reads them into the result tuple. Revisit if the must-set analysis wants SSA-style definite-assignment instead of an alloca + per-path check.
• D3 — multi-return closure-type values / lambda literals. Deferred past the function-decl phases (needs a ClosureInfo.multi_return flag). Phases 0–4 cover named function declarations only.

Validation (every phase)

• zig build && zig build test green (full corpus).
• New examples/<category>/… locked with snapshots; review the diff for .ir churn only where expected (the prelude type table is untouched by this stream, so churn should be minimal/none).
• Adversarial review of each phase before it lands.

Category for examples

Multi-return is a core type/return feature — use the types block (01xx), next free numbers, unless a better fit emerges.