Author SHA1 Message Date
bquarkz 74c7522dd1 feat(vm): integrate metered strings and native retention for PLN-0176 step 19 2026-10-07 20:50:44 +01:00
bquarkz 1124ac10e7 feat(vm): execute reference tests and casts for PLN-0176 step 22 2026-10-07 20:36:28 +01:00
bquarkz c7236f1269 feat(vm): execute Dynamic instructions and exact costs for PLN-0176 step 21 2026-10-07 20:34:11 +01:00
bquarkz ba603ce64a feat(vm): enforce typed CALL RET and native entry boundaries for PLN-0176 step 26 2026-10-07 20:32:09 +01:00
bquarkz a9d91be39e feat(vm): publish validated shared PBX v1 images for PLN-0176 step 14 2026-10-07 20:26:01 +01:00
bquarkz a563f3b456 feat(loader): materialize bounded PBX v1 payloads for PLN-0176 step 09 2026-10-07 20:25:25 +01:00
bquarkz 43b466c813 feat(vm): add metered shared-string infrastructure for PLN-0176 step 19 2026-10-07 19:24:54 +01:00
bquarkz 01112da951 feat(verifier): add conservative type flow for PLN-0176 step 25 2026-10-07 19:09:37 +01:00
bquarkz 8d32fef65c feat(vm): add reference conversion helpers for PLN-0176 step 22 2026-10-07 18:27:10 +01:00
bquarkz 60d66d22a5 feat(verifier): add bounded stack analysis for PLN-0176 step 24 2026-10-07 18:27:09 +01:00
bquarkz 43314573d7 fix(loader): bound PBX input admission for PLN-0176 step 09 2026-10-07 17:58:16 +01:00
bquarkz dff4041de7 feat(bytecode): complete PLN-0176 step 08 typed PBX v1 writer 2026-10-07 17:53:30 +01:00
bquarkz 126a9e50e7 feat(registry): checkpoint PLN-0176 foundations and validated partial integrations 2026-10-07 17:49:46 +01:00
bquarkz 01fab56cc6 Merge pull request 'feat: add headless automation protocol and CLI' (#41) from dev/studio-headless-runtime-ai-first into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #41
2026-09-28 16:29:00 +00:00
bquarkz 4f10f6e584 feat: add headless automation protocol and CLI
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-09-28 15:36:22 +01:00
bquarkz e8e4d64e42 chore: keep only discussion lessons tracked
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-09-24 06:14:02 +01:00
bquarkz 31ad7f9446 bump new version and updates
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-09-24 06:08:53 +01:00
bquarkz 6d185ab97e Merge pull request 'harden deterministic headless runtime control' (#40) from dev/headless-automation-host-hardening into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #40
2026-09-23 06:30:01 +00:00
119 changed files with 17989 additions and 2904 deletions
+4
View File
@@ -66,3 +66,7 @@ AGENTS.md
.python-version
.venv
discussion/*
!discussion/lessons/
!discussion/lessons/**
Generated
+1122 -348
View File
File diff suppressed because it is too large Load Diff
@@ -24,6 +24,15 @@ pub const TRAP_BAD_RET_SLOTS: u32 = 0x0000_000C;
/// The intrinsic ID provided is not recognized by the runtime, or its metadata is invalid.
pub const TRAP_INVALID_INTRINSIC: u32 = 0x0000_000D;
/// Valid absence used where an instance is required.
pub const TRAP_NULL_REFERENCE: u32 = 0x0000_000E;
/// Invalid, dead or stale generational heap reference.
pub const TRAP_INVALID_HANDLE: u32 = 0x0000_000F;
/// Quota, checked size overflow or recoverable allocation failure.
pub const TRAP_RESOURCE_LIMIT: u32 = 0x0000_0010;
/// Known input query unavailable on this platform.
pub const TRAP_UNAVAILABLE: u32 = 0x0000_0011;
use serde::{Deserialize, Serialize};
/// Detailed information about a source code span.
@@ -360,6 +360,34 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u32(parse_u32_any(ops)?, &mut out);
}
"DYN_PACK" | "DYN_UNPACK" | "DYN_CAN_UNPACK" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let opcode = match mn {
"DYN_PACK" => CoreOpCode::DynPack,
"DYN_UNPACK" => CoreOpCode::DynUnpack,
_ => CoreOpCode::DynCanUnpack,
};
emit_u16(opcode as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"REF_IS_EXACT" | "REF_IMPLEMENTS" | "REF_TO_TRAIT" | "REF_CAST" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (a, b) = parse_keyvals(ops)?;
let (source, target) = parse_pair(a, "source", b, "target")?;
let opcode = match mn {
"REF_IS_EXACT" => CoreOpCode::RefIsExact,
"REF_IMPLEMENTS" => CoreOpCode::RefImplements,
"REF_TO_TRAIT" => CoreOpCode::RefToTrait,
_ => CoreOpCode::RefCast,
};
emit_u16(opcode as u16, &mut out);
emit_u32(source, &mut out);
emit_u32(target, &mut out);
}
other => return Err(AsmError::UnknownMnemonic(other.into())),
}
}
@@ -90,7 +90,7 @@ impl<'a> DecodedInstr<'a> {
/// Returns the decoded instruction with canonical `next_pc`.
#[inline]
pub fn decode_next(pc: usize, bytes: &'_ [u8]) -> Result<DecodedInstr<'_>, DecodeError> {
if pc + 2 > bytes.len() {
if pc.checked_add(2).is_none_or(|end| end > bytes.len()) {
return Err(DecodeError::TruncatedOpcode { pc });
}
@@ -100,7 +100,13 @@ pub fn decode_next(pc: usize, bytes: &'_ [u8]) -> Result<DecodedInstr<'_>, Decod
let spec: CoreOpcodeSpec = opcode.spec();
let imm_start = pc + 2;
let imm_end = imm_start + (spec.imm_bytes as usize);
let imm_end =
imm_start.checked_add(spec.imm_bytes as usize).ok_or(DecodeError::TruncatedImmediate {
pc,
opcode,
need: spec.imm_bytes as usize,
have: bytes.len().saturating_sub(imm_start),
})?;
if imm_end > bytes.len() {
return Err(DecodeError::TruncatedImmediate {
@@ -60,10 +60,21 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
| CoreOpCode::SetLocal
| CoreOpCode::Call
| CoreOpCode::Sleep
| CoreOpCode::Hostcall => {
| CoreOpCode::Hostcall
| CoreOpCode::DynPack
| CoreOpCode::DynUnpack
| CoreOpCode::DynCanUnpack => {
let v = u32::from_le_bytes(imm.try_into().unwrap());
format!("{}", v)
}
CoreOpCode::RefIsExact
| CoreOpCode::RefImplements
| CoreOpCode::RefToTrait
| CoreOpCode::RefCast => {
let source = u32::from_le_bytes(imm[..4].try_into().unwrap());
let target = u32::from_le_bytes(imm[4..].try_into().unwrap());
format!("source={}, target={}", source, target)
}
CoreOpCode::MakeClosure => {
let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap());
let cap = u32::from_le_bytes(imm[4..8].try_into().unwrap());
@@ -1,8 +1,9 @@
//! Core ISA profile (bytecode-level, stable, canonical).
//!
//! This profile is the canonical opcode surface used by decoder/disasm and
//! mirrors the runtime-visible instruction set implemented today, including
//! closures, coroutines, intrinsics, and hostcall patching semantics.
//! exposes the canonical encoding for closures, coroutines, intrinsics,
//! hostcall patching and Registry instructions. Recognition by tooling alone
//! does not authorize execution without validated program metadata.
// For PR-1.4 we define the core profile as the current `OpCode` set. We re-export
// the opcode type and spec so downstream tools can import from a stable path:
+11 -3
View File
@@ -12,13 +12,21 @@ mod value;
pub use abi::{
SourceSpan, TrapInfo, TRAP_BAD_RET_SLOTS, TRAP_DIV_ZERO, TRAP_EXPLICIT,
TRAP_ILLEGAL_INSTRUCTION, TRAP_INVALID_FUNC, TRAP_INVALID_INTRINSIC, TRAP_INVALID_LOCAL,
TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_STACK_UNDERFLOW, TRAP_TYPE,
TRAP_ILLEGAL_INSTRUCTION, TRAP_INVALID_FUNC, TRAP_INVALID_HANDLE, TRAP_INVALID_INTRINSIC,
TRAP_INVALID_LOCAL, TRAP_INVALID_SYSCALL, TRAP_NULL_REFERENCE, TRAP_OOB, TRAP_RESOURCE_LIMIT,
TRAP_STACK_UNDERFLOW, TRAP_TYPE, TRAP_UNAVAILABLE,
};
pub use assembler::{assemble, AsmError};
pub use decoder::{decode_next, DecodeError};
pub use decoder::{decode_next, DecodeError, DecodedInstr};
pub use disassembler::disassemble;
pub use layout::{compute_function_layouts, FunctionLayout};
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl, PBX_MAGIC};
pub use program_image::ProgramImage;
pub use value::{string_materialization_count, HeapRef, Value};
pub mod load_limits;
pub mod registry;
pub mod registry_codec;
mod registry_instruction;
pub use registry_instruction::RegistryStackEffect;
@@ -0,0 +1,350 @@
//! Shared PBX v1 resource limits and structured validation failures.
//! Counters are deterministic; a failed reservation never changes usage.
use std::fmt;
const MIB: u64 = 1_048_576;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LoadCode {
InvalidFormat,
UnsupportedFormat,
InvalidReference,
InvalidRegistry,
InvalidCode,
ResourceLimit,
InvalidEntrypoint,
}
impl LoadCode {
pub const fn tag(self) -> &'static str {
match self {
Self::InvalidFormat => "LOAD_INVALID_FORMAT",
Self::UnsupportedFormat => "LOAD_UNSUPPORTED_FORMAT",
Self::InvalidReference => "LOAD_INVALID_REFERENCE",
Self::InvalidRegistry => "LOAD_INVALID_REGISTRY",
Self::InvalidCode => "LOAD_INVALID_CODE",
Self::ResourceLimit => "LOAD_RESOURCE_LIMIT",
Self::InvalidEntrypoint => "LOAD_INVALID_ENTRYPOINT",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LoadReason {
Magic,
Version,
Endianness,
Reserved,
SectionKind,
MissingSection,
DuplicateSection,
Overlap,
Truncated,
TrailingBytes,
InvalidFlag,
Utf8,
Category,
Builtin,
TypeId,
FunctionId,
OwnerCategory,
TraitCategory,
DuplicateBuiltin,
DuplicateArray,
ArrayCycle,
DuplicateImplementation,
MethodCount,
Signature,
CodeRange,
FrameSlots,
ReturnSlots,
Overflow,
Limit,
Allocation,
ConstantTag,
DebugRange,
DuplicateSyscall,
UnknownOpcode,
LocalSlot,
JumpTarget,
InstructionBoundary,
BooleanImmediate,
ConstantIndex,
NativeId,
UnpatchedHostcall,
StackUnderflow,
StackOverflow,
StackJoin,
ReturnHeight,
UnterminatedPath,
UnknownClosureCallee,
NotClosure,
InvalidYield,
TypeMismatch,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(usize)]
pub enum LoadResource {
PbxBytes,
CodeBytes,
Types,
Functions,
Implementations,
NestedRecords,
NameBytes,
RegistryBytes,
TemporaryBytes,
Work,
ConstantEntries,
ConstantStringBytes,
}
const RESOURCE_COUNT: usize = 12;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IdDomain {
Type,
Function,
Implementation,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LoadFailure {
pub code: LoadCode,
pub reason: LoadReason,
pub section: Option<u32>,
pub offset: Option<usize>,
pub record: Option<u32>,
pub member: Option<u32>,
pub id_domain: Option<IdDomain>,
pub referenced_id: Option<u32>,
pub function: Option<u32>,
pub pc: Option<u32>,
pub resource: Option<LoadResource>,
pub requested: Option<u64>,
pub limit: Option<u64>,
}
impl LoadFailure {
pub fn new(code: LoadCode, reason: LoadReason) -> Self {
Self {
code,
reason,
section: None,
offset: None,
record: None,
member: None,
id_domain: None,
referenced_id: None,
function: None,
pc: None,
resource: None,
requested: None,
limit: None,
}
}
pub fn at(mut self, section: u32, offset: usize) -> Self {
self.section = Some(section);
self.offset = Some(offset);
self
}
pub fn record(mut self, record: u32) -> Self {
self.record = Some(record);
self
}
pub fn member(mut self, member: u32) -> Self {
self.member = Some(member);
self
}
pub fn in_section(mut self, section: u32) -> Self {
self.section = Some(section);
self
}
pub fn reference(mut self, domain: IdDomain, id: u32) -> Self {
self.id_domain = Some(domain);
self.referenced_id = Some(id);
self
}
pub fn in_function(mut self, function: u32, pc: Option<u32>) -> Self {
self.function = Some(function);
self.pc = pc;
self
}
pub fn resource(resource: LoadResource, requested: u64, limit: u64) -> Self {
Self {
resource: Some(resource),
requested: Some(requested),
limit: Some(limit),
..Self::new(LoadCode::ResourceLimit, LoadReason::Limit)
}
}
}
impl fmt::Display for LoadFailure {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}: {:?}", self.code.tag(), self.reason)?;
if let Some(section) = self.section {
write!(f, " in section {section}")?;
}
if let Some(offset) = self.offset {
write!(f, " at byte {offset}")?;
}
if let Some(record) = self.record {
write!(f, " (record {record})")?;
}
if let Some(resource) = self.resource {
write!(f, " ({resource:?}: {:?} / {:?})", self.requested, self.limit)?;
}
Ok(())
}
}
impl std::error::Error for LoadFailure {}
/// Product maxima; callers may lower limits but cannot raise the accepted ceilings.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LoadLimits {
pub pbx_bytes: u64,
pub code_bytes: u64,
pub types: u64,
pub functions: u64,
pub implementations: u64,
pub nested_records: u64,
pub name_bytes: u64,
pub individual_name_bytes: u64,
pub registry_bytes: u64,
pub temporary_bytes: u64,
pub work: u64,
pub frame_slots: u64,
pub result_slots: u64,
pub constant_entries: u64,
pub constant_string_bytes: u64,
pub individual_string_bytes: u64,
}
impl Default for LoadLimits {
fn default() -> Self {
Self {
pbx_bytes: 64 * MIB,
code_bytes: 32 * MIB,
types: 65_536,
functions: 65_536,
implementations: 262_144,
nested_records: 1_048_576,
name_bytes: 4 * MIB,
individual_name_bytes: 4096,
registry_bytes: 64 * MIB,
temporary_bytes: 128 * MIB,
work: 268_435_456,
frame_slots: 16_384,
result_slots: 1024,
constant_entries: 1_048_576,
constant_string_bytes: 64 * MIB,
individual_string_bytes: 4 * MIB,
}
}
}
impl LoadLimits {
fn ceiling(self, r: LoadResource) -> u64 {
match r {
LoadResource::PbxBytes => self.pbx_bytes,
LoadResource::CodeBytes => self.code_bytes,
LoadResource::Types => self.types,
LoadResource::Functions => self.functions,
LoadResource::Implementations => self.implementations,
LoadResource::NestedRecords => self.nested_records,
LoadResource::NameBytes => self.name_bytes,
LoadResource::RegistryBytes => self.registry_bytes,
LoadResource::TemporaryBytes => self.temporary_bytes,
LoadResource::Work => self.work,
LoadResource::ConstantEntries => self.constant_entries,
LoadResource::ConstantStringBytes => self.constant_string_bytes,
}
}
}
/// One load attempt's counters. Successful retained allocations stay charged
/// for the remainder of this attempt; executable-image lifetime accounting is
/// a separate owner. Reuse a budget only when its earlier allocations still live.
#[derive(Debug)]
pub struct LoadBudget {
limits: LoadLimits,
used: [u64; RESOURCE_COUNT],
}
impl LoadBudget {
pub fn new(limits: LoadLimits) -> Self {
Self { limits, used: [0; RESOURCE_COUNT] }
}
pub fn limit(&self, r: LoadResource) -> u64 {
self.limits.ceiling(r).min(LoadLimits::default().ceiling(r))
}
pub fn individual_string_limit(&self) -> u64 {
self.limits.individual_string_bytes.min(4 * MIB)
}
pub fn individual_name_limit(&self) -> u64 {
self.limits.individual_name_bytes.min(4096)
}
pub fn frame_limit(&self) -> u64 {
self.limits.frame_slots.min(16_384)
}
pub fn result_limit(&self) -> u64 {
self.limits.result_slots.min(1024)
}
pub fn used(&self, r: LoadResource) -> u64 {
self.used[r as usize]
}
pub fn charge(&mut self, r: LoadResource, amount: u64) -> Result<(), LoadFailure> {
let next = self
.used(r)
.checked_add(amount)
.ok_or_else(|| LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Overflow))?;
self.check(r, next)?;
self.used[r as usize] = next;
Ok(())
}
pub fn check(&self, r: LoadResource, amount: u64) -> Result<(), LoadFailure> {
if amount > self.limit(r) {
Err(LoadFailure::resource(r, amount, self.limit(r)))
} else {
Ok(())
}
}
pub fn refund(&mut self, r: LoadResource, amount: u64) {
self.used[r as usize] = self.used[r as usize]
.checked_sub(amount)
.expect("internal load budget accounting imbalance");
}
pub fn work(&mut self, amount: usize) -> Result<(), LoadFailure> {
self.charge(LoadResource::Work, amount as u64)
}
pub(crate) fn vector<T>(
&mut self,
count: usize,
r: LoadResource,
) -> Result<Vec<T>, LoadFailure> {
let bytes = count
.checked_mul(std::mem::size_of::<T>())
.ok_or_else(|| LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Overflow))?
as u64;
self.charge(r, bytes)?;
let mut result = Vec::new();
if result.try_reserve_exact(count).is_err() {
self.refund(r, bytes);
return Err(LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Allocation));
}
let actual = (result.capacity() as u64)
.checked_mul(std::mem::size_of::<T>() as u64)
.ok_or_else(|| LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Overflow))?;
if let Err(err) = self.charge(r, actual - bytes) {
self.refund(r, bytes);
return Err(err);
}
Ok(result)
}
/// Roll back retained counters on failure; attempted work remains charged.
pub(crate) fn transaction<T>(
&mut self,
f: impl FnOnce(&mut Self) -> Result<T, LoadFailure>,
) -> Result<T, LoadFailure> {
let before = self.used;
let result = f(self);
if result.is_err() {
let work = self.used(LoadResource::Work);
self.used = before;
self.used[LoadResource::Work as usize] = work;
}
result
}
}
@@ -202,6 +202,22 @@ pub enum OpCode {
/// Synchronizes the VM with the hardware frame (usually 60Hz).
/// Execution pauses until the next VSync.
FrameSync = 0x80,
// Registry-dependent typed operations (DEC-0045).
/// DYN_PACK: TypeId:u32; requires validated Registry metadata.
DynPack = 0x90,
/// DYN_UNPACK: TypeId:u32; requires validated Registry metadata.
DynUnpack = 0x91,
/// DYN_CAN_UNPACK: TypeId:u32; requires validated Registry metadata.
DynCanUnpack = 0x92,
/// REF_IS_EXACT: source:TypeId, target:TypeId; requires validated Registry metadata.
RefIsExact = 0x93,
/// REF_IMPLEMENTS: source:TypeId, target:TypeId; requires validated Registry metadata.
RefImplements = 0x94,
/// REF_TO_TRAIT: source:TypeId, target:TypeId; requires validated Registry metadata.
RefToTrait = 0x95,
/// REF_CAST: source:TypeId, target:TypeId; requires validated Registry metadata.
RefCast = 0x96,
}
impl TryFrom<u16> for OpCode {
@@ -259,6 +275,14 @@ impl TryFrom<u16> for OpCode {
0x71 => Ok(OpCode::Hostcall),
0x72 => Ok(OpCode::Intrinsic),
0x80 => Ok(OpCode::FrameSync),
0x90 => Ok(OpCode::DynPack),
0x91 => Ok(OpCode::DynUnpack),
0x92 => Ok(OpCode::DynCanUnpack),
0x93 => Ok(OpCode::RefIsExact),
0x94 => Ok(OpCode::RefImplements),
0x95 => Ok(OpCode::RefToTrait),
0x96 => Ok(OpCode::RefCast),
_ => Err(format!("Invalid OpCode: 0x{:04X}", value)),
}
}
@@ -319,6 +343,13 @@ impl OpCode {
OpCode::Hostcall => 1,
OpCode::Intrinsic => 1,
OpCode::FrameSync => 1,
OpCode::DynPack => 8,
OpCode::DynUnpack => 4,
OpCode::DynCanUnpack => 3,
OpCode::RefIsExact => 4,
OpCode::RefImplements => 4,
OpCode::RefToTrait => 5,
OpCode::RefCast => 4,
}
}
}
@@ -5,18 +5,24 @@ use crate::opcode::OpCode;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OpcodeSpec {
pub name: &'static str,
pub imm_bytes: u8, // immediate payload size (decode)
pub pops: u16, // slots popped
pub pushes: u16, // slots pushed
pub is_branch: bool, // has a control-flow target
pub imm_bytes: u8, // immediate payload size (decode)
/// None requires Registry resolution; it never means zero slots.
pub pops: Option<u16>, // slots popped
/// None requires Registry resolution; it never means zero slots.
pub pushes: Option<u16>, // slots pushed
pub is_branch: bool, // has a control-flow target
pub is_terminator: bool, // ends basic block: JMP/RET/TRAP/HALT
pub may_trap: bool, // runtime trap possible
pub may_trap: bool, // runtime trap possible
/// Marks this opcode as a VM safepoint. Used by GC/scheduler policies.
pub is_safepoint: bool,
}
pub trait OpCodeSpecExt {
fn spec(&self) -> OpcodeSpec;
/// These instructions cannot be verified from slot-only FunctionMeta.
fn requires_registry(&self) -> bool {
self.spec().pops.is_none() || self.spec().pushes.is_none()
}
}
impl OpCodeSpecExt for OpCode {
@@ -25,8 +31,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Nop => OpcodeSpec {
name: "NOP",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -35,8 +41,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Halt => OpcodeSpec {
name: "HALT",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: true,
may_trap: false,
@@ -45,8 +51,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Jmp => OpcodeSpec {
name: "JMP",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: true,
is_terminator: true,
may_trap: false,
@@ -55,8 +61,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::JmpIfFalse => OpcodeSpec {
name: "JMP_IF_FALSE",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: true,
is_terminator: false,
may_trap: true,
@@ -65,8 +71,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::JmpIfTrue => OpcodeSpec {
name: "JMP_IF_TRUE",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: true,
is_terminator: false,
may_trap: true,
@@ -75,8 +81,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Trap => OpcodeSpec {
name: "TRAP",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: true,
may_trap: true,
@@ -85,8 +91,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushConst => OpcodeSpec {
name: "PUSH_CONST",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -95,8 +101,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Pop => OpcodeSpec {
name: "POP",
imm_bytes: 0,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -105,8 +111,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PopN => OpcodeSpec {
name: "POP_N",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -115,8 +121,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Dup => OpcodeSpec {
name: "DUP",
imm_bytes: 0,
pops: 1,
pushes: 2,
pops: Some(1),
pushes: Some(2),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -125,8 +131,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Swap => OpcodeSpec {
name: "SWAP",
imm_bytes: 0,
pops: 2,
pushes: 2,
pops: Some(2),
pushes: Some(2),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -135,8 +141,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushI64 => OpcodeSpec {
name: "PUSH_I64",
imm_bytes: 8,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -145,8 +151,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushF64 => OpcodeSpec {
name: "PUSH_F64",
imm_bytes: 8,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -155,8 +161,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushBool => OpcodeSpec {
name: "PUSH_BOOL",
imm_bytes: 1,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -165,8 +171,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushI32 => OpcodeSpec {
name: "PUSH_I32",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -175,8 +181,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Add => OpcodeSpec {
name: "ADD",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -185,8 +191,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Sub => OpcodeSpec {
name: "SUB",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -195,8 +201,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Mul => OpcodeSpec {
name: "MUL",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -205,8 +211,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Div => OpcodeSpec {
name: "DIV",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -215,8 +221,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Mod => OpcodeSpec {
name: "MOD",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -225,8 +231,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Eq => OpcodeSpec {
name: "EQ",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -235,8 +241,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Neq => OpcodeSpec {
name: "NEQ",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -245,8 +251,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Lt => OpcodeSpec {
name: "LT",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -255,8 +261,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Gt => OpcodeSpec {
name: "GT",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -265,8 +271,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::And => OpcodeSpec {
name: "AND",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -275,8 +281,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Or => OpcodeSpec {
name: "OR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -285,8 +291,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Not => OpcodeSpec {
name: "NOT",
imm_bytes: 0,
pops: 1,
pushes: 1,
pops: Some(1),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -295,8 +301,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitAnd => OpcodeSpec {
name: "BIT_AND",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -305,8 +311,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitOr => OpcodeSpec {
name: "BIT_OR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -315,8 +321,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitXor => OpcodeSpec {
name: "BIT_XOR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -325,8 +331,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Shl => OpcodeSpec {
name: "SHL",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -335,8 +341,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Shr => OpcodeSpec {
name: "SHR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -345,8 +351,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Lte => OpcodeSpec {
name: "LTE",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -355,8 +361,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Gte => OpcodeSpec {
name: "GTE",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -365,8 +371,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Neg => OpcodeSpec {
name: "NEG",
imm_bytes: 0,
pops: 1,
pushes: 1,
pops: Some(1),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -375,8 +381,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::GetGlobal => OpcodeSpec {
name: "GET_GLOBAL",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -385,8 +391,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::SetGlobal => OpcodeSpec {
name: "SET_GLOBAL",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -395,8 +401,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::GetLocal => OpcodeSpec {
name: "GET_LOCAL",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -405,8 +411,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::SetLocal => OpcodeSpec {
name: "SET_LOCAL",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -415,8 +421,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Call => OpcodeSpec {
name: "CALL",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -425,8 +431,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Ret => OpcodeSpec {
name: "RET",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: true,
may_trap: false,
@@ -437,8 +443,8 @@ impl OpCodeSpecExt for OpCode {
// Two u32 immediates: fn_id and capture_count
imm_bytes: 8,
// Dynamic, depends on capture_count; keep 0 here for verifier-free spec
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -449,8 +455,8 @@ impl OpCodeSpecExt for OpCode {
// One u32 immediate: arg_count (user args, excludes hidden arg0)
imm_bytes: 4,
// Dynamic: pops closure_ref + arg_count; keep 0 in spec layer
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -461,8 +467,8 @@ impl OpCodeSpecExt for OpCode {
// Two u32 immediates: fn_id and arg_count
imm_bytes: 8,
// Dynamic pops depends on arg_count; keep 0 here in spec layer
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -471,8 +477,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Yield => OpcodeSpec {
name: "YIELD",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
// Not a block terminator; effect realized at safepoint
is_terminator: false,
@@ -484,8 +490,8 @@ impl OpCodeSpecExt for OpCode {
name: "SLEEP",
// One u32 immediate: duration_ticks
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
// Ends execution at safepoint after instruction completes
is_terminator: false,
@@ -496,8 +502,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Hostcall => OpcodeSpec {
name: "HOSTCALL",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -506,8 +512,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Syscall => OpcodeSpec {
name: "SYSCALL",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -516,8 +522,78 @@ impl OpCodeSpecExt for OpCode {
OpCode::Intrinsic => OpcodeSpec {
name: "INTRINSIC",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::DynPack => OpcodeSpec {
name: "DYN_PACK",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::DynUnpack => OpcodeSpec {
name: "DYN_UNPACK",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::DynCanUnpack => OpcodeSpec {
name: "DYN_CAN_UNPACK",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefIsExact => OpcodeSpec {
name: "REF_IS_EXACT",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefImplements => OpcodeSpec {
name: "REF_IMPLEMENTS",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefToTrait => OpcodeSpec {
name: "REF_TO_TRAIT",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefCast => OpcodeSpec {
name: "REF_CAST",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -526,8 +602,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::FrameSync => OpcodeSpec {
name: "FRAME_SYNC",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -17,7 +17,7 @@ pub struct ProgramImage {
pub rom: Arc<[u8]>,
pub constant_pool: Arc<[Value]>,
pub functions: Arc<[FunctionMeta]>,
pub debug_info: Option<DebugInfo>,
pub debug_info: Option<Arc<DebugInfo>>,
pub exports: Arc<HashMap<String, u32>>,
}
@@ -33,7 +33,7 @@ impl ProgramImage {
rom: Arc::from(rom),
constant_pool: Arc::from(constant_pool),
functions: Arc::from(functions),
debug_info,
debug_info: debug_info.map(Arc::new),
exports: Arc::new(exports),
}
}
@@ -116,7 +116,7 @@ impl From<ProgramImage> for BytecodeModule {
const_pool,
functions: program.functions.as_ref().to_vec(),
code: program.rom.as_ref().to_vec(),
debug_info: program.debug_info.clone(),
debug_info: program.debug_info.as_deref().cloned(),
exports,
syscalls: Vec::new(),
}
@@ -0,0 +1,607 @@
//! Typed PBX declarations and bounded immutable Registry resolution.
//! These declarations do not authorize execution: code and bindings still require verification.
use crate::load_limits::IdDomain;
use crate::load_limits::{
LoadBudget, LoadCode as C, LoadFailure as E, LoadReason as R, LoadResource as Q,
};
use crate::Value;
use std::sync::Arc;
macro_rules! id {
($name:ident) => {
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct $name(pub u32);
};
}
id!(TypeId);
id!(FunctionId);
id!(ImplementationId);
id!(BuiltinId);
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NamedType {
pub type_id: TypeId,
pub name: Option<String>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Signature {
pub parameters: Vec<NamedType>,
pub results: Vec<TypeId>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MethodDecl {
pub name: Option<String>,
pub signature: Signature,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TypeKind {
Builtin(BuiltinId),
Struct(Vec<NamedType>),
Array(TypeId),
Trait(Vec<MethodDecl>),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TypeDecl {
pub name: Option<String>,
pub kind: TypeKind,
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FunctionDecl {
pub name: Option<String>,
pub signature: Signature,
pub code_offset: u32,
pub code_len: u32,
pub local_slots: u32,
pub max_stack_slots: u32,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImplementationDecl {
pub owner: TypeId,
pub trait_id: TypeId,
pub methods: Vec<FunctionId>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct RegistryDeclarations {
pub types: Vec<TypeDecl>,
pub functions: Vec<FunctionDecl>,
pub implementations: Vec<ImplementationDecl>,
}
pub type StringSlot = Option<Arc<str>>;
#[derive(Debug, Clone)]
pub struct DynamicSlot {
pub type_id: Option<TypeId>,
pub payload: Value,
}
impl Default for DynamicSlot {
fn default() -> Self {
Self { type_id: None, payload: Value::Null }
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DefaultKind {
Int32,
Int64,
Float,
Bool,
Null,
Vec2,
Pixel,
Trait,
Dynamic,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Ownership {
Plain,
GuestReference,
NativeString,
TraitReceiver,
Dynamic,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StorageLayout {
pub size: usize,
pub alignment: usize,
pub slots: u32,
pub ownership: Ownership,
pub default: DefaultKind,
}
impl StorageLayout {
fn new(
size: usize,
alignment: usize,
slots: u32,
ownership: Ownership,
default: DefaultKind,
) -> Self {
Self { size, alignment, slots, ownership, default }
}
pub fn nullable(self) -> bool {
!matches!(self.ownership, Ownership::Plain)
}
/// Canonical stack-side defaults, with no allocation or source constructor.
/// Native typed storage still requires its own initialized-slot construction.
pub fn default_values(self) -> &'static [Value] {
match self.default {
DefaultKind::Int32 => &[Value::Int32(0)],
DefaultKind::Int64 => &[Value::Int64(0)],
DefaultKind::Float => &[Value::Float(0.0)],
DefaultKind::Bool => &[Value::Boolean(false)],
DefaultKind::Null => &[Value::Null],
DefaultKind::Vec2 => &[Value::Float(0.0), Value::Float(0.0)],
DefaultKind::Pixel => &[Value::Int64(0), Value::Int64(0), Value::Int64(0)],
DefaultKind::Trait | DefaultKind::Dynamic => &[Value::Null, Value::Null],
}
}
}
impl BuiltinId {
pub const COLOR: Self = Self(1);
pub const VEC2: Self = Self(2);
pub const PIXEL: Self = Self(3);
pub const INT32: Self = Self(0x10);
pub const INT64: Self = Self(0x11);
pub const FLOAT: Self = Self(0x12);
pub const BOOL: Self = Self(0x13);
pub const STRING: Self = Self(0x14);
pub const DYNAMIC: Self = Self(0x15);
pub fn layout(self) -> Result<StorageLayout, E> {
use DefaultKind as D;
use Ownership as O;
let (size, alignment, slots, ownership, default) = match self {
Self::COLOR => (4, 4, 1, O::Plain, D::Int64),
Self::VEC2 => (16, 8, 2, O::Plain, D::Vec2),
Self::PIXEL => (24, 8, 3, O::Plain, D::Pixel),
Self::INT32 => (4, 4, 1, O::Plain, D::Int32),
Self::INT64 => (8, 8, 1, O::Plain, D::Int64),
Self::FLOAT => (8, 8, 1, O::Plain, D::Float),
Self::BOOL => (1, 1, 1, O::Plain, D::Bool),
Self::STRING => {
(size_of::<StringSlot>(), align_of::<StringSlot>(), 1, O::NativeString, D::Null)
}
Self::DYNAMIC => {
(size_of::<DynamicSlot>(), align_of::<DynamicSlot>(), 2, O::Dynamic, D::Dynamic)
}
_ => return Err(E::new(C::UnsupportedFormat, R::Builtin)),
};
Ok(StorageLayout::new(size, alignment, slots, ownership, default))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FieldLayout {
pub type_id: TypeId,
pub offset: usize,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OwnedField {
pub offset: usize,
pub ownership: Ownership,
}
#[derive(Debug, PartialEq, Eq)]
pub struct StructLayout {
pub size: usize,
pub alignment: usize,
pub fields: Vec<FieldLayout>,
/// Sorted offsets for fields requiring guest tracing or native ownership handling.
pub owned_fields: Vec<OwnedField>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ArrayLayout {
pub element_type_id: TypeId,
pub stride: usize,
pub element_alignment: usize,
}
#[derive(Debug, PartialEq, Eq)]
pub struct TypeLayout {
pub storage: StorageLayout,
pub instance: Option<StructLayout>,
pub array: Option<ArrayLayout>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FunctionLayout {
pub parameter_slots: u32,
pub result_slots: u32,
}
#[derive(Debug)]
pub struct Registry {
declarations: RegistryDeclarations,
layouts: Vec<TypeLayout>,
functions: Vec<FunctionLayout>,
// Sorted by owner/trait; original implementation IDs are never remapped.
implementations: Vec<(TypeId, TypeId, ImplementationId)>,
}
impl Registry {
pub fn declarations(&self) -> &RegistryDeclarations {
&self.declarations
}
pub fn type_layout(&self, id: TypeId) -> Option<&TypeLayout> {
self.layouts.get(id.0 as usize)
}
pub fn function_layout(&self, id: FunctionId) -> Option<&FunctionLayout> {
self.functions.get(id.0 as usize)
}
pub fn implementation(&self, owner: TypeId, trait_id: TypeId) -> Option<ImplementationId> {
self.implementations
.binary_search_by_key(&(owner, trait_id), |&(a, b, _)| (a, b))
.ok()
.map(|i| self.implementations[i].2)
}
/// Resolves declarations, not code/bindings. The caller must still verify before publication.
/// Declaration allocations are retained and charged here, even for non-PBX producers.
pub fn resolve(
declarations: RegistryDeclarations,
code_len: usize,
budget: &mut LoadBudget,
) -> Result<Self, E> {
budget.transaction(|budget| Self::resolve_inner(declarations, code_len, budget))
}
fn resolve_inner(
d: RegistryDeclarations,
code_len: usize,
b: &mut LoadBudget,
) -> Result<Self, E> {
b.check(Q::Types, d.types.len() as u64)?;
b.check(Q::Functions, d.functions.len() as u64)?;
b.check(Q::Implementations, d.implementations.len() as u64)?;
b.check(Q::CodeBytes, code_len as u64)?;
charge_declarations(&d, b)?;
validate_declarations(&d, b)?;
let mut layouts = b.vector(d.types.len(), Q::RegistryBytes)?;
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
let storage = match t.kind {
TypeKind::Builtin(id) => id.layout().map_err(|e| e.record(i as u32))?,
TypeKind::Trait(_) => {
StorageLayout::new(16, 8, 2, Ownership::TraitReceiver, DefaultKind::Trait)
}
_ => StorageLayout::new(8, 8, 1, Ownership::GuestReference, DefaultKind::Null),
};
layouts.push(TypeLayout { storage, instance: None, array: None });
}
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
if let TypeKind::Array(element_type_id) = t.kind {
let element = layouts[element_type_id.0 as usize].storage;
layouts[i].array = Some(ArrayLayout {
element_type_id,
stride: align(element.size, element.alignment)?,
element_alignment: element.alignment,
});
}
if let TypeKind::Struct(fields) = &t.kind {
let mut offsets = b.vector(fields.len(), Q::RegistryBytes)?;
b.work(fields.len())?;
let owned_count = fields
.iter()
.filter(|f| layouts[f.type_id.0 as usize].storage.ownership != Ownership::Plain)
.count();
let mut owned = b.vector(owned_count, Q::RegistryBytes)?;
let (mut size, mut alignment) = (0, 1);
for field in fields {
b.work(1)?;
let layout = layouts[field.type_id.0 as usize].storage;
size = align(size, layout.alignment)?;
offsets.push(FieldLayout { type_id: field.type_id, offset: size });
if layout.ownership != Ownership::Plain {
owned.push(OwnedField { offset: size, ownership: layout.ownership });
}
size = size.checked_add(layout.size).ok_or_else(overflow)?;
alignment = alignment.max(layout.alignment);
}
layouts[i].instance = Some(StructLayout {
size: align(size, alignment)?,
alignment,
fields: offsets,
owned_fields: owned,
});
}
}
let mut functions = b.vector(d.functions.len(), Q::RegistryBytes)?;
let mut ranges = b.vector(d.functions.len(), Q::TemporaryBytes)?;
for (i, f) in d.functions.iter().enumerate() {
b.work(1)?;
let params = width(f.signature.parameters.iter().map(|p| p.type_id), &layouts, b)?;
let results = width(f.signature.results.iter().copied(), &layouts, b)?;
let frame = u64::from(params) + u64::from(f.local_slots) + u64::from(f.max_stack_slots);
if frame > b.frame_limit() {
return Err(E::new(C::InvalidCode, R::FrameSlots)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
if u64::from(results) > b.result_limit() {
return Err(E::new(C::InvalidCode, R::ReturnSlots)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
let end = f.code_offset.checked_add(f.code_len).ok_or_else(|| {
E::new(C::InvalidCode, R::CodeRange)
.in_section(1)
.record(i as u32)
.in_function(i as u32, Some(f.code_offset))
})?;
if end as usize > code_len || f.code_len == 0 {
return Err(E::new(C::InvalidCode, R::CodeRange)
.in_section(1)
.record(i as u32)
.in_function(i as u32, Some(f.code_offset)));
}
ranges.push((f.code_offset, end, i as u32));
functions.push(FunctionLayout { parameter_slots: params, result_slots: results });
}
sort_work(ranges.len(), b)?;
ranges.sort_unstable();
for pair in ranges.windows(2) {
b.work(1)?;
if pair[0].1 > pair[1].0 {
return Err(E::new(C::InvalidCode, R::CodeRange).record(pair[1].2));
}
}
b.refund(Q::TemporaryBytes, (ranges.capacity() * size_of::<(u32, u32, u32)>()) as u64);
drop(ranges);
let mut implementations = b.vector(d.implementations.len(), Q::RegistryBytes)?;
for (i, imp) in d.implementations.iter().enumerate() {
b.work(1)?;
if !matches!(d.types[imp.owner.0 as usize].kind, TypeKind::Struct(_)) {
return Err(E::new(C::InvalidReference, R::OwnerCategory)
.in_section(7)
.record(i as u32)
.reference(IdDomain::Type, imp.owner.0));
}
let TypeKind::Trait(methods) = &d.types[imp.trait_id.0 as usize].kind else {
return Err(E::new(C::InvalidReference, R::TraitCategory)
.in_section(7)
.record(i as u32)
.reference(IdDomain::Type, imp.trait_id.0));
};
if methods.len() != imp.methods.len() {
return Err(E::new(C::InvalidRegistry, R::MethodCount)
.in_section(7)
.record(i as u32));
}
for (j, (method, id)) in methods.iter().zip(&imp.methods).enumerate() {
let signature = &d.functions[id.0 as usize].signature;
b.work(signature.parameters.len() + signature.results.len() + 1)?;
if signature.parameters.first().map(|p| p.type_id) != Some(imp.owner)
|| signature.parameters.len() != method.signature.parameters.len() + 1
|| !signature.parameters.iter().skip(1).map(|p| p.type_id).eq(method
.signature
.parameters
.iter()
.map(|p| p.type_id))
|| signature.results != method.signature.results
{
return Err(E::new(C::InvalidRegistry, R::Signature)
.in_section(7)
.record(i as u32)
.member(j as u32));
}
}
implementations.push((imp.owner, imp.trait_id, ImplementationId(i as u32)));
}
sort_work(implementations.len(), b)?;
implementations.sort_unstable();
for pair in implementations.windows(2) {
b.work(1)?;
if (pair[0].0, pair[0].1) == (pair[1].0, pair[1].1) {
return Err(E::new(C::InvalidRegistry, R::DuplicateImplementation)
.in_section(7)
.record(pair[1].2 .0));
}
}
Ok(Self { declarations: d, layouts, functions, implementations })
}
}
fn overflow() -> E {
E::new(C::ResourceLimit, R::Overflow)
}
fn align(n: usize, a: usize) -> Result<usize, E> {
n.checked_add(a - 1).map(|v| v & !(a - 1)).ok_or_else(overflow)
}
fn width(
ids: impl Iterator<Item = TypeId>,
layouts: &[TypeLayout],
b: &mut LoadBudget,
) -> Result<u32, E> {
let mut sum = 0u32;
for id in ids {
b.work(1)?;
sum = sum.checked_add(layouts[id.0 as usize].storage.slots).ok_or_else(overflow)?;
}
Ok(sum)
}
fn sort_work(n: usize, b: &mut LoadBudget) -> Result<(), E> {
let bits = usize::BITS - n.leading_zeros();
b.work(n.checked_mul(bits as usize + 1).ok_or_else(overflow)?)
}
fn type_ref(id: TypeId, d: &RegistryDeclarations) -> Result<(), E> {
if (id.0 as usize) < d.types.len() {
Ok(())
} else {
Err(E::new(C::InvalidReference, R::TypeId).reference(IdDomain::Type, id.0))
}
}
fn name(name: &Option<String>, b: &mut LoadBudget) -> Result<(), E> {
if let Some(name) = name {
if name.len() as u64 > b.individual_name_limit() {
return Err(E::resource(Q::NameBytes, name.len() as u64, b.individual_name_limit()));
}
b.charge(Q::NameBytes, name.len() as u64)?;
b.work(name.len())?;
}
Ok(())
}
fn named(items: &[NamedType], d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::NestedRecords, items.len() as u64)?;
for (i, item) in items.iter().enumerate() {
b.work(1)?;
type_ref(item.type_id, d).map_err(|e| e.member(i as u32))?;
name(&item.name, b)?;
}
Ok(())
}
fn signature(s: &Signature, d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
named(&s.parameters, d, b)?;
b.charge(Q::NestedRecords, s.results.len() as u64)?;
for (i, id) in s.results.iter().enumerate() {
b.work(1)?;
type_ref(*id, d).map_err(|e| e.member(i as u32))?;
}
Ok(())
}
/// Validate all edges before indexed layout resolution; IDs remain table positions.
pub(crate) fn validate_declarations(d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::Types, d.types.len() as u64)?;
b.charge(Q::Functions, d.functions.len() as u64)?;
b.charge(Q::Implementations, d.implementations.len() as u64)?;
let mut constructors = b.vector(d.types.len(), Q::TemporaryBytes)?;
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
name(&t.name, b).map_err(|e| e.in_section(6).record(i as u32))?;
let result = (|| match &t.kind {
TypeKind::Builtin(id) => {
id.layout()?;
constructors.push((0, id.0, i as u32));
Ok(())
}
TypeKind::Array(id) => {
type_ref(*id, d)?;
constructors.push((1, id.0, i as u32));
Ok(())
}
TypeKind::Struct(fields) => named(fields, d, b),
TypeKind::Trait(methods) => {
b.charge(Q::NestedRecords, methods.len() as u64)?;
for m in methods {
b.work(1)?;
name(&m.name, b)?;
signature(&m.signature, d, b)?;
}
Ok(())
}
})();
result.map_err(|e| e.in_section(6).record(i as u32))?;
}
sort_work(constructors.len(), b)?;
constructors.sort_unstable();
for pair in constructors.windows(2) {
b.work(1)?;
if (pair[0].0, pair[0].1) == (pair[1].0, pair[1].1) {
return Err(E::new(
C::InvalidRegistry,
if pair[1].0 == 0 { R::DuplicateBuiltin } else { R::DuplicateArray },
)
.record(pair[1].2));
}
}
b.refund(Q::TemporaryBytes, (constructors.capacity() * size_of::<(i32, u32, u32)>()) as u64);
drop(constructors);
// Iterative tri-color walk: every Array has one successor; nominal nodes terminate walks.
let mut colors = b.vector::<u8>(d.types.len(), Q::TemporaryBytes)?;
colors.resize(d.types.len(), 0);
for start in 0..d.types.len() {
b.work(1)?;
let mut node = start;
while colors[node] == 0 {
b.work(1)?;
colors[node] = 1;
match d.types[node].kind {
TypeKind::Array(id) => node = id.0 as usize,
_ => break,
}
}
if colors[node] == 1 && matches!(d.types[node].kind, TypeKind::Array(_)) {
return Err(E::new(C::InvalidRegistry, R::ArrayCycle).record(node as u32));
}
node = start;
while colors[node] == 1 {
b.work(1)?;
colors[node] = 2;
match d.types[node].kind {
TypeKind::Array(id) => node = id.0 as usize,
_ => break,
}
}
}
b.refund(Q::TemporaryBytes, colors.capacity() as u64);
drop(colors);
for (i, f) in d.functions.iter().enumerate() {
b.work(1)?;
name(&f.name, b).map_err(|e| e.in_section(1).record(i as u32))?;
signature(&f.signature, d, b).map_err(|e| e.in_section(1).record(i as u32))?;
}
for (i, imp) in d.implementations.iter().enumerate() {
b.work(1)?;
type_ref(imp.owner, d).map_err(|e| e.in_section(7).record(i as u32))?;
type_ref(imp.trait_id, d).map_err(|e| e.in_section(7).record(i as u32))?;
b.charge(Q::NestedRecords, imp.methods.len() as u64)?;
for (j, id) in imp.methods.iter().enumerate() {
b.work(1)?;
if id.0 as usize >= d.functions.len() {
return Err(E::new(C::InvalidReference, R::FunctionId)
.in_section(7)
.reference(IdDomain::Function, id.0)
.record(i as u32)
.member(j as u32));
}
}
}
Ok(())
}
fn charge_vec<T>(v: &Vec<T>, b: &mut LoadBudget) -> Result<(), E> {
b.charge(
Q::RegistryBytes,
(v.capacity() as u64).checked_mul(size_of::<T>() as u64).ok_or_else(overflow)?,
)
}
fn charge_name(n: &Option<String>, b: &mut LoadBudget) -> Result<(), E> {
if let Some(n) = n {
b.charge(Q::RegistryBytes, n.capacity() as u64)?;
}
Ok(())
}
fn charge_named(v: &Vec<NamedType>, b: &mut LoadBudget) -> Result<(), E> {
charge_vec(v, b)?;
for p in v {
b.work(1)?;
charge_name(&p.name, b)?;
}
Ok(())
}
fn charge_signature(s: &Signature, b: &mut LoadBudget) -> Result<(), E> {
charge_named(&s.parameters, b)?;
charge_vec(&s.results, b)
}
fn charge_declarations(d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::RegistryBytes, size_of::<Registry>() as u64)?;
charge_vec(&d.types, b)?;
charge_vec(&d.functions, b)?;
charge_vec(&d.implementations, b)?;
for t in &d.types {
b.work(1)?;
charge_name(&t.name, b)?;
match &t.kind {
TypeKind::Struct(fields) => charge_named(fields, b)?,
TypeKind::Trait(methods) => {
charge_vec(methods, b)?;
for m in methods {
b.work(1)?;
charge_name(&m.name, b)?;
charge_signature(&m.signature, b)?;
}
}
_ => {}
}
}
for f in &d.functions {
b.work(1)?;
charge_name(&f.name, b)?;
charge_signature(&f.signature, b)?;
}
for imp in &d.implementations {
b.work(1)?;
charge_vec(&imp.methods, b)?;
}
Ok(())
}
@@ -0,0 +1,475 @@
//! Strict PBX v1 envelope and Registry sections. No legacy fallback.
//! Envelope parsing is structural only: non-Registry sections and instructions
//! must be validated by their consumers before an executable image is published.
use crate::load_limits::{
LoadBudget, LoadCode as C, LoadFailure as E, LoadReason as R, LoadResource as Q,
};
use crate::registry::*;
#[derive(Debug, Clone, Copy)]
pub struct Section<'a> {
pub kind: u32,
pub offset: usize,
pub bytes: &'a [u8],
}
#[derive(Debug)]
pub struct PbxEnvelope<'a> {
sections: [Option<Section<'a>>; 8],
}
impl<'a> PbxEnvelope<'a> {
pub fn section(&self, kind: u32) -> Option<Section<'a>> {
self.sections.get(kind as usize).copied().flatten()
}
pub fn parse(bytes: &'a [u8], b: &mut LoadBudget) -> Result<Self, E> {
b.transaction(|b| Self::parse_inner(bytes, b))
}
fn parse_inner(bytes: &'a [u8], b: &mut LoadBudget) -> Result<Self, E> {
b.check(Q::PbxBytes, bytes.len() as u64)?;
if bytes.len() < 32 {
return Err(E::new(C::InvalidFormat, R::Truncated));
}
b.work(32)?;
if &bytes[..4] != b"PBX\0" {
return Err(E::new(C::InvalidFormat, R::Magic));
}
if bytes[4..6] != [1, 0] {
return Err(E::new(C::UnsupportedFormat, R::Version));
}
if bytes[6] != 0 {
return Err(E::new(C::InvalidFormat, R::Endianness));
}
if bytes[7] != 0 || bytes[12..32].iter().any(|&x| x != 0) {
return Err(E::new(C::InvalidFormat, R::Reserved));
}
let count = u32::from_le_bytes(bytes[8..12].try_into().unwrap()) as usize;
let directory_end =
count.checked_mul(12).and_then(|n| n.checked_add(32)).ok_or_else(overflow)?;
if directory_end > bytes.len() {
return Err(E::new(C::InvalidFormat, R::Truncated));
}
let mut result = Self { sections: [None; 8] };
for i in 0..count {
b.work(13)?;
let pos = 32 + i * 12;
let kind = u32::from_le_bytes(bytes[pos..pos + 4].try_into().unwrap());
if kind > 7 {
return Err(E::new(C::UnsupportedFormat, R::SectionKind).at(kind, pos));
}
if result.sections[kind as usize].is_some() {
return Err(E::new(C::InvalidFormat, R::DuplicateSection).at(kind, pos));
}
let start = u32::from_le_bytes(bytes[pos + 4..pos + 8].try_into().unwrap()) as usize;
let len = u32::from_le_bytes(bytes[pos + 8..pos + 12].try_into().unwrap()) as usize;
let end = start.checked_add(len).ok_or_else(overflow)?;
if end > bytes.len() {
return Err(E::new(C::InvalidFormat, R::Truncated).at(kind, start));
}
if start < directory_end {
return Err(E::new(C::InvalidFormat, R::Overlap).at(kind, start));
}
if kind == 2 {
b.check(Q::CodeBytes, len as u64)?;
}
for other in result.sections.iter().flatten() {
b.work(1)?;
if len > 0
&& !other.bytes.is_empty()
&& start < other.offset + other.bytes.len()
&& other.offset < end
{
return Err(E::new(C::InvalidFormat, R::Overlap).at(kind, start));
}
}
result.sections[kind as usize] =
Some(Section { kind, offset: start, bytes: &bytes[start..end] });
}
for kind in [0, 1, 2, 4, 5, 6, 7] {
if result.sections[kind].is_none() {
return Err(E::new(C::InvalidFormat, R::MissingSection).at(kind as u32, 8));
}
}
Ok(result)
}
/// Decode and resolve Registry metadata only. This is not an executable loader.
pub fn resolve_registry(&self, b: &mut LoadBudget) -> Result<Registry, E> {
b.transaction(|b| {
let resources = [
Q::TemporaryBytes,
Q::Types,
Q::Functions,
Q::Implementations,
Q::NestedRecords,
Q::NameBytes,
];
let before = resources.map(|r| b.used(r));
let types = Reader::new(self.section(6).unwrap(), b).types()?;
let functions = Reader::new(self.section(1).unwrap(), b).functions()?;
let implementations = Reader::new(self.section(7).unwrap(), b).implementations()?;
// Ownership moves from parse scratch to retained Registry. No clone or
// simultaneous second declaration allocation occurs at this boundary.
for (r, used) in resources.into_iter().zip(before) {
b.refund(r, b.used(r) - used);
}
Registry::resolve(
RegistryDeclarations { types, functions, implementations },
self.section(2).unwrap().bytes.len(),
b,
)
})
}
}
fn overflow() -> E {
E::new(C::ResourceLimit, R::Overflow)
}
struct Reader<'a, 'b> {
section: Section<'a>,
pos: usize,
budget: &'b mut LoadBudget,
}
impl<'a, 'b> Reader<'a, 'b> {
fn new(section: Section<'a>, budget: &'b mut LoadBudget) -> Self {
Self { section, pos: 0, budget }
}
fn error(&self, code: C, reason: R) -> E {
E::new(code, reason).at(self.section.kind, self.section.offset + self.pos)
}
fn take(&mut self, n: usize) -> Result<&'a [u8], E> {
let end = self.pos.checked_add(n).ok_or_else(overflow)?;
let value = self
.section
.bytes
.get(self.pos..end)
.ok_or_else(|| self.error(C::InvalidFormat, R::Truncated))?;
self.budget.work(n)?;
self.pos = end;
Ok(value)
}
fn byte(&mut self) -> Result<u8, E> {
Ok(self.take(1)?[0])
}
fn u32(&mut self) -> Result<u32, E> {
Ok(u32::from_le_bytes(self.take(4)?.try_into().unwrap()))
}
fn finish(&self) -> Result<(), E> {
if self.pos == self.section.bytes.len() {
Ok(())
} else {
Err(self.error(C::InvalidFormat, R::TrailingBytes))
}
}
fn list<T>(&mut self, resource: Q, min_bytes: usize) -> Result<(Vec<T>, usize), E> {
let count = self.u32()? as usize;
self.budget.charge(resource, count as u64)?;
let min = count.checked_mul(min_bytes).ok_or_else(overflow)?;
if min > self.section.bytes.len() - self.pos {
return Err(self.error(C::InvalidFormat, R::Truncated));
}
Ok((self.budget.vector(count, Q::TemporaryBytes)?, count))
}
fn name(&mut self) -> Result<Option<String>, E> {
match self.byte()? {
0 => Ok(None),
1 => {
let len = self.u32()? as usize;
if len as u64 > self.budget.individual_name_limit() {
return Err(E::resource(
Q::NameBytes,
len as u64,
self.budget.individual_name_limit(),
)
.at(self.section.kind, self.section.offset + self.pos));
}
self.budget.charge(Q::NameBytes, len as u64)?;
let bytes = self.take(len)?;
self.budget.work(len)?;
let value = std::str::from_utf8(bytes)
.map_err(|_| self.error(C::InvalidFormat, R::Utf8))?;
self.budget.work(len)?;
let mut storage = self.budget.vector::<u8>(len, Q::TemporaryBytes)?;
storage.extend_from_slice(value.as_bytes());
// UTF-8 was checked above; moving Vec into String performs no allocation.
Ok(Some(
String::from_utf8(storage)
.map_err(|_| self.error(C::InvalidFormat, R::Utf8))?,
))
}
_ => Err(self.error(C::InvalidFormat, R::InvalidFlag)),
}
}
fn named(&mut self) -> Result<Vec<NamedType>, E> {
let (mut out, n) = self.list(Q::NestedRecords, 5)?;
for i in 0..n {
self.budget.work(1)?;
let type_id = TypeId(self.u32()?);
let name = self.name().map_err(|e| e.member(i as u32))?;
out.push(NamedType { type_id, name });
}
Ok(out)
}
fn signature(&mut self) -> Result<Signature, E> {
let parameters = self.named()?;
let (mut results, n) = self.list(Q::NestedRecords, 4)?;
for _ in 0..n {
self.budget.work(1)?;
results.push(TypeId(self.u32()?));
}
Ok(Signature { parameters, results })
}
fn types(mut self) -> Result<Vec<TypeDecl>, E> {
let (mut out, n) = self.list(Q::Types, 6)?;
for i in 0..n {
self.budget.work(1)?;
let record = (|| {
let kind = self.byte()?;
let name = self.name()?;
let kind = match kind {
0 => TypeKind::Builtin(BuiltinId(self.u32()?)),
1 => TypeKind::Struct(self.named()?),
2 => TypeKind::Array(TypeId(self.u32()?)),
3 => {
let (mut methods, n) = self.list(Q::NestedRecords, 9)?;
for j in 0..n {
self.budget.work(1)?;
let name = self.name()?;
let signature = self.signature().map_err(|e| e.member(j as u32))?;
methods.push(MethodDecl { name, signature });
}
TypeKind::Trait(methods)
}
_ => return Err(self.error(C::UnsupportedFormat, R::Category)),
};
Ok(TypeDecl { name, kind })
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(record);
}
self.finish()?;
Ok(out)
}
fn functions(mut self) -> Result<Vec<FunctionDecl>, E> {
let (mut out, n) = self.list(Q::Functions, 25)?;
for i in 0..n {
self.budget.work(1)?;
let f = (|| {
Ok(FunctionDecl {
name: self.name()?,
signature: self.signature()?,
code_offset: self.u32()?,
code_len: self.u32()?,
local_slots: self.u32()?,
max_stack_slots: self.u32()?,
})
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(f);
}
self.finish()?;
Ok(out)
}
fn implementations(mut self) -> Result<Vec<ImplementationDecl>, E> {
let (mut out, n) = self.list(Q::Implementations, 12)?;
for i in 0..n {
self.budget.work(1)?;
let imp = (|| {
let owner = TypeId(self.u32()?);
let trait_id = TypeId(self.u32()?);
let (mut methods, n) = self.list(Q::NestedRecords, 4)?;
for _ in 0..n {
self.budget.work(1)?;
methods.push(FunctionId(self.u32()?));
}
Ok(ImplementationDecl { owner, trait_id, methods })
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(imp);
}
self.finish()?;
Ok(out)
}
}
/// Raw section input for a v1 envelope writer. Non-Registry section bytes must
/// come from their own validated writers; this API never invents defaults.
#[derive(Clone, Copy)]
pub struct SectionData<'a> {
pub kind: u32,
pub bytes: &'a [u8],
}
/// Assemble strict v1 sections. The output buffer is charged to temporary load storage.
pub fn encode_envelope(sections: &[SectionData<'_>], b: &mut LoadBudget) -> Result<Vec<u8>, E> {
b.transaction(|b| {
let mut by_kind = [None; 8];
for section in sections {
b.work(1)?;
if section.kind > 7 {
return Err(E::new(C::UnsupportedFormat, R::SectionKind));
}
if by_kind[section.kind as usize].replace(section.bytes).is_some() {
return Err(E::new(C::InvalidFormat, R::DuplicateSection));
}
}
for k in [0, 1, 2, 4, 5, 6, 7] {
if by_kind[k].is_none() {
return Err(E::new(C::InvalidFormat, R::MissingSection).at(k as u32, 8));
}
}
b.check(Q::CodeBytes, by_kind[2].unwrap().len() as u64)?;
let count = sections.len();
let directory_end = 32 + 12 * count;
let total = sections
.iter()
.try_fold(directory_end, |n, s| n.checked_add(s.bytes.len()).ok_or_else(overflow))?;
b.check(Q::PbxBytes, total as u64)?;
b.work(total)?;
let mut out = b.vector(total, Q::TemporaryBytes)?;
out.extend_from_slice(b"PBX\0");
out.extend_from_slice(&[1, 0, 0, 0]);
out.extend_from_slice(&(count as u32).to_le_bytes());
out.extend_from_slice(&[0; 20]);
let mut offset = directory_end;
for (kind, data) in by_kind.iter().enumerate() {
if let Some(data) = data {
out.extend_from_slice(&(kind as u32).to_le_bytes());
out.extend_from_slice(&(offset as u32).to_le_bytes());
out.extend_from_slice(&(data.len() as u32).to_le_bytes());
offset += data.len();
}
}
for data in by_kind.into_iter().flatten() {
out.extend_from_slice(data);
}
Ok(out)
})
}
#[derive(Debug)]
pub struct RegistrySections {
pub types: Vec<u8>,
pub functions: Vec<u8>,
pub implementations: Vec<u8>,
}
/// Field-by-field serialization of already resolved Registry declarations.
/// There is no source-language inference or unsupported-value-to-null fallback.
pub fn encode_registry(registry: &Registry, b: &mut LoadBudget) -> Result<RegistrySections, E> {
b.transaction(|b| {
let d = registry.declarations();
let types = write_section(b, |w| {
w.count(d.types.len())?;
for t in &d.types {
w.byte(match t.kind {
TypeKind::Builtin(_) => 0,
TypeKind::Struct(_) => 1,
TypeKind::Array(_) => 2,
TypeKind::Trait(_) => 3,
})?;
w.name(&t.name)?;
match &t.kind {
TypeKind::Builtin(id) => w.u32(id.0)?,
TypeKind::Struct(fields) => w.named(fields)?,
TypeKind::Array(id) => w.u32(id.0)?,
TypeKind::Trait(methods) => {
w.count(methods.len())?;
for m in methods {
w.name(&m.name)?;
w.signature(&m.signature)?;
}
}
}
}
Ok(())
})?;
let functions = write_section(b, |w| {
w.count(d.functions.len())?;
for f in &d.functions {
w.name(&f.name)?;
w.signature(&f.signature)?;
w.u32(f.code_offset)?;
w.u32(f.code_len)?;
w.u32(f.local_slots)?;
w.u32(f.max_stack_slots)?;
}
Ok(())
})?;
let implementations = write_section(b, |w| {
w.count(d.implementations.len())?;
for imp in &d.implementations {
w.u32(imp.owner.0)?;
w.u32(imp.trait_id.0)?;
w.count(imp.methods.len())?;
for id in &imp.methods {
w.u32(id.0)?;
}
}
Ok(())
})?;
Ok(RegistrySections { types, functions, implementations })
})
}
// Count first so a malicious producer cannot trigger unbounded geometric growth.
struct Writer<'a> {
out: Option<&'a mut Vec<u8>>,
len: usize,
budget: &'a mut LoadBudget,
}
impl Writer<'_> {
fn bytes(&mut self, bytes: &[u8]) -> Result<(), E> {
self.budget.work(bytes.len())?;
self.len = self.len.checked_add(bytes.len()).ok_or_else(overflow)?;
self.budget.check(Q::PbxBytes, self.len as u64)?;
if let Some(out) = self.out.as_mut() {
out.extend_from_slice(bytes);
}
Ok(())
}
fn byte(&mut self, n: u8) -> Result<(), E> {
self.bytes(&[n])
}
fn u32(&mut self, n: u32) -> Result<(), E> {
self.bytes(&n.to_le_bytes())
}
fn count(&mut self, n: usize) -> Result<(), E> {
self.u32(u32::try_from(n).map_err(|_| overflow())?)
}
fn name(&mut self, n: &Option<String>) -> Result<(), E> {
match n {
None => self.byte(0),
Some(n) => {
self.byte(1)?;
self.count(n.len())?;
self.bytes(n.as_bytes())
}
}
}
fn named(&mut self, items: &[NamedType]) -> Result<(), E> {
self.count(items.len())?;
for p in items {
self.u32(p.type_id.0)?;
self.name(&p.name)?;
}
Ok(())
}
fn signature(&mut self, s: &Signature) -> Result<(), E> {
self.named(&s.parameters)?;
self.count(s.results.len())?;
for id in &s.results {
self.u32(id.0)?;
}
Ok(())
}
}
fn write_section(
b: &mut LoadBudget,
write: impl Fn(&mut Writer<'_>) -> Result<(), E>,
) -> Result<Vec<u8>, E> {
let mut counter = Writer { out: None, len: 0, budget: b };
write(&mut counter)?;
let len = counter.len;
let mut out = b.vector(len, Q::TemporaryBytes)?;
write(&mut Writer { out: Some(&mut out), len: 0, budget: b })?;
Ok(out)
}
mod payloads;
pub use payloads::{OwnedPbx, ParsedPbx};
mod writer;
pub use writer::PbxModule;
@@ -0,0 +1,385 @@
//! Validation of unchanged non-Registry section encodings, without allocating
//! guest constants or publishing an executable image.
use super::*;
use crate::abi::SourceSpan;
use crate::load_limits::IdDomain;
use crate::model::{ConstantPoolEntry, DebugInfo, Export, SyscallDecl};
use std::cmp::Ordering;
/// Owned, bounded PBX v1 tables for the executable loader. This is not an
/// executable image: bindings and instruction/type verification are still due.
#[derive(Debug)]
pub struct OwnedPbx {
pub registry: Registry,
pub constants: Vec<ConstantPoolEntry>,
pub code: Vec<u8>,
pub debug: Option<DebugInfo>,
pub exports: Vec<Export>,
pub syscalls: Vec<SyscallDecl>,
}
impl OwnedPbx {
pub fn parse(bytes: &[u8], budget: &mut LoadBudget) -> Result<Self, E> {
budget.transaction(|budget| {
let parsed = ParsedPbx::parse(bytes, budget)?;
let constants = Reader::new(parsed.section(0).unwrap(), budget).owned_constants()?;
let exports = Reader::new(parsed.section(4).unwrap(), budget).owned_exports()?;
let syscalls = Reader::new(parsed.section(5).unwrap(), budget).owned_syscalls()?;
let debug = parsed
.section(3)
.map(|section| Reader::new(section, budget).owned_debug())
.transpose()?;
let section = parsed.section(2).unwrap();
let mut code = budget
.vector(section.bytes.len(), Q::TemporaryBytes)
.map_err(|e| e.at(2, section.offset))?;
budget.work(section.bytes.len()).map_err(|e| e.at(2, section.offset))?;
code.extend_from_slice(section.bytes);
Ok(Self { registry: parsed.registry, constants, code, debug, exports, syscalls })
})
}
}
/// All PBX tables have passed binary and reference validation. Code has NOT
/// passed instruction/type-flow verification and host calls are NOT bound.
#[derive(Debug)]
pub struct ParsedPbx<'a> {
envelope: PbxEnvelope<'a>,
registry: Registry,
}
impl<'a> ParsedPbx<'a> {
pub fn parse(bytes: &'a [u8], budget: &mut LoadBudget) -> Result<Self, E> {
budget.transaction(|budget| {
let envelope = PbxEnvelope::parse(bytes, budget)?;
let registry = envelope.resolve_registry(budget)?;
let functions = registry.declarations().functions.len();
let code_len = envelope.section(2).unwrap().bytes.len();
Reader::new(envelope.section(0).unwrap(), budget).constants()?;
Reader::new(envelope.section(4).unwrap(), budget).exports(functions)?;
Reader::new(envelope.section(5).unwrap(), budget).syscalls()?;
if let Some(debug) = envelope.section(3) {
Reader::new(debug, budget).debug(functions, code_len)?;
}
Ok(Self { envelope, registry })
})
}
pub fn registry(&self) -> &Registry {
&self.registry
}
pub fn section(&self, kind: u32) -> Option<Section<'a>> {
self.envelope.section(kind)
}
/// Re-encode validated tables in canonical directory order; debug absence is preserved.
pub fn encode(&self, budget: &mut LoadBudget) -> Result<Vec<u8>, E> {
let mut sections = [SectionData { kind: 0, bytes: &[] }; 8];
let mut count = 0;
for kind in 0..8 {
if let Some(section) = self.section(kind) {
sections[count] = SectionData { kind, bytes: section.bytes };
count += 1;
}
}
encode_envelope(&sections[..count], budget)
}
}
impl<'a> Reader<'a, '_> {
fn owned_vector<T>(&mut self, count: usize) -> Result<Vec<T>, E> {
self.budget
.vector(count, Q::TemporaryBytes)
.map_err(|e| e.at(self.section.kind, self.section.offset + self.pos))
}
fn owned_text(&mut self, len: usize) -> Result<String, E> {
let value = self.utf8(len)?;
let mut bytes = self.owned_vector(len)?;
self.budget.work(len)?;
bytes.extend_from_slice(value.as_bytes());
Ok(String::from_utf8(bytes).expect("UTF-8 checked before allocation"))
}
fn owned_constants(mut self) -> Result<Vec<ConstantPoolEntry>, E> {
let count = self.raw_count(1)?;
let mut out = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let value = (|| {
Ok(match self.byte()? {
0 => ConstantPoolEntry::Null,
1 => ConstantPoolEntry::Int64(i64::from_le_bytes(
self.take(8)?.try_into().unwrap(),
)),
2 => ConstantPoolEntry::Float64(f64::from_bits(u64::from_le_bytes(
self.take(8)?.try_into().unwrap(),
))),
3 => ConstantPoolEntry::Boolean(self.byte()? == 1),
4 => {
let len = self.u32()? as usize;
ConstantPoolEntry::String(self.owned_text(len)?)
}
5 => ConstantPoolEntry::Int32(i32::from_le_bytes(
self.take(4)?.try_into().unwrap(),
)),
_ => return Err(self.error(C::UnsupportedFormat, R::ConstantTag)),
})
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(value);
}
self.finish()?;
Ok(out)
}
fn owned_exports(mut self) -> Result<Vec<Export>, E> {
let count = self.raw_count(8)?;
let mut out = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let func_idx = self.u32()?;
let len = self.u32()? as usize;
let symbol = self.owned_text(len).map_err(|e| e.record(i as u32))?;
out.push(Export { func_idx, symbol });
}
self.finish()?;
Ok(out)
}
fn owned_syscalls(mut self) -> Result<Vec<SyscallDecl>, E> {
let count = self.raw_count(10)?;
let mut out = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let record = (|| {
let len = self.u16()? as usize;
let module = self.owned_text(len)?;
let len = self.u16()? as usize;
let name = self.owned_text(len)?;
Ok(SyscallDecl {
module,
name,
version: self.u16()?,
arg_slots: self.u16()?,
ret_slots: self.u16()?,
})
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(record);
}
self.finish()?;
Ok(out)
}
fn owned_debug(mut self) -> Result<DebugInfo, E> {
let count = self.raw_count(16)?;
let mut pc_to_span = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let value = (|| {
Ok((
self.u32()?,
SourceSpan { file_id: self.u32()?, start: self.u32()?, end: self.u32()? },
))
})()
.map_err(|e: E| e.record(i as u32))?;
pc_to_span.push(value);
}
let count = self.raw_count(8)?;
let mut function_names = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let id = self.u32()?;
let len = self.u32()? as usize;
let name = self.owned_text(len).map_err(|e| e.record(i as u32))?;
function_names.push((id, name));
}
self.finish()?;
Ok(DebugInfo { pc_to_span, function_names })
}
fn u16(&mut self) -> Result<u16, E> {
Ok(u16::from_le_bytes(self.take(2)?.try_into().unwrap()))
}
fn raw_count(&mut self, minimum: usize) -> Result<usize, E> {
let count = self.u32()? as usize;
if count.checked_mul(minimum).ok_or_else(overflow)? > self.section.bytes.len() - self.pos {
return Err(self.error(C::InvalidFormat, R::Truncated));
}
Ok(count)
}
fn utf8(&mut self, len: usize) -> Result<&'a str, E> {
let bytes = self.take(len)?;
self.budget.work(len)?;
std::str::from_utf8(bytes).map_err(|_| self.error(C::InvalidFormat, R::Utf8))
}
fn text(&mut self, len: usize) -> Result<&'a str, E> {
if len as u64 > self.budget.individual_name_limit() {
return Err(E::resource(Q::NameBytes, len as u64, self.budget.individual_name_limit())
.at(self.section.kind, self.section.offset + self.pos));
}
self.utf8(len)
}
fn function(&self, id: u32, count: usize) -> Result<(), E> {
if id as usize >= count {
Err(self.error(C::InvalidReference, R::FunctionId).reference(IdDomain::Function, id))
} else {
Ok(())
}
}
fn constants(mut self) -> Result<(), E> {
let count = self.u32()? as usize;
self.budget.charge(Q::ConstantEntries, count as u64)?;
if count > self.section.bytes.len() - self.pos {
return Err(self.error(C::InvalidFormat, R::Truncated));
}
for i in 0..count {
self.budget.work(1)?;
(|| {
match self.byte()? {
0 => {}
1 | 2 => {
self.take(8)?;
}
3 => {
if self.byte()? > 1 {
return Err(self.error(C::InvalidFormat, R::InvalidFlag));
}
}
4 => {
let len = self.u32()? as usize;
if len as u64 > self.budget.individual_string_limit() {
return Err(E::resource(
Q::ConstantStringBytes,
len as u64,
self.budget.individual_string_limit(),
)
.at(0, self.section.offset + self.pos));
}
self.budget.charge(Q::ConstantStringBytes, len as u64)?;
self.utf8(len)?;
}
5 => {
self.take(4)?;
}
_ => return Err(self.error(C::UnsupportedFormat, R::ConstantTag)),
}
Ok(())
})()
.map_err(|e: E| e.record(i as u32))?;
}
self.finish()
}
fn exports(mut self, functions: usize) -> Result<(), E> {
let count = self.raw_count(8)?;
for i in 0..count {
self.budget.work(1)?;
let id = self.u32()?;
self.function(id, functions).map_err(|e| e.record(i as u32))?;
let len = self.u32()? as usize;
self.text(len).map_err(|e| e.record(i as u32))?;
}
self.finish()
}
fn debug(mut self, functions: usize, code_len: usize) -> Result<(), E> {
let count = self.raw_count(16)?;
for i in 0..count {
self.budget.work(1)?;
let pc = self.u32()?;
self.u32()?; // source file ID, local to debug information
let start = self.u32()?;
let end = self.u32()?;
if pc as usize >= code_len || end < start {
return Err(self.error(C::InvalidFormat, R::DebugRange).record(i as u32));
}
}
let names = self.raw_count(8)?;
for i in 0..names {
self.budget.work(1)?;
let id = self.u32()?;
self.function(id, functions).map_err(|e| e.record(i as u32))?;
let len = self.u32()? as usize;
self.text(len).map_err(|e| e.record(i as u32))?;
}
self.finish()
}
pub(super) fn syscalls(mut self) -> Result<(), E> {
let count = self.raw_count(10)?;
let mut identities = self.budget.vector(count, Q::TemporaryBytes)?;
for i in 0..count {
self.budget.work(1)?;
let len = self.u16()? as usize;
let module = self.text(len).map_err(|e| e.record(i as u32))?;
let len = self.u16()? as usize;
let name = self.text(len).map_err(|e| e.record(i as u32))?;
let version = self.u16()?;
self.u16()?; // argument slots, unchanged SYSC encoding
self.u16()?; // result slots
identities.push((module, name, version, i as u32));
}
self.finish()?;
// Fallible heapsort bounds both auxiliary storage and comparison work;
// unlike sorting with an error flag it stops immediately at quota refusal.
fallible_sort(&mut identities, |a, b| {
let module = text_cmp(a.0, b.0, self.budget)?;
if module != Ordering::Equal {
return Ok(module);
}
let name = text_cmp(a.1, b.1, self.budget)?;
if name != Ordering::Equal {
return Ok(name);
}
self.budget.work(1)?;
Ok((a.2, a.3).cmp(&(b.2, b.3)))
})?;
for pair in identities.windows(2) {
self.budget.work(1)?;
if text_cmp(pair[0].0, pair[1].0, self.budget)? == Ordering::Equal
&& text_cmp(pair[0].1, pair[1].1, self.budget)? == Ordering::Equal
&& pair[0].2 == pair[1].2
{
return Err(self.error(C::InvalidFormat, R::DuplicateSyscall).record(pair[1].3));
}
}
self.budget.refund(
Q::TemporaryBytes,
(identities.capacity() * size_of::<(&str, &str, u16, u32)>()) as u64,
);
Ok(())
}
}
fn text_cmp(a: &str, b: &str, budget: &mut LoadBudget) -> Result<Ordering, E> {
for (a, b) in a.bytes().zip(b.bytes()) {
budget.work(2)?;
match a.cmp(&b) {
Ordering::Equal => {}
other => return Ok(other),
}
}
budget.work(1)?;
Ok(a.len().cmp(&b.len()))
}
fn fallible_sort<T>(
items: &mut [T],
mut cmp: impl FnMut(&T, &T) -> Result<Ordering, E>,
) -> Result<(), E> {
fn sift<T>(
items: &mut [T],
mut root: usize,
cmp: &mut impl FnMut(&T, &T) -> Result<Ordering, E>,
) -> Result<(), E> {
while let Some(child) =
root.checked_mul(2).and_then(|n| n.checked_add(1)).filter(|&i| i < items.len())
{
let mut child = child;
if child + 1 < items.len() && cmp(&items[child], &items[child + 1])? == Ordering::Less {
child += 1;
}
if cmp(&items[root], &items[child])? != Ordering::Less {
break;
}
items.swap(root, child);
root = child;
}
Ok(())
}
for root in (0..items.len() / 2).rev() {
sift(items, root, &mut cmp)?;
}
for end in (1..items.len()).rev() {
items.swap(0, end);
sift(&mut items[..end], 0, &mut cmp)?;
}
Ok(())
}
@@ -0,0 +1,195 @@
//! Producer-side serialization of a complete typed module. This writer emits
//! only v1; executable consumers still need bindings and code verification.
use super::*;
use crate::load_limits::IdDomain;
use crate::model::{ConstantPoolEntry, DebugInfo, Export, SyscallDecl};
/// Borrowed producer data with already resolved Registry declarations. There
/// is no version selector, inferred signature or generic Value-to-null path.
pub struct PbxModule<'a> {
pub registry: &'a Registry,
pub constants: &'a [ConstantPoolEntry],
pub code: &'a [u8],
pub debug: Option<&'a DebugInfo>,
pub exports: &'a [Export],
pub syscalls: &'a [SyscallDecl],
}
impl PbxModule<'_> {
/// All intermediate sections coexist with the final output and are charged
/// until dropped. On success only the returned Vec capacity remains charged.
pub fn serialize(&self, budget: &mut LoadBudget) -> Result<Vec<u8>, E> {
budget.transaction(|budget| {
let temporary_before = budget.used(Q::TemporaryBytes);
budget.check(Q::CodeBytes, self.code.len() as u64)?;
for (id, function) in self.registry.declarations().functions.iter().enumerate() {
budget.work(1)?;
if u64::from(function.code_offset) + u64::from(function.code_len)
> self.code.len() as u64
{
return Err(E::new(C::InvalidCode, R::CodeRange)
.in_section(2)
.in_function(id as u32, Some(function.code_offset)));
}
}
let registry = encode_registry(self.registry, budget)?;
let constants = write_section(budget, |w| self.write_constants(w))?;
let exports = write_section(budget, |w| self.write_exports(w))?;
let syscalls = write_section(budget, |w| self.write_syscalls(w))?;
// Reuse the bounded identity validator; do not introduce a second
// native-binding catalog or an unbounded duplicate search.
Reader::new(Section { kind: 5, offset: 0, bytes: &syscalls }, budget).syscalls()?;
let debug = self
.debug
.map(|di| write_section(budget, |w| self.write_debug(di, w)))
.transpose()?;
let mut sections = [SectionData { kind: 0, bytes: &[] }; 8];
let mut count = 0;
for (kind, bytes) in [
(0, Some(constants.as_slice())),
(1, Some(registry.functions.as_slice())),
(2, Some(self.code)),
(3, debug.as_deref()),
(4, Some(exports.as_slice())),
(5, Some(syscalls.as_slice())),
(6, Some(registry.types.as_slice())),
(7, Some(registry.implementations.as_slice())),
] {
if let Some(bytes) = bytes {
sections[count] = SectionData { kind, bytes };
count += 1;
}
}
let out = encode_envelope(&sections[..count], budget)?;
// The borrowed section array and all owned intermediate Vecs die
// before return. Preserve prior scratch plus returned output only.
let retained = out.capacity() as u64;
drop(debug);
drop(syscalls);
drop(exports);
drop(constants);
drop(registry);
budget.refund(
Q::TemporaryBytes,
budget.used(Q::TemporaryBytes) - temporary_before - retained,
);
Ok(out)
})
}
fn write_constants(&self, w: &mut Writer<'_>) -> Result<(), E> {
w.budget.check(Q::ConstantEntries, self.constants.len() as u64)?;
w.count(self.constants.len())?;
let mut string_bytes = 0u64;
for (id, entry) in self.constants.iter().enumerate() {
w.budget.work(1)?;
match entry {
ConstantPoolEntry::Null => w.byte(0)?,
ConstantPoolEntry::Int64(value) => {
w.byte(1)?;
w.bytes(&value.to_le_bytes())?;
}
ConstantPoolEntry::Float64(value) => {
w.byte(2)?;
w.bytes(&value.to_bits().to_le_bytes())?;
}
ConstantPoolEntry::Boolean(value) => {
w.byte(3)?;
w.byte(u8::from(*value))?;
}
ConstantPoolEntry::String(value) => {
if value.len() as u64 > w.budget.individual_string_limit() {
return Err(E::resource(
Q::ConstantStringBytes,
value.len() as u64,
w.budget.individual_string_limit(),
)
.in_section(0)
.record(id as u32));
}
string_bytes =
string_bytes.checked_add(value.len() as u64).ok_or_else(overflow)?;
w.budget.check(Q::ConstantStringBytes, string_bytes)?;
w.byte(4)?;
w.count(value.len())?;
w.bytes(value.as_bytes())?;
}
ConstantPoolEntry::Int32(value) => {
w.byte(5)?;
w.bytes(&value.to_le_bytes())?;
}
}
}
Ok(())
}
fn check_function(&self, id: u32) -> Result<(), E> {
if id as usize >= self.registry.declarations().functions.len() {
Err(E::new(C::InvalidReference, R::FunctionId).reference(IdDomain::Function, id))
} else {
Ok(())
}
}
fn write_exports(&self, w: &mut Writer<'_>) -> Result<(), E> {
w.count(self.exports.len())?;
for (record, export) in self.exports.iter().enumerate() {
w.budget.work(1)?;
self.check_function(export.func_idx)
.map_err(|e| e.in_section(4).record(record as u32))?;
w.u32(export.func_idx)?;
w.text(&export.symbol, 4)?;
}
Ok(())
}
fn write_syscalls(&self, w: &mut Writer<'_>) -> Result<(), E> {
w.count(self.syscalls.len())?;
for syscall in self.syscalls {
w.budget.work(1)?;
w.text(&syscall.module, 2)?;
w.text(&syscall.name, 2)?;
w.bytes(&syscall.version.to_le_bytes())?;
w.bytes(&syscall.arg_slots.to_le_bytes())?;
w.bytes(&syscall.ret_slots.to_le_bytes())?;
}
Ok(())
}
fn write_debug(&self, debug: &DebugInfo, w: &mut Writer<'_>) -> Result<(), E> {
w.count(debug.pc_to_span.len())?;
for (record, (pc, span)) in debug.pc_to_span.iter().enumerate() {
w.budget.work(1)?;
if *pc as usize >= self.code.len() || span.end < span.start {
return Err(E::new(C::InvalidFormat, R::DebugRange)
.in_section(3)
.record(record as u32));
}
w.u32(*pc)?;
w.u32(span.file_id)?;
w.u32(span.start)?;
w.u32(span.end)?;
}
w.count(debug.function_names.len())?;
for (record, (id, name)) in debug.function_names.iter().enumerate() {
w.budget.work(1)?;
self.check_function(*id).map_err(|e| e.in_section(3).record(record as u32))?;
w.u32(*id)?;
w.text(name, 4)?;
}
Ok(())
}
}
impl Writer<'_> {
fn text(&mut self, value: &str, length_bytes: usize) -> Result<(), E> {
if value.len() as u64 > self.budget.individual_name_limit() {
return Err(E::resource(
Q::NameBytes,
value.len() as u64,
self.budget.individual_name_limit(),
));
}
if length_bytes == 2 {
self.bytes(&u16::try_from(value.len()).map_err(|_| overflow())?.to_le_bytes())?;
} else {
self.count(value.len())?;
}
self.bytes(value.as_bytes())
}
}
@@ -0,0 +1,83 @@
//! Registry-aware immediate validation and slot effects for typed instructions.
use crate::decoder::DecodedInstr;
use crate::isa::core::{CoreOpCode as Op, CoreOpCodeSpecExt};
use crate::load_limits::{IdDomain, LoadCode, LoadFailure, LoadReason};
use crate::registry::{Registry, TypeId, TypeKind};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RegistryStackEffect {
pub pops: u32,
pub pushes: u32,
}
impl DecodedInstr<'_> {
/// Resolve an instruction's exact group widths and check immediate domains.
/// None means this is not a Registry instruction, not a zero stack effect.
/// This does not prove that the values on the stack satisfy the signature.
pub fn registry_stack_effect(
&self,
registry: &Registry,
) -> Result<Option<RegistryStackEffect>, LoadFailure> {
if !self.opcode.requires_registry() {
return Ok(None);
}
let malformed = || {
let mut e = LoadFailure::new(LoadCode::InvalidCode, LoadReason::Truncated);
e.pc = u32::try_from(self.pc).ok();
e
};
let type_info = |id: u32| {
let decl = registry.declarations().types.get(id as usize);
let layout = registry.type_layout(TypeId(id));
decl.zip(layout).ok_or_else(|| {
let mut e = LoadFailure::new(LoadCode::InvalidReference, LoadReason::TypeId)
.reference(IdDomain::Type, id);
e.pc = u32::try_from(self.pc).ok();
e
})
};
let bad_category = |id: u32| {
let mut e = LoadFailure::new(LoadCode::InvalidReference, LoadReason::Category)
.reference(IdDomain::Type, id);
e.pc = u32::try_from(self.pc).ok();
e
};
let (pops, pushes) = match self.opcode {
Op::DynPack | Op::DynUnpack | Op::DynCanUnpack => {
let id = self.imm_u32().map_err(|_| malformed())?;
let (_, layout) = type_info(id)?;
match self.opcode {
Op::DynPack => (layout.storage.slots, 2),
Op::DynUnpack => (2, layout.storage.slots),
_ => (2, 1),
}
}
Op::RefIsExact | Op::RefImplements | Op::RefToTrait | Op::RefCast => {
let (source, target) = self.imm_u32x2().map_err(|_| malformed())?;
let (source_decl, source_layout) = type_info(source)?;
let (target_decl, target_layout) = type_info(target)?;
if !matches!(
source_decl.kind,
TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Trait(_)
) {
return Err(bad_category(source));
}
let trait_target = matches!(self.opcode, Op::RefImplements | Op::RefToTrait);
if (trait_target && !matches!(target_decl.kind, TypeKind::Trait(_)))
|| (!trait_target
&& !matches!(target_decl.kind, TypeKind::Struct(_) | TypeKind::Array(_)))
{
return Err(bad_category(target));
}
let pushes = if matches!(self.opcode, Op::RefIsExact | Op::RefImplements) {
1
} else {
target_layout.storage.slots
};
(source_layout.storage.slots, pushes)
}
_ => unreachable!("requires_registry is defined by the typed opcode catalogue"),
};
Ok(Some(RegistryStackEffect { pops, pushes }))
}
}
+32 -26
View File
@@ -1,7 +1,6 @@
use serde::{Deserialize, Serialize};
use std::cell::Cell;
use std::cmp::Ordering;
use std::fmt::Write;
use std::sync::Arc;
thread_local! {
@@ -10,17 +9,28 @@ thread_local! {
/// Opaque handle that references an object stored in the VM heap.
///
/// This is an index-based handle. It does not imply ownership and carries
/// no lifetime information. GC/allocator integration will come in later PRs.
/// Handles belong to the heap/session that issued them. Native boundaries must
/// preserve that provenance. Generation zero is reserved; compact null is (0, 0).
#[repr(C, align(8))]
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)]
pub struct HeapRef(pub u32);
pub struct HeapRef {
pub index: u32,
pub generation: u32,
}
impl HeapRef {
pub const NULL: Self = Self { index: 0, generation: 0 };
pub const fn is_null(self) -> bool {
self.index == 0 && self.generation == 0
}
}
/// Represents any piece of data that can be stored on the VM stack or in globals.
///
/// The PVM is "dynamically typed" at the bytecode level, meaning a single
/// `Value` enum can hold different primitive types. The VM performs
/// automatic type promotion (e.g., adding an Int32 to a Float64 results
/// in a Float64) to ensure mathematical correctness.
/// This enum is a physical carrier, not a semantic type declaration. Registry
/// boundaries validate exact types and complete multi-slot groups. Arithmetic
/// instructions may have their own numeric promotion rules; those rules do not
/// authorize implicit conversions at typed storage or call boundaries.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum Value {
@@ -108,24 +118,20 @@ impl Value {
}
pub fn append_to_string(&self, out: &mut String) {
self.write_text(out).expect("writing into String is infallible");
}
/// Writes existing Value text without allocating a String, so bounded
/// callers can measure and reserve with their own fmt::Write sink.
pub fn write_text(&self, out: &mut impl std::fmt::Write) -> std::fmt::Result {
match self {
Value::Int32(i) => {
let _ = write!(out, "{}", i);
}
Value::Int64(i) => {
let _ = write!(out, "{}", i);
}
Value::Float(f) => {
let _ = write!(out, "{}", f);
}
Value::Boolean(b) => {
let _ = write!(out, "{}", b);
}
Value::String(s) => out.push_str(s),
Value::HeapRef(r) => {
let _ = write!(out, "[HeapRef {}]", r.0);
}
Value::Null => out.push_str("null"),
Value::Int32(i) => write!(out, "{}", i),
Value::Int64(i) => write!(out, "{}", i),
Value::Float(f) => write!(out, "{}", f),
Value::Boolean(b) => write!(out, "{}", b),
Value::String(s) => out.write_str(s),
Value::HeapRef(r) => write!(out, "[HeapRef {}:{}]", r.index, r.generation),
Value::Null => out.write_str("null"),
}
}
@@ -138,7 +144,7 @@ impl Value {
Value::Int32(i) => i.to_string().len(),
Value::Int64(i) => i.to_string().len(),
Value::Float(f) => f.to_string().len(),
Value::HeapRef(r) => 11 + r.0.to_string().len(),
Value::HeapRef(r) => 11 + r.index.to_string().len() + r.generation.to_string().len(),
}
}
@@ -0,0 +1,128 @@
use prometeu_bytecode::isa::core::{CoreOpCode as Op, CoreOpCodeSpecExt};
use prometeu_bytecode::load_limits::{LoadBudget, LoadCode, LoadLimits, LoadReason};
use prometeu_bytecode::registry::*;
use prometeu_bytecode::{assemble, decode_next, disassemble, DecodeError, RegistryStackEffect};
fn registry() -> Registry {
let types = vec![
TypeKind::Builtin(BuiltinId::INT32),
TypeKind::Builtin(BuiltinId::VEC2),
TypeKind::Builtin(BuiltinId::PIXEL),
TypeKind::Builtin(BuiltinId::DYNAMIC),
TypeKind::Struct(vec![]),
TypeKind::Array(TypeId(0)),
TypeKind::Trait(vec![]),
]
.into_iter()
.map(|kind| TypeDecl { name: None, kind })
.collect();
Registry::resolve(
RegistryDeclarations { types, ..Default::default() },
0,
&mut LoadBudget::new(LoadLimits::default()),
)
.unwrap()
}
#[test]
fn all_typed_instructions_match_independent_bytes_and_costs() {
let cases: &[(&str, &[u8], u64)] = &[
("DYN_PACK 16909060", &[0x90, 0, 4, 3, 2, 1], 8),
("DYN_UNPACK 16909060", &[0x91, 0, 4, 3, 2, 1], 4),
("DYN_CAN_UNPACK 16909060", &[0x92, 0, 4, 3, 2, 1], 3),
("REF_IS_EXACT source=16909060, target=84281096", &[0x93, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
("REF_IMPLEMENTS source=16909060, target=84281096", &[0x94, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
("REF_TO_TRAIT source=16909060, target=84281096", &[0x95, 0, 4, 3, 2, 1, 8, 7, 6, 5], 5),
("REF_CAST source=16909060, target=84281096", &[0x96, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
];
for &(text, bytes, cycles) in cases {
assert_eq!(assemble(text).unwrap(), bytes);
assert_eq!(disassemble(bytes).unwrap(), text);
let decoded = decode_next(0, bytes).unwrap();
assert_eq!(decoded.next_pc, bytes.len());
assert_eq!(decoded.opcode.cycles(), cycles);
assert_eq!(decoded.opcode.spec().pops, None);
assert_eq!(decoded.opcode.spec().pushes, None);
assert!(decoded.opcode.requires_registry());
for n in 0..bytes.len() {
assert!(decode_next(0, &bytes[..n]).is_err(), "{text}, prefix {n}");
}
}
assert!(matches!(
decode_next(0, &[0x97, 0]),
Err(DecodeError::UnknownOpcode { opcode: 0x97, .. })
));
}
#[test]
fn slot_effects_resolve_semantic_widths_and_reference_categories() {
let registry = registry();
for (text, pops, pushes) in [
("DYN_PACK 0", 1, 2),
("DYN_PACK 1", 2, 2),
("DYN_PACK 2", 3, 2),
("DYN_PACK 3", 2, 2),
("DYN_UNPACK 2", 2, 3),
("DYN_CAN_UNPACK 2", 2, 1),
("REF_IS_EXACT source=6, target=4", 2, 1),
("REF_IMPLEMENTS source=5, target=6", 1, 1),
("REF_TO_TRAIT source=4, target=6", 1, 2),
("REF_TO_TRAIT source=6, target=6", 2, 2),
("REF_CAST source=6, target=4", 2, 1),
] {
let bytes = assemble(text).unwrap();
assert_eq!(
decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap(),
Some(RegistryStackEffect { pops, pushes }),
"{text}"
);
}
assert_eq!(decode_next(0, &[0, 0]).unwrap().registry_stack_effect(&registry).unwrap(), None);
}
#[test]
fn invalid_type_immediates_are_contextual_load_errors() {
let registry = registry();
for text in ["DYN_PACK 7", "DYN_UNPACK 4294967295", "REF_CAST source=7, target=4"] {
let bytes = assemble(text).unwrap();
let e = decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap_err();
assert_eq!(
(e.code, e.reason, e.pc),
(LoadCode::InvalidReference, LoadReason::TypeId, Some(0))
);
}
for text in [
"REF_CAST source=3, target=4",
"REF_IS_EXACT source=4, target=6",
"REF_TO_TRAIT source=4, target=0",
"REF_IMPLEMENTS source=0, target=6",
] {
let bytes = assemble(text).unwrap();
let e = decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap_err();
assert_eq!(
(e.code, e.reason),
(LoadCode::InvalidReference, LoadReason::Category),
"{text}"
);
}
}
#[test]
fn assembler_rejects_missing_overflowing_or_ambiguous_type_ids() {
for text in [
"DYN_PACK",
"DYN_PACK -1",
"DYN_PACK 4294967296",
"DYN_PACK 1 2",
"REF_CAST source=4",
"REF_CAST source=4, target=5, target=6",
"REF_CAST source=4, trait=6",
] {
assert!(assemble(text).is_err(), "{text}");
}
}
#[test]
fn decoder_extreme_pc_does_not_overflow() {
assert!(matches!(
decode_next(usize::MAX, &[]),
Err(DecodeError::TruncatedOpcode { pc: usize::MAX })
));
assert_eq!(Op::DynPack as u16, 0x0090);
}
@@ -0,0 +1,886 @@
use prometeu_bytecode::load_limits::{
LoadBudget, LoadCode, LoadFailure, LoadLimits, LoadReason, LoadResource,
};
use prometeu_bytecode::registry::*;
use prometeu_bytecode::registry_codec::*;
fn budget() -> LoadBudget {
LoadBudget::new(LoadLimits::default())
}
fn named(id: u32) -> NamedType {
NamedType { type_id: TypeId(id), name: None }
}
fn builtin(id: BuiltinId) -> TypeDecl {
TypeDecl { name: None, kind: TypeKind::Builtin(id) }
}
fn resolve(d: RegistryDeclarations) -> Result<Registry, LoadFailure> {
Registry::resolve(d, 100, &mut budget())
}
fn hex(s: &str) -> Vec<u8> {
s.split_whitespace().map(|b| u8::from_str_radix(b, 16).unwrap()).collect()
}
// Independently specified PBX, not generated by any production serializer.
// Header 32 bytes, seven directory entries (84 bytes), payload starts at 116.
// constants=116/4, functions=120/29, code=149/2, exports=151/4,
// syscalls=155/4, types=159/10, implementations=169/4. Total=173.
fn minimal_bytes() -> Vec<u8> {
hex("
50 42 58 00 01 00 00 00 07 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 74 00 00 00 04 00 00 00
01 00 00 00 78 00 00 00 1d 00 00 00
02 00 00 00 95 00 00 00 02 00 00 00
04 00 00 00 97 00 00 00 04 00 00 00
05 00 00 00 9b 00 00 00 04 00 00 00
06 00 00 00 9f 00 00 00 0a 00 00 00
07 00 00 00 a9 00 00 00 04 00 00 00
00 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 02 00 00 00 00 00 00 00 00 00 00 00
01 00
00 00 00 00
00 00 00 00
01 00 00 00 00 00 13 00 00 00
00 00 00 00")
}
fn minimal_registry() -> Registry {
resolve(RegistryDeclarations {
types: vec![builtin(BuiltinId::BOOL)],
functions: vec![FunctionDecl { code_len: 2, ..Default::default() }],
..Default::default()
})
.unwrap()
}
fn envelope(types: &[u8], functions: &[u8], implementations: &[u8]) -> Vec<u8> {
let empty = [0; 4];
let code = [1, 0];
encode_envelope(
&[
SectionData { kind: 0, bytes: &empty },
SectionData { kind: 1, bytes: functions },
SectionData { kind: 2, bytes: &code },
SectionData { kind: 4, bytes: &empty },
SectionData { kind: 5, bytes: &empty },
SectionData { kind: 6, bytes: types },
SectionData { kind: 7, bytes: implementations },
],
&mut budget(),
)
.unwrap()
}
#[test]
fn writer_matches_independent_minimal_envelope() {
let sections = encode_registry(&minimal_registry(), &mut budget()).unwrap();
let bytes = envelope(&sections.types, &sections.functions, &sections.implementations);
assert_eq!(bytes, minimal_bytes());
assert_eq!(bytes.len(), 173);
let mut b = budget();
let env = PbxEnvelope::parse(&bytes, &mut b).unwrap();
assert_eq!(env.section(2).unwrap().offset, 149);
let registry = env.resolve_registry(&mut b).unwrap();
assert_eq!(registry.declarations(), minimal_registry().declarations());
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
assert_eq!(registry.declarations().functions[0].max_stack_slots, 0);
}
#[test]
fn owned_v1_decoder_accepts_independent_bytes_without_publishing_an_image() {
let mut b = budget();
let owned = OwnedPbx::parse(&minimal_bytes(), &mut b).unwrap();
assert_eq!(owned.registry.declarations(), minimal_registry().declarations());
assert_eq!(owned.code, [1, 0]);
assert!(owned.constants.is_empty());
assert!(owned.exports.is_empty());
assert!(owned.syscalls.is_empty());
assert!(owned.debug.is_none());
assert_eq!(b.used(LoadResource::TemporaryBytes), owned.code.capacity() as u64);
}
#[test]
fn owned_payloads_preserve_utf8_float_bits_names_and_binding_declarations() {
use prometeu_bytecode::model::{ConstantPoolEntry as K, DebugInfo, Export, SyscallDecl};
use prometeu_bytecode::SourceSpan;
let registry = minimal_registry();
let constants = [
K::Null,
K::Int32(i32::MIN),
K::Int64(i64::MAX),
K::Float64(f64::from_bits(0x7ff8000000000042)),
K::Boolean(true),
K::String("é猫".into()),
K::String(String::new()),
];
let debug = DebugInfo {
pc_to_span: vec![(0, SourceSpan { file_id: 9, start: 2, end: 7 })],
function_names: vec![(0, "débug".into())],
};
let exports = [Export { func_idx: 0, symbol: "入口".into() }];
let syscalls = [SyscallDecl {
module: "system".into(),
name: "hasCart".into(),
version: 1,
arg_slots: 0,
ret_slots: 1,
}];
let bytes = PbxModule {
registry: &registry,
constants: &constants,
code: &[1, 0],
debug: Some(&debug),
exports: &exports,
syscalls: &syscalls,
}
.serialize(&mut budget())
.unwrap();
let mut b = budget();
let module = OwnedPbx::parse(&bytes, &mut b).unwrap();
assert_eq!(&module.constants[..3], &constants[..3]);
let K::Float64(value) = module.constants[3] else { panic!() };
assert_eq!(value.to_bits(), 0x7ff8000000000042);
assert_eq!(&module.constants[4..], &constants[4..]);
assert_eq!(module.debug.as_ref(), Some(&debug));
assert_eq!(module.exports, exports);
assert_eq!(module.syscalls, syscalls);
assert_eq!(b.used(LoadResource::ConstantEntries), 7);
assert_eq!(b.used(LoadResource::ConstantStringBytes), 5);
drop(bytes);
assert_eq!(module.constants[5], K::String("é猫".into()));
}
#[test]
fn owned_payload_refusal_rolls_back_all_ownership_and_preserves_prior_budget() {
let bytes = minimal_bytes();
let mut full = budget();
OwnedPbx::parse(&bytes, &mut full).unwrap();
let limits = LoadLimits { work: full.used(LoadResource::Work) - 1, ..Default::default() };
let mut b = LoadBudget::new(limits);
b.charge(LoadResource::TemporaryBytes, 7).unwrap();
b.charge(LoadResource::RegistryBytes, 3).unwrap();
let failure = OwnedPbx::parse(&bytes, &mut b).unwrap_err();
assert_eq!(failure.resource, Some(LoadResource::Work));
assert_eq!(failure.section, Some(2));
assert_eq!(b.used(LoadResource::TemporaryBytes), 7);
assert_eq!(b.used(LoadResource::RegistryBytes), 3);
assert_eq!(b.used(LoadResource::Types), 0);
assert_eq!(b.used(LoadResource::ConstantEntries), 0);
let mut limits = LoadLimits::default();
limits.temporary_bytes = 1;
let mut b = LoadBudget::new(limits);
assert_eq!(
OwnedPbx::parse(&bytes, &mut b).unwrap_err().resource,
Some(LoadResource::TemporaryBytes)
);
assert_eq!(b.used(LoadResource::RegistryBytes), 0);
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
}
#[test]
fn complete_module_writer_matches_independent_minimal_bytes_and_refunds_scratch() {
let registry = minimal_registry();
let module = PbxModule {
registry: &registry,
constants: &[],
code: &[1, 0],
debug: None,
exports: &[],
syscalls: &[],
};
let mut b = budget();
b.charge(LoadResource::TemporaryBytes, 7).unwrap();
let bytes = module.serialize(&mut b).unwrap();
assert_eq!(bytes, minimal_bytes());
assert_eq!(b.used(LoadResource::TemporaryBytes), 7 + bytes.capacity() as u64);
assert_eq!(b.used(LoadResource::RegistryBytes), 0);
assert_eq!(b.used(LoadResource::ConstantEntries), 0);
ParsedPbx::parse(&bytes, &mut budget()).unwrap();
}
#[test]
fn complete_module_writer_preserves_non_registry_encodings() {
use prometeu_bytecode::model::{ConstantPoolEntry as K, DebugInfo, Export, SyscallDecl};
use prometeu_bytecode::SourceSpan;
let registry = minimal_registry();
let constants = [
K::Null,
K::Int64(-1),
K::Float64(f64::from_bits(0x7ff8000000001234)),
K::Boolean(true),
K::String("é".into()),
K::Int32(-2),
K::String(String::new()),
];
let debug = DebugInfo {
pc_to_span: vec![(0, SourceSpan { file_id: 7, start: 2, end: 9 })],
function_names: vec![(0, String::new())],
};
let exports = [Export { symbol: "boot".into(), func_idx: 0 }];
let syscalls = [SyscallDecl {
module: "m".into(),
name: "n".into(),
version: 3,
arg_slots: 2,
ret_slots: 1,
}];
let module = PbxModule {
registry: &registry,
constants: &constants,
code: &[1, 0],
debug: Some(&debug),
exports: &exports,
syscalls: &syscalls,
};
let bytes = module.serialize(&mut budget()).unwrap();
let parsed = ParsedPbx::parse(&bytes, &mut budget()).unwrap();
assert_eq!(
parsed.section(0).unwrap().bytes,
hex("07 00 00 00 00
01 ff ff ff ff ff ff ff ff
02 34 12 00 00 00 00 f8 7f
03 01 04 02 00 00 00 c3 a9 05 fe ff ff ff 04 00 00 00 00")
);
assert_eq!(
parsed.section(3).unwrap().bytes,
hex("01 00 00 00 00 00 00 00
07 00 00 00 02 00 00 00 09 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00")
);
assert_eq!(
parsed.section(4).unwrap().bytes,
hex("01 00 00 00 00 00 00 00 04 00 00 00 62 6f 6f 74")
);
assert_eq!(
parsed.section(5).unwrap().bytes,
hex("01 00 00 00 01 00 6d 01 00 6e 03 00 02 00 01 00")
);
}
#[test]
fn complete_module_writer_rejects_invalid_payload_records_without_retaining_scratch() {
use prometeu_bytecode::model::{DebugInfo, Export, SyscallDecl};
use prometeu_bytecode::SourceSpan;
let registry = minimal_registry();
let bad_export = [Export { symbol: "bad".into(), func_idx: u32::MAX }];
let syscall = SyscallDecl { module: "m".into(), name: "n".into(), ..Default::default() };
let duplicates = [syscall.clone(), syscall];
let bad_debug = DebugInfo {
pc_to_span: vec![(2, SourceSpan { file_id: 0, start: 0, end: 1 })],
..Default::default()
};
for (exports, syscalls, debug, reason) in [
(&bad_export[..], &[][..], None, LoadReason::FunctionId),
(&[][..], &duplicates[..], None, LoadReason::DuplicateSyscall),
(&[][..], &[][..], Some(&bad_debug), LoadReason::DebugRange),
] {
let mut b = budget();
b.charge(LoadResource::TemporaryBytes, 7).unwrap();
let e = PbxModule {
registry: &registry,
constants: &[],
code: &[1, 0],
debug,
exports,
syscalls,
}
.serialize(&mut b)
.unwrap_err();
assert_eq!(e.reason, reason);
assert_eq!(b.used(LoadResource::TemporaryBytes), 7);
assert!(b.used(LoadResource::Work) > 0);
}
}
#[test]
fn complete_module_writer_checks_constant_quotas_before_payload_allocation() {
use prometeu_bytecode::model::ConstantPoolEntry as K;
let registry = minimal_registry();
let constants = [K::String("abc".into()), K::String("abc".into())];
let module = PbxModule {
registry: &registry,
constants: &constants,
code: &[1, 0],
debug: None,
exports: &[],
syscalls: &[],
};
for (resource, limit) in [
(LoadResource::ConstantEntries, 1),
(LoadResource::ConstantStringBytes, 5),
(LoadResource::TemporaryBytes, 1),
] {
let mut limits = LoadLimits::default();
match resource {
LoadResource::ConstantEntries => limits.constant_entries = limit,
LoadResource::ConstantStringBytes => limits.constant_string_bytes = limit,
LoadResource::TemporaryBytes => limits.temporary_bytes = limit,
_ => unreachable!(),
}
let mut b = LoadBudget::new(limits);
let error = module.serialize(&mut b).unwrap_err();
assert_eq!(error.code, LoadCode::ResourceLimit);
assert_eq!(error.resource, Some(resource));
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
}
}
#[test]
fn complete_module_writer_rejects_code_range_mismatch() {
let registry = minimal_registry();
let e = PbxModule {
registry: &registry,
constants: &[],
code: &[],
debug: None,
exports: &[],
syscalls: &[],
}
.serialize(&mut budget())
.unwrap_err();
assert_eq!((e.code, e.reason), (LoadCode::InvalidCode, LoadReason::CodeRange));
assert_eq!((e.function, e.pc), (Some(0), Some(0)));
}
#[test]
fn representative_records_match_fixed_bytes_and_preserve_names_without_debug() {
let types = hex("
04 00 00 00
00 00 13 00 00 00
01 01 00 00 00 00 01 00 00 00 00 00 00 00 00
02 00 01 00 00 00
03 00 01 00 00 00 01 01 00 00 00 6d
01 00 00 00 00 00 00 00 01 01 00 00 00 70
01 00 00 00 00 00 00 00");
let functions = hex("
01 00 00 00 01 01 00 00 00 66
02 00 00 00 01 00 00 00 00 00 00 00 00 01 01 00 00 00 70
01 00 00 00 00 00 00 00
00 00 00 00 02 00 00 00 00 00 00 00 01 00 00 00");
let implementations = hex("01 00 00 00 01 00 00 00 03 00 00 00 01 00 00 00 00 00 00 00");
let bytes = envelope(&types, &functions, &implementations);
let mut b = budget();
let env = PbxEnvelope::parse(&bytes, &mut b).unwrap();
assert!(env.section(3).is_none());
let r = env.resolve_registry(&mut b).unwrap();
assert_eq!(r.declarations().types[0].name, None);
assert_eq!(r.declarations().types[1].name, Some(String::new()));
assert_eq!(r.declarations().functions[0].signature.parameters[1].name.as_deref(), Some("p"));
assert_eq!(r.implementation(TypeId(1), TypeId(3)), Some(ImplementationId(0)));
assert_eq!(r.type_layout(TypeId(2)).unwrap().storage.size, 8);
let encoded = encode_registry(&r, &mut budget()).unwrap();
assert_eq!(encoded.types, types);
assert_eq!(encoded.functions, functions);
assert_eq!(encoded.implementations, implementations);
}
#[test]
fn every_truncated_envelope_is_rejected_without_panic() {
let bytes = minimal_bytes();
for n in 0..bytes.len() {
let mut b = budget();
assert!(PbxEnvelope::parse(&bytes[..n], &mut b).is_err(), "prefix {n}");
}
}
#[test]
fn envelope_mutations_have_typed_reasons() {
for (offset, value, code, reason) in [
(0, 0, LoadCode::InvalidFormat, LoadReason::Magic),
(4, 0, LoadCode::UnsupportedFormat, LoadReason::Version),
(6, 1, LoadCode::InvalidFormat, LoadReason::Endianness),
(7, 1, LoadCode::InvalidFormat, LoadReason::Reserved),
(31, 1, LoadCode::InvalidFormat, LoadReason::Reserved),
(32, 8, LoadCode::UnsupportedFormat, LoadReason::SectionKind),
(44, 0, LoadCode::InvalidFormat, LoadReason::DuplicateSection),
(36, 0, LoadCode::InvalidFormat, LoadReason::Overlap),
(48, 116, LoadCode::InvalidFormat, LoadReason::Overlap),
] {
let mut bytes = minimal_bytes();
bytes[offset] = value;
let err = PbxEnvelope::parse(&bytes, &mut budget()).unwrap_err();
assert_eq!((err.code, err.reason), (code, reason), "offset {offset}");
}
}
#[test]
fn mandatory_empty_sections_are_required() {
let mut bytes = minimal_bytes();
bytes[32] = 3; // replaces constants with optional debug
let err = PbxEnvelope::parse(&bytes, &mut budget()).unwrap_err();
assert_eq!(err.reason, LoadReason::MissingSection);
assert_eq!(err.section, Some(0));
}
#[test]
fn record_flags_utf8_trailing_bytes_and_unknown_categories_fail() {
let valid = minimal_bytes();
let mut b = budget();
let env = PbxEnvelope::parse(&valid, &mut b).unwrap();
let functions = env.section(1).unwrap().bytes;
let implementations = env.section(7).unwrap().bytes;
for (types, reason) in [
(hex("01 00 00 00 00 02 13 00 00 00"), LoadReason::InvalidFlag),
(hex("01 00 00 00 04 00 13 00 00 00"), LoadReason::Category),
(hex("01 00 00 00 00 01 01 00 00 00 ff 13 00 00 00"), LoadReason::Utf8),
(hex("01 00 00 00 00 00 13 00 00 00 ff"), LoadReason::TrailingBytes),
(hex("01 00 00 00 00 00 00 01 00 00"), LoadReason::Builtin),
] {
let bytes = envelope(&types, functions, implementations);
let mut b = budget();
let env = PbxEnvelope::parse(&bytes, &mut b).unwrap();
let err = env.resolve_registry(&mut b).unwrap_err();
assert_eq!(err.reason, reason);
assert_eq!(b.used(LoadResource::RegistryBytes), 0);
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
}
}
#[test]
fn oversized_counts_fail_before_dependent_allocation() {
let bytes = envelope(&[255; 4], &[0; 4], &[0; 4]);
let mut b = budget();
let env = PbxEnvelope::parse(&bytes, &mut b).unwrap();
let err = env.resolve_registry(&mut b).unwrap_err();
assert_eq!(err.resource, Some(LoadResource::Types));
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
}
#[test]
fn logical_scalar_layout_and_empty_nominal_identity() {
let d = RegistryDeclarations {
types: vec![
builtin(BuiltinId::BOOL),
builtin(BuiltinId::INT32),
TypeDecl { name: None, kind: TypeKind::Struct(vec![named(0), named(1), named(0)]) },
TypeDecl { name: None, kind: TypeKind::Struct(vec![]) },
TypeDecl { name: None, kind: TypeKind::Struct(vec![]) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(2)) },
],
..Default::default()
};
let r = resolve(d).unwrap();
let s = r.type_layout(TypeId(2)).unwrap();
assert_eq!(s.storage.size, 8);
let p = s.instance.as_ref().unwrap();
assert_eq!((p.size, p.alignment), (12, 4));
assert_eq!(p.fields.iter().map(|f| f.offset).collect::<Vec<_>>(), vec![0, 4, 8]);
assert!(p.owned_fields.is_empty());
for id in [3, 4] {
let l = r.type_layout(TypeId(id)).unwrap().instance.as_ref().unwrap();
assert_eq!((l.size, l.alignment), (0, 1));
}
assert_eq!(r.type_layout(TypeId(5)).unwrap().storage.size, 8);
assert_eq!(r.declarations().types.len(), 6);
}
#[test]
fn nominal_recursion_and_forward_references_terminate() {
let r = resolve(RegistryDeclarations {
types: vec![
TypeDecl { name: None, kind: TypeKind::Struct(vec![named(0), named(1)]) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
],
..Default::default()
})
.unwrap();
let layout = r.type_layout(TypeId(0)).unwrap().instance.as_ref().unwrap();
assert_eq!(layout.size, 16);
assert_eq!(layout.owned_fields.len(), 2);
}
#[test]
fn duplicate_imports_and_arrays_and_structural_cycles_fail() {
let cases = [
(vec![builtin(BuiltinId::BOOL), builtin(BuiltinId::BOOL)], LoadReason::DuplicateBuiltin),
(
vec![
builtin(BuiltinId::BOOL),
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
],
LoadReason::DuplicateArray,
),
(vec![TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) }], LoadReason::ArrayCycle),
(
vec![
TypeDecl { name: None, kind: TypeKind::Array(TypeId(1)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
],
LoadReason::ArrayCycle,
),
];
for (types, reason) in cases {
assert_eq!(
resolve(RegistryDeclarations { types, ..Default::default() }).unwrap_err().reason,
reason
);
}
}
#[test]
fn long_array_chain_uses_bounded_iteration() {
let mut types: Vec<_> = (0..10_000)
.map(|i| TypeDecl { name: None, kind: TypeKind::Array(TypeId(i + 1)) })
.collect();
types.push(builtin(BuiltinId::INT32));
assert!(resolve(RegistryDeclarations { types, ..Default::default() }).is_ok());
}
#[test]
fn invalid_references_are_not_indexed() {
let d = RegistryDeclarations {
types: vec![TypeDecl { name: None, kind: TypeKind::Struct(vec![named(u32::MAX)]) }],
..Default::default()
};
let e = resolve(d).unwrap_err();
assert_eq!(e.code, LoadCode::InvalidReference);
assert_eq!(e.member, Some(0));
}
#[test]
fn all_builtin_widths_native_layout_and_unknown_imports() {
for (id, size, alignment, slots) in [
(1, 4, 4, 1),
(2, 16, 8, 2),
(3, 24, 8, 3),
(0x10, 4, 4, 1),
(0x11, 8, 8, 1),
(0x12, 8, 8, 1),
(0x13, 1, 1, 1),
] {
let l = BuiltinId(id).layout().unwrap();
assert_eq!((l.size, l.alignment, l.slots), (size, alignment, slots));
assert!(!l.nullable());
}
let s = BuiltinId::STRING.layout().unwrap();
assert_eq!((s.size, s.alignment), (size_of::<StringSlot>(), align_of::<StringSlot>()));
assert!(s.nullable());
let d = BuiltinId::DYNAMIC.layout().unwrap();
assert_eq!((d.size, d.alignment), (size_of::<DynamicSlot>(), align_of::<DynamicSlot>()));
for id in [0, 4, 0x100, 0x101, 0x102, u32::MAX] {
assert_eq!(BuiltinId(id).layout().unwrap_err().reason, LoadReason::Builtin);
}
}
fn implemented() -> RegistryDeclarations {
RegistryDeclarations {
types: vec![
builtin(BuiltinId::VEC2),
TypeDecl { name: None, kind: TypeKind::Struct(vec![]) },
TypeDecl {
name: None,
kind: TypeKind::Trait(vec![MethodDecl {
name: None,
signature: Signature { parameters: vec![named(0)], results: vec![TypeId(0)] },
}]),
},
],
functions: vec![FunctionDecl {
signature: Signature { parameters: vec![named(1), named(0)], results: vec![TypeId(0)] },
code_len: 2,
max_stack_slots: 2,
..Default::default()
}],
implementations: vec![ImplementationDecl {
owner: TypeId(1),
trait_id: TypeId(2),
methods: vec![FunctionId(0)],
}],
}
}
#[test]
fn multi_slot_signatures_derive_counts_and_validate_exact_trait_pair() {
let r = resolve(implemented()).unwrap();
assert_eq!(
r.function_layout(FunctionId(0)),
Some(&FunctionLayout { parameter_slots: 3, result_slots: 2 })
);
let mut d = implemented();
d.functions[0].signature.parameters.swap(0, 1);
assert_eq!(resolve(d).unwrap_err().reason, LoadReason::Signature);
let mut d = implemented();
d.functions[0].signature.results.clear();
assert_eq!(resolve(d).unwrap_err().reason, LoadReason::Signature);
let mut d = implemented();
d.implementations.push(d.implementations[0].clone());
assert_eq!(resolve(d).unwrap_err().reason, LoadReason::DuplicateImplementation);
let mut d = implemented();
d.implementations[0].methods.clear();
assert_eq!(resolve(d).unwrap_err().reason, LoadReason::MethodCount);
let mut d = implemented();
d.implementations[0].owner = TypeId(0);
assert_eq!(resolve(d).unwrap_err().reason, LoadReason::OwnerCategory);
}
#[test]
fn literal_zero_max_stack_is_preserved_and_frame_limits_are_not_truncated() {
let mut d = implemented();
d.functions[0].max_stack_slots = 0;
assert!(resolve(d).is_ok());
let mut d = implemented();
d.functions[0].local_slots = 65_536;
assert_eq!(resolve(d).unwrap_err().reason, LoadReason::FrameSlots);
let mut d = implemented();
d.functions[0].code_offset = u32::MAX;
assert_eq!(resolve(d).unwrap_err().reason, LoadReason::CodeRange);
let mut d = implemented();
d.functions.push(d.functions[0].clone());
assert_eq!(resolve(d).unwrap_err().reason, LoadReason::CodeRange);
}
#[test]
fn work_retained_and_temporary_limits_refuse_before_publication() {
for limits in [
LoadLimits { work: 1, ..Default::default() },
LoadLimits { registry_bytes: 1, ..Default::default() },
LoadLimits { temporary_bytes: 1, ..Default::default() },
] {
let mut b = LoadBudget::new(limits);
let e = Registry::resolve(implemented(), 100, &mut b).unwrap_err();
assert_eq!(e.code, LoadCode::ResourceLimit);
assert_eq!(b.used(LoadResource::RegistryBytes), 0);
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
}
}
#[test]
fn budget_boundaries_are_transactional_and_product_ceiling_cannot_be_raised() {
let mut b = LoadBudget::new(LoadLimits { temporary_bytes: 8, ..Default::default() });
b.charge(LoadResource::TemporaryBytes, 8).unwrap();
assert!(b.charge(LoadResource::TemporaryBytes, 1).is_err());
assert_eq!(b.used(LoadResource::TemporaryBytes), 8);
b.refund(LoadResource::TemporaryBytes, 8);
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
let b = LoadBudget::new(LoadLimits { pbx_bytes: u64::MAX, ..Default::default() });
assert_eq!(b.limit(LoadResource::PbxBytes), 64 * 1_048_576);
}
#[test]
fn name_limits_include_aggregate_and_empty_is_not_absent() {
let mut d = implemented();
d.types[0].name = Some("x".repeat(4097));
assert_eq!(resolve(d).unwrap_err().resource, Some(LoadResource::NameBytes));
let mut d = implemented();
d.types[0].name = Some("ab".into());
d.types[1].name = Some("cd".into());
let mut b = LoadBudget::new(LoadLimits { name_bytes: 3, ..Default::default() });
assert_eq!(
Registry::resolve(d, 100, &mut b).unwrap_err().resource,
Some(LoadResource::NameBytes)
);
}
fn with_section(kind: u32, payload: &[u8]) -> Vec<u8> {
let bytes = minimal_bytes();
let mut b = budget();
let env = PbxEnvelope::parse(&bytes, &mut b).unwrap();
let mut sections = Vec::new();
for k in 0..8 {
if k == kind {
sections.push(SectionData { kind: k, bytes: payload });
} else if let Some(section) = env.section(k) {
sections.push(SectionData { kind: k, bytes: section.bytes });
}
}
encode_envelope(&sections, &mut budget()).unwrap()
}
#[test]
fn full_pbx_validation_accepts_independent_minimal_fixture() {
let bytes = minimal_bytes();
let mut b = budget();
let parsed = ParsedPbx::parse(&bytes, &mut b).unwrap();
assert_eq!(parsed.encode(&mut budget()).unwrap(), bytes);
assert_eq!(parsed.registry().declarations(), minimal_registry().declarations());
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
}
#[test]
fn constants_are_strict_and_validate_every_tag_without_lossy_utf8() {
let constants=hex("06 00 00 00 00 01 ff ff ff ff ff ff ff ff 02 00 00 00 00 00 00 00 00 03 01 04 03 00 00 00 61 62 63 05 ff ff ff ff");
let bytes = with_section(0, &constants);
let mut b = budget();
let parsed = ParsedPbx::parse(&bytes, &mut b).unwrap();
assert_eq!(parsed.section(0).unwrap().bytes, constants);
assert_eq!(b.used(LoadResource::ConstantEntries), 6);
assert_eq!(b.used(LoadResource::ConstantStringBytes), 3);
for (cp, reason) in [
(hex("01 00 00 00 03 02"), LoadReason::InvalidFlag),
(hex("01 00 00 00 04 01 00 00 00 ff"), LoadReason::Utf8),
(hex("01 00 00 00 06"), LoadReason::ConstantTag),
(hex("01 00 00 00 01 ff"), LoadReason::Truncated),
(hex("00 00 00 00 ff"), LoadReason::TrailingBytes),
] {
let bytes = with_section(0, &cp);
let mut b = budget();
let e = ParsedPbx::parse(&bytes, &mut b).unwrap_err();
assert_eq!(e.reason, reason);
assert_eq!(e.section, Some(0));
assert_eq!(b.used(LoadResource::RegistryBytes), 0);
}
}
#[test]
fn constant_string_limits_are_checked_before_materialization() {
let bytes = with_section(0, &hex("01 00 00 00 04 03 00 00 00 61 62 63"));
for limits in [
LoadLimits { individual_string_bytes: 2, ..Default::default() },
LoadLimits { constant_string_bytes: 2, ..Default::default() },
LoadLimits { constant_entries: 0, ..Default::default() },
] {
let mut b = LoadBudget::new(limits);
let e = ParsedPbx::parse(&bytes, &mut b).unwrap_err();
assert_eq!(e.code, LoadCode::ResourceLimit);
assert_eq!(b.used(LoadResource::ConstantStringBytes), 0);
assert_eq!(b.used(LoadResource::RegistryBytes), 0);
}
}
#[test]
fn export_and_debug_references_are_checked_and_table_tails_rejected() {
let export = hex("01 00 00 00 00 00 00 00 04 00 00 00 6d 61 69 6e");
assert!(ParsedPbx::parse(&with_section(4, &export), &mut budget()).is_ok());
let mut bad = export;
bad[4] = 1;
let e = ParsedPbx::parse(&with_section(4, &bad), &mut budget()).unwrap_err();
assert_eq!(e.code, LoadCode::InvalidReference);
assert_eq!(e.referenced_id, Some(1));
// One pc/span record; one function name. These are independent of signature names.
let debug=hex("01 00 00 00 00 00 00 00 07 00 00 00 0a 00 00 00 0c 00 00 00 01 00 00 00 00 00 00 00 01 00 00 00 66");
let bytes = with_section(3, &debug);
assert!(ParsedPbx::parse(&bytes, &mut budget()).is_ok());
let mut bad = debug;
bad[4] = 2;
assert_eq!(
ParsedPbx::parse(&with_section(3, &bad), &mut budget()).unwrap_err().reason,
LoadReason::DebugRange
);
for kind in [3, 4, 5] {
let payload =
if kind == 3 { hex("00 00 00 00 00 00 00 00 ff") } else { hex("00 00 00 00 ff") };
assert_eq!(
ParsedPbx::parse(&with_section(kind, &payload), &mut budget()).unwrap_err().reason,
LoadReason::TrailingBytes
);
}
}
#[test]
fn syscall_identity_validation_keeps_versions_distinct_and_rejects_duplicates() {
// module m, name n, version 1, zero arguments/results.
let entry = hex("01 00 6d 01 00 6e 01 00 00 00 00 00");
let mut payload = vec![2, 0, 0, 0];
payload.extend_from_slice(&entry);
payload.extend_from_slice(&entry);
let e = ParsedPbx::parse(&with_section(5, &payload), &mut budget()).unwrap_err();
assert_eq!((e.reason, e.section, e.record), (LoadReason::DuplicateSyscall, Some(5), Some(1)));
payload[22] = 2; // version in second 12-byte entry
let bytes = with_section(5, &payload);
let mut b = budget();
assert!(ParsedPbx::parse(&bytes, &mut b).is_ok());
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
}
#[test]
fn array_stride_uses_stored_element_layout_and_defaults_are_typed() {
use prometeu_bytecode::Value;
let registry = resolve(RegistryDeclarations {
types: vec![
builtin(BuiltinId::INT32),
builtin(BuiltinId::BOOL),
builtin(BuiltinId::VEC2),
TypeDecl { name: None, kind: TypeKind::Struct(vec![named(0), named(1)]) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(1)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(2)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(3)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(4)) },
],
..Default::default()
})
.unwrap();
for (id, stride, alignment) in [(4, 4, 4), (5, 1, 1), (6, 16, 8), (7, 8, 8), (8, 8, 8)] {
let a = registry.type_layout(TypeId(id)).unwrap().array.unwrap();
assert_eq!((a.stride, a.element_alignment), (stride, alignment));
}
assert!(matches!(BuiltinId::INT32.layout().unwrap().default_values(), [Value::Int32(0)]));
assert!(matches!(BuiltinId::BOOL.layout().unwrap().default_values(), [Value::Boolean(false)]));
assert!(matches!(BuiltinId::COLOR.layout().unwrap().default_values(), [Value::Int64(0)]));
assert!(matches!(BuiltinId::STRING.layout().unwrap().default_values(), [Value::Null]));
assert!(matches!(
BuiltinId::DYNAMIC.layout().unwrap().default_values(),
[Value::Null, Value::Null]
));
for value in BuiltinId::VEC2.layout().unwrap().default_values() {
let Value::Float(value) = value else { panic!("expected float default") };
assert_eq!(value.to_bits(), 0);
}
assert_eq!(registry.type_layout(TypeId(3)).unwrap().storage.default_values(), &[Value::Null]);
}
/// Run explicitly in release mode; records a map-only comparison, not VM/GC throughput.
#[test]
#[ignore = "explicit layout measurement; not a timing assertion"]
fn reference_map_probe() {
use std::hint::black_box;
use std::time::Instant;
for period in [1, 16, 256] {
let d = RegistryDeclarations {
types: vec![
builtin(BuiltinId::INT64),
TypeDecl { name: None, kind: TypeKind::Struct(vec![]) },
TypeDecl {
name: None,
kind: TypeKind::Struct(
(0..4096).map(|i| named(if i % period == 0 { 1 } else { 0 })).collect(),
),
},
],
..Default::default()
};
let mut b = budget();
let load_start = Instant::now();
let r = Registry::resolve(d, 0, &mut b).unwrap();
let load_ns = load_start.elapsed().as_nanos();
let layout = r.type_layout(TypeId(2)).unwrap().instance.as_ref().unwrap();
let mut bitmap = vec![0u64; 64];
for field in &layout.owned_fields {
let bit = field.offset / 8;
bitmap[bit / 64] |= 1u64 << (bit % 64);
}
let runs = 10_000;
let start = Instant::now();
let mut list_checksum = 0usize;
for _ in 0..runs {
for field in black_box(&layout.owned_fields) {
list_checksum = list_checksum.wrapping_add(field.offset);
}
}
black_box(list_checksum);
let list_ns = start.elapsed().as_nanos();
let start = Instant::now();
let mut bitmap_checksum = 0usize;
for _ in 0..runs {
for (word_index, &word) in black_box(&bitmap).iter().enumerate() {
let mut word = word;
while word != 0 {
bitmap_checksum = bitmap_checksum
.wrapping_add((word_index * 64 + word.trailing_zeros() as usize) * 8);
word &= word - 1;
}
}
}
black_box(bitmap_checksum);
let bitmap_ns = start.elapsed().as_nanos();
assert_eq!(list_checksum, bitmap_checksum);
println!("arch={} fields=4096 period={} roots={} payload={} registry={} load_ns={} list_bytes={} bitmap_bytes={} runs={} list_ns={} bitmap_ns={}",
std::env::consts::ARCH,period,layout.owned_fields.len(),layout.size,b.used(LoadResource::RegistryBytes),load_ns,
layout.owned_fields.capacity()*size_of::<OwnedField>(),bitmap.capacity()*8,runs,list_ns,bitmap_ns);
}
}
#[test]
fn independent_multi_slot_signature_fixture_has_no_serialized_widths() {
// vec2 import; fn(vec2)->vec2; GET_LOCAL 0; GET_LOCAL 1; RET.
let types = hex("01 00 00 00 00 00 02 00 00 00");
let functions=hex("01 00 00 00 00 01 00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 0e 00 00 00 00 00 00 00 02 00 00 00");
let code = hex("42 00 00 00 00 00 42 00 01 00 00 00 51 00");
let empty = [0; 4];
let bytes = encode_envelope(
&[
SectionData { kind: 0, bytes: &empty },
SectionData { kind: 1, bytes: &functions },
SectionData { kind: 2, bytes: &code },
SectionData { kind: 4, bytes: &empty },
SectionData { kind: 5, bytes: &empty },
SectionData { kind: 6, bytes: &types },
SectionData { kind: 7, bytes: &empty },
],
&mut budget(),
)
.unwrap();
let parsed = ParsedPbx::parse(&bytes, &mut budget()).unwrap();
assert_eq!(
parsed.registry().function_layout(FunctionId(0)),
Some(&FunctionLayout { parameter_slots: 2, result_slots: 2 })
);
let sections = encode_registry(parsed.registry(), &mut budget()).unwrap();
assert_eq!(sections.functions, functions);
assert_eq!(sections.types, types);
}
@@ -278,6 +278,7 @@ pub enum CartridgeError {
MissingProgram,
MissingAssets,
IoError,
ProgramLoadFailed(prometeu_bytecode::load_limits::LoadFailure),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize, Serialize)]
@@ -5,6 +5,9 @@ use crate::cartridge::{
CartridgeManifest,
};
use crate::syscalls::{CapFlags, caps};
use prometeu_bytecode::load_limits::{
LoadBudget, LoadFailure, LoadLimits, LoadReason, LoadResource,
};
use std::collections::HashSet;
use std::fs;
use std::io::{Read, Seek, SeekFrom};
@@ -58,7 +61,9 @@ impl DirectoryCartridgeLoader {
return Err(CartridgeError::MissingProgram);
}
let program = fs::read(program_path).map_err(|_| CartridgeError::IoError)?;
let mut program_file = fs::File::open(program_path).map_err(|_| CartridgeError::IoError)?;
let program_len = program_file.metadata().map_err(|_| CartridgeError::IoError)?.len();
let program = read_program(&mut program_file, program_len, LoadLimits::default())?;
let assets_pa_path = path.join("assets.pa");
let (assets, asset_table, preload) = if assets_pa_path.exists() {
@@ -98,6 +103,59 @@ impl DirectoryCartridgeLoader {
pub struct PackedCartridgeLoader;
/// Admit the PBX input separately from parsing scratch. Metadata rejects an
/// oversized file before reservation; bounded reads also cover file growth.
fn read_program(
reader: &mut impl Read,
size_hint: u64,
limits: LoadLimits,
) -> Result<Vec<u8>, CartridgeError> {
let budget = LoadBudget::new(limits);
let limit = budget.limit(LoadResource::PbxBytes);
budget.check(LoadResource::PbxBytes, size_hint).map_err(CartridgeError::ProgramLoadFailed)?;
let resource_error = |reason, requested| {
let mut error = LoadFailure::resource(LoadResource::PbxBytes, requested, limit);
error.reason = reason;
CartridgeError::ProgramLoadFailed(error)
};
let mut out = Vec::<u8>::new();
let initial =
usize::try_from(size_hint).map_err(|_| resource_error(LoadReason::Overflow, size_hint))?;
out.try_reserve_exact(initial)
.map_err(|_| resource_error(LoadReason::Allocation, size_hint))?;
budget
.check(LoadResource::PbxBytes, out.capacity() as u64)
.map_err(CartridgeError::ProgramLoadFailed)?;
let mut chunk = [0u8; 8192];
loop {
// At the ceiling inspect one extra byte without growing the input.
let remaining = limit - out.len() as u64;
let read_len = remaining.min(chunk.len() as u64).max(1) as usize;
let count = match reader.read(&mut chunk[..read_len]) {
Ok(count) => count,
Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
Err(_) => return Err(CartridgeError::IoError),
};
if count == 0 {
return Ok(out);
}
let requested = (out.len() as u64)
.checked_add(count as u64)
.ok_or_else(|| resource_error(LoadReason::Overflow, u64::MAX))?;
budget
.check(LoadResource::PbxBytes, requested)
.map_err(CartridgeError::ProgramLoadFailed)?;
// Reserve exact growth rather than allowing Vec's geometric growth to
// exceed admission. Existing spare capacity is reused without billing twice.
out.try_reserve_exact(count)
.map_err(|_| resource_error(LoadReason::Allocation, requested))?;
budget
.check(LoadResource::PbxBytes, out.capacity() as u64)
.map_err(CartridgeError::ProgramLoadFailed)?;
out.extend_from_slice(&chunk[..count]);
}
}
impl PackedCartridgeLoader {
pub fn load(_path: &Path) -> Result<Cartridge, CartridgeError> {
Err(CartridgeError::InvalidFormat)
@@ -204,6 +262,7 @@ mod tests {
use crate::asset::{AssetCodec, AssetEntry, BankType, PreloadEntry};
use crate::cartridge::{ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude};
use crate::glyph_bank::GLYPH_BANK_MAX_PALETTE_COUNT_V1;
use prometeu_bytecode::load_limits::LoadCode;
use serde_json::json;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
@@ -289,6 +348,76 @@ mod tests {
manifest
}
#[test]
fn program_admission_accepts_exact_limit_and_rejects_growth_after_metadata() {
let limits = LoadLimits { pbx_bytes: 3, ..Default::default() };
for hint in [0, 1, 3] {
assert_eq!(read_program(&mut &b"abc"[..], hint, limits).unwrap(), b"abc");
let error = read_program(&mut &b"abcd"[..], hint, limits).unwrap_err();
let CartridgeError::ProgramLoadFailed(error) = error else {
panic!("typed PBX admission failure expected")
};
assert_eq!((error.code, error.reason), (LoadCode::ResourceLimit, LoadReason::Limit));
assert_eq!(
(error.resource, error.requested, error.limit),
(Some(LoadResource::PbxBytes), Some(4), Some(3))
);
}
}
#[test]
fn program_admission_rejects_oversized_metadata_before_reading() {
struct MustNotRead;
impl Read for MustNotRead {
fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
panic!("must reject before reading")
}
}
let limits = LoadLimits { pbx_bytes: 3, ..Default::default() };
assert!(matches!(
read_program(&mut MustNotRead, 4, limits),
Err(CartridgeError::ProgramLoadFailed(_))
));
}
#[test]
fn program_admission_handles_empty_short_and_interrupted_reads() {
assert!(read_program(&mut &[][..], 0, LoadLimits::default()).unwrap().is_empty());
struct ShortReads {
interrupted: bool,
remaining: &'static [u8],
}
impl Read for ShortReads {
fn read(&mut self, bytes: &mut [u8]) -> std::io::Result<usize> {
if !self.interrupted {
self.interrupted = true;
return Err(std::io::ErrorKind::Interrupted.into());
}
if self.remaining.is_empty() {
return Ok(0);
}
bytes[0] = self.remaining[0];
self.remaining = &self.remaining[1..];
Ok(1)
}
}
let mut reader = ShortReads { interrupted: false, remaining: b"abc" };
assert_eq!(read_program(&mut reader, 2, LoadLimits::default()).unwrap(), b"abc");
}
#[test]
fn directory_loader_rejects_oversized_pbx_with_default_limit() {
let dir = TestCartridgeDir::new(manifest_with_capabilities(None));
let file = fs::OpenOptions::new().write(true).open(dir.path().join("program.pbx")).unwrap();
let limit = LoadLimits::default().pbx_bytes;
file.set_len(limit + 1).unwrap(); // Sparse file; no giant content allocation.
let error = DirectoryCartridgeLoader::load(dir.path()).unwrap_err();
let CartridgeError::ProgramLoadFailed(error) = error else {
panic!("typed PBX admission failure expected")
};
assert_eq!((error.requested, error.limit), (Some(limit + 1), Some(64 * 1_048_576)));
}
#[test]
fn load_without_capabilities_defaults_to_none() {
let dir = TestCartridgeDir::new(manifest_with_capabilities(None));
@@ -1,4 +1,5 @@
use crate::app_mode::AppMode;
#[cfg(test)]
use prometeu_bytecode::Value;
use serde::{Deserialize, Serialize};
@@ -35,7 +36,7 @@ pub enum DebugResponse {
#[serde(rename = "handshake")]
Handshake { protocol_version: u32, runtime_version: String, cartridge: HandshakeCartridge },
#[serde(rename = "getState")]
GetState { pc: usize, stack_top: Vec<Value>, frame_index: u64, app_id: u32 },
GetState { pc: usize, stack_top: crate::ValueSnapshot, frame_index: u64, app_id: u32 },
#[serde(rename = "breakpoints")]
Breakpoints { pcs: Vec<usize> },
}
@@ -115,7 +116,8 @@ mod tests {
fn test_get_state_serialization() {
let resp = DebugResponse::GetState {
pc: 42,
stack_top: vec![Value::Int64(10), Value::String("test".into()), Value::Boolean(true)],
stack_top: vec![Value::Int64(10), Value::String("test".into()), Value::Boolean(true)]
.into(),
frame_index: 5,
app_id: 1,
};
+234 -10
View File
@@ -1,27 +1,251 @@
use crate::vm_fault::VmFault;
use prometeu_bytecode::{HeapRef, Value};
use std::sync::Arc;
/// Native producers describe their output before materializing guest content.
/// The VM provides the session allocator; HAL does not own guest quotas.
pub trait GuestStringAllocator {
fn build(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault>;
}
/// Writes only into result slots reserved by the VM. A native handler cannot
/// grow the operand buffer or exceed its declared result count.
pub struct HostReturn<'a> {
stack: &'a mut Vec<Value>,
remaining: usize,
overflowed: bool,
strings: &'a mut dyn GuestStringAllocator,
failure: Option<VmFault>,
}
impl<'a> HostReturn<'a> {
pub fn new(stack: &'a mut Vec<Value>) -> Self {
Self { stack }
pub fn new(
stack: &'a mut Vec<Value>,
result_slots: usize,
strings: &'a mut dyn GuestStringAllocator,
) -> Self {
Self { stack, remaining: result_slots, overflowed: false, strings, failure: None }
}
pub fn failure(&self) -> Option<&VmFault> {
self.failure.as_ref()
}
pub fn overflowed(&self) -> bool {
self.overflowed
}
fn admit(&mut self) -> bool {
if self.failure.is_some() {
return false;
}
if self.remaining == 0 || self.stack.len() == self.stack.capacity() {
self.overflowed = true;
false
} else {
self.remaining -= 1;
true
}
}
pub fn push_bool(&mut self, v: bool) {
self.stack.push(Value::Boolean(v));
if self.admit() {
self.stack.push(Value::Boolean(v));
}
}
pub fn push_int(&mut self, v: i64) {
self.stack.push(Value::Int64(v));
if self.admit() {
self.stack.push(Value::Int64(v));
}
}
pub fn push_null(&mut self) {
self.stack.push(Value::Null);
if self.admit() {
self.stack.push(Value::Null);
}
}
pub fn push_gate(&mut self, g: usize) {
// Temporary: cast incoming handle/HeapRef index. Real allocator will provide proper handles.
self.stack.push(Value::HeapRef(HeapRef(g as u32)));
/// Return a handle issued by the current session's heap.
pub fn push_gate(&mut self, handle: HeapRef) {
if self.admit() {
self.stack.push(if handle.is_null() { Value::Null } else { Value::HeapRef(handle) });
}
}
pub fn push_string(&mut self, s: String) {
self.stack.push(Value::string(s));
pub fn push_string(&mut self, text: &str) -> Result<(), VmFault> {
self.push_string_with_len(text.len(), &mut |writer| writer.write_str(text))
}
pub fn push_string_with_len(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<(), VmFault> {
if !self.admit() {
return self.failure.clone().map_or(Ok(()), Err);
}
match self.strings.build(length, writer) {
Ok(content) => {
self.stack.push(Value::String(content));
Ok(())
}
Err(error) => {
self.failure = Some(error.clone());
Err(error)
}
}
}
pub fn push_utf8_lossy(&mut self, bytes: &[u8]) -> Result<(), VmFault> {
let mut length = 0usize;
lossy_chunks(bytes, &mut |part| {
length = length.checked_add(part.len()).ok_or(std::fmt::Error)?;
Ok(())
})
.map_err(|_| size_overflow())?;
self.push_string_with_len(length, &mut |writer| {
lossy_chunks(bytes, &mut |part| writer.write_str(part))
})
}
pub fn push_hex(&mut self, bytes: &[u8]) -> Result<(), VmFault> {
const HEX: &[u8; 16] = b"0123456789abcdef";
let length = bytes.len().checked_mul(2).ok_or_else(size_overflow)?;
self.push_string_with_len(length, &mut |writer| {
for &byte in bytes {
let pair = [HEX[(byte >> 4) as usize], HEX[(byte & 15) as usize]];
writer.write_str(std::str::from_utf8(&pair).expect("ASCII hex"))?;
}
Ok(())
})
}
pub fn push_joined<'s, I: Iterator<Item = &'s str> + Clone>(
&mut self,
parts: I,
separator: &str,
) -> Result<(), VmFault> {
let mut length = 0usize;
for (index, part) in parts.clone().enumerate() {
if index > 0 {
length = length.checked_add(separator.len()).ok_or_else(size_overflow)?;
}
length = length.checked_add(part.len()).ok_or_else(size_overflow)?;
}
self.push_string_with_len(length, &mut |writer| {
for (index, part) in parts.clone().enumerate() {
if index > 0 {
writer.write_str(separator)?;
}
writer.write_str(part)?;
}
Ok(())
})
}
}
fn size_overflow() -> VmFault {
VmFault::Trap(prometeu_bytecode::TRAP_RESOURCE_LIMIT, "Native string length overflow".into())
}
fn lossy_chunks(
mut bytes: &[u8],
emit: &mut dyn FnMut(&str) -> std::fmt::Result,
) -> std::fmt::Result {
while !bytes.is_empty() {
match std::str::from_utf8(bytes) {
Ok(valid) => {
emit(valid)?;
break;
}
Err(error) => {
let valid = error.valid_up_to();
emit(std::str::from_utf8(&bytes[..valid]).expect("validated prefix"))?;
emit("\u{fffd}")?;
match error.error_len() {
Some(invalid) => bytes = &bytes[valid + invalid..],
None => break,
}
}
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
struct RejectStrings;
impl GuestStringAllocator for RejectStrings {
fn build(
&mut self,
_length: usize,
_writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault> {
panic!("unexpected string allocation")
}
}
#[test]
fn native_results_cannot_grow_the_reserved_buffer_or_exceed_the_signature() {
let mut stack = Vec::with_capacity(8);
let capacity = stack.capacity();
let mut strings = RejectStrings;
let mut ret = HostReturn::new(&mut stack, 1, &mut strings);
ret.push_int(7);
ret.push_int(8);
assert!(ret.overflowed());
assert_eq!(stack, vec![Value::Int64(7)]);
assert_eq!(stack.capacity(), capacity);
let mut empty = Vec::new();
let mut ret = HostReturn::new(&mut empty, 1, &mut strings);
ret.push_null();
assert!(ret.overflowed());
assert!(empty.is_empty());
assert_eq!(empty.capacity(), 0);
}
struct Collect;
impl GuestStringAllocator for Collect {
fn build(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault> {
let mut text = String::new();
writer(&mut text).unwrap();
assert_eq!(text.len(), length);
Ok(Arc::from(text))
}
}
#[test]
fn measured_native_encoding_matches_utf8_lossy_hex_and_join_semantics() {
for bytes in [
b"plain".as_slice(),
"é猫".as_bytes(),
&[0xff, 0xe2, 0x82],
&[0xf0, 0x80, 0x80, 0x80, 0x61, 0xc2, 0xa9],
&[],
] {
let mut stack = Vec::with_capacity(1);
let mut allocator = Collect;
let mut ret = HostReturn::new(&mut stack, 1, &mut allocator);
ret.push_utf8_lossy(bytes).unwrap();
assert_eq!(stack, vec![Value::string(String::from_utf8_lossy(bytes).as_ref())]);
}
for byte in 0..=255u8 {
let bytes = [b'a', byte, b'b', byte];
let mut stack = Vec::with_capacity(1);
let mut allocator = Collect;
HostReturn::new(&mut stack, 1, &mut allocator).push_utf8_lossy(&bytes).unwrap();
assert_eq!(stack, vec![Value::string(String::from_utf8_lossy(&bytes).as_ref())]);
}
let mut stack = Vec::with_capacity(2);
let mut allocator = Collect;
let mut ret = HostReturn::new(&mut stack, 2, &mut allocator);
ret.push_hex(&[0, 0x12, 0xab, 0xff]).unwrap();
ret.push_joined(["", "é", "猫"].into_iter(), ";").unwrap();
assert_eq!(stack, vec![Value::string("0012abff"), Value::string(";é;猫")]);
}
#[test]
fn full_native_result_buffer_does_not_invoke_string_allocator() {
let mut stack = Vec::with_capacity(1);
let mut allocator = RejectStrings;
let mut ret = HostReturn::new(&mut stack, 0, &mut allocator);
ret.push_string("ignored").unwrap();
assert!(ret.overflowed());
assert!(stack.is_empty());
}
}
+2
View File
@@ -36,6 +36,7 @@ pub mod telemetry;
pub mod tile;
pub mod tilemap;
pub mod touch_bridge;
pub mod value_snapshot;
pub mod vm_fault;
pub use asset_bridge::AssetBridge;
@@ -64,3 +65,4 @@ pub use render_worker::{
RenderWorkerBackend, RenderWorkerError, RenderWorkerFrameSink, RenderWorkerTelemetry,
};
pub use touch_bridge::TouchBridge;
pub use value_snapshot::ValueSnapshot;
@@ -11,6 +11,12 @@ pub use resolver::{
resolve_declared_program_syscalls, resolve_program_syscalls, resolve_syscall,
};
/// Native metadata iteration for bounded image binding. This is not guest
/// reflection; callers account comparisons before examining catalogue entries.
pub fn catalogue() -> impl Iterator<Item = &'static SyscallRegistryEntry> {
domains::all_entries()
}
/// Enumeration of all System Calls (Syscalls) available in the Prometeu environment.
///
/// Syscalls are the primary mechanism for a program running in the Virtual Machine
@@ -0,0 +1,62 @@
use prometeu_bytecode::Value;
use serde::{Deserialize, Serialize};
use std::sync::Arc;
/// Native/debug ownership only. Wire data is the ordinary list of values;
/// opaque accounting domains stay alive for every retained string allocation.
#[derive(Clone, Default, Serialize, Deserialize)]
#[serde(transparent)]
pub struct ValueSnapshot {
values: Vec<Value>,
#[serde(skip)]
owners: [Option<Arc<dyn Send + Sync>>; 2],
}
impl ValueSnapshot {
pub fn with_owners(values: Vec<Value>, owners: [Option<Arc<dyn Send + Sync>>; 2]) -> Self {
Self { values, owners }
}
pub fn retained_domains(&self) -> usize {
self.owners.iter().filter(|owner| owner.is_some()).count()
}
}
impl std::ops::Deref for ValueSnapshot {
type Target = [Value];
fn deref(&self) -> &[Value] {
&self.values
}
}
impl std::fmt::Debug for ValueSnapshot {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
self.values.fmt(f)
}
}
impl PartialEq<Vec<Value>> for ValueSnapshot {
fn eq(&self, other: &Vec<Value>) -> bool {
self.values == *other
}
}
impl From<Vec<Value>> for ValueSnapshot {
/// External/native values have no provenance and are copied on guest import.
fn from(values: Vec<Value>) -> Self {
Self::with_owners(values, [None, None])
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn serialization_contains_values_and_never_exports_native_domain_metadata() {
let owner: Arc<dyn Send + Sync> = Arc::new(17u32);
let snapshot = ValueSnapshot::with_owners(
vec![Value::string("shared"), Value::Null],
[Some(owner), None],
);
assert_eq!(snapshot.retained_domains(), 1);
let bytes = serde_json::to_string(&snapshot).unwrap();
assert_eq!(bytes, "[\"shared\",null]");
let imported: ValueSnapshot = serde_json::from_str(&bytes).unwrap();
assert_eq!(imported.retained_domains(), 0);
assert_eq!(&*imported, &*snapshot);
}
}
@@ -3,7 +3,6 @@ use crate::os::{GameLifecycleEvent, SystemOS};
use crate::task::TaskId;
use crate::vm_session::VmSession;
use crate::{RenderWorkerConfig, RenderWorkerController};
use prometeu_bytecode::Value;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame};
use prometeu_hal::{
@@ -100,7 +99,7 @@ impl<'a> VmFacade<'a> {
self.active_session().map(|session| session.vm.pc())
}
pub fn active_operand_stack_top(&self, n: usize) -> Vec<Value> {
pub fn active_operand_stack_top(&self, n: usize) -> prometeu_hal::ValueSnapshot {
self.active_session().map(|session| session.vm.operand_stack_top(n)).unwrap_or_default()
}
@@ -561,7 +561,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
.ok_or_else(|| VmFault::Panic("Invalid handle".into()))?
.clone();
match self.fs.read_file(&path) {
Ok(data) => ret.push_string(String::from_utf8_lossy(&data).into_owned()),
Ok(data) => ret.push_utf8_lossy(&data)?,
Err(_) => ret.push_null(),
}
Ok(())
@@ -588,8 +588,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
let path = expect_string(args, 0, "path")?;
match self.fs.list_dir(&path) {
Ok(entries) => {
let names: Vec<String> = entries.into_iter().map(|e| e.name).collect();
ret.push_string(names.join(";"));
ret.push_joined(entries.iter().map(|entry| entry.name.as_str()), ";")?;
}
Err(_) => ret.push_null(),
}
@@ -645,14 +644,14 @@ impl NativeInterface for VmRuntimeHost<'_> {
let max_bytes = expect_non_negative_usize(args, 2, "max_bytes")?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_string(String::new());
ret.push_string("")?;
ret.push_int(0);
return Ok(());
}
let read =
self.memcard.slot_read(self.fs, self.current_app_id, slot, offset, max_bytes);
ret.push_int(read.status as i64);
ret.push_string(hex_encode(&read.bytes));
ret.push_hex(&read.bytes)?;
ret.push_int(read.bytes_read as i64);
Ok(())
}
@@ -866,16 +865,6 @@ fn expect_non_negative_usize(args: &[Value], index: usize, field: &str) -> Resul
Ok(val as usize)
}
fn hex_encode(bytes: &[u8]) -> String {
const HEX: &[u8; 16] = b"0123456789abcdef";
let mut out = String::with_capacity(bytes.len() * 2);
for &b in bytes {
out.push(HEX[(b >> 4) as usize] as char);
out.push(HEX[(b & 0x0f) as usize] as char);
}
out
}
fn hex_decode(s: &str) -> Result<Vec<u8>, VmFault> {
fn nibble(c: u8) -> Option<u8> {
match c {
@@ -77,7 +77,11 @@ impl VirtualMachineRuntime {
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if vm.call_stack_is_empty() {
vm.prepare_boot_call();
if let Err(error) = vm.prepare_boot_call() {
let report = CrashReport::VmInit { error };
self.last_crash_report = Some(report.clone());
return Some(report);
}
}
let step_result = {
let mut ctx = HostContext::new_platform(Some(platform));
@@ -168,7 +172,11 @@ impl VirtualMachineRuntime {
self.begin_logical_frame(signals, platform);
if self.needs_prepare_entry_call || vm.call_stack_is_empty() {
vm.prepare_boot_call();
if let Err(error) = vm.prepare_boot_call() {
let report = CrashReport::VmInit { error };
self.last_crash_report = Some(report.clone());
return Some(report);
}
self.needs_prepare_entry_call = false;
}
+144 -569
View File
@@ -1,4 +1,7 @@
use prometeu_bytecode::Value;
use prometeu_bytecode::{
Value,
registry::{BuiltinId, StorageLayout},
};
use prometeu_hal::{HostContext, color::Color};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -53,14 +56,18 @@ impl IntrinsicKey {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum BuiltinScalarType {
Int,
Int32,
Int64,
Float,
Bool,
Str,
String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum AbiType {
/// Internal group components; neither can establish a valid Dynamic alone.
DynamicTag,
DynamicPayload,
Scalar(BuiltinScalarType),
Builtin(BuiltinTypeKey),
}
@@ -75,6 +82,7 @@ pub enum BuiltinLayoutType {
pub enum BuiltinTypeShape {
Scalar,
Aggregate,
Dynamic,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -111,14 +119,33 @@ impl BuiltinTypeMeta {
out
}
pub fn storage_layout(
&self,
) -> Result<StorageLayout, prometeu_bytecode::load_limits::LoadFailure> {
BuiltinId(self.id).layout()
}
pub fn validate_flat_values(&self, values: &[Value]) -> Result<(), BuiltinValueError> {
if self.shape == BuiltinTypeShape::Dynamic {
if values.len() != 2 {
return Err(BuiltinValueError::ArityMismatch { expected: 2, got: values.len() });
}
if matches!(values, [Value::Null, Value::Null]) {
return Ok(());
}
// A non-null tag is a program TypeId, and its payload may be a box.
// This context-free catalogue must never claim to validate it.
return Err(BuiltinValueError::RegistryRequired);
}
let layout = self.flatten_layout();
validate_values_against_layout(values, &layout)
}
fn flatten_into(&self, out: &mut Vec<AbiType>) {
match self.shape {
BuiltinTypeShape::Scalar => out.extend_from_slice(self.flat_slot_layout),
BuiltinTypeShape::Scalar | BuiltinTypeShape::Dynamic => {
out.extend_from_slice(self.flat_slot_layout)
}
BuiltinTypeShape::Aggregate => {
for field in self.fields {
flatten_layout_type(field.field_type, out);
@@ -134,7 +161,7 @@ pub enum BuiltinConstSlotValue {
Int64(i64),
Float(f64),
Bool(bool),
NominalBuiltin { builtin: BuiltinTypeKey, carrier: i32 },
NominalBuiltin { builtin: BuiltinTypeKey, carrier: u32 },
}
pub type BuiltinConstHook = fn() -> Vec<Value>;
@@ -178,12 +205,12 @@ impl BuiltinConstMeta {
pub enum IntrinsicExecutionError {
ArityMismatch { expected: usize, got: usize },
TypeMismatch { index: usize, expected: AbiType },
InvalidBuiltinCarrier { owner: &'static str, name: &'static str, carrier: i64 },
HardwareUnavailable,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BuiltinValueError {
RegistryRequired,
ArityMismatch { expected: usize, got: usize },
TypeMismatch { index: usize, expected: AbiType },
}
@@ -218,14 +245,28 @@ impl IntrinsicMeta {
}
pub fn validate_result_values(&self, values: &[Value]) -> Result<(), IntrinsicExecutionError> {
if values.len() != self.ret_slots() {
Self::validate_values(values, self.ret_layout)
}
pub fn validate_argument_values(
&self,
values: &[Value],
) -> Result<(), IntrinsicExecutionError> {
Self::validate_values(values, self.arg_layout)
}
fn validate_values(
values: &[Value],
layout: &[AbiType],
) -> Result<(), IntrinsicExecutionError> {
if values.len() != layout.len() {
return Err(IntrinsicExecutionError::ArityMismatch {
expected: self.ret_slots(),
expected: layout.len(),
got: values.len(),
});
}
for (index, (value, expected)) in values.iter().zip(self.ret_layout.iter()).enumerate() {
for (index, (value, expected)) in values.iter().zip(layout.iter()).enumerate() {
if !value_matches_abi_type(value, *expected) {
return Err(IntrinsicExecutionError::TypeMismatch { index, expected: *expected });
}
@@ -242,7 +283,9 @@ impl BuiltinConstSlotValue {
BuiltinConstSlotValue::Int64(value) => Value::Int64(value),
BuiltinConstSlotValue::Float(value) => Value::Float(value),
BuiltinConstSlotValue::Bool(value) => Value::Boolean(value),
BuiltinConstSlotValue::NominalBuiltin { carrier, .. } => Value::Int32(carrier),
BuiltinConstSlotValue::NominalBuiltin { carrier, .. } => {
Value::Int64(i64::from(carrier))
}
}
}
}
@@ -250,21 +293,15 @@ impl BuiltinConstSlotValue {
const COLOR: BuiltinTypeKey = BuiltinTypeKey::new("color", 1);
const VEC2: BuiltinTypeKey = BuiltinTypeKey::new("vec2", 1);
const PIXEL: BuiltinTypeKey = BuiltinTypeKey::new("pixel", 1);
const INPUT_PAD: BuiltinTypeKey = BuiltinTypeKey::new("input.pad", 1);
const INPUT_TOUCH: BuiltinTypeKey = BuiltinTypeKey::new("input.touch", 1);
const INPUT_BUTTON: BuiltinTypeKey = BuiltinTypeKey::new("input.button", 1);
const COLOR_LAYOUT: [AbiType; 1] = [AbiType::Builtin(COLOR)];
const VEC2_LAYOUT: [AbiType; 2] =
[AbiType::Scalar(BuiltinScalarType::Float), AbiType::Scalar(BuiltinScalarType::Float)];
const PIXEL_LAYOUT: [AbiType; 3] = [
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int64),
AbiType::Scalar(BuiltinScalarType::Int64),
AbiType::Builtin(COLOR),
];
const INPUT_PAD_LAYOUT: [AbiType; 1] = [AbiType::Builtin(INPUT_PAD)];
const INPUT_TOUCH_LAYOUT: [AbiType; 1] = [AbiType::Builtin(INPUT_TOUCH)];
const INPUT_BUTTON_LAYOUT: [AbiType; 1] = [AbiType::Builtin(INPUT_BUTTON)];
const VEC2_FIELDS: [BuiltinFieldMeta; 2] = [
BuiltinFieldMeta {
@@ -285,13 +322,13 @@ const PIXEL_FIELDS: [BuiltinFieldMeta; 3] = [
BuiltinFieldMeta {
name: "x",
start_slot: 0,
field_type: BuiltinLayoutType::Scalar(BuiltinScalarType::Int),
field_type: BuiltinLayoutType::Scalar(BuiltinScalarType::Int64),
flat_slot_width: 1,
},
BuiltinFieldMeta {
name: "y",
start_slot: 1,
field_type: BuiltinLayoutType::Scalar(BuiltinScalarType::Int),
field_type: BuiltinLayoutType::Scalar(BuiltinScalarType::Int64),
flat_slot_width: 1,
},
BuiltinFieldMeta {
@@ -302,7 +339,7 @@ const PIXEL_FIELDS: [BuiltinFieldMeta; 3] = [
},
];
const BUILTIN_TYPES: [BuiltinTypeMeta; 6] = [
const BUILTIN_TYPES: [BuiltinTypeMeta; 9] = [
BuiltinTypeMeta {
id: 0x0001,
name: COLOR.name,
@@ -330,35 +367,34 @@ const BUILTIN_TYPES: [BuiltinTypeMeta; 6] = [
flat_slot_layout: &PIXEL_LAYOUT,
flat_slot_width: 3,
},
scalar_meta(0x10, "Int32", &[AbiType::Scalar(BuiltinScalarType::Int32)]),
scalar_meta(0x11, "Int64", &[AbiType::Scalar(BuiltinScalarType::Int64)]),
scalar_meta(0x12, "Float", &[AbiType::Scalar(BuiltinScalarType::Float)]),
scalar_meta(0x13, "Bool", &[AbiType::Scalar(BuiltinScalarType::Bool)]),
scalar_meta(0x14, "String", &[AbiType::Scalar(BuiltinScalarType::String)]),
BuiltinTypeMeta {
id: 0x0100,
name: INPUT_PAD.name,
version: INPUT_PAD.version,
shape: BuiltinTypeShape::Scalar,
id: 0x15,
name: "Dynamic",
version: 1,
shape: BuiltinTypeShape::Dynamic,
fields: &[],
flat_slot_layout: &INPUT_PAD_LAYOUT,
flat_slot_width: 1,
},
BuiltinTypeMeta {
id: 0x0101,
name: INPUT_TOUCH.name,
version: INPUT_TOUCH.version,
shape: BuiltinTypeShape::Scalar,
fields: &[],
flat_slot_layout: &INPUT_TOUCH_LAYOUT,
flat_slot_width: 1,
},
BuiltinTypeMeta {
id: 0x0102,
name: INPUT_BUTTON.name,
version: INPUT_BUTTON.version,
shape: BuiltinTypeShape::Scalar,
fields: &[],
flat_slot_layout: &INPUT_BUTTON_LAYOUT,
flat_slot_width: 1,
flat_slot_layout: &[AbiType::DynamicTag, AbiType::DynamicPayload],
flat_slot_width: 2,
},
];
const fn scalar_meta(id: u32, name: &'static str, layout: &'static [AbiType]) -> BuiltinTypeMeta {
BuiltinTypeMeta {
id,
name,
version: 1,
shape: BuiltinTypeShape::Scalar,
fields: &[],
flat_slot_layout: layout,
flat_slot_width: 1,
}
}
const VEC2_ZERO_LAYOUT: [AbiType; 2] =
[AbiType::Scalar(BuiltinScalarType::Float), AbiType::Scalar(BuiltinScalarType::Float)];
const VEC2_ZERO_SLOTS: [BuiltinConstSlotValue; 2] =
@@ -434,27 +470,20 @@ const NO_ARGS: [AbiType; 0] = [];
const COLOR_ARGS: [AbiType; 1] = [AbiType::Builtin(COLOR)];
const COLOR_RET: [AbiType; 1] = [AbiType::Builtin(COLOR)];
const COLOR_RGB_ARGS: [AbiType; 3] = [
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int64),
AbiType::Scalar(BuiltinScalarType::Int64),
AbiType::Scalar(BuiltinScalarType::Int64),
];
const COLOR_RGBA_ARGS: [AbiType; 4] = [
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int64),
AbiType::Scalar(BuiltinScalarType::Int64),
AbiType::Scalar(BuiltinScalarType::Int64),
AbiType::Scalar(BuiltinScalarType::Int64),
];
const COLOR_HTML_RGBA_ARGS: [AbiType; 1] = [AbiType::Scalar(BuiltinScalarType::Str)];
const PAD_RET: [AbiType; 1] = [AbiType::Builtin(INPUT_PAD)];
const TOUCH_RET: [AbiType; 1] = [AbiType::Builtin(INPUT_TOUCH)];
const BUTTON_RET: [AbiType; 1] = [AbiType::Builtin(INPUT_BUTTON)];
const PAD_ARGS: [AbiType; 1] = [AbiType::Builtin(INPUT_PAD)];
const TOUCH_ARGS: [AbiType; 1] = [AbiType::Builtin(INPUT_TOUCH)];
const BUTTON_ARGS: [AbiType; 1] = [AbiType::Builtin(INPUT_BUTTON)];
const BOOL_RET: [AbiType; 1] = [AbiType::Scalar(BuiltinScalarType::Bool)];
const INT_RET: [AbiType; 1] = [AbiType::Scalar(BuiltinScalarType::Int)];
const COLOR_HTML_RGBA_ARGS: [AbiType; 1] = [AbiType::Scalar(BuiltinScalarType::String)];
const INT_RET: [AbiType; 1] = [AbiType::Scalar(BuiltinScalarType::Int64)];
const INTRINSICS: [IntrinsicMeta; 42] = [
const INTRINSICS: [IntrinsicMeta; 21] = [
IntrinsicMeta {
id: 0x1000,
owner: "vec2",
@@ -686,237 +715,6 @@ const INTRINSICS: [IntrinsicMeta; 42] = [
may_allocate: false,
implementation: color_transparent,
},
IntrinsicMeta {
id: 0x2000,
owner: "input",
name: "pad",
version: 1,
arg_layout: &NO_ARGS,
ret_layout: &PAD_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad,
},
IntrinsicMeta {
id: 0x2001,
owner: "input",
name: "touch",
version: 1,
arg_layout: &NO_ARGS,
ret_layout: &TOUCH_RET,
deterministic: true,
may_allocate: false,
implementation: input_touch,
},
IntrinsicMeta {
id: 0x2010,
owner: "input.pad",
name: "up",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_up,
},
IntrinsicMeta {
id: 0x2011,
owner: "input.pad",
name: "down",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_down,
},
IntrinsicMeta {
id: 0x2012,
owner: "input.pad",
name: "left",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_left,
},
IntrinsicMeta {
id: 0x2013,
owner: "input.pad",
name: "right",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_right,
},
IntrinsicMeta {
id: 0x2014,
owner: "input.pad",
name: "a",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_a,
},
IntrinsicMeta {
id: 0x2015,
owner: "input.pad",
name: "b",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_b,
},
IntrinsicMeta {
id: 0x2016,
owner: "input.pad",
name: "x",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_x,
},
IntrinsicMeta {
id: 0x2017,
owner: "input.pad",
name: "y",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_y,
},
IntrinsicMeta {
id: 0x2018,
owner: "input.pad",
name: "l",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_l,
},
IntrinsicMeta {
id: 0x2019,
owner: "input.pad",
name: "r",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_r,
},
IntrinsicMeta {
id: 0x201A,
owner: "input.pad",
name: "start",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_start,
},
IntrinsicMeta {
id: 0x201B,
owner: "input.pad",
name: "select",
version: 1,
arg_layout: &PAD_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_pad_select,
},
IntrinsicMeta {
id: 0x2020,
owner: "input.touch",
name: "button",
version: 1,
arg_layout: &TOUCH_ARGS,
ret_layout: &BUTTON_RET,
deterministic: true,
may_allocate: false,
implementation: input_touch_button,
},
IntrinsicMeta {
id: 0x2021,
owner: "input.touch",
name: "x",
version: 1,
arg_layout: &TOUCH_ARGS,
ret_layout: &INT_RET,
deterministic: true,
may_allocate: false,
implementation: input_touch_x,
},
IntrinsicMeta {
id: 0x2022,
owner: "input.touch",
name: "y",
version: 1,
arg_layout: &TOUCH_ARGS,
ret_layout: &INT_RET,
deterministic: true,
may_allocate: false,
implementation: input_touch_y,
},
IntrinsicMeta {
id: 0x2030,
owner: "input.button",
name: "pressed",
version: 1,
arg_layout: &BUTTON_ARGS,
ret_layout: &BOOL_RET,
deterministic: true,
may_allocate: false,
implementation: input_button_pressed,
},
IntrinsicMeta {
id: 0x2031,
owner: "input.button",
name: "released",
version: 1,
arg_layout: &BUTTON_ARGS,
ret_layout: &BOOL_RET,
deterministic: true,
may_allocate: false,
implementation: input_button_released,
},
IntrinsicMeta {
id: 0x2032,
owner: "input.button",
name: "down",
version: 1,
arg_layout: &BUTTON_ARGS,
ret_layout: &BOOL_RET,
deterministic: true,
may_allocate: false,
implementation: input_button_down,
},
IntrinsicMeta {
id: 0x2033,
owner: "input.button",
name: "hold",
version: 1,
arg_layout: &BUTTON_ARGS,
ret_layout: &INT_RET,
deterministic: true,
may_allocate: false,
implementation: input_button_hold,
},
];
pub fn lookup_builtin_type(name: &str, version: u16) -> Option<&'static BuiltinTypeMeta> {
@@ -944,11 +742,15 @@ pub fn materialize_builtin_constant(
pub fn lookup_intrinsic(owner: &str, name: &str, version: u16) -> Option<&'static IntrinsicMeta> {
INTRINSICS
.iter()
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.find(|meta| meta.owner == owner && meta.name == name && meta.version == version)
}
pub fn lookup_intrinsic_by_id(id: u32) -> Option<&'static IntrinsicMeta> {
INTRINSICS.iter().find(|meta| meta.id == id)
INTRINSICS
.iter()
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.find(|meta| meta.id == id)
}
fn flatten_layout_type(layout_type: BuiltinLayoutType, out: &mut Vec<AbiType>) {
@@ -967,20 +769,26 @@ fn expect_float_arg(args: &[Value], index: usize) -> Result<f64, IntrinsicExecut
let value = args
.get(index)
.ok_or(IntrinsicExecutionError::ArityMismatch { expected: index + 1, got: args.len() })?;
value.as_float().ok_or(IntrinsicExecutionError::TypeMismatch {
index,
expected: AbiType::Scalar(BuiltinScalarType::Float),
})
match value {
Value::Float(value) => Ok(*value),
_ => Err(IntrinsicExecutionError::TypeMismatch {
index,
expected: AbiType::Scalar(BuiltinScalarType::Float),
}),
}
}
fn expect_int_arg(args: &[Value], index: usize) -> Result<i64, IntrinsicExecutionError> {
let value = args
.get(index)
.ok_or(IntrinsicExecutionError::ArityMismatch { expected: index + 1, got: args.len() })?;
value.as_integer().ok_or(IntrinsicExecutionError::TypeMismatch {
index,
expected: AbiType::Scalar(BuiltinScalarType::Int),
})
match value {
Value::Int64(value) => Ok(*value),
_ => Err(IntrinsicExecutionError::TypeMismatch {
index,
expected: AbiType::Scalar(BuiltinScalarType::Int64),
}),
}
}
fn expect_string_arg(args: &[Value], index: usize) -> Result<&str, IntrinsicExecutionError> {
@@ -991,18 +799,24 @@ fn expect_string_arg(args: &[Value], index: usize) -> Result<&str, IntrinsicExec
Value::String(value) => Ok(value.as_ref()),
_ => Err(IntrinsicExecutionError::TypeMismatch {
index,
expected: AbiType::Scalar(BuiltinScalarType::Str),
expected: AbiType::Scalar(BuiltinScalarType::String),
}),
}
}
fn value_matches_abi_type(value: &Value, expected: AbiType) -> bool {
match expected {
AbiType::Scalar(BuiltinScalarType::Int) => value.as_integer().is_some(),
AbiType::Scalar(BuiltinScalarType::Float) => value.as_float().is_some(),
AbiType::Scalar(BuiltinScalarType::Int32) => matches!(value, Value::Int32(_)),
AbiType::Scalar(BuiltinScalarType::Int64) => matches!(value, Value::Int64(_)),
AbiType::Scalar(BuiltinScalarType::Float) => matches!(value, Value::Float(_)),
AbiType::Scalar(BuiltinScalarType::Bool) => matches!(value, Value::Boolean(_)),
AbiType::Scalar(BuiltinScalarType::Str) => matches!(value, Value::String(_)),
AbiType::Builtin(_) => value.as_integer().is_some(),
AbiType::Scalar(BuiltinScalarType::String) => {
matches!(value, Value::String(_) | Value::Null)
}
AbiType::Builtin(key) if key == COLOR => {
matches!(value, Value::Int64(raw) if u32::try_from(*raw).is_ok())
}
AbiType::Builtin(_) | AbiType::DynamicTag | AbiType::DynamicPayload => false,
}
}
@@ -1023,11 +837,6 @@ fn validate_values_against_layout(
Ok(())
}
const PAD_HANDLE: i64 = 1;
const TOUCH_HANDLE: i64 = 1;
const PAD_BUTTON_BASE: i64 = 0x100;
const TOUCH_BUTTON_CARRIER: i64 = 0x200;
fn vec2_dot(
args: &[Value],
_ctx: &mut HostContext<'_>,
@@ -1069,7 +878,7 @@ fn expect_channel(args: &[Value], index: usize) -> Result<u8, IntrinsicExecution
let value = expect_int_arg(args, index)?;
u8::try_from(value).map_err(|_| IntrinsicExecutionError::TypeMismatch {
index,
expected: AbiType::Scalar(BuiltinScalarType::Int),
expected: AbiType::Scalar(BuiltinScalarType::Int64),
})
}
@@ -1088,7 +897,7 @@ fn color_from_raw(
let raw = u32::try_from(expect_int_arg(args, 0)?).map_err(|_| {
IntrinsicExecutionError::TypeMismatch {
index: 0,
expected: AbiType::Scalar(BuiltinScalarType::Int),
expected: AbiType::Scalar(BuiltinScalarType::Int64),
}
})?;
Ok(color_value(Color::from_raw(raw)))
@@ -1124,7 +933,7 @@ fn color_html_rgba(
let color = parse_html_rgba(expect_string_arg(args, 0)?).ok_or({
IntrinsicExecutionError::TypeMismatch {
index: 0,
expected: AbiType::Scalar(BuiltinScalarType::Str),
expected: AbiType::Scalar(BuiltinScalarType::String),
}
})?;
Ok(color_value(color))
@@ -1227,254 +1036,6 @@ fn color_transparent(
color_const(Color::TRANSPARENT)
}
fn input_pad(
_args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
Ok(vec![Value::Int64(PAD_HANDLE)])
}
fn input_touch(
_args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
Ok(vec![Value::Int64(TOUCH_HANDLE)])
}
fn input_pad_up(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "up")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE)])
}
fn input_pad_down(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "down")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 1)])
}
fn input_pad_left(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "left")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 2)])
}
fn input_pad_right(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "right")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 3)])
}
fn input_pad_a(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "a")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 4)])
}
fn input_pad_b(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "b")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 5)])
}
fn input_pad_x(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "x")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 6)])
}
fn input_pad_y(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "y")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 7)])
}
fn input_pad_l(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "l")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 8)])
}
fn input_pad_r(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "r")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 9)])
}
fn input_pad_start(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "start")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 10)])
}
fn input_pad_select(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_pad_handle(args, "select")?;
Ok(vec![Value::Int64(PAD_BUTTON_BASE + 11)])
}
fn input_touch_button(
args: &[Value],
_ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_touch_handle(args, "button")?;
Ok(vec![Value::Int64(TOUCH_BUTTON_CARRIER)])
}
fn input_touch_x(
args: &[Value],
ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_touch_handle(args, "x")?;
let platform =
ctx.require_platform().map_err(|_| IntrinsicExecutionError::HardwareUnavailable)?;
Ok(vec![Value::Int64(platform.input().touch().x() as i64)])
}
fn input_touch_y(
args: &[Value],
ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
expect_touch_handle(args, "y")?;
let platform =
ctx.require_platform().map_err(|_| IntrinsicExecutionError::HardwareUnavailable)?;
Ok(vec![Value::Int64(platform.input().touch().y() as i64)])
}
fn input_button_pressed(
args: &[Value],
ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
let button = resolve_button(args, "pressed", ctx)?;
Ok(vec![Value::Boolean(button.pressed)])
}
fn input_button_released(
args: &[Value],
ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
let button = resolve_button(args, "released", ctx)?;
Ok(vec![Value::Boolean(button.released)])
}
fn input_button_down(
args: &[Value],
ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
let button = resolve_button(args, "down", ctx)?;
Ok(vec![Value::Boolean(button.down)])
}
fn input_button_hold(
args: &[Value],
ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
let button = resolve_button(args, "hold", ctx)?;
Ok(vec![Value::Int64(button.hold_frames as i64)])
}
fn expect_pad_handle(args: &[Value], name: &'static str) -> Result<(), IntrinsicExecutionError> {
let carrier = expect_builtin_carrier(args, 0)?;
if carrier != PAD_HANDLE {
return Err(IntrinsicExecutionError::InvalidBuiltinCarrier {
owner: "input.pad",
name,
carrier,
});
}
Ok(())
}
fn expect_touch_handle(args: &[Value], name: &'static str) -> Result<(), IntrinsicExecutionError> {
let carrier = expect_builtin_carrier(args, 0)?;
if carrier != TOUCH_HANDLE {
return Err(IntrinsicExecutionError::InvalidBuiltinCarrier {
owner: "input.touch",
name,
carrier,
});
}
Ok(())
}
fn expect_builtin_carrier(args: &[Value], index: usize) -> Result<i64, IntrinsicExecutionError> {
let value = args
.get(index)
.ok_or(IntrinsicExecutionError::ArityMismatch { expected: index + 1, got: args.len() })?;
value.as_integer().ok_or(IntrinsicExecutionError::TypeMismatch {
index,
expected: AbiType::Scalar(BuiltinScalarType::Int),
})
}
fn resolve_button(
args: &[Value],
name: &'static str,
ctx: &mut HostContext<'_>,
) -> Result<prometeu_hal::button::Button, IntrinsicExecutionError> {
let carrier = expect_builtin_carrier(args, 0)?;
let platform =
ctx.require_platform().map_err(|_| IntrinsicExecutionError::HardwareUnavailable)?;
let input = platform.input();
if carrier == TOUCH_BUTTON_CARRIER {
return Ok(*input.touch().f());
}
let Some(index) = carrier.checked_sub(PAD_BUTTON_BASE) else {
return Err(IntrinsicExecutionError::InvalidBuiltinCarrier {
owner: "input.button",
name,
carrier,
});
};
let button = match index {
0 => *input.pad().up(),
1 => *input.pad().down(),
2 => *input.pad().left(),
3 => *input.pad().right(),
4 => *input.pad().a(),
5 => *input.pad().b(),
6 => *input.pad().x(),
7 => *input.pad().y(),
8 => *input.pad().l(),
9 => *input.pad().r(),
10 => *input.pad().start(),
11 => *input.pad().select(),
_ => {
return Err(IntrinsicExecutionError::InvalidBuiltinCarrier {
owner: "input.button",
name,
carrier,
});
}
};
Ok(button)
}
#[cfg(test)]
mod tests {
use super::*;
@@ -1501,8 +1062,8 @@ mod tests {
assert_eq!(
pixel.flatten_layout(),
vec![
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int),
AbiType::Scalar(BuiltinScalarType::Int64),
AbiType::Scalar(BuiltinScalarType::Int64),
AbiType::Builtin(COLOR),
]
);
@@ -1570,8 +1131,8 @@ mod tests {
assert_eq!(lookup_intrinsic_by_id(length.id).map(|meta| meta.key()), Some(length.key()));
let hold =
lookup_intrinsic("input.button", "hold", 1).expect("input.button.hold must exist");
assert_eq!(hold.arg_layout.len(), 1);
lookup_intrinsic("input.pad.up", "hold", 1).expect("input.pad.up.hold must exist");
assert_eq!(hold.arg_layout.len(), 0);
assert_eq!(hold.ret_layout.len(), 1);
assert!(hold.deterministic);
assert!(!hold.may_allocate);
@@ -1621,7 +1182,7 @@ mod tests {
fn input_intrinsic_requires_hardware_context() {
let mut ctx = HostContext::new(None);
let touch_x = lookup_intrinsic("input.touch", "x", 1).expect("input.touch.x must exist");
let err = (touch_x.implementation)(&[Value::Int64(TOUCH_HANDLE)], &mut ctx)
let err = (touch_x.implementation)(&[], &mut ctx)
.expect_err("touch.x must fail without hardware context");
assert_eq!(err, IntrinsicExecutionError::HardwareUnavailable);
}
@@ -1629,9 +1190,23 @@ mod tests {
#[test]
fn pixel_flat_values_validate_with_color_carrier_slot() {
let pixel = lookup_builtin_type("pixel", 1).expect("pixel builtin must exist");
let values = vec![Value::Int32(1), Value::Int32(2), Value::Int32(0xF800)];
let values = vec![Value::Int64(1), Value::Int64(2), Value::Int64(0xF800)];
pixel.validate_flat_values(&values).expect("pixel flat values must validate");
assert_eq!(pixel.flat_slot_width, 3);
assert_eq!(pixel.field("color").map(|field| field.start_slot), Some(2));
}
}
/// Loader-side lookup charges each catalogue record before examining it.
pub(crate) fn metered_lookup_intrinsic(
id: u32,
budget: &mut prometeu_bytecode::load_limits::LoadBudget,
) -> Result<Option<&'static IntrinsicMeta>, prometeu_bytecode::load_limits::LoadFailure> {
for meta in INTRINSICS.iter().chain(crate::input_intrinsics::INPUT_INTRINSICS.iter()) {
budget.work(1)?;
if meta.id == id {
return Ok(Some(meta));
}
}
Ok(None)
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,147 @@
//! Exact-width immutable native storage for a present multi-slot Dynamic.
use crate::resource_budget::{
Reservation, ResourceFailure, ResourceReason, RuntimeBudget, RuntimeResource as Q,
};
use crate::value_contract::ValueError;
use prometeu_bytecode::Value;
use prometeu_bytecode::registry::{Registry, TypeId};
use std::alloc::{Layout, alloc, dealloc};
use std::ptr::NonNull;
use std::sync::Arc;
#[derive(Debug)]
pub(super) struct DynamicBox {
registry: Arc<Registry>,
type_id: TypeId,
values: Box<[Value]>,
charge: Reservation,
}
impl DynamicBox {
/// Heap validates the exact non-Dynamic multi-slot group before construction.
/// Source owners remain borrowed until publication; allocation never invokes GC.
pub fn new(
registry: Arc<Registry>,
type_id: TypeId,
values: &[Value],
budget: &RuntimeBudget,
) -> Result<Self, ResourceFailure> {
let bytes = budget.bytes::<Value>(values.len(), Q::GuestBytes)?;
let layout = Layout::array::<Value>(values.len())
.map_err(|_| budget.failure(Q::GuestBytes, ResourceReason::SizeOverflow, bytes))?;
let charge = budget.reserve(Q::GuestBytes, bytes)?;
let ptr = if values.is_empty() {
NonNull::dangling()
} else {
// SAFETY: checked nonzero array layout; a null allocator result is a
// recoverable resource failure and drops the provisional reservation.
NonNull::new(unsafe { alloc(layout) }.cast::<Value>()).ok_or_else(|| {
budget.failure(Q::GuestBytes, ResourceReason::AllocationFailed, bytes)
})?
};
let mut pending = PendingValues { ptr, layout, initialized: 0 };
for value in values {
let cloned = value.clone();
// SAFETY: initialized advances within the exactly allocated Value array;
// ptr::write moves each owner into an unused, aligned native slot.
unsafe {
ptr.as_ptr().add(pending.initialized).write(cloned);
}
pending.initialized += 1;
}
// SAFETY: allocation came from the global allocator with precisely the
// Box<[Value]> layout; all elements are initialized. Transfer ownership
// without Vec capacity/shrink reallocations or a second allocation.
let boxed = unsafe {
Box::from_raw(std::ptr::slice_from_raw_parts_mut(ptr.as_ptr(), values.len()))
};
std::mem::forget(pending);
Ok(Self { registry, type_id, values: boxed, charge })
}
pub fn bytes(&self) -> u64 {
self.charge.amount()
}
pub fn values(&self) -> &[Value] {
&self.values
}
pub fn typed_values(
&self,
registry: &Registry,
type_id: TypeId,
) -> Result<&[Value], ValueError> {
if !std::ptr::eq(self.registry.as_ref(), registry) || self.type_id != type_id {
return Err(ValueError::Type);
}
Ok(&self.values)
}
}
/// Owns the partially initialized allocation until Box takes over. A panic
/// while constructing an owner drops only the initialized prefix, then frees it.
struct PendingValues {
ptr: NonNull<Value>,
layout: Layout,
initialized: usize,
}
impl Drop for PendingValues {
fn drop(&mut self) {
// SAFETY: initialized counts constructed Values only, all uniquely owned.
unsafe {
std::ptr::drop_in_place(std::ptr::slice_from_raw_parts_mut(
self.ptr.as_ptr(),
self.initialized,
));
if self.layout.size() != 0 {
dealloc(self.ptr.as_ptr().cast(), self.layout);
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn interrupted_native_initialization_drops_the_constructed_prefix_and_refunds() {
let budget = RuntimeBudget::default();
let text: Arc<str> = Arc::from("partially initialized");
let result = std::panic::catch_unwind(|| {
let layout = Layout::array::<Value>(3).unwrap();
let _charge = budget.reserve(Q::GuestBytes, layout.size() as u64).unwrap();
// SAFETY: checked nonzero layout; only the first slot is initialized.
let ptr = NonNull::new(unsafe { alloc(layout) }.cast::<Value>()).unwrap();
let mut pending = PendingValues { ptr, layout, initialized: 0 };
unsafe {
ptr.as_ptr().write(Value::String(text.clone()));
}
pending.initialized = 1;
assert_eq!(Arc::strong_count(&text), 2);
panic!("simulate interrupted construction before the next native slot");
});
assert!(result.is_err());
assert_eq!(Arc::strong_count(&text), 1);
assert_eq!(budget.used(Q::GuestBytes), 0);
}
#[test]
fn zero_width_storage_owns_no_allocation_and_is_not_a_valid_guest_box() {
let registry = crate::typed_storage::tests::fixture_registry();
let budget = RuntimeBudget::default();
let empty = DynamicBox::new(registry, TypeId(5), &[], &budget).unwrap();
assert!(empty.values().is_empty());
assert_eq!(empty.bytes(), 0);
drop(empty);
assert_eq!(budget.used(Q::GuestBytes), 0);
// Heap's group validator rejects empty values before invoking this storage constructor.
let mut heap = crate::heap::Heap::with_budget(&budget);
assert_eq!(
heap.allocate_dynamic_box(
crate::typed_storage::tests::fixture_registry(),
TypeId(5),
&[]
)
.unwrap_err(),
ValueError::Type
);
}
}
@@ -0,0 +1,436 @@
use super::*;
use crate::resource_budget::{ResourceReason, RuntimeLimits};
use crate::typed_storage::tests::fixture_registry;
use crate::value_contract::{
ValueError as E, can_unpack_dynamic as can_unpack, pack_dynamic as pack,
unpack_dynamic as unpack,
};
use prometeu_bytecode::load_limits::LoadBudget;
use prometeu_bytecode::registry::ImplementationDecl;
const I32: TypeId = TypeId(0);
const I64: TypeId = TypeId(1);
const COLOR: TypeId = TypeId(4);
const VEC: TypeId = TypeId(5);
const PIXEL: TypeId = TypeId(6);
const STRING: TypeId = TypeId(7);
const DYNAMIC: TypeId = TypeId(8);
const ENEMY: TypeId = TypeId(9);
const OTHER: TypeId = TypeId(10);
const MIXED: TypeId = TypeId(11);
const TRAIT: TypeId = TypeId(12);
const INTS: TypeId = TypeId(13);
const DYNAMICS: TypeId = TypeId(18);
fn payload_handle(values: &[Value]) -> HeapRef {
let [Value::Int64(_), Value::HeapRef(r)] = values else { panic!("boxed Dynamic pair") };
*r
}
fn forge_box(heap: &mut Heap, registry: Arc<Registry>, ty: TypeId, values: &[Value]) -> HeapRef {
let dynamic_box = DynamicBox::new(registry, ty, values, &heap.budget).unwrap();
heap.insert_object(StoredObject {
header: ObjectHeader::new(ObjectKind::DynamicBox, values.len() as u32),
payload: BudgetVec::new(&heap.budget, Q::GuestBytes),
array_elems: None,
closure_env: None,
coroutine: None,
typed: None,
dynamic_box: Some(dynamic_box),
})
.unwrap()
}
#[test]
fn multi_slot_pack_has_one_exact_charged_box_and_immutable_copied_values() {
let registry = fixture_registry();
let budget = RuntimeBudget::default();
let mut heap = Heap::with_budget(&budget);
for (ty, mut input) in [
(VEC, vec![Value::Float(1.25), Value::Float(-2.5)]),
(
PIXEL,
vec![Value::Int64(i64::MIN), Value::Int64(i64::MAX), Value::Int64(u32::MAX.into())],
),
] {
let before = budget.used(Q::GuestBytes);
let original = input.clone();
let dynamic = pack(&registry, &mut heap, ty, &input).unwrap();
assert_eq!(
budget.used(Q::GuestBytes) - before,
(size_of::<StoredObject>() + input.len() * size_of::<Value>()) as u64
);
let r = payload_handle(dynamic.as_slice());
assert_eq!(heap.header(r).unwrap().kind, ObjectKind::DynamicBox);
assert_eq!(heap.dynamic_box_values(&registry, r, ty).unwrap().len(), input.len());
input.fill(Value::Null);
assert_eq!(unpack(&registry, &heap, ty, dynamic.as_slice()).unwrap().as_slice(), original);
assert!(can_unpack(&registry, &heap, ty, dynamic.as_slice()).unwrap());
assert!(
!can_unpack(&registry, &heap, if ty == VEC { PIXEL } else { VEC }, dynamic.as_slice())
.unwrap()
);
}
assert_eq!(heap.len(), 2);
assert_eq!(budget.used(Q::GuestBytes), heap.used_bytes.load(Ordering::Relaxed) as u64);
heap.sweep();
assert_eq!(budget.used(Q::GuestBytes), 0);
}
#[test]
fn repack_and_dynamic_extraction_preserve_the_pair_without_another_box() {
let registry = fixture_registry();
let mut heap = Heap::new();
let first = pack(&registry, &mut heap, VEC, &[Value::Float(3.0), Value::Float(4.0)]).unwrap();
for _ in 0..100 {
let again = pack(&registry, &mut heap, DYNAMIC, first.as_slice()).unwrap();
let extracted = unpack(&registry, &heap, DYNAMIC, again.as_slice()).unwrap();
assert_eq!(extracted.as_slice(), first.as_slice());
assert!(can_unpack(&registry, &heap, DYNAMIC, again.as_slice()).unwrap());
}
assert_eq!(heap.allocation_count(), 1);
assert_eq!(heap.len(), 1);
}
#[test]
fn scalar_string_and_reference_payloads_are_direct_and_exact() {
let registry = fixture_registry();
let mut heap = Heap::new();
let enemy = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
let text: Arc<str> = Arc::from("shared");
let before = heap.allocation_count();
for (ty, input) in [
(I32, Value::Int32(7)),
(I64, Value::Int64(7)),
(COLOR, Value::Int64(7)),
(STRING, Value::String(text.clone())),
(ENEMY, Value::HeapRef(enemy)),
] {
let dynamic = pack(&registry, &mut heap, ty, std::slice::from_ref(&input)).unwrap();
let result = unpack(&registry, &heap, ty, dynamic.as_slice()).unwrap();
assert_eq!(result.as_slice(), [input]);
if let [Value::String(alias)] = result.as_slice() {
assert!(Arc::ptr_eq(alias, &text));
}
if ty == I64 {
assert!(!can_unpack(&registry, &heap, COLOR, dynamic.as_slice()).unwrap());
}
if ty == COLOR {
assert!(!can_unpack(&registry, &heap, I64, dynamic.as_slice()).unwrap());
}
if ty == ENEMY {
assert!(!can_unpack(&registry, &heap, TRAIT, dynamic.as_slice()).unwrap());
}
}
assert_eq!(heap.allocation_count(), before);
assert_eq!(Arc::strong_count(&text), 1);
}
#[test]
fn null_compatibility_preserves_typed_identity_and_rebuilds_absent_trait() {
let registry = fixture_registry();
let mut heap = Heap::new();
let untyped = [Value::Null, Value::Null];
for ty in [STRING, ENEMY, OTHER, TRAIT, INTS] {
assert!(can_unpack(&registry, &heap, ty, &untyped).unwrap());
let absent = registry.type_layout(ty).unwrap().storage.default_values();
assert_eq!(unpack(&registry, &heap, ty, &untyped).unwrap().as_slice(), absent);
let typed = pack(&registry, &mut heap, ty, absent).unwrap();
assert_eq!(typed.as_slice(), [Value::Int64(ty.0.into()), Value::Null]);
assert_eq!(unpack(&registry, &heap, ty, typed.as_slice()).unwrap().as_slice(), absent);
let other = if ty == STRING { ENEMY } else { STRING };
assert!(!can_unpack(&registry, &heap, other, typed.as_slice()).unwrap());
assert_eq!(unpack(&registry, &heap, other, typed.as_slice()).unwrap_err(), E::Type);
}
for ty in [I32, VEC, PIXEL] {
assert!(!can_unpack(&registry, &heap, ty, &untyped).unwrap());
assert_eq!(unpack(&registry, &heap, ty, &untyped).unwrap_err(), E::Type);
}
assert_eq!(pack(&registry, &mut heap, DYNAMIC, &untyped).unwrap().as_slice(), untyped);
assert_eq!(heap.allocation_count(), 0);
}
#[test]
fn trait_box_keeps_receiver_identity_and_gc_reaches_through_typed_dynamic_storage() {
let registry = fixture_registry();
let mut heap = Heap::new();
let receiver = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
let source = [Value::HeapRef(receiver), Value::Int64(0)];
// A safepoint before pack sees the original source reference.
heap.mark_from_roots([receiver]).unwrap();
heap.sweep();
let dynamic = pack(&registry, &mut heap, TRAIT, &source).unwrap();
let r = payload_handle(dynamic.as_slice());
let holder = heap.allocate_typed_array(registry.clone(), DYNAMICS, 2).unwrap();
heap.store_typed(&registry, holder, 0, dynamic.as_slice()).unwrap();
heap.store_typed(&registry, holder, 1, dynamic.as_slice()).unwrap();
assert_eq!(heap.len(), 3); // Receiver, one shared box, holder.
heap.mark_from_roots([holder]).unwrap();
heap.sweep();
assert!(heap.is_valid(receiver));
assert!(heap.is_valid(r));
assert_eq!(unpack(&registry, &heap, TRAIT, dynamic.as_slice()).unwrap().as_slice(), source);
heap.store_typed(&registry, holder, 0, &[Value::Null, Value::Null]).unwrap();
heap.mark_from_roots([holder]).unwrap();
heap.sweep();
assert!(heap.is_valid(r)); // Second alias still owns reachability.
heap.store_typed(&registry, holder, 1, &[Value::Null, Value::Null]).unwrap();
heap.mark_from_roots([holder]).unwrap();
heap.sweep();
assert!(!heap.is_valid(r));
assert!(!heap.is_valid(receiver));
}
#[test]
fn box_is_not_a_guest_instance_or_collection_and_cannot_be_a_trait_receiver() {
let registry = fixture_registry();
let mut heap = Heap::new();
let dynamic = pack(&registry, &mut heap, VEC, &[Value::Float(0.0), Value::Float(0.0)]).unwrap();
let r = payload_handle(dynamic.as_slice());
assert_eq!(heap.load_typed(&registry, r, 0).unwrap_err(), E::Type);
assert_eq!(heap.store_typed(&registry, r, 0, &[Value::Float(1.0)]).unwrap_err(), E::Type);
assert_eq!(
value_contract::validate(&registry, &heap, ENEMY, &[Value::HeapRef(r)]).unwrap_err(),
E::Type
);
assert_eq!(
value_contract::validate(&registry, &heap, TRAIT, &[Value::HeapRef(r), Value::Int64(0)])
.unwrap_err(),
E::Type
);
assert_eq!(heap.concrete_type(r, &registry).unwrap_err(), E::Type);
}
#[test]
fn malformed_dynamic_queries_fault_before_reporting_ordinary_mismatch() {
let registry = fixture_registry();
let mut heap = Heap::new();
let receiver = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
for bad in [
vec![],
vec![Value::Null],
vec![Value::Null, Value::Int64(0)],
vec![Value::Int64(DYNAMIC.0.into()), Value::Null],
vec![Value::Int64(VEC.0.into()), Value::HeapRef(receiver)],
vec![Value::Int64(VEC.0.into()), Value::HeapRef(HeapRef::NULL)],
vec![Value::Int64(u32::MAX as i64 + 1), Value::Null],
vec![Value::Int64(999), Value::Null],
vec![Value::Int64(I32.0.into()), Value::Int64(0)],
] {
assert_eq!(can_unpack(&registry, &heap, STRING, &bad).unwrap_err(), E::Type);
assert_eq!(unpack(&registry, &heap, STRING, &bad).unwrap_err(), E::Type);
}
let stale = heap
.allocate_dynamic_box(registry.clone(), VEC, &[Value::Float(1.0), Value::Float(2.0)])
.unwrap();
heap.sweep();
let live = heap
.allocate_dynamic_box(registry.clone(), VEC, &[Value::Float(3.0), Value::Float(4.0)])
.unwrap();
assert_eq!(stale.index, live.index);
assert_ne!(stale.generation, live.generation);
for handle in [
stale,
HeapRef { index: live.index, generation: 0 },
HeapRef { index: u32::MAX, generation: 1 },
] {
let bad = [Value::Int64(VEC.0.into()), Value::HeapRef(handle)];
assert_eq!(can_unpack(&registry, &heap, STRING, &bad).unwrap_err(), E::InvalidHandle);
}
}
#[test]
fn forged_box_category_type_width_group_and_registry_are_rejected() {
let registry = fixture_registry();
let mut heap = Heap::new();
let receiver = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
let wrong_boxes = [
forge_box(&mut heap, registry.clone(), VEC, &[Value::Float(1.0)]),
forge_box(&mut heap, registry.clone(), VEC, &[Value::Float(1.0), Value::Int64(2)]),
forge_box(&mut heap, registry.clone(), TRAIT, &[Value::HeapRef(receiver), Value::Int64(0)]),
forge_box(&mut heap, fixture_registry(), VEC, &[Value::Float(1.0), Value::Float(2.0)]),
heap.allocate_object(ObjectKind::DynamicBox, &[]).unwrap(),
];
for r in wrong_boxes {
assert_eq!(
can_unpack(&registry, &heap, STRING, &[Value::Int64(VEC.0.into()), Value::HeapRef(r)])
.unwrap_err(),
E::Type
);
}
for contents in
[vec![Value::Null, Value::Null], vec![Value::HeapRef(receiver), Value::Int64(1)]]
{
let r = forge_box(&mut heap, registry.clone(), TRAIT, &contents);
assert_eq!(
can_unpack(&registry, &heap, TRAIT, &[Value::Int64(TRAIT.0.into()), Value::HeapRef(r)])
.unwrap_err(),
E::Type
);
}
let r = forge_box(&mut heap, registry.clone(), VEC, &[Value::Float(1.0), Value::Float(2.0)]);
heap.objects[r.index as usize].as_mut().unwrap().header.payload_len = 3;
assert_eq!(heap.dynamic_box_values(&registry, r, VEC).unwrap_err(), E::Type);
}
#[test]
fn invalid_pack_never_allocates_or_consumes_source_values() {
let registry = fixture_registry();
let budget = RuntimeBudget::default();
let mut heap = Heap::with_budget(&budget);
for (ty, input) in [
(VEC, vec![Value::Float(1.0)]),
(PIXEL, vec![Value::Int64(0), Value::Int64(0), Value::Int64(-1)]),
(TRAIT, vec![Value::Null, Value::Int64(0)]),
(DYNAMIC, vec![Value::Null, Value::Int64(0)]),
] {
let copy = input.clone();
assert_eq!(pack(&registry, &mut heap, ty, &input).unwrap_err(), E::Type);
assert_eq!(input, copy);
assert_eq!(heap.len(), 0);
assert_eq!(budget.used(Q::GuestBytes), 0);
}
// The lower-level allocator also rejects categories that must never box.
for (ty, input) in [
(I32, vec![Value::Int32(0)]),
(TRAIT, vec![Value::Null, Value::Null]),
(DYNAMIC, vec![Value::Null, Value::Null]),
(DYNAMIC, vec![Value::Int64(I32.0.into()), Value::Int32(1)]),
] {
assert_eq!(heap.allocate_dynamic_box(registry.clone(), ty, &input).unwrap_err(), E::Type);
}
assert_eq!(heap.allocation_count(), 0);
}
#[test]
fn box_guest_quota_boundary_and_late_table_failure_refund_all_reservations() {
let registry = fixture_registry();
let bytes = (size_of::<StoredObject>() + 2 * size_of::<Value>()) as u64;
for limit in [bytes - 1, bytes] {
let budget =
RuntimeBudget::new(RuntimeLimits::default().lowered(Q::GuestBytes, limit).unwrap());
let mut heap = Heap::with_budget(&budget);
let source = [Value::Float(1.0), Value::Float(2.0)];
let result = pack(&registry, &mut heap, VEC, &source);
if limit == bytes {
assert!(result.is_ok());
assert_eq!(budget.used(Q::GuestBytes), bytes);
} else {
assert!(
matches!(result, Err(E::Resource(e)) if e.resource == Q::GuestBytes && e.reason == ResourceReason::Limit)
);
assert_eq!(heap.allocation_count(), 0);
for q in [Q::GuestBytes, Q::HandleSlots, Q::AuxiliaryBytes, Q::TemporaryBytes] {
assert_eq!(budget.used(q), 0);
}
}
assert_eq!(source, [Value::Float(1.0), Value::Float(2.0)]);
}
let budget =
RuntimeBudget::new(RuntimeLimits::default().lowered(Q::AuxiliaryBytes, 0).unwrap());
let mut heap = Heap::with_budget(&budget);
assert!(
matches!(pack(&registry, &mut heap, VEC, &[Value::Float(1.0), Value::Float(2.0)]), Err(E::Resource(e)) if e.resource == Q::AuxiliaryBytes)
);
assert_eq!(heap.len(), 0);
for q in [Q::GuestBytes, Q::HandleSlots, Q::AuxiliaryBytes, Q::TemporaryBytes] {
assert_eq!(budget.used(q), 0);
}
}
#[test]
fn query_and_unpack_succeed_at_full_heap_quota_without_allocating() {
let registry = fixture_registry();
let bytes = (size_of::<StoredObject>() + 2 * size_of::<Value>()) as u64;
let budget =
RuntimeBudget::new(RuntimeLimits::default().lowered(Q::GuestBytes, bytes).unwrap());
let mut heap = Heap::with_budget(&budget);
let dynamic = pack(&registry, &mut heap, VEC, &[Value::Float(1.0), Value::Float(2.0)]).unwrap();
for _ in 0..100 {
assert!(can_unpack(&registry, &heap, VEC, dynamic.as_slice()).unwrap());
assert_eq!(
unpack(&registry, &heap, VEC, dynamic.as_slice()).unwrap().as_slice(),
[Value::Float(1.0), Value::Float(2.0)]
);
assert_eq!(
pack(&registry, &mut heap, DYNAMIC, dynamic.as_slice()).unwrap().as_slice(),
dynamic.as_slice()
);
}
assert_eq!(heap.allocation_count(), 1);
assert_eq!(budget.used(Q::GuestBytes), bytes);
assert_eq!(budget.used(Q::TemporaryBytes), 0);
}
#[test]
fn collecting_a_trait_box_drops_transitive_native_owners_once() {
let mut declarations = fixture_registry().declarations().clone();
declarations.implementations.push(ImplementationDecl {
owner: MIXED,
trait_id: TRAIT,
methods: vec![],
});
let registry = Arc::new(
Registry::resolve(declarations, 0, &mut LoadBudget::new(Default::default())).unwrap(),
);
let mut heap = Heap::new();
let text: Arc<str> = Arc::from("retained through boxed trait");
let receiver = heap.allocate_typed_struct(registry.clone(), MIXED).unwrap();
heap.store_typed(&registry, receiver, 3, &[Value::String(text.clone())]).unwrap();
let dynamic =
pack(&registry, &mut heap, TRAIT, &[Value::HeapRef(receiver), Value::Int64(2)]).unwrap();
// Receiver -> Dynamic box -> receiver is a real typed heap cycle.
heap.store_typed(&registry, receiver, 4, dynamic.as_slice()).unwrap();
let r = payload_handle(dynamic.as_slice());
heap.mark_from_roots([r]).unwrap();
heap.sweep();
assert_eq!(Arc::strong_count(&text), 2);
heap.sweep();
assert_eq!(Arc::strong_count(&text), 1);
assert_eq!(heap.len(), 0);
}
#[test]
fn raw_box_storage_drops_native_owners_even_for_rejected_groups() {
let registry = fixture_registry();
let budget = RuntimeBudget::default();
let mut heap = Heap::with_budget(&budget);
let text: Arc<str> = Arc::from("malformed box fixture");
let r = forge_box(
&mut heap,
registry.clone(),
VEC,
&[Value::String(text.clone()), Value::Float(1.0)],
);
assert_eq!(Arc::strong_count(&text), 2);
assert_eq!(heap.dynamic_box_values(&registry, r, VEC).unwrap_err(), E::Type);
heap.sweep();
assert_eq!(Arc::strong_count(&text), 1);
assert_eq!(budget.used(Q::GuestBytes), 0);
}
#[test]
fn failed_trait_box_publication_preserves_source_roots_and_existing_table_capacities() {
let registry = fixture_registry();
let one_slot_aux =
(size_of::<Option<StoredAllocation>>() + size_of::<u32>() + size_of::<usize>()) as u64;
let budget = RuntimeBudget::new(
RuntimeLimits::default().lowered(Q::AuxiliaryBytes, one_slot_aux).unwrap(),
);
let mut heap = Heap::with_budget(&budget);
let receiver = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
let before = budget.used(Q::GuestBytes);
let source = [Value::HeapRef(receiver), Value::Int64(0)];
assert!(
matches!(pack(&registry, &mut heap, TRAIT, &source), Err(E::Resource(e)) if e.resource == Q::AuxiliaryBytes)
);
assert_eq!(heap.len(), 1);
assert_eq!(heap.allocation_count(), 1);
assert_eq!(budget.used(Q::GuestBytes), before);
assert_eq!(budget.used(Q::AuxiliaryBytes), one_slot_aux);
assert_eq!(budget.used(Q::HandleSlots), 1);
assert_eq!(budget.used(Q::TemporaryBytes), 0);
assert_eq!(source, [Value::HeapRef(receiver), Value::Int64(0)]);
heap.mark_from_roots(source.iter().filter_map(crate::roots::value_heap_ref)).unwrap();
heap.sweep();
assert!(heap.is_valid(receiver));
}
@@ -0,0 +1,102 @@
//! Fixed queries over the logical-frame input snapshot. No endpoint or selector
//! crosses the guest boundary; names below identify operations, not value types.
use crate::builtins::{AbiType, BuiltinScalarType, IntrinsicExecutionError, IntrinsicMeta};
use prometeu_bytecode::Value;
use prometeu_hal::{HostContext, InputPlatform, button::Button};
const BOOL: &[AbiType] = &[AbiType::Scalar(BuiltinScalarType::Bool)];
const INT: &[AbiType] = &[AbiType::Scalar(BuiltinScalarType::Int64)];
const fn query(
id: u32,
owner: &'static str,
name: &'static str,
ret_layout: &'static [AbiType],
implementation: crate::IntrinsicImplementation,
) -> IntrinsicMeta {
IntrinsicMeta {
id,
owner,
name,
version: 1,
arg_layout: &[],
ret_layout,
deterministic: true,
may_allocate: false,
implementation,
}
}
fn snapshot<'a>(
args: &[Value],
ctx: &'a HostContext<'_>,
) -> Result<&'a dyn InputPlatform, IntrinsicExecutionError> {
if !args.is_empty() {
return Err(IntrinsicExecutionError::ArityMismatch { expected: 0, got: args.len() });
}
let platform = ctx.platform.as_deref().ok_or(IntrinsicExecutionError::HardwareUnavailable)?;
Ok(platform.input())
}
fn read_button<const PROPERTY: u8>(button: &Button) -> Vec<Value> {
vec![match PROPERTY {
0 => Value::Boolean(button.pressed),
1 => Value::Boolean(button.released),
2 => Value::Boolean(button.down),
3 => Value::Int64(i64::from(button.hold_frames)),
_ => unreachable!("private input property outside the fixed catalogue"),
}]
}
// This single mapping defines IDs, canonical names and their snapshot readers.
macro_rules! input_queries {
($(($base:literal, $prefix:literal, $reader:ident, $device:ident, $button:ident)),* $(,)?) => {
pub(crate) const INPUT_INTRINSICS: [IntrinsicMeta; 54] = [
$(
query($base, $prefix, "pressed", BOOL, $reader::<0>),
query($base + 1, $prefix, "released", BOOL, $reader::<1>),
query($base + 2, $prefix, "down", BOOL, $reader::<2>),
query($base + 3, $prefix, "hold", INT, $reader::<3>),
)*
query(0x2134, "input.touch", "x", INT, touch_x),
query(0x2135, "input.touch", "y", INT, touch_y),
];
$(
fn $reader<const PROPERTY: u8>(
args: &[Value], ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
Ok(read_button::<PROPERTY>(snapshot(args, ctx)?.$device().$button()))
}
)*
}
}
input_queries!(
(0x2100, "input.pad.up", up, pad, up),
(0x2104, "input.pad.down", down, pad, down),
(0x2108, "input.pad.left", left, pad, left),
(0x210C, "input.pad.right", right, pad, right),
(0x2110, "input.pad.a", a, pad, a),
(0x2114, "input.pad.b", b, pad, b),
(0x2118, "input.pad.x", x, pad, x),
(0x211C, "input.pad.y", y, pad, y),
(0x2120, "input.pad.l", l, pad, l),
(0x2124, "input.pad.r", r, pad, r),
(0x2128, "input.pad.start", start, pad, start),
(0x212C, "input.pad.select", select, pad, select),
(0x2130, "input.touch.button", touch_button, touch, f),
);
fn touch_x(
args: &[Value],
ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
Ok(vec![Value::Int64(i64::from(snapshot(args, ctx)?.touch().x()))])
}
fn touch_y(
args: &[Value],
ctx: &mut HostContext<'_>,
) -> Result<Vec<Value>, IntrinsicExecutionError> {
Ok(vec![Value::Int64(i64::from(snapshot(args, ctx)?.touch().y()))])
}
+17
View File
@@ -1,12 +1,27 @@
mod builtins;
mod call_frame;
mod input_intrinsics;
mod local_addressing;
// Keep the verifier internal in production builds, but expose it for integration tests
// so the golden verifier suite can exercise it without widening the public API in releases.
mod heap;
mod object;
pub mod resource_budget;
mod roots;
// Bounded Registry preflight is consumed by the upcoming v1 image loader.
mod program_image;
#[allow(dead_code)]
mod registry_verifier;
mod scheduler;
pub use program_image::{ImageStringLease, ValidatedProgramImage};
// Image/session creation and native provenance consume this in step 19.
#[allow(dead_code)]
mod string_ledger;
// Registry-backed consumers are integrated with executable images in PLN-0176.
#[allow(dead_code)]
mod typed_storage;
#[allow(dead_code)]
mod value_contract;
#[cfg(not(test))]
mod verifier;
#[cfg(test)]
@@ -24,3 +39,5 @@ pub use builtins::{
pub use prometeu_hal::{HostContext, HostReturn, NativeInterface, SyscallId};
pub use virtual_machine::{BudgetReport, LogicalFrameEndingReason, VirtualMachine};
pub use vm_init_error::{LoaderPatchError, VmInitError};
pub use verifier::VerifierError;
+6
View File
@@ -88,6 +88,12 @@ pub enum ObjectKind {
/// contained `HeapRef`s directly.
/// - `payload_len` is 0 for this fixed-layout object.
Coroutine = 6,
/// Registry-defined Struct with a compact typed instance payload.
Struct = 7,
/// Internal immutable multi-slot Dynamic payload, never a nominal guest type.
DynamicBox = 8,
// Future kinds must be appended here to keep tag numbers stable.
}
@@ -0,0 +1,430 @@
//! PBX v1 publication: immutable metadata and shared payload, after bindings
//! and bounded whole-program verification. No public unchecked constructor.
use crate::{LoaderPatchError, VmInitError};
use prometeu_bytecode::isa::core::CoreOpCode as Op;
use prometeu_bytecode::load_limits::{
LoadBudget, LoadCode as C, LoadFailure as E, LoadReason as R, LoadResource as Q,
};
use prometeu_bytecode::model::{ConstantPoolEntry as K, DebugInfo, Export};
use prometeu_bytecode::registry::{FunctionId, Registry};
use prometeu_bytecode::registry_codec::OwnedPbx;
use prometeu_bytecode::{FunctionMeta, ProgramImage, Value};
use prometeu_hal::syscalls::{CapFlags, DeclaredLoadError, SyscallResolved};
use std::collections::HashMap;
use std::sync::{Arc, Mutex, Weak};
const DOMAINS: [Q; 11] = [
Q::PbxBytes,
Q::CodeBytes,
Q::Types,
Q::Functions,
Q::Implementations,
Q::NestedRecords,
Q::NameBytes,
Q::RegistryBytes,
Q::TemporaryBytes,
Q::ConstantEntries,
Q::ConstantStringBytes,
];
#[derive(Debug)]
struct ImageStrings {
records: Vec<(Weak<str>, usize)>,
bytes: u64,
}
impl ImageStrings {
fn reconcile(&mut self) {
self.records.retain(|(weak, len)| {
if weak.strong_count() == 0 {
self.bytes -= *len as u64;
false
} else {
true
}
});
}
}
/// Native retention carries the image accounting domain with the content.
/// This is provenance metadata, not a new guest string representation.
#[derive(Debug, Clone)]
pub struct ImageStringLease {
content: Arc<str>,
domain: Arc<Mutex<ImageStrings>>,
}
impl ImageStringLease {
pub fn content(&self) -> &Arc<str> {
&self.content
}
pub fn retained_content(&self) -> (u64, usize) {
let mut domain = self.domain.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
domain.reconcile();
(domain.bytes, domain.records.len())
}
}
#[derive(Debug)]
pub struct ValidatedProgramImage {
registry: Arc<Registry>,
pub(crate) execution: ProgramImage,
exports: Vec<Export>,
strings: Arc<Mutex<ImageStrings>>,
registry_bytes: u64,
payload_bytes: u64,
capabilities: CapFlags,
}
impl ValidatedProgramImage {
pub(crate) fn string_retention(&self) -> Arc<dyn Send + Sync> {
self.strings.clone()
}
pub fn registry(&self) -> &Arc<Registry> {
&self.registry
}
pub fn code(&self) -> &[u8] {
&self.execution.rom
}
pub fn constants(&self) -> &[Value] {
&self.execution.constant_pool
}
pub fn debug(&self) -> Option<&DebugInfo> {
self.execution.debug_info.as_deref()
}
pub fn exports(&self) -> &[Export] {
&self.exports
}
pub fn capabilities(&self) -> CapFlags {
self.capabilities
}
/// Domain measurements are native capacities/content, not process RSS.
pub fn registry_bytes(&self) -> u64 {
self.registry_bytes
}
pub fn payload_bytes(&self) -> u64 {
self.payload_bytes
}
pub fn lease_constant(&self, index: usize) -> Option<ImageStringLease> {
let Value::String(content) = self.constants().get(index)? else { return None };
Some(ImageStringLease { content: content.clone(), domain: self.strings.clone() })
}
pub fn retains_string(&self, content: &Arc<str>) -> bool {
let strings = self.strings.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
strings.records.iter().any(|(weak, _)| std::ptr::eq(weak.as_ptr(), Arc::as_ptr(content)))
}
pub fn constant_content(&self) -> (u64, usize) {
let mut strings = self.strings.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
strings.reconcile();
(strings.bytes, strings.records.len())
}
/// Only this factory can publish an image. Unsupported versions have no
/// fallback. The caller's input domain is separate from load scratch.
pub fn load(
bytes: &[u8],
budget: &mut LoadBudget,
capabilities: CapFlags,
) -> Result<Arc<Self>, VmInitError> {
let before = DOMAINS.map(|resource| budget.used(resource));
let result = Self::load_inner(bytes, budget, capabilities);
// Failure drops partial owners before this rollback; success transfers
// scratch-owned payload into the measured immutable image domain.
for (resource, old) in DOMAINS.into_iter().zip(before) {
if result.is_err() || resource == Q::TemporaryBytes {
budget.refund(resource, budget.used(resource) - old);
}
}
result
}
fn load_inner(
bytes: &[u8],
b: &mut LoadBudget,
capabilities: CapFlags,
) -> Result<Arc<Self>, VmInitError> {
let payload_before = b.used(Q::TemporaryBytes);
let registry_before = b.used(Q::RegistryBytes);
let mut module = OwnedPbx::parse(bytes, b)?;
if module.registry.declarations().functions.is_empty() {
return Err(E::new(C::InvalidEntrypoint, R::FunctionId).in_function(0, None).into());
}
bind(&mut module, b, capabilities)?;
crate::registry_verifier::validate_registry_types(
&module.code,
&module.registry,
&module.constants,
b,
)?;
let mut functions =
scratch::<FunctionMeta>(module.registry.declarations().functions.len(), b)?;
for (index, f) in module.registry.declarations().functions.iter().enumerate() {
b.work(1)?;
let slots = module.registry.function_layout(FunctionId(index as u32)).unwrap();
// The accepted 16,384-slot frame/1,024-slot result ceilings prove
// these cached execution widths fit; no serialized field narrows.
let narrow = |n| {
u16::try_from(n).map_err(|_| {
E::new(C::InvalidCode, R::FrameSlots)
.in_function(index as u32, Some(f.code_offset))
})
};
functions.push(FunctionMeta {
code_offset: f.code_offset,
code_len: f.code_len,
param_slots: narrow(slots.parameter_slots)?,
local_slots: narrow(f.local_slots)?,
return_slots: narrow(slots.result_slots)?,
max_stack_slots: narrow(f.max_stack_slots)?,
});
}
let constants_capacity = (module.constants.capacity() * size_of::<K>()) as u64;
b.work(module.constants.len())?;
let string_count = module.constants.iter().filter(|c| matches!(c, K::String(_))).count();
let mut records = scratch::<(Weak<str>, usize)>(string_count, b)?;
let mut values = scratch::<Value>(module.constants.len(), b)?;
let mut content_bytes = 0;
for constant in module.constants {
b.work(1)?;
let value = match constant {
K::Null => Value::Null,
K::Int32(v) => Value::Int32(v),
K::Int64(v) => Value::Int64(v),
K::Float64(v) => Value::Float(v),
K::Boolean(v) => Value::Boolean(v),
K::String(text) => {
arc_charge::<u8>(text.len(), b, Q::TemporaryBytes)?;
b.work(text.len())?;
let content: Arc<str> = Arc::from(text.as_str());
content_bytes += text.len() as u64;
records.push((Arc::downgrade(&content), text.len()));
b.refund(Q::TemporaryBytes, text.capacity() as u64);
Value::String(content)
}
};
values.push(value);
}
b.refund(Q::TemporaryBytes, constants_capacity);
// Binding no longer needs source declarations. They were validated,
// used exactly, and can be released before final payload publication.
b.work(module.syscalls.len())?;
let syscall_bytes = (module.syscalls.capacity()
* size_of::<prometeu_bytecode::SyscallDecl>()) as u64
+ module
.syscalls
.iter()
.map(|d| (d.module.capacity() + d.name.capacity()) as u64)
.sum::<u64>();
drop(module.syscalls);
b.refund(Q::TemporaryBytes, syscall_bytes);
let rom = shared_slice(module.code, b)?;
let constant_pool = shared_slice(values, b)?;
let functions = shared_slice(functions, b)?;
let debug_info = if let Some(debug) = module.debug {
arc_charge::<DebugInfo>(1, b, Q::TemporaryBytes)?;
Some(Arc::new(debug))
} else {
None
};
// Export vectors retain source order; lookup can preserve the existing
// last-declaration-wins native entry behavior without another HashMap.
arc_charge::<Mutex<ImageStrings>>(1, b, Q::TemporaryBytes)?;
let strings = Arc::new(Mutex::new(ImageStrings { records, bytes: content_bytes }));
arc_charge::<Registry>(1, b, Q::RegistryBytes)?;
let registry = Arc::new(module.registry);
arc_charge::<Self>(1, b, Q::TemporaryBytes)?;
arc_charge::<HashMap<String, u32>>(1, b, Q::TemporaryBytes)?;
let registry_bytes = b.used(Q::RegistryBytes) - registry_before;
let payload_bytes = b.used(Q::TemporaryBytes) - payload_before;
let execution = ProgramImage {
rom,
constant_pool,
functions,
debug_info,
exports: Arc::new(HashMap::new()),
};
Ok(Arc::new(Self {
registry,
execution,
exports: module.exports,
strings,
registry_bytes,
payload_bytes,
capabilities,
}))
}
}
pub(crate) fn scratch<T>(count: usize, b: &mut LoadBudget) -> Result<Vec<T>, E> {
let bytes = count
.checked_mul(size_of::<T>())
.ok_or_else(|| E::new(C::ResourceLimit, R::Overflow))? as u64;
b.charge(Q::TemporaryBytes, bytes)?;
let mut out = Vec::new();
out.try_reserve_exact(count).map_err(|_| {
let mut e = E::resource(Q::TemporaryBytes, bytes, b.limit(Q::TemporaryBytes));
e.reason = R::Allocation;
e
})?;
b.charge(Q::TemporaryBytes, (out.capacity() - count) as u64 * size_of::<T>() as u64)?;
Ok(out)
}
fn arc_charge<T>(count: usize, b: &mut LoadBudget, resource: Q) -> Result<(), E> {
let align = align_of::<T>().max(align_of::<usize>());
let bytes = count
.checked_mul(size_of::<T>())
.and_then(|n| n.checked_add(2 * size_of::<usize>() + align - 1))
.map(|n| n / align * align)
.ok_or_else(|| E::new(C::ResourceLimit, R::Overflow))?;
b.charge(resource, bytes as u64)
}
fn shared_slice<T>(items: Vec<T>, b: &mut LoadBudget) -> Result<Arc<[T]>, E> {
arc_charge::<T>(items.len(), b, Q::TemporaryBytes)?;
b.work(items.len())?;
let capacity = (items.capacity() * size_of::<T>()) as u64;
let shared = Arc::from(items);
b.refund(Q::TemporaryBytes, capacity);
Ok(shared)
}
fn same_text(left: &str, right: &str, b: &mut LoadBudget) -> Result<bool, E> {
b.work(1)?;
if left.len() != right.len() {
return Ok(false);
}
for (a, c) in left.bytes().zip(right.bytes()) {
b.work(2)?;
if a != c {
return Ok(false);
}
}
Ok(true)
}
fn diagnostic_text(text: &str, b: &mut LoadBudget) -> Result<String, E> {
let mut bytes = scratch(text.len(), b)?;
b.work(text.len())?;
bytes.extend_from_slice(text.as_bytes());
Ok(String::from_utf8(bytes).expect("declaration text is UTF-8"))
}
fn patch_error(error: LoaderPatchError) -> VmInitError {
VmInitError::LoaderPatchFailed(error)
}
fn bind(module: &mut OwnedPbx, b: &mut LoadBudget, caps: CapFlags) -> Result<(), VmInitError> {
let before = b.used(Q::TemporaryBytes);
let result = (|| {
let mut resolved = scratch::<SyscallResolved>(module.syscalls.len(), b)?;
let mut used = scratch::<bool>(module.syscalls.len(), b)?;
b.work(module.syscalls.len())?;
used.resize(module.syscalls.len(), false);
for decl in &module.syscalls {
let mut found = None;
for entry in prometeu_hal::syscalls::catalogue() {
b.work(1)?;
if entry.meta.version == decl.version
&& same_text(entry.meta.module, &decl.module, b)?
&& same_text(entry.meta.name, &decl.name, b)?
{
found = Some(SyscallResolved { id: entry.meta.id, meta: entry.meta });
break;
}
}
let native_error = if let Some(value) = found {
if value.meta.caps & !caps != 0 {
Some(DeclaredLoadError::MissingCapability {
required: value.meta.caps,
provided: caps,
module: diagnostic_text(&decl.module, b)?,
name: diagnostic_text(&decl.name, b)?,
version: decl.version,
})
} else if decl.arg_slots != value.meta.arg_slots as u16
|| decl.ret_slots != value.meta.ret_slots
{
Some(DeclaredLoadError::AbiMismatch {
module: diagnostic_text(&decl.module, b)?,
name: diagnostic_text(&decl.name, b)?,
version: decl.version,
declared_arg_slots: decl.arg_slots,
declared_ret_slots: decl.ret_slots,
expected_arg_slots: value.meta.arg_slots as u16,
expected_ret_slots: value.meta.ret_slots,
})
} else {
resolved.push(value);
None
}
} else {
Some(DeclaredLoadError::UnknownSyscall {
module: diagnostic_text(&decl.module, b)?,
name: diagnostic_text(&decl.name, b)?,
version: decl.version,
})
};
if let Some(error) = native_error {
return Err(patch_error(LoaderPatchError::ResolveFailed(error)));
}
}
for (id, function) in module.registry.declarations().functions.iter().enumerate() {
let mut pc = function.code_offset as usize;
let end = pc + function.code_len as usize;
while pc < end {
let instruction = (|| {
b.work(2)?;
let instruction = prometeu_bytecode::decode_next(pc, &module.code[..end])
.map_err(|e| {
E::new(
C::InvalidCode,
if matches!(e, prometeu_bytecode::DecodeError::UnknownOpcode { .. })
{
R::UnknownOpcode
} else {
R::Truncated
},
)
})?;
b.work(instruction.imm.len() + 1)?;
Ok(instruction)
})()
.map_err(|e: E| e.in_section(2).in_function(id as u32, Some(pc as u32)))?;
let next = instruction.next_pc;
match instruction.opcode {
Op::Hostcall => {
let index = instruction.imm_u32().unwrap();
let syscall = resolved.get(index as usize).ok_or_else(|| {
patch_error(LoaderPatchError::HostcallIndexOutOfBounds {
pc,
sysc_index: index,
syscalls_len: resolved.len(),
})
})?;
b.work(7)?;
used[index as usize] = true;
module.code[pc..pc + 2]
.copy_from_slice(&(Op::Syscall as u16).to_le_bytes());
module.code[pc + 2..pc + 6].copy_from_slice(&syscall.id.to_le_bytes());
}
Op::Syscall => {
return Err(patch_error(LoaderPatchError::RawSyscallInPreloadArtifact {
pc,
syscall_id: instruction.imm_u32().unwrap(),
}));
}
_ => {}
}
pc = next;
}
}
for (index, (decl, used)) in module.syscalls.iter().zip(&used).enumerate() {
b.work(1)?;
if !used {
return Err(patch_error(LoaderPatchError::UnusedSyscallDecl {
sysc_index: index as u32,
module: diagnostic_text(&decl.module, b)?,
name: diagnostic_text(&decl.name, b)?,
version: decl.version,
}));
}
}
Ok(())
})();
b.refund(Q::TemporaryBytes, b.used(Q::TemporaryBytes) - before);
result
}
#[cfg(test)]
mod tests;
@@ -0,0 +1,260 @@
use super::*;
use prometeu_bytecode::load_limits::LoadLimits;
use prometeu_bytecode::registry::{
BuiltinId, FunctionDecl, RegistryDeclarations, TypeDecl, TypeKind,
};
use prometeu_bytecode::registry_codec::PbxModule;
use prometeu_bytecode::{SourceSpan, SyscallDecl};
use prometeu_hal::syscalls::{Syscall, caps, meta_for};
fn budget() -> LoadBudget {
LoadBudget::new(LoadLimits::default())
}
fn fixture(
code: &[u8],
max: u32,
constants: &[K],
debug: Option<&DebugInfo>,
syscalls: &[SyscallDecl],
) -> Vec<u8> {
let registry = Registry::resolve(
RegistryDeclarations {
types: vec![TypeDecl {
name: Some("boolean".into()),
kind: TypeKind::Builtin(BuiltinId::BOOL),
}],
functions: vec![FunctionDecl {
name: Some("boot".into()),
code_len: code.len() as u32,
max_stack_slots: max,
..Default::default()
}],
..Default::default()
},
code.len(),
&mut budget(),
)
.unwrap();
PbxModule { registry: &registry, code, constants, debug, exports: &[], syscalls }
.serialize(&mut budget())
.unwrap()
}
fn has_cart() -> SyscallDecl {
let m = meta_for(Syscall::SystemHasCart);
SyscallDecl {
module: m.module.into(),
name: m.name.into(),
version: m.version,
arg_slots: m.arg_slots as u16,
ret_slots: m.ret_slots,
}
}
fn hostcall_code() -> Vec<u8> {
let mut code = (Op::Hostcall as u16).to_le_bytes().to_vec();
code.extend_from_slice(&0u32.to_le_bytes());
code.extend_from_slice(&(Op::Pop as u16).to_le_bytes());
code.extend_from_slice(&(Op::Halt as u16).to_le_bytes());
code
}
#[test]
fn publication_shares_owners_and_preserves_payload_bits_and_names() {
let debug = DebugInfo {
pc_to_span: vec![(0, SourceSpan { file_id: 7, start: 2, end: 3 })],
function_names: vec![(0, "debug boot".into())],
};
let constants = [
K::Null,
K::String("é猫".into()),
K::String(String::new()),
K::Float64(f64::from_bits(0x7ff8000000000042)),
K::Float64(-0.0),
];
let bytes = fixture(&[1, 0], 0, &constants, Some(&debug), &[]);
let mut b = budget();
b.charge(Q::TemporaryBytes, 7).unwrap();
let image = ValidatedProgramImage::load(&bytes, &mut b, caps::NONE).unwrap();
assert_eq!(b.used(Q::TemporaryBytes), 7);
assert!(image.payload_bytes() > 0 && image.registry_bytes() > 0);
assert_eq!(image.registry().declarations().functions[0].name.as_deref(), Some("boot"));
assert_eq!(image.execution.functions[0].max_stack_slots, 0);
assert_eq!(image.constant_content(), (5, 2));
assert!(image.lease_constant(0).is_none());
let Value::Float(nan) = image.constants()[3] else { panic!() };
let Value::Float(zero) = image.constants()[4] else { panic!() };
assert_eq!(nan.to_bits(), 0x7ff8000000000042);
assert_eq!(zero.to_bits(), (-0.0f64).to_bits());
let projection = image.execution.clone();
assert!(Arc::ptr_eq(&projection.rom, &image.execution.rom));
assert!(Arc::ptr_eq(&projection.constant_pool, &image.execution.constant_pool));
assert!(Arc::ptr_eq(
projection.debug_info.as_ref().unwrap(),
image.execution.debug_info.as_ref().unwrap()
));
assert_eq!(image.debug().unwrap().function_names[0].1, "debug boot");
let lease = image.lease_constant(1).unwrap();
let Value::String(text) = &image.constants()[1] else { panic!() };
assert!(Arc::ptr_eq(text, lease.content()));
drop(bytes);
drop(projection);
drop(image);
assert_eq!(lease.content().as_ref(), "é猫");
assert_eq!(lease.retained_content(), (5, 1));
}
#[test]
fn binding_precedes_publication_and_does_not_mutate_input() {
let code = hostcall_code();
let bytes = fixture(&code, 1, &[], None, &[has_cart()]);
let original = bytes.clone();
let image = ValidatedProgramImage::load(&bytes, &mut budget(), caps::SYSTEM).unwrap();
assert_eq!(bytes, original);
assert_eq!(&image.code()[..2], &(Op::Syscall as u16).to_le_bytes());
assert_eq!(&image.code()[2..6], &(Syscall::SystemHasCart as u32).to_le_bytes());
assert_eq!(image.capabilities(), caps::SYSTEM);
}
#[test]
fn native_binding_errors_keep_identity_and_roll_back_image_ownership() {
let code = hostcall_code();
let mut unknown = has_cart();
unknown.name = "missing".into();
let mut abi = has_cart();
abi.ret_slots = 2;
for (decl, caps, expected) in
[(unknown, caps::SYSTEM, 0), (has_cart(), caps::NONE, 1), (abi, caps::SYSTEM, 2)]
{
let bytes = fixture(&code, 1, &[], None, &[decl]);
let mut b = budget();
b.charge(Q::TemporaryBytes, 7).unwrap();
b.charge(Q::RegistryBytes, 3).unwrap();
let error = ValidatedProgramImage::load(&bytes, &mut b, caps).unwrap_err();
let VmInitError::LoaderPatchFailed(LoaderPatchError::ResolveFailed(error)) = error else {
panic!("{error:?}")
};
assert!(matches!(
(expected, error),
(0, DeclaredLoadError::UnknownSyscall { .. })
| (1, DeclaredLoadError::MissingCapability { .. })
| (2, DeclaredLoadError::AbiMismatch { .. })
));
assert_eq!(b.used(Q::TemporaryBytes), 7);
assert_eq!(b.used(Q::RegistryBytes), 3);
assert_eq!(b.used(Q::Functions), 0);
assert_eq!(b.used(Q::ConstantEntries), 0);
assert!(b.used(Q::Work) > 0);
}
}
#[test]
fn raw_or_unbound_calls_cannot_reach_an_image() {
let mut raw = hostcall_code();
raw[..2].copy_from_slice(&(Op::Syscall as u16).to_le_bytes());
let mut out_of_bounds = hostcall_code();
out_of_bounds[2..6].copy_from_slice(&1u32.to_le_bytes());
for (code, decls, kind) in [
(&raw[..], vec![], 0),
(&out_of_bounds[..], vec![has_cart()], 1),
(&[1, 0][..], vec![has_cart()], 2),
] {
let bytes = fixture(code, 1, &[], None, &decls);
let error = ValidatedProgramImage::load(&bytes, &mut budget(), caps::SYSTEM).unwrap_err();
assert!(matches!(
(kind, error),
(
0,
VmInitError::LoaderPatchFailed(
LoaderPatchError::RawSyscallInPreloadArtifact { .. }
)
) | (
1,
VmInitError::LoaderPatchFailed(LoaderPatchError::HostcallIndexOutOfBounds { .. })
) | (2, VmInitError::LoaderPatchFailed(LoaderPatchError::UnusedSyscallDecl { .. }))
));
}
}
#[test]
fn verification_rejects_unreachable_bad_instructions_and_underflow() {
let pop = (Op::Pop as u16).to_le_bytes();
for code in [&pop[..], &[1, 0, 0xff, 0xff][..]] {
let bytes = fixture(code, 0, &[], None, &[]);
let mut b = budget();
let VmInitError::RegistryLoadFailed(error) =
ValidatedProgramImage::load(&bytes, &mut b, caps::NONE).unwrap_err()
else {
panic!()
};
assert_eq!(error.function, Some(0));
assert_eq!(b.used(Q::RegistryBytes), 0);
assert_eq!(b.used(Q::TemporaryBytes), 0);
}
}
#[test]
fn late_work_refusal_releases_all_new_owners() {
let bytes = fixture(&[1, 0], 0, &[K::String("abc".into())], None, &[]);
let mut full = budget();
ValidatedProgramImage::load(&bytes, &mut full, caps::NONE).unwrap();
let mut b = LoadBudget::new(LoadLimits { work: full.used(Q::Work) - 1, ..Default::default() });
b.charge(Q::TemporaryBytes, 7).unwrap();
b.charge(Q::RegistryBytes, 3).unwrap();
let VmInitError::RegistryLoadFailed(error) =
ValidatedProgramImage::load(&bytes, &mut b, caps::NONE).unwrap_err()
else {
panic!()
};
assert_eq!(error.resource, Some(Q::Work));
assert_eq!(b.used(Q::TemporaryBytes), 7);
assert_eq!(b.used(Q::RegistryBytes), 3);
assert_eq!(b.used(Q::ConstantStringBytes), 0);
assert_eq!(b.used(Q::PbxBytes), 0);
}
#[test]
fn constant_strings_share_image_domain_across_sessions_and_native_snapshots() {
use crate::resource_budget::{RuntimeLimits, RuntimeResource};
use crate::{HostContext, HostReturn, NativeInterface, VirtualMachine};
struct Native;
impl NativeInterface for Native {
fn syscall(
&mut self,
_id: u32,
_args: &[Value],
_ret: &mut HostReturn,
_ctx: &mut HostContext,
) -> Result<(), prometeu_hal::vm_fault::VmFault> {
Ok(())
}
}
let mut code = (Op::PushConst as u16).to_le_bytes().to_vec();
code.extend_from_slice(&0u32.to_le_bytes());
code.extend_from_slice(&(Op::Halt as u16).to_le_bytes());
let bytes = fixture(&code, 1, &[K::String("shared".into())], None, &[]);
let image = ValidatedProgramImage::load(&bytes, &mut budget(), caps::NONE).unwrap();
let lease = image.lease_constant(0).unwrap();
let limits = RuntimeLimits::default().lowered(RuntimeResource::StringBytes, 0).unwrap();
let mut first = VirtualMachine::from_image(image.clone(), limits.clone());
let mut second = VirtualMachine::from_image(image.clone(), limits);
first.prepare_boot_call().unwrap();
second.prepare_boot_call().unwrap();
for vm in [&mut first, &mut second] {
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
let snapshot = first.operand_stack_top(1);
let other = second.operand_stack_top(1);
let (Value::String(left), Value::String(right)) = (&snapshot[0], &other[0]) else { panic!() };
assert!(Arc::ptr_eq(left, right));
assert_eq!(snapshot.retained_domains(), 1);
drop(image);
drop(first);
drop(second);
drop(other);
assert_eq!(lease.retained_content(), (6, 1));
drop(lease);
let Value::String(text) = &snapshot[0] else { panic!() };
assert_eq!(text.as_ref(), "shared");
}
@@ -0,0 +1,219 @@
//! Bounded structural preflight of declared Registry code ranges. This phase
//! checks every instruction, including unreachable code. Stack/type-flow,
//! bindings and entry validation must still succeed before image publication.
use prometeu_bytecode::isa::core::{CoreOpCode as Op, CoreOpCodeSpecExt};
use prometeu_bytecode::load_limits::{
IdDomain, LoadBudget, LoadCode as C, LoadFailure as E, LoadReason as R, LoadResource as Q,
};
use prometeu_bytecode::registry::{FunctionId, Registry};
use prometeu_bytecode::{DecodeError, decode_next};
pub(crate) fn validate_registry_instructions(
code: &[u8],
registry: &Registry,
constant_entries: usize,
budget: &mut LoadBudget,
) -> Result<(), E> {
let temporary_before = budget.used(Q::TemporaryBytes);
let result = validate_inner(code, registry, constant_entries, budget);
// All maps live inside validate_inner and are already dropped here. Failure
// refunds scratch while preserving attempted work and prior load ownership.
budget.refund(Q::TemporaryBytes, budget.used(Q::TemporaryBytes) - temporary_before);
result
}
fn validate_inner(
code: &[u8],
registry: &Registry,
constants: usize,
budget: &mut LoadBudget,
) -> Result<(), E> {
budget.check(Q::CodeBytes, code.len() as u64)?;
budget.check(Q::ConstantEntries, constants as u64)?;
budget.check(Q::Functions, registry.declarations().functions.len() as u64)?;
for (index, function) in registry.declarations().functions.iter().enumerate() {
let function_id = index as u32;
budget
.work(1)
.map_err(|e| e.in_section(2).in_function(function_id, Some(function.code_offset)))?;
let start = function.code_offset as usize;
let end = start
.checked_add(function.code_len as usize)
.ok_or_else(|| error(R::CodeRange, function_id, start))?;
let contextual =
|e: E, pc: usize| e.in_section(2).in_function(function_id, u32::try_from(pc).ok());
let body = code.get(start..end).ok_or_else(|| error(R::CodeRange, function_id, start))?;
let widths = registry.function_layout(FunctionId(function_id)).unwrap();
let local_slots = u64::from(widths.parameter_slots) + u64::from(function.local_slots);
let total = local_slots + u64::from(function.max_stack_slots);
if total > budget.frame_limit() {
return Err(error(R::FrameSlots, function_id, start));
}
if u64::from(widths.result_slots) > budget.result_limit() {
return Err(error(R::ReturnSlots, function_id, start));
}
let function_scratch_before = budget.used(Q::TemporaryBytes);
let mut at_pc = start;
let result = (|| {
let mut boundaries = boundary_map(
body.len().checked_add(1).ok_or_else(|| E::new(C::ResourceLimit, R::Overflow))?,
budget,
)?;
let mut pc = 0;
while pc < body.len() {
at_pc = start + pc;
let instruction =
metered_decode(pc, body, budget).map_err(|e| contextual(e, start + pc))?;
budget.work(1)?; // Boundary write.
boundaries[pc] = 1;
pc = instruction.next_pc;
}
budget.work(1)?;
boundaries[body.len()] = 1; // Existing jump-to-function-end return boundary.
pc = 0;
while pc < body.len() {
at_pc = start + pc;
let instruction =
metered_decode(pc, body, budget).map_err(|e| contextual(e, start + pc))?;
let fail = |reason| error(reason, function_id, start + pc);
if instruction.opcode.requires_registry() {
budget.work(
if matches!(
instruction.opcode,
Op::DynPack | Op::DynUnpack | Op::DynCanUnpack
) {
2
} else {
4
},
)?;
}
instruction
.registry_stack_effect(registry)
.map_err(|e| contextual(e, start + pc))?;
match instruction.opcode {
Op::Jmp | Op::JmpIfTrue | Op::JmpIfFalse => {
budget.work(1)?; // Branch edge.
let target = instruction.imm_u32().unwrap() as usize;
if target > body.len() {
return Err(fail(R::JumpTarget));
}
budget.work(1)?; // Boundary read.
if boundaries[target] == 0 {
return Err(fail(R::InstructionBoundary));
}
}
Op::GetLocal | Op::SetLocal => {
let slot = instruction.imm_u32().unwrap();
if u64::from(slot) >= local_slots {
return Err(fail(R::LocalSlot).member(slot));
}
}
Op::PushBool if instruction.imm_u8().unwrap() > 1 => {
return Err(fail(R::BooleanImmediate));
}
Op::PushConst => {
let id = instruction.imm_u32().unwrap();
if id as usize >= constants {
return Err(with_id(reference_error(fail(R::ConstantIndex)), id));
}
}
Op::Call | Op::MakeClosure | Op::Spawn => {
let id = if instruction.opcode == Op::Call {
instruction.imm_u32().unwrap()
} else {
instruction.imm_u32x2().unwrap().0
};
let callee = registry.function_layout(FunctionId(id)).ok_or_else(|| {
reference_error(fail(R::FunctionId)).reference(IdDomain::Function, id)
})?;
if instruction.opcode == Op::Spawn
&& instruction.imm_u32x2().unwrap().1 != callee.parameter_slots
{
return Err(fail(R::Signature).reference(IdDomain::Function, id));
}
}
Op::Hostcall => {
return Err(with_id(
fail(R::UnpatchedHostcall),
instruction.imm_u32().unwrap(),
));
}
Op::Syscall => {
let id = instruction.imm_u32().unwrap();
if prometeu_hal::syscalls::Syscall::from_u32(id).is_none() {
return Err(with_id(reference_error(fail(R::NativeId)), id));
}
}
Op::Intrinsic => {
let id = instruction.imm_u32().unwrap();
if crate::builtins::metered_lookup_intrinsic(id, budget)?.is_none() {
return Err(with_id(reference_error(fail(R::NativeId)), id));
}
}
_ => {}
}
pc = instruction.next_pc;
}
Ok(())
})()
.map_err(|e: E| if e.function.is_none() { contextual(e, at_pc) } else { e });
// Free each function's map before the next. No aggregate unmetered CFG.
budget.refund(Q::TemporaryBytes, budget.used(Q::TemporaryBytes) - function_scratch_before);
result?;
}
Ok(())
}
fn boundary_map(count: usize, budget: &mut LoadBudget) -> Result<Vec<u8>, E> {
budget.charge(Q::TemporaryBytes, count as u64)?;
let mut values = Vec::new();
values.try_reserve_exact(count).map_err(|_| {
let mut e = E::resource(Q::TemporaryBytes, count as u64, budget.limit(Q::TemporaryBytes));
e.reason = R::Allocation;
e
})?;
budget.charge(Q::TemporaryBytes, (values.capacity() - count) as u64)?;
budget.work(count)?; // Initialize every map byte before it can be read.
values.resize(count, 0);
Ok(values)
}
fn metered_decode<'a>(
pc: usize,
bytes: &'a [u8],
budget: &mut LoadBudget,
) -> Result<prometeu_bytecode::DecodedInstr<'a>, E> {
budget.work(bytes.len().saturating_sub(pc).min(2))?;
let result = decode_next(pc, bytes).map_err(|e| {
E::new(
C::InvalidCode,
match e {
DecodeError::UnknownOpcode { .. } => R::UnknownOpcode,
_ => R::Truncated,
},
)
})?;
budget.work(result.imm.len() + 1)?; // Immediate examination and instruction.
Ok(result)
}
fn error(reason: R, function: u32, pc: usize) -> E {
E::new(C::InvalidCode, reason).in_section(2).in_function(function, u32::try_from(pc).ok())
}
fn with_id(mut e: E, id: u32) -> E {
e.referenced_id = Some(id);
e
}
#[cfg(test)]
mod tests;
fn reference_error(mut e: E) -> E {
e.code = C::InvalidReference;
e
}
mod heights;
// The executable v1 loader is the pending production consumer.
#[allow(unused_imports)]
pub(crate) use heights::validate_registry_stacks;
mod types;
#[allow(unused_imports)]
pub(crate) use types::validate_registry_types;
@@ -0,0 +1,395 @@
//! Bounded basic-block stack analysis. This does not publish an image or prove
//! semantic argument types. Closure target facts preserve the existing known
//! callee restriction; no guest callable descriptor is invented here.
use super::*;
#[derive(Clone, Copy, PartialEq, Eq)]
enum Fact {
Unknown,
NonClosure,
Closure(u32),
}
pub(super) struct Block<F> {
pub start: usize,
pub end: usize,
pub state: Option<Vec<F>>,
pub queued: bool,
}
pub(crate) fn validate_registry_stacks(
code: &[u8],
registry: &Registry,
constants: usize,
budget: &mut LoadBudget,
) -> Result<(), E> {
validate_registry_instructions(code, registry, constants, budget)?;
let before = budget.used(Q::TemporaryBytes);
let result = (|| {
for (id, function) in registry.declarations().functions.iter().enumerate() {
let function_before = budget.used(Q::TemporaryBytes);
budget
.work(1)
.map_err(|e| e.in_section(2).in_function(id as u32, Some(function.code_offset)))?;
let start = function.code_offset as usize;
let body = &code[start..start + function.code_len as usize];
let mut at_pc = 0;
let result = analyze(body, registry, id as u32, budget, &mut at_pc)
.map_err(|e| e.in_section(2).in_function(id as u32, Some((start + at_pc) as u32)));
// analyze has dropped all blocks, states and the worklist here.
budget.refund(Q::TemporaryBytes, budget.used(Q::TemporaryBytes) - function_before);
result?;
}
Ok(())
})();
budget.refund(Q::TemporaryBytes, budget.used(Q::TemporaryBytes) - before);
result
}
fn analyze(
body: &[u8],
registry: &Registry,
id: u32,
budget: &mut LoadBudget,
at_pc: &mut usize,
) -> Result<(), E> {
let function = &registry.declarations().functions[id as usize];
let layout = registry.function_layout(FunctionId(id)).unwrap();
let locals = layout.parameter_slots as usize + function.local_slots as usize;
let max = function.max_stack_slots as usize;
let results = layout.result_slots as usize;
if body.is_empty() {
return if results == 0 {
Ok(())
} else {
Err(count_error(R::ReturnHeight, 0, results as u64))
};
}
let mut blocks = basic_blocks::<Fact>(body, budget, at_pc)?;
let count = blocks.len();
let mut pc;
let mut initial = scratch::<Fact>(locals, budget)?;
budget.work(locals)?;
initial.resize(locals, Fact::NonClosure); // Additional locals start Null.
budget.work(layout.parameter_slots as usize)?;
initial[..layout.parameter_slots as usize].fill(Fact::Unknown);
blocks[0].state = Some(initial);
let mut worklist = scratch::<usize>(count, budget)?;
budget.work(2)?;
blocks[0].queued = true;
worklist.push(0);
let total = locals.checked_add(max).ok_or_else(|| E::new(C::ResourceLimit, R::Overflow))?;
let mut working = scratch::<Fact>(total, budget)?;
budget.work(total)?;
working.resize(total, Fact::Unknown);
while let Some(index) = worklist.pop() {
*at_pc = blocks[index].start;
budget.work(3)?;
blocks[index].queued = false;
let input = blocks[index].state.as_ref().unwrap();
budget.work(input.len().checked_mul(2).ok_or_else(overflow)?)?;
working[..input.len()].copy_from_slice(input);
let mut height = input.len() - locals;
let end = blocks[index].end;
pc = blocks[index].start;
while pc < end {
*at_pc = pc;
let instruction = metered_decode(pc, body, budget)?;
budget.work(1)?; // Instruction transfer, independently of decoding.
let spec = instruction.opcode.spec();
let mut effect = if instruction.opcode.requires_registry() {
budget.work(
if matches!(instruction.opcode, Op::DynPack | Op::DynUnpack | Op::DynCanUnpack)
{
2
} else {
4
},
)?;
let effect = instruction.registry_stack_effect(registry)?.unwrap();
(u64::from(effect.pops), u64::from(effect.pushes))
} else {
(u64::from(spec.pops.unwrap()), u64::from(spec.pushes.unwrap()))
};
match instruction.opcode {
Op::PopN => effect = (u64::from(instruction.imm_u32().unwrap()), 0),
Op::MakeClosure => effect = (u64::from(instruction.imm_u32x2().unwrap().1), 1),
Op::Spawn => effect = (u64::from(instruction.imm_u32x2().unwrap().1), 0),
Op::Call => {
budget.work(1)?;
let callee = registry
.function_layout(FunctionId(instruction.imm_u32().unwrap()))
.unwrap();
effect = (u64::from(callee.parameter_slots), u64::from(callee.result_slots));
}
Op::CallClosure => {
let arguments = u64::from(instruction.imm_u32().unwrap());
if (height as u64) < arguments + 1 {
return Err(count_error(R::StackUnderflow, height as u64, arguments + 1));
}
budget.work(2)?;
let target = match working[locals + height - 1] {
Fact::Closure(target) => target,
Fact::NonClosure => return Err(E::new(C::InvalidCode, R::NotClosure)),
Fact::Unknown => {
return Err(E::new(C::InvalidCode, R::UnknownClosureCallee));
}
};
let callee = registry.function_layout(FunctionId(target)).unwrap();
if u64::from(callee.parameter_slots) != arguments + 1 {
return Err(count_error(
R::Signature,
arguments + 1,
u64::from(callee.parameter_slots),
)
.reference(IdDomain::Function, target));
}
effect = (arguments + 1, u64::from(callee.result_slots));
}
Op::Ret => {
if height != results {
return Err(count_error(R::ReturnHeight, height as u64, results as u64));
}
effect = (results as u64, 0);
}
Op::Syscall => {
budget.work(1)?;
let native =
prometeu_hal::syscalls::Syscall::from_u32(instruction.imm_u32().unwrap())
.unwrap();
effect = (native.args_count() as u64, native.results_count() as u64);
}
Op::Intrinsic => {
let native = crate::builtins::metered_lookup_intrinsic(
instruction.imm_u32().unwrap(),
budget,
)?
.unwrap();
effect = (native.arg_slots() as u64, native.ret_slots() as u64);
}
Op::Yield if height != 0 => {
return Err(count_error(R::InvalidYield, height as u64, 0));
}
_ => {}
}
if (height as u64) < effect.0 {
return Err(count_error(R::StackUnderflow, height as u64, effect.0));
}
let out = (height as u64) - effect.0 + effect.1;
// Zero is an actual ceiling in v1; do not infer or rewrite it.
if out > max as u64 {
return Err(count_error(R::StackOverflow, out, max as u64));
}
let popped = effect.0 as usize;
let pushed = effect.1 as usize;
let base = locals + height - popped;
match instruction.opcode {
Op::Dup => {
budget.work(3)?;
let fact = working[locals + height - 1];
working[base] = fact;
working[base + 1] = fact;
}
Op::Swap => {
budget.work(4)?;
working.swap(base, base + 1);
}
Op::GetLocal => {
budget.work(2)?;
working[base] = working[instruction.imm_u32().unwrap() as usize];
}
Op::SetLocal => {
budget.work(2)?;
working[instruction.imm_u32().unwrap() as usize] = working[base];
}
Op::MakeClosure => {
budget.work(1)?;
working[base] = Fact::Closure(instruction.imm_u32x2().unwrap().0);
}
_ => {
budget.work(pushed)?;
let fact = if matches!(
instruction.opcode,
Op::PushConst | Op::PushI32 | Op::PushI64 | Op::PushF64 | Op::PushBool
) || instruction.opcode.requires_registry()
{
Fact::NonClosure
} else {
Fact::Unknown
};
working[base..base + pushed].fill(fact);
}
}
height = out as usize;
if spec.is_branch {
let target = instruction.imm_u32().unwrap() as usize;
if target == body.len() {
if height != results {
return Err(count_error(R::ReturnHeight, height as u64, results as u64));
}
} else {
propagate(
target,
&working[..locals + height],
locals,
Fact::Unknown,
&mut blocks,
&mut worklist,
budget,
)?;
}
}
if spec.is_terminator {
break;
}
pc = instruction.next_pc;
if pc == end {
if pc == body.len() {
return Err(E::new(C::InvalidCode, R::UnterminatedPath));
}
propagate(
pc,
&working[..locals + height],
locals,
Fact::Unknown,
&mut blocks,
&mut worklist,
budget,
)?;
}
}
}
Ok(())
}
pub(super) fn propagate<F: Copy + Eq>(
target: usize,
incoming: &[F],
locals: usize,
unknown: F,
blocks: &mut [Block<F>],
queue: &mut Vec<usize>,
budget: &mut LoadBudget,
) -> Result<(), E> {
budget.work(1)?; // Edge.
let mut low = 0;
let mut high = blocks.len();
while low < high {
budget.work(1)?;
let mid = low + (high - low) / 2;
if blocks[mid].start < target {
low = mid + 1;
} else {
high = mid;
}
}
let node = &mut blocks[low];
debug_assert_eq!(node.start, target);
budget.work(1)?;
let changed = if let Some(current) = &mut node.state {
if current.len() != incoming.len() {
return Err(count_error(
R::StackJoin,
(incoming.len() - locals) as u64,
(current.len() - locals) as u64,
));
}
budget.work(incoming.len().checked_mul(3).ok_or_else(overflow)?)?;
let mut changed = false;
for (old, &new) in current.iter_mut().zip(incoming) {
if *old != new {
budget.work(1)?;
if *old != unknown {
budget.work(1)?;
*old = unknown;
changed = true;
}
}
}
changed
} else {
let mut state = scratch::<F>(incoming.len(), budget)?;
budget.work(incoming.len().checked_mul(2).ok_or_else(overflow)?)?;
state.extend_from_slice(incoming);
node.state = Some(state);
true
};
budget.work(1)?;
if changed && !node.queued {
budget.work(2)?;
debug_assert!(queue.len() < queue.capacity());
node.queued = true;
queue.push(low);
}
Ok(())
}
fn count_error(reason: R, actual: u64, expected: u64) -> E {
let mut e = E::new(C::InvalidCode, reason);
e.requested = Some(actual);
e.limit = Some(expected);
e
}
fn overflow() -> E {
E::new(C::ResourceLimit, R::Overflow)
}
pub(super) fn scratch<T>(count: usize, budget: &mut LoadBudget) -> Result<Vec<T>, E> {
let bytes = count.checked_mul(size_of::<T>()).ok_or_else(overflow)? as u64;
budget.charge(Q::TemporaryBytes, bytes)?;
let mut values = Vec::new();
values.try_reserve_exact(count).map_err(|_| {
let mut e = E::resource(Q::TemporaryBytes, bytes, budget.limit(Q::TemporaryBytes));
e.reason = R::Allocation;
e
})?;
let actual = values.capacity().checked_mul(size_of::<T>()).ok_or_else(overflow)? as u64;
budget.charge(Q::TemporaryBytes, actual - bytes)?;
Ok(values)
}
/// Metered CFG construction shared by the stack and semantic analyses.
pub(super) fn basic_blocks<F>(
body: &[u8],
budget: &mut LoadBudget,
at_pc: &mut usize,
) -> Result<Vec<Block<F>>, E> {
let mut leaders = scratch::<u8>(body.len() + 1, budget)?;
budget.work(body.len() + 2)?;
leaders.resize(body.len() + 1, 0);
leaders[0] = 1;
let mut pc = 0;
while pc < body.len() {
*at_pc = pc;
let instruction = metered_decode(pc, body, budget)?;
let spec = instruction.opcode.spec();
if spec.is_branch {
budget.work(1)?;
leaders[instruction.imm_u32().unwrap() as usize] = 1;
}
if spec.is_branch || spec.is_terminator {
budget.work(1)?;
leaders[instruction.next_pc] = 1;
}
pc = instruction.next_pc;
}
budget.work(body.len())?;
let count = leaders[..body.len()].iter().filter(|&&mark| mark != 0).count();
let mut blocks = scratch::<Block<F>>(count, budget)?;
budget.work(body.len())?;
for (pc, &mark) in leaders[..body.len()].iter().enumerate() {
if mark == 0 {
continue;
}
budget.work(2)?;
if let Some(previous) = blocks.last_mut() {
previous.end = pc;
}
blocks.push(Block { start: pc, end: body.len(), state: None, queued: false });
}
let bytes = leaders.capacity() as u64;
drop(leaders);
budget.refund(Q::TemporaryBytes, bytes);
Ok(blocks)
}
@@ -0,0 +1,570 @@
use super::*;
use prometeu_bytecode::load_limits::LoadLimits;
use prometeu_bytecode::registry::{
BuiltinId as B, FunctionDecl, NamedType, RegistryDeclarations, Signature, TypeDecl, TypeId,
TypeKind,
};
fn op(code: &mut Vec<u8>, op: Op) {
code.extend_from_slice(&(op as u16).to_le_bytes());
}
fn arg(code: &mut Vec<u8>, op_code: Op, n: u32) {
op(code, op_code);
code.extend_from_slice(&n.to_le_bytes());
}
fn registry(code: &[u8], functions: Vec<FunctionDecl>) -> Registry {
Registry::resolve(
RegistryDeclarations {
types: vec![
TypeDecl { name: None, kind: TypeKind::Builtin(B::INT32) },
TypeDecl { name: None, kind: TypeKind::Builtin(B::VEC2) },
TypeDecl { name: None, kind: TypeKind::Struct(vec![]) },
TypeDecl { name: None, kind: TypeKind::Trait(vec![]) },
],
functions,
implementations: vec![],
},
code.len(),
&mut LoadBudget::new(Default::default()),
)
.unwrap()
}
fn function(code: &[u8]) -> FunctionDecl {
FunctionDecl { code_len: code.len() as u32, max_stack_slots: 4, ..Default::default() }
}
fn check(code: &[u8], registry: &Registry) -> Result<(), E> {
validate_registry_instructions(code, registry, 1, &mut LoadBudget::new(Default::default()))
}
fn stacks(code: &[u8], registry: &Registry) -> Result<(), E> {
validate_registry_stacks(code, registry, 1, &mut LoadBudget::new(Default::default()))
}
#[test]
fn stack_analysis_honors_literal_zero_and_wide_pop_operands() {
let mut code = vec![];
arg(&mut code, Op::PushI32, 0);
op(&mut code, Op::Halt);
let r = registry(&code, vec![FunctionDecl { max_stack_slots: 0, ..function(&code) }]);
let e = stacks(&code, &r).unwrap_err();
assert_eq!(
(e.reason, e.requested, e.limit, e.pc),
(R::StackOverflow, Some(1), Some(0), Some(0))
);
for count in [65_536, u32::MAX] {
let mut code = vec![];
arg(&mut code, Op::PopN, count);
let r = registry(&code, vec![function(&code)]);
let e = stacks(&code, &r).unwrap_err();
assert_eq!(
(e.reason, e.requested, e.limit),
(R::StackUnderflow, Some(0), Some(u64::from(count)))
);
}
}
#[test]
fn stack_analysis_cannot_consume_parameters_or_extra_locals_as_temporaries() {
let mut code = vec![];
op(&mut code, Op::Pop);
let r = registry(
&code,
vec![FunctionDecl {
local_slots: 100,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(1), name: None }],
results: vec![],
},
..function(&code)
}],
);
let e = stacks(&code, &r).unwrap_err();
assert_eq!((e.reason, e.pc), (R::StackUnderflow, Some(0)));
}
#[test]
fn stack_analysis_resolves_multislot_calls_and_registry_operations() {
let mut code = vec![];
for _ in 0..2 {
op(&mut code, Op::PushF64);
code.extend_from_slice(&0f64.to_le_bytes());
}
arg(&mut code, Op::DynPack, 1);
arg(&mut code, Op::DynUnpack, 1);
arg(&mut code, Op::Call, 1);
op(&mut code, Op::Halt);
let callee = code.len();
arg(&mut code, Op::GetLocal, 0);
arg(&mut code, Op::GetLocal, 1);
op(&mut code, Op::Ret);
let signature = Signature {
parameters: vec![NamedType { type_id: TypeId(1), name: None }],
results: vec![TypeId(1)],
};
let r = registry(
&code,
vec![
FunctionDecl { code_len: callee as u32, max_stack_slots: 2, ..function(&code) },
FunctionDecl {
code_offset: callee as u32,
code_len: (code.len() - callee) as u32,
signature,
max_stack_slots: 2,
..Default::default()
},
],
);
assert!(stacks(&code, &r).is_ok());
// This is a slot proof only, not validation of Runtime Dynamic boxes.
}
#[test]
fn stack_analysis_checks_returns_empty_bodies_and_implicit_end_branches() {
for operation in [Op::Ret, Op::Jmp] {
let mut code = vec![];
if operation == Op::Jmp {
arg(&mut code, operation, 6);
} else {
op(&mut code, operation);
}
let f = FunctionDecl {
signature: Signature { parameters: vec![], results: vec![TypeId(0)] },
..function(&code)
};
let r = registry(&code, vec![f]);
let e = stacks(&code, &r).unwrap_err();
assert_eq!((e.reason, e.requested, e.limit), (R::ReturnHeight, Some(0), Some(1)));
}
// Resolved Registries already reject empty declared function bodies.
let e = Registry::resolve(
RegistryDeclarations { functions: vec![Default::default()], ..Default::default() },
0,
&mut LoadBudget::new(Default::default()),
)
.unwrap_err();
assert_eq!(e.reason, R::CodeRange);
let r = registry(&[], vec![]);
assert!(stacks(&[], &r).is_ok());
let code = (Op::Nop as u16).to_le_bytes();
let r = registry(&code, vec![function(&code)]);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::UnterminatedPath);
}
#[test]
fn stack_analysis_rejects_different_join_heights_and_accepts_a_bounded_loop() {
let mut code = vec![];
op(&mut code, Op::PushBool);
code.push(1);
arg(&mut code, Op::JmpIfTrue, 21);
arg(&mut code, Op::PushI32, 0);
arg(&mut code, Op::Jmp, 23);
op(&mut code, Op::Nop);
op(&mut code, Op::Halt);
let r = registry(&code, vec![function(&code)]);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::StackJoin);
let mut code = vec![];
arg(&mut code, Op::Jmp, 0);
let r = registry(&code, vec![FunctionDecl { max_stack_slots: 0, ..function(&code) }]);
assert!(stacks(&code, &r).is_ok());
}
#[test]
fn stack_analysis_accounts_only_reachable_transfers_but_preflights_dead_operands() {
let mut code = vec![];
op(&mut code, Op::Halt);
arg(&mut code, Op::PopN, u32::MAX);
let r = registry(&code, vec![FunctionDecl { max_stack_slots: 0, ..function(&code) }]);
assert!(stacks(&code, &r).is_ok());
let mut code = vec![];
op(&mut code, Op::Halt);
arg(&mut code, Op::GetLocal, 0);
let r = registry(&code, vec![function(&code)]);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::LocalSlot);
}
#[test]
fn stack_analysis_refunds_all_state_buffers_and_preserves_prior_ownership() {
let mut code = vec![];
arg(&mut code, Op::PushI32, 0);
op(&mut code, Op::Halt);
let r = registry(&code, vec![function(&code)]);
let mut b = LoadBudget::new(Default::default());
b.charge(Q::TemporaryBytes, 7).unwrap();
b.charge(Q::RegistryBytes, 11).unwrap();
validate_registry_stacks(&code, &r, 1, &mut b).unwrap();
assert_eq!((b.used(Q::TemporaryBytes), b.used(Q::RegistryBytes)), (7, 11));
let mut limits = LoadLimits::default();
limits.temporary_bytes = 32; // Decode maps fit; CFG/state/work buffers cannot all fit.
let mut b = LoadBudget::new(limits);
b.charge(Q::TemporaryBytes, 7).unwrap();
let e = validate_registry_stacks(&code, &r, 1, &mut b).unwrap_err();
assert_eq!((e.code, e.resource), (C::ResourceLimit, Some(Q::TemporaryBytes)));
assert_eq!(b.used(Q::TemporaryBytes), 7);
assert_eq!((e.function, e.section), (Some(0), Some(2)));
}
#[test]
fn stack_analysis_straight_line_storage_is_bounded_by_blocks_not_instruction_frames() {
let mut code = Vec::new();
for _ in 0..20_000 {
op(&mut code, Op::Nop);
}
op(&mut code, Op::Halt);
let r = registry(
&code,
vec![FunctionDecl { local_slots: 300, max_stack_slots: 0, ..function(&code) }],
);
let mut limits = LoadLimits::default();
limits.temporary_bytes = 41_000;
let mut b = LoadBudget::new(limits);
validate_registry_stacks(&code, &r, 1, &mut b).unwrap();
assert_eq!(b.used(Q::TemporaryBytes), 0);
}
#[test]
fn stack_analysis_retains_unknown_closure_and_yield_safety_rules() {
let mut code = vec![];
arg(&mut code, Op::GetLocal, 0);
arg(&mut code, Op::CallClosure, 0);
op(&mut code, Op::Halt);
let f = FunctionDecl {
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![],
},
..function(&code)
};
let r = registry(&code, vec![f]);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::UnknownClosureCallee);
let mut code = vec![];
arg(&mut code, Op::GetLocal, 0);
arg(&mut code, Op::CallClosure, 0);
let r = registry(&code, vec![FunctionDecl { local_slots: 1, ..function(&code) }]);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::NotClosure);
let mut code = vec![];
arg(&mut code, Op::PushI32, 0);
op(&mut code, Op::Yield);
let r = registry(&code, vec![function(&code)]);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::InvalidYield);
}
#[test]
fn stack_analysis_preserves_closure_facts_through_permutations_before_rejecting_bad_arity() {
let mut code = vec![];
arg(&mut code, Op::PushI32, 0);
arg(&mut code, Op::MakeClosure, 1);
code.extend_from_slice(&0u32.to_le_bytes());
op(&mut code, Op::Swap);
op(&mut code, Op::Pop);
op(&mut code, Op::Dup);
op(&mut code, Op::Pop);
arg(&mut code, Op::SetLocal, 0);
arg(&mut code, Op::GetLocal, 0);
arg(&mut code, Op::CallClosure, 0);
op(&mut code, Op::Halt);
let end = code.len();
op(&mut code, Op::Ret);
let r = registry(
&code,
vec![
FunctionDecl {
code_len: end as u32,
local_slots: 1,
max_stack_slots: 2,
..function(&code)
},
FunctionDecl { code_offset: end as u32, code_len: 2, ..Default::default() },
],
);
let e = stacks(&code, &r).unwrap_err();
// The callee deliberately lacks hidden arg0: this fixture is rejected,
// and does not invent a typed descriptor for a valid guest closure.
assert_eq!((e.reason, e.referenced_id), (R::Signature, Some(1)));
assert_eq!((e.requested, e.limit), (Some(1), Some(0)));
}
#[test]
fn stack_analysis_checks_closure_counts_without_wraparound() {
for operation in [Op::MakeClosure, Op::CallClosure] {
let mut code = vec![];
if operation == Op::MakeClosure {
arg(&mut code, operation, 0);
code.extend_from_slice(&u32::MAX.to_le_bytes());
} else {
arg(&mut code, operation, u32::MAX);
}
op(&mut code, Op::Halt);
let r = registry(&code, vec![function(&code)]);
let e = stacks(&code, &r).unwrap_err();
assert_eq!(e.reason, R::StackUnderflow);
assert_eq!(e.limit, Some(u64::from(u32::MAX) + u64::from(operation == Op::CallClosure)));
}
}
#[test]
fn stack_analysis_charges_work_for_loop_reprocessing_and_refunds_on_exhaustion() {
let mut code = vec![];
arg(&mut code, Op::Jmp, 6);
arg(&mut code, Op::GetLocal, 0);
op(&mut code, Op::Pop);
arg(&mut code, Op::Call, 1);
arg(&mut code, Op::SetLocal, 0);
op(&mut code, Op::PushBool);
code.push(1);
arg(&mut code, Op::JmpIfTrue, 6);
op(&mut code, Op::Halt);
let end = code.len();
arg(&mut code, Op::PushI32, 1);
op(&mut code, Op::Ret);
let r = registry(
&code,
vec![
FunctionDecl {
code_len: end as u32,
local_slots: 1,
max_stack_slots: 1,
..function(&code)
},
FunctionDecl {
code_offset: end as u32,
code_len: (code.len() - end) as u32,
max_stack_slots: 1,
signature: Signature { parameters: vec![], results: vec![TypeId(0)] },
..Default::default()
},
],
);
let mut b = LoadBudget::new(Default::default());
validate_registry_stacks(&code, &r, 1, &mut b).unwrap();
let mut limits = LoadLimits::default();
limits.work = b.used(Q::Work) - 1;
let mut limited = LoadBudget::new(limits);
limited.charge(Q::TemporaryBytes, 7).unwrap();
let e = validate_registry_stacks(&code, &r, 1, &mut limited).unwrap_err();
assert_eq!((e.code, e.resource), (C::ResourceLimit, Some(Q::Work)));
assert_eq!((e.function, e.pc), (Some(1), Some((code.len() - 2) as u32)));
assert_eq!(limited.used(Q::TemporaryBytes), 7);
assert_eq!(limited.used(Q::Work), limits.work);
}
#[test]
fn typed_opcodes_and_relative_jumps_are_resolved_in_declared_ranges() {
let mut code = vec![];
op(&mut code, Op::Halt);
arg(&mut code, Op::DynPack, 1);
arg(&mut code, Op::DynUnpack, 1);
arg(&mut code, Op::DynCanUnpack, 1);
for (operation, target) in
[(Op::RefIsExact, 2), (Op::RefCast, 2), (Op::RefImplements, 3), (Op::RefToTrait, 3)]
{
arg(&mut code, operation, 2);
code.extend_from_slice(&(target as u32).to_le_bytes());
}
let start = code.len();
arg(&mut code, Op::Jmp, 6);
let r = registry(
&code,
vec![
FunctionDecl { code_len: start as u32, ..function(&code) },
FunctionDecl {
code_offset: start as u32,
code_len: 6,
max_stack_slots: 0,
..Default::default()
},
],
);
assert!(check(&code, &r).is_ok());
// This phase is structural: stack heights/type groups still need the next analysis.
}
#[test]
fn unreachable_bad_type_ids_and_categories_preserve_function_and_pc() {
for (operation, id) in [(Op::DynPack, 99), (Op::RefCast, 0)] {
let mut code = vec![];
op(&mut code, Op::Halt);
arg(&mut code, operation, id);
if operation == Op::RefCast {
code.extend_from_slice(&2_u32.to_le_bytes());
}
let r = registry(&code, vec![function(&code)]);
let e = check(&code, &r).unwrap_err();
assert_eq!(e.code, C::InvalidReference);
assert_eq!(e.function, Some(0));
assert_eq!(e.pc, Some(2));
assert_eq!(e.section, Some(2));
assert_eq!(e.referenced_id, Some(id));
}
}
#[test]
fn jumps_reject_cross_range_and_mid_instruction_even_when_unreachable() {
for (target, reason) in [(7, R::JumpTarget), (3, R::InstructionBoundary)] {
let mut code = vec![];
arg(&mut code, Op::Jmp, target);
op(&mut code, Op::Halt);
let r = registry(
&code,
vec![
FunctionDecl { code_len: 6, ..function(&code) },
FunctionDecl { code_offset: 6, code_len: 2, ..function(&code) },
],
);
let e = check(&code, &r).unwrap_err();
assert_eq!((e.code, e.reason, e.pc), (C::InvalidCode, reason, Some(0)));
}
}
#[test]
fn local_bounds_use_derived_parameter_widths_and_u32_local_counts() {
let mut code = vec![];
arg(&mut code, Op::GetLocal, 70);
let mut f = function(&code);
f.signature = Signature {
parameters: vec![NamedType { type_id: TypeId(1), name: None }],
results: vec![],
};
f.local_slots = 69; // vec2 contributes two parameter slots, total 71.
let r = registry(&code, vec![f.clone()]);
assert!(check(&code, &r).is_ok());
for slot in [71, 65_536, u32::MAX] {
let mut bad = vec![];
arg(&mut bad, Op::SetLocal, slot);
let e = check(&bad, &r).unwrap_err();
assert_eq!((e.reason, e.member), (R::LocalSlot, Some(slot)));
}
let mut limits = LoadLimits::default();
limits.frame_slots = 74;
let mut budget = LoadBudget::new(limits);
let e = validate_registry_instructions(&code, &r, 1, &mut budget).unwrap_err();
assert_eq!(e.reason, R::FrameSlots); // 2 parameters + 69 locals + 4 temporaries = 75.
assert_eq!(budget.used(Q::TemporaryBytes), 0);
}
#[test]
fn unreachable_function_constant_boolean_and_native_operands_are_checked() {
for (operation, id, reason) in [
(Op::Call, u32::MAX, R::FunctionId),
(Op::PushConst, 1, R::ConstantIndex),
(Op::Intrinsic, u32::MAX, R::NativeId),
(Op::Syscall, u32::MAX, R::NativeId),
(Op::Hostcall, 0, R::UnpatchedHostcall),
] {
let mut code = vec![];
op(&mut code, Op::Halt);
arg(&mut code, operation, id);
let r = registry(&code, vec![function(&code)]);
let e = check(&code, &r).unwrap_err();
assert_eq!((e.reason, e.pc, e.referenced_id), (reason, Some(2), Some(id)));
assert_eq!(
e.code,
if operation == Op::Hostcall { C::InvalidCode } else { C::InvalidReference }
);
}
let code = [
(Op::Halt as u16).to_le_bytes().as_slice(),
(Op::PushBool as u16).to_le_bytes().as_slice(),
&[2],
]
.concat();
let r = registry(&code, vec![function(&code)]);
assert_eq!(check(&code, &r).unwrap_err().reason, R::BooleanImmediate);
}
#[test]
fn spawn_arity_does_not_truncate_and_closure_function_ids_are_checked() {
for (operation, function_id, count, reason) in
[(Op::Spawn, 0, 65_536, R::Signature), (Op::MakeClosure, 1, 0, R::FunctionId)]
{
let mut code = vec![];
op(&mut code, Op::Halt);
arg(&mut code, operation, function_id);
code.extend_from_slice(&(count as u32).to_le_bytes());
let r = registry(&code, vec![function(&code)]);
assert_eq!(check(&code, &r).unwrap_err().reason, reason);
}
}
#[test]
fn declared_range_is_not_extended_into_gaps_or_neighbor_functions() {
let code = vec![Op::Halt as u8, 0, 0xff, 0xff];
let r = registry(&code, vec![FunctionDecl { code_len: 2, ..function(&code) }]);
assert!(check(&code, &r).is_ok()); // Unowned gap is outside this phase's ranges.
let r = registry(&code, vec![function(&code)]);
assert_eq!(check(&code, &r).unwrap_err().reason, R::UnknownOpcode);
let short = &code[..1];
assert_eq!(check(short, &r).unwrap_err().reason, R::CodeRange);
}
#[test]
fn scratch_is_refunded_per_function_and_preserves_prior_load_ownership() {
let code = vec![Op::Halt as u8, 0, Op::Halt as u8, 0];
let r = registry(
&code,
vec![
FunctionDecl { code_len: 2, ..function(&code) },
FunctionDecl { code_offset: 2, code_len: 2, ..function(&code) },
],
);
let mut limits = LoadLimits::default();
limits.temporary_bytes = 8;
let mut budget = LoadBudget::new(limits);
budget.charge(Q::TemporaryBytes, 5).unwrap();
budget.charge(Q::RegistryBytes, 10).unwrap();
validate_registry_instructions(&code, &r, 1, &mut budget).unwrap();
assert_eq!(budget.used(Q::TemporaryBytes), 5); // Both 3-byte maps fit separately.
assert_eq!(budget.used(Q::RegistryBytes), 10);
assert!(budget.used(Q::Work) > 0);
}
#[test]
fn scratch_and_work_exhaustion_fail_with_context_and_no_counter_leak() {
let code = vec![Op::Halt as u8, 0];
let r = registry(&code, vec![function(&code)]);
for limits in [
LoadLimits { temporary_bytes: 2, ..Default::default() },
LoadLimits { work: 4, ..Default::default() },
] {
let mut budget = LoadBudget::new(limits);
let e = validate_registry_instructions(&code, &r, 1, &mut budget).unwrap_err();
assert_eq!(e.code, C::ResourceLimit);
assert_eq!(e.function, Some(0));
assert_eq!(e.pc, Some(0));
assert_eq!(budget.used(Q::TemporaryBytes), 0);
assert!(budget.used(Q::Work) <= budget.limit(Q::Work));
}
}
#[test]
fn truncated_immediates_cannot_borrow_bytes_from_the_next_function() {
let code = vec![Op::PushI64 as u8, 0, Op::Halt as u8, 0];
let r = registry(
&code,
vec![
FunctionDecl { code_len: 2, ..function(&code) },
FunctionDecl { code_offset: 2, code_len: 2, ..function(&code) },
],
);
let e = check(&code, &r).unwrap_err();
assert_eq!((e.code, e.reason, e.pc), (C::InvalidCode, R::Truncated, Some(0)));
}
#[test]
fn native_lookup_work_refusal_retains_the_actual_instruction_pc() {
let mut code = vec![];
op(&mut code, Op::Halt);
arg(&mut code, Op::Intrinsic, 0x2100);
let r = registry(&code, vec![function(&code)]);
assert!(check(&code, &r).is_ok()); // Known input query, even in unreachable code.
// One function + nine initialized map bytes + two decoding passes and
// boundary writes consume 33 units before the first catalogue record.
let limits = LoadLimits { work: 33, ..Default::default() };
let mut budget = LoadBudget::new(limits);
let e = validate_registry_instructions(&code, &r, 1, &mut budget).unwrap_err();
assert_eq!(
(e.code, e.resource, e.function, e.pc),
(C::ResourceLimit, Some(Q::Work), Some(0), Some(2))
);
assert_eq!(budget.used(Q::TemporaryBytes), 0);
assert_eq!(budget.used(Q::Work), 33);
}
@@ -0,0 +1,748 @@
//! Finite conservative facts, with errors decided only after convergence.
//! This never removes runtime group, null, generation or bounds validation.
use super::heights::{basic_blocks, propagate, scratch};
use super::*;
use crate::builtins::{AbiType, BuiltinScalarType};
use prometeu_bytecode::model::ConstantPoolEntry as Constant;
use prometeu_bytecode::registry::{BuiltinId as B, TypeId, TypeKind};
const I32: u8 = 1;
const I64: u8 = 2;
const FLOAT: u8 = 4;
const BOOL: u8 = 8;
const STRING: u8 = 16;
const REFERENCE: u8 = 32;
const NULL: u8 = 64;
const ANY: u8 = 127;
const NUMERIC: u8 = I32 | I64 | FLOAT;
#[derive(Clone, Copy, PartialEq, Eq)]
enum Fact {
Unknown,
Null,
Carrier(u8),
Int64(i64),
Group { ty: TypeId, part: u32, origin: u64 },
Dynamic { part: u32, origin: u64 },
Closure(u32),
}
pub(crate) fn validate_registry_types(
code: &[u8],
registry: &Registry,
constants: &[Constant],
budget: &mut LoadBudget,
) -> Result<(), E> {
heights::validate_registry_stacks(code, registry, constants.len(), budget)?;
let before = budget.used(Q::TemporaryBytes);
let result = (|| {
for (id, function) in registry.declarations().functions.iter().enumerate() {
let phase_before = budget.used(Q::TemporaryBytes);
let start = function.code_offset as usize;
let body = &code[start..start + function.code_len as usize];
let mut pc = 0;
let result = analyze(body, registry, id as u32, constants, budget, &mut pc)
.map_err(|e| e.in_section(2).in_function(id as u32, Some((start + pc) as u32)));
budget.refund(Q::TemporaryBytes, budget.used(Q::TemporaryBytes) - phase_before);
result?;
}
Ok(())
})();
budget.refund(Q::TemporaryBytes, budget.used(Q::TemporaryBytes) - before);
result
}
fn analyze(
body: &[u8],
registry: &Registry,
id: u32,
constants: &[Constant],
budget: &mut LoadBudget,
at_pc: &mut usize,
) -> Result<(), E> {
let function = &registry.declarations().functions[id as usize];
let layout = registry.function_layout(FunctionId(id)).unwrap();
let locals = layout.parameter_slots as usize + function.local_slots as usize;
let mut blocks = basic_blocks::<Fact>(body, budget, at_pc)?;
let mut initial = scratch::<Fact>(locals, budget)?;
budget.work(locals)?;
initial.resize(locals, Fact::Null);
let mut offset = 0;
for (index, parameter) in function.signature.parameters.iter().enumerate() {
let width = group(
&mut initial[offset..],
registry,
parameter.type_id,
(1u64 << 63) | index as u64,
budget,
)?;
offset += width;
}
budget.work(2)?;
blocks[0].state = Some(initial);
blocks[0].queued = true;
let mut queue = scratch::<usize>(blocks.len(), budget)?;
queue.push(0);
let count = locals + function.max_stack_slots as usize;
let mut working = scratch::<Fact>(count, budget)?;
budget.work(count)?;
working.resize(count, Fact::Unknown);
// Phase one transfers and widens facts without reporting state-dependent
// mismatches. Calls use signatures, not interprocedural body inference.
while let Some(index) = queue.pop() {
*at_pc = blocks[index].start;
budget.work(3)?;
blocks[index].queued = false;
let input = blocks[index].state.as_ref().unwrap();
budget.work(input.len() * 2)?;
working[..input.len()].copy_from_slice(input);
let mut height = input.len() - locals;
let mut pc = blocks[index].start;
let end = blocks[index].end;
while pc < end {
*at_pc = pc;
let instruction = metered_decode(pc, body, budget)?;
transfer(&instruction, &mut working, locals, &mut height, registry, constants, budget)?;
let spec = instruction.opcode.spec();
if spec.is_branch {
let target = instruction.imm_u32().unwrap() as usize;
if target < body.len() {
propagate(
target,
&working[..locals + height],
locals,
Fact::Unknown,
&mut blocks,
&mut queue,
budget,
)?;
}
}
if spec.is_terminator {
break;
}
pc = instruction.next_pc;
if pc == end && pc < body.len() {
propagate(
pc,
&working[..locals + height],
locals,
Fact::Unknown,
&mut blocks,
&mut queue,
budget,
)?;
}
}
}
// Phase two deterministically replays only stabilized reachable states.
for block in &blocks {
*at_pc = block.start;
budget.work(1)?;
let Some(input) = &block.state else {
continue;
};
budget.work(input.len() * 2)?;
working[..input.len()].copy_from_slice(input);
let mut height = input.len() - locals;
let mut pc = block.start;
while pc < block.end {
*at_pc = pc;
let instruction = metered_decode(pc, body, budget)?;
check(&instruction, &working, locals, height, registry, id, budget)?;
transfer(&instruction, &mut working, locals, &mut height, registry, constants, budget)?;
if instruction.opcode.spec().is_terminator {
break;
}
pc = instruction.next_pc;
}
}
Ok(())
}
fn group(
out: &mut [Fact],
registry: &Registry,
ty: TypeId,
origin: u64,
budget: &mut LoadBudget,
) -> Result<usize, E> {
budget.work(1)?;
let width = registry.type_layout(ty).unwrap().storage.slots as usize;
budget.work(width)?;
for (part, fact) in out[..width].iter_mut().enumerate() {
*fact = Fact::Group { ty, part: part as u32, origin };
}
Ok(width)
}
fn component(registry: &Registry, ty: TypeId, part: u32, budget: &mut LoadBudget) -> Result<u8, E> {
budget.work(1)?;
Ok(match &registry.declarations().types[ty.0 as usize].kind {
TypeKind::Struct(_) | TypeKind::Array(_) => REFERENCE | NULL,
TypeKind::Trait(_) => {
if part == 0 {
REFERENCE | NULL
} else {
I64 | NULL
}
}
TypeKind::Builtin(B::INT32) => I32,
TypeKind::Builtin(B::INT64 | B::COLOR | B::PIXEL) => I64,
TypeKind::Builtin(B::FLOAT | B::VEC2) => FLOAT,
TypeKind::Builtin(B::BOOL) => BOOL,
TypeKind::Builtin(B::STRING) => STRING | NULL,
TypeKind::Builtin(B::DYNAMIC) => {
if part == 0 {
I64 | NULL
} else {
ANY
}
}
_ => unreachable!("Registry rejects unsupported BuiltinIds"),
})
}
fn mask(fact: Fact, registry: &Registry, budget: &mut LoadBudget) -> Result<u8, E> {
budget.work(1)?;
Ok(match fact {
Fact::Unknown => ANY,
Fact::Null => NULL,
Fact::Carrier(mask) => mask,
Fact::Int64(_) => I64,
Fact::Closure(_) => REFERENCE,
Fact::Group { ty, part, .. } => return component(registry, ty, part, budget),
Fact::Dynamic { part: 0, .. } => I64 | NULL,
Fact::Dynamic { .. } => ANY,
})
}
fn invalidate(
working: &mut [Fact],
ty: TypeId,
origin: u64,
registry: &Registry,
budget: &mut LoadBudget,
) -> Result<(), E> {
budget.work(1)?;
if registry.type_layout(ty).unwrap().storage.slots <= 1 {
return Ok(());
}
budget.work(working.len() * 2)?;
for fact in working {
if let Fact::Group { ty, part, origin: other } = *fact {
if origin == other {
let carrier = component(registry, ty, part, budget)?;
budget.work(1)?;
*fact = if carrier == ANY { Fact::Unknown } else { Fact::Carrier(carrier) };
}
}
}
Ok(())
}
fn transfer(
instruction: &prometeu_bytecode::DecodedInstr<'_>,
working: &mut [Fact],
locals: usize,
height: &mut usize,
registry: &Registry,
constants: &[Constant],
budget: &mut LoadBudget,
) -> Result<(), E> {
budget.work(1)?;
let opcode = instruction.opcode;
let spec = opcode.spec();
let (mut pops, mut pushes) = if opcode.requires_registry() {
budget.work(4)?;
let effect = instruction.registry_stack_effect(registry)?.unwrap();
(effect.pops as usize, effect.pushes as usize)
} else {
(spec.pops.unwrap() as usize, spec.pushes.unwrap() as usize)
};
let mut call = None;
let mut native = None;
match opcode {
Op::PopN => pops = instruction.imm_u32().unwrap() as usize,
Op::MakeClosure => pops = instruction.imm_u32x2().unwrap().1 as usize,
Op::Spawn => pops = instruction.imm_u32x2().unwrap().1 as usize,
Op::Call | Op::CallClosure => {
budget.work(1)?;
let target = if opcode == Op::Call {
instruction.imm_u32().unwrap()
} else {
let Fact::Closure(target) = working[locals + *height - 1] else {
return Err(E::new(C::InvalidCode, R::UnknownClosureCallee));
};
target
};
let layout = registry.function_layout(FunctionId(target)).unwrap();
pops = layout.parameter_slots as usize;
pushes = layout.result_slots as usize;
call = Some(target);
}
Op::Ret => {
// Stack analysis has already proved exact height; no continuation.
pops = *height;
pushes = 0;
}
Op::Syscall => {
budget.work(1)?;
let syscall =
prometeu_hal::syscalls::Syscall::from_u32(instruction.imm_u32().unwrap()).unwrap();
pops = syscall.args_count();
pushes = syscall.results_count();
}
Op::Intrinsic => {
let meta =
crate::builtins::metered_lookup_intrinsic(instruction.imm_u32().unwrap(), budget)?
.unwrap();
pops = meta.arg_slots();
pushes = meta.ret_slots();
native = Some(meta);
}
_ => {}
}
let base = locals + *height - pops;
let before = locals + *height;
// A partial pop destroys the group's relational proof, including copies.
// Every group has at most three components; do not do an unbounded search.
for index in base..before {
budget.work(1)?;
if let Fact::Group { ty, origin, part } = working[index] {
budget.work(1)?;
let width = registry.type_layout(ty).unwrap().storage.slots as usize;
if width > 1 {
let start = index.checked_sub(part as usize);
budget.work(width * 2)?;
let intact = start.is_some_and(|start| start >= base && start + width <= before)
&& (0..width).all(|part| {
working[start.unwrap() + part]
== Fact::Group { ty, origin, part: part as u32 }
});
if !intact {
invalidate(&mut working[..base], ty, origin, registry, budget)?;
}
}
}
if let Fact::Dynamic { origin, part } = working[index] {
budget.work(4)?;
let start = index.checked_sub(part as usize);
let intact = start.is_some_and(|start| start >= base && start + 2 <= before)
&& (0..2).all(|part| {
working[start.unwrap() + part] == Fact::Dynamic { part: part as u32, origin }
});
if !intact {
invalidate_dynamic(&mut working[..base], origin, budget)?;
}
}
}
match opcode {
Op::Dup => {
budget.work(3)?;
let fact = working[before - 1];
working[base] = fact;
working[base + 1] = fact;
}
Op::Swap => {
budget.work(4)?;
working.swap(base, base + 1);
}
Op::GetLocal => {
budget.work(2)?;
working[base] = working[instruction.imm_u32().unwrap() as usize];
}
Op::SetLocal => {
budget.work(3)?;
let slot = instruction.imm_u32().unwrap() as usize;
let source = working[base];
if let Fact::Group { ty, origin, .. } = working[slot] {
invalidate(&mut working[..before], ty, origin, registry, budget)?;
}
if let Fact::Dynamic { origin, .. } = working[slot] {
invalidate_dynamic(&mut working[..before], origin, budget)?;
}
working[slot] = source;
}
Op::PushI32 => {
budget.work(1)?;
working[base] = Fact::Carrier(I32);
}
Op::PushI64 => {
budget.work(1)?;
working[base] = Fact::Int64(i64::from_le_bytes(instruction.imm.try_into().unwrap()));
}
Op::PushF64 => {
budget.work(1)?;
working[base] = Fact::Carrier(FLOAT);
}
Op::PushBool => {
budget.work(1)?;
working[base] = Fact::Carrier(BOOL);
}
Op::PushConst => {
budget.work(2)?;
working[base] = match &constants[instruction.imm_u32().unwrap() as usize] {
Constant::Null => Fact::Null,
Constant::Int32(_) => Fact::Carrier(I32),
Constant::Int64(value) => Fact::Int64(*value),
Constant::Float64(_) => Fact::Carrier(FLOAT),
Constant::Boolean(_) => Fact::Carrier(BOOL),
Constant::String(_) => Fact::Carrier(STRING),
};
}
Op::MakeClosure => {
budget.work(1)?;
working[base] = Fact::Closure(instruction.imm_u32x2().unwrap().0);
}
Op::Call | Op::CallClosure => {
let signature = &registry.declarations().functions[call.unwrap() as usize].signature;
let mut offset = base;
for (index, ty) in signature.results.iter().enumerate() {
offset += group(
&mut working[offset..],
registry,
*ty,
(instruction.pc as u64) << 32 | index as u64,
budget,
)?;
}
}
Op::Intrinsic => {
for (offset, abi) in native.unwrap().ret_layout.iter().enumerate() {
budget.work(1)?;
working[base + offset] = Fact::Carrier(abi_mask(*abi));
}
}
Op::DynPack => {
budget.work(1)?;
let ty = TypeId(instruction.imm_u32().unwrap());
if !matches!(
registry.declarations().types[ty.0 as usize].kind,
TypeKind::Builtin(B::DYNAMIC)
) {
budget.work(2)?;
let origin = (1u64 << 62) | instruction.pc as u64;
working[base] = Fact::Dynamic { part: 0, origin };
working[base + 1] = Fact::Dynamic { part: 1, origin };
}
}
Op::DynUnpack => {
budget.work(1)?;
let ty = TypeId(instruction.imm_u32().unwrap());
if !matches!(
registry.declarations().types[ty.0 as usize].kind,
TypeKind::Builtin(B::DYNAMIC)
) {
group(&mut working[base..], registry, ty, (instruction.pc as u64) << 32, budget)?;
}
}
Op::RefCast | Op::RefToTrait => {
group(
&mut working[base..],
registry,
TypeId(instruction.imm_u32x2().unwrap().1),
(instruction.pc as u64) << 32,
budget,
)?;
}
Op::Eq
| Op::Neq
| Op::Lt
| Op::Gt
| Op::Lte
| Op::Gte
| Op::And
| Op::Or
| Op::Not
| Op::RefIsExact
| Op::RefImplements
| Op::DynCanUnpack => {
budget.work(1)?;
working[base] = Fact::Carrier(BOOL);
}
Op::Add
| Op::Sub
| Op::Mul
| Op::Div
| Op::Mod
| Op::BitAnd
| Op::BitOr
| Op::BitXor
| Op::Shl
| Op::Shr => {
let left = mask(working[base], registry, budget)?;
let right = mask(working[base + 1], registry, budget)?;
let out = if opcode == Op::Add && (left == STRING || right == STRING) {
STRING
} else if left & !NUMERIC == 0 && right & !NUMERIC == 0 {
if left == FLOAT || right == FLOAT {
FLOAT
} else if left == I64 || right == I64 {
I64
} else {
I32
}
} else {
ANY
};
budget.work(1)?;
working[base] = if out == ANY { Fact::Unknown } else { Fact::Carrier(out) };
}
Op::Neg => {
let carrier = mask(working[base], registry, budget)?;
budget.work(1)?;
working[base] = Fact::Carrier(carrier);
}
_ => {
budget.work(pushes)?;
working[base..base + pushes].fill(Fact::Unknown);
}
}
*height = *height - pops + pushes;
Ok(())
}
fn abi_mask(abi: AbiType) -> u8 {
match abi {
AbiType::Scalar(BuiltinScalarType::Int32) => I32,
AbiType::Scalar(BuiltinScalarType::Int64) => I64,
AbiType::Scalar(BuiltinScalarType::Float) => FLOAT,
AbiType::Scalar(BuiltinScalarType::Bool) => BOOL,
AbiType::Scalar(BuiltinScalarType::String) => STRING,
AbiType::Builtin(key) if key.name == "color" => I64,
AbiType::DynamicTag => I64 | NULL,
_ => ANY,
}
}
fn invalidate_dynamic(values: &mut [Fact], origin: u64, budget: &mut LoadBudget) -> Result<(), E> {
budget.work(values.len() * 2)?;
for value in values {
if let Fact::Dynamic { part, origin: other } = *value {
if origin == other {
budget.work(1)?;
*value = if part == 0 { Fact::Carrier(I64 | NULL) } else { Fact::Unknown };
}
}
}
Ok(())
}
fn mismatch(member: usize) -> E {
E::new(C::InvalidCode, R::TypeMismatch).member(member as u32)
}
fn require(
value: Fact,
allowed: u8,
member: usize,
registry: &Registry,
budget: &mut LoadBudget,
) -> Result<(), E> {
if mask(value, registry, budget)? & allowed == 0 { Err(mismatch(member)) } else { Ok(()) }
}
fn check_group(
values: &[Fact],
ty: TypeId,
registry: &Registry,
budget: &mut LoadBudget,
) -> Result<(), E> {
budget.work(2)?;
let kind = &registry.declarations().types[ty.0 as usize].kind;
let width = registry.type_layout(ty).unwrap().storage.slots as usize;
if matches!(values[0], Fact::Closure(_))
&& matches!(kind, TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Trait(_))
{
return Err(mismatch(0).reference(IdDomain::Type, ty.0));
}
budget.work(1)?;
if let Fact::Group { ty: source, part: 0, origin } = values[0] {
budget.work(1)?;
if source != ty && registry.type_layout(source).unwrap().storage.slots as usize == width {
budget.work(width * 2)?;
if values[..width]
.iter()
.enumerate()
.all(|(part, &fact)| fact == Fact::Group { ty: source, part: part as u32, origin })
{
return Err(mismatch(0).reference(IdDomain::Type, ty.0));
}
}
}
if let [Fact::Dynamic { part: 0, origin: left }, Fact::Dynamic { part: 1, origin: right }] =
&values[..width]
{
budget.work(1)?;
if left == right && !matches!(kind, TypeKind::Builtin(B::DYNAMIC)) {
return Err(mismatch(0).reference(IdDomain::Type, ty.0));
}
}
for (part, &value) in values[..width].iter().enumerate() {
require(value, component(registry, ty, part as u32, budget)?, part, registry, budget)
.map_err(|e| e.reference(IdDomain::Type, ty.0))?;
}
// Known invalid pair/range facts are proof; uncertain relations retain the
// runtime whole-group check, even if their component carriers match.
if matches!(kind, TypeKind::Trait(_) | TypeKind::Builtin(B::DYNAMIC))
&& values[0] == Fact::Null
&& mask(values[1], registry, budget)? & NULL == 0
{
return Err(mismatch(1).reference(IdDomain::Type, ty.0));
}
let color = matches!(kind, TypeKind::Builtin(B::COLOR | B::PIXEL));
if color {
budget.work(1)?;
if let Fact::Int64(value) = values[width - 1] {
if u32::try_from(value).is_err() {
return Err(mismatch(width - 1).reference(IdDomain::Type, ty.0));
}
}
}
Ok(())
}
fn check(
instruction: &prometeu_bytecode::DecodedInstr<'_>,
working: &[Fact],
locals: usize,
height: usize,
registry: &Registry,
id: u32,
budget: &mut LoadBudget,
) -> Result<(), E> {
budget.work(1)?;
let end = locals + height;
match instruction.opcode {
Op::Call | Op::Spawn => {
let target = if instruction.opcode == Op::Call {
instruction.imm_u32().unwrap()
} else {
instruction.imm_u32x2().unwrap().0
};
budget.work(1)?;
let callee = registry.function_layout(FunctionId(target)).unwrap();
let mut base = end - callee.parameter_slots as usize;
for parameter in
&registry.declarations().functions[target as usize].signature.parameters
{
check_group(&working[base..], parameter.type_id, registry, budget)?;
budget.work(1)?;
base += registry.type_layout(parameter.type_id).unwrap().storage.slots as usize;
}
}
Op::Ret => {
let mut base = locals;
for ty in &registry.declarations().functions[id as usize].signature.results {
check_group(&working[base..], *ty, registry, budget)?;
budget.work(1)?;
base += registry.type_layout(*ty).unwrap().storage.slots as usize;
}
}
Op::CallClosure => {
budget.work(1)?;
let Fact::Closure(target) = working[end - 1] else {
return Err(E::new(C::InvalidCode, R::UnknownClosureCallee));
};
let parameters =
&registry.declarations().functions[target as usize].signature.parameters;
budget.work(1)?;
let receiver = parameters.first().unwrap();
if registry.type_layout(receiver.type_id).unwrap().storage.slots != 1 {
return Err(mismatch(0));
}
check_group(&working[end - 1..end], receiver.type_id, registry, budget)?;
let mut base = end - instruction.imm_u32().unwrap() as usize - 1;
for parameter in parameters.iter().skip(1) {
check_group(&working[base..], parameter.type_id, registry, budget)?;
budget.work(1)?;
base += registry.type_layout(parameter.type_id).unwrap().storage.slots as usize;
}
}
Op::DynPack => {
budget.work(1)?;
let ty = TypeId(instruction.imm_u32().unwrap());
let width = registry.type_layout(ty).unwrap().storage.slots as usize;
check_group(&working[end - width..], ty, registry, budget)?;
}
Op::DynUnpack | Op::DynCanUnpack => {
if let [
Fact::Group { ty, part: 0, origin: left },
Fact::Group { ty: other, part: 1, origin: right },
] = &working[end - 2..end]
{
budget.work(1)?;
if ty == other
&& left == right
&& !matches!(
registry.declarations().types[ty.0 as usize].kind,
TypeKind::Builtin(B::DYNAMIC)
)
{
return Err(mismatch(0));
}
}
require(working[end - 2], I64 | NULL, 0, registry, budget)?;
if working[end - 2] == Fact::Null
&& mask(working[end - 1], registry, budget)? & NULL == 0
{
return Err(mismatch(1));
}
}
Op::RefCast | Op::RefToTrait | Op::RefIsExact | Op::RefImplements => {
budget.work(1)?;
let ty = TypeId(instruction.imm_u32x2().unwrap().0);
let width = registry.type_layout(ty).unwrap().storage.slots as usize;
check_group(&working[end - width..], ty, registry, budget)?;
}
Op::Intrinsic => {
let native =
crate::builtins::metered_lookup_intrinsic(instruction.imm_u32().unwrap(), budget)?
.unwrap();
let base = end - native.arg_slots();
for (part, abi) in native.arg_layout.iter().enumerate() {
require(working[base + part], abi_mask(*abi), part, registry, budget)?;
}
}
Op::JmpIfTrue | Op::JmpIfFalse | Op::Not => {
require(working[end - 1], BOOL, 0, registry, budget)?
}
Op::And | Op::Or => {
require(working[end - 2], BOOL, 0, registry, budget)?;
require(working[end - 1], BOOL, 1, registry, budget)?;
}
Op::Neg => require(working[end - 1], NUMERIC, 0, registry, budget)?,
Op::Lt | Op::Gt | Op::Lte | Op::Gte => {
let left = mask(working[end - 2], registry, budget)?;
let right = mask(working[end - 1], registry, budget)?;
if !(left & NUMERIC != 0 && right & NUMERIC != 0
|| left & STRING != 0 && right & STRING != 0
|| left & BOOL != 0 && right & BOOL != 0)
{
return Err(mismatch(0));
}
}
Op::Add
| Op::Sub
| Op::Mul
| Op::Div
| Op::Mod
| Op::BitAnd
| Op::BitOr
| Op::BitXor
| Op::Shl
| Op::Shr => {
let left = mask(working[end - 2], registry, budget)?;
let right = mask(working[end - 1], registry, budget)?;
if instruction.opcode != Op::Add || (left & STRING == 0 && right & STRING == 0) {
let allowed = if matches!(
instruction.opcode,
Op::BitAnd | Op::BitOr | Op::BitXor | Op::Shl | Op::Shr
) {
I32 | I64
} else {
NUMERIC
};
require(working[end - 2], allowed, 0, registry, budget)?;
require(working[end - 1], allowed, 1, registry, budget)?;
}
}
_ => {}
}
Ok(())
}
#[cfg(test)]
mod tests;
@@ -0,0 +1,309 @@
use super::*;
use prometeu_bytecode::load_limits::LoadLimits;
use prometeu_bytecode::registry::{
FunctionDecl, NamedType, RegistryDeclarations, Signature, TypeDecl,
};
fn op(code: &mut Vec<u8>, opcode: Op) {
code.extend_from_slice(&(opcode as u16).to_le_bytes());
}
fn arg(code: &mut Vec<u8>, opcode: Op, value: u32) {
op(code, opcode);
code.extend_from_slice(&value.to_le_bytes());
}
fn boolean(code: &mut Vec<u8>, value: bool) {
op(code, Op::PushBool);
code.push(u8::from(value));
}
fn int64(code: &mut Vec<u8>, value: i64) {
op(code, Op::PushI64);
code.extend_from_slice(&value.to_le_bytes());
}
fn float(code: &mut Vec<u8>, value: f64) {
op(code, Op::PushF64);
code.extend_from_slice(&value.to_le_bytes());
}
fn function(
offset: usize,
len: usize,
parameters: &[u32],
results: &[u32],
locals: u32,
max: u32,
) -> FunctionDecl {
FunctionDecl {
code_offset: offset as u32,
code_len: len as u32,
local_slots: locals,
max_stack_slots: max,
signature: Signature {
parameters: parameters
.iter()
.map(|&id| NamedType { name: None, type_id: TypeId(id) })
.collect(),
results: results.iter().copied().map(TypeId).collect(),
},
name: None,
}
}
fn registry(code: &[u8], functions: Vec<FunctionDecl>) -> Registry {
let kind = |kind| TypeDecl { name: None, kind };
Registry::resolve(
RegistryDeclarations {
types: vec![
kind(TypeKind::Builtin(B::INT32)),
kind(TypeKind::Builtin(B::INT64)),
kind(TypeKind::Builtin(B::FLOAT)),
kind(TypeKind::Builtin(B::BOOL)),
kind(TypeKind::Builtin(B::STRING)),
kind(TypeKind::Builtin(B::VEC2)),
kind(TypeKind::Builtin(B::COLOR)),
kind(TypeKind::Builtin(B::PIXEL)),
kind(TypeKind::Builtin(B::DYNAMIC)),
kind(TypeKind::Struct(vec![])),
kind(TypeKind::Struct(vec![])),
kind(TypeKind::Trait(vec![])),
],
functions,
implementations: vec![],
},
code.len(),
&mut LoadBudget::new(Default::default()),
)
.unwrap()
}
fn check(code: &[u8], r: &Registry, constants: &[Constant]) -> Result<(), E> {
validate_registry_types(code, r, constants, &mut LoadBudget::new(Default::default()))
}
#[test]
fn equal_height_mixed_type_joins_are_order_independent_and_require_runtime_checks() {
for reverse in [false, true] {
let mut code = vec![];
arg(&mut code, Op::GetLocal, 0);
let branch = code.len();
arg(&mut code, Op::JmpIfTrue, 0);
if reverse {
boolean(&mut code, true);
} else {
arg(&mut code, Op::PushI32, 1);
}
let jump = code.len();
arg(&mut code, Op::Jmp, 0);
let right = code.len();
if reverse {
arg(&mut code, Op::PushI32, 1);
} else {
boolean(&mut code, true);
}
let join = code.len();
arg(&mut code, Op::Call, 1);
op(&mut code, Op::Halt);
let main_end = code.len();
op(&mut code, Op::Ret);
code[branch + 2..branch + 6].copy_from_slice(&(right as u32).to_le_bytes());
code[jump + 2..jump + 6].copy_from_slice(&(join as u32).to_le_bytes());
let r = registry(
&code,
vec![function(0, main_end, &[3], &[], 0, 1), function(main_end, 2, &[0], &[], 0, 0)],
);
assert!(check(&code, &r, &[]).is_ok());
}
}
#[test]
fn loop_widening_happens_before_type_error_decisions() {
let mut code = vec![];
boolean(&mut code, false);
arg(&mut code, Op::SetLocal, 0);
let jump = code.len();
arg(&mut code, Op::Jmp, 0);
let header = code.len();
arg(&mut code, Op::GetLocal, 0);
arg(&mut code, Op::Call, 1);
arg(&mut code, Op::PushI32, 1);
arg(&mut code, Op::SetLocal, 0);
boolean(&mut code, true);
arg(&mut code, Op::JmpIfTrue, header as u32);
op(&mut code, Op::Halt);
let end = code.len();
op(&mut code, Op::Ret);
code[jump + 2..jump + 6].copy_from_slice(&(header as u32).to_le_bytes());
let r =
registry(&code, vec![function(0, end, &[], &[], 1, 1), function(end, 2, &[0], &[], 0, 0)]);
// No branch-condition inference: the stabilized call input is Unknown,
// so the runtime still discriminates the actual argument at consumption.
assert!(check(&code, &r, &[]).is_ok());
}
#[test]
fn proved_call_and_return_mismatches_preserve_exact_type_and_pc() {
let mut code = vec![];
boolean(&mut code, true);
let pc = code.len();
arg(&mut code, Op::Call, 1);
op(&mut code, Op::Halt);
let end = code.len();
op(&mut code, Op::Ret);
let r =
registry(&code, vec![function(0, end, &[], &[], 0, 1), function(end, 2, &[0], &[], 0, 0)]);
let e = check(&code, &r, &[]).unwrap_err();
assert_eq!(
(e.code, e.reason, e.function, e.pc, e.referenced_id),
(C::InvalidCode, R::TypeMismatch, Some(0), Some(pc as u32), Some(0))
);
let mut code = vec![];
boolean(&mut code, true);
op(&mut code, Op::Ret);
let r = registry(&code, vec![function(0, code.len(), &[], &[0], 0, 1)]);
assert_eq!(check(&code, &r, &[]).unwrap_err().pc, Some(3));
}
#[test]
fn generic_null_locals_are_nullable_but_never_numeric_defaults() {
for (result, accepted) in [(0, false), (4, true), (9, true)] {
let mut code = vec![];
arg(&mut code, Op::GetLocal, 0);
op(&mut code, Op::Ret);
let r = registry(&code, vec![function(0, code.len(), &[], &[result], 1, 1)]);
assert_eq!(check(&code, &r, &[]).is_ok(), accepted);
}
}
#[test]
fn exact_nominal_groups_need_an_explicit_reference_cast() {
for explicit in [false, true] {
let mut code = vec![];
arg(&mut code, Op::GetLocal, 0);
if explicit {
arg(&mut code, Op::RefCast, 9);
code.extend_from_slice(&10u32.to_le_bytes());
}
arg(&mut code, Op::Call, 1);
op(&mut code, Op::Halt);
let end = code.len();
op(&mut code, Op::Ret);
let r = registry(
&code,
vec![function(0, end, &[9], &[], 0, 1), function(end, 2, &[10], &[], 0, 0)],
);
assert_eq!(check(&code, &r, &[]).is_ok(), explicit);
}
}
#[test]
fn partial_multislot_writes_keep_carriers_but_drop_the_relational_proof() {
let mut code = vec![];
float(&mut code, 3.0);
arg(&mut code, Op::SetLocal, 1);
arg(&mut code, Op::GetLocal, 0);
arg(&mut code, Op::GetLocal, 1);
arg(&mut code, Op::Call, 1);
op(&mut code, Op::Halt);
let end = code.len();
op(&mut code, Op::Ret);
let r =
registry(&code, vec![function(0, end, &[5], &[], 0, 2), function(end, 2, &[5], &[], 0, 0)]);
assert!(check(&code, &r, &[]).is_ok());
// Reusing a scalar local does not impose its original parameter type.
let mut code = vec![];
boolean(&mut code, true);
arg(&mut code, Op::SetLocal, 0);
arg(&mut code, Op::GetLocal, 0);
op(&mut code, Op::Ret);
let r = registry(&code, vec![function(0, code.len(), &[0], &[3], 0, 1)]);
assert!(check(&code, &r, &[]).is_ok());
}
#[test]
fn invalid_trait_dynamic_pairs_and_color_ranges_are_proved_mismatches() {
for parameter in [8, 11] {
let mut code = vec![];
arg(&mut code, Op::PushConst, 0);
int64(&mut code, 0);
arg(&mut code, Op::Call, 1);
op(&mut code, Op::Halt);
let end = code.len();
op(&mut code, Op::Ret);
let r = registry(
&code,
vec![function(0, end, &[], &[], 0, 2), function(end, 2, &[parameter], &[], 0, 0)],
);
assert_eq!(check(&code, &r, &[Constant::Null]).unwrap_err().reason, R::TypeMismatch);
}
let mut code = vec![];
int64(&mut code, i64::from(u32::MAX) + 1);
arg(&mut code, Op::DynPack, 6);
op(&mut code, Op::Halt);
let r = registry(&code, vec![function(0, code.len(), &[], &[], 0, 2)]);
assert_eq!(check(&code, &r, &[]).unwrap_err().referenced_id, Some(6));
}
#[test]
fn arithmetic_promotions_do_not_promote_typed_boundaries() {
for (result, accepted) in [(0, false), (1, true)] {
let mut code = vec![];
arg(&mut code, Op::PushI32, 1);
int64(&mut code, 2);
op(&mut code, Op::Add);
op(&mut code, Op::Ret);
let r = registry(&code, vec![function(0, code.len(), &[], &[result], 0, 2)]);
assert_eq!(check(&code, &r, &[]).is_ok(), accepted);
}
}
#[test]
fn intrinsic_and_reference_operands_are_checked_after_convergence() {
let mut code = vec![];
for _ in 0..4 {
boolean(&mut code, true);
}
arg(&mut code, Op::Intrinsic, 0x1000);
op(&mut code, Op::Halt);
let r = registry(&code, vec![function(0, code.len(), &[], &[], 0, 4)]);
assert_eq!(check(&code, &r, &[]).unwrap_err().reason, R::TypeMismatch);
let mut code = vec![];
boolean(&mut code, true);
arg(&mut code, Op::RefIsExact, 9);
code.extend_from_slice(&9u32.to_le_bytes());
op(&mut code, Op::Halt);
let r = registry(&code, vec![function(0, code.len(), &[], &[], 0, 1)]);
assert_eq!(check(&code, &r, &[]).unwrap_err().reason, R::TypeMismatch);
}
#[test]
fn known_closure_receivers_are_not_faked_as_user_struct_types() {
let mut code = vec![];
arg(&mut code, Op::MakeClosure, 1);
code.extend_from_slice(&0u32.to_le_bytes());
arg(&mut code, Op::CallClosure, 0);
op(&mut code, Op::Halt);
let end = code.len();
op(&mut code, Op::Ret);
let r =
registry(&code, vec![function(0, end, &[], &[], 0, 1), function(end, 2, &[9], &[], 0, 0)]);
// No provisional callable descriptor: a Closure is never a guest Struct.
assert_eq!(check(&code, &r, &[]).unwrap_err().reason, R::TypeMismatch);
}
#[test]
fn type_analysis_is_metered_and_releases_scratch_on_success_and_failure() {
let mut code = vec![];
arg(&mut code, Op::PushI32, 0);
op(&mut code, Op::Ret);
let r = registry(&code, vec![function(0, code.len(), &[], &[0], 0, 1)]);
let mut full = LoadBudget::new(Default::default());
validate_registry_types(&code, &r, &[], &mut full).unwrap();
assert_eq!(full.used(Q::TemporaryBytes), 0);
let mut limits = LoadLimits::default();
limits.work = full.used(Q::Work) - 1;
let mut limited = LoadBudget::new(limits);
limited.charge(Q::TemporaryBytes, 7).unwrap();
let e = validate_registry_types(&code, &r, &[], &mut limited).unwrap_err();
assert_eq!(
(e.code, e.resource, e.function, e.pc),
(C::ResourceLimit, Some(Q::Work), Some(0), Some(6))
);
assert_eq!(limited.used(Q::TemporaryBytes), 7);
assert!(limited.used(Q::Work) <= limits.work);
}
@@ -0,0 +1,514 @@
//! Session accounting shared by owners, with reservations refunded on failure/drop.
//! These quotas account VM domains, not process RSS or allocator metadata.
use std::collections::VecDeque;
use std::fmt;
use std::sync::{Arc, Mutex, MutexGuard};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(usize)]
pub enum RuntimeResource {
GuestBytes,
HandleSlots,
AuxiliaryBytes,
TemporaryBytes,
StringBytes,
StringAllocations,
IndividualStringBytes,
CallDepth,
}
const COUNT: usize = 8;
const MIB: u64 = 1_048_576;
const CEILINGS: [u64; COUNT] =
[256 * MIB, 1_048_576, 64 * MIB, 64 * MIB, 64 * MIB, 262_144, 4 * MIB, 1_024];
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RuntimeLimits([u64; COUNT]);
impl Default for RuntimeLimits {
fn default() -> Self {
Self(CEILINGS)
}
}
impl RuntimeLimits {
pub fn get(&self, resource: RuntimeResource) -> u64 {
self.0[resource as usize]
}
/// Test/host configurations may lower ceilings; guest code cannot raise them.
pub fn lowered(
mut self,
resource: RuntimeResource,
limit: u64,
) -> Result<Self, ResourceFailure> {
if limit > self.get(resource) {
return Err(ResourceFailure {
resource,
reason: ResourceReason::Limit,
requested: limit,
limit: self.get(resource),
});
}
self.0[resource as usize] = limit;
Ok(self)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ResourceReason {
Limit,
SizeOverflow,
AllocationFailed,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ResourceFailure {
pub resource: RuntimeResource,
pub reason: ResourceReason,
pub requested: u64,
pub limit: u64,
}
impl fmt::Display for ResourceFailure {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"{:?}: {:?}, requested {}, limit {}",
self.resource, self.reason, self.requested, self.limit
)
}
}
impl std::error::Error for ResourceFailure {}
#[derive(Debug)]
struct State {
limits: RuntimeLimits,
used: [u64; COUNT],
}
#[derive(Debug, Clone)]
pub struct RuntimeBudget(Arc<Mutex<State>>);
impl Default for RuntimeBudget {
fn default() -> Self {
Self::new(RuntimeLimits::default())
}
}
impl RuntimeBudget {
pub fn new(limits: RuntimeLimits) -> Self {
Self(Arc::new(Mutex::new(State { limits, used: [0; COUNT] })))
}
fn state(&self) -> MutexGuard<'_, State> {
self.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
}
pub fn used(&self, resource: RuntimeResource) -> u64 {
self.state().used[resource as usize]
}
pub fn limit(&self, resource: RuntimeResource) -> u64 {
self.state().limits.get(resource)
}
pub fn check(&self, resource: RuntimeResource, requested: u64) -> Result<(), ResourceFailure> {
let limit = self.limit(resource);
if requested > limit {
Err(ResourceFailure { resource, reason: ResourceReason::Limit, requested, limit })
} else {
Ok(())
}
}
pub fn failure(
&self,
resource: RuntimeResource,
reason: ResourceReason,
requested: u64,
) -> ResourceFailure {
ResourceFailure { resource, reason, requested, limit: self.limit(resource) }
}
pub fn bytes<T>(
&self,
count: usize,
resource: RuntimeResource,
) -> Result<u64, ResourceFailure> {
count
.checked_mul(size_of::<T>())
.and_then(|bytes| u64::try_from(bytes).ok())
.ok_or_else(|| self.failure(resource, ResourceReason::SizeOverflow, u64::MAX))
}
pub fn reserve(
&self,
resource: RuntimeResource,
amount: u64,
) -> Result<Reservation, ResourceFailure> {
let mut state = self.state();
let current = state.used[resource as usize];
let limit = state.limits.get(resource);
let requested = current.checked_add(amount).ok_or(ResourceFailure {
resource,
reason: ResourceReason::SizeOverflow,
requested: u64::MAX,
limit,
})?;
if requested > limit {
return Err(ResourceFailure {
resource,
reason: ResourceReason::Limit,
requested,
limit,
});
}
state.used[resource as usize] = requested;
Ok(Reservation { budget: self.clone(), resource, amount })
}
pub(crate) fn empty_charge(&self, resource: RuntimeResource) -> Reservation {
Reservation { budget: self.clone(), resource, amount: 0 }
}
}
/// Unique accounting ownership; moving this token never charges a second time.
#[derive(Debug)]
pub struct Reservation {
budget: RuntimeBudget,
resource: RuntimeResource,
amount: u64,
}
impl Reservation {
pub fn amount(&self) -> u64 {
self.amount
}
pub(crate) fn absorb(&mut self, mut other: Self) {
assert!(Arc::ptr_eq(&self.budget.0, &other.budget.0));
assert_eq!(self.resource, other.resource);
self.amount += other.amount;
other.amount = 0;
}
fn resize(&mut self, amount: u64) -> Result<(), ResourceFailure> {
if amount > self.amount {
self.absorb(self.budget.reserve(self.resource, amount - self.amount)?);
} else {
self.budget.state().used[self.resource as usize] -= self.amount - amount;
self.amount = amount;
}
Ok(())
}
}
impl Drop for Reservation {
fn drop(&mut self) {
self.budget.state().used[self.resource as usize] -= self.amount;
}
}
/// Scheduler storage owns its capacity charge, including unused capacity.
/// During growth, the old allocation is also covered by a temporary reservation.
#[derive(Debug)]
pub(crate) struct BudgetQueue<T> {
data: VecDeque<T>,
charge: Reservation,
}
impl<T> BudgetQueue<T> {
#[cfg(test)]
pub(crate) fn capacity_bytes(&self) -> u64 {
self.charge.amount
}
pub fn new(budget: &RuntimeBudget) -> Self {
Self { data: VecDeque::new(), charge: budget.empty_charge(RuntimeResource::AuxiliaryBytes) }
}
#[cfg(test)]
pub fn len(&self) -> usize {
self.data.len()
}
pub fn is_empty(&self) -> bool {
self.data.is_empty()
}
pub fn pop_front(&mut self) -> Option<T> {
self.data.pop_front()
}
pub fn reserve(&mut self, additional: usize) -> Result<(), ResourceFailure> {
let b = &self.charge.budget;
let q = RuntimeResource::AuxiliaryBytes;
let required = self
.data
.len()
.checked_add(additional)
.ok_or_else(|| b.failure(q, ResourceReason::SizeOverflow, u64::MAX))?;
if required <= self.data.capacity() {
return Ok(());
}
// Exact growth prevents a geometric allocation from exceeding the available quota.
let bytes = b.bytes::<T>(required, q)?;
let mut extra = b.reserve(q, bytes - self.charge.amount)?;
let _temporary = b.reserve(RuntimeResource::TemporaryBytes, self.charge.amount)?;
let mut candidate = VecDeque::new();
candidate
.try_reserve_exact(required)
.map_err(|_| b.failure(q, ResourceReason::AllocationFailed, bytes))?;
let actual = b.bytes::<T>(candidate.capacity(), q)?;
// If the allocator reports excess capacity, reject before publishing the new buffer.
extra.resize(actual - self.charge.amount)?;
candidate.append(&mut self.data);
self.data = candidate;
self.charge.absorb(extra);
Ok(())
}
pub fn push_back(&mut self, value: T) -> Result<(), ResourceFailure> {
self.reserve(1)?;
self.data.push_back(value);
Ok(())
}
pub fn insert(&mut self, index: usize, value: T) -> Result<(), ResourceFailure> {
self.reserve(1)?;
self.data.insert(index, value);
Ok(())
}
pub fn partition_point(&self, predicate: impl FnMut(&T) -> bool) -> usize {
self.data.partition_point(predicate)
}
}
#[cfg(test)]
mod tests {
use super::*;
use RuntimeResource::*;
#[test]
fn accepted_limits_are_fixed_and_can_only_be_lowered() {
let limits = RuntimeLimits::default();
for (resource, expected) in [
(GuestBytes, 268_435_456),
(HandleSlots, 1_048_576),
(AuxiliaryBytes, 67_108_864),
(TemporaryBytes, 67_108_864),
(StringBytes, 67_108_864),
(StringAllocations, 262_144),
(IndividualStringBytes, 4_194_304),
(CallDepth, 1_024),
] {
assert_eq!(limits.get(resource), expected);
assert!(limits.clone().lowered(resource, expected + 1).is_err());
assert_eq!(limits.clone().lowered(resource, 0).unwrap().get(resource), 0);
}
}
#[test]
fn shared_reservations_refund_on_failure_and_follow_their_owner() {
let budget = RuntimeBudget::new(RuntimeLimits::default().lowered(GuestBytes, 10).unwrap());
let charge = budget.reserve(GuestBytes, 7).unwrap();
let shared = budget.clone();
let failure = shared.reserve(GuestBytes, 4).unwrap_err();
assert_eq!((failure.resource, failure.requested, failure.limit), (GuestBytes, 11, 10));
assert_eq!(budget.used(GuestBytes), 7);
let transferred = charge;
assert_eq!(shared.used(GuestBytes), 7);
let tail = shared.reserve(GuestBytes, 3).unwrap();
assert_eq!(shared.used(GuestBytes), 10);
drop(transferred);
assert_eq!(shared.used(GuestBytes), 3);
drop(tail);
assert_eq!(shared.used(GuestBytes), 0);
}
#[test]
fn queue_capacity_is_retained_until_drop_and_transfer_does_not_charge_twice() {
let budget =
RuntimeBudget::new(RuntimeLimits::default().lowered(AuxiliaryBytes, 16).unwrap());
let mut queue = BudgetQueue::<u64>::new(&budget);
queue.push_back(11).unwrap();
queue.push_back(22).unwrap();
assert_eq!(budget.used(AuxiliaryBytes), 16);
assert!(queue.push_back(33).is_err());
assert_eq!(queue.pop_front(), Some(11));
assert_eq!(budget.used(AuxiliaryBytes), 16);
queue.push_back(44).unwrap(); // reuse retained capacity
let mut moved = queue;
assert_eq!(budget.used(AuxiliaryBytes), 16);
assert_eq!(moved.pop_front(), Some(22));
assert_eq!(moved.pop_front(), Some(44));
drop(moved);
assert_eq!(budget.used(AuxiliaryBytes), 0);
assert_eq!(budget.used(TemporaryBytes), 0);
}
#[test]
fn temporary_growth_refusal_keeps_old_buffer_and_refunds_provisional_charge() {
let limits = RuntimeLimits::default()
.lowered(AuxiliaryBytes, 16)
.unwrap()
.lowered(TemporaryBytes, 0)
.unwrap();
let budget = RuntimeBudget::new(limits);
let mut queue = BudgetQueue::<u64>::new(&budget);
queue.push_back(11).unwrap();
let error = queue.push_back(22).unwrap_err();
assert_eq!((error.resource, error.requested), (TemporaryBytes, 8));
assert_eq!(budget.used(AuxiliaryBytes), 8);
assert_eq!(queue.pop_front(), Some(11));
assert_eq!(queue.pop_front(), None);
assert_eq!(budget.used(TemporaryBytes), 0);
}
#[test]
fn size_and_length_overflow_fail_before_growth() {
let budget = RuntimeBudget::default();
assert_eq!(
budget.bytes::<u64>(usize::MAX, AuxiliaryBytes).unwrap_err().reason,
ResourceReason::SizeOverflow
);
let mut queue = BudgetQueue::<u64>::new(&budget);
queue.push_back(11).unwrap();
assert_eq!(queue.reserve(usize::MAX).unwrap_err().reason, ResourceReason::SizeOverflow);
assert_eq!(budget.used(AuxiliaryBytes), 8);
assert_eq!(queue.pop_front(), Some(11));
}
}
/// Contiguous execution storage. The capacity reservation travels with the buffer
/// when a coroutine suspends/resumes, and is refunded only when storage is dropped.
#[derive(Debug)]
pub struct BudgetVec<T> {
data: Vec<T>,
charge: Reservation,
}
impl<T> BudgetVec<T> {
pub fn new(budget: &RuntimeBudget, resource: RuntimeResource) -> Self {
Self { data: Vec::new(), charge: budget.empty_charge(resource) }
}
pub(crate) fn prepare_growth(
&self,
additional: usize,
) -> Result<Option<VecGrowth<T>>, ResourceFailure> {
let b = &self.charge.budget;
let q = self.charge.resource;
let required = self
.data
.len()
.checked_add(additional)
.ok_or_else(|| b.failure(q, ResourceReason::SizeOverflow, u64::MAX))?;
if required <= self.data.capacity() {
return Ok(None);
}
let bytes = b.bytes::<T>(required, q)?;
let mut extra = b.reserve(q, bytes - self.charge.amount)?;
let temporary = b.reserve(RuntimeResource::TemporaryBytes, self.charge.amount)?;
let mut candidate = Vec::new();
candidate
.try_reserve_exact(required)
.map_err(|_| b.failure(q, ResourceReason::AllocationFailed, bytes))?;
extra.resize(b.bytes::<T>(candidate.capacity(), q)? - self.charge.amount)?;
Ok(Some(VecGrowth {
candidate,
extra,
_temporary: temporary,
old_capacity: self.data.capacity(),
}))
}
pub(crate) fn commit_growth(&mut self, growth: Option<VecGrowth<T>>) {
if let Some(mut growth) = growth {
assert_eq!(self.data.capacity(), growth.old_capacity);
growth.candidate.append(&mut self.data);
self.data = growth.candidate;
self.charge.absorb(growth.extra);
}
}
pub fn reserve(&mut self, additional: usize) -> Result<(), ResourceFailure> {
let growth = self.prepare_growth(additional)?;
self.commit_growth(growth);
Ok(())
}
pub(crate) fn accounted_bytes(&self) -> u64 {
self.charge.amount
}
pub(crate) fn from_slice(
budget: &RuntimeBudget,
resource: RuntimeResource,
values: &[T],
) -> Result<Self, ResourceFailure>
where
T: Clone,
{
let mut result = Self::new(budget, resource);
result.reserve(values.len())?;
result.data.extend_from_slice(values);
Ok(result)
}
pub fn push(&mut self, value: T) -> Result<(), ResourceFailure> {
self.reserve(1)?;
self.data.push(value);
Ok(())
}
pub fn resize(&mut self, len: usize, value: T) -> Result<(), ResourceFailure>
where
T: Clone,
{
self.reserve(len.saturating_sub(self.data.len()))?;
self.data.resize(len, value);
Ok(())
}
pub fn pop(&mut self) -> Option<T> {
self.data.pop()
}
pub fn clear(&mut self) {
self.data.clear();
}
pub(crate) fn retain(&mut self, keep: impl FnMut(&T) -> bool) {
self.data.retain(keep);
}
pub(crate) fn extend_from_slice(&mut self, values: &[T]) -> Result<(), ResourceFailure>
where
T: Clone,
{
self.reserve(values.len())?;
self.data.extend_from_slice(values);
Ok(())
}
pub fn truncate(&mut self, len: usize) {
self.data.truncate(len);
}
pub fn capacity(&self) -> usize {
self.data.capacity()
}
pub fn as_slice(&self) -> &[T] {
&self.data
}
pub fn drain(&mut self, range: impl std::ops::RangeBounds<usize>) -> std::vec::Drain<'_, T> {
self.data.drain(range)
}
pub fn take(&mut self) -> Self {
let empty = Self::new(&self.charge.budget, self.charge.resource);
std::mem::replace(self, empty)
}
/// Only used with the bounded native result writer after reserving its result slots.
pub(crate) fn native_result_buffer(&mut self) -> &mut Vec<T> {
&mut self.data
}
#[cfg(test)]
pub(crate) fn fixture(data: Vec<T>) -> Self {
let budget = RuntimeBudget::default();
let bytes = budget.bytes::<T>(data.capacity(), RuntimeResource::AuxiliaryBytes).unwrap();
let charge = budget.reserve(RuntimeResource::AuxiliaryBytes, bytes).unwrap();
Self { data, charge }
}
}
impl<T> std::ops::Deref for BudgetVec<T> {
type Target = [T];
fn deref(&self) -> &[T] {
&self.data
}
}
impl<T> std::ops::DerefMut for BudgetVec<T> {
fn deref_mut(&mut self) -> &mut [T] {
&mut self.data
}
}
impl<'a, T> IntoIterator for &'a BudgetVec<T> {
type Item = &'a T;
type IntoIter = std::slice::Iter<'a, T>;
fn into_iter(self) -> Self::IntoIter {
self.data.iter()
}
}
#[cfg(test)]
impl<T: PartialEq> PartialEq<Vec<T>> for BudgetVec<T> {
fn eq(&self, other: &Vec<T>) -> bool {
&self.data == other
}
}
/// Unpublished growth can be dropped to refund every provisional reservation.
pub(crate) struct VecGrowth<T> {
candidate: Vec<T>,
extra: Reservation,
_temporary: Reservation,
old_capacity: usize,
}
+8 -4
View File
@@ -7,9 +7,13 @@ pub trait RootVisitor {
}
/// Helper: if `val` is a `Value::HeapRef`, call the visitor.
pub(crate) fn value_heap_ref(value: &Value) -> Option<HeapRef> {
if let Value::HeapRef(r) = value { Some(*r) } else { None }
}
pub fn visit_value_for_roots<V: RootVisitor + ?Sized>(val: &Value, visitor: &mut V) {
if let Value::HeapRef(r) = val {
visitor.visit_heap_ref(*r);
if let Some(r) = value_heap_ref(val) {
visitor.visit_heap_ref(r);
}
}
@@ -31,11 +35,11 @@ mod tests {
fn visits_heapref_on_operand_stack() {
let mut vm = VirtualMachine::default();
// Place a HeapRef on the operand stack
vm.push_operand_for_test(Value::HeapRef(HeapRef(123)));
vm.push_operand_for_test(Value::HeapRef(HeapRef { index: 123, generation: 1 }));
let mut v = CollectVisitor { seen: vec![] };
vm.visit_roots(&mut v);
assert_eq!(v.seen, vec![HeapRef(123)]);
assert_eq!(v.seen, vec![HeapRef { index: 123, generation: 1 }]);
}
}
+70 -41
View File
@@ -1,4 +1,4 @@
use std::collections::VecDeque;
use crate::resource_budget::{BudgetQueue, ResourceFailure, RuntimeBudget};
use prometeu_bytecode::HeapRef;
@@ -8,12 +8,12 @@ use prometeu_bytecode::HeapRef;
/// - FIFO for ready coroutines.
/// - Sleeping coroutines are ordered by `wake_tick` and moved to ready when `wake_tick <= current_tick`.
/// - No randomness, no preemption, no context switching here.
#[derive(Debug, Default)]
#[derive(Debug)]
pub struct Scheduler {
/// Queue of runnable coroutines (FIFO)
ready_queue: VecDeque<HeapRef>,
ready_queue: BudgetQueue<HeapRef>,
/// Sleeping list kept sorted by (wake_tick, insertion_order)
sleeping: Vec<SleepEntry>,
sleeping: BudgetQueue<SleepEntry>,
/// Currently selected coroutine (purely informational here)
current: Option<HeapRef>,
/// Monotonic counter to preserve deterministic order for same wake_tick
@@ -28,15 +28,34 @@ struct SleepEntry {
}
impl Scheduler {
#[cfg(test)]
pub(crate) fn capacity_bytes(&self) -> u64 {
self.ready_queue.capacity_bytes() + self.sleeping.capacity_bytes()
}
#[cfg(test)]
pub fn new() -> Self {
Self::default()
Self::with_budget(&RuntimeBudget::default())
}
pub fn with_budget(budget: &RuntimeBudget) -> Self {
Self {
ready_queue: BudgetQueue::new(budget),
sleeping: BudgetQueue::new(budget),
current: None,
next_seq: 0,
}
}
pub fn reserve_ready(&mut self) -> Result<(), ResourceFailure> {
self.ready_queue.reserve(1)
}
// ---------- Ready queue operations ----------
/// Enqueue a coroutine to the ready FIFO.
pub fn enqueue_ready(&mut self, coro: HeapRef) {
self.ready_queue.push_back(coro);
pub fn enqueue_ready(&mut self, coro: HeapRef) -> Result<(), ResourceFailure> {
self.ready_queue.push_back(coro)
}
/// Dequeue next ready coroutine (front of FIFO).
@@ -70,36 +89,25 @@ impl Scheduler {
/// Put a coroutine to sleep until `wake_tick`.
/// A coroutine is woken when `current_tick >= wake_tick`.
/// The sleeping list is kept stably ordered to guarantee determinism.
pub fn sleep_until(&mut self, coro: HeapRef, wake_tick: u64) {
pub fn sleep_until(&mut self, coro: HeapRef, wake_tick: u64) -> Result<(), ResourceFailure> {
let entry = SleepEntry { wake_tick, seq: self.next_seq, coro };
let idx =
self.sleeping.partition_point(|e| (e.wake_tick, e.seq) <= (entry.wake_tick, entry.seq));
self.sleeping.insert(idx, entry)?;
self.next_seq = self.next_seq.wrapping_add(1);
// Binary search insertion point by wake_tick, then by seq to keep total order deterministic
let idx = match self.sleeping.binary_search_by(|e| {
if e.wake_tick == entry.wake_tick {
e.seq.cmp(&entry.seq)
} else {
e.wake_tick.cmp(&entry.wake_tick)
}
}) {
Ok(i) => i, // equal element position; insert after to preserve FIFO among equals
Err(i) => i,
};
self.sleeping.insert(idx, entry);
Ok(())
}
/// Move all sleeping coroutines with `wake_tick <= current_tick` to ready queue (FIFO by wake order).
pub fn wake_ready(&mut self, current_tick: u64) {
// Find split point where wake_tick > current_tick
/// Reserve the destination before removing any sleeping entries. A failed
/// transfer preserves both queues and never loses a runnable coroutine.
pub fn wake_ready(&mut self, current_tick: u64) -> Result<(), ResourceFailure> {
let split = self.sleeping.partition_point(|e| e.wake_tick <= current_tick);
if split == 0 {
return;
}
let mut ready_slice: Vec<SleepEntry> = self.sleeping.drain(0..split).collect();
// Already in order by (wake_tick, seq); push in that order to preserve determinism
for e in ready_slice.drain(..) {
self.ready_queue.push_back(e.coro);
self.ready_queue.reserve(split)?;
for _ in 0..split {
let entry = self.sleeping.pop_front().expect("validated sleeping prefix");
self.ready_queue.push_back(entry.coro)?;
}
Ok(())
}
/// Returns true if there are any sleeping coroutines.
@@ -113,15 +121,15 @@ mod tests {
use super::*;
fn hr(id: u32) -> HeapRef {
HeapRef(id)
HeapRef { index: id, generation: 1 }
}
#[test]
fn fifo_ready_queue_is_deterministic() {
let mut s = Scheduler::new();
s.enqueue_ready(hr(1));
s.enqueue_ready(hr(2));
s.enqueue_ready(hr(3));
s.enqueue_ready(hr(1)).unwrap();
s.enqueue_ready(hr(2)).unwrap();
s.enqueue_ready(hr(3)).unwrap();
assert_eq!(s.ready_len(), 3);
assert_eq!(s.dequeue_next(), Some(hr(1)));
@@ -133,23 +141,44 @@ mod tests {
#[test]
fn sleeping_wake_is_stable_and_fifo_by_insertion() {
let mut s = Scheduler::new();
s.sleep_until(hr(10), 5); // first with wake at 5
s.sleep_until(hr(11), 5); // second with same wake
s.sleep_until(hr(12), 6); // later wake
s.sleep_until(hr(10), 5).unwrap(); // first with wake at 5
s.sleep_until(hr(11), 5).unwrap(); // second with same wake
s.sleep_until(hr(12), 6).unwrap(); // later wake
// Before tick 5: nothing wakes
s.wake_ready(4);
s.wake_ready(4).unwrap();
assert!(s.is_ready_empty());
// At tick 5: first two wake in insertion order
s.wake_ready(5);
s.wake_ready(5).unwrap();
assert_eq!(s.dequeue_next(), Some(hr(10)));
assert_eq!(s.dequeue_next(), Some(hr(11)));
assert!(s.is_ready_empty());
// At tick 6: last one wakes
s.wake_ready(6);
s.wake_ready(6).unwrap();
assert_eq!(s.dequeue_next(), Some(hr(12)));
assert!(s.is_ready_empty());
}
#[test]
fn wake_refusal_preserves_sleepers_and_fifo_order() {
use crate::resource_budget::{RuntimeLimits, RuntimeResource};
let budget = RuntimeBudget::new(
RuntimeLimits::default()
.lowered(RuntimeResource::AuxiliaryBytes, (2 * size_of::<SleepEntry>()) as u64)
.unwrap(),
);
let mut s = Scheduler::with_budget(&budget);
s.sleep_until(hr(1), 4).unwrap();
s.sleep_until(hr(2), 4).unwrap();
let charged = budget.used(RuntimeResource::AuxiliaryBytes);
assert!(s.wake_ready(4).is_err());
assert_eq!(budget.used(RuntimeResource::AuxiliaryBytes), charged);
assert_eq!(budget.used(RuntimeResource::TemporaryBytes), 0);
assert!(s.is_ready_empty());
assert_eq!(s.sleeping.pop_front().unwrap().coro, hr(1));
assert_eq!(s.sleeping.pop_front().unwrap().coro, hr(2));
drop(s);
assert_eq!(budget.used(RuntimeResource::AuxiliaryBytes), 0);
}
}
@@ -0,0 +1,263 @@
//! Allocation-identity accounting over ordinary Arc<str> values.
//! The ledger never owns string content strongly. Native owners retain an
//! explicit provenance lease; guest slots remain Arc<str>, with no drop wrapper.
use crate::resource_budget::{
BudgetVec, Reservation, ResourceFailure, ResourceReason, RuntimeBudget, RuntimeResource as Q,
};
use prometeu_bytecode::Value;
use std::sync::{Arc, Mutex, MutexGuard, Weak};
#[derive(Debug)]
struct Entry {
content: Weak<str>,
_bytes: Reservation,
_allocation: Reservation,
}
#[derive(Debug)]
struct Domain {
budget: RuntimeBudget,
entries: BudgetVec<Entry>,
_state: Reservation,
}
#[derive(Debug, Clone)]
pub(crate) struct StringLedger(Arc<Mutex<Domain>>);
/// Host/tool retention must retain provenance along with the Arc. This is
/// boundary metadata, never a replacement for Value::String/StringSlot.
#[derive(Debug, Clone)]
pub(crate) struct StringLease {
content: Arc<str>,
domain: StringLedger,
}
impl StringLease {
pub(crate) fn content(&self) -> &Arc<str> {
&self.content
}
pub(crate) fn domain(&self) -> &StringLedger {
&self.domain
}
}
impl StringLedger {
pub(crate) fn retention(&self) -> Arc<dyn Send + Sync> {
self.0.clone()
}
pub(crate) fn new(budget: RuntimeBudget) -> Result<Self, ResourceFailure> {
let state = budget.reserve(
Q::AuxiliaryBytes,
budget.bytes::<Mutex<Domain>>(1, Q::AuxiliaryBytes)? + 2 * size_of::<usize>() as u64,
)?;
let entries = BudgetVec::new(&budget, Q::AuxiliaryBytes);
Ok(Self(Arc::new(Mutex::new(Domain { budget, entries, _state: state }))))
}
fn domain(&self) -> MutexGuard<'_, Domain> {
self.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
}
/// Safepoint reconciliation is bounded by the accepted allocation count.
/// Retain compacts in place; unused capacity remains charged until drop.
pub(crate) fn reconcile(&self) -> usize {
self.domain().reconcile()
}
pub(crate) fn tracked_allocations(&self) -> usize {
self.domain().entries.len()
}
pub(crate) fn retains(&self, content: &Arc<str>) -> bool {
let address = Arc::as_ptr(content);
self.domain().entries.iter().any(|entry| std::ptr::eq(entry.content.as_ptr(), address))
}
pub(crate) fn lease(&self, content: &Arc<str>) -> Option<StringLease> {
self.retains(content)
.then(|| StringLease { content: content.clone(), domain: self.clone() })
}
/// Imports always materialize a distinct allocation in the destination
/// domain. Assignment/call/storage of existing guest Arcs uses Arc::clone.
pub(crate) fn import(&self, text: &str) -> Result<Arc<str>, ResourceFailure> {
let mut domain = self.domain();
let charges = domain.prepare(text.len())?;
// Rust's stable Arc allocation can abort on physical allocator failure;
// quotas and fallible ledger/buffer growth are checked before this call.
let content: Arc<str> = Arc::from(text);
domain.publish(&content, charges);
Ok(content)
}
pub(crate) fn concat(&self, left: &str, right: &str) -> Result<Arc<str>, ResourceFailure> {
let mut domain = self.domain();
let len = left.len().checked_add(right.len()).ok_or_else(|| {
domain.budget.failure(Q::StringBytes, ResourceReason::SizeOverflow, u64::MAX)
})?;
let charges = domain.prepare(len)?;
// The temporary buffer and eventual content coexist. Its actual
// capacity is accounted independently, not hidden by the final length.
let mut buffer = BudgetVec::<u8>::new(&domain.budget, Q::TemporaryBytes);
buffer.reserve(len)?;
buffer.extend_from_slice(left.as_bytes())?;
buffer.extend_from_slice(right.as_bytes())?;
let text = std::str::from_utf8(&buffer).expect("concatenating UTF-8 preserves validity");
let content: Arc<str> = Arc::from(text);
domain.publish(&content, charges);
Ok(content)
}
pub(crate) fn format(&self, value: &Value) -> Result<Arc<str>, ResourceFailure> {
self.format_values(&[value])
}
pub(crate) fn concat_values(
&self,
left: &Value,
right: &Value,
) -> Result<Arc<str>, ResourceFailure> {
self.format_values(&[left, right])
}
fn format_values(&self, values: &[&Value]) -> Result<Arc<str>, ResourceFailure> {
let mut domain = self.domain();
let mut counter = SizeCounter(0);
for value in values {
value.write_text(&mut counter).map_err(|_| {
domain.budget.failure(Q::StringBytes, ResourceReason::SizeOverflow, u64::MAX)
})?;
}
let charges = domain.prepare(counter.0)?;
let mut writer =
TextBuffer { bytes: BudgetVec::new(&domain.budget, Q::TemporaryBytes), failure: None };
writer.bytes.reserve(counter.0)?;
for value in values {
if value.write_text(&mut writer).is_err() {
return Err(writer.failure.expect("bounded writer records its resource failure"));
}
}
let text = std::str::from_utf8(&writer.bytes).expect("Value text is UTF-8");
let content: Arc<str> = Arc::from(text);
domain.publish(&content, charges);
Ok(content)
}
}
struct SizeCounter(usize);
impl std::fmt::Write for SizeCounter {
fn write_str(&mut self, text: &str) -> std::fmt::Result {
self.0 = self.0.checked_add(text.len()).ok_or(std::fmt::Error)?;
Ok(())
}
}
struct TextBuffer {
bytes: BudgetVec<u8>,
failure: Option<ResourceFailure>,
}
pub(crate) enum MaterializeError {
Resource(ResourceFailure),
InvalidLength,
}
impl From<ResourceFailure> for MaterializeError {
fn from(error: ResourceFailure) -> Self {
Self::Resource(error)
}
}
impl StringLedger {
pub(crate) fn build(
&self,
length: usize,
write: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, MaterializeError> {
let mut domain = self.domain();
let charges = domain.prepare(length)?;
let mut writer = LimitedTextBuffer {
buffer: TextBuffer {
bytes: BudgetVec::new(&domain.budget, Q::TemporaryBytes),
failure: None,
},
length,
};
writer.buffer.bytes.reserve(length)?;
if write(&mut writer).is_err() {
return Err(writer
.buffer
.failure
.map(MaterializeError::Resource)
.unwrap_or(MaterializeError::InvalidLength));
}
if writer.buffer.bytes.len() != length {
return Err(MaterializeError::InvalidLength);
}
let text = std::str::from_utf8(&writer.buffer.bytes).expect("fmt::Write receives UTF-8");
let content: Arc<str> = Arc::from(text);
domain.publish(&content, charges);
Ok(content)
}
}
struct LimitedTextBuffer {
buffer: TextBuffer,
length: usize,
}
impl std::fmt::Write for LimitedTextBuffer {
fn write_str(&mut self, text: &str) -> std::fmt::Result {
if text.len() > self.length.saturating_sub(self.buffer.bytes.len()) {
return Err(std::fmt::Error);
}
std::fmt::Write::write_str(&mut self.buffer, text)
}
}
impl std::fmt::Write for TextBuffer {
fn write_str(&mut self, text: &str) -> std::fmt::Result {
self.bytes.extend_from_slice(text.as_bytes()).map_err(|failure| {
self.failure = Some(failure);
std::fmt::Error
})
}
}
struct Charges {
bytes: Reservation,
allocation: Reservation,
}
impl Domain {
fn reconcile(&mut self) -> usize {
let before = self.entries.len();
self.entries.retain(|entry| entry.content.strong_count() != 0);
before - self.entries.len()
}
fn reserve_content(&self, len: u64) -> Result<Charges, ResourceFailure> {
let bytes = self.budget.reserve(Q::StringBytes, len)?;
let allocation = self.budget.reserve(Q::StringAllocations, 1)?;
Ok(Charges { bytes, allocation })
}
fn prepare(&mut self, len: usize) -> Result<Charges, ResourceFailure> {
let len = u64::try_from(len).map_err(|_| {
self.budget.failure(Q::StringBytes, ResourceReason::SizeOverflow, u64::MAX)
})?;
self.budget.check(Q::IndividualStringBytes, len)?;
let charges = match self.reserve_content(len) {
Ok(charges) => charges,
Err(failure) if failure.reason == ResourceReason::Limit => {
// One bounded pressure pass; never remove a live allocation.
self.reconcile();
self.reserve_content(len)?
}
Err(failure) => return Err(failure),
};
if let Err(failure) = self.entries.reserve(1) {
if failure.reason != ResourceReason::Limit {
return Err(failure);
}
self.reconcile();
self.entries.reserve(1)?;
}
Ok(charges)
}
fn publish(&mut self, content: &Arc<str>, charges: Charges) {
self.entries
.push(Entry {
content: Arc::downgrade(content),
_bytes: charges.bytes,
_allocation: charges.allocation,
})
.expect("prepare reserved one ledger record before materialization");
}
}
#[cfg(test)]
mod tests;
@@ -0,0 +1,261 @@
use super::*;
use crate::resource_budget::RuntimeLimits;
fn fixture(overrides: &[(Q, u64)]) -> (RuntimeBudget, StringLedger) {
let mut limits = RuntimeLimits::default();
for &(resource, ceiling) in overrides {
limits = limits.lowered(resource, ceiling).unwrap();
}
let budget = RuntimeBudget::new(limits);
let ledger = StringLedger::new(budget.clone()).unwrap();
(budget, ledger)
}
#[test]
fn clones_share_charge_but_equal_independent_allocations_do_not() {
let (budget, ledger) = fixture(&[]);
let first = ledger.import("same").unwrap();
let cloned = first.clone();
assert_eq!(budget.used(Q::StringBytes), 4);
assert_eq!(budget.used(Q::StringAllocations), 1);
let second = ledger.import("same").unwrap();
assert!(!Arc::ptr_eq(&first, &second));
assert_eq!(budget.used(Q::StringBytes), 8);
assert_eq!(budget.used(Q::StringAllocations), 2);
drop(first);
drop(second);
assert_eq!(ledger.reconcile(), 1);
assert_eq!(budget.used(Q::StringBytes), 4);
drop(cloned);
// The Weak and counters survive the last owner until reconciliation.
assert_eq!(budget.used(Q::StringBytes), 4);
assert_eq!(ledger.reconcile(), 1);
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 0);
}
#[test]
fn native_writer_quota_refusal_happens_before_callback_or_content_materialization() {
let (budget, ledger) = fixture(&[(Q::StringBytes, 2)]);
let mut called = false;
let result = ledger.build(3, &mut |writer| {
called = true;
writer.write_str("abc")
});
assert!(
matches!(result,Err(MaterializeError::Resource(error)) if error.resource==Q::StringBytes)
);
assert!(!called);
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 0);
assert_eq!(budget.used(Q::TemporaryBytes), 0);
}
#[test]
fn native_writer_length_mismatch_cannot_grow_buffer_and_refunds_content_reservations() {
let (budget, ledger) = fixture(&[]);
for (length, text) in [(2, "abc"), (4, "abc")] {
assert!(matches!(
ledger.build(length, &mut |writer| writer.write_str(text)),
Err(MaterializeError::InvalidLength)
));
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 0);
assert_eq!(budget.used(Q::TemporaryBytes), 0);
assert_eq!(ledger.tracked_allocations(), 0);
}
let content = ledger
.build(5, &mut |writer| {
writer.write_str("é")?;
writer.write_str("猫")
})
.ok()
.unwrap();
assert_eq!(&*content, "é猫");
assert_eq!(budget.used(Q::StringBytes), 5);
assert_eq!(budget.used(Q::StringAllocations), 1);
}
#[test]
fn empty_strings_still_consume_distinct_allocation_records() {
let (budget, ledger) = fixture(&[(Q::StringAllocations, 2), (Q::StringBytes, 0)]);
let first = ledger.import("").unwrap();
let second = ledger.import("").unwrap();
assert!(!Arc::ptr_eq(&first, &second));
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 2);
let e = ledger.import("").unwrap_err();
assert_eq!((e.resource, e.requested, e.limit), (Q::StringAllocations, 3, 2));
assert_eq!(ledger.tracked_allocations(), 2);
}
#[test]
fn content_and_individual_limits_are_checked_before_materialization() {
let (budget, ledger) = fixture(&[(Q::StringBytes, 4), (Q::IndividualStringBytes, 3)]);
assert_eq!(ledger.import("1234").unwrap_err().resource, Q::IndividualStringBytes);
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(ledger.tracked_allocations(), 0);
let retained = ledger.import("123").unwrap();
let err = ledger.import("45").unwrap_err();
assert_eq!((err.resource, err.requested, err.limit), (Q::StringBytes, 5, 4));
assert_eq!(budget.used(Q::StringBytes), 3);
assert_eq!(budget.used(Q::StringAllocations), 1);
assert_eq!(&*retained, "123");
}
#[test]
fn pressure_reconciliation_reclaims_only_dead_owners_and_reuses_capacity() {
let (budget, ledger) = fixture(&[(Q::StringBytes, 3), (Q::StringAllocations, 1)]);
let content = ledger.import("abc").unwrap();
let auxiliary = budget.used(Q::AuxiliaryBytes);
assert!(ledger.import("abc").is_err());
drop(content);
let replacement = ledger.import("xyz").unwrap();
assert_eq!(&*replacement, "xyz");
assert_eq!(budget.used(Q::StringBytes), 3);
assert_eq!(budget.used(Q::StringAllocations), 1);
assert_eq!(budget.used(Q::AuxiliaryBytes), auxiliary);
assert_eq!(budget.used(Q::TemporaryBytes), 0);
}
#[test]
fn allocation_count_failure_refunds_provisional_content_charge() {
let (budget, ledger) = fixture(&[(Q::StringAllocations, 0)]);
assert_eq!(ledger.import("abc").unwrap_err().resource, Q::StringAllocations);
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(ledger.tracked_allocations(), 0);
}
#[test]
fn ledger_growth_is_fallible_and_keeps_live_records_on_refusal() {
let state = (size_of::<Mutex<Domain>>() + 2 * size_of::<usize>()) as u64;
let (budget, ledger) = fixture(&[(Q::AuxiliaryBytes, state)]);
assert_eq!(ledger.import("abc").unwrap_err().resource, Q::AuxiliaryBytes);
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 0);
assert_eq!(budget.used(Q::AuxiliaryBytes), state);
assert_eq!(budget.used(Q::TemporaryBytes), 0);
assert_eq!(ledger.tracked_allocations(), 0);
}
#[test]
fn concatenation_accounts_utf8_length_and_temporary_result_coexistence() {
let (budget, ledger) = fixture(&[(Q::StringBytes, 5), (Q::TemporaryBytes, 5)]);
let result = ledger.concat("é", "猫").unwrap();
assert_eq!(&*result, "é猫");
assert_eq!(budget.used(Q::StringBytes), 5);
assert_eq!(budget.used(Q::TemporaryBytes), 0);
assert_eq!(ledger.tracked_allocations(), 1);
}
#[test]
fn temporary_refusal_leaves_no_published_content_or_content_reservation() {
let (budget, ledger) = fixture(&[(Q::TemporaryBytes, 2)]);
let error = ledger.concat("ab", "c").unwrap_err();
assert_eq!((error.resource, error.requested, error.limit), (Q::TemporaryBytes, 3, 2));
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 0);
assert_eq!(budget.used(Q::TemporaryBytes), 0);
assert_eq!(ledger.tracked_allocations(), 0);
// Direct import does not need a temporary concatenation buffer.
let imported = ledger.import("abc").unwrap();
assert_eq!(&*imported, "abc");
}
#[test]
fn foreign_arc_import_copies_into_destination_without_implicit_session_sharing() {
let (first_budget, first) = fixture(&[]);
let (second_budget, second) = fixture(&[]);
let source = first.import("text").unwrap();
assert!(first.retains(&source));
assert!(!second.retains(&source));
assert!(second.lease(&source).is_none());
let imported = second.import(&source).unwrap();
assert!(!Arc::ptr_eq(&source, &imported));
assert!(second.retains(&imported));
assert_eq!(first_budget.used(Q::StringBytes), 4);
assert_eq!(second_budget.used(Q::StringBytes), 4);
}
#[test]
fn native_provenance_lease_keeps_accounting_domain_alive_after_session_owner() {
let (budget, ledger) = fixture(&[]);
let content = ledger.import("kept").unwrap();
let host = ledger.lease(&content).unwrap();
let tool = host.clone();
drop(content);
drop(ledger);
assert_eq!(&**host.content(), "kept");
assert_eq!(host.domain().reconcile(), 0);
assert_eq!(budget.used(Q::StringBytes), 4);
drop(host);
assert_eq!(budget.used(Q::StringAllocations), 1);
drop(tool);
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 0);
assert_eq!(budget.used(Q::AuxiliaryBytes), 0);
}
#[test]
fn shared_domain_survives_one_consumer_and_final_drop_releases_weak_storage() {
let (budget, ledger) = fixture(&[]);
let shared = ledger.clone();
let value = ledger.import("image").unwrap();
drop(ledger);
assert!(shared.retains(&value));
assert_eq!(budget.used(Q::StringBytes), 5);
drop(value);
shared.reconcile();
assert_eq!(budget.used(Q::StringBytes), 0);
assert!(budget.used(Q::AuxiliaryBytes) > 0);
drop(shared);
assert_eq!(budget.used(Q::AuxiliaryBytes), 0);
}
#[test]
fn domain_construction_refusal_does_not_publish_a_partial_owner() {
let budget =
RuntimeBudget::new(RuntimeLimits::default().lowered(Q::AuxiliaryBytes, 0).unwrap());
assert_eq!(StringLedger::new(budget.clone()).unwrap_err().resource, Q::AuxiliaryBytes);
assert_eq!(budget.used(Q::AuxiliaryBytes), 0);
}
#[test]
fn bounded_formatting_preserves_existing_value_text_without_unmetered_string_buffers() {
let (budget, ledger) = fixture(&[]);
for value in [
Value::Int32(i32::MIN),
Value::Int64(i64::MAX),
Value::Float(-0.0),
Value::Float(f64::MAX),
Value::Float(f64::NAN),
Value::Boolean(false),
Value::Null,
Value::HeapRef(prometeu_bytecode::HeapRef { index: u32::MAX, generation: 7 }),
Value::String(Arc::from("é猫")),
] {
let text = ledger.format(&value).unwrap();
assert_eq!(&*text, value.to_string());
assert_eq!(budget.used(Q::TemporaryBytes), 0);
drop(text);
ledger.reconcile();
assert_eq!(budget.used(Q::StringBytes), 0);
}
let text = ledger.concat_values(&Value::String(Arc::from("x=")), &Value::Int64(42)).unwrap();
assert_eq!(&*text, "x=42");
assert_eq!(budget.used(Q::StringBytes), 4);
}
#[test]
fn formatting_refuses_result_and_temporary_limits_with_no_content_publication() {
let (budget, ledger) = fixture(&[(Q::IndividualStringBytes, 2)]);
assert_eq!(ledger.format(&Value::Int32(123)).unwrap_err().resource, Q::IndividualStringBytes);
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 0);
assert_eq!(ledger.tracked_allocations(), 0);
let (budget, ledger) = fixture(&[(Q::TemporaryBytes, 2)]);
assert_eq!(ledger.format(&Value::Boolean(false)).unwrap_err().resource, Q::TemporaryBytes);
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 0);
assert_eq!(ledger.tracked_allocations(), 0);
}
@@ -0,0 +1,341 @@
//! Compact native field/element storage backed by resolved Registry layouts.
//! No collection opcodes: consumers use indices and the shared value contract.
mod allocation;
use crate::resource_budget::{ResourceReason, RuntimeBudget, RuntimeResource as Q};
use crate::value_contract::{ValueError, ValueGroup, u32_carrier};
use allocation::Allocation;
use prometeu_bytecode::registry::{
BuiltinId as B, DynamicSlot, Ownership, Registry, StringSlot, TypeId, TypeKind,
};
use prometeu_bytecode::{HeapRef, Value};
use std::sync::Arc;
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct TraitSlot {
receiver: HeapRef,
implementation: u32,
padding: u32,
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct PixelSlot {
x: i64,
y: i64,
color: u32,
padding: u32,
}
#[derive(Debug)]
pub(crate) struct TypedStorage {
registry: Arc<Registry>,
type_id: TypeId,
// None for a Struct instance, Some(count) for an Array instance.
count: Option<usize>,
initialized: usize,
data: Allocation,
}
impl TypedStorage {
pub fn new_struct(
registry: Arc<Registry>,
type_id: TypeId,
budget: &RuntimeBudget,
) -> Result<Self, ValueError> {
let layout = registry
.type_layout(type_id)
.and_then(|l| l.instance.as_ref())
.ok_or(ValueError::Type)?;
let data = Allocation::new(layout.size, layout.alignment, budget)?;
let mut storage = Self { registry, type_id, count: None, initialized: 0, data };
storage.initialize();
Ok(storage)
}
pub fn new_array(
registry: Arc<Registry>,
type_id: TypeId,
count: u32,
budget: &RuntimeBudget,
) -> Result<Self, ValueError> {
let layout = registry.type_layout(type_id).and_then(|l| l.array).ok_or(ValueError::Type)?;
let size = layout
.stride
.checked_mul(count as usize)
.ok_or_else(|| budget.failure(Q::GuestBytes, ResourceReason::SizeOverflow, u64::MAX))?;
let data = Allocation::new(size, layout.element_alignment, budget)?;
let mut storage =
Self { registry, type_id, count: Some(count as usize), initialized: 0, data };
storage.initialize();
Ok(storage)
}
pub fn registry(&self) -> &Registry {
&self.registry
}
pub fn type_id(&self) -> TypeId {
self.type_id
}
pub fn bytes(&self) -> u64 {
self.data.bytes()
}
pub fn len(&self) -> usize {
self.count.unwrap_or_else(|| {
self.registry.type_layout(self.type_id).unwrap().instance.as_ref().unwrap().fields.len()
})
}
fn slot(&self, index: usize) -> Result<(TypeId, usize), ValueError> {
if index >= self.len() {
return Err(ValueError::Bounds);
}
let layout = self.registry.type_layout(self.type_id).unwrap();
if let Some(array) = layout.array {
Ok((array.element_type_id, array.stride * index))
} else {
let field = layout.instance.as_ref().unwrap().fields[index];
Ok((field.type_id, field.offset))
}
}
pub fn slot_type(&self, index: usize) -> Result<TypeId, ValueError> {
self.slot(index).map(|s| s.0)
}
fn initialize(&mut self) {
for index in 0..self.len() {
let (ty, offset) = self.slot(index).unwrap();
// SAFETY: fresh resolved nonoverlapping field/element, no publication
// until every native value is constructed. Count advances only after init.
unsafe {
match self.registry.declarations().types[ty.0 as usize].kind {
TypeKind::Struct(_) | TypeKind::Array(_) => {
self.data.init(offset, HeapRef::NULL)
}
TypeKind::Trait(_) => self.data.init(
offset,
TraitSlot { receiver: HeapRef::NULL, implementation: 0, padding: 0 },
),
TypeKind::Builtin(id) => match id {
B::INT32 => self.data.init(offset, 0_i32),
B::INT64 => self.data.init(offset, 0_i64),
B::FLOAT => self.data.init(offset, 0_f64),
B::BOOL => self.data.init(offset, 0_u8),
B::COLOR => self.data.init(offset, 0_u32),
B::VEC2 => self.data.init(offset, [0_f64; 2]),
B::PIXEL => {
self.data.init(offset, PixelSlot { x: 0, y: 0, color: 0, padding: 0 })
}
B::STRING => self.data.init::<StringSlot>(offset, None),
B::DYNAMIC => self.data.init(offset, DynamicSlot::default()),
_ => unreachable!("resolved builtin"),
},
}
}
self.initialized += 1;
}
}
pub fn read(&self, index: usize) -> Result<ValueGroup, ValueError> {
let (ty, offset) = self.slot(index)?;
// SAFETY: private backing storage was initialized according to this exact
// immutable Registry. Only matching typed writes can change its contents.
let result = unsafe {
match self.registry.declarations().types[ty.0 as usize].kind {
TypeKind::Struct(_) | TypeKind::Array(_) => {
let r = *self.data.get::<HeapRef>(offset);
ValueGroup::new(&[if r.is_null() { Value::Null } else { Value::HeapRef(r) }])
}
TypeKind::Trait(_) => {
let t = self.data.get::<TraitSlot>(offset);
if t.receiver.is_null() {
if t.implementation != 0 {
return Err(ValueError::Type);
}
ValueGroup::new(&[Value::Null, Value::Null])
} else {
ValueGroup::new(&[
Value::HeapRef(t.receiver),
Value::Int64(t.implementation.into()),
])
}
}
TypeKind::Builtin(id) => match id {
B::INT32 => ValueGroup::new(&[Value::Int32(*self.data.get(offset))]),
B::INT64 => ValueGroup::new(&[Value::Int64(*self.data.get(offset))]),
B::FLOAT => ValueGroup::new(&[Value::Float(*self.data.get(offset))]),
B::BOOL => match *self.data.get::<u8>(offset) {
0 => ValueGroup::new(&[Value::Boolean(false)]),
1 => ValueGroup::new(&[Value::Boolean(true)]),
_ => return Err(ValueError::Type),
},
B::COLOR => {
ValueGroup::new(&[Value::Int64((*self.data.get::<u32>(offset)).into())])
}
B::VEC2 => {
let [x, y] = *self.data.get::<[f64; 2]>(offset);
ValueGroup::new(&[Value::Float(x), Value::Float(y)])
}
B::PIXEL => {
let p = self.data.get::<PixelSlot>(offset);
ValueGroup::new(&[
Value::Int64(p.x),
Value::Int64(p.y),
Value::Int64(p.color.into()),
])
}
B::STRING => ValueGroup::new(&[self
.data
.get::<StringSlot>(offset)
.as_ref()
.map_or(Value::Null, |s| Value::String(s.clone()))]),
B::DYNAMIC => {
let d = self.data.get::<DynamicSlot>(offset);
ValueGroup::new(&[
d.type_id.map_or(Value::Null, |t| Value::Int64(t.0.into())),
d.payload.clone(),
])
}
_ => unreachable!("resolved builtin"),
},
}
};
Ok(result)
}
/// Heap validates the complete group and provenance before calling this.
/// All matching checks/conversions happen before replacement, so an error
/// preserves both the old value and its native owners.
pub fn write_validated(&mut self, index: usize, values: &[Value]) -> Result<(), ValueError> {
let (ty, offset) = self.slot(index)?;
// SAFETY: each arm uses the same resident type as initialize/read/drop;
// &mut self gives exclusive access. Native assignment drops exactly once.
unsafe {
match (&self.registry.declarations().types[ty.0 as usize].kind, values) {
(TypeKind::Struct(_) | TypeKind::Array(_), [Value::Null]) => {
self.data.replace(offset, HeapRef::NULL)
}
(TypeKind::Struct(_) | TypeKind::Array(_), [Value::HeapRef(r)]) => {
self.data.replace(offset, *r)
}
(TypeKind::Trait(_), [Value::Null, Value::Null]) => self.data.replace(
offset,
TraitSlot { receiver: HeapRef::NULL, implementation: 0, padding: 0 },
),
(TypeKind::Trait(_), [Value::HeapRef(r), id]) => self.data.replace(
offset,
TraitSlot { receiver: *r, implementation: u32_carrier(id)?, padding: 0 },
),
(TypeKind::Builtin(B::INT32), [Value::Int32(v)]) => self.data.replace(offset, *v),
(TypeKind::Builtin(B::INT64), [Value::Int64(v)]) => self.data.replace(offset, *v),
(TypeKind::Builtin(B::FLOAT), [Value::Float(v)]) => self.data.replace(offset, *v),
(TypeKind::Builtin(B::BOOL), [Value::Boolean(v)]) => {
self.data.replace(offset, u8::from(*v))
}
(TypeKind::Builtin(B::COLOR), [v]) => self.data.replace(offset, u32_carrier(v)?),
(TypeKind::Builtin(B::VEC2), [Value::Float(x), Value::Float(y)]) => {
self.data.replace(offset, [*x, *y])
}
(TypeKind::Builtin(B::PIXEL), [Value::Int64(x), Value::Int64(y), color]) => {
self.data.replace(
offset,
PixelSlot { x: *x, y: *y, color: u32_carrier(color)?, padding: 0 },
)
}
(TypeKind::Builtin(B::STRING), [Value::Null]) => {
self.data.replace::<StringSlot>(offset, None)
}
(TypeKind::Builtin(B::STRING), [Value::String(s)]) => {
self.data.replace::<StringSlot>(offset, Some(s.clone()))
}
(TypeKind::Builtin(B::DYNAMIC), [tag, payload]) => {
let type_id = if matches!(tag, Value::Null) {
None
} else {
Some(TypeId(u32_carrier(tag)?))
};
self.data.replace(offset, DynamicSlot { type_id, payload: payload.clone() });
}
_ => return Err(ValueError::Type),
}
}
Ok(())
}
/// Iterates only resolved ownership-map entries; padding/scalar fields are
/// never interpreted as references. No temporary root buffer is allocated.
pub fn root_count(&self) -> usize {
let layout = self.registry.type_layout(self.type_id).unwrap();
if let Some(array) = layout.array {
let owner = self.registry.type_layout(array.element_type_id).unwrap().storage.ownership;
if matches!(
owner,
Ownership::GuestReference | Ownership::TraitReceiver | Ownership::Dynamic
) {
self.len()
} else {
0
}
} else {
layout.instance.as_ref().unwrap().owned_fields.len()
}
}
pub fn root_at(&self, index: usize) -> Option<HeapRef> {
assert!(index < self.root_count());
let layout = self.registry.type_layout(self.type_id).unwrap();
let (offset, ownership) = if let Some(array) = layout.array {
(
index * array.stride,
self.registry.type_layout(array.element_type_id).unwrap().storage.ownership,
)
} else {
let field = layout.instance.as_ref().unwrap().owned_fields[index];
(field.offset, field.ownership)
};
// SAFETY: private caller indexes the resolved map within root_count();
// resident native values were all constructed before heap publication.
let reference = unsafe {
match ownership {
Ownership::GuestReference => Some(*self.data.get::<HeapRef>(offset)),
Ownership::TraitReceiver => Some(self.data.get::<TraitSlot>(offset).receiver),
Ownership::Dynamic => {
crate::roots::value_heap_ref(&self.data.get::<DynamicSlot>(offset).payload)
}
_ => None,
}
};
reference.filter(|r| !r.is_null())
}
}
impl Drop for TypedStorage {
fn drop(&mut self) {
let layout = self.registry.type_layout(self.type_id).unwrap();
if let Some(array) = layout.array {
let ownership =
self.registry.type_layout(array.element_type_id).unwrap().storage.ownership;
if !matches!(ownership, Ownership::NativeString | Ownership::Dynamic) {
return;
}
for index in 0..self.initialized {
drop_native(&mut self.data, index * array.stride, ownership);
}
} else {
let instance = layout.instance.as_ref().unwrap();
// An interrupted constructor owns only the prefix before this offset.
let end = instance.fields.get(self.initialized).map_or(instance.size, |f| f.offset);
for field in &instance.owned_fields {
if field.offset >= end {
break;
}
drop_native(&mut self.data, field.offset, field.ownership);
}
}
}
}
fn drop_native(data: &mut Allocation, offset: usize, ownership: Ownership) {
// SAFETY: caller visits each initialized native ownership-map entry once.
// Allocation::drop deallocates the backing memory only after this traversal.
unsafe {
match ownership {
Ownership::NativeString => data.drop_at::<StringSlot>(offset),
Ownership::Dynamic => data.drop_at::<DynamicSlot>(offset),
_ => {}
}
}
}
#[cfg(test)]
pub(crate) mod tests;
@@ -0,0 +1,87 @@
//! Private aligned allocation. TypedStorage constructs/drops native owners;
//! this owner only manages the backing allocation and its quota reservation.
use crate::resource_budget::{
Reservation, ResourceFailure, ResourceReason, RuntimeBudget, RuntimeResource as Q,
};
use std::alloc::{Layout, alloc_zeroed, dealloc};
use std::ptr::NonNull;
#[derive(Debug)]
pub(super) struct Allocation {
ptr: NonNull<u8>,
layout: Layout,
charge: Reservation,
}
// The allocation is uniquely owned. Typed access is private to TypedStorage,
// whose resident StringSlot/DynamicSlot/plain carriers are all Send + Sync.
unsafe impl Send for Allocation {}
unsafe impl Sync for Allocation {}
impl Allocation {
pub fn new(
size: usize,
alignment: usize,
budget: &RuntimeBudget,
) -> Result<Self, ResourceFailure> {
let layout = Layout::from_size_align(size, alignment).map_err(|_| {
budget.failure(Q::GuestBytes, ResourceReason::SizeOverflow, size as u64)
})?;
let charge = budget.reserve(Q::GuestBytes, size as u64)?;
let ptr = if size == 0 {
// Never dereferenced/deallocated; no element exists in an empty payload.
NonNull::dangling()
} else {
// SAFETY: nonzero checked Layout; null is handled as a resource failure.
NonNull::new(unsafe { alloc_zeroed(layout) }).ok_or_else(|| {
budget.failure(Q::GuestBytes, ResourceReason::AllocationFailed, size as u64)
})?
};
Ok(Self { ptr, layout, charge })
}
pub fn bytes(&self) -> u64 {
self.charge.amount()
}
fn at<T>(&self, offset: usize) -> *mut T {
assert!(offset.checked_add(size_of::<T>()).is_some_and(|end| end <= self.layout.size()));
assert!(self.layout.align() >= align_of::<T>());
assert!(offset.is_multiple_of(align_of::<T>()));
// SAFETY: checked bounds/alignment, nonzero accessed type lies in allocation.
unsafe { self.ptr.as_ptr().add(offset).cast() }
}
/// Caller guarantees T is initialized and is the resident type at offset.
pub unsafe fn get<T>(&self, offset: usize) -> &T {
// SAFETY: caller's typed initialization invariant and checked address.
unsafe { &*self.at::<T>(offset) }
}
/// Caller guarantees exclusive access and a valid initialized T at offset.
pub unsafe fn replace<T>(&mut self, offset: usize, value: T) {
// SAFETY: caller guarantees initialized matching type; assignment drops old owner.
unsafe {
*self.at::<T>(offset) = value;
}
}
/// Caller guarantees the destination is uninitialized storage for exactly T.
pub unsafe fn init<T>(&mut self, offset: usize, value: T) {
// SAFETY: checked address, ownership is moved into previously unused storage.
unsafe {
self.at::<T>(offset).write(value);
}
}
/// Caller guarantees an initialized T which will never be used again.
pub unsafe fn drop_at<T>(&mut self, offset: usize) {
// SAFETY: caller walks each initialized native slot exactly once.
unsafe {
std::ptr::drop_in_place(self.at::<T>(offset));
}
}
}
impl Drop for Allocation {
fn drop(&mut self) {
if self.layout.size() != 0 {
// SAFETY: same pointer/Layout returned by alloc_zeroed, unique owner.
unsafe {
dealloc(self.ptr.as_ptr(), self.layout);
}
}
}
}
@@ -0,0 +1,528 @@
use super::*;
use crate::heap::{Heap, StoredObject};
use crate::resource_budget::{ResourceReason, RuntimeLimits};
use crate::value_contract::{self, ValueError as E};
use prometeu_bytecode::load_limits::LoadBudget;
use prometeu_bytecode::registry::{ImplementationDecl, NamedType, RegistryDeclarations, TypeDecl};
use std::sync::atomic::Ordering;
const I32: TypeId = TypeId(0);
const I64: TypeId = TypeId(1);
const FLOAT: TypeId = TypeId(2);
const BOOL: TypeId = TypeId(3);
const COLOR: TypeId = TypeId(4);
const VEC: TypeId = TypeId(5);
const PIXEL: TypeId = TypeId(6);
const STRING: TypeId = TypeId(7);
const DYNAMIC: TypeId = TypeId(8);
const ENEMY: TypeId = TypeId(9);
const OTHER: TypeId = TypeId(10);
const MIXED: TypeId = TypeId(11);
const TRAIT: TypeId = TypeId(12);
const INTS: TypeId = TypeId(13);
const VECS: TypeId = TypeId(14);
const REFS: TypeId = TypeId(15);
const STRINGS: TypeId = TypeId(16);
const TRAITS: TypeId = TypeId(17);
const DYNAMICS: TypeId = TypeId(18);
const BOOLS: TypeId = TypeId(19);
const PIXELS: TypeId = TypeId(20);
const FLOATS: TypeId = TypeId(21);
const LONGS: TypeId = TypeId(22);
const COLORS: TypeId = TypeId(23);
const ARRAYS: TypeId = TypeId(24);
pub(crate) fn fixture_registry() -> Arc<Registry> {
let mut types: Vec<_> =
[B::INT32, B::INT64, B::FLOAT, B::BOOL, B::COLOR, B::VEC2, B::PIXEL, B::STRING, B::DYNAMIC]
.into_iter()
.map(TypeKind::Builtin)
.collect();
types.extend([
TypeKind::Struct(vec![]),
TypeKind::Struct(vec![]),
TypeKind::Struct(
[BOOL, I32, BOOL, STRING, DYNAMIC, TRAIT, ENEMY, VEC, PIXEL, INTS]
.into_iter()
.map(|type_id| NamedType { type_id, name: None })
.collect(),
),
TypeKind::Trait(vec![]),
]);
types.extend(
[I32, VEC, ENEMY, STRING, TRAIT, DYNAMIC, BOOL, PIXEL, FLOAT, I64, COLOR, INTS]
.into_iter()
.map(TypeKind::Array),
);
Arc::new(
Registry::resolve(
RegistryDeclarations {
types: types.into_iter().map(|kind| TypeDecl { kind, name: None }).collect(),
functions: vec![],
implementations: vec![
ImplementationDecl { owner: ENEMY, trait_id: TRAIT, methods: vec![] },
ImplementationDecl { owner: OTHER, trait_id: TRAIT, methods: vec![] },
],
},
0,
&mut LoadBudget::new(Default::default()),
)
.unwrap(),
)
}
fn values(heap: &Heap, registry: &Registry, r: HeapRef, i: usize) -> Vec<Value> {
heap.load_typed(registry, r, i).unwrap().as_slice().to_vec()
}
#[test]
fn defaults_are_typed_compact_and_construct_no_referenced_objects() {
let registry = fixture_registry();
let budget = RuntimeBudget::default();
let mut heap = Heap::with_budget(&budget);
for array in
[INTS, VECS, REFS, STRINGS, TRAITS, DYNAMICS, BOOLS, PIXELS, FLOATS, LONGS, COLORS, ARRAYS]
{
let before = budget.used(Q::GuestBytes);
let r = heap.allocate_typed_array(registry.clone(), array, 3).unwrap();
let layout = registry.type_layout(array).unwrap().array.unwrap();
assert_eq!(
budget.used(Q::GuestBytes) - before,
(size_of::<StoredObject>() + 3 * layout.stride) as u64
);
let default =
registry.type_layout(layout.element_type_id).unwrap().storage.default_values();
for i in 0..3 {
assert_eq!(values(&heap, &registry, r, i), default);
}
}
assert_eq!(heap.len(), 12); // No children, subarrays, boxes or wrappers.
let mixed = heap.allocate_typed_struct(registry.clone(), MIXED).unwrap();
let fields = &registry.type_layout(MIXED).unwrap().instance.as_ref().unwrap().fields;
for (i, field) in fields.iter().enumerate() {
assert_eq!(
values(&heap, &registry, mixed, i),
registry.type_layout(field.type_id).unwrap().storage.default_values()
);
}
let empty = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
assert!(heap.is_valid(empty));
assert_eq!(heap.load_typed(&registry, empty, 0).unwrap_err(), E::Bounds);
assert_eq!(heap.used_bytes.load(Ordering::Relaxed) as u64, budget.used(Q::GuestBytes));
}
#[test]
fn exact_scalar_roundtrips_preserve_float_bits_pixel_width_and_color_range() {
let registry = fixture_registry();
let mut heap = Heap::new();
for (ty, input) in [
(INTS, vec![Value::Int32(i32::MIN)]),
(LONGS, vec![Value::Int64(i64::MAX)]),
(BOOLS, vec![Value::Boolean(true)]),
(COLORS, vec![Value::Int64(u32::MAX.into())]),
(VECS, vec![Value::Float(-0.0), Value::Float(f64::INFINITY)]),
(PIXELS, vec![Value::Int64(i64::MIN), Value::Int64(i64::MAX), Value::Int64(0x11223344)]),
] {
let r = heap.allocate_typed_array(registry.clone(), ty, 1).unwrap();
heap.store_typed(&registry, r, 0, &input).unwrap();
assert_eq!(values(&heap, &registry, r, 0), input);
}
let r = heap.allocate_typed_array(registry.clone(), FLOATS, 1).unwrap();
for bits in [0_u64, (-0.0_f64).to_bits(), 0x7ff8000000000123] {
heap.store_typed(&registry, r, 0, &[Value::Float(f64::from_bits(bits))]).unwrap();
let output = values(&heap, &registry, r, 0);
let Value::Float(v) = output[0] else { panic!("exact Float carrier") };
assert_eq!(v.to_bits(), bits);
}
let r = heap.allocate_typed_array(registry.clone(), COLORS, 1).unwrap();
for value in [
Value::Int64(-1),
Value::Int64(u32::MAX as i64 + 1),
Value::Int32(0),
Value::Float(0.0),
Value::Null,
] {
assert_eq!(heap.store_typed(&registry, r, 0, &[value]).unwrap_err(), E::Type);
}
assert_eq!(values(&heap, &registry, r, 0), [Value::Int64(0)]);
}
#[test]
fn string_reads_share_identity_and_failed_overwrite_keeps_the_old_owner() {
let registry = fixture_registry();
let mut heap = Heap::new();
let r = heap.allocate_typed_array(registry.clone(), STRINGS, 2).unwrap();
let text: Arc<str> = Arc::from("hello");
let input = [Value::String(text.clone())];
heap.store_typed(&registry, r, 0, &input).unwrap();
assert_eq!(Arc::strong_count(&text), 3);
assert_eq!(heap.store_typed(&registry, r, 0, &[Value::Int64(1)]).unwrap_err(), E::Type);
assert_eq!(Arc::strong_count(&text), 3);
let copy = heap.load_typed(&registry, r, 0).unwrap();
let [Value::String(alias)] = copy.as_slice() else { panic!("String carrier") };
assert!(Arc::ptr_eq(alias, &text));
assert_eq!(Arc::strong_count(&text), 4);
heap.store_typed(&registry, r, 0, &[Value::Null]).unwrap();
assert_eq!(Arc::strong_count(&text), 3);
heap.store_typed(&registry, r, 1, &[Value::String(Arc::from(""))]).unwrap();
assert!(
matches!(values(&heap, &registry, r, 1).as_slice(), [Value::String(s)] if s.is_empty())
);
drop(copy);
drop(input);
assert_eq!(Arc::strong_count(&text), 1);
heap.sweep();
}
#[test]
fn complete_trait_pairs_accept_implementation_zero_and_preserve_receiver_aliases() {
let registry = fixture_registry();
let mut heap = Heap::new();
let enemy = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
let r = heap.allocate_typed_array(registry.clone(), TRAITS, 2).unwrap();
let pair = [Value::HeapRef(enemy), Value::Int64(0)];
heap.store_typed(&registry, r, 0, &pair).unwrap();
assert_eq!(values(&heap, &registry, r, 0), pair);
for bad in [
vec![Value::HeapRef(enemy), Value::Int64(1)],
vec![Value::HeapRef(enemy), Value::Null],
vec![Value::Null, Value::Int64(0)],
vec![Value::HeapRef(HeapRef::NULL), Value::Int64(0)],
vec![Value::HeapRef(enemy), Value::Int32(0)],
vec![Value::HeapRef(enemy), Value::Int64(-1)],
vec![Value::HeapRef(enemy)],
] {
assert_eq!(heap.store_typed(&registry, r, 0, &bad).unwrap_err(), E::Type);
}
assert_eq!(values(&heap, &registry, r, 0), pair);
heap.mark_from_roots([r]).unwrap();
heap.sweep();
assert!(heap.is_valid(enemy));
heap.store_typed(&registry, r, 0, &[Value::Null, Value::Null]).unwrap();
heap.mark_from_roots([r]).unwrap();
heap.sweep();
assert!(!heap.is_valid(enemy));
}
#[test]
fn dynamic_checks_semantic_ids_and_direct_or_typed_null_payloads() {
let registry = fixture_registry();
let mut heap = Heap::new();
let r = heap.allocate_typed_array(registry.clone(), DYNAMICS, 1).unwrap();
let text: Arc<str> = Arc::from("shared");
for input in [
vec![Value::Int64(I32.0.into()), Value::Int32(17)],
vec![Value::Int64(COLOR.0.into()), Value::Int64(0x11223344)],
vec![Value::Int64(STRING.0.into()), Value::String(text.clone())],
vec![Value::Int64(STRING.0.into()), Value::Null],
vec![Value::Int64(TRAIT.0.into()), Value::Null],
vec![Value::Int64(ENEMY.0.into()), Value::Null],
vec![Value::Null, Value::Null],
] {
heap.store_typed(&registry, r, 0, &input).unwrap();
assert_eq!(values(&heap, &registry, r, 0), input);
}
for bad in [
vec![Value::Null, Value::Int32(0)],
vec![Value::Int64(I32.0.into()), Value::Int64(0)],
vec![Value::Int64(I32.0.into()), Value::Null],
vec![Value::Int64(DYNAMIC.0.into()), Value::Null],
vec![Value::Int64(999), Value::Null],
vec![Value::Int64(-1), Value::Null],
vec![Value::Int32(0), Value::Int32(0)],
vec![Value::Int64(VEC.0.into()), Value::Float(0.0)],
] {
assert_eq!(heap.store_typed(&registry, r, 0, &bad).unwrap_err(), E::Type);
}
assert_eq!(heap.len(), 1); // No box for typed null, no direct-value boxing.
assert_eq!(Arc::strong_count(&text), 1);
}
#[test]
fn compact_reference_arrays_require_exact_type_live_generation_and_registry() {
let registry = fixture_registry();
let mut heap = Heap::new();
let refs = heap.allocate_typed_array(registry.clone(), REFS, 1).unwrap();
let enemy = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
let other = heap.allocate_typed_struct(registry.clone(), OTHER).unwrap();
heap.store_typed(&registry, refs, 0, &[Value::HeapRef(enemy)]).unwrap();
assert_eq!(
heap.store_typed(&registry, refs, 0, &[Value::HeapRef(other)]).unwrap_err(),
E::Type
);
assert_eq!(
heap.store_typed(
&registry,
refs,
0,
&[Value::HeapRef(HeapRef { index: enemy.index, generation: enemy.generation + 1 })]
)
.unwrap_err(),
E::InvalidHandle
);
heap.mark_from_roots([refs]).unwrap();
heap.sweep();
assert!(heap.is_valid(enemy));
assert!(!heap.is_valid(other));
let next = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
assert_eq!(next.index, other.index);
assert_eq!(
heap.store_typed(&registry, refs, 0, &[Value::HeapRef(other)]).unwrap_err(),
E::InvalidHandle
);
let foreign = fixture_registry();
assert_eq!(heap.load_typed(&foreign, refs, 0).unwrap_err(), E::Type);
let foreign_enemy = heap.allocate_typed_struct(foreign, ENEMY).unwrap();
assert_eq!(
heap.store_typed(&registry, refs, 0, &[Value::HeapRef(foreign_enemy)]).unwrap_err(),
E::Type
);
assert_eq!(values(&heap, &registry, refs, 0), [Value::HeapRef(enemy)]);
}
#[test]
fn mixed_struct_gc_uses_reference_maps_and_drops_native_dynamic_strings() {
let registry = fixture_registry();
let mut heap = Heap::new();
let holder = heap.allocate_typed_struct(registry.clone(), MIXED).unwrap();
let child = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
let dead = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
let text: Arc<str> = Arc::from("owner");
heap.store_typed(&registry, holder, 3, &[Value::String(text.clone())]).unwrap();
heap.store_typed(
&registry,
holder,
4,
&[Value::Int64(STRING.0.into()), Value::String(text.clone())],
)
.unwrap();
heap.store_typed(&registry, holder, 6, &[Value::HeapRef(child)]).unwrap();
// Scalar bits resembling a handle must never retain the unrelated object.
heap.store_typed(
&registry,
holder,
8,
&[
Value::Int64(((dead.generation as u64) << 32 | dead.index as u64) as i64),
Value::Int64(0),
Value::Int64(0),
],
)
.unwrap();
assert_eq!(Arc::strong_count(&text), 3);
heap.mark_from_roots([holder]).unwrap();
heap.sweep();
assert!(heap.is_valid(child));
assert!(!heap.is_valid(dead));
heap.sweep();
assert_eq!(Arc::strong_count(&text), 1);
}
#[test]
fn dynamic_reference_roots_and_array_references_preserve_identity() {
let registry = fixture_registry();
let mut heap = Heap::new();
let outer = heap.allocate_typed_array(registry.clone(), ARRAYS, 1).unwrap();
let child = heap.allocate_typed_array(registry.clone(), INTS, 1).unwrap();
let root = heap.allocate_typed_array(registry.clone(), DYNAMICS, 1).unwrap();
heap.store_typed(&registry, outer, 0, &[Value::HeapRef(child)]).unwrap();
heap.store_typed(&registry, root, 0, &[Value::Int64(ARRAYS.0.into()), Value::HeapRef(outer)])
.unwrap();
heap.mark_from_roots([root]).unwrap();
heap.sweep();
assert_eq!(heap.len(), 3);
heap.store_typed(&registry, child, 0, &[Value::Int32(42)]).unwrap();
let [Value::HeapRef(alias)] = values(&heap, &registry, outer, 0)[..] else {
panic!("reference")
};
assert_eq!(values(&heap, &registry, alias, 0), [Value::Int32(42)]);
}
#[test]
fn empty_bounds_null_and_wrong_category_are_distinct() {
let registry = fixture_registry();
let mut heap = Heap::new();
let empty = heap.allocate_typed_array(registry.clone(), STRINGS, 0).unwrap();
assert_eq!(heap.load_typed(&registry, empty, 0).unwrap_err(), E::Bounds);
assert_eq!(
heap.store_typed(&registry, empty, usize::MAX, &[Value::Null]).unwrap_err(),
E::Bounds
);
assert_eq!(heap.load_typed(&registry, HeapRef::NULL, 0).unwrap_err(), E::NullReference);
let closure = heap.alloc_closure(0, &[]).unwrap();
assert_eq!(
value_contract::validate(&registry, &heap, ENEMY, &[Value::HeapRef(closure)]).unwrap_err(),
E::Type
);
assert!(matches!(heap.allocate_typed_struct(registry.clone(), STRING), Err(E::Type)));
assert!(matches!(heap.allocate_typed_array(registry, TRAIT, 1), Err(E::Type)));
}
#[test]
fn native_slots_are_aligned_and_corrupt_compact_pairs_are_rejected() {
let registry = fixture_registry();
let mut mixed =
TypedStorage::new_struct(registry.clone(), MIXED, &RuntimeBudget::default()).unwrap();
let offset = mixed.slot(3).unwrap().1;
// SAFETY: exact initialized StringSlot, as established by the immutable layout.
let addr = unsafe { mixed.data.get::<StringSlot>(offset) } as *const _ as usize;
assert_eq!(addr % align_of::<StringSlot>(), 0);
let offset = mixed.slot(4).unwrap().1;
let addr = unsafe { mixed.data.get::<DynamicSlot>(offset) } as *const _ as usize;
assert_eq!(addr % align_of::<DynamicSlot>(), 0);
let offset = mixed.slot(5).unwrap().1;
unsafe {
mixed
.data
.replace(offset, TraitSlot { receiver: HeapRef::NULL, implementation: 1, padding: 0 });
}
assert_eq!(mixed.read(5).unwrap_err(), E::Type);
let offset = mixed.slot(0).unwrap().1;
unsafe {
mixed.data.replace(offset, 2_u8);
}
assert_eq!(mixed.read(0).unwrap_err(), E::Type);
assert_eq!(size_of::<TraitSlot>(), 16);
assert_eq!(size_of::<PixelSlot>(), 24);
}
#[test]
fn unpublished_native_prefix_cleanup_drops_only_initialized_slots() {
let registry = fixture_registry();
let budget = RuntimeBudget::default();
let text: Arc<str> = Arc::from("prefix");
let layout = registry.type_layout(STRINGS).unwrap().array.unwrap();
let data = Allocation::new(layout.stride * 3, layout.element_alignment, &budget).unwrap();
let mut storage =
TypedStorage { registry, type_id: STRINGS, count: Some(3), initialized: 0, data };
// Simulate cancellation during initialization. Remaining native slots were
// never constructed; cleanup must not interpret their zero backing bytes.
unsafe {
storage.data.init::<StringSlot>(0, Some(text.clone()));
}
storage.initialized = 1;
assert_eq!(Arc::strong_count(&text), 2);
drop(storage);
assert_eq!(Arc::strong_count(&text), 1);
assert_eq!(budget.used(Q::GuestBytes), 0);
}
#[test]
fn allocation_failure_after_native_initialization_refunds_every_domain() {
let registry = fixture_registry();
let budget =
RuntimeBudget::new(RuntimeLimits::default().lowered(Q::AuxiliaryBytes, 0).unwrap());
let mut heap = Heap::with_budget(&budget);
assert!(
matches!(heap.allocate_typed_struct(registry, MIXED), Err(E::Resource(e)) if e.resource == Q::AuxiliaryBytes)
);
assert_eq!(heap.len(), 0);
assert_eq!(heap.allocation_count(), 0);
for q in [Q::GuestBytes, Q::HandleSlots, Q::AuxiliaryBytes, Q::TemporaryBytes] {
assert_eq!(budget.used(q), 0);
}
}
#[test]
fn huge_array_fails_before_initialization_and_reused_storage_gets_defaults() {
let registry = fixture_registry();
let budget = RuntimeBudget::default();
let mut heap = Heap::with_budget(&budget);
assert!(
matches!(heap.allocate_typed_array(registry.clone(), PIXELS, u32::MAX), Err(E::Resource(e)) if matches!(e.reason, ResourceReason::Limit | ResourceReason::SizeOverflow))
);
assert_eq!(budget.used(Q::GuestBytes), 0);
let first = heap.allocate_typed_array(registry.clone(), VECS, 1).unwrap();
heap.store_typed(&registry, first, 0, &[Value::Float(1.0), Value::Float(2.0)]).unwrap();
heap.sweep();
let reused = heap.allocate_typed_array(registry.clone(), VECS, 1).unwrap();
assert_eq!(first.index, reused.index);
assert_ne!(first.generation, reused.generation);
assert_eq!(values(&heap, &registry, reused, 0), [Value::Float(0.0), Value::Float(0.0)]);
}
#[test]
fn failed_multislot_writes_are_atomic_and_do_not_drop_native_owners() {
let registry = fixture_registry();
let mut heap = Heap::new();
let r = heap.allocate_typed_array(registry.clone(), DYNAMICS, 1).unwrap();
let text: Arc<str> = Arc::from("keep");
heap.store_typed(
&registry,
r,
0,
&[Value::Int64(STRING.0.into()), Value::String(text.clone())],
)
.unwrap();
let dead = HeapRef { index: 999, generation: 1 };
for (bad, error) in [
(vec![Value::Int64(STRING.0.into())], E::Type),
(vec![Value::Null, Value::String(text.clone())], E::Type),
(vec![Value::Int64(ENEMY.0.into()), Value::HeapRef(dead)], E::InvalidHandle),
(vec![Value::Int64(VEC.0.into()), Value::HeapRef(dead)], E::InvalidHandle),
(vec![Value::Int64(VEC.0.into()), Value::HeapRef(r)], E::Type),
(vec![Value::Int64(TRAIT.0.into()), Value::HeapRef(r)], E::Type),
] {
let before = Arc::strong_count(&text);
assert_eq!(heap.store_typed(&registry, r, 0, &bad).unwrap_err(), error);
assert_eq!(Arc::strong_count(&text), before);
let output = heap.load_typed(&registry, r, 0).unwrap();
let [Value::Int64(tag), Value::String(alias)] = output.as_slice() else {
panic!("original group")
};
assert_eq!(*tag, STRING.0 as i64);
assert!(Arc::ptr_eq(alias, &text));
}
assert_eq!(Arc::strong_count(&text), 2);
heap.sweep();
assert_eq!(Arc::strong_count(&text), 1);
}
#[test]
fn typed_boundaries_never_use_cross_numeric_value_equality_or_partial_groups() {
let registry = fixture_registry();
let heap = Heap::new();
for (ty, bad) in [
(I32, vec![Value::Int64(0)]),
(I64, vec![Value::Int32(0)]),
(FLOAT, vec![Value::Int64(0)]),
(BOOL, vec![Value::Int32(0)]),
(VEC, vec![Value::Float(1.0)]),
(VEC, vec![Value::Int64(1), Value::Float(1.0)]),
(PIXEL, vec![Value::Int32(0), Value::Int64(0), Value::Int64(0)]),
(PIXEL, vec![Value::Int64(0), Value::Int64(0), Value::Int64(u32::MAX as i64 + 1)]),
(ENEMY, vec![Value::HeapRef(HeapRef::NULL)]),
(TypeId(u32::MAX), vec![Value::Null]),
] {
assert_eq!(value_contract::validate(&registry, &heap, ty, &bad).unwrap_err(), E::Type);
}
assert_eq!(
value_contract::validate(
&registry,
&heap,
ENEMY,
&[Value::HeapRef(HeapRef { index: 1, generation: 0 })]
)
.unwrap_err(),
E::InvalidHandle
);
}
#[test]
fn typed_dynamic_self_cycle_uses_one_mark_worklist_entry() {
let registry = fixture_registry();
let budget = RuntimeBudget::new(
RuntimeLimits::default().lowered(Q::TemporaryBytes, size_of::<HeapRef>() as u64).unwrap(),
);
let mut heap = Heap::with_budget(&budget);
let r = heap.allocate_typed_array(registry.clone(), DYNAMICS, 128).unwrap();
for i in 0..128 {
heap.store_typed(&registry, r, i, &[Value::Int64(DYNAMICS.0.into()), Value::HeapRef(r)])
.unwrap();
}
heap.mark_from_roots(std::iter::repeat_n(r, 128)).unwrap();
heap.sweep();
assert!(heap.is_valid(r));
assert_eq!(budget.used(Q::TemporaryBytes), 0);
heap.sweep();
assert_eq!(budget.used(Q::GuestBytes), 0);
}
@@ -0,0 +1,302 @@
//! Exact Registry-aware boundary checks. No numeric coercion or object-graph walk.
use crate::heap::Heap;
use crate::resource_budget::ResourceFailure;
use prometeu_bytecode::registry::{BuiltinId as B, Registry, TypeId, TypeKind};
use prometeu_bytecode::{HeapRef, Value};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum ValueError {
Type,
InvalidHandle,
NullReference,
Bounds,
Resource(ResourceFailure),
}
impl From<ResourceFailure> for ValueError {
fn from(value: ResourceFailure) -> Self {
Self::Resource(value)
}
}
/// The accepted catalogue has at most three slots per stored value. This buffer
/// clones native owners, but never allocates a temporary Vec for a read.
#[derive(Debug)]
pub(crate) struct ValueGroup {
values: [Value; 3],
len: usize,
}
impl ValueGroup {
pub fn new(values: &[Value]) -> Self {
assert!(values.len() <= 3);
let mut result =
Self { values: [Value::Null, Value::Null, Value::Null], len: values.len() };
result.values[..values.len()].clone_from_slice(values);
result
}
pub fn as_slice(&self) -> &[Value] {
&self.values[..self.len]
}
}
pub(crate) fn u32_carrier(value: &Value) -> Result<u32, ValueError> {
match value {
Value::Int64(n) => u32::try_from(*n).map_err(|_| ValueError::Type),
_ => Err(ValueError::Type),
}
}
pub(crate) fn validate(
registry: &Registry,
heap: &Heap,
type_id: TypeId,
values: &[Value],
) -> Result<(), ValueError> {
let layout = registry.type_layout(type_id).ok_or(ValueError::Type)?;
if values.len() != layout.storage.slots as usize {
return Err(ValueError::Type);
}
let kind = &registry.declarations().types[type_id.0 as usize].kind;
let valid = match kind {
TypeKind::Struct(_) | TypeKind::Array(_) => match &values[0] {
Value::Null => true,
Value::HeapRef(r) => {
if r.is_null() {
return Err(ValueError::Type);
}
heap.concrete_type(*r, registry)? == type_id
}
_ => false,
},
TypeKind::Trait(_) => return validate_trait(registry, heap, type_id, values),
TypeKind::Builtin(B::DYNAMIC) => return validate_dynamic(registry, heap, values),
TypeKind::Builtin(id) => match (*id, values) {
(B::INT32, [Value::Int32(_)])
| (B::INT64, [Value::Int64(_)])
| (B::FLOAT, [Value::Float(_)])
| (B::BOOL, [Value::Boolean(_)])
| (B::STRING, [Value::String(_) | Value::Null])
| (B::VEC2, [Value::Float(_), Value::Float(_)]) => true,
(B::COLOR, [color]) => u32_carrier(color).is_ok(),
(B::PIXEL, [Value::Int64(_), Value::Int64(_), color]) => u32_carrier(color).is_ok(),
_ => false,
},
};
if valid { Ok(()) } else { Err(ValueError::Type) }
}
fn validate_trait(
registry: &Registry,
heap: &Heap,
trait_id: TypeId,
values: &[Value],
) -> Result<(), ValueError> {
if matches!(values, [Value::Null, Value::Null]) {
return Ok(());
}
let [Value::HeapRef(receiver), implementation] = values else { return Err(ValueError::Type) };
if receiver.is_null() {
return Err(ValueError::Type);
}
let owner = heap.concrete_type(*receiver, registry)?;
let id = u32_carrier(implementation)?;
let implementation =
registry.declarations().implementations.get(id as usize).ok_or(ValueError::Type)?;
if implementation.owner == owner && implementation.trait_id == trait_id {
Ok(())
} else {
Err(ValueError::Type)
}
}
fn validate_dynamic(registry: &Registry, heap: &Heap, values: &[Value]) -> Result<(), ValueError> {
if values.len() != 2 {
return Err(ValueError::Type);
}
if matches!(values, [Value::Null, Value::Null]) {
return Ok(());
}
let type_id = TypeId(u32_carrier(&values[0])?);
let layout = registry.type_layout(type_id).ok_or(ValueError::Type)?;
if matches!(
registry.declarations().types[type_id.0 as usize].kind,
TypeKind::Builtin(B::DYNAMIC)
) {
return Err(ValueError::Type); // Repacking is identity, never Dynamic<Dynamic>.
}
if matches!(values[1], Value::Null) {
return if layout.storage.nullable() { Ok(()) } else { Err(ValueError::Type) };
}
if layout.storage.slots == 1 {
return validate(registry, heap, type_id, &values[1..]);
}
let Value::HeapRef(handle) = values[1] else { return Err(ValueError::Type) };
if handle == HeapRef::NULL {
return Err(ValueError::Type);
}
heap.dynamic_box_values(registry, handle, type_id)?;
Ok(())
}
/// Semantic pack helper. The interpreter must retain source stack roots until
/// this returns and publish/consume the complete group atomically.
pub(crate) fn pack_dynamic(
registry: &std::sync::Arc<Registry>,
heap: &mut Heap,
type_id: TypeId,
values: &[Value],
) -> Result<ValueGroup, ValueError> {
validate(registry, heap, type_id, values)?;
if is_dynamic(registry, type_id) {
return Ok(ValueGroup::new(values));
}
let payload = if values.iter().all(|v| matches!(v, Value::Null)) {
Value::Null // Includes absent traits: typed null does not need a box.
} else if values.len() == 1 {
values[0].clone()
} else {
Value::HeapRef(heap.allocate_dynamic_box(registry.clone(), type_id, values)?)
};
Ok(ValueGroup::new(&[Value::Int64(type_id.0.into()), payload]))
}
fn is_dynamic(registry: &Registry, type_id: TypeId) -> bool {
matches!(registry.declarations().types[type_id.0 as usize].kind, TypeKind::Builtin(B::DYNAMIC))
}
/// Compatibility validates malformed input even for a mismatched destination.
/// No allocation, extraction, or Arc/box clone occurs in a query.
pub(crate) fn can_unpack_dynamic(
registry: &Registry,
heap: &Heap,
target: TypeId,
values: &[Value],
) -> Result<bool, ValueError> {
let target_layout = registry.type_layout(target).ok_or(ValueError::Type)?;
validate_dynamic(registry, heap, values)?;
if is_dynamic(registry, target) {
return Ok(true);
}
match &values[0] {
Value::Null => Ok(target_layout.storage.nullable()),
tag => Ok(TypeId(u32_carrier(tag)?) == target),
}
}
pub(crate) fn unpack_dynamic(
registry: &Registry,
heap: &Heap,
target: TypeId,
values: &[Value],
) -> Result<ValueGroup, ValueError> {
if !can_unpack_dynamic(registry, heap, target, values)? {
return Err(ValueError::Type);
}
if is_dynamic(registry, target) {
return Ok(ValueGroup::new(values));
}
let layout = registry.type_layout(target).unwrap().storage;
if matches!(values[1], Value::Null) {
return Ok(ValueGroup::new(layout.default_values()));
}
if layout.slots == 1 {
return Ok(ValueGroup::new(&values[1..]));
}
let Value::HeapRef(r) = values[1] else { return Err(ValueError::Type) };
Ok(ValueGroup::new(heap.dynamic_box_values(registry, r, target)?))
}
// All reference operations validate complete source values before querying the
// underlying concrete object. Invalid handles/pairs never become false or null.
fn reference(
registry: &Registry,
heap: &Heap,
source: TypeId,
values: &[Value],
) -> Result<Option<(HeapRef, TypeId)>, ValueError> {
let kind = registry.declarations().types.get(source.0 as usize).ok_or(ValueError::Type)?;
if !matches!(kind.kind, TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Trait(_)) {
return Err(ValueError::Type);
}
validate(registry, heap, source, values)?;
match values.first() {
Some(Value::Null) => Ok(None),
Some(Value::HeapRef(receiver)) => {
Ok(Some((*receiver, heap.concrete_type(*receiver, registry)?)))
}
_ => Err(ValueError::Type),
}
}
fn concrete_target(registry: &Registry, target: TypeId) -> Result<(), ValueError> {
if matches!(
registry.declarations().types.get(target.0 as usize).map(|t| &t.kind),
Some(TypeKind::Struct(_) | TypeKind::Array(_))
) {
Ok(())
} else {
Err(ValueError::Type)
}
}
fn trait_target(registry: &Registry, target: TypeId) -> Result<(), ValueError> {
if matches!(
registry.declarations().types.get(target.0 as usize).map(|t| &t.kind),
Some(TypeKind::Trait(_))
) {
Ok(())
} else {
Err(ValueError::Type)
}
}
pub(crate) fn ref_is_exact(
registry: &Registry,
heap: &Heap,
source: TypeId,
target: TypeId,
values: &[Value],
) -> Result<bool, ValueError> {
concrete_target(registry, target)?;
Ok(reference(registry, heap, source, values)?.is_some_and(|(_, ty)| ty == target))
}
pub(crate) fn ref_implements(
registry: &Registry,
heap: &Heap,
source: TypeId,
target: TypeId,
values: &[Value],
) -> Result<bool, ValueError> {
trait_target(registry, target)?;
Ok(reference(registry, heap, source, values)?
.is_some_and(|(_, ty)| registry.implementation(ty, target).is_some()))
}
pub(crate) fn ref_to_trait(
registry: &Registry,
heap: &Heap,
source: TypeId,
target: TypeId,
values: &[Value],
) -> Result<ValueGroup, ValueError> {
trait_target(registry, target)?;
let Some((receiver, ty)) = reference(registry, heap, source, values)? else {
return Ok(ValueGroup::new(&[Value::Null, Value::Null]));
};
let implementation = registry.implementation(ty, target).ok_or(ValueError::Type)?;
Ok(ValueGroup::new(&[Value::HeapRef(receiver), Value::Int64(implementation.0.into())]))
}
pub(crate) fn ref_cast(
registry: &Registry,
heap: &Heap,
source: TypeId,
target: TypeId,
values: &[Value],
) -> Result<ValueGroup, ValueError> {
concrete_target(registry, target)?;
let Some((receiver, ty)) = reference(registry, heap, source, values)? else {
return Ok(ValueGroup::new(&[Value::Null]));
};
if ty != target {
return Err(ValueError::Type);
}
Ok(ValueGroup::new(&[Value::HeapRef(receiver)]))
}
#[cfg(test)]
mod reference_tests;
@@ -0,0 +1,179 @@
use super::*;
use crate::resource_budget::{RuntimeBudget, RuntimeLimits, RuntimeResource as Q};
use prometeu_bytecode::load_limits::LoadBudget;
use prometeu_bytecode::registry::{ImplementationDecl, RegistryDeclarations, TypeDecl};
use std::sync::Arc;
fn fixture() -> (Arc<Registry>, Heap, RuntimeBudget) {
let kind = |kind| TypeDecl { name: None, kind };
let registry = Arc::new(
Registry::resolve(
RegistryDeclarations {
types: vec![
kind(TypeKind::Builtin(B::INT32)),
kind(TypeKind::Struct(vec![])),
kind(TypeKind::Struct(vec![])),
kind(TypeKind::Array(TypeId(0))),
kind(TypeKind::Array(TypeId(1))),
kind(TypeKind::Trait(vec![])),
kind(TypeKind::Trait(vec![])),
kind(TypeKind::Builtin(B::DYNAMIC)),
],
functions: vec![],
implementations: vec![
ImplementationDecl { owner: TypeId(1), trait_id: TypeId(5), methods: vec![] },
ImplementationDecl { owner: TypeId(1), trait_id: TypeId(6), methods: vec![] },
ImplementationDecl { owner: TypeId(2), trait_id: TypeId(6), methods: vec![] },
],
},
0,
&mut LoadBudget::new(Default::default()),
)
.unwrap(),
);
let budget = RuntimeBudget::new(RuntimeLimits::default());
let heap = Heap::with_budget(&budget);
(registry, heap, budget)
}
#[test]
fn cross_trait_conversion_preserves_receiver_and_accepts_implementation_zero() {
let (r, mut heap, budget) = fixture();
let receiver = heap.allocate_typed_struct(r.clone(), TypeId(1)).unwrap();
let concrete = [Value::HeapRef(receiver)];
let before =
[budget.used(Q::GuestBytes), budget.used(Q::AuxiliaryBytes), budget.used(Q::HandleSlots)];
let first = ref_to_trait(&r, &heap, TypeId(1), TypeId(5), &concrete).unwrap();
assert!(matches!(first.as_slice(), [Value::HeapRef(h), Value::Int64(0)] if *h == receiver));
let second = ref_to_trait(&r, &heap, TypeId(5), TypeId(6), first.as_slice()).unwrap();
assert!(matches!(second.as_slice(), [Value::HeapRef(h), Value::Int64(1)] if *h == receiver));
assert!(ref_implements(&r, &heap, TypeId(5), TypeId(6), first.as_slice()).unwrap());
assert!(ref_is_exact(&r, &heap, TypeId(6), TypeId(1), second.as_slice()).unwrap());
let restored = ref_cast(&r, &heap, TypeId(6), TypeId(1), second.as_slice()).unwrap();
assert!(matches!(restored.as_slice(), [Value::HeapRef(h)] if *h == receiver));
assert_eq!(
before,
[budget.used(Q::GuestBytes), budget.used(Q::AuxiliaryBytes), budget.used(Q::HandleSlots)]
);
}
#[test]
fn null_queries_are_false_and_null_conversions_preserve_absence() {
let (r, heap, _) = fixture();
for (source, values) in [
(TypeId(1), vec![Value::Null]),
(TypeId(3), vec![Value::Null]),
(TypeId(5), vec![Value::Null, Value::Null]),
] {
assert!(!ref_is_exact(&r, &heap, source, TypeId(1), &values).unwrap());
assert!(!ref_implements(&r, &heap, source, TypeId(5), &values).unwrap());
assert!(matches!(
ref_cast(&r, &heap, source, TypeId(1), &values).unwrap().as_slice(),
[Value::Null]
));
assert!(matches!(
ref_to_trait(&r, &heap, source, TypeId(5), &values).unwrap().as_slice(),
[Value::Null, Value::Null]
));
}
}
#[test]
fn incompatible_present_values_fault_only_on_conversion() {
let (r, mut heap, _) = fixture();
let receiver = heap.allocate_typed_struct(r.clone(), TypeId(2)).unwrap();
let values = [Value::HeapRef(receiver)];
assert!(!ref_is_exact(&r, &heap, TypeId(2), TypeId(1), &values).unwrap());
assert!(!ref_implements(&r, &heap, TypeId(2), TypeId(5), &values).unwrap());
assert_eq!(ref_cast(&r, &heap, TypeId(2), TypeId(1), &values).unwrap_err(), ValueError::Type);
assert_eq!(
ref_to_trait(&r, &heap, TypeId(2), TypeId(5), &values).unwrap_err(),
ValueError::Type
);
// The actual U view of B cannot masquerade as the T view of A.
let view = ref_to_trait(&r, &heap, TypeId(2), TypeId(6), &values).unwrap();
assert_eq!(
ref_to_trait(&r, &heap, TypeId(6), TypeId(5), view.as_slice()).unwrap_err(),
ValueError::Type
);
}
#[test]
fn arrays_use_exact_constructor_identity_and_never_implement_traits() {
let (r, mut heap, _) = fixture();
let receiver = heap.allocate_typed_array(r.clone(), TypeId(3), 0).unwrap();
let values = [Value::HeapRef(receiver)];
assert!(ref_is_exact(&r, &heap, TypeId(3), TypeId(3), &values).unwrap());
assert!(!ref_is_exact(&r, &heap, TypeId(3), TypeId(4), &values).unwrap());
assert!(!ref_implements(&r, &heap, TypeId(3), TypeId(5), &values).unwrap());
assert_eq!(ref_cast(&r, &heap, TypeId(3), TypeId(4), &values).unwrap_err(), ValueError::Type);
assert_eq!(
ref_to_trait(&r, &heap, TypeId(3), TypeId(5), &values).unwrap_err(),
ValueError::Type
);
}
#[test]
fn malformed_trait_pairs_are_not_ordinary_mismatches() {
let (r, mut heap, _) = fixture();
let receiver = heap.allocate_typed_struct(r.clone(), TypeId(1)).unwrap();
for values in [
vec![Value::Null, Value::Int64(0)],
vec![Value::Null, Value::Int64(1)],
vec![Value::HeapRef(receiver), Value::Int32(0)],
vec![Value::HeapRef(receiver), Value::Int64(1)],
vec![Value::HeapRef(receiver), Value::Int64(2)],
vec![Value::HeapRef(receiver), Value::Int64(-1)],
vec![Value::HeapRef(receiver), Value::Int64(u32::MAX.into())],
] {
assert_eq!(ref_is_exact(&r, &heap, TypeId(5), TypeId(2), &values), Err(ValueError::Type));
assert_eq!(ref_implements(&r, &heap, TypeId(5), TypeId(6), &values), Err(ValueError::Type));
assert_eq!(
ref_to_trait(&r, &heap, TypeId(5), TypeId(6), &values).unwrap_err(),
ValueError::Type
);
}
}
#[test]
fn stale_wrong_registry_and_false_source_type_remain_errors() {
let (r, mut heap, _) = fixture();
let receiver = heap.allocate_typed_struct(r.clone(), TypeId(1)).unwrap();
let values = [Value::HeapRef(receiver)];
assert_eq!(ref_is_exact(&r, &heap, TypeId(2), TypeId(1), &values), Err(ValueError::Type));
let (other, _, _) = fixture();
assert_eq!(ref_implements(&other, &heap, TypeId(1), TypeId(5), &values), Err(ValueError::Type));
heap.mark_from_roots([]).unwrap();
heap.sweep();
assert_eq!(
ref_is_exact(&r, &heap, TypeId(1), TypeId(2), &values),
Err(ValueError::InvalidHandle)
);
assert_eq!(
ref_to_trait(&r, &heap, TypeId(1), TypeId(5), &values).unwrap_err(),
ValueError::InvalidHandle
);
}
#[test]
fn reference_operations_reject_dynamic_builtin_and_wrong_immediate_categories() {
let (r, heap, _) = fixture();
for source in [TypeId(0), TypeId(7), TypeId(u32::MAX)] {
assert_eq!(
ref_is_exact(&r, &heap, source, TypeId(1), &[Value::Null]),
Err(ValueError::Type)
);
}
assert_eq!(
ref_is_exact(&r, &heap, TypeId(1), TypeId(5), &[Value::Null]),
Err(ValueError::Type)
);
assert_eq!(
ref_implements(&r, &heap, TypeId(1), TypeId(1), &[Value::Null]),
Err(ValueError::Type)
);
assert_eq!(
ref_cast(&r, &heap, TypeId(1), TypeId(u32::MAX), &[Value::Null]).unwrap_err(),
ValueError::Type
);
}
+356 -53
View File
@@ -9,6 +9,18 @@ use std::collections::{HashMap, HashSet, VecDeque};
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum VerifierError {
InvalidLocalSlot {
pc: usize,
slot: u32,
slots: u32,
},
InvalidBoolImmediate {
pc: usize,
},
RegistryRequired {
pc: usize,
opcode: OpCode,
},
UnknownOpcode {
pc: usize,
opcode: u16,
@@ -36,19 +48,19 @@ pub enum VerifierError {
},
StackOverflow {
pc: usize,
height: u16,
limit: u16,
height: u32,
limit: u32,
},
StackMismatchJoin {
pc: usize,
target: usize,
height_in: u16,
height_target: u16,
height_in: u32,
height_target: u32,
},
BadRetStackHeight {
pc: usize,
height: u16,
expected: u16,
height: u32,
expected: u32,
},
FunctionOutOfBounds {
func_idx: usize,
@@ -95,19 +107,19 @@ pub enum VerifierError {
/// User-provided arg_count for CALL_CLOSURE does not match callee signature
BadClosureArgCount {
pc: usize,
expected: u16,
got: u16,
expected: u32,
got: u32,
},
/// YIELD executed in an invalid context (minimal safety rule violation)
InvalidYieldContext {
pc: usize,
height: u16,
height: u32,
},
/// SPAWN arg_count does not match callee param_slots
BadSpawnArgCount {
pc: usize,
expected: u16,
got: u16,
expected: u32,
got: u32,
},
}
@@ -178,6 +190,67 @@ impl Verifier {
}
}
})?;
if instr.opcode.requires_registry() {
return Err(VerifierError::RegistryRequired {
pc: func_start + pc,
opcode: instr.opcode,
});
}
match instr.opcode {
OpCode::Call | OpCode::MakeClosure | OpCode::Spawn => {
let id = if instr.opcode == OpCode::Call {
instr.imm_u32().unwrap()
} else {
instr.imm_u32x2().unwrap().0
};
let callee = all_functions
.get(id as usize)
.ok_or(VerifierError::InvalidFuncId { pc: func_start + pc, id })?;
if instr.opcode == OpCode::Spawn {
let got = instr.imm_u32x2().unwrap().1;
if got != u32::from(callee.param_slots) {
return Err(VerifierError::BadSpawnArgCount {
pc: func_start + pc,
expected: u32::from(callee.param_slots),
got,
});
}
}
}
OpCode::GetLocal | OpCode::SetLocal => {
let slot = instr.imm_u32().unwrap();
let slots = u32::from(func.param_slots) + u32::from(func.local_slots);
if slot >= slots {
return Err(VerifierError::InvalidLocalSlot {
pc: func_start + pc,
slot,
slots,
});
}
}
OpCode::Hostcall => {
return Err(VerifierError::HostcallNotPatched {
pc: func_start + pc,
sysc_index: instr.imm_u32().unwrap(),
});
}
OpCode::Syscall => {
let id = instr.imm_u32().unwrap();
if Syscall::from_u32(id).is_none() {
return Err(VerifierError::InvalidSyscallId { pc: func_start + pc, id });
}
}
OpCode::Intrinsic => {
let id = instr.imm_u32().unwrap();
if lookup_intrinsic_by_id(id).is_none() {
return Err(VerifierError::InvalidIntrinsicId { pc: func_start + pc, id });
}
}
OpCode::PushBool if instr.imm_u8().unwrap() > 1 => {
return Err(VerifierError::InvalidBoolImmediate { pc: func_start + pc });
}
_ => {}
}
pc = instr.next_pc;
}
@@ -185,6 +258,29 @@ impl Verifier {
return Err(VerifierError::TrailingBytes { func_idx, at_pc: func_start + pc });
}
// Check branch immediates over the whole decoded range, before reachability
// analysis, so dead code cannot hide an invalid target or boundary.
let mut pc = 0;
while pc < func_code.len() {
let instr = decode_next(pc, func_code).unwrap();
if instr.opcode.spec().is_branch {
let target = instr.imm_u32().unwrap() as usize;
if target > func_code.len() {
return Err(VerifierError::InvalidJumpTarget {
pc: func_start + pc,
target: func_start + target,
});
}
if target < func_code.len() && !valid_pc.contains(&target) {
return Err(VerifierError::JumpToMidInstruction {
pc: func_start + pc,
target: func_start + target,
});
}
}
pc = instr.next_pc;
}
// Minimal stack type lattice to validate closure semantics
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum SlotTy {
@@ -215,14 +311,22 @@ impl Verifier {
while let Some(pc) = worklist.pop_front() {
let in_types = stack_types_in.get(&pc).cloned().unwrap();
let in_height = in_types.len() as u16;
let in_height = in_types.len() as u64;
let instr = decode_next(pc, func_code).unwrap(); // Guaranteed to succeed due to first pass
let spec = instr.opcode.spec();
let static_pops = spec.pops.ok_or(VerifierError::RegistryRequired {
pc: func_start + pc,
opcode: instr.opcode,
})?;
let static_pushes = spec.pushes.ok_or(VerifierError::RegistryRequired {
pc: func_start + pc,
opcode: instr.opcode,
})?;
// Resolve dynamic pops/_pushes
let (pops, _pushes) = match instr.opcode {
OpCode::PopN => {
let n = instr.imm_u32().unwrap() as u16;
let n = instr.imm_u32().unwrap() as u64;
(n, 0)
}
OpCode::Call => {
@@ -230,18 +334,18 @@ impl Verifier {
let callee = all_functions.get(func_id as usize).ok_or_else(|| {
VerifierError::InvalidFuncId { pc: func_start + pc, id: func_id }
})?;
(callee.param_slots, callee.return_slots)
(u64::from(callee.param_slots), u64::from(callee.return_slots))
}
OpCode::MakeClosure => {
// imm: fn_id (u32), capture_count (u32)
let (_fn_id, capture_count_u32) = instr.imm_u32x2().unwrap();
let capture_count = capture_count_u32 as u16;
let capture_count = capture_count_u32 as u64;
(capture_count, 1)
}
OpCode::CallClosure => {
// imm: arg_count (u32). Pops closure_ref + arg_count, _pushes callee returns.
// We can't determine _pushes here without looking at TOS type; will validate below.
let arg_count = instr.imm_u32().unwrap() as u16;
let arg_count = instr.imm_u32().unwrap() as u64;
// Temporarily set _pushes=0; we'll compute real _pushes after type checks.
(arg_count + 1, 0)
}
@@ -251,18 +355,18 @@ impl Verifier {
let callee = all_functions.get(fn_id as usize).ok_or_else(|| {
VerifierError::InvalidFuncId { pc: func_start + pc, id: fn_id }
})?;
let arg_count = arg_count_u32 as u16;
let arg_count = arg_count_u32 as u64;
// Enforce exact arity match for safety and determinism
if callee.param_slots != arg_count {
if u64::from(callee.param_slots) != arg_count {
return Err(VerifierError::BadSpawnArgCount {
pc: func_start + pc,
expected: callee.param_slots,
got: arg_count,
expected: u32::from(callee.param_slots),
got: arg_count as u32,
});
}
(arg_count, 0)
}
OpCode::Ret => (func.return_slots, 0),
OpCode::Ret => (u64::from(func.return_slots), 0),
OpCode::Hostcall => {
return Err(VerifierError::HostcallNotPatched {
pc: func_start + pc,
@@ -274,16 +378,16 @@ impl Verifier {
let syscall = Syscall::from_u32(id).ok_or_else(|| {
VerifierError::InvalidSyscallId { pc: func_start + pc, id }
})?;
(syscall.args_count() as u16, syscall.results_count() as u16)
(syscall.args_count() as u64, syscall.results_count() as u64)
}
OpCode::Intrinsic => {
let id = instr.imm_u32().unwrap();
let intrinsic = lookup_intrinsic_by_id(id).ok_or_else(|| {
VerifierError::InvalidIntrinsicId { pc: func_start + pc, id }
})?;
(intrinsic.arg_slots() as u16, intrinsic.ret_slots() as u16)
(intrinsic.arg_slots() as u64, intrinsic.ret_slots() as u64)
}
_ => (spec.pops, spec.pushes),
_ => (u64::from(static_pops), u64::from(static_pushes)),
};
if in_height < pops {
@@ -299,7 +403,7 @@ impl Verifier {
{
return Err(VerifierError::InvalidYieldContext {
pc: func_start + pc,
height: in_height,
height: in_height as u32,
});
}
@@ -326,21 +430,21 @@ impl Verifier {
let callee = all_functions.get(fn_id as usize).ok_or_else(|| {
VerifierError::InvalidFuncId { pc: func_start + pc, id: fn_id }
})?;
let user_argc = instr.imm_u32().unwrap() as u16;
let user_argc = instr.imm_u32().unwrap() as u64;
if callee.param_slots == 0 {
// Hidden arg0 must exist in callee signature
return Err(VerifierError::BadClosureArgCount {
pc: func_start + pc,
expected: 0,
got: user_argc,
got: user_argc as u32,
});
}
let expected_user = callee.param_slots - 1; // exclude hidden arg0
if expected_user != user_argc {
if u64::from(expected_user) != user_argc {
return Err(VerifierError::BadClosureArgCount {
pc: func_start + pc,
expected: expected_user,
got: user_argc,
expected: u32::from(expected_user),
got: user_argc as u32,
});
}
// Push callee returns as Unknown types
@@ -380,6 +484,8 @@ impl Verifier {
opcode: OpCode::Dup,
});
}
// Generic transfer popped the original; restore it and its copy.
out_types.push(tos);
out_types.push(tos);
}
// Swap swaps top-2 types; ensure enough stack
@@ -390,8 +496,10 @@ impl Verifier {
opcode: OpCode::Swap,
});
}
let len = out_types.len();
out_types.swap(len - 1, len - 2);
// Generic transfer popped both values; rebuild the swapped pair.
let len = in_types.len();
out_types.push(in_types[len - 1]);
out_types.push(in_types[len - 2]);
}
// Arithmetic/logic produce NonClosure but we don't strictly need it; mark Unknown conservatively
// Calls and syscalls return Unknown
@@ -405,21 +513,21 @@ impl Verifier {
OpCode::Syscall => {
let id = instr.imm_u32().unwrap();
let syscall = Syscall::from_u32(id).unwrap();
for _ in 0..(syscall.results_count() as u16) {
for _ in 0..syscall.results_count() {
out_types.push(Unknown);
}
}
OpCode::Intrinsic => {
let id = instr.imm_u32().unwrap();
let intrinsic = lookup_intrinsic_by_id(id).unwrap();
for _ in 0..(intrinsic.ret_slots() as u16) {
for _ in 0..intrinsic.ret_slots() {
out_types.push(Unknown);
}
}
_ => {
// Default: push Unknown for any declared _pushes
if spec.pushes > 0 {
for _ in 0..spec.pushes {
if static_pushes > 0 {
for _ in 0..static_pushes {
out_types.push(Unknown);
}
}
@@ -432,29 +540,36 @@ impl Verifier {
// If we reached here, we handled it above and set dynamic_pushes
0
}
OpCode::Syscall => spec.pushes, // already added Unknowns above
OpCode::Intrinsic => spec.pushes, // already added Unknowns above
OpCode::Call => spec.pushes, // already added Unknowns above
_ => spec.pushes,
OpCode::Syscall => static_pushes, // already added Unknowns above
OpCode::Intrinsic => static_pushes, // already added Unknowns above
OpCode::Call => static_pushes, // already added Unknowns above
_ => static_pushes,
});
let out_height = (out_types.len()) as u16;
max_stack = max_stack.max(out_height);
// Enforce declared max stack if provided (0 means "no explicit limit")
if func.max_stack_slots != 0 && out_height > func.max_stack_slots {
let out_height = out_types.len() as u32;
if out_height > u32::from(u16::MAX) {
return Err(VerifierError::StackOverflow {
pc: func_start + pc,
height: out_height,
limit: func.max_stack_slots,
limit: u32::from(u16::MAX),
});
}
max_stack = max_stack.max(out_height as u16);
// Enforce declared max stack if provided (0 means "no explicit limit")
if func.max_stack_slots != 0 && out_height > u32::from(func.max_stack_slots) {
return Err(VerifierError::StackOverflow {
pc: func_start + pc,
height: out_height,
limit: u32::from(func.max_stack_slots),
});
}
if instr.opcode == OpCode::Ret && in_height != func.return_slots {
if instr.opcode == OpCode::Ret && in_height != u64::from(func.return_slots) {
return Err(VerifierError::BadRetStackHeight {
pc: func_start + pc,
height: in_height,
expected: func.return_slots,
height: in_height as u32,
expected: u32::from(func.return_slots),
});
}
@@ -496,11 +611,11 @@ impl Verifier {
if target_rel == func_len {
// jump to the end of function
if out_height != func.return_slots {
if out_height != u32::from(func.return_slots) {
return Err(VerifierError::BadRetStackHeight {
pc: func_start + pc,
height: out_height,
expected: func.return_slots,
expected: u32::from(func.return_slots),
});
}
} else {
@@ -512,7 +627,7 @@ impl Verifier {
}
if let Some(existing_types) = stack_types_in.get_mut(&target_rel) {
let existing_height = existing_types.len() as u16;
let existing_height = existing_types.len() as u32;
if existing_height != out_height {
return Err(VerifierError::StackMismatchJoin {
pc: func_start + pc,
@@ -546,7 +661,7 @@ impl Verifier {
let func_len = layouts.get(func_idx).map(|l| l.end - l.start).unwrap_or_else(|| 0);
if next_pc < func_len {
if let Some(existing_types) = stack_types_in.get_mut(&next_pc) {
let existing_height = existing_types.len() as u16;
let existing_height = existing_types.len() as u32;
if existing_height != out_height {
return Err(VerifierError::StackMismatchJoin {
pc: func_start + pc,
@@ -951,6 +1066,18 @@ mod golden_ext {
#[cfg(test)]
mod tests {
#[test]
fn slot_only_verifier_rejects_registry_instruction_even_when_unreachable() {
use super::{Verifier, VerifierError};
use prometeu_bytecode::{FunctionMeta, assemble};
let code = assemble("HALT\nDYN_PACK 0").unwrap();
let f = FunctionMeta { code_len: code.len() as u32, ..Default::default() };
assert!(matches!(
Verifier::verify(&code, &[f]),
Err(VerifierError::RegistryRequired { pc: 2, .. })
));
}
use super::*;
#[test]
@@ -1388,3 +1515,179 @@ mod tests {
assert_eq!(res, Err(VerifierError::BadRetStackHeight { pc: 6, height: 2, expected: 1 }));
}
}
#[cfg(test)]
mod width_regressions {
use super::*;
fn op(code: &mut Vec<u8>, opcode: OpCode) {
code.extend_from_slice(&(opcode as u16).to_le_bytes());
}
fn arg(code: &mut Vec<u8>, opcode: OpCode, n: u32) {
op(code, opcode);
code.extend_from_slice(&n.to_le_bytes());
}
fn one(code: &[u8]) -> Vec<FunctionMeta> {
vec![FunctionMeta { code_len: code.len() as u32, ..Default::default() }]
}
#[test]
fn popn_u32_counts_do_not_wrap_to_zero() {
for n in [65_536, u32::MAX] {
let mut code = vec![];
arg(&mut code, OpCode::PopN, n);
op(&mut code, OpCode::Halt);
assert_eq!(
Verifier::verify(&code, &one(&code)).unwrap_err(),
VerifierError::StackUnderflow { pc: 0, opcode: OpCode::PopN }
);
}
}
#[test]
fn closure_capture_u32_counts_do_not_wrap_to_zero() {
let mut code = vec![];
arg(&mut code, OpCode::MakeClosure, 0);
code.extend_from_slice(&65_536_u32.to_le_bytes());
op(&mut code, OpCode::Halt);
assert_eq!(
Verifier::verify(&code, &one(&code)).unwrap_err(),
VerifierError::StackUnderflow { pc: 0, opcode: OpCode::MakeClosure }
);
}
#[test]
fn closure_argument_plus_receiver_cannot_overflow() {
for n in [65_536, u32::MAX] {
let mut code = vec![];
arg(&mut code, OpCode::MakeClosure, 0);
code.extend_from_slice(&0_u32.to_le_bytes());
arg(&mut code, OpCode::CallClosure, n);
op(&mut code, OpCode::Halt);
assert_eq!(
Verifier::verify(&code, &one(&code)).unwrap_err(),
VerifierError::StackUnderflow { pc: 10, opcode: OpCode::CallClosure }
);
}
}
#[test]
fn spawn_diagnostic_preserves_the_full_u32_argument_count() {
let mut code = vec![];
arg(&mut code, OpCode::Spawn, 0);
code.extend_from_slice(&65_536_u32.to_le_bytes());
op(&mut code, OpCode::Halt);
assert_eq!(
Verifier::verify(&code, &one(&code)).unwrap_err(),
VerifierError::BadSpawnArgCount { pc: 0, expected: 0, got: 65_536 }
);
}
#[test]
fn inferred_stack_height_cannot_wrap_when_exported_to_current_function_metadata() {
let mut code = vec![];
arg(&mut code, OpCode::Call, 1);
op(&mut code, OpCode::Dup);
op(&mut code, OpCode::Halt);
let functions = vec![
FunctionMeta { code_len: code.len() as u32, ..Default::default() },
FunctionMeta {
code_offset: code.len() as u32,
return_slots: u16::MAX,
..Default::default()
},
];
assert_eq!(
Verifier::verify(&code, &functions).unwrap_err(),
VerifierError::StackOverflow { pc: 6, height: 65_536, limit: 65_535 }
);
}
#[test]
fn local_indices_cannot_address_temporary_slots_even_in_dead_code() {
for operation in [OpCode::GetLocal, OpCode::SetLocal] {
let mut code = vec![];
op(&mut code, OpCode::Halt);
arg(&mut code, operation, 1);
let mut functions = one(&code);
functions[0].local_slots = 1;
assert_eq!(
Verifier::verify(&code, &functions).unwrap_err(),
VerifierError::InvalidLocalSlot { pc: 2, slot: 1, slots: 1 }
);
}
}
#[test]
fn unreachable_bad_functions_natives_booleans_and_jumps_are_rejected() {
for operation in [OpCode::Call, OpCode::Intrinsic, OpCode::Syscall] {
let mut code = vec![];
op(&mut code, OpCode::Halt);
arg(&mut code, operation, u32::MAX);
assert!(Verifier::verify(&code, &one(&code)).is_err());
}
let mut code = vec![];
op(&mut code, OpCode::Halt);
op(&mut code, OpCode::PushBool);
code.push(2);
assert_eq!(
Verifier::verify(&code, &one(&code)).unwrap_err(),
VerifierError::InvalidBoolImmediate { pc: 2 }
);
let mut code = vec![];
op(&mut code, OpCode::Halt);
arg(&mut code, OpCode::Jmp, 3);
assert_eq!(
Verifier::verify(&code, &one(&code)).unwrap_err(),
VerifierError::JumpToMidInstruction { pc: 2, target: 3 }
);
}
#[test]
fn dup_increases_height_and_restores_both_copies_for_arithmetic() {
let mut code = vec![];
arg(&mut code, OpCode::PushI32, 7);
op(&mut code, OpCode::Dup);
op(&mut code, OpCode::Add);
op(&mut code, OpCode::Ret);
let mut functions = one(&code);
functions[0].return_slots = 1;
assert_eq!(Verifier::verify(&code, &functions).unwrap(), vec![2]);
}
#[test]
fn swap_preserves_height_and_known_closure_in_the_correct_position() {
let mut code = vec![];
arg(&mut code, OpCode::MakeClosure, 1);
code.extend_from_slice(&0_u32.to_le_bytes());
arg(&mut code, OpCode::PushI32, 5);
op(&mut code, OpCode::Swap);
arg(&mut code, OpCode::CallClosure, 1);
op(&mut code, OpCode::Ret);
let start = code.len();
op(&mut code, OpCode::Ret);
let functions = vec![
FunctionMeta { code_len: start as u32, ..Default::default() },
FunctionMeta {
code_offset: start as u32,
code_len: 2,
param_slots: 2,
..Default::default()
},
];
assert_eq!(Verifier::verify(&code, &functions).unwrap(), vec![2, 0]);
}
#[test]
fn dup_preserves_the_known_callee_in_each_closure_copy() {
let mut code = vec![];
arg(&mut code, OpCode::MakeClosure, 1);
code.extend_from_slice(&0_u32.to_le_bytes());
op(&mut code, OpCode::Dup);
arg(&mut code, OpCode::CallClosure, 0);
arg(&mut code, OpCode::CallClosure, 0);
op(&mut code, OpCode::Ret);
let start = code.len();
op(&mut code, OpCode::Ret);
let functions = vec![
FunctionMeta { code_len: start as u32, ..Default::default() },
FunctionMeta {
code_offset: start as u32,
code_len: 2,
param_slots: 1,
..Default::default()
},
];
assert_eq!(Verifier::verify(&code, &functions).unwrap(), vec![2, 0]);
}
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,69 @@
use super::*;
use crate::value_contract::{self, ValueGroup};
use prometeu_bytecode::registry::TypeId;
impl VirtualMachine {
pub(super) fn execute_dynamic(
&mut self,
opcode: OpCode,
target: u32,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
let image = self.validated_image.clone().ok_or_else(|| {
self.trap(
prometeu_bytecode::TRAP_ILLEGAL_INSTRUCTION,
opcode as u16,
"Instruction requires a validated Program Registry".into(),
pc,
)
})?;
let registry = image.registry();
let target = TypeId(target);
let width =
registry.type_layout(target).expect("validated instruction TypeId").storage.slots
as usize;
let consumed = if opcode == OpCode::DynPack { width } else { 2 };
let produced = match opcode {
OpCode::DynPack => 2,
OpCode::DynUnpack => width,
OpCode::DynCanUnpack => 1,
_ => unreachable!(),
};
if self.temporary_slots() < consumed {
return Err(self.trap(
TRAP_STACK_UNDERFLOW,
opcode as u16,
"Incomplete Dynamic source group".into(),
pc,
));
}
// Keep source roots and provisional capacity until a complete result is
// available. A refused box allocation cannot consume the source group.
let growth = self
.operand_stack
.prepare_growth(produced.saturating_sub(consumed))
.map_err(|e| self.resource_trap(e, opcode, pc))?;
let base = self.operand_stack.len() - consumed;
let values = &self.operand_stack[base..];
let result = match opcode {
OpCode::DynPack => {
value_contract::pack_dynamic(registry, &mut self.heap, target, values)
}
OpCode::DynUnpack => {
value_contract::unpack_dynamic(registry, &self.heap, target, values)
}
OpCode::DynCanUnpack => {
value_contract::can_unpack_dynamic(registry, &self.heap, target, values)
.map(|yes| ValueGroup::new(&[Value::Boolean(yes)]))
}
_ => unreachable!(),
}
.map_err(|e| self.value_trap(e, opcode, pc))?;
self.operand_stack.commit_growth(growth);
self.operand_stack.truncate(base);
self.operand_stack
.extend_from_slice(result.as_slice())
.expect("result capacity reserved before evaluation");
Ok(())
}
}
@@ -1,63 +1,62 @@
use super::*;
impl VirtualMachine {
pub(super) fn handle_safepoint(&mut self) {
pub(super) fn handle_safepoint(&mut self) -> Result<(), ResourceFailure> {
if self.gc_alloc_threshold > 0 {
let live_now = self.heap.len();
let since_last = live_now.saturating_sub(self.last_gc_live_count);
if since_last >= self.gc_alloc_threshold {
struct CollectRoots(Vec<prometeu_bytecode::HeapRef>);
impl crate::roots::RootVisitor for CollectRoots {
fn visit_heap_ref(&mut self, r: prometeu_bytecode::HeapRef) {
self.0.push(r);
}
}
let mut collector = CollectRoots(Vec::new());
self.visit_roots(&mut collector);
if let Some(cur) = self.current_coro {
collector.0.push(cur);
}
let mut coro_roots = self.heap.suspended_coroutine_handles();
collector.0.append(&mut coro_roots);
self.heap.mark_from_roots(collector.0);
// Parameters/locals are already in the operand buffer. Stream roots
// without a duplicate collection; suspended contexts are scanned by Heap.
let roots = self
.operand_stack
.iter()
.chain(self.globals.iter())
.filter_map(crate::roots::value_heap_ref)
.chain(self.current_coro);
self.heap.mark_session_roots(roots)?;
self.heap.sweep();
self.last_gc_live_count = self.heap.len();
}
}
if let Some(strings) = &self.strings {
strings.reconcile();
}
self.current_tick = self.current_tick.wrapping_add(1);
self.scheduler.wake_ready(self.current_tick);
self.scheduler.wake_ready(self.current_tick)?;
let mut switched_out = false;
if let Some(cur) = self.current_coro {
if let Some(wake) = self.sleep_requested_until.take() {
if let Some(wake) = self.sleep_requested_until {
self.scheduler.sleep_until(cur, wake)?;
self.sleep_requested_until = None;
if let Some(co) = self.heap.coroutine_data_mut(cur) {
co.pc = self.pc;
co.stack = std::mem::take(&mut self.operand_stack);
co.frames = std::mem::take(&mut self.call_stack);
co.stack = self.operand_stack.take();
co.frames = self.call_stack.take();
co.state = CoroutineState::Sleeping;
co.wake_tick = wake;
}
self.scheduler.sleep_until(cur, wake);
self.current_coro = None;
self.scheduler.clear_current();
switched_out = true;
} else if self.yield_requested {
self.scheduler.enqueue_ready(cur)?;
if let Some(co) = self.heap.coroutine_data_mut(cur) {
co.pc = self.pc;
co.stack = std::mem::take(&mut self.operand_stack);
co.frames = std::mem::take(&mut self.call_stack);
co.stack = self.operand_stack.take();
co.frames = self.call_stack.take();
co.state = CoroutineState::Ready;
}
self.scheduler.enqueue_ready(cur);
self.current_coro = None;
self.scheduler.clear_current();
switched_out = true;
} else if self.halted || self.pc >= self.program.rom.len() {
if let Some(co) = self.heap.coroutine_data_mut(cur) {
co.pc = self.pc;
co.stack = std::mem::take(&mut self.operand_stack);
co.frames = std::mem::take(&mut self.call_stack);
co.stack = self.operand_stack.take();
co.frames = self.call_stack.take();
co.state = CoroutineState::Finished;
}
self.current_coro = None;
@@ -70,8 +69,8 @@ impl VirtualMachine {
if let Some(next) = self.scheduler.dequeue_next() {
if let Some(co) = self.heap.coroutine_data_mut(next) {
self.pc = co.pc;
self.operand_stack = std::mem::take(&mut co.stack);
self.call_stack = std::mem::take(&mut co.frames);
self.operand_stack = co.stack.take();
self.call_stack = co.frames.take();
co.state = CoroutineState::Running;
}
self.current_coro = Some(next);
@@ -84,6 +83,7 @@ impl VirtualMachine {
}
self.yield_requested = false;
Ok(())
}
pub fn visit_roots<V: RootVisitor + ?Sized>(&self, visitor: &mut V) {
@@ -70,17 +70,19 @@ fn patch_module_hostcalls(
impl VirtualMachine {
pub fn initialize(&mut self, program_bytes: Vec<u8>) -> Result<(), VmInitError> {
self.program = ProgramImage::default();
self.validated_image = None;
self.strings = None;
self.pc = 0;
self.operand_stack.clear();
self.call_stack.clear();
self.globals.clear();
self.heap = Heap::new();
self.heap = Heap::with_budget(&self.budget);
self.cycles = 0;
self.halted = true;
self.last_gc_live_count = 0;
self.current_tick = 0;
self.sleep_requested_until = None;
self.scheduler = Scheduler::new();
self.scheduler = Scheduler::with_budget(&self.budget);
self.current_coro = None;
let program = match prometeu_bytecode::BytecodeLoader::load(&program_bytes) {
@@ -89,7 +91,7 @@ impl VirtualMachine {
.map_err(VmInitError::LoaderPatchFailed)?;
let max_stacks = Verifier::verify(&module.code, &module.functions)
.map_err(|e| VmInitError::VerificationFailed(format!("{:?}", e)))?;
.map_err(VmInitError::VerificationFailed)?;
let mut program = ProgramImage::from(module);
let mut functions = program.functions.as_ref().to_vec();
@@ -128,22 +130,77 @@ impl VirtualMachine {
self.capabilities = caps;
}
pub fn prepare_boot_call(&mut self) {
self.prepare_call_by_index(0);
pub fn prepare_boot_call(&mut self) -> Result<(), VmInitError> {
self.prepare_call_by_index(0, &[])
}
pub fn prepare_call(&mut self, entrypoint: &str) {
pub fn prepare_call(&mut self, entrypoint: &str) -> Result<(), VmInitError> {
self.prepare_call_with_args(entrypoint, &[])
}
pub fn prepare_call_with_args(
&mut self,
entrypoint: &str,
arguments: &[Value],
) -> Result<(), VmInitError> {
let func_idx = if let Ok(idx) = entrypoint.parse::<usize>() {
idx
} else if let Some(image) = &self.validated_image {
image
.exports()
.iter()
.rfind(|export| export.symbol == entrypoint)
.map(|export| export.func_idx as usize)
.ok_or(VmInitError::EntrypointNotFound)?
} else {
self.program.exports.get(entrypoint).map(|&idx| idx as usize).ok_or(()).unwrap_or(0)
};
self.prepare_call_by_index(func_idx);
self.prepare_call_by_index(func_idx, arguments)
}
fn prepare_call_by_index(&mut self, func_idx: usize) {
fn prepare_call_by_index(
&mut self,
func_idx: usize,
arguments: &[Value],
) -> Result<(), VmInitError> {
if self.validated_image.is_some() {
self.check_signature_group(func_idx, false, arguments).map_err(|(slot, error)| {
if self.program.functions.get(func_idx).is_none() {
VmInitError::EntrypointNotFound
} else {
VmInitError::EntrypointArgumentsInvalid {
function: func_idx as u32,
slot: slot as u32,
trap_code: Self::value_error_code(error),
}
}
})?;
}
self.budget.check(RuntimeResource::CallDepth, 1)?;
let mut imported = BudgetVec::new(&self.budget, RuntimeResource::TemporaryBytes);
if self.validated_image.is_some() {
imported.reserve(arguments.len())?;
for value in arguments {
imported.push(self.import_string_value(value)?)?;
}
}
let callee = self.program.functions.get(func_idx).cloned().unwrap_or_default();
let total_slots = callee.param_slots as usize + callee.local_slots as usize;
let stack_growth = self
.operand_stack
.prepare_growth(total_slots.saturating_sub(self.operand_stack.len()))?;
let frame_growth =
self.call_stack.prepare_growth(1usize.saturating_sub(self.call_stack.len()))?;
let main_href = self.heap.allocate_coroutine(
callee.code_offset as usize,
CoroutineState::Running,
0,
BudgetVec::new(&self.budget, RuntimeResource::AuxiliaryBytes),
BudgetVec::new(&self.budget, RuntimeResource::AuxiliaryBytes),
)?;
self.operand_stack.commit_growth(stack_growth);
self.call_stack.commit_growth(frame_growth);
self.pc = callee.code_offset as usize;
self.halted = false;
@@ -151,9 +208,14 @@ impl VirtualMachine {
self.call_stack.clear();
if let Some(func) = self.program.functions.get(func_idx) {
let total_slots = func.param_slots as u32 + func.local_slots as u32;
for _ in 0..total_slots {
self.operand_stack.push(Value::Null);
let typed = self.validated_image.is_some();
if typed {
self.operand_stack.extend_from_slice(&imported)?;
}
let null_slots =
func.local_slots as usize + if typed { 0 } else { func.param_slots as usize };
for _ in 0..null_slots {
self.operand_stack.push(Value::Null)?;
}
}
@@ -161,16 +223,10 @@ impl VirtualMachine {
return_pc: self.program.rom.len() as u32,
stack_base: 0,
func_idx,
});
})?;
let main_href = self.heap.allocate_coroutine(
self.pc,
CoroutineState::Running,
0,
Vec::new(),
Vec::new(),
);
self.current_coro = Some(main_href);
self.scheduler.set_current(self.current_coro);
Ok(())
}
}
@@ -0,0 +1,66 @@
use super::*;
use crate::value_contract::{self, ValueGroup};
use prometeu_bytecode::registry::TypeId;
impl VirtualMachine {
pub(super) fn execute_reference(
&mut self,
opcode: OpCode,
source: u32,
target: u32,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
let image = self.validated_image.clone().ok_or_else(|| {
self.trap(
prometeu_bytecode::TRAP_ILLEGAL_INSTRUCTION,
opcode as u16,
"Instruction requires a validated Program Registry".into(),
pc,
)
})?;
let registry = image.registry();
let source = TypeId(source);
let target = TypeId(target);
let consumed =
registry.type_layout(source).expect("validated source TypeId").storage.slots as usize;
let produced: usize = if opcode == OpCode::RefToTrait { 2 } else { 1 };
if self.temporary_slots() < consumed {
return Err(self.trap(
TRAP_STACK_UNDERFLOW,
opcode as u16,
"Incomplete reference source group".into(),
pc,
));
}
let growth = self
.operand_stack
.prepare_growth(produced.saturating_sub(consumed))
.map_err(|e| self.resource_trap(e, opcode, pc))?;
let base = self.operand_stack.len() - consumed;
let values = &self.operand_stack[base..];
let result = match opcode {
OpCode::RefIsExact => {
value_contract::ref_is_exact(registry, &self.heap, source, target, values)
.map(|yes| ValueGroup::new(&[Value::Boolean(yes)]))
}
OpCode::RefImplements => {
value_contract::ref_implements(registry, &self.heap, source, target, values)
.map(|yes| ValueGroup::new(&[Value::Boolean(yes)]))
}
OpCode::RefToTrait => {
value_contract::ref_to_trait(registry, &self.heap, source, target, values)
}
OpCode::RefCast => {
value_contract::ref_cast(registry, &self.heap, source, target, values)
}
_ => unreachable!(),
}
.map_err(|e| self.value_trap(e, opcode, pc))?;
self.operand_stack.commit_growth(growth);
self.operand_stack.truncate(base);
self.operand_stack
.extend_from_slice(result.as_slice())
.expect("result capacity reserved before evaluation");
Ok(())
}
}
@@ -1,6 +1,26 @@
use super::*;
impl VirtualMachine {
pub(super) fn check_call_depth(&self) -> Result<(), ResourceFailure> {
let depth = self.call_stack.len().checked_add(1).ok_or_else(|| {
self.budget.failure(
RuntimeResource::CallDepth,
crate::resource_budget::ResourceReason::SizeOverflow,
u64::MAX,
)
})?;
self.budget.check(RuntimeResource::CallDepth, depth as u64)
}
pub(super) fn resource_trap(
&self,
error: ResourceFailure,
opcode: OpCode,
pc: u32,
) -> LogicalFrameEndingReason {
self.trap(TRAP_RESOURCE_LIMIT, opcode as u16, error.to_string(), pc)
}
pub fn trap(
&self,
code: u32,
@@ -11,11 +31,28 @@ impl VirtualMachine {
LogicalFrameEndingReason::Trap(self.program.create_trap(code, opcode, message, pc))
}
pub fn push(&mut self, val: Value) {
self.operand_stack.push(val);
pub fn push(&mut self, val: Value) -> Result<(), ResourceFailure> {
let growth = self.operand_stack.prepare_growth(1)?;
let val = self.import_string_value(&val)?;
self.operand_stack.commit_growth(growth);
self.operand_stack.push(val)
}
pub fn pop(&mut self) -> Result<Value, String> {
pub(super) fn push_trap(
&mut self,
val: Value,
opcode: OpCode,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
// Interpreter copies already belong to the current image/session;
// native imports use the public push boundary instead.
self.operand_stack.push(val).map_err(|e| self.resource_trap(e, opcode, pc))
}
pub(crate) fn pop(&mut self) -> Result<Value, String> {
if self.temporary_slots() == 0 {
return Err("Stack underflow".into());
}
self.operand_stack.pop().ok_or("Stack underflow".into())
}
@@ -32,7 +69,10 @@ impl VirtualMachine {
val.as_integer().ok_or_else(|| "Expected integer".into())
}
pub fn peek(&self) -> Result<&Value, String> {
pub(crate) fn peek(&self) -> Result<&Value, String> {
if self.temporary_slots() == 0 {
return Err("Stack underflow".into());
}
self.operand_stack.last().ok_or("Stack underflow".into())
}
@@ -67,7 +107,7 @@ impl VirtualMachine {
let a = self.pop_trap(opcode, start_pc, format!("{:?} requires two operands", opcode))?;
match f(a, b) {
Ok(res) => {
self.push(res);
self.push_trap(res, opcode, start_pc)?;
Ok(())
}
Err(OpError::Trap(code, msg)) => Err(self.trap(code, opcode as u16, msg, start_pc)),
@@ -0,0 +1,69 @@
use super::*;
use crate::string_ledger::{MaterializeError, StringLedger};
use std::sync::Arc;
pub(super) struct SessionStringAllocator<'a> {
pub ledger: &'a mut Option<StringLedger>,
pub budget: RuntimeBudget,
}
impl prometeu_hal::host_return::GuestStringAllocator for SessionStringAllocator<'_> {
fn build(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault> {
if self.ledger.is_none() {
*self.ledger = Some(StringLedger::new(self.budget.clone()).map_err(resource_fault)?);
}
self.ledger.as_ref().unwrap().build(length, writer).map_err(|error| match error {
MaterializeError::Resource(resource) => resource_fault(resource),
MaterializeError::InvalidLength => VmFault::Panic(
"Native string writer did not produce its declared UTF-8 length".into(),
),
})
}
}
fn resource_fault(resource: ResourceFailure) -> VmFault {
VmFault::Trap(TRAP_RESOURCE_LIMIT, resource.to_string())
}
impl VirtualMachine {
pub(super) fn import_string_value(&mut self, value: &Value) -> Result<Value, ResourceFailure> {
let Value::String(content) = value else {
return Ok(value.clone());
};
if self.validated_image.as_ref().is_some_and(|image| image.retains_string(content))
|| self.strings.as_ref().is_some_and(|domain| domain.retains(content))
{
return Ok(value.clone());
}
if self.strings.is_none() {
self.strings = Some(StringLedger::new(self.budget.clone())?);
}
self.strings.as_ref().unwrap().import(content).map(Value::String)
}
pub(super) fn execute_string_add(
&mut self,
opcode: OpCode,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
if self.strings.is_none() {
self.strings = Some(
StringLedger::new(self.budget.clone())
.map_err(|error| self.resource_trap(error, opcode, pc))?,
);
}
let base = self.operand_stack.len() - 2;
let content = self
.strings
.as_ref()
.unwrap()
.concat_values(&self.operand_stack[base], &self.operand_stack[base + 1])
.map_err(|error| self.resource_trap(error, opcode, pc))?;
self.operand_stack.truncate(base);
self.operand_stack
.push(Value::String(content))
.expect("ADD replaces two existing slots with one");
Ok(())
}
}
@@ -0,0 +1,79 @@
use super::*;
use crate::value_contract::{self, ValueError};
impl VirtualMachine {
pub(super) fn temporary_slots(&self) -> usize {
if self.validated_image.is_none() {
return self.operand_stack.len();
}
let floor = self
.call_stack
.last()
.map(|frame| {
let function = &self.program.functions[frame.func_idx];
frame.stack_base + function.param_slots as usize + function.local_slots as usize
})
.unwrap_or(0);
self.operand_stack.len().saturating_sub(floor)
}
pub(super) fn value_error_code(error: ValueError) -> u32 {
match error {
ValueError::Type => TRAP_TYPE,
ValueError::InvalidHandle => TRAP_INVALID_HANDLE,
ValueError::NullReference => TRAP_NULL_REFERENCE,
ValueError::Bounds => TRAP_OOB,
ValueError::Resource(_) => TRAP_RESOURCE_LIMIT,
}
}
pub(super) fn value_trap(
&self,
error: ValueError,
opcode: OpCode,
pc: u32,
) -> LogicalFrameEndingReason {
if let ValueError::Resource(resource) = error {
return self.resource_trap(resource, opcode, pc);
}
self.trap(
Self::value_error_code(error),
opcode as u16,
format!("Invalid typed value: {error:?}"),
pc,
)
}
pub(super) fn check_signature_group(
&self,
function: usize,
results: bool,
values: &[Value],
) -> Result<(), (usize, ValueError)> {
let Some(image) = &self.validated_image else {
return Ok(());
};
let declaration =
image.registry().declarations().functions.get(function).ok_or((0, ValueError::Type))?;
let signature = &declaration.signature;
let count = if results { signature.results.len() } else { signature.parameters.len() };
let mut slot = 0;
for index in 0..count {
let ty = if results {
signature.results[index]
} else {
signature.parameters[index].type_id
};
let width = image.registry().type_layout(ty).unwrap().storage.slots as usize;
let end = slot + width;
let values = values.get(slot..end).ok_or((slot, ValueError::Type))?;
value_contract::validate(image.registry(), &self.heap, ty, values)
.map_err(|e| (slot, e))?;
slot = end;
}
if values.len() != slot {
return Err((slot, ValueError::Type));
}
Ok(())
}
}
@@ -0,0 +1,727 @@
use super::*;
use crate::{HostReturn, ValidatedProgramImage};
use prometeu_bytecode::load_limits::LoadBudget;
use prometeu_bytecode::registry::{
BuiltinId as B, FunctionDecl, ImplementationDecl, NamedType, Registry, RegistryDeclarations,
Signature, TypeDecl, TypeId, TypeKind,
};
use prometeu_bytecode::registry_codec::PbxModule;
use std::sync::Arc;
struct Native;
impl NativeInterface for Native {
fn syscall(
&mut self,
_id: u32,
_args: &[Value],
_ret: &mut HostReturn,
_ctx: &mut HostContext,
) -> Result<(), VmFault> {
Ok(())
}
}
fn op(code: &mut Vec<u8>, opcode: OpCode) {
code.extend_from_slice(&(opcode as u16).to_le_bytes());
}
fn arg(code: &mut Vec<u8>, opcode: OpCode, argument: u32) {
op(code, opcode);
code.extend_from_slice(&argument.to_le_bytes());
}
fn function(
offset: usize,
len: usize,
parameters: &[u32],
results: &[u32],
locals: u32,
max: u32,
) -> FunctionDecl {
FunctionDecl {
name: Some(format!("f{offset}")),
code_offset: offset as u32,
code_len: len as u32,
local_slots: locals,
max_stack_slots: max,
signature: Signature {
parameters: parameters
.iter()
.map(|&id| NamedType { type_id: TypeId(id), name: None })
.collect(),
results: results.iter().copied().map(TypeId).collect(),
},
}
}
fn image(code: &[u8], functions: Vec<FunctionDecl>) -> Arc<ValidatedProgramImage> {
let kind = |kind| TypeDecl { name: None, kind };
let mut types: Vec<_> =
[B::INT32, B::INT64, B::FLOAT, B::BOOL, B::STRING, B::VEC2, B::COLOR, B::PIXEL, B::DYNAMIC]
.into_iter()
.map(|id| kind(TypeKind::Builtin(id)))
.collect();
types.extend([
kind(TypeKind::Struct(vec![])),
kind(TypeKind::Struct(vec![])),
kind(TypeKind::Trait(vec![])),
kind(TypeKind::Trait(vec![])),
kind(TypeKind::Array(TypeId(0))),
kind(TypeKind::Array(TypeId(3))),
]);
let registry = Registry::resolve(
RegistryDeclarations {
types,
functions,
implementations: vec![
ImplementationDecl { owner: TypeId(9), trait_id: TypeId(11), methods: vec![] },
ImplementationDecl { owner: TypeId(9), trait_id: TypeId(12), methods: vec![] },
],
},
code.len(),
&mut LoadBudget::new(Default::default()),
)
.unwrap();
let bytes = PbxModule {
registry: &registry,
code,
constants: &[],
debug: None,
exports: &[],
syscalls: &[],
}
.serialize(&mut LoadBudget::new(Default::default()))
.unwrap();
ValidatedProgramImage::load(&bytes, &mut LoadBudget::new(Default::default()), NONE).unwrap()
}
fn run(vm: &mut VirtualMachine) -> LogicalFrameEndingReason {
vm.run_budget(1000, &mut Native, &mut HostContext::new(None)).unwrap().reason
}
fn dynamic_vm(
operation: OpCode,
target: u32,
input_slots: usize,
output_slots: usize,
limits: RuntimeLimits,
) -> VirtualMachine {
let mut code = vec![];
for slot in 0..input_slots {
arg(&mut code, OpCode::GetGlobal, slot as u32);
}
arg(&mut code, operation, target);
op(&mut code, OpCode::Halt);
let image = image(
&code,
vec![function(0, code.len(), &[], &[], 0, input_slots.max(output_slots) as u32)],
);
let mut vm = VirtualMachine::from_image(image, limits);
vm.prepare_boot_call().unwrap();
vm
}
fn load_globals_and_step(
vm: &mut VirtualMachine,
inputs: &[Value],
) -> Result<(), LogicalFrameEndingReason> {
vm.globals.extend_from_slice(inputs).unwrap();
for _ in inputs {
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
let before = vm.cycles;
let opcode = decode_next(vm.pc, &vm.program.rom).unwrap().opcode;
let result = vm.step(&mut Native, &mut HostContext::new(None));
let expected = match opcode {
OpCode::DynPack => 8,
OpCode::DynUnpack => 4,
OpCode::DynCanUnpack => 3,
OpCode::RefIsExact | OpCode::RefImplements | OpCode::RefCast => 4,
OpCode::RefToTrait => 5,
_ => panic!("not a typed conversion"),
};
assert_eq!(vm.cycles - before, expected);
result
}
#[test]
fn decoded_dynamic_scalar_string_reference_and_null_paths_have_exact_attempt_costs() {
for (ty, value) in [
(0, Value::Int32(17)),
(1, Value::Int64(17)),
(2, Value::Float(17.)),
(3, Value::Boolean(true)),
(4, Value::String(Arc::from("shared"))),
(4, Value::Null),
(9, Value::Null),
(13, Value::Null),
] {
let mut pack = dynamic_vm(OpCode::DynPack, ty, 1, 2, RuntimeLimits::default());
load_globals_and_step(&mut pack, &[value.clone()]).unwrap();
assert_eq!(pack.operand_stack.as_slice(), &[Value::Int64(ty.into()), value.clone()]);
let pair = pack.operand_stack.as_slice();
let mut unpack = dynamic_vm(OpCode::DynUnpack, ty, 2, 1, RuntimeLimits::default());
load_globals_and_step(&mut unpack, pair).unwrap();
assert_eq!(unpack.operand_stack.as_slice(), &[value]);
}
for (target, expected) in [(0, false), (4, true), (5, false), (8, true), (11, true)] {
let mut vm = dynamic_vm(OpCode::DynCanUnpack, target, 2, 1, RuntimeLimits::default());
load_globals_and_step(&mut vm, &[Value::Null, Value::Null]).unwrap();
assert_eq!(vm.operand_stack.as_slice(), &[Value::Boolean(expected)]);
assert_eq!(vm.heap.len(), 1); // Only the entry coroutine, no query allocation.
}
}
#[test]
fn decoded_dynamic_box_roundtrip_and_identity_never_nest_boxes() {
for (ty, values) in [
(5, vec![Value::Float(1.), Value::Float(2.)]),
(7, vec![Value::Int64(-1), Value::Int64(2), Value::Int64(u32::MAX as i64)]),
] {
let mut code = vec![];
for slot in 0..values.len() {
arg(&mut code, OpCode::GetGlobal, slot as u32);
}
arg(&mut code, OpCode::DynPack, ty);
arg(&mut code, OpCode::DynPack, 8);
arg(&mut code, OpCode::DynUnpack, 8);
arg(&mut code, OpCode::DynUnpack, ty);
op(&mut code, OpCode::Halt);
let image = image(&code, vec![function(0, code.len(), &[], &[], 0, 3)]);
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
load_globals_and_step(&mut vm, &values).unwrap();
let heap_len = vm.heap.len();
let boxed = vm.operand_stack[1].clone();
for _ in 0..2 {
let opcode = decode_next(vm.pc, &vm.program.rom).unwrap().opcode;
let before = vm.cycles;
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(vm.cycles - before, if opcode == OpCode::DynPack { 8 } else { 4 });
assert_eq!(vm.heap.len(), heap_len);
assert_eq!(vm.operand_stack[1], boxed);
}
let before = vm.cycles;
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(vm.cycles - before, 4);
assert_eq!(vm.operand_stack.as_slice(), values.as_slice());
assert_eq!(vm.heap.len(), 2);
}
}
#[test]
fn decoded_dynamic_malformed_pairs_trap_once_without_consuming_source() {
for operation in [OpCode::DynUnpack, OpCode::DynCanUnpack] {
for pair in [
vec![Value::Null, Value::Int32(3)],
vec![Value::Int64(0), Value::Boolean(true)],
vec![Value::Int64(8), Value::Null],
vec![Value::Int64(-1), Value::Null],
vec![Value::Int64(5), Value::HeapRef(HeapRef { index: 99, generation: 1 })],
] {
let mut vm = dynamic_vm(operation, 0, 2, 1, RuntimeLimits::default());
let result = load_globals_and_step(&mut vm, &pair);
assert!(
matches!(result,Err(LogicalFrameEndingReason::Trap(info)) if info.code==TRAP_TYPE || info.code==TRAP_INVALID_HANDLE)
);
assert_eq!(vm.operand_stack.as_slice(), pair.as_slice());
}
}
}
#[test]
fn decoded_box_quota_failure_leaves_unpacked_values_rooted_and_unchanged() {
let mut vm = dynamic_vm(
OpCode::DynPack,
5,
2,
2,
RuntimeLimits::default().lowered(RuntimeResource::HandleSlots, 1).unwrap(),
);
let input = [Value::Float(1.), Value::Float(2.)];
let guest_before = vm.budget.used(RuntimeResource::GuestBytes);
assert!(
matches!(load_globals_and_step(&mut vm,&input),Err(LogicalFrameEndingReason::Trap(info)) if info.code==TRAP_RESOURCE_LIMIT)
);
assert_eq!(vm.operand_stack.as_slice(), &input);
assert_eq!(vm.heap.len(), 1);
assert_eq!(vm.budget.used(RuntimeResource::GuestBytes), guest_before);
}
#[test]
fn decoded_dynamic_preserves_present_struct_array_and_trait_identity_in_one_session() {
for (ty, width) in [(9, 1), (13, 1), (11, 2)] {
let mut code = vec![];
for slot in 0..width {
arg(&mut code, OpCode::GetGlobal, slot);
}
arg(&mut code, OpCode::DynPack, ty);
arg(&mut code, OpCode::DynUnpack, ty);
op(&mut code, OpCode::Halt);
let image = image(&code, vec![function(0, code.len(), &[], &[], 0, 2)]);
let registry = image.registry().clone();
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
let reference = if ty == 13 {
vm.heap.allocate_typed_array(registry, TypeId(13), 4).unwrap()
} else {
vm.heap.allocate_typed_struct(registry, TypeId(9)).unwrap()
};
let values = if width == 2 {
vec![Value::HeapRef(reference), Value::Int64(0)]
} else {
vec![Value::HeapRef(reference)]
};
let before = vm.heap.len();
load_globals_and_step(&mut vm, &values).unwrap();
assert_eq!(vm.heap.len(), before + if width == 2 { 1 } else { 0 });
let cycles = vm.cycles;
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(vm.cycles - cycles, 4);
assert_eq!(vm.operand_stack.as_slice(), values.as_slice());
}
}
#[test]
fn dynamic_query_consumes_pair_and_reports_fixed_cost_through_budget_report() {
let mut vm = dynamic_vm(OpCode::DynCanUnpack, 0, 2, 1, RuntimeLimits::default());
vm.globals.extend_from_slice(&[Value::Int64(0), Value::Int32(2)]).unwrap();
for _ in 0..2 {
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
let report = vm.run_budget(3, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(report.cycles_used, 3);
assert_eq!(report.steps_executed, 1);
assert_eq!(report.reason, LogicalFrameEndingReason::BudgetExhausted);
assert_eq!(vm.operand_stack.as_slice(), &[Value::Boolean(true)]);
}
fn reference_vm(operation: OpCode, source: u32, target: u32) -> VirtualMachine {
let width = if matches!(source, 11 | 12) { 2 } else { 1 };
let mut code = vec![];
for slot in 0..width {
arg(&mut code, OpCode::GetGlobal, slot);
}
arg(&mut code, operation, source);
code.extend_from_slice(&target.to_le_bytes());
op(&mut code, OpCode::Halt);
let image = image(&code, vec![function(0, code.len(), &[], &[], 0, 2)]);
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
vm
}
#[test]
fn decoded_cross_trait_conversion_and_concrete_cast_preserve_receiver_without_wrappers() {
for (operation, target, expected) in [
(OpCode::RefToTrait, 12, 1),
(OpCode::RefCast, 9, 2),
(OpCode::RefIsExact, 9, 3),
(OpCode::RefImplements, 12, 3),
] {
let mut vm = reference_vm(operation, 11, target);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let receiver = vm.heap.allocate_typed_struct(registry, TypeId(9)).unwrap();
let before = vm.heap.len();
load_globals_and_step(&mut vm, &[Value::HeapRef(receiver), Value::Int64(0)]).unwrap();
let result = match expected {
1 => vec![Value::HeapRef(receiver), Value::Int64(1)],
2 => vec![Value::HeapRef(receiver)],
_ => vec![Value::Boolean(true)],
};
assert_eq!(vm.operand_stack.as_slice(), result.as_slice());
assert_eq!(vm.heap.len(), before);
}
}
#[test]
fn decoded_null_queries_are_false_and_null_conversions_are_absent() {
for (operation, target) in [
(OpCode::RefIsExact, 9),
(OpCode::RefImplements, 11),
(OpCode::RefToTrait, 11),
(OpCode::RefCast, 9),
] {
for (source, input) in [(9, vec![Value::Null]), (12, vec![Value::Null, Value::Null])] {
let mut vm = reference_vm(operation, source, target);
load_globals_and_step(&mut vm, &input).unwrap();
let expected = match operation {
OpCode::RefIsExact | OpCode::RefImplements => vec![Value::Boolean(false)],
OpCode::RefToTrait => vec![Value::Null, Value::Null],
_ => vec![Value::Null],
};
assert_eq!(vm.operand_stack.as_slice(), expected.as_slice());
assert_eq!(vm.heap.len(), 1);
}
}
}
#[test]
fn decoded_reference_malformed_source_never_becomes_false_or_null() {
for (operation, target) in [
(OpCode::RefIsExact, 9),
(OpCode::RefImplements, 11),
(OpCode::RefToTrait, 11),
(OpCode::RefCast, 9),
] {
for input in [
vec![Value::Null, Value::Int64(0)],
vec![Value::HeapRef(HeapRef { index: 99, generation: 1 }), Value::Int64(0)],
vec![Value::HeapRef(HeapRef::NULL), Value::Int64(0)],
] {
let mut vm = reference_vm(operation, 11, target);
assert!(
matches!(load_globals_and_step(&mut vm,&input),Err(LogicalFrameEndingReason::Trap(info)) if info.code==TRAP_TYPE || info.code==TRAP_INVALID_HANDLE)
);
assert_eq!(vm.operand_stack.as_slice(), input.as_slice());
}
let mut vm = reference_vm(operation, 11, target);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let receiver = vm.heap.allocate_typed_struct(registry, TypeId(9)).unwrap();
let input = [Value::HeapRef(receiver), Value::Int64(1)]; // Implementation 1 belongs to trait 12, not source trait 11.
assert!(
matches!(load_globals_and_step(&mut vm,&input),Err(LogicalFrameEndingReason::Trap(info)) if info.code==TRAP_TYPE)
);
assert_eq!(vm.operand_stack.as_slice(), &input);
}
}
#[test]
fn decoded_array_identity_is_invariant_and_arrays_have_no_trait_implementation() {
for (operation, target, expected) in [
(OpCode::RefIsExact, 13, true),
(OpCode::RefIsExact, 14, false),
(OpCode::RefImplements, 11, false),
] {
let mut vm = reference_vm(operation, 13, target);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let array = vm.heap.allocate_typed_array(registry, TypeId(13), 3).unwrap();
load_globals_and_step(&mut vm, &[Value::HeapRef(array)]).unwrap();
assert_eq!(vm.operand_stack.as_slice(), &[Value::Boolean(expected)]);
}
for (operation, target) in [(OpCode::RefToTrait, 11), (OpCode::RefCast, 14)] {
let mut vm = reference_vm(operation, 13, target);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let array = vm.heap.allocate_typed_array(registry, TypeId(13), 3).unwrap();
let input = [Value::HeapRef(array)];
assert!(
matches!(load_globals_and_step(&mut vm,&input),Err(LogicalFrameEndingReason::Trap(info)) if info.code==TRAP_TYPE)
);
assert_eq!(vm.operand_stack.as_slice(), &input);
}
}
#[test]
fn decoded_stale_handle_is_an_invalid_handle_even_when_target_type_differs() {
for (operation, target) in [
(OpCode::RefIsExact, 10),
(OpCode::RefImplements, 12),
(OpCode::RefToTrait, 12),
(OpCode::RefCast, 10),
] {
let mut vm = reference_vm(operation, 9, target);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let receiver = vm.heap.allocate_typed_struct(registry, TypeId(9)).unwrap();
vm.heap.mark_from_roots(vm.current_coro).unwrap();
vm.heap.sweep();
let input = [Value::HeapRef(receiver)];
assert!(
matches!(load_globals_and_step(&mut vm,&input),Err(LogicalFrameEndingReason::Trap(info)) if info.code==TRAP_INVALID_HANDLE)
);
assert_eq!(vm.operand_stack.as_slice(), &input);
}
}
#[test]
fn decoded_string_add_accounts_content_and_preserves_inputs_on_quota_refusal() {
let mut code = vec![];
arg(&mut code, OpCode::GetLocal, 0);
arg(&mut code, OpCode::GetLocal, 1);
op(&mut code, OpCode::Add);
op(&mut code, OpCode::Halt);
let image = image(&code, vec![function(0, code.len(), &[4, 0], &[], 0, 2)]);
for (ceiling, success) in [(4, false), (5, true)] {
let mut vm = VirtualMachine::from_image(
image.clone(),
RuntimeLimits::default().lowered(RuntimeResource::StringBytes, ceiling).unwrap(),
);
vm.prepare_call_with_args("0", &[Value::String(Arc::from("é")), Value::Int32(7)]).unwrap();
assert_eq!(vm.budget.used(RuntimeResource::StringBytes), 2);
let result = run(&mut vm);
if success {
assert_eq!(result, LogicalFrameEndingReason::Halted);
assert_eq!(vm.operand_stack.last(), Some(&Value::String(Arc::from("é7"))));
assert_eq!(vm.budget.used(RuntimeResource::StringBytes), 5);
assert_eq!(vm.budget.used(RuntimeResource::StringAllocations), 2);
} else {
assert!(
matches!(result,LogicalFrameEndingReason::Trap(info) if info.code==TRAP_RESOURCE_LIMIT && info.pc==12)
);
assert_eq!(vm.operand_stack.len(), 4);
assert_eq!(vm.operand_stack[2..], vm.operand_stack[..2]);
assert_eq!(vm.budget.used(RuntimeResource::StringBytes), 2);
assert_eq!(vm.budget.used(RuntimeResource::StringAllocations), 1);
}
assert_eq!(vm.budget.used(RuntimeResource::TemporaryBytes), 0);
}
}
#[test]
fn native_import_and_snapshot_retention_preserve_domain_across_session_close() {
let image = image(&[1, 0], vec![function(0, 2, &[], &[], 0, 1)]);
let mut vm = VirtualMachine::from_image(image.clone(), RuntimeLimits::default());
let external: Arc<str> = Arc::from("same");
vm.push(Value::String(external.clone())).unwrap();
let Value::String(first) = &vm.operand_stack[0] else { panic!() };
let first = first.clone();
assert!(!Arc::ptr_eq(&first, &external));
vm.push(Value::String(first.clone())).unwrap();
assert_eq!(vm.budget.used(RuntimeResource::StringBytes), 4);
let snapshot = vm.operand_stack_top(2);
assert_eq!(snapshot.retained_domains(), 1);
let budget = vm.budget.clone();
drop(first);
drop(vm);
assert_eq!(budget.used(RuntimeResource::StringBytes), 4);
let retained = snapshot.clone();
drop(snapshot);
assert_eq!(budget.used(RuntimeResource::StringAllocations), 1);
let mut destination = VirtualMachine::from_image(image, RuntimeLimits::default());
destination.push(retained[0].clone()).unwrap();
let (Value::String(source), Value::String(imported)) =
(&retained[0], &destination.operand_stack[0])
else {
panic!()
};
assert!(!Arc::ptr_eq(source, imported));
assert_eq!(destination.budget.used(RuntimeResource::StringBytes), 4);
drop(retained);
assert_eq!(budget.used(RuntimeResource::StringBytes), 0);
assert_eq!(budget.used(RuntimeResource::StringAllocations), 0);
}
#[test]
fn native_string_failures_cannot_publish_partial_results_even_if_handler_ignores_error() {
struct ReturnsString;
impl NativeInterface for ReturnsString {
fn syscall(
&mut self,
_id: u32,
_args: &[Value],
ret: &mut HostReturn,
_ctx: &mut HostContext,
) -> Result<(), VmFault> {
let _ = ret.push_string("abc");
Ok(())
}
}
let mut code = vec![];
arg(&mut code, OpCode::Syscall, prometeu_hal::syscalls::Syscall::SystemHasCart as u32);
let mut vm = VirtualMachine::with_runtime_limits(
code,
vec![],
RuntimeLimits::default().lowered(RuntimeResource::StringBytes, 2).unwrap(),
);
vm.program.functions = Arc::from(vec![prometeu_bytecode::FunctionMeta {
code_len: 6,
max_stack_slots: 1,
..Default::default()
}]);
vm.set_capabilities(prometeu_hal::syscalls::caps::SYSTEM);
vm.prepare_boot_call().unwrap();
let report = vm.run_budget(100, &mut ReturnsString, &mut HostContext::new(None)).unwrap();
// This synthetic native implementation tests the bounded writer, not the
// has-cart handler's ordinary Boolean semantic contract.
assert!(
matches!(report.reason,LogicalFrameEndingReason::Trap(info) if info.code==TRAP_RESOURCE_LIMIT && info.pc==0)
);
assert!(vm.operand_stack.is_empty());
assert_eq!(vm.budget.used(RuntimeResource::StringBytes), 0);
assert_eq!(vm.budget.used(RuntimeResource::StringAllocations), 0);
}
#[test]
fn typed_sessions_share_image_but_have_independent_execution_and_heap() {
let image = image(&[1, 0], vec![function(0, 2, &[], &[], 0, 0)]);
let mut first = VirtualMachine::from_image(image.clone(), RuntimeLimits::default());
let mut second = VirtualMachine::from_image(image.clone(), RuntimeLimits::default());
assert!(Arc::ptr_eq(&first.program.rom, &second.program.rom));
assert!(Arc::ptr_eq(&first.program.constant_pool, &second.program.constant_pool));
first.prepare_boot_call().unwrap();
second.prepare_boot_call().unwrap();
assert_eq!(run(&mut first), LogicalFrameEndingReason::Halted);
assert!(!second.halted);
assert_eq!(second.pc, 0);
drop(first);
drop(image);
assert_eq!(run(&mut second), LogicalFrameEndingReason::Halted);
}
#[test]
fn entry_rejects_bad_complete_groups_before_frame_or_heap_publication() {
let image = image(&[1, 0], vec![function(0, 2, &[5, 8], &[], 2, 0)]);
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
for args in [
vec![],
vec![Value::Float(1.), Value::Int32(2), Value::Null, Value::Null],
vec![Value::Float(1.), Value::Float(2.), Value::Int64(0), Value::Boolean(true)],
] {
assert!(matches!(
vm.prepare_call_with_args("0", &args),
Err(VmInitError::EntrypointArgumentsInvalid { trap_code: TRAP_TYPE, .. })
));
assert_eq!(vm.heap.len(), 0);
assert!(vm.call_stack.is_empty());
assert!(vm.operand_stack.is_empty());
assert_eq!(vm.budget.used(RuntimeResource::AuxiliaryBytes), 0);
}
vm.prepare_call_with_args("0", &[Value::Float(1.), Value::Float(2.), Value::Null, Value::Null])
.unwrap();
assert_eq!(&vm.operand_stack[4..], &[Value::Null, Value::Null]);
assert!(vm.pop().is_err()); // A generic pop cannot consume parameters/locals.
}
#[test]
fn unknown_at_call_is_checked_after_branch_merge_without_publishing_bad_frame() {
let mut code = vec![];
arg(&mut code, OpCode::GetLocal, 0);
let branch = code.len();
arg(&mut code, OpCode::JmpIfTrue, 0);
arg(&mut code, OpCode::PushI32, 17);
let jump = code.len();
arg(&mut code, OpCode::Jmp, 0);
let right = code.len();
op(&mut code, OpCode::PushBool);
code.push(1);
let join = code.len();
arg(&mut code, OpCode::Call, 1);
op(&mut code, OpCode::Halt);
let end = code.len();
op(&mut code, OpCode::Ret);
code[branch + 2..branch + 6].copy_from_slice(&(right as u32).to_le_bytes());
code[jump + 2..jump + 6].copy_from_slice(&(join as u32).to_le_bytes());
let image =
image(&code, vec![function(0, end, &[3], &[], 0, 1), function(end, 2, &[0], &[], 0, 0)]);
for (condition, success) in [(false, true), (true, false)] {
let mut vm = VirtualMachine::from_image(image.clone(), RuntimeLimits::default());
vm.prepare_call_with_args("0", &[Value::Boolean(condition)]).unwrap();
let result = run(&mut vm);
if success {
assert_eq!(result, LogicalFrameEndingReason::Halted);
} else {
assert!(
matches!(result,LogicalFrameEndingReason::Trap(info) if info.code==TRAP_TYPE && info.pc==join as u32 && info.opcode==OpCode::Call as u16)
);
assert_eq!(vm.call_stack.len(), 1);
assert_eq!(vm.operand_stack.last(), Some(&Value::Boolean(true)));
}
}
}
#[test]
fn ordered_multi_group_return_preserves_native_owners_and_receiver_identity() {
let mut code = vec![];
// vec2, trait, Dynamic and string occupy seven slots together.
for slot in 0..7 {
arg(&mut code, OpCode::GetLocal, slot);
}
op(&mut code, OpCode::Ret);
let image = image(&code, vec![function(0, code.len(), &[5, 11, 8, 4], &[5, 11, 8, 4], 2, 7)]);
let registry = image.registry().clone();
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
let receiver = vm.heap.allocate_typed_struct(registry, TypeId(9)).unwrap();
let text: Arc<str> = Arc::from("retained");
let args = [
Value::Float(1.),
Value::Float(2.),
Value::HeapRef(receiver),
Value::Int64(0),
Value::Int64(0),
Value::Int32(17),
Value::String(text.clone()),
];
vm.prepare_call_with_args("0", &args).unwrap();
let Value::String(imported) = &vm.operand_stack[6] else { panic!() };
let imported = imported.clone();
assert!(!Arc::ptr_eq(&imported, &text));
assert_eq!(run(&mut vm), LogicalFrameEndingReason::EndOfRom);
assert_eq!(vm.operand_stack.as_slice(), &args);
assert!(vm.call_stack.is_empty());
let Value::String(returned) = &vm.operand_stack[6] else { panic!() };
assert!(Arc::ptr_eq(returned, &imported));
}
#[test]
fn unknown_return_and_late_return_resource_failures_keep_current_frame_and_operands() {
let mut code = vec![];
arg(&mut code, OpCode::GetGlobal, 0);
op(&mut code, OpCode::Ret);
let image = image(&code, vec![function(0, code.len(), &[], &[0], 0, 1)]);
for (value, limits, expected) in [
(Value::Boolean(true), RuntimeLimits::default(), TRAP_TYPE),
(
Value::Int32(3),
RuntimeLimits::default().lowered(RuntimeResource::TemporaryBytes, 0).unwrap(),
TRAP_RESOURCE_LIMIT,
),
] {
let mut vm = VirtualMachine::from_image(image.clone(), limits);
vm.prepare_boot_call().unwrap();
vm.globals.push(value.clone()).unwrap();
let result = run(&mut vm);
assert!(
matches!(result,LogicalFrameEndingReason::Trap(info) if info.code==expected && info.pc==6)
);
assert_eq!(vm.call_stack.len(), 1);
assert_eq!(vm.operand_stack.as_slice(), &[value]);
}
}
#[test]
fn direct_call_returns_zero_or_one_result_and_initializes_generic_locals() {
for results in [&[][..], &[0][..]] {
let mut code = vec![];
arg(&mut code, OpCode::Call, 1);
op(&mut code, OpCode::Halt);
let end = code.len();
if !results.is_empty() {
arg(&mut code, OpCode::PushI32, 42);
}
op(&mut code, OpCode::Ret);
let image = image(
&code,
vec![
function(0, end, &[], &[], 0, 1),
function(end, code.len() - end, &[], results, 3, results.len() as u32),
],
);
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(vm.call_stack.len(), 2);
assert_eq!(vm.operand_stack.as_slice(), &[Value::Null, Value::Null, Value::Null]);
assert_eq!(run(&mut vm), LogicalFrameEndingReason::Halted);
assert_eq!(vm.operand_stack.len(), results.len());
if !results.is_empty() {
assert_eq!(vm.operand_stack[0], Value::Int32(42));
}
}
}
#[test]
fn call_growth_refusal_does_not_publish_frame_or_keep_provisional_capacity() {
let mut code = vec![];
arg(&mut code, OpCode::Call, 1);
op(&mut code, OpCode::Halt);
let end = code.len();
op(&mut code, OpCode::Ret);
let image =
image(&code, vec![function(0, end, &[], &[], 0, 0), function(end, 2, &[], &[], 100, 0)]);
let mut vm = VirtualMachine::from_image(
image,
RuntimeLimits::default().lowered(RuntimeResource::AuxiliaryBytes, 2048).unwrap(),
);
vm.prepare_boot_call().unwrap();
let before = vm.budget.used(RuntimeResource::AuxiliaryBytes);
assert!(
matches!(run(&mut vm),LogicalFrameEndingReason::Trap(info) if info.code==TRAP_RESOURCE_LIMIT && info.pc==0)
);
assert_eq!(vm.call_stack.len(), 1);
assert!(vm.operand_stack.is_empty());
assert_eq!(vm.budget.used(RuntimeResource::AuxiliaryBytes), before);
assert_eq!(vm.budget.used(RuntimeResource::TemporaryBytes), 0);
}
@@ -10,10 +10,25 @@ pub enum LoaderPatchError {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum VmInitError {
RegistryLoadFailed(prometeu_bytecode::load_limits::LoadFailure),
RuntimeResourceLimit(crate::resource_budget::ResourceFailure),
InvalidFormat,
UnsupportedFormat,
ImageLoadFailed(prometeu_bytecode::LoadError),
LoaderPatchFailed(LoaderPatchError),
EntrypointNotFound,
VerificationFailed(String),
EntrypointArgumentsInvalid { function: u32, slot: u32, trap_code: u32 },
VerificationFailed(crate::verifier::VerifierError),
}
impl From<crate::resource_budget::ResourceFailure> for VmInitError {
fn from(value: crate::resource_budget::ResourceFailure) -> Self {
Self::RuntimeResourceLimit(value)
}
}
impl From<prometeu_bytecode::load_limits::LoadFailure> for VmInitError {
fn from(value: prometeu_bytecode::load_limits::LoadFailure) -> Self {
Self::RegistryLoadFailed(value)
}
}
@@ -0,0 +1,155 @@
use prometeu_bytecode::registry::{BuiltinId, DynamicSlot, StringSlot};
use prometeu_bytecode::{TRAP_TYPE, Value, assembler::assemble};
use prometeu_hal::{color::Color, vm_fault::VmFault};
use prometeu_vm::{
AbiType, BuiltinScalarType, BuiltinValueError, HostContext, HostReturn,
LogicalFrameEndingReason, NativeInterface, VirtualMachine, lookup_builtin_type,
lookup_intrinsic, materialize_builtin_constant,
};
#[test]
fn all_nine_descriptors_match_registry_storage_and_canonical_defaults() {
for (name, id, size, alignment, width, nullable) in [
("color", 1, 4, 4, 1, false),
("vec2", 2, 16, 8, 2, false),
("pixel", 3, 24, 8, 3, false),
("Int32", 0x10, 4, 4, 1, false),
("Int64", 0x11, 8, 8, 1, false),
("Float", 0x12, 8, 8, 1, false),
("Bool", 0x13, 1, 1, 1, false),
("String", 0x14, size_of::<StringSlot>(), align_of::<StringSlot>(), 1, true),
("Dynamic", 0x15, size_of::<DynamicSlot>(), align_of::<DynamicSlot>(), 2, true),
] {
let meta = lookup_builtin_type(name, 1).unwrap();
assert_eq!(meta.id, id);
let layout = meta.storage_layout().unwrap();
assert_eq!(layout, BuiltinId(id).layout().unwrap());
assert_eq!(
(layout.size, layout.alignment, layout.slots, layout.nullable()),
(size, alignment, width, nullable)
);
assert_eq!(u32::from(meta.flat_slot_width), width);
assert_eq!(meta.flatten_layout().len(), width as usize);
meta.validate_flat_values(layout.default_values()).unwrap();
assert!(lookup_builtin_type(name, 2).is_none());
}
for alias in [
"Int",
"Number",
"Void",
"Null",
"int",
"float",
"bool",
"str",
"input.pad",
"input.touch",
"input.button",
] {
assert!(lookup_builtin_type(alias, 1).is_none(), "{alias}");
}
}
#[test]
fn primitive_carriers_are_exact_and_only_string_accepts_scalar_null() {
let cases = [
("Int32", Value::Int32(8)),
("Int64", Value::Int64(8)),
("Float", Value::Float(8.0)),
("Bool", Value::Boolean(true)),
("String", Value::String("eight".into())),
];
for (name, valid) in &cases {
let meta = lookup_builtin_type(name, 1).unwrap();
meta.validate_flat_values(std::slice::from_ref(valid)).unwrap();
for (other_name, invalid) in &cases {
if other_name != name {
assert!(
meta.validate_flat_values(std::slice::from_ref(invalid)).is_err(),
"{name} <- {other_name}"
);
}
}
assert_eq!(meta.validate_flat_values(&[Value::Null]).is_ok(), *name == "String");
}
let dynamic = lookup_builtin_type("Dynamic", 1).unwrap();
dynamic.validate_flat_values(&[Value::Null, Value::Null]).unwrap();
assert!(dynamic.validate_flat_values(&[Value::Null]).is_err());
assert_eq!(
dynamic.validate_flat_values(&[Value::Int32(0), Value::Int32(8)]),
Err(BuiltinValueError::RegistryRequired)
);
assert_eq!(
dynamic.validate_flat_values(&[Value::Null, Value::Int32(8)]),
Err(BuiltinValueError::RegistryRequired)
);
}
#[test]
fn color_range_and_aggregate_component_carriers_do_not_narrow() {
let color = lookup_builtin_type("color", 1).unwrap();
for raw in [0, 0x11223344, u32::MAX as i64] {
color.validate_flat_values(&[Value::Int64(raw)]).unwrap();
}
for value in [
Value::Int32(1),
Value::Int64(-1),
Value::Int64(u32::MAX as i64 + 1),
Value::Float(1.0),
Value::Null,
] {
assert!(color.validate_flat_values(&[value]).is_err());
}
let pixel = lookup_builtin_type("pixel", 1).unwrap();
let wide = [Value::Int64(i64::MIN), Value::Int64(i64::MAX), Value::Int64(u32::MAX as i64)];
pixel.validate_flat_values(&wide).unwrap();
assert!(
pixel.validate_flat_values(&[wide[2].clone(), wide[1].clone(), wide[0].clone()]).is_err()
);
for (field, slot) in [("x", 0), ("y", 1), ("color", 2)] {
assert_eq!(pixel.field(field).unwrap().start_slot, slot);
}
let vec2 = lookup_builtin_type("vec2", 1).unwrap();
vec2.validate_flat_values(&[Value::Float(1.25), Value::Float(-2.5)]).unwrap();
assert!(vec2.validate_flat_values(&[Value::Int64(1), Value::Float(2.0)]).is_err());
assert_eq!(
materialize_builtin_constant("color", "red", 1).unwrap().unwrap(),
vec![Value::Int64(Color::RED.raw() as i64)]
);
}
struct NoSyscalls;
impl NativeInterface for NoSyscalls {
fn syscall(
&mut self,
_: u32,
_: &[Value],
_: &mut HostReturn,
_: &mut HostContext,
) -> Result<(), VmFault> {
panic!("unexpected syscall")
}
}
#[test]
fn intrinsic_boundaries_reject_implicit_carrier_conversions_in_execution() {
for source in [
"PUSH_I32 1\nINTRINSIC 0x1100", // color.from_raw requires Int64
"PUSH_I32 1\nINTRINSIC 0x1106", // color.alpha requires the color carrier
"PUSH_I64 1\nPUSH_F64 f64:0x4000000000000000\nINTRINSIC 0x1001", // Float/Float required
"PUSH_I64 -1\nINTRINSIC 0x1106", // out-of-range color
] {
let mut vm = VirtualMachine::new(assemble(source).unwrap(), vec![]);
vm.prepare_call("0").expect("prepare entry call");
let report = vm.run_budget(100, &mut NoSyscalls, &mut HostContext::new(None)).unwrap();
assert!(
matches!(report.reason, LogicalFrameEndingReason::Trap(trap) if trap.code == TRAP_TYPE),
"{source}"
);
}
let hold = lookup_intrinsic("input.pad.up", "hold", 1).unwrap();
assert_eq!(hold.ret_layout, &[AbiType::Scalar(BuiltinScalarType::Int64)]);
assert!(hold.validate_result_values(&[Value::Int32(1)]).is_err());
let color = lookup_intrinsic("color", "red", 1).unwrap();
assert!(color.validate_result_values(&[Value::Int64(-1)]).is_err());
}
@@ -31,7 +31,7 @@ fn vm_rejects_legacy_input_syscall_id() {
let mut vm = VirtualMachine::new(rom, vec![]);
let mut native = NoopNative;
let mut ctx = HostContext::new(None);
vm.prepare_call("0");
vm.prepare_call("0").expect("prepare entry call");
vm.set_capabilities(prometeu_hal::syscalls::caps::ALL);
let report = vm.run_budget(100, &mut native, &mut ctx).expect("VM run failed");
@@ -40,7 +40,7 @@ fn scheduler_wake_and_ready_order_is_deterministic() {
let run_once = || -> Vec<LogicalFrameEndingReason> {
let mut vm = VirtualMachine::new(rom.clone(), vec![]);
vm.prepare_call("0");
vm.prepare_call("0").expect("prepare entry call");
let mut native = NoopNative;
let mut ctx = HostContext::new(None);
let mut reasons = Vec::new();
@@ -41,7 +41,7 @@ fn vm_executes_valid_program_in_slices() {
// Construct VM directly; assume input is already verified.
let mut vm = VirtualMachine::new(rom, vec![]);
vm.prepare_call("0");
vm.prepare_call("0").expect("prepare entry call");
let mut native = NoopNative;
let mut ctx = HostContext::new(None);
@@ -19,8 +19,8 @@ prometeu-system = { path = "../../console/prometeu-system" }
prometeu-drivers = { path = "../../console/prometeu-drivers" }
prometeu-hal = { path= "../../console/prometeu-hal" }
winit = "0.30.12"
pixels = "0.15.0"
pixels = "0.17.2"
cpal = "0.15.3"
ringbuf = "0.4.7"
serde_json = "1.0.149"
clap = { version = "4.5", features = ["derive"] }
clap = { version = "4.5", features = ["derive"] }
@@ -397,7 +397,7 @@ impl AudioMixer {
let vol_l = vol_f * (1.0 - pan_f).sqrt();
let vol_r = vol_f * pan_f.sqrt();
for frame in buffer.chunks_exact_mut(2) {
for frame in buffer.as_chunks_mut::<2>().0 {
let pos_int = voice.pos as usize;
let pos_fract = voice.pos - pos_int as f64;
@@ -12,3 +12,13 @@ prometeu-drivers = { path = "../../console/prometeu-drivers" }
prometeu-firmware = { path = "../../console/prometeu-firmware" }
prometeu-hal = { path = "../../console/prometeu-hal" }
prometeu-system = { path = "../../console/prometeu-system" }
prometeu-vm = { path = "../../console/prometeu-vm" }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
base64 = "0.22"
png = "0.17"
getrandom = "0.3"
[[bench]]
name = "temporal"
harness = false
@@ -0,0 +1,83 @@
use std::fs;
use std::hint::black_box;
use std::path::{Path, PathBuf};
use std::time::{Instant, SystemTime, UNIX_EPOCH};
use prometeu_bytecode::SourceSpan;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta};
use prometeu_host_headless::{AdvanceFramesStop, HeadlessHost};
const SAMPLE_FRAMES: u64 = 300;
const SAMPLE_COUNT: u32 = 10;
fn main() {
let cartridge = benchmark_cartridge();
let mut samples = Vec::with_capacity(SAMPLE_COUNT as usize);
for _ in 0..SAMPLE_COUNT {
let mut host = HeadlessHost::new();
host.boot(cartridge.to_string_lossy()).expect("boot benchmark cartridge");
let started = Instant::now();
let outcome =
black_box(host.advance_frames(SAMPLE_FRAMES)).expect("advance benchmark frames");
let elapsed = started.elapsed();
assert_eq!(outcome.completed, SAMPLE_FRAMES);
assert_eq!(outcome.stop, AdvanceFramesStop::Completed);
samples.push(elapsed.as_secs_f64());
}
samples.sort_by(f64::total_cmp);
let median_seconds = samples[samples.len() / 2];
let frames_per_second = SAMPLE_FRAMES as f64 / median_seconds;
println!(
"headless advance_frames: median={median_seconds:.6}s frames={SAMPLE_FRAMES} throughput={frames_per_second:.2} frames/s samples={SAMPLE_COUNT}"
);
fs::remove_dir_all(&cartridge).expect("remove benchmark cartridge");
}
fn benchmark_cartridge() -> PathBuf {
let directory = std::env::temp_dir().join(format!(
"prometeu-headless-benchmark-{}-{}",
std::process::id(),
SystemTime::now().duration_since(UNIX_EPOCH).expect("system clock").as_nanos()
));
fs::create_dir_all(&directory).expect("create benchmark cartridge");
let code = assemble("FRAME_SYNC\nRET\n").expect("assemble benchmark program");
let module = BytecodeModule {
version: 0,
const_pool: vec![],
functions: vec![FunctionMeta {
code_offset: 0,
code_len: code.len() as u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 1,
}],
code,
debug_info: Some(DebugInfo {
pc_to_span: vec![(0, SourceSpan { file_id: 1, start: 0, end: 10 })],
function_names: vec![(0, "main".into())],
}),
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
syscalls: vec![],
}
.serialize();
fs::write(directory.join("program.pbx"), module).expect("write benchmark program");
write_manifest(&directory);
directory
}
fn write_manifest(directory: &Path) {
fs::write(
directory.join("manifest.json"),
"{\n \"magic\": \"PMTU\",\n \"cartridge_version\": 1,\n \"app_id\": 90,\n \"title\": \"Headless Temporal Benchmark\",\n \"app_version\": \"0.1.0\",\n \"app_mode\": \"Game\",\n \"capabilities\": []\n}\n",
)
.expect("write benchmark manifest");
}
@@ -0,0 +1,406 @@
//! Versioned external tooling boundary; the host API itself remains synchronous.
mod wire;
pub use wire::Limits;
use crate::{AdvanceFrameOutcome, HeadlessHost};
use serde_json::{Value, json};
use std::io::{self, BufRead, Write};
use std::sync::{Arc, Mutex, mpsc};
use wire::{CAPABILITIES, Command, Request, WireError};
#[derive(Default)]
struct Control {
active: Option<String>,
advancing: bool,
canceled: bool,
}
enum Job {
Work(String, Command),
Stop(Option<String>),
ReadError(io::Error),
}
struct Output<W> {
writer: Mutex<W>,
session: String,
limit: usize,
}
impl<W: Write> Output<W> {
fn send(&self, value: Value) -> io::Result<()> {
let mut bytes = serde_json::to_vec(&value)?;
if bytes.len() > self.limit {
bytes = serde_json::to_vec(&json!({"type":"response","sessionId":self.session,
"requestId":value.get("requestId"),"error":{"code":"response_too_large",
"message":"response exceeds configured limit","details":{"maxResponseBytes":self.limit}}}))?;
}
if bytes.len() > self.limit {
return Err(io::Error::other("response limit cannot contain error"));
}
let mut writer = self.writer.lock().map_err(|_| io::Error::other("output poisoned"))?;
writer.write_all(&bytes)?;
writer.write_all(b"\n")?;
writer.flush()
}
fn reply(&self, id: Option<&str>, result: Result<Value, WireError>) -> io::Result<()> {
let mut value = json!({"type":"response","sessionId":self.session,"requestId":id});
match result {
Ok(r) => value["result"] = r,
Err(e) => value["error"] = serde_json::to_value(e)?,
}
self.send(value)
}
}
enum Line {
Data(Vec<u8>),
Oversized,
Truncated,
Eof,
}
/// Consume at most one line without ever accumulating more than the configured bound.
fn read_line(reader: &mut impl BufRead, limit: usize) -> io::Result<Line> {
let mut bytes = Vec::new();
let mut oversized = false;
loop {
let chunk = reader.fill_buf()?;
if chunk.is_empty() {
return Ok(if oversized {
Line::Oversized
} else if bytes.is_empty() {
Line::Eof
} else {
Line::Truncated
});
}
let newline = chunk.iter().position(|b| *b == b'\n');
let length = newline.unwrap_or(chunk.len());
if !oversized {
if length > limit.saturating_sub(bytes.len()) {
oversized = true;
bytes.clear();
} else {
bytes.extend_from_slice(&chunk[..length]);
}
}
reader.consume(length + usize::from(newline.is_some()));
if newline.is_some() {
if bytes.last() == Some(&b'\r') {
bytes.pop();
}
return Ok(if oversized { Line::Oversized } else { Line::Data(bytes) });
}
}
}
fn read_commands<R: BufRead, W: Write>(
mut input: R,
output: &Output<W>,
control: &Mutex<Control>,
sender: &mpsc::Sender<Job>,
limits: &Limits,
) -> io::Result<()> {
let mut initialized = false;
loop {
let bytes = match read_line(&mut input, limits.max_command_bytes)? {
Line::Eof => break,
Line::Truncated => {
output.reply(None, Err(WireError::new("invalid_request", "EOF before LF")))?;
break;
}
Line::Oversized => {
output.reply(
None,
Err(WireError::new("request_too_large", "command exceeds configured limit")),
)?;
continue;
}
Line::Data(bytes) => bytes,
};
let raw: Value = match serde_json::from_slice(&bytes) {
Ok(value) => value,
Err(error) => {
output.reply(None, Err(WireError::new("invalid_request", error.to_string())))?;
continue;
}
};
let id = raw
.get("requestId")
.and_then(Value::as_str)
.filter(|id| wire::valid_id(id))
.map(str::to_owned);
let request = serde_json::from_value::<Request>(raw)
.map_err(|e| WireError::new("invalid_request", e.to_string()))
.and_then(wire::parse);
let (id, command) = match request {
Ok(value) => value,
Err(error) => {
output.reply(id.as_deref(), Err(error))?;
continue;
}
};
if let Command::Shutdown = command {
let mut c = control.lock().unwrap();
c.canceled = true;
sender.send(Job::Stop(Some(id))).map_err(|_| io::Error::other("execution stopped"))?;
return Ok(());
}
if let Command::Initialize(params) = command {
let result = if initialized {
Err(WireError::new("already_initialized", "session already initialized"))
} else if params.protocol_version.major != 1 {
Err(WireError::new("incompatible_version", "protocol major must be 1"))
} else if params
.required_capabilities
.iter()
.any(|c| !CAPABILITIES.contains(&c.as_str()))
{
Err(WireError::new("unsupported_capability", "required capability unavailable"))
} else {
initialized = true;
Ok(json!({"protocolVersion":{"major":1,"minor":0},"capabilities":CAPABILITIES}))
};
output.reply(Some(&id), result)?;
continue;
}
if !initialized {
output.reply(Some(&id), Err(WireError::new("not_initialized", "initialize first")))?;
continue;
}
let mut c = control.lock().unwrap();
if let Command::Cancel(params) = command {
let result = if c.advancing && c.active.as_deref() == Some(&params.target_request_id) {
c.canceled = true;
Ok(json!({"targetRequestId":params.target_request_id,"requested":true}))
} else {
Err(WireError::new("not_cancelable", "no matching active advance"))
};
output.reply(Some(&id), result)?;
continue;
}
if c.active.is_some() {
output.reply(Some(&id), Err(WireError::new("busy", "a host operation is active")))?;
continue;
}
if let Command::Advance(params) = &command
&& params.frames > limits.max_frames
{
output.reply(
Some(&id),
Err(WireError::new("limit_exceeded", "frames exceeds maxFrames")),
)?;
continue;
}
c.active = Some(id.clone());
c.advancing = matches!(command, Command::Advance(_));
c.canceled = false;
sender.send(Job::Work(id, command)).map_err(|_| io::Error::other("execution stopped"))?;
}
let mut c = control.lock().unwrap();
c.canceled = true;
sender.send(Job::Stop(None)).map_err(|_| io::Error::other("execution stopped"))
}
fn execute<W: Write>(
host: &mut HeadlessHost,
command: Command,
id: &str,
output: &Output<W>,
control: &Mutex<Control>,
) -> io::Result<Result<Value, WireError>> {
Ok(match command {
Command::Boot(p) => {
host.boot(p.path).map(|()| wire::state(host.get_state())).map_err(wire::host_error)
}
Command::Reset => {
host.reset();
Ok(wire::state(host.get_state()))
}
Command::SetInput(p) => {
host.set_input(p.into());
Ok(json!({}))
}
Command::ClearInput => {
host.clear_input();
Ok(json!({}))
}
Command::GetState => Ok(wire::state(host.get_state())),
Command::GetFault => Ok(host.get_fault().as_ref().map(wire::fault).unwrap_or(Value::Null)),
Command::Capture => host.capture_frame().map_err(wire::host_error).and_then(wire::capture),
Command::Advance(p) => {
let mut result = json!({"requested":p.frames,"completed":0,"stop":"completed"});
for completed in 0..p.frames {
if control.lock().unwrap().canceled {
result["stop"] = json!("canceled");
break;
}
match host.advance_frame() {
Ok(AdvanceFrameOutcome::FrameCompleted { .. }) => {
result["completed"] = json!(completed + 1);
output.send(
json!({"type":"progress","sessionId":output.session,"requestId":id,
"requested":p.frames,"completed":completed + 1}),
)?;
}
Ok(AdvanceFrameOutcome::Faulted(report)) => {
result["stop"] = json!("faulted");
result["fault"] = wire::fault(&report);
break;
}
Ok(AdvanceFrameOutcome::Terminated) => {
result["stop"] = json!("terminated");
break;
}
Err(error) => {
result["stop"] = json!("host_error");
result["error"] = serde_json::to_value(wire::host_error(error))?;
break;
}
}
}
Ok(result)
}
_ => unreachable!("reader handles control commands"),
})
}
/// Serve one process session. The input reader stays responsive while the owner
/// executes a frame. On fatal output failure the process caller must exit; a
/// blocking OS stdin reader cannot be joined until that input is closed.
pub fn serve<R: BufRead + Send + 'static, W: Write + Send + 'static>(
input: R,
writer: W,
limits: Limits,
runtime_version: &str,
) -> io::Result<()> {
limits.validate()?;
let mut random = [0u8; 16];
getrandom::fill(&mut random).map_err(|e| io::Error::other(e.to_string()))?;
let session: String = random.iter().map(|v| format!("{v:02x}")).collect();
let output =
Arc::new(Output { writer: Mutex::new(writer), session, limit: limits.max_response_bytes });
output.send(
json!({"type":"hello","sessionId":output.session,"protocolVersion":{"major":1,"minor":0},
"runtimeVersion":runtime_version,"capabilities":CAPABILITIES,"limits":limits}),
)?;
let control = Arc::new(Mutex::new(Control::default()));
let (sender, receiver) = mpsc::channel();
let reader_output = output.clone();
let reader_control = control.clone();
let reader = std::thread::spawn(move || {
if let Err(error) = read_commands(input, &reader_output, &reader_control, &sender, &limits)
{
reader_control.lock().unwrap().canceled = true;
let _ = sender.send(Job::ReadError(error));
}
});
let mut host = HeadlessHost::new();
while let Ok(job) = receiver.recv() {
match job {
Job::Work(id, command) => {
let result = execute(&mut host, command, &id, &output, &control)?;
// Release authority under the same lock as response publication:
// a client reacting to this reply cannot race a stale busy flag.
let mut c = control.lock().unwrap();
output.reply(Some(&id), result)?;
c.active = None;
c.advancing = false;
}
Job::Stop(id) => {
drop(host);
if let Some(id) = id {
output.reply(Some(&id), Ok(json!({"closed":true})))?;
}
reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
return Ok(());
}
Job::ReadError(error) => return Err(error),
}
}
reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::{BufReader, Cursor};
#[test]
fn bounded_lines_accept_fragmentation_and_recover_after_oversize() {
let mut reader = BufReader::with_capacity(2, Cursor::new(b"12345\n123456\nok\r\n"));
assert!(matches!(read_line(&mut reader, 5).unwrap(), Line::Data(v) if v == b"12345"));
assert!(matches!(read_line(&mut reader, 5).unwrap(), Line::Oversized));
assert!(matches!(read_line(&mut reader, 5).unwrap(), Line::Data(v) if v == b"ok"));
assert!(matches!(read_line(&mut reader, 5).unwrap(), Line::Eof));
assert!(matches!(read_line(&mut Cursor::new(b"no LF"), 10).unwrap(), Line::Truncated));
}
#[test]
fn input_snapshot_is_replacement_and_rejects_unknown_fields() {
let input: wire::Input = serde_json::from_value(json!({"right":true})).unwrap();
let signals: prometeu_hal::InputSignals = input.into();
assert!(signals.right_signal);
assert!(!signals.left_signal);
assert_eq!(signals.x_pos, 0);
assert!(serde_json::from_value::<wire::Input>(json!({"rigth":true})).is_err());
}
#[test]
fn response_limit_counts_the_complete_envelope_and_keeps_correlation() {
let output =
Output { writer: Mutex::new(Vec::new()), session: "session".into(), limit: 4096 };
output.reply(Some("capture"), Ok(json!({"data":"x".repeat(4096)}))).unwrap();
let bytes = output.writer.into_inner().unwrap();
assert!(bytes.len() <= 4097);
let result: Value = serde_json::from_slice(&bytes).unwrap();
assert_eq!(result["requestId"], "capture");
assert_eq!(result["sessionId"], "session");
assert_eq!(result["error"]["code"], "response_too_large");
assert!(result.get("result").is_none());
}
#[test]
fn distributed_request_fixtures_are_accepted_by_the_actual_parser() {
let requests: Vec<Value> = serde_json::from_str(include_str!(
"../../../../../devtools/headless-protocol/requests.json"
))
.unwrap();
assert_eq!(requests.len(), 11);
for request in requests {
wire::parse(serde_json::from_value(request).unwrap()).unwrap();
}
}
#[test]
fn capture_preserves_independent_ids_and_excludes_padding_without_channel_loss() {
use base64::Engine as _;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::{FrameId, OwnedRgba8888Frame, RenderOwnership};
let frame = OwnedRgba8888Frame::new(
FrameId::new(91),
RenderOwnership::new(1, AppMode::Game, 41),
1,
2,
2,
vec![0x12345678, 0xffffffff, 0xabcdef01, 0xffffffff],
)
.unwrap();
let capture =
wire::capture(crate::CapturedFrame { logical_frame_index: 7, frame }).unwrap();
assert_eq!(capture["logicalFrameIndex"], 7);
assert_eq!(capture["frameId"], 91);
assert_eq!(capture["stridePixels"], 2);
let png = base64::engine::general_purpose::STANDARD
.decode(capture["data"].as_str().unwrap())
.unwrap();
let mut reader = png::Decoder::new(Cursor::new(png)).read_info().unwrap();
let mut bytes = vec![0; reader.output_buffer_size()];
let info = reader.next_frame(&mut bytes).unwrap();
assert_eq!((info.width, info.height), (1, 2));
assert_eq!(&bytes[..info.buffer_size()], &[0x12, 0x34, 0x56, 0x78, 0xab, 0xcd, 0xef, 0x01]);
}
}
@@ -0,0 +1,335 @@
use base64::{Engine as _, engine::general_purpose::STANDARD};
use prometeu_bytecode::Value as VmValue;
use prometeu_hal::InputSignals;
use prometeu_system::CrashReport;
use prometeu_vm::VmInitError;
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use std::io;
use crate::{CapturedFrame, HostError, HostExecutionStatus, HostState};
pub const CAPABILITIES: &[&str] = &[
"boot",
"reset",
"set_input",
"clear_input",
"advance",
"capture",
"get_state",
"get_fault",
"cancel",
"shutdown",
];
#[derive(Clone, Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Limits {
pub max_frames: u64,
pub max_command_bytes: usize,
pub max_response_bytes: usize,
pub handshake_timeout_ms: u64,
pub call_timeout_ms: u64,
pub shutdown_timeout_ms: u64,
}
impl Default for Limits {
fn default() -> Self {
Self {
max_frames: 600,
max_command_bytes: 64 * 1024,
max_response_bytes: 32 * 1024 * 1024,
handshake_timeout_ms: 5_000,
call_timeout_ms: 60_000,
shutdown_timeout_ms: 5_000,
}
}
}
impl Limits {
pub fn validate(&self) -> io::Result<()> {
if self.max_frames == 0
|| self.max_command_bytes < 4096
|| self.max_response_bytes < 4096
|| self.handshake_timeout_ms == 0
|| self.call_timeout_ms == 0
|| self.shutdown_timeout_ms == 0
{
return Err(io::Error::new(
io::ErrorKind::InvalidInput,
"limits must be positive and message bounds at least 4096 bytes",
));
}
Ok(())
}
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Request {
pub request_id: String,
pub command: String,
pub params: Value,
}
pub(super) fn valid_id(id: &str) -> bool {
!id.is_empty() && id.len() <= 128
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub(super) struct Version {
pub major: u32,
pub minor: u32,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Initialize {
pub protocol_version: Version,
pub required_capabilities: Vec<String>,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(super) struct Boot {
pub path: String,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(super) struct Advance {
pub frames: u64,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Cancel {
pub target_request_id: String,
}
#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Input {
up: bool,
down: bool,
left: bool,
right: bool,
a: bool,
b: bool,
x: bool,
y: bool,
l: bool,
r: bool,
start: bool,
select: bool,
touch: bool,
touch_x: i32,
touch_y: i32,
}
impl From<Input> for InputSignals {
fn from(s: Input) -> Self {
Self {
up_signal: s.up,
down_signal: s.down,
left_signal: s.left,
right_signal: s.right,
a_signal: s.a,
b_signal: s.b,
x_signal: s.x,
y_signal: s.y,
l_signal: s.l,
r_signal: s.r,
start_signal: s.start,
select_signal: s.select,
f_signal: s.touch,
x_pos: s.touch_x,
y_pos: s.touch_y,
}
}
}
#[derive(Debug)]
pub(super) enum Command {
Initialize(Initialize),
Boot(Boot),
Reset,
SetInput(Input),
ClearInput,
Advance(Advance),
Capture,
GetState,
GetFault,
Cancel(Cancel),
Shutdown,
}
fn params<T: serde::de::DeserializeOwned>(value: Value) -> Result<T, WireError> {
serde_json::from_value(value).map_err(|e| WireError::new("invalid_params", e.to_string()))
}
fn empty(value: &Value) -> Result<(), WireError> {
if value.as_object().is_some_and(|v| v.is_empty()) {
Ok(())
} else {
Err(WireError::new("invalid_params", "expected an empty params object"))
}
}
pub(super) fn parse(req: Request) -> Result<(String, Command), WireError> {
if !valid_id(&req.request_id) {
return Err(WireError::new("invalid_request", "requestId must contain 1..128 UTF-8 bytes"));
}
let command = match req.command.as_str() {
"initialize" => Command::Initialize(params(req.params)?),
"boot" => {
let p: Boot = params(req.params)?;
if p.path.trim().is_empty() {
return Err(WireError::new("invalid_params", "path is empty"));
}
Command::Boot(p)
}
"advance" => Command::Advance(params(req.params)?),
"set_input" => Command::SetInput(params(req.params)?),
"cancel" => {
let p: Cancel = params(req.params)?;
if !valid_id(&p.target_request_id) {
return Err(WireError::new("invalid_params", "invalid targetRequestId"));
}
Command::Cancel(p)
}
"reset" | "clear_input" | "capture" | "get_state" | "get_fault" | "shutdown" => {
empty(&req.params)?;
match req.command.as_str() {
"reset" => Command::Reset,
"clear_input" => Command::ClearInput,
"capture" => Command::Capture,
"get_state" => Command::GetState,
"get_fault" => Command::GetFault,
_ => Command::Shutdown,
}
}
_ => return Err(WireError::new("unknown_command", "unknown command")),
};
Ok((req.request_id, command))
}
#[derive(Debug, Serialize)]
pub(super) struct WireError {
pub code: &'static str,
pub message: String,
pub details: Value,
}
impl WireError {
pub fn new(code: &'static str, message: impl Into<String>) -> Self {
Self { code, message: message.into(), details: json!({}) }
}
}
pub(super) fn host_error(error: HostError) -> WireError {
let (code, details) = match &error {
HostError::AlreadyBooted => ("already_booted", json!({})),
HostError::BootFailed { reason, report } => {
("boot_failed", json!({"reason":reason,"fault":report.as_ref().map(fault)}))
}
HostError::InvalidState { operation, status } => {
("invalid_state", json!({"operation":operation,"status":status_name(*status)}))
}
HostError::FrameAdvanceWatchdogExpired { host_tick_limit } => {
("watchdog_expired", json!({"hostTickLimit":host_tick_limit}))
}
HostError::FrameNotPublished { previous } => {
("frame_not_published", json!({"previousFrameId":previous.map(|id| id.get())}))
}
HostError::NoFrameAvailable => ("no_frame_available", json!({})),
};
WireError { code, message: error.to_string(), details }
}
fn status_name(status: HostExecutionStatus) -> &'static str {
match status {
HostExecutionStatus::Running => "running",
HostExecutionStatus::Paused => "paused",
HostExecutionStatus::Terminated => "terminated",
HostExecutionStatus::Faulted => "faulted",
}
}
fn stack_value(value: &VmValue) -> Value {
match value {
VmValue::Int32(v) => json!({"kind":"int32","value":v}),
VmValue::Int64(v) => json!({"kind":"int64","value":v.to_string()}),
VmValue::Float(v) => json!({"kind":"float64","value":v.to_string()}),
VmValue::Boolean(v) => json!({"kind":"boolean","value":v}),
VmValue::String(v) => json!({"kind":"string","value":v.as_ref()}),
VmValue::HeapRef(v) => {
json!({"kind":"heap_ref","value":{"index":v.index,"generation":v.generation}})
}
VmValue::Null => json!({"kind":"null","value":null}),
}
}
pub(super) fn state(s: HostState) -> Value {
json!({"pc":s.pc,"stackTop":s.stack_top.iter().map(stack_value).collect::<Vec<_>>(),
"logicalFrameIndex":s.frame_index,"tickIndex":s.tick_index,"appId":s.app_id,
"status":status_name(s.status)})
}
pub(super) fn fault(report: &CrashReport) -> Value {
let mut result = json!({"kind":report.kind(),"pc":report.pc(),"summary":report.summary()});
match report {
CrashReport::VmTrap { trap } => {
result["trap"] = json!({"code":trap.code,"opcode":trap.opcode,
"message":trap.message,"pc":trap.pc,"span":trap.span});
}
CrashReport::VmPanic { message, .. } => {
result["message"] = json!(message);
}
CrashReport::VmInit { error } => {
let code = match error {
VmInitError::RegistryLoadFailed(_) => "registry_load_failed",
VmInitError::RuntimeResourceLimit(_) => "runtime_resource_limit",
VmInitError::InvalidFormat => "invalid_format",
VmInitError::UnsupportedFormat => "unsupported_format",
VmInitError::ImageLoadFailed(_) => "image_load_failed",
VmInitError::LoaderPatchFailed(_) => "loader_patch_failed",
VmInitError::EntrypointNotFound => "entrypoint_not_found",
VmInitError::EntrypointArgumentsInvalid { .. } => "entrypoint_arguments_invalid",
VmInitError::VerificationFailed(_) => "verification_failed",
};
result["initError"] = json!({"code":code,"message":format!("{error:?}")});
}
}
result
}
pub(super) fn capture(c: CapturedFrame) -> Result<Value, WireError> {
let frame = c.frame;
let width = u32::try_from(frame.width)
.map_err(|_| WireError::new("capture_failed", "width exceeds PNG limit"))?;
let height = u32::try_from(frame.height)
.map_err(|_| WireError::new("capture_failed", "height exceeds PNG limit"))?;
let mut rgba = Vec::new();
for y in 0..frame.height {
for pixel in frame.row(y).ok_or_else(|| WireError::new("capture_failed", "invalid row"))? {
rgba.extend_from_slice(&pixel.to_be_bytes());
}
}
let mut bytes = Vec::new();
{
let mut encoder = png::Encoder::new(&mut bytes, width, height);
encoder.set_color(png::ColorType::Rgba);
encoder.set_depth(png::BitDepth::Eight);
let mut writer =
encoder.write_header().map_err(|e| WireError::new("capture_failed", e.to_string()))?;
writer
.write_image_data(&rgba)
.map_err(|e| WireError::new("capture_failed", e.to_string()))?;
writer.finish().map_err(|e| WireError::new("capture_failed", e.to_string()))?;
}
Ok(json!({"mimeType":"image/png","encoding":"base64","data":STANDARD.encode(bytes),
"width":width,"height":height,"stridePixels":frame.stride_pixels,"pixelFormat":"RGBA8888",
"logicalFrameIndex":c.logical_frame_index,"frameId":frame.frame_id.get()}))
}
+83 -12
View File
@@ -1,7 +1,6 @@
use std::fmt;
use std::sync::Arc;
use prometeu_bytecode::Value;
use prometeu_drivers::MemoryBanks;
use prometeu_drivers::hardware::Hardware;
use prometeu_firmware::firmware_state::{AppCrashesStep, ResetStep};
@@ -14,7 +13,7 @@ use prometeu_hal::{
use prometeu_system::{CrashReport, LatestRenderFrameStore};
const BOOT_TICK_LIMIT: usize = 64;
const LOGICAL_FRAME_TICK_LIMIT: usize = 100_000;
const HOST_FRAME_ADVANCE_TICK_LIMIT: usize = 100_000;
/// One published logical frame plus the automation counter.
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -27,7 +26,7 @@ pub struct CapturedFrame {
#[derive(Debug, Clone)]
pub struct HostState {
pub pc: usize,
pub stack_top: Vec<Value>,
pub stack_top: prometeu_hal::ValueSnapshot,
pub frame_index: u64,
pub tick_index: u64,
pub app_id: u32,
@@ -68,7 +67,7 @@ pub enum HostError {
AlreadyBooted,
BootFailed { reason: String, report: Option<CrashReport> },
InvalidState { operation: &'static str, status: HostExecutionStatus },
LogicalFrameDidNotClose,
FrameAdvanceWatchdogExpired { host_tick_limit: usize },
FrameNotPublished { previous: Option<FrameId> },
NoFrameAvailable,
}
@@ -81,8 +80,11 @@ impl fmt::Display for HostError {
Self::InvalidState { operation, status } => {
write!(f, "{operation} is invalid while execution is {status:?}")
}
Self::LogicalFrameDidNotClose => {
write!(f, "logical frame did not reach FrameSync, end of ROM, or a fault")
Self::FrameAdvanceWatchdogExpired { host_tick_limit } => {
write!(
f,
"headless host frame-advance watchdog expired after {host_tick_limit} firmware ticks"
)
}
Self::FrameNotPublished { .. } => {
write!(f, "logical frame closed without its canonical published frame")
@@ -217,19 +219,20 @@ impl HeadlessHost {
self.firmware.os.vm().set_paused(false);
self.firmware.os.vm().request_debug_step();
for _ in 0..LOGICAL_FRAME_TICK_LIMIT {
for _ in 0..HOST_FRAME_ADVANCE_TICK_LIMIT {
self.tick_once();
if let Some(report) = self.get_fault() {
self.finish_frame_step();
self.finish_frame_advance();
return Ok(AdvanceFrameOutcome::Faulted(report));
}
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
self.finish_frame_advance();
return Ok(AdvanceFrameOutcome::Terminated);
}
let logical_frame_index = self.firmware.os.vm().logical_frame_index();
if logical_frame_index > start {
self.finish_frame_step();
self.finish_frame_advance();
let frame = self
.platform
.store
@@ -247,8 +250,10 @@ impl HeadlessHost {
}
}
self.finish_frame_step();
Err(HostError::LogicalFrameDidNotClose)
self.finish_frame_advance();
Err(HostError::FrameAdvanceWatchdogExpired {
host_tick_limit: HOST_FRAME_ADVANCE_TICK_LIMIT,
})
}
pub fn advance_frames(&mut self, count: u64) -> Result<AdvanceFramesOutcome, HostError> {
@@ -349,7 +354,7 @@ impl HeadlessHost {
}
}
fn finish_frame_step(&mut self) {
fn finish_frame_advance(&mut self) {
self.firmware.os.vm().set_paused(true);
self.firmware.os.vm().clear_debug_step_request();
}
@@ -423,3 +428,69 @@ impl RuntimePlatform for HeadlessPlatform {
self.hardware.telemetry()
}
}
#[cfg(test)]
mod tests {
use std::fs;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, Export, FunctionMeta};
use super::{AdvanceFrameOutcome, HeadlessHost};
#[test]
fn termination_during_frame_advance_clears_host_step_control() {
let cartridge = non_closing_cartridge();
let mut host = HeadlessHost::new();
host.boot(cartridge.to_string_lossy()).expect("boot non-closing cartridge");
host.firmware.request_home_from_host();
assert_eq!(
host.advance_frame().expect("lifecycle termination"),
AdvanceFrameOutcome::Terminated
);
assert!(host.firmware.os.vm().paused());
assert!(!host.firmware.os.vm().debug_step_requested());
fs::remove_dir_all(cartridge).expect("remove test cartridge");
}
fn non_closing_cartridge() -> std::path::PathBuf {
let directory = std::env::temp_dir().join(format!(
"prometeu-headless-termination-cleanup-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.expect("system clock")
.as_nanos()
));
fs::create_dir_all(&directory).expect("create test cartridge");
let code = assemble("JMP 0\n").expect("assemble non-closing program");
let module = BytecodeModule {
version: 0,
const_pool: vec![],
functions: vec![FunctionMeta {
code_offset: 0,
code_len: code.len() as u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 1,
}],
code,
debug_info: None,
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
syscalls: vec![],
}
.serialize();
fs::write(directory.join("program.pbx"), module).expect("write test program");
fs::write(
directory.join("manifest.json"),
"{\n \"magic\": \"PMTU\",\n \"cartridge_version\": 1,\n \"app_id\": 91,\n \"title\": \"Termination Cleanup\",\n \"app_version\": \"0.1.0\",\n \"app_mode\": \"Game\",\n \"capabilities\": []\n}\n",
)
.expect("write test manifest");
directory
}
}
@@ -6,6 +6,7 @@
//! The desktop host's `stepFrame` command still advances on the 60 Hz winit loop.
//! That pacing stays in `prometeu-host-desktop-winit` until a later protocol agenda.
pub mod automation;
mod host;
pub use host::{
@@ -1,6 +1,5 @@
use std::fs;
use std::path::Path;
use std::time::{Duration, Instant};
use prometeu_bytecode::SourceSpan;
use prometeu_bytecode::assembler::assemble;
@@ -107,7 +106,10 @@ fn outer_frame_limit_is_a_host_error_and_finishes_paused() {
let mut host = HeadlessHost::new();
host.boot(&dir).expect("boot non-closing cartridge");
assert_eq!(host.advance_frame(), Err(HostError::LogicalFrameDidNotClose));
assert_eq!(
host.advance_frame(),
Err(HostError::FrameAdvanceWatchdogExpired { host_tick_limit: 100_000 })
);
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
assert!(host.get_fault().is_none());
}
@@ -350,11 +352,9 @@ fn end_of_rom_completes_a_logical_frame() {
}
#[test]
fn three_hundred_frames_finish_without_refresh_sleep() {
fn three_hundred_frames_complete_without_realtime_pacing() {
let mut host = boot_color();
let started = Instant::now();
assert_completed(host.advance_frames(300).expect("fast frames"), 300);
assert!(started.elapsed() < Duration::from_secs(2));
}
#[test]
@@ -481,9 +481,7 @@ fn color_program() -> Vec<u8> {
PUSH_I32 0\n\
HOSTCALL 1\n\
POP_N 1\n\
INTRINSIC 0x2000\n\
INTRINSIC 0x2013\n\
INTRINSIC 0x2032\n"));
INTRINSIC 0x210E\n"));
let jump_to_blue = rom.len() + 2;
rom.extend(asm("JMP_IF_FALSE 0"));
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
@@ -495,17 +493,17 @@ fn color_program() -> Vec<u8> {
fn input_edge_program() -> Vec<u8> {
let mut rom = Vec::new();
let pressed_jump = emit_right_predicate(&mut rom, 0x2030);
let pressed_jump = emit_right_predicate(&mut rom, 0x210C);
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
let released_at = rom.len() as u32;
rom[pressed_jump..pressed_jump + 4].copy_from_slice(&released_at.to_le_bytes());
let released_jump = emit_right_predicate(&mut rom, 0x2031);
let released_jump = emit_right_predicate(&mut rom, 0x210D);
rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
let down_at = rom.len() as u32;
rom[released_jump..released_jump + 4].copy_from_slice(&down_at.to_le_bytes());
let down_jump = emit_right_predicate(&mut rom, 0x2032);
let down_jump = emit_right_predicate(&mut rom, 0x210E);
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
let idle_at = rom.len() as u32;
rom[down_jump..down_jump + 4].copy_from_slice(&idle_at.to_le_bytes());
@@ -515,7 +513,7 @@ fn input_edge_program() -> Vec<u8> {
}
fn emit_right_predicate(rom: &mut Vec<u8>, predicate: u32) -> usize {
rom.extend(asm(&format!("INTRINSIC 0x2000\nINTRINSIC 0x2013\nINTRINSIC {predicate:#x}\n")));
rom.extend(asm(&format!("INTRINSIC {predicate:#x}\n")));
let target = rom.len() + 2;
rom.extend(asm("JMP_IF_FALSE 0\n"));
target
@@ -523,17 +521,17 @@ fn emit_right_predicate(rom: &mut Vec<u8>, predicate: u32) -> usize {
fn touch_edge_program() -> Vec<u8> {
let mut rom = Vec::new();
let pressed_jump = emit_touch_predicate(&mut rom, 0x2030);
let pressed_jump = emit_touch_predicate(&mut rom, 0x2130);
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
let released_at = rom.len() as u32;
rom[pressed_jump..pressed_jump + 4].copy_from_slice(&released_at.to_le_bytes());
let released_jump = emit_touch_predicate(&mut rom, 0x2031);
let released_jump = emit_touch_predicate(&mut rom, 0x2131);
rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
let down_at = rom.len() as u32;
rom[released_jump..released_jump + 4].copy_from_slice(&down_at.to_le_bytes());
let down_jump = emit_touch_predicate(&mut rom, 0x2032);
let down_jump = emit_touch_predicate(&mut rom, 0x2132);
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
let idle_at = rom.len() as u32;
rom[down_jump..down_jump + 4].copy_from_slice(&idle_at.to_le_bytes());
@@ -544,9 +542,9 @@ fn touch_edge_program() -> Vec<u8> {
fn emit_touch_predicate(rom: &mut Vec<u8>, predicate: u32) -> usize {
rom.extend(asm(&format!(
"INTRINSIC 0x2001\nINTRINSIC 0x2020\nINTRINSIC {predicate:#x}\n\
INTRINSIC 0x2001\nINTRINSIC 0x2021\nPUSH_I64 123\nEQ\nAND\n\
INTRINSIC 0x2001\nINTRINSIC 0x2022\nPUSH_I64 45\nEQ\nAND\n"
"INTRINSIC {predicate:#x}\n\
INTRINSIC 0x2134\nPUSH_I64 123\nEQ\nAND\n\
INTRINSIC 0x2135\nPUSH_I64 45\nEQ\nAND\n"
)));
let target = rom.len() + 2;
rom.extend(asm("JMP_IF_FALSE 0\n"));
@@ -0,0 +1,231 @@
//! Independent catalogue and execution oracles for the fixed input ABI.
use prometeu_bytecode::{TRAP_INVALID_INTRINSIC, TRAP_UNAVAILABLE, Value, assembler::assemble};
use prometeu_drivers::TestPlatform;
use prometeu_hal::{InputSignals, RuntimePlatform, vm_fault::VmFault};
use prometeu_vm::{
AbiType, BuiltinScalarType, HostContext, HostReturn, IntrinsicExecutionError,
LogicalFrameEndingReason, NativeInterface, VirtualMachine, lookup_builtin_type,
lookup_intrinsic, lookup_intrinsic_by_id,
};
const BUTTONS: [(&str, u32); 13] = [
("input.pad.up", 0x2100),
("input.pad.down", 0x2104),
("input.pad.left", 0x2108),
("input.pad.right", 0x210C),
("input.pad.a", 0x2110),
("input.pad.b", 0x2114),
("input.pad.x", 0x2118),
("input.pad.y", 0x211C),
("input.pad.l", 0x2120),
("input.pad.r", 0x2124),
("input.pad.start", 0x2128),
("input.pad.select", 0x212C),
("input.touch.button", 0x2130),
];
struct NoSyscalls;
impl NativeInterface for NoSyscalls {
fn syscall(
&mut self,
_: u32,
_: &[Value],
_: &mut HostReturn,
_: &mut HostContext,
) -> Result<(), VmFault> {
panic!("input must not invoke a syscall")
}
}
#[test]
fn catalogue_has_exact_names_ids_signatures_and_no_endpoint_aliases() {
let mut ids = std::collections::BTreeSet::new();
for (owner, base) in BUTTONS {
for (offset, property) in ["pressed", "released", "down", "hold"].into_iter().enumerate() {
let meta = lookup_intrinsic(owner, property, 1).unwrap();
assert_eq!(meta.id, base + offset as u32);
assert!(ids.insert(meta.id));
assert_eq!(lookup_intrinsic_by_id(meta.id).unwrap().key(), meta.key());
assert!(meta.arg_layout.is_empty());
assert_eq!(
meta.ret_layout,
&[AbiType::Scalar(if offset == 3 {
BuiltinScalarType::Int64
} else {
BuiltinScalarType::Bool
})]
);
assert!(meta.deterministic);
assert!(!meta.may_allocate);
assert!(lookup_intrinsic(owner, property, 2).is_none());
}
}
for (name, id) in [("x", 0x2134), ("y", 0x2135)] {
let meta = lookup_intrinsic("input.touch", name, 1).unwrap();
assert_eq!(meta.id, id);
assert!(ids.insert(id));
assert!(meta.arg_layout.is_empty());
assert_eq!(meta.ret_layout, &[AbiType::Scalar(BuiltinScalarType::Int64)]);
}
assert_eq!(ids.len(), 54);
assert!(lookup_intrinsic_by_id(0x2136).is_none());
for id in [0x2000, 0x2001]
.into_iter()
.chain(0x2010..=0x201B)
.chain(0x2020..=0x2022)
.chain(0x2030..=0x2033)
{
assert!(lookup_intrinsic_by_id(id).is_none(), "removed ID {id:#x}");
}
for name in ["input.pad", "input.touch", "input.button", "input.touch.button"] {
assert!(lookup_builtin_type(name, 1).is_none());
}
for (owner, name) in [
("input", "pad"),
("input", "touch"),
("input.pad", "up"),
("input.touch", "button"),
("input.button", "down"),
] {
assert!(lookup_intrinsic(owner, name, 1).is_none());
}
let csv = include_str!("../../../../docs/vm-arch/INTRINSICS.csv");
let mut documented = std::collections::BTreeSet::new();
for row in csv.lines().skip(1) {
let columns: Vec<_> = row.split(',').collect();
if !columns[2].starts_with("input.") {
continue;
}
let id = columns[1].parse::<u32>().unwrap();
let meta = lookup_intrinsic(columns[4], columns[5], 1).unwrap();
assert_eq!(id, meta.id);
assert_eq!(columns[2], format!("{}.{}", meta.owner, meta.name));
assert_eq!(&columns[6..9], &["0", "1", ""]);
assert_eq!(
columns[9],
if meta.name == "hold" || meta.owner == "input.touch" { "Int64" } else { "Bool" }
);
assert!(documented.insert(id));
}
assert_eq!(ids, documented);
}
fn set_frame(platform: &mut TestPlatform, active: Option<usize>) {
let mut signals = InputSignals { x_pos: -123, y_pos: i32::MAX, ..Default::default() };
if let Some(index) = active {
let fields = [
&mut signals.up_signal,
&mut signals.down_signal,
&mut signals.left_signal,
&mut signals.right_signal,
&mut signals.a_signal,
&mut signals.b_signal,
&mut signals.x_signal,
&mut signals.y_signal,
&mut signals.l_signal,
&mut signals.r_signal,
&mut signals.start_signal,
&mut signals.select_signal,
&mut signals.f_signal,
];
*fields[index] = true;
}
platform.input_mut().pad_mut().begin_frame(&signals);
platform.input_mut().touch_mut().begin_frame(&signals);
}
fn query_all(platform: &mut TestPlatform) -> Vec<Value> {
let mut ctx = HostContext::new(Some(platform));
(0x2100..=0x2135)
.map(|id| {
let meta = lookup_intrinsic_by_id(id).unwrap();
let result = (meta.implementation)(&[], &mut ctx).unwrap();
meta.validate_result_values(&result).unwrap();
result.into_iter().next().unwrap()
})
.collect()
}
#[test]
fn every_button_uses_its_own_snapshot_and_queries_do_not_advance_frames() {
let mut platform = TestPlatform::new();
for active in 0..13 {
set_frame(&mut platform, None);
for (pressed, released, down, hold) in [
(true, false, true, 1),
(false, false, true, 2),
(false, true, false, 0),
(false, false, false, 0),
] {
set_frame(&mut platform, down.then_some(active));
let result = query_all(&mut platform);
assert_eq!(query_all(&mut platform), result, "same-frame queries changed state");
for index in 0..13 {
let values = if index == active {
(pressed, released, down, hold)
} else {
(false, false, false, 0)
};
assert_eq!(
&result[index * 4..index * 4 + 4],
&[
Value::Boolean(values.0),
Value::Boolean(values.1),
Value::Boolean(values.2),
Value::Int64(values.3),
],
"button {index}, active {active}"
);
}
assert_eq!(&result[52..], &[Value::Int64(-123), Value::Int64(i32::MAX as i64)]);
}
}
}
#[test]
fn vm_queries_charge_one_cycle_each_and_allocate_no_guest_objects() {
let mut source = String::new();
for id in 0x2100..=0x2135 {
source.push_str(&format!("INTRINSIC {id}\n"));
}
let mut vm = VirtualMachine::new(assemble(&source).unwrap(), vec![]);
vm.prepare_call("0").expect("prepare entry call");
let objects = vm.heap().len();
let mut platform = TestPlatform::new();
set_frame(&mut platform, Some(3));
let expected = query_all(&mut platform);
let report =
vm.run_budget(54, &mut NoSyscalls, &mut HostContext::new(Some(&mut platform))).unwrap();
assert_eq!(report.cycles_used, 54);
assert_eq!(report.steps_executed, 54);
assert_eq!(vm.heap().len(), objects);
// Inspection returns the topmost slot first.
assert_eq!(vm.operand_stack_top(54), expected.into_iter().rev().collect::<Vec<_>>());
}
#[test]
fn every_known_query_faults_when_unavailable_and_rejects_arguments() {
for id in 0x2100..=0x2135 {
let meta = lookup_intrinsic_by_id(id).unwrap();
let mut ctx = HostContext::new(None);
assert_eq!(
(meta.implementation)(&[], &mut ctx),
Err(IntrinsicExecutionError::HardwareUnavailable)
);
assert_eq!(
(meta.implementation)(&[Value::Int64(0)], &mut ctx),
Err(IntrinsicExecutionError::ArityMismatch { expected: 0, got: 1 })
);
let mut vm = VirtualMachine::new(assemble(&format!("INTRINSIC {id}\n")).unwrap(), vec![]);
vm.prepare_call("0").expect("prepare entry call");
let report = vm.run_budget(10, &mut NoSyscalls, &mut ctx).unwrap();
assert!(matches!(report.reason, LogicalFrameEndingReason::Trap(trap)
if trap.code == TRAP_UNAVAILABLE && trap.pc == 0));
assert!(vm.operand_stack_top(1).is_empty());
}
let mut vm = VirtualMachine::new(assemble("INTRINSIC 0x2136\n").unwrap(), vec![]);
vm.prepare_call("0").expect("prepare entry call");
let report = vm.run_budget(10, &mut NoSyscalls, &mut HostContext::new(None)).unwrap();
assert!(matches!(report.reason, LogicalFrameEndingReason::Trap(trap)
if trap.code == TRAP_INVALID_INTRINSIC));
}
+15
View File
@@ -13,11 +13,26 @@ path = "src/main.rs"
name = "prometeu-runtime"
path = "src/bin/prometeu-runtime.rs"
[[bin]]
name = "prometeu-headless"
path = "src/bin/prometeu-headless.rs"
[package.metadata.dist]
dist = true
include = [
"../../../devtools/headless-protocol",
"../../../docs/specs/runtime/11a-headless-automation-protocol.md",
]
[dependencies]
clap = { version = "4.5", features = ["derive"] }
prometeu-host-desktop-winit = { path = "../../host/prometeu-host-desktop-winit" }
prometeu-host-headless = { path = "../../host/prometeu-host-headless" }
[dev-dependencies]
jsonschema = { version = "0.33", default-features = false }
serde_json = "1"
prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
prometeu-hal = { path = "../../console/prometeu-hal" }
base64 = "0.22"
png = "0.17"
@@ -0,0 +1,17 @@
use clap::Parser;
use prometeu_cli::{HeadlessArgs, run_headless};
#[derive(Parser)]
#[command(
name = "prometeu-headless",
version,
about = "Deterministic headless JSONL automation host"
)]
struct Cli {
#[command(flatten)]
options: HeadlessArgs,
}
fn main() -> std::io::Result<()> {
run_headless(Cli::parse().options)
}
+62
View File
@@ -0,0 +1,62 @@
//! Shared CLI options for the dispatcher and its headless executable.
use clap::Args;
use prometeu_host_headless::automation::Limits;
#[derive(Args, Debug)]
pub struct HeadlessArgs {
/// Use the versioned JSONL stdin/stdout protocol (required).
#[arg(long, required = true)]
pub stdio: bool,
#[arg(long, default_value_t = 600)]
pub max_frames: u64,
#[arg(long, default_value_t = 65536)]
pub max_command_bytes: usize,
#[arg(long, default_value_t = 33554432)]
pub max_response_bytes: usize,
#[arg(long, default_value_t = 5000)]
pub handshake_timeout_ms: u64,
#[arg(long, default_value_t = 60000)]
pub call_timeout_ms: u64,
#[arg(long, default_value_t = 5000)]
pub shutdown_timeout_ms: u64,
}
impl HeadlessArgs {
pub fn limits(&self) -> Limits {
Limits {
max_frames: self.max_frames,
max_command_bytes: self.max_command_bytes,
max_response_bytes: self.max_response_bytes,
handshake_timeout_ms: self.handshake_timeout_ms,
call_timeout_ms: self.call_timeout_ms,
shutdown_timeout_ms: self.shutdown_timeout_ms,
}
}
pub fn forwarded_args(&self) -> Vec<String> {
vec![
"--stdio".into(),
"--max-frames".into(),
self.max_frames.to_string(),
"--max-command-bytes".into(),
self.max_command_bytes.to_string(),
"--max-response-bytes".into(),
self.max_response_bytes.to_string(),
"--handshake-timeout-ms".into(),
self.handshake_timeout_ms.to_string(),
"--call-timeout-ms".into(),
self.call_timeout_ms.to_string(),
"--shutdown-timeout-ms".into(),
self.shutdown_timeout_ms.to_string(),
]
}
}
pub fn run_headless(args: HeadlessArgs) -> std::io::Result<()> {
prometeu_host_headless::automation::serve(
std::io::BufReader::new(std::io::stdin()),
std::io::stdout(),
args.limits(),
env!("CARGO_PKG_VERSION"),
)
}
+8
View File
@@ -19,6 +19,8 @@ struct Cli {
#[derive(Subcommand)]
enum Commands {
/// Starts the versioned headless automation process (no native window).
Headless(prometeu_cli::HeadlessArgs),
/// Executes a cartridge using the available runtime.
Run {
/// Path to the cartridge (directory or .pmc file).
@@ -65,6 +67,11 @@ fn main() {
};
match cli.command {
Some(Commands::Headless(options)) => {
let args = options.forwarded_args();
let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
dispatch(&exe_dir, "prometeu-headless", &borrowed);
}
Some(Commands::Run { cart }) => {
dispatch(&exe_dir, "prometeu-runtime", &["--run", &cart]);
}
@@ -99,6 +106,7 @@ fn dispatch(exe_dir: &Path, bin_name: &str, args: &[&str]) {
"prometeu: command '{}' is not yet available in this distribution on {}",
match bin_name {
"prometeu-runtime" => "run/debug",
"prometeu-headless" => "headless",
"prometeuc" => "build/verify c",
"prometeup" => "pack/verify p",
_ => bin_name,
@@ -0,0 +1,615 @@
use base64::{Engine as _, engine::general_purpose::STANDARD};
use prometeu_bytecode::SourceSpan;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl};
use prometeu_host_headless::{AdvanceFramesStop, HeadlessHost};
use serde_json::{Value, json};
use std::collections::HashMap;
use std::fs;
use std::io::{BufRead, BufReader, Write};
use std::path::{Path, PathBuf};
use std::process::{Child, ChildStdin, Command, Stdio};
use std::sync::{
atomic::{AtomicU64, Ordering},
mpsc,
};
use std::time::{Duration, Instant};
struct TempDir(PathBuf);
impl TempDir {
fn new() -> Self {
static COUNTER: AtomicU64 = AtomicU64::new(0);
let path = std::env::temp_dir().join(format!(
"prometeu-protocol-test-{}-{}-{}",
std::process::id(),
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos(),
COUNTER.fetch_add(1, Ordering::Relaxed)
));
fs::create_dir(&path).unwrap();
Self(path)
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.0);
}
}
struct Client {
child: Child,
input: Option<ChildStdin>,
messages: mpsc::Receiver<Result<Value, String>>,
pending: HashMap<String, Value>,
next: u64,
hello: Value,
}
impl Client {
fn new(args: &[&str]) -> Self {
Self::spawn(Path::new(env!("CARGO_BIN_EXE_prometeu-headless")), args, None)
}
fn spawn(binary: &Path, args: &[&str], cwd: Option<&Path>) -> Self {
let mut command = Command::new(binary);
command.args(args).stdin(Stdio::piped()).stdout(Stdio::piped()).stderr(Stdio::inherit());
if let Some(cwd) = cwd {
command.current_dir(cwd);
}
let mut child = command.spawn().unwrap();
let input = child.stdin.take();
let stdout = child.stdout.take().unwrap();
let (sender, messages) = mpsc::channel();
std::thread::spawn(move || {
for line in BufReader::new(stdout).lines() {
let value = line.map_err(|e| e.to_string()).and_then(|line| {
serde_json::from_str(&line)
.map_err(|e| format!("non-protocol stdout: {e}: {line}"))
});
if sender.send(value).is_err() {
break;
}
}
});
let mut client =
Self { child, input, messages, pending: HashMap::new(), next: 0, hello: Value::Null };
client.hello = client.event();
assert_eq!(client.hello["type"], "hello");
client
}
fn event(&self) -> Value {
let message = self
.messages
.recv_timeout(Duration::from_secs(15))
.expect("protocol reply deadline")
.unwrap();
static SCHEMA: std::sync::OnceLock<jsonschema::Validator> = std::sync::OnceLock::new();
let schema = SCHEMA.get_or_init(|| {
let value: Value = serde_json::from_str(include_str!(
"../../../../devtools/headless-protocol/response.schema.json"
))
.unwrap();
jsonschema::validator_for(&value).unwrap()
});
if let Err(error) = schema.validate(&message) {
panic!("server message violates published schema: {error}: {message}");
}
message
}
fn raw(&mut self, bytes: &[u8]) {
self.input.as_mut().unwrap().write_all(bytes).unwrap();
self.input.as_mut().unwrap().flush().unwrap();
}
fn send(&mut self, command: &str, params: Value) -> String {
self.next += 1;
let id = format!("q{}", self.next);
let mut bytes =
serde_json::to_vec(&json!({"requestId":id,"command":command,"params":params})).unwrap();
bytes.push(b'\n');
self.raw(&bytes);
id
}
fn response(&mut self, id: &str) -> Value {
if let Some(value) = self.pending.remove(id) {
return value;
}
loop {
let message = self.event();
if message["type"] == "progress" {
continue;
}
let message_id = message["requestId"].as_str().unwrap().to_owned();
if message_id == id {
return message;
}
self.pending.insert(message_id, message);
}
}
fn call(&mut self, command: &str, params: Value) -> Value {
let id = self.send(command, params);
self.response(&id)
}
fn ok(&mut self, command: &str, params: Value) -> Value {
let response = self.call(command, params);
assert!(response.get("error").is_none(), "{response}");
response["result"].clone()
}
fn initialize(&mut self) {
self.ok("initialize", json!({"protocolVersion":{"major":1,"minor":0},"requiredCapabilities":["advance","capture","cancel"]}));
}
fn wait_exit(&mut self) {
let deadline = Instant::now() + Duration::from_secs(5);
loop {
if let Some(status) = self.child.try_wait().unwrap() {
assert!(status.success(), "{status}");
return;
}
assert!(Instant::now() < deadline, "process did not exit");
std::thread::sleep(Duration::from_millis(5));
}
}
fn close(&mut self) {
self.ok("shutdown", json!({}));
self.input.take();
self.wait_exit();
}
}
impl Drop for Client {
fn drop(&mut self) {
let _ = self.child.kill();
let _ = self.child.wait();
}
}
fn cartridge(code: &str, gfx: bool) -> TempDir {
cartridge_bytes(assemble(code).unwrap(), gfx)
}
fn cartridge_bytes(code: Vec<u8>, gfx: bool) -> TempDir {
let dir = TempDir::new();
let module = BytecodeModule {
version: 0,
const_pool: vec![],
functions: vec![FunctionMeta {
code_offset: 0,
code_len: code.len() as u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 8,
}],
code,
debug_info: Some(DebugInfo {
pc_to_span: vec![(0, SourceSpan { file_id: 7, start: 11, end: 15 })],
function_names: vec![(0, "main".into())],
}),
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
syscalls: if gfx {
vec![SyscallDecl {
module: "gfx2d".into(),
name: "clear".into(),
version: 1,
arg_slots: 1,
ret_slots: 0,
}]
} else {
vec![]
},
};
fs::write(dir.0.join("program.pbx"), module.serialize()).unwrap();
fs::write(
dir.0.join("manifest.json"),
serde_json::to_vec(&json!({"magic":"PMTU","cartridge_version":1,"app_id":41,
"title":"Protocol test","app_version":"0.1.0","app_mode":"Game","capabilities":["gfx2d"]}))
.unwrap(),
)
.unwrap();
dir
}
fn colored_cart() -> TempDir {
cartridge("PUSH_I64 4278190335\nHOSTCALL 0\nFRAME_SYNC\nRET\n", true)
}
fn boot(client: &mut Client, dir: &TempDir) {
client.ok("boot", json!({"path":dir.0}));
}
fn png_bytes(capture: &Value) -> Vec<u8> {
let bytes = STANDARD.decode(capture["data"].as_str().unwrap()).unwrap();
let decoder = png::Decoder::new(std::io::Cursor::new(bytes));
let mut reader = decoder.read_info().unwrap();
let mut output = vec![0; reader.output_buffer_size()];
let info = reader.next_frame(&mut output).unwrap();
assert_eq!(info.color_type, png::ColorType::Rgba);
assert_eq!(info.width as u64, capture["width"].as_u64().unwrap());
assert_eq!(info.height as u64, capture["height"].as_u64().unwrap());
output.truncate(info.buffer_size());
output
}
#[test]
fn handshake_versions_capabilities_and_limits_are_explicit() {
let mut c = Client::new(&["--stdio"]);
assert_eq!(c.hello["runtimeVersion"], env!("CARGO_PKG_VERSION"));
assert_eq!(c.hello["protocolVersion"], json!({"major":1,"minor":0}));
assert_eq!(
c.hello["limits"],
json!({"maxFrames":600,"maxCommandBytes":65536,"maxResponseBytes":33554432,
"handshakeTimeoutMs":5000,"callTimeoutMs":60000,"shutdownTimeoutMs":5000})
);
assert_eq!(c.call("get_state", json!({}))["error"]["code"], "not_initialized");
assert_eq!(
c.call(
"initialize",
json!({"protocolVersion":{"major":2,"minor":0},"requiredCapabilities":[]})
)["error"]["code"],
"incompatible_version"
);
assert_eq!(
c.call(
"initialize",
json!({"protocolVersion":{"major":1,"minor":0},"requiredCapabilities":["telepathy"]})
)["error"]["code"],
"unsupported_capability"
);
assert_eq!(
c.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":42},"requiredCapabilities":[]})
)["protocolVersion"]["minor"],
0
);
assert_eq!(
c.call(
"initialize",
json!({"protocolVersion":{"major":1,"minor":0},"requiredCapabilities":[]})
)["error"]["code"],
"already_initialized"
);
c.close();
}
#[test]
fn malformed_fragmented_and_oversized_commands_do_not_desynchronize() {
let mut c = Client::new(&["--stdio", "--max-command-bytes", "4096"]);
c.initialize();
c.raw(b"not json\n");
assert_eq!(c.event()["error"]["code"], "invalid_request");
c.raw(&[0xff, b'\n']);
assert_eq!(c.event()["error"]["code"], "invalid_request");
let mut huge = vec![b' '; 5000];
huge.push(b'\n');
c.raw(&huge);
assert_eq!(c.event()["error"]["code"], "request_too_large");
c.raw(b"{\"requestId\":\"fragment\",\"command\":\"get_");
assert!(c.messages.try_recv().is_err());
c.raw(b"state\",\"params\":{}}\r\n");
assert_eq!(c.response("fragment")["result"]["status"], "terminated");
assert_eq!(c.call("get_state", json!({"typo":1}))["error"]["code"], "invalid_params");
assert_eq!(c.call("advance", json!({"frames":-1}))["error"]["code"], "invalid_params");
assert_eq!(c.call("advance", json!({"frames":601}))["error"]["code"], "limit_exceeded");
assert_eq!(c.call("missing", json!({}))["error"]["code"], "unknown_command");
c.close();
}
#[test]
fn lifecycle_and_capture_match_the_in_process_canonical_oracle() {
let dir = colored_cart();
let mut c = Client::new(&["--stdio"]);
c.initialize();
assert_eq!(c.call("capture", json!({}))["error"]["code"], "no_frame_available");
boot(&mut c, &dir);
assert_eq!(c.call("boot", json!({"path":dir.0}))["error"]["code"], "already_booted");
let initial = c.ok("get_state", json!({}));
assert_eq!(initial, c.ok("get_state", json!({})), "no background ticks");
assert_eq!(
c.ok("advance", json!({"frames":0})),
json!({"requested":0,"completed":0,"stop":"completed"})
);
c.ok("set_input", json!({"right":true,"touch":true,"touchX":123,"touchY":45}));
c.ok("clear_input", json!({}));
let outcome = c.ok("advance", json!({"frames":3}));
assert_eq!(outcome["completed"], 3);
let capture = c.ok("capture", json!({}));
let mut host = HeadlessHost::new();
host.boot(dir.0.to_string_lossy()).unwrap();
assert_eq!(host.advance_frames(3).unwrap().stop, AdvanceFramesStop::Completed);
let expected = host.capture_frame().unwrap();
let pixels: Vec<u8> = expected.frame.pixels.iter().flat_map(|v| v.to_be_bytes()).collect();
assert_eq!(png_bytes(&capture), pixels);
assert_eq!(capture["logicalFrameIndex"], expected.logical_frame_index);
assert_eq!(capture["frameId"], expected.frame.frame_id.get());
assert_eq!(capture["stridePixels"], expected.frame.stride_pixels);
assert_eq!(c.ok("get_fault", json!({})), Value::Null);
c.ok("reset", json!({}));
assert_eq!(c.call("capture", json!({}))["error"]["code"], "no_frame_available");
assert_eq!(c.ok("advance", json!({"frames":1}))["stop"], "terminated");
boot(&mut c, &dir);
c.ok("advance", json!({"frames":3}));
assert_eq!(c.ok("capture", json!({})), capture);
c.close();
}
#[test]
fn independent_processes_match_pixels_ids_state_and_fault() {
// Color is selected by the real normalized RIGHT-down intrinsic.
let mut code = assemble("INTRINSIC 0x210E\n").unwrap();
let jump = code.len() + 2;
code.extend(
assemble("JMP_IF_FALSE 0\nPUSH_I64 4278190335\nHOSTCALL 0\nFRAME_SYNC\nRET\n").unwrap(),
);
let blue = code.len() as u32;
code[jump..jump + 4].copy_from_slice(&blue.to_le_bytes());
code.extend(assemble("PUSH_I64 65535\nHOSTCALL 0\nFRAME_SYNC\nRET\n").unwrap());
let dir = cartridge_bytes(code, true);
let run = |c: &mut Client| {
boot(c, &dir);
c.ok("set_input", json!({"right":true}));
c.ok("advance", json!({"frames":12}));
let held = c.ok("capture", json!({}));
assert!(png_bytes(&held).as_chunks::<4>().0.iter().all(|p| *p == [255, 0, 0, 255]));
c.ok("clear_input", json!({}));
c.ok("advance", json!({"frames":1}));
let released = c.ok("capture", json!({}));
assert!(png_bytes(&released).as_chunks::<4>().0.iter().all(|p| *p == [0, 0, 255, 255]));
(held, released, c.ok("get_state", json!({})), c.ok("get_fault", json!({})))
};
let mut first = Client::new(&["--stdio"]);
first.initialize();
let expected = run(&mut first);
first.ok("reset", json!({}));
assert_eq!(run(&mut first), expected);
first.close();
let mut second = Client::new(&["--stdio"]);
second.initialize();
assert_eq!(run(&mut second), expected);
second.close();
}
#[test]
fn partial_guest_fault_and_host_watchdog_are_distinct_outcomes() {
let mut code =
assemble("GET_GLOBAL 0\nPUSH_I32 1\nADD\nSET_GLOBAL 0\nGET_GLOBAL 0\nPUSH_I32 3\nEQ\n")
.unwrap();
let jump = code.len() + 2;
code.extend(assemble("JMP_IF_FALSE 0\nTRAP\n").unwrap());
let next = code.len() as u32;
code[jump..jump + 4].copy_from_slice(&next.to_le_bytes());
code.extend(assemble("PUSH_I64 255\nHOSTCALL 0\nFRAME_SYNC\nRET\n").unwrap());
let dir = cartridge_bytes(code, true);
let mut c = Client::new(&["--stdio"]);
c.initialize();
boot(&mut c, &dir);
let outcome = c.ok("advance", json!({"frames":5}));
assert_eq!(outcome["completed"], 2);
assert_eq!(outcome["stop"], "faulted");
assert_eq!(outcome["fault"], c.ok("get_fault", json!({})));
c.ok("reset", json!({}));
let infinite = cartridge("JMP 0\n", false);
boot(&mut c, &infinite);
let outcome = c.ok("advance", json!({"frames":5}));
assert_eq!(outcome["completed"], 0);
assert_eq!(outcome["stop"], "host_error");
assert_eq!(outcome["error"]["code"], "watchdog_expired");
assert_eq!(c.ok("get_fault", json!({})), Value::Null);
assert_eq!(c.ok("get_state", json!({}))["status"], "paused");
c.close();
}
#[test]
fn faults_and_boot_failures_are_structured_not_log_parsing() {
let dir = cartridge("TRAP\nFRAME_SYNC\nRET\n", false);
let mut c = Client::new(&["--stdio"]);
c.initialize();
boot(&mut c, &dir);
let result = c.ok("advance", json!({"frames":5}));
assert_eq!(result["completed"], 0);
assert_eq!(result["stop"], "faulted");
assert_eq!(result["fault"]["kind"], "vm_trap");
assert!(result["fault"]["trap"]["code"].is_number());
assert_eq!(c.ok("get_fault", json!({})), result["fault"]);
assert_eq!(c.ok("get_state", json!({}))["status"], "faulted");
c.ok("reset", json!({}));
fs::write(dir.0.join("program.pbx"), b"not PBX").unwrap();
let response = c.call("boot", json!({"path":dir.0}));
assert_eq!(response["error"]["code"], "boot_failed");
assert_eq!(response["error"]["details"]["fault"]["kind"], "vm_init");
assert!(response["error"]["details"]["fault"]["initError"]["code"].is_string());
c.close();
}
#[test]
fn conflicting_work_is_rejected_and_cancellation_reports_partial_progress() {
let dir = colored_cart();
let mut c = Client::new(&["--stdio", "--max-frames", "100000"]);
c.initialize();
boot(&mut c, &dir);
let advance = c.send("advance", json!({"frames":100000}));
assert_eq!(c.event()["type"], "progress");
assert_eq!(c.call("reset", json!({}))["error"]["code"], "busy");
c.ok("cancel", json!({"targetRequestId":advance}));
let response = c.response(&advance);
let result = &response["result"];
assert_eq!(result["stop"], "canceled");
assert!(
result["completed"].as_u64().unwrap() >= 1
&& result["completed"].as_u64().unwrap() < 100000
);
assert_eq!(c.ok("get_state", json!({}))["logicalFrameIndex"], result["completed"]);
assert_eq!(
c.call("cancel", json!({"targetRequestId":advance}))["error"]["code"],
"not_cancelable"
);
c.close();
}
#[test]
fn shutdown_and_eof_interrupt_active_work_without_resuming_it() {
let dir = colored_cart();
for explicit in [true, false] {
let mut c = Client::new(&["--stdio", "--max-frames", "100000"]);
c.initialize();
boot(&mut c, &dir);
let advance = c.send("advance", json!({"frames":100000}));
assert_eq!(c.event()["type"], "progress");
if explicit {
let shutdown = c.send("shutdown", json!({}));
assert_eq!(c.response(&advance)["result"]["stop"], "canceled");
assert_eq!(c.response(&shutdown)["result"]["closed"], true);
} else {
c.input.take();
assert_eq!(c.response(&advance)["result"]["stop"], "canceled");
}
c.wait_exit();
}
}
#[test]
fn idle_eof_and_truncated_eof_close_the_process() {
for suffix in [b"".as_slice(), b"{\"requestId\":\"partial\"".as_slice()] {
let mut c = Client::new(&["--stdio"]);
c.raw(suffix);
c.input.take();
if !suffix.is_empty() {
assert_eq!(c.event()["error"]["code"], "invalid_request");
}
c.wait_exit();
}
}
#[test]
fn dispatcher_works_from_a_relocated_installation_and_other_cwd() {
let installation = TempDir::new();
let cwd = TempDir::new();
let dispatcher = installation.0.join(if cfg!(windows) { "prometeu.exe" } else { "prometeu" });
let headless = installation.0.join(if cfg!(windows) {
"prometeu-headless.exe"
} else {
"prometeu-headless"
});
fs::copy(env!("CARGO_BIN_EXE_prometeu"), &dispatcher).unwrap();
fs::copy(env!("CARGO_BIN_EXE_prometeu-headless"), &headless).unwrap();
let mut c = Client::spawn(
&dispatcher,
&[
"headless",
"--stdio",
"--max-frames",
"17",
"--max-command-bytes",
"8192",
"--max-response-bytes",
"16384",
"--handshake-timeout-ms",
"1234",
"--call-timeout-ms",
"2345",
"--shutdown-timeout-ms",
"3456",
],
Some(&cwd.0),
);
assert_eq!(
c.hello["limits"],
json!({"maxFrames":17,"maxCommandBytes":8192,"maxResponseBytes":16384,
"handshakeTimeoutMs":1234,"callTimeoutMs":2345,"shutdownTimeoutMs":3456})
);
c.initialize();
c.close();
let help = Command::new(&dispatcher).arg("--help").output().unwrap();
let help = String::from_utf8(help.stdout).unwrap();
for name in ["run", "debug", "headless"] {
assert!(help.contains(name));
}
}
#[test]
fn missing_binary_and_invalid_cli_limits_fail_explicitly() {
let installation = TempDir::new();
let dispatcher = installation.0.join(if cfg!(windows) { "prometeu.exe" } else { "prometeu" });
fs::copy(env!("CARGO_BIN_EXE_prometeu"), &dispatcher).unwrap();
let result = Command::new(&dispatcher).args(["headless", "--stdio"]).output().unwrap();
assert!(!result.status.success());
assert!(String::from_utf8_lossy(&result.stderr).contains("headless"));
for args in
[vec!["--stdio", "--max-frames", "0"], vec!["--stdio", "--max-response-bytes", "1"], vec![]]
{
let result =
Command::new(env!("CARGO_BIN_EXE_prometeu-headless")).args(args).output().unwrap();
assert!(!result.status.success());
assert!(result.stdout.is_empty());
}
}
#[test]
fn schemas_and_distributed_request_fixtures_are_consistent() {
let request: Value = serde_json::from_str(include_str!(
"../../../../devtools/headless-protocol/request.schema.json"
))
.unwrap();
let response: Value = serde_json::from_str(include_str!(
"../../../../devtools/headless-protocol/response.schema.json"
))
.unwrap();
jsonschema::meta::validate(&request).unwrap();
jsonschema::meta::validate(&response).unwrap();
let validator = jsonschema::validator_for(&request).unwrap();
let valid: Vec<Value> =
serde_json::from_str(include_str!("../../../../devtools/headless-protocol/requests.json"))
.unwrap();
for request in valid {
validator.validate(&request).unwrap();
}
let invalid: Vec<Value> = serde_json::from_str(include_str!(
"../../../../devtools/headless-protocol/invalid-requests.json"
))
.unwrap();
let mut c = Client::new(&["--stdio"]);
c.initialize();
for request in invalid {
assert!(!validator.is_valid(&request), "{request}");
let mut bytes = serde_json::to_vec(&request).unwrap();
bytes.push(b'\n');
c.raw(&bytes);
assert!(c.event().get("error").is_some(), "{request}");
}
c.close();
}
#[test]
#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive"]
fn packaged_installation_smoke() {
let installation = PathBuf::from(
std::env::var_os("PROMETEU_PROTOCOL_TEST_INSTALL")
.expect("set extracted distribution path"),
);
for file in [
"prometeu",
"prometeu-runtime",
"prometeu-headless",
"headless-protocol/request.schema.json",
"headless-protocol/response.schema.json",
"11a-headless-automation-protocol.md",
] {
assert!(installation.join(file).is_file(), "missing packaged {file}");
}
let cwd = TempDir::new();
let dir = colored_cart();
let mut c =
Client::spawn(&installation.join("prometeu"), &["headless", "--stdio"], Some(&cwd.0));
assert_eq!(c.hello["runtimeVersion"], env!("CARGO_PKG_VERSION"));
c.initialize();
boot(&mut c, &dir);
c.ok("advance", json!({"frames":3}));
let capture = c.ok("capture", json!({}));
assert!(png_bytes(&capture).as_chunks::<4>().0.iter().all(|p| *p == [255, 0, 0, 255]));
c.input.take();
c.wait_exit();
}
@@ -0,0 +1,49 @@
[
{
"requestId": "negative",
"command": "advance",
"params": {
"frames": -1
}
},
{
"requestId": "wrong-input",
"command": "set_input",
"params": {
"rigth": true
}
},
{
"requestId": "extra",
"command": "get_state",
"params": {
"extra": true
}
},
{
"requestId": "unknown",
"command": "missing",
"params": {}
},
{
"requestId": "blank-path",
"command": "boot",
"params": {
"path": ""
}
},
{
"requestId": "",
"command": "reset",
"params": {}
},
{
"requestId": "no-params",
"command": "get_state"
},
{
"requestId": "null-params",
"command": "get_state",
"params": null
}
]
@@ -0,0 +1,284 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://prometeu.dev/headless/v1/request.schema.json",
"title": "Prometeu Headless v1 Request",
"type": "object",
"additionalProperties": false,
"required": [
"requestId",
"command",
"params"
],
"properties": {
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"command": {
"type": "string"
},
"params": {
"type": "object"
}
},
"oneOf": [
{
"properties": {
"command": {
"const": "initialize"
},
"params": {
"type": "object",
"additionalProperties": false,
"required": [
"protocolVersion",
"requiredCapabilities"
],
"properties": {
"protocolVersion": {
"$ref": "#/$defs/version"
},
"requiredCapabilities": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
{
"properties": {
"command": {
"const": "boot"
},
"params": {
"type": "object",
"additionalProperties": false,
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"minLength": 1,
"pattern": "\\S"
}
}
}
}
},
{
"properties": {
"command": {
"const": "advance"
},
"params": {
"type": "object",
"additionalProperties": false,
"required": [
"frames"
],
"properties": {
"frames": {
"type": "integer",
"minimum": 0,
"maximum": 18446744073709551615
}
}
}
}
},
{
"properties": {
"command": {
"const": "set_input"
},
"params": {
"$ref": "#/$defs/input"
}
}
},
{
"properties": {
"command": {
"const": "cancel"
},
"params": {
"type": "object",
"additionalProperties": false,
"required": [
"targetRequestId"
],
"properties": {
"targetRequestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
}
}
}
},
{
"properties": {
"command": {
"const": "reset"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "clear_input"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "capture"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "get_state"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "get_fault"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
},
{
"properties": {
"command": {
"const": "shutdown"
},
"params": {
"type": "object",
"maxProperties": 0
}
}
}
],
"$defs": {
"version": {
"type": "object",
"additionalProperties": false,
"required": [
"major",
"minor"
],
"properties": {
"major": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"minor": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"input": {
"type": "object",
"additionalProperties": false,
"properties": {
"up": {
"type": "boolean",
"default": false
},
"down": {
"type": "boolean",
"default": false
},
"left": {
"type": "boolean",
"default": false
},
"right": {
"type": "boolean",
"default": false
},
"a": {
"type": "boolean",
"default": false
},
"b": {
"type": "boolean",
"default": false
},
"x": {
"type": "boolean",
"default": false
},
"y": {
"type": "boolean",
"default": false
},
"l": {
"type": "boolean",
"default": false
},
"r": {
"type": "boolean",
"default": false
},
"start": {
"type": "boolean",
"default": false
},
"select": {
"type": "boolean",
"default": false
},
"touch": {
"type": "boolean",
"default": false
},
"touchX": {
"type": "integer",
"minimum": -2147483648,
"maximum": 2147483647,
"default": 0
},
"touchY": {
"type": "integer",
"minimum": -2147483648,
"maximum": 2147483647,
"default": 0
}
}
}
}
}
+78
View File
@@ -0,0 +1,78 @@
[
{
"requestId": "init",
"command": "initialize",
"params": {
"protocolVersion": {
"major": 1,
"minor": 0
},
"requiredCapabilities": [
"advance",
"capture",
"cancel"
]
}
},
{
"requestId": "boot",
"command": "boot",
"params": {
"path": "/cartridge"
}
},
{
"requestId": "reset",
"command": "reset",
"params": {}
},
{
"requestId": "input",
"command": "set_input",
"params": {
"right": true,
"touch": true,
"touchX": 123,
"touchY": 45
}
},
{
"requestId": "clear",
"command": "clear_input",
"params": {}
},
{
"requestId": "advance",
"command": "advance",
"params": {
"frames": 60
}
},
{
"requestId": "capture",
"command": "capture",
"params": {}
},
{
"requestId": "get_state",
"command": "get_state",
"params": {}
},
{
"requestId": "get_fault",
"command": "get_fault",
"params": {}
},
{
"requestId": "shutdown",
"command": "shutdown",
"params": {}
},
{
"requestId": "cancel",
"command": "cancel",
"params": {
"targetRequestId": "advance"
}
}
]
@@ -0,0 +1,666 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Prometeu headless server messages v1.0",
"$comment": "requestId additionally has a 128 UTF-8-byte bound; uint counters require lossless decoding. v1.0 producers are checked strictly. Consumers must allow compatible minor extensions.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"const": "hello"
},
"sessionId": {
"type": "string",
"minLength": 1
},
"protocolVersion": {
"$ref": "#/$defs/version"
},
"runtimeVersion": {
"type": "string",
"minLength": 1
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"limits": {
"$ref": "#/$defs/limits"
}
},
"required": [
"type",
"sessionId",
"protocolVersion",
"runtimeVersion",
"capabilities",
"limits"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "progress"
},
"sessionId": {
"type": "string",
"minLength": 1
},
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"requested": {
"type": "integer",
"minimum": 0
},
"completed": {
"type": "integer",
"minimum": 0
}
},
"required": [
"type",
"sessionId",
"requestId",
"requested",
"completed"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "response"
},
"sessionId": {
"type": "string",
"minLength": 1
},
"requestId": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 128
},
"error": {
"$ref": "#/$defs/error"
}
},
"required": [
"type",
"sessionId",
"requestId",
"error"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "response"
},
"sessionId": {
"type": "string",
"minLength": 1
},
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"result": {
"anyOf": [
{
"$ref": "#/$defs/negotiated"
},
{
"$ref": "#/$defs/state"
},
{
"$ref": "#/$defs/advance"
},
{
"$ref": "#/$defs/capture"
},
{
"$ref": "#/$defs/fault"
},
{
"type": "null"
},
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"targetRequestId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"requested": {
"const": true
}
},
"required": [
"targetRequestId",
"requested"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"closed": {
"const": true
}
},
"required": [
"closed"
],
"additionalProperties": false
}
]
}
},
"required": [
"type",
"sessionId",
"requestId",
"result"
],
"additionalProperties": false
}
],
"$defs": {
"version": {
"type": "object",
"properties": {
"major": {
"const": 1
},
"minor": {
"type": "integer",
"minimum": 0
}
},
"required": [
"major",
"minor"
],
"additionalProperties": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
}
},
"required": [
"code",
"message",
"details"
],
"additionalProperties": false
},
"stack": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "int32"
},
"value": {
"type": "integer",
"minimum": -2147483648,
"maximum": 2147483647
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"enum": [
"int64",
"float64",
"string"
]
},
"value": {
"type": "string"
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "heap_ref"
},
"value": {
"type": "integer",
"minimum": 0
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "boolean"
},
"value": {
"type": "boolean"
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "null"
},
"value": {
"type": "null"
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
}
]
},
"state": {
"type": "object",
"properties": {
"pc": {
"type": "integer",
"minimum": 0
},
"stackTop": {
"type": "array",
"items": {
"$ref": "#/$defs/stack"
}
},
"logicalFrameIndex": {
"type": "integer",
"minimum": 0
},
"tickIndex": {
"type": "integer",
"minimum": 0
},
"appId": {
"type": "integer",
"minimum": 0
},
"status": {
"enum": [
"running",
"paused",
"terminated",
"faulted"
]
}
},
"required": [
"pc",
"stackTop",
"logicalFrameIndex",
"tickIndex",
"appId",
"status"
],
"additionalProperties": false
},
"fault": {
"oneOf": [
{
"type": "object",
"properties": {
"pc": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"summary": {
"type": "string"
},
"kind": {
"const": "vm_trap"
},
"trap": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": 0
},
"opcode": {
"type": "integer",
"minimum": 0
},
"message": {
"type": "string"
},
"pc": {
"type": "integer",
"minimum": 0
},
"span": {
"type": [
"object",
"null"
]
}
},
"required": [
"code",
"opcode",
"message",
"pc",
"span"
],
"additionalProperties": false
}
},
"required": [
"pc",
"summary",
"kind",
"trap"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"pc": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"summary": {
"type": "string"
},
"kind": {
"const": "vm_panic"
},
"message": {
"type": "string"
}
},
"required": [
"pc",
"summary",
"kind",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"pc": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"summary": {
"type": "string"
},
"kind": {
"const": "vm_init"
},
"initError": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"pc",
"summary",
"kind",
"initError"
],
"additionalProperties": false
}
]
},
"advance": {
"type": "object",
"properties": {
"requested": {
"type": "integer",
"minimum": 0
},
"completed": {
"type": "integer",
"minimum": 0
},
"stop": {
"enum": [
"completed",
"faulted",
"terminated",
"canceled",
"host_error"
]
},
"fault": {
"$ref": "#/$defs/fault"
},
"error": {
"$ref": "#/$defs/error"
}
},
"required": [
"requested",
"completed",
"stop"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"stop": {
"const": "faulted"
}
}
},
"then": {
"required": [
"fault"
]
}
},
{
"if": {
"properties": {
"stop": {
"const": "host_error"
}
}
},
"then": {
"required": [
"error"
]
}
}
]
},
"capture": {
"type": "object",
"properties": {
"mimeType": {
"const": "image/png"
},
"encoding": {
"const": "base64"
},
"data": {
"type": "string",
"contentEncoding": "base64"
},
"width": {
"type": "integer",
"minimum": 1
},
"height": {
"type": "integer",
"minimum": 1
},
"stridePixels": {
"type": "integer",
"minimum": 1
},
"pixelFormat": {
"const": "RGBA8888"
},
"logicalFrameIndex": {
"type": "integer",
"minimum": 0
},
"frameId": {
"type": "integer",
"minimum": 0
}
},
"required": [
"mimeType",
"encoding",
"data",
"width",
"height",
"stridePixels",
"pixelFormat",
"logicalFrameIndex",
"frameId"
],
"additionalProperties": false
},
"negotiated": {
"type": "object",
"properties": {
"protocolVersion": {
"$ref": "#/$defs/version"
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"protocolVersion",
"capabilities"
],
"additionalProperties": false
},
"limits": {
"type": "object",
"properties": {
"maxFrames": {
"type": "integer",
"minimum": 1
},
"maxCommandBytes": {
"type": "integer",
"minimum": 1
},
"maxResponseBytes": {
"type": "integer",
"minimum": 1
},
"handshakeTimeoutMs": {
"type": "integer",
"minimum": 1
},
"callTimeoutMs": {
"type": "integer",
"minimum": 1
},
"shutdownTimeoutMs": {
"type": "integer",
"minimum": 1
}
},
"required": [
"maxFrames",
"maxCommandBytes",
"maxResponseBytes",
"handshakeTimeoutMs",
"callTimeoutMs",
"shutdownTimeoutMs"
],
"additionalProperties": false
}
}
}
@@ -1,25 +0,0 @@
{"type":"meta","next_id":{"DSC":25,"AGD":25,"DEC":13,"PLN":11,"LSN":29,"CLSN":1}}
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"workflow/agendas/AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"workflow/agendas/AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0007","file":"workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0005","file":"workflow/decisions/DEC-0005-perf-push-based-telemetry-model.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0005","file":"workflow/plans/PLN-0005-perf-push-based-telemetry-implementation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0026","file":"lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0013","status":"open","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0012","file":"workflow/agendas/AGD-0012-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"},{"id":"AGD-0022","file":"AGD-0022-host-overlay-tooling-boundary-revision.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"AGD-0023","file":"AGD-0023-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0007","file":"workflow/decisions/DEC-0007-perf-host-debug-overlay-isolation.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"DEC-0009","file":"DEC-0009-host-overlay-tooling-boundary.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0022"},{"id":"DEC-0010","file":"DEC-0010-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0023"}],"plans":[{"id":"PLN-0006","file":"workflow/plans/PLN-0006-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"PLN-0008","file":"PLN-0008-host-overlay-native-composition-alignment.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0007","DEC-0008","DEC-0009","DEC-0010"]}],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0024","status":"open","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[{"id":"AGD-0024","file":"AGD-0024-generic-memory-bank-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0012","file":"DEC-0012-asset-manager-bank-telemetry-slot-contract.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0024"}],"plans":[{"id":"PLN-0010","file":"PLN-0010-asset-manager-bank-telemetry-slot-contract.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0012"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0016","file":"workflow/agendas/AGD-0016-asset-entry-metadata-normalization-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[{"id":"DEC-0004","file":"workflow/decisions/DEC-0004-asset-entry-metadata-normalization-contract.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-09"}],"plans":[],"lessons":[{"id":"LSN-0023","file":"lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"asset-load-asset-id-int-contract","title":"Asset Load Asset ID Int Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["asset","runtime","abi"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0019","file":"lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"workflow/agendas/AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"workflow/decisions/DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"workflow/plans/PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
@@ -1,26 +0,0 @@
{"type":"meta","next_id":{"DSC":26,"AGD":26,"DEC":14,"PLN":17,"LSN":31,"CLSN":1}}
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"workflow/agendas/AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"workflow/agendas/AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0007","file":"workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0005","file":"workflow/decisions/DEC-0005-perf-push-based-telemetry-model.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0005","file":"workflow/plans/PLN-0005-perf-push-based-telemetry-implementation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0026","file":"lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"scene-bank-and-viewport-cache-refactor","title":"Scene Bank and Viewport Cache Refactor","created_at":"2026-04-11","updated_at":"2026-04-14","tags":["gfx","tilemap","runtime","render"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"lessons/DSC-0025-scene-bank-and-viewport-cache-refactor/LSN-0030-canonical-scene-cache-and-resolver-split.md","status":"done","created_at":"2026-04-14","updated_at":"2026-04-14"}]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0016","file":"workflow/agendas/AGD-0016-asset-entry-metadata-normalization-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[{"id":"DEC-0004","file":"workflow/decisions/DEC-0004-asset-entry-metadata-normalization-contract.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-09"}],"plans":[],"lessons":[{"id":"LSN-0023","file":"lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"asset-load-asset-id-int-contract","title":"Asset Load Asset ID Int Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["asset","runtime","abi"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0019","file":"lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"workflow/agendas/AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"workflow/decisions/DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"workflow/plans/PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
@@ -1,29 +0,0 @@
{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":17,"PLN":30,"LSN":31,"CLSN":1}}
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"workflow/agendas/AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"workflow/agendas/AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0007","file":"workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0005","file":"workflow/decisions/DEC-0005-perf-push-based-telemetry-model.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0005","file":"workflow/plans/PLN-0005-perf-push-based-telemetry-implementation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0026","file":"lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"scene-bank-and-viewport-cache-refactor","title":"Scene Bank and Viewport Cache Refactor","created_at":"2026-04-11","updated_at":"2026-04-14","tags":["gfx","tilemap","runtime","render"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"lessons/DSC-0025-scene-bank-and-viewport-cache-refactor/LSN-0030-canonical-scene-cache-and-resolver-split.md","status":"done","created_at":"2026-04-14","updated_at":"2026-04-14"}]}
{"type":"discussion","id":"DSC-0026","status":"open","ticket":"render-all-scene-cache-and-camera-integration","title":"Integrate render_all with Scene Cache and Camera","created_at":"2026-04-14","updated_at":"2026-04-15","tags":["gfx","runtime","render","camera","scene"],"agendas":[{"id":"AGD-0026","file":"workflow/agendas/AGD-0026-render-all-scene-cache-and-camera-integration.md","status":"accepted","created_at":"2026-04-14","updated_at":"2026-04-15"}],"decisions":[{"id":"DEC-0014","file":"workflow/decisions/DEC-0014-frame-composer-render-integration.md","status":"accepted","created_at":"2026-04-14","updated_at":"2026-04-15","ref_agenda":"AGD-0026"}],"plans":[{"id":"PLN-0017","file":"workflow/plans/PLN-0017-frame-composer-core-and-hardware-ownership.md","status":"accepted","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0014"]},{"id":"PLN-0018","file":"workflow/plans/PLN-0018-sprite-controller-and-frame-emission-model.md","status":"accepted","created_at":"2026-04-14","updated_at":"2026-04-14","ref_decisions":["DEC-0014"]},{"id":"PLN-0019","file":"workflow/plans/PLN-0019-scene-binding-camera-and-scene-status.md","status":"accepted","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0014"]},{"id":"PLN-0020","file":"workflow/plans/PLN-0020-cache-refresh-and-render-frame-path.md","status":"accepted","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0014"]},{"id":"PLN-0021","file":"workflow/plans/PLN-0021-service-retirement-callsite-migration-and-regression.md","status":"accepted","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0014"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0027","status":"open","ticket":"frame-composer-public-syscall-surface","title":"Agenda - FrameComposer Public Syscall Surface","created_at":"2026-04-17","updated_at":"2026-04-17","tags":["gfx","runtime","syscall","abi","frame-composer","scene","camera","sprites"],"agendas":[{"id":"AGD-0027","file":"workflow/agendas/AGD-0027-frame-composer-public-syscall-surface.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17"}],"decisions":[{"id":"DEC-0015","file":"workflow/decisions/DEC-0015-frame-composer-public-syscall-surface.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_agenda":"AGD-0027"}],"plans":[{"id":"PLN-0022","file":"workflow/plans/PLN-0022-composer-syscall-domain-and-spec-propagation.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0015"]},{"id":"PLN-0023","file":"workflow/plans/PLN-0023-composer-runtime-dispatch-and-legacy-removal.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0015"]},{"id":"PLN-0024","file":"workflow/plans/PLN-0024-composer-cartridge-tooling-and-regression-migration.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0015"]},{"id":"PLN-0025","file":"workflow/plans/PLN-0025-final-ci-validation-and-polish.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0015"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0028","status":"open","ticket":"deferred-overlay-and-primitive-composition","title":"Deferred Overlay and Primitive Composition over FrameComposer","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["gfx","runtime","render","frame-composer","overlay","primitives","hud"],"agendas":[{"id":"AGD-0028","file":"workflow/agendas/AGD-0028-deferred-overlay-and-primitive-composition.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18"}],"decisions":[{"id":"DEC-0016","file":"workflow/decisions/DEC-0016-deferred-gfx-overlay-outside-frame-composer.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_agenda":"AGD-0028"}],"plans":[{"id":"PLN-0026","file":"workflow/plans/PLN-0026-gfx-overlay-contract-and-spec-propagation.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0016"]},{"id":"PLN-0027","file":"workflow/plans/PLN-0027-deferred-gfx-overlay-subsystem.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0016"]},{"id":"PLN-0028","file":"workflow/plans/PLN-0028-runtime-frame-end-overlay-integration-and-parity.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0016"]},{"id":"PLN-0029","file":"workflow/plans/PLN-0029-final-overlay-ci-validation-and-polish.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0016"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0016","file":"workflow/agendas/AGD-0016-asset-entry-metadata-normalization-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[{"id":"DEC-0004","file":"workflow/decisions/DEC-0004-asset-entry-metadata-normalization-contract.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-09"}],"plans":[],"lessons":[{"id":"LSN-0023","file":"lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"asset-load-asset-id-int-contract","title":"Asset Load Asset ID Int Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["asset","runtime","abi"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0019","file":"lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"workflow/agendas/AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"workflow/decisions/DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"workflow/plans/PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
@@ -1,29 +0,0 @@
{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":17,"PLN":30,"LSN":32,"CLSN":1}}
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"workflow/agendas/AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"workflow/agendas/AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0007","file":"workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0005","file":"workflow/decisions/DEC-0005-perf-push-based-telemetry-model.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0005","file":"workflow/plans/PLN-0005-perf-push-based-telemetry-implementation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0026","file":"lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"scene-bank-and-viewport-cache-refactor","title":"Scene Bank and Viewport Cache Refactor","created_at":"2026-04-11","updated_at":"2026-04-14","tags":["gfx","tilemap","runtime","render"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"lessons/DSC-0025-scene-bank-and-viewport-cache-refactor/LSN-0030-canonical-scene-cache-and-resolver-split.md","status":"done","created_at":"2026-04-14","updated_at":"2026-04-14"}]}
{"type":"discussion","id":"DSC-0026","status":"done","ticket":"render-all-scene-cache-and-camera-integration","title":"Integrate render_all with Scene Cache and Camera","created_at":"2026-04-14","updated_at":"2026-04-18","tags":["gfx","runtime","render","camera","scene"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"lessons/DSC-0026-render-all-scene-cache-and-camera-integration/LSN-0031-frame-composition-belongs-above-the-render-backend.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
{"type":"discussion","id":"DSC-0027","status":"open","ticket":"frame-composer-public-syscall-surface","title":"Agenda - FrameComposer Public Syscall Surface","created_at":"2026-04-17","updated_at":"2026-04-17","tags":["gfx","runtime","syscall","abi","frame-composer","scene","camera","sprites"],"agendas":[{"id":"AGD-0027","file":"workflow/agendas/AGD-0027-frame-composer-public-syscall-surface.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17"}],"decisions":[{"id":"DEC-0015","file":"workflow/decisions/DEC-0015-frame-composer-public-syscall-surface.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_agenda":"AGD-0027"}],"plans":[{"id":"PLN-0022","file":"workflow/plans/PLN-0022-composer-syscall-domain-and-spec-propagation.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0015"]},{"id":"PLN-0023","file":"workflow/plans/PLN-0023-composer-runtime-dispatch-and-legacy-removal.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0015"]},{"id":"PLN-0024","file":"workflow/plans/PLN-0024-composer-cartridge-tooling-and-regression-migration.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0015"]},{"id":"PLN-0025","file":"workflow/plans/PLN-0025-final-ci-validation-and-polish.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0015"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0028","status":"open","ticket":"deferred-overlay-and-primitive-composition","title":"Deferred Overlay and Primitive Composition over FrameComposer","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["gfx","runtime","render","frame-composer","overlay","primitives","hud"],"agendas":[{"id":"AGD-0028","file":"workflow/agendas/AGD-0028-deferred-overlay-and-primitive-composition.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18"}],"decisions":[{"id":"DEC-0016","file":"workflow/decisions/DEC-0016-deferred-gfx-overlay-outside-frame-composer.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_agenda":"AGD-0028"}],"plans":[{"id":"PLN-0026","file":"workflow/plans/PLN-0026-gfx-overlay-contract-and-spec-propagation.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0016"]},{"id":"PLN-0027","file":"workflow/plans/PLN-0027-deferred-gfx-overlay-subsystem.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0016"]},{"id":"PLN-0028","file":"workflow/plans/PLN-0028-runtime-frame-end-overlay-integration-and-parity.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0016"]},{"id":"PLN-0029","file":"workflow/plans/PLN-0029-final-overlay-ci-validation-and-polish.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0016"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0016","file":"workflow/agendas/AGD-0016-asset-entry-metadata-normalization-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[{"id":"DEC-0004","file":"workflow/decisions/DEC-0004-asset-entry-metadata-normalization-contract.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-09"}],"plans":[],"lessons":[{"id":"LSN-0023","file":"lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"asset-load-asset-id-int-contract","title":"Asset Load Asset ID Int Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["asset","runtime","abi"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0019","file":"lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"workflow/agendas/AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"workflow/decisions/DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"workflow/plans/PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
@@ -1,29 +0,0 @@
{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":18,"PLN":33,"LSN":34,"CLSN":1}}
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"workflow/agendas/AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"workflow/agendas/AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0007","file":"workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0005","file":"workflow/decisions/DEC-0005-perf-push-based-telemetry-model.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0005","file":"workflow/plans/PLN-0005-perf-push-based-telemetry-implementation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0026","file":"lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0012","status":"review","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-19","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-04-18"}],"decisions":[{"id":"DEC-0009","file":"workflow/decisions/DEC-0009-host-owned-debug-and-certification.md","status":"accepted","created_at":"2026-04-18","updated_at":"2026-04-19","ref_agenda":"AGD-0011"}],"plans":[{"id":"PLN-0030","file":"workflow/plans/PLN-0030-dec9-spec-boundary-propagation.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]},{"id":"PLN-0031","file":"workflow/plans/PLN-0031-dec9-runtime-bank-abi-cleanup.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]},{"id":"PLN-0032","file":"workflow/plans/PLN-0032-dec9-host-debugger-and-certification-alignment.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19","ref_decisions":["DEC-0009"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"scene-bank-and-viewport-cache-refactor","title":"Scene Bank and Viewport Cache Refactor","created_at":"2026-04-11","updated_at":"2026-04-14","tags":["gfx","tilemap","runtime","render"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"lessons/DSC-0025-scene-bank-and-viewport-cache-refactor/LSN-0030-canonical-scene-cache-and-resolver-split.md","status":"done","created_at":"2026-04-14","updated_at":"2026-04-14"}]}
{"type":"discussion","id":"DSC-0026","status":"done","ticket":"render-all-scene-cache-and-camera-integration","title":"Integrate render_all with Scene Cache and Camera","created_at":"2026-04-14","updated_at":"2026-04-18","tags":["gfx","runtime","render","camera","scene"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"lessons/DSC-0026-render-all-scene-cache-and-camera-integration/LSN-0031-frame-composition-belongs-above-the-render-backend.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
{"type":"discussion","id":"DSC-0027","status":"done","ticket":"frame-composer-public-syscall-surface","title":"Agenda - FrameComposer Public Syscall Surface","created_at":"2026-04-17","updated_at":"2026-04-18","tags":["gfx","runtime","syscall","abi","frame-composer","scene","camera","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"lessons/DSC-0027-frame-composer-public-syscall-surface/LSN-0032-public-abi-must-follow-the-canonical-service-boundary.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
{"type":"discussion","id":"DSC-0028","status":"done","ticket":"deferred-overlay-and-primitive-composition","title":"Deferred Overlay and Primitive Composition over FrameComposer","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["gfx","runtime","render","frame-composer","overlay","primitives","hud"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"lessons/DSC-0028-deferred-overlay-and-primitive-composition/LSN-0033-debug-primitives-should-be-a-final-overlay-not-part-of-game-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0016","file":"workflow/agendas/AGD-0016-asset-entry-metadata-normalization-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[{"id":"DEC-0004","file":"workflow/decisions/DEC-0004-asset-entry-metadata-normalization-contract.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-09"}],"plans":[],"lessons":[{"id":"LSN-0023","file":"lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"asset-load-asset-id-int-contract","title":"Asset Load Asset ID Int Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["asset","runtime","abi"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0019","file":"lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"workflow/agendas/AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"workflow/decisions/DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"workflow/plans/PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
View File
-51
View File
@@ -1,51 +0,0 @@
{"type":"meta","next_id":{"DSC":51,"AGD":54,"DEC":45,"PLN":176,"LSN":59,"CLSN":1}}
{"type":"discussion","id":"DSC-0050","status":"done","ticket":"headless-automation-host-hardening","title":"AGD-0052 Hardening — Headless Automation Host and Deterministic Runtime Control","created_at":"2026-09-22","updated_at":"2026-09-23","tags":["runtime","host","headless","automation","deterministic","concurrency","testing"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0058","file":"discussion/lessons/DSC-0050-headless-automation-host-hardening/LSN-0058-deterministic-observation-must-follow-the-active-producer.md","status":"done","created_at":"2026-09-23","updated_at":"2026-09-23"}]}
{"type":"discussion","id":"DSC-0049","status":"done","ticket":"headless-automation-host-and-deterministic-runtime-control","title":"Headless Automation Host and Deterministic Runtime Control","created_at":"2026-09-22","updated_at":"2026-09-22","tags":["runtime","host","headless","automation","testing","ai","deterministic","input","framebuffer","debugger"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0057","file":"discussion/lessons/DSC-0049-headless-automation-host-and-deterministic-runtime-control/LSN-0057-deterministic-host-control-follows-logical-runtime-boundaries.md","status":"done","created_at":"2026-09-22","updated_at":"2026-09-22"}]}
{"type":"discussion","id":"DSC-0044","status":"done","ticket":"hub-suspended-game-kill-affordance","title":"Hub Suspended Game Kill Affordance","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["hub","lifecycle","game","ui"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0054","file":"discussion/lessons/DSC-0044-hub-suspended-game-kill-affordance/LSN-0054-manual-hub-kill-must-share-game-termination-cleanup.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
{"type":"discussion","id":"DSC-0043","status":"done","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0053","file":"discussion/lessons/DSC-0043-system-os-cartridge-switch-orchestrator/LSN-0053-game-switching-is-lifecycle-replacement-not-loader-work.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
{"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}
{"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]}
{"type":"discussion","id":"DSC-0041","status":"done","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0041-foreground-stack-game-pause-shell-vm-backed/LSN-0052-foreground-ownership-and-vm-session-ownership-are-separate.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
{"type":"discussion","id":"DSC-0042","status":"done","ticket":"real-render-worker-establishment","title":"Real Render Worker Establishment","created_at":"2026-06-06","updated_at":"2026-06-20","tags":["runtime","renderer","worker","concurrency","host","hal","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0049","file":"discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md","status":"done","created_at":"2026-06-20","updated_at":"2026-06-20"}]}
{"type":"discussion","id":"DSC-0038","status":"done","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0038-render-frame-packet-boundary/LSN-0047-typed-render-submissions-preserve-domain-boundaries.md","status":"done","created_at":"2026-06-04","updated_at":"2026-06-04"}]}
{"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
{"type":"discussion","id":"DSC-0034","status":"done","ticket":"system-os-domain-facades","title":"Agenda - SystemOS Domain Facades","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","services","api-surface","lifecycle","fs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0034-system-os-domain-facades/LSN-0043-systemos-domain-facades.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-06-04","tags":["perf","runtime","telemetry"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-06-04","tags":["ci","jenkins","gitea"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0021","file":"discussion/lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-04-21","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md","status":"done","created_at":"2026-04-21","updated_at":"2026-04-21"}]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-09-22","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-09-22"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"done","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-07-03","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03"}]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-09-22","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-09-22"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-09-22","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-09-22"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0045","status":"open","ticket":"background-service-audio-execution","title":"Background Service and Audio Execution","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","service","audio","background","architecture"],"agendas":[{"id":"AGD-0048","file":"AGD-0048-background-service-audio-execution.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-06-04","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-07-01","tags":["perf","asset","fs","async","scheduler","runtime"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md","status":"done","created_at":"2026-07-01","updated_at":"2026-07-01"}]}
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0010-perf-host-desktop-frame-pacing-and-presentation/LSN-0036-frame-publication-and-host-invalidation-must-be-separate.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20"}]}
{"type":"discussion","id":"DSC-0011","status":"abandoned","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-06-28","tags":[],"agendas":[{"id":"AGD-0010","file":"AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"abandoned","created_at":"2026-03-27","updated_at":"2026-06-28","_override_reason":"User explicitly chose to remove this agenda because it no longer applies to the current render scenario; future optimizations can be discussed when needed."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to abandon this discussion because it no longer applies to the current render scenario; future optimizations can be discussed when needed."}
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-19","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0034","file":"discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19"}]}
{"type":"discussion","id":"DSC-0013","status":"done","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"scene-bank-and-viewport-cache-refactor","title":"Scene Bank and Viewport Cache Refactor","created_at":"2026-04-11","updated_at":"2026-04-14","tags":["gfx","tilemap","runtime","render"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0025-scene-bank-and-viewport-cache-refactor/LSN-0030-canonical-scene-cache-and-resolver-split.md","status":"done","created_at":"2026-04-14","updated_at":"2026-04-14"}]}
{"type":"discussion","id":"DSC-0026","status":"done","ticket":"render-all-scene-cache-and-camera-integration","title":"Integrate render_all with Scene Cache and Camera","created_at":"2026-04-14","updated_at":"2026-04-18","tags":["gfx","runtime","render","camera","scene"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0031","file":"discussion/lessons/DSC-0026-render-all-scene-cache-and-camera-integration/LSN-0031-frame-composition-belongs-above-the-render-backend.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
{"type":"discussion","id":"DSC-0027","status":"done","ticket":"frame-composer-public-syscall-surface","title":"Agenda - FrameComposer Public Syscall Surface","created_at":"2026-04-17","updated_at":"2026-04-18","tags":["gfx","runtime","syscall","abi","frame-composer","scene","camera","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0027-frame-composer-public-syscall-surface/LSN-0032-public-abi-must-follow-the-canonical-service-boundary.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
{"type":"discussion","id":"DSC-0028","status":"done","ticket":"deferred-overlay-and-primitive-composition","title":"Deferred Overlay and Primitive Composition over FrameComposer","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["gfx","runtime","render","frame-composer","overlay","primitives","hud"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0028-deferred-overlay-and-primitive-composition/LSN-0033-debug-primitives-should-be-a-final-overlay-not-part-of-game-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
{"type":"discussion","id":"DSC-0029","status":"done","ticket":"scene-bank-glyph-runtime-binding-leak","title":"Scene Bank Glyph Runtime Binding Leak","created_at":"2026-04-24","updated_at":"2026-04-24","tags":["gfx","runtime","asset","scene","glyph","format","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0038","file":"discussion/lessons/DSC-0029-scene-bank-glyph-runtime-binding-leak/LSN-0038-cold-scene-dependencies-must-bind-by-asset-identity.md","status":"done","created_at":"2026-04-24","updated_at":"2026-04-24"}]}
{"type":"discussion","id":"DSC-0014","status":"done","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0035","file":"discussion/lessons/DSC-0014-perf-vm-allocation-and-copy-pressure/LSN-0035-first-materialization-is-not-the-same-as-hot-path-copy-pressure.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20"}]}
{"type":"discussion","id":"DSC-0015","status":"abandoned","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[{"id":"AGD-0014","file":"AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"abandoned","created_at":"2026-03-27","updated_at":"2026-04-20","_override_reason":"User explicitly chose to close the discussion without decision because FS->memory copy for the program is already acceptable."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to abandon the discussion without creating a decision because FS->memory copy for the program is already acceptable."}
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-06-04","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"discussion/lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-06-04","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"asset-load-asset-id-int-contract","title":"Asset Load Asset ID Int Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["asset","runtime","abi"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0019","file":"discussion/lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-06-04","tags":["ci","jenkins"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0020","file":"discussion/lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0030","status":"done","ticket":"internal-viewport-270p","title":"Agenda - Internal Viewport 270p (480x270)","created_at":"2026-04-27","updated_at":"2026-04-28","tags":["gfx","runtime","viewport","resolution","frame-composer","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"discussion/lessons/DSC-0030-internal-viewport-270p/LSN-0039-resolution-baseline-changes-are-runtime-wide-contracts.md","status":"done","created_at":"2026-04-28","updated_at":"2026-04-28"}]}
{"type":"discussion","id":"DSC-0031","status":"done","ticket":"runtime-mode-separation-game-system","title":"Agenda - Runtime Mode Separation: Game and System","created_at":"2026-05-11","updated_at":"2026-05-14","tags":["runtime","firmware","hub","system-apps","game-mode","scheduler"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0031-runtime-mode-separation-game-system/LSN-0040-system-pipeline-separation.md","status":"done","created_at":"2026-05-14","updated_at":"2026-05-14"}]}
{"type":"discussion","id":"DSC-0032","status":"done","ticket":"system-os-lifecycle-process-task-contract","title":"Agenda - SystemOS Lifecycle, Process and Task Contract","created_at":"2026-05-14","updated_at":"2026-05-15","tags":["runtime","os","lifecycle","process","task","shell","firmware"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0041","file":"discussion/lessons/DSC-0032-system-os-lifecycle-process-task-contract/LSN-0041-systemos-lifecycle-authority.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
{"type":"discussion","id":"DSC-0033","status":"done","ticket":"system-os-service-ownership-and-module-layout","title":"Agenda - SystemOS Service Ownership and Module Layout","created_at":"2026-05-14","updated_at":"2026-05-15","tags":["runtime","os","services","module-layout","vm","window-manager","logging"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0033-system-os-service-ownership-and-module-layout/LSN-0042-systemos-service-ownership-boundary.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
{"type":"discussion","id":"DSC-0036","status":"done","ticket":"prometeu-hub-ui-direction","title":"Agenda - Prometeu Hub UI Direction","created_at":"2026-05-15","updated_at":"2026-05-22","tags":["hub","ui","shell","system-apps","lifecycle","design-system"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md","status":"done","created_at":"2026-05-22","updated_at":"2026-05-22"}]}
{"type":"discussion","id":"DSC-0037","status":"done","ticket":"rgba8888-framebuffer-and-pixel-format-direction","title":"Agenda - RGBA8888 Framebuffer and Pixel Format Direction","created_at":"2026-05-22","updated_at":"2026-05-23","tags":["gfx","framebuffer","rgb565","rgba8888","renderer","assets","host","backend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0037-rgba8888-framebuffer-and-pixel-format-direction/LSN-0046-pixel-format-contracts-must-move-as-one-surface.md","status":"done","created_at":"2026-05-23","updated_at":"2026-05-23"}]}
{"type":"discussion","id":"DSC-0046","status":"done","ticket":"runtime-owned-variable-glyph-bank-palette-protocol","title":"Runtime-Owned Variable Glyph Bank Palette Protocol","created_at":"2026-07-14","updated_at":"2026-07-14","tags":["runtime","gfx","assets","glyph-bank","palette-serialization","protocol"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0055","file":"discussion/lessons/DSC-0046-runtime-owned-variable-glyph-bank-palette-protocol/LSN-0055-runtime-owned-asset-protocols-must-align-payload-residency-and-lookup.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14"}]}
{"type":"discussion","id":"DSC-0047","status":"open","ticket":"portable-host-backend-strategy","title":"Portable Host Backend Strategy","created_at":"2026-07-14","updated_at":"2026-09-22","tags":["host","desktop","portable","sdl","backend","rendering","input","audio","linux","android","handheld"],"agendas":[{"id":"AGD-0050","file":"AGD-0050-portable-host-backend-strategy.md","status":"open","created_at":"2026-07-14","updated_at":"2026-09-22"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0048","status":"done","ticket":"corrigir-identificacao-formato-pbx","title":"Corrigir Identificacao do Formato PBX","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["runtime","bytecode","pbx","loader","format","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0056","file":"discussion/lessons/DSC-0048-corrigir-identificacao-formato-pbx/LSN-0056-runtime-artifact-identity-must-not-borrow-frontend-names.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
@@ -1,118 +0,0 @@
---
id: AGD-0002
ticket: packed-cartridge-loader-pmc
title: Agenda - Packed Cartridge Loader PMC
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - Packed Cartridge Loader PMC
## Problema
O loader reconhece a extensão `.pmc`, mas o caminho empacotado ainda nao existe de verdade.
Hoje o dispatcher aceita a intenção e delega para um loader que sempre falha com `InvalidFormat`.
## Dor
- A plataforma declara dois formatos de entrada, mas só um funciona.
- Distribuição real de cartuchos fica travada no layout de diretório.
- Host, firmware e ferramentas nao conseguem validar o caminho de distribuição final.
- O runtime continua dependente de estrutura de workspace em vez de artefato fechado.
## Alvo da Discussao
Definir o formato e o contrato do cartucho empacotado `.pmc` como artefato de distribuição do runtime.
O objetivo nao é só "descompactar um zip", e sim fixar:
- layout interno;
- regras de validação;
- limites de compatibilidade;
- superfície de erro;
- impacto em assinatura/versionamento futuro.
## O Que Precisa Ser Definido
1. Container.
O `.pmc` é zip, tar, formato próprio, ou envelope simples com header e blobs?
2. Estrutura interna.
Quais arquivos são obrigatórios e opcionais:
- `manifest.json`
- `program.pbx`
- `assets.pa`
- outros metadados
3. Regras de validação.
Ordem de parsing, integridade, presença de arquivos, tamanho máximo, duplicatas e versão suportada.
4. Política de compatibilidade.
Como o loader reage a versões futuras do container e do manifesto.
5. Segurança e determinismo.
Como impedir traversal, nomes ambíguos, arquivos extras maliciosos e dependência da ordem física do container.
6. Relação com o loader de diretório.
O comportamento validado deve ser idêntico entre diretório e `.pmc`, mudando apenas a origem dos bytes.
## O Que Necessita Para Resolver
- especificação mínima do container `.pmc`;
- decisão sobre biblioteca/abordagem de parsing;
- matriz de erros determinísticos;
- testes com cartuchos sintéticos válidos e inválidos;
- garantia de equivalência comportamental com o loader de diretório.
## Fora de Escopo
- compressão otimizada;
- assinatura criptográfica;
- distribuição incremental;
- pipeline completo do builder/packer.
## Critério de Saida Desta Agenda
Pode virar PR quando houver definição escrita de:
- formato do `.pmc`;
- arquivos obrigatórios;
- erros canônicos;
- invariantes de segurança;
- estratégia de testes de compatibilidade entre diretório e pacote;
- equivalência observável entre diretório e `.pmc` para qualquer host que use `CartridgeLoader`, incluindo o host desktop e o host headless de `AGD-0052`.
## Revalidação — 2026-09-22
Revalidada contra o código atual e contra `AGD-0052` / `DSC-0049` (Headless Automation Host and Deterministic Runtime Control). A agenda permanece aberta.
### O que permanece
`PackedCartridgeLoader::load` ainda retorna `CartridgeError::InvalidFormat` sem ler o arquivo. O dispatcher continua aceitando a extensão `.pmc` e delegando para esse stub. O loader de diretório é o caminho real: `manifest.json`, `program.pbx` e `assets.pa` quando a capability de asset exige. Boot direto (`BootTarget::Cartridge`) e o host desktop usam esse mesmo `CartridgeLoader`.
O problema original segue válido: a plataforma anuncia dois formatos e só o diretório funciona.
### Efeito da direção headless
`AGD-0052` coloca o host headless como consumidor novo do loader, e deixa o formato `.pmc` fora do primeiro ciclo. O primeiro boot automatizado usa cartucho de diretório, o mesmo artefato que o host desktop já carrega.
Consequências para esta agenda:
- headless, CI e agente não definem o container;
- quando `.pmc` existir, diretório e pacote precisam materializar o mesmo cartucho lógico, para o determinismo não depender da origem dos bytes;
- a ordem física do container continua impedida de alterar o resultado, como o item de segurança e determinismo já pedia;
- esta agenda não absorve captura de framebuffer, replay ou protocolo de automação.
### O que não mudou no critério
Formato, arquivos obrigatórios, erros canônicos, invariantes de segurança e testes de equivalência continuam sendo o fechamento. O critério de saída ganhou só a exigência de que essa equivalência valha para todo host do `CartridgeLoader`.
### Perguntas que continuam abertas
- [ ] O `.pmc` é zip, tar, formato próprio ou envelope com header e blobs?
- [ ] Quais entradas são obrigatórias além das que o loader de diretório já exige?
- [ ] Qual matriz de erro determinística substitui o `InvalidFormat` genérico do stub?
@@ -1,84 +0,0 @@
---
id: AGD-0004
ticket: system-fault-semantics-and-control-surface
title: Agenda - System Fault Semantics and Control Surface
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - System Fault Semantics and Control Surface
## Problema
O domínio `system` exposto à userland ficou pequeno, e a política de retorno dele ainda não está escrita.
Estado em 2026-09-22:
- a superfície gerada é só `system.has_cart` (`Syscall::SystemHasCart`), com 1 retorno e capability `SYSTEM`;
- o dispatch devolve `true` fixo, sem consultar cartucho e sem `status`;
- `system.run_cart` saiu da ABI de userland. Launch de cartucho é ação de SystemOS/firmware/host (`LSN-0051`, `DSC-0004`);
- fault de execução da VM já tem forma estruturada em `CrashReport` (`VmTrap`, `VmPanic`, `VmInit`), observada pelo host e pelo debugger.
O texto de 2026-03-27 tratava `SystemRunCart` como operação ainda sem efeito e apontava a agenda `009` e `virtual_machine_runtime/dispatch.rs`. Esses dois pontos ficaram obsoletos. A política de fault do que permanece no domínio `system` continua aberta.
## Dor
- `has_cart` pode permanecer um bool fixo e mascarar ausência, cartucho inválido ou consulta fora de autoridade;
- uma futura operação de `system` pode herdar `Trap` ou `Panic` onde o contrato transversal pede `status`;
- automação headless (`AGD-0052`) precisa observar fault estruturado sem que esta agenda redesenhe `CrashReport` nem invente syscall de controle para CI ou agente.
## Hotspots Atuais
- `crates/console/prometeu-hal/src/syscalls/domains/system.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` (`SystemHasCart` retorna `true`)
- `crates/console/prometeu-system/src/crash_report.rs`
- `docs/specs/runtime/16a-syscall-policies.md`
- `discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md`
## Alvo da Discussao
Fechar a política de fault e retorno do domínio `system` que ainda é visível à userland, e separar essa política da observação de fault de VM feita pelo host.
## O Que Precisa Ser Definido
1. Queries simples.
Decidir a política de `has_cart`: bool atual, `status` mais payload, ou outra forma compatível com `16a`. Incluir o que a consulta realmente observa.
2. Operações que não voltam para a userland.
`run_cart` permanece fora da ABI de convidado. Falha de boot direto continua no caminho de host/firmware (`CartridgeError`, `CrashReport::VmInit`, transição de firmware), não como syscall de app.
3. Relação com firmware e com o host.
Delimitar falha de app, falha de firmware e falha de runtime. `CrashReport` é a observação estruturada de Trap/Panic/init. `summary()` e log são apresentação, não o contrato.
## Dependencias
- `docs/specs/runtime/16a-syscall-policies.md`
- `LSN-0051` / `DSC-0004`
- `AGD-0052` / `DSC-0049`, apenas como consumidor da observação estruturada
## Critério de Saida Desta Agenda
Pode virar decision quando houver definição escrita sobre:
- matriz de `status` / `Trap` / `Panic` para as operações userland que o domínio `system` mantém, começando por `has_cart`;
- confirmação de que launch de cartucho permanece fora da ABI de convidado;
- fronteira entre retorno operacional de syscall, erro de loader/boot e `CrashReport`.
## Revalidação — 2026-09-22
Revalidada contra o código atual e contra `AGD-0052`. A agenda permanece aberta. O alvo encolheu: ela não reabre `run_cart`.
### O que a direção headless muda
`AGD-0052` exige que automação distinga execução em curso, pause, término, `Trap` e `Panic` lendo dados estruturados. Esse requisito observa `CrashReport` e o estado da VM. Ele não altera a semântica normativa de fault de outros domínios e não cria syscall `system` para controle headless.
Esta agenda continua dona da matriz de retorno de `system`. A agenda headless continua dona de como o host expõe o fault que já existe.
### Perguntas que continuam abertas
- [ ] `has_cart` passa a ter `status` e um significado real de presença de cartucho, ou o bool atual é o contrato e o stub `true` é o bug a corrigir em outra discussão?
- [ ] Alguma falha de boot direto precisa ser visível ao convidado, ou toda falha de launch permanece em host, firmware e `CrashReport`?
- [ ] Quais campos de `CrashReport` são o contrato observável (`kind`, `pc`, `trap.code`) e quais são só texto de log?
@@ -1,99 +0,0 @@
---
id: AGD-0005
ticket: vm-owned-random-service
title: Agenda - VM-Owned Random Service
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - VM-Owned Random Service
## Problema
Precisamos de random como primeiro consumidor stateful VM-owned, mas sem fechar um contrato minimo o dominio pode nascer incoerente e nao deterministico.
## Alvo da Discussao
Fechar o perfil minimo de random VM-owned em cima do core definido na decisao `006`.
## O Que Precisa Ser Definido
1. Surface minima do servico.
Fechar operacoes como:
- `new(seed) -> rng_ref`;
- `next(rng_ref) -> int`;
- `destroy(rng_ref)`.
2. Determinismo e replay.
Definir:
- seed explicita obrigatoria;
- regra de reproducao frame a frame;
- comportamento esperado em replay.
3. Lifecycle e validade.
Definir:
- como lidar com `rng_ref` invalido/stale;
- relacao com GC;
- destruicao explicita vs cleanup por GC.
4. Fault/status do dominio.
Definir:
- quais erros sao `status`;
- quais casos viram `Trap`;
- inexistencia de `Panic` operacional.
5. Metadados e versionamento.
Definir IDs/version das operacoes de random para garantir mapeamento 1:1 FE/backend/runtime.
## Open Questions de Arquitetura
1. O caminho determinístico aceita só seed explícita. Entropia de host, se um dia existir, é modo separado e fica fora da timeline automatizada?
2. `next` retorna apenas `int` ou precisamos variantes (`u32`, `float`) no mesmo ciclo?
3. precisamos de clone/split de gerador no MVP?
4. destruicao explicita deve ser obrigatoria para certificacao/custo ou opcional?
5. O primeiro oráculo de `AGD-0052` pode provar determinismo com cartucho que não chama random, e qualquer cartucho que chame random espera o fechamento desta agenda?
## Dependencias
- contexto histórico, já aposentado como decisão viva: `discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md` cita `006-vm-owned-stateful-core-contract.md`
- `docs/vm-arch/ISA_CORE.md`
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
- `docs/specs/runtime/16a-syscall-policies.md`
- `AGD-0052` / `DSC-0049`, como consumidor do contrato determinístico
Não há arquivo vivo em `discussion/workflow/decisions/` para a decisão `006`. Esta agenda não trata esse texto como contrato atual.
## Fora de Escopo
- entropia não determinística como contrato base;
- PRNGs múltiplos no mesmo ciclo de fechamento;
- APIs de coleções stateful;
- window/app model;
- formato persistente de replay. Esta agenda define reprodução em memória: seed explícita mais sequência de `next`. Arquivo, versão e timeline de input ficam para a agenda de replay citada por `AGD-0052`.
## Criterio de Saida Desta Agenda
Pode virar decision quando houver definição escrita sobre:
- surface mínima de random VM-owned;
- contrato de determinismo: seed explícita, ausência de entropia implícita de host, reprodução da sequência;
- fault/status de random;
- IDs/versionamento e validações de verifier para as operações do domínio;
- o que um host automatizado precisa fixar (seeds iniciais) para que duas execuções coincidam.
## Revalidação — 2026-09-22
Revalidada contra o código atual e contra `AGD-0052`. A agenda permanece aberta. Não existe serviço de random na VM. O scheduler declara ausência de randomness. `prometeu-test-support` oferece `StdRng` semeado para testes Rust; isso não é random de convidado.
### Efeito da direção headless
`AGD-0052` diz que random VM-owned usado em execução automatizada obedece ao contrato desta agenda, e que entropia implícita do host não entra no caminho determinístico. Isso reforça a pergunta 1 na direção de seed explícita como único modo determinístico.
O primeiro teste end-to-end headless pode usar um cartucho que não chama random. Esse teste prova input, frame e fault. Ele não prova random. Cartucho cujo resultado depende de random só serve como oráculo depois que esta agenda fechar seeds, sequência e faults.
Relógio de parede em telemetria (`host_cpu_time_us`, timestamp de certificação) não é fonte de random e não entra neste contrato.
Replay em arquivo continua fora daqui e fora do primeiro ciclo headless. O que esta agenda precisa deixar pronto é a reprodução em memória da sequência a partir das seeds.
@@ -1,157 +0,0 @@
---
id: AGD-0006
ticket: app-home-filesystem-surface-and-semantics
title: Agenda - App Home Filesystem Surface and Semantics
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - App Home Filesystem Surface and Semantics
## Problema
Apps precisam de filesystem util para dados de usuario, cache e configuracao, mas sem acesso ao FS inteiro do host.
Sem um contrato claro de `home` por app, a API tende a crescer com semantica inconsistente entre plataformas.
## Inputs Ja Fechados
1. Todo `app` acessa somente sua `home` logica.
2. Nunca ha acesso direto ao filesystem global do host pela userland.
3. O runtime `fs` interno continua cobrindo tanto `game` quanto `app`.
4. Existe uma async IO lane compartilhavel por assets, memcard e FS. Esta
agenda deve decidir a API publica de FS considerando essa lane, mas a
existencia da lane ja esta fechada por `DEC-0034`.
## Fronteira com a Async IO Lane
`DEC-0034` fecha a existencia de uma lane serial para trabalho async de IO. FS
pode consumir essa lane internamente para escrita, configuracao, leitura ou
listagem, conforme prioridade operacional definida pelo runtime.
Esta agenda continua dona da decisao sobre API publica de FS para `app home`.
Portanto, a existencia da lane nao implica criar agora request handles, polling
publico ou novas syscalls de FS. Esses shapes permanecem em aberto aqui.
## Alvo da Discussao
Fechar a superficie e semantica funcional de `fs` para perfil `app`, com sandbox por `app_id` e transporte de bytes via decisao `003`.
## O Que Precisa Ser Definido
1. Surface minima do perfil `app`.
Operacoes candidatas:
- `read`;
- `write`;
- `exists`;
- `stat`;
- `list_dir`;
- `delete`;
- `mkdir`;
- `rename`.
2. Modelo de caminho logico.
Definir:
- raiz virtual (`home`);
- normalizacao de path;
- bloqueio de path traversal;
- limites de profundidade/tamanho.
3. Mapeamento host.
Definir:
- como `home` vira caminho fisico no host;
- isolamento entre apps por `app_id`;
- regras de portabilidade entre hosts.
4. Semantica de leitura/escrita.
Definir:
- leitura total vs parcial;
- overwrite vs append;
- truncation;
- criacao implicita;
- escrita atomica por arquivo (quando aplicavel).
5. Quotas e capacidade.
Definir:
- se v1 tem quota por app;
- comportamento para `storage full`;
- exposicao de metrica de uso livre/ocupado.
6. Metadados e listagem.
Definir:
- campos minimos de `stat`;
- shape canonico de `list_dir`;
- timestamps (sim/nao e com qual garantia).
7. Fault/status do dominio.
Fechar fronteira de:
- `status` operacional;
- `Trap` estrutural;
- `Panic` interno.
E obrigatorio fechar, por operacao, a matriz final de retorno e fault class.
## Responsabilidade Absorvida da Agenda 003
No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para:
1. Catalogo de `status` de filesystem para app.
Minimo esperado:
- `OK`;
- `NOT_FOUND`;
- `PATH_INVALID`;
- `ACCESS_DENIED`;
- `NO_SPACE`;
- `ALREADY_EXISTS`;
- `UNAVAILABLE`.
2. Matriz por operacao (`read`, `write`, `exists`, `stat`, `list_dir`, `delete`, `mkdir`, `rename`).
Para cada caso, classificar explicitamente:
- `status`;
- `Trap`;
- `Panic`.
3. Shape de retorno por operacao.
Definir, no minimo:
- `status` como primeiro retorno;
- `bytes_transferred` em `read`/`write` quando aplicavel;
- payload de metadados/listagem com formato canonico.
4. Regra de escrita parcial.
`write` nao pode reportar sucesso parcial silencioso.
Quando a operacao nao puder ser concluida conforme contrato, deve retornar falha de dominio.
## Open Questions de Arquitetura
1. O v1 precisa de quota fixa por app ou apenas limites fisicos do host?
2. `rename` entra no MVP ou pode ficar para fase seguinte?
3. Qual conjunto minimo de metadados garante portabilidade real entre hosts?
4. Qual grau de atomicidade e obrigatorio para escrita de arquivo no v1?
5. Quais operacoes de FS devem consumir a async IO lane e quais permanecem
sincrono-aparentes para a userland?
## Dependencias
- `../decisions/003-vm-owned-byte-transfer-protocol.md`
- `../decisions/007-filesystem-fault-core-policy.md`
- `../specs/13-cartridge.md`
- `../specs/12-firmware-pos-and-prometeuhub.md`
- `../specs/16a-syscall-policies.md`
## Fora de Escopo
- slots de memcard para `game` (fechado na `spec 08`);
- acesso cross-app;
- sync remoto/cloud;
- DB embutido como contrato de plataforma.
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- surface minima de `fs` para `app` em `home`;
- sandbox e isolamento por `app_id`;
- semantica final de path/read/write/listagem;
- matriz completa de fault/status para as operacoes do perfil `app`.
@@ -1,208 +0,0 @@
---
id: AGD-0048
ticket: background-service-audio-execution
title: Agenda - Background Service and Audio Execution
status: open
created: 2026-07-05
resolved:
decision:
tags: [runtime, os, lifecycle, service, audio, background, architecture]
---
# Agenda - Background Service and Audio Execution
## Contexto
O runtime ja tem sinais claros de preparacao para multitarefa controlada:
- `TaskState::Background` existe como estado de tarefa;
- `VmSession` separa estado mutavel de VM por tarefa/processo;
- `SystemOS` e dono de lifecycle, task/process, VM sessions, filesystem,
memcard, windows e logging;
- a spec de eventos separa foreground ownership de execution eligibility;
- o contrato atual declara que execucao real em background fica fora do v1, mas
o modelo foi desenhado para permitir servicos ou processos de midia no futuro.
O caso motivador e:
```text
Game foreground -> Home -> music player -> escolher musica -> voltar ao Game
```
Depois disso, o Game deve voltar ao foreground enquanto o player continua
executando e produzindo audio junto com audio do Game.
## Problema
Hoje o runtime preserva sessoes, mas nao tem contrato para uma sessao continuar
executando quando nao e foreground.
Os pontos atuais que bloqueiam o caso:
- `TaskKind` so distingue `Game` e `Shell`;
- `ProcessKind` so distingue `VmGame`, `VmShell` e `NativeShell`;
- `ProcessState` nao possui estado normativo de background-running;
- `GameRunningStep` ticka apenas o Game foreground;
- `ShellRunningStep` ticka apenas o Shell foreground;
- `HubHomeStep` nao ticka sessoes VM em background;
- `Audio` e `AudioMixer` usam vozes globais sem namespace por tarefa/sessao;
- cada logical frame chama `platform.audio_mut().clear_commands()`, o que torna
perigoso tickar dois produtores de audio no mesmo frame;
- pausa de lifecycle hoje emite `MasterPause`, afetando o mixer inteiro.
Sem uma decisao, background service pode virar apenas "tickar mais uma VM", mas
isso quebraria isolamento, audio, debugger, lifecycle e previsibilidade.
## Pontos Criticos
1. **Execution eligibility nao e foreground.**
O contrato atual ja separa os conceitos, mas a implementacao ainda so ticka o
owner foreground. Precisamos introduzir uma politica explicita de quem pode
executar em background.
2. **Servico nao e Shell escondido.**
Um music player pode ter UI de Shell para escolher musica, mas a reproducao
continua como servico quando a UI deixa o foreground. Fechar isso como
`Shell` em background confundiria janela, tarefa, sessao e servico.
3. **Audio precisa de origem.**
Hoje `voice_id` e global no mixer. Se Game e player usam `voice_id = 0`, um
sobrescreve o outro. Precisamos decidir se o mixer tera namespaces por
`AudioOwner`, se servicos terao pool dedicado, ou se o player nao usara a
mesma superficie `audio.*`.
4. **Pausa de Game nao pode pausar servico de midia.**
`MasterPause` global serve para o contrato atual de pausa/debug, mas nao
expressa "pausar Game audio e manter music player". Pausa precisa virar
escopo por origem ou politica de mixer.
5. **Servico precisa de lifecycle proprio.**
Deve existir contrato para start, foreground UI, background-running, stop,
crash, terminate, recurso negado, e talvez wake/resume de UI.
6. **Budget e determinismo precisam ser fechados.**
Se servicos rodam junto com Game, precisamos decidir cota por frame, ordem de
ticks, starvation, crash isolation, e se background service participa do
mesmo tempo deterministico da maquina.
7. **Sistema de apps precisa descobrir e lancar o player.**
Hoje Home lista Game cartridges e tem Shells nativos fixos. O caso de music
player exige decidir se ele e cartridge `System`, app instalado, Shell nativo,
ou novo perfil `Service`.
## Opcoes
### Opcao A - Background Service como novo tipo de processo/sessao
Criar contrato explicito para `Service`:
- `TaskKind::Service` ou entidade equivalente;
- `ProcessKind::VmService` / `NativeService`;
- execution eligibility independente de foreground;
- UI de controle opcional via Shell task associada ao servico;
- audio com origem por service/session;
- lifecycle proprio: start, background, foreground-control, stop, crash.
**Pros:**
- modela diretamente music player e futuros servicos;
- preserva a separacao entre UI foreground e execucao;
- evita transformar Shell em "processo que tambem e daemon";
- facilita quotas, permissao e observabilidade.
**Contras:**
- maior mudanca arquitetural;
- exige novo contrato em specs, SystemOS, firmware, audio e testes;
- precisa fechar politica de recursos antes de implementar.
**Manutencao:**
- melhor base para crescer com qualidade, desde que o MVP seja pequeno.
### Opcao B - Shell em background com audio permitido
Permitir que uma VM Shell continue tickando quando sai do foreground e use audio
normalmente.
**Pros:**
- reaproveita Shell, WindowManager e VM session existentes;
- menor numero de novos tipos no curto prazo.
**Contras:**
- mistura UI e servico;
- torna `TaskState::Background` semantico antes de definir `ProcessState`;
- abre precedente para qualquer Shell continuar executando;
- nao resolve sozinho namespace de audio, pause por origem, quotas e debugging.
**Manutencao:**
- atraente como atalho, mas tende a espalhar excecoes pela firmware state
machine.
### Opcao C - Audio player como servico nativo OS-owned, sem VM background
Implementar music player como servico nativo de SystemOS, controlado por uma
Shell UI. A reproducao continua no host/OS sem tickar VM em background.
**Pros:**
- entrega o caso de musica com menor risco para scheduler VM;
- evita abrir execucao arbitraria de background agora;
- audio service pode ser projetado como recurso OS-owned e depois exposto.
**Contras:**
- nao resolve background VM services em geral;
- player deixa de ser app userland completo no primeiro ciclo;
- precisa ainda fechar origem/mixagem de audio e relacao com UI.
**Manutencao:**
- bom MVP se o objetivo imediato for media playback, mas deve ser declarado como
`media service` nativo, nao como contrato geral de background VM.
## Sugestao / Recomendacao
Recomendo fechar em duas camadas:
1. **Decisao de arquitetura:** introduzir o conceito de service/background
execution como contrato de SystemOS, separado de foreground Shell e Game.
Essa decisao deve definir execution eligibility, lifecycle, quotas, crash
policy, controle de UI e relacao com VM sessions.
2. **MVP de media:** implementar primeiro um `media/audio service` com escopo
reduzido, preferencialmente OS-owned ou `Service` bem delimitado, antes de
permitir background VM arbitrario.
Para excelente qualidade, o primeiro plano nao deve tentar "qualquer app em
background". O alvo deve ser: um unico servico de audio/midia, com origem de
audio propria, controle por Hub/Shell, execucao enquanto Game esta foreground,
e testes end-to-end de mistura e lifecycle.
## Perguntas em Aberto
- O music player deve ser um cartridge `System`, um novo `Service`, ou um
servico nativo do OS controlado por Shell?
- A UI do player e a reproducao pertencem a mesma tarefa ou a tarefas
separadas?
- Um servico pode ter janela foreground temporaria e continuar sem janela?
- Quantos servicos background podem existir no MVP: um media service ou N
servicos?
- O background service recebe ticks todo frame, tick rate reduzido, ou apenas
eventos?
- O audio mixer deve isolar vozes por `TaskId`, `ProcessId`, `VmSessionId`,
`AppId`, ou novo `AudioOwner`?
- Como pausar apenas o audio do Game durante Home/debug sem pausar musica?
- O debugger inspeciona foreground session apenas ou tambem sessoes background?
- Como crash de servico e exibido: toast/log, janela de crash, ou parada
silenciosa com diagnostico?
- Que capacidades sao necessarias para media service: `audio`, `fs`, `asset`,
talvez `background_audio`?
## Criterio para Encerrar
Esta agenda pode virar decisao quando houver resposta escrita para:
- modelo de entidade (`Service` novo vs Shell background vs native OS service);
- execution eligibility e ordem de ticks;
- lifecycle e estados de task/process;
- ownership/namespace de audio e politica de pausa por origem;
- relacao entre UI foreground do player e reproducao background;
- escopo do MVP e explicitamente o que fica fora;
- testes obrigatorios de lifecycle, audio mixing, crash isolation e regressao do
contrato Game/Home/Shell existente.

Some files were not shown because too many files have changed in this diff Show More