refactor(compiler)!: migrate SDK to minimal storage ISA
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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user