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

8.6 KiB

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, arrays and optional and the shared Cursor protocol.

Authority and scope

This chapter is the canonical owner of the detailed contract described below. The domain reading guide 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 Capture first to last
reverseCursor() Cursor 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 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 for the language-neutral instruction contract.