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 README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ par with it on array loops — see [Performance](docs/performance.md).
| WebAssembly | [docs/wasm.md](docs/wasm.md) |
| Memory models (`gc`, `rc`, `none`) | [docs/memory-models.md](docs/memory-models.md) |
| The `-mm=own` single-owner model | [docs/own-memory-model.md](docs/own-memory-model.md) |
| How ready `-mm=own` is | [docs/own-readiness.md](docs/own-readiness.md) |
| Benchmarks against Rust and C++ | [docs/performance.md](docs/performance.md) |
| C and C++ bindings with `tsbindgen` | [docs/tsbindgen.md](docs/tsbindgen.md) |
| Calling C++ classes (`@cpp`) | [docs/cpp-classes.md](docs/cpp-classes.md) |
Expand Down
10 changes: 10 additions & 0 deletions docs/own-memory-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -843,6 +843,7 @@ a reference gives it back on every path out of a function.
## Current limits

`-mm=own` is still in development, and some valid TypeScript does not compile under it yet.
[own-readiness.md](own-readiness.md) says how far it is, with measurements.

- The default library has an `-mm=own` build, and arrays, strings and their methods work. `Map`
and `Set` work with number, boolean and string keys and values (`new Map<string, number>()`,
Expand Down Expand Up @@ -890,6 +891,15 @@ a reference gives it back on every path out of a function.
(`fill`) is copied each time.
- A parameter with a default (`constructor(private items: T[] = [])`) is kept like any other
parameter, whether the caller passes it or not.
- A linked list whose nodes own their `next` works: a local that steps down it (`for (let c =
this.head; c; c = c.next)`) borrows the nodes, a new node goes in at the head (`n.next = this.head;
this.head = n`) or at the tail (`c.next = n`), and `this.head = this.head.next` or `c.next =
c.next.next` takes a node out. The node taken out is freed right there, so read what you need of
it first: `const h = this.head; const v = h.v; this.head = h.next; return v;`, not `return h.v`
after the assignment. Not accepted yet: a node made with the old head as an argument (`this.head =
new Node(v, this.head)`), a walk that assigns a parameter (`n = n.next`), and an insert that
recurses on a parameter and gives it back (`t.left = insert(t.left, v)`); write the last as a
method that recurses on `this`.
- `Shared<T>` cycles are never freed.
- There are no lifetime annotations: a borrow that the compiler cannot follow is an error, even
when the program would be correct. The fix is usually a move, a fresh value or `Shared<T>`.
Expand Down
181 changes: 181 additions & 0 deletions docs/own-readiness.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
# `-mm=own`: readiness

Where the single-owner memory model stands, measured on `main` at `363b13ce`, 2026-11-15, with the
Release compiler on Windows x64. The linked-list rows of [Shapes that matter](#shapes-that-matter)
were rejected in that measurement and are fixed by the change that adds this page; the table shows
them as they are with it. The model itself is described in
[own-memory-model.md](own-memory-model.md); the tiers and their exit criteria are in the
[production-readiness plan](production-readiness-plan.md).

## Verdict

**`-mm=own` is not ready for production. It is usable for new code written for it, and it is a
preview for porting existing TypeScript.**

- Everything its design set out to build is built, and the tracker has no open defect against it.
- Nothing unsound was found in this round of measurement.
- It still rejects about one in five programs the other models accept, and it has no leak-free
way to write a back-reference.
- Memory-safety bugs were still being found in real code in the three days before this was written.
- None of the three tier 3 exit criteria in the plan is met.

It stays in tier 3 ("experimental") in the plan's terms.

## Scorecard

| Area | Status | What it rests on |
| --- | --- | --- |
| Design | Complete | Spec phases 0-8 and the later designs (parameter decorators, facts from object files, immortal keepers, generic containers) are merged. One item is deferred: `WeakRef<T>` under own. |
| Tracker | Clean | No open GitHub issue. The own items of `TSLANG_ISSUES.md` (31-33, 39-42, 47-85) are fixed, with one remnant: whole-program facts (item 48). |
| Soundness | No failure found, not proven | See [Soundness](#soundness). |
| Coverage of TypeScript | Partial | 707 of 882 corpus files (80%) compile. See [Coverage](#coverage). |
| Default library | Nearly complete | Its `-mm=own` build passes its tests; 2 of 230 are skipped as refused by design (`array_flatMap_shared`, `map_groupBy`). |
| Separate compilation | Works, with a cost | `--own-facts` and shared libraries carry facts. A call of a method of an exported class that is not `@final` still ends every borrow. |
| Platforms | In the release matrix | Windows, Linux, wasm32/wasm64 and Android run the own legs in CI. Only Windows was run for this document. |
| Tests | Broad | 560 files in `tslang/test/tester/own` (359 of them expected errors), and the general corpus runs under own in CI. |
| Real code | One program | native_ts_graphics compiles and passes 525/525 under own, after a 55-file source change. See [Real code](#real-code). |
| Tier 3 exit criteria | 0 of 3 | See [Exit criteria](#exit-criteria). |

## Soundness

The claim of the model is that an accepted program never frees a block twice, never reads a freed
one and never leaks. What was checked:

- **Differential fuzzing.** `tslang/test/fuzz/mm_fuzz.py`, 400 seeds from 915000: 738 programs
checked, 353 accepted by own, each built ahead of time and compared with `-mm=gc`. No mismatch,
no crash, under own or rc.
- **Churn loops.** Four shapes that older notes or the guide called refused, and that compile today
(a parameter a generator assigns, a value merged from `?:` stored into a field and then used, a
new object passed through a function that returns its argument, a reassigned `Shared<T>`
parameter): one to three million iterations each, ahead of time. Output equal to gc's, and peak
memory flat at 5.7 MB.
- **The corpus.** No file made the compiler crash under own.

This is weak evidence, for three reasons. Half of what the fuzzer generates is rejected, so about
350 programs ran. It was Windows only, and the Windows heap hides double frees that glibc reports.
And compiling one real codebase turned up, between 2026-11-13 and 2026-11-15, a read of freed
memory (item 50), a double free (item 83), a fix that leaked 2.7 GB and was backed out (item 80),
and a compiler crash in about one run in 500 (#867). All are fixed. The rate says more are there.

## Coverage

Every file of `tslang/test/tester/tests` was compiled with `--no-default-lib --opt --opt_level=3`
under gc and under own. Of 915 files, 882 compile under gc; of those, 707 compile under own and 175
are rejected. The corpus holds own's own regression tests, which raises the figure, and a few
multi-file tests compiled alone without their facts, which lowers it.

The rejections, by message:

| Count | Message | Kind |
| --- | --- | --- |
| 23 | takes a second reference; cannot prove a move or a borrow here yet | Not yet |
| 19 | borrows a field but is used after it may be released or overwritten | Rule, often conservative |
| 19 | used after its value was moved | Rule |
| 15 | borrows a field and cannot be stored, returned or captured | Rule |
| 9 | an object literal that holds a value it owns is moved only into a local or returned | Not yet |
| 8 | a parameter, kept here, but the callers cannot be made to give it up | Needs `@keeps` |
| 7 | merged from several branches (`?:`, `&&`, `\|\|`, `??`, a loop) | Not yet |
| 7 + 6 | borrows an element (stored, or used after a release) | Rule |
| 6 + 4 | borrows the result of a call | Rule |
| 5 | captured by a closure that escapes, and still used | By design |
| 5 | a global's value lent to a call that may release it | Conservative |
| 42 | 22 other messages, one to five files each | Mixed |

About 50 of the 175 say in the message that the compiler cannot prove something yet. The rest are
the model's rules; some of those are the single-owner design working as intended, and some are the
analysis being more careful than the program needs.

### Shapes that matter

Probed one by one under the JIT:

| Shape | Result |
| --- | --- |
| Walking a list: `for (let c = this.head; c; c = c.next)` | Compiles and runs |
| List `push`: `n.next = this.head; this.head = n` | Compiles and runs |
| Appending at the tail, cutting the tail: `c.next = n`, `c.next = null` after the walk | Compiles and runs |
| List `pop`: `this.head = this.head.next`; unlinking: `c.next = c.next.next` | Compiles and runs |
| Using the popped node afterwards: `this.head = h.next; return h.v` | Rejected: the node is freed by the assignment; read it first |
| Push through a constructor: `this.head = new Node(v, this.head)` | Rejected |
| Walking by assigning a parameter: `n = n.next` | Rejected |
| Tree insert by recursion on a parameter: `t.l = ins(t.l, v)` | Rejected |
| Tree insert and sum as methods recursing on `this` | Compiles and runs |
| Parent link: `k.parent = this` | Rejected; the answer is `Shared<T>`, whose cycles leak |
| `new WeakRef(a)` | Rejected: built on the collector |
| `new Map<string, Node>()`, `filter` over class instances | Rejected by design; `Shared<Node>` |
| Swap through a local: `let t = a[i]; a[i] = a[j]; a[j] = t` | Rejected by design; `[a[i], a[j]] = [a[j], a[i]]` |
| `x ??= new B()` on a parameter | Rejected ("merged from several branches") |
| A closure that assigns a parameter it captures | Rejected |
| `m.forEach((v, k) => { total += v; })` on a `Map` or a `Set` | Compiles and runs |
| `m.forEach((v, k) => { names.push(k); })` | Rejected, with no source position in the error |
| try/catch/finally, unions, `any`, async functions (11 corpus files) | Compile; async was not run for this document |

## Real code

native_ts_graphics (the `build-own` of powder_sandbox) is the one outside codebase compiled under
own. The sweep that got it there produced compiler items 50-85 in three days, and the source needed
a 55-file change (+432 / -351): getters that return an object of the caller's own instead of a lent
one, statements reordered so a value is used before it is given away, global rows copied where
kept, `@final` on classes, and swaps in place of a sort through a temporary. With those it passes
its 525 tests under own, as under gc and rc.

That is the realistic cost of a port today: the program works, and a noticeable share of it is
rewritten to say who owns what.

## Performance

Covered in [performance.md](performance.md) and [memory-models.md](memory-models.md). In short: the
ray tracer under own runs within about 1.4x of the Rust version with `@value` vectors, memory stays
at the working set, and there is no collector or count at run time. Performance is not what holds
the model back.

## Exit criteria

From the plan's Phase 5 row for `-mm=own`:

| Criterion | Met | Notes |
| --- | --- | --- |
| Close the open items: optional accessor fields, capturing callbacks | No | An optional interface field filled by an accessor is a clean error under every model, not supported. Capturing callbacks over `Map` and `Set` work for numbers and fail when the callback pushes a key into a captured array. |
| A written specification of the ownership rules | No | The rules exist as a design log of about 5,000 lines (`tslang/docs/superpowers/specs/2026-09-24-own-memory-model-design.md`) and as the user guide. Neither is a specification someone could implement or check against. |
| Error messages reviewed by someone new to the model | No | Not done. Without `--di` most messages say `'this value'` in place of the variable's name. |

The tier also repeats the Phase 2 gate for its own scope: no open crash or miscompile, an
assertions-enabled CI leg, and a soak run. The first holds today; the other two do not exist for own.

## What is left, in order

1. **A non-owning back-reference.** `WeakRef<T>` under own, or a declared borrowing field. Without
it a tree with parent links either does not compile or leaks.
2. **The rest of linked structures.** A list now works; a node built from the old head, a walk
that assigns a parameter and the recursive tree insert do not. These are what a newcomer writes
first.
3. **The "not yet" messages.** Second references the compiler cannot classify, values merged from
branches, object literals that hold owned values.
4. **Capturing callbacks over `Map` and `Set`**, and a source position for the error they give.
5. **Whole-program facts**, so a class nobody extends does not need `@final` to keep its callers'
borrows.
6. **The exit criteria**: a rules specification, an outside review of the messages, variable names
in messages without `--di`.
7. **Soundness evidence at scale**: fuzzing on Linux with a perturbing allocator, an AddressSanitizer
run of compiled own programs, a second and third outside codebase.

## What it is ready for

| Use | Ready |
| --- | --- |
| New code written for own: trees of owners, values, arrays, strings, `Shared<T>` where shared | Yes, as a preview |
| Numeric and allocation-heavy kernels where a collector or counting costs too much | Yes, as a preview |
| Porting an existing TypeScript program unchanged | No |
| Programs built on graphs with back-references | No |
| A release that promises memory safety to outside users | No |

## How this was measured

- Compiler: `main` at `363b13ce`, Release, Windows 11 x64. Default library built the same day.
- Corpus sweep: each file of `tslang/test/tester/tests` with `--emit=llvm --no-default-lib --opt
--opt_level=3`, under `-mm=gc` and `-mm=own`, compile only.
- Fuzzer: `python mm_fuzz.py --jobs 4 run --count 400 --seed 915000`.
- Probes and churn loops: small files, JIT for accept or reject, ahead-of-time builds for output and
peak working set against gc.
- Not run: the full ctest suite, the default library's tests, anything on Linux, wasm or Android.
Those lines of the scorecard come from the CI configuration and the repository's records.
Original file line number Diff line number Diff line change
Expand Up @@ -5795,3 +5795,58 @@ function does not own" (`own_err_delete_param`). A local read after its `delete`

Tests: `own_param_assigned` (own, rc, gc), `own_delete` (own, rc), and the seven corpus files only these
two stopped, under own (`test-*-own-flipped-*`).

## 82. A linked list: a local that walks down, a node taken out, 2026-11-16

A singly linked list whose nodes own their `next` was refused in every method a newcomer writes first:
the walk, `push`, the append at the tail and `pop`. Four rules, all in the inference pass.

**A `let` given only borrows owns nothing (`chainOf`).** A read through such a `let` (TSLANG 56) had
the `let`'s slot for its root, and the slot's assignments and release for the ends of what was read:
`c = c.next` in a loop ended its own borrow. The chain now goes through the `let` to the roots of every
value it is given (its initializer and each assignment), with `anyPlace` set: what is read through `c`
lasts as long as what `c` borrowed, and any release that could hold it ends it. The declaration is a
kill for the uses of an assigned borrow (`collectBorrowerUses`), as an assignment is: a path from a
drop back to the declaration does not carry the old value. Measured on a function with 8,000 reads
through one such `let`: 63-69 s before, 7.4-7.8 s now (the slot's ends were found again for each read).

**A field of what was read, overwritten, frees nothing above it (`checkPlaceRead`, `frees`).** `if (c)
c.next = null` and `c.next = n` after a walk release a field of the borrowed node, not the node: an
owner is never under what it owns. A release of a field or an element is no drop for a read when its
object is the value read, or is read out of it through owning places (an element, or a class field
that is no back-reference and no borrowing field; not through a handle). Through a `let` the read is
assigned to, the same holds when the `let` only walks down from there: every assignment that can
follow gives it a value read out of what it holds, and its declaration cannot run again. A `let` that
may be given the head again is refused (`own_err_list_walk_up`), as is a use of what was read out of
the field before (`own_err_list_lookahead_cut`).

**The refill may store the object the taker is a field of (`refilledFieldTakeOf`).** `n.next =
this.head; this.head = n;` is TSLANG 49's move of a field into another place with the source refilled
right after; rc's retain of the refill's value stopped the match unless that value was `null`. The
retain of the value the refill stores is let through.

**A value taken out of the object its place holds (`splicedFieldTakeOf`).** `this.head =
this.head.next`, `prev.next = prev.next.next`, also through a `const` that names the object. The store's
release of the place frees the object, and with it what its field holds. The read is a take: the field
is given up right before the release, and the value is the place's. The match is local: the read, rc's
retain, the place's release and the store in one block with only reads between, the object a read of
the same field of the same object as the store's place, both owning class fields that hold an object
or null. That the place still holds the object there is the borrow check of the object's own read;
the store is no use of that borrow (`splicedTakers`, filled where a function's state is reset), and a
use of the object after it is refused (`own_err_list_pop_used_after`): read what is needed first.

The object may be one an append-only global keeps too (spec 25, the keepers), which the release does
not free. Emptying its field would then show: gc keeps `KEEP[0].next`. So the field is given up by a
new op, `ts.TakeOutOfField(object, field)`: a mortal object's field is emptied, an immortal object
keeps it and the value it holds is made immortal, since the kept object and the place both hold it
from then on (`OwnershipRoutineLogic::emitTakeOutOfField`; `00linked_list_kept`).

Still refused: the popped node used after the assignment, a node made with the old head as an argument
(`this.head = new Node(v, this.head)`: a call between the read and the refill), a walk that assigns a
parameter (`n = n.next`: an assigned parameter is kept, section 81), and an insert that recurses on a
parameter and gives it back (`t.left = insert(t.left, v)`).

Tests: `00linked_list` and `00linked_list_kept` (own, rc, gc, none; also `-noopt` under own), and
`own_err_list_walk_dropped`, `_walk_call_drops`, `_lookahead_cut`, `_walk_up`, `_pop_used_after`,
`_next_kept_twice`, `_refill_from_param`. The corpus, the mm fuzzer (1,000 seeds) and native_ts_graphics'
own build are unchanged by it: no file newly refused.
Loading
Loading