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,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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user