Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
13 changes: 8 additions & 5 deletions quest/m2/ts-model/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<dyn Future>`, 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
Expand All @@ -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<Option<T>>` 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
26 changes: 26 additions & 0 deletions quest/m2/ts-model/stock.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions quest/m3/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<dyn Future>` 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
Expand Down
19 changes: 19 additions & 0 deletions quest/m3/ts-dyn.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# [L] Trait objects

## Goal

[rust2-ts](/ts/README.md) translates trait objects (`&dyn Trait`, `Box<dyn Trait>`, and
`Box<dyn Future>`, `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.
7 changes: 4 additions & 3 deletions quest/m3/ts-unsafe.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 5 additions & 6 deletions ts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down