types/rtti/todo: closed containers by default, then option as omission - #1725

…ssion

Files one issue with two ordered stages: a bare `Struct`/`Tuple` becomes
closed with `open(c)`/`rest(c, r)` stating otherwise, and then `option(t)`
becomes omission rather than `or(t, undefined)`.

Stage 1 makes `validate`'s success cast sound — `Ts<readonly[42]>` is the
exact tuple, so returning `[42, 'extra']` under that type is a lie about
`.length` — and matches what `edag` already writes 21 times. Stage 2 closes
the gap where no schema separates `{}` from `{ a: undefined }`, and forces
`parse`'s construction answer, which dissolves parse-omits-undefined-members.

The order is deliberate: stage 2 reads the acceptance tables stage 1
rewrites, so the reverse order rewrites every table, proof and consumer
schema twice.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

`Ts<[1, or(option, number)]>` is `readonly[1,number?]`, and that rendering is
exact rather than an approximation: checked against the repo's tsc, the type
accepts `[1]` and `[1, 2]`, rejects `[1, undefined]` with TS2322, and rejects
`[1, 2, 3]`, which is what the closed schema does. Reading position 1 still
gives `number | undefined`, matching JavaScript.

Records that the exactness needs both stages — stage 1 for the length, stage 2
for the element type — that it depends on `exactOptionalPropertyTypes`, which
this repo sets, and that the runtime printer and `Ts<>` converge on the same
spelling afterwards. Adds the proof task that pins it.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

Review found three claims in stage 2 that do not hold; all three verified
against the code and fixed.

The set algebra is bitwise and genuinely unchanged, but the normalizations
are not "two bit tests swapped": three sites read absence and only
`objectMayOmit` is a substitution. `trimPrefix` must move its test to the
trailing declared position, since a rest carries no absent bit and a bit test
on it is dead — measured, `close([option(number)], option(number))` and
`array(option(number))` are one Node today, and the stage-2 counterpart
`rest([or(option, number)], number)` would no longer collapse to
`array(number)`. The declared-key drop keeps its "rest is gone" guard, which
`objectSet` already applies; only `isTop` moves, to `or(option, unknown)` for
a declared member.

Also settles the case the bit-strip creates: `array(option)` is the empty
array, since length bounds a closed array, which is what `close` already
does. That surfaced a live divergence — `toData(array(or()))` and
`toData(close([]))` are the same Node, yet the thunk readers accept
`new Array(1)` for one and reject it for the other, because the array handler
walks `Object.entries` and never bounds length.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

Review found the stage 2 rule undefined when a rest resolves to a rule.
`trimPrefix` already declines to see through a reference, and a rule cannot be
stripped globally: the same rule may sit at a declared position, where the bit
is meaningful. For `X = or(option, array(X))` the stripped form is not even
inline — it is the fixpoint `X' = array(X')`.

Stage 2 therefore strips an inline rest and leaves a referenced one alone,
joining the structural incompleteness the data form already accepts for rule
names: semantically equal, structurally distinct, mutual subsets rather than
equal. `subset` masks the absent bit at rest positions so that mutual-subset
property actually holds. Derived rules would restore canonicality at the price
of the bisimulation-grade machinery the module deliberately avoids; recorded
as the alternative with its cost.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

Review found a third renderer over the data form that the task lists never
named. `media/json/schema/module.f.mjs` derives `required` and `minItems` from
`admitsUndefined`, so under stage 2 `{ a: or(option, number) }` would render
`required: ["a"]` while RTTI accepts `{}`.

Its two uses of the undefined bit split rather than both moving: the one
driving `required`/`minItems` asks about absence and takes the absent bit,
while `stripUndefined` asks what JSON can carry and stays on `undefined` — so
a key of `or(number, undefined)` renders as a required `number`, an
under-approximation JSON forces, alongside the `NaN` and `-0` corners the
module already documents.

Stage 1 reaches the same file more quietly: it follows the data form, so a
bare struct starts rendering `additionalProperties: false` on its own, and its
proof pins the old output.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

…ions

Review found that omitting an absent member from `parse`'s entry list corrupts
the array kind: `arrayRebuild` is `entries => entries.map(([, v]) => v)`, so
`[, 3]` would rebuild as `[3]`, shifting the required value to index 0 and
returning something that fails its own schema. Acceptance rows would not catch
it, so the proof now asserts on the built value.

The predecessor issue avoided this by only dropping a trailing run and leaving
an interior `undefined` explicit. Stage 2 cannot: absence and `undefined` are
different values now, so an interior absent position has to stay a hole.

