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.
This commit is contained in:
@@ -244,3 +244,37 @@ before mutation. A refused preparation still charges the attempted work. Neither
|
||||
operation is a safepoint. Consumers must prepare any potentially failing return
|
||||
carrier and all call operands before publication; a series of ordinary stores is
|
||||
not a substitute for whole-operation safety.
|
||||
|
||||
|
||||
## Atomic publication of multiple Struct instances
|
||||
|
||||
FIELDS_PUBLISH (`0xAB`) has one little-endian u32 schema TypeId immediate. The
|
||||
schema MUST be a Registry Struct whose ordered field types are all Struct types.
|
||||
Names are descriptive only. The schema is declarative metadata; no request object,
|
||||
new Registry category or preparation token is allocated or exposed.
|
||||
|
||||
For each schema entry, the operand stack supplies one nullable destination
|
||||
reference followed by every destination field's complete typed value group, in
|
||||
field declaration order. The stack effect is the sum, over entries, of one plus
|
||||
the destination instance's initialization-slot count; no results are produced.
|
||||
Null skips that destination, but every supplied field group is still validated.
|
||||
Non-null destinations require exact concrete Struct identity and a live reference
|
||||
of the current session/generation. Array, Trait, Fn and builtin schema entries are
|
||||
invalid, including in unreachable instructions. The full schema and exact stack
|
||||
height/groups are checked under normal Registry admission/work limits.
|
||||
|
||||
Validate all destinations and value groups before any shared write or operand
|
||||
consumption. The original operands remain roots throughout preparation. Then write
|
||||
all fields in schema order, without allocation, fallible validation, callbacks,
|
||||
GC or scheduler interleaving, and consume the entire input. Input values are
|
||||
captured before publication; repeated destinations use ordered last-write
|
||||
semantics. Complete multi-slot/native/reference groups retain identity and normal
|
||||
ownership. A failed attempt preserves every destination and the operand stack.
|
||||
|
||||
The operation allocates no publication scratch or guest object. Operand/frame and
|
||||
source value preparation remain normally charged and may fail before publication.
|
||||
Base cost is 6 cycles. After the stack-height check, precharge one cycle per schema
|
||||
entry and one per destination field execution slot for the complete declared
|
||||
attempt, including skipped destinations. Quotas are unchanged.
|
||||
This is a generic typed storage mechanism; collection algorithms and node topology
|
||||
remain source-owned, with no collection-specific VM instruction or syscall.
|
||||
|
||||
@@ -0,0 +1,127 @@
|
||||
# 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.
|
||||
@@ -152,11 +152,12 @@ faults. List itself rejects directly optional elements.
|
||||
|
||||
## Reuse, costs and conformance
|
||||
|
||||
The shared implementation is independent of List representation. Future Linked<T>
|
||||
and Set<T> producers use Cursor<T>; Map<K,V> uses Cursor<keyval<K,V>>. Set/Map gain
|
||||
The shared implementation is independent of List representation.
|
||||
[Linked](sdk-linked-and-cursor.md) uses Cursor<T> for forward and reverse captures.
|
||||
Future Set<T> producers use Cursor<T>; Map<K,V> uses Cursor<keyval<K,V>>. Set/Map gain
|
||||
no ordering guarantee between captures. A captured keyval association is read-only
|
||||
and does not follow later association replacement; referenced objects stay shared.
|
||||
Those collections and keyval are separate deliveries.
|
||||
Set/Map and keyval are separate deliveries.
|
||||
|
||||
For n logical List positions and k present occurrences, capture takes O(n) work
|
||||
and O(k) additional nodes; next follows one link in O(1). Each node costs allocation,
|
||||
|
||||
@@ -202,3 +202,12 @@ The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v0
|
||||
## VM-owned random core
|
||||
|
||||
See the [random contract](../specs/runtime/02e-vm-owned-random-core.md) for Random BuiltinId 0x0016, ObjectKind tag 9, intrinsics 0x4000–0x4003, atomic state mutation, bounded 4+8*N costs and rejection-limit trap 0x00000015. Random is managed by the VM heap and existing GC, without host entropy or PBX changes.
|
||||
|
||||
|
||||
## Atomic publication of multiple Struct instances
|
||||
|
||||
FIELDS_PUBLISH (0xAB) atomically publishes complete typed fields to multiple
|
||||
source-selected Struct destinations. Its schema is an ordinary Registry Struct;
|
||||
no new category, request object, syscall or safepoint is introduced. Exact nullable
|
||||
destination rules, stack effects, validation, costs and commit semantics are in the
|
||||
[canonical instruction contract](../specs/runtime/02-vm-instruction-set.md#atomic-publication-of-multiple-struct-instances).
|
||||
|
||||
@@ -198,3 +198,12 @@ STORAGE_PUBLISH (0xAA) provide generic logical validation, complete stored-group
|
||||
transfer and prepared atomic publication. Their encoding, typed operands, exact
|
||||
faults, overlap semantics, costs and preflight/commit guarantees are defined by
|
||||
the [canonical instruction contract](../specs/runtime/02-vm-instruction-set.md#logical-guards-and-atomic-storage-publication). No new Registry category, syscall, collection algorithm or safepoint is introduced.
|
||||
|
||||
|
||||
## Atomic publication of multiple Struct instances
|
||||
|
||||
FIELDS_PUBLISH (0xAB) atomically publishes complete typed fields to multiple
|
||||
source-selected Struct destinations. Its schema is an ordinary Registry Struct;
|
||||
no new category, request object, syscall or safepoint is introduced. Exact nullable
|
||||
destination rules, stack effects, validation, costs and commit semantics are in the
|
||||
[canonical instruction contract](../specs/runtime/02-vm-instruction-set.md#atomic-publication-of-multiple-struct-instances).
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
runtime.revision=d9b9eeb171d2861ec660d4cf5703b0795eac49a9
|
||||
runtime.revision=57992cf214e8a5f9de53a40dba9aaa7fab038c91
|
||||
INTRINSICS.csv.sha256=0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa
|
||||
BUILTIN_CONSTANTS.csv.sha256=e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039
|
||||
|
||||
Reference in New Issue
Block a user