lyng/notes/plan_scope_slots_elimination.md

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.