refactor(compiler)!: migrate SDK to minimal storage ISA
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good

Replace retired guards and publication opcodes with SDK checks, neutral TRAP and sequential List/Linked mutations with explicit failure phases. Preserve snapshot cursors and import schema 2 metadata with the delivered provider pin.

Include common/source/installed conformance, debug and release evidence, synchronized specs and the consolidated lesson. Runtime checkout remains unchanged.
This commit is contained in:
2026-10-24 01:35:42 +01:00
parent 77aada6259
commit 632ba6d0d6
51 changed files with 2688 additions and 711 deletions
@@ -1,7 +1,7 @@
# 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
Typed 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).
@@ -44,8 +44,8 @@ successor nodes beyond the ends. Nodes and private helpers are not a public API.
| `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
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.
@@ -56,8 +56,8 @@ 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
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.
@@ -83,21 +83,29 @@ 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
## Mutation phases 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.
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.
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.
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
@@ -117,11 +125,11 @@ optional-element diagnostics, both Cursor orders/states and mutation independenc
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
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 publication](../../general/specs/typed-registry-and-pbx-v0.md)
See [generic Registry/PBX storage](../../general/specs/typed-registry-and-pbx-v0.md)
for the language-neutral instruction contract.
+42 -19
View File
@@ -1,8 +1,8 @@
# SDK List and snapshot Cursor
Owner: `compiler/pbs`. List and Cursor algorithms belong to the executable PBS
SDK. Logical guards, complete stored-group transfers and atomic publication are
language-neutral compiler/runtime mechanisms. This contract builds on
SDK. Typed storage, complete stored-group transfers and terminal failure are
language-neutral compiler/runtime mechanisms. Logical checks are SDK algorithms. This contract builds on
[arrays and optional](typed-arrays-and-optional-execution.md),
[generic structs](generic-structs-and-free-functions.md) and
[generic contracts](generic-contracts.md).
@@ -56,9 +56,12 @@ Receiver and arguments are evaluated once in source order. Indices, lengths and
capacities accept int and long with localized lossless promotion; this does not
add general numeric conversion. No long value may be truncated.
Invalid logical indices raise TRAP_OOB, including indices inside physical capacity.
Negative lengths, structural overflow and quota refusals preserve the applicable
Array/provider fault classification. Failures are never translated into none.
SDK checks reject invalid logical indices, negative lengths/capacities and requests
above Array's u32 structural maximum before mutation with TRAP_EXPLICIT and a
source location. This includes indices inside physical capacity. Physical Array
instructions that actually execute retain their own fault/resource classification.
Failures are never translated into none. Growth arithmetic must not overflow or
truncate; clamping applies only to a valid requested length.
## Capacity policy
@@ -75,20 +78,40 @@ never shrinks and preserves size. Trim uses exactly size. Old and candidate arra
may coexist; neither discarded references nor replaced storage promise immediate
GC or immediate quota recovery.
## Complete mutation attempts
## Mutation preparation, visible writes and faults
Private storage transfer preserves whole existing groups, presence tags and
reference identities. Shifting must not unpack each public Array optional and
repack/rebox every payload. Prepare potentially failing validation, packing,
allocations, return carriers, scratch and publication operands before modifying
observable storage. Then publish the complete selected slot/range and field
changes without a fallible allocation, callback, scheduler or GC boundary.
Transfer whole stored groups, presence tags and reference identities; do not
unpack and rebox all existing elements during shifting. Prepare validation,
next size, inserted values, candidates and optional return carriers before the
first visible write. This preparation does not prove all later instructions
infallible. Values/receiver/argument effects already evaluated are not rolled back.
Any refused attempt leaves size, backing reference, capacity, slots and roots
unchanged. This includes insert/remove without growth and preparation of
removeAt's optional result. Individually atomic Array instructions do not by
themselves establish this guarantee. Previously evaluated argument effects are
not rolled back. Unpublished candidates obey normal ownership and budgets.
With growth, construct a private candidate and copy prefix/suffix directly into
their final positions; store the new value privately, then install storage and
length in sequence. Without growth, prepare the inserted stored group in a private
one-slot array, shift with overlap-safe ARRAY_COPY, copy that complete prepared
slot, then update length. Both copies retain scratch, validation and charging,
including empty copies. This one-slot preparation is charged allocation, not a
promise of allocation-free insertion or whole-array reconstruction.
Removal prepares its optional result, shifts the suffix, clears the old tail and
updates length. Clear and in-capacity resize clear the selected interval in index
order before assigning length. Growing resize prepares/copies a private candidate
before installing storage and length. Reserve/trim prepare/copy candidates and
replace storage only. Indexed replacement/clearAt alter a single checked position.
| Outcome | Guarantee |
| --- | --- |
| Logical rejection or preparation refusal before the first visible write | Preserve previous size, backing, capacity, slots and collection roots. Unpublished candidates obey normal ownership/quotas; immediate quota recovery is not promised. |
| Successful return | All collection invariants, cleanup, groups, identity and snapshot contracts hold. |
| Internal/resource fault after the first visible write | Propagate the fault; earlier writes can remain and collection invariants can be incomplete. No rollback, safe reuse, retry or automatic recovery is promised. |
The last row explicitly replaces the former whole-mutation refusal guarantee.
Individual instruction failure still preserves its own entry operands/storage.
No catch, poison flag or recovery API is introduced. The SDK inserts no user
callbacks or explicit suspension during mutation updates. BudgetExhausted and
pauses are resumable instruction boundaries, not faults or rollback. The host or
debugger may observe intermediate state; a method is not an atomic region.
## Cursor protocol
@@ -168,9 +191,9 @@ through allocations and calls; provider quotas remain unchanged.
Conformance must execute real PBS through common IR and PBX in the production VM.
It covers every operation, constructor/type rule, logical bounds, exact growth,
holes and full groups, aliases, the entire Cursor table, snapshot independence,
shared object mutation, non-List producers, full-operation refusals with and without
shared object mutation, non-List producers, refusals before and after visible mutation with and without
growth, prefix reclamation, last-node retention, editor projections and installed
SDK/spec/example distribution. Generic publication also requires non-PBS tests.
SDK/spec/example distribution. Neutral storage/copy/terminal paths also require non-PBS tests.
Value search/removal, sorting, bulk APIs, new equality, public nodes, deep freezing,
general effect/transaction syntax and Linked/Set/Map implementations are out of scope.
@@ -60,7 +60,7 @@ Presence must be checked using the Dynamic tag before extraction. `DYN_CAN_UNPAC
PBS optional values use private nullable Struct carriers: null denotes none and a private instance contains the full payload for some. Named tuples remain flattened at callable boundaries and use private storage carriers where a single Registry type is required. These private carriers are inaccessible to source programs. They preserve nested optional distinctions, tuple value behavior and reference aliases within payloads.
Lowering must keep complete receiver/index/value groups rooted across allocations, calls and collection operations. GC, native ownership, quota accounting, costs and atomic refusals remain runtime contracts. No failure may publish partially initialized handles or be suppressed as none; no quota may be relaxed to satisfy conformance.
Lowering must keep complete receiver/index/value groups rooted across allocations, calls and collection operations. GC, native ownership, quota accounting, costs and per-instruction refusal preservation remain runtime contracts. No failure may publish partially initialized handles or be suppressed as none; no quota may be relaxed to satisfy conformance.
## Struct and contract integration
@@ -97,3 +97,9 @@ See [Runtime Random integration](runtime-random-integration.md) for opaque gener
these contextual construction positions and storage rules. A generic T field can
hold an optional value, but substituting an optional value type into array<T>
remains invalid. Array's private packing does not become a generic argument ABI.
SDK collections add logical checks before physical Array operations and terminate
logical refusals with TRAP_EXPLICIT. Their multi-instruction methods use the
[List mutation-phase contract](sdk-list-and-cursor.md#mutation-preparation-visible-writes-and-faults)
and [Linked contract](sdk-linked-and-cursor.md#mutation-phases-and-lifetime);
per-instruction storage guarantees do not imply whole-method rollback.