From 799017c0455df4efeef321ebb65cde57f99aeae0 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Tue, 27 Oct 2026 19:17:55 -0700 Subject: [PATCH] chore(quest): plan for stock crates that translate without config A stock crate should translate with no annotations or config. Record that in AGENTS.md, move `unsafe` and trait objects from never to not yet, and plan the gaps: well-known crates mapped by rust2-ts itself (m2) and trait objects (m3). moq's safe cfg twins stay as a stopgap that ts-unsafe retires. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 1 + quest/m2/ts-model/README.md | 13 ++++++++----- quest/m2/ts-model/stock.md | 26 ++++++++++++++++++++++++++ quest/m3/README.md | 1 + quest/m3/ts-dyn.md | 19 +++++++++++++++++++ quest/m3/ts-unsafe.md | 7 ++++--- ts/README.md | 11 +++++------ 7 files changed, 64 insertions(+), 14 deletions(-) create mode 100644 quest/m2/ts-model/stock.md create mode 100644 quest/m3/ts-dyn.md diff --git a/AGENTS.md b/AGENTS.md index 255a9ec18..6a0d4bfeb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,6 +31,7 @@ Each project lives in its own top-level directory; the [quest tree](quest/README - Prefer upstream and maintained crates over hand-rolling. Measure before claiming an improvement over them. - Every change needs a consumer that uses it now and is worth its cost; name it in the PR. moq is the first consumer of every project here. +- Translators take stock crates as they are: no annotations, and no config beyond true platform boundaries. Each config key or source change a consumer needs is a gap to close. - Deleting code is better than adding code. - Comments explain the non-obvious why, never the history. - New dependencies use the newest stable version. Do not bump package versions unless asked. diff --git a/quest/m2/ts-model/README.md b/quest/m2/ts-model/README.md index 031ca9f36..25f0f0da5 100644 --- a/quest/m2/ts-model/README.md +++ b/quest/m2/ts-model/README.md @@ -30,11 +30,13 @@ Decided with the maintainer on 2026-10-27, from a census of the model's 22 publi the translator is specific to moq: dependencies follow general rules, and moq's own changes (safe `cfg` twins of its `unsafe`, `dyn Expiry` as an enum, dropping or binding `hashlink`, `slab`, and `smallvec`) are one research-tier quest in moq's tree. -- `unsafe`, raw pointers, and trait objects stay out of the translated subset. Internal - `unsafe` in moq-net and kio gets safe `cfg` twins in moq, so differential tests cover - it; only true boundaries (`Box`, clocks, `rand`, DEFLATE) bind to - hand-written TS. A dependency containing `unsafe` is bound by the consumer, until - [unsafe code the translator can model](/quest/m3/ts-unsafe.md) translates. +- Until `unsafe` and trait objects translate, internal `unsafe` in moq-net and kio gets + safe `cfg` twins in moq, so differential tests cover it, and a dependency containing + `unsafe` is bound by the consumer. These are stopgaps: decided with the maintainer on + 2026-10-27, a stock crate translates with no annotations or config, so + [unsafe code the translator can model](/quest/m3/ts-unsafe.md) and + [trait objects](/quest/m3/ts-dyn.md) remove them. Only true platform boundaries (clocks, + `rand`, DEFLATE) stay bound. - Each child measures this target by the census of `ts/moq/model.toml`, rooted at those types with the boundaries bound, which nightly reports beside the whole crate. - The end-to-end work stays here: the model's roots, its differential harness, and the @@ -51,4 +53,5 @@ Public API: the translator's output for moq-net's model. - [Options of values that can be undefined](/quest/m2/ts-model/nested-option.md) - `Option>` and `Option<()>` keep `None` apart from `Some(None)` - [Std's mutable references to values JS copies](/quest/m2/ts-model/std-places.md) - `as_mut`, `get_or_insert`, `iter_mut`, and the rest give an `rt.Place` - [The rest of std the model reaches](/quest/m2/ts-model/std-rest.md) - the std calls the census still refuses +- [Well-known crates without config](/quest/m2/ts-model/stock.md) - rust2-ts maps `bytes`, `rand`, and `tracing` itself, so `model.toml` stops binding and ignoring them - [Async in the TypeScript translator](/quest/m2/ts-async.md) - kio's producers and consumers are futures diff --git a/quest/m2/ts-model/stock.md b/quest/m2/ts-model/stock.md new file mode 100644 index 000000000..f27b6f704 --- /dev/null +++ b/quest/m2/ts-model/stock.md @@ -0,0 +1,26 @@ +# [M] Well-known crates without config + +## Goal + +[rust2-ts](/ts/README.md) translates calls into `bytes`, `rand`, and `tracing` with no +binding or `ignore-macros` from the consumer, as it does std's, proven by differential +tests against native Rust. `ts/moq/model.toml` drops its entries for them. + +## Plan + +Decided with the maintainer on 2026-10-27: a stock crate translates with no annotations or +config, so a consumer's config holds only its own platform boundaries. moq's model binds +`bytes::Bytes`, `bytes::BytesMut`, and `rand::rng`, and ignores `tracing`'s macros. + +- rust2-ts ships these mappings itself, as it ships std's. Each matches the crate's + semantics exactly; where the crate depends on the platform, such as `rand`'s source of + randomness, say what the mapping uses. +- A mapping stands in only where the crate cannot translate from source: `bytes` has + `unsafe` inside. Prefer translating from source once + [unsafe code the translator can model](/quest/m3/ts-unsafe.md) covers it. +- `tracing`'s macros need a meaning without config: dropping them changes nothing + observable unless a subscriber is installed. Decide what an installed subscriber sees. +- Report the model's census before and after. + +Public API: the translator's output; `ignore-macros` and `[bind]` entries for these crates +become unnecessary. diff --git a/quest/m3/README.md b/quest/m3/README.md index 77abab773..a9eabdf52 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -17,6 +17,7 @@ generic std gap is planned here even when moq never calls it. - [Relink without rebuilding](/quest/m3/relink.md) - measure upstream's skip of dependency-only rebuilds on moq's edits once it reaches nightly - [Unsafe code the translator can model](/quest/m3/ts-unsafe.md) - a dependency using only `unsafe` the translator can model translates from source - [The rest of Duration](/quest/m3/ts-duration.md) - compound assignment, float conversions, and `Sum` on a `Duration` translate +- [Trait objects](/quest/m3/ts-dyn.md) - `dyn Trait` and `Box` translate, so a consumer neither rewrites nor binds them - [The rest of format specs](/quest/m3/ts-fmt-specs.md) - precision, argument widths, `+`, and the other radixes format as `core::fmt` does - [Waiting: type-check in process with tsrs](/quest/m3/ts-tsrs.md) - rust2-ts checks bindings through tsrs instead of `tsc` once it is a stable library - [Fold matches across tests that aren't variant switches](/quest/m3/ts-fold-guards.md) - a match an `if` or guard decided drops its dead arms diff --git a/quest/m3/ts-dyn.md b/quest/m3/ts-dyn.md new file mode 100644 index 000000000..1e8c6009a --- /dev/null +++ b/quest/m3/ts-dyn.md @@ -0,0 +1,19 @@ +# [L] Trait objects + +## Goal + +[rust2-ts](/ts/README.md) translates trait objects (`&dyn Trait`, `Box`, and +`Box`, `Pin`ned or not), with Rust's dispatch and drop order, proven by +differential tests against native Rust, so a consumer neither rewrites nor binds them. + +## Plan + +Decided with the maintainer on 2026-10-27: a stock crate translates with no annotations or +config, so trait objects move from never to not yet. Until this lands, moq rewrites +`dyn Expiry` as an enum and binds its boxed futures ([bindings](/ts/README.md#bindings)). + +- `&dyn Debug` and `&dyn Display` already translate; build on how they do. +- A boxed future must keep Rust's laziness and cancellation as + [async](/quest/m2/ts-async.md) defines them. + +Public API: the translator's output. diff --git a/quest/m3/ts-unsafe.md b/quest/m3/ts-unsafe.md index b2d01d7f0..1892cb0a7 100644 --- a/quest/m3/ts-unsafe.md +++ b/quest/m3/ts-unsafe.md @@ -10,9 +10,10 @@ source instead of being bound by hand. ## Plan Decided with the maintainer on 2026-10-27: a dependency containing `unsafe` is bound by -the consumer [at first](/ts/README.md#bindings); this follows once a consumer binds -enough of them to justify it. The census of moq-net's model found `bytes`, `hashlink`, -`slab`, and `smallvec` bound, and kio's lock-free `log`. +the consumer [at first](/ts/README.md#bindings), and moq gives its own `unsafe` safe +`cfg(rust2_ts)` twins. Both are stopgaps, since a stock crate should translate with no +annotations or config; this quest is what retires them. The census of moq-net's model +found `bytes`, `hashlink`, `slab`, and `smallvec` bound, and kio's lock-free `log`. - An `unsafe` operation outside the modeled set is refused with its span, as today. - Undefined behavior in Rust need not be reproduced, but a translated program never diff --git a/ts/README.md b/ts/README.md index 03c6410ae..84944d07a 100644 --- a/ts/README.md +++ b/ts/README.md @@ -413,14 +413,13 @@ they need. and async handoff bundles are within 25 bytes gzipped, and `just ts bench` measures them within the A/A route's spread in Node, Bun, Chrome, and Firefox. -## Never - -Outside the subset for good: `unsafe` and raw pointers, and trait objects other than -`&dyn Debug` and `&dyn Display`. A boundary that needs one, such as a boxed future, binds -to hand-written TS ([bindings](#bindings)). - ## Not yet +`unsafe` and raw pointers ([unsafe](/quest/m3/ts-unsafe.md)), and trait objects other than +`&dyn Debug` and `&dyn Display` ([trait objects](/quest/m3/ts-dyn.md)), fail translation. +Until they translate, an item that needs one, such as a boxed future, binds to +hand-written TS ([bindings](#bindings)). + These fail translation: floats, statics, async closures, a closure that owns a value that drops given to std's iterators or collections, and values that drop in some iterators ([Drop](/quest/m2/ts-drop.md)), a `Cow` of other than `str`,