Merge remote-tracking branch 'origin/develop' into work/compose-host

# Conflicts:
#	ksp-fixtures/compose/src/desktopMain/kotlin/fixture/compose/PythonComposition.kt

Author: b-re-w

AGENTS.md

@@ -160,7 +160,8 @@ interoperability in both directions:
 | `binary/` | Source archives of per-platform CPython distributions |
 | `python_for_kotlin_binding.mermaid` | User-authored sketch of the object model (see rule 14) |
 | `docs/INTENT.md`, `docs/SPEC.md` | Intent and behavioural contract (rule 5) |
-| `docs/design/`, `docs/platforms/`, `docs/investigations/`, `docs/roadmap/` | Design records, platform notes, investigations, progress log |
+| `docs/design/`, `docs/platforms/`, `docs/investigations/`, `docs/roadmap/` | Current design records (one per topic), platform notes, investigation conclusions, the work left to do |
+| `docs/archive/` | Superseded designs and investigation narratives, kept for history (see its `README.md`) |
 
 ### Source-set hierarchy
 

PROJECT.md

@@ -4,7 +4,7 @@ Kotlin Multiplatform 에 CPython 을 임베딩해 **Kotlin 과 Python 이 서로
 쓰게 한다. 모든 지원 플랫폼에서 같은 방식으로 동작하고, 경계를 넘는 비용을 측정하며 줄인다.
 
 - 의도(경계): [`docs/INTENT.md`](docs/INTENT.md) · 스펙(동작 계약과 상태): [`docs/SPEC.md`](docs/SPEC.md)
-- 에이전트 규정: [`AGENTS.md`](AGENTS.md) · 진척 기록: [`docs/roadmap/ROADMAP.md`](docs/roadmap/ROADMAP.md)
+- 에이전트 규정: [`AGENTS.md`](AGENTS.md) · 남은 작업: [`docs/roadmap/ROADMAP.md`](docs/roadmap/ROADMAP.md)
 
 ---
 
@@ -13,7 +13,7 @@ Kotlin Multiplatform 에 CPython 을 임베딩해 **Kotlin 과 Python 이 서로
 | 방향 | 이름 | 메커니즘 | 상세 |
 |---|---|---|---|
 | Kotlin → Python | **다운콜** | CPython Stable ABI 함수 호출 (`expect` 약 330개) | [`docs/design/downcall-design.md`](docs/design/downcall-design.md) |
