Files
prometeu-studio/docs/specs/compiler-languages/pbs/22. SDK Linked and Cursor Specification.md
T

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.