From b600a9ab607a766c9b9e064ceed5d2482d323a66 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Tue, 3 Nov 2026 07:12:50 -0800 Subject: [PATCH] chore(quest): record the pushed Vec capacity decision, measuring a wrapper first Co-Authored-By: Claude Opus 5.5 --- quest/m3/ts-vec-clear-capacity.md | 33 +++++++++++++++++++++---------- quest/m3/ts-vec-exact-capacity.md | 2 ++ 2 files changed, 25 insertions(+), 10 deletions(-) diff --git a/quest/m3/ts-vec-clear-capacity.md b/quest/m3/ts-vec-clear-capacity.md index a4d3278c7..8666f5642 100644 --- a/quest/m3/ts-vec-clear-capacity.md +++ b/quest/m3/ts-vec-clear-capacity.md @@ -5,14 +5,31 @@ [rust2-ts](/ts/README.md) keeps a `Vec`'s capacity through every step that drops its length, as std guarantees, when the capacity came only from pushes. That covers `clear`, `truncate`, `pop`, `drain`, `retain`, `dedup`, `resize` down, `split_off`, `remove`, and -`swap_remove`. Differential tests against native Rust prove it. +`swap_remove`. Differential tests against native Rust prove it. A measured wrapper +decides how, or whether the divergence is documented instead. ## Plan -std documents that `clear` and `truncate` leave the capacity unchanged, and that a `Vec` -never shrinks on its own. So the guarantee-only model the maintainer chose on 2026-11-01 -must keep this capacity. It is a guarantee, not the exact capacity -[that quest](/quest/m3/ts-vec-exact-capacity.md) leaves open. +Decided with the maintainer on 2026-11-03: + +> std documents that `clear`/`truncate` don't change a Vec's capacity, but the +> guarantee-only model reports 0 or 1 afterwards. What should the quest aim for? +> +> - ✅ Try a wrapper first: measure ts-vec-exact-capacity's untried idea, a Vec object +> holding its own length and capacity over its array, on push/stack and the other TS +> benchmarks, against the 1.1x-2.8x of peak tracking, before choosing. +> - Fix it and accept the measured cost. +> - Document the divergence and drop the quest. + +This conflicts with the 2026-11-02 decision recorded in +[that quest](/quest/m3/ts-vec-exact-capacity.md) to keep only std's capacity guarantees, +since `clear` and `truncate` keeping the capacity is itself documented. So the first step +is a measurement: build the wrapper and time it on `push/stack` and the other TS +benchmarks in Node, Chrome, Bun, and Firefox, against peak tracking's 1.24x, 1.11x, 2.3x, +and 2.8x on `push/stack`. Then bring the numbers back to choose between the wrapper, +fixing it at the measured cost, and documenting the divergence. A wrapper that holds its +own capacity would give std's exact capacity too, so this quest may merge with +[that quest](/quest/m3/ts-vec-exact-capacity.md) once measured. A `Vec` whose capacity is implicit, grown by pushes or made exact by `vecExact`, reads it back through `capOf` from its current length, so the capacity falls with the length. @@ -38,13 +55,9 @@ floor that `with_capacity` or `reserve` set, and those already hold their capaci cases need a check that the capacity never drops below what it was before a step that shortens the vector. -Recommendation: record the implicit capacity once, when a step first drops the length -below it, so later steps grow from it. Measure on `push/stack` across engines first. A -record made on every pop cost 1.24x to 2.8x there in that quest's measurement. - Public API: the translator's output. ## Related - [A vector's exact capacity as it shrinks](/quest/m3/ts-vec-exact-capacity.md) - std's exact capacity, beyond its guarantees, so a deque made from a shrunk `Vec` splits its slices where std's does -- `quest/m3/ts-clone-from-capacity.md`, added in [moq-dev/rust2#527](https://github.com/moq-dev/rust2/pull/527) - the capacity of a `Vec` that `clone_from` writes over inside a container; link it by path once #527 lands +- [A vector's capacity where clone_from writes it in a container](/quest/m3/ts-clone-from-capacity.md) - the capacity of a `Vec` that `clone_from` writes over inside a container diff --git a/quest/m3/ts-vec-exact-capacity.md b/quest/m3/ts-vec-exact-capacity.md index 2ffb7654c..6ece2b6d0 100644 --- a/quest/m3/ts-vec-exact-capacity.md +++ b/quest/m3/ts-vec-exact-capacity.md @@ -23,6 +23,8 @@ capacity the runtime models for the `Vec`, which holds only std's guarantees (de differently from std's. - Untried: a `Vec` as a wrapper object holding its own length and capacity over its array, measured on the same workload before it is weighed against that decision. + [The pushed capacity quest](/quest/m3/ts-vec-clear-capacity.md) measures it first, as + the maintainer decided on 2026-11-03. Public API: the translator's output.