Launch the JavaFX 2 project shell on Java 25 with an interactive viewport, managed Play lifecycle and project mutation guards. Preserve headless/MCP and save compatibility, and qualify exact runtime executable bundles. Separate unit JaCoCo gates from opt-in integration suites and use the internal Pong fixture for the headless visual pilot. Move maintenance and native conformance tools into tooling; retain the VS Code extension and update current navigation links. Validation: tooling make verify passed, including 1064 Studio unit tests, JaCoCo thresholds and 22 headless integration tests.
211 lines
12 KiB
Markdown
211 lines
12 KiB
Markdown
---
|
|
id: LSN-0092
|
|
ticket: runtime-storage-isa-consumer-migration
|
|
title: Sequential collection mutations need explicit failure boundaries
|
|
created: 2026-10-24
|
|
tags: [compiler, compiler-pbs, runtime-integration, storage, collections]
|
|
---
|
|
|
|
## Original problem and ownership
|
|
|
|
Owner: `compiler`, with propagation to `compiler/pbs` and `vm-arch`.
|
|
|
|
The delivered runtime removed logical guard and compound publication opcodes
|
|
0xA7/0xA8/0xAA/0xAB. Studio's List/Linked SDK still depended on them and promised
|
|
that every refused method preserved the complete collection. Pinning the new
|
|
provider alone would therefore invalidate emitted PBX and leave the source
|
|
contract unsupported. The provider also moved intrinsic metadata to schema 2.
|
|
|
|
AGD-0098 converged into accepted DEC-0077 and implementation PLN-0155. The user
|
|
explicitly accepted the recommendations inspired by OpenJDK 25 and .NET 10, then
|
|
authorized planning and implementation. These identifiers record workflow
|
|
provenance; the completed control artifacts are removed by CLI housekeeping.
|
|
The durable normative surfaces are the specifications linked below.
|
|
|
|
The entire migration belongs to Studio. Runtime revision
|
|
`dcf6561ea73446e0a3e1cf1c73eda20923b38df0` is consumed unchanged. No runtime code,
|
|
manifest, lockfile, instruction, quota or commit is a write target. External Cargo
|
|
projects/targets qualify the production loader/VM without editing that checkout.
|
|
|
|
## Consolidated decision
|
|
|
|
Keep List's private array/logical size and Linked's private doubly linked nodes,
|
|
collection identity, capacity policy and shared snapshot Cursor. Prepare logical
|
|
checks, next sizes, values, candidates and return carriers before visible mutation;
|
|
then use ordinary typed stores and retained ARRAY_COPY. Do not reconstruct a
|
|
whole collection on every update to simulate the retired publication mechanism.
|
|
|
|
The accepted contract distinguishes three outcomes:
|
|
|
|
| Outcome | Guarantee |
|
|
| --- | --- |
|
|
| Rejection/preparation failure before the first visible mutation | The prior collection remains unchanged; argument effects and provisional allocations are not rolled back. |
|
|
| Successful method return | All size/storage/topology, group, identity, cleanup and snapshot invariants hold. |
|
|
| Internal/resource fault after visible mutation starts | Earlier writes can remain and invariants can be incomplete. There is no whole-method rollback, safe-reuse, retry or automatic-recovery guarantee. |
|
|
|
|
The last row deliberately replaces the old stronger promise. It is not a basic
|
|
consistency guarantee. A single instruction still preserves its own entry state
|
|
when it fails; that does not undo previous successful instructions.
|
|
|
|
BudgetExhausted and debugger pauses are instruction-boundary suspensions, not
|
|
faults. Normal resumption continues the method at its current PC. Source methods
|
|
are not atomic observation regions for the host/debugger. No user callback or
|
|
explicit suspension is inserted into the sequence that completes mutation.
|
|
|
|
Java and C# informed the prepare-then-update structure, not a universal error
|
|
recovery claim. Their ordinary iterators are also not a reason to replace an
|
|
already accepted PBS snapshot protocol with fail-fast behavior.
|
|
|
|
## Final algorithms and costs
|
|
|
|
### List prepares packed values before shifting
|
|
|
|
For insertion with growth, build a private backing and copy the prefix and suffix
|
|
directly into their final positions. For `[A,B,C]` with insertion of X at index 1,
|
|
the candidate becomes `[A,X,B,C,...]` before storage/length are installed. Existing
|
|
stored groups move intact, including holes, tags and identities.
|
|
|
|
Without growth, PBS Array assignment accepts T, whereas clearing uses
|
|
`array.clear(index)`. Packing a new generic value can allocate. The SDK therefore
|
|
prepares that value in a private one-slot array, shifts the suffix with ARRAY_COPY,
|
|
copies the complete prepared slot, then updates logical length. This creates a
|
|
charged temporary allocation and additional copy scratch; it does not clone the
|
|
whole list or promise allocation-free insertion. A later copy/operand failure
|
|
retains earlier writes under the accepted phase contract.
|
|
|
|
Removal prepares the optional result, shifts the suffix, clears the old tail and
|
|
updates length. Clear and in-capacity resize clear their intervals in index order
|
|
before setting length. Growing resize prepares/copies its private candidate;
|
|
reserve/trim prepare candidates and replace storage without changing size.
|
|
Indexed replacement and clearAt affect one checked position.
|
|
|
|
The policy remains capacity 16 by default, exact explicit capacity including zero,
|
|
approximately 1.5x automatic growth with checked/clamped valid requirements,
|
|
nonshrinking exact reserve and trim to size. Successful shrink/removal/clear never
|
|
resurrect discarded values on regrowth. Old/candidate/temporary arrays coexist
|
|
under ordinary quotas and tracing; reclamation is not immediate.
|
|
|
|
### Linked prepares nodes/results, then updates links
|
|
|
|
Insertion locates neighbors, checks the next signed-long size and prepares the new
|
|
node before updating previous.next or head, next.previous or tail, then length.
|
|
Removal prepares the optional result and neighbor values before updating those
|
|
two sides and length. Replacement changes value only; clear changes head, tail,
|
|
then length. Linked does not inherit Array's u32 length bound.
|
|
|
|
Some later source operand/carrier preparation can still refuse resources. The
|
|
implementation and tests do not rename sequential link stores as atomic
|
|
publication or assume that prepared source values make the remaining code
|
|
infallible. A fault can occur after a successful earlier write.
|
|
|
|
### Cursor remains an independent snapshot
|
|
|
|
Capture constructs private immutable singly linked nodes and exposes only a
|
|
complete result. Capture failure leaves the source unchanged. Forward and reverse
|
|
Linked captures preserve their respective orders. Captured references preserve
|
|
identity and observe later mutations of the referenced objects, while collection
|
|
replacement/insertion/removal does not rewrite the captured sequence.
|
|
|
|
A nonempty Cursor starts at the first value. hasNext tests for a successor; next
|
|
without one retains the last value; only an empty-born Cursor reports current
|
|
absent. Prefixes become collectible as traversal advances, and the final current
|
|
node/value remains retained until the Cursor releases it. No live/fail-fast
|
|
iterator, public node or deep freeze was added.
|
|
|
|
## Logical refusals and the neutral terminal path
|
|
|
|
Bounds and length checks execute as PBS comparisons/branches. Reads/writes require
|
|
`0 <= index < size`; insertion allows `index == size`. Negative or above-u32
|
|
Array length/capacity requests and invalid logical indices terminate through the
|
|
trusted private SDK fail binding, lowered to existing TRAP 0x05.
|
|
|
|
Common IR, IRVM, validation, optimization, emission and source spans now carry
|
|
that zero-operand terminal operation. It raises TRAP_EXPLICIT rather than
|
|
pretending to preserve retired guard diagnostics/costs. Physical Array operations
|
|
that actually execute retain their own faults and resource context. None remains
|
|
legitimate absence, not a replacement for a fault.
|
|
|
|
The four retired Registry kinds, publication schema builder and dedicated extra
|
|
publication immediate fields were removed. Producer preload rejects the retired
|
|
encodings even in dead code. Decoding actual instruction positions avoids false
|
|
positives when an Int32 immediate contains the same numeric bytes.
|
|
|
|
## Copy attempt boundaries and schema 2
|
|
|
|
ARRAY_COPY remains u16 LE 0xA9 plus Array TypeId u32 LE, consuming source,
|
|
sourceStart, target, targetStart, count. Exact receivers and Int64 offsets/count,
|
|
strict physical ranges, overlap snapshots, complete groups/native owners and
|
|
scratch cleanup remain provider responsibilities.
|
|
|
|
For valid selectable N and Registry width W, attempted cost is `4 + 2*N*W`, charged
|
|
before receiver/range/group/scratch refusal. N=10/W=1 costs 24 on success and the
|
|
specified refusals; W=2 costs 44. Empty copies validate and cost 4. Negative or
|
|
above-u32 counts select base 4 and ordinary fault precedence. Zero budget executes
|
|
nothing; positive budget admits the full attempt with overshoot, and a failed
|
|
attempt is Trap with zero successful target steps. Checked arithmetic overflow
|
|
using synthetic internal widths is separately qualified provider evidence, not a
|
|
claim that admitted consumer descriptors can reach those widths.
|
|
|
|
All 108 intrinsic definitions retain all 25 schema-2 fields. A dedicated profile
|
|
value validates schema, ordered nullable bits, invocation/scratch/context tuples
|
|
and fixed/rejection/UTF-8 cost parameters. Deterministic does not mean pure.
|
|
Known null String admission follows each entry: hash.string admits it and returns
|
|
the provider's zero hash vector, while older non-nullable String entries reject
|
|
it at load. Importing hash metadata does not deliver PBS hashing facades or Set/Map.
|
|
|
|
Catalogs, SHA/digests, compiler and SDK packaged resources now agree with the
|
|
selected clean provider. Runtime architecture mirrors are copied byte-for-byte;
|
|
ordinary compilation/parity tests continue using only local versioned resources.
|
|
|
|
## Qualification and reproducible evidence
|
|
|
|
The [qualification record](runtime-conformance-evidence.json) identifies source
|
|
fingerprints, provider revision/clean state, toolchains, fixture digests, commands,
|
|
log hashes, test totals and observed execution/refusal counts. Full raw logs are
|
|
compressed losslessly as `.log.gz` files beside it; the record includes both
|
|
compressed-file and original uncompressed SHA-256 values. The evidence separates the normal test suite, installed-JAR examples,
|
|
explicit exporter parity, debug/release conformance and focused unchanged-provider
|
|
copy defenses. Historical List/Linked evidence remains tied to its original pins.
|
|
|
|
The consumer harness measures refusal limits from setup/success peaks, then
|
|
single-steps operations and compares every original-object state with the same
|
|
successful instruction prefix. It asserts complete prior-state preservation only
|
|
before visible mutation, and records completed writes afterward. Source snapshots
|
|
are non-owning observations; they neither add guest roots nor write the collection.
|
|
This catches both accidental early mutation and accidental claims of rollback.
|
|
|
|
The corpus includes normal/optimized source methods, 28 phase-marker variants,
|
|
neutral store/copy/terminal fixtures, 22 copy cases across paired producer paths, dead retired opcodes
|
|
versus immediate bytes, zero-budget/overshoot/fault precedence, quotas, GC,
|
|
import/reexport and actual packaged examples compiled outside the checkout.
|
|
Existing unrelated headless-schema gaps are reported explicitly by the harness;
|
|
they are not silently relabeled as schema conformance or fixed in runtime here.
|
|
|
|
## Pitfalls and maintenance guidance
|
|
|
|
- Preparing a value is not proof that every later load, carrier, call or store
|
|
sequence cannot fail. Publish the actual failure boundary.
|
|
- Do not assert unchanged collections after every refusal once the accepted
|
|
contract permits prior writes. Compare the real instruction prefix instead.
|
|
- Do not unpack/rebox all shifted values or discard empty-copy validation/cycles.
|
|
- Do not count frame locals as missing copy operands or confuse a pause with a fault.
|
|
- Do not infer nullable admission, purity or zero scratch from names/determinism.
|
|
- Updating a CSV/pin alone is not a consumer integration. Code, installed
|
|
resources, source execution and provenance must move together.
|
|
- Set/Map still need their own contracts and algorithms. The retired publication
|
|
instructions are not available to their future implementations, and this work
|
|
does not accept their pending product choices.
|
|
- Changing the runtime to rescue an incomplete producer is outside this delivery.
|
|
|
|
## Durable references
|
|
|
|
- [Common Registry/PBX](../../../docs/specs/compiler/25.%20Typed%20Registry%20and%20PBX%20v0%20Specification.md).
|
|
- [Runtime catalog consumer](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md).
|
|
- [List/Cursor](../../../docs/specs/compiler-languages/pbs/21.%20SDK%20List%20and%20Cursor%20Specification.md),
|
|
[Linked](../../../docs/specs/compiler-languages/pbs/22.%20SDK%20Linked%20and%20Cursor%20Specification.md) and
|
|
[Array/optional](../../../docs/specs/compiler-languages/pbs/14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md).
|
|
- [Conformance commands and coverage](../../../../tooling/scripts/pbx-conformance/README.md).
|
|
- [Selected provider pin](../../../docs/vm-arch/runtime-catalog.properties).
|
|
- Original decisions/planning: accepted DEC-0077 and completed PLN-0155 in DSC-0096,
|
|
consolidated here before their required housekeeping removal.
|