Implement SDK list<T> and Cursor<T> with trusted compiler bindings and generic storage publication across IR and PBX. Pin the runtime provider and include specs, conformance coverage, installed examples, and DSC-0090 lessons.
267 lines
16 KiB
Markdown
267 lines
16 KiB
Markdown
# Studio PBX producer conformance
|
|
|
|
Owner: compiler/general. This harness uses the production runtime loader and VM;
|
|
it does not implement a Java approximation of runtime admission.
|
|
|
|
From the Studio root:
|
|
|
|
```sh
|
|
./gradlew :prometeu-compiler:prometeu-build-pipeline:test --tests '*LinkedRegistryTest' --tests '*PbxRegistryConformanceTest' --tests '*TypedCommonPipelineTest' --tests '*RuntimeCatalogPipelineTest'
|
|
./gradlew :prometeu-architecture-tests:test --tests '*PbsRuntimeAlignmentTest' --tests '*PbsStructuredValuesTest' --tests '*PbsClosuresTest' --tests '*PbsGenericContractsTest'
|
|
python3 tools/pbx-conformance/run.py --runtime ../runtime
|
|
```
|
|
|
|
The Java tests generate PBX in the build-pipeline module's
|
|
`build/registry-conformance`. `run.py` creates a temporary Cargo project, copies
|
|
the runtime lockfile and references its bytecode/hal/vm/system crates by path.
|
|
It never modifies the runtime checkout. Add `--online` for an uncached machine;
|
|
by default Cargo uses only cached dependencies. Java 25, Rust and the runtime
|
|
checkout's dependencies are required.
|
|
|
|
The output identifies runtime revision, OS/architecture and load configuration.
|
|
Positive fixtures distinguish loading from execution. The vec2 signature fixture
|
|
is deliberately load-only because its entry requires arguments. Native binding
|
|
uses SYSTEM for the positive case and NONE for missing-capability rejection;
|
|
all other cases use NONE. Resource tests explicitly lower default limits.
|
|
|
|
Negative fixtures mutate Java-produced bytes independently of the writer to
|
|
exercise malformed input that the writer correctly refuses to construct.
|
|
Initialization JSON comes from `prometeu_system::CrashReport`, and is checked
|
|
against the runtime's published headless schema. Saved JSON files remain under
|
|
the generated fixture directory. Studio process tests replay selected observed
|
|
payloads from `prometeu-app/src/test/resources/runtime` and assert unchanged MCP
|
|
projection, including null executed PC and nested verifier context.
|
|
|
|
## Known upstream schema defect
|
|
|
|
At runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, the LoadReason Rust enum
|
|
includes LifecycleRole, LifecycleSignature, DuplicateLifecycleRole and
|
|
NonFiniteValue, absent from the published JSON schema enum. This corpus
|
|
observes LifecycleRole and NonFiniteValue. The harness prints an explicit
|
|
`UPSTREAM SCHEMA GAP` for those two reasons and verifies that adding exactly
|
|
the missing enum value makes the original payload valid. It never alters the
|
|
payload or reports those cases as conforming to the unmodified schema. Any
|
|
other schema failure remains fatal. Track the runtime correction in AGD75;
|
|
remove the exception once the schema is corrected.
|
|
|
|
The original registry/catalog fixtures qualify common backend production. The
|
|
PBS fixtures below additionally qualify source lowering; this harness does not
|
|
claim installed-runtime deployment or memcard persistence.
|
|
|
|
## Runtime catalog consumer fixtures
|
|
|
|
The catalog corpus adds common-IR Random calls with an aliased handle, a discarded
|
|
first result, mixed next/nextf/range calls and a subsequent next. The VM checks the
|
|
independent seed-42 handoff vector and identical charged work before/after
|
|
optimization. Constants are compared slot-by-slot against runtime materialization,
|
|
including exact Float bits and both slots of `vec2.zero`. Pool deduplication may
|
|
share a value but cannot omit a group component.
|
|
|
|
A known zero-argument touch query loads and traps `TRAP_UNAVAILABLE` without a
|
|
hardware context. A removed endpoint ID is rejected even after an unreachable
|
|
HALT. `color.html_rgba` executes with a String value and rejects a proven null
|
|
at load time, matching the runtime verifier's stricter rule despite the
|
|
dispatcher's nullable String carrier. These are distinct outcomes. Run the separate provider-export check with
|
|
`python3 tools/runtime-catalog/verify.py --runtime ../runtime` to compare the
|
|
selected source revision, imported CSV bytes and exporter output as well.
|
|
|
|
|
|
## PBS source and input qualification
|
|
|
|
`PbsRuntimeAlignmentTest` compiles actual SDK declarations and source programs
|
|
through the PBS frontend, production common IR, typed Registry and PBX writer.
|
|
Its 114 fixtures execute on the selected runtime: all 48 Pad combinations with
|
|
both literal Button arguments and enum locals passed through a typed function,
|
|
six Touch queries, numeric boundaries/conversions/faults, builtin groups,
|
|
String, fixed multiple returns and named application with observable Y,X effects.
|
|
|
|
The controlled input platform asserts the exact button/coordinate reader and
|
|
one read per public query. Each query is also executed without a platform to
|
|
prove TRAP_UNAVAILABLE. The loaded PBS registries are checked for the defaults
|
|
of all eight existing value types, including null String, positive Float zero
|
|
and complete vec2/pixel groups. No source constructors or new collection API
|
|
are introduced to test storage defaults.
|
|
|
|
The harness requires the complete fixture count. It must not pass by skipping
|
|
missing PBS fixtures. Integer arithmetic wrapping is distinct from checked
|
|
Int64-to-Int32 narrowing and Float numeric-range faults. The full installed
|
|
knowledge gate remains separate and mandatory for SDK resource/producer
|
|
integration.
|
|
|
|
## PBS typed arrays, optional and Struct/contract execution
|
|
|
|
`PbsStructuredValuesTest` generates 27 mandatory `pbs-structured-*` fixtures.
|
|
They cover contextual arrays, nested levels, vacancy/zero, clear/length, aliasing,
|
|
int/long bounds, single evaluation, lazy optional fallback, inferred/explicit
|
|
optional tuples, native vec2 groups, fields and constructors, overloads and Self,
|
|
contract elements/dispatch, imported services/structs/contracts, global file-init,
|
|
and the installed example. The runtime harness names every required fixture;
|
|
a missing file is an error.
|
|
|
|
Eighteen additional runs lower GuestBytes or HandleSlots to 0, 1 or 2. They assert
|
|
resource faults, bounded accounting, no object publication at zero quota, and
|
|
release of session ownership. The integer-storage fixture succeeds with one
|
|
handle total, proving that its three integers do not allocate individual boxes.
|
|
String session accounting is checked after each structured execution.
|
|
|
|
The GC fixture compiles all allocations, roots and post-collection reads from PBS.
|
|
A test-only driver hook replaces one isolated marker assignment with FRAME_SYNC
|
|
and NOPs without changing code offsets; it does not add PBS sync syntax. At the
|
|
real runtime safepoint, at least 1,100 discarded objects are reclaimed while
|
|
nested references, tuples and strings remain readable. `resource-diagnostics`
|
|
is enabled solely for observation. Default production ceilings and GC threshold
|
|
are unchanged outside the explicitly lowered quota runs. This is semantic and
|
|
resource conformance, not a performance benchmark or installed game qualification.
|
|
|
|
## PBS first-class functions and closure lifetime
|
|
|
|
`PbsClosuresTest` adds nine mandatory source/load/execute fixtures: named and
|
|
anonymous functions, snapshots, shared objects/arrays, nested function captures,
|
|
complete tuple groups and contract receivers, independent environments, Fn fields
|
|
and overload selection, imported functions, and the installed example. Each
|
|
returns 42. Six additional GuestBytes/HandleSlots runs at limits 0, 1 and 2 check
|
|
closure allocation faults and session ownership, bringing structured quota runs
|
|
to 24.
|
|
|
|
The tenth fixture, `closure-frame-lifecycle.pbx`, uses the existing production
|
|
lifecycle assembler without bytecode patching. Its first frame stores a closure
|
|
capturing an object; the next frame invokes it twice (41, then 42) and drops the
|
|
reference. Each of three frames also discards 1,200 closures. The harness asserts
|
|
threshold collections, retained closure/object reachability after frame one,
|
|
and reclamation after release. The remaining root is the global array.
|
|
PBS publishes FRAME_ROOT and the existing guarded wrapper returns normally.
|
|
No sync syntax, new frame integration, suspension or coroutine is introduced.
|
|
|
|
## PBS service constants and runtime math
|
|
|
|
`PbsRuntimeMathTest` produces 261 independent numeric cases in both ordinary and
|
|
optimized bytecode (522 mandatory executions per runtime profile), covering all
|
|
26 math/mathf signatures. The checked-in corpus preserves 240 provider scalar
|
|
fixture rows and exact contract examples (duplicates removed); provenance is in
|
|
`prometeu-architecture-tests/src/test/resources/math/provenance.txt`.
|
|
|
|
The harness verifies exact bits/faults, selected intrinsic identity and one
|
|
retained call per case. Single-step charging is compared with the provider's
|
|
opcode costs and independent fixture call cost; full-budget charging must equal
|
|
their sum, and optimization must preserve total cycles. Additional cases exercise
|
|
pi/tau, literal sin, ordinary int/long service constants, constant dependencies,
|
|
and real module imports with service aliases. The installed example also imports
|
|
both SDK services, so installedKnowledgeTest covers their packaged resources.
|
|
|
|
```sh
|
|
./gradlew :prometeu-architecture-tests:test --tests '*PbsRuntimeMathTest'
|
|
python3 tools/pbx-conformance/run.py --runtime ../runtime --math-only
|
|
python3 tools/pbx-conformance/run.py --runtime ../runtime --math-only --release
|
|
```
|
|
|
|
Omit `--math-only` for the full existing corpus. `--release` selects the optimized
|
|
Rust runtime harness; it is independent of the PBS optimizer variants included in
|
|
every run. Optional `CARGO_TARGET_DIR` can retain build artifacts outside the
|
|
runtime checkout. Each invocation prints runtime revision, platform, profile,
|
|
features, lockfile and provider catalog/oracle hashes. Local evidence qualifies
|
|
macOS/arm64 only; macOS/x86_64 and Linux/x86_64 remain pending.
|
|
|
|
## PBS explicit Random integration
|
|
|
|
`PbsRuntimeRandomTest` adds 226 source fixtures plus one real SDK import/alias
|
|
fixture. The 48 unchanged provider oracle rows produce 192 exact integer/Float
|
|
cases (six seeds, eight draws, two output kinds and two optimizer variants).
|
|
The remaining paired fixtures cover mixed/discarded draws, independent objects,
|
|
locals/globals/fields/arrays/parameters/results/captures, named/positional effects,
|
|
unit/extreme ranges, invalid limits, null and typed-null Dynamic storage, real
|
|
rejection followed by acceptance, and collection roots.
|
|
|
|
Each paired fixture runs with single-instruction budgets and twice with full
|
|
budgets, comparing exact result bits or faults, intrinsic charges and total
|
|
cycles. Explicit source `as long` conversions are charged separately. The GC
|
|
fixture reuses the existing test-only FRAME_SYNC marker hook; all allocations,
|
|
roots and post-collection draws are compiled PBS. At least 1,100 discarded Random
|
|
objects are reclaimed while array, field and closure references preserve the
|
|
same generator. The import fixture uses the production workspace builder and
|
|
lifecycle assembler. The focused driver calls file initializers before Probe.main;
|
|
it does not claim a new lifecycle API.
|
|
|
|
```sh
|
|
./gradlew :prometeu-architecture-tests:test --tests '*PbsRuntimeRandomTest'
|
|
python3 tools/pbx-conformance/run.py --runtime ../runtime --random-only
|
|
python3 tools/pbx-conformance/run.py --runtime ../runtime --random-only --release
|
|
```
|
|
|
|
The driver rejects an oracle copy that differs from the selected provider and
|
|
prints source/oracle/catalog/lockfile fingerprints and toolchain/profile details.
|
|
A complete run includes the Random corpus and keeps it separate from the older
|
|
114 input/type fixtures. Rare synthetic 64-attempt acceptance/cap/rollback,
|
|
malformed carriers and native provenance are provider tests, not PBS-produced
|
|
claims. Qualify those separately with the provider's `random_contract` suite and
|
|
`cargo test -p prometeu-vm --lib random` in debug/release. No alternate RNG or
|
|
public injection hook is used. Installed knowledge validation remains a separate
|
|
gate for packaged SDK/spec/example resources.
|
|
|
|
## PBS generic contracts
|
|
|
|
`PbsGenericContractsTest` generates fourteen mandatory source fixtures:
|
|
`identity`, `manual`, `multiple`, `tuple`, `optional`, `function`, `contract`,
|
|
`native`, `recursive`, `phantom`, `receiver`, `gc`, `installed` and `imports`.
|
|
The corpus uses ordinary concrete Trait descriptors on the existing runtime.
|
|
It checks several applications on one owner, ordered substitution, composed
|
|
multi-slot values, finite recursion, canonical aliases/reexports and distinct
|
|
same-named argument declarations. The imported program uses the production
|
|
workspace builder and lifecycle assembler.
|
|
|
|
The generic and handwritten concrete identity fixtures both execute with one
|
|
heap handle, establishing that contract adaptation needs no generic wrapper.
|
|
Typed absence and implementation index zero are valid. A mismatched Trait call
|
|
must be rejected by the verifier or trap with the runtime type check. The GC
|
|
fixture retains a contract receiver through a closure while at least 1,100
|
|
discarded objects are reclaimed. Reduced GuestBytes, HandleSlots and loader
|
|
implementation limits verify refusal and ownership release. Descriptor counts
|
|
and PBX byte sizes are printed as evidence, without a performance threshold.
|
|
|
|
```sh
|
|
./gradlew :prometeu-architecture-tests:test --tests '*PbsGenericContractsTest'
|
|
python3 tools/pbx-conformance/run.py --runtime ../runtime --generic-contracts-only
|
|
```
|
|
|
|
The full harness also requires these fixtures. The driver uses an external
|
|
runtime checkout without editing its sources or changing PBX, ISA or quotas.
|
|
|
|
|
|
## SDK List, shared Cursor and generic storage
|
|
|
|
Generate the source corpus and the language-neutral storage fixtures, then run:
|
|
|
|
```sh
|
|
./gradlew :prometeu-compiler:prometeu-build-pipeline:test :prometeu-architecture-tests:test :prometeu-app:installedKnowledgeTest
|
|
python3 tools/pbx-conformance/run.py --runtime ../runtime --list-cursor-only
|
|
```
|
|
|
|
The full harness also requires this corpus. Missing ordinary, optimized, quota,
|
|
GC, import/reexport or installed-JAR fixtures fail explicitly. Two synthetic
|
|
common-IR programs execute INDEX_GUARD, ARRAY_CHECK_LENGTH, ARRAY_COPY and
|
|
STORAGE_PUBLISH through ordinary and optimized producer paths without PBS types.
|
|
List source cases cover every mutator, exact growth, logical versus physical
|
|
bounds, int/long arguments (including named application), holes, aliases,
|
|
vec2/pixel/tuple/Fn/contract/reference groups and every state of a Cursor that remains on its last node.
|
|
An independent producer distinguishes some(none) from an empty Cursor.
|
|
|
|
Four source-generated mutation fixtures expose explicit before/completed markers.
|
|
The harness lowers GuestBytes, HandleSlots, AuxiliaryBytes and TemporaryBytes from
|
|
measured setup/success peaks. After each refused attempt it independently observes
|
|
all List fields and complete backing groups, including reference generations and
|
|
presence tags. Coverage gates require refusals in no-growth publication scratch,
|
|
removeAt optional return allocation, candidate allocation, node construction and
|
|
operand/frame preparation. Read-only resource diagnostics use non-owning storage
|
|
observations outside guest execution; no observation introduces a GC root or write.
|
|
|
|
The controlled safepoint fixture expects 1,200 nodes/objects initially, one after
|
|
traversal, one after repeated next on the final node, and zero after releasing the
|
|
Cursor. It also requires no live source/snapshot array. Shared payload fields stay
|
|
observable; prefix roots and the final payload obey normal reachability and GC.
|
|
The installed fixture is compiled by the isolated installDist JVM using the actual
|
|
packaged spec/example/SDK, then loaded and executed by this production VM harness.
|
|
|
|
Evidence prints compiler/provider source hashes, exact provider revision and dirty
|
|
state, toolchain, platform/profile, capabilities, every default VM ceiling and each
|
|
explicitly lowered refusal limit. Development runs against a dirty provider are
|
|
identified as such; final catalog verification requires its clean selected commit.
|