regression: checkMissingReturns false-positives on transformExpression when chad-native.ts has 8+ registerStdlib calls (introduced in #583)

[cs01]

Bug

The checkMissingReturns pass (in src/semantic/safety-checks.ts, invoked from src/codegen/llvm-generator.ts:3033 during codegen prep) false-positives on the transformExpression function in src/parser-native/transformer.ts (or src/parser-ts/handlers/expressions.ts — same name) when chad-native.ts contains 8 or more registerStdlib() calls.

Both transformExpression definitions return on all paths (switch with default case that returns a value or throws). The check incorrectly flags them only past a threshold of registered stdlib modules.

Repro

From a fresh checkout of origin/main (SHA 0f8e9a26 at time of filing):

1. Add one more registerStdlib(...) call to src/chad-native.ts, anywhere after the existing 7:

   registerStdlib("anything.ts", ChadScript.embedFile("../lib/colors.ts"));

   The 8th can reference any existing lib content — content doesn't matter, count does.

2. Build stage 0: npm run build && node dist/chad-node.js build src/chad-native.ts -o /tmp/chad-stage0

3. Run it on itself: /tmp/chad-stage0 build src/chad-native.ts -o /tmp/stage1

Result:

Semantic analysis passed
Generating LLVM IR...
error: function 'transformExpression' does not return a value on all code paths
  = help: add a return statement to all branches

Reducing back to 7 registerStdlib calls → compile succeeds. Content of the embedded file is irrelevant; so is the path, key name, and position.

Bisect

• b1c00c87 (pre-typeOf-migration) — 8 calls compiles fine
• b52c6449 (refactor(codegen): migrate 4 llvm-generator resolveExpressionType sites to typeOf() #583 first typeOf migration) — 8 calls fails
• 82108faa (refactor(codegen): migrate map-allocator to typeOf() #584 map-allocator migration) — fails (inherits)
• 0f8e9a26 (refactor(codegen): drop redundant resolveExpressionType fallback in variable-allocator #592 variable-allocator cleanup) — fails (inherits)

Introduced in #583.

Impact

Blocks any PR that adds an 8th stdlib module. Currently blocking #585 (net module — registerStdlib("net.ts", ...) was the 8th). The existing 7-stdlib main branch works fine, so the regression didn't surface until someone tried to add a new stdlib.

Likely cause (speculation)

#583 changed how resolveExpressionType results are cached via the typeOf() annotator. The regression is probably a hash/ordering dependency that kicks in past a certain AST size — most likely the switch-case analysis in mrAllReturn reads stale cached type info for case consequents when the top-level function count crosses a threshold.

Workaround

Keep registerStdlib calls ≤ 7 until fixed. (Not a real workaround for anyone shipping a new stdlib module.)

[cs01]

Diagnosis

Looked at this after landing #594. #583 is not the root cause — it's the trigger that pushed an existing native-compiler fragility past its threshold.

Why #583 can't directly cause this

checkMissingReturns (safety-checks.ts:543) is pure AST traversal:

• Called from llvm-generator.ts:3033, which is before annotateTypes at line 3046.
• mrAllReturn / mrIsNever never read the typeOf cache or any resolved-type state.
• refactor(codegen): migrate 4 llvm-generator resolveExpressionType sites to typeOf() #583 only modified 4 resolver calls in the global-var allocator path — code that runs far later, during IR emission.

So the logic of checkMissingReturns itself can't see anything #583 changed.

What's actually broken

The check only fails when stage 0 native is run on itself. Node-compiled stage 0 (per CLAUDE.md playbook) probably still compiles a cleanly-reported AST; it's the native binary's execution of checkMissingReturns that goes sideways past a threshold.

This is the same class as memory/native-missing-returns-false-positive.md: checkMissingReturns false-positives on exhaustive switches, triggered by unrelated AST shifts, diagnosed by running node compiler first.

The byte-level shift from #583 (different IR for 4 global-var paths → different stage 0 binary) is just a seed that pushes register layout / type-assertion offsets / pointer aliasing in transformExpression's compiled form over whatever native-compiler cliff already exists. #584, #592, #594 inherit it because they don't touch that path.

Recommended fix path

1. Repro under node compiler first. If node-compiled stage 0 reports clean, the bug is confined to native codegen for transformExpression specifically.
2. Bisect the native regression by function, not by AST count. Add one function at a time to a minimal repro until the false positive appears; that function's generated IR is the smoking gun.
3. Most likely culprit (by memory file pattern): a switch body whose compiled native code has a rule add --target-cpu flag and use x86-64 in ci to fix sigill on runners #2 (type-assertion field-order mismatch) or rule Add cross compilation support #5 (||-opaque member access) that shifts visible behavior at size thresholds.

Why not revert #583

Reverting #583 would roll back the first typeOf consumer migration — the whole #595 umbrella stands on it. More importantly, the fragility exists independent of #583; a different unrelated PR next week would trigger the same failure at a different threshold. Fix the native-compiler fragility, don't mask it.

Unblocking #585

If net module is the 8th stdlib and ship-blocked, acceptable workarounds until root-cause:

• Merge net module without registering it in chad-native.ts, register in a follow-up once regression: checkMissingReturns false-positives on transformExpression when chad-native.ts has 8+ registerStdlib calls (introduced in #583) #597 is fixed.
• Or split another stdlib out of the registered set temporarily.

Neither is pretty — root-cause is the real fix. Needs LLDB-level native-compiler debug, same shape as memory/sema-migration-blockers.md blocker A. Not a quick fix from the typeOf loop — separate focused session.

[cs01]

Env-dependent confirmation

Ran a focused root-cause pass with a subagent in a clean worktree at latest main — the subagent could not reproduce the bug (8 and even 13 registerStdlib calls compile cleanly on their box, macOS arm64, Darwin 25.3.0).

Meanwhile on my box (also macOS arm64) and in CI (build-linux-glibc Ubuntu 22.04 + build-macos macos-latest, PR #585), the bug reproduces deterministically on the same repo, same HEAD. So:

• On-machine repros vary even with same OS/arch
• CI runners reliably reproduce
• Subagent's box doesn't reproduce

This strongly supports the pinned diagnosis that it's a native-compiler IR-layout sensitivity — stage 0's byte-level layout differs subtly between machines (likely due to toolchain / package-lock / node_modules cache state → dist/chad-node.js bytes → stage 0 bytes). Some layouts land past the fragility threshold, some don't.

Diagnostic follow-up that should work on a repro'ing machine: under the broken stage 0, add console.log(JSON.stringify(...)) at safety-checks.ts:573 right before mrAllReturn(fnBodies[i].statements, nn) to dump the AST the checker is walking. Compare against the same dump from a NON-broken stage 0 (same source). First divergent node = the codegen bug location. If the AST dumps are identical, the bug is in the native codegen of mrAllReturn itself — LLDB the native _mrAllReturn in the broken binary.

PR #585 CI is blocked on this. Not pushing more to that branch until this issue is resolved. Happy to run diagnostics on my (repro-ing) box if helpful.

[cs01]

Diagnostic — AST dump confirms: bug is in native-compiled mrAllReturn

Added console.log(JSON.stringify(fnBodies[i])) instrumentation at safety-checks.ts:573 right before mrAllReturn, ran under both node-chad and native-chad at the same source. Two concrete findings:

1. Parsers disagree on function-body shape

For transformExpression (src/parser-native/transformer.ts:496 + src/parser-ts/handlers/expressions.ts:31):

• node-chad sees fn.body.statements = [ifStatement] — 34-deep if (type==="...") { return ... } else { if (...) ... } chain. Every level returns. Walked the entire chain programmatically; every then_last=return, terminal else is return. Correctly exhaustive.
• native-chad sees fn.body.statements = [{type:"block", statements: [...]}] — an extra outer block wrapping the same chain.

The AST divergence is a separate parser bug, but it should not cause the false positive: mrAllReturn has a block case that recurses into the inner statements.

2. Same AST in passing and failing runs

Built native stage 0 in both the "broken" (trips the check) and "not-broken" configurations. Both see the identical [block]-wrapped AST for transformExpression. So the difference between the two runs is NOT what AST mrAllReturn receives — it's how mrAllReturn itself behaves when running under different native-binary byte layouts.

Additional confirmation of the IR-layout-fragility theory: adding my instrumentation bytes to safety-checks.ts tipped even the 7-registerStdlib case into failing. Any perturbation crosses or un-crosses the threshold. Reducing to 7 entries only works in the un-instrumented build.

Conclusion

The bug is definitively in native-compiled mrAllReturn's block case (safety-checks.ts:273-275) or one of its callees (mrIsNever, mrHasBreak) — not in AST construction, not in safety-checks logic at the TS level, not in the typeOf migration.

Both the node and native AST shapes correctly all-return if the checker walks them properly; node does, native (under certain byte layouts) doesn't.

Concrete next step

LLDB the native stage 0 binary at _mrAllReturn, set breakpoint entering the block case for transformExpression's body, step through the recursive call, watch where the recursion returns false. The codegen is almost certainly either:

• Mishandling the BlockStatement.statements field offset under certain alloca layouts
• Pointer-aliasing between stmt cast to BlockStatement vs another type in a sibling case arm
• Recursion return-value not being propagated through the if (mrAllReturn(...)) return true; lowering

Happy to hand off to whoever has LLDB cycles on a repro'ing machine.

[cs01]

Isolated the mechanism

Walked the native binary vs node binary execution of mrAllReturn on parser-native/transformer.ts:transformExpression (using the #585 net-module branch where the bug actually blocks CI).

Finding

The AST seen by checkMissingReturns differs between parsers:

• parser-ts (transformSwitchToIfElse in handlers/statements.ts:674): returns an IfStatement directly. Function body: [IfStatement].
• parser-native (transformSwitchStatement in transformer.ts:2262): wraps the chained-if in a BlockStatement (line 2388). Function body: [BlockStatement { statements: [IfStatement] }].

Both structures are correctness-equivalent for mrAllReturn on paper — the block-case at safety-checks.ts:273 recurses into the wrapped if. Node compiler verifies this: with the node-built stage 0, mrAllReturn returns true on body=[if].

But the native binary's mrAllReturn returns false on body=[block{[if]}] — confirmed via inline DIAG prints in the native stage 0 binary:

DIAG_597 transformExpression stmts=1
DIAG_597 [0] ty=block
DIAG_597   block.stmts=1
DIAG_597   block[0] ty=if
DIAG_597     if.hasElse=true
DIAG_597     thenRet=1
DIAG_597     elseRet=0
DIAG_597 mrAllReturn=0

The outer if has its then-branch returning correctly, but the else-branch (which is a block containing the next if in the chained-if ladder) returns 0 — wrongly.

Where the bug lives

Not in checkMissingReturns logic itself (node stage 0 evaluates it fine). The bug is in how the native-compiled binary executes mrAllReturn's recursion into the else branch of the chained-if-ladder. Some case deep in the ladder returns a wrong "does this return" answer, propagating up.

Attempted deeper bisect via recursive-walk DIAG in native — segfaulted (exit 139) when walking IfStatement/BlockStatement structure inline. Suggests this is the same class as the rule #2 / rule #4 type-assertion fragility (CLAUDE.md "Patterns That Crash Native Code"), where certain struct traversal patterns fail native-specifically.

Two fix paths

1. Root-cause (proper): LLDB-bisect which level of the chained-if ladder's else-branch gets wrongly classified. Likely a native-specific bug in mrAllReturn's statement-type-dispatch when handling deeply nested if chains — possibly a stype === "block" → "if" recursion where a struct field access returns unexpectedly. Playbook: memory/playbook_native_lldb_debug.md.

2. Sidestep to unblock add net module: tcp sockets via libuv (prereq for pure-ts postgres driver) #585: Change parser-native/transformSwitchStatement to return the chainedIf directly (matching parser-ts behavior) instead of wrapping in BlockStatement. The block wrapper is redundant. Signature change + one caller update at transformer.ts:264 to handle the new shape. Fix in ~20 LOC. Does not solve the underlying native fragility — next AST-shift will hit it again — but unblocks stdlib expansion today.

Recommend path 2 for immediate unblock (file a follow-up issue referencing path 1 as the real fix). Otherwise #585 and all future stdlib additions stay gated.

Worktree state

• .worktrees/net-module (feat/net-module-tcp) clean, DIAG reverted.
• DIAG output above was captured pre-revert for the record.

[cs01]

Sidestep fix attempt — failed

Tried path 2 from previous comment: changed parser-native/transformSwitchStatement to return the chainedIf directly instead of wrapping in BlockStatement. After rebuild, stage 0 still emits the same transformExpression false positive.

So the block-wrapper hypothesis was wrong — or incomplete. Native mrAllReturn is failing on the chained-if structure itself, not just when there's an outer block wrapper. Needs real LLDB bisection of which if-case in the ladder native classifies as non-returning.

Reverted the fix attempt; worktree .worktrees/net-module is clean.

Remaining hypotheses to test under LLDB

1. One of the case bodies in parser-native's desugared ladder doesn't actually end in a return as expected. Dump the whole chainedIf tree pre-checkMissingReturns and cross-check each case body's last statement.
2. The inner if recursion in native's mrAllReturn hits rule add --target-cpu flag and use x86-64 in ci to fix sigill on runners #2 struct-layout drift (IfStatement vs BlockStatement field order varying with type-assertion site).
3. mrIsLiteralTrue / mrHasBreak / one of the helpers returns wrong boolean in native, causing a case to be misclassified.

Bottom line

#597 is not a quick fix. Needs dedicated LLDB session. #585 remains blocked until root-caused. Suggest whoever picks this up starts by dumping the full desugared transformExpression AST from native (bypassing the type-assertion-sensitive struct access I hit), not from node.

[cs01]

Fixed in #603 (merged as aaf7ac84). Helper-extraction approach: moved the void-check logic out of the switch case into transformUnaryExpressionOrVoid, keeping the case body as a single statement. This avoids the bare-case-decl pattern that triggered parser-native's dropped-trailing-return bug.

What's still open (tracked in this issue's comments, not fixed yet): the underlying tree-sitter / parser-native iteration quirk where namedChildCount reports 3 instead of 4 for case X: const; if(..) return; return;. The helper extraction works around that; #601 filed as the semantic-guard followup to reject the pattern at compile-time so future bare-case-decl doesn't re-trigger this class.

Unblocks #585 (net TCP module) and future stdlib expansion.