docs: consolidate canonical specs and preserve PBS reference IDs
This commit is contained in:
@@ -0,0 +1,213 @@
|
||||
# SDK List and snapshot Cursor
|
||||
|
||||
Status: Normative. Owner: `compiler/pbs`.
|
||||
Scope: SDK List and Cursor.
|
||||
|
||||
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](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md),
|
||||
[generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md) and
|
||||
[generic contracts](16.%20Generic%20Contracts%20Specification.md).
|
||||
|
||||
## Authority and scope
|
||||
|
||||
This chapter is the canonical owner of the detailed contract described below.
|
||||
The [domain reading guide](README.md) identifies related chapters and their
|
||||
separate responsibilities. Cross-cutting chapters refer here for these rules.
|
||||
Runtime-owned ABI, instruction, resource and execution contracts retain their
|
||||
authority; this chapter specifies their compiler or PBS consumer requirements.
|
||||
|
||||
## 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<T> | 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:
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```pbs
|
||||
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:
|
||||
|
||||
```pbs
|
||||
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.
|
||||
[Stack/Queue](25.%20SDK%20Stack%20and%20Queue%20Specification.md) capture in their LIFO/FIFO removal orders.
|
||||
[Linked](22.%20SDK%20Linked%20and%20Cursor%20Specification.md) uses Cursor<T> for forward and reverse captures.
|
||||
[Set](23.%20SDK%20Set%20and%20Identity%20Specification.md) produces Cursor<T>; Map<K,V> uses
|
||||
Cursor<keyval<K,V>> as specified by [Map/Keyval](24.%20SDK%20Map%20and%20Keyval%20Specification.md).
|
||||
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.
|
||||
Reference in New Issue
Block a user