collections: hide `Staged` and the stage types (C8)

orion commented

2026-10-05 21:07:24 +00:00

Collaborator

Context

std/iteration exports Staged and ten per-stage iterator types without anything outside the package naming them. COLLECTIONS.md section 3.6 makes the rule: a type is public when something outside the package names it, and not otherwise. Iterate.through is declared as answering Iterate<Output>, and std/iteration/src/lib.trb already says "the stage types themselves are not exported". This slice makes the declarations agree.

Goal

Drop public from:

Staged in std/iteration/src/staged.trb (the std/stream Staged<Input, Item, Failure> is a different type and keeps its public and its export),
the ten stage types in std/iteration/src/stages.trb: Mapped, Filtered, FilterMapped, MappedWhile, FlatMapped, Taken, Skipped, TakenWhile, Zipped, Sorted.

Queueing stays public and exported (a driver outside the package reaches it, STREAMS section 13 point 6). The *Mapping / *Filtering stage values in stage.trb are already non-public. The rule of section 3.6 goes into the module comment of std/iteration/src/lib.trb.

Acceptance criteria

public removed from exactly the eleven types above; Queueing, the traits, the stage functions and std/stream's Staged unchanged.
The module comment of std/iteration/src/lib.trb states the rule "a type is public when something outside the package names it, and not otherwise" (and that Staged and the stage types are the cases).
docs/standard-library/iteration.md ("Staged and Queueing") and the generated skills/torbscript-standard-library/references/standard-library/iteration.md no longer present Staged as a name users can write; skills/ regenerated.
Nothing outside std/iteration names the eleven types (checked: std/stream, the compiler, tests, examples). If the checker rejects a non-public type in the signature of a public member, record the message and fix the declaration, not the rule.
COLLECTIONS.md section 5 marks C8 Done (as C5 and C6 are) and the closing line ("What is left is C2c, then C7 and C8") is updated.
Gates a (and b where CLAUDE.md asks) green in CI.

Source

COLLECTIONS.md C8 and section 3.6 ("Staged is one name in two packages and stays one").

Seed and breaking change

No syntax change, no new native, no new driver flag. The compiler resolves none of these names by string (grepped compiler/src; call.trb only mentions Staged.of in a comment about std/stream).
Not breaking in practice: no code in the repo names the types outside std/iteration, and the public API (Iterate.through, map, filter, ...) is unchanged. No seed refresh needed.

Size

One PR, one refactor(std/iteration) commit (plus the docs/skills regeneration in the same commit or a docs commit). Small, as the design record estimates. The earlier ordering constraint (after C2, so two agents do not edit std/iteration at once) is met: C2/C2b/C2c are done.

Dependencies

None open.

Moved from the planning lists of the docs; the design record stays the specification.