Records the constraint that decides the implementation. `Array.prototype.map`
preserves holes, `Array.from({ length }, ...)` yields a dense array, and
FunctionalScript has no index assignment or mutation — so the array kind's
rebuild maps over the value while the check keeps walking the schema.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

Two review findings, both real.

`CloseTs<C> = ConstTs<C>` ignores its rest, which was harmless while closed was
the wrapper. After stage 1 the open form is the wrapper, so a straight rename
would make `Ts<typeof open([42])>` the exact `readonly[42]` while
`validate(open([42]))([42, 'extra'])` returns two elements — the unsound cast
relocated rather than removed. The struct kind needs nothing, being width-open
already; the tuple tail turns out to be expressible, measured against the
repo's tsc: a mapped schema tuple takes a rest element, `...unknown[]` covers
`open(c)`, and a rest may follow an optional element. `TupleTs`'s documented
failure is that tail composed with the trailing-optional transform, which stage
1 must spike.

Stage 2 never tasked the `option(t)` call sites: 52 across 10 modules outside
rtti. `checkJs` makes a missed one `TS2554` rather than a silently
absence-only schema, verified, but the schemas are wrong until migrated.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

…iblings

Human review, four items, all verified.

The migration is not a rename. `option(t)` is `or(t, undefined)`, so it accepts
a present `undefined` — measured — and rewriting it to `or(option, t)` narrows
every migrated schema; the faithful form is `or(option, t, undefined)`. This
issue takes the narrowing deliberately, per site rather than swept, and the
changelog now says the schemas got stricter rather than that a spelling
changed.

The `close` counts were per-line, not per-occurrence: `data/proof.f.mjs` is 50
rather than 39, `parse/proof.f.mjs` (24) was missing, and the two `ts` proofs
were uncounted — 124 in all.

Stage 2's proof task now names the pin it abolishes, `validate/proof.f.mjs:290`,
whose `[undefined, 5]` is commented as the same value as the hole and stops
being so.

Related now cites both siblings: #1716, whose lever is the `close(c, rest?)`
overload stage 1 deletes and which already documents the empty-rest length-check
defect this file's `array(or())` row belongs to, and #1719, whose worked
examples are written in the eDSL this proposal respells.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

Review observed that `or(option, number)` and `number` accept the same inputs
at the entry while staying structurally distinct, and asked for the bit to be
stripped there as it is in a rest.

Recorded the opposite decision with its reason. A rest node has no life outside
its position — every value that position sees is a present member, so the bit
is vacuous by construction. An entry node is the schema itself, and a `Data` is
serializable, so a consumer may embed it at a member position where the bit is
live; stripping at the root would lose information that reappears as a silent
meaning change on reuse. The two sets really are different, and this form
compares sets — the entry position just cannot witness it.

Joins the rule-name limit in data/README.md as a stated incompleteness rather
than a latent one.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

…readers

Two review findings, both verified, one of them a defect in this file's own
previous fix.

Mapping over the value preserves length, so the trailing absent run would not
shorten and `[1, ,]` under `[1, or(option, number)]` would serialize back to
`[1,null]` — the defect stage 2 exists to remove. The rebuild is slice-then-map:
truncate to the last present declared position, then map the parsed element
results over it, so a trailing run shortens while an interior hole survives.
Measured: slice keeps an interior hole and drops a trailing one, and a map after
either keeps it.

`orVisit` tries union members in order, so a present value under
`or(option, t)` reaches the `option` branch first and needs an ordinary
rejection there. Extending the `Visitor` type does not force it: both
`parseVisitor` and `validateVisitor` are cast to `any`, so a missing handler is
a `v.option is not a function` throw rather than a type error, with no
`try`/`catch` in the language to contain it.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

…sition case

Two review findings, both verified against the code.

"Strip the absent bit" is data-form vocabulary with no meaning in `ts/types.ts`,
where `OptionalFields` keys on `undefined extends Ts<T[K]>` and members arrive
already reduced through `Ts`. The task now names a branded uninhabited marker:
not `never`, which vanishes in a union and takes the information with it, and
not `undefined`, which would make `or(undefined, number)` optional too and
conflate the pair this stage separates. `Exclude` at the array/record element
keeps `Ts<array(or(option, number))>` as `readonly number[]`, and at the reader
result types it is "observable only at a container position" in type-level
vocabulary.

The redesigned `trimPrefix` reaches a referenced trailing position independently
of a referenced rest, and neither it nor `arraySet` takes a rule set to resolve
one with. The referenced exemption now covers both, so `rest([X], number)` with
a recursive `X` stays structurally distinct from `array(number)` by a stated
rule rather than by accident.

