From dd3594240e23793338603947a1983ffa74f5bd19 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 7 Oct 2026 21:36:16 +0100 Subject: [PATCH] perf(registry): record bounded layout load and GC evidence for PLN-0176 step 35 --- .../prometeu-bytecode/src/load_limits.rs | 36 ++++- .../prometeu-vm/src/program_image/tests.rs | 28 ++++ .../prometeu-vm/src/typed_storage/tests.rs | 153 ++++++++++++++++++ docs/vm-arch/ARCHITECTURE.md | 4 +- docs/vm-arch/registry-layout-evidence.md | 97 +++++++++++ 5 files changed, 316 insertions(+), 2 deletions(-) create mode 100644 docs/vm-arch/registry-layout-evidence.md diff --git a/crates/console/prometeu-bytecode/src/load_limits.rs b/crates/console/prometeu-bytecode/src/load_limits.rs index 77bb0c5..cb33693 100644 --- a/crates/console/prometeu-bytecode/src/load_limits.rs +++ b/crates/console/prometeu-bytecode/src/load_limits.rs @@ -270,10 +270,11 @@ impl LoadLimits { pub struct LoadBudget { limits: LoadLimits, used: [u64; RESOURCE_COUNT], + peak: [u64; RESOURCE_COUNT], } impl LoadBudget { pub fn new(limits: LoadLimits) -> Self { - Self { limits, used: [0; RESOURCE_COUNT] } + Self { limits, used: [0; RESOURCE_COUNT], peak: [0; RESOURCE_COUNT] } } pub fn limit(&self, r: LoadResource) -> u64 { self.limits.ceiling(r).min(LoadLimits::default().ceiling(r)) @@ -293,6 +294,12 @@ impl LoadBudget { pub fn used(&self, r: LoadResource) -> u64 { self.used[r as usize] } + /// Highest admitted reservation total during this budget's lifetime. + /// Refunds and failed load transactions retain this measurement; refused + /// charges do not increase it. This is accounted capacity, not process RSS. + pub fn peak_usage(&self, r: LoadResource) -> u64 { + self.peak[r as usize] + } pub fn charge(&mut self, r: LoadResource, amount: u64) -> Result<(), LoadFailure> { let next = self .used(r) @@ -300,6 +307,7 @@ impl LoadBudget { .ok_or_else(|| LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Overflow))?; self.check(r, next)?; self.used[r as usize] = next; + self.peak[r as usize] = self.peak[r as usize].max(next); Ok(()) } pub fn check(&self, r: LoadResource, amount: u64) -> Result<(), LoadFailure> { @@ -356,3 +364,29 @@ impl LoadBudget { result } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn peak_tracks_admitted_capacity_through_refunds_and_failed_transactions() { + let mut budget = LoadBudget::new(LoadLimits { temporary_bytes: 10, ..Default::default() }); + budget.charge(LoadResource::TemporaryBytes, 3).unwrap(); + let result: Result<(), LoadFailure> = budget.transaction(|budget| { + budget.charge(LoadResource::TemporaryBytes, 7)?; + budget.work(2)?; + budget.charge(LoadResource::TemporaryBytes, 1) + }); + assert!(result.is_err()); + assert_eq!(budget.used(LoadResource::TemporaryBytes), 3); + assert_eq!(budget.peak_usage(LoadResource::TemporaryBytes), 10); + assert_eq!(budget.used(LoadResource::Work), 2); + assert_eq!(budget.peak_usage(LoadResource::Work), 2); + budget.refund(LoadResource::TemporaryBytes, 3); + assert_eq!(budget.used(LoadResource::TemporaryBytes), 0); + assert_eq!(budget.peak_usage(LoadResource::TemporaryBytes), 10); + assert!(budget.charge(LoadResource::TemporaryBytes, u64::MAX).is_err()); + assert_eq!(budget.peak_usage(LoadResource::TemporaryBytes), 10); + } +} diff --git a/crates/console/prometeu-vm/src/program_image/tests.rs b/crates/console/prometeu-vm/src/program_image/tests.rs index 6ecacca..05bc707 100644 --- a/crates/console/prometeu-vm/src/program_image/tests.rs +++ b/crates/console/prometeu-vm/src/program_image/tests.rs @@ -258,3 +258,31 @@ fn constant_strings_share_image_domain_across_sessions_and_native_snapshots() { let Value::String(text) = &snapshot[0] else { panic!() }; assert_eq!(text.as_ref(), "shared"); } + +#[test] +#[ignore = "explicit release measurement; not a timing assertion"] +fn sealed_image_load_probe() { + use std::time::Instant; + let constants: Vec<_> = + (0..512).map(|index| K::String(format!("{index:04}:{}", "x".repeat(59)))).collect(); + let bytes = fixture(&[1, 0], 0, &constants, None, &[]); + let mut budget = budget(); + let start = Instant::now(); + let image = ValidatedProgramImage::load(&bytes, &mut budget, caps::NONE).unwrap(); + let elapsed = start.elapsed().as_nanos(); + assert_eq!(image.constant_content(), (32768, 512)); + assert_eq!(budget.used(Q::TemporaryBytes), 0); + println!( + "image arch={} pbx={} registry={} payload={} work={} peak_scratch={} retained_scratch={} strings={} allocations={} load_ns={}", + std::env::consts::ARCH, + bytes.len(), + image.registry_bytes(), + image.payload_bytes(), + budget.used(Q::Work), + budget.peak_usage(Q::TemporaryBytes), + budget.used(Q::TemporaryBytes), + image.constant_content().0, + image.constant_content().1, + elapsed + ); +} diff --git a/crates/console/prometeu-vm/src/typed_storage/tests.rs b/crates/console/prometeu-vm/src/typed_storage/tests.rs index 4ae486f..d08cf42 100644 --- a/crates/console/prometeu-vm/src/typed_storage/tests.rs +++ b/crates/console/prometeu-vm/src/typed_storage/tests.rs @@ -526,3 +526,156 @@ fn typed_dynamic_self_cycle_uses_one_mark_worklist_entry() { heap.sweep(); assert_eq!(budget.used(Q::GuestBytes), 0); } + +#[test] +#[ignore = "explicit release measurement; not a timing assertion"] +fn storage_and_gc_probe() { + use crate::value_contract::{pack_dynamic, unpack_dynamic}; + use std::hint::black_box; + use std::time::Instant; + println!( + "native arch={} Value={}/{} HeapRef={}/{} StringSlot={}/{} DynamicSlot={}/{} TraitSlot={}/{} StoredObject={}/{}", + std::env::consts::ARCH, + size_of::(), + align_of::(), + size_of::(), + align_of::(), + size_of::(), + align_of::(), + size_of::(), + align_of::(), + size_of::(), + align_of::(), + size_of::(), + align_of::() + ); + let registry = fixture_registry(); + for array in [INTS, BOOLS, VECS, PIXELS, REFS, STRINGS, TRAITS, DYNAMICS] { + let budget = RuntimeBudget::default(); + let mut heap = Heap::with_budget(&budget); + let layout = registry.type_layout(array).unwrap().array.unwrap(); + let count = 4096; + let start = Instant::now(); + let reference = heap.allocate_typed_array(registry.clone(), array, count).unwrap(); + let allocation_ns = start.elapsed().as_nanos(); + let default = + registry.type_layout(layout.element_type_id).unwrap().storage.default_values(); + assert_eq!(heap.load_typed(®istry, reference, 4095).unwrap().as_slice(), default); + let start = Instant::now(); + for index in 0..100_000 { + black_box( + heap.load_typed(black_box(®istry), reference, index % count as usize).unwrap(), + ); + } + let access_ns = start.elapsed().as_nanos(); + println!( + "array type={} count={} stride={} align={} guest={} aux={} handles={} allocation_ns={} reads=100000 access_ns={}", + array.0, + count, + layout.stride, + layout.element_alignment, + budget.used(Q::GuestBytes), + budget.used(Q::AuxiliaryBytes), + budget.used(Q::HandleSlots), + allocation_ns, + access_ns + ); + heap.mark_from_roots([reference]).unwrap(); + heap.sweep(); + assert_eq!(heap.len(), 1); + heap.sweep(); + assert_eq!(budget.used(Q::GuestBytes), 0); + drop(heap); + assert_eq!(budget.used(Q::AuxiliaryBytes), 0); + } + for period in [1, 16, 256] { + let mut declarations = registry.declarations().clone(); + let ty = TypeId(declarations.types.len() as u32); + declarations.types.push(TypeDecl { + name: None, + kind: TypeKind::Struct( + (0..4096) + .map(|index| NamedType { + name: None, + type_id: if index % period == 0 { ENEMY } else { I64 }, + }) + .collect(), + ), + }); + let mut load = LoadBudget::new(Default::default()); + let registry = Arc::new(Registry::resolve(declarations, 0, &mut load).unwrap()); + let budget = RuntimeBudget::default(); + let mut heap = Heap::with_budget(&budget); + let holder = heap.allocate_typed_struct(registry.clone(), ty).unwrap(); + let child = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap(); + let dead = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap(); + for index in (0..4096).step_by(period) { + heap.store_typed(®istry, holder, index, &[Value::HeapRef(child)]).unwrap(); + } + let start = Instant::now(); + for _ in 0..1000 { + heap.mark_from_roots([holder]).unwrap(); + heap.sweep(); + } + let gc_ns = start.elapsed().as_nanos(); + assert_eq!(heap.len(), 2); + assert!(heap.is_valid(child)); + assert!(!heap.is_valid(dead)); + assert_eq!(budget.used(Q::TemporaryBytes), 0); + println!( + "gc period={} fields=4096 roots={} live={} guest={} aux={} work={} load_peak_scratch={} rounds=1000 gc_ns={}", + period, + 4096 / period, + heap.len(), + budget.used(Q::GuestBytes), + budget.used(Q::AuxiliaryBytes), + load.used(prometeu_bytecode::load_limits::LoadResource::Work), + load.peak_usage(prometeu_bytecode::load_limits::LoadResource::TemporaryBytes), + gc_ns + ); + } + let budget = RuntimeBudget::default(); + let mut heap = Heap::with_budget(&budget); + let start = Instant::now(); + let dynamic = + pack_dynamic(®istry, &mut heap, VEC, &[Value::Float(3.0), Value::Float(4.0)]).unwrap(); + let pack_ns = start.elapsed().as_nanos(); + let start = Instant::now(); + for _ in 0..100_000 { + black_box(unpack_dynamic(®istry, &heap, VEC, black_box(dynamic.as_slice())).unwrap()); + } + println!( + "dynamic vec2_boxes={} guest={} pack_ns={} unpacks=100000 unpack_ns={}", + heap.len(), + budget.used(Q::GuestBytes), + pack_ns, + start.elapsed().as_nanos() + ); + let holder = heap.allocate_typed_array(registry.clone(), DYNAMICS, 1).unwrap(); + heap.store_typed(®istry, holder, 0, dynamic.as_slice()).unwrap(); + heap.mark_from_roots([holder]).unwrap(); + heap.sweep(); + assert_eq!(heap.len(), 2); + heap.sweep(); + assert_eq!(budget.used(Q::GuestBytes), 0); + let strings = crate::string_ledger::StringLedger::new(budget.clone()).unwrap(); + let text = strings.import("shared-native").unwrap(); + let weak = Arc::downgrade(&text); + let root = heap.allocate_typed_struct(registry.clone(), MIXED).unwrap(); + heap.store_typed(®istry, root, 3, &[Value::String(text.clone())]).unwrap(); + heap.store_typed(®istry, root, 4, &[Value::Int64(STRING.0.into()), Value::String(text)]) + .unwrap(); + assert_eq!(budget.used(Q::StringBytes), 13); + heap.mark_from_roots([root]).unwrap(); + heap.sweep(); + strings.reconcile(); + assert!(weak.upgrade().is_some()); + assert_eq!(budget.used(Q::StringBytes), 13); + heap.sweep(); + strings.reconcile(); + assert!(weak.upgrade().is_none()); + assert_eq!(budget.used(Q::StringBytes), 0); + println!( + "native_string content=13 storage_owners=2 allocations=1 rooted_gc=retained unrooted_gc=released" + ); +} diff --git a/docs/vm-arch/ARCHITECTURE.md b/docs/vm-arch/ARCHITECTURE.md index 3038894..7ea575d 100644 --- a/docs/vm-arch/ARCHITECTURE.md +++ b/docs/vm-arch/ARCHITECTURE.md @@ -125,7 +125,7 @@ The verifier statically checks bytecode for structural safety and stack‑shape 4.2 Runtime vs Verifier Guarantees -- The verifier guarantees structural correctness and stack‑shape invariants. It does not perform full type checking of value contents; dynamic checks (e.g., numeric domain checks, polymorphic comparisons, concrete syscall argument validation) occur at runtime and may trap. +- The Registry verifier checks structure and stack shape and conservatively tracks known types through control flow. It rejects proved incompatibilities; Unknown values retain runtime checks at typed boundaries. Numeric domain checks, polymorphic comparisons and concrete syscall argument validation may still trap at runtime. The legacy production loader remains pending the callable migration described below. - Capability gating for syscalls is enforced at load from cartridge capability flags and checked again at runtime by the VM/native interface. @@ -187,3 +187,5 @@ The verifier statically checks bytecode for structural safety and stack‑shape ## Program Registry v1 The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v1.md) defines immutable image-owned Type/Function metadata linked by dense IDs. Descriptors are native metadata outside guest GC; nominal identity does not depend on names. Stack/local execution retains Value, while typed storage uses resolved aligned layouts. PBX v1 is the sole target format; publication requires full bounded validation. Callable/closure/coroutine typed integration awaits its separate contract and must preserve existing behavior until then. + +`ValidatedProgramImage::load` publishes a shared image only after bounded decoding, native binding and Registry verification; `VirtualMachine::from_image` creates sessions that consume its typed signatures, constants and conversion instructions. Production `initialize` and the existing example generators still await coordinated migration with the callable contract. The [producer handoff](registry-producer-handoff.md) documents schema, input IDs and named-argument order, while [layout evidence](registry-layout-evidence.md) records reproducible load/access/GC measurements and the current publication boundary. diff --git a/docs/vm-arch/registry-layout-evidence.md b/docs/vm-arch/registry-layout-evidence.md new file mode 100644 index 0000000..8c5f8d2 --- /dev/null +++ b/docs/vm-arch/registry-layout-evidence.md @@ -0,0 +1,97 @@ +# Registry layout, load and GC evidence + +This report records bounded technical fixtures for DEC-0045 / PLN-0176 step 35. The normative contract is [Program Registry and PBX v1](../specs/runtime/02c-program-registry-and-pbx-v1.md); producer obligations and publication status are in the [producer handoff](registry-producer-handoff.md). + +Measured on 2026-10-07: Darwin arm64, Rust 1.98.1 (`48a229cea`), host `aarch64-apple-darwin`, LLVM 22.1.8, optimized Cargo release profile. The code baseline is `c6fff08`; this report's commit also contains the load high-water instrumentation and measurement fixtures. Wall-clock values are single observations, not thresholds or statistically established throughput. No timing assertion is used. + +## Reproduction + +```sh +cargo test -p prometeu-bytecode --release --test registry_v1 reference_map_probe -- --ignored --nocapture +cargo test -p prometeu-vm --release --lib probe -- --ignored --nocapture --test-threads=1 +cargo test -p prometeu-vm --release --lib decoded_trait_box_is_the_only_receiver_root_across_frame_sync_gc --quiet +cargo test -p prometeu-vm --lib ownership_tests --quiet +``` + +The first probe compares ownership-map traversal with a synthetic bitmap. The second executes complete sealed-image loading, typed-array allocation/access, object tracing and native-owner cleanup. Its tests run sequentially. Fixtures construct internal typed containers because guest collection allocation/read/write operations belong to AGD-0054. No new collection instruction or cost is inferred from native helper timings. + +## Native representation and typed-array access + +Native sizes/alignment in bytes on this target: + +| Carrier or owner | Size | Alignment | +| --- | ---: | ---: | +| `Value` | 24 | 8 | +| `HeapRef` | 8 | 8 | +| `StringSlot` | 16 | 8 | +| `DynamicSlot` | 32 | 8 | +| Compact trait slot | 16 | 8 | +| `StoredObject` | 416 | 8 | + +`Value` remains the execution carrier. Arrays use resolved storage directly. The fixture allocates 4,096 default-initialized elements per array in a fresh heap, checks the last element, then performs 100,000 checked `load_typed` reads with `black_box`. It does not allocate a result Vec per read. Reference/native arrays below contain their null defaults, so these access times do not measure live-handle validation or String cloning throughput. + +| Element | Stride / alignment | Guest bytes | Auxiliary bytes | Allocation ns | 100,000 reads ns | +| --- | ---: | ---: | ---: | ---: | ---: | +| int32 | 4 / 4 | 16,800 | 60 | 45,709 | 2,439,084 | +| bool | 1 / 1 | 4,512 | 60 | 14,792 | 2,348,666 | +| vec2 | 16 / 8 | 65,952 | 60 | 18,167 | 2,220,125 | +| pixel | 24 / 8 | 98,720 | 60 | 17,208 | 2,469,125 | +| Struct reference | 8 / 8 | 33,184 | 60 | 21,833 | 1,990,667 | +| String | 16 / 8 | 65,952 | 60 | 15,042 | 2,069,584 | +| Trait | 16 / 8 | 65,952 | 60 | 13,500 | 2,019,667 | +| Dynamic | 32 / 8 | 131,488 | 60 | 17,875 | 2,330,000 | + +Each case owns one handle. Guest bytes equal one actual `StoredObject` plus `count * stride`. Auxiliary bytes are the initial generational-table capacities, separate from element storage and Registry metadata. After marking the array it survives; after an unrooted sweep guest bytes return to zero, and dropping the heap releases retained auxiliary tables. Native header sizes are implementation details, not PBX fields or portable guest ABI promises. + +## Complete load and scratch ownership + +The sealed-image fixture contains one named bool type, one named zero-argument HALT function and 512 distinct 64-byte String constants; no debug records or native calls. + +| Measurement | Value | +| --- | ---: | +| PBX bytes | 35,520 | +| Retained Registry bytes | 587 | +| Retained image payload accounting | 65,880 | +| Deterministic load work units | 204,641 | +| Peak admitted temporary bytes | 77,906 | +| Temporary bytes after publication | 0 | +| String content bytes / allocations | 32,768 / 512 | +| Complete load ns | 184,416 | + +`LoadBudget::peak_usage` measures the highest successfully admitted reservation total in a budget's lifetime. Refunds and failed transactions retain that high-water mark; rejected charges do not increase it. The associated test proves rollback restores current ownership while preserving attempted work and peak history. These are accounted capacities and coexistence reservations, including conservative native owner sizing; they are not allocator telemetry or process RSS. Image payload, constant content and PBX admission are different counters, so this table must not be summed into a physical-memory total. A single fixture does not establish worst-case load work or peak scratch at the 64 MiB PBX ceiling. + +## Ownership maps and actual object GC + +The map-only fixture has 4,096 eight-byte fields, with a reference every `period` fields. It traverses the resolved ownership list and a synthetic bitmap 10,000 times and checks equal offsets/checksums. Its Registry has only the three types needed for that comparison. + +| Period | Mapped entries | Registry bytes | List / bitmap bytes | Resolve ns | List traversal ns | Bitmap traversal ns | +| --- | ---: | ---: | ---: | ---: | ---: | ---: | +| 1 | 4,096 | 262,816 | 65,536 / 512 | 271,709 | 8,048,708 | 62,797,875 | +| 16 | 256 | 201,376 | 4,096 / 512 | 121,083 | 819,584 | 4,254,000 | +| 256 | 16 | 197,536 | 256 / 512 | 30,959 | 89,458 | 442,791 | + +The actual GC fixture extends the storage test Registry with a 4,096-field Struct. Every mapped reference aliases the same live child; an unrelated child is unrooted. The one holder root retains exactly two objects after mark/sweep. It repeats 1,000 collections, verifies that the unrelated handle is invalid and releases the temporary mark worklist on every collection. + +| Period | Mapped entries | Live guest bytes | Retained auxiliary bytes | Resolve work | Resolve peak scratch | 1,000 GC rounds ns | +| --- | ---: | ---: | ---: | ---: | ---: | ---: | +| 1 | 4,096 | 33,600 | 180 | 16,765 | 312 | 15,308,125 | +| 16 | 256 | 33,600 | 180 | 16,765 | 312 | 1,039,625 | +| 256 | 16 | 33,600 | 180 | 16,765 | 312 | 138,916 | + +Mapped entries are edges, not distinct worklist roots. Repeated aliases enqueue the child once. Retained auxiliary capacity includes the swept object's reusable handle slot. Resolve scratch here measures direct Registry resolution, not complete PBX decoding. The timing shows the expected dependence on mapped edges for these fixtures; it does not establish pause times for a broad object graph or justify changing the accepted map representation. + +## Dynamic conversion and native ownership + +A vec2 pack creates one immutable box with 464 guest bytes: the 416-byte structural owner plus two 24-byte Values. The observed pack took 1,000 ns; 100,000 exact vec2 unpacks took 2,816,583 ns. Storing the Dynamic pair in a typed array, marking that array and sweeping retains the box; removing the root releases its guest charge. Separate conformance tests prove repeated Dynamic copies/repacking preserve the box handle, typed-null traits allocate no box and malformed category/type/width/handle combinations fail. + +Decoded guest operations have independently asserted attempt costs: Dynamic pack/unpack/query = 8/4/3, reference exact/implements/cast = 4, reference-to-trait = 5. Each charges once on success or trap. Native timings above do not redefine those costs. + +The decoded trait-box test removes the original global receiver owners, then reaches `FRAME_SYNC` through the sealed image. GC retains the box and receiver solely through the operand-stack Dynamic pair. After unpack and two POPs, the next permitted GC invalidates both handles and retains the entry coroutine. This proves the real interpreter/safepoint path as well as the internal container path. + +The native fixture stores one session-imported 13-byte String in both a String field and a direct Dynamic field: two storage owners, one content allocation and one charge. Rooted collection retains it; unrooted collection drops both owners and ledger reconciliation releases content/allocation charges. The focused ownership test additionally removes the String field while the Dynamic alias remains, checks Arc identity and proves only the final owner permits release. Image constants, cross-session imports and retained native snapshots have separate integration tests. + +## Publication boundary + +The sealed v1 image, bounded verifier, typed direct calls, Dynamic/reference execution, metered native strings and structured host diagnostics have executable evidence. Production `VirtualMachine::initialize` still uses the old loader, and existing generators still emit version 0. Their coordinated migration must preserve existing closures and awaits AGD-0055's callable contract; the producer handoff records that dependency. The whole plan and final publication audit remain in progress. + +These measurements cover bounded layout/load/access/ownership/GC behavior. Representative-game capacity and headroom belong to AGD-0060; coordinated long-run stress belongs to AGD-0059. No external compiler implementation, cross-host stress acceptance, regenerated production PBX smoke or complete workflow closure is claimed by this report.