## Context `std/iteration` exports `Staged` and ten per-stage iterator types without anything outside the package naming them. COLLECTIONS.md section 3.6 makes the rule: **a type is `public` when something outside the package names it, and not otherwise.** `Iterate.through` is declared as answering `Iterate<Output>`, and `std/iteration/src/lib.trb` already says "the stage types themselves are not exported". This slice makes the declarations agree. ## Goal Drop `public` from: - `Staged` in `std/iteration/src/staged.trb` (the `std/stream` `Staged<Input, Item, Failure>` is a different type and keeps its `public` and its export), - the ten stage types in `std/iteration/src/stages.trb`: `Mapped`, `Filtered`, `FilterMapped`, `MappedWhile`, `FlatMapped`, `Taken`, `Skipped`, `TakenWhile`, `Zipped`, `Sorted`. `Queueing` stays `public` and exported (a driver outside the package reaches it, STREAMS section 13 point 6). The `*Mapping` / `*Filtering` stage values in `stage.trb` are already non-public. The rule of section 3.6 goes into the module comment of `std/iteration/src/lib.trb`. ## Acceptance criteria - [ ] `public` removed from exactly the eleven types above; `Queueing`, the traits, the stage functions and `std/stream`'s `Staged` unchanged. - [ ] The module comment of `std/iteration/src/lib.trb` states the rule "a type is `public` when something outside the package names it, and not otherwise" (and that `Staged` and the stage types are the cases). - [ ] `docs/standard-library/iteration.md` ("Staged and Queueing") and the generated `skills/torbscript-standard-library/references/standard-library/iteration.md` no longer present `Staged` as a name users can write; `skills/` regenerated. - [ ] Nothing outside `std/iteration` names the eleven types (checked: `std/stream`, the compiler, tests, examples). If the checker rejects a non-public type in the signature of a public member, record the message and fix the declaration, not the rule. - [ ] COLLECTIONS.md section 5 marks C8 **Done** (as C5 and C6 are) and the closing line ("What is left is C2c, then C7 and C8") is updated. - [ ] Gates a (and b where `CLAUDE.md` asks) green in CI. ## Source - [COLLECTIONS.md C8](https://git.torb.dev/torbscript/language/src/commit/393ef2608e4a60b8ff76d8b6b408951b822d887d/docs/design/COLLECTIONS.md#L999) and section 3.6 ("`Staged` is one name in two packages and stays one"). ## Seed and breaking change - No syntax change, no new native, no new driver flag. The compiler resolves none of these names by string (grepped `compiler/src`; `call.trb` only mentions `Staged.of` in a comment about `std/stream`). - Not breaking in practice: no code in the repo names the types outside `std/iteration`, and the public API (`Iterate.through`, `map`, `filter`, ...) is unchanged. No seed refresh needed. ## Size One PR, one `refactor(std/iteration)` commit (plus the docs/skills regeneration in the same commit or a `docs` commit). Small, as the design record estimates. The earlier ordering constraint (after C2, so two agents do not edit `std/iteration` at once) is met: C2/C2b/C2c are done. ## Dependencies None open. _Moved from the planning lists of the docs; the design record stays the specification._

orion added the

loop

label

2026-10-05 21:07:24 +00:00

orion commented

2026-10-08 13:36:49 +00:00

Author

Collaborator

[loop:torbscript] claim refine by session:loop-torbscript-20261008 until 2026-10-08T15:40:00Z

orion added the

ready

label

2026-10-08 13:37:58 +00:00

orion commented

2026-10-08 13:37:59 +00:00

Author

Collaborator

[loop:torbscript] refine: C8 is fully decided in COLLECTIONS.md 3.6 (no open choice, no seed/syntax change, not breaking, one small PR); issue body rewritten to the definition of ready, labelled ready, next: implement

[loop:torbscript] refine: C8 is fully decided in COLLECTIONS.md 3.6 (no open choice, no seed/syntax change, not breaking, one small PR); issue body rewritten to the definition of ready, labelled `ready`, next: implement

orion commented

2026-10-08 13:38:41 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261008 until 2026-10-08T19:40:00Z

orion referenced this issue from a pull request that will close it,

2026-10-08 13:39:56 +00:00

refactor(std/iteration): hide Staged and the stage types (C8) #196

orion referenced this issue

2026-10-08 13:42:17 +00:00

collections: RingList, ConsStack, BankersQueue, Heap (C7) #139

orion commented

2026-10-08 14:06:08 +00:00

Author

Collaborator

[loop:torbscript] implement: PR #196 (branch loop/140-hide-staged) is red and closed, next: waiting (owner decision: the design premise of C8 does not hold)

Finding: in TorbScript public on a declaration is what lets a sibling file import it (compiler/src/semantics/scope.trb: use X from "./stages" reports "X is not exported by ..., It is declared there, but not public"). The package boundary is separate: it is only what std/iteration/src/lib.trb re-exports with public use. Staged and the ten stage types are already not re-exported there, so no consumer outside std/iteration can name them today. Removing public as COLLECTIONS.md 3.6 / C8 prescribes breaks use Staged from "./staged" and use Mapped, Filtered, ... from "./stages" in std/iteration/src/iteration.trb; forge CI bootstrap (linux-x64) of the PR failed in step 1 with error: an expression without a type is not supported by the native back end yet (at std/iteration/src/iteration.trb:130:5) (309 problems).

