sx/current/CHECKPOINT-MULTIRET.md

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

Plan: current/PLAN-MULTIRET.md. Branch: feat/multi-return.

Last completed step

Phases 0–3 implemented (final suite + snapshot capture in progress). Examples renumbered to the free types block 0202–0206 (0130/0131 already had duplicate existing owners).

• Phase 0 — empty () in the type path → void. (0202)
• Phase 1 — multi-return SIGNATURES (A, B) / (x: A, y: B) / (A, B, !) (≥2 value slots) parse to a tuple_type_expr tagged is_multi_return; a single-value (T, !) is a plain failable (= -> T !). Return resolver yields the reused tuple TypeId; resolveParamType rejects a multi-return tuple (return-position-only). Consumed by destructuring. (0203, 0204)
• Phase 2 — bare comma return v1, v2 (positional) / return x = v, y = w (named): the return parser builds the same tuple_literal the .(…) form produces. Single positional return v unchanged. (used throughout 0203–0205)
• Phase 3 — NAMED-return slots are in-scope assignable LOCALS: bound as zero-init allocas (bindNamedReturnSlots), the implicit return is synthesized from them (synthesizeNamedReturn → reuses lowerReturn), and the MUST-SET rule errors on an unset/undefaulted slot (bodyAssignsTo, path-insensitive MVP). Works with the failable error channel too. (0205 positive, 0206 negative)

Earlier foundation: parser collectGenericNames descends tuple/optional/function nodes; generic.zig extractTypeParam handle the (value, !) tuple.

Current state (works, verified by probes)

• () -> () ≡ void; -> (A, B) / -> (x: A, y: B) / -> (A, B, !) multi-return.
• return a, b / return x = a, y = b bare comma; named-return locals + implicit return + must-set diagnostic; failable named multi-return.
• (A, B) in a PARAM slot → loud diagnostic.
• Representation: TupleTypeExpr.is_multi_return flag + Lowering.named_return_names state (reuses tuple ABI; no new TypeInfo variant; multi-return-ness derivable from the FnDecl AST).

Post-Phase-3 changes (this session)

• Representation refactored to a dedicated ReturnTypeExpr AST node (user preferred it over the TupleTypeExpr.is_multi_return flag). Resolves to a reused .tuple TypeId via the shared internTupleLike helper. Forced .return_type_expr arms onto the exhaustive node.data switches (sema, semantic_diagnostics) — the coverage benefit. Param-position reject + the named-return-locals / must-set sites now key off .return_type_expr.
• Destructure-only enforcement REVERSED (user): single-binding a multi-return is ALLOWED. c := f(); c.sum works (the result is a tuple of the value slots). For a failable multi-return, c := f() catch … binds only the value slots — the error stays on the ! channel (verified). The callIsMultiReturn reject was removed. Examples 0203/0204 updated to show single-bind + field access (output byte-identical, snapshots unchanged).

Phase 4 — named-return DEFAULTS (done, suite pending)

