feat(pbs): add mutable lists and stable snapshot cursors

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.
This commit is contained in:
2026-10-23 00:46:39 +01:00
parent 76a8b074e8
commit c410e35001
46 changed files with 2683 additions and 165 deletions
+40
View File
@@ -224,3 +224,43 @@ python3 tools/pbx-conformance/run.py --runtime ../runtime --generic-contracts-on
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.
+201 -1
View File
@@ -36,6 +36,12 @@ impl NativeInterface for NoNative {
fn main() {
let root = std::path::PathBuf::from(std::env::args().nth(1).expect("fixture directory"));
use prometeu_vm::resource_budget::{RuntimeLimits,RuntimeResource as Q};
let limits=RuntimeLimits::default();
for resource in [Q::GuestBytes,Q::HandleSlots,Q::AuxiliaryBytes,Q::TemporaryBytes,Q::StringBytes,Q::StringAllocations,Q::IndividualStringBytes,Q::CallDepth] {
println!("DEFAULT VM LIMIT {resource:?}={}",limits.get(resource));
}
if std::env::args().any(|arg| arg == "--list-cursor-only") { verify_common_storage_fixtures(&root); verify_pbs_list_cursor_fixtures(&root); return; }
if std::env::args().any(|arg| arg == "--generic-contracts-only") { verify_pbs_generic_contract_fixtures(&root); return; }
if std::env::args().any(|arg| arg == "--generic-structs-only") { verify_pbs_generic_struct_fixtures(&root); return; }
if std::env::args().any(|arg| arg == "--random-only") { verify_pbs_random_fixtures(&root); return; }
@@ -47,6 +53,8 @@ fn main() {
verify_pbs_structured_fixtures(&root);
verify_pbs_generic_contract_fixtures(&root);
verify_pbs_generic_struct_fixtures(&root);
verify_common_storage_fixtures(&root);
verify_pbs_list_cursor_fixtures(&root);
verify_pbs_resource_refusals(&root);
verify_pbs_closure_frames(&root);
for name in [
@@ -483,7 +491,7 @@ fn verify_pbs_fixtures(root: &std::path::Path) {
for entry in std::fs::read_dir(root).unwrap() {
let path = entry.unwrap().path();
let name = path.file_stem().unwrap().to_str().unwrap();
if name.starts_with("pbs-random-") || name.starts_with("pbs-math-") || name.starts_with("pbs-structured-") || name.starts_with("pbs-generic-contract-") || name.starts_with("pbs-generic-struct-") || !name.starts_with("pbs-") || path.extension().and_then(|v| v.to_str()) != Some("pbx") { continue; }
if name.starts_with("pbs-random-") || name.starts_with("pbs-math-") || name.starts_with("pbs-structured-") || name.starts_with("pbs-generic-contract-") || name.starts_with("pbs-generic-struct-") || name.starts_with("pbs-list-") || !name.starts_with("pbs-") || path.extension().and_then(|v| v.to_str()) != Some("pbx") { continue; }
count += 1;
let bytes = std::fs::read(&path).unwrap();
let image = ValidatedProgramImage::load(&bytes, &mut LoadBudget::new(LoadLimits::default()), caps::NONE)
@@ -1026,3 +1034,195 @@ fn verify_pbs_random_fixtures(root: &std::path::Path) {
println!("RANDOM PASS real SDK imports and aliases");
}
fn verify_pbs_list_cursor_fixtures(root: &std::path::Path) {
use prometeu_vm::{LogicalFrameEndingReason as End, resource_budget::{RuntimeLimits,RuntimeResource}};
use prometeu_bytecode::{TRAP_OOB,TRAP_RESOURCE_LIMIT};
let successful=["basic","construction","capacity","holes","structural-growth","cursor-empty","cursor-single",
"cursor-many","snapshot","false-present","shared-optional","identity","tuple","nested-array","function","evaluation","vec2","pixel","contract"];
let faults=[("fault-read",TRAP_OOB),("fault-write",TRAP_OOB),("fault-negative",TRAP_OOB),
("fault-insert",TRAP_OOB),("fault-length",TRAP_OOB),("fault-overflow",TRAP_RESOURCE_LIMIT),
("fault-long-index",TRAP_OOB),("fault-constructor",TRAP_OOB)];
let cases=successful.into_iter().map(|n|(n,None)).chain(faults.into_iter().map(|(n,c)|(n,Some(c))))
.flat_map(|(name,fault)|[(name.to_string(),fault),(format!("{name}-optimized"),fault)]);
for (name,fault) in cases {
let bytes=std::fs::read(root.join(format!("pbs-list-{name}.pbx")))
.unwrap_or_else(|e|panic!("missing mandatory SDK List/Cursor fixture {name}: {e}"));
let image=ValidatedProgramImage::load(&bytes,&mut LoadBudget::new(LoadLimits::default()),caps::NONE)
.unwrap_or_else(|e|panic!("List/Cursor {name}: {e:?}"));
let mut vm=VirtualMachine::from_image(image,RuntimeLimits::default());
let observer=vm.resource_observer();
vm.prepare_boot_call().unwrap();
let report=vm.run_budget(1_000_000,&mut NoNative,&mut HostContext::new(None)).unwrap();
if let Some(code)=fault {
let End::Trap(info)=report.reason else {panic!("{name}: {report:?}")};
assert_eq!(info.code,code,"{name}: {info:?}");
} else {
assert!(matches!(report.reason,End::Halted|End::EndOfRom),"{name}: {report:?}");
assert_eq!(vm.operand_stack_top(1),vec![Value::Int32(42)],"{name}");
}
drop(vm);
for resource in [RuntimeResource::GuestBytes,RuntimeResource::HandleSlots,RuntimeResource::AuxiliaryBytes,
RuntimeResource::TemporaryBytes,RuntimeResource::StringBytes,RuntimeResource::StringAllocations] {
assert_eq!(observer.used(resource),0,"{name}: final owner release {resource:?}");
}
println!("PBS LIST/CURSOR SOURCE/LOAD/EXEC PASS {name}");
}
verify_list_cursor_refusals(root);
verify_list_cursor_gc(root);
verify_list_cursor_distribution(root);
}
fn list_storage(vm:&VirtualMachine,image:&ValidatedProgramImage)->(prometeu_vm::resource_diagnostics::StorageObject,prometeu_vm::resource_diagnostics::StorageObject) {
use prometeu_vm::resource_diagnostics::StorageValue as V;
let objects=vm.heap().diagnostic_typed_storage();
let object=objects.iter().find(|o|image.registry().declarations().types[o.type_id.0 as usize].name.as_deref()==Some("list<int>"))
.expect("one source List remains observable").clone();
let V::Reference(backing)=object.groups[0][0] else {panic!("List storage reference")};
let array=objects.iter().find(|o|o.reference==backing).unwrap().clone();
(object,array)
}
fn verify_list_cursor_refusals(root:&std::path::Path) {
use prometeu_vm::{LogicalFrameEndingReason as End, resource_budget::{RuntimeLimits,RuntimeResource as Q}};
use prometeu_vm::resource_diagnostics::StorageValue as V;
use prometeu_bytecode::{decode_next,TRAP_RESOURCE_LIMIT};
use prometeu_bytecode::isa::core::CoreOpCode as Op;
let mut publication_scratch=false;let mut return_carrier=false;let mut nodes=false;let mut candidate=false;let mut operand_preparation=false;
for name in ["insert","remove","growth","cursor"] {
let bytes=std::fs::read(root.join(format!("pbs-list-refusal-{name}.pbx"))).expect("mandatory refusal fixture");
let image=ValidatedProgramImage::load(&bytes,&mut LoadBudget::new(LoadLimits::default()),caps::NONE).unwrap();
let marker=|value:i32| {
let mut pc=0;let mut found=Vec::new();
while pc<image.code().len() {let instruction=decode_next(pc,image.code()).unwrap();
if instruction.opcode==Op::PushI32&&instruction.imm_i32().unwrap()==value {found.push(pc);}
pc=instruction.next_pc;
}
assert_eq!(found.len(),1,"one explicit test marker");found[0]
};
let before_pc=marker(314160);let after_pc=marker(314161);
let prepare=|limits| {
let mut vm=VirtualMachine::from_image(image.clone(),limits);vm.prepare_boot_call().unwrap();
vm.insert_breakpoint(before_pc);vm.insert_breakpoint(after_pc);vm
};
let mut baseline=prepare(RuntimeLimits::default());
assert!(matches!(baseline.run_budget(20_000_000,&mut NoNative,&mut HostContext::new(None)).unwrap().reason,End::Breakpoint));
let before=baseline.resource_snapshot();let original=list_storage(&baseline,&image);
baseline.remove_breakpoint(before_pc);
assert!(matches!(baseline.run_budget(20_000_000,&mut NoNative,&mut HostContext::new(None)).unwrap().reason,End::Breakpoint));
let completed=baseline.resource_snapshot();let changed=list_storage(&baseline,&image);
let expected_size=match name {"insert"|"growth"=>129,"remove"=>127,_=>128};
assert_eq!(changed.0.groups[1],[V::Int64(expected_size)],"{name} logical size after success");
if name=="remove" {assert_eq!(changed.1.groups[12][1],V::Int32(13));assert_eq!(changed.1.groups[127],[V::Null,V::Null]);}
if name=="insert" {assert_eq!(changed.1.groups[12][1],V::Int32(42));assert_eq!(changed.1.groups[13][1],V::Int32(12));}
if name=="growth" {assert_eq!(changed.1.groups.len(),192);assert_eq!(changed.1.groups[128][1],V::Int32(42));}
if name=="cursor" {assert_eq!(changed,original);}
let mut refusals=0;
for q in [Q::GuestBytes,Q::HandleSlots,Q::AuxiliaryBytes,Q::TemporaryBytes] {
let lower=before.budget.peaks[q as usize];let upper=completed.budget.peaks[q as usize];
if lower>=upper {continue;}
let mut limits=vec![lower,lower+(upper-lower)/4,lower+(upper-lower)/2,upper-1];
if q==Q::HandleSlots {limits.extend(lower..upper.min(lower+16));}
limits.sort_unstable();limits.dedup();
for limit in limits {
let mut vm=prepare(RuntimeLimits::default().lowered(q,limit).unwrap());
let observer=vm.resource_observer();
let setup=vm.run_budget(20_000_000,&mut NoNative,&mut HostContext::new(None)).unwrap();
assert!(matches!(setup.reason,End::Breakpoint),"{name} setup at {q:?}={limit}: {setup:?}");
let state=list_storage(&vm,&image);
vm.remove_breakpoint(before_pc);
let report=vm.run_budget(20_000_000,&mut NoNative,&mut HostContext::new(None)).unwrap();
if let End::Trap(info)=report.reason {
assert_eq!(info.code,TRAP_RESOURCE_LIMIT,"{name} at {q:?}={limit}: {info:?}");
assert_eq!(list_storage(&vm,&image),state,"{name}: no partial slots/backing/size at {q:?}={limit}");
let instruction=decode_next(info.pc as usize,image.code()).unwrap();
publication_scratch|=q==Q::TemporaryBytes&&instruction.opcode==Op::StoragePublish;
operand_preparation|=q==Q::AuxiliaryBytes;
candidate|=name=="growth"&&instruction.opcode==Op::ArrayNew;
if instruction.opcode==Op::StructNew {
let ty=instruction.imm_u32().unwrap();
let declaration=&image.registry().declarations().types[ty as usize];
nodes|=name=="cursor"&&declaration.name.as_deref().is_some_and(|n|n.starts_with("_SnapshotNode<"));
if name=="remove" {
if let prometeu_bytecode::registry::TypeKind::Struct(fields)=&declaration.kind {
return_carrier|=fields.len()==1&&matches!(image.registry().declarations().types[fields[0].type_id.0 as usize].kind,
prometeu_bytecode::registry::TypeKind::Builtin(prometeu_bytecode::registry::BuiltinId::INT32));
}
}
}
refusals+=1;
println!("PBS LIST ATOMIC REFUSAL {name} resource={q:?} limit={limit} opcode={:?}",instruction.opcode);
} else {assert!(matches!(report.reason,End::Breakpoint),"{name}: {report:?}");}
drop(vm);
for resource in [Q::GuestBytes,Q::HandleSlots,Q::AuxiliaryBytes,Q::TemporaryBytes] {assert_eq!(observer.used(resource),0);}
}
}
assert!(refusals>0,"{name}: mandatory source refusals executed");
}
assert!(publication_scratch,"no-growth publication scratch refusal");
assert!(return_carrier,"removeAt optional return allocation refusal");
assert!(candidate,"growth candidate allocation refusal");
assert!(nodes,"snapshot node allocation refusal");
assert!(operand_preparation,"source operation operand/frame preparation refusal");
}
fn verify_list_cursor_gc(root:&std::path::Path) {
use prometeu_vm::{LogicalFrameEndingReason as End,resource_budget::RuntimeLimits};
use prometeu_vm::resource_diagnostics::StorageValue as V;
let bytes=std::fs::read(root.join("pbs-list-gc.pbx")).expect("mandatory snapshot GC fixture");
let image=ValidatedProgramImage::load(&bytes,&mut LoadBudget::new(LoadLimits::default()),caps::NONE).unwrap();
let mut vm=VirtualMachine::from_image(image.clone(),RuntimeLimits::default());vm.prepare_boot_call().unwrap();
let mut previous=0;
for (round,(nodes,items)) in [(1200,1200),(1,1),(1,1),(0,0)].into_iter().enumerate() {
let report=vm.run_budget(30_000_000,&mut NoNative,&mut HostContext::new(None)).unwrap();
assert!(matches!(report.reason,End::FrameSync),"snapshot GC {round}: {report:?}");
let snapshot=vm.resource_snapshot();assert!(snapshot.gc.collections>previous);previous=snapshot.gc.collections;
let objects=vm.heap().diagnostic_typed_storage();
assert!(!objects.iter().any(|o|matches!(image.registry().declarations().types[o.type_id.0 as usize].kind,
prometeu_bytecode::registry::TypeKind::Array(_))),"Cursor retains no source or snapshot array");
let named=|name:&str|objects.iter().filter(|o|image.registry().declarations().types[o.type_id.0 as usize].name.as_deref()==Some(name)).collect::<Vec<_>>();
assert_eq!(named("_SnapshotNode<Item>").len(),nodes,"prefix nodes round {round}");
let values=named("Item");assert_eq!(values.len(),items,"captured object roots round {round}");
if items==1 {assert_eq!(values[0].groups[0],[V::Int32(1199)],"sticky last payload remains live");}
println!("PBS CURSOR GC PASS round={round} nodes={nodes} items={items} collected={}",snapshot.gc.reclaimed);
}
let report=vm.run_budget(100_000,&mut NoNative,&mut HostContext::new(None)).unwrap();
assert!(matches!(report.reason,End::Halted|End::EndOfRom));assert_eq!(vm.operand_stack_top(1),vec![Value::Int32(42)]);
}
fn verify_common_storage_fixtures(root:&std::path::Path) {
use prometeu_vm::{LogicalFrameEndingReason as End,resource_budget::RuntimeLimits};
for name in ["common-storage","common-storage-optimized"] {
let bytes=std::fs::read(root.join(format!("{name}.pbx"))).expect("mandatory non-PBS storage fixture");
let image=ValidatedProgramImage::load(&bytes,&mut LoadBudget::new(LoadLimits::default()),caps::NONE).unwrap();
let mut vm=VirtualMachine::from_image(image,RuntimeLimits::default());vm.prepare_boot_call().unwrap();
let report=vm.run_budget(100_000,&mut NoNative,&mut HostContext::new(None)).unwrap();
assert!(matches!(report.reason,End::Halted|End::EndOfRom),"{name}: {report:?}");
assert_eq!(vm.operand_stack_top(1),vec![Value::Int32(42)]);
println!("COMMON STORAGE SOURCE/LOAD/EXEC PASS {name}");
}
}
fn verify_list_cursor_distribution(root:&std::path::Path) {
use prometeu_vm::{LogicalFrameEndingReason as End,resource_budget::RuntimeLimits};
for name in ["imports","installed"] {
let bytes=std::fs::read(root.join(format!("pbs-list-{name}.pbx"))).expect("mandatory workspace/installed List fixture");
let image=ValidatedProgramImage::load(&bytes,&mut LoadBudget::new(LoadLimits::default()),caps::NONE).unwrap();
let mut vm=VirtualMachine::from_image(image.clone(),RuntimeLimits::default());vm.prepare_boot_call().unwrap();
let report=vm.run_budget(1_000_000,&mut NoNative,&mut HostContext::new(None)).unwrap();
assert!(matches!(report.reason,End::FrameSync|End::Halted|End::EndOfRom),"{name}: {report:?}");
use prometeu_vm::resource_diagnostics::StorageValue as V;
let objects=vm.heap().diagnostic_typed_storage();
let cursor=objects.iter().find(|o|image.registry().declarations().types[o.type_id.0 as usize].name.as_deref()==Some("_SnapshotCursor<int>"))
.expect("distributed frame actually created its shared snapshot Cursor");
let V::Reference(current)=cursor.groups[0][0] else {panic!("nonempty Cursor retains its current node carrier")};
let carrier=objects.iter().find(|o|o.reference==current).unwrap();
let V::Reference(node)=carrier.groups[0][0] else {panic!("current points at a snapshot node")};
let node=objects.iter().find(|o|o.reference==node).unwrap();
assert_eq!(node.groups[0],[V::Int32(22)],"{name}: complete traversal retains the final value");
assert_eq!(node.groups[1],[V::Null],"{name}: final node has no successor");
println!("PBS LIST/CURSOR DISTRIBUTION LOAD/EXEC PASS {name}");
}
}
+7 -1
View File
@@ -15,6 +15,7 @@ parser.add_argument("--release", action="store_true", help="Execute an optimized
parser.add_argument("--math-only", action="store_true", help="Run the complete PBS math corpus only")
parser.add_argument("--random-only", action="store_true", help="Run the complete PBS Random corpus only")
parser.add_argument("--generic-contracts-only", action="store_true", help="Run the mandatory generic-contract source corpus only")
parser.add_argument("--list-cursor-only", action="store_true", help="Run the mandatory SDK List/Cursor corpus only")
parser.add_argument("--generic-structs-only", action="store_true", help="Run the mandatory generic-struct/function source corpus only")
args = parser.parse_args()
runtime = args.runtime.resolve()
@@ -29,6 +30,11 @@ for source in [pathlib.Path(__file__), pathlib.Path(__file__).with_name("main.rs
pathlib.Path("prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/random/main.pbs")]:
print("sha256", source, hashlib.sha256(source.read_bytes()).hexdigest(), flush=True)
print("runtime", subprocess.check_output(["git", "-C", str(runtime), "rev-parse", "HEAD"], text=True).strip(), flush=True)
print("runtime working tree", subprocess.check_output(["git","-C",str(runtime),"status","--short"],text=True).strip() or "clean",flush=True)
for source in [pathlib.Path("prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsListCursorTest.java"),
pathlib.Path("prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/collections/main.pbs"),
runtime / "crates/console/prometeu-vm/src/virtual_machine/storage_publication.rs"]:
print("sha256",source,hashlib.sha256(source.read_bytes()).hexdigest(),flush=True)
print("platform", platform.platform(), "limits=default capabilities=NONE", flush=True)
print("profile", "release" if args.release else "dev", "features=resource-diagnostics", flush=True)
for relative in ["Cargo.lock", "docs/vm-arch/INTRINSICS.csv", "docs/vm-arch/BUILTIN_CONSTANTS.csv", "crates/console/prometeu-vm/tests/fixtures/numeric-conformance.tsv", "crates/console/prometeu-vm/tests/fixtures/random-conformance.tsv"]:
@@ -44,4 +50,4 @@ with tempfile.TemporaryDirectory(prefix="pbx-conformance-") as directory:
(root / "Cargo.lock").write_text((runtime / "Cargo.lock").read_text())
(root / "src").mkdir()
(root / "src/main.rs").write_text(pathlib.Path(__file__).with_name("main.rs").read_text())
subprocess.run(["cargo", "run", *(["--release"] if args.release else []), *([] if args.online else ["--offline"]), "--manifest-path", str(root / "Cargo.toml"), "--", str(args.fixtures.resolve()), str(runtime / "devtools/headless-protocol/response.schema.json"), *(["--math-only"] if args.math_only else []), *(["--random-only"] if args.random_only else []), *(["--generic-contracts-only"] if args.generic_contracts_only else []), *(["--generic-structs-only"] if args.generic_structs_only else [])], check=True)
subprocess.run(["cargo", "run", *(["--release"] if args.release else []), *([] if args.online else ["--offline"]), "--manifest-path", str(root / "Cargo.toml"), "--", str(args.fixtures.resolve()), str(runtime / "devtools/headless-protocol/response.schema.json"), *(["--math-only"] if args.math_only else []), *(["--random-only"] if args.random_only else []), *(["--generic-contracts-only"] if args.generic_contracts_only else []), *(["--generic-structs-only"] if args.generic_structs_only else []), *(["--list-cursor-only"] if args.list_cursor_only else [])], check=True)