Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
9a29281
chore(quest): claim quest/m2/ts-mir-spike.md
kixelated Oct 24, 2026
5b7aa54
wip(ts): MIR lowering prototype translates the codec fixture
kixelated Oct 24, 2026
bddeae7
wip(ts): MIR lowering translates the task fixture's futures as state …
kixelated Oct 24, 2026
e052d5d
Merge remote-tracking branch 'origin/main' into quest/m2/ts-mir-spike
kixelated Oct 24, 2026
f6d636b
wip(ts): MIR lowering copies only where a copy could change, and fold…
kixelated Oct 24, 2026
1492905
wip(ts): MIR lowering unwinds through cleanups, and steps ranges in p…
kixelated Oct 24, 2026
2f0d0ef
wip(ts): MIR drop glue from rustc's shims, left-out macros by their c…
kixelated Oct 24, 2026
f4680d5
wip(ts): drops on panic tested against native unwinding; MIR returns …
kixelated Oct 24, 2026
72d7f1a
wip(ts): MIR lowering leaves the checks the runtime makes to it; lint
kixelated Oct 24, 2026
f49c38f
wip(ts): the lang fixture passes from MIR: next's protocol, own itera…
kixelated Oct 24, 2026
79b1b0f
wip: rewrite the drop and async quests and the README's design note t…
kixelated Oct 24, 2026
aecbe8f
wip: final numbers in the quests and README
kixelated Oct 24, 2026
6a6d78d
Merge remote-tracking branch 'origin/main' into quest/m2/ts-mir-spike
kixelated Oct 24, 2026
f6678bb
fix(ts): read an aggregate's field in place only through names nothin…
kixelated Oct 24, 2026
4766695
fix(ts): keep a folded call's effects with what it folds into, and re…
kixelated Oct 25, 2026
d0001f5
quest(ts-shared): rt.copy copies through shared references
kixelated Oct 25, 2026
7a59f1c
fix(ts): a move closure keeps the reference a variable held when it w…
kixelated Oct 25, 2026
e2bfc4c
fix(ts): a value held back reads a source changed in place where it f…
kixelated Oct 25, 2026
c4ad18b
docs(ts): the speed after review, and panics that unwind
kixelated Oct 25, 2026
62fa534
fix(ts): share an argument's copy only where the callee can't change …
kixelated Oct 25, 2026
66b54ae
fix(ts): refuse Option::insert and Option::replace from MIR
kixelated Oct 25, 2026
c59c322
fix(ts): share an argument's copy only with a callee whose result can…
kixelated Oct 25, 2026
d00c775
Merge remote-tracking branch 'origin/main' into quest/m2/ts-mir-spike
kixelated Oct 25, 2026
7581fa3
fix(ts): a whole write through a copied reference changes the object …
kixelated Oct 25, 2026
04e3c71
perf(ts): take a range apart before reading the slice it indexes
kixelated Oct 25, 2026
157bdca
fix(ts): replace only through an alias of a borrowed place, not a cop…
kixelated Oct 25, 2026
71b437d
docs(ts): MIR's speed against THIR after the review fixes
kixelated Oct 25, 2026
a87d03b
fix(ts): refuse copying a closure that changes what it captured
kixelated Oct 25, 2026
fc4bf73
docs(quest): MIR's codec speed blocks making MIR the only lowering
kixelated Oct 25, 2026
86398a7
Merge remote-tracking branch 'origin/main' into quest/m2/ts-mir-spike
kixelated Oct 25, 2026
e77cea3
fix(ts): a copy of a local changed in place reads memory, so no write…
kixelated Oct 25, 2026
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
3 changes: 2 additions & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ 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
- [MIR's codec as fast as THIR's](/quest/m2/ts-mir-codec.md) - the codec from MIR no slower than from THIR in any engine
- [Lower bodies from MIR](/quest/m2/ts-mir.md) - the MIR spike's prototype becomes the only lowering, and the THIR one goes
- [Enum variant field order](/quest/m2/ts-variant-order.md) - a variant's fields evaluate in the order written, not declared
- [Stable names](/quest/m2/ts-stable-names.md) - generic instances and trait-impl methods always carry their suffix, so callers' names never shift
- [Diverging calls through closures and generics](/quest/m2/ts-never-edges.md) - closures returning `!` and generics at `!` pass `tsc`
Expand Down
53 changes: 21 additions & 32 deletions quest/m2/ts-async.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,46 +8,35 @@ Differential tests against native Rust prove the same polls, wakes, drops, and r

