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¶
- 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).ObjectCallsand the wrappers also reference each other (the desktop facade importsNode,Area2D, …). A KMP module that holds the shared tree and itsactual ObjectCallsis therefore not the design's "small reversible module": it is the root runtime and:ios-runtimefolded into one multiplatform build, which the design explicitly deferred. java.lang.foreign.MemorySegmentis the public handle type. Every wrapper constructor takes it (1,041 files; 628MemorySegment.NULLuses in generated bodies). iOS compiles because a shim class in the same package exists in its own source set. In a KMPcommonMainthat JDK package cannot be declared orexpected; 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:GodotHandleis now a per-platform@JvmInline value classunder one fully-qualified name, and no public wrapper or script signature names ajava.lang.foreigntype any more. Closed by task 104 step 3 (parcel A): the shared tree names nojava.lang.foreigntype at all — the raw pointer isnet.multigesture.kanama.binding.runtime.RawSegment(plus a top-levelNULL_SEGMENT), a plaintypealiasper platform that parcel C turns intoexpect/actual, andGodotHandleis one shared file over it.- Value types are hand-written and diverged per platform. The 18 shared
types/*.ktnames differ in about 2,400 lines (desktop uses PanamaArenaandValueLayoutplus method-bind calls; iOS usesBuiltinCalls);Vector4iexists only on desktop; iOS carries a hand-writtenReal.ktwhere 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 undersrc/commonMain/kotlin/net/multigesture/kanama/types(public surface = the union of the two it replaced,Vector4iincluded), reaching the engine only through theBuiltinCallsfacade, which exists once per platform under one fully-qualified name. Task 104 step 3 parcel C' made it anexpect object, so the compiler keeps the two identical and the Python contract gate is deleted.Real.ktis now a generated common file plus a JVM-onlyGodotRealSegmentfor 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¶
- 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.
- 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-loudUnsupportedOperationExceptionbodies on iOS for un-audited shapes (rejected by the design's no-stub rule andcheck_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. - 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-runtimeas aniosMainsource 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.ktcompanions, 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.ktdesktop 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:
@JvmStaticon every platform (Kotlin/Native accepts the@OptionalExpectationannotation),Node.createTween()openon both, the iOSGodotObjectno longerAutoCloseable(the generated iOSRefCounteddeclares it), iOSRefCounted.unreference()internal,@ManualGodotLifetimeApigone from the generated iOSclose(). - 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
installAddonJar60 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/actualmove, 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
kanamais onekotlin("multiplatform")module withjvm(),iosArm64()andiosSimulatorArm64();:ios-runtimeis 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/actualand the compiler is the contract:expect sealed interface RawSegment { fun address(): Long }+expect val NULL_SEGMENT,expect object BuiltinCalls, and a GENERATEDexpect object ObjectCallscarrying 1,352 of the 1,359 ptrcall helpers the tree calls. Both backends' objects areactual objects withactualon each matching member.scripts/check_builtin_calls_contract.pyis deleted;scripts/check_objectcalls_parity.pystays and gained the one check the compiler cannot make — that the generatedexpectlist 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: acommonMainclass extending ajvmMainclass failscompileKotlinJvmwithUnresolved 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 internalcheckOpen()/requireOpenHandle(). Measured attempt: 93,637 errors oncompileKotlinJvm, 93,616 oncompileKotlinIosArm64. So the tree moved tosrc/sharedApi/kotlinand stays ONE set of sources compiled per platform (and copied for Android), whilesrc/commonMain/kotlinbecame the real common fragment: the value types,GodotHandle, theexpectfiles and the generatedReal.kt. Making those 29 classesexpect/actualis filed as task 117; it is what the design's blocker 1 actually costs. - Seven referenced
ObjectCallshelpers cannot beexpectmembers 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 (anactualmay 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 leadingactualmodifier; its audit now strips block comments as well as line comments and matches declaration keywords by regex instead of the two fragmentsexpect 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/kotlinas acommonMainsource directory, 26 errors, allUnresolved reference, nine distinct names:callWithVariantArgs, the sixObjectCallshelpers whose signatures nameGodotCallable/Material,GodotSignalandMainThread. - The move. The tree (1,010 generated classes +
GodotObject,RefCounted,GodotCallable) lives insrc/commonMain/kotlin/net/multigesture/kanama/api/;src/sharedApiis deleted, thejvmMain/iosMainsource directories are gone, the generator writes tocommonMain, and the Android plugin's single copy ofcommonMain(minus*.expect.kt) carries the tree.compileCommonMainKotlinMetadatacompiles the whole API. - The nine names. All 1,450
ObjectCallshelpers the tree calls areexpectmembers (the six wrapper-typed helpers joined as-is, iOSptrcallWithTypedMaterialListArgnow takesList<Material>;callWithVariantArgslost itsowned = falsedefault — the flag is private on each platform behindcallWithVariantArgsOwned), andcheck_objectcalls_parity.pyfails on any exception.GodotSignal/SignalConnectionareexpect classes andMainThreadanexpect object, each with oneactualper platform; the hand-shaped parity gate (check_wrapper_parity.py) retired with them. Its one-sided-member check — anactualwith a public member the other platform lacks, which the compiler allows — lives on ascheck_actual_public_surface.py, now against theexpect(P4′ review). expectdeclarations 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.pyholds the rule.@JvmStaticon anexpectis not enough on the JVM. With the annotation on theexpect object MainThreadmembers only, K2 compiles with a warning ("Annotation@JvmStaticis 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_WRAPPERSclasses (Tween, Engine, FileAccess, …) extend common classes from platform code; nothing in the tree references them. Generating them once is a follow-up task. TheiosMainmetadata compilation stays disabled: the iOS-only api files still carry@JvmStatic/@JvmName(263@OptionalExpectationerrors in 16 files when re-enabled, nothing else). - Build cost (one Mac, each task alone with
--rerun-tasks --no-build-cacheafter 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).