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
+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.