diff --git a/quest/README.md b/quest/README.md index ee43b493a..124d7d2f4 100644 --- a/quest/README.md +++ b/quest/README.md @@ -8,11 +8,12 @@ grouped into milestones ordered by priority. ## Plan m0 holds urgent fixes. m1 is the work with a consumer waiting on it now: -the UniFFI fork moq switches to and its perf work. m2 is research: the -TypeScript translator, a track moq compares against its WASM route, and the -fork's gated or speculative work. m3 holds the build-speed tracks, which the -[build-speed benchmark](/bench/build/README.md) rescopes before they start, and -speculative work. +the UniFFI fork moq switches to, the exporter spike that may replace it, and +the fork's perf work. m2 is research: the TypeScript translator, a track moq +compares against its WASM route, and the fork's gated or speculative work. m3 +holds the build-speed tracks, which the +[build-speed benchmark](/bench/build/README.md) rescopes before they start, +and speculative work. Decided with the maintainer on 2026-10-23, when rust2 was planned from moq ([moq-dev/moq#6578](https://github.com/moq-dev/moq/pull/6578)): @@ -30,6 +31,6 @@ Decided with the maintainer on 2026-10-23, when rust2 was planned from moq ## Required - [m0: immediate priorities](/quest/m0/README.md) - urgent fixes -- [m1: consumers waiting](/quest/m1/README.md) - the UniFFI fork moq switches to, its binding benchmark and perf work +- [m1: consumers waiting](/quest/m1/README.md) - the UniFFI fork moq switches to, its binding benchmark, the exporter spike, and the fork's perf work - [m2: research](/quest/m2/README.md) - the TypeScript translator's spikes and features toward moq-net's model, and the fork's gated work - [m3: deferred](/quest/m3/README.md) - the pure-Rust profile and upstream's build-speed levers, measured by the benchmark diff --git a/quest/m1/README.md b/quest/m1/README.md index 15cf2962a..49f7795d2 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -2,13 +2,23 @@ ## Goal -The work moq is waiting on: the UniFFI fork its bindings switch to and the fork's -perf work moq planned. +The work moq is waiting on: the UniFFI fork its bindings switch to, the exporter +spike that may replace it, and the fork's perf work moq planned. + +## Plan + +Decided with the maintainer on 2026-10-24: an [exporter](/quest/m1/ffi-export-spike.md) +that turns a crate's `pub` API into bindings, with no attributes, may replace the UniFFI +fork. The fork stays in maintenance and keeps building moq's bindings; its feature +quests, here and in m2, pause until the spike reports, which decides whether each is +folded into the exporter. The spike sits in m1 because it blocks them. The binding +benchmark continues as the exporter's baseline. ## Required - [Waiting: publish the UniFFI fork](/quest/m1/uniffi-release.md) - the fork publishes to crates.io under `rust2-*` names, once the maintainer decides it should - [Binding benchmark](/quest/m1/ffi-bench.md) - moq's `bench-ffi` moves here and measures every wrapper against the fork, nightly +- [Exporter spike](/quest/m1/ffi-export-spike.md) - moq-net's `pub` API exported to a C ABI and header by a rustc driver, with refusals counted and compared against moq's `rs/moq-c` - [Payload bytes](/quest/m1/ffi-bytes.md) - payloads cross the FFI in bulk copies, proven in every wrapper - [Kotlin calls](/quest/m1/kt-ffi-calls.md) - Kotlin calls cost about what Python's and Go's do, starting from upstream's JNI bindgen - [Waiting: moq's poll-native async](/quest/m1/moq-poll-migrate.md) - condition: moq's `ffi-poll-migrate` quest has landed diff --git a/quest/m1/ffi-bytes.md b/quest/m1/ffi-bytes.md index cb2dfd627..dde7b0503 100644 --- a/quest/m1/ffi-bytes.md +++ b/quest/m1/ffi-bytes.md @@ -49,4 +49,5 @@ Public API: none unless `&[u8]` lands, which changes Kotlin's parameter type. ## Required +- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter - [Binding benchmark](/quest/m1/ffi-bench.md) - the before and after numbers diff --git a/quest/m1/ffi-export-spike.md b/quest/m1/ffi-export-spike.md new file mode 100644 index 000000000..77691173a --- /dev/null +++ b/quest/m1/ffi-export-spike.md @@ -0,0 +1,54 @@ +# [L] Exporter spike: a crate's pub API to C + +## Goal + +A prototype exporter turns a crate's `pub` API into a C ABI and a C header, with no +attributes in the Rust source. It runs on moq-net's public API directly, not moq-ffi, +and its report counts every refusal, which shows how much of the moq-ffi wrapper crate +is really needed. It compares the C output with moq's hand-written `rs/moq-c`, and +decides whether the exporter replaces [the UniFFI fork](/uniffi/README.md) and what +becomes of the fork feature quests paused behind it. + +## Plan + +Decided with the maintainer on 2026-10-24: replace UniFFI's macros with an opinionated +Rust-to-language exporter. A crate's `pub` API alone defines what gets exported, with no +`#[uniffi::export]` attributes. + +- **Source**: a rustc driver, reusing [rust2-ts](/ts/README.md)'s driver infrastructure + on the same pinned nightly, so types, visibility, and trait impls come from the + compiler. Chosen over rustdoc JSON and parsing the source. +- **Output**: its own IR and its own generators, not UniFFI metadata. +- **Opinions**: every `pub` item reachable from the crate root is exported by fixed + rules: + - a struct whose fields are all `pub` becomes a record, and other types become + objects behind `Arc`; + - `Result` becomes errors; + - `async fn` becomes a future; + - `pub` traits become callback interfaces. + + Anything that doesn't map is a compile error with a source span, unless a config file + excludes it. Nothing is skipped silently, and nothing is opted in by attribute. +- **Target**: moq-net's public API, at a pinned moq revision as `just ts moq` pins one. + The refusal count is the measure of what a wrapper crate still has to add. +- **First output**: a C ABI plus a C header, matching the earlier C-first decision: + every other language layers on that one ABI later. Compare it against moq's + hand-written `rs/moq-c`. +- **The UniFFI fork**: spike first, with the fork in maintenance. New fork features + pause behind this spike: the [C-first bindings spike](/quest/m2/uniffi-c-first-spike.md), + the [namespaced contract](/quest/m2/uniffi-contract.md), and the perf quests + ([payload bytes](/quest/m1/ffi-bytes.md), + [zero-copy returns](/quest/m2/ffi-bytes-return.md), + [cheaper async](/quest/m2/ffi-async.md), + [checksums](/quest/m2/ffi-checksums.md), + [code size](/quest/m2/ffi-code-size.md), + [Kotlin calls](/quest/m1/kt-ffi-calls.md), and + [foreign poll](/quest/m1/ffi-poll-protocol.md)). Their findings feed the exporter's + design, and the report says, for each, whether it is folded into the exporter. The + fork keeps building moq's bindings until the exporter replaces it. + +Public API: a new tool. + +## Related + +- [Binding benchmark](/quest/m1/ffi-bench.md) - continues, as the baseline the exporter is measured against diff --git a/quest/m1/ffi-poll-protocol.md b/quest/m1/ffi-poll-protocol.md index 2e084338f..3f6aaf0c0 100644 --- a/quest/m1/ffi-poll-protocol.md +++ b/quest/m1/ffi-poll-protocol.md @@ -73,6 +73,7 @@ terminal to per-read. ## Required +- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter - [Binding benchmark](/quest/m1/ffi-bench.md) - the numbers every wrapper is measured on - [moq's poll-native async](/quest/m1/moq-poll-migrate.md) - the kio poll each export wraps, with `ffi::Task` gone diff --git a/quest/m1/kt-ffi-calls.md b/quest/m1/kt-ffi-calls.md index 94503b80e..a9930c2ed 100644 --- a/quest/m1/kt-ffi-calls.md +++ b/quest/m1/kt-ffi-calls.md @@ -41,4 +41,5 @@ Public API: none expected. ## Required +- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter - [Binding benchmark](/quest/m1/ffi-bench.md) - the before and after numbers diff --git a/quest/m2/README.md b/quest/m2/README.md index 92779dcca..e9019d67b 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -16,6 +16,9 @@ Decided with the maintainer on 2026-10-24: the translator's output ranks correct then speed, then the size of the consumer's final tree-shaken, minified JS; readability is not a goal, and types must be solid at the API boundary ([design](/ts/README.md#design)). +The fork's feature quests here pause until the [exporter spike](/quest/m1/ffi-export-spike.md) +reports; [m1](/quest/m1/README.md#plan) records the decision. + ## Required - [MIR lowering spike](/quest/m2/ts-mir-spike.md) - the whole lowering ported to MIR on two fixtures decides whether the translator moves diff --git a/quest/m2/ffi-async.md b/quest/m2/ffi-async.md index 33a4fd786..f2d73a350 100644 --- a/quest/m2/ffi-async.md +++ b/quest/m2/ffi-async.md @@ -25,4 +25,5 @@ Public API: none expected. ## Required +- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter - [Foreign poll for hot reads](/quest/m1/ffi-poll-protocol.md) - the waker design this reuses diff --git a/quest/m2/ffi-bytes-return.md b/quest/m2/ffi-bytes-return.md index e0c98308e..84ddc7939 100644 --- a/quest/m2/ffi-bytes-return.md +++ b/quest/m2/ffi-bytes-return.md @@ -25,4 +25,5 @@ Public API: returned payload types may change per language. ## Required +- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter - [Payload bytes](/quest/m1/ffi-bytes.md) - the numbers that justify it diff --git a/quest/m2/ffi-checksums.md b/quest/m2/ffi-checksums.md index d804d367c..974384d89 100644 --- a/quest/m2/ffi-checksums.md +++ b/quest/m2/ffi-checksums.md @@ -20,5 +20,6 @@ Public API: none; generated bindings lose their checksum calls. ## Required +- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter - [Namespaced FFI contract](/quest/m2/uniffi-contract.md) - what refuses a mismatched library once the checksums are gone - [Binding benchmark](/quest/m1/ffi-bench.md) - load time, size, and symbol numbers diff --git a/quest/m2/ffi-code-size.md b/quest/m2/ffi-code-size.md index 2dc2d6bc8..9f8fa2796 100644 --- a/quest/m2/ffi-code-size.md +++ b/quest/m2/ffi-code-size.md @@ -18,4 +18,5 @@ Public API: generated code changes shape; wrapper APIs do not. ## Required +- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter - [Binding benchmark](/quest/m1/ffi-bench.md) - the size report diff --git a/quest/m2/uniffi-c-first-spike.md b/quest/m2/uniffi-c-first-spike.md index 10068bb98..76e7755db 100644 --- a/quest/m2/uniffi-c-first-spike.md +++ b/quest/m2/uniffi-c-first-spike.md @@ -42,6 +42,10 @@ generator with two error styles that each support only part of UniFFI: - moq's expected-style C++ bindings are today's baseline; the rewrite may change them, so the report says how moq migrates. +## Required + +- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter + ## Related - [Nightly MSVC and macOS](/quest/m2/uniffi-ci-msvc-macos.md) - the compile matrix this spike measures by hand, run nightly diff --git a/quest/m2/uniffi-contract.md b/quest/m2/uniffi-contract.md index 983f2b113..87092e962 100644 --- a/quest/m2/uniffi-contract.md +++ b/quest/m2/uniffi-contract.md @@ -26,3 +26,7 @@ anyway. Public API: the generated contract check, and the scaffolding's exported contract symbol. + +## Required + +- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter