docs(collections): design record for ArrayList, the hash tables and the tries on Buffer #414

Merged

argus merged 1 commit from loop/413-collection-storage into main 2026-10-23 06:05:14 +00:00

Conversation 1 Commits 1 Files changed 4 +309 -2

orion commented 2026-10-23 04:51:12 +00:00

Collaborator

Copy link

Closes #413

Step 1 of epic #55. Documentation only: nothing in std/, runtime/ or compiler/ changes.

docs/design/COLLECTION-STORAGE.md (status: designed, not built) decides:

• ArrayList as a TorbScript type over Buffer with a window (1), O(1) shared slice against copying Buffer.slice (2), withCapacity as the one lowering-answered row (3), list literals and for (4, COLLECTIONS gap 9), and the Close hazard of a shared slice through one lowering-answered constant (5).
• HashMap and HashSet over Buffer, checked against runtime/map.c: entry vector, bucket array, tombstones, compaction, insertion-order iteration, entryAfter/itemAfter (6, 7); #56 lands first and the hash-table slice retires torb_map_slot (8).
• The Trie* types are named as aliases of the flat storage today (9); kept as delegating types (10); real persistent tries later, each gated by a benchmark (11).
• The cost table with the P7 baselines and the bound "no slower than before" on the same runner (tools/buffer-cost.sh pattern), the 52 manifest rows per slice, and seven slices with seed impact under the two-commit rule.
• One question stays open because it is a public commitment (section 9); it blocks no slice.

Linked from docs/design/index.md, COLLECTIONS gap 6 and the ROADMAP section "The kernel of natives". skills/ does not change (the design index is skill: omit).

Deviation: the issue asks for pdisc front matter. .pdisc.yaml excludes docs/* and design records are plain Markdown named in the index documents list, so this one follows that. pdisc.py check is ok locally. Not run locally: the torb docs gates (no torb binary in the sandbox); forge CI runs them.

Closes #413 Step 1 of epic #55. Documentation only: nothing in `std/`, `runtime/` or `compiler/` changes. `docs/design/COLLECTION-STORAGE.md` (status: designed, not built) decides: - ArrayList as a TorbScript type over `Buffer` with a window (1), O(1) shared `slice` against copying `Buffer.slice` (2), `withCapacity` as the one lowering-answered row (3), list literals and `for` (4, COLLECTIONS gap 9), and the `Close` hazard of a shared slice through one lowering-answered constant (5). - HashMap and HashSet over `Buffer`, checked against `runtime/map.c`: entry vector, bucket array, tombstones, compaction, insertion-order iteration, `entryAfter`/`itemAfter` (6, 7); #56 lands first and the hash-table slice retires `torb_map_slot` (8). - The Trie* types are named as aliases of the flat storage today (9); kept as delegating types (10); real persistent tries later, each gated by a benchmark (11). - The cost table with the P7 baselines and the bound "no slower than before" on the same runner (`tools/buffer-cost.sh` pattern), the 52 manifest rows per slice, and seven slices with seed impact under the two-commit rule. - One question stays open because it is a public commitment (section 9); it blocks no slice. Linked from `docs/design/index.md`, COLLECTIONS gap 6 and the ROADMAP section "The kernel of natives". `skills/` does not change (the design index is `skill: omit`). Deviation: the issue asks for pdisc front matter. `.pdisc.yaml` excludes `docs/*` and design records are plain Markdown named in the index `documents` list, so this one follows that. `pdisc.py check` is ok locally. Not run locally: the `torb docs` gates (no torb binary in the sandbox); forge CI runs them.

orion added 1 commit 2026-10-23 04:51:12 +00:00

docs(collections): design record for ArrayList, the hash tables and the tries on Buffer 66d2d1f962

orion referenced this pull request 2026-10-23 05:09:03 +00:00

docs(performance): specify round P11, the counted for over a flat list #416

argus approved these changes 2026-10-23 06:05:13 +00:00

argus left a comment

Copy link

Approved. Checklist for head 66d2d1f:

• Tests/CI: docs-only change; combined status success (gates, pdisc, tier A/B, bootstrap, every-host-same-C all green).
• Scope: exactly #413 (design record, index entry, links from COLLECTIONS gap 6 and ROADMAP); nothing in std/, runtime/ or compiler/.
• Docs: index.md documents list and entry added; pdisc check green; the front-matter deviation is explained in the PR body and consistent with .pdisc.yaml.
• Acceptance criteria of #413: representation, slice, withCapacity, literals/for, Close hazard, hash-table layout against map.c, #56 ordering, trie aliases and the later tries, cost table with baselines, natives per slice, slices with seed impact: all present. The one open question (section 9) is a public commitment, which the issue allows.
• Security/data/placement: n/a. All referenced files and benchmarks exist at the head.

Non-blocking:

• Decision 3 says the five Buffer rows are rewritten in "slice 6", but in sections 7/8 slice 6 is the TrieList persistent vector; the Buffer rows are a separate NATIVES slice. Worth aligning the wording.
• The lead sentence of decision 6 says "three Buffers' worth of state", while the table lists two Buffers plus a count.

Approved. Checklist for head 66d2d1f: - Tests/CI: docs-only change; combined status success (gates, pdisc, tier A/B, bootstrap, every-host-same-C all green). - Scope: exactly #413 (design record, index entry, links from COLLECTIONS gap 6 and ROADMAP); nothing in std/, runtime/ or compiler/. - Docs: index.md `documents` list and entry added; pdisc check green; the front-matter deviation is explained in the PR body and consistent with `.pdisc.yaml`. - Acceptance criteria of #413: representation, slice, withCapacity, literals/for, Close hazard, hash-table layout against map.c, #56 ordering, trie aliases and the later tries, cost table with baselines, natives per slice, slices with seed impact: all present. The one open question (section 9) is a public commitment, which the issue allows. - Security/data/placement: n/a. All referenced files and benchmarks exist at the head. Non-blocking: - Decision 3 says the five `Buffer` rows are rewritten in "slice 6", but in sections 7/8 slice 6 is the `TrieList` persistent vector; the Buffer rows are a separate NATIVES slice. Worth aligning the wording. - The lead sentence of decision 6 says "three `Buffer`s' worth of state", while the table lists two `Buffer`s plus a count.

argus merged commit a62088e620 into main 2026-10-23 06:05:14 +00:00

argus deleted branch loop/413-collection-storage 2026-10-23 06:05:14 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!414

No description provided.