Options for the owner: (a) amend 3.6/C8: the rule is "a type is exported from the package (public use in lib.trb) when something outside names it", the declarations stay public, and only the lib.trb comment, docs and the C8 note change (no code change); (b) move the stage types and Staged into iteration.trb so they can be non-public (large, mechanical, Queueing stays in staged.trb); (c) add a package-private visibility to the language (syntax change, two-commit seed round). Recommendation: (a).

[loop:torbscript] implement: PR https://git.torb.dev/torbscript/language/pulls/196 (branch `loop/140-hide-staged`) is red and closed, next: waiting (owner decision: the design premise of C8 does not hold) Finding: in TorbScript `public` on a declaration is what lets a *sibling file* import it (`compiler/src/semantics/scope.trb`: `use X from "./stages"` reports "`X` is not exported by ..., It is declared there, but not `public`"). The package boundary is separate: it is only what `std/iteration/src/lib.trb` re-exports with `public use`. `Staged` and the ten stage types are already not re-exported there, so no consumer outside `std/iteration` can name them today. Removing `public` as COLLECTIONS.md 3.6 / C8 prescribes breaks `use Staged from "./staged"` and `use Mapped, Filtered, ... from "./stages"` in `std/iteration/src/iteration.trb`; forge CI `bootstrap (linux-x64)` of the PR failed in step 1 with `error: an expression without a type is not supported by the native back end yet (at std/iteration/src/iteration.trb:130:5)` (309 problems). Options for the owner: (a) amend 3.6/C8: the rule is "a type is exported from the package (`public use` in lib.trb) when something outside names it", the declarations stay `public`, and only the lib.trb comment, docs and the C8 note change (no code change); (b) move the stage types and `Staged` into `iteration.trb` so they can be non-public (large, mechanical, Queueing stays in `staged.trb`); (c) add a package-private visibility to the language (syntax change, two-commit seed round). Recommendation: (a).

orion referenced this issue

2026-10-08 14:06:08 +00:00

refactor(std/iteration): hide Staged and the stage types (C8) #196

orion removed the

ready

label

2026-10-08 14:06:36 +00:00

orion commented

2026-10-08 14:06:36 +00:00

Author

Collaborator

[loop:torbscript] owner decision: C8 (COLLECTIONS.md 3.6) assumes dropping public hides Staged and the stage types, but public is also what lets a sibling file import them; the package boundary is already public use in lib.trb, which does not re-export them (finding and CI evidence in the comment above).

Options: (a) amend 3.6/C8 so the declarations stay public and only lib.trb decides the package surface (docs/comment change, no code); (b) move Staged and the stage types into iteration.trb so they can be non-public (large mechanical change); (c) add package-private visibility to the language (syntax change, seed round). Recommendation: (a).

v: 1
id: q1
asked_by: orion
to: torben
blocking: true
kind: decision
question: C8 hide Staged: amend the design record so the types stay public and lib.trb alone defines the package surface (a), move them into iteration.trb (b), or add package-private visibility to the language (c)?
options: a = amend 3.6/C8 (docs only), b = move types into iteration.trb, c = package-private visibility (syntax, seed)
recommendation: a

next: waiting (owner decision)

[loop:torbscript] owner decision: C8 (COLLECTIONS.md 3.6) assumes dropping `public` hides `Staged` and the stage types, but `public` is also what lets a sibling file import them; the package boundary is already `public use` in `lib.trb`, which does not re-export them (finding and CI evidence in the comment above). Options: (a) amend 3.6/C8 so the declarations stay `public` and only `lib.trb` decides the package surface (docs/comment change, no code); (b) move `Staged` and the stage types into `iteration.trb` so they can be non-public (large mechanical change); (c) add package-private visibility to the language (syntax change, seed round). Recommendation: (a). ```hos-question v: 1 id: q1 asked_by: orion to: torben blocking: true kind: decision question: C8 hide Staged: amend the design record so the types stay public and lib.trb alone defines the package surface (a), move them into iteration.trb (b), or add package-private visibility to the language (c)? options: a = amend 3.6/C8 (docs only), b = move types into iteration.trb, c = package-private visibility (syntax, seed) recommendation: a ``` next: waiting (owner decision)

