feat(pbs): add linked collections and bidirectional snapshots

Implement SDK linked<T> with forward and reverse Cursor snapshots, trusted compiler integration, and neutral FIELDS_PUBLISH producer support. Pin the tested runtime revision and include specs, editor and installed knowledge coverage, conformance fixtures, and DSC-0091 lessons and evidence.
This commit is contained in:
2026-10-23 10:28:44 +01:00
parent c410e35001
commit 77aada6259
38 changed files with 3040 additions and 57 deletions
+173 -16
View File
@@ -41,6 +41,7 @@ fn main() {
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 == "--linked-only") { verify_common_storage_fixtures(&root); verify_pbs_linked_fixtures(&root); return; }
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; }
@@ -55,6 +56,7 @@ fn main() {
verify_pbs_generic_struct_fixtures(&root);
verify_common_storage_fixtures(&root);
verify_pbs_list_cursor_fixtures(&root);
verify_pbs_linked_fixtures(&root);
verify_pbs_resource_refusals(&root);
verify_pbs_closure_frames(&root);
for name in [
@@ -491,7 +493,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-list-") || !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-linked-") || !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)
@@ -1168,10 +1170,12 @@ fn verify_list_cursor_refusals(root:&std::path::Path) {
assert!(operand_preparation,"source operation operand/frame preparation refusal");
}
fn verify_list_cursor_gc(root:&std::path::Path) {
fn verify_list_cursor_gc(root:&std::path::Path) { verify_collection_cursor_gc(root,"list"); }
fn verify_collection_cursor_gc(root:&std::path::Path,collection:&str) {
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 bytes=std::fs::read(root.join(format!("pbs-{collection}-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;
@@ -1184,9 +1188,10 @@ fn verify_list_cursor_gc(root:&std::path::Path) {
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}");
if collection=="linked" {assert!(named("_LinkedNode<Item>").is_empty(),"snapshot does not retain original Linked nodes");}
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);
println!("PBS {} CURSOR GC PASS round={round} nodes={nodes} items={items} collected={}",collection.to_uppercase(),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)]);
@@ -1194,7 +1199,7 @@ fn verify_list_cursor_gc(root:&std::path::Path) {
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"] {
for name in ["common-storage","common-storage-optimized","common-fields","common-fields-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();
@@ -1205,24 +1210,176 @@ fn verify_common_storage_fixtures(root:&std::path::Path) {
}
}
fn verify_list_cursor_distribution(root:&std::path::Path) {
fn verify_list_cursor_distribution(root:&std::path::Path) { verify_collection_distribution(root,"list",22); }
fn verify_collection_distribution(root:&std::path::Path,collection:&str,last:i32) {
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 bytes=std::fs::read(root.join(format!("pbs-{collection}-{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}");
let cursors=objects.iter().filter(|o|image.registry().declarations().types[o.type_id.0 as usize].name.as_deref()==Some("_SnapshotCursor<int>")).collect::<Vec<_>>();
assert!(!cursors.is_empty(),"distributed frame actually created its shared snapshot Cursor");
let mut retained=Vec::new();
for cursor in cursors {
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();
let V::Int32(value)=node.groups[0][0] else {panic!("typed captured value")};
retained.push(value);
assert_eq!(node.groups[1],[V::Null],"{name}: final node has no successor");
}
retained.sort_unstable();
let expected=if collection=="linked"&&name=="installed" {vec![20,22]} else {vec![last]};
assert_eq!(retained,expected,"{collection} {name}: complete traversal retains each final value");
println!("PBS {} DISTRIBUTION LOAD/EXEC PASS {name}",collection.to_uppercase());
}
}
fn verify_pbs_linked_fixtures(root: &std::path::Path) {
use prometeu_vm::{LogicalFrameEndingReason as End, resource_budget::{RuntimeLimits,RuntimeResource}};
use prometeu_bytecode::TRAP_OOB;
let successful=["basic","links","construction","long-size","empty-cursor","empty-reverseCursor",
"single-cursor","single-reverseCursor","snapshot","false-present","optional-field","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-remove",TRAP_OOB),("fault-overflow",TRAP_OOB),("fault-long-index",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-linked-{name}.pbx")))
.unwrap_or_else(|e|panic!("missing mandatory SDK Linked fixture {name}: {e}"));
let image=ValidatedProgramImage::load(&bytes,&mut LoadBudget::new(LoadLimits::default()),caps::NONE)
.unwrap_or_else(|e|panic!("Linked {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 LINKED SOURCE/LOAD/EXEC PASS {name}");
}
verify_linked_collection_gc(root);
verify_linked_refusals(root);
verify_collection_cursor_gc(root,"linked");
verify_collection_distribution(root,"linked",20);
}
fn linked_state(vm:&VirtualMachine,image:&ValidatedProgramImage)->Vec<prometeu_vm::resource_diagnostics::StorageObject> {
use prometeu_vm::resource_diagnostics::StorageValue as V;
let objects=vm.heap().diagnostic_typed_storage();
let root=objects.iter().find(|o|image.registry().declarations().types[o.type_id.0 as usize].name.as_deref()==Some("linked<int>"))
.expect("source Linked remains observable");
let mut pending=vec![root.reference];let mut state=Vec::new();
while let Some(reference)=pending.pop() {
if state.iter().any(|o:&prometeu_vm::resource_diagnostics::StorageObject|o.reference==reference) {continue;}
let object=objects.iter().find(|o|o.reference==reference).expect("live complete Linked group");
for group in &object.groups {for value in group {if let V::Reference(r)=value {pending.push(*r);}}}
state.push(object.clone());
}
state.sort_by_key(|o|(o.reference.index,o.reference.generation));state
}
fn verify_linked_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 node_allocation=false;let mut optional_return=false;let mut snapshot_allocation=false;let mut preparation=false;
for name in ["insert","add","addFirst","remove","removeFirst","removeLast","replace","clear","cursor","reverseCursor"] {
let bytes=std::fs::read(root.join(format!("pbs-linked-refusal-{name}.pbx"))).expect("mandatory Linked 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);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=linked_state(&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 after=baseline.resource_snapshot();let changed=linked_state(&baseline,&image);
let owner=changed.iter().find(|o|image.registry().declarations().types[o.type_id.0 as usize].name.as_deref()==Some("linked<int>")).unwrap();
let expected=match name {"insert"|"add"|"addFirst"=>33,"remove"|"removeFirst"|"removeLast"=>31,"clear"=>0,_=>32};
assert_eq!(owner.groups[2],[V::Int64(expected)]);
if name=="cursor"||name=="reverseCursor" {assert_eq!(changed,original);}
let mut refused=0;
for q in [Q::GuestBytes,Q::HandleSlots,Q::AuxiliaryBytes,Q::TemporaryBytes] {
let lower=before.budget.peaks[q as usize];let upper=after.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+24));}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 {q:?}={limit}: {setup:?}");
let old=linked_state(&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} {q:?}={limit}: {info:?}");
assert_eq!(linked_state(&vm,&image),old,"{name}: all original fields, groups and reciprocal links at {q:?}={limit}");
let instruction=decode_next(info.pc as usize,image.code()).unwrap();
preparation|=q==Q::AuxiliaryBytes;
if instruction.opcode==Op::StructNew {
let declaration=&image.registry().declarations().types[instruction.imm_u32().unwrap() as usize];
node_allocation|=declaration.name.as_deref()==Some("_LinkedNode<int>");
snapshot_allocation|=declaration.name.as_deref()==Some("_SnapshotNode<int>");
if name.starts_with("remove") {
if let prometeu_bytecode::registry::TypeKind::Struct(fields)=&declaration.kind {
optional_return|=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));
}
}
}
refused+=1;println!("PBS LINKED 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!(refused>0,"{name}: whole-source-operation refusals required");
}
assert!(node_allocation,"new Linked node refusal");assert!(optional_return,"optional removed-value refusal");
assert!(snapshot_allocation,"snapshot node refusal");assert!(preparation,"frame/operand preparation refusal");
}
fn verify_linked_collection_gc(root:&std::path::Path) {
use prometeu_vm::{LogicalFrameEndingReason as End,resource_budget::RuntimeLimits};
let bytes=std::fs::read(root.join("pbs-linked-gc-collection.pbx")).expect("mandatory Linked removal/clear 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,count) in [1200,1197,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),"collection GC {round}: {report:?}");
let collections=vm.resource_snapshot().gc.collections;assert!(collections>previous,"real collection at round {round}");previous=collections;
let objects=vm.heap().diagnostic_typed_storage();
for name in ["_LinkedNode<Item>","Item"] {
let actual=objects.iter().filter(|o|image.registry().declarations().types[o.type_id.0 as usize].name.as_deref()==Some(name)).count();
assert_eq!(actual,count,"{name} after removal/clear at round {round}");
}
println!("PBS LINKED COLLECTION GC PASS round={round} nodes={count} items={count}");
}
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)]);
}