-| Python → Kotlin | **업콜** | 빌드 타임 생성 함수 테이블 + 플랫폼별 진입점 1개 | [`docs/design/upcall-design.md`](docs/design/upcall-design.md) |
+| Python → Kotlin | **업콜** | 빌드 타임 생성 함수 테이블 + 플랫폼별 진입점 1개 | [`docs/design/upcall.md`](docs/design/upcall.md) |
 
 ```
             ┌──────────────────────────────────────────┐

README.md

@@ -185,7 +185,7 @@ no per-platform Python → Kotlin binding code. Details: [design notes](docs/des
 
 ## 📊 Status
 
-Honest summary — see the [roadmap](docs/roadmap/ROADMAP.md) for the full record.
+Honest summary — see the [roadmap](docs/roadmap/ROADMAP.md) for what is left to do.
 
 | Area | State |
 |---|---|

benchmarks/cost_table.py

@@ -4,7 +4,7 @@
 
 Why this exists
 ---------------
-`docs/upcall-design.md` and `docs/downcall-design.md` both carry cost tables, and both have been
+`docs/design/upcall.md` and `docs/design/downcall-design.md` both carry cost tables, and both have been
 invalidated at least once by numbers that were transcribed by hand from a run whose conditions were
 not written down next to them. The two failures were:
 

benchmarks/rn-benchmark/COMPARISON.md

@@ -1,7 +1,7 @@
 # React Native's boundary against PythonMultiplatform's, measured the same way
 
 Reference project: `/Volumes/macMini/thisisthepy/PythonMultiplatform`, whose figures below are
-quoted from `docs/upcall-design.md`, `docs/downcall-design.md` and `ROADMAP.md` at the commit
+quoted from `docs/design/upcall.md`, `docs/downcall-design.md` and `ROADMAP.md` at the commit
 **`73c40da4`** (`develop`, 2026-08-14). **Nothing in the reference project was modified or re-run**;
 its numbers are read, not reproduced.
 
@@ -13,7 +13,7 @@ its numbers are read, not reproduced.
 **One fourth source, added for the iOS comparison and cited separately everywhere it appears:**
 `docs/cost-table.md`, whose `iosSimulatorArm64` row was captured at **`958c0082b294`** at load
 [1.97, 2.29, 5.92], marked uncontaminated, from three runs. §4b and §1c use it rather than
-`upcall-design.md` because it is the only reference-side source that publishes an iOS upcall, its
+`docs/design/upcall.md` because it is the only reference-side source that publishes an iOS upcall, its
 same-run pure-Python callee control and its `withPython` scope figure together — the three cells the
 comparison needs from one execution. Its upcall figure (2253.20–2312.97 ns) and §4a's quoted
 2266–2301 ns are close but **are not the same measurement**; neither is derived from the other.
@@ -62,7 +62,7 @@ by reading generated code rather than documentation:
 
 | | React Native | PythonMultiplatform |
 |---|---|---|
-| **iOS** | JSI (C++) → Objective-C message send. One crossing. The generated `RNBenchSpec.h` builds `NativeBenchSpecJSI` over `ObjCTurboModule::InitParams` and calls the ObjC method directly. | No runtime boundary at all: a `PyMethodDef` whose `ml_meth` is a `staticCFunction` in the same binary (`docs/upcall-design.md`, "cheapest of the three"). |
+| **iOS** | JSI (C++) → Objective-C message send. One crossing. The generated `RNBenchSpec.h` builds `NativeBenchSpecJSI` over `ObjCTurboModule::InitParams` and calls the ObjC method directly. | No runtime boundary at all: a `PyMethodDef` whose `ml_meth` is a `staticCFunction` in the same binary (`docs/design/upcall.md` §7.4). |
 | **Android** | JSI (C++) → **JNI** → Kotlin. Two crossings. Confirmed with `nm` on the built `libappmodules.so`: `NativeBenchSpecJSI::NativeBenchSpecJSI(JavaTurboModule::InitParams const&)`. | C entry point in `artMain/cinterop/jni_onload.def` → **JNI** → Kotlin. Two crossings, "one shim per shape, plus a JNI upcall per call". |
 
 So on both projects Android is structurally the expensive side of the same asymmetry, for the same
@@ -107,7 +107,7 @@ all. Getting this wrong is the failure mode that matters most: two tables side b
 comparison whether or not the cells correspond.
 
 Reference-side sources: `UpcallBoundaryCostTest` (`commonTest`, quoted through
-`docs/upcall-design.md` §"One upcall, across all five platforms") and `overhead/BenchmarkTest`
+`docs/design/upcall.md` §"One upcall, across all five platforms") and `overhead/BenchmarkTest`
 (quoted through `docs/downcall-design.md`).
 
 | row here | what it charges | reference-project counterpart | same direction? | comparable? |
@@ -265,7 +265,7 @@ JS (Hermes, no JIT) --JSI--> C++ --JNI--> Kotlin, running on ART
 
 The callee of every boundary row is `BenchModule.kt` executing on ART. **ART is precisely the
 runtime whose tier-up the reference project measured, and it produced the largest warmup requirement
-in its entire table** (`docs/upcall-design.md`, "Is 100 000 enough on a device?"):
+in its entire table** (`docs/design/upcall.md` §7.2):
 
 | reference target | first repetition ÷ plateau | flat from | margin at a 100 000 warmup |
 |---|---|---|---|
@@ -350,7 +350,7 @@ row on iOS**, which is the opposite of what §3a predicts for Android.
 
 ### 4a. Ours, quoted (not re-run)
 
-`UpcallBoundaryCostTest`, `docs/upcall-design.md`. **Re-quoted 2026-08-14 at `73c40da4`.** The
+`UpcallBoundaryCostTest`, `docs/design/upcall.md`. **Re-quoted 2026-08-14 at `73c40da4`.** The
 previous version of this table was taken at `bd0029d1` and is superseded: it carried four rows as
 *italic* 3 000-warmup readings and two ART rows with three columns reading *not recorded*. Upstream
 has since re-measured every device row at the 100 000 warmup and filled all five columns from one

benchmarks/rn-benchmark/README.md

@@ -1,7 +1,7 @@
 # rn-benchmark
 
 A React Native app whose only purpose is to price the **JS ↔ native boundary** with the same
-measurement method the [PythonMultiplatform](../thisisthepy/PythonMultiplatform) repository uses to
+measurement method the [PythonMultiplatform](../..) repository uses to
 price its **Python ↔ Kotlin** boundary, so that the two can be read next to each other.
 
 The comparison itself, including what corresponds to what and what is still unmeasured, is in

benchmarks/rn-benchmark/RNBench/bench/appRun.js

@@ -39,7 +39,7 @@ const REPS = 5;
  *   JS (Hermes, no JIT) --JSI--> C++ --JNI--> **Kotlin, running on ART**
  *
  * The callee of every boundary row is `BenchModule.kt` executing on ART, and ART is precisely the
- * runtime whose tier-up the reference project measured: its `docs/upcall-design.md` sweep found ART
+ * runtime whose tier-up the reference project measured: its `docs/design/upcall.md` sweep found ART
  * on `pmp_api36` still 9% above its plateau at 70 000 calls and only arriving at ~90 000-100 000 --
  * the largest warmup requirement of any configuration it measured, and the one that set its
  * constant. So the RN Android boundary rows sit on the same curve, for the same reason, on the same

benchmarks/rn-benchmark/RNBench/bench/harness.js

@@ -134,7 +134,7 @@
 
   /**
    * Where a sweep settles, in the same terms the reference project's device sweep table uses
-   * (`docs/upcall-design.md`, "Is 100 000 enough on a device?"): first repetition over the plateau,
+   * (`docs/design/upcall.md` §7.2): first repetition over the plateau,
    * the call count from which the series stays flat, and the margin a given warmup has over it.
    *
    * The plateau is the mean of the second half, so it cannot be dragged by the early readings the

docs/INTENT.md

@@ -78,7 +78,7 @@ Behind the per-platform entry point, every platform uses the same generated func
 no per-platform Python → Kotlin binding code to maintain.
 
 > Inferred — confirm with the maintainer: this "one mechanism everywhere" property is a goal, not
-> only an implementation detail. It is stated as a decision in `PROJECT.md` and `docs/design/upcall-design.md`.
+> only an implementation detail. It is stated as a decision in `PROJECT.md` and `docs/design/upcall.md`.
 
 ## 3. What it deliberately is NOT
 
@@ -87,7 +87,7 @@ no per-platform Python → Kotlin binding code to maintain.
 | A binder that renames namespaces (`androidx` → `pythonx`, or any other) | §2.2 |
 | A replacement for the `pythonx` packages | §2.3 — they are real packages in their own repository |
 | Runtime-reflection or name-lookup based binding | §2.1 — impossible under Kotlin/Native and native image |
-| A hand-written wrapper per Kotlin function or class | Generic adaptation plus generated tables; per-declaration wrappers were tried in 2024 and rotted (`docs/design/pythonx-adapter-design.md`) |
+| A hand-written wrapper per Kotlin function or class | Generic adaptation plus generated tables; per-declaration wrappers were tried in 2024 and rotted (`docs/archive/pythonx-adapter-design.md`) |
 | A Python re-implementation, transpiler, or JVM-hosted Python | It embeds CPython itself, so C extensions keep working |
 | A build tool, dependency resolver or packager | That is pypackpack (the work) and toolchain (the Gradle vocabulary) |
 | A sub-interpreter parallelism model | Rejected: extensions that do not declare multi-interpreter support fail to import; parallelism comes from free-threaded CPython |

docs/SPEC.md

@@ -178,6 +178,13 @@ All in `PM/commonTest`, so they run wherever the interpreter loads.
   on disk is what `import pythonx` loads. The answer is the same whichever installer
   (`PythonProxySource`, `PythonxAdapter`) ran first for a table. `Status: implemented` on desktop —
   `PM/desktopTest/.../pythonx/KotlinNamedSurfaceTest.kt`, `ksp-fixtures/compose/.../KotlinSignatureMetadataTest.kt`.
+- **U-9** A Pythonic package can serve extra member names on a Kotlin proxy through one hook,
+  `python_multiplatform.binding.add_member_resolver(fn)`, `fn(kotlin_type_name, requested_name,
+  kotlin_member_names) -> kotlin_name | None`, asked only when no Kotlin member of that name exists.
+  The binder renames nothing itself (no resolver: `AttributeError`), and aliases are cached in the
+  registry, not written on the proxy class (`dir()` stays Kotlin-only). Contract in `KotlinSurface.kt`'s
+  KDoc. `Status: implemented` on desktop — `PM/desktopTest/.../pythonx/MemberResolverTest.kt`,
+  `ksp-fixtures/compose/.../MemberResolverComposeTest.kt`.
 
 ## 6. Binding prebuilt libraries (Gradle plugin)