Changelog: none

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MQwnUe7SYoUFXchmAfx8Yf

…sites

- `RestTs`'s tail renders `...(Ts<R> | undefined)[]`: both readers check an
  undeclared member as an entry, so a hole past the prefix is accepted
  (verified: `validate(close([42], string))([42, , ])` is `ok`, `hasOwn(v, 1)`
  false) while `...string[]` types that index `string`, and
  `noUncheckedIndexedAccess` is off. `open(c)` is unaffected.
- `arraySetSubset` compares each prefix position straight through `nodeSubset`,
  so the absent bit makes `[or(option, number)]` no subset of `array(number)`
  though both its values are admitted. Split the position test the way the
  object kind already splits present-set from may-omit, and restate the
  doc comment's `undefined`-keyed shortest-array argument.
- Migrate three more sites stage 1 inverts: `../parse/module.f.mjs`'s module
  doc (the open-default statement, the "do not add a length check"
  instruction, and the `close(...)` examples), `media/json/todo/rtti-parse.md`,
  and `excluded-string-values.md`.

The `...(Ts<R> | undefined)[]` rule needs a guard. `rest([42], option)`
strips its inline rest to nothing after stage 2, so both readers and the
runtime printer see the exact `[42]`, while the formula computes
`Ts<option>` as `never`, adds `undefined`, and renders
`readonly [42, ...undefined[]]` — admitting `[42, undefined]`, which the
schema rejects. `rest([42], or())` is the same in stage 1, without any
absence involved.

Strip absence from the rest; if what remains is empty, render the exact
tuple. Noted that the exact rendering is only fully right once the length
bound lands: measured, `validate(close([42], or()))([42, , ])` is `ok`
while `validate(close([42]))([42, , ])` is `error` — the `array(or())`
divergence the acceptance table already records.

…ion)

- The bound belongs with the rendering it makes sound. Stage 1 is what
  makes `RestTs` render an empty rest as the exact tuple, so shipping
  that without the bound hands `rest([42], or())` a `readonly [42]` over
  a value `validate` accepts at length 2 — the unsound cast this issue
  opens with, on a narrower spelling. Moved out of stage 2 and given
  `rest([42], or())` against `[42, , ]` as a second pin.
- `ArrayTs` emits `readonly []` when the marker exclusion leaves `never`.
  `readonly never[]` is not the empty array: `readonly never[] =
  new Array<never>(1)` type-checks and its `.length` is `number`, while
  `readonly []` rejects it and its `.length` is `0` — both measured. So
  `Ts<array(option)>` would otherwise be wider than the runtime printer
  on the schema "Length still bounds a closed array" exists to settle.
  `RecordTs` needs no counterpart — an object type has no length.

…sites

- Stage 1's validator item covered only the "Do not add a length check"
  paragraph. The module doc also carries a `## Structs and tuples are
  open` section (:29-38) stating the rule as this reader's own contract,
  a `## Closed containers` section (:47-52) defining close(c)/close(c,
  rest), and an `@example` that demonstrates the open reading and calls
  `close` twice. Deleting the paragraph alone would leave two section
  headings asserting the reverse of the code.
- The stage 2 documentation sweep was a markdown inventory, and a comment
  is no more compiled than a .md file, so eleven JSDoc sites in six files
  fell between the two sweeps. Two are statements of the semantics stage
  2 replaces rather than spellings: ts/proof.f.mjs:27 defines `option(t)`
  as `or(t, undefined)`, and data/module.f.mjs:453 argues a design
  decision from the very subset claim that flips in data/proof.f.mjs:620.
  The markdown count stands; the scope did not.

- "The rest admits nothing" needs the semantic definition, not a
  paraphrase. `[or()]` is closed after stage 1 and has no inhabitant, and
  measured, `validate(close([42], [or()]))([42, , ])` is `ok` while
  `([42, 1])` is `error` — so a reader keyed on the exported `never`
  bounds nothing there, and the empty-rest `RestTs` rule would type an
  accepted length-2 array as the exact `readonly [42]`.
  close-counts-trailing-undefined works the criterion out in full (a
  `toData` equality compared up to rule renaming with `subset` both ways,
  fixed by five cases) and this file deletes that file, so the criterion
  is now its own carry-over task with `rest([42], [or()])` pinned.
- checked-const-pin.md:14,36 quotes the `casAddArgs` schema twice as its
  motivating example. Not a call site, so neither the `option(` sweep nor
  `checkJs` reaches it, and it outlives stage 2 — it would be left
  arguing from a schema whose `type` key had become required.

… stage 1

