@@ -387,10 +387,24 @@ All in `PM/commonTest`, so they run wherever the interpreter loads.
   `toString()` of it; `null` stays `None` for `CharSequence?`); a `CharSequence` parameter is still
   declined (#73). `Status: implemented`, `GP/artifact/TextStateBindingTest.kt`,
   `python-multiplatform-compose/fixtures/compose/.../TextFieldStateRenderTest.kt`.
-- **B-2** The walker on **klibs** (Kotlin/Native libraries). `Status: partial`,
-  `GP/artifact/KlibScannerTest.kt` and `python-multiplatform-gradle-plugin/fixtures/klib-artifact` assert that the scanned klib's
-  declarations are declined with reasons; no klib declaration is bound at run time yet. It reads
-  top-level functions only: no class constructor, property or member function (B-1, #215).
+- **B-2** The walker on **klibs** (Kotlin/Native libraries). `Status: partial`. It reads
+  top-level functions only: no class constructor, property or member function yet (B-1, #215).
+  Since #234 a **Kotlin object crosses as a handle**: a type whose class is a public, non-generic,
+  non-value `class`, `interface`, `enum class` or `object` of the walked klib is an `OBJECT` slot
+  or result, non-null or nullable, cast in generated source as the jar producer casts one, and a
+  handle result carries its ancestry from the klib's supertypes. Handles are the common
+  trampoline's and `HandleTable`'s, under the jar side's rules: passing one back into Kotlin takes
+  no second slot, and dropping it releases it exactly once. Still declined, each with its reason:
+  a type of another klib (`kotlin.coroutines.CoroutineContext`), a class of package `kotlin` other
+  than the boundary's primitives, an extension (the pinned compiler's klib ABI has no receiver type),
+  and any `@Deprecated` declaration (the ABI has no level, and a `HIDDEN` one, such as
+  `kotlinx.coroutines.Job0`, cannot be called from source). From `kotlinx-coroutines-core` this binds
+  `Job`, `SupervisorJob`, `MainScope`, `Mutex`, `Semaphore`, `newSingleThreadContext` and
+  `newFixedThreadPoolContext`. `GP/artifact/KlibScannerTest.kt`, `GP/artifact/KlibObjectHandleTest.kt`;
+  `python-multiplatform-gradle-plugin/fixtures/klib-artifact` builds `androidNativeArm64` and
+  `iosSimulatorArm64` from one table in `nativeMain`, and its suite (`WalkedKlibArtifactHandleTest`,
+  `WalkedKlibArtifactTableTest`, `WalkedKlibArtifactPythonImportTest`) runs through Gradle on the iOS
+  simulator (`iosSimulatorArm64Test`); on androidNative it is linked by the build and run by hand.
 - **B-3** Default arguments can be omitted from Python (a call per subset of defaulted parameters,
   ambiguous omissions refused). `Status: implemented`, `GP/artifact/DefaultOmissionTest.kt`,
   `python-multiplatform-gradle-plugin/fixtures/artifact/.../WalkedArtifactDefaultOmissionTest.kt`, `PM/commonTest/.../PythonxDefaultsTest.kt`.
 
@@ -4,17 +4,18 @@
  * go into.
  *
  * `:python-multiplatform-gradle-plugin-fixtures:artifact` is `docs/design/ecosystem.md` §5b's second producer over a **jar** -- this is
- * the same producer over a **klib**, ROADMAP §16e's "investigated, not implemented" half. One target
- * only, and it is `androidNativeArm64` rather than `desktop`: a jar is what a JVM target resolves, a
- * klib is what a Kotlin/Native target resolves, and `PythonArtifactBindingsTask
+ * the same producer over a **klib**. Kotlin/Native targets rather than `desktop`: a jar is what a JVM
+ * target resolves, a klib is what a Kotlin/Native target resolves, and `PythonArtifactBindingsTask
  * .artifactConfiguration`/`.artifactSourceSet` are single-valued (ROADMAP §16f #1) -- one module can
  * wire one walked configuration, so this fixture is the klib producer's own module rather than a
- * second target bolted onto `:artifact`.
+ * second target bolted onto `:artifact`. Since issue #234 it builds `androidNativeArm64` and
+ * `iosSimulatorArm64`: the androidNativeArm64 klib is walked, the table is generated into the shared
+ * `nativeMain`, and the suite in `nativeTest` runs through Gradle on the simulator.
  *
  * `kotlinx-coroutines-core` is the klib walked, for the same reason JUnit is `:artifact`'s: a real,
  * independently-versioned third-party artefact nothing here controls or cooperates with.
  *
- * ### The suite is linked by the build and run by hand
+ * ### On androidNativeArm64 the suite is linked by the build and run by hand (`iosSimulatorArm64Test` runs it)
  *
  * KGP gives `androidNativeArm64` a `linkDebugTestAndroidNativeArm64` and **no run task** -- it
  * registers one only where it knows how to reach a host, and an Android device is neither the build
@@ -38,17 +39,32 @@ plugins {
     id("io.github.thisisthepy.python.multiplatform.bindings")
 }
 
+val pythonDownloadDir = project(":python-multiplatform").layout.buildDirectory.dir("python-standalone").get().asFile
+val fixturePythonVersion = project.findProperty("pythonVersion")?.toString() ?: project.rootProject.version.toString()
+val fixturePythonLibVersion = fixturePythonVersion.split('.').subList(0, 2).joinToString(".")
+
 kotlin {
+    // Applied now rather than after evaluation, so `nativeMain`/`nativeTest` exist for the blocks below
+    // and for `pythonBindings.artifactSourceSet` (issue #234).
+    applyDefaultHierarchyTemplate()
+
     androidNativeArm64 {
         // Mirrors `:python-multiplatform-ksp:fixtures:app`'s own androidNativeArm64 linker config: the test binary needs
         // the same CPython symbols resolved at final link time, since `python-multiplatform`'s klib
         // only declares them via cinterop and does not itself embed a static libpython.
-        val downloadDir = project(":python-multiplatform").layout.buildDirectory.dir("python-standalone").get().asFile
-        val pyVersion = project.findProperty("pythonVersion")?.toString() ?: project.rootProject.version.toString()
-        val libVersion = pyVersion.split('.').subList(0, 2).joinToString(".")
-        val targetExtractDir = "$downloadDir/extracted/$pyVersion/android-aarch64/prefix"
+        val targetExtractDir = "$pythonDownloadDir/extracted/$fixturePythonVersion/android-aarch64/prefix"
         binaries.getTest(org.jetbrains.kotlin.gradle.plugin.mpp.NativeBuildType.DEBUG).linkerOpts.addAll(
-            listOf("-L$targetExtractDir/lib/", "-lpython$libVersion", "-Wl,--allow-shlib-undefined"),
+            listOf("-L$targetExtractDir/lib/", "-lpython$fixturePythonLibVersion", "-Wl,--allow-shlib-undefined"),
+        )
+    }
+    // Issue #234: the simulator target, so the suite runs through Gradle (`iosSimulatorArm64Test`)
+    // rather than only being linked. Linked the way `:python-multiplatform`'s own simulator test
+    // binary is: against the xcframework's simulator slice, with an explicit `-rpath`, because
+    // `Python.framework` has an @rpath-relative install name and is not copied beside the binary.
+    iosSimulatorArm64 {
+        val slice = "$pythonDownloadDir/extracted/$fixturePythonVersion/ios/Python.xcframework/ios-arm64_x86_64-simulator"
+        binaries.getTest(org.jetbrains.kotlin.gradle.plugin.mpp.NativeBuildType.DEBUG).linkerOpts.addAll(
+            listOf("-framework", "Python", "-F$slice", "-rpath", slice),
         )
     }
 
@@ -58,33 +74,47 @@ kotlin {
                 implementation(projects.pythonMultiplatform)
             }
         }
-        val androidNativeArm64Main by getting {
+        // Both native targets share the walked table and the suite (issue #234): the table is
+        // generated into `nativeMain`, and the tests live in `nativeTest`.
+        val nativeMain by getting {
             dependencies {
                 // A real, separately-published klib. Nothing about it knows it is going to be
                 // walked -- KlibScanner reads its ABI the same way it would read anyone else's.
                 implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1")
             }
         }
-        val androidNativeArm64Test by getting {
+        val nativeTest by getting {
             dependencies {
                 implementation(libs.kotlin.test)
             }
         }
     }
 }
 
+// The iOS `Python.framework` carries no standard library; `:python-multiplatform` unpacks the
+// simulator's, and the test binary is pointed at it the way that module points its own.
+tasks.withType<org.jetbrains.kotlin.gradle.targets.native.tasks.KotlinNativeSimulatorTest>().configureEach {
+    dependsOn(":python-multiplatform:extractIosSimulatorStdlib")
+    val pythonHome = project(":python-multiplatform").layout.buildDirectory.dir("python-stdlib/ios-simulator").get().asFile.absolutePath
+    // simctl only forwards variables into the spawned process when they carry this prefix.
+    environment("SIMCTL_CHILD_PYTHONHOME", pythonHome)
+    environment("PYTHONHOME", pythonHome)
+}
+
 pythonBindings {
     role.set("app")
     processor.set(projects.pythonMultiplatformKsp)
 
+    // The androidNativeArm64 klib is walked (what `KlibScannerTest` walks too); the table lands in
+    // `nativeMain`, so the simulator target compiles the same calls against its own klib.
     artifactConfiguration.set("androidNativeArm64CompileKlibraries")
-    artifactSourceSet.set("androidNativeArm64Main")
+    artifactSourceSet.set("nativeMain")
     // Broad on purpose, unlike `:artifact`'s narrow `junit.runner`/`junit.framework`: coroutines'
     // public surface is almost entirely `CoroutineScope`/`Job`/`Flow`-typed extensions, plus a couple
     // of `@PublishedApi internal` declarations that are binary-visible but not source-visible outside
-    // the library that owns them -- none of those are bindable today, so the whole namespace yields
-    // **zero** declarations. `WalkedKlibArtifactTableTest` pins that as the correct number, not a gap:
-    // an earlier version bound the `@PublishedApi internal` one and failed to compile the first time
+    // the library that owns them. Those stay declined; since issue #234 the factories whose types are
+    // the klib's own classes bind (`Job`, `Mutex`, ...), and `WalkedKlibArtifactTableTest` pins the list.
+    // An earlier version bound the `@PublishedApi internal` one and failed to compile the first time
     // its output was actually built rather than only unit-tested -- `KlibScanWorkAction`'s KDoc has
     // the story. See that file's own KDoc for what the walker declines and why.
     artifactIncludePackages.set(listOf("kotlinx.coroutines"))
 
@@ -0,0 +1,84 @@
+package fixture.artifact
+
+import python.multiplatform.ffi.Python3
+import python.multiplatform.ffi.upcall.PythonProxySource
+import python.multiplatform.generated.FunctionTable
+import python.multiplatform.generated.artifacts.ArtifactTable
+import python.multiplatform.reflection.HandleTable
+import python.multiplatform.reflection.ObjectReference
+import python.multiplatform.reflection.UpcallTable
+import python.native.ffi.UpcallEntry
+import kotlin.test.AfterTest
+import kotlin.test.BeforeTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertNotNull
+import kotlin.test.assertNull
+
+/**
+ * Issue #234 on Kotlin/Native: a Kotlin object a walked klib declaration returns crosses as a handle,
+ * goes back into Kotlin as that object, and follows the jar side's lifetime rules -- the common
+ * trampoline's and `HandleTable`'s, which the klib boundary uses unchanged.
+ *
+ * - A handle Python holds is one `HandleTable` slot; passing it back into Kotlin (`Job(parent)`)
+ *   neither releases it nor takes a second slot.
+ * - Dropping every Python reference releases each slot exactly once: the live count returns to its
+ *   baseline, the raw handle no longer resolves, and a second release is refused (no double release).
+ *
+ * Red before #234: `Job` is not importable, because the walker declined every `kotlinx.coroutines`
+ * declaration.
+ */
+class WalkedKlibArtifactHandleTest {
+
+    @BeforeTest
+    fun installTheWalkersTableIntoAnInterpreter() {
+        Python3.initialize(silent = true)
+        UpcallTable.clear()
+        UpcallTable.install(FunctionTable.fragments + ArtifactTable.fragments)
+        val mainGlobals = Python3.import("__main__").getAttr("__dict__")
+        check(UpcallEntry.publish(mainGlobals.pointer)) { "the upcall bootstrap could not be published" }
+        PythonProxySource.install()
+    }
+
+    @AfterTest
+    fun cleanup() {
+        UpcallTable.clear()
+    }
+
+    @Test
+    fun aHandleGoesBackIntoKotlinAndIsReleasedExactlyOnce() {
+        Python3.exec("import gc\ngc.collect()")
+        val baseline = HandleTable.liveCount
+        Python3.exec(
+            """
+            from kotlinx.coroutines import Job
+            _kh_parent = Job(None)
+            _kh_raw = _kh_parent._pm_handle
+            _kh_children = [Job(_kh_parent) for _ in range(3)]
+            assert _kh_parent._pm_handle == _kh_raw, 'passing the handle into Kotlin changed it'
+            """.trimIndent(),
+        )
+        // One slot for the parent and one per child: passing the parent in took no slot of its own.
+        assertEquals(baseline + 4, HandleTable.liveCount)
+        val raw = Python3.import("__main__").getAttr("_kh_raw").toString().toLong()
+        assertNotNull(HandleTable.resolveRaw(raw), "the parent's handle should still resolve while Python holds it")
+
+        Python3.exec("del _kh_parent, _kh_children\nimport gc\ngc.collect()")
+        assertEquals(baseline, HandleTable.liveCount, "every slot is released exactly once")
+        assertNull(HandleTable.resolveRaw(raw), "a released handle must not resolve")
+        assertFalse(HandleTable.release(ObjectReference(raw)), "a second release must be refused")
+    }
+
+    @Test
+    fun aNullableHandleParameterTakesNone() {
+        Python3.exec(
+            """
+            from kotlinx.coroutines import Job
+            _kh_job = Job(None)
+            assert _kh_job is not None
+            del _kh_job
+            """.trimIndent(),
+        )
+    }
+}
@@ -55,30 +55,33 @@ class WalkedKlibArtifactTableTest {
     }
 
     /**
-     * The fixed text: everything `KlibScanner` bound out of the whole `kotlinx-coroutines-core`
-     * klib under the `kotlinx.coroutines` namespace -- nothing, correctly. This class's own KDoc has
-     * the reason; `KlibScannerTest.aRealThirdPartyKlibIsScannedWithoutCrashingAndDeclinesEveryDeclaration`
-     * pins the same fact walking the klib directly rather than through the build. If the two ever
-     * disagree, the wiring between `KlibScanner` and this generated table is what broke.
-     *
-     * A generated fragment file is only ever written when a walked artefact contributes at least one
-     * entry (`PythonArtifactBindingsTask.generate`'s `if (entries.isEmpty()) return@forEach`), so an
-     * empty klib means `ArtifactTable.fragments` itself has zero elements -- not one fragment with an
-     * empty `entries()`.
+     * The fixed text: everything `KlibScanner` bound out of the whole `kotlinx-coroutines-core` klib
+     * under the `kotlinx.coroutines` namespace. Zero before issue #234, when no Kotlin object could
+     * cross the klib boundary; since then the factories whose types are the klib's own classes.
+     * `KlibScannerTest.aRealThirdPartyKlibIsScannedWithoutCrashingAndBindsItsHandleFactories` pins the
+     * same list walking the klib directly; if the two disagree, the wiring between `KlibScanner` and
+     * this generated table is what broke.
      */
     @Test
-    fun theWalkerCorrectlyDeclinesEveryDeclarationInTheKlib() {
-        assertEquals(emptyList(), ArtifactTable.fragments)
+    fun theWalkerBindsExactlyTheKlibsHandleFactories() {
         ArtifactTable.registerInto()
-        assertEquals(emptyList(), UpcallTable.entries())
+        assertEquals(
+            listOf(
+                "kotlinx.coroutines.Job",
+                "kotlinx.coroutines.MainScope",
+                "kotlinx.coroutines.SupervisorJob",
+                "kotlinx.coroutines.newFixedThreadPoolContext",
+                "kotlinx.coroutines.newSingleThreadContext",
+                "kotlinx.coroutines.sync.Mutex",
+                "kotlinx.coroutines.sync.Semaphore",
+            ),
+            UpcallTable.entries().map { it.name }.filter { it.startsWith("kotlinx.") }.sorted(),
+        )
     }
 
-    /**
-     * `registerInto` on an empty `ArtifactTable` must not fail, and must not resolve a name that was
-     * never bound -- the two failure modes a table with zero fragments could otherwise hide.
-     */
+    /** `registerInto` must not resolve a name that was never bound: `checkIndexOverflow` stays declined. */
     @Test
-    fun registeringAnEmptyTableIsHarmlessAndResolvesNothing() {
+    fun aDeclinedNameStillResolvesToNothing() {
         ArtifactTable.registerInto()
         val entry = UpcallTable.resolve("kotlinx.coroutines.flow.internal.checkIndexOverflow")
         assertTrue(!entry.isValid, "checkIndexOverflow must not resolve: it is @PublishedApi internal and must stay declined")