feat(vm): publish typed fields across multiple structs atomically

Add schema-driven FIELDS_PUBLISH without collection-specific runtime behavior. Validate every nullable destination and complete field group before allocation-free publication, with neutral ownership, malformed-input and quota coverage.
This commit is contained in:
Nilton Constantino
2026-10-23 09:53:40 +01:00
committed by bquarkz
parent d9b9eeb171
commit 57992cf214
13 changed files with 384 additions and 12 deletions
@@ -179,7 +179,7 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u16(CoreOpCode::Ret as u16, &mut out);
}
"YIELD" | "SLEEP" | "SPAWN" => {
return Err(AsmError::InvalidOperand("retired coroutine instruction".into()))
return Err(AsmError::InvalidOperand("retired coroutine instruction".into()));
}
"FRAME_SYNC" => {
emit_u16(CoreOpCode::FrameSync as u16, &mut out);
@@ -362,11 +362,12 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u32(field, &mut out);
}
"STRUCT_NEW" | "ARRAY_NEW" | "ARRAY_LEN" | "ARRAY_GET" | "ARRAY_SET"
| "ARRAY_CHECK_LENGTH" | "ARRAY_COPY" => {
| "ARRAY_CHECK_LENGTH" | "ARRAY_COPY" | "FIELDS_PUBLISH" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let op = match mn {
"FIELDS_PUBLISH" => CoreOpCode::FieldsPublish,
"STRUCT_NEW" => CoreOpCode::StructNew,
"ARRAY_NEW" => CoreOpCode::ArrayNew,
"ARRAY_LEN" => CoreOpCode::ArrayLen,
@@ -21,9 +21,9 @@
//! - Floats use exact bit-pattern format to prevent locale/rounding differences.
//! - Ordering is the canonical decode order; no address prefixes are emitted.
use crate::DecodeError;
use crate::decode_next;
use crate::isa::core::{CoreOpCode, CoreOpCodeSpecExt};
use crate::DecodeError;
fn fmt_f64_bits(bits: u64) -> String {
// Fixed-width 16 hex digits, lowercase.
@@ -72,7 +72,8 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
| CoreOpCode::ArrayGet
| CoreOpCode::ArraySet
| CoreOpCode::ArrayCheckLength
| CoreOpCode::ArrayCopy => {
| CoreOpCode::ArrayCopy
| CoreOpCode::FieldsPublish => {
let v = u32::from_le_bytes(imm.try_into().unwrap());
format!("{}", v)
}
@@ -210,6 +210,8 @@ pub enum OpCode {
/// Move/fill array ranges and two selected Struct fields in one attempt.
/// Array TypeId, Struct TypeId, first field, second field (four u32).
StoragePublish = 0xAA,
/// Atomic full-field writes to schema-selected nullable Struct destinations.
FieldsPublish = 0xAB,
}
impl TryFrom<u16> for OpCode {
@@ -287,6 +289,7 @@ impl TryFrom<u16> for OpCode {
0xA8 => Ok(OpCode::ArrayCheckLength),
0xA9 => Ok(OpCode::ArrayCopy),
0xAA => Ok(OpCode::StoragePublish),
0xAB => Ok(OpCode::FieldsPublish),
_ => Err(format!("Invalid OpCode: 0x{:04X}", value)),
}
@@ -366,7 +369,7 @@ impl OpCode {
OpCode::ArraySet => 4,
OpCode::IndexGuard | OpCode::ArrayCheckLength => 2,
OpCode::ArrayCopy => 4,
OpCode::StoragePublish => 6,
OpCode::StoragePublish | OpCode::FieldsPublish => 6,
}
}
}
@@ -676,10 +676,14 @@ impl OpCodeSpecExt for OpCode {
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayCheckLength | OpCode::ArrayCopy | OpCode::StoragePublish => OpcodeSpec {
OpCode::ArrayCheckLength
| OpCode::ArrayCopy
| OpCode::StoragePublish
| OpCode::FieldsPublish => OpcodeSpec {
name: match self {
OpCode::ArrayCheckLength => "ARRAY_CHECK_LENGTH",
OpCode::ArrayCopy => "ARRAY_COPY",
OpCode::FieldsPublish => "FIELDS_PUBLISH",
_ => "STORAGE_PUBLISH",
},
imm_bytes: if *self == OpCode::StoragePublish { 16 } else { 4 },
@@ -86,7 +86,7 @@ impl DecodedInstr<'_> {
)
}
Op::GetCapture => {
return Err(LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex))
return Err(LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex));
}
Op::CallTrait => {
let (ty, method) = self.imm_u32x2().map_err(|_| malformed())?;
@@ -133,6 +133,28 @@ impl DecodedInstr<'_> {
};
(source_layout.storage.slots, pushes)
}
Op::FieldsPublish => {
let schema = self.imm_u32().map_err(|_| malformed())?;
let (decl, _) = type_info(schema)?;
let TypeKind::Struct(entries) = &decl.kind else {
return Err(bad_category(schema));
};
let mut slots = 0u32;
for entry in entries {
let (owner, layout) = type_info(entry.type_id.0)?;
if !matches!(owner.kind, TypeKind::Struct(_)) {
return Err(bad_category(entry.type_id.0));
}
let fields =
u32::try_from(layout.instance.as_ref().unwrap().initialization_slots)
.map_err(|_| malformed())?;
slots = slots
.checked_add(1)
.and_then(|n| n.checked_add(fields))
.ok_or_else(malformed)?;
}
(slots, 0)
}
Op::ArrayCheckLength | Op::ArrayCopy | Op::StoragePublish => {
let (array, owner, first, second) = if self.opcode == Op::StoragePublish {
let [a, o, f, s] = self.imm_u32x4().map_err(|_| malformed())?;
@@ -188,11 +210,7 @@ impl DecodedInstr<'_> {
.get(field as usize)
.ok_or_else(|| bad_category(id).member(field))?;
let w = registry.type_layout(f.type_id).unwrap().storage.slots;
if op == Op::StructGet {
(1, w)
} else {
(1 + w, 0)
}
if op == Op::StructGet { (1, w) } else { (1 + w, 0) }
}
}
} else {
@@ -87,6 +87,17 @@ fn validate_inner(
},
)?;
}
if instruction.opcode == Op::FieldsPublish {
if let Some(declaration) =
registry.declarations().types.get(instruction.imm_u32().unwrap() as usize)
{
if let prometeu_bytecode::registry::TypeKind::Struct(entries) =
&declaration.kind
{
budget.work(entries.len())?;
}
}
}
instruction
.registry_stack_effect_in(registry, FunctionId(function_id))
.map_err(|e| contextual(e, start + pc))?;
@@ -709,6 +709,27 @@ fn check(
require(working[end - 2], I64, 0, registry, budget)?;
require(working[end - 1], I64, 1, registry, budget)?;
}
Op::FieldsPublish => {
let schema = TypeId(instruction.imm_u32().unwrap());
let effect = instruction.registry_stack_effect(registry)?.unwrap();
let mut at = end - effect.pops as usize;
let TypeKind::Struct(entries) = &registry.declarations().types[schema.0 as usize].kind
else {
unreachable!()
};
for entry in entries {
budget.work(1)?;
check_group(&working[at..], entry.type_id, registry, budget)?;
at += 1;
for field in
&registry.type_layout(entry.type_id).unwrap().instance.as_ref().unwrap().fields
{
budget.work(1)?;
check_group(&working[at..], field.type_id, registry, budget)?;
at += registry.type_layout(field.type_id).unwrap().storage.slots as usize;
}
}
}
Op::ArrayCopy | Op::StoragePublish => {
let [a, o, f, s] = if instruction.opcode == Op::StoragePublish {
instruction.imm_u32x4().unwrap()
@@ -1086,6 +1086,9 @@ impl VirtualMachine {
let (source, target) = instr.imm_u32x2().unwrap();
return self.execute_reference(opcode, source, target, start_pc as u32);
}
OpCode::FieldsPublish => {
return self.execute_fields_publication(instr.imm_u32().unwrap(), start_pc as u32);
}
OpCode::IndexGuard
| OpCode::ArrayCheckLength
| OpCode::ArrayCopy
@@ -180,3 +180,107 @@ impl VirtualMachine {
Ok(())
}
}
impl VirtualMachine {
/// A Struct schema lists destination Struct types, without allocating a request.
/// Inputs stay rooted and unconsumed until validation of the entire attempt.
pub(super) fn execute_fields_publication(
&mut self,
schema: u32,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
let opcode = OpCode::FieldsPublish;
self.cycles += opcode.cycles();
let image = self.validated_image.clone().expect("validated Registry operation");
let registry = image.registry();
let prometeu_bytecode::registry::TypeKind::Struct(entries) =
&registry.declarations().types[schema as usize].kind
else {
unreachable!()
};
let consumed: usize = entries
.iter()
.map(|entry| {
1 + registry
.type_layout(entry.type_id)
.unwrap()
.instance
.as_ref()
.unwrap()
.fields
.iter()
.map(|f| registry.type_layout(f.type_id).unwrap().storage.slots as usize)
.sum::<usize>()
})
.sum();
if self.temporary_slots() < consumed {
return Err(self.trap(
TRAP_STACK_UNDERFLOW,
opcode as u16,
"Incomplete field publication operands".into(),
pc,
));
}
self.cycles += consumed as u64;
let base = self.operand_stack.len() - consumed;
let mut at = base;
for entry in entries {
match self.operand_stack[at] {
Value::Null => {}
Value::HeapRef(receiver) => {
if self
.heap
.concrete_type(receiver, registry)
.map_err(|e| self.value_trap(e, opcode, pc))?
!= entry.type_id
{
return Err(self.value_trap(ValueError::Type, opcode, pc));
}
}
_ => return Err(self.value_trap(ValueError::Type, opcode, pc)),
}
at += 1;
for field in
&registry.type_layout(entry.type_id).unwrap().instance.as_ref().unwrap().fields
{
let width = registry.type_layout(field.type_id).unwrap().storage.slots as usize;
value_contract::validate(
registry,
&self.heap,
field.type_id,
&self.operand_stack[at..at + width],
)
.map_err(|e| self.value_trap(e, opcode, pc))?;
at += width;
}
}
// No allocation, provenance lookup, validation, callback, GC or scheduler
// boundary follows. Repeated destinations use ordered last-write semantics.
at = base;
for entry in entries {
let receiver = match self.operand_stack[at] {
Value::HeapRef(r) => Some(r),
_ => None,
};
at += 1;
for (index, field) in registry
.type_layout(entry.type_id)
.unwrap()
.instance
.as_ref()
.unwrap()
.fields
.iter()
.enumerate()
{
let width = registry.type_layout(field.type_id).unwrap().storage.slots as usize;
if let Some(receiver) = receiver {
self.heap.commit_typed(receiver, index, &self.operand_stack[at..at + width]);
}
at += width;
}
}
self.operand_stack.truncate(base);
Ok(())
}
}
@@ -222,3 +222,157 @@ fn dead_invalid_operands_and_split_typed_groups_are_rejected() {
support::load(&assemble("PUSH_BOOL 1\nPUSH_I64 3\nINDEX_GUARD\nHALT").unwrap()).is_err()
);
}
fn fields_machine() -> VirtualMachine {
use prometeu_bytecode::registry::{NamedType, TypeDecl, TypeKind};
let mut code = String::new();
for i in 0..12 {
code += &format!("GET_GLOBAL {i}\n");
}
code += "FIELDS_PUBLISH 27\nHALT";
let code = assemble(&code).unwrap();
let mut declarations = support::declarations(code.len());
assert_eq!(declarations.types.len(), 26);
let field = |id| NamedType { type_id: TypeId(id), name: None };
declarations.types.push(TypeDecl {
name: None,
kind: TypeKind::Struct([0, 5, 4, 9].into_iter().map(field).collect()),
});
declarations.types.push(TypeDecl {
name: None,
kind: TypeKind::Struct([26, 26].into_iter().map(field).collect()),
});
let image = crate::ValidatedProgramImage::load(
&support::bytes_with(&code, declarations),
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
prometeu_hal::syscalls::caps::NONE,
)
.unwrap();
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
vm
}
#[test]
fn fields_publication_is_complete_preserves_native_and_reference_groups_and_needs_no_scratch() {
for alias in [false, true] {
let mut vm = fields_machine();
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let first = vm.heap.allocate_typed_struct(registry.clone(), TypeId(26)).unwrap();
let second = if alias {
first
} else {
vm.heap.allocate_typed_struct(registry.clone(), TypeId(26)).unwrap()
};
let payload = vm.heap.allocate_typed_struct(registry.clone(), TypeId(9)).unwrap();
let text: std::sync::Arc<str> = "owned".into();
let inputs = [
Value::HeapRef(first),
Value::Int32(1),
Value::Float(2.),
Value::Float(3.),
Value::String(text.clone()),
Value::HeapRef(payload),
Value::HeapRef(second),
Value::Int32(42),
Value::Float(20.),
Value::Float(22.),
Value::String(text.clone()),
Value::HeapRef(payload),
];
operands(&mut vm, &inputs);
for resource in [
RuntimeResource::GuestBytes,
RuntimeResource::HandleSlots,
RuntimeResource::TemporaryBytes,
RuntimeResource::AuxiliaryBytes,
] {
vm.budget.test_lower_limit(resource, vm.budget.used(resource));
}
let count = vm.heap.allocation_count();
let cycles = vm.cycles;
step(&mut vm).unwrap();
assert_eq!(vm.cycles - cycles, 18);
assert_eq!(count, vm.heap.allocation_count());
assert!(vm.operand_stack.is_empty());
assert_eq!(
vm.heap.load_typed(&registry, first, 0).unwrap().as_slice(),
[Value::Int32(if alias { 42 } else { 1 })]
);
assert_eq!(
vm.heap.load_typed(&registry, second, 1).unwrap().as_slice(),
[Value::Float(20.), Value::Float(22.)]
);
let native = vm.heap.load_typed(&registry, first, 2).unwrap();
let Value::String(stored) = &native.as_slice()[0] else { panic!() };
assert!(std::sync::Arc::ptr_eq(stored, &text));
assert_eq!(
vm.heap.load_typed(&registry, first, 3).unwrap().as_slice(),
[Value::HeapRef(payload)]
);
}
}
#[test]
fn fields_publication_checks_late_groups_and_skipped_destinations_before_any_write() {
for skipped in [false, true] {
let mut vm = fields_machine();
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let first = vm.heap.allocate_typed_struct(registry.clone(), TypeId(26)).unwrap();
let second = vm.heap.allocate_typed_struct(registry.clone(), TypeId(26)).unwrap();
let inputs = [
Value::HeapRef(first),
Value::Int32(42),
Value::Float(1.),
Value::Float(2.),
Value::Null,
Value::Null,
if skipped { Value::Null } else { Value::HeapRef(second) },
Value::Int32(7),
Value::Float(3.),
Value::Float(4.),
Value::Boolean(true),
Value::Null,
];
operands(&mut vm, &inputs);
fault(step(&mut vm), TRAP_TYPE);
assert_eq!(vm.operand_stack.as_slice(), inputs);
for owner in [first, second] {
assert_eq!(
vm.heap.load_typed(&registry, owner, 0).unwrap().as_slice(),
[Value::Int32(0)]
);
}
}
let mut vm = fields_machine();
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let first = vm.heap.allocate_typed_struct(registry.clone(), TypeId(26)).unwrap();
let inputs = [
Value::HeapRef(first),
Value::Int32(42),
Value::Float(1.),
Value::Float(2.),
Value::Null,
Value::Null,
Value::Null,
Value::Int32(7),
Value::Float(3.),
Value::Float(4.),
Value::Null,
Value::Null,
];
operands(&mut vm, &inputs);
step(&mut vm).unwrap();
assert_eq!(vm.heap.load_typed(&registry, first, 0).unwrap().as_slice(), [Value::Int32(42)]);
}
#[test]
fn fields_publication_rejects_bad_schemas_dead_operands_and_truncation() {
for text in ["HALT\nFIELDS_PUBLISH 0", "HALT\nFIELDS_PUBLISH 99", "HALT\nFIELDS_PUBLISH 9"] {
assert!(support::load(&assemble(text).unwrap()).is_err(), "{text}");
}
let bytes = assemble("FIELDS_PUBLISH 26").unwrap();
for end in 2..bytes.len() {
assert!(prometeu_bytecode::decode_next(0, &bytes[..end]).is_err());
}
}
@@ -219,3 +219,37 @@ before mutation. A refused preparation still charges the attempted work. Neither
operation is a safepoint. Consumers must prepare any potentially failing return
carrier and all call operands before publication; a series of ordinary stores is
not a substitute for whole-operation safety.
## Atomic publication of multiple Struct instances
FIELDS_PUBLISH (`0xAB`) has one little-endian u32 schema TypeId immediate. The
schema MUST be a Registry Struct whose ordered field types are all Struct types.
Names are descriptive only. The schema is declarative metadata; no request object,
new Registry category or preparation token is allocated or exposed.
For each schema entry, the operand stack supplies one nullable destination
reference followed by every destination field's complete typed value group, in
field declaration order. The stack effect is the sum, over entries, of one plus
the destination instance's initialization-slot count; no results are produced.
Null skips that destination, but every supplied field group is still validated.
Non-null destinations require exact concrete Struct identity and a live reference
of the current session/generation. Array, Trait, Fn and builtin schema entries are
invalid, including in unreachable instructions. The full schema and exact stack
height/groups are checked under normal Registry admission/work limits.
Validate all destinations and value groups before any shared write or operand
consumption. The original operands remain roots throughout preparation. Then write
all fields in schema order, without allocation, fallible validation, callbacks,
GC or scheduler interleaving, and consume the entire input. Input values are
captured before publication; repeated destinations use ordered last-write
semantics. Complete multi-slot/native/reference groups retain identity and normal
ownership. A failed attempt preserves every destination and the operand stack.
The operation allocates no publication scratch or guest object. Operand/frame and
source value preparation remain normally charged and may fail before publication.
Base cost is 6 cycles. After the stack-height check, precharge one cycle per schema
entry and one per destination field execution slot for the complete declared
attempt, including skipped destinations. Quotas are unchanged.
This is a generic typed storage mechanism; collection algorithms and node topology
remain source-owned, with no collection-specific VM instruction or syscall.
+9
View File
@@ -202,3 +202,12 @@ The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v0
## VM-owned random core
See the [random contract](../specs/runtime/02e-vm-owned-random-core.md) for Random BuiltinId 0x0016, ObjectKind tag 9, intrinsics 0x4000–0x4003, atomic state mutation, bounded 4+8*N costs and rejection-limit trap 0x00000015. Random is managed by the VM heap and existing GC, without host entropy or PBX changes.
## Atomic publication of multiple Struct instances
FIELDS_PUBLISH (0xAB) atomically publishes complete typed fields to multiple
source-selected Struct destinations. Its schema is an ordinary Registry Struct;
no new category, request object, syscall or safepoint is introduced. Exact nullable
destination rules, stack effects, validation, costs and commit semantics are in the
[canonical instruction contract](../specs/runtime/02-vm-instruction-set.md#atomic-publication-of-multiple-struct-instances).
+9
View File
@@ -198,3 +198,12 @@ STORAGE_PUBLISH (0xAA) provide generic logical validation, complete stored-group
transfer and prepared atomic publication. Their encoding, typed operands, exact
faults, overlap semantics, costs and preflight/commit guarantees are defined by
the [canonical instruction contract](../specs/runtime/02-vm-instruction-set.md#logical-guards-and-atomic-storage-publication). No new Registry category, syscall, collection algorithm or safepoint is introduced.
## Atomic publication of multiple Struct instances
FIELDS_PUBLISH (0xAB) atomically publishes complete typed fields to multiple
source-selected Struct destinations. Its schema is an ordinary Registry Struct;
no new category, request object, syscall or safepoint is introduced. Exact nullable
destination rules, stack effects, validation, costs and commit semantics are in the
[canonical instruction contract](../specs/runtime/02-vm-instruction-set.md#atomic-publication-of-multiple-struct-instances).