A file's semantics depend on HOW IT WAS REACHED (main / import / load_file) — for-body scoping and top-level `return` both differ

[InauguralPhysicist]

Found by pointing the AOT at the module/load_file splice roads (ouroboros#141/#146). The AOT compiles ahead of time, so it has to know what a construct MEANS before it knows which road the file arrived by — and that turns out to be unanswerable today, because the same file means different things on different roads.

1. A for body binding survives on two roads out of three

Identical three-line file, mp.eigs:

for q in range of 2:
    inner is 5
print of inner

reached as	result
main program (eigenscript mp.eigs)	prints 5, exit 0
import mp	Error line 3: undefined variable "inner", exit 1
load_file of "mp.eigs"	prints 5, exit 0

The module road also drops it from the module dict (keys of M omits inner, M.inner is null) — self-consistent with the error, but not with the other two roads.

2. Top-level return has three meanings, one per road

reached as	meaning
main program	end the program, exit 0, returned value discarded
imported module	end the module; bindings below it never come into existence
load_file target	end THAT FILE only, yield its value to the load_file call, caller continues

Each is defensible alone. Together they mean a file cannot be understood without knowing its caller.

Why this is worth changing rather than documenting

EigenScript is pre-v1 with no external consumers, so this is a design decision that can still be made once rather than lived with. Concretely, road-dependence costs:

• The AOT cannot compile two of the three roads. Both are now refused loudly (ouroboros#146). A module or load_file target using either construct is outside the AOT envelope entirely — not because the construct is hard, but because its meaning is not a property of the file.
• It is invisible to testing. Every one of these behaviours is individually sensible and individually tested; only the cross-road comparison shows the disagreement, and nothing was comparing roads.
• It blocks static tooling generally, not just the AOT — a linter, an LSP, or a docs generator asking "what does this module export?" has the same problem the AOT has.

Suggested direction (not a demand — the shape matters more than my guess)

A file`s top level should mean one thing regardless of arrival:

• for should scope its body consistently on all three roads (either it leaks everywhere or nowhere; ouroboros measured that if/loop while/try/match case all leak and only for does not, which is itself worth a second look).
• Top-level return should uniformly end THE CURRENT FILE and yield its value; the main-program case is then just the outermost file, and "exit 0, value discarded" falls out of nobody consuming the outermost value.

That rule is compilable, which the current one is not.

Provenance

Fourteen blind-critic rounds against the AOTs import/splice implementation. Rounds 9-12 were all the same underlying question — the module dict is "a snapshot of what RAN", so a static walk cannot reproduce it — and rounds 13-14 found the return` roads. The consumer-forces-the-language loop applies to the AOT as much as to any other consumer: the AOT shows what has to be TRUE in the VM for compilation to be possible at all.

[InauguralPhysicist]

Third instance, and the one with a measurable cost: load_file resolves CWD-relative first, so a program means different things depending on the directory you invoke it from.

A/inc.eigs   print of "SCRIPTDIR-COPY"
B/inc.eigs   print of "CWD-COPY"
A/prog.eigs  load_file of "inc.eigs"

cd A && eigenscript prog.eigs	SCRIPTDIR-COPY
cd B && eigenscript ../A/prog.eigs	CWD-COPY

Same program text, same relative path, different file loaded.

This one is not merely awkward to compile — it is structurally impossible, and it costs the AOT its main lever. Compiled from A, the binary prints SCRIPTDIR-COPY from either directory; the VM run from B prints CWD-COPY. Both exit 0, so it is a silent wrong answer:

run from B     VM: CWD-COPY      AOT: SCRIPTDIR-COPY      both rc 0

A compiler cannot know the runtime working directory. The only way for the AOT to match is to keep EVERY load_file as a runtime interpreted call — which is precisely what ouroboros#129 removed in order to make DMG fast, back when 2,470 of its 3,288 lines were being interpreted rather than compiled. So the cwd-first rule is not a corner case for the AOT; it makes static splicing unsound in general and only accidentally correct today (nothing in the ecosystem ships a shadowing copy).

Suggested direction, same shape as the other two: resolve load_file relative to the SOURCE FILE, with the stdlib/exe-dir step after it, and drop cwd from the chain. That makes a file`s dependencies a property of the file — which is what every other language does, and what makes them statically resolvable. If cwd-relative loading is wanted deliberately, it should be an explicit distinct form rather than the first step of the default chain.

Measured on the current tree, 2026-08-29.

[InauguralPhysicist]

Fourth instance, from blind-critic round 32 on the AOT — and this one varies by BOTH nesting depth and binding kind.

A for binder over an existing binding:

binding	context	post-loop value
local x is 7	nested define	7 — binder loop-scoped
local x is 7	top-level define	2 — binder persists
parameter d	nested define	2 — binder persists

Identical function body, 15 as a nested define and 10 as a top-level one:

define b(d) as:
    local x is 7
    for x in [1, 2]:
        d is d + x
    return d + x

Measured on the current tree, 2026-08-30. The AOT refuses the nested-local
shape loudly (ouroboros round 32) since it emits one C variable in every case
— but as with the other three instances, the refusal is a guard against a rule
that is well-defined dynamically and inconsistent statically, and should be
deleted rather than improved if a uniform binder-scoping rule lands.

[InauguralPhysicist]

Fifth row for the binder-scoping table, from round 34: the loop-scoping rule for a for binder applies to a define nested in ANY block, not only in a function — a define inside a module-level if also gets loop-scoped binders (prints 15, the module global stays 7).

The AOT currently holds parity there by accident of a different limit (a main-body func inside a block has no emit case, so it refuses loudly). Recording it so the rule is stated correctly: "nested in any block", keyed on depth, with the define's own parameter as the single persisting kind.

[InauguralPhysicist]

Sixth row, from ouroboros round 40 — and this one depends on a NON-LOCAL fact.

A for binder over a function PARAMETER: post-loop, the identical function
gives

module context	f of 1 returns
no module x	8 — binder persists in the param
x is 5 at module scope	1 — binder loop-scoped

define f(x) as:
    for x in [7, 8]:
        local q is x
    return x

The binder's scoping is decided by whether a same-named binding exists in a
scope the function never touches. (The tape rows are their own asymmetry:
binder writes record on the name history in every configuration, while plain
param assignments never do.)

The AOT refuses the shadow configuration loudly (one C variable cannot express
both halves) and had been silently wrong on it since for-unboxing existed —
VM 1|5 vs AOT 8|5, both rc 0, discovered only when a tape fixture happened to
combine the shadow with a binder. Same standing note: delete the guard rather
than improve it if a uniform rule lands.

[InauguralPhysicist]

Landed in #1106 (squash e1b61ad), 6 blind-critic rounds across two model families (Fable + GPT-6 Astra), both critics dry at round 5.

Resolution is now a property of the file, never the process cwd: absolute → containing file's directory → eigs_modules walk → nearest eigs.json project root → stdlib exe-relative → ~/.local/lib/eigenscript; the bare cwd try and the <base>/.. hack are gone, and a failed resolution names what was tried. Chosen over source-relative by census (929 literal load_file targets ecosystem-wide, 821 repo-root-relative). A for body's is at module top level now binds in module scope on every road; top-level return documented and cross-road-fixtured as "end the current file, yield its value".

Two feature bugs surfaced by the rounds and fixed twinned across sites: eval provenance inside an imported module (OP_IMPORT + eigs_eval_file); an import-road for-body write to an existing loop-local (VM + JIT inline fast path). Plus a flaky planted-race control (#1107) and a CI-only harness assuming the make layout.

Consumer sweep before merge broke 5/16 on latent cwd-dependence (polymethod, liferaft, iLambdaAi, ouroboros, tidelog); all repaired with eigs.json project-root markers (tidelog also a hermetic determinism driver), pushed to their mains, green on both v0.42.0 and the new runtime ahead of the pin bump.

The ouroboros AOT/tooling guards that refuse these constructs as the EigenScript#1056 class can now be revisited — resolution and for-body module scoping are uniform.