# Plan: Eliminate Scope Slots for Module + Extensions (Frame-Backed Only)

Goal (1 + 2)
- Module-level vars must be frame-backed just like locals; no special scope storage.
- Extension wrappers must use frame slots as well; no scope-slot storage.
- Scope remains only as a facade for Kotlin extern symbols (reflection/interop), not as primary storage.

Non-Goals (for now)
- Full reflection redesign (set aside).
- Removing scope slots entirely (interop/reflection may still need a facade).

Current Findings (high level)
- BytecodeCompiler still builds scope slots for module symbols and for extension wrappers via pendingScopeNameRefs.
- CmdRuntime reads/writes scope slots whenever slot < scopeSlotCount.
- RESOLVE_SCOPE_SLOT + addr slots are emitted for moving between scope and frame slots.

Design Direction
- Frame slots are the sole storage for module vars and extension wrappers.
- Scope slots are reserved for explicit extern/interop names only (not part of this change).
- Module symbols are captured like any other (closure capture via FrameSlotRef), no module slot plan or scope slot mapping.
- Persist the module frame inside ModuleScope so its lifetime matches the module.

Key Decisions
- Module scope is just another frame in the parent chain; do not seed or persist module vars through scope slots.
- Extension wrappers are treated like ordinary locals/globals in frame slots; no pending scope name refs.
- Compatibility: when `seedScope` is not a `ModuleScope`, module-level declarations still map to scope slots so `Scope.eval(...)` retains cross-call variables.

Work Plan

Phase A: Compiler changes (scope slot creation)
1) Stop adding module declarations to scope slots
   - In `BytecodeCompiler.collectScopeSlots`, when `moduleScopeId` matches a declaration, treat it as a local slot, not a scope slot.
   - Remove `isModuleDecl` special-casing that pushes into `scopeSlotMap`.

2) Remove synthetic scope slots for extension wrappers
   - Gate `pendingScopeNameRefs` (extension callable/getter/setter queueing) behind explicit scope-slot usage.
   - Ensure extension wrappers are resolved via local slot indices only (frame-backed).

3) Tighten scope-slot eligibility
   - `isModuleSlot(...)` should no longer route module names to scope slots.
   - Only names in `allowedScopeNames` / `scopeSlotNameSet` (extern/interop) should become scope slots.

4) ResolveSlot prefers frame slots for everything
   - Update `resolveSlot` to pick local slots for module/extension names.
   - Only return scopeSlotMap entries for explicit extern/interop names.

Phase B: Runtime changes (module frame)
1) Persist the module frame inside ModuleScope
   - Add `ModuleScope.ensureModuleFrame(fn)` that creates/reuses a `BytecodeFrame` with `fn.localCount`.
   - Store local slot metadata on ModuleScope for future interop (names/mutables/delegated).

2) Use the module frame when executing the module bytecode
   - `CmdFrame` should reuse the module frame when `scope0 is ModuleScope` and args are empty.
   - Avoid clobbering module locals with args.

3) Remove module seed path that depends on scope slots
   - Remove `moduleSlotPlan` application in `Script.execute`.
   - Keep `seedImportBindings` and `seedModuleLocals`, but write into the module frame (scopeSlotCount should be 0).

Phase C: Bytecode + ABI considerations
1) No new opcodes required for (1) + (2)
   - If we later need persistence across module reloads, introduce explicit sync opcodes (requires approval).

2) Migration safety
   - Keep existing scope-slot ops for interop only; do not delete opcodes yet.

Detailed Change List (by file)
- `lynglib/src/commonMain/kotlin/net/sergeych/lyng/bytecode/BytecodeCompiler.kt`
  - `collectScopeSlots`: treat module declarations as locals; do not map into `scopeSlotMap`.
  - Remove/guard `pendingScopeNameRefs` queuing for extension wrappers.
  - `isModuleSlot`: stop routing by moduleScopeId; only allow for explicit interop names.
  - `resolveSlot`: prefer local slots; avoid scope slot fallback for module/extension names.

- `lynglib/src/commonMain/kotlin/net/sergeych/lyng/Script.kt`
  - Remove module slot plan application that assumes scope slots.
  - Ensure module vars survive via frame capture rather than scope seeding.

- `lynglib/src/commonMain/kotlin/net/sergeych/lyng/ModuleScope.kt`
  - Add module frame storage + metadata and `ensureModuleFrame(fn)`.

- `lynglib/src/commonMain/kotlin/net/sergeych/lyng/bytecode/CmdRuntime.kt`
  - Use module frame when `scope0 is ModuleScope` in `CmdFrame`.

Testing / Validation
- Disassemble compiled modules: verify no `RESOLVE_SCOPE_SLOT` for module vars or extension wrappers.
- Run `:lynglib:jvmTest` and at least one module script execution that references module vars across calls.
- Verify extension call wrappers still resolve and invoke correctly without scope-slot backing.

Risks / Open Questions
- Module persistence: if module vars were previously “persisted” via scope slots, confirm frame-backed storage matches desired lifetime.
- Extension wrapper lookup: ensure name resolution does not rely on scope slot indexing anywhere else.

Approval Gates
- Any new opcode or runtime sync step must be proposed separately and approved before implementation.