10 KiB
SDK List and snapshot Cursor
Owner: compiler/pbs. List and Cursor algorithms belong to the executable PBS
SDK. Typed storage, complete stored-group transfers and terminal failure are
language-neutral compiler/runtime mechanisms. Logical checks are SDK algorithms. This contract builds on
arrays and optional,
generic structs and
generic contracts.
Type, identity and construction
The SDK exports the ordinary generic struct list<T> and contract Cursor<T>
from its collections module. Applications are invariant. A directly optional
element, including through grouping, is invalid; optional (list<T>) is valid.
Nested valid arrays, structs, contracts, functions and value groups keep their
normal types and identities. An unrelated user declaration named list does not
acquire SDK behavior.
new list<T>() creates size zero and capacity 16. new list<T>(capacity) creates
size zero with exactly that capacity, including zero. Contextual new list()
and new list(capacity) require an expected concrete List type. Constructor
values do not infer T. Only the backing array is allocated; elements are absent.
List has stable reference identity. Assignment and parameter passing share that identity; aliases observe mutations even when growth replaces its private backing array. Storage, internal nodes and private compiler bindings are inaccessible to clients. No public Dynamic or universal element type is introduced.
Logical positions and operations
Every observable List satisfies 0 <= size <= capacity. Size includes holes.
Capacity is physical storage and never makes additional indices accessible.
Zero and false are present values, distinct from holes.
| Operation | Result | Behavior |
|---|---|---|
size() |
long | Logical positions, including holes |
capacity() |
long | Physical backing length |
xs[i] |
optional T | Present value or hole at 0 <= i < size |
xs[i] = value |
unit | Replace one valid position without extending size |
add(value) |
unit | Append at size; do not fill earlier holes |
insert(i, value) |
unit | Insert at 0 <= i <= size; shift slots and holes right |
clearAt(i) |
unit | Clear a valid position without shifting or changing size |
removeAt(i) |
optional T | Return old content, shift left, clear old tail, decrement size |
clear() |
unit | Clear all contents and size, preserve capacity |
resize(n) |
unit | Grow with holes or clear discarded suffix; set logical size |
reserve(n) |
unit | Grow exactly to n only when n exceeds capacity |
trim() |
unit | Set capacity exactly to size, including zero |
cursor() |
Cursor | Complete immediate snapshot of present occurrences |
Removing a hole still removes its position and decrements size. Shrink, removal
and clear discard all hidden suffix references: regrowing must not resurrect old
values. Physical shrinking occurs only through trim. resize(0) preserves capacity.
Receiver and arguments are evaluated once in source order. Indices, lengths and capacities accept int and long with localized lossless promotion; this does not add general numeric conversion. No long value may be truncated.
SDK checks reject invalid logical indices, negative lengths/capacities and requests above Array's u32 structural maximum before mutation with TRAP_EXPLICIT and a source location. This includes indices inside physical capacity. Physical Array instructions that actually execute retain their own fault/resource classification. Failures are never translated into none. Growth arithmetic must not overflow or truncate; clamping applies only to a valid requested length.
Capacity policy
When required size r exceeds capacity c, automatic growth is:
candidate = max(r, c + max(1, ceil(c / 2)))
new capacity = min(Array structural maximum, candidate)
Calculate without overflow. Clamp only if r itself fits the structural maximum; otherwise raise the applicable provider failure. Explicit reserve uses exactly n, never shrinks and preserves size. Trim uses exactly size. Old and candidate arrays may coexist; neither discarded references nor replaced storage promise immediate GC or immediate quota recovery.
Mutation preparation, visible writes and faults
Transfer whole stored groups, presence tags and reference identities; do not unpack and rebox all existing elements during shifting. Prepare validation, next size, inserted values, candidates and optional return carriers before the first visible write. This preparation does not prove all later instructions infallible. Values/receiver/argument effects already evaluated are not rolled back.
With growth, construct a private candidate and copy prefix/suffix directly into their final positions; store the new value privately, then install storage and length in sequence. Without growth, prepare the inserted stored group in a private one-slot array, shift with overlap-safe ARRAY_COPY, copy that complete prepared slot, then update length. Both copies retain scratch, validation and charging, including empty copies. This one-slot preparation is charged allocation, not a promise of allocation-free insertion or whole-array reconstruction.
Removal prepares its optional result, shifts the suffix, clears the old tail and updates length. Clear and in-capacity resize clear the selected interval in index order before assigning length. Growing resize prepares/copies a private candidate before installing storage and length. Reserve/trim prepare/copy candidates and replace storage only. Indexed replacement/clearAt alter a single checked position.
| Outcome | Guarantee |
|---|---|
| Logical rejection or preparation refusal before the first visible write | Preserve previous size, backing, capacity, slots and collection roots. Unpublished candidates obey normal ownership/quotas; immediate quota recovery is not promised. |
| Successful return | All collection invariants, cleanup, groups, identity and snapshot contracts hold. |
| Internal/resource fault after the first visible write | Propagate the fault; earlier writes can remain and collection invariants can be incomplete. No rollback, safe reuse, retry or automatic recovery is promised. |
The last row explicitly replaces the former whole-mutation refusal guarantee. Individual instruction failure still preserves its own entry operands/storage. No catch, poison flag or recovery API is introduced. The SDK inserts no user callbacks or explicit suspension during mutation updates. BudgetExhausted and pauses are resumable instruction boundaries, not faults or rollback. The host or debugger may observe intermediate state; a method is not an atomic region.
Cursor protocol
declare contract Cursor<T> {
fn hasNext() -> bool;
fn next();
fn current() -> optional T;
}
The shared SDK implementation captures one private immutable singly linked, non-circular node per present occurrence. It uses no snapshot array and retains no source-slot or editable source-node association. List capture scans logical positions and preserves increasing index order, duplicates and complete values. Capture finishes before returning; failure exposes no partial Cursor.
A nonempty Cursor starts on its first node. hasNext() tests for a successor.
next() advances only when a successor exists; otherwise it does nothing.
current() reports the current node without advancing. Only a snapshot born
empty reports none. Repeated calls never advance beyond the last node.
| Snapshot and position | hasNext() | current() |
|---|---|---|
| Empty, initially or after any next | false | none |
| [A], initially or after any next | false | some(A) |
| [A, B], initially | true | some(A) |
| [A, B], after one or any further next | false | some(B) |
Consume the current value before deciding whether to advance:
while true {
if let value = cursor.current() {
// Consume value.
} else {
break;
}
if cursor.hasNext() {
cursor.next();
} else {
break;
}
}
A hasNext-only loop skips the last element. Waiting for current to become none does not terminate a nonempty snapshot. There is no index, reset, removal, clone or new for-in protocol. Another complete traversal creates another snapshot.
Captured object references preserve identity and observe subsequent field mutation. Later List insertions, replacements, removals, clear, resize and backing changes do not alter the captured sequence. Snapshot links and captured values are not rewritten. The Cursor retains only its current node and suffix, allowing consumed prefixes to become unreachable. It keeps the final node/value while reachable. Other owners remain independent; reclamation happens through normal GC.
The outer optional describes node existence. A future producer with optional T
must distinguish some(none) from an empty Cursor. Type/resource faults remain
faults. List itself rejects directly optional elements.
Reuse, costs and conformance
The shared implementation is independent of List representation. Linked uses Cursor for forward and reverse captures. Set produces Cursor; Map<K,V> uses Cursor<keyval<K,V>> as specified by Map/Keyval. Set/Map gain no ordering guarantee between captures. A captured keyval association is read-only and does not follow later association replacement; referenced objects stay shared. Map owns entry production and Keyval representation while reusing this protocol.
For n logical List positions and k present occurrences, capture takes O(n) work and O(k) additional nodes; next follows one link in O(1). Each node costs allocation, ownership and eventual GC work. Do not promise lower memory than arrays, zero allocation or allocation-free optional results. All complete groups remain rooted through allocations and calls; provider quotas remain unchanged.
Conformance must execute real PBS through common IR and PBX in the production VM. It covers every operation, constructor/type rule, logical bounds, exact growth, holes and full groups, aliases, the entire Cursor table, snapshot independence, shared object mutation, non-List producers, refusals before and after visible mutation with and without growth, prefix reclamation, last-node retention, editor projections and installed SDK/spec/example distribution. Neutral storage/copy/terminal paths also require non-PBS tests.
Value search/removal, sorting, bulk APIs, new equality, public nodes, deep freezing, general effect/transaction syntax and Linked/Set/Map implementations are out of scope.