-> (sum: i32 = 0, good: bool): the parser parses = <expr> per slot into ReturnTypeExpr.field_defaults; bindNamedReturnSlots seeds a defaulted slot with its (lowered+coerced) default; a defaulted slot is EXEMPT from the must-set rule. Also fixed hasFnBodyAfterArrow (the fn-def-vs-type-const lookahead) to skip = + literal tokens in the return-type scan — otherwise a = made the decl misread as a bodyless type-const ("expected ';'" at the body {). Lock: 0207.

Adversarial-review fixes (this session)

An adversarial review found 8 issues; fixed the soundness + silent-wrong ones:

• #1 (segfault on a conditionally-assigned non-scalar slot) → must-set is now PATH-SENSITIVE definite-assignment (definitelyAssigns, stmt.zig): a slot not assigned on every non-diverging path (and undefaulted) is a COMPILE ERROR, not a runtime garbage read. return/raise count as divergence; if needs both branches; push bodies count; match needs an else arm + all arms.
• #2 (wrong-type default → segfault) → bindNamedReturnSlots type-checks a default via the coercion classifier (.none ⇒ diagnostic). (NOTE: the same silent bitcast/segfault exists for ANY annotated assignment x: i32 = "hi" — a broader PRE-EXISTING type-checking gap, not multi-return-specific.)
• #3 / #8 (return arity garbage) + #4 (named elements ignored) → validateMultiReturn (stmt.zig, called from lowerReturn): rejects a bare value where ≥2 are required, wrong arity, a comma list from a single-value fn, and named elements out of slot order. (Reordering-by-name is a future nicety; for now a mismatch is a loud error, never silent-wrong.)
• #5 (slot shadows param) → collision diagnostic in bindNamedReturnSlots.
• #7 (push/defer false must-set error) → subsumed by the DA rewrite (push bodies count; defer correctly does NOT, as it runs after the implicit return).

Known limitations / next

• #6 (design gap): ReturnTypeExpr silently accepted in non-return positions — DONE (2026-06-27): generic-type-arg position now rejected (rejectMultiReturnValueType at both instantiateGenericStruct arg-resolution sites, generic.zig). Param / field / variable already rejected. Type-alias T :: (A,B) is value-parsed → already rejected. Closure-RETURN (A,B) is a legitimate return position → see D3 below (works as a multi-return closure). Lock: 0215 (negative generic-arg).
• Reordering named return elements by name (vs requiring slot order) — DONE (2026-06-27): reorderNamedReturn (stmt.zig) permutes a fully-named multi-return list to slot order by name (value-only AND full-failable-tuple forms); errors on unknown / duplicate / missing-slot names; positional & mixed lists pass through unchanged. validateMultiReturn's old slot-order check was removed. Adversarial review caught a silent mis-permute in the full-failable- tuple named form (now reordered/validated, not positionally dropped). Lock: 0210 (positive reorder, incl. failable) + 0214 (negative: unknown / duplicate).
• PRE-EXISTING: annotated-assignment type mismatch (x: i32 = "hi") segfaults — RESOLVED as issue 0197 (2026-06-27): width-mismatch guard (checkAssignable / noneReinterpretIsUnsafe, coerce.zig) at every annotated-slot store site; the named-return-default guard now shares it. Locked by examples/diagnostics/1205 + 1206.
• Multi-return CLOSURE-TYPE values / lambda literals deferred (D3). — RESOLVED (2026-06-27): they ALREADY WORK via the reused tuple machinery. A Closure() -> (A, B) value's call result destructures (a, b := cb()), single-binds + field-accesses (c := cb(); c.0), and a () => { return v1, v2; } lambda literal satisfies a multi-return closure param — verified identical to the function-decl surface. NO ClosureInfo.multi_return marker needed (the destructure-only rule was reversed, so there's nothing extra to enforce). Lock: 0216.
• Generic multi-return (Task 2d): DONE. POSITIONAL works — (a: $T, b: $U) -> (T, U) (inferred) and ($T: Type, …) -> (T, U) (explicit); lock 0217. NAMED-slot implicit-return form now works too (issue 0200 RESOLVED — monomorphizeFunction now calls bindNamedReturnSlots; covers free fns + generic struct methods, defaults, failable); lock 0218.
• Docs: readme.md / specs.md not yet updated for multi-return (docs-track rule).

Known issues

• issue 0198: implicit Any → T unbox unchecked (segfault / silent garbage) — RESOLVED (2026-06-27): implicit Any → T is now a compile error (coerceMode .unbox_any arm, mode == .implicit); xx + match dispatch unaffected. Locked by examples/diagnostics/1207.
• issue 0199: Any == <concrete> aborts the LLVM verifier — RESOLVED (2026-06-27): the Any-shaped ==/!= arm (expr.zig) now fires when EITHER operand is .any, boxing the concrete side first. Lock 0654.
• issue 0200: NAMED generic multi-return implicit-return "produces no value" — RESOLVED (2026-06-27): monomorphizeFunction now calls bindNamedReturnSlots (it previously bound params but skipped named-return slots). Covers generic free fns + struct methods, defaults, failable. Lock 0218.

Log

• 2026-06-27 session (handover: issue 0197 → finish multi-return → Io Phase 3):
  • issue 0197 RESOLVED — width-mismatch guard at every annotated-slot store site (var/const-decl, single + multi assignment for identifier/field/index/ element/deref, named-return defaults). Examples 1205 + 1206. Adversarial review caught & fixed: a bare-fn-ref false-positive (size-discriminator via typeSizeBytes, not the wrong fn-ref typing) and an aggregate-overrun false-negative (sx-padded sizeOf → LLVM-accurate typeSizeBytes); cascade suppression via externalErrorsExist (guard tallies its own diagnostics).
  • issue 0198 RESOLVED — implicit Any → T unbox is now a compile error (reviewer-confirmed sound). Example 1207. issue 0199 FILED (Any==concrete LLVM-verify abort, loud, open).
  • multi-return Task 2 DONE (2a reorder 0210/0214; 2b reject in generic-arg 0215; 2c D3 closures already work 0216; 2d positional generic works 0217 + named-generic gap filed as 0200). Multi-return feature surface complete.
  • REMAINING (next session): Task 3 Io-unification Phase 3 (the capture-typing blocker below + true cancellation — needs fresh context + both macOS & aarch64-linux validation per PLAN-IO-UNIFY.md). (0198/0199/0200 all resolved this session; no open multi-return/type-check issues remain.)
• Pivoted here from the Io-unification Phase 3 (true cancellation), which is PAUSED at its blocker: capturing a failable closure into a nested closure loses its failability (worker() catch → operand type 'unresolved'; repro .sx-tmp/pD.sx/pE.sx). That capture-typing gap is unrelated to multi-return and waits for a later session. The Io-Phase-3 stdlib edits (core/sched/io + example 1825) were REVERTED to keep the tree green; the multi-return-relevant compiler changes were kept.
• Foundation landed + suite green; plan + checkpoint written.