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.
128 lines
7.4 KiB
Markdown
128 lines
7.4 KiB
Markdown
# 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](generic-structs-and-free-functions.md),
|
|
[arrays and optional](typed-arrays-and-optional-execution.md) and the
|
|
[shared Cursor protocol](sdk-list-and-cursor.md#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<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_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<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.
|
|
|
|
## 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](../../general/specs/typed-registry-and-pbx-v0.md)
|
|
for the language-neutral instruction contract.
|