Add explicit script import prep APIs and VM regression tests

lynglib/src/commonMain/kotlin/net/sergeych/lyng/Script.kt

@@ -46,6 +46,28 @@ class Script(
 //    private val catchReturn: Boolean = false,
 ) : Statement() {
     fun statements(): List<Statement> = statements
+
+    /**
+     * Explicitly apply this script's import/module bindings to [scope] without executing the script.
+     * This is intended for embedding scenarios where the host owns scope lifecycle and wants
+     * script-specific imports to be a separate, opt-in preparation step.
+     */
+    suspend fun importInto(scope: Scope, seedScope: Scope = scope): Scope {
+        prepareScriptScope(scope, seedScope)
+        return scope
+    }
+
+    /**
+     * Create a fresh raw module scope and apply this script's import/module bindings to it.
+     * If [seedScope] is provided, its import provider is reused and seed-bound imports resolve from it.
+     */
+    suspend fun instantiateModule(seedScope: Scope? = null, pos: Pos = this.pos): ModuleScope {
+        val provider = seedScope?.currentImportProvider ?: defaultImportManager
+        val module = provider.newModuleAt(pos)
+        prepareScriptScope(module, seedScope ?: module)
+        return module
+    }
+
     override suspend fun execute(scope: Scope): Obj {
         scope.pos = pos
         val execScope = resolveModuleScope(scope) ?: scope
@@ -75,6 +97,19 @@ class Script(
         return ObjVoid
     }
 
+    private suspend fun prepareScriptScope(scope: Scope, seedScope: Scope) {
+        if (importBindings.isNotEmpty() || importedModules.isNotEmpty()) {
+            seedImportBindings(scope, seedScope)
+        }
+        if (moduleSlotPlan.isNotEmpty()) {
+            scope.applySlotPlan(moduleSlotPlan)
+            for (name in moduleSlotPlan.keys) {
+                val record = scope.objects[name] ?: scope.localBindings[name] ?: continue
+                scope.updateSlotFor(name, record)
+            }
+        }
+    }
+
     private suspend fun seedModuleSlots(scope: Scope, seedScope: Scope) {
         if (importBindings.isEmpty() && importedModules.isEmpty()) return
         seedImportBindings(scope, seedScope)

lynglib/src/commonMain/kotlin/net/sergeych/lyng/bytecode/SeedLocals.kt

@@ -36,7 +36,7 @@ internal suspend fun seedFrameLocalsFromScope(frame: CmdFrame, scope: Scope) {
         } else {
             record.value
         }
-        if (value is net.sergeych.lyng.FrameSlotRef && value.refersTo(frame.frame, base + i)) {
+        if (value is net.sergeych.lyng.FrameSlotRef && value.refersTo(frame.frame, i)) {
             continue
         }
         frame.setObjUnchecked(base + i, value)

lynglib/src/commonTest/kotlin/ScriptImportPreparationTest.kt

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2026 Sergey S. Chernov
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import kotlinx.coroutines.test.runTest
+import net.sergeych.lyng.Compiler
+import net.sergeych.lyng.Script
+import net.sergeych.lyng.Source
+import net.sergeych.lyng.obj.toInt
+import net.sergeych.lyng.pacman.ImportManager
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotNull
+import kotlin.test.assertNull
+
+class ScriptImportPreparationTest {
+
+    @Test
+    fun scriptImportIntoExplicitlyPreparesExistingScope() = runTest {
+        val manager = ImportManager()
+        manager.addTextPackages(
+            """
+            package foo
+
+            val answer = 42
+            """.trimIndent()
+        )
+        val script = Compiler.compile(
+            Source(
+                "<prepare-scope>",
+                """
+                import foo
+                answer
+                """.trimIndent()
+            ),
+            manager
+        )
+        val scope = manager.newModule()
+
+        assertNull(scope["answer"])
+
+        script.importInto(scope)
+
+        val record = assertNotNull(scope["answer"])
+        assertEquals(42, scope.resolve(record, "answer").toInt())
+    }
+
+    @Test
+    fun scriptInstantiateModuleUsesSeedScopeImportProvider() = runTest {
+        val manager = ImportManager()
+        manager.addTextPackages(
+            """
+            package foo
+
+            val answer = 42
+            """.trimIndent()
+        )
+        val script = Compiler.compile(
+            Source(
+                "<instantiate-module>",
+                """
+                import foo
+                answer
+                """.trimIndent()
+            ),
+            manager
+        )
+        val seedScope = manager.newModule()
+
+        val module = script.instantiateModule(seedScope)
+
+        val record = assertNotNull(module["answer"])
+        assertEquals(42, module.resolve(record, "answer").toInt())
+    }
+}

lynglib/src/commonTest/kotlin/SeedLocalsRegressionTest.kt

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2026 Sergey S. Chernov
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import kotlinx.coroutines.test.runTest
+import net.sergeych.lyng.FrameSlotRef
+import net.sergeych.lyng.Pos
+import net.sergeych.lyng.Scope
+import net.sergeych.lyng.bytecode.BytecodeConst
+import net.sergeych.lyng.bytecode.CmdFrame
+import net.sergeych.lyng.bytecode.CmdFunction
+import net.sergeych.lyng.bytecode.CmdVm
+import net.sergeych.lyng.bytecode.seedFrameLocalsFromScope
+import kotlin.test.Test
+import kotlin.test.assertNull
+
+class SeedLocalsRegressionTest {
+
+    @Test
+    fun seedFrameLocalsSkipsSelfReferentialFrameSlotRef() = runTest {
+        val fn = CmdFunction(
+            name = "seed-self-ref",
+            localCount = 1,
+            addrCount = 0,
+            returnLabels = emptySet(),
+            scopeSlotCount = 1,
+            scopeSlotIndices = intArrayOf(0),
+            scopeSlotNames = arrayOf(null),
+            scopeSlotIsModule = booleanArrayOf(false),
+            localSlotNames = arrayOf("x"),
+            localSlotMutables = booleanArrayOf(true),
+            localSlotDelegated = booleanArrayOf(false),
+            localSlotCaptures = booleanArrayOf(false),
+            constants = listOf(BytecodeConst.IntVal(0)),
+            cmds = emptyArray(),
+            posByIp = emptyArray()
+        )
+        val scope = Scope(null, pos = Pos.builtIn)
+        val record = scope.addConst("x", net.sergeych.lyng.obj.ObjInt.of(1))
+        val frame = CmdFrame(CmdVm(), fn, scope, emptyList())
+        record.value = FrameSlotRef(frame.frame, 0)
+        scope.updateSlotFor("x", record)
+
+        seedFrameLocalsFromScope(frame, scope)
+
+        assertNull(frame.frame.getRawObj(0))
+    }
+}