- The empty-tail exception said "the absence-stripped rest is empty",
  which is a different question from the empty-rest criterion the length
  bound uses. A retained reference separates them: for the absence-only
  cycle the reference exemption keeps unstripped, `toData(rest([42], X))`
  still carries `rest: "X"`, so the readers accept hole-only arrays of any
  length, while stripping absence from `X` leaves nothing — the wrong test
  renders the exact `readonly [42]` over a length-2 value. Keyed on the
  criterion it keeps its tail: `...undefined[]` is wider than the schema
  but wide in the direction the success cast needs.
- The acceptance-table paragraph still assigned the `array(or())` fix to
  stage 2, contradicting the task moved to stage 1 two commits ago. Stage
  1 is what cannot ship without it; stage 2 would only have reached the
  same defect again through `array(option)`.

- `| undefined` on the tail is necessary but not sufficient. A hole past
  the prefix can be readable through the prototype, and then it is neither
  absent nor checked: `undeclaredEntries` filters `Object.entries`, so
  measured, `validate(close([42], string))` is `ok` on a `[42, , ]` whose
  prototype carries `1: 99`, and the tail promises `string | undefined`
  over a number. Decide the rest region by what the index reads — walk the
  index range and hold every HasProperty index to the rest. `parse`
  escapes it by rebuilding. Same hazard as stage 2's declared-member
  prototype task, one region to the left.
- Swept the tree for JSDoc stating the open/closed contract instead of
  naming sites as review finds them: types.ts:35-40,:168,
  module.f.mjs:120-128, ts/types.ts:112-124,:194,:201,
  ts/module.f.mjs:292,:308, data/types.ts:33-36,
  data/module.f.mjs:774-780 — all declaration files the tag and
  constructor edits touch without a checker reading the sentence. Plus
  three consumers that justify a design decision by the open default.

a conservative type-level empty-rest test

- `Absent extends _TsRaw<T[K]>` cannot decide optionality. Measured:
  `_TsRaw<unknown>` is `unknown`, `Absent extends unknown` is true, and
  `unknown | Absent` is `unknown` — so the closed `{ a: unknown }`, which
  stage 2 rejects `{}` for, would render `a?:` and become
  indistinguishable from `{ a: or(option, unknown) }`, which the runtime
  printer tells apart. The marker is absorbed by the top; only the schema
  still carries the fact. `OptionalFields` keys on a structural
  `_AdmitsAbsence<T>` recursing through `or`, which does no flattening.
- The inherited-index walk is bounded by `length`, and an inherited index
  can lie above it. Measured, `close([42])` and `array(number)` accept
  such values too, so this is the whole reader family and cannot be fixed
  by extending a walk. Bound the readable set at the `isArray` boundary,
  or state the incompleteness.
- `RestTs` cannot evaluate the empty-rest criterion — it is `toData` plus
  `subset`, and `Ts<[or()]>` is `readonly [never]`, not `never`. Specify a
  conservative syntactic approximation that keeps the tail when it cannot
  tell: wide but sound, versus an unsound dropped tail.

…h hole

Measured with `Array.prototype[10] = 99`: `[42]` has exactly
`Array.prototype` and length 1, and `validate(close([42], string))`
still accepts it while `v[10]` reads `99`. So the boundary check closes
only the per-value half, and the previous claim that it makes every
index walk complete was wrong.

The two halves differ in kind: a per-value prototype is a property of
the argument, which a reader can inspect; pollution of the intrinsic is
a property of the realm, invisible to any per-value test and free to
change between a check and a read. Both need host code outside the
subset, which forbids mutation — so the answer is to state the
assumption in the README beside the others the readers rest on, and
treat a prototype check as a narrowing rather than a fix.

The delete item (:669) called the length bound (:737) and the criterion
(:718) "above" when both follow it, and the criterion item called the
delete item "below" when it precedes. Reworded to the correct directions.

- The consumer-rationale item listed three sites; a sweep that excluded
  proof files missed five. Two media READMEs base a whole extension
  strategy on the blanket claim, and three proof comments state it as the
  reason their row expects `ok` — those rows keep passing under `open(...)`
  while their stated reason stops being true.
- The inherited-index walk named only `undeclaredEntries`.
  `arraySetValidate` filters `Object.entries` on its own path, and
  measured, the data reader answers `ok` on the same value, so fixing one
  would leave the two disagreeing.

The stage-2 task citing "the prototype asymmetry
close-counts-trailing-undefined records" and the `## Related` entry both
sit after stage 1 in a file that survives to stage 2, so deleting the
issue without them leaves dangling links. The stage-1 tasks naming it
are fine — that PR is the one doing the deleting.