147 lines
8.6 KiB
Markdown
147 lines
8.6 KiB
Markdown
# SDK Linked and bidirectional snapshot capture
|
|
|
|
Status: Normative. Owner: `compiler/pbs`.
|
|
Scope: SDK Linked and Cursor.
|
|
|
|
Linked algorithms belong to executable PBS SDK source.
|
|
Typed storage, faults, ownership, GC and quotas remain generic
|
|
compiler/provider mechanisms. This contract builds on [generic structs](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md),
|
|
[arrays and optional](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) and the
|
|
[shared Cursor protocol](21.%20SDK%20List%20and%20Cursor%20Specification.md#cursor-protocol).
|
|
|
|
## 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 collections SDK exports `linked<T>`. It is an ordinary invariant generic
|
|
struct with stable reference identity: aliases observe mutations of the same
|
|
collection. `new linked<T>()` creates an empty collection. Contextual construction
|
|
follows generic struct rules, requiring a concrete expected application; constructor
|
|
values do not infer T. There is no capacity argument.
|
|
|
|
A directly optional element, including through grouping, is invalid.
|
|
`optional (linked<T>)` remains valid, as do otherwise valid element types containing
|
|
optional fields. Values retain their complete groups and normal identities,
|
|
including tuples, native values, arrays, functions and contract views. No public
|
|
Dynamic, universal Element or wrapper node is introduced.
|
|
|
|
Storage consists of private doubly linked nodes, each containing one present
|
|
value. Logical size equals node count. Empty collections have no head or tail;
|
|
one-node collections have the same head and tail. Neighbor links are reciprocal,
|
|
forward and backward traversals agree, and there are no extra predecessor or
|
|
successor nodes beyond the ends. Nodes and private helpers are not a public API.
|
|
|
|
## Operations and bounds
|
|
|
|
| Operation | Result | Behavior |
|
|
| --- | --- | --- |
|
|
| `size()` | long | Number of elements |
|
|
| `first()` / `last()` | optional T | End value, or none when empty |
|
|
| `xs[i]` | optional T | Present value at a valid index |
|
|
| `xs[i] = value` | unit | Replace a valid position without changing size |
|
|
| `add(value)` | unit | Append |
|
|
| `addFirst(value)` | unit | Prepend |
|
|
| `insert(i, value)` | unit | Insert at `0 <= i <= size` |
|
|
| `removeAt(i)` | optional T | Remove and return a valid position |
|
|
| `removeFirst()` / `removeLast()` | optional T | Remove and return end value, or none when empty |
|
|
| `clear()` | unit | Remove all elements and set size to zero |
|
|
| `cursor()` | Cursor<T> | Capture first to last |
|
|
| `reverseCursor()` | Cursor<T> | Capture last to first |
|
|
|
|
Reading, replacing and removing by index require `0 <= i < size`; invalid indices
|
|
raise TRAP_EXPLICIT even when empty. Insertion accepts size, including zero in an empty
|
|
collection. Other insertion indices raise TRAP_EXPLICIT. Every valid position contains
|
|
an element, so indexed read/removal returns a present optional. Zero and false are
|
|
present values. Empty-end results do not suppress type or resource faults.
|
|
|
|
Insertion/removal changes the logical indices of following elements. Replacement
|
|
preserves size. There are no holes, clearAt, capacity, reserve, trim or resize.
|
|
Duplicate occurrences are preserved; no equality or uniqueness rule is imposed.
|
|
Value search/removal is outside this API, consistently with List.
|
|
|
|
Size is nonnegative long. Indices accept int and long with localized lossless
|
|
promotion, without general numeric conversion or truncation. The SDK checks the
|
|
current size against the maximum signed long before incrementing, using SDK comparisons
|
|
and terminal TRAP_EXPLICIT; an unrepresentable next size is rejected before arithmetic or
|
|
mutation. Array's u32 structural maximum is not a Linked size limit. Provider
|
|
quotas and applicable structural limits can refuse allocation much earlier.
|
|
Receiver/arguments evaluate once in source order, including named application.
|
|
|
|
## Snapshots and costs
|
|
|
|
Both capture methods return the existing Cursor<T> contract and preserve its
|
|
complete state table. A nonempty cursor starts on its first captured value;
|
|
hasNext asks whether a successor exists; next without a successor does nothing.
|
|
Only a snapshot born empty has an absent current. Repeated next retains the final
|
|
value. Capturing `[A, B, C]` produces `[A, B, C]` or `[C, B, A]` respectively.
|
|
|
|
Each capture completes before return and owns private immutable singly linked,
|
|
non-circular snapshot nodes, independent of the collection's doubly linked nodes.
|
|
It uses no snapshot array or live association with editable source nodes.
|
|
Subsequent insertion, replacement, removal and clear cannot change the captured
|
|
sequence. Shared objects retain identity and later field changes remain visible.
|
|
There is no removal/reset through Cursor or public node access.
|
|
|
|
End operations locate their nodes without traversal. Indexed operations search
|
|
from the nearer end and remain O(n) in the worst case. Both captures cost O(n)
|
|
work and O(n) additional nodes; next follows one link in O(1). Allocation,
|
|
optional-carrier preparation, ownership and eventual GC retain their normal
|
|
costs. Repeated indexed reads are not an efficient traversal strategy.
|
|
|
|
## Mutation phases and lifetime
|
|
|
|
Before the first visible write, prepare bounds, next size, candidate nodes,
|
|
optional results and complete field values. Insertion updates previous.next or
|
|
head, then next.previous or tail, then length. Removal prepares its result and
|
|
neighbors, updates the same two sides, then length. Indexed replacement updates
|
|
only value; clear assigns head, tail and length in that order. Source algorithms
|
|
own these choices; the VM has no Linked instruction, publication schema or syscall.
|
|
|
|
A logical rejection or preparation refusal before mutation preserves the previous
|
|
head/tail/size, elements and neighbor links. Successful return restores all public
|
|
invariants. An internal/resource fault after the first visible write propagates
|
|
without rollback: earlier writes may remain and topology/size can be incomplete.
|
|
No safe reuse, retry or automatic recovery is promised. This explicitly replaces
|
|
the former whole-method refusal guarantee, and is not a basic-consistency claim.
|
|
Previously evaluated argument effects remain ordinary source effects.
|
|
|
|
Individual instruction failures preserve their own entry state. Operand/call/
|
|
optional preparation remains charged and can fail; sequential stores are not a
|
|
transaction. No user callback or explicit suspension is inserted during updates.
|
|
BudgetExhausted and debugger pauses can stop between instructions and resume at
|
|
the current PC without completing or undoing the method. Host/debugger observation
|
|
is not atomic. No catch, poison flag or recovery API is introduced.
|
|
|
|
Unpublished candidates follow normal ownership and quotas. Capture failure returns
|
|
no partial Cursor and does not change the source. Removal and clear release
|
|
collection references to discarded nodes and payloads. Doubly linked cycles are
|
|
collected by normal tracing when unreachable; no immediate reclamation is promised.
|
|
Snapshots retain payloads, not the editable source topology; consumed prefixes
|
|
become collectible while the last current value stays retained until released.
|
|
|
|
## Conformance and distribution
|
|
|
|
Qualification executes real PBS through common IR/PBX and the production verifier
|
|
and VM, with ordinary and optimized producer paths. Cover the full API in empty,
|
|
single and multi-node states, reciprocal links and size, nearest-end lookup, all
|
|
bounds, int/long and single/named evaluation, complete groups and identity,
|
|
optional-element diagnostics, both Cursor orders/states and mutation independence.
|
|
|
|
Independently observe all original fields, link carriers, nodes and groups around
|
|
quota refusals, including node/result/operand preparation. Exercise ordinary GC
|
|
safepoints for removed nodes/values, clear, snapshots and prefix/final release.
|
|
Neutral stores/copy/terminal failure also require non-PBS producers and
|
|
malformed/dead instruction coverage. Regress shared Array/List/generic/contract/Cursor behavior and editor/LSP
|
|
projections. Ship the specification and executable example with installed SDK
|
|
knowledge, compile the actual packaged example outside the checkout and execute
|
|
its emitted PBX with the production provider.
|
|
|
|
See [generic Registry/PBX storage](../../compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md)
|
|
for the language-neutral instruction contract.
|