## Plan

Decided by the async spike ([#16](https://github.com/kixelated/rust2/pull/16)) on
2026-10-24: an async body is a generator lowered from THIR, not a state machine lowered
from MIR. MIR's were about twice as fast per await level, but would need a second
lowering of everything an async body can hold, and read as basic blocks. What landed
there: an `async fn` returns `rt.future(body, drop, ...upvars)`, whose body is a
module-level `function*` of what it captured (a generator function made per call costs
V8 about 25 times as much), `.await` is a poll loop around `yield`, and `rt.spawn` runs
a future from a microtask as a promise. The task fixture's trace test covers a
kio-shaped channel at await depths 1, 4, and 16.

What moq-net still needs, by its census at the pinned revision:

- `Poll`'s helpers (about 270 calls: `is_ready`, `is_pending`, `map`, `map_ok`,
`map_err`), `pin!` (47), `poll_fn` (51 with its `poll`), and `Box::pin` (17, a boxed
future that binds to hand-written TS at the boundary, per the
[model](/quest/m2/ts-model.md)).
- An async block that captures part of a variable (47), or borrows a number mutably
(4); async closures.
Decided by the MIR spike ([#36](https://github.com/kixelated/rust2/pull/36)): an async
body is the state machine rustc's coroutine transform makes, lowered from MIR. Each
coroutine instance is a class of its state, its captures, and the locals it keeps
across an `.await`; its `poll` is the transform's resume function, a loop over a
`switch` on the next block since it enters loops in the middle, and its
`[Symbol.dispose]` is the transform's drop, which drops what the state it is in holds.
A handoff through 1, 4, and 16 async functions measured 1.5-2.7x faster than #16's
generators in Node, 1.8-5.5x in Bun, and 1.4-3.5x in Chrome, and past depth 1 faster
than moq's hand-written promises. `rt.spawn` stays.

What moq-net still needs, by its census from MIR at the pinned revision:

- `Poll`'s helpers (about 340 calls: `is_ready`, `is_pending`, `map`, `map_ok`,
`map_err`), `pin!` (50 with `PinMacroHelper`), `poll_fn` (31), `future::pending`
(5), and `Box::pin` (29, a boxed future that binds to hand-written TS at the
boundary, per the [model](/quest/m2/ts-model.md)).
- `?` inside a function that returns `Poll`, as `ready!(..)?` writes it: 284 sites.
- Async closures.
- kio's own API, reached across crates (`Pending`, `Consumer::poll`,
`Waiter::poll_future`, `Tasks`), with the atomics, `OnceLock`, and coop budget behind
it, which the model quest brings along.
- The edge: `rt.spawn`'s shape for callers, and cancelling a spawned task.

If a profile of moq's client finds await overhead, `yield*` between translated futures
would skip each level's `poll`; measure it on the [TS benchmark](/ts/README.md#bench).

Decided with the maintainer on 2026-10-24: the async spike
([#16](https://github.com/kixelated/rust2/pull/16)) merges with generators from
THIR, and the [MIR lowering spike](/quest/m2/ts-mir-spike.md) then decides
whether the whole lowering moves to MIR; rewrite this plan to its report too.
Also in scope, found since:

- `?` inside a function that returns `Poll`, as `ready!(..)?` writes it: about
224 sites in moq-net.
- A `()` future awaited as a statement fails `tsc`: `Future<void>` against
`Future<undefined>`.
An async block that captures part of a variable, which THIR refused 47 times, is a
capture like any other in MIR.

Public API: the translator's output for async code.

## Required

- [MIR lowering spike](/quest/m2/ts-mir-spike.md) - rewrite to the spike's report before starting
- [Lower bodies from MIR](/quest/m2/ts-mir.md) - async bodies come from the coroutine transform
- [Drop in the TypeScript translator](/quest/m2/ts-drop.md) - async bodies hold the values that drop it still refuses
78 changes: 30 additions & 48 deletions quest/m2/ts-drop.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,56 +9,38 @@ native Rust.

## Plan

Decided by the async spike ([#16](https://github.com/kixelated/rust2/pull/16)) on
2026-10-24: drop points come from the THIR lowering's own scopes, not MIR. What landed
there: a class that drops gets `[Symbol.dispose]` as drop glue (its `Drop` impl, then
each field); a variable drops in a `finally` at the end of its scope; a move leaves
`undefined` behind, so a variable moved on some paths drops on the others. The task
fixture's trace test proves it on kio's waiters, wakers, and channels.

What still fails translation, each with its span (the reject fixture has one of each),
ranked by the census of moq-net at the pinned revision (kio's has 28 in all):

- Dropping a value whose drop no `[Symbol.dispose]` carries (657): a `Result`, an
`Option` or `Poll` of one, an enum or tuple holding one, a `Vec` of one. Each needs
glue of its own, switching on the variant.
- A temporary that drops, unless a call or binding takes it whole (280): borrowed, a
field or index of one, a `match`, `if let`, `let`, or let chain that moves only part
of it, and a guarded arm that binds one. Rust drops it at the end of its statement, or
of the `match`.
- A `for` loop over values that drop (60): each at the end of its iteration, and the
rest on a `break`.
- An iterator that owns a value that drops (55): a `Vec` of one moved into it, or an
adaptor over items that drop. An `rt.Iter` drops nothing it skips, consumes, or still
holds when it is dropped.
- A std mapping that may discard an operand that drops (19): `bool::then_some`,
`Option::ok_or`, `map_or`, and `unwrap_or`, and `Result::ok`. Each refuses any operand
that drops today, even one it always keeps, such as `ok_or`'s option: `keeps_operands`
in `library.rs` should name the operands each mapping may discard instead.
- Struct update syntax from a value that drops (16), a closure capturing one (13), a
generic type that implements `Drop` (11), a parameter that drops bound by a pattern,
a rest pattern that moves values that drop out of a place, and an array repeat of a
value that drops.
- A value that drops, moved ahead of an `.await` in the same call (3) or in the place
an assignment writes it to, which a cancel would leave in a temporary no scope drops,
and an `Arc` or `Mutex` holding a borrow of a value that drops, which JS would drop
as the value itself.

Decided with the maintainer on 2026-10-24: the async spike
([#16](https://github.com/kixelated/rust2/pull/16)) merges with drop points from
THIR's scopes, and the [MIR lowering spike](/quest/m2/ts-mir-spike.md) then
decides whether drops move to MIR's elaboration; rewrite this plan to its report
too. Also in scope, found since: a temporary that drops and is held across an
`.await` is owned instead of refused (3 refusal sites), which needs declarations
at scope level.

Watch the cost: each move of a value that drops writes `undefined` to where it was, and
each scope holding one becomes a `try`/`finally`. A pass that proves a variable moved on
every path, or on none, would drop most of both; measure it on the
[TS benchmark](/ts/README.md#bench) before adding it.
Decided by the MIR spike ([#36](https://github.com/kixelated/rust2/pull/36)): drop
points come from MIR's drop elaboration, which puts each drop where Rust runs it, with
a flag where a value moved on some paths only, so the lowering adds nothing of its own:
no `finally` per scope, and no `undefined` left by a move. A panic unwinds through the
cleanup blocks of `-C panic=unwind` MIR, which a function runs from a `catch` (the
task fixture's unwinding test checks them against native unwinding). An enum, tuple,
or `Result` that drops is dropped by glue lowered from rustc's own `drop_in_place`
shim.

What still fails translation from MIR, by the census of moq-net at the pinned revision
(kio's has 9 in all):

- An iterator that owns a value that drops (95): an `rt.Iter` drops nothing it skips,
consumes, or still holds when it is dropped.
- Dropping a value whose glue is std's (128): a `Vec` of a value without
`[Symbol.dispose]`, such as an enum, and the instances of generic enums a census
lowers over their type parameters.
- A std mapping that may discard an operand that drops (20): `keeps_operands` in
`library.rs` refuses any operand that drops, even one a mapping always keeps;
it should name the operands each mapping may discard instead.
- A generic type that implements `Drop` (11).

THIR's refusals that MIR's elaboration closes, for comparison: 657 drops of a value
without glue, 280 temporaries that drop, 60 `for` loops, 112 moves out of other places,
and 75 more in patterns, closures, and struct updates.

Watch the cost: a function whose cleanup does something JS can see sets a variable
before each call that can panic and wraps its body in a `try`; measure any change on
the [TS benchmark](/ts/README.md#bench).

Public API: the translator's output for values that drop.

## Required

- [MIR lowering spike](/quest/m2/ts-mir-spike.md) - rewrite to the spike's report before starting
- [Lower bodies from MIR](/quest/m2/ts-mir.md) - drops come from MIR's elaboration
17 changes: 17 additions & 0 deletions quest/m2/ts-mir-codec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# [M] MIR's codec as fast as THIR's

## Goal

Lowering moq-net's codec from MIR runs it no slower than THIR's lowering on
`just ts bench`, in Node, Bun, and Chromium, before MIR becomes the only lowering.

## Plan

Decided with the maintainer on 2026-10-24: this blocks making MIR the default. On
[#36](https://github.com/kixelated/rust2/pull/36)'s head, after its review fixes, the
codec's geometric mean from MIR was 1.10x THIR's in Node, 1.02x in Bun, and 1.12x in
Chromium, against A/A controls of 1.00. Group encode was 1.9-2.6x slower in every
engine, frames encode 1.3-1.4x in Chromium, and small varint encodes up to 1.6x in
Node (but 0.7x in Bun). An earlier run, before the review fixes and the bench's
random order, put the codec within 8% apart from group encode, so start by
separating what the review fixes' copies cost from what was always there.
35 changes: 0 additions & 35 deletions quest/m2/ts-mir-spike.md

This file was deleted.

50 changes: 50 additions & 0 deletions quest/m2/ts-mir.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# [L] Lower bodies from MIR

## Goal

[rust2-ts](/ts/README.md) lowers every body from MIR, as the
[MIR spike](https://github.com/kixelated/rust2/pull/36) decided: `--lower` goes,
the THIR lowering (`src/lower/body.rs`, `pat.rs`, the drop scopes in `drop.rs`, and
`rt.future`'s generators) is deleted, and every fixture passes its snapshot,
differential, unwinding, and census tests from MIR.

## Plan

The spike's prototype (`src/lower/mir/`) already passes the codec, lang, and task
fixtures' differential tests and the task fixture's unwinding test. What the move
still needs:

- The reject fixture and its census, rewritten to what MIR refuses (`reject_mir`
already checks MIR's errors), and snapshots of MIR's output. Constructs THIR refuses that MIR lowers move into the differential
fixtures, such as a `move` closure taking a reference from a variable assigned again
after (`a closure that copies a mutable variable`), which the prototype snapshots.
- The census to at least THIR's coverage of moq-net and kio. MIR types each
intermediate it holds, so a gap in the library or model shows up once more per
temporary; read the census by construct, not by total. MIR-only refusals to close:
`?` on `Poll<Result<..>>` (284, which THIR refused as 235 too), `ControlFlow` other
than from `?`, switches on and fields of types without a mapping, and a reference
copied out of a field and then passed on.
- `?` on an `Option` returned through a `next` whose item can be `undefined`, and the
other THIR special cases the prototype mirrors (`for` loops by the iterator protocol,
`from_be_bytes` of bytes made in place, ranges stepped in place): keep each only
where `just ts bench` measures it.
- Size: the task fixture's bundle is 35% larger gzipped than THIR's, the codec's 9%.
Likely wins, each to measure: a coroutine resume function structured where the
graph allows (a dispatch at each loop header the resume enters, rather than a
`switch` over every block), temporaries folded through reads of borrowed places, and
`_0 = v; return _0` returned in place.
- Source maps: MIR spans point at calls and asserts; check stack traces read well.
- Panics unwind (`-C panic=unwind`), as decided in
[#36](https://github.com/kixelated/rust2/pull/36) at a measured 4-6% on V8's async
handoff; `RUST2_TS_ABORT`, kept only to measure aborting, goes with `--lower`.

Watch what the prototype's comments say it relies on: MIR's single-assignment
temporaries, `Box` derefs elaborated into `BoxDerefTransmute`, and drop shims that
take a raw pointer. A nightly bump that changes them should fail loudly, as each does
now.

Public API: the translator's whole output, and the `--lower` option, which goes.

## Required

- [MIR's codec as fast as THIR's](/quest/m2/ts-mir-codec.md) - the codec from MIR no slower than from THIR in any engine
3 changes: 3 additions & 0 deletions quest/m2/ts-shared.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ is its own guard. Left: `Rc`, `weak_count` (a dropped `Weak` counts nothing yet)
panics. A re-entrant `Mutex` lock on one thread is unspecified in Rust; pick
a loud failure (panic) and document it.
- Measure the counter overhead on the [TS benchmark](/ts/README.md#bench).
- `rt.copy` copies a `Copy` aggregate deeply, through the shared references in it,
so copying `(&Arc<T>, u8)` copies the `Arc` and its count, or a `Cell` and its
value. Copy only what the type owns.

Public API: the translator's output for shared and interior-mutable types.

Expand Down
35 changes: 27 additions & 8 deletions ts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
A rustc driver that translates a subset of Rust to TypeScript with source maps. No WASM: the output is plain ES modules that Node, Bun, and bundlers run as is.

```bash
rust2-ts --config ts.toml (--out dir | --census file.md) [--manifest-path Cargo.toml] [-- cargo args]
rust2-ts --config ts.toml (--out dir | --census file.md) [--manifest-path Cargo.toml] [--lower thir|mir] [-- cargo args]
```

It runs `cargo check` on the package with itself as `RUSTC_WRAPPER`, for
Expand All @@ -28,6 +28,10 @@ ignore-macros = ["tracing::trace"]
moq consumes it as the `ts` package of this repository's flake. In this repository,
`just ts run ...` runs it from source on the pinned nightly.

`--lower mir` lowers bodies from MIR instead of THIR: the prototype the MIR spike
built, which the translator is moving to ([quest](/quest/m2/ts-mir.md)). The rest of
this page describes the THIR lowering, the default, except where it says MIR.

## Census

`--census file.md` translates nothing. It treats every item in the library as a root,
Expand Down Expand Up @@ -201,11 +205,20 @@ they need.
(`rev`, `zip`, `peekable`), and a `next` returning an item or `rt.DONE` allocates
nothing per item. `just ts bench` measures chains of `map`, `filter`, `any`, `skip`,
and `take` 1.4-8x faster than the same ES helpers in Node, Bun, and Chrome.
- Bodies lower from THIR, which keeps loops, `match`, and `?` shaped as written. Drops
come from its scopes, and async bodies are generators: MIR state machines were about
twice as fast per await level, but would need a second lowering
([#16](https://github.com/kixelated/rust2/pull/16) measured both). The
[MIR spike](/quest/m2/ts-mir-spike.md) decides whether the whole lowering moves.
- Bodies lower from MIR ([moving](/quest/m2/ts-mir.md)): drops are where drop
elaboration put them, exact by construction, with no `finally` per scope or
`undefined` left by a move, and a panic runs the cleanup blocks `-C panic=unwind`
MIR has, from a `catch`. Async bodies are the coroutine transform's state machines,
a class each. The MIR spike ([#36](https://github.com/kixelated/rust2/pull/36)) ported
the whole lowering and measured it against THIR's: every fixture's differential test
passes either way, but MIR closes about 1,100 of the 1,400 drop refusals in moq-net's
census, runs an async handoff 1.4-5.5x faster at depths 1 to 16 in Node, Bun, and
Chrome, and runs the codec 2-12% slower than THIR, for 9% more gzip on the codec's
bundle and 35% on the async fixture's. Blocks become nested blocks, loops, and `if`s by Ramsey's
"Beyond Relooper", except a coroutine's resume function, which enters loops in the
middle and becomes a loop over a `switch` on the next block. Temporaries assigned
once and read once fold back into the expression that reads them unless that
would reorder an effect.

## Never

Expand Down Expand Up @@ -258,9 +271,15 @@ built natively for wasm32 and run beside its translation on the same inputs by
- `task` trims moq's kio to a channel of `Arc`ed state, waiters, and wakers, under async
functions. Its caller is hand-written TS (`tests/task.ts`): a FIFO executor that runs a
script of spawns, sends, polls, and drops, and logs every poll, wake, and drop, as the
fixture's native executor does. The logs must match byte for byte.
fixture's native executor does. The logs must match byte for byte. `tests/unwind.ts`
also runs the scripts natively on the host (`examples/unwind.rs`), where a panic
unwinds, catching and logging each step's panic and going on, so what a panic drops
must match too.
- `reject` holds constructs outside the subset; its expected errors are `expected.txt`,
and its expected census is `census.md`.
those from MIR `expected-mir.txt`, and its expected census is `census.md`.

The codec, lang, and task fixtures also run their differential tests from MIR
(`codec_mir`, `lang_mir`, and `task_mir`), without snapshots.

`tests/spawn.ts` checks that `rt.spawn` yields to a timer after its 128-poll budget, and
rejects when a future panics as it drops.
Expand Down
Loading