Skip to content

Shared Wrapper Tree: Design Check

Kanama shipped two committed generated wrapper trees for the native backends: desktop/Android under src/main/kotlin/net/multigesture/kanama/api and iOS under ios-runtime/src/iosMain/kotlin/net/multigesture/kanama/api (today: one tree under src/commonMain/kotlin/net/multigesture/kanama/api, KMP common code, and neither of those modules exists any more — see the 2026-09-15 and 2026-10-01 sections at the end). The task-21 design ("commonMain unification") proposed one shared tree with an expect/actual ObjectCalls seam; the drift gate landed, the physical move did not. Task 103 re-opened the move. This page records what the code said when the move was checked (2026-09), so the next attempt starts from facts instead of the design's assumptions. Nothing here changes behaviour.

What the two trees are today

Desktop/Android tree iOS tree
Files 1,053 (988 generated, 47 hand-shaped, 18 non-API) 1,029 (1,013 generated, 8 hand-shaped, 3 collision-class files; 9 more collision classes live in IosGodotApi.kt)
Lines 302,193 181,056, plus 26,677 generated iOS ObjectCalls helpers (a separate ObjectCallsGenerated.kt then; the GENERATED MEMBERS region of the iOS ObjectCalls.kt since task 104 step 3b)
Generated on both platforms 979 classes
Identical after stripping KDoc and the iOS wildcard import 0 of 979

Of the 979 shared generated classes, 691 differ only because the iOS emitter omits @JvmStatic. The other 288 differ in method set: 1,178 methods across 279 classes are emitted on desktop and skipped on iOS because their ptrcall helper shape is not audited there (510 distinct ObjectCalls helpers, 893 call sites). That subset is real, deliberate (IOS_AUDIT_ONLY), and gated; it is not drift. But one tree means one method set, so it is the first thing a merge has to answer.

Blockers the design named, and what the code says

Blocker Verdict
Android consuming expect/actual through the source remap Not a blocker. prepareAndroidKanamaSources already copies kanama-common-api's commonMain minus the expect file and strips actual from the JVM actual. A new root is one more from(...) block; the audit's forbidden fragments (expect class, actual class) need object variants added.
iOS KDoc stripping Not a blocker. KDoc is owned by sync_kdoc_from_godot_docs.py and stripped by the drift gate's comparable_source; emitting it once is a flag, not a design problem.
iOS collision classes and the two hand-shaped lists Not a blocker, but larger than "~55". The union of DESKTOP_HANDSHAPED (47), IOS_HANDSHAPED (8), IOS_HANDWRITTEN_COLLISION_CLASSES (12) and IOS_UNSUPPORTED_CLASSES (2) is 56 classes that need a per-platform file. 34 desktop hand-shaped classes are generated on iOS and 5 iOS hand-shaped ones are generated on desktop, so "per-platform variant" often means "generated on one side, hand-written on the other", not two hand files.
Node.createTween() openness Not only openness. iOS SceneTree is a Node subclass that overrides createTween(); desktop SceneTree is an object facade with @JvmStatic createTween(). Node is hand-shaped on desktop and generated (with an iOS custom section) on iOS, so it is a per-platform file either way; making it open on both is a one-word alignment once the trees merge.
iOS-only GodotObject : AutoCloseable and public unreference() Independent of the tree move. Historical (until task 117 P3′): both lived in per-platform base files (GodotObject.kt / IosGodotApi.kt), so aligning them was a small standalone change (task 97 R10c). Task 117 P3′ wrote GodotObject and RefCounted once in the shared tree (then src/sharedApi, src/commonMain since P4′); unreference() is gone.
Two-tree assumptions in tooling Real but mechanical. check_wrapper_generator.py (API_DIR/IOS_API_DIR, two exemption sets), upgrade_godot.sh step 5, check_ios_no_silent_stubs.py, api_wrapper_coverage.py; sync_kdoc_from_godot_docs.py only knows the desktop tree.

