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
+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}");
}
}