Files
prometeu-studio/docs/compiler/pbs/specs/sdk-linked-and-cursor.md
T
bquarkz 77aada6259 feat(pbs): add linked collections and bidirectional snapshots
Implement SDK linked<T> with forward and reverse Cursor snapshots, trusted compiler integration, and neutral FIELDS_PUBLISH producer support. Pin the tested runtime revision and include specs, editor and installed knowledge coverage, conformance fixtures, and DSC-0091 lessons and evidence.
2026-10-23 10:28:44 +01:00

7.4 KiB

SDK Linked and bidirectional snapshot capture

Owner: compiler/pbs. Linked algorithms belong to executable PBS SDK source. Multi-object publication, 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.

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_OOB even when empty. Insertion accepts size, including zero in an empty collection. Other insertion indices raise TRAP_OOB. 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 the generic logical guard; 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.

Complete mutation attempts and lifetime

Before publication, prepare bounds, next size, candidate nodes, optional results, all field values and call/operand resources. Private generic FIELDS_PUBLISH publishes complete field groups of source-selected objects after validating all receivers and groups. Null destinations represent missing neighbors. Algorithms select the new head/tail/size and neighbor fields in SDK source; the VM has no Linked opcode or syscall.

No fallible allocation, callback, scheduler or GC boundary may expose partial publication. A refused mutation preserves all previous head/tail/size values, elements and neighbor links. This includes optional return preparation for removals and mutations without new nodes. Individually atomic stores do not prove whole-operation atomicity. Previously evaluated argument effects are ordinary source effects and are not rolled back.

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. Generic publication also requires non-PBS producers and malformed/dead operand 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 publication for the language-neutral instruction contract.