Blockers the design did not name

  1. The dependency closure is the whole runtime. Starting from the generated wrappers alone, transitive references reach 1,087 of the 1,096 files under src/main/kotlin (99 %): GodotObject → ScriptBridge, ObjectCalls → GodotFFI, hand-shaped wrappers → KanamaScript; on iOS 1,050 of 1,056 (ObjectCalls → KanamaIosRuntime). ObjectCalls and the wrappers also reference each other (the desktop facade imports Node, Area2D, …). A KMP module that holds the shared tree and its actual ObjectCalls is therefore not the design's "small reversible module": it is the root runtime and :ios-runtime folded into one multiplatform build, which the design explicitly deferred.
  2. java.lang.foreign.MemorySegment is the public handle type. Every wrapper constructor takes it (1,041 files; 628 MemorySegment.NULL uses in generated bodies). iOS compiles because a shim class in the same package exists in its own source set. In a KMP commonMain that JDK package cannot be declared or expected; the shared tree would have to switch every public signature to a Kanama-owned handle type, a source-visible API change the design did not cost. Resolved by task 104 step 1: GodotHandle is now a per-platform @JvmInline value class under one fully-qualified name, and no public wrapper or script signature names a java.lang.foreign type any more. Closed by task 104 step 3 (parcel A): the shared tree names no java.lang.foreign type at all — the raw pointer is net.multigesture.kanama.binding.runtime.RawSegment (plus a top-level NULL_SEGMENT), a plain typealias per platform that parcel C turns into expect/actual, and GodotHandle is one shared file over it.
  3. Value types are hand-written and diverged per platform. The 18 shared types/*.kt names differ in about 2,400 lines (desktop uses Panama Arena and ValueLayout plus method-bind calls; iOS uses BuiltinCalls); Vector4i exists only on desktop; iOS carries a hand-written Real.kt where desktop generates one at build time. The design listed value types as "shared in commonMain" as if they were generated. Under KMP they need their own unification first; under a shared source directory they stay per platform. Resolved by task 104 step 2: the 19 value types are one hand-written set under src/commonMain/kotlin/net/multigesture/kanama/types (public surface = the union of the two it replaced, Vector4i included), reaching the engine only through the BuiltinCalls facade, which exists once per platform under one fully-qualified name. Task 104 step 3 parcel C' made it an expect object, so the compiler keeps the two identical and the Python contract gate is deleted. Real.kt is now a generated common file plus a JVM-only GodotRealSegment for its Panama accessors.

Two mechanisms, and what each costs

(a) KMP commonMain + expect/actual ObjectCalls, per the design. Requires: root and :ios-runtime become one KMP module (blocker 1); a Kanama handle type replaces MemorySegment in public signatures (blocker 2); value types are unified or expected (blocker 3); the desktop 40k-line hand-written ObjectCalls gains actual on ~1,400 members with reconciled parameter names (getSingleton(name) vs getSingleton(className) today); the iOS generated extension helpers become members of the actual object. Gains a compiler-checked contract declaration. Done by task 104 step 3 parcel B (the keywords excepted): all 1,359 helpers the shared tree calls are members of object ObjectCalls on both platforms with the same parameter names in the same order, desktop's being canonical — the 1,384 generated iOS helpers now land as members in the GENERATED MEMBERS region of the iOS ObjectCalls.kt instead of as extensions in a separate file, and scripts/check_objectcalls_parity.py proves it on every local_ci run (0 deltas).

(b) One shared source directory compiled by each platform module. The generator emits one file per class into a shared root; the root JVM module and :ios-runtime add that root as a srcDir; Android's copy task adds it as one more from(...). Each platform compiles the shared files against its own ObjectCalls, types, and MemorySegment, exactly as Android already does with the desktop tree. No KMP change, no public type change, per-platform value types untouched. The "contract" is enforced by each platform's compile (a shared wrapper calling a helper iOS lacks fails compileKotlinIosArm64) rather than by an expect declaration. Loses the declaration; keeps everything else the design wanted (one tree, no copies, single-tree drift gate, KDoc emitted once).

Either way the 1,178 desktop-only methods need a home before any file is shared.

What has to be decided before the move starts

  1. Mechanism: (a) or (b). Recommendation: (b). It is the only shape that fits without a runtime-wide build rewrite, and it is the shape Android has used successfully for every release.
  2. The 1,178 desktop-only methods (279 classes). Options: audit the 510 missing iOS helper shapes first (C shim, Kotlin/Native helper, self-test rows, device gate; the honest prerequisite, and the reason task 21's exit criteria were never met); or emit them into a per-platform companion file (<Class>.jvm.kt, extension members over the shared class) so the shared tree holds the audited intersection and the desktop-only surface is explicit, drift-gated, and shrinks as shapes are audited; or emit fail-loud UnsupportedOperationException bodies on iOS for un-audited shapes (rejected by the design's no-stub rule and check_ios_no_silent_stubs.py); or drop them from desktop (rejected: public API regression). Recommendation: the companion-file split now, the shape audit as its own funded task.
  3. Only under (a): the public handle type, the value-type unification, and the root-to-KMP conversion each need their own decision.

Alignments that need no decision and can land with the move: emit @JvmStatic on iOS too (kotlin.jvm.JvmStatic is declared @OptionalExpectation in the common stdlib, like the @JvmName the iOS tree already carries; confirm with compileKotlinIosArm64 when adopting); one hand-shaped table with platform tags in check_wrapper_generator.py; Node.createTween() open on both platforms; iOS GodotObject aligned with desktop (not AutoCloseable; RefCounted is) and its unreference() hidden.

What was done (2026-09, task 103)

Mechanism (b) landed; (a) stays the long-term target and is filed separately.

  • One generated tree, src/commonMain/kotlin/net/multigesture/kanama/api (979 classes), compiled by the root JVM module, by :ios-runtime as an iosMain source root, and by the Android plugin through the PanamaPort copy. The iOS copies are gone; iOS keeps 54 files (8 hand-shaped, 34 iOS-only generated, 3 collision-class files, 4 <Class>.ios.kt companions, 5 non-API).
  • The shared file holds the members both backends can call. The 1,178 desktop-only methods became extension members in 277 <Class>.jvm.kt desktop companions (1,274 members with the desktop-only properties; 494 helper shapes waited on), each headed by the helpers it waits on, all listed in the generated iOS Shape Gap page. 99 properties are read-only in the shared tree because only their setter is desktop-only. A script that calls a companion member imports it by name (import net.multigesture.kanama.api.getUsedCells); eight demo scripts needed that (kanama-demos#48). No wildcard imports.
  • One platform-tagged table, PER_PLATFORM_WRAPPERS (56 classes), replaced the two hand-shaped lists and the collision/unsupported registries.
  • The gate is single-tree (check_single_tree) and runs in-process: about 5 s instead of 57 s.
  • The alignments: @JvmStatic on every platform (Kotlin/Native accepts the @OptionalExpectation annotation), Node.createTween() open on both, the iOS GodotObject no longer AutoCloseable (the generated iOS RefCounted declares it), iOS RefCounted.unreference() internal, @ManualGodotLifetimeApi gone from the generated iOS close().
  • Measured before → after (one run each, same machine, clean builds, Gradle build cache off): wrapper sources 2 trees / 2,082 files / 483,249 lines → 3 directories / 1,384 files / 326,999 lines (shared 233,944; desktop 73,482 of which companions 22,189; iOS 19,573); drift gate 57.5 s → 4.7 s; clean desktop installAddonJar 60 s → 73 s (277 more Kotlin files), warm 4.6 s → 5.7 s; iOS klib 46.5 s → 46.3 s; iOS debug static link 106 s → 103 s.
  • Not done, by decision: the audit of the missing iOS helper shapes (its own task; each family that lands moves its members back into the shared file on the next regen), and the KMP expect/actual move, which still needs everything listed under (a) above.

What was done (2026-09-15, task 104 step 3 parcels C+D)

Mechanism (a) landed for the SEAMS; the tree itself stays mechanism (b), and the reason is measured rather than assumed.

  • One module. Root kanama is one kotlin("multiplatform") module with jvm(), iosArm64() and iosSimulatorArm64(); :ios-runtime is deleted and its cinterop, static lib, per-target script dirs and per-target KSP moved to the root. src/main/kotlin → src/jvmMain/kotlin, src/test → src/jvmTest, ios-runtime/src/iosMain/kotlin → src/iosMain/kotlin.
  • The seams are expect/actual and the compiler is the contract: expect sealed interface RawSegment { fun address(): Long } + expect val NULL_SEGMENT, expect object BuiltinCalls, and a GENERATED expect object ObjectCalls carrying 1,352 of the 1,359 ptrcall helpers the tree calls. Both backends' objects are actual objects with actual on each matching member. scripts/check_builtin_calls_contract.py is deleted; scripts/check_objectcalls_parity.py stays and gained the one check the compiler cannot make — that the generated expect list still equals the set of helpers the tree calls.
  • The generated tree is NOT commonMain, and that is the finding. K2 resolves a source file in the common fragment against common code ONLY, inside every platform compilation and not just the metadata one (isolated repro: a commonMain class extending a jvmMain class fails compileKotlinJvm with Unresolved reference). The tree is not self-contained: its 979 classes extend and call the hand-shaped per-platform wrappers — GodotObject, Node, Node3D, RefCounted, Resource, Material, Image, Font, … 29 classes, 2,695 desktop vs 2,572 iOS members, 2,498 same-named — plus their internal checkOpen() / requireOpenHandle(). Measured attempt: 93,637 errors on compileKotlinJvm, 93,616 on compileKotlinIosArm64. So the tree moved to src/sharedApi/kotlin and stays ONE set of sources compiled per platform (and copied for Android), while src/commonMain/kotlin became the real common fragment: the value types, GodotHandle, the expect files and the generated Real.kt. Making those 29 classes expect/actual is filed as task 117; it is what the design's blocker 1 actually costs.
  • Seven referenced ObjectCalls helpers cannot be expect members and are the parity gate's documented exceptions: six name a hand-shaped platform class in their signature (GodotCallable, Material) and one carries a default argument, which no lane can express (an actual may not restate a default, and the Android copy has no common fragment at all).
  • The Android remap learned decision D's two rules: skip *.expect.kt, strip a leading actual modifier; its audit now strips block comments as well as line comments and matches declaration keywords by regex instead of the two fragments expect class / actual class.

What was done (2026-10-01, task 117 P4′)

Mechanism (a) landed for the tree too: the API wrapper tree is KMP common code.

  • The blocker shrank to nine names. Task 117 P1′–P3′ generated the hand-shaped classes once and wrote the three roots once, so the 93,637 errors above became, in a throwaway rewiring of src/sharedApi/kotlin as a commonMain source directory, 26 errors, all Unresolved reference, nine distinct names: callWithVariantArgs, the six ObjectCalls helpers whose signatures name GodotCallable/Material, GodotSignal and MainThread.
  • The move. The tree (1,010 generated classes + GodotObject, RefCounted, GodotCallable) lives in src/commonMain/kotlin/net/multigesture/kanama/api/; src/sharedApi is deleted, the jvmMain/iosMain source directories are gone, the generator writes to commonMain, and the Android plugin's single copy of commonMain (minus *.expect.kt) carries the tree. compileCommonMainKotlinMetadata compiles the whole API.
  • The nine names. All 1,450 ObjectCalls helpers the tree calls are expect members (the six wrapper-typed helpers joined as-is, iOS ptrcallWithTypedMaterialListArg now takes List<Material>; callWithVariantArgs lost its owned = false default — the flag is private on each platform behind callWithVariantArgsOwned), and check_objectcalls_parity.py fails on any exception. GodotSignal/SignalConnection are expect classes and MainThread an expect object, each with one actual per platform; the hand-shaped parity gate (check_wrapper_parity.py) retired with them. Its one-sided-member check — an actual with a public member the other platform lacks, which the compiler allows — lives on as check_actual_public_surface.py, now against the expect (P4′ review).
  • expect declarations carry no default argument (D24): the Android copy skips *.expect.kt, so a default would vanish there. GodotSignal's defaults became overloads; check_expect_no_defaults.py holds the rule.
  • @JvmStatic on an expect is not enough on the JVM. With the annotation on the expect object MainThread members only, K2 compiles with a warning ("Annotation @JvmStatic is missing on actual declaration") and the JVM class has no static methods. D6's fallback applies: the annotation is on the expect and mirrored on both actuals.
  • Still per platform, and legal: the 24 PER_PLATFORM_WRAPPERS classes (Tween, Engine, FileAccess, …) extend common classes from platform code; nothing in the tree references them. Generating them once is a follow-up task. The iosMain metadata compilation stays disabled: the iOS-only api files still carry @JvmStatic/@JvmName (263 @OptionalExpectation errors in 16 files when re-enabled, nothing else).
  • Build cost (one Mac, each task alone with --rerun-tasks --no-build-cache after a warm-up, task time from Gradle's --profile; task 104's parcel-E spike numbers, from another machine, for scale):
task 104 parcel E (spike, machine C) before (main 689960f8) after (task 117 P4′)
compileKotlinJvm 34 s 54.97 s (76 s wall) 51.32 s (73 s wall)
compileKotlinIosArm64 29 s 34.27 s (58 s wall) 36.47 s (62 s wall)
linkDebugStaticIosArm64 75 s 113.75 s (171 s wall) 121.55 s (182 s wall)
linkReleaseStaticIosArm64 — 529.94 s; 1,506.08 s on a re-run 1,269.73 s; 1,071.76 s on a re-run
installAddonJar (whole build) — 93.89 s (95 s wall) 82.63 s (83 s wall)
libkanama_ios_runtime.a debug 224.8 MiB 235,775,424 B (224.9 MiB) 236,065,128 B (225.1 MiB)
libkanama_ios_runtime.a release — 124,719,880 B (118.9 MiB) 124,691,160 B (118.9 MiB)
kanama.jar 11.6 MiB 12,245,507 B (11.68 MiB) 12,247,869 B (11.68 MiB)

The compile, debug-link and install numbers move within run-to-run noise, and the artifacts are the same size to 0.12 %. The release link is not comparable on this machine: the same baseline commit took 530 s once and 1,506 s on a re-run, tracking background load (load average 5–9 during the slow runs; a first after-run of installAddonJar under the same load took 1,439 s and was re-run). Commands: ./gradlew --no-daemon -Pkotlin.compiler.execution.strategy=in-process --no-build-cache --rerun-tasks --profile <task> (installAddonJar with -PkanamaProjectDir=<checkout>/example_project).