orion commented

2026-10-08 14:36:20 +00:00

Author

Collaborator

[loop:torbscript] owner decision recorded (torben via WhatsApp, 2026-10-08 16:35 Europe/Berlin): "Große Umbauten sind kein Problem, wenn sie Sinn ergeben" (large refactors are no problem if they make sense).

Owner left the choice to Orion and ruled out size as an argument. Decided on the merits: option (a). Reason: lib.trb with public use already is the package boundary, the types are invisible outside the package today, and public on a declaration means "importable by sibling files". Moving everything into iteration.trb (b) would only work around that by building one oversized file, with no gain in what users see; package-private visibility (c) adds a second concept for a boundary the language already has. Scope: amend COLLECTIONS.md 3.6 / C8 and the doc comments, no code change. Labelled ready.

[loop:torbscript] owner decision recorded (torben via WhatsApp, 2026-10-08 16:35 Europe/Berlin): "Große Umbauten sind kein Problem, wenn sie Sinn ergeben" (large refactors are no problem if they make sense). Owner left the choice to Orion and ruled out size as an argument. Decided on the merits: option (a). Reason: `lib.trb` with `public use` already is the package boundary, the types are invisible outside the package today, and `public` on a declaration means "importable by sibling files". Moving everything into `iteration.trb` (b) would only work around that by building one oversized file, with no gain in what users see; package-private visibility (c) adds a second concept for a boundary the language already has. Scope: amend COLLECTIONS.md 3.6 / C8 and the doc comments, no code change. Labelled `ready`.

orion added the

ready

label

2026-10-08 14:36:20 +00:00

orion commented

2026-10-08 17:50:22 +00:00

Author

Collaborator

[question-closed] q=q1 reason=answered-elsewhere

orion commented

2026-10-08 20:29:00 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261008 until 2026-10-08T22:29Z

orion commented

2026-10-08 20:29:39 +00:00

Author

Collaborator

[loop:torbscript] release implement: no worker could be started (sessions_spawn: the model account is unavailable, usage limit). Nothing was changed. next: implement (ready)

orion commented

2026-10-08 21:04:37 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261008 until 2026-10-08T23:04Z

orion referenced this issue from a pull request that will close it,

2026-10-08 21:05:36 +00:00

docs(collections): keep Staged and the stage types public, lib.trb is the surface (C8) #219

orion referenced this issue from a commit

2026-10-08 21:05:36 +00:00

docs(collections): keep Staged and the stage types public, lib.trb is the surface (C8)

orion commented

2026-10-08 21:20:52 +00:00

Author

Collaborator

[loop:torbscript] implement: PR #219, CI success, next: review (waiting on the merge gate argus)

Option (a): docs/design/COLLECTIONS.md 3.6 and C8 amended (C8 marked Done, revised by 3.6; closing line updated) and the lib.trb module comment states the rule. No code change; docs/standard-library and skills/ untouched (the design record is not part of the generated skills). Worker usage: one subagent (sonnet), small.

[loop:torbscript] implement: PR https://git.torb.dev/torbscript/language/pulls/219, CI success, next: review (waiting on the merge gate argus) Option (a): docs/design/COLLECTIONS.md 3.6 and C8 amended (C8 marked Done, revised by 3.6; closing line updated) and the lib.trb module comment states the rule. No code change; docs/standard-library and skills/ untouched (the design record is not part of the generated skills). Worker usage: one subagent (sonnet), small.

argus closed this issue

2026-10-08 21:20:53 +00:00

Rows
Columns

collections: hide Staged and the stage types (C8) #140

Context

Goal

Acceptance criteria

Source

Seed and breaking change

Size

Dependencies

collections: hide `Staged` and the stage types (C8) #140