Implement SDK list<T> and Cursor<T> with trusted compiler bindings and generic storage publication across IR and PBX. Pin the runtime provider and include specs, conformance coverage, installed examples, and DSC-0090 lessons.
8.5 KiB
SDK List and snapshot Cursor
Owner: compiler/pbs. List and Cursor algorithms belong to the executable PBS
SDK. Logical guards, complete stored-group transfers and atomic publication are
language-neutral compiler/runtime mechanisms. 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.
Invalid logical indices raise TRAP_OOB, including indices inside physical capacity. Negative lengths, structural overflow and quota refusals preserve the applicable Array/provider fault classification. Failures are never translated into none.
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.
Complete mutation attempts
Private storage transfer preserves whole existing groups, presence tags and reference identities. Shifting must not unpack each public Array optional and repack/rebox every payload. Prepare potentially failing validation, packing, allocations, return carriers, scratch and publication operands before modifying observable storage. Then publish the complete selected slot/range and field changes without a fallible allocation, callback, scheduler or GC boundary.
Any refused attempt leaves size, backing reference, capacity, slots and roots unchanged. This includes insert/remove without growth and preparation of removeAt's optional result. Individually atomic Array instructions do not by themselves establish this guarantee. Previously evaluated argument effects are not rolled back. Unpublished candidates obey normal ownership and budgets.
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. Future Linked and Set producers use Cursor; Map<K,V> uses Cursor<keyval<K,V>>. 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. Those collections and keyval are separate deliveries.
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, full-operation refusals with and without growth, prefix reclamation, last-node retention, editor projections and installed SDK/spec/example distribution. Generic publication also requires 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.