17 Commits
Author SHA1 Message Date
bquarkz 2d5735cb13 chore: retire Discussion Framework workflow and retain lessons
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-11-16 16:45:34 +00:00
bquarkz dccf4d0775 fix(ci): declare llvm-tools-preview in pinned toolchain
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-11-16 10:00:49 +00:00
bquarkz c3589be1ad fix(headless): wait for memcard bootstrap IO progress
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
Coordinate bounded native publication progress during frame advance while preserving watchdogs, guest budgets and resource ownership. Add controlled and packaged reopen regressions, clarify the runtime specs, and retain qualification evidence.
2026-11-10 23:26:40 +00:00
bquarkz 49d7fca0b7 chore(toolchain): pin Rust to 1.98.1
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
2026-11-10 22:39:19 +00:00
bquarkz c649e02816 feat(headless): expose negotiated native log observation 2026-11-10 21:57:34 +00:00
bquarkz 09d8778f04 fix(runtime): support older stable Rust atomic updates
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-11-05 09:00:19 +00:00
bquarkz 1aa939eca8 fix(runtime): replace deprecated atomic fetch_update calls
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
2026-11-03 00:01:58 +00:00
bquarkz a4bec5bc45 feat(host): expose memcard controls and qualify process persistence
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-10-30 10:10:07 +00:00
bquarkz dcf6561ea7 refactor(vm)!: remove publication and logical guard opcodes
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Remove INDEX_GUARD, ARRAY_CHECK_LENGTH, STORAGE_PUBLISH and FIELDS_PUBLISH
from decoding, metadata, tooling, verification and execution. Keep ARRAY_LEN
and overlap-safe ARRAY_COPY with complete-group ownership and early charging
of calculable copy work, including refused attempts.

Update specifications, producer handoff, qualification evidence and lessons.
Share collection test support and remove redundant Copy clones for Clippy.

Validation: make ci-domains passed with 1,095 workspace tests, five separately
executed debugger socket tests and all 15 unchanged coverage domain gates.
VM release, resource diagnostics and layer/quality suites also passed.

BREAKING CHANGE: PBX using opcodes 0xA7, 0xA8, 0xAA or 0xAB is rejected,
including unreachable instructions. Consumers must adapt their emission and
collection algorithms or operational guarantees.
2026-10-23 23:37:56 +01:00
bquarkz 69ad1931de feat(vm): add reference identity and deterministic value hashing 2026-10-23 14:29:00 +01:00
Nilton Constantino 57992cf214 feat(vm): publish typed fields across multiple structs atomically
Add schema-driven FIELDS_PUBLISH without collection-specific runtime behavior. Validate every nullable destination and complete field group before allocation-free publication, with neutral ownership, malformed-input and quota coverage.
2026-10-23 09:53:40 +01:00
bquarkz d9b9eeb171 Add generic logical guards and atomic storage publication 2026-10-22 22:24:28 +01:00
bquarkz f7d7c16753 docs: include Random in registry handoff builtin list
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-10-14 15:04:07 +01:00
bquarkz 07b69314b1 Merge pull request 'Dev/runtime improvements for games' (#42) from dev/runtime-improvements-for-games into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #42
2026-10-14 13:58:56 +00:00
bquarkz 4669ced98e fix(ci): accept installed llvm-tools component name
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-10-14 14:43:09 +01:00
bquarkz a2275932a5 Keep PBX at v0 and simplify Jenkins quality gate
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
2026-10-14 14:35:44 +01:00
bquarkz 39468740c3 docs: close runtime quality review with consolidated lesson
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
2026-10-14 14:24:14 +01:00
181 changed files with 17931 additions and 750 deletions
+5 -5
View File
@@ -13,14 +13,15 @@ jobs:
with:
submodules: recursive
- uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt, clippy, llvm-tools-preview
- name: Install repository Rust toolchain
run: |
toolchain=$(python3 -c 'import tomllib; print(tomllib.load(open("rust-toolchain.toml", "rb"))["toolchain"]["channel"])')
rustup toolchain install "$toolchain" --profile minimal
- uses: Swatinem/rust-cache@v2
- name: Discard reports from previous runs
run: rm -rf target/quality-gate target/llvm-cov
run: rm -rf target/llvm-cov
- name: Provision quality-gate tools and native dependencies
run: bash scripts/provision-quality-gate.sh
@@ -34,6 +35,5 @@ jobs:
with:
name: quality-gate-${{ runner.os }}-${{ github.sha }}
path: |
target/quality-gate/**
target/llvm-cov/**
if-no-files-found: warn
-4
View File
@@ -66,7 +66,3 @@ AGENTS.md
.python-version
.venv
discussion/*
!discussion/lessons/
!discussion/lessons/**
+5 -7
View File
@@ -1,4 +1,4 @@
.PHONY: fmt fmt-check clippy test-local test-debugger-socket clean coverage coverage-xml coverage-json coverage-report-json coverage-domain-list coverage-domain-evidence coverage-domain-audit coverage-domain-gate test ci ci-domains test-quality-gate cobertura
.PHONY: fmt fmt-check clippy test-local test-debugger-socket clean coverage coverage-xml coverage-json coverage-report-json coverage-domain-list coverage-domain-evidence coverage-domain-audit coverage-domain-gate test ci ci-domains cobertura
fmt:
cargo fmt --all
@@ -47,14 +47,12 @@ coverage-domain-gate:
./scripts/coverage-domain-evidence.sh --check-all
test: fmt-check clippy test-local test-debugger-socket
# Keep the step list here: CI providers consume the repository contract.
# The runner executes each step serially even if the caller supplies make -j.
CI_DOMAIN_STEPS = clean fmt-check clippy test-quality-gate test-local test-debugger-socket coverage coverage-report-json coverage-xml coverage-json coverage-domain-audit coverage-domain-gate
# Local and GitHub entry point; Jenkins exposes the same targets as stages.
CI_DOMAIN_STEPS = clean fmt-check clippy test-local test-debugger-socket coverage coverage-report-json coverage-xml coverage-json coverage-domain-audit coverage-domain-gate
ci: ci-domains
ci-domains:
python3 scripts/run-quality-gate.py $(CI_DOMAIN_STEPS)
rm -rf target/llvm-cov
+@set -e; for step in $(CI_DOMAIN_STEPS); do $(MAKE) --no-print-directory -j1 $$step; done
test-quality-gate:
python3 -B -m unittest discover -s scripts/tests -p 'test_quality_gate.py'
cobertura: coverage-xml coverage-json
+20 -7
View File
@@ -1,14 +1,14 @@
# PROMETEU Runtime
PROMETEU is an educational and experimental fantasy handheld / fantasy console.
This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, firmware/system services, host integration, CLI entrypoints, development utilities, specs, and discussion artifacts.
This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, firmware/system services, host integration, CLI entrypoints, development utilities, specs, and engineering lessons.
The VM is only one subsystem of the machine. The canonical docs in this repository intentionally distinguish:
- machine-level specs;
- VM/runtime internal architecture;
- implementation crates;
- discussion workflow and lessons learned.
- engineering lessons learned.
## What This Repository Contains
@@ -19,7 +19,7 @@ The VM is only one subsystem of the machine. The canonical docs in this reposito
- `docs/specs/runtime/`: canonical PROMETEU machine specs
- `docs/vm-arch/`: canonical VM/runtime architecture and ISA references
- `devtools/`: debugger protocol material
- `discussion/`: agendas, decisions, plans, and lessons for architectural work
- `discussion/lessons/`: published engineering lessons and supporting assets
- `test-cartridges/`: cartridge fixtures used for validation and manual runs
## Canonical Documentation
@@ -29,7 +29,11 @@ Use these entrypoints instead of inferring the model from isolated source files:
- [Machine specs](docs/specs/runtime/README.md): authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI
- [VM architecture](docs/vm-arch/ARCHITECTURE.md): authoritative internal architecture for VM/runtime invariants
- [ISA reference](docs/vm-arch/ISA_CORE.md): bytecode-level instruction set authority
- [Discussion workflow](discussion/index.ndjson): architectural agenda, decision, and execution traceability
- [Engineering lessons](discussion/lessons/): published results and rationale
Engineering discussions, decisions, plans and execution evidence are maintained in
the enclosing [Prometeu Engineering workspace](../README.md) using
[AI Engineering](../.ai-engineering/README.md).
## Workspace Layout
@@ -60,11 +64,21 @@ Other ecosystem commands, such as build, pack, and verification tooling, are not
## Requirements
- Rust toolchain from [rust-toolchain.toml](rust-toolchain.toml)
- Rust **1.98.1**, pinned in [rust-toolchain.toml](rust-toolchain.toml)
- `rustup` for toolchain installation and management
- `cargo-llvm-cov` for coverage targets such as `make coverage` and `make ci-domains`
- a local graphical environment for desktop runtime commands
From the repository root, install and verify the pinned toolchain:
```bash
rustup toolchain install 1.98.1 --profile minimal --component rustfmt,clippy
rustc --version
```
Rustup selects the pinned version automatically for commands run in this repository.
CI installs the toolchain from the same file.
## Quick Start
Build the workspace:
@@ -145,7 +159,6 @@ This produces:
- `target/llvm-cov/report.json`
- `target/llvm-cov/summary.json`
- `target/llvm-cov/cobertura.xml`
- `target/quality-gate/metadata.json` and per-step logs
Domain-oriented evidence helpers:
@@ -174,7 +187,7 @@ Improving the global percentage alone is not sufficient review evidence when the
The project is still in active architectural and implementation convergence.
- the machine contract is being clarified through the specs and discussion workflow;
- the machine contract is being clarified through the specs and AI Engineering;
- the workspace already contains concrete runtime and host code;
- the CLI dispatcher currently exposes the runtime paths that are backed by binaries in this workspace.
@@ -179,7 +179,7 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u16(CoreOpCode::Ret as u16, &mut out);
}
"YIELD" | "SLEEP" | "SPAWN" => {
return Err(AsmError::InvalidOperand("retired coroutine instruction".into()))
return Err(AsmError::InvalidOperand("retired coroutine instruction".into()));
}
"FRAME_SYNC" => {
emit_u16(CoreOpCode::FrameSync as u16, &mut out);
@@ -345,7 +345,7 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u32(ty, &mut out);
emit_u32(field, &mut out);
}
"STRUCT_NEW" | "ARRAY_NEW" | "ARRAY_LEN" | "ARRAY_GET" | "ARRAY_SET" => {
"STRUCT_NEW" | "ARRAY_NEW" | "ARRAY_LEN" | "ARRAY_GET" | "ARRAY_SET" | "ARRAY_COPY" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
@@ -354,23 +354,32 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
"ARRAY_NEW" => CoreOpCode::ArrayNew,
"ARRAY_LEN" => CoreOpCode::ArrayLen,
"ARRAY_GET" => CoreOpCode::ArrayGet,
"ARRAY_COPY" => CoreOpCode::ArrayCopy,
_ => CoreOpCode::ArraySet,
};
emit_u16(op as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"DYN_PACK" | "DYN_UNPACK" | "DYN_CAN_UNPACK" => {
"DYN_PACK" | "DYN_UNPACK" | "DYN_CAN_UNPACK" | "REF_IDENTITY_HASH" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let opcode = match mn {
"DYN_PACK" => CoreOpCode::DynPack,
"DYN_UNPACK" => CoreOpCode::DynUnpack,
"REF_IDENTITY_HASH" => CoreOpCode::RefIdentityHash,
_ => CoreOpCode::DynCanUnpack,
};
emit_u16(opcode as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"REF_IDENTITY_EQ" => {
let (a, b) = parse_keyvals(ops)?;
let (left, right) = parse_pair(a, "left", b, "right")?;
emit_u16(CoreOpCode::RefIdentityEq as u16, &mut out);
emit_u32(left, &mut out);
emit_u32(right, &mut out);
}
"REF_IS_EXACT" | "REF_IMPLEMENTS" | "REF_TO_TRAIT" | "REF_CAST" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
@@ -65,12 +65,14 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
| CoreOpCode::Hostcall
| CoreOpCode::DynPack
| CoreOpCode::DynUnpack
| CoreOpCode::RefIdentityHash
| CoreOpCode::DynCanUnpack
| CoreOpCode::StructNew
| CoreOpCode::ArrayNew
| CoreOpCode::ArrayLen
| CoreOpCode::ArrayGet
| CoreOpCode::ArraySet => {
| CoreOpCode::ArraySet
| CoreOpCode::ArrayCopy => {
let v = u32::from_le_bytes(imm.try_into().unwrap());
format!("{}", v)
}
@@ -79,6 +81,11 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
let field = u32::from_le_bytes(imm[4..].try_into().unwrap());
format!("type={}, field={}", ty, field)
}
CoreOpCode::RefIdentityEq => {
let left = u32::from_le_bytes(imm[..4].try_into().unwrap());
let right = u32::from_le_bytes(imm[4..].try_into().unwrap());
format!("left={}, right={}", left, right)
}
CoreOpCode::RefIsExact
| CoreOpCode::RefImplements
| CoreOpCode::RefToTrait
@@ -1,4 +1,4 @@
//! Shared PBX v1 resource limits and structured validation failures.
//! Shared PBX v0 resource limits and structured validation failures.
//! Counters are deterministic; a failed reservation never changes usage.
use serde::{Deserialize, Serialize};
use std::fmt;
@@ -192,6 +192,10 @@ pub enum OpCode {
RefToTrait = 0x95,
/// REF_CAST: source:TypeId, target:TypeId; requires validated Registry metadata.
RefCast = 0x96,
/// Query a complete typed reference identity; source TypeId.
RefIdentityHash = 0x97,
/// Compare two complete typed references; left/right TypeIds.
RefIdentityEq = 0x98,
// Registry-backed collection operations. cycles() is their base component.
StructNew = 0xA0,
@@ -201,6 +205,8 @@ pub enum OpCode {
ArrayLen = 0xA4,
ArrayGet = 0xA5,
ArraySet = 0xA6,
/// Complete stored groups, overlap-safe; Array TypeId:u32.
ArrayCopy = 0xA9,
}
impl TryFrom<u16> for OpCode {
@@ -267,6 +273,8 @@ impl TryFrom<u16> for OpCode {
0x94 => Ok(OpCode::RefImplements),
0x95 => Ok(OpCode::RefToTrait),
0x96 => Ok(OpCode::RefCast),
0x97 => Ok(OpCode::RefIdentityHash),
0x98 => Ok(OpCode::RefIdentityEq),
0xA0 => Ok(OpCode::StructNew),
0xA1 => Ok(OpCode::StructGet),
0xA2 => Ok(OpCode::StructSet),
@@ -274,6 +282,7 @@ impl TryFrom<u16> for OpCode {
0xA4 => Ok(OpCode::ArrayLen),
0xA5 => Ok(OpCode::ArrayGet),
0xA6 => Ok(OpCode::ArraySet),
0xA9 => Ok(OpCode::ArrayCopy),
_ => Err(format!("Invalid OpCode: 0x{:04X}", value)),
}
@@ -344,6 +353,8 @@ impl OpCode {
OpCode::RefImplements => 4,
OpCode::RefToTrait => 5,
OpCode::RefCast => 4,
OpCode::RefIdentityHash => 8,
OpCode::RefIdentityEq => 4,
OpCode::StructNew => 8,
OpCode::StructGet => 3,
OpCode::StructSet => 4,
@@ -351,6 +362,7 @@ impl OpCode {
OpCode::ArrayLen => 3,
OpCode::ArrayGet => 3,
OpCode::ArraySet => 4,
OpCode::ArrayCopy => 4,
}
}
}
@@ -596,6 +596,26 @@ impl OpCodeSpecExt for OpCode {
may_trap: true,
is_safepoint: false,
},
OpCode::RefIdentityHash => OpcodeSpec {
name: "REF_IDENTITY_HASH",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefIdentityEq => OpcodeSpec {
name: "REF_IDENTITY_EQ",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::StructNew => OpcodeSpec {
name: "STRUCT_NEW",
imm_bytes: 4,
@@ -666,6 +686,16 @@ impl OpCodeSpecExt for OpCode {
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayCopy => OpcodeSpec {
name: "ARRAY_COPY",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::FrameSync => OpcodeSpec {
name: "FRAME_SYNC",
imm_bytes: 0,
@@ -52,6 +52,19 @@ pub enum TypeKind {
Trait(Vec<MethodDecl>),
Fn(Signature),
}
impl TypeKind {
/// Categories supported by identity queries, not by legacy REF_* conversions.
pub fn is_identity_reference(&self) -> bool {
matches!(
self,
Self::Struct(_)
| Self::Array(_)
| Self::Fn(_)
| Self::Trait(_)
| Self::Builtin(BuiltinId::RANDOM)
)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TypeDecl {
pub name: Option<String>,
@@ -1,4 +1,4 @@
//! Strict PBX v1 envelope and Registry sections. No legacy fallback.
//! Strict PBX v0 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::{
@@ -32,7 +32,7 @@ impl<'a> PbxEnvelope<'a> {
if &bytes[..4] != b"PBX\0" {
return Err(E::new(C::InvalidFormat, R::Magic));
}
if bytes[4..6] != [1, 0] {
if bytes[4..6] != [0, 0] {
return Err(E::new(C::UnsupportedFormat, R::Version));
}
if bytes[6] != 0 {
@@ -314,14 +314,14 @@ impl<'a, 'b> Reader<'a, 'b> {
}
}
/// Raw section input for a v1 envelope writer. Non-Registry section bytes must
/// Raw section input for a v0 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.
/// Assemble strict v0 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; 9];
@@ -349,7 +349,7 @@ pub fn encode_envelope(sections: &[SectionData<'_>], b: &mut LoadBudget) -> Resu
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(&[0, 0, 0, 0]);
out.extend_from_slice(&(count as u32).to_le_bytes());
out.extend_from_slice(&[0; 20]);
let mut offset = directory_end;
@@ -6,7 +6,7 @@ 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
/// Owned, bounded PBX v0 tables for the executable loader. This is not an
/// executable image: bindings and instruction/type verification are still due.
#[derive(Debug)]
pub struct OwnedPbx {
@@ -1,5 +1,5 @@
//! Producer-side serialization of a complete typed module. This writer emits
//! only v1; executable consumers still need bindings and code verification.
//! only v0; executable consumers still need bindings and code verification.
use super::*;
use crate::load_limits::IdDomain;
use crate::model::{ConstantPoolEntry, DebugInfo, Export, SyscallDecl};
@@ -86,7 +86,7 @@ impl DecodedInstr<'_> {
)
}
Op::GetCapture => {
return Err(LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex))
return Err(LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex));
}
Op::CallTrait => {
let (ty, method) = self.imm_u32x2().map_err(|_| malformed())?;
@@ -133,6 +133,29 @@ impl DecodedInstr<'_> {
};
(source_layout.storage.slots, pushes)
}
Op::RefIdentityHash | Op::RefIdentityEq => {
let (left, right) = if self.opcode == Op::RefIdentityHash {
(self.imm_u32().map_err(|_| malformed())?, None)
} else {
let (a, b) = self.imm_u32x2().map_err(|_| malformed())?;
(a, Some(b))
};
let mut pops = 0;
for id in std::iter::once(left).chain(right) {
let (decl, layout) = type_info(id)?;
if !decl.kind.is_identity_reference() {
return Err(bad_category(id));
}
pops += layout.storage.slots;
}
(pops, 1)
}
Op::ArrayCopy => {
let array = self.imm_u32().map_err(|_| malformed())?;
let (_, layout) = type_info(array)?;
layout.array.ok_or_else(|| bad_category(array))?;
(5, 0)
}
Op::StructNew
| Op::StructGet
| Op::StructSet
@@ -34,6 +34,8 @@ fn all_typed_instructions_match_independent_bytes_and_costs() {
("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),
("REF_IDENTITY_HASH 16909060", &[0x97, 0, 4, 3, 2, 1], 8),
("REF_IDENTITY_EQ left=16909060, right=84281096", &[0x98, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
];
for &(text, bytes, cycles) in cases {
assert_eq!(assemble(text).unwrap(), bytes);
@@ -49,8 +51,8 @@ fn all_typed_instructions_match_independent_bytes_and_costs() {
}
}
assert!(matches!(
decode_next(0, &[0x97, 0]),
Err(DecodeError::UnknownOpcode { opcode: 0x97, .. })
decode_next(0, &[0x99, 0]),
Err(DecodeError::UnknownOpcode { opcode: 0x99, .. })
));
}
#[test]
@@ -68,6 +70,8 @@ fn slot_effects_resolve_semantic_widths_and_reference_categories() {
("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),
("REF_IDENTITY_HASH 6", 2, 1),
("REF_IDENTITY_EQ left=6, right=4", 3, 1),
] {
let bytes = assemble(text).unwrap();
assert_eq!(
@@ -94,6 +98,9 @@ fn invalid_type_immediates_are_contextual_load_errors() {
"REF_IS_EXACT source=4, target=6",
"REF_TO_TRAIT source=4, target=0",
"REF_IMPLEMENTS source=0, target=6",
"REF_IDENTITY_HASH 0",
"REF_IDENTITY_HASH 3",
"REF_IDENTITY_EQ left=4, right=1",
] {
let bytes = assemble(text).unwrap();
let e = decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap_err();
@@ -114,6 +121,10 @@ fn assembler_rejects_missing_overflowing_or_ambiguous_type_ids() {
"REF_CAST source=4",
"REF_CAST source=4, target=5, target=6",
"REF_CAST source=4, trait=6",
"REF_IDENTITY_HASH",
"REF_IDENTITY_HASH -1",
"REF_IDENTITY_EQ left=4",
"REF_IDENTITY_EQ left=4, target=5",
] {
assert!(assemble(text).is_err(), "{text}");
}
@@ -204,3 +215,62 @@ fn collection_effects_and_cached_initialization_width_are_exact() {
);
}
}
#[test]
fn removed_storage_encodings_and_mnemonics_are_unsupported() {
for opcode in [0xa7u16, 0xa8, 0xaa, 0xab] {
assert!(Op::try_from(opcode).is_err());
let bytes = opcode.to_le_bytes();
assert!(
matches!(decode_next(0,&bytes),Err(DecodeError::UnknownOpcode{pc:0,opcode: actual}) if actual == opcode)
);
assert!(disassemble(&bytes).is_err());
}
for text in
["INDEX_GUARD", "ARRAY_CHECK_LENGTH 1", "STORAGE_PUBLISH 1,2,0,1", "FIELDS_PUBLISH 1"]
{
assert!(assemble(text).is_err(), "{text}");
}
}
#[test]
fn range_copy_encoding_effects_and_registry_categories_are_independent_oracles() {
let bytes = [0xa9, 0, 4, 3, 2, 1];
assert_eq!(assemble("ARRAY_COPY 16909060").unwrap(), bytes);
assert_eq!(disassemble(&bytes).unwrap(), "ARRAY_COPY 16909060");
let instruction = decode_next(0, &bytes).unwrap();
assert_eq!(instruction.opcode, Op::ArrayCopy);
assert_eq!(instruction.opcode.cycles(), 4);
let spec = instruction.opcode.spec();
assert_eq!((spec.imm_bytes, spec.pops, spec.pushes), (4, None, None));
assert!(instruction.opcode.requires_registry() && spec.may_trap);
assert!(!spec.is_safepoint && !spec.is_branch && !spec.is_terminator);
for end in 0..6 {
assert!(decode_next(0, &bytes[..end]).is_err());
}
let registry = registry();
let bytes = assemble("ARRAY_COPY 5").unwrap();
assert_eq!(
decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap(),
Some(RegistryStackEffect { pops: 5, pushes: 0 })
);
for (id, reason) in [
(0, LoadReason::Category),
(4, LoadReason::Category),
(6, LoadReason::Category),
(99, LoadReason::TypeId),
] {
let bytes = assemble(&format!("ARRAY_COPY {id}")).unwrap();
let error = decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap_err();
assert_eq!(
(error.code, error.reason, error.pc),
(LoadCode::InvalidReference, reason, Some(0))
);
}
for text in ["ARRAY_COPY", "ARRAY_COPY -1", "ARRAY_COPY 4294967296", "ARRAY_COPY 1 2"] {
assert!(assemble(text).is_err());
}
// These are legal immediate bytes, not instruction boundaries.
let bytes = assemble("PUSH_I64 18735214094965159\nHALT").unwrap();
assert!(disassemble(&bytes).is_ok());
}
@@ -172,7 +172,7 @@ fn hex(s: &str) -> Vec<u8> {
// syscalls=168/4, types=172/10, implementations=182/4, captures=186/8. Total=194.
fn minimal_bytes() -> Vec<u8> {
hex("
50 42 58 00 01 00 00 00 08 00 00 00
50 42 58 00 00 00 00 00 08 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 80 00 00 00 04 00 00 00
01 00 00 00 84 00 00 00 1e 00 00 00
@@ -241,7 +241,7 @@ fn writer_matches_independent_minimal_envelope() {
}
#[test]
fn owned_v1_decoder_accepts_independent_bytes_without_publishing_an_image() {
fn owned_v0_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());
@@ -536,7 +536,7 @@ fn every_truncated_envelope_is_rejected_without_panic() {
fn envelope_mutations_have_typed_reasons() {
for (offset, value, code, reason) in [
(0, 0, LoadCode::InvalidFormat, LoadReason::Magic),
(4, 0, LoadCode::UnsupportedFormat, LoadReason::Version),
(4, 1, LoadCode::UnsupportedFormat, LoadReason::Version),
(6, 1, LoadCode::InvalidFormat, LoadReason::Endianness),
(7, 1, LoadCode::InvalidFormat, LoadReason::Reserved),
(31, 1, LoadCode::InvalidFormat, LoadReason::Reserved),
+14 -3
View File
@@ -13,7 +13,8 @@ fn io_error(e: std::io::Error) -> Error {
use std::io::ErrorKind as K;
match e.kind() {
K::NotFound => Error::Unavailable,
K::PermissionDenied => Error::ReadOnly,
K::PermissionDenied => Error::AccessDenied,
K::AlreadyExists => Error::AlreadyExists,
K::StorageFull => Error::NoSpace,
K::InvalidInput | K::UnexpectedEof => Error::InvalidRange,
K::Unsupported => Error::Unsupported,
@@ -21,8 +22,15 @@ fn io_error(e: std::io::Error) -> Error {
}
}
impl FileMemcard {
fn lock(file: &File) -> Result<(), Error> {
file.try_lock().map_err(|error| match error {
std::fs::TryLockError::WouldBlock => Error::Busy,
std::fs::TryLockError::Error(error) => io_error(error),
})
}
pub fn open(path: &Path, read_only: bool) -> Result<Self, Error> {
let file = OpenOptions::new().read(true).write(!read_only).open(path).map_err(io_error)?;
Self::lock(&file)?;
let length = file.metadata().map_err(io_error)?.len();
Ok(Self { file, length, read_only })
}
@@ -47,7 +55,9 @@ impl FileMemcard {
.create_new(true)
.open(&temporary)
.map_err(io_error)?;
let mut published = false;
let result = (|| {
Self::lock(&file)?;
let mut card = Self { file, length, read_only: false };
let zeros = [0u8; 65_536];
let mut offset = 0;
@@ -64,6 +74,7 @@ impl FileMemcard {
card.sync()?;
// hard_link publishes without replacing a user file; parent sync makes the name durable.
std::fs::hard_link(&temporary, path).map_err(io_error)?;
published = true;
File::open(parent).and_then(|f| f.sync_all()).map_err(io_error)?;
Ok(card)
})();
@@ -71,10 +82,10 @@ impl FileMemcard {
std::fs::remove_file(&temporary).and_then(|()| File::open(parent)?.sync_all());
match result {
Ok(card) => {
cleanup.map_err(io_error)?;
cleanup.map_err(|_| Error::Indeterminate)?;
Ok(card)
}
Err(e) => Err(e),
Err(e) => Err(if published { Error::Indeterminate } else { e }),
}
}
#[cfg(not(unix))]
@@ -18,6 +18,8 @@ impl ControlledWallClock {
}
/// Advance civil time explicitly, saturating at the largest timestamp.
// `try_update` requires Rust 1.95; keep older stable CI toolchains compatible.
#[allow(deprecated)]
pub fn advance(&self, seconds: u64) {
// Harness control may retry on a concurrent update; reads remain a single load.
let _ = self.seconds.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
@@ -48,6 +48,25 @@ impl LoadCartridgeStep {
pub fn needs_memcard_choice(&self) -> bool {
self.awaiting_memcard && !self.preparing_memcard
}
/// Typed host and UI admission share this single policy boundary.
pub fn choose_memcard(
&mut self,
os: &mut prometeu_system::SystemOS,
choice: prometeu_system::memcard::admission::Choice,
created_at: u64,
) -> prometeu_system::memcard::image::Result<()> {
if !self.needs_memcard_choice() {
return Err(prometeu_system::memcard::image::Error::InvalidState);
}
os.memcard().choose_for_game(
self.cartridge.app_id,
self.cartridge.memcard_slots.unwrap() as usize,
choice,
created_at,
)?;
self.preparing_memcard = true;
Ok(())
}
pub fn new_game_switch(cartridge: Cartridge) -> Self {
Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) }
@@ -128,13 +147,8 @@ impl LoadCartridgeStep {
Choice::MemoryExisting
};
let created_at = ctx.platform.wall_clock().utc_unix_seconds();
match ctx.os.memcard().choose_for_game(
self.cartridge.app_id,
self.cartridge.memcard_slots.unwrap() as usize,
choice,
created_at,
) {
Ok(()) => self.preparing_memcard = true,
match self.choose_memcard(ctx.os, choice, created_at) {
Ok(()) => {}
Err(error) => self.memcard_message = Self::preparation_message(error),
}
}
@@ -57,6 +57,21 @@ impl LogService {
self.events.iter().filter(|e| e.seq > seq).cloned().collect()
}
/// Non-destructive page in native sequence order. A null cursor includes zero.
pub fn get_page(&self, after: Option<u64>, limit: usize) -> Vec<LogEvent> {
self.events
.iter()
.filter(|event| after.is_none_or(|seq| event.seq > seq))
.take(limit)
.cloned()
.collect()
}
/// Retained bounds, independent of any reader's progress.
pub fn sequence_bounds(&self) -> (Option<u64>, Option<u64>) {
(self.events.front().map(|event| event.seq), self.last_seq())
}
pub fn last_seq(&self) -> Option<u64> {
self.events.back().map(|e| e.seq)
}
@@ -107,4 +122,35 @@ mod tests {
assert_eq!(after[0].msg, "Log 3");
assert_eq!(after[1].msg, "Log 4");
}
#[test]
fn pages_preserve_zero_requery_and_retained_bounds() {
let mut service = LogService::new(3);
assert_eq!(service.sequence_bounds(), (None, None));
assert!(service.get_page(None, 2).is_empty());
for i in 0..3 {
service.log(i, i, LogLevel::Info, LogSource::Pos, 7, format!("{i}"));
}
assert_eq!(service.sequence_bounds(), (Some(0), Some(2)));
for _ in 0..2 {
let page = service.get_page(None, 2);
assert_eq!(page.iter().map(|event| event.seq).collect::<Vec<_>>(), vec![0, 1]);
}
assert_eq!(service.get_page(Some(1), 2)[0].seq, 2);
assert!(service.get_page(Some(2), 2).is_empty());
service.log(3, 3, LogLevel::Info, LogSource::Pos, 7, "next".into());
assert_eq!(service.sequence_bounds(), (Some(1), Some(3)));
assert_eq!(service.get_page(Some(2), 2)[0].seq, 3);
assert_eq!(service.get_page(None, 10).len(), 3);
}
#[test]
fn page_cursors_preserve_large_unsigned_sequences() {
let mut service = LogService::new(3);
service.next_seq = u64::MAX - 2;
service.log(0, 0, LogLevel::Info, LogSource::Pos, 0, "first".into());
service.log(0, 0, LogLevel::Info, LogSource::Pos, 0, "second".into());
assert_eq!(service.get_page(Some(u64::MAX - 2), 1)[0].seq, u64::MAX - 1);
assert!(service.get_page(Some(u64::MAX), 1).is_empty());
}
}
@@ -6,6 +6,10 @@ pub enum MemcardIoError {
InvalidRange,
NoSpace,
Unsupported,
Busy,
AccessDenied,
AlreadyExists,
Indeterminate,
IoError,
}
@@ -64,6 +64,14 @@ impl SystemOS {
pub fn memcard(&mut self) -> &mut MemcardService {
&mut self.memcard
}
/// A successful return confirms the shared worker has stopped and joined.
pub fn stop_background_io(&mut self) -> Result<(), crate::AsyncWorkLaneError> {
if let Some(controller) = &mut self.io_controller {
controller.stop()?;
}
self.io_controller = None;
Ok(())
}
/// Host/player operations are admitted only while gameplay is suspended.
pub fn replace_memcard(
@@ -162,6 +170,16 @@ impl SystemOS {
self.log_service.get_after(seq)
}
/// Coherent non-destructive page and retained bounds; does not execute the VM.
pub fn log_snapshot(
&self,
after: Option<u64>,
limit: usize,
) -> (Vec<LogEvent>, Option<u64>, Option<u64>) {
let (oldest, newest) = self.log_service.sequence_bounds();
(self.log_service.get_page(after, limit), oldest, newest)
}
pub fn frame_index(&mut self) -> u64 {
self.vm().logical_frame_index()
}
@@ -2,6 +2,7 @@
//! shared IO worker owns storage during a publication. Legacy per-slot files are
//! intentionally neither read nor migrated by this service.
pub mod admission;
pub mod diagnostics;
pub mod guest;
pub mod image;
pub mod session;
@@ -37,6 +37,7 @@ pub struct Admission {
pub state: PreparationState,
pub snapshot_budget: usize,
faulted: bool,
replacement_observation: Option<super::diagnostics::SessionDiagnostics>,
}
impl Default for Admission {
fn default() -> Self {
@@ -48,10 +49,26 @@ impl Default for Admission {
state: PreparationState::Idle,
snapshot_budget: DEFAULT_SNAPSHOT_BUDGET,
faulted: false,
replacement_observation: None,
}
}
}
impl MemcardService {
pub fn session_diagnostics(&self) -> super::diagnostics::SessionDiagnostics {
self.admission.replacement_observation.clone().unwrap_or_else(|| self.session.diagnostics())
}
pub fn preparation_active(&self) -> bool {
self.admission.receiver.is_some()
}
pub fn installed_card_id(&self) -> Option<[u8; 16]> {
self.admission.installed.as_ref().map(|c| c.current().card_id)
}
pub fn cancel_pending(&mut self) {
self.session.cancel_pending();
if let Some(control) = &self.admission.control {
control.cancel();
}
}
pub fn host_faulted(&self) -> bool {
self.admission.faulted || self.session.host_faulted()
}
@@ -60,7 +77,11 @@ impl MemcardService {
}
pub fn installed_health(&self) -> Option<(bool, bool, bool)> {
self.admission.installed.as_ref().map(|card| {
(card.recovered, card.degraded, card.write_blocked || card.storage_read_only())
(
card.recovered,
card.degraded,
card.write_blocked || card.storage_read_only() || card.uncertain,
)
})
}
pub fn card_has_game(&self, app_id: u32) -> bool {
@@ -135,6 +156,9 @@ impl MemcardService {
let owned =
card.catalog.games.iter().find(|g| g.app_id == app_id).map_or(0, |g| g.slots.len());
if choice == Choice::Persistent {
if card.uncertain {
return Err(Error::Indeterminate);
}
if card.storage_read_only() || card.write_blocked {
return Err(Error::ReadOnly);
}
@@ -171,6 +195,10 @@ impl MemcardService {
}
Choice::Persistent => {
let mut card = card.take().unwrap();
if card.uncertain {
session.retain_idle_card(card);
return Err(Error::Indeterminate);
}
if card.storage_read_only() || card.write_blocked {
session.retain_idle_card(card);
return Err(Error::ReadOnly);
@@ -256,9 +284,24 @@ impl MemcardService {
&mut self,
storage: Box<dyn MemcardStorage>,
load_existing: bool,
) -> Result<()> {
self.replace_card_job(move |session, control| {
session.replace_storage(storage, load_existing, control)
})
}
pub fn reconcile_card_with(
&mut self,
open: impl FnOnce() -> Result<Box<dyn MemcardStorage>> + Send + 'static,
) -> Result<()> {
self.replace_card_job(move |session, control| session.reconcile_storage_with(open, control))
}
fn replace_card_job(
&mut self,
operation: impl FnOnce(&mut Session, &PublicationControl) -> Result<()> + Send + 'static,
) -> Result<()> {
if self.admission.receiver.is_some()
|| self.session.has_in_flight()
|| self.session.io_active()
|| self.session.has_deferred_write()
|| self.session.is_boot_active()
{
return Err(Error::Busy);
@@ -266,6 +309,7 @@ impl MemcardService {
if self.admission.faulted {
return Err(Error::ReadOnly);
}
self.admission.replacement_observation = Some(self.session.diagnostics());
let handoff = Arc::new(Mutex::new(Some(std::mem::take(&mut self.session))));
let worker = handoff.clone();
let control = Arc::new(PublicationControl::default());
@@ -275,13 +319,14 @@ impl MemcardService {
.lane
.submit_memcard_commit_write(move |_| {
let mut session = worker.lock().unwrap().take().unwrap();
let result = session.replace_storage(storage, load_existing, &worker_control);
let result = operation(&mut session, &worker_control);
let _ = tx.send(Prepared::Replacement(session, result));
crate::AsyncWorkJobOutcome::Completed
})
.is_err()
{
self.session = handoff.lock().unwrap().take().unwrap();
self.admission.replacement_observation = None;
return Err(Error::InvalidState);
}
self.admission.control = Some(control);
@@ -331,6 +376,7 @@ impl MemcardService {
}
self.admission.receiver = None;
self.admission.control = None;
self.admission.replacement_observation = None;
}
Err(mpsc::TryRecvError::Disconnected) => {
self.admission.state = PreparationState::Failed(Error::InvalidState);
@@ -361,3 +407,37 @@ impl MemcardService {
}
}
}
#[cfg(all(test, unix))]
mod tests {
use super::*;
use prometeu_drivers::memcard::FileMemcard;
use prometeu_hal::memcard::MemcardIoError;
#[test]
fn idle_uncertain_media_remains_blocked_before_another_persistent_admission() {
let path = std::env::temp_dir().join(format!(
"memcard-uncertain-idle-{}-{}",
std::process::id(),
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
));
let io = FileMemcard::create(&path, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap();
let mut card = Card::mount(Box::new(io)).unwrap();
card.uncertain = true;
let mut service = MemcardService::new();
// An ended session returns its backend to the same installed-card state.
service.admission.installed = Some(card);
assert_eq!(service.installed_health(), Some((false, false, true)));
assert_eq!(
service.choose_for_game(42, 1, Choice::Persistent, 0),
Err(Error::Indeterminate)
);
assert!(service.card_installed());
assert_eq!(service.lane.pending_depth(), 0);
service.uninstall_card().unwrap();
std::fs::remove_file(path).unwrap();
}
}
@@ -0,0 +1,31 @@
//! Read-only native observations. These do not consume the guest request entry.
use super::{
image::Error,
session::{Mode, RequestResult},
};
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RequestDiagnostics {
pub result: RequestResult,
pub storage_error: Option<Error>,
pub slot: Option<usize>,
pub operation: &'static str,
pub retained: bool,
pub io_active: bool,
pub deferred: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionDiagnostics {
pub app_id: Option<u32>,
pub card_id: Option<[u8; 16]>,
pub epoch: u64,
pub mode: Option<Mode>,
pub health: (bool, bool, bool),
pub dirty_slots: Vec<usize>,
pub request: Option<RequestDiagnostics>,
pub io_active: bool,
pub removal_pending: bool,
pub reconciliation_required: bool,
pub restart_required: bool,
}
@@ -31,12 +31,14 @@ pub fn status(e: Error) -> i64 {
use prometeu_hal::memcard::MemcardIoError as I;
match e {
Error::NoSpace | Error::Io(I::NoSpace) => 3,
Error::AccessDenied => 4,
Error::AccessDenied
| Error::IdentityMismatch
| Error::Io(I::AccessDenied | I::AlreadyExists) => 4,
Error::Corrupt => 5,
Error::Indeterminate => 6,
Error::Indeterminate | Error::Io(I::Indeterminate) => 6,
Error::Io(I::Unavailable) => 7,
Error::InvalidState | Error::Canceled => 8,
Error::Busy => 9,
Error::Busy | Error::Io(I::Busy) => 9,
Error::ReadOnly | Error::CounterExhausted | Error::Io(I::ReadOnly) => 10,
Error::InvalidRange | Error::Io(I::InvalidRange) => 11,
Error::Unsupported | Error::Io(I::Unsupported) => 12,
@@ -29,6 +29,7 @@ pub enum Error {
OutOfMemory,
AccessDenied,
InvalidState,
IdentityMismatch,
}
impl From<MemcardIoError> for Error {
fn from(e: MemcardIoError) -> Self {
@@ -7,6 +7,8 @@ use std::time::{Duration, Instant};
pub const GUEST_BYTES: usize = 4096;
static NEXT_CONTEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
// `try_update` requires Rust 1.95; keep older stable CI toolchains compatible.
#[allow(deprecated)]
fn next_context() -> Result<u64> {
NEXT_CONTEXT
.fetch_update(
@@ -71,12 +73,14 @@ struct Request {
job: AsyncWorkJobId,
released: bool,
saves_payload: bool,
worker_returned: bool,
}
/// Main-lane control; the Card moves into the single worker while its source is protected.
#[derive(Default)]
pub struct Session {
card_id: Option<[u8; 16]>,
uncertain_target: Option<Map>,
known_card_exclusions: Option<([u8; 16], [bool; BLOCK_COUNT])>,
health: (bool, bool, bool),
context: u64,
epoch: u64,
@@ -100,6 +104,82 @@ pub struct Session {
deferred: Option<(u64, usize, u64, Instant)>,
}
impl Session {
/// IO ownership, independent of a completed result retained for guest release.
pub fn io_active(&self) -> bool {
self.request.as_ref().is_some_and(|r| !r.worker_returned)
}
pub fn has_deferred_write(&self) -> bool {
self.deferred.is_some()
}
pub fn cancel_pending(&mut self) {
if let Some(r) = &self.request {
r.control.cancel();
}
if let Some((id, local, ..)) = self.deferred.take() {
self.slots[local].protected = false;
self.memory_result = Some(RequestResult {
id,
state: RequestState::Failure,
reason: RequestReason::Storage(Error::Canceled),
});
}
}
pub fn diagnostics(&self) -> super::diagnostics::SessionDiagnostics {
use super::diagnostics::{RequestDiagnostics, SessionDiagnostics};
let request = if let Some((id, local, ..)) = self.deferred {
Some(RequestDiagnostics {
result: RequestResult {
id,
state: RequestState::Pending,
reason: RequestReason::None,
},
storage_error: None,
slot: Some(local),
operation: "commit",
retained: true,
io_active: false,
deferred: true,
})
} else if let Some(r) = &self.request {
Some(RequestDiagnostics {
result: r.result,
storage_error: r.worker_error,
slot: r.saves_payload.then_some(r.local),
operation: if r.saves_payload { "commit" } else { "presentation" },
retained: !r.released,
io_active: self.io_active(),
deferred: false,
})
} else {
self.memory_result.map(|result| RequestDiagnostics {
result,
storage_error: None,
slot: None,
operation: "commit",
retained: true,
io_active: false,
deferred: false,
})
};
SessionDiagnostics {
app_id: self.mode.map(|_| self.app_id),
card_id: self.card_id,
epoch: self.epoch,
mode: self.mode,
health: self.health(),
dirty_slots: self
.slots
.iter()
.enumerate()
.filter_map(|(i, s)| s.data.read().ok().filter(|s| s.dirty).map(|_| i))
.collect(),
request,
io_active: self.io_active(),
removal_pending: self.removal_pending,
reconciliation_required: self.reconcile_blocked,
restart_required: self.faulted,
}
}
pub fn context(&self) -> u64 {
self.context
}
@@ -531,6 +611,7 @@ impl Session {
job,
released: !saves_payload,
saves_payload,
worker_returned: false,
});
Ok(())
}
@@ -674,6 +755,7 @@ impl Session {
job,
released: false,
saves_payload: true,
worker_returned: false,
});
Ok(id)
}
@@ -692,6 +774,7 @@ impl Session {
let Some(r) = &mut self.request else { return };
match r.receiver.try_recv() {
Ok(completion) => {
r.worker_returned = true;
r.worker_error = completion.result.error;
let current =
self.mode.is_some() && r.session == self.context && r.epoch == self.epoch;
@@ -819,7 +902,7 @@ impl Session {
return Err(Error::Busy);
}
r.released = true;
if self.card.is_some() {
if r.worker_returned {
self.request = None;
}
Ok(())
@@ -833,7 +916,7 @@ impl Session {
r.control.cancel();
r.released = true;
}
if self.card.is_some() {
if !self.io_active() {
self.request = None;
}
self.removal_pending = false;
@@ -869,7 +952,23 @@ impl Session {
load_existing: bool,
control: &PublicationControl,
) -> Result<()> {
if self.has_in_flight() || self.boot_active || self.mode.is_none() {
self.replace_storage_with(move || Ok(storage), load_existing, false, control)
}
pub(super) fn reconcile_storage_with(
&mut self,
open: impl FnOnce() -> Result<Box<dyn prometeu_hal::memcard::MemcardStorage>>,
control: &PublicationControl,
) -> Result<()> {
self.replace_storage_with(open, false, true, control)
}
fn replace_storage_with(
&mut self,
open: impl FnOnce() -> Result<Box<dyn prometeu_hal::memcard::MemcardStorage>>,
load_existing: bool,
same_only: bool,
control: &PublicationControl,
) -> Result<()> {
if self.io_active() || self.deferred.is_some() || self.boot_active || self.mode.is_none() {
return Err(Error::Busy);
}
if self.icon.is_empty()
@@ -882,11 +981,18 @@ impl Session {
{
self.uncertain_target = card.attempted_publication.clone();
}
let known = self.card.as_ref().map(|c| (c.current().card_id, c.known_exclusions()));
if let Some(card) = &self.card {
self.known_card_exclusions = Some((card.current().card_id, card.known_exclusions()));
}
let known = self.known_card_exclusions;
self.card.take(); // Release the old scratch before mounting another image.
self.scratch = None;
self.reconcile_blocked = true;
self.card = Some(Card::mount(storage)?);
let candidate = Card::mount(open()?)?;
if same_only && self.card_id != Some(candidate.current().card_id) {
return Err(Error::IdentityMismatch);
}
self.card = Some(candidate);
let card = self.card.as_mut().unwrap();
let same = self.card_id == Some(card.current().card_id);
if let Some((id, known)) = known
@@ -973,14 +1079,15 @@ impl Session {
Ok(())
}
pub fn detach(&mut self) -> Result<()> {
if self.deferred.is_some()
|| self
.request
.as_ref()
.is_some_and(|r| r.result.state == RequestState::Pending || self.card.is_none())
{
if self.deferred.is_some() || self.io_active() {
return Err(Error::Busy);
}
if self.card.is_none() && self.scratch.is_none() {
let mut scratch = Vec::new();
scratch.try_reserve_exact(SLOT_BYTES).map_err(|_| Error::OutOfMemory)?;
scratch.resize(SLOT_BYTES, 0);
self.scratch = Some(scratch);
}
self.mode = Some(Mode::MemoryOnly);
self.removal_pending = false;
self.reconcile_blocked = false;
@@ -16,6 +16,8 @@ impl PublicationControl {
pub fn publication_attempted(&self) -> bool {
self.0.load(Ordering::SeqCst) & 1 != 0
}
// `try_update` requires Rust 1.95; keep older stable CI toolchains compatible.
#[allow(deprecated)]
fn enter(&self) -> Result<()> {
self.0
.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |state| {
+91 -2
View File
@@ -235,12 +235,13 @@ pub type IntrinsicHostImplementation =
pub enum IntrinsicImplementation {
Host(IntrinsicHostImplementation),
VmOwned,
BorrowedInline(crate::IntrinsicInlineImplementation),
}
impl IntrinsicImplementation {
pub fn host_callback(self) -> Option<IntrinsicHostImplementation> {
match self {
Self::Host(f) => Some(f),
Self::VmOwned => None,
Self::VmOwned | Self::BorrowedInline(_) => None,
}
}
}
@@ -249,12 +250,14 @@ impl IntrinsicImplementation {
pub enum IntrinsicCostModel {
Fixed,
RandomRejectionV1,
ArgumentUtf8BytesV1,
}
impl IntrinsicCostModel {
pub const fn name(self) -> &'static str {
match self {
Self::Fixed => "fixed",
Self::RandomRejectionV1 => "random_rejection_v1",
Self::ArgumentUtf8BytesV1 => "argument_utf8_bytes_v1",
}
}
}
@@ -266,11 +269,14 @@ pub struct IntrinsicMeta {
pub name: &'static str,
pub version: u16,
pub arg_layout: &'static [AbiType],
pub arg_nullable: &'static [bool],
pub ret_layout: &'static [AbiType],
pub parameter_names: &'static [&'static str],
/// Full fixed cost, or base cost for a variable model.
pub cost_cycles: u64,
pub cost_model: IntrinsicCostModel,
pub cost_arg_index: Option<usize>,
pub cost_per_byte: u64,
pub attempt_cost_cycles: u64,
pub max_attempts: u32,
pub mutates_guest_state: bool,
@@ -300,7 +306,16 @@ impl IntrinsicMeta {
&self,
values: &[Value],
) -> Result<(), IntrinsicExecutionError> {
Self::validate_values(values, self.arg_layout)
Self::validate_values(values, self.arg_layout)?;
for (index, (value, nullable)) in values.iter().zip(self.arg_nullable).enumerate() {
if matches!(value, Value::Null) && !nullable {
return Err(IntrinsicExecutionError::TypeMismatch {
index,
expected: self.arg_layout[index],
});
}
}
Ok(())
}
fn validate_values(
@@ -563,10 +578,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "dot",
version: 1,
arg_layout: &VEC2_DOT_ARGS,
arg_nullable: &[false; VEC2_DOT_ARGS.len()],
ret_layout: &SINGLE_FLOAT_RET,
parameter_names: &["ax", "ay", "bx", "by"],
cost_cycles: 10,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -580,10 +598,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "length",
version: 1,
arg_layout: &VEC2_LENGTH_ARGS,
arg_nullable: &[false; VEC2_LENGTH_ARGS.len()],
ret_layout: &SINGLE_FLOAT_RET,
parameter_names: &["x", "y"],
cost_cycles: 40,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -597,10 +618,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "from_raw",
version: 1,
arg_layout: &INT_RET,
arg_nullable: &[false; INT_RET.len()],
ret_layout: &COLOR_RET,
parameter_names: &["raw"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -614,10 +638,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "rgb",
version: 1,
arg_layout: &COLOR_RGB_ARGS,
arg_nullable: &[false; COLOR_RGB_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &["r", "g", "b"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -631,10 +658,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "rgba",
version: 1,
arg_layout: &COLOR_RGBA_ARGS,
arg_nullable: &[false; COLOR_RGBA_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &["r", "g", "b", "a"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -648,10 +678,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "html_rgba",
version: 1,
arg_layout: &COLOR_HTML_RGBA_ARGS,
arg_nullable: &[false; COLOR_HTML_RGBA_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &["value"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -665,10 +698,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "gray_scale",
version: 1,
arg_layout: &INT_RET,
arg_nullable: &[false; INT_RET.len()],
ret_layout: &COLOR_RET,
parameter_names: &["value"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -682,10 +718,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "hex",
version: 1,
arg_layout: &COLOR_ARGS,
arg_nullable: &[false; COLOR_ARGS.len()],
ret_layout: &INT_RET,
parameter_names: &["color"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -699,10 +738,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "alpha",
version: 1,
arg_layout: &COLOR_ARGS,
arg_nullable: &[false; COLOR_ARGS.len()],
ret_layout: &INT_RET,
parameter_names: &["color"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -716,10 +758,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "black",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -733,10 +778,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "white",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -750,10 +798,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "red",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -767,10 +818,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "green",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -784,10 +838,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "blue",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -801,10 +858,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "yellow",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -818,10 +878,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "orange",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -835,10 +898,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "indigo",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -852,10 +918,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "gray",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -869,10 +938,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "cyan",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -886,10 +958,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "magenta",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -903,10 +978,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
name: "transparent",
version: 1,
arg_layout: &NO_ARGS,
arg_nullable: &[false; NO_ARGS.len()],
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -944,6 +1022,7 @@ pub fn lookup_intrinsic(owner: &str, name: &str, version: u16) -> Option<&'stati
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.chain(crate::math_intrinsics::MATH_INTRINSICS.iter())
.chain(crate::random_intrinsics::RANDOM_INTRINSICS.iter())
.chain(crate::hash_intrinsics::HASH_INTRINSICS.iter())
.find(|meta| meta.owner == owner && meta.name == name && meta.version == version)
}
@@ -953,6 +1032,7 @@ pub fn lookup_intrinsic_by_id(id: u32) -> Option<&'static IntrinsicMeta> {
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.chain(crate::math_intrinsics::MATH_INTRINSICS.iter())
.chain(crate::random_intrinsics::RANDOM_INTRINSICS.iter())
.chain(crate::hash_intrinsics::HASH_INTRINSICS.iter())
.find(|meta| meta.id == id)
}
@@ -1254,9 +1334,17 @@ pub(crate) fn metered_lookup_intrinsic(
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.chain(crate::math_intrinsics::MATH_INTRINSICS.iter())
.chain(crate::random_intrinsics::RANDOM_INTRINSICS.iter())
.chain(crate::hash_intrinsics::HASH_INTRINSICS.iter())
{
budget.work(1)?;
if meta.id == id {
budget.work(meta.arg_slots() + 1)?;
meta.validate_descriptor().map_err(|_| {
prometeu_bytecode::load_limits::LoadFailure::new(
prometeu_bytecode::load_limits::LoadCode::InvalidCode,
prometeu_bytecode::load_limits::LoadReason::NativeId,
)
})?;
return Ok(Some(meta));
}
}
@@ -1270,6 +1358,7 @@ pub fn intrinsic_catalog() -> impl Iterator<Item = &'static IntrinsicMeta> {
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.chain(crate::math_intrinsics::MATH_INTRINSICS.iter())
.chain(crate::random_intrinsics::RANDOM_INTRINSICS.iter())
.chain(crate::hash_intrinsics::HASH_INTRINSICS.iter())
}
pub fn builtin_constant_catalog() -> impl Iterator<Item = &'static BuiltinConstMeta> {
BUILTIN_CONSTS.iter()
+10 -3
View File
@@ -16,14 +16,15 @@ fn atom(t: AbiType) -> String {
}
pub fn intrinsic_catalog_csv() -> String {
let mut out = String::from(
"final_id_hex,final_id_dec,canonical_name,canonical_version,owner,name,arg_slots,ret_slots,arg_layout,ret_layout,deterministic,may_allocate,parameter_names,cost_cycles,mutates_guest_state,cost_model,attempt_cost_cycles,max_attempts\n",
"final_id_hex,final_id_dec,canonical_name,canonical_version,owner,name,arg_slots,ret_slots,arg_layout,ret_layout,deterministic,may_allocate,parameter_names,cost_cycles,mutates_guest_state,cost_model,attempt_cost_cycles,max_attempts,schema_version,arg_nullable,invocation_model,scratch_model,context_access,cost_arg_index,cost_per_byte\n",
);
let mut entries: Vec<_> = intrinsic_catalog().collect();
entries.sort_by_key(|m| m.id);
for m in entries {
m.validate_descriptor().expect("valid canonical intrinsic descriptor");
writeln!(
&mut out,
"0x{:04X},{},{}.{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{}",
"0x{:04X},{},{}.{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},2,{},{},{},{},{},{}",
m.id,
m.id,
m.owner,
@@ -42,7 +43,13 @@ pub fn intrinsic_catalog_csv() -> String {
m.mutates_guest_state,
m.cost_model.name(),
m.attempt_cost_cycles,
m.max_attempts
m.max_attempts,
m.arg_nullable.iter().map(bool::to_string).collect::<Vec<_>>().join("|"),
m.invocation_model(),
m.scratch_model(),
m.context_access(),
m.cost_arg_index.map_or_else(String::new, |i| i.to_string()),
m.cost_per_byte
)
.unwrap();
}
@@ -0,0 +1,66 @@
use crate::{
AbiType, BuiltinScalarType as S, IntrinsicCostModel as C, IntrinsicExecutionError as E,
IntrinsicImplementation as I, IntrinsicMeta, IntrinsicResults,
};
use prometeu_bytecode::Value;
const fn entry(
id: u32,
name: &'static str,
abi: AbiType,
nullable: bool,
handler: crate::IntrinsicInlineImplementation,
) -> IntrinsicMeta {
IntrinsicMeta {
id,
owner: "hash",
name,
version: 1,
arg_layout: match abi {
AbiType::Scalar(S::Int64) => &[AbiType::Scalar(S::Int64)],
AbiType::Scalar(S::Float) => &[AbiType::Scalar(S::Float)],
AbiType::Scalar(S::String) => &[AbiType::Scalar(S::String)],
_ => panic!("unsupported hash input ABI"),
},
ret_layout: &[AbiType::Scalar(S::Int64)],
arg_nullable: if nullable { &[true] } else { &[false] },
parameter_names: &["value"],
cost_cycles: 8,
cost_model: if matches!(abi, AbiType::Scalar(S::String)) {
C::ArgumentUtf8BytesV1
} else {
C::Fixed
},
cost_arg_index: if matches!(abi, AbiType::Scalar(S::String)) { Some(0) } else { None },
cost_per_byte: if matches!(abi, AbiType::Scalar(S::String)) { 1 } else { 0 },
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: I::BorrowedInline(handler),
}
}
pub(crate) const HASH_INTRINSICS: [IntrinsicMeta; 3] = [
entry(0x4100, "i64", AbiType::Scalar(S::Int64), false, hash_i64),
entry(0x4101, "float", AbiType::Scalar(S::Float), false, hash_float),
entry(0x4102, "string", AbiType::Scalar(S::String), true, hash_string),
];
fn hash_i64(args: &[Value], out: &mut IntrinsicResults) -> Result<(), E> {
let Value::Int64(value) = args[0] else { unreachable!("exact validated Int64") };
out.push(Value::Int64(crate::hashing::xxh64(&value.to_le_bytes()) as i64))
}
fn hash_float(args: &[Value], out: &mut IntrinsicResults) -> Result<(), E> {
let Value::Float(value) = args[0] else { unreachable!("exact validated Float") };
crate::numeric::check_inputs(&[value])?;
let bits = if value == 0.0 { 0 } else { value.to_bits() };
out.push(Value::Int64(crate::hashing::xxh64(&bits.to_le_bytes()) as i64))
}
fn hash_string(args: &[Value], out: &mut IntrinsicResults) -> Result<(), E> {
let hash = match &args[0] {
Value::Null => 0,
Value::String(s) => crate::hashing::xxh64(s.as_bytes()) as i64,
_ => unreachable!("exact validated nullable String"),
};
out.push(Value::Int64(hash))
}
+131
View File
@@ -0,0 +1,131 @@
//! Hash-v1: portable XXH64, seed zero, over explicit machine byte encodings.
use prometeu_bytecode::HeapRef;
const P1: u64 = 0x9E3779B185EBCA87;
const P2: u64 = 0xC2B2AE3D27D4EB4F;
const P3: u64 = 0x165667B19E3779F9;
const P4: u64 = 0x85EBCA77C2B2AE63;
const P5: u64 = 0x27D4EB2F165667C5;
fn word(bytes: &[u8]) -> u64 {
u64::from_le_bytes(bytes[..8].try_into().expect("complete XXH64 lane"))
}
fn round(acc: u64, lane: u64) -> u64 {
acc.wrapping_add(lane.wrapping_mul(P2)).rotate_left(31).wrapping_mul(P1)
}
fn merge(acc: u64, lane: u64) -> u64 {
(acc ^ round(0, lane)).wrapping_mul(P1).wrapping_add(P4)
}
pub(crate) fn xxh64(mut bytes: &[u8]) -> u64 {
let length = bytes.len() as u64;
let mut hash = if bytes.len() >= 32 {
let mut acc = [P1.wrapping_add(P2), P2, 0, 0u64.wrapping_sub(P1)];
while bytes.len() >= 32 {
for (index, value) in acc.iter_mut().enumerate() {
*value = round(*value, word(&bytes[index * 8..]));
}
bytes = &bytes[32..];
}
let mut hash = acc[0]
.rotate_left(1)
.wrapping_add(acc[1].rotate_left(7))
.wrapping_add(acc[2].rotate_left(12))
.wrapping_add(acc[3].rotate_left(18));
for value in acc {
hash = merge(hash, value);
}
hash
} else {
P5
};
hash = hash.wrapping_add(length);
while bytes.len() >= 8 {
hash ^= round(0, word(bytes));
hash = hash.rotate_left(27).wrapping_mul(P1).wrapping_add(P4);
bytes = &bytes[8..];
}
if bytes.len() >= 4 {
hash ^= u64::from(u32::from_le_bytes(bytes[..4].try_into().unwrap())).wrapping_mul(P1);
hash = hash.rotate_left(23).wrapping_mul(P2).wrapping_add(P3);
bytes = &bytes[4..];
}
for byte in bytes {
hash ^= u64::from(*byte).wrapping_mul(P5);
hash = hash.rotate_left(11).wrapping_mul(P1);
}
hash ^= hash >> 33;
hash = hash.wrapping_mul(P2);
hash ^= hash >> 29;
hash = hash.wrapping_mul(P3);
hash ^ (hash >> 32)
}
pub(crate) fn reference(value: Option<HeapRef>) -> i64 {
value.map_or(0, |reference| {
let mut bytes = [0; 8];
bytes[..4].copy_from_slice(&reference.index.to_le_bytes());
bytes[4..].copy_from_slice(&reference.generation.to_le_bytes());
xxh64(&bytes) as i64
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn matches_all_independent_c_reference_vectors() {
let mut count = 0;
for row in include_str!("../tests/fixtures/hash-conformance.tsv").lines().skip(1) {
let f: Vec<_> = row.split('\t').collect();
let expected = u64::from_str_radix(f[2], 16).unwrap();
let actual = match f[0] {
"bytes" | "string" => {
let bytes: Vec<_> = (0..f[1].len())
.step_by(2)
.map(|i| u8::from_str_radix(&f[1][i..i + 2], 16).unwrap())
.collect();
xxh64(&bytes)
}
"i64" => xxh64(&f[1].parse::<i64>().unwrap().to_le_bytes()),
"float" => {
let bits = u64::from_str_radix(f[1], 16).unwrap();
let bits = if f64::from_bits(bits) == 0.0 { 0 } else { bits };
xxh64(&bits.to_le_bytes())
}
"reference" => {
let (index, generation) = f[1].split_once(',').unwrap();
reference(Some(HeapRef {
index: index.parse().unwrap(),
generation: generation.parse().unwrap(),
})) as u64
}
"null" => reference(None) as u64,
kind => panic!("unknown vector {kind}"),
};
assert_eq!(actual, expected, "{row}");
count += 1;
}
assert_eq!(count, 118);
}
#[test]
fn sequential_handles_spread_and_bucket_collisions_do_not_imply_identity() {
let mut buckets = [0; 256];
let mut first = [None; 256];
let mut collisions = 0;
for index in 1..=16384 {
let handle = HeapRef { index, generation: 1 };
let bucket = reference(Some(handle)) as u64 as usize & 255;
buckets[bucket] += 1;
if let Some(previous) = first[bucket] {
assert_ne!(previous, handle);
collisions += 1;
} else {
first[bucket] = Some(handle);
}
}
assert!(buckets.iter().all(|&count| (32..=100).contains(&count)), "{buckets:?}");
assert_eq!(collisions, 16384 - 256);
}
}
+40
View File
@@ -428,6 +428,34 @@ impl Heap {
self.allocation_count.load(Ordering::Relaxed)
}
/// Host-side observations only, outside guest execution and atomic commits.
#[cfg(feature = "resource-diagnostics")]
pub fn diagnostic_typed_storage(&self) -> Vec<crate::resource_diagnostics::StorageObject> {
use crate::resource_diagnostics::{StorageObject, StorageValue};
self.objects
.iter()
.enumerate()
.filter_map(|(index, object)| {
let storage = object.as_ref()?.typed.as_ref()?;
let groups = (0..storage.len())
.map(|i| {
storage
.read(i)
.expect("initialized typed storage")
.as_slice()
.iter()
.map(StorageValue::observe)
.collect()
})
.collect();
Some(StorageObject {
reference: HeapRef { index: index as u32, generation: self.generations[index] },
type_id: storage.type_id(),
groups,
})
})
.collect()
}
#[cfg(feature = "resource-diagnostics")]
pub(crate) fn diagnostic_handles(&self) -> (usize, usize) {
(self.free_list.len(), self.objects.len() - self.free_list.len() - self.len())
@@ -520,6 +548,18 @@ impl Heap {
value_contract::validate(registry, self, storage.slot_type(index)?, values.as_slice())?;
Ok(values)
}
/// Caller has checked all receivers, bounds and groups for the entire attempt.
/// This commit path performs no allocation, provenance lookup or guest callback.
pub(crate) fn commit_typed(&mut self, r: HeapRef, index: usize, values: &[Value]) {
self.objects[r.index as usize]
.as_mut()
.unwrap()
.typed
.as_mut()
.unwrap()
.write_validated(index, values)
.expect("prevalidated storage publication");
}
pub(crate) fn store_typed(
&mut self,
registry: &Registry,
@@ -20,10 +20,13 @@ const fn query(
name,
version: 1,
arg_layout: &[],
arg_nullable: &[],
ret_layout,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -0,0 +1,143 @@
//! The native handler variant and descriptor jointly define the invocation contract.
use crate::{
AbiType, BuiltinScalarType, IntrinsicCostModel, IntrinsicExecutionError as E,
IntrinsicImplementation as I, IntrinsicMeta,
};
use prometeu_bytecode::Value;
pub type IntrinsicInlineImplementation = fn(&[Value], &mut IntrinsicResults) -> Result<(), E>;
const INLINE_SLOTS: usize = 3;
/// Fixed native staging only; no heap buffer or mutable execution context.
#[derive(Debug)]
pub struct IntrinsicResults {
values: [Value; INLINE_SLOTS],
len: usize,
limit: usize,
overflowed: bool,
}
impl IntrinsicResults {
pub(crate) fn new(limit: usize) -> Self {
assert!(limit <= INLINE_SLOTS);
Self { values: [const { Value::Null }; INLINE_SLOTS], len: 0, limit, overflowed: false }
}
pub fn push(&mut self, value: Value) -> Result<(), E> {
if self.len >= self.limit {
self.overflowed = true;
return Err(E::ArityMismatch { expected: self.limit, got: self.len + 1 });
}
self.values[self.len] = value;
self.len += 1;
Ok(())
}
pub(crate) fn validate(&self, meta: &IntrinsicMeta) -> Result<(), E> {
if self.overflowed {
return Err(E::ArityMismatch { expected: self.limit, got: self.limit + 1 });
}
meta.validate_result_values(&self.values[..self.len])
}
pub(crate) fn as_slice(&self) -> &[Value] {
&self.values[..self.len]
}
pub(crate) fn into_values(self) -> impl Iterator<Item = Value> {
self.values.into_iter().take(self.len)
}
}
impl IntrinsicMeta {
pub fn invocation_model(&self) -> &'static str {
match self.implementation {
I::Host(_) => "host_buffered_v1",
I::VmOwned => "vm_owned_v1",
I::BorrowedInline(_) => "borrowed_inline_v1",
}
}
pub fn scratch_model(&self) -> &'static str {
match self.implementation {
I::BorrowedInline(_) => "none",
_ => "existing_contract_v1",
}
}
pub fn context_access(&self) -> &'static str {
match self.implementation {
I::Host(_) => "host",
I::VmOwned => "vm_state",
I::BorrowedInline(_) => "none",
}
}
/// Derivation from the handler variant makes incompatible profile claims unrepresentable.
pub fn validate_descriptor(&self) -> Result<(), &'static str> {
if self.arg_nullable.len() != self.arg_slots()
|| self.parameter_names.len() != self.arg_slots()
{
return Err("argument metadata widths disagree");
}
for abi in self.arg_layout.iter().chain(self.ret_layout) {
if !matches!(abi, AbiType::Scalar(_))
&& !matches!(abi, AbiType::Builtin(key) if (key.name == "Random" || key.name == "color") && key.version == 1)
{
return Err("unsupported intrinsic ABI layout");
}
}
for (abi, nullable) in self.arg_layout.iter().zip(self.arg_nullable) {
let permits_null = matches!(abi, AbiType::Scalar(BuiltinScalarType::String))
|| matches!(abi, AbiType::Builtin(key) if key.name == "Random" && key.version == 1);
if *nullable && !permits_null {
return Err("non-nullable ABI carrier declared nullable");
}
}
match self.cost_model {
IntrinsicCostModel::Fixed => {
if self.cost_arg_index.is_some()
|| self.cost_per_byte != 0
|| self.attempt_cost_cycles != 0
|| self.max_attempts != 0
{
return Err("fixed cost has variable parameters");
}
}
IntrinsicCostModel::RandomRejectionV1 => {
if !matches!(self.implementation, I::VmOwned)
|| self.cost_arg_index.is_some()
|| self.cost_per_byte != 0
|| self.attempt_cost_cycles == 0
|| self.max_attempts == 0
{
return Err("invalid random rejection cost parameters");
}
}
IntrinsicCostModel::ArgumentUtf8BytesV1 => {
if !matches!(self.implementation, I::BorrowedInline(_))
|| self.cost_arg_index.and_then(|i| self.arg_layout.get(i))
!= Some(&AbiType::Scalar(BuiltinScalarType::String))
|| self.cost_per_byte == 0
|| self.attempt_cost_cycles != 0
|| self.max_attempts != 0
{
return Err("invalid String byte-cost parameters");
}
}
}
if matches!(self.implementation, I::BorrowedInline(_))
&& (self.ret_slots() > INLINE_SLOTS
|| self.ret_slots() > self.arg_slots()
|| self.may_allocate
|| self.mutates_guest_state
|| !self.deterministic)
{
return Err("handler violates bounded invocation capabilities");
}
Ok(())
}
/// None is checked cost overflow. Wrong/missing carriers have no inferred length.
pub(crate) fn attempted_cost(&self, args: &[Value]) -> Option<u64> {
if self.cost_model != IntrinsicCostModel::ArgumentUtf8BytesV1 {
return Some(self.cost_cycles);
}
let bytes = match self.cost_arg_index.and_then(|i| args.get(i)) {
Some(Value::String(value)) => value.len() as u64,
_ => 0,
};
bytes.checked_mul(self.cost_per_byte)?.checked_add(self.cost_cycles)
}
}
+4
View File
@@ -2,7 +2,11 @@
extern crate self as prometeu_vm;
mod builtins;
mod catalog;
mod hash_intrinsics;
mod hashing;
mod intrinsic_contract;
pub use catalog::{builtin_constant_catalog_csv, intrinsic_catalog_csv};
pub use intrinsic_contract::{IntrinsicInlineImplementation, IntrinsicResults};
mod call_frame;
mod input_intrinsics;
mod math_intrinsics;
@@ -20,10 +20,17 @@ const fn entry<const ID: u32>(
name,
version: 1,
arg_layout,
arg_nullable: match arg_layout.len() {
1 => &[false],
2 => &[false, false],
_ => &[false, false, false],
},
ret_layout,
parameter_names,
cost_cycles,
cost_model: crate::IntrinsicCostModel::Fixed,
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
@@ -1,4 +1,4 @@
//! PBX v1 publication: immutable metadata and shared payload, after bindings
//! PBX v0 publication: immutable metadata and shared payload, after bindings
//! and bounded whole-program verification. No public unchecked constructor.
use crate::string_identity_index::Identity;
use crate::{LoaderPatchError, VmInitError};
@@ -21,6 +21,13 @@ const fn entry(
name,
version: 1,
arg_layout: args,
arg_nullable: if id == 0x4000 {
&[false]
} else if rejection {
&[true, false, false]
} else {
&[true]
},
ret_layout: ret,
parameter_names: names,
cost_cycles: cost,
@@ -29,6 +36,8 @@ const fn entry(
} else {
IntrinsicCostModel::Fixed
},
cost_arg_index: None,
cost_per_byte: 0,
attempt_cost_cycles: if rejection { 8 } else { 0 },
max_attempts: if rejection { crate::random::MAX_ATTEMPTS } else { 0 },
deterministic: true,
@@ -485,6 +485,10 @@ fn transfer(
group(&mut working[base..], registry, ty, (instruction.pc as u64) << 32, budget)?;
}
}
Op::RefIdentityHash => {
budget.work(1)?;
working[base] = Fact::Carrier(I64);
}
Op::RefCast | Op::RefToTrait => {
group(
&mut working[base..],
@@ -503,6 +507,7 @@ fn transfer(
| Op::And
| Op::Or
| Op::Not
| Op::RefIdentityEq
| Op::RefIsExact
| Op::RefImplements
| Op::DynCanUnpack => {
@@ -705,6 +710,15 @@ fn check(
}
}
Op::ArrayNew => require(working[end - 1], I64, 0, registry, budget)?,
Op::ArrayCopy => {
let array = TypeId(instruction.imm_u32().unwrap());
let base = end - 5;
check_group(&working[base..base + 1], array, registry, budget)?;
check_group(&working[base + 2..base + 3], array, registry, budget)?;
for i in [1, 3, 4] {
require(working[base + i], I64, i, registry, budget)?;
}
}
Op::StructGet | Op::StructSet | Op::ArrayLen | Op::ArrayGet | Op::ArraySet => {
budget.work(3)?;
let (id, field) = if matches!(instruction.opcode, Op::StructGet | Op::StructSet) {
@@ -760,6 +774,21 @@ fn check(
return Err(mismatch(1));
}
}
Op::RefIdentityHash | Op::RefIdentityEq => {
let (left, right) = if instruction.opcode == Op::RefIdentityHash {
(instruction.imm_u32().unwrap(), None)
} else {
let (a, b) = instruction.imm_u32x2().unwrap();
(a, Some(b))
};
let lw = registry.type_layout(TypeId(left)).unwrap().storage.slots as usize;
let rw = right
.map_or(0, |id| registry.type_layout(TypeId(id)).unwrap().storage.slots as usize);
check_group(&working[end - lw - rw..end - rw], TypeId(left), registry, budget)?;
if let Some(id) = right {
check_group(&working[end - rw..end], TypeId(id), registry, budget)?;
}
}
Op::RefCast | Op::RefToTrait | Op::RefIsExact | Op::RefImplements => {
budget.work(1)?;
let ty = TypeId(instruction.imm_u32x2().unwrap().0);
@@ -772,7 +801,12 @@ fn check(
.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)?;
let accepted = if native.arg_nullable[part] {
abi_mask(*abi) | NULL
} else {
abi_mask(*abi) & !NULL
};
require(working[base + part], accepted, part, registry, budget)?;
}
}
Op::JmpIfTrue | Op::JmpIfFalse | Op::Not => {
@@ -87,3 +87,39 @@ mod tests {
assert_eq!(h.max_ns, 99);
}
}
/// Non-owning storage observations for engineering qualification. These values
/// never retain a guest object or a native string owner and cannot write storage.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum StorageValue {
Null,
Int32(i32),
Int64(i64),
FloatBits(u64),
Boolean(bool),
Reference(prometeu_bytecode::HeapRef),
StringIdentity { address: usize, bytes: usize },
}
impl StorageValue {
pub(crate) fn observe(value: &prometeu_bytecode::Value) -> Self {
use prometeu_bytecode::Value;
match value {
Value::Null => Self::Null,
Value::Int32(n) => Self::Int32(*n),
Value::Int64(n) => Self::Int64(*n),
Value::Float(n) => Self::FloatBits(n.to_bits()),
Value::Boolean(n) => Self::Boolean(*n),
Value::HeapRef(r) => Self::Reference(*r),
Value::String(s) => Self::StringIdentity {
address: std::sync::Arc::as_ptr(s) as *const () as usize,
bytes: s.len(),
},
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StorageObject {
pub reference: prometeu_bytecode::HeapRef,
pub type_id: prometeu_bytecode::registry::TypeId,
pub groups: Vec<Vec<StorageValue>>,
}
@@ -221,6 +221,24 @@ pub(crate) fn unpack_dynamic(
// All reference operations validate complete source values before querying the
// underlying concrete object. Invalid handles/pairs never become false or null.
pub(crate) fn identity_reference(
registry: &Registry,
heap: &Heap,
source: TypeId,
values: &[Value],
) -> Result<Option<HeapRef>, ValueError> {
let kind = registry.declarations().types.get(source.0 as usize).ok_or(ValueError::Type)?;
if !kind.kind.is_identity_reference() {
return Err(ValueError::Type);
}
validate(registry, heap, source, values)?;
match values.first() {
Some(Value::Null) => Ok(None),
Some(Value::HeapRef(reference)) => Ok(Some(*reference)),
_ => Err(ValueError::Type),
}
}
fn reference(
registry: &Registry,
heap: &Heap,
@@ -1,12 +1,20 @@
use crate::numeric;
use crate::resource_budget::BudgetVec;
mod array_copy;
#[cfg(test)]
mod array_copy_tests;
mod callable;
#[cfg(test)]
#[path = "../tests/support/collections.rs"]
mod collection_test_support;
mod collections;
#[cfg(test)]
mod collections_tests;
mod control;
mod dynamic;
mod gc;
mod identity;
mod intrinsic;
mod lifecycle;
mod loader;
mod native_arrays;
@@ -327,8 +335,10 @@ impl VirtualMachine {
}
let charged_math = if opcode == OpCode::Intrinsic {
lookup_intrinsic_by_id(instr.imm_u32().unwrap())
.filter(|m| m.owner == "vec2" || m.owner == "mathf" || m.owner.starts_with("math."))
lookup_intrinsic_by_id(instr.imm_u32().unwrap()).filter(|m| {
matches!(m.implementation, crate::IntrinsicImplementation::Host(_))
&& (m.owner == "vec2" || m.owner == "mathf" || m.owner.starts_with("math."))
})
} else {
None
};
@@ -952,6 +962,12 @@ impl VirtualMachine {
)
})?;
if matches!(
intrinsic.implementation,
crate::IntrinsicImplementation::BorrowedInline(_)
) {
return self.execute_inline_intrinsic(intrinsic, pc_at_intrinsic);
}
if matches!(intrinsic.implementation, crate::IntrinsicImplementation::VmOwned) {
return self.execute_random(intrinsic, pc_at_intrinsic);
}
@@ -1083,6 +1099,18 @@ impl VirtualMachine {
let (source, target) = instr.imm_u32x2().unwrap();
return self.execute_reference(opcode, source, target, start_pc as u32);
}
OpCode::RefIdentityHash | OpCode::RefIdentityEq => {
let (left, right) = if opcode == OpCode::RefIdentityHash {
(instr.imm_u32().unwrap(), None)
} else {
let (left, right) = instr.imm_u32x2().unwrap();
(left, Some(right))
};
return self.execute_identity(opcode, left, right, start_pc as u32);
}
OpCode::ArrayCopy => {
return self.execute_array_copy(instr.imm_u32().unwrap(), start_pc as u32);
}
OpCode::StructNew
| OpCode::StructGet
| OpCode::StructSet
@@ -2485,7 +2513,7 @@ mod tests {
let mut vm = VirtualMachine::default();
let mut header = vec![0u8; 32];
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
header[4..6].copy_from_slice(&0u16.to_le_bytes()); // retired version
header[4..6].copy_from_slice(&1u16.to_le_bytes()); // unsupported version
let res = vm.initialize(header);
assert!(
@@ -2494,11 +2522,11 @@ mod tests {
}
#[test]
fn test_loader_hardening_malformed_pbx_v1() {
fn test_loader_hardening_malformed_pbx_v0() {
let mut vm = VirtualMachine::default();
let mut header = vec![0u8; 32];
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
header[4..6].copy_from_slice(&1u16.to_le_bytes());
header[4..6].copy_from_slice(&0u16.to_le_bytes());
header[8..12].copy_from_slice(&1u32.to_le_bytes()); // missing directory
let res = vm.initialize(header);
@@ -3893,3 +3921,7 @@ mod callable_tests;
#[cfg(feature = "resource-diagnostics")]
pub mod string_provenance_qualification;
#[cfg(test)]
#[path = "virtual_machine/identity_tests.rs"]
mod identity_tests;
@@ -0,0 +1,110 @@
//! Complete-group snapshot copy: charge, validate, prepare, then commit.
use super::*;
use crate::value_contract::{ValueError, ValueGroup};
use prometeu_bytecode::registry::TypeId;
fn planned_cost(count: u32, width: u64) -> Option<u64> {
u64::from(count).checked_mul(2)?.checked_mul(width)?.checked_add(4)
}
impl VirtualMachine {
pub(super) fn execute_array_copy(
&mut self,
array_id: u32,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
let opcode = OpCode::ArrayCopy;
self.cycles += opcode.cycles();
let image = self.validated_image.clone().expect("validated Array TypeId");
let registry = image.registry();
let array_ty = TypeId(array_id);
let element = registry.type_layout(array_ty).unwrap().array.unwrap().element_type_id;
let width = registry.type_layout(element).unwrap().storage.slots;
if self.temporary_slots() < 5 {
return Err(self.trap(
TRAP_STACK_UNDERFLOW,
opcode as u16,
"Incomplete array copy operands".into(),
pc,
));
}
let base = self.operand_stack.len() - 5;
// Inspect count only to select cost, without changing ordinary fault order.
if let Value::Int64(n) = self.operand_stack[base + 4]
&& let Ok(n) = u32::try_from(n)
{
let cost = planned_cost(n, u64::from(width))
.ok_or_else(|| self.collection_size_trap(opcode, pc, u64::MAX))?;
self.cycles += cost - opcode.cycles();
}
let receiver = |offset: usize| {
let r = match self.operand_stack[base + offset] {
Value::HeapRef(r) => r,
Value::Null => return Err(self.value_trap(ValueError::NullReference, opcode, pc)),
_ => return Err(self.value_trap(ValueError::Type, opcode, pc)),
};
if self.heap.concrete_type(r, registry).map_err(|e| self.value_trap(e, opcode, pc))?
!= array_ty
{
return Err(self.value_trap(ValueError::Type, opcode, pc));
}
Ok(r)
};
let source = receiver(0)?;
let target = receiver(2)?;
let integer = |offset: usize| match self.operand_stack[base + offset] {
Value::Int64(n) => Ok(n),
_ => Err(self.value_trap(ValueError::Type, opcode, pc)),
};
let source_start = integer(1)?;
let target_start = integer(3)?;
let count = integer(4)?;
let range = |r, start: i64| {
let len = self
.heap
.typed_array_len(r, registry)
.map_err(|e| self.value_trap(e, opcode, pc))?;
if start < 0 || count < 0 || start > len as i64 || count > len as i64 - start {
return Err(self.value_trap(ValueError::Bounds, opcode, pc));
}
Ok(start as usize)
};
let source_start = range(source, source_start)?;
let target_start = range(target, target_start)?;
let count = count as usize;
// Operands remain roots; every fallible operation precedes shared writes.
let mut prepared =
BudgetVec::<ValueGroup>::new(&self.budget, RuntimeResource::TemporaryBytes);
prepared.reserve(count).map_err(|e| self.resource_trap(e, opcode, pc))?;
for i in 0..count {
let group = self
.heap
.load_typed(registry, source, source_start + i)
.map_err(|e| self.value_trap(e, opcode, pc))?;
prepared.push(group).expect("complete scratch reservation");
}
// Snapshot captured. No allocation, validation, GC, callback or scheduler.
for (i, group) in prepared.iter().enumerate() {
self.heap.commit_typed(target, target_start + i, group.as_slice());
}
self.operand_stack.truncate(base);
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::planned_cost;
#[test]
fn checked_cost_covers_the_full_sum_without_wrap_or_saturation() {
assert_eq!(planned_cost(10, 1), Some(24));
assert_eq!(planned_cost(10, 3), Some(64));
assert_eq!(planned_cost(0, u64::MAX), Some(4));
assert_eq!(planned_cost(u32::MAX, 3), Some(25_769_803_774));
// Synthetic widths exercise defensive overflow, not valid guest layouts.
assert_eq!(planned_cost(1, u64::MAX), None);
assert_eq!(planned_cost(1, u64::MAX / 2), None);
assert_eq!(planned_cost(u32::MAX, u64::MAX), None);
}
}
@@ -0,0 +1,487 @@
use super::collection_test_support as support;
use super::*;
use crate::ValidatedProgramImage;
use prometeu_bytecode::{assemble, registry::TypeId};
use support::Native;
fn machine(instruction: &str, count: usize) -> VirtualMachine {
let mut text = String::new();
for i in 0..count {
text += &format!("GET_GLOBAL {i}\n");
}
text += instruction;
text += "\nHALT";
let mut vm = VirtualMachine::from_image(
support::load(&assemble(&text).unwrap()).unwrap(),
RuntimeLimits::default(),
);
vm.prepare_boot_call().unwrap();
vm
}
fn operands(vm: &mut VirtualMachine, values: &[Value]) {
vm.globals.extend_from_slice(values).unwrap();
for _ in values {
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
}
fn step(vm: &mut VirtualMachine) -> Result<(), LogicalFrameEndingReason> {
vm.step(&mut Native, &mut HostContext::new(None))
}
#[test]
fn raw_copy_preserves_absence_and_box_identity_without_heap_allocations() {
let mut vm = machine("ARRAY_COPY 15", 5);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let a = vm.heap.allocate_typed_array(registry.clone(), TypeId(15), 4).unwrap();
let boxed = vm
.heap
.allocate_dynamic_box(registry.clone(), TypeId(5), &[Value::Float(1.), Value::Float(2.)])
.unwrap();
let present = [Value::Int64(5), Value::HeapRef(boxed)];
vm.heap.store_typed(&registry, a, 0, &present).unwrap();
operands(
&mut vm,
&[Value::HeapRef(a), Value::Int64(0), Value::HeapRef(a), Value::Int64(1), Value::Int64(3)],
);
let before = vm.heap.allocation_count();
vm.budget
.test_lower_limit(RuntimeResource::GuestBytes, vm.budget.used(RuntimeResource::GuestBytes));
step(&mut vm).unwrap();
assert_eq!(vm.heap.allocation_count(), before);
assert_eq!(vm.heap.load_typed(&registry, a, 1).unwrap().as_slice(), present);
for i in [2, 3] {
assert_eq!(
vm.heap.load_typed(&registry, a, i).unwrap().as_slice(),
[Value::Null, Value::Null]
);
}
}
fn pair(ty: u32, len: u32) -> (VirtualMachine, HeapRef, HeapRef) {
let mut vm = machine(&format!("ARRAY_COPY {ty}"), 5);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let source = vm.heap.allocate_typed_array(registry.clone(), TypeId(ty), len).unwrap();
let target = vm.heap.allocate_typed_array(registry, TypeId(ty), len).unwrap();
(vm, source, target)
}
fn copy_inputs(source: HeapRef, target: HeapRef, count: i64) -> [Value; 5] {
[
Value::HeapRef(source),
Value::Int64(0),
Value::HeapRef(target),
Value::Int64(0),
Value::Int64(count),
]
}
fn refused(vm: &mut VirtualMachine, code: u32, cost: u64) {
let inputs = vm.operand_stack.as_slice().to_vec();
let (pc, cycles, temporary, objects) =
(vm.pc, vm.cycles, vm.budget.used(RuntimeResource::TemporaryBytes), vm.heap.len());
let LogicalFrameEndingReason::Trap(info) = step(vm).unwrap_err() else { panic!() };
assert_eq!((info.code, info.opcode, info.pc), (code, 0xa9, pc as u32));
assert_eq!(vm.cycles - cycles, cost);
assert_eq!(vm.operand_stack.as_slice(), inputs);
assert_eq!(vm.budget.used(RuntimeResource::TemporaryBytes), temporary);
assert_eq!(vm.heap.len(), objects);
}
#[test]
fn calculable_work_is_precharged_on_receivers_carriers_and_ranges_in_fault_order() {
for case in 0..20 {
let (mut vm, source, target) = pair(11, 10);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let wrong = vm.heap.allocate_typed_struct(registry.clone(), TypeId(19)).unwrap();
let foreign = support::load(&assemble("HALT").unwrap()).unwrap();
let foreign_ref =
vm.heap.allocate_typed_array(foreign.registry().clone(), TypeId(11), 10).unwrap();
let stale = HeapRef { index: source.index, generation: source.generation + 1 };
let mut inputs = copy_inputs(source, target, 10);
let (offset, value, code) = match case {
0 => (0, Value::Null, TRAP_NULL_REFERENCE),
1 => (2, Value::Null, TRAP_NULL_REFERENCE),
2 => (0, Value::HeapRef(stale), TRAP_INVALID_HANDLE),
3 => (2, Value::HeapRef(stale), TRAP_INVALID_HANDLE),
4 => (0, Value::HeapRef(wrong), TRAP_TYPE),
5 => (2, Value::HeapRef(wrong), TRAP_TYPE),
6 => (0, Value::HeapRef(foreign_ref), TRAP_TYPE),
7 => (2, Value::Int32(0), TRAP_TYPE),
8 => (1, Value::Int32(0), TRAP_TYPE),
9 => (3, Value::Null, TRAP_TYPE),
10 => (1, Value::Int64(-1), TRAP_OOB),
11 => (3, Value::Int64(-1), TRAP_OOB),
12 => (1, Value::Int64(1), TRAP_OOB),
13 => (3, Value::Int64(1), TRAP_OOB),
14 => {
inputs[1] = Value::Int32(0); // Receiver fault precedes offset carrier.
(2, Value::Null, TRAP_NULL_REFERENCE)
}
15 => {
inputs[1] = Value::Int64(-1); // All carriers precede source range.
(3, Value::Int32(0), TRAP_TYPE)
}
16 => (0, Value::Int32(0), TRAP_TYPE),
17 => {
let wrong_array =
vm.heap.allocate_typed_array(registry.clone(), TypeId(22), 10).unwrap();
(2, Value::HeapRef(wrong_array), TRAP_TYPE)
}
18 => (1, Value::Int64(i64::MAX), TRAP_OOB),
_ => (3, Value::Int64(i64::MAX), TRAP_OOB),
};
inputs[offset] = value;
operands(&mut vm, &inputs);
// Quota refusal must not mask earlier faults, even with full cost selected.
vm.budget.test_lower_limit(
RuntimeResource::TemporaryBytes,
vm.budget.used(RuntimeResource::TemporaryBytes),
);
refused(&mut vm, code, 24);
for i in 0..10 {
assert_eq!(
vm.heap.load_typed(&registry, target, i).unwrap().as_slice(),
[Value::Int32(0)]
);
}
}
}
#[test]
fn invalid_count_selects_only_base_without_reordering_ordinary_faults() {
for count in [
Value::Int32(10),
Value::Null,
Value::Int64(-1),
Value::Int64(u32::MAX as i64 + 1),
Value::Int64(i64::MAX),
] {
for bad_receiver in [false, true] {
let (mut vm, source, target) = pair(11, 10);
let mut inputs = copy_inputs(source, target, 0);
inputs[4] = count.clone();
if bad_receiver {
inputs[0] = Value::Null;
}
operands(&mut vm, &inputs);
let code = if bad_receiver {
TRAP_NULL_REFERENCE
} else if matches!(count, Value::Int64(_)) {
TRAP_OOB
} else {
TRAP_TYPE
};
refused(&mut vm, code, 4);
}
}
}
#[test]
fn incomplete_temporary_operands_never_read_frame_locals_for_cost() {
let code = assemble(
"GET_GLOBAL 0\nGET_GLOBAL 1\nGET_GLOBAL 2\nGET_GLOBAL 3\nGET_GLOBAL 4\nARRAY_COPY 11\nHALT",
)
.unwrap();
for available in 0..5 {
let mut declarations = support::declarations(code.len());
declarations.functions[0].local_slots = 5;
let image = ValidatedProgramImage::load(
&support::bytes_with(&code, declarations),
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
prometeu_hal::syscalls::caps::NONE,
)
.unwrap();
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
// Internal defense: skip the verified producers, leaving only locals and
// an incomplete temporary group. This is not an admitted bad program.
vm.operand_stack[4] = Value::Int64(10);
vm.operand_stack.extend_from_slice(&vec![Value::Int64(10); available]).unwrap();
vm.pc = 30;
refused(&mut vm, TRAP_STACK_UNDERFLOW, 4);
}
}
#[test]
fn overlap_snapshots_complete_multislot_groups_and_has_no_identity_discount() {
for (source_start, target_start, count) in [(0, 1, 3), (1, 0, 3), (0, 0, 4)] {
for refuse in [false, true] {
let mut vm = machine("ARRAY_COPY 12", 5);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let array = vm.heap.allocate_typed_array(registry.clone(), TypeId(12), 4).unwrap();
for i in 0..4 {
vm.heap
.store_typed(
&registry,
array,
i,
&[Value::Float(i as f64), Value::Float(i as f64 + 10.)],
)
.unwrap();
}
let before: Vec<_> = (0..4)
.map(|i| vm.heap.load_typed(&registry, array, i).unwrap().as_slice().to_vec())
.collect();
operands(
&mut vm,
&[
Value::HeapRef(array),
Value::Int64(source_start),
Value::HeapRef(array),
Value::Int64(target_start),
Value::Int64(count),
],
);
let temporary = vm.budget.used(RuntimeResource::TemporaryBytes);
if refuse {
vm.budget.test_lower_limit(RuntimeResource::TemporaryBytes, temporary);
refused(&mut vm, TRAP_RESOURCE_LIMIT, if count == 3 { 16 } else { 20 });
} else {
let cycles = vm.cycles;
step(&mut vm).unwrap();
assert_eq!(vm.cycles - cycles, if count == 3 { 16 } else { 20 });
assert!(vm.operand_stack.is_empty());
}
for i in 0..4 {
let expected =
if !refuse && i >= target_start as usize && i < (target_start + count) as usize
{
&before[(i as i64 - target_start + source_start) as usize]
} else {
&before[i]
};
assert_eq!(vm.heap.load_typed(&registry, array, i).unwrap().as_slice(), expected);
}
assert_eq!(vm.budget.used(RuntimeResource::TemporaryBytes), temporary);
}
}
}
#[test]
fn scratch_quota_and_allocator_refusals_preserve_all_destinations_and_work() {
for allocation_failure in [false, true] {
let (mut vm, source, target) = pair(11, 10);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
for i in 0..10 {
vm.heap.store_typed(&registry, source, i, &[Value::Int32(i as i32 + 1)]).unwrap();
}
operands(&mut vm, &copy_inputs(source, target, 10));
if allocation_failure {
crate::resource_budget::FAIL_NEXT_VEC_ALLOCATION.with(|fail| fail.set(true));
} else {
vm.budget.test_lower_limit(
RuntimeResource::TemporaryBytes,
vm.budget.used(RuntimeResource::TemporaryBytes),
);
}
let (cycles, temporary) = (vm.cycles, vm.budget.used(RuntimeResource::TemporaryBytes));
let LogicalFrameEndingReason::Trap(info) = step(&mut vm).unwrap_err() else { panic!() };
assert_eq!((info.code, info.opcode, info.pc), (TRAP_RESOURCE_LIMIT, 0xa9, 30));
let resource = info.resource.unwrap();
assert_eq!(resource.resource, RuntimeResource::TemporaryBytes);
assert_eq!(
resource.reason,
if allocation_failure {
crate::resource_budget::ResourceReason::AllocationFailed
} else {
crate::resource_budget::ResourceReason::Limit
}
);
assert_eq!(vm.cycles - cycles, 24);
assert_eq!(vm.budget.used(RuntimeResource::TemporaryBytes), temporary);
assert_eq!(vm.operand_stack.as_slice(), copy_inputs(source, target, 10));
for i in 0..10 {
assert_eq!(
vm.heap.load_typed(&registry, target, i).unwrap().as_slice(),
[Value::Int32(0)]
);
}
}
}
#[test]
fn late_invalid_source_group_releases_partial_preparation_without_any_write() {
let (mut vm, source, target) = pair(17, 10);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let node = vm.heap.allocate_typed_struct(registry.clone(), TypeId(9)).unwrap();
vm.heap.store_typed(&registry, source, 0, &[Value::HeapRef(node)]).unwrap();
// Internal corruption of the last stored handle exercises a late read fault.
vm.heap.commit_typed(
source,
9,
&[Value::HeapRef(HeapRef { index: node.index, generation: node.generation + 1 })],
);
operands(&mut vm, &copy_inputs(source, target, 10));
refused(&mut vm, TRAP_INVALID_HANDLE, 24);
for i in 0..10 {
assert_eq!(vm.heap.load_typed(&registry, target, i).unwrap().as_slice(), [Value::Null]);
}
}
#[test]
fn empty_copy_validates_both_receivers_and_strict_ranges_without_scratch() {
for case in 0..5 {
let (mut vm, source, target) = pair(11, 2);
let mut inputs = copy_inputs(source, target, 0);
inputs[1] = Value::Int64(2);
inputs[3] = Value::Int64(2);
let code = match case {
0 => None,
1 => {
inputs[0] = Value::Null;
Some(TRAP_NULL_REFERENCE)
}
2 => {
inputs[2] = Value::Null;
Some(TRAP_NULL_REFERENCE)
}
3 => {
inputs[1] = Value::Int64(3);
Some(TRAP_OOB)
}
_ => {
inputs[3] = Value::Int64(-1);
Some(TRAP_OOB)
}
};
operands(&mut vm, &inputs);
vm.budget.test_lower_limit(
RuntimeResource::TemporaryBytes,
vm.budget.used(RuntimeResource::TemporaryBytes),
);
if let Some(code) = code {
refused(&mut vm, code, 4);
} else {
let cycles = vm.cycles;
step(&mut vm).unwrap();
assert_eq!(vm.cycles - cycles, 4);
assert!(vm.operand_stack.is_empty());
}
}
}
#[test]
fn zero_budget_and_positive_overshoot_preserve_trap_priority_and_step_count() {
for fail in [false, true] {
let (mut vm, source, target) = pair(11, 10);
operands(&mut vm, &copy_inputs(source, target, 10));
if fail {
vm.budget.test_lower_limit(
RuntimeResource::TemporaryBytes,
vm.budget.used(RuntimeResource::TemporaryBytes),
);
}
let (pc, cycles, inputs) = (vm.pc, vm.cycles, vm.operand_stack.as_slice().to_vec());
let report = vm.run_budget(0, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!((report.cycles_used, report.steps_executed), (0, 0));
assert_eq!((vm.pc, vm.cycles), (pc, cycles));
assert_eq!(vm.operand_stack.as_slice(), inputs);
let report = vm.run_budget(1, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!((report.cycles_used, report.steps_executed), (24, if fail { 0 } else { 1 }));
if fail {
let LogicalFrameEndingReason::Trap(info) = report.reason else { panic!() };
assert_eq!((info.code, info.opcode, info.pc), (TRAP_RESOURCE_LIMIT, 0xa9, pc as u32));
assert_eq!(vm.operand_stack.as_slice(), inputs);
} else {
assert_eq!(report.reason, LogicalFrameEndingReason::BudgetExhausted);
}
}
}
#[test]
fn copied_groups_preserve_owners_and_references_through_collection_without_guest_growth() {
for ty in [11, 12, 13, 14, 15, 16, 17] {
let (mut vm, source, target) = pair(ty, 1);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let node = vm.heap.allocate_typed_struct(registry.clone(), TypeId(9)).unwrap();
vm.push(Value::String(std::sync::Arc::from("copy owner"))).unwrap();
let string = vm.pop().unwrap();
let group = match ty {
11 => vec![Value::Int32(7)],
12 => vec![Value::Float(1.), Value::Float(2.)],
13 => vec![Value::Int64(1), Value::Int64(2), Value::Int64(3)],
14 => vec![string.clone()],
15 => vec![Value::Int64(4), string.clone()],
16 => vec![Value::HeapRef(node), Value::Int64(0)],
_ => vec![Value::HeapRef(node)],
};
vm.heap.store_typed(&registry, source, 0, &group).unwrap();
operands(&mut vm, &copy_inputs(source, target, 1));
let objects = vm.heap.allocation_count();
let guest = vm.budget.used(RuntimeResource::GuestBytes);
for q in [
RuntimeResource::GuestBytes,
RuntimeResource::HandleSlots,
RuntimeResource::AuxiliaryBytes,
] {
vm.budget.test_lower_limit(q, vm.budget.used(q));
}
let cycles = vm.cycles;
step(&mut vm).unwrap();
assert_eq!(
vm.cycles - cycles,
match ty {
12 | 15 | 16 => 8,
13 => 10,
_ => 6,
}
);
assert_eq!(vm.heap.allocation_count(), objects);
assert_eq!(vm.budget.used(RuntimeResource::GuestBytes), guest);
assert_eq!(vm.heap.load_typed(&registry, target, 0).unwrap().as_slice(), group);
drop(group);
drop(string);
vm.globals.clear();
vm.globals.push(Value::HeapRef(target)).unwrap();
vm.gc_alloc_threshold = 1;
vm.handle_safepoint().unwrap();
assert!(!vm.heap.is_valid(source));
assert!(vm.heap.is_valid(target));
if [16, 17].contains(&ty) {
assert!(vm.heap.is_valid(node));
}
if [14, 15].contains(&ty) {
assert_eq!(vm.budget.used(RuntimeResource::StringAllocations), 1);
}
// Remove all roots and collect using the actual session root traversal.
vm.globals.clear();
vm.last_gc_live_count = 0;
vm.handle_safepoint().unwrap();
assert_eq!(vm.heap.len(), 0);
assert_eq!(vm.budget.used(RuntimeResource::StringAllocations), 0);
}
}
#[test]
fn refused_copy_keeps_source_and_previous_target_native_owners_rooted() {
let (mut vm, source, target) = pair(14, 1);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
for (array, text) in [(source, "candidate owner"), (target, "previous owner")] {
vm.push(Value::String(std::sync::Arc::from(text))).unwrap();
let value = vm.pop().unwrap();
vm.heap.store_typed(&registry, array, 0, &[value]).unwrap();
}
operands(&mut vm, &copy_inputs(source, target, 1));
let temporary = vm.budget.used(RuntimeResource::TemporaryBytes);
vm.budget.test_lower_limit(RuntimeResource::TemporaryBytes, temporary);
refused(&mut vm, TRAP_RESOURCE_LIMIT, 6);
assert_eq!(
vm.heap.load_typed(&registry, source, 0).unwrap().as_slice(),
[Value::String(std::sync::Arc::from("candidate owner"))]
);
assert_eq!(
vm.heap.load_typed(&registry, target, 0).unwrap().as_slice(),
[Value::String(std::sync::Arc::from("previous owner"))]
);
vm.budget.test_lower_limit(
RuntimeResource::TemporaryBytes,
RuntimeLimits::default().get(RuntimeResource::TemporaryBytes),
);
vm.globals.clear(); // Failed operands are now the only session roots.
vm.gc_alloc_threshold = 1;
vm.handle_safepoint().unwrap();
assert!(vm.heap.is_valid(source) && vm.heap.is_valid(target));
assert_eq!(vm.budget.used(RuntimeResource::StringAllocations), 2);
vm.operand_stack.clear();
vm.last_gc_live_count = 0;
vm.handle_safepoint().unwrap();
assert_eq!(vm.heap.len(), 0);
assert_eq!(vm.budget.used(RuntimeResource::StringAllocations), 0);
}
@@ -175,7 +175,7 @@ impl VirtualMachine {
.expect("result capacity reserved before publication");
Ok(())
}
fn collection_size_trap(
pub(super) fn collection_size_trap(
&self,
opcode: OpCode,
pc: u32,
@@ -1,6 +1,5 @@
use super::collection_test_support as support;
use super::*;
#[path = "../../tests/support/collections.rs"]
mod support;
use crate::value_contract::ValueError;
use prometeu_bytecode::assemble;
use support::Native;
@@ -0,0 +1,59 @@
use super::*;
use crate::value_contract;
use prometeu_bytecode::registry::TypeId;
impl VirtualMachine {
pub(super) fn execute_identity(
&mut self,
opcode: OpCode,
left: u32,
right: Option<u32>,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
let image = self.validated_image.clone().ok_or_else(|| {
self.trap(
prometeu_bytecode::TRAP_ILLEGAL_INSTRUCTION,
opcode as u16,
"Identity instruction requires a validated Registry".into(),
pc,
)
})?;
let registry = image.registry();
let left = TypeId(left);
let right = right.map(TypeId);
let lw = registry.type_layout(left).unwrap().storage.slots as usize;
let rw = right.map_or(0, |ty| registry.type_layout(ty).unwrap().storage.slots as usize);
self.cycles += opcode.cycles() + (lw + rw) as u64;
if self.temporary_slots() < lw + rw {
return Err(self.trap(
TRAP_STACK_UNDERFLOW,
opcode as u16,
"Incomplete identity operands".into(),
pc,
));
}
let base = self.operand_stack.len() - lw - rw;
let first = value_contract::identity_reference(
registry,
&self.heap,
left,
&self.operand_stack[base..base + lw],
)
.map_err(|e| self.value_trap(e, opcode, pc))?;
let result = if let Some(ty) = right {
let second = value_contract::identity_reference(
registry,
&self.heap,
ty,
&self.operand_stack[base + lw..],
)
.map_err(|e| self.value_trap(e, opcode, pc))?;
Value::Boolean(first == second)
} else {
Value::Int64(crate::hashing::reference(first))
};
self.operand_stack.truncate(base);
self.operand_stack.push(result).expect("identity result replaces existing inputs");
Ok(())
}
}
@@ -0,0 +1,236 @@
use super::*;
#[path = "../../tests/support/identity.rs"]
mod support;
use crate::{
IntrinsicExecutionError, IntrinsicImplementation, IntrinsicMeta, IntrinsicResults,
hash_intrinsics::HASH_INTRINSICS,
};
use prometeu_bytecode::{HeapRef, RuntimeResource as Q, registry::TypeId};
use std::sync::Arc;
use support::*;
fn empty() -> VirtualMachine {
vm(&[("RET", sig(&[], &[]))], &[])
}
fn push(v: &mut VirtualMachine, values: &[Value]) {
for value in values {
v.operand_stack.push(value.clone()).unwrap();
}
}
fn usage(v: &VirtualMachine) -> Vec<u64> {
[
Q::GuestBytes,
Q::HandleSlots,
Q::AuxiliaryBytes,
Q::TemporaryBytes,
Q::StringBytes,
Q::StringAllocations,
]
.map(|q| v.budget.used(q))
.to_vec()
}
fn fault(result: Result<(), LogicalFrameEndingReason>, expected: u32) {
assert!(
matches!(result,Err(LogicalFrameEndingReason::Trap(ref t)) if t.code==expected),
"{result:?}"
);
}
fn hash(v: &mut VirtualMachine, ty: u32, values: &[Value]) -> i64 {
push(v, values);
v.execute_identity(OpCode::RefIdentityHash, ty, None, 0).unwrap();
let Value::Int64(value) = v.operand_stack.pop().unwrap() else { panic!() };
value
}
#[test]
fn identity_faults_preserve_complete_groups_and_charge_once_in_left_to_right_order() {
let mut v = empty();
let registry = v.validated_image.as_ref().unwrap().registry().clone();
let live = v.heap.allocate_typed_struct(registry.clone(), TypeId(5)).unwrap();
let wrong = v.heap.allocate_typed_struct(registry, TypeId(11)).unwrap();
let stale = HeapRef { index: 999999, generation: 1 };
for (left, right, values, code) in [
(5, None, vec![Value::HeapRef(stale)], TRAP_INVALID_HANDLE),
(5, None, vec![Value::HeapRef(wrong)], TRAP_TYPE),
(5, None, vec![Value::HeapRef(HeapRef::NULL)], TRAP_TYPE),
(6, None, vec![Value::HeapRef(live)], TRAP_TYPE),
(9, None, vec![Value::HeapRef(HeapRef::NULL)], TRAP_TYPE),
(10, None, vec![Value::HeapRef(HeapRef::NULL)], TRAP_INVALID_HANDLE),
(7, None, vec![Value::Null, Value::Int64(0)], TRAP_TYPE),
(7, None, vec![Value::HeapRef(live), Value::Null], TRAP_TYPE),
(7, None, vec![Value::HeapRef(live), Value::Int64(1)], TRAP_TYPE),
(7, None, vec![Value::HeapRef(live), Value::Int64(-1)], TRAP_TYPE),
(7, None, vec![Value::HeapRef(live), Value::Int64(999)], TRAP_TYPE),
(7, None, vec![Value::HeapRef(stale), Value::Int64(0)], TRAP_INVALID_HANDLE),
// A null left side still validates the complete right group.
(5, Some(7), vec![Value::Null, Value::HeapRef(live), Value::Int64(1)], TRAP_TYPE),
(5, Some(11), vec![Value::Null, Value::HeapRef(stale)], TRAP_INVALID_HANDLE),
// Both invalid: left TYPE takes precedence over right INVALID_HANDLE.
(5, Some(5), vec![Value::HeapRef(wrong), Value::HeapRef(stale)], TRAP_TYPE),
] {
v.operand_stack.truncate(8); // Entry's eight reserved local slots.
push(&mut v, &values);
let operands = v.operand_stack.as_slice().to_vec();
let before = usage(&v);
let cycles = v.cycles;
let op = if right.is_some() { OpCode::RefIdentityEq } else { OpCode::RefIdentityHash };
let width = if left == 7 { 2 } else { 1 } + right.map_or(0, |r| if r == 7 { 2 } else { 1 });
fault(v.execute_identity(op, left, right, 0), code);
assert_eq!(v.operand_stack.as_slice(), operands);
assert_eq!(usage(&v), before);
assert_eq!(v.cycles - cycles, op.cycles() + width);
}
v.operand_stack.truncate(8);
let before = v.cycles;
fault(v.execute_identity(OpCode::RefIdentityEq, 7, Some(7), 0), TRAP_STACK_UNDERFLOW);
assert_eq!(v.cycles - before, 8);
}
#[test]
fn gc_preserves_live_aliases_but_hashes_do_not_root_collected_handles() {
let mut v = empty();
let registry = v.validated_image.as_ref().unwrap().registry().clone();
let live = v.heap.allocate_typed_struct(registry.clone(), TypeId(5)).unwrap();
let dead = v.heap.allocate_typed_struct(registry.clone(), TypeId(5)).unwrap();
let live_hash = hash(&mut v, 5, &[Value::HeapRef(live)]);
let dead_hash = hash(&mut v, 5, &[Value::HeapRef(dead)]);
v.globals.push(Value::HeapRef(live)).unwrap();
v.globals.push(Value::Int64(dead_hash)).unwrap();
v.gc_alloc_threshold = 1;
v.handle_safepoint().unwrap();
assert!(v.heap.is_valid(live));
assert!(!v.heap.is_valid(dead));
assert_eq!(hash(&mut v, 7, &[Value::HeapRef(live), Value::Int64(0)]), live_hash);
let replacement = v.heap.allocate_typed_struct(registry, TypeId(5)).unwrap();
assert_eq!(replacement.index, dead.index);
assert_ne!(replacement.generation, dead.generation);
push(&mut v, &[Value::HeapRef(dead), Value::HeapRef(replacement)]);
fault(v.execute_identity(OpCode::RefIdentityEq, 5, Some(5), 0), TRAP_INVALID_HANDLE);
}
#[test]
fn new_queries_ignore_exhausted_guest_and_scratch_quotas_and_do_not_collect() {
let mut v = empty();
let registry = v.validated_image.as_ref().unwrap().registry().clone();
let live = v.heap.allocate_typed_struct(registry, TypeId(5)).unwrap();
push(&mut v, &[Value::HeapRef(live)]);
for q in [
Q::GuestBytes,
Q::HandleSlots,
Q::AuxiliaryBytes,
Q::TemporaryBytes,
Q::StringBytes,
Q::StringAllocations,
] {
v.budget.test_lower_limit(q, v.budget.used(q));
}
let before = usage(&v);
let allocations = v.heap.allocation_count();
v.gc_alloc_threshold = 1;
v.execute_identity(OpCode::RefIdentityHash, 5, None, 0).unwrap();
v.execute_inline_intrinsic(&HASH_INTRINSICS[0], 0).unwrap();
assert_eq!(v.heap.allocation_count(), allocations);
assert!(v.heap.is_valid(live)); // No root remains, but neither operation is a safepoint.
assert_eq!(usage(&v), before);
}
#[test]
fn inline_faults_preserve_float_bits_owners_and_attempted_cost() {
let mut v = empty();
for bits in [f64::INFINITY.to_bits(), f64::NEG_INFINITY.to_bits(), 0x7ff8000000001234] {
push(&mut v, &[Value::Float(f64::from_bits(bits))]);
let before = usage(&v);
let cycles = v.cycles;
fault(
v.execute_inline_intrinsic(&HASH_INTRINSICS[1], 0),
prometeu_bytecode::TRAP_NON_FINITE,
);
assert!(matches!(v.operand_stack.last(),Some(Value::Float(f)) if f.to_bits()==bits));
assert_eq!(usage(&v), before);
assert_eq!(v.cycles - cycles, 8);
v.operand_stack.pop();
}
let foreign: Arc<str> = Arc::from("owner outside image and session");
push(&mut v, &[Value::String(foreign.clone())]);
let refs = Arc::strong_count(&foreign);
let before = usage(&v);
let cycles = v.cycles;
fault(v.execute_inline_intrinsic(&HASH_INTRINSICS[2], 0), TRAP_TYPE);
assert_eq!(Arc::strong_count(&foreign), refs);
assert_eq!(usage(&v), before);
assert_eq!(v.cycles - cycles, 8 + foreign.len() as u64);
let mut overflow = HASH_INTRINSICS[2];
overflow.cost_per_byte = u64::MAX;
let cycles = v.cycles;
fault(v.execute_inline_intrinsic(&overflow, 0), TRAP_RESOURCE_LIMIT);
assert_eq!(v.cycles - cycles, 8);
assert_eq!(Arc::strong_count(&foreign), refs);
v.operand_stack.pop();
let cycles = v.cycles;
fault(v.execute_inline_intrinsic(&HASH_INTRINSICS[2], 0), TRAP_STACK_UNDERFLOW);
assert_eq!(v.cycles - cycles, 8);
push(&mut v, &[Value::Int64(7)]);
let cycles = v.cycles;
fault(v.execute_inline_intrinsic(&HASH_INTRINSICS[2], 0), TRAP_TYPE);
assert_eq!(v.cycles - cycles, 8);
assert_eq!(v.operand_stack.last(), Some(&Value::Int64(7)));
}
#[test]
fn equal_string_content_hashes_across_image_session_and_import_owners() {
use prometeu_bytecode::model::ConstantPoolEntry as K;
let mut v = vm(
&[("PUSH_CONST 0\nINTRINSIC 0x4102\nRET", sig(&[], &[0]))],
&[K::String("same\0π".into())],
);
step(&mut v).unwrap();
let Value::String(image_owner) = v.operand_stack.last().unwrap().clone() else { panic!() };
v.strings = Some(crate::string_ledger::StringLedger::new(v.budget.clone()).unwrap());
let session = v.strings.as_ref().unwrap().concat("same", "\0π").unwrap();
let imported = v.strings.as_ref().unwrap().import("same\0π").unwrap();
assert!(!Arc::ptr_eq(&session, &imported));
let mut hashes = vec![];
v.operand_stack.pop();
for owner in [&image_owner, &session, &imported] {
push(&mut v, &[Value::String(owner.clone())]);
let before = usage(&v);
let count = Arc::strong_count(owner);
v.execute_inline_intrinsic(&HASH_INTRINSICS[2], 0).unwrap();
assert_eq!(usage(&v), before);
assert_eq!(Arc::strong_count(owner), count - 1);
hashes.push(v.operand_stack.pop().unwrap());
}
assert!(hashes.windows(2).all(|pair| pair[0] == pair[1]));
}
fn missing(_: &[Value], _: &mut IntrinsicResults) -> Result<(), IntrinsicExecutionError> {
Ok(())
}
fn wrong(_: &[Value], out: &mut IntrinsicResults) -> Result<(), IntrinsicExecutionError> {
out.push(Value::Boolean(true))
}
fn excess(_: &[Value], out: &mut IntrinsicResults) -> Result<(), IntrinsicExecutionError> {
out.push(Value::Int64(1))?;
let _ = out.push(Value::Int64(2)); // Ignoring the error cannot publish a partial result.
Ok(())
}
#[test]
fn shared_invocation_rejects_bad_outputs_without_consuming_original_string_owner() {
let mut v = empty();
let Value::String(content) = v.import_string_value(&Value::String(Arc::from("kept"))).unwrap()
else {
panic!()
};
push(&mut v, &[Value::String(content.clone())]);
let count = Arc::strong_count(&content);
let before = usage(&v);
for handler in [missing, wrong, excess] {
let mut meta: IntrinsicMeta = HASH_INTRINSICS[2];
meta.owner = "test"; // The shared executor is independent of the hash namespace.
meta.implementation = IntrinsicImplementation::BorrowedInline(handler);
fault(v.execute_inline_intrinsic(&meta, 0), TRAP_INVALID_INTRINSIC);
assert_eq!(Arc::strong_count(&content), count);
assert_eq!(usage(&v), before);
assert!(matches!(v.operand_stack.last(),Some(Value::String(s)) if Arc::ptr_eq(s,&content)));
}
}
@@ -0,0 +1,113 @@
//! Shared borrowed invocation; algorithms receive no host/VM context.
use super::*;
use crate::{
AbiType, IntrinsicExecutionError as E, IntrinsicImplementation as I, IntrinsicMeta,
IntrinsicResults,
};
impl VirtualMachine {
fn inline_values(
&self,
values: &[Value],
layout: &[AbiType],
) -> Result<(), crate::value_contract::ValueError> {
use crate::value_contract::ValueError;
for (value, abi) in values.iter().zip(layout) {
match value {
Value::String(content) if self.validated_image.is_some() => {
if !self.validated_image.as_ref().unwrap().retains_string(content)
&& !self.strings.as_ref().is_some_and(|domain| domain.retains(content))
{
return Err(ValueError::Type);
}
}
Value::HeapRef(reference) if matches!(abi, AbiType::Builtin(key) if key.name == "Random") =>
{
self.heap.random_state(*reference)?;
}
_ => {}
}
}
Ok(())
}
pub(super) fn execute_inline_intrinsic(
&mut self,
meta: &IntrinsicMeta,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
let op = OpCode::Intrinsic;
let consumed = meta.arg_slots();
let enough = self.temporary_slots() >= consumed;
let args =
if enough { &self.operand_stack[self.operand_stack.len() - consumed..] } else { &[] };
let Some(cost) = meta.attempted_cost(args) else {
self.cycles += meta.cost_cycles;
return Err(self.trap(
TRAP_RESOURCE_LIMIT,
op as u16,
"Intrinsic attempted cost overflow".into(),
pc,
));
};
self.cycles += cost;
meta.validate_descriptor()
.map_err(|message| self.trap(TRAP_INVALID_INTRINSIC, op as u16, message.into(), pc))?;
if !enough {
return Err(self.trap(
TRAP_STACK_UNDERFLOW,
op as u16,
"Incomplete intrinsic operands".into(),
pc,
));
}
let I::BorrowedInline(handler) = meta.implementation else {
return Err(self.trap(
TRAP_INVALID_INTRINSIC,
op as u16,
"Wrong invocation profile".into(),
pc,
));
};
let base = self.operand_stack.len() - consumed;
let args = &self.operand_stack[base..];
meta.validate_argument_values(args).map_err(|_| {
self.trap(TRAP_TYPE, op as u16, "Invalid intrinsic argument carrier".into(), pc)
})?;
self.inline_values(args, meta.arg_layout)
.map_err(|error| self.value_trap(error, op, pc))?;
let mut out = IntrinsicResults::new(meta.ret_slots());
handler(args, &mut out).map_err(|error| match error {
E::Numeric(error) => {
self.trap(error.code, op as u16, format!("Intrinsic numeric fault: {error:?}"), pc)
}
_ => self.trap(
TRAP_INVALID_INTRINSIC,
op as u16,
format!("Invalid intrinsic handler output: {error:?}"),
pc,
),
})?;
out.validate(meta).map_err(|error| {
self.trap(
TRAP_INVALID_INTRINSIC,
op as u16,
format!("Invalid intrinsic result: {error:?}"),
pc,
)
})?;
self.inline_values(out.as_slice(), meta.ret_layout).map_err(|_| {
self.trap(
TRAP_INVALID_INTRINSIC,
op as u16,
"Invalid intrinsic result ownership".into(),
pc,
)
})?;
self.operand_stack.truncate(base);
for value in out.into_values() {
self.operand_stack.push(value).expect("bounded result replaces admitted inputs");
}
Ok(())
}
}
@@ -132,3 +132,39 @@ fn collection_load_limits_and_analysis_refusals_keep_context_and_refund_scratch(
assert_eq!(budget.used(LoadResource::RegistryBytes), 0);
}
}
#[test]
fn removed_storage_opcodes_reject_even_in_unreachable_instruction_positions() {
use prometeu_bytecode::load_limits::{LoadCode, LoadReason};
use prometeu_vm::VmInitError;
for opcode in [0xa7u16, 0xa8, 0xaa, 0xab] {
for dead in [false, true] {
let mut code = if dead { vec![1, 0] } else { vec![] };
let pc = code.len() as u32;
code.extend_from_slice(&opcode.to_le_bytes());
let VmInitError::RegistryLoadFailed(error) = load(&code).unwrap_err() else { panic!() };
assert_eq!(error.code, LoadCode::InvalidCode);
assert_eq!(error.reason, LoadReason::UnknownOpcode);
assert_eq!((error.function, error.pc), (Some(0), Some(pc)));
}
}
// The same bytes are accepted as an Int64 immediate, never decoded as opcodes.
let code = [0x14, 0, 0xa7, 0, 0xa8, 0, 0xaa, 0, 0xab, 0, 1, 0];
assert_eq!(
run(&code),
[Value::Int64(i64::from_le_bytes([0xa7, 0, 0xa8, 0, 0xaa, 0, 0xab, 0]))]
);
}
#[test]
fn neutral_pbx_copy_moves_a_range_and_preserves_physical_length() {
let code=assemble("PUSH_I64 2\nARRAY_NEW 11\nSET_GLOBAL 0\nGET_GLOBAL 0\nPUSH_I64 0\nPUSH_I32 42\nARRAY_SET 11\nGET_GLOBAL 0\nPUSH_I64 0\nGET_GLOBAL 0\nPUSH_I64 1\nPUSH_I64 1\nARRAY_COPY 11\nGET_GLOBAL 0\nPUSH_I64 1\nARRAY_GET 11\nGET_GLOBAL 0\nARRAY_LEN 11\nHALT").unwrap();
assert_eq!(run(&code), [Value::Int64(2), Value::Int32(42)]);
for text in [
"HALT\nARRAY_COPY 9",
"HALT\nARRAY_COPY 99",
"PUSH_I64 1\nARRAY_NEW 11\nPUSH_I64 0\nPUSH_I64 1\nARRAY_NEW 11\nPUSH_I64 0\nPUSH_BOOL 1\nARRAY_COPY 11\nHALT",
] {
assert!(load(&assemble(text).unwrap()).is_err(), "{text}");
}
}
@@ -134,3 +134,96 @@ fn provenance_queries_allocate_nothing_at_all_qualification_sizes() {
assert_eq!(counts, (1, 1), "only snapshot Value storage allocates");
}
}
#[path = "support/identity.rs"]
mod identity_support;
#[test]
fn identity_and_borrowed_hash_instruction_regions_do_not_allocate() {
use prometeu_bytecode::model::ConstantPoolEntry as K;
for (name, initialize, operand, operation, steps, closure) in [
("hash_i64", "PUSH_I64 -73\nSET_LOCAL 0", "GET_LOCAL 0", "INTRINSIC 0x4100", 4, false),
("hash_float", "PUSH_CONST 0\nSET_LOCAL 0", "GET_LOCAL 0", "INTRINSIC 0x4101", 4, false),
("hash_string", "PUSH_CONST 1\nSET_LOCAL 0", "GET_LOCAL 0", "INTRINSIC 0x4102", 4, false),
(
"struct_hash",
"STRUCT_NEW 5\nSET_LOCAL 0",
"GET_LOCAL 0",
"REF_IDENTITY_HASH 5",
4,
false,
),
(
"array_hash",
"PUSH_I64 0\nARRAY_NEW 6\nSET_LOCAL 0",
"GET_LOCAL 0",
"REF_IDENTITY_HASH 6",
4,
false,
),
(
"fn_hash",
"MAKE_CLOSURE fn=1,type=9\nSET_LOCAL 0",
"GET_LOCAL 0",
"REF_IDENTITY_HASH 9",
4,
true,
),
(
"random_hash",
"PUSH_I64 1\nINTRINSIC 0x4000\nSET_LOCAL 0",
"GET_LOCAL 0",
"REF_IDENTITY_HASH 10",
4,
false,
),
(
"trait_hash",
"STRUCT_NEW 5\nREF_TO_TRAIT source=5,target=7\nSET_LOCAL 1\nSET_LOCAL 0",
"GET_LOCAL 0\nGET_LOCAL 1",
"REF_IDENTITY_HASH 7",
5,
false,
),
(
"struct_eq",
"STRUCT_NEW 5\nSET_LOCAL 0",
"GET_LOCAL 0\nGET_LOCAL 0",
"REF_IDENTITY_EQ left=5,right=5",
5,
false,
),
(
"trait_eq",
"STRUCT_NEW 5\nREF_TO_TRAIT source=5,target=7\nSET_LOCAL 1\nSET_LOCAL 0",
"GET_LOCAL 0\nGET_LOCAL 1\nGET_LOCAL 0\nGET_LOCAL 1",
"REF_IDENTITY_EQ left=7,right=7",
7,
false,
),
] {
let start = assemble(initialize).unwrap().len();
let text = format!("{initialize}\n{operand}\n{operation}\nPOP\nJMP {start}");
let mut bodies = vec![(text.as_str(), identity_support::sig(&[], &[]))];
if closure {
bodies.push(("RET", identity_support::sig(&[], &[])));
}
let mut vm =
identity_support::vm(&bodies, &[K::Float64(-0.0), K::String("π\0".repeat(512))]);
let mut host = HostContext::new(None);
while vm.pc() != start {
vm.step(&mut identity_support::Native, &mut host).unwrap();
}
for _ in 0..steps * 10 {
vm.step(&mut identity_support::Native, &mut host).unwrap();
}
let heap_allocations = vm.heap().allocation_count();
COUNTS.with(|c| c.set(Some((0, 0))));
for _ in 0..steps * 1000 {
vm.step(&mut identity_support::Native, &mut host).unwrap();
}
let counts = COUNTS.with(|c| c.replace(None).unwrap());
assert_eq!(counts, (0, 0), "{name}: allocations and deallocations");
assert_eq!(vm.heap().allocation_count(), heap_allocations, "{name}: guest allocations");
}
}
File diff suppressed because one or more lines are too long
@@ -0,0 +1,23 @@
# Hash-v1 oracle provenance
`hash-conformance.tsv` is generated by `hash-oracle.py` against the official C
XXH64 reference, not the Rust VM implementation. Ordinary tests read the checked-in
vectors and need no library, network or Python dependency.
Reference: https://github.com/Cyan4973/xxHash/blob/v0.8.3/xxhash.h
Header SHA-256: `17973c0dc49d9854ca26caa191f0e12f7a424b68858d9a78de3860d959d85e4b`.
The generator verifies both the header digest and `XXH_versionNumber()==803`.
Example reproduction on macOS, after downloading that pinned header:
```sh
clang -dynamiclib -O2 -x c -DXXH_IMPLEMENTATION -DXXH_STATIC_LINKING_ONLY xxhash.h -o libxxhash-oracle.dylib
python3 hash-oracle.py --header xxhash.h --library ./libxxhash-oracle.dylib
```
On Linux, use `-shared -fPIC` instead of `-dynamiclib`. The generator explicitly
encodes little-endian integers/reference components and finite Float bit patterns,
canonicalizes signed zeros, and uses seed zero. The null row is the machine
contract's direct zero result, not a hash of an empty message. Arbitrary `bytes`
rows exercise the internal algorithm; they do not expose guest byte strings.
@@ -0,0 +1,51 @@
"""Regenerate hash-v1 vectors using upstream XXH64, never the Rust executor."""
import argparse
import ctypes
import hashlib
from pathlib import Path
import struct
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--library", required=True, type=Path)
parser.add_argument("--header", required=True, type=Path)
parser.add_argument("--output", type=Path, default=Path(__file__).with_name("hash-conformance.tsv"))
args = parser.parse_args()
expected = "17973c0dc49d9854ca26caa191f0e12f7a424b68858d9a78de3860d959d85e4b"
assert hashlib.sha256(args.header.read_bytes()).hexdigest() == expected
library = ctypes.CDLL(str(args.library.resolve()))
assert library.XXH_versionNumber() == 803
digest = library.XXH64
digest.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_uint64]
digest.restype = ctypes.c_uint64
rows = ["kind\tinput\texpected_hash_hex"]
def emit(kind, value, data):
buffer = ctypes.create_string_buffer(data)
result = digest(ctypes.cast(buffer, ctypes.c_void_p), len(data), 0)
rows.append(f"{kind}\t{value}\t{result:016X}")
for size in list(range(71)) + [95, 96, 97, 127, 128, 129, 255, 256, 257, 1024, 4097]:
data = bytes((i * 131 + 17) & 255 for i in range(size))
emit("bytes", data.hex(), data)
for value in [0, 1, -1, 2, -2, -(2**63), 2**63 - 1, 2**53 + 1, 2**32]:
emit("i64", value, struct.pack("<q", value))
for bits in [0, 0x8000000000000000, 0x3FF0000000000000, 0xBFF0000000000000,
0x3FE0000000000000, 0xBFE0000000000000, 1, 0x8000000000000001,
0x000FFFFFFFFFFFFF, 0x0010000000000000,
0x7FEFFFFFFFFFFFFF, 0xFFEFFFFFFFFFFFFF, 0x4340000000000000]:
canonical = 0 if bits & 0x7FFFFFFFFFFFFFFF == 0 else bits
emit("float", f"{bits:016X}", struct.pack("<Q", canonical))
for value in ["", "hello", "\0", "ação 😀", "a" * 31, "a" * 32, "a" * 33, "z" * 1025]:
data = value.encode("utf-8")
emit("string", data.hex(), data)
for index, generation in [(0, 1), (1, 1), (1, 2), (1024, 1), (2**32-1, 2**32-1)]:
emit("reference", f"{index},{generation}", struct.pack("<II", index, generation))
rows.append("null\tnull\t0000000000000000")
args.output.write_text("\n".join(rows) + "\n", encoding="utf-8")
print(f"Generated {len(rows)-1} vectors with upstream XXH64 v0.8.3, seed 0.")
if __name__ == "__main__":
main()
@@ -0,0 +1,152 @@
#[path = "support/identity.rs"]
mod support;
use prometeu_bytecode::{Value, model::ConstantPoolEntry as K};
use prometeu_vm::{HostContext, LogicalFrameEndingReason as End};
use support::*;
#[test]
fn scalar_pbx_execution_matches_independent_c_reference_vectors() {
let mut count = 0;
for row in include_str!("fixtures/hash-conformance.tsv").lines().skip(1) {
let fields: Vec<_> = row.split('\t').collect();
let expected = u64::from_str_radix(fields[2], 16).unwrap() as i64;
let (value, id, bytes) = match fields[0] {
"i64" => (K::Int64(fields[1].parse().unwrap()), 0x4100, 0),
"float" => {
(K::Float64(f64::from_bits(u64::from_str_radix(fields[1], 16).unwrap())), 0x4101, 0)
}
"string" => {
let bytes = hex_bytes(fields[1]);
let size = bytes.len();
(K::String(String::from_utf8(bytes).unwrap()), 0x4102, size)
}
"null" => (K::Null, 0x4102, 0),
_ => continue,
};
let source = format!("PUSH_CONST 0\nINTRINSIC {id}\nRET");
let mut vm = vm(&[(&source, sig(&[], &[0]))], &[value]);
step(&mut vm).unwrap();
let report = vm.run_budget(1, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(report.reason, End::BudgetExhausted);
assert_eq!(report.cycles_used, 8 + bytes as u64, "{row}");
assert_eq!(&*vm.operand_stack_top(1), &[Value::Int64(expected)], "{row}");
assert_eq!(run(&mut vm).reason, End::EndOfRom);
count += 1;
}
assert_eq!(count, 31);
}
#[test]
fn identities_survive_mutation_and_views_validate_implementation_zero() {
let source = "STRUCT_NEW 5\nSET_LOCAL 0\nGET_LOCAL 0\nREF_IDENTITY_HASH 5\nSET_LOCAL 1\nGET_LOCAL 0\nPUSH_I64 73\nSTRUCT_SET type=5,field=0\nGET_LOCAL 0\nREF_IDENTITY_HASH 5\nGET_LOCAL 1\nEQ\nGET_LOCAL 0\nREF_TO_TRAIT source=5,target=7\nREF_IDENTITY_HASH 7\nGET_LOCAL 1\nEQ\nGET_LOCAL 0\nREF_TO_TRAIT source=5,target=7\nGET_LOCAL 0\nREF_TO_TRAIT source=5,target=8\nREF_IDENTITY_EQ left=7,right=8\nGET_LOCAL 0\nSTRUCT_NEW 5\nREF_IDENTITY_EQ left=5,right=5\nRET";
let mut vm = vm(&[(source, sig(&[], &[2, 2, 2, 2]))], &[]);
assert_eq!(run(&mut vm).reason, End::EndOfRom);
assert_eq!(
&*vm.operand_stack_top(4),
&[Value::Boolean(false), Value::Boolean(true), Value::Boolean(true), Value::Boolean(true)]
);
}
#[test]
fn array_closure_and_random_have_instance_identity() {
for (source, bodies) in [
(
"PUSH_I64 1\nARRAY_NEW 6\nSET_LOCAL 0\nGET_LOCAL 0\nREF_IDENTITY_HASH 6\nSET_LOCAL 1\nGET_LOCAL 0\nPUSH_I64 0\nPUSH_I64 42\nARRAY_SET 6\nGET_LOCAL 0\nREF_IDENTITY_HASH 6\nGET_LOCAL 1\nEQ\nRET",
false,
),
(
"PUSH_I64 42\nINTRINSIC 0x4000\nSET_LOCAL 0\nGET_LOCAL 0\nREF_IDENTITY_HASH 10\nSET_LOCAL 1\nGET_LOCAL 0\nINTRINSIC 0x4001\nPOP\nGET_LOCAL 0\nREF_IDENTITY_HASH 10\nGET_LOCAL 1\nEQ\nRET",
false,
),
(
"MAKE_CLOSURE fn=1,type=9\nSET_LOCAL 0\nGET_LOCAL 0\nGET_LOCAL 0\nREF_IDENTITY_EQ left=9,right=9\nGET_LOCAL 0\nMAKE_CLOSURE fn=1,type=9\nREF_IDENTITY_EQ left=9,right=9\nNOT\nAND\nRET",
true,
),
] {
let mut functions = vec![(source, sig(&[], &[2]))];
if bodies {
functions.push(("RET", sig(&[], &[])));
}
let mut vm = vm(&functions, &[]);
assert_eq!(run(&mut vm).reason, End::EndOfRom);
assert_eq!(&*vm.operand_stack_top(1), &[Value::Boolean(true)]);
}
}
#[test]
fn canonical_null_groups_compare_and_hash_without_instance_faults() {
let source = "PUSH_CONST 0\nPUSH_CONST 0\nREF_IDENTITY_HASH 7\nPUSH_CONST 0\nPUSH_CONST 0\nPUSH_CONST 0\nREF_IDENTITY_EQ left=6,right=7\nRET";
let mut vm = vm(&[(source, sig(&[], &[0, 2]))], &[K::Null]);
assert_eq!(run(&mut vm).reason, End::EndOfRom);
assert_eq!(&*vm.operand_stack_top(2), &[Value::Boolean(true), Value::Int64(0)]);
}
#[test]
fn admission_rejects_ineligible_sources_and_bad_native_ids_even_when_dead() {
for instruction in [
"REF_IDENTITY_HASH 0",
"REF_IDENTITY_HASH 3",
"REF_IDENTITY_HASH 4",
"REF_IDENTITY_HASH 12",
"REF_IDENTITY_HASH 13",
"REF_IDENTITY_HASH 14",
"REF_IDENTITY_HASH 9999",
"REF_IDENTITY_EQ left=5,right=3",
"INTRINSIC 0x41FF",
] {
let text = format!("HALT\n{instruction}");
assert!(image(&[(&text, sig(&[], &[]))], &[]).is_err(), "{instruction}");
}
assert!(image(&[("PUSH_CONST 0\nINTRINSIC 0x4102\nRET", sig(&[], &[0]))], &[K::Null]).is_ok());
for id in [0x1103, 0x4100, 0x4101] {
let text = format!("PUSH_CONST 0\nINTRINSIC {id}\nPOP\nRET");
assert!(image(&[(&text, sig(&[], &[]))], &[K::Null]).is_err(), "{id}");
}
assert!(image(&[("PUSH_I64 3\nREF_IDENTITY_HASH 5\nRET", sig(&[], &[0]))], &[]).is_err());
}
#[test]
fn whole_instruction_budget_admission_preserves_zero_and_overshoot() {
let mut vm = vm(
&[("PUSH_CONST 0\nINTRINSIC 0x4102\nRET", sig(&[], &[0]))],
&[K::String("x".repeat(65))],
);
step(&mut vm).unwrap();
let before = vm.pc();
let zero = vm.run_budget(0, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(zero.cycles_used, 0);
assert_eq!(vm.pc(), before);
let one = vm.run_budget(1, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(one.reason, End::BudgetExhausted);
assert_eq!(one.cycles_used, 73);
assert_eq!(one.steps_executed, 1);
}
#[test]
fn every_eligible_absence_has_zero_hash_and_exact_identity_instruction_cost() {
for (ty, width) in [(5, 1), (6, 1), (7, 2), (9, 1), (10, 1)] {
let source = format!("{}REF_IDENTITY_HASH {ty}\nRET", "PUSH_CONST 0\n".repeat(width));
let mut vm = vm(&[(&source, sig(&[], &[0]))], &[K::Null]);
for _ in 0..width {
step(&mut vm).unwrap();
}
let before = vm.pc();
let zero = vm.run_budget(0, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!((zero.cycles_used, zero.steps_executed), (0, 0));
assert_eq!(vm.pc(), before);
let one = vm.run_budget(1, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!((one.cycles_used, one.steps_executed), (8 + width as u64, 1));
assert_eq!(&*vm.operand_stack_top(1), &[Value::Int64(0)]);
}
for source in [
"PUSH_CONST 0\nSTRUCT_NEW 5\nREF_IDENTITY_EQ left=6,right=5\nRET",
"STRUCT_NEW 5\nSTRUCT_NEW 11\nREF_IDENTITY_EQ left=5,right=11\nRET",
] {
let mut vm = vm(&[(source, sig(&[], &[2]))], &[K::Null]);
step(&mut vm).unwrap();
step(&mut vm).unwrap();
let one = vm.run_budget(1, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!((one.cycles_used, one.steps_executed), (6, 1));
assert_eq!(&*vm.operand_stack_top(1), &[Value::Boolean(false)]);
}
}
@@ -0,0 +1,105 @@
use prometeu_bytecode::Value;
use prometeu_vm::{
AbiType, BuiltinScalarType as S, IntrinsicCostModel as C, intrinsic_catalog,
intrinsic_catalog_csv, lookup_intrinsic_by_id,
};
use std::collections::BTreeSet;
#[test]
fn schema_two_has_exact_columns_profiles_and_per_slot_nullable_lists() {
let csv = intrinsic_catalog_csv();
assert_eq!(csv, include_str!("../../../../docs/vm-arch/INTRINSICS.csv"));
let mut rows = csv.lines();
assert_eq!(
rows.next().unwrap(),
"final_id_hex,final_id_dec,canonical_name,canonical_version,owner,name,arg_slots,ret_slots,arg_layout,ret_layout,deterministic,may_allocate,parameter_names,cost_cycles,mutates_guest_state,cost_model,attempt_cost_cycles,max_attempts,schema_version,arg_nullable,invocation_model,scratch_model,context_access,cost_arg_index,cost_per_byte"
);
let mut ids = BTreeSet::new();
let mut keys = BTreeSet::new();
let mut previous = 0;
for row in rows {
let f: Vec<_> = row.split(',').collect();
assert_eq!(f.len(), 25);
assert_eq!(f[18], "2");
let id = f[1].parse::<u32>().unwrap();
assert!(id > previous);
previous = id;
assert!(ids.insert(id));
assert!(keys.insert((f[2], f[3])));
let meta = lookup_intrinsic_by_id(id).unwrap();
meta.validate_descriptor().unwrap();
assert_eq!(f[19].split('|').filter(|s| !s.is_empty()).count(), meta.arg_slots());
assert_eq!(f[20], meta.invocation_model());
assert_eq!(f[21], meta.scratch_model());
assert_eq!(f[22], meta.context_access());
if id < 0x4100 {
assert_eq!(f[21], "existing_contract_v1");
assert_eq!(f[23], "");
assert_eq!(f[24], "0");
assert_eq!(f[20], if f[4] == "random" { "vm_owned_v1" } else { "host_buffered_v1" });
for (abi, nullable) in meta.arg_layout.iter().zip(meta.arg_nullable) {
assert_eq!(*nullable, matches!(abi,AbiType::Builtin(key) if key.name=="Random"));
}
} else {
assert_eq!(&f[20..23], &["borrowed_inline_v1", "none", "none"]);
assert_eq!(meta.cost_cycles, 8);
assert_eq!(meta.ret_layout, &[AbiType::Scalar(S::Int64)]);
assert_eq!(meta.arg_nullable, &[id == 0x4102]);
}
}
assert_eq!(ids.len(), 108);
assert_eq!(intrinsic_catalog().count(), 108);
}
#[test]
fn incompatible_descriptors_fail_instead_of_gaining_implicit_capabilities() {
let original = *lookup_intrinsic_by_id(0x4102).unwrap();
for variant in 0..14 {
let mut meta = original;
match variant {
0 => meta.arg_nullable = &[],
1 => meta.parameter_names = &[],
2 => meta.cost_arg_index = None,
3 => meta.cost_arg_index = Some(1),
4 => meta.cost_per_byte = 0,
5 => meta.attempt_cost_cycles = 1,
6 => meta.max_attempts = 1,
7 => meta.may_allocate = true,
8 => meta.mutates_guest_state = true,
9 => meta.deterministic = false,
10 => meta.ret_layout = &[AbiType::Scalar(S::Int64); 4],
11 => meta.ret_layout = &[AbiType::Scalar(S::Int64); 2],
12 => meta.ret_layout = &[AbiType::DynamicPayload],
13 => meta.arg_layout = &[AbiType::DynamicTag],
_ => unreachable!(),
}
assert!(meta.validate_descriptor().is_err(), "variant {variant}");
}
let mut meta = *lookup_intrinsic_by_id(0x4100).unwrap();
meta.arg_nullable = &[true];
assert!(meta.validate_descriptor().is_err());
meta.arg_nullable = &[false];
meta.cost_arg_index = Some(0);
assert!(meta.validate_descriptor().is_err());
meta.cost_model = C::ArgumentUtf8BytesV1;
meta.cost_per_byte = 1;
assert!(meta.validate_descriptor().is_err());
meta.cost_model = C::RandomRejectionV1;
meta.cost_arg_index = None;
meta.cost_per_byte = 0;
meta.attempt_cost_cycles = 8;
meta.max_attempts = 64;
assert!(meta.validate_descriptor().is_err());
}
#[test]
fn nullability_does_not_relax_existing_string_or_numeric_arguments() {
for id in [0x4100, 0x4101, 0x1103] {
assert!(
lookup_intrinsic_by_id(id).unwrap().validate_argument_values(&[Value::Null]).is_err()
);
}
assert!(
lookup_intrinsic_by_id(0x4102).unwrap().validate_argument_values(&[Value::Null]).is_ok()
);
}
@@ -9,7 +9,7 @@ use prometeu_vm::{
// Independent executable oracle: 32-byte header, eight directory entries,
// payload at 128, one Bool import, one zero-slot HALT function; total 194.
fn minimal() -> Vec<u8> {
"50 42 58 00 01 00 00 00 08 00 00 00
"50 42 58 00 00 00 00 00 08 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 80 00 00 00 04 00 00 00
01 00 00 00 84 00 00 00 1e 00 00 00
@@ -46,7 +46,7 @@ impl NativeInterface for Native {
}
#[test]
fn independent_v1_bytes_load_publish_and_execute_through_the_public_sealed_boundary() {
fn independent_v0_bytes_load_publish_and_execute_through_the_public_sealed_boundary() {
let bytes = minimal();
assert_eq!(bytes.len(), 194);
let mut load = LoadBudget::new(Default::default());
@@ -64,7 +64,7 @@ fn independent_v1_bytes_load_publish_and_execute_through_the_public_sealed_bound
#[test]
fn single_violation_oracles_reject_before_image_publication_with_typed_context() {
for (offset, replacement, code, reason, pc) in [
(4, 0, LoadCode::UnsupportedFormat, LoadReason::Version, None),
(4, 1, LoadCode::UnsupportedFormat, LoadReason::Version, None),
(178, 0, LoadCode::UnsupportedFormat, LoadReason::Builtin, None),
(162, 0xff, LoadCode::InvalidCode, LoadReason::UnknownOpcode, Some(0)),
(162, 0x11, LoadCode::InvalidCode, LoadReason::StackUnderflow, Some(0)),
@@ -0,0 +1,114 @@
#![allow(dead_code)]
use prometeu_bytecode::{
assemble, load_limits::LoadBudget, model::ConstantPoolEntry, registry::*,
registry_codec::PbxModule,
};
use prometeu_vm::{
HostContext, HostReturn, LogicalFrameEndingReason, NativeInterface, ValidatedProgramImage,
VirtualMachine, VmInitError,
};
use std::sync::Arc;
pub struct Native;
impl NativeInterface for Native {
fn syscall(
&mut self,
_: u32,
_: &[prometeu_bytecode::Value],
_: &mut HostReturn,
_: &mut HostContext,
) -> Result<(), prometeu_hal::vm_fault::VmFault> {
panic!("identity corpus uses no host syscall")
}
}
pub fn sig(parameters: &[u32], results: &[u32]) -> Signature {
Signature {
parameters: parameters
.iter()
.map(|&id| NamedType { type_id: TypeId(id), name: None })
.collect(),
results: results.iter().copied().map(TypeId).collect(),
}
}
pub fn types() -> Vec<TypeDecl> {
let field = || NamedType { type_id: TypeId(0), name: None };
vec![
TypeKind::Builtin(BuiltinId::INT64),
TypeKind::Builtin(BuiltinId::FLOAT),
TypeKind::Builtin(BuiltinId::BOOL),
TypeKind::Builtin(BuiltinId::STRING),
TypeKind::Builtin(BuiltinId::DYNAMIC),
TypeKind::Struct(vec![field()]),
TypeKind::Array(TypeId(0)),
TypeKind::Trait(vec![]),
TypeKind::Trait(vec![]),
TypeKind::Fn(sig(&[], &[])),
TypeKind::Builtin(BuiltinId::RANDOM),
TypeKind::Struct(vec![field()]),
TypeKind::Builtin(BuiltinId::COLOR),
TypeKind::Builtin(BuiltinId::VEC2),
TypeKind::Builtin(BuiltinId::PIXEL),
TypeKind::Builtin(BuiltinId::INT32),
]
.into_iter()
.map(|kind| TypeDecl { name: None, kind })
.collect()
}
pub fn image(
bodies: &[(&str, Signature)],
constants: &[ConstantPoolEntry],
) -> Result<Arc<ValidatedProgramImage>, VmInitError> {
let mut code = vec![];
let mut functions = vec![];
for (source, signature) in bodies {
let body = assemble(source).unwrap();
functions.push(FunctionDecl {
signature: signature.clone(),
local_slots: 8,
max_stack_slots: 64,
code_offset: code.len() as u32,
code_len: body.len() as u32,
..Default::default()
});
code.extend(body);
}
let mut budget = LoadBudget::new(Default::default());
let registry = Registry::resolve(
RegistryDeclarations {
types: types(),
functions,
implementations: vec![
ImplementationDecl { owner: TypeId(5), trait_id: TypeId(7), methods: vec![] },
ImplementationDecl { owner: TypeId(5), trait_id: TypeId(8), methods: vec![] },
],
},
code.len(),
&mut budget,
)
.unwrap();
let bytes = PbxModule {
registry: &registry,
code: &code,
constants,
debug: None,
exports: &[],
syscalls: &[],
}
.serialize(&mut budget)
.unwrap();
ValidatedProgramImage::load(&bytes, &mut LoadBudget::new(Default::default()), 0)
}
pub fn vm(bodies: &[(&str, Signature)], constants: &[ConstantPoolEntry]) -> VirtualMachine {
let mut vm = VirtualMachine::from_image(image(bodies, constants).unwrap(), Default::default());
vm.prepare_boot_call().unwrap();
vm
}
pub fn run(vm: &mut VirtualMachine) -> prometeu_vm::BudgetReport {
vm.run_budget(1_000_000, &mut Native, &mut HostContext::new(None)).unwrap()
}
pub fn step(vm: &mut VirtualMachine) -> Result<(), LogicalFrameEndingReason> {
vm.step(&mut Native, &mut HostContext::new(None))
}
pub fn hex_bytes(value: &str) -> Vec<u8> {
(0..value.len()).step_by(2).map(|i| u8::from_str_radix(&value[i..i + 2], 16).unwrap()).collect()
}
@@ -107,4 +107,5 @@ mod tests {
}
}
pub mod memcard_fixture;
pub mod program;
@@ -0,0 +1,146 @@
//! Neutral PBX/ABI fixture. No source-language frontend or compiler is involved.
use crate::program::{TestProgram, scalar_catalog};
use prometeu_bytecode::{
assembler::assemble,
model::{ConstantPoolEntry, SyscallDecl},
registry::*,
};
use std::collections::BTreeMap;
#[derive(Clone, Copy)]
pub enum MemcardFixture {
Write,
Read,
ReadWithPresentation,
Dirty,
}
#[derive(Default)]
struct Code {
bytes: Vec<u8>,
labels: BTreeMap<&'static str, u32>,
fixups: Vec<(usize, &'static str)>,
}
impl Code {
fn emit(&mut self, text: &str) {
self.bytes.extend(assemble(text).expect("fixture assembly"));
}
fn mark(&mut self, name: &'static str) {
self.labels.insert(name, self.bytes.len() as u32);
}
fn jump(&mut self, op: &str, name: &'static str) {
self.fixups.push((self.bytes.len() + 2, name));
self.emit(&format!("{op} 0"));
}
fn check(&mut self, value: i64, int32: bool) {
self.emit(&format!("PUSH_{} {value}\nEQ", if int32 { "I32" } else { "I64" }));
let resume = self.bytes.len() + 8; // conditional jump followed by a terminal trap
self.emit(&format!("JMP_IF_TRUE {resume}\nTRAP"));
}
fn finish(mut self) -> Vec<u8> {
for (offset, label) in self.fixups {
self.bytes[offset..offset + 4].copy_from_slice(&self.labels[label].to_le_bytes());
}
self.bytes
}
}
/// Stack oracle at a completed frame: 100 pending, 101 durable SUCCESS,
/// 104 MEMORY_ONLY, 201 exact existing readback, 301 dirty/uncommitted RAM.
/// Read never writes or submits a commit; a missing/wrong payload traps.
pub fn memcard_program(kind: MemcardFixture) -> Vec<u8> {
let reads = matches!(kind, MemcardFixture::Read | MemcardFixture::ReadWithPresentation);
let mut main = Code::default();
main.emit("HOSTCALL 0");
main.check(0, true);
main.emit("PUSH_I64 4\nARRAY_NEW 9\nSET_GLOBAL 1");
if reads {
let read_import = if matches!(kind, MemcardFixture::Read) { 1 } else { 2 };
main.emit(&format!("GET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 4\nHOSTCALL {read_import}"));
main.check(4, false);
main.check(0, false);
for (i, value) in [0, 127, 128, 255].into_iter().enumerate() {
main.emit(&format!("GET_GLOBAL 1\nPUSH_I64 {i}\nARRAY_GET 9"));
main.check(value, true);
}
main.mark("done");
main.emit("PUSH_I64 201\nFRAME_SYNC\nPOP_N 1");
main.jump("JMP", "done");
} else {
for (i, value) in [0, 127, 128, 255].into_iter().enumerate() {
main.emit(&format!("GET_GLOBAL 1\nPUSH_I64 {i}\nPUSH_I32 {value}\nARRAY_SET 9"));
}
main.emit("GET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 4\nHOSTCALL 2");
main.check(4, false);
main.check(0, false);
if matches!(kind, MemcardFixture::Dirty) {
main.mark("done");
main.emit("PUSH_I64 301\nFRAME_SYNC\nPOP_N 1");
main.jump("JMP", "done");
} else {
main.emit("GET_GLOBAL 0\nPUSH_I32 0\nHOSTCALL 3\nSET_GLOBAL 2");
main.check(0, false);
main.mark("query");
main.emit("GET_GLOBAL 0\nGET_GLOBAL 2\nHOSTCALL 4\nPOP_N 1\nSET_GLOBAL 3");
main.check(0, false);
main.emit("GET_GLOBAL 3\nPUSH_I64 100\nADD\nFRAME_SYNC\nPOP_N 1");
main.jump("JMP", "query");
}
}
main.mark("error");
main.emit("TRAP");
let mut code = main.finish();
let main_len = code.len() as u32;
let hook = if matches!(kind, MemcardFixture::Read) {
assemble("GET_LOCAL 0\nSET_GLOBAL 0\nPUSH_I32 0\nRET").unwrap()
} else {
assemble("GET_LOCAL 0\nSET_GLOBAL 0\nPUSH_I64 560\nARRAY_NEW 9\nSET_GLOBAL 1\nGET_LOCAL 0\nPUSH_CONST 0\nPUSH_I64 1\nPUSH_I32 1\nPUSH_I32 1\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 560\nHOSTCALL 1\nPOP_N 1\nPUSH_I32 0\nRET").unwrap()
};
let hook_len = hook.len() as u32;
code.extend(hook);
let mut types = scalar_catalog();
types.push(TypeDecl { name: None, kind: TypeKind::Array(TypeId(1)) });
let mut imports = vec![("bootstrap", 0, 1)];
if !matches!(kind, MemcardFixture::Read) {
imports.push(("presentation", 8, 1));
}
match kind {
MemcardFixture::Read | MemcardFixture::ReadWithPresentation => {
imports.push(("slot_read", 6, 2));
}
MemcardFixture::Dirty => imports.push(("slot_write", 6, 2)),
MemcardFixture::Write => {
imports.extend([("slot_write", 6, 2), ("slot_commit", 2, 2), ("query", 2, 3)])
}
}
let syscalls = imports
.into_iter()
.map(|(name, arg_slots, ret_slots)| SyscallDecl {
module: "mem".into(),
name: name.into(),
version: 1,
arg_slots,
ret_slots,
})
.collect();
TestProgram {
const_pool: vec![ConstantPoolEntry::String("Neutral persistence fixture".into())],
code,
functions: vec![
FunctionDecl { code_len: main_len, max_stack_slots: 32, ..Default::default() },
FunctionDecl {
lifecycle_role: LifecycleRole::MemcardBoot,
code_offset: main_len,
code_len: hook_len,
max_stack_slots: 32,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![TypeId(1)],
},
..Default::default()
},
],
syscalls,
..Default::default()
}
.serialize_with_types(types)
}
@@ -63,10 +63,13 @@ impl TestProgram {
}
}
pub fn serialize(&self) -> Vec<u8> {
self.serialize_with_types(scalar_catalog())
}
pub fn serialize_with_types(&self, types: Vec<TypeDecl>) -> Vec<u8> {
let mut budget = LoadBudget::new(Default::default());
let registry = Registry::resolve(
RegistryDeclarations {
types: scalar_catalog(),
types,
functions: self.functions.clone(),
implementations: vec![],
},
@@ -2,7 +2,7 @@
mod wire;
pub use wire::Limits;
use crate::{AdvanceFrameOutcome, HeadlessHost};
use crate::{AdvanceFrameOutcome, HeadlessHost, PendingWrites, TeardownPolicy};
use serde_json::{Value, json};
use std::io::{self, BufRead, Write};
use std::sync::{Arc, Mutex, mpsc};
@@ -16,7 +16,8 @@ struct Control {
}
enum Job {
Work(String, Command),
Work(String, Command, bool),
Shutdown(String, TeardownPolicy, bool, mpsc::Sender<bool>),
Stop(Option<String>),
ReadError(io::Error),
}
@@ -104,6 +105,8 @@ fn read_commands<R: BufRead, W: Write>(
limits: &Limits,
) -> io::Result<()> {
let mut initialized = false;
let mut memcard = false;
let mut log_read = false;
loop {
let bytes = match read_line(&mut input, limits.max_command_bytes)? {
Line::Eof => break,
@@ -142,11 +145,36 @@ fn read_commands<R: BufRead, W: Write>(
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 matches!(command, Command::GetLogs(_)) && !log_read {
output.reply(
Some(&id),
Err(WireError::new(
"unsupported_capability",
"negotiate minor 1.2 and require log_read first",
)),
)?;
continue;
}
if command.needs_memcard() && !memcard {
output.reply(
Some(&id),
Err(WireError::new(
"unsupported_capability",
"negotiate minor 1.1 and require memcard first",
)),
)?;
continue;
}
if let Command::Shutdown(params) = command {
control.lock().unwrap().canceled = true;
let (tx, rx) = mpsc::channel();
sender
.send(Job::Shutdown(id, params.policy(), memcard, tx))
.map_err(|_| io::Error::other("execution stopped"))?;
if rx.recv().map_err(|_| io::Error::other("execution stopped"))? {
return Ok(());
}
continue;
}
if let Command::Initialize(params) = command {
let result = if initialized {
@@ -159,9 +187,23 @@ fn read_commands<R: BufRead, W: Write>(
.any(|c| !CAPABILITIES.contains(&c.as_str()))
{
Err(WireError::new("unsupported_capability", "required capability unavailable"))
} else if params.protocol_version.minor == 0
&& params.required_capabilities.iter().any(|c| c == "memcard")
{
Err(WireError::new("incompatible_version", "memcard requires protocol minor >= 1"))
} else if params.protocol_version.minor < 2
&& params.required_capabilities.iter().any(|c| c == "log_read")
{
Err(WireError::new("incompatible_version", "log_read requires protocol minor >= 2"))
} else {
initialized = true;
Ok(json!({"protocolVersion":{"major":1,"minor":0},"capabilities":CAPABILITIES}))
memcard = params.protocol_version.minor >= 1
&& params.required_capabilities.iter().any(|c| c == "memcard");
log_read = params.protocol_version.minor >= 2
&& params.required_capabilities.iter().any(|c| c == "log_read");
Ok(
json!({"protocolVersion":{"major":1,"minor":params.protocol_version.minor.min(2)},"capabilities":CAPABILITIES}),
)
};
output.reply(Some(&id), result)?;
continue;
@@ -197,7 +239,9 @@ fn read_commands<R: BufRead, W: Write>(
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"))?;
sender
.send(Job::Work(id, command, memcard))
.map_err(|_| io::Error::other("execution stopped"))?;
}
let mut c = control.lock().unwrap();
c.canceled = true;
@@ -210,14 +254,39 @@ fn execute<W: Write>(
id: &str,
output: &Output<W>,
control: &Mutex<Control>,
memcard: bool,
) -> 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)
let result = if let Some(choice) = p.memcard_choice {
host.boot_with_memcard_choice(p.path, choice.into())
} else {
host.boot(p.path)
};
result.map(|()| wire::state(host.get_state())).map_err(wire::host_error)
}
Command::Reset => {
host.reset();
Ok(wire::state(host.get_state()))
Command::Reset(params) => host
.reset_with_policy(params.policy())
.map(|snapshot| {
let mut state = wire::state(host.get_state());
if memcard {
state["memcard"] = json!(snapshot);
}
state
})
.map_err(wire::host_error),
Command::MemcardMount(p) => {
host.mount_memcard(p).map(|s| json!(s)).map_err(wire::host_error)
}
Command::MemcardUnmount => {
host.unmount_memcard().map(|s| json!(s)).map_err(wire::host_error)
}
Command::GetMemcardState => Ok(json!(host.get_memcard_state())),
Command::MemcardReconcile => {
host.reconcile_memcard().map(|s| json!(s)).map_err(wire::host_error)
}
Command::MemcardContinueInMemory => {
host.continue_memcard_in_memory().map(|s| json!(s)).map_err(wire::host_error)
}
Command::SetInput(p) => {
host.set_input(p.into());
@@ -229,6 +298,7 @@ fn execute<W: Write>(
}
Command::GetState => Ok(wire::state(host.get_state())),
Command::GetFault => Ok(host.get_fault().as_ref().map(wire::fault).unwrap_or(Value::Null)),
Command::GetLogs(params) => wire::logs(host, params, &output.session),
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"});
@@ -254,6 +324,10 @@ fn execute<W: Write>(
result["stop"] = json!("terminated");
break;
}
Ok(AdvanceFrameOutcome::ActionRequired) => {
result["stop"] = json!("action_required");
break;
}
Err(error) => {
result["stop"] = json!("host_error");
result["error"] = serde_json::to_value(wire::host_error(error))?;
@@ -283,7 +357,7 @@ pub fn serve<R: BufRead + Send + 'static, W: Write + Send + 'static>(
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},
json!({"type":"hello","sessionId":output.session,"protocolVersion":{"major":1,"minor":2},
"runtimeVersion":runtime_version,"capabilities":CAPABILITIES,"limits":limits}),
)?;
let control = Arc::new(Mutex::new(Control::default()));
@@ -298,18 +372,58 @@ pub fn serve<R: BufRead + Send + 'static, W: Write + Send + 'static>(
}
});
let mut host = HeadlessHost::new();
while let Ok(job) = receiver.recv() {
loop {
host.poll_memcard();
let job = match receiver.recv_timeout(std::time::Duration::from_millis(5)) {
Ok(job) => job,
Err(mpsc::RecvTimeoutError::Timeout) => continue,
Err(mpsc::RecvTimeoutError::Disconnected) => break,
};
match job {
Job::Work(id, command) => {
let result = execute(&mut host, command, &id, &output, &control)?;
Job::Work(id, command, memcard) => {
let result = match execute(&mut host, command, &id, &output, &control, memcard) {
Ok(result) => result,
Err(error) => {
cleanup_after_loss(&mut host);
return Err(error);
}
};
// 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)?;
if let Err(error) = output.reply(Some(&id), result) {
drop(c);
cleanup_after_loss(&mut host);
return Err(error);
}
c.active = None;
c.advancing = false;
}
Job::Shutdown(id, policy, memcard, ack) => match host.shutdown(policy) {
Ok(snapshot) => {
drop(host);
let mut value = json!({"closed":true});
if memcard {
value["memcard"] = json!(snapshot);
}
output.reply(Some(&id), Ok(value))?;
let _ = ack.send(true);
reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
return Ok(());
}
Err(error) => {
if let Err(error) = output.reply(Some(&id), Err(wire::host_error(error))) {
cleanup_after_loss(&mut host);
return Err(error);
}
let _ = ack.send(false);
}
},
Job::Stop(id) => {
let _ = host.shutdown(TeardownPolicy {
discard_unsaved: true,
pending_writes: PendingWrites::Cancel,
});
drop(host);
if let Some(id) = id {
output.reply(Some(&id), Ok(json!({"closed":true})))?;
@@ -317,13 +431,24 @@ pub fn serve<R: BufRead + Send + 'static, W: Write + Send + 'static>(
reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
return Ok(());
}
Job::ReadError(error) => return Err(error),
Job::ReadError(error) => {
let _ = host.shutdown(TeardownPolicy {
discard_unsaved: true,
pending_writes: PendingWrites::Cancel,
});
return Err(error);
}
}
}
reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
Ok(())
}
fn cleanup_after_loss(host: &mut HeadlessHost) {
let _ = host
.shutdown(TeardownPolicy { discard_unsaved: true, pending_writes: PendingWrites::Cancel });
}
#[cfg(test)]
mod tests {
use super::*;
@@ -369,7 +494,7 @@ mod tests {
"../../../../../devtools/headless-protocol/requests.json"
))
.unwrap();
assert_eq!(requests.len(), 11);
assert!(!requests.is_empty());
for request in requests {
wire::parse(serde_json::from_value(request).unwrap()).unwrap();
}
@@ -8,7 +8,10 @@ use std::io;
#[cfg(test)]
mod fault_tests;
use crate::{CapturedFrame, HostError, HostExecutionStatus, HostState};
use crate::{
CapturedFrame, HostError, HostExecutionStatus, HostState, MediaAccess, MediaAction,
MemcardChoice, MemcardMount, PendingWrites, TeardownPolicy,
};
pub const CAPABILITIES: &[&str] = &[
"boot",
@@ -19,8 +22,15 @@ pub const CAPABILITIES: &[&str] = &[
"capture",
"get_state",
"get_fault",
"log_read",
"cancel",
"shutdown",
"memcard",
"memcard_mount",
"memcard_unmount",
"get_memcard_state",
"memcard_reconcile",
"memcard_continue_in_memory",
];
#[derive(Clone, Debug, Serialize)]
@@ -95,6 +105,33 @@ pub(super) struct Initialize {
#[serde(deny_unknown_fields)]
pub(super) struct Boot {
pub path: String,
#[serde(default, rename = "memcardChoice", deserialize_with = "present")]
pub memcard_choice: Option<MemcardChoice>,
}
fn present<'de, D: serde::Deserializer<'de>, T: Deserialize<'de>>(
d: D,
) -> Result<Option<T>, D::Error> {
T::deserialize(d).map(Some)
}
#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Teardown {
#[serde(deserialize_with = "present")]
pub discard_unsaved: Option<bool>,
#[serde(deserialize_with = "present")]
pub pending_writes: Option<PendingWrites>,
}
impl Teardown {
pub fn explicit(&self) -> bool {
self.discard_unsaved.is_some() || self.pending_writes.is_some()
}
pub fn policy(&self) -> TeardownPolicy {
TeardownPolicy {
discard_unsaved: self.discard_unsaved.unwrap_or(false),
pending_writes: self.pending_writes.unwrap_or_default(),
}
}
}
#[derive(Debug, Deserialize)]
@@ -103,6 +140,19 @@ pub(super) struct Advance {
pub frames: u64,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct GetLogs {
// Explicit deserializer makes the nullable field required, including on first read.
#[serde(deserialize_with = "nullable_cursor")]
pub after_sequence: Option<u64>,
pub limit: u16,
}
fn nullable_cursor<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<u64>, D::Error> {
Option::<u64>::deserialize(d)
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Cancel {
@@ -155,15 +205,35 @@ impl From<Input> for InputSignals {
pub(super) enum Command {
Initialize(Initialize),
Boot(Boot),
Reset,
Reset(Teardown),
MemcardMount(MemcardMount),
MemcardUnmount,
GetMemcardState,
MemcardReconcile,
MemcardContinueInMemory,
SetInput(Input),
ClearInput,
Advance(Advance),
Capture,
GetState,
GetFault,
GetLogs(GetLogs),
Cancel(Cancel),
Shutdown,
Shutdown(Teardown),
}
impl Command {
pub fn needs_memcard(&self) -> bool {
match self {
Self::MemcardMount(_)
| Self::MemcardUnmount
| Self::GetMemcardState
| Self::MemcardReconcile
| Self::MemcardContinueInMemory => true,
Self::Boot(p) => p.memcard_choice.is_some(),
Self::Reset(p) | Self::Shutdown(p) => p.explicit(),
_ => false,
}
}
}
fn params<T: serde::de::DeserializeOwned>(value: Value) -> Result<T, WireError> {
@@ -192,6 +262,24 @@ pub(super) fn parse(req: Request) -> Result<(String, Command), WireError> {
Command::Boot(p)
}
"advance" => Command::Advance(params(req.params)?),
"get_logs" => {
let p: GetLogs = params(req.params)?;
if !(1..=1024).contains(&p.limit) {
return Err(WireError::new("invalid_params", "limit must be 1..1024"));
}
Command::GetLogs(p)
}
"reset" => Command::Reset(params(req.params)?),
"shutdown" => Command::Shutdown(params(req.params)?),
"memcard_mount" => {
let p: MemcardMount = params(req.params)?;
if p.path.trim().is_empty()
|| matches!((p.action, p.access), (MediaAction::Create, MediaAccess::ReadOnly))
{
return Err(WireError::new("invalid_params", "invalid media path/action/access"));
}
Command::MemcardMount(p)
}
"set_input" => Command::SetInput(params(req.params)?),
"cancel" => {
let p: Cancel = params(req.params)?;
@@ -200,15 +288,25 @@ pub(super) fn parse(req: Request) -> Result<(String, Command), WireError> {
}
Command::Cancel(p)
}
"reset" | "clear_input" | "capture" | "get_state" | "get_fault" | "shutdown" => {
"clear_input"
| "capture"
| "get_state"
| "get_fault"
| "memcard_unmount"
| "get_memcard_state"
| "memcard_reconcile"
| "memcard_continue_in_memory" => {
empty(&req.params)?;
match req.command.as_str() {
"reset" => Command::Reset,
"memcard_unmount" => Command::MemcardUnmount,
"get_memcard_state" => Command::GetMemcardState,
"memcard_reconcile" => Command::MemcardReconcile,
"memcard_continue_in_memory" => Command::MemcardContinueInMemory,
"clear_input" => Command::ClearInput,
"capture" => Command::Capture,
"get_state" => Command::GetState,
"get_fault" => Command::GetFault,
_ => Command::Shutdown,
_ => unreachable!(),
}
}
_ => return Err(WireError::new("unknown_command", "unknown command")),
@@ -231,6 +329,9 @@ impl WireError {
pub(super) fn host_error(error: HostError) -> WireError {
let (code, details) = match &error {
HostError::Memcard(e) => {
("memcard_error", json!({"operation":e.operation,"reason":e.reason,"state":e.state}))
}
HostError::AlreadyBooted => ("already_booted", json!({})),
HostError::BootFailed { reason, report } => {
("boot_failed", json!({"reason":reason,"fault":report.as_deref().map(fault)}))
@@ -278,6 +379,48 @@ pub(super) fn state(s: HostState) -> Value {
"status":status_name(s.status)})
}
pub(super) fn logs(
host: &crate::HeadlessHost,
params: GetLogs,
session: &str,
) -> Result<Value, WireError> {
let (events, oldest, newest) =
host.log_snapshot(params.after_sequence, usize::from(params.limit));
if params.after_sequence.is_some_and(|after| newest.is_none_or(|newest| after > newest)) {
return Err(WireError::new("invalid_cursor", "afterSequence exceeds the log stream"));
}
let gap = oldest.is_some_and(|oldest| match params.after_sequence {
None => oldest > 0,
Some(after) => after.checked_add(1).is_some_and(|next| next < oldest),
});
let next = events.last().map(|event| event.seq).or(params.after_sequence);
Ok(
json!({"sessionId":session,"logEpoch":0,"events":events.iter().map(log_event).collect::<Vec<_>>(),
"oldestSequence":oldest,"newestSequence":newest,"nextAfterSequence":next,
"gap":gap,"overflow":oldest.is_some_and(|oldest| oldest > 0)}),
)
}
fn log_event(event: &prometeu_hal::log::LogEvent) -> Value {
use prometeu_hal::log::{LogLevel, LogSource};
let level = match event.level {
LogLevel::Trace => "trace",
LogLevel::Debug => "debug",
LogLevel::Info => "info",
LogLevel::Warn => "warn",
LogLevel::Error => "error",
};
let (source, app_id) = match event.source {
LogSource::Pos => ("pos", None),
LogSource::Hub => ("hub", None),
LogSource::Vm => ("vm", None),
LogSource::Fs => ("fs", None),
LogSource::App { app_id } => ("app", Some(app_id)),
};
json!({"sequence":event.seq,"frame":event.frame,"timestampMs":event.ts_ms,
"level":level,"source":source,"appId":app_id,"tag":event.tag,"message":event.msg})
}
pub(super) fn fault(report: &CrashReport) -> Value {
let mut result = json!({"kind":report.kind(),"pc":report.pc(),"summary":report.summary()});
match report {
@@ -323,3 +466,105 @@ pub(super) fn capture(c: CapturedFrame) -> Result<Value, WireError> {
"width":width,"height":height,"stridePixels":frame.stride_pixels,"pixelFormat":"RGBA8888",
"logicalFrameIndex":c.logical_frame_index,"frameId":frame.frame_id.get()}))
}
#[cfg(test)]
mod log_tests {
use super::*;
use prometeu_hal::log::{LogEvent, LogLevel, LogSource};
#[test]
fn oversized_native_event_is_an_error_without_partial_result() {
let event = LogEvent {
seq: 0,
frame: 0,
ts_ms: 0,
level: LogLevel::Error,
source: LogSource::Vm,
tag: 0,
msg: "x".repeat(8192),
};
let output = super::super::Output {
writer: std::sync::Mutex::new(Vec::new()),
session: "session".into(),
limit: 4096,
};
output.reply(Some("logs"), Ok(json!({"events":[log_event(&event)]}))).unwrap();
let bytes = output.writer.into_inner().unwrap();
assert!(bytes.len() <= 4097);
let response: Value = serde_json::from_slice(&bytes).unwrap();
assert_eq!(response["error"]["code"], "response_too_large");
assert_eq!(response["requestId"], "logs");
assert!(response.get("result").is_none());
}
#[test]
fn native_records_preserve_unsigned_maxima_and_typed_sources() {
for (source, name, app_id) in [
(LogSource::Pos, "pos", None),
(LogSource::Hub, "hub", None),
(LogSource::Vm, "vm", None),
(LogSource::Fs, "fs", None),
(LogSource::App { app_id: u32::MAX }, "app", Some(u32::MAX)),
] {
for (level, level_name) in [
(LogLevel::Trace, "trace"),
(LogLevel::Debug, "debug"),
(LogLevel::Info, "info"),
(LogLevel::Warn, "warn"),
(LogLevel::Error, "error"),
] {
let event = LogEvent {
seq: u64::MAX,
frame: u64::MAX,
ts_ms: u64::MAX,
level,
source,
tag: u16::MAX,
msg: "complete native message".into(),
};
let encoded = log_event(&event);
let decoded: Value =
serde_json::from_slice(&serde_json::to_vec(&encoded).unwrap()).unwrap();
for key in ["sequence", "frame", "timestampMs"] {
assert_eq!(decoded[key].as_u64(), Some(u64::MAX));
}
assert_eq!(decoded["level"], level_name);
assert_eq!(decoded["source"], name);
assert_eq!(decoded["appId"], json!(app_id));
assert_eq!(decoded["tag"], u16::MAX);
assert_eq!(decoded["message"], event.msg);
}
}
}
#[test]
fn required_nullable_cursor_and_limit_reject_malformed_values() {
for value in [
json!({"limit":1}),
json!({"afterSequence":null}),
json!({"afterSequence":-1,"limit":1}),
json!({"afterSequence":1.5,"limit":1}),
json!({"afterSequence":"0","limit":1}),
json!({"afterSequence":null,"limit":0}),
json!({"afterSequence":null,"limit":1025}),
json!({"afterSequence":null,"limit":1,"filter":"app"}),
] {
assert!(
parse(Request {
request_id: "logs".into(),
command: "get_logs".into(),
params: value
})
.is_err()
);
}
assert!(
parse(Request {
request_id: "logs".into(),
command: "get_logs".into(),
params: json!({"afterSequence":u64::MAX,"limit":1024})
})
.is_ok()
);
}
}
+161 -19
View File
@@ -1,5 +1,6 @@
use std::fmt;
use std::sync::Arc;
use std::time::{Duration, Instant};
use prometeu_drivers::hardware::Hardware;
use prometeu_drivers::{ControlledWallClock, MemoryBanks};
@@ -11,9 +12,30 @@ use prometeu_hal::{
RuntimePlatform, TelemetryPlatform, WallClock,
};
use prometeu_system::{CrashReport, LatestRenderFrameStore};
#[path = "memcard.rs"]
mod memcard;
pub use memcard::{
MediaAccess, MediaAction, MemcardChoice, MemcardFailure, MemcardMount, MemcardState,
PendingWrites, TeardownPolicy,
};
const BOOT_TICK_LIMIT: usize = 5000;
const HOST_FRAME_ADVANCE_TICK_LIMIT: usize = 100_000;
const BOOTSTRAP_IO_WAIT_QUANTUM: Duration = Duration::from_millis(5);
const BOOTSTRAP_IO_WAIT_LIMIT: Duration = Duration::from_secs(2);
/// One deadline for the entire advance, including repeated admission to the gate.
#[derive(Default)]
struct BootstrapIoWait {
deadline: Option<Instant>,
}
impl BootstrapIoWait {
fn next_wait(&mut self, now: Instant) -> Option<Duration> {
let deadline = *self.deadline.get_or_insert(now + BOOTSTRAP_IO_WAIT_LIMIT);
let remaining = deadline.saturating_duration_since(now);
(!remaining.is_zero()).then_some(remaining.min(BOOTSTRAP_IO_WAIT_QUANTUM))
}
}
/// One published logical frame plus the automation counter.
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -46,6 +68,7 @@ pub enum AdvanceFrameOutcome {
FrameCompleted { logical_frame_index: u64, frame_id: FrameId },
Faulted(CrashReport),
Terminated,
ActionRequired,
}
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -53,6 +76,7 @@ pub enum AdvanceFramesStop {
Completed,
Faulted(CrashReport),
Terminated,
ActionRequired,
}
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -64,6 +88,7 @@ pub struct AdvanceFramesOutcome {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HostError {
Memcard(Box<MemcardFailure>),
AlreadyBooted,
BootFailed { reason: String, report: Option<Box<CrashReport>> },
InvalidState { operation: &'static str, status: HostExecutionStatus },
@@ -75,6 +100,7 @@ pub enum HostError {
impl fmt::Display for HostError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Memcard(error) => write!(f, "{}: {}", error.operation, error.reason),
Self::AlreadyBooted => write!(f, "boot requires reset before another attempt"),
Self::BootFailed { reason, .. } => write!(f, "boot failed: {reason}"),
Self::InvalidState { operation, status } => {
@@ -104,6 +130,7 @@ pub struct HeadlessHost {
boot_attempted: bool,
last_completed_frame: Option<CompletedFrame>,
controlled_wall_clock: Option<Arc<ControlledWallClock>>,
media: memcard::MediaSelection,
}
#[derive(Debug, Clone, Copy)]
@@ -153,6 +180,7 @@ impl HeadlessHost {
boot_attempted: false,
last_completed_frame: None,
controlled_wall_clock,
media: Default::default(),
}
}
@@ -166,6 +194,15 @@ impl HeadlessHost {
self.controlled_wall_clock.as_deref()
}
/// Observe native log history without advancing, draining or changing lifecycle.
pub fn log_snapshot(
&self,
after: Option<u64>,
limit: usize,
) -> (Vec<prometeu_hal::log::LogEvent>, Option<u64>, Option<u64>) {
self.firmware.os.log_snapshot(after, limit)
}
/// Load `path` and tick until the firmware is in `GameRunning`.
///
/// The transition into `GameRunning` is the last tick. The first game
@@ -189,15 +226,20 @@ impl HeadlessHost {
return Err(HostError::AlreadyBooted);
}
self.boot_attempted = true;
self.media.choice = choice;
self.media.boot_phase = "loading";
let path = path.into();
self.firmware.boot_target = BootTarget::Cartridge { path, debug: false, debug_port: 7777 };
let boot_deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
let mut choice_submitted = false;
for _ in 0..BOOT_TICK_LIMIT {
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
self.media.boot_phase = "running";
return Ok(());
}
if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) {
self.media.boot_phase = "failed";
let report = self.get_fault();
let reason = report
.as_ref()
@@ -206,33 +248,55 @@ impl HeadlessHost {
return Err(HostError::BootFailed { reason, report: report.map(Box::new) });
}
if matches!(self.firmware.state, FirmwareState::HubHome(_)) {
self.media.boot_phase = "failed";
return Err(HostError::BootFailed {
reason: "cartridge did not load".to_string(),
report: None,
});
}
let progress = self.firmware.os.memcard().lane.progress_stamp();
if let FirmwareState::LoadCartridge(step) = &self.firmware.state
&& step.cartridge.memcard_slots.is_none()
&& choice.is_some()
{
self.media.boot_phase = "failed";
return Err(self.memcard_error("boot", "invalid_state"));
}
if choice_submitted
&& let prometeu_system::memcard::admission::PreparationState::Failed(error) =
self.firmware.os.memcard().admission.state
{
self.media.boot_phase = "failed";
return Err(self.memcard_error("boot", memcard::error_name(error)));
}
let waiting = matches!(&self.firmware.state,FirmwareState::LoadCartridge(step) if step.needs_memcard_choice());
if waiting {
let Some(choice) = choice else {
return Err(HostError::BootFailed {
reason: "Memory-card choice required; use boot_with_memcard_choice".into(),
report: None,
});
self.media.boot_phase = "choice_required";
return Err(self.memcard_error("boot", "choice_required"));
};
self.signals = InputSignals::default();
self.tick_once();
self.signals = match choice {
prometeu_system::memcard::admission::Choice::Persistent => {
InputSignals { a_signal: true, ..Default::default() }
}
prometeu_system::memcard::admission::Choice::MemoryFresh => {
InputSignals { x_signal: true, ..Default::default() }
}
prometeu_system::memcard::admission::Choice::MemoryExisting => {
InputSignals { y_signal: true, ..Default::default() }
if self.firmware.os.memcard().preparation_active() {
self.poll_memcard();
self.firmware
.os
.memcard()
.lane
.wait_for_progress(progress, std::time::Duration::from_millis(5));
continue;
}
let created_at = self.platform.wall_clock().utc_unix_seconds();
let result = match &mut self.firmware.state {
FirmwareState::LoadCartridge(step) => {
step.choose_memcard(&mut self.firmware.os, choice, created_at)
}
_ => unreachable!(),
};
if let Err(error) = result {
self.media.boot_phase = "failed";
return Err(self.memcard_error("boot", memcard::error_name(error)));
}
choice_submitted = true;
self.media.boot_phase = "preparing";
}
self.tick_once();
self.signals = InputSignals::default();
@@ -251,6 +315,7 @@ impl HeadlessHost {
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
Ok(())
} else {
self.media.boot_phase = "failed";
Err(HostError::BootFailed {
reason: "boot did not reach the game".to_string(),
report: self.get_fault().map(Box::new),
@@ -258,7 +323,10 @@ impl HeadlessHost {
}
}
pub fn reset(&mut self) {
pub fn reset(&mut self) -> Result<(), HostError> {
self.reset_with_policy(TeardownPolicy::default()).map(|_| ())
}
fn reset_inner(&mut self) {
self.signals = InputSignals::default();
self.firmware.change_state(
FirmwareState::Reset(ResetStep),
@@ -296,7 +364,11 @@ impl HeadlessHost {
return Ok(AdvanceFrameOutcome::Faulted(report));
}
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
return Ok(AdvanceFrameOutcome::Terminated);
return Ok(if self.host_action_required() {
AdvanceFrameOutcome::ActionRequired
} else {
AdvanceFrameOutcome::Terminated
});
}
let start = self.firmware.os.vm().logical_frame_index();
@@ -304,7 +376,13 @@ impl HeadlessHost {
self.firmware.os.vm().set_paused(false);
self.firmware.os.vm().request_debug_step();
let mut io_wait = BootstrapIoWait::default();
for _ in 0..HOST_FRAME_ADVANCE_TICK_LIMIT {
// A controlled lifecycle slice can consume the runtime step marker
// without closing a logical frame. This operation still owns the
// request until its first frame or an explicit stop boundary.
self.firmware.os.vm().set_paused(false);
self.firmware.os.vm().request_debug_step();
self.tick_once();
if let Some(report) = self.get_fault() {
self.finish_frame_advance();
@@ -312,7 +390,11 @@ impl HeadlessHost {
}
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
self.finish_frame_advance();
return Ok(AdvanceFrameOutcome::Terminated);
return Ok(if self.host_action_required() {
AdvanceFrameOutcome::ActionRequired
} else {
AdvanceFrameOutcome::Terminated
});
}
let logical_frame_index = self.firmware.os.vm().logical_frame_index();
@@ -333,6 +415,24 @@ impl HeadlessHost {
frame_id: frame.frame_id,
});
}
loop {
// Refresh before every observation/poll: another lane job may
// have progressed without completing this publication.
let progress = self.firmware.os.memcard().lane.progress_stamp();
if !self.bootstrap_io_pending() {
break;
}
// Native polling and waiting do not execute machine ticks.
self.poll_memcard();
if self.host_action_required() {
self.finish_frame_advance();
return Ok(AdvanceFrameOutcome::ActionRequired);
}
if self.bootstrap_io_pending() {
self.wait_for_bootstrap_io(&mut io_wait, progress)?;
}
}
}
self.finish_frame_advance();
@@ -341,6 +441,32 @@ impl HeadlessHost {
})
}
fn bootstrap_io_pending(&mut self) -> bool {
let FirmwareState::GameRunning(step) = &self.firmware.state else { return false };
let task = step.task_id;
let hook_complete = self
.firmware
.os
.sessions()
.vm_session_for_task(task)
.is_some_and(|session| session.vm.memcard_boot_result() == Some(0));
let service = self.firmware.os.memcard();
hook_complete && service.session.boot_pending() && service.session.io_active()
}
fn wait_for_bootstrap_io(
&mut self,
wait: &mut BootstrapIoWait,
progress: u64,
) -> Result<(), HostError> {
let Some(timeout) = wait.next_wait(Instant::now()) else {
self.finish_frame_advance();
return Err(self.memcard_error("advance", "restart_required"));
};
self.firmware.os.memcard().lane.wait_for_progress(progress, timeout);
Ok(())
}
pub fn advance_frames(&mut self, count: u64) -> Result<AdvanceFramesOutcome, HostError> {
let mut completed = 0;
for _ in 0..count {
@@ -360,6 +486,13 @@ impl HeadlessHost {
stop: AdvanceFramesStop::Terminated,
});
}
AdvanceFrameOutcome::ActionRequired => {
return Ok(AdvanceFramesOutcome {
requested: count,
completed,
stop: AdvanceFramesStop::ActionRequired,
});
}
}
}
Ok(AdvanceFramesOutcome { requested: count, completed, stop: AdvanceFramesStop::Completed })
@@ -416,6 +549,8 @@ impl HeadlessHost {
fn execution_status(&mut self) -> HostExecutionStatus {
if self.fault_is_visible() {
HostExecutionStatus::Faulted
} else if self.host_action_required() {
HostExecutionStatus::Paused
} else if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
HostExecutionStatus::Terminated
} else if self.firmware.os.vm().paused() {
@@ -432,7 +567,9 @@ impl HeadlessHost {
fn require_active(&mut self, operation: &'static str) -> Result<(), HostError> {
let status = self.execution_status();
if matches!(status, HostExecutionStatus::Running | HostExecutionStatus::Paused) {
if matches!(status, HostExecutionStatus::Running | HostExecutionStatus::Paused)
&& !self.host_action_required()
{
Ok(())
} else {
Err(HostError::InvalidState { operation, status })
@@ -463,6 +600,11 @@ impl RenderSubmissionSink for HeadlessPlatform {
let frame_id = submission.frame_id;
let ownership = submission.ownership;
self.hardware.submit_render_submission(submission)?;
// Host dialogs use their own producer and may reuse FrameId::ZERO.
// Capture/advance observe only canonical game publications.
if ownership.app_mode != prometeu_hal::app_mode::AppMode::Game {
return Ok(());
}
let (width, height) = self.hardware.gfx.size();
let pixels = self.hardware.gfx.front_buffer().to_vec();
let frame = OwnedRgba8888Frame::packed(frame_id, ownership, width, height, pixels)
@@ -11,5 +11,6 @@ mod host;
pub use host::{
AdvanceFrameOutcome, AdvanceFramesOutcome, AdvanceFramesStop, CapturedFrame, HeadlessHost,
HostError, HostExecutionStatus, HostState,
HostError, HostExecutionStatus, HostState, MediaAccess, MediaAction, MemcardChoice,
MemcardFailure, MemcardMount, MemcardState, PendingWrites, TeardownPolicy,
};
@@ -0,0 +1,480 @@
//! Public native host controls; all image policy stays in the shared system service.
use super::{HeadlessHost, HostError};
use prometeu_drivers::memcard::FileMemcard;
use prometeu_firmware::FirmwareState;
use prometeu_hal::memcard::{MemcardIoError, MemcardStorage};
use prometeu_system::memcard::{
admission::{Choice, PreparationState},
image::{Error, IMAGE_BYTES},
session::{Mode, RequestReason, RequestState},
transaction::Card,
};
use serde::{Deserialize, Serialize};
use std::{
path::PathBuf,
time::{Duration, Instant},
};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum MediaAction {
Open,
Create,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum MediaAccess {
ReadWrite,
ReadOnly,
}
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MemcardMount {
pub path: String,
pub action: MediaAction,
pub access: MediaAccess,
}
#[derive(Debug, Clone, Copy, Default, Deserialize, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum PendingWrites {
#[default]
Wait,
Cancel,
}
#[derive(Debug, Clone, Copy, Default, Deserialize)]
#[serde(default, deny_unknown_fields, rename_all = "camelCase")]
pub struct TeardownPolicy {
pub discard_unsaved: bool,
pub pending_writes: PendingWrites,
}
#[derive(Debug, Clone, Copy, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemcardChoice {
Persistent,
MemoryFresh,
MemoryExisting,
}
impl From<MemcardChoice> for Choice {
fn from(c: MemcardChoice) -> Self {
match c {
MemcardChoice::Persistent => Self::Persistent,
MemcardChoice::MemoryFresh => Self::MemoryFresh,
MemcardChoice::MemoryExisting => Self::MemoryExisting,
}
}
}
pub(super) fn choice_name(c: Choice) -> &'static str {
match c {
Choice::Persistent => "persistent",
Choice::MemoryFresh => "memory_fresh",
Choice::MemoryExisting => "memory_existing",
}
}
pub(super) fn error_name(e: Error) -> &'static str {
match e {
Error::Io(e) => match e {
MemcardIoError::Unavailable => "unavailable",
MemcardIoError::ReadOnly => "read_only",
MemcardIoError::InvalidRange => "invalid_range",
MemcardIoError::NoSpace => "no_space",
MemcardIoError::Unsupported => "unsupported",
MemcardIoError::Busy => "busy",
MemcardIoError::AccessDenied => "access_denied",
MemcardIoError::AlreadyExists => "already_exists",
MemcardIoError::Indeterminate => "indeterminate",
MemcardIoError::IoError => "io_error",
},
Error::Corrupt => "corrupt",
Error::Unsupported => "unsupported",
Error::NoSpace => "no_space",
Error::InvalidRange => "invalid_range",
Error::CounterExhausted => "counter_exhausted",
Error::ReadOnly => "read_only",
Error::Indeterminate => "indeterminate",
Error::Busy => "busy",
Error::Canceled => "canceled",
Error::OutOfMemory => "out_of_memory",
Error::AccessDenied => "access_denied",
Error::InvalidState => "invalid_state",
Error::IdentityMismatch => "identity_mismatch",
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct MemcardState {
pub media: MediaState,
pub session: SessionState,
pub dirty: bool,
pub dirty_slots: Vec<usize>,
pub request: Option<RequestObservation>,
pub io: IoState,
pub recovery: RecoveryState,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct MediaState {
pub path: Option<PathBuf>,
pub card_id: Option<String>,
pub access: Option<MediaAccess>,
pub mount_epoch: String,
pub preparation: &'static str,
pub error: Option<&'static str>,
pub recovered: bool,
pub degraded: bool,
pub write_blocked: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionState {
pub app_id: Option<u32>,
pub choice: Option<&'static str>,
pub mode: Option<&'static str>,
pub boot_attempted: bool,
pub boot_phase: &'static str,
pub resident: bool,
pub action_required: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RequestObservation {
pub id: String,
pub state: &'static str,
pub reason: &'static str,
pub storage_error: Option<&'static str>,
pub operation: &'static str,
pub slot: Option<usize>,
pub retained: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct IoState {
pub active: bool,
pub deferred: bool,
pub phase: &'static str,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RecoveryState {
pub removal_pending: bool,
pub reconciliation_required: bool,
pub restart_required: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MemcardFailure {
pub operation: &'static str,
pub reason: &'static str,
pub state: MemcardState,
}
#[derive(Default)]
pub(super) struct MediaSelection {
path: Option<PathBuf>,
access: Option<MediaAccess>,
card_id: Option<[u8; 16]>,
error: Option<&'static str>,
pub choice: Option<Choice>,
pub boot_phase: &'static str,
shutdown_failed: bool,
}
impl HeadlessHost {
/// Poll only native work. This does not tick firmware or execute guest code.
pub fn poll_memcard(&mut self) {
self.firmware.os.poll_background_io(&mut self.platform);
}
pub(super) fn memcard_error(
&mut self,
operation: &'static str,
reason: &'static str,
) -> HostError {
HostError::Memcard(Box::new(MemcardFailure {
operation,
reason,
state: self.get_memcard_state(),
}))
}
pub fn get_memcard_state(&mut self) -> MemcardState {
let resident = self.firmware.os.lifecycle().resident_game_task().is_some();
let service = self.firmware.os.memcard();
let d = service.session_diagnostics();
let preparation = service.preparation_active();
let host_faulted = service.host_faulted() || self.media.shutdown_failed;
let (state, error) = match service.admission.state {
PreparationState::Idle => ("idle", None),
PreparationState::Pending => ("pending", None),
PreparationState::Ready => ("ready", None),
PreparationState::Failed(e) => ("failed", Some(error_name(e))),
};
let id = d.card_id.or(service.installed_card_id()).or(self.media.card_id);
let health = if d.mode.is_some() {
d.health
} else {
service.installed_health().unwrap_or((false, false, false))
};
let phase = if preparation {
"preparing"
} else if d.request.as_ref().is_some_and(|r| r.deferred) {
"deferred"
} else if d.io_active {
if service.lane.telemetry().active_job_id == service.session.pending_job() {
"running"
} else {
"queued"
}
} else if d.request.is_some() {
"returned"
} else {
"idle"
};
MemcardState {
media: MediaState {
path: self.media.path.clone(),
access: self.media.access,
card_id: id.map(|id| id.iter().map(|v| format!("{v:02x}")).collect()),
mount_epoch: d.epoch.to_string(),
preparation: state,
error: error.or(self.media.error),
recovered: health.0,
degraded: health.1,
write_blocked: health.2,
},
session: SessionState {
app_id: d.app_id,
choice: self.media.choice.map(choice_name),
mode: d.mode.map(|m| match m {
Mode::Persistent => "persistent",
Mode::MemoryOnly => "memory_only",
}),
boot_attempted: self.boot_attempted,
boot_phase: if self.media.boot_phase.is_empty() {
"idle"
} else {
self.media.boot_phase
},
resident,
action_required: d.mode.is_some()
&& resident
&& (d.removal_pending
|| host_faulted
|| !matches!(self.firmware.state, FirmwareState::GameRunning(_))),
},
dirty: !d.dirty_slots.is_empty(),
dirty_slots: d.dirty_slots,
request: d.request.map(|r| RequestObservation {
id: r.result.id.to_string(),
state: match r.result.state {
RequestState::Pending => "pending",
RequestState::Success => "success",
RequestState::Failure => "failure",
RequestState::Indeterminate => "indeterminate",
RequestState::MemoryOnly => "memory_only",
},
reason: match r.result.reason {
RequestReason::None => "none",
RequestReason::Timeout => "timeout",
RequestReason::RestartRequired => "restart_required",
RequestReason::Storage(e) => error_name(e),
},
storage_error: r.storage_error.map(error_name),
operation: r.operation,
slot: r.slot,
retained: r.retained,
}),
io: IoState {
active: preparation || d.io_active,
deferred: phase == "deferred",
phase,
},
recovery: RecoveryState {
removal_pending: d.removal_pending,
reconciliation_required: d.reconciliation_required,
restart_required: host_faulted,
},
}
}
pub fn mount_memcard(&mut self, options: MemcardMount) -> Result<MemcardState, HostError> {
self.poll_memcard();
if self.firmware.os.lifecycle().resident_game_task().is_some() {
return Err(self.memcard_error("memcard_mount", "invalid_state"));
}
if options.path.trim().is_empty()
|| matches!(
(options.action, options.access),
(MediaAction::Create, MediaAccess::ReadOnly)
)
{
return Err(self.memcard_error("memcard_mount", "invalid_state"));
}
let path = std::path::absolute(&options.path)
.map_err(|_| self.memcard_error("memcard_mount", "unavailable"))?;
// Do not change selection when admission is refused as busy.
let open_path = path.clone();
let result = self.firmware.os.memcard().mount_card_with(move || {
let io = match options.action {
MediaAction::Open => {
FileMemcard::open(&open_path, options.access == MediaAccess::ReadOnly)?
}
MediaAction::Create => FileMemcard::create(&open_path, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})?,
};
Ok(Box::new(io) as Box<dyn MemcardStorage>)
});
result.map_err(|e| self.memcard_error("memcard_mount", error_name(e)))?;
self.media.path = Some(path);
self.media.access = Some(options.access);
self.media.error = None;
self.media.card_id = None;
if let Err(error) = self.wait_preparation("memcard_mount") {
if let HostError::Memcard(e) = &error {
self.media.error = Some(e.reason);
}
return Err(error);
}
self.media.card_id = self.firmware.os.memcard().installed_card_id();
Ok(self.get_memcard_state())
}
pub fn unmount_memcard(&mut self) -> Result<MemcardState, HostError> {
self.poll_memcard();
if self.firmware.os.lifecycle().resident_game_task().is_some() {
return Err(self.memcard_error("memcard_unmount", "invalid_state"));
}
self.firmware
.os
.memcard()
.uninstall_card()
.map_err(|e| self.memcard_error("memcard_unmount", error_name(e)))?;
self.media = MediaSelection { boot_phase: self.media.boot_phase, ..Default::default() };
Ok(self.get_memcard_state())
}
fn wait_preparation(&mut self, operation: &'static str) -> Result<(), HostError> {
let deadline = Instant::now() + Duration::from_secs(2);
loop {
self.poll_memcard();
match self.firmware.os.memcard().admission.state {
PreparationState::Ready => return Ok(()),
PreparationState::Failed(e) => {
let reason = if self.firmware.os.memcard().host_faulted() {
"restart_required"
} else {
error_name(e)
};
return Err(self.memcard_error(operation, reason));
}
_ => {}
}
if Instant::now() >= deadline {
return Err(self.memcard_error(operation, "restart_required"));
}
let lane = self.firmware.os.memcard().lane.clone();
lane.wait_for_progress(lane.progress_stamp(), Duration::from_millis(5));
}
}
pub fn prepare_teardown(
&mut self,
policy: TeardownPolicy,
operation: &'static str,
) -> Result<MemcardState, HostError> {
self.poll_memcard();
if matches!(policy.pending_writes, PendingWrites::Cancel) {
self.firmware.os.memcard().cancel_pending();
}
let deadline = Instant::now() + Duration::from_secs(2);
loop {
self.poll_memcard();
let state = self.get_memcard_state();
if !state.io.active && !state.io.deferred {
break;
}
if state.recovery.restart_required || Instant::now() >= deadline {
return Err(self.memcard_error(operation, "restart_required"));
}
let lane = self.firmware.os.memcard().lane.clone();
lane.wait_for_progress(lane.progress_stamp(), Duration::from_millis(5));
}
if self.get_memcard_state().dirty && !policy.discard_unsaved {
return Err(self.memcard_error(operation, "unsaved_changes"));
}
Ok(self.get_memcard_state())
}
pub fn reset_with_policy(&mut self, policy: TeardownPolicy) -> Result<MemcardState, HostError> {
self.prepare_teardown(policy, "reset")?;
self.reset_inner();
self.media.choice = None;
self.media.boot_phase = "idle";
self.poll_memcard();
Ok(self.get_memcard_state())
}
pub fn shutdown(&mut self, policy: TeardownPolicy) -> Result<MemcardState, HostError> {
let state = self.prepare_teardown(policy, "shutdown")?;
if self.firmware.os.stop_background_io().is_err() {
self.media.shutdown_failed = true;
return Err(self.memcard_error("shutdown", "restart_required"));
}
self.firmware.os.memcard().session.end_session();
self.firmware.os.memcard().poll(Instant::now());
self.firmware
.os
.memcard()
.uninstall_card()
.map_err(|e| self.memcard_error("shutdown", error_name(e)))?;
Ok(state)
}
pub fn reconcile_memcard(&mut self) -> Result<MemcardState, HostError> {
self.poll_memcard();
if !self.suspended_for_memcard() {
return Err(self.memcard_error("memcard_reconcile", "invalid_state"));
}
let path = self
.media
.path
.clone()
.ok_or_else(|| self.memcard_error("memcard_reconcile", "invalid_state"))?;
let read_only = self.media.access == Some(MediaAccess::ReadOnly);
self.firmware
.os
.memcard()
.reconcile_card_with(move || {
Ok(Box::new(FileMemcard::open(&path, read_only)?) as Box<dyn MemcardStorage>)
})
.map_err(|e| self.memcard_error("memcard_reconcile", error_name(e)))?;
self.wait_preparation("memcard_reconcile")?;
self.media.error = None;
if !self.firmware.resume_resident_game_from_home() {
return Err(self.memcard_error("memcard_reconcile", "invalid_state"));
}
Ok(self.get_memcard_state())
}
pub fn continue_memcard_in_memory(&mut self) -> Result<MemcardState, HostError> {
self.poll_memcard();
if !self.suspended_for_memcard() {
return Err(self.memcard_error("memcard_continue_in_memory", "invalid_state"));
}
self.firmware
.os
.detach_memcard()
.map_err(|e| self.memcard_error("memcard_continue_in_memory", error_name(e)))?;
if !self.firmware.resume_resident_game_from_home() {
return Err(self.memcard_error("memcard_continue_in_memory", "invalid_state"));
}
Ok(self.get_memcard_state())
}
fn suspended_for_memcard(&mut self) -> bool {
let Some(task) = self.firmware.os.lifecycle().resident_game_task() else { return false };
self.firmware.os.lifecycle().task_state(task)
== Some(prometeu_system::task::TaskState::Suspended)
&& (self.firmware.os.memcard().session.removal_pending()
|| self.firmware.os.memcard().session.diagnostics().reconciliation_required
|| self.firmware.os.memcard().session.host_faulted())
}
pub(super) fn host_action_required(&mut self) -> bool {
self.firmware.os.memcard().session.mode().is_some()
&& self.firmware.os.lifecycle().resident_game_task().is_some()
&& (self.firmware.os.memcard().session.removal_pending()
|| self.firmware.os.memcard().host_faulted()
|| !matches!(self.firmware.state, FirmwareState::GameRunning(_)))
}
}
#[cfg(test)]
#[path = "memcard_tests.rs"]
mod tests;
@@ -0,0 +1,487 @@
use super::*;
use crate::{AdvanceFrameOutcome, HostExecutionStatus};
use prometeu_test_support::memcard_fixture::{MemcardFixture, memcard_program};
use std::{fs, sync::mpsc};
/// Holds the first native write after admission; the controller decides its outcome.
struct BootstrapStore {
file: FileMemcard,
entered: mpsc::Sender<()>,
continue_io: mpsc::Receiver<Result<(), MemcardIoError>>,
held: bool,
}
impl MemcardStorage for BootstrapStore {
fn len(&self) -> Result<u64, MemcardIoError> {
self.file.len()
}
fn read_only(&self) -> bool {
false
}
fn read_at(&mut self, offset: u64, bytes: &mut [u8]) -> Result<(), MemcardIoError> {
self.file.read_at(offset, bytes)
}
fn write_at(&mut self, offset: u64, bytes: &[u8]) -> Result<(), MemcardIoError> {
if !self.held {
self.held = true;
let _ = self.entered.send(());
self.continue_io
.recv_timeout(Duration::from_secs(5))
.unwrap_or(Err(MemcardIoError::IoError))?;
}
self.file.write_at(offset, bytes)
}
fn sync(&mut self) -> Result<(), MemcardIoError> {
self.file.sync()
}
}
fn reopen_with_controlled_io(
kind: MemcardFixture,
) -> (Fixture, HeadlessHost, mpsc::Receiver<()>, mpsc::Sender<Result<(), MemcardIoError>>) {
use prometeu_system::memcard::{
image::{Game, Icon, crc32c},
transaction::{DurableResult, PublicationControl},
};
let f = Fixture::new(kind);
let file = FileMemcard::create(&f.image, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap();
let mut card = Card::mount(Box::new(file)).unwrap();
let icon = [0; 560];
card.register(
Game {
app_id: 42,
title: "Existing record".into(),
data_format_version: 1,
created_at: 0,
slots: vec![0],
icon: Icon { offset: 0, frames: 1, duration: 1, crc32c: crc32c(&icon) },
},
&icon,
&PublicationControl::default(),
)
.unwrap();
assert_eq!(
card.commit(0, &[0, 127, 128, 255], 0, &PublicationControl::default()).durable,
DurableResult::Success
);
drop(card);
let (entered_tx, entered) = mpsc::channel();
let (continue_io, release_rx) = mpsc::channel();
let mut host = HeadlessHost::new();
host.media.path = Some(f.image.clone());
host.media.access = Some(MediaAccess::ReadWrite);
host.install_memcard(Box::new(BootstrapStore {
file: FileMemcard::open(&f.image, false).unwrap(),
entered: entered_tx,
continue_io: release_rx,
held: false,
}))
.unwrap();
host.boot_with_memcard_choice(f.cart.to_string_lossy(), Choice::Persistent).unwrap();
assert_eq!(host.get_state().tick_index, 0);
(f, host, entered, continue_io)
}
#[test]
fn first_reopen_frame_waits_for_controlled_presentation_without_replaying() {
let (_f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let (finished_tx, finished) = mpsc::channel();
let controller = std::thread::spawn(move || {
entered.recv_timeout(Duration::from_secs(3)).unwrap();
// Observe the owner while publication is provably held. This is a
// channel deadline, not a sleep used to infer that IO has started.
let premature = finished.recv_timeout(Duration::from_millis(300)).is_ok();
let _ = continue_io.send(Ok(()));
premature
});
let result = host.advance_frame();
let _ = finished_tx.send(());
let premature = controller.join().unwrap();
assert!(!premature, "advance returned while native publication was held: {result:?}");
assert!(matches!(
result,
Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. })
));
let state = host.get_state();
assert_eq!(state.frame_index, 1);
assert_eq!(state.tick_index, 2);
assert_eq!(state.status, HostExecutionStatus::Paused);
assert_eq!(state.stack_top.last(), Some(&prometeu_bytecode::Value::Int64(201)));
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
assert!(!host.get_memcard_state().io.active);
assert_eq!(host.capture_frame().unwrap().logical_frame_index, 1);
host.shutdown(TeardownPolicy::default()).unwrap();
}
#[test]
fn blocked_bootstrap_reaches_native_deadline_and_keeps_worker_lock() {
let (f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let started = Instant::now();
let result = host.advance_frame();
entered.recv_timeout(Duration::from_secs(1)).unwrap();
let state = host.get_memcard_state();
let busy = matches!(FileMemcard::open(&f.image, false), Err(MemcardIoError::Busy));
// Always let the worker return before asserting, including on the old host.
continue_io.send(Ok(())).unwrap();
settle(&mut host);
assert_eq!(result.unwrap(), AdvanceFrameOutcome::ActionRequired);
assert!(started.elapsed() < Duration::from_secs(3));
assert!(state.recovery.restart_required);
assert!(state.io.active && busy);
assert_eq!(host.get_state().frame_index, 0);
assert_eq!(host.get_state().tick_index, 1);
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
}
#[test]
fn ordinary_gameplay_commit_does_not_wait_for_native_io() {
let (_f, mut host, entered, continue_io) = reopen_with_controlled_io(MemcardFixture::Read);
host.advance_frame().unwrap();
let service = host.firmware.os.memcard();
let context = service.session.context();
service.session.write(context, 0, 0, &[0, 127, 128, 255]).unwrap();
service.session.commit(context, 0, 0, Instant::now(), &service.lane).unwrap();
entered.recv_timeout(Duration::from_secs(2)).unwrap();
let result = host.advance_frame();
let pending = host.get_memcard_state();
continue_io.send(Ok(())).unwrap();
settle(&mut host);
assert!(matches!(
result,
Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 2, .. })
));
assert!(pending.io.active);
assert_eq!(pending.request.unwrap().operation, "commit");
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
host.shutdown(TeardownPolicy::default()).unwrap();
}
#[test]
fn bootstrap_wait_deadline_is_shared_across_wakes_and_reentry() {
use super::super::{BOOTSTRAP_IO_WAIT_QUANTUM, BootstrapIoWait};
let start = Instant::now();
let mut wait = BootstrapIoWait::default();
assert_eq!(wait.next_wait(start), Some(BOOTSTRAP_IO_WAIT_QUANTUM));
assert_eq!(
wait.next_wait(start + Duration::from_millis(1000)),
Some(BOOTSTRAP_IO_WAIT_QUANTUM)
);
assert_eq!(wait.next_wait(start + Duration::from_millis(1999)), Some(Duration::from_millis(1)));
assert_eq!(wait.next_wait(start + Duration::from_secs(2)), None);
assert_eq!(wait.next_wait(start + Duration::from_secs(3)), None);
}
#[test]
fn bootstrap_outer_timeout_preserves_native_snapshot_and_machine_state() {
use super::super::BootstrapIoWait;
let (_f, mut host, _entered, _release) = reopen_with_controlled_io(MemcardFixture::Read);
let before = host.get_state();
host.firmware.os.vm().set_paused(false);
host.firmware.os.vm().request_debug_step();
let mut wait = BootstrapIoWait { deadline: Some(Instant::now()) };
let error = host.wait_for_bootstrap_io(&mut wait, 0).unwrap_err();
let snapshot = host.get_memcard_state();
let HostError::Memcard(error) = error else { panic!("expected a native memcard error") };
assert_eq!(error.operation, "advance");
assert_eq!(error.reason, "restart_required");
assert_eq!(error.state, snapshot);
let after = host.get_state();
assert_eq!((after.pc, after.frame_index, after.tick_index), (before.pc, 0, 0));
assert_eq!(after.stack_top.to_vec(), before.stack_top.to_vec());
assert_eq!(after.status, HostExecutionStatus::Paused);
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
host.shutdown(TeardownPolicy::default()).unwrap();
}
#[test]
fn failed_bootstrap_io_returns_native_media_action_without_guest_fault() {
let (_f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let controller = std::thread::spawn(move || {
entered.recv_timeout(Duration::from_secs(2)).unwrap();
continue_io.send(Err(MemcardIoError::Unavailable)).unwrap();
});
let result = host.advance_frame();
controller.join().unwrap();
assert_eq!(result.unwrap(), AdvanceFrameOutcome::ActionRequired);
let state = host.get_memcard_state();
assert!(state.recovery.removal_pending);
assert!(!state.io.active);
assert_eq!(host.get_state().frame_index, 0);
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
}
#[test]
fn queued_bootstrap_publication_can_progress_without_moving_guest_during_poll() {
use prometeu_system::AsyncWorkJobOutcome;
let (_f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let (busy_tx, busy) = mpsc::channel();
let (unblock, unblock_rx) = mpsc::channel();
host.firmware
.os
.memcard()
.lane
.submit_memcard_commit_write(move |_| {
busy_tx.send(()).unwrap();
let _ = unblock_rx.recv_timeout(Duration::from_secs(3));
AsyncWorkJobOutcome::Completed
})
.unwrap();
busy.recv_timeout(Duration::from_secs(2)).unwrap();
for _ in 0..10 {
host.firmware.os.vm().set_paused(false);
host.firmware.os.vm().request_debug_step();
host.tick_once();
if host.bootstrap_io_pending() {
break;
}
}
let pending = host.bootstrap_io_pending();
let queued = host.get_memcard_state();
let before = host.get_state();
host.poll_memcard();
let after = host.get_state();
let (finished_tx, finished) = mpsc::channel();
let controller = std::thread::spawn(move || {
let premature = finished.recv_timeout(Duration::from_millis(300)).is_ok();
let _ = unblock.send(());
entered.recv_timeout(Duration::from_secs(2)).unwrap();
let _ = continue_io.send(Ok(()));
premature
});
let result = host.advance_frame();
let _ = finished_tx.send(());
let premature = controller.join().unwrap();
assert!(pending);
assert!(!premature, "advance returned while its publication was queued: {result:?}");
assert_eq!(queued.io.phase, "queued");
assert_eq!(
(before.pc, before.frame_index, before.tick_index),
(after.pc, after.frame_index, after.tick_index)
);
assert_eq!(before.stack_top.to_vec(), after.stack_top.to_vec());
assert!(matches!(
result,
Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. })
));
host.shutdown(TeardownPolicy::default()).unwrap();
}
struct Fixture {
root: PathBuf,
image: PathBuf,
cart: PathBuf,
}
impl Fixture {
fn new(kind: MemcardFixture) -> Self {
static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
let root = std::env::temp_dir().join(format!(
"native-memcard-{}-{}-{}",
std::process::id(),
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos(),
COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
));
let cart = root.join("cart");
fs::create_dir_all(&cart).unwrap();
fs::write(cart.join("program.pbx"), memcard_program(kind)).unwrap();
fs::write(cart.join("manifest.json"),r#"{"magic":"PMTU","cartridge_version":1,"app_id":42,"title":"Native memcard","app_version":"1","app_mode":"Game","capabilities":["memcard"],"memcard_slots":1}"#).unwrap();
let image = root.join("save.pmc");
Self { root, image, cart }
}
fn mount(&self, host: &mut HeadlessHost) {
host.mount_memcard(MemcardMount {
path: self.image.to_string_lossy().into_owned(),
action: MediaAction::Create,
access: MediaAccess::ReadWrite,
})
.unwrap();
host.boot_with_memcard_choice(self.cart.to_string_lossy(), Choice::Persistent).unwrap();
}
}
impl Drop for Fixture {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.root);
}
}
fn settle(host: &mut HeadlessHost) {
let deadline = Instant::now() + Duration::from_secs(3);
loop {
host.poll_memcard();
if !host.get_memcard_state().io.active {
break;
}
assert!(Instant::now() < deadline, "IO did not cease");
let lane = host.firmware.os.memcard().lane.clone();
lane.wait_for_progress(lane.progress_stamp(), Duration::from_millis(5));
}
}
fn pause_for_media(host: &mut HeadlessHost) {
let task = host.firmware.os.lifecycle().resident_game_task().unwrap();
host.firmware.os.lifecycle().suspend_task(task).unwrap();
assert_eq!(
host.firmware.os.lifecycle().task_state(task),
Some(prometeu_system::task::TaskState::Suspended)
);
}
#[test]
fn same_media_recovery_rejects_replacement_and_preserves_ram_continuation() {
let f = Fixture::new(MemcardFixture::Dirty);
let mut host = HeadlessHost::new();
f.mount(&mut host);
assert!(matches!(host.advance_frame().unwrap(), AdvanceFrameOutcome::FrameCompleted { .. }));
settle(&mut host);
let context = host.firmware.os.memcard().session.context();
host.firmware.os.memcard().session.notify_removal();
pause_for_media(&mut host);
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
assert_eq!(host.advance_frame().unwrap(), AdvanceFrameOutcome::ActionRequired);
let old = f.root.join("old.pmc");
fs::rename(&f.image, &old).unwrap();
let replacement = FileMemcard::create(&f.image, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap();
drop(replacement);
let error = host.reconcile_memcard().unwrap_err();
assert!(matches!(error,HostError::Memcard(e) if e.reason=="identity_mismatch"));
let mut bytes = [0; 4];
host.firmware.os.memcard().session.read(context, 0, 0, &mut bytes).unwrap();
assert_eq!(bytes, [0, 127, 128, 255]);
fs::rename(&f.image, f.root.join("other.pmc")).unwrap();
fs::rename(&old, &f.image).unwrap();
let restored = host.reconcile_memcard().unwrap();
assert!(restored.dirty);
assert!(!restored.recovery.reconciliation_required);
assert_eq!(host.firmware.os.memcard().session.context(), context);
assert!(matches!(host.advance_frame().unwrap(), AdvanceFrameOutcome::FrameCompleted { .. }));
assert_eq!(host.get_state().stack_top.last(), Some(&prometeu_bytecode::Value::Int64(301)));
host.shutdown(TeardownPolicy { discard_unsaved: true, ..Default::default() }).unwrap();
}
#[test]
fn explicit_continue_in_ram_preserves_dirty_snapshot_and_uses_no_new_boot() {
let f = Fixture::new(MemcardFixture::Dirty);
let mut host = HeadlessHost::new();
f.mount(&mut host);
host.advance_frame().unwrap();
settle(&mut host);
let context = host.firmware.os.memcard().session.context();
host.firmware.os.memcard().session.notify_removal();
pause_for_media(&mut host);
let ram = host.continue_memcard_in_memory().unwrap();
assert_eq!(ram.session.mode, Some("memory_only"));
assert!(ram.dirty);
assert_eq!(host.firmware.os.memcard().session.context(), context);
host.advance_frame().unwrap();
host.shutdown(TeardownPolicy { discard_unsaved: true, ..Default::default() }).unwrap();
}
struct GateStore {
file: FileMemcard,
inside_publication: bool,
payload_seen: bool,
fired: bool,
entered: mpsc::Sender<()>,
continue_io: mpsc::Receiver<()>,
}
impl MemcardStorage for GateStore {
fn len(&self) -> Result<u64, MemcardIoError> {
self.file.len()
}
fn read_only(&self) -> bool {
false
}
fn read_at(&mut self, o: u64, b: &mut [u8]) -> Result<(), MemcardIoError> {
self.file.read_at(o, b)
}
fn sync(&mut self) -> Result<(), MemcardIoError> {
self.file.sync()
}
fn write_at(&mut self, o: u64, b: &[u8]) -> Result<(), MemcardIoError> {
let payload = o >= prometeu_system::memcard::image::DATA_OFFSET;
self.payload_seen |= payload;
let publication = self.payload_seen && (o == 8192 || o == 12288);
if !self.fired && if self.inside_publication { publication } else { payload } {
self.fired = true;
if self.inside_publication {
self.file.write_at(o, b)?;
}
self.entered.send(()).unwrap();
self.continue_io.recv_timeout(Duration::from_secs(10)).unwrap();
return Err(MemcardIoError::IoError);
}
self.file.write_at(o, b)
}
}
#[test]
fn unceased_io_retains_lock_and_terminal_result_survives_late_return_and_reconcile() {
for inside_publication in [false, true] {
let f = Fixture::new(MemcardFixture::Write);
let file = FileMemcard::create(&f.image, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap();
let (entered_tx, entered) = mpsc::channel();
let (continue_io, release_rx) = mpsc::channel();
let mut host = HeadlessHost::new();
host.media.path = Some(f.image.clone());
host.media.access = Some(MediaAccess::ReadWrite);
host.install_memcard(Box::new(GateStore {
file,
inside_publication,
payload_seen: false,
fired: false,
entered: entered_tx,
continue_io: release_rx,
}))
.unwrap();
host.boot_with_memcard_choice(f.cart.to_string_lossy(), Choice::Persistent).unwrap();
host.advance_frame().unwrap();
entered.recv_timeout(Duration::from_secs(3)).unwrap();
host.firmware.os.memcard().poll(Instant::now() + Duration::from_secs(2));
let before = host.get_memcard_state();
assert!(before.io.active);
assert!(before.recovery.restart_required);
assert_eq!(
before.request.as_ref().unwrap().state,
if inside_publication { "indeterminate" } else { "failure" }
);
assert!(
matches!(host.shutdown(TeardownPolicy{discard_unsaved:true,..Default::default()}),Err(HostError::Memcard(e)) if e.reason=="restart_required")
);
assert!(matches!(FileMemcard::open(&f.image, false), Err(MemcardIoError::Busy)));
continue_io.send(()).unwrap();
settle(&mut host);
let returned = host.get_memcard_state().request;
let original = before.request.as_ref().unwrap();
let late = returned.as_ref().unwrap();
assert_eq!(
(&late.id, late.state, late.reason),
(&original.id, original.state, original.reason),
"late completion cannot rewrite the original result"
);
assert_eq!(late.storage_error, Some("io_error"));
pause_for_media(&mut host);
let restored = host.reconcile_memcard().unwrap();
assert_eq!(
restored.request, returned,
"recovery must not consume or rewrite the guest result"
);
assert!(!restored.recovery.restart_required);
host.shutdown(TeardownPolicy { discard_unsaved: true, ..Default::default() }).unwrap();
}
}
@@ -61,7 +61,7 @@ fn thousand_reset_reload_cycles_release_session_owners_and_preserve_controls() {
));
assert_eq!(&*host.get_state().stack_top, &[Value::Int32(73)]);
assert!(host.get_fault().is_none());
host.reset();
host.reset().expect("reset");
assert_eq!(host.firmware.os.sessions().vm_session_count(), 0);
assert_eq!(
observer.diagnostic_snapshot().used,
@@ -37,7 +37,7 @@ fn controlled_civil_time_is_independent_of_frames_pause_and_reset() {
host.controlled_wall_clock().unwrap().set(10);
host.advance_frame().expect("frame after clock adjustment");
assert_eq!(host.wall_clock().utc_unix_seconds(), 10);
host.reset();
host.reset().expect("reset");
assert_eq!(host.wall_clock().utc_unix_seconds(), 10);
host.boot(&cartridge).expect("reboot");
assert_eq!(host.wall_clock().utc_unix_seconds(), 10);
@@ -57,7 +57,7 @@ fn injected_civil_clock_remains_the_runtime_source_across_lifecycle() {
assert_eq!(host.wall_clock().utc_unix_seconds(), u64::MAX);
clock.set(42);
assert_eq!(host.wall_clock().utc_unix_seconds(), 42);
host.reset();
host.reset().expect("reset");
clock.advance(3);
assert_eq!(host.wall_clock().utc_unix_seconds(), 45);
}
@@ -290,7 +290,7 @@ fn two_runs_match_oracle() {
fn reset_matches_fresh_host() {
let mut host = boot_color();
let _ = run_on(&mut host);
host.reset();
host.reset().expect("reset");
assert_eq!(host.get_state().status, HostExecutionStatus::Terminated);
assert_eq!(host.capture_frame(), Err(HostError::NoFrameAvailable));
host.boot(color_cartridge()).expect("reboot");
@@ -357,7 +357,7 @@ fn batch_stops_early_on_fault_and_reports_partial_progress() {
#[test]
fn advance_after_reset_reports_termination_without_ticking() {
let mut host = boot_color();
host.reset();
host.reset().expect("reset");
let before = host.get_state().tick_index;
assert_eq!(host.advance_frame().expect("termination outcome"), AdvanceFrameOutcome::Terminated);
+1 -1
View File
@@ -108,7 +108,7 @@ pub fn build_program() -> Vec<u8> {
],
}
.serialize(&mut LoadBudget::new(Default::default()))
.expect("bounded v1 program")
.expect("bounded v0 program")
}
pub fn manifest_json() -> Vec<u8> {
+1 -1
View File
@@ -114,7 +114,7 @@ pub fn generate() -> Result<()> {
syscalls: &syscalls,
}
.serialize(&mut LoadBudget::new(Default::default()))
.expect("bounded v1 program");
.expect("bounded v0 program");
let mut out_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
out_dir.pop(); // pbxgen-stress
+22
View File
@@ -2,6 +2,28 @@
use clap::Args;
use prometeu_host_headless::automation::Limits;
#[derive(Args, Debug)]
pub struct DesktopMediaArgs {
/// Explicit memory-card image used by the desktop host.
#[arg(long, value_name = "PATH")]
pub memcard: Option<String>,
/// Create a new image; never replace an existing destination.
#[arg(long, requires = "memcard")]
pub create_memcard: bool,
}
impl DesktopMediaArgs {
pub fn forwarded_args(&self) -> Vec<String> {
let mut args = Vec::new();
if let Some(path) = &self.memcard {
args.extend(["--memcard".into(), path.clone()]);
}
if self.create_memcard {
args.push("--create-memcard".into());
}
args
}
}
#[derive(Args, Debug)]
pub struct HeadlessArgs {
/// Use the versioned JSONL stdin/stdout protocol (required).
+14 -8
View File
@@ -25,6 +25,8 @@ enum Commands {
Run {
/// Path to the cartridge (directory or .pmc file).
cart: String,
#[command(flatten)]
media: prometeu_cli::DesktopMediaArgs,
},
/// Executes a cartridge in Assisted Mode (Debug).
/// The runtime will wait for a DevTools connection before starting.
@@ -34,6 +36,8 @@ enum Commands {
/// TCP port for the DevTools server (default: 7777).
#[arg(long, default_value_t = 7777)]
port: u16,
#[command(flatten)]
media: prometeu_cli::DesktopMediaArgs,
},
}
@@ -72,15 +76,17 @@ fn main() {
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]);
Some(Commands::Run { cart, media }) => {
let mut args = vec!["--run".into(), cart];
args.extend(media.forwarded_args());
let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
dispatch(&exe_dir, "prometeu-runtime", &borrowed);
}
Some(Commands::Debug { cart, port }) => {
dispatch(
&exe_dir,
"prometeu-runtime",
&["--debug", &cart, "--port", &port.to_string()],
);
Some(Commands::Debug { cart, port, media }) => {
let mut args = vec!["--debug".into(), cart, "--port".into(), port.to_string()];
args.extend(media.forwarded_args());
let borrowed: Vec<&str> = args.iter().map(String::as_str).collect();
dispatch(&exe_dir, "prometeu-runtime", &borrowed);
}
None => {
use clap::CommandFactory;
@@ -1,7 +1,7 @@
use base64::{Engine as _, engine::general_purpose::STANDARD};
use prometeu_bytecode::SourceSpan;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{DebugInfo, Export, SyscallDecl};
use prometeu_bytecode::model::{ConstantPoolEntry, DebugInfo, Export, SyscallDecl};
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_host_headless::{AdvanceFramesStop, HeadlessHost};
use prometeu_test_support::program::{TestProgram, int64_signature};
@@ -16,6 +16,8 @@ use std::sync::{
mpsc,
};
use std::time::{Duration, Instant};
#[path = "support/memcard_process.rs"]
mod memcard_process;
struct TempDir(PathBuf);
impl TempDir {
@@ -221,6 +223,48 @@ fn cartridge_bytes(code: Vec<u8>, gfx: bool) -> TempDir {
fn colored_cart() -> TempDir {
cartridge("PUSH_I64 4278190335\nHOSTCALL 0\nRET\n", true)
}
fn logging_cart(messages_per_frame: usize, message: &str) -> TempDir {
let dir = TempDir::new();
let code = assemble(&format!(
"{}RET\n",
"PUSH_I64 2\nPUSH_I64 41000\nPUSH_CONST 0\nHOSTCALL 0\n".repeat(messages_per_frame)
))
.unwrap();
let mut module = TestProgram::single(code, int64_signature(0, 0), 0, 3);
module.const_pool = vec![ConstantPoolEntry::String(message.into())];
module.exports = vec![Export { symbol: "main".into(), func_idx: 0 }];
module.syscalls = vec![SyscallDecl {
module: "log".into(),
name: "write_tag".into(),
version: 1,
arg_slots: 3,
ret_slots: 0,
}];
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":"Native log test",
"app_version":"0.1.0","app_mode":"Game","capabilities":["log"]}))
.unwrap(),
)
.unwrap();
dir
}
fn initialize_logs(client: &mut Client) {
let result = client.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":2},
"requiredCapabilities":["log_read"]}),
);
assert_eq!(result["protocolVersion"]["minor"], 2);
}
fn read_log_page(client: &mut Client, after: Value, limit: u16) -> Value {
client.ok("get_logs", json!({"afterSequence":after,"limit":limit}))
}
fn boot(client: &mut Client, dir: &TempDir) {
client.ok("boot", json!({"path":dir.0}));
}
@@ -241,7 +285,7 @@ fn png_bytes(capture: &Value) -> Vec<u8> {
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["protocolVersion"], json!({"major":1,"minor":2}));
assert_eq!(
c.hello["limits"],
json!({"maxFrames":600,"maxCommandBytes":65536,"maxResponseBytes":33554432,
@@ -267,7 +311,7 @@ fn handshake_versions_capabilities_and_limits_are_explicit() {
"initialize",
json!({"protocolVersion":{"major":1,"minor":42},"requiredCapabilities":[]})
)["protocolVersion"]["minor"],
0
2
);
assert_eq!(
c.call(
@@ -430,11 +474,15 @@ fn faults_and_boot_failures_are_structured_not_log_parsing() {
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();
initialize_logs(&mut c);
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");
assert_eq!(
c.call("get_logs", json!({"afterSequence":null,"limit":1}))["error"]["code"],
"busy"
);
c.ok("cancel", json!({"targetRequestId":advance}));
let response = c.response(&advance);
let result = &response["result"];
@@ -549,6 +597,187 @@ fn missing_binary_and_invalid_cli_limits_fail_explicitly() {
}
}
#[test]
fn log_read_requires_explicit_capability_and_minor_two() {
for minor in [0, 1, 2] {
let mut c = Client::new(&["--stdio"]);
assert!(c.hello["capabilities"].as_array().unwrap().contains(&json!("log_read")));
if minor < 2 {
assert_eq!(
c.call(
"initialize",
json!({"protocolVersion":{"major":1,"minor":minor},
"requiredCapabilities":["log_read"]})
)["error"]["code"],
"incompatible_version"
);
}
let initialized = c.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":minor},
"requiredCapabilities":[]}),
);
assert_eq!(initialized["protocolVersion"]["minor"], minor);
assert_eq!(
c.call("get_logs", json!({"afterSequence":null,"limit":1}))["error"]["code"],
"unsupported_capability"
);
assert_eq!(c.ok("get_state", json!({}))["logicalFrameIndex"], 0);
c.close();
}
}
#[test]
fn native_log_pages_are_read_only_replayable_and_survive_reset() {
let dir = logging_cart(2, "{\"native\":\"é\"}");
let mut c = Client::new(&["--stdio"]);
initialize_logs(&mut c);
let initial = read_log_page(&mut c, Value::Null, 1);
assert_eq!(initial["events"][0]["sequence"], 0);
assert_eq!(initial["events"][0]["source"], "pos");
assert_eq!(initial["events"][0]["appId"], Value::Null);
assert_eq!(initial["sessionId"], c.hello["sessionId"]);
assert_eq!(initial["logEpoch"], 0);
assert_eq!(initial["gap"], false);
assert_eq!(initial["overflow"], false);
boot(&mut c, &dir);
c.ok("advance", json!({"frames":2}));
let state = c.ok("get_state", json!({}));
let fault = c.ok("get_fault", json!({}));
let all = read_log_page(&mut c, Value::Null, 1024);
let native = all["events"].as_array().unwrap();
let app: Vec<_> = native.iter().filter(|event| event["source"] == "app").collect();
assert_eq!(app.len(), 4);
assert!(app.iter().all(|event| event["tag"] == 41000
&& event["appId"] == 41
&& event["level"] == "info"
&& event["message"] == "{\"native\":\"é\"}"));
let mut cursor = Value::Null;
let mut paged = Vec::new();
loop {
let page = read_log_page(&mut c, cursor.clone(), 2);
assert_eq!(page, read_log_page(&mut c, cursor.clone(), 2));
paged.extend(page["events"].as_array().unwrap().iter().cloned());
cursor = page["nextAfterSequence"].clone();
if cursor == page["newestSequence"] {
break;
}
}
assert_eq!(&paged, native);
let empty = read_log_page(&mut c, cursor.clone(), 1);
assert!(empty["events"].as_array().unwrap().is_empty());
assert_eq!(empty["nextAfterSequence"], cursor);
assert_eq!(state, c.ok("get_state", json!({})));
assert_eq!(fault, c.ok("get_fault", json!({})));
assert_eq!(
c.call("get_logs", json!({"afterSequence":u64::MAX,"limit":1}))["error"]["code"],
"invalid_cursor"
);
c.ok("reset", json!({}));
let reset = read_log_page(&mut c, Value::Null, 1024);
assert_eq!(&reset["events"].as_array().unwrap()[..native.len()], native);
let after_reset = read_log_page(&mut c, cursor, 1024);
assert!(!after_reset["events"].as_array().unwrap().is_empty());
assert_eq!(after_reset["gap"], false);
assert_eq!(after_reset["logEpoch"], 0);
assert_eq!(after_reset["sessionId"], all["sessionId"]);
c.close();
let mut other = Client::new(&["--stdio"]);
initialize_logs(&mut other);
let fresh = read_log_page(&mut other, Value::Null, 1);
assert_ne!(fresh["sessionId"], all["sessionId"]);
assert_eq!(fresh["events"][0]["sequence"], 0);
assert_eq!(
other.call("get_logs", json!({"afterSequence":all["newestSequence"],"limit":1}))["error"]["code"],
"invalid_cursor"
);
other.close();
}
#[test]
fn timely_readers_outlive_ring_capacity_while_stale_cursors_report_gaps() {
let dir = logging_cart(10, "retention");
let mut c = Client::new(&["--stdio"]);
initialize_logs(&mut c);
boot(&mut c, &dir);
let mut cursor = Value::Null;
let mut count = 0;
let mut saw_eviction = false;
for _ in 0..5 {
assert_eq!(c.ok("advance", json!({"frames":100}))["completed"], 100);
loop {
let page = read_log_page(&mut c, cursor.clone(), 128);
assert_eq!(page["gap"], false);
saw_eviction |= page["overflow"] == true;
for event in page["events"].as_array().unwrap() {
assert_eq!(event["sequence"].as_u64().unwrap(), count);
count += 1;
}
cursor = page["nextAfterSequence"].clone();
if cursor == page["newestSequence"] {
break;
}
}
}
assert!(count > 4096 && saw_eviction);
for stale in [Value::Null, json!(0)] {
let page = read_log_page(&mut c, stale, 1);
assert_eq!(page["gap"], true);
assert_eq!(page["overflow"], true);
assert!(page["oldestSequence"].as_u64().unwrap() > 0);
assert_eq!(page["events"][0]["sequence"], page["oldestSequence"]);
}
let empty = read_log_page(&mut c, cursor.clone(), 1);
assert_eq!(empty["gap"], false);
assert_eq!(empty["overflow"], true);
assert_eq!(empty["nextAfterSequence"], cursor);
c.close();
}
#[test]
fn bounded_log_responses_can_be_retried_without_draining() {
let dir = logging_cart(10, &"x".repeat(200));
let mut c = Client::new(&["--stdio", "--max-response-bytes", "4096"]);
initialize_logs(&mut c);
boot(&mut c, &dir);
c.ok("advance", json!({"frames":5}));
let state = c.ok("get_state", json!({}));
let response = c.call("get_logs", json!({"afterSequence":null,"limit":1024}));
assert_eq!(response["error"]["code"], "response_too_large");
assert!(response.get("result").is_none());
let first = read_log_page(&mut c, Value::Null, 1);
assert_eq!(first["events"][0]["sequence"], 0);
assert_eq!(first, read_log_page(&mut c, Value::Null, 1));
assert_eq!(state, c.ok("get_state", json!({})));
c.close();
}
#[test]
fn log_observation_preserves_existing_guest_length_and_rate_limits() {
let dir = logging_cart(12, &"x".repeat(300));
let mut c = Client::new(&["--stdio"]);
initialize_logs(&mut c);
boot(&mut c, &dir);
c.ok("advance", json!({"frames":1}));
let page = read_log_page(&mut c, Value::Null, 1024);
let app: Vec<_> = page["events"]
.as_array()
.unwrap()
.iter()
.filter(|event| event["source"] == "app")
.collect();
let messages: Vec<_> = app.iter().filter(|event| event["tag"] == 41000).collect();
assert_eq!(messages.len(), 10);
assert!(messages.iter().all(|event| event["message"].as_str().unwrap().len() == 256));
assert_eq!(app.len(), 11);
assert!(app.iter().any(|event| event["tag"] == 0
&& event["level"] == "warn"
&& event["message"] == "App exceeded log limit per frame"));
assert_eq!(page["gap"], false);
assert_eq!(page["overflow"], false);
c.close();
}
#[test]
fn schemas_and_distributed_request_fixtures_are_consistent() {
let request: Value = serde_json::from_str(include_str!(
@@ -614,3 +843,47 @@ fn packaged_installation_smoke() {
c.input.take();
c.wait_exit();
}
#[test]
#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation"]
fn packaged_memcard_reopen_first_frame() {
let installation = PathBuf::from(
std::env::var_os("PROMETEU_PROTOCOL_TEST_INSTALL").expect("set isolated installation path"),
);
memcard_process::presentation_reopen(&installation.join("prometeu"));
}
#[test]
#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation"]
fn packaged_native_log_observation() {
let installation = PathBuf::from(
std::env::var_os("PROMETEU_PROTOCOL_TEST_INSTALL").expect("set isolated installation path"),
);
let cwd = TempDir::new();
let dir = logging_cart(1, "installed native log");
let mut c =
Client::spawn(&installation.join("prometeu"), &["headless", "--stdio"], Some(&cwd.0));
initialize_logs(&mut c);
boot(&mut c, &dir);
c.ok("advance", json!({"frames":1}));
let page = read_log_page(&mut c, Value::Null, 1024);
assert_eq!(page["gap"], false);
assert!(
page["events"]
.as_array()
.unwrap()
.iter()
.any(|event| event["source"] == "app" && event["message"] == "installed native log")
);
let installed_schema: Value = serde_json::from_slice(
&fs::read(installation.join("headless-protocol/response.schema.json")).unwrap(),
)
.unwrap();
jsonschema::validator_for(&installed_schema)
.unwrap()
.validate(&json!({
"type":"response","sessionId":c.hello["sessionId"],"requestId":"logs","result":page,
}))
.unwrap();
c.close();
}
@@ -0,0 +1,412 @@
use super::*;
use prometeu_test_support::memcard_fixture::{MemcardFixture, memcard_program};
fn card(kind: MemcardFixture, version: &str) -> TempDir {
let dir = TempDir::new();
fs::write(dir.0.join("program.pbx"), memcard_program(kind)).unwrap();
fs::write(
dir.0.join("manifest.json"),
serde_json::to_vec(&json!({
"magic":"PMTU","cartridge_version":1,"app_id":4294967295u32,
"title":"Neutral persistence","app_version":version,"app_mode":"Game",
"capabilities":["memcard"],"memcard_slots":1
}))
.unwrap(),
)
.unwrap();
dir
}
fn start_at(binary: &Path) -> Client {
let mut c = Client::spawn(binary, &["headless", "--stdio"], Some(&std::env::temp_dir()));
c.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":1},"requiredCapabilities":["memcard"]}),
);
c
}
fn start() -> Client {
start_at(Path::new(env!("CARGO_BIN_EXE_prometeu")))
}
fn mount(c: &mut Client, path: &Path, action: &str, access: &str) -> Value {
c.ok("memcard_mount", json!({"path":path,"action":action,"access":access}))
}
fn launch(c: &mut Client, dir: &TempDir, choice: &str) {
c.ok("boot", json!({"path":dir.0,"memcardChoice":choice}));
}
fn oracle(c: &mut Client, expected: i64) {
let deadline = Instant::now() + Duration::from_secs(5);
loop {
let advance = c.ok("advance", json!({"frames":1}));
assert_eq!(
advance["stop"],
"completed",
"{advance}; state={}; mem={}; fault={}",
c.ok("get_state", json!({})),
c.ok("get_memcard_state", json!({})),
c.ok("get_fault", json!({}))
);
let state = c.ok("get_state", json!({}));
let top = state["stackTop"].as_array().unwrap();
if top.last().and_then(|v| v["value"].as_str()) == Some(&expected.to_string()) {
return;
}
assert!(Instant::now() < deadline, "oracle {expected} not reached: {state}");
}
}
fn reason(c: &mut Client, command: &str, params: Value, expected: &str) -> Value {
let error = c.call(command, params)["error"].clone();
assert_eq!(error["code"], "memcard_error", "{error}");
assert_eq!(error["details"]["reason"], expected, "{error}");
error["details"]["state"].clone()
}
fn persistence(binary: &Path) {
let root = TempDir::new();
let image = root.0.join("save.pmc");
let write = card(MemcardFixture::Write, "1");
let mut first = start_at(binary);
let mounted = mount(&mut first, &image, "create", "read_write");
assert_eq!(mounted["media"]["cardId"].as_str().unwrap().len(), 32);
launch(&mut first, &write, "persistent");
oracle(&mut first, 101);
let saved = first.ok("get_memcard_state", json!({}));
assert_eq!(saved["request"]["state"], "success");
assert_eq!(saved["request"]["retained"], true);
assert_eq!(saved["dirty"], false);
assert_eq!(saved["io"]["active"], false);
first.close();
let bytes = fs::read(&image).unwrap();
for version in ["1", "2"] {
let read = card(MemcardFixture::Read, version);
let mut next = start_at(binary);
mount(&mut next, &image, "open", "read_write");
launch(&mut next, &read, "persistent");
oracle(&mut next, 201);
assert_eq!(next.ok("get_state", json!({}))["appId"], 4294967295u32);
assert_eq!(
next.ok("get_memcard_state", json!({}))["request"],
Value::Null,
"reader must not submit a save"
);
next.close();
assert!(fs::read(&image).unwrap() == bytes, "readback must not rewrite the image");
}
let read = card(MemcardFixture::Read, "2");
let mut memory = start_at(binary);
mount(&mut memory, &image, "open", "read_only");
reason(&mut memory, "boot", json!({"path":read.0,"memcardChoice":"persistent"}), "read_only");
memory.ok("reset", json!({}));
launch(&mut memory, &read, "memory_existing");
oracle(&mut memory, 201);
assert_eq!(memory.ok("get_memcard_state", json!({}))["session"]["mode"], "memory_only");
memory.close();
assert!(fs::read(&image).unwrap() == bytes);
}
pub(super) fn presentation_reopen(binary: &Path) {
let root = TempDir::new();
let image = root.0.join("presentation-reopen.pmc");
let write = card(MemcardFixture::Write, "1");
let mut writer = start_at(binary);
mount(&mut writer, &image, "create", "read_write");
launch(&mut writer, &write, "persistent");
oracle(&mut writer, 101);
assert_eq!(writer.ok("get_memcard_state", json!({}))["dirty"], false);
writer.close();
for version in ["1", "2"] {
let read = card(MemcardFixture::ReadWithPresentation, version);
let mut reader = start_at(binary);
mount(&mut reader, &image, "open", "read_write");
launch(&mut reader, &read, "persistent");
let booted = reader.ok("get_state", json!({}));
assert_eq!(booted["pc"], 0);
assert_eq!(booted["tickIndex"], 0);
assert_eq!(booted["logicalFrameIndex"], 0);
// Exactly one command owns the first frame; there is no oracle retry.
let advanced = reader.ok("advance", json!({"frames":1}));
assert_eq!(advanced, json!({"requested":1,"completed":1,"stop":"completed"}));
let state = reader.ok("get_state", json!({}));
assert_eq!(state["logicalFrameIndex"], 1);
assert_eq!(state["tickIndex"], 2);
assert_eq!(state["status"], "paused");
assert_eq!(state["appId"], 4294967295u32);
assert_eq!(state["stackTop"].as_array().unwrap().last().unwrap()["value"], "201");
assert_eq!(reader.ok("get_fault", json!({})), Value::Null);
let media = reader.ok("get_memcard_state", json!({}));
assert_eq!(
media["request"],
Value::Null,
"presentation must finish without a payload save"
);
assert_eq!(media["io"]["active"], false);
assert_eq!(media["dirty"], false);
assert_eq!(reader.ok("capture", json!({}))["logicalFrameIndex"], 1);
reader.close();
}
// Preserve the original reader's independent read-without-writing oracle.
let bytes = fs::read(&image).unwrap();
let read = card(MemcardFixture::Read, "2");
let mut reader = start_at(binary);
mount(&mut reader, &image, "open", "read_write");
launch(&mut reader, &read, "persistent");
oracle(&mut reader, 201);
reader.close();
assert_eq!(fs::read(&image).unwrap(), bytes);
}
#[test]
fn memcard_reopen_presentation_completes_exactly_one_first_frame() {
presentation_reopen(Path::new(env!("CARGO_BIN_EXE_prometeu")));
}
#[test]
fn memcard_public_distinct_process_save_readback_and_version_identity() {
persistence(Path::new(env!("CARGO_BIN_EXE_prometeu")));
}
#[test]
#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive"]
fn packaged_memcard_process_persistence() {
let installation = PathBuf::from(
std::env::var_os("PROMETEU_PROTOCOL_TEST_INSTALL").expect("extracted distribution"),
);
persistence(&installation.join("prometeu"));
}
#[test]
fn memcard_dirty_refusal_retains_channel_and_explicit_ram_has_no_save() {
let dirty = card(MemcardFixture::Dirty, "1");
let mut c = start();
launch(&mut c, &dirty, "memory_fresh");
oracle(&mut c, 301);
for command in ["shutdown", "reset"] {
let state = reason(&mut c, command, json!({}), "unsaved_changes");
assert_eq!(state["dirty"], true);
assert_eq!(state["session"]["resident"], true);
assert_eq!(c.ok("get_state", json!({}))["appId"], 4294967295u32);
}
let reset = c.ok("reset", json!({"discardUnsaved":true,"pendingWrites":"cancel"}));
assert_eq!(reset["memcard"]["dirty"], false);
let write = card(MemcardFixture::Write, "1");
launch(&mut c, &write, "memory_fresh");
oracle(&mut c, 104);
let state = c.ok("get_memcard_state", json!({}));
assert_eq!(state["request"]["state"], "memory_only");
assert_eq!(state["dirty"], true);
assert_eq!(state["io"]["active"], false);
assert_eq!(state["media"]["path"], Value::Null);
c.ok("shutdown", json!({"discardUnsaved":true}));
c.wait_exit();
}
#[test]
fn memcard_media_errors_and_negotiation_never_select_a_fallback() {
let root = TempDir::new();
let missing = root.0.join("missing.pmc");
let mut old = Client::new(&["--stdio"]);
old.initialize();
assert_eq!(
old.call("memcard_mount", json!({"path":missing,"action":"create","access":"read_write"}))
["error"]["code"],
"unsupported_capability"
);
assert!(!missing.exists());
old.close();
let mut c = Client::new(&["--stdio"]);
assert_eq!(
c.call(
"initialize",
json!({"protocolVersion":{"major":1,"minor":0},"requiredCapabilities":["memcard"]})
)["error"]["code"],
"incompatible_version"
);
c.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":1},"requiredCapabilities":["memcard"]}),
);
reason(
&mut c,
"memcard_mount",
json!({"path":missing,"action":"open","access":"read_write"}),
"unavailable",
);
assert!(!missing.exists());
let cart = card(MemcardFixture::Write, "1");
reason(&mut c, "boot", json!({"path":cart.0}), "choice_required");
assert_eq!(c.ok("get_state", json!({}))["logicalFrameIndex"], 0);
c.ok("reset", json!({}));
let corrupt = root.0.join("corrupt.pmc");
let mut bytes = vec![0; 5_259_264];
bytes[..8].copy_from_slice(b"PMCARD1\0");
bytes[8] = 1;
fs::write(&corrupt, &bytes).unwrap();
reason(
&mut c,
"memcard_mount",
json!({"path":corrupt,"action":"open","access":"read_write"}),
"corrupt",
);
assert!(fs::read(&corrupt).unwrap() == bytes);
assert_eq!(c.ok("get_memcard_state", json!({}))["session"]["mode"], Value::Null);
c.close();
}
#[cfg(unix)]
#[test]
fn memcard_process_ownership_covers_aliases_readers_and_release() {
let root = TempDir::new();
let image = root.0.join("save.pmc");
let hard = root.0.join("hard.pmc");
let sym = root.0.join("sym.pmc");
let mut owner = start();
mount(&mut owner, &image, "create", "read_write");
fs::hard_link(&image, &hard).unwrap();
std::os::unix::fs::symlink(&image, &sym).unwrap();
let bytes = fs::read(&image).unwrap();
let mut contender = start();
for path in [&image, &hard, &sym] {
for access in ["read_only", "read_write"] {
reason(
&mut contender,
"memcard_mount",
json!({"path":path,"action":"open","access":access}),
"busy",
);
}
}
reason(
&mut contender,
"memcard_mount",
json!({"path":image,"action":"create","access":"read_write"}),
"already_exists",
);
assert!(fs::read(&image).unwrap() == bytes);
owner.ok("memcard_unmount", json!({}));
mount(&mut contender, &image, "open", "read_only");
reason(
&mut owner,
"memcard_mount",
json!({"path":image,"action":"open","access":"read_only"}),
"busy",
);
contender.close();
mount(&mut owner, &image, "open", "read_write");
owner.close();
}
#[cfg(unix)]
#[test]
fn memcard_creation_race_and_process_death_release_real_ownership() {
let root = TempDir::new();
let image = root.0.join("race.pmc");
// Kill the actual storage-owning process rather than its dispatcher parent.
let mut a = Client::new(&["--stdio"]);
let mut b = Client::new(&["--stdio"]);
for c in [&mut a, &mut b] {
c.ok(
"initialize",
json!({"protocolVersion":{"major":1,"minor":1},"requiredCapabilities":["memcard"]}),
);
}
let params = json!({"path":image,"action":"create","access":"read_write"});
let aid = a.send("memcard_mount", params.clone());
let bid = b.send("memcard_mount", params);
let ar = a.response(&aid);
let br = b.response(&bid);
assert_ne!(
ar.get("result").is_some(),
br.get("result").is_some(),
"exactly one creator must win"
);
let (winner, loser, error) =
if ar.get("result").is_some() { (&mut a, &mut b, br) } else { (&mut b, &mut a, ar) };
assert_eq!(error["error"]["details"]["reason"], "already_exists");
let before = fs::read(&image).unwrap();
winner.child.kill().unwrap();
winner.child.wait().unwrap();
mount(loser, &image, "open", "read_write");
loser.close();
assert!(fs::read(&image).unwrap() == before);
}
#[cfg(unix)]
#[test]
fn memcard_access_denial_is_typed_and_does_not_create_or_modify_media() {
use std::os::unix::fs::PermissionsExt;
let root = TempDir::new();
let image = root.0.join("denied.pmc");
let mut creator = start();
mount(&mut creator, &image, "create", "read_write");
creator.close();
let before = fs::read(&image).unwrap();
fs::set_permissions(&image, fs::Permissions::from_mode(0o0)).unwrap();
let mut c = start();
reason(
&mut c,
"memcard_mount",
json!({"path":image,"action":"open","access":"read_write"}),
"access_denied",
);
c.close();
fs::set_permissions(&image, fs::Permissions::from_mode(0o600)).unwrap();
assert!(fs::read(&image).unwrap() == before);
}
#[cfg(unix)]
#[test]
fn desktop_dispatch_forwards_explicit_media_without_interpreting_player_policy() {
use std::os::unix::fs::PermissionsExt;
let installation = TempDir::new();
let dispatcher = installation.0.join("prometeu");
fs::copy(env!("CARGO_BIN_EXE_prometeu"), &dispatcher).unwrap();
let runtime = installation.0.join("prometeu-runtime");
fs::write(&runtime, "#!/bin/sh\nprintf '%s\\n' \"$@\"\n").unwrap();
fs::set_permissions(&runtime, fs::Permissions::from_mode(0o755)).unwrap();
for command in ["run", "debug"] {
let output = Command::new(&dispatcher)
.args([command, "cartridge", "--memcard", "image with spaces.pmc", "--create-memcard"])
.output()
.unwrap();
assert!(output.status.success());
let actual = String::from_utf8(output.stdout).unwrap();
let mut expected = vec![format!("--{command}"), "cartridge".into()];
if command == "debug" {
expected.extend(["--port".into(), "7777".into()]);
}
expected.extend([
"--memcard".into(),
"image with spaces.pmc".into(),
"--create-memcard".into(),
]);
assert_eq!(actual.lines().collect::<Vec<_>>(), expected);
}
assert!(
!Command::new(&dispatcher)
.args(["run", "cartridge", "--create-memcard"])
.output()
.unwrap()
.status
.success()
);
}
#[test]
fn memcard_idle_observation_never_advances_guest_counters() {
let root = TempDir::new();
let image = root.0.join("save.pmc");
let cart = card(MemcardFixture::Write, "1");
let mut c = start();
mount(&mut c, &image, "create", "read_write");
launch(&mut c, &cart, "persistent");
c.ok("advance", json!({"frames":1}));
let before = c.ok("get_state", json!({}));
let deadline = Instant::now() + Duration::from_secs(3);
loop {
let state = c.ok("get_memcard_state", json!({}));
if !state["io"]["active"].as_bool().unwrap() {
assert_eq!(state["request"]["state"], "success");
break;
}
assert!(Instant::now() < deadline);
}
let after = c.ok("get_state", json!({}));
for field in ["pc", "logicalFrameIndex", "tickIndex", "stackTop"] {
assert_eq!(before[field], after[field], "{field}");
}
c.close();
}
@@ -45,5 +45,138 @@
"requestId": "null-params",
"command": "get_state",
"params": null
},
{
"requestId": "bad-mem-8",
"command": "memcard_mount",
"params": {
"path": "x",
"action": "create",
"access": "read_only"
}
},
{
"requestId": "bad-mem-9",
"command": "memcard_mount",
"params": {
"path": "x",
"action": "open"
}
},
{
"requestId": "bad-mem-10",
"command": "boot",
"params": {
"path": "x",
"memcardChoice": null
}
},
{
"requestId": "bad-mem-11",
"command": "boot",
"params": {
"path": "x",
"memcardChoice": "auto"
}
},
{
"requestId": "bad-mem-12",
"command": "shutdown",
"params": {
"discardUnsaved": null
}
},
{
"requestId": "bad-mem-13",
"command": "reset",
"params": {
"pendingWrites": "save"
}
},
{
"requestId": "bad-mem-14",
"command": "get_memcard_state",
"params": {
"anything": true
}
},
{
"requestId": "bad-logs-0",
"command": "get_logs",
"params": {
"limit": 1
}
},
{
"requestId": "bad-logs-1",
"command": "get_logs",
"params": {
"afterSequence": null
}
},
{
"requestId": "bad-logs-2",
"command": "get_logs",
"params": {
"afterSequence": null,
"limit": 0
}
},
{
"requestId": "bad-logs-3",
"command": "get_logs",
"params": {
"afterSequence": null,
"limit": 1025
}
},
{
"requestId": "bad-logs-4",
"command": "get_logs",
"params": {
"afterSequence": null,
"limit": 1.5
}
},
{
"requestId": "bad-logs-5",
"command": "get_logs",
"params": {
"afterSequence": -1,
"limit": 1
}
},
{
"requestId": "bad-logs-6",
"command": "get_logs",
"params": {
"afterSequence": 18446744073709551616,
"limit": 1
}
},
{
"requestId": "bad-logs-7",
"command": "get_logs",
"params": {
"afterSequence": "0",
"limit": 1
}
},
{
"requestId": "bad-logs-8",
"command": "get_logs",
"params": {
"afterSequence": 0.5,
"limit": 1
}
},
{
"requestId": "bad-logs-9",
"command": "get_logs",
"params": {
"afterSequence": null,
"limit": 1,
"filter": "app"
}
}
]
+165 -3
View File
@@ -1,7 +1,7 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://prometeu.dev/headless/v1/request.schema.json",
"title": "Prometeu Headless v1 Request",
"title": "Prometeu Headless v1.2 Request",
"type": "object",
"additionalProperties": false,
"required": [
@@ -65,6 +65,13 @@
"type": "string",
"minLength": 1,
"pattern": "\\S"
},
"memcardChoice": {
"enum": [
"persistent",
"memory_fresh",
"memory_existing"
]
}
}
}
@@ -129,7 +136,19 @@
},
"params": {
"type": "object",
"maxProperties": 0
"properties": {
"discardUnsaved": {
"type": "boolean"
},
"pendingWrites": {
"enum": [
"wait",
"cancel"
]
}
},
"required": [],
"additionalProperties": false
}
}
},
@@ -184,7 +203,150 @@
},
"params": {
"type": "object",
"maxProperties": 0
"properties": {
"discardUnsaved": {
"type": "boolean"
},
"pendingWrites": {
"enum": [
"wait",
"cancel"
]
}
},
"required": [],
"additionalProperties": false
}
}
},
{
"properties": {
"command": {
"const": "memcard_mount"
},
"params": {
"type": "object",
"properties": {
"path": {
"type": "string",
"minLength": 1,
"pattern": "\\S"
},
"action": {
"enum": [
"open",
"create"
]
},
"access": {
"enum": [
"read_write",
"read_only"
]
}
},
"required": [
"path",
"action",
"access"
],
"additionalProperties": false,
"not": {
"properties": {
"action": {
"const": "create"
},
"access": {
"const": "read_only"
}
},
"required": [
"action",
"access"
]
}
}
}
},
{
"properties": {
"command": {
"const": "memcard_unmount"
},
"params": {
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
}
},
{
"properties": {
"command": {
"const": "get_memcard_state"
},
"params": {
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
}
},
{
"properties": {
"command": {
"const": "memcard_reconcile"
},
"params": {
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
}
},
{
"properties": {
"command": {
"const": "memcard_continue_in_memory"
},
"params": {
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
}
},
{
"properties": {
"command": {
"const": "get_logs"
},
"params": {
"type": "object",
"additionalProperties": false,
"required": [
"afterSequence",
"limit"
],
"properties": {
"afterSequence": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 18446744073709551615
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1024
}
}
}
}
}
+111
View File
@@ -74,5 +74,116 @@
"params": {
"targetRequestId": "advance"
}
},
{
"requestId": "mem-11",
"command": "initialize",
"params": {
"protocolVersion": {
"major": 1,
"minor": 1
},
"requiredCapabilities": [
"memcard"
]
}
},
{
"requestId": "mem-12",
"command": "memcard_mount",
"params": {
"path": "/save.pmc",
"action": "open",
"access": "read_only"
}
},
{
"requestId": "mem-13",
"command": "memcard_mount",
"params": {
"path": "/new.pmc",
"action": "create",
"access": "read_write"
}
},
{
"requestId": "mem-14",
"command": "boot",
"params": {
"path": "/cartridge",
"memcardChoice": "memory_existing"
}
},
{
"requestId": "mem-15",
"command": "get_memcard_state",
"params": {}
},
{
"requestId": "mem-16",
"command": "memcard_unmount",
"params": {}
},
{
"requestId": "mem-17",
"command": "memcard_reconcile",
"params": {}
},
{
"requestId": "mem-18",
"command": "memcard_continue_in_memory",
"params": {}
},
{
"requestId": "mem-19",
"command": "reset",
"params": {
"discardUnsaved": true,
"pendingWrites": "cancel"
}
},
{
"requestId": "mem-20",
"command": "shutdown",
"params": {
"pendingWrites": "wait"
}
},
{
"requestId": "logs-init",
"command": "initialize",
"params": {
"protocolVersion": {
"major": 1,
"minor": 2
},
"requiredCapabilities": [
"log_read"
]
}
},
{
"requestId": "logs-first",
"command": "get_logs",
"params": {
"afterSequence": null,
"limit": 1
}
},
{
"requestId": "logs-next",
"command": "get_logs",
"params": {
"afterSequence": 0,
"limit": 1024
}
},
{
"requestId": "logs-u64",
"command": "get_logs",
"params": {
"afterSequence": 18446744073709551615,
"limit": 128
}
}
]
+555 -7
View File
@@ -1,7 +1,7 @@
{
"$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.",
"title": "Prometeu Headless v1.2 Response",
"$comment": "Producer schema for supported 1.0/1.1/1.2 shapes. Consumers permit compatible minor additions; 64-bit identities require lossless decoding.",
"oneOf": [
{
"type": "object",
@@ -167,12 +167,21 @@
"properties": {
"closed": {
"const": true
},
"memcard": {
"$ref": "#/$defs/memcard"
}
},
"required": [
"closed"
],
"additionalProperties": false
},
{
"$ref": "#/$defs/memcard"
},
{
"$ref": "#/$defs/logPage"
}
]
}
@@ -222,7 +231,42 @@
"message",
"details"
],
"additionalProperties": false
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"code": {
"const": "memcard_error"
}
}
},
"then": {
"properties": {
"details": {
"type": "object",
"properties": {
"operation": {
"type": "string"
},
"reason": {
"$ref": "#/$defs/memcardReason"
},
"state": {
"$ref": "#/$defs/memcard"
}
},
"required": [
"operation",
"reason",
"state"
],
"additionalProperties": false
}
}
}
}
]
},
"stack": {
"oneOf": [
@@ -271,8 +315,24 @@
"const": "heap_ref"
},
"value": {
"type": "integer",
"minimum": 0
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"generation": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"index",
"generation"
],
"additionalProperties": false
}
},
"required": [
@@ -347,6 +407,9 @@
"terminated",
"faulted"
]
},
"memcard": {
"$ref": "#/$defs/memcard"
}
},
"required": [
@@ -694,7 +757,8 @@
"faulted",
"terminated",
"canceled",
"host_error"
"host_error",
"action_required"
]
},
"fault": {
@@ -952,7 +1016,7 @@
"DuplicateFn",
"StructuralTypeCycle",
"CaptureIndex",
"CaptureCount",
"CaptureCount",
"CapturedDirectCall",
"RemovedOpcode",
"ArrayCycle",
@@ -1368,6 +1432,490 @@
"additionalProperties": false
}
]
},
"memcardReason": {
"enum": [
"choice_required",
"unavailable",
"corrupt",
"unsupported",
"read_only",
"access_denied",
"already_exists",
"busy",
"no_space",
"out_of_memory",
"invalid_state",
"invalid_range",
"counter_exhausted",
"identity_mismatch",
"unsaved_changes",
"indeterminate",
"restart_required",
"io_error",
"canceled"
]
},
"memcard": {
"type": "object",
"properties": {
"media": {
"type": "object",
"properties": {
"path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cardId": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9a-f]{32}$"
},
{
"type": "null"
}
]
},
"access": {
"anyOf": [
{
"enum": [
"read_write",
"read_only"
]
},
{
"type": "null"
}
]
},
"mountEpoch": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"preparation": {
"enum": [
"idle",
"pending",
"ready",
"failed"
]
},
"error": {
"anyOf": [
{
"$ref": "#/$defs/memcardReason"
},
{
"type": "null"
}
]
},
"recovered": {
"type": "boolean"
},
"degraded": {
"type": "boolean"
},
"writeBlocked": {
"type": "boolean"
}
},
"required": [
"path",
"cardId",
"access",
"mountEpoch",
"preparation",
"error",
"recovered",
"degraded",
"writeBlocked"
],
"additionalProperties": false
},
"session": {
"type": "object",
"properties": {
"appId": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
{
"type": "null"
}
]
},
"choice": {
"anyOf": [
{
"enum": [
"persistent",
"memory_fresh",
"memory_existing"
]
},
{
"type": "null"
}
]
},
"mode": {
"anyOf": [
{
"enum": [
"persistent",
"memory_only"
]
},
{
"type": "null"
}
]
},
"bootAttempted": {
"type": "boolean"
},
"bootPhase": {
"enum": [
"idle",
"loading",
"choice_required",
"preparing",
"running",
"failed"
]
},
"resident": {
"type": "boolean"
},
"actionRequired": {
"type": "boolean"
}
},
"required": [
"appId",
"choice",
"mode",
"bootAttempted",
"bootPhase",
"resident",
"actionRequired"
],
"additionalProperties": false
},
"dirty": {
"type": "boolean"
},
"dirtySlots": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 63
},
"uniqueItems": true,
"maxItems": 64
},
"request": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"state": {
"enum": [
"pending",
"success",
"failure",
"indeterminate",
"memory_only"
]
},
"reason": {
"anyOf": [
{
"$ref": "#/$defs/memcardReason"
},
{
"enum": [
"none",
"timeout"
]
}
]
},
"storageError": {
"anyOf": [
{
"$ref": "#/$defs/memcardReason"
},
{
"type": "null"
}
]
},
"operation": {
"enum": [
"commit",
"presentation"
]
},
"slot": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 63
},
{
"type": "null"
}
]
},
"retained": {
"type": "boolean"
}
},
"required": [
"id",
"state",
"reason",
"storageError",
"operation",
"slot",
"retained"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"io": {
"type": "object",
"properties": {
"active": {
"type": "boolean"
},
"deferred": {
"type": "boolean"
},
"phase": {
"enum": [
"idle",
"preparing",
"deferred",
"queued",
"running",
"returned"
]
}
},
"required": [
"active",
"deferred",
"phase"
],
"additionalProperties": false
},
"recovery": {
"type": "object",
"properties": {
"removalPending": {
"type": "boolean"
},
"reconciliationRequired": {
"type": "boolean"
},
"restartRequired": {
"type": "boolean"
}
},
"required": [
"removalPending",
"reconciliationRequired",
"restartRequired"
],
"additionalProperties": false
}
},
"required": [
"media",
"session",
"dirty",
"dirtySlots",
"request",
"io",
"recovery"
],
"additionalProperties": false
},
"logEvent": {
"type": "object",
"properties": {
"sequence": {
"type": "integer",
"minimum": 0,
"maximum": 18446744073709551615
},
"frame": {
"type": "integer",
"minimum": 0,
"maximum": 18446744073709551615
},
"timestampMs": {
"type": "integer",
"minimum": 0,
"maximum": 18446744073709551615
},
"level": {
"enum": [
"trace",
"debug",
"info",
"warn",
"error"
]
},
"source": {
"enum": [
"pos",
"hub",
"vm",
"fs",
"app"
]
},
"appId": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 4294967295
},
"tag": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"message": {
"type": "string"
}
},
"required": [
"sequence",
"frame",
"timestampMs",
"level",
"source",
"appId",
"tag",
"message"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"source": {
"const": "app"
}
}
},
"then": {
"properties": {
"appId": {
"type": "integer"
}
}
},
"else": {
"properties": {
"appId": {
"type": "null"
}
}
}
}
]
},
"logPage": {
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"minLength": 1
},
"logEpoch": {
"type": "integer",
"minimum": 0,
"maximum": 18446744073709551615
},
"events": {
"type": "array",
"maxItems": 1024,
"items": {
"$ref": "#/$defs/logEvent"
}
},
"oldestSequence": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 18446744073709551615
},
"newestSequence": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 18446744073709551615
},
"nextAfterSequence": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 18446744073709551615
},
"gap": {
"type": "boolean"
},
"overflow": {
"type": "boolean"
}
},
"required": [
"sessionId",
"logEpoch",
"events",
"oldestSequence",
"newestSequence",
"nextAfterSequence",
"gap",
"overflow"
],
"additionalProperties": false
}
}
}
@@ -127,13 +127,14 @@ This evidence does not claim Linux or Intel Mac coverage execution.
The module-tree ownership correction derives from accepted DEC-0059. Its
[current measured evidence](../../../docs/vm-arch/COVERAGE_DOMAINS_CURRENT.json)
preserves the earlier evidence records and restores system/core to 87.71%
without changing the other 14 floors. The fresh local map has 257 source files
and 15 exclusive domains. All domain gates pass: system/fs measures 78.73%,
without changing the other 14 floors. The initial repaired map had 257 source files
and 15 exclusive domains. Its domain gates passed: system/fs measured 78.73%,
system/core 93.69%, asset/bank 90.52% and drivers/core 89.17%.
Ten policy tests cover both generic validity and intended specialized owners.
The existing repository target passes 1,021 tests with 11 ignored; strict
workspace Clippy still reports existing VM diagnostics. Coverage qualification
must not be presented as completed strict workspace qualification.
That initial repository target passed 1,021 tests with 11 ignored while strict
workspace Clippy still reported VM diagnostics. The final strict gate subsequently
passed on the completed source, as recorded in the [runtime quality lesson](../DSC-0064-runtime-branch-quality-review/LSN-0070-runtime-quality-needs-independent-oracles-and-owned-evidence.md).
The current evidence retains the initial ownership comparison separately.
## Takeaways
@@ -110,7 +110,7 @@ data after remount. This establishes priority and retained progress through
observable ordering, rather than a host-specific latency threshold. Separate
regressions cover cancellation, superseding and preload publication.
This refinement follows [DEC-0064](../../workflow/decisions/DEC-0064-q7-share-asset-decoding-validation-and-conformance.md).
This refinement follows DEC-0064, summarized in the [runtime quality lesson](../DSC-0064-runtime-branch-quality-review/LSN-0070-runtime-quality-needs-independent-oracles-and-owned-evidence.md).
The published contract is [Asset Management](../../../docs/specs/runtime/15-asset-management.md#43-decoding-validation-and-physical-payload-completeness).
The ordering fixture uses the persistent transaction protocol with a deterministic
storage backend; file-host latency measurements remain separate evidence.
@@ -16,7 +16,7 @@ DSC-0052; the workflow scaffolding is disposable, while these explanations and t
[discussion index](../../index.ndjson) persist.
The normative references are [function values and closures](../../../docs/specs/runtime/02b-vm-function-values-and-closures.md),
[Registry and PBX v1](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md),
[Registry and PBX v1](../../../docs/specs/runtime/02c-program-registry-and-pbx-v0.md),
[frame continuation](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md)
and [memory ownership](../../../docs/specs/runtime/03-memory-stack-heap-and-allocation.md).
The earlier [Registry lesson](../DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md)
@@ -54,7 +54,7 @@ Interpolation follows the same selected boundary. A one-shot interpolates into t
The correction derives from DEC-0060 in DSC-0064. Synthetic regressions cover exact PCM, fractional seams and tails, incomplete and invalid markers, empty samples, rate conversion, multiple wraps and extreme finite pitch. These tests exercise the existing delivery and control paths without establishing new device timing or reclamation guarantees. The [sample contract](../../../docs/specs/runtime/05-audio-peripheral.md#6-samples-interpolation-and-ownership) remains normative.
Local macOS/aarch64 qualification on 2026-10-14 passed 19 host audio tests (one physical-device test ignored), nine driver audio tests and ten runtime audio tests. The existing `make ci-domains` target passed with 1,027 tests passed, zero failed and 11 ignored, including all 15 domain gates. Strict all-target/all-feature Clippy passed for the desktop host. Strict workspace qualification remains pending because of existing VM lint errors; this correction does not claim to resolve the repository-wide quality gate.
Local macOS/aarch64 qualification on 2026-10-14 passed 19 host audio tests (one physical-device test ignored), nine driver audio tests and ten runtime audio tests. The existing `make ci-domains` target passed with 1,027 tests passed, zero failed and 11 ignored, including all 15 domain gates. Strict all-target/all-feature Clippy passed for the desktop host. That initial run preceded repair of existing VM lint errors. The later strict shared gate passed on the completed source; see the [runtime quality lesson](../DSC-0064-runtime-branch-quality-review/LSN-0070-runtime-quality-needs-independent-oracles-and-owned-evidence.md) for final acceptance and complementary production decode/save pressure evidence.
### Original Voice-Control Qualification
@@ -18,7 +18,7 @@ an eight-hour endurance test. This lesson preserves the decision and its revisio
after workflow cleanup; the [discussion index](../../index.ndjson) tracks closure.
Normative references remain [memory and GC](../../../docs/specs/runtime/03-memory-stack-heap-and-allocation.md),
[Registry/PBX](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md),
[Registry/PBX](../../../docs/specs/runtime/02c-program-registry-and-pbx-v0.md),
[typed callables](../../../docs/specs/runtime/02b-vm-function-values-and-closures.md)
and [single-context lifecycle](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md).
The [published evidence report](../../../docs/vm-arch/resource-stability-qualification.md)
@@ -16,7 +16,7 @@ closed that delivery. Coordinated production activation was explicitly received
as future-plan suggestions in AGD-0055. Closing this delivery does not mean the
old production loader or version-0 example generators were migrated.
The normative reference is [Program Registry and PBX v1](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md).
The normative reference is [Program Registry and PBX v1](../../../docs/specs/runtime/02c-program-registry-and-pbx-v0.md).
The [permanent handoff](../../../docs/vm-arch/registry-producer-handoff.md) records
delivered APIs, producer oracles and pending integration ownership. This lesson
explains published mechanisms; it does not define callable/capture policy.
@@ -134,8 +134,8 @@ quotas. This is boundary-work evidence, not a claim of faster game frames.
Synthetic collision keys and work-limit tests complement real-address timings;
allocator-selected address order is not a stable test oracle across loads.
This implementation follows [DEC-0065](../../workflow/decisions/DEC-0065-q8-index-string-provenance-within-existing-quotas.md).
The [published ownership contract](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md#memory-ownership-and-quotas)
This implementation follows DEC-0065, summarized in the [runtime quality lesson](../DSC-0064-runtime-branch-quality-review/LSN-0070-runtime-quality-needs-independent-oracles-and-owned-evidence.md).
The [published ownership contract](../../../docs/specs/runtime/02c-program-registry-and-pbx-v0.md#memory-ownership-and-quotas)
remains normative; native import, snapshot retention and typed storage tests
verify the same owner lifetimes through the new indices.
@@ -18,7 +18,7 @@ meaning. A game's local slot index remains stable while physical blocks rotate.
The historical source was accepted decision DEC-0055, executed through PLN-0186
for AGD-0064. Those workflow artifacts are disposable; the normative references
are [Save Memory and MEMCARD](../../../docs/specs/runtime/08-save-memory-and-memcard.md),
[Registry](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md),
[Registry](../../../docs/specs/runtime/02c-program-registry-and-pbx-v0.md),
[Host ABI](../../../docs/specs/runtime/16-host-abi-and-syscalls.md) and
[producer handoff](../../../docs/vm-arch/registry-producer-handoff.md).
@@ -12,7 +12,7 @@ Optional BeforePause and BeforeResume functions now run around the existing OS
suspension and reactivation transitions. The implementation derives from accepted
DEC-0054 and PLN-0185, originating in AGD-0065 / DSC-0062. These workflow records
are disposable; the durable contracts are
[Registry roles](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md#optional-lifecycle-roles)
[Registry roles](../../../docs/specs/runtime/02c-program-registry-and-pbx-v0.md#optional-lifecycle-roles)
and [controlled lifecycle calls](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md#controlled-lifecycle-calls).
## Binding Describes a Runtime Event, Not a Frontend Construct
@@ -0,0 +1,122 @@
---
id: LSN-0070
ticket: runtime-branch-quality-review
title: Runtime Quality Needs Independent Oracles and Owned Evidence
created: 2026-10-14
tags: [quality, runtime, ownership, validation]
---
## Context
A branch review found eight gaps spanning deadline reasons, coverage ownership,
one-shot audio, recurring VM allocations, callback reclamation, CI enforcement,
asset decoder parity and string provenance lookup. Accepted decisions DEC-0058
through DEC-0065 were executed by PLN-0189 through PLN-0196. This lesson preserves
the resulting reasoning after removal of those workflow artifacts; the linked
published contracts remain normative.
The common failure mode was evidence that proved a nearby property while leaving
the intended property unchecked. A callback can avoid locks while still freeing
memory. Two decoders can agree on output while accepting the same malformed file.
A coverage percentage can rise because ownership moved, without any new test.
A fast lookup can hide expensive construction and uncharged metadata.
## Key Decisions
### Observe the boundary where the guarantee becomes true
The [memcard contract](../../../docs/specs/runtime/08-save-memory-and-memcard.md)
keeps the first deadline escalation reason stable while distinguishing durable
completion from pending or failed work. Fake-clock boundary tests and explicit
publication ordering make those distinctions observable without sleeping.
The [audio contract](../../../docs/specs/runtime/05-audio-peripheral.md) distinguishes
one-shot completion from looping and logical inactivity from physical ownership.
A finished voice may become silent before its sample can be reclaimed. Two bounded
return packets move sample and vector owners to host service; pool exhaustion
retains bounded ownership and defers delivery. Count both allocations and frees
inside the callback, then independently prove eventual owner release outside it.
### Shared mechanics still need independent expected results
The [asset contract](../../../docs/specs/runtime/15-asset-management.md) uses common
metadata validation and decoding mechanics for synchronous and incremental paths.
Conformance checks include independently specified pixels, palette bytes and PCM,
plus malformed metadata and physically truncated payloads. Agreement between two
entry points is useful, but cannot by itself establish correctness.
The real production decoder/save ordering fixture pauses at a safe decode step,
queues persistent work and checks writes and synchronization before decode resumes.
That deterministic ordering oracle is stronger evidence of priority than a latency
threshold on one host. Host latency remains a separate observation.
### Move cost deliberately and account for the destination
Recurring VM stack/return work reuses capacity after warmup; release allocator
checks measure the execution region separately from setup. String provenance uses
image and session indices under existing ownership quotas. Index metadata and
construction cost are charged and measured, including collision and refusal paths.
See the [Registry contract](../../../docs/specs/runtime/02c-program-registry-and-pbx-v0.md)
and [provenance qualification](../../../docs/vm-arch/string-provenance-qualification.md).
Lookup improvements do not establish faster game frames or cheaper construction.
### The repository owns acceptance and measurement identity
The [coverage policy](../../../docs/vm-arch/COVERAGE_DOMAINS.md) assigns each source
to exactly one domain, includes module descendants, and keeps acceptance floors
independent of observed percentages. Ownership repair and behavioral improvement
must be evaluated separately against the same report before comparing fresh runs.
The shared strict gate records source/config identity, preserves command failures,
removes stale reports and publishes available evidence even when a stage fails.
Local execution and CI call the same target. A successful focused test does not
replace the full gate; a successful local gate does not certify an unexecuted OS.
## Published Evidence and Its Limits
The final source commit is `3f9d2355462d3b5675f5edc6e488ab325eb024d8`, with Rust
fingerprint `309a069f8b0560d1e9d1f9f4e011b709c89729383aeacd100c8c2ff5c3cff28d`.
On macOS/aarch64 with rustc 1.98.1, all twelve `make ci-domains` stages passed:
1,060 ordinary tests, five socket tests, three runner tests and all fifteen fixed
coverage floors. Thirteen ordinary tests were ignored. The fresh coverage replay
also passed 1,060 tests; those are repeated tests, not additional unique cases.
[Current coverage evidence](../../../docs/vm-arch/COVERAGE_DOMAINS_CURRENT.json)
retains the earlier ownership-repair comparison and identifies the final corpus.
The ten focused coverage tests and two release/all-feature VM allocation tests
passed again during closure without source changes.
[Audio qualification](../../../docs/vm-arch/audio-callback-qualification.md) retains
the named physical-device smoke and the initial device failures. Complementary
release measurement ran 1,000 sixteen-voice callbacks while a separate process
repeated the real production decoder/FileMemcard fixture fourteen times. Callback
p50/p95/p99/max were 14.542/97.667/399.041/1,070.708 microseconds against a nominal
5,333.333-microsecond period. Callback allocation/free counts were both zero;
sample owners went from sixteen to zero after teardown. The
[measurement record](../../../docs/vm-arch/audio-production-pressure-qualification.json)
records overlapping process intervals, environment and individual pressure rounds.
This is host-concurrent pressure evidence, not same-process console integration
or a worst-case latency guarantee. Each pressure round alternates twenty production
loads and durable 64-KiB commits; the separate deterministic fixture establishes
save preemption during decoding. Physical audio, synthetic timing, allocator
counts and save ordering answer different questions and retain separate scopes.
No Linux/remote CI, human listening assessment, long-duration soak or gameplay
speedup is claimed by this closure.
## Related Domain Lessons
- [Save publication and resource ownership](../DSC-0061-memcard-fixed-slots-v1/LSN-0067-save-publication-and-resource-ownership-are-separate.md).
- [Repository-owned domain gates](../DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md).
- [Audio delivery and lifecycle](../DSC-0055-guest-audio-voice-control/LSN-0069-audio-admission-needs-a-delivery-boundary-and-independent-lifecycle-control.md).
- [Materialization and recurring VM cost](../DSC-0014-perf-vm-allocation-and-copy-pressure/LSN-0035-first-materialization-is-not-the-same-as-hot-path-copy-pressure.md).
- [Serial async lanes](../DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md).
- [Registry boundaries and owned values](../DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md).
## Pitfalls and Takeaways
- Test the promised boundary with an independent oracle, including failure paths.
- Separate admission, execution, publication and reclamation when reasoning about cost.
- Preserve owner counts and quota accounting when replacing scans or moving work.
- Bind acceptance evidence to source/config fingerprints, not merely a nearby commit.
- Close deferred gates on the final source, while keeping environmental limits explicit.
- Preserve reusable reasoning and durable measurements; discard completed workflow scaffolding.
@@ -0,0 +1,135 @@
---
id: LSN-0072
ticket: vm-storage-publication-neutrality
title: Primitives Need Independent Semantics and Failed Attempts Still Cost Work
created: 2026-10-23
tags: [vm, isa, storage, atomicity, ownership, cycles, frontend-neutrality]
---
## Context and Published Result
DEC-0067, accepted from AGD-0068 and implemented by PLN-0198, reduced the storage
ISA after reviewing additions requested by a consumer. The runtime removed
INDEX_GUARD (0xA7), ARRAY_CHECK_LENGTH (0xA8), STORAGE_PUBLISH (0xAA) and
FIELDS_PUBLISH (0xAB). ARRAY_COPY remains at 0xA9 and ARRAY_LEN at 0xA4. The
supported encodings and fault/cost contracts live in the
[canonical ISA](../../../docs/specs/runtime/02-vm-instruction-set.md#typed-array-range-copy),
[time model](../../../docs/specs/runtime/01-time-model-and-cycles.md#collection-attempt-charging)
and [memory specification](../../../docs/specs/runtime/03-memory-stack-heap-and-allocation.md#prepared-array-range-copy).
The [producer handoff](../../../docs/vm-arch/collection-producer-handoff.md) and
[qualification record](../../../docs/vm-arch/STORAGE_QUALIFICATION.md) describe
integration obligations and executable evidence. This lesson explains the result;
it does not establish a separate contract.
## A Consumer Request Is Evidence, Not a Permanent ISA Commitment
A real compiler or SDK can expose missing capabilities. That makes its use cases
valuable evidence, but delivery in one consumer does not make every added helper
an enduring machine primitive. Re-evaluate the operation's own semantics, failure
boundary and reuse across representations. Backward compatibility was explicitly
not a requirement for this revision.
The removed guards expressed logical limits and allocation-free validation that
the producer can organize through its existing control flow. ARRAY_LEN remains
useful as a direct physical query; removing logical helpers does not remove
physical validation from allocation and array access. A collection's logical
length can differ from its backing array's physical length.
The removed publications coupled several mutations into fixed or schema-selected
batches. Supporting one current collection algorithm did not justify maintaining
those compound machine guarantees. ARRAY_COPY survives because strict typed
range transfer, snapshot overlap and complete-group ownership provide independent
machine semantics without identifying a source collection.
Learning from Java, C#, Rust and Go means examining principles and tradeoffs,
not selecting a mandatory frontend. JavaScript and Lua were philosophical tests
of the architecture's independence. No engine, frontend or object from either
language was needed to implement or qualify this change.
## An Instruction Boundary Does Not Roll Back a Source Operation
ARRAY_COPY starts with five prepared operands. It reserves full scratch, captures
all source groups and then commits prevalidated writes. Failure preserves its
operands and destinations while releasing provisional scratch. Earlier source
calculations, allocations or callbacks keep their effects.
Snapshot preparation explains overlap: when copying indices 0..3 to 1..4 of the
same array, the source sequence is captured before any destination store. Native
String owners, HeapRefs, Dynamic tags/boxes and Trait groups travel together.
Splitting carriers or cloning payload graphs would change the operation.
A series of individually validated STRUCT_SET or ARRAY_SET instructions does not
inherit a shared rollback boundary. A consumer that previously relied on a batch
must establish its invariant through an appropriate algorithm/representation or
explicitly revise its operational guarantee. A renamed helper emitting sequential
stores does not prove equivalence. Consumer migration remains an independent
delivery; it does not block publication of the runtime's own supported surface.
## Select Cost Early Without Selecting the First Fault Early
Let N be count and W the immutable Registry element-slot width. ARRAY_COPY charges
4+2*N*W when all five temporary operands are available and N is an exact Int64 in
0..u32::MAX. For ten one-slot elements the attempt costs 24 even if a receiver is
null, a range is invalid or scratch reservation fails. That charge records the
planned work of an admitted attempt, independently of published state.
Inspecting N early only selects cost. It does not move an invalid count ahead of
an invalid receiver in ordinary fault precedence. If count has a wrong carrier or
is outside the calculable domain, charge base 4 and follow normal validation.
With null source and negative count, the receiver fault still wins. Frame locals
must never stand in for missing temporary operands.
Zero count still validates both receivers and ranges and costs 4. Identity and
aliasing do not discount a copy. Checked total-cost overflow has its explicit
base-charge/SizeOverflow path; synthetic widths test this defense without claiming
that such widths are admitted guest layouts.
This extends the reasoning in
[Collection Attempts Preserve Groups and Charge Work Before Publication](../DSC-0051-game-state-collections-and-objects/LSN-0060-collection-attempts-preserve-groups-and-charge-work-before-publication.md):
unchanged state and consumed cycles are compatible outcomes. Positive budget
admits an entire instruction with overshoot; zero admits none. A failed attempt
reports its trap and charged cycles, but contributes no successful target step.
## Remove Support at Every Boundary
Removing dispatch alone leaves assemblers, decoder metadata or dead-code
verification advertising obsolete capabilities. This implementation removes all
four variants, encodings, metadata, assembler/disassembler cases, Registry effects,
verifier paths and executors. Unsupported instruction positions reject during
admission, including after HALT. The same byte values inside a legitimate immediate
remain data, so a raw byte search is not an admission rule.
The retained copy now has a dedicated executor. Tests inherited from the compound
publication paths were migrated to copy-specific overlap, quota and group cases.
That preserves relevant evidence while eliminating tests of obsolete successes.
## Evidence and Practical Limits
The qualification record identifies the source baseline and working-tree
fingerprints rather than attributing uncommitted code to a new provider SHA.
Tests use independent literal encodings and serialized neutral PBX, the production
loader/VM, exact cycle/fault oracles, quota and allocation-failure injection,
late invalid source groups, overlap in both directions, frame temporary floors,
zero/positive budgets, and native/guest owners across collection.
Internal state injection is labeled separately from admitted-program evidence.
The checked-cost overflow test uses synthetic widths; it does not relax Registry
layout rules. Test-only cleanup also shares the collection fixture module and
removes redundant Copy clones to satisfy Clippy without changing identity/hash
semantics. Full gate results and remaining ignored tests are recorded with their
actual execution status.
These results do not establish the Studio SDK's migration, its old compound
atomicity guarantees, new collection algorithms, or JavaScript/Lua conformance.
Those claims require the consumer's own accepted contract and new evidence on
an identified provider.
## Pitfalls
- Keeping a primitive solely because a delivered SDK already emits it.
- Removing a logical guard while accidentally weakening physical bounds checks.
- Charging only after receiver/range validation, which changes failed-attempt cost.
- Letting cost inspection reorder value faults or read below the temporary floor.
- Dropping ownership/overlap coverage when deleting the old compound executor.
- Treating stores as a transaction, or claiming old consumer evidence for a new provider.
- Searching arbitrary payload bytes instead of actual instruction boundaries.
@@ -0,0 +1,146 @@
---
id: LSN-0071
ticket: vm-identity-and-value-hashing
title: Identity domains and borrowed intrinsic invocation
created: 2026-10-23
tags: [vm, identity, hashing, values, compiler]
---
## Context
The runtime needed stable identity queries and scalar/content hashing while
preserving typed values, faults, owners and execution accounting. Existing
Host intrinsics buffered arguments/results and exposed mutable context. That
path could not establish the required no-scratch/no-guest-allocation contract
by adding a purity flag alone.
The executed decision was DEC-0066, originating in AGD-0069; PLN-0197 delivered
the independent runtime provider. Their permanent lifecycle provenance is in
[the discussion index](../../index.ndjson). Workflow control artifacts are
removed after completion. Published authority is the
[canonical identity/hash specification](../../../docs/specs/runtime/02f-vm-identity-and-value-hashing.md),
with the [qualification record](../../../docs/vm-arch/IDENTITY_HASHING_QUALIFICATION.md)
and [producer handoff](../../../docs/vm-arch/identity-hashing-producer-handoff.md).
This lesson explains the published design; it does not replace its contract.
## Key decisions
### Equality belongs to a selected domain
**What:** The VM provides exact reference identity plus separate Int64, Float
and String hashes. SDK/producer policy selects equality, numeric canonicalization,
component composition and optional/Dynamic behavior.
**Why:** Sharing a physical carrier does not establish a semantic equality domain.
Two Trait views can share one receiver even with different implementation IDs;
two closures with identical code/captures still have separate instance identity.
Conversely, separately owned Strings can share content and therefore a content
hash. A universal equality layer would silently choose language policy.
**Trade-offs:** Producers need coherent wrappers and composition. They gain
explicit control without duplicating the machine's handle validation or hash
algorithm. A hypothetical Lua consumer was a design stress test; no Lua frontend
was implemented or needed for provider qualification.
### Improve intrinsic invocation with an executable profile
**What:** borrowed_inline_v1 borrows the original stack arguments, computes into
fixed native output slots, validates complete output and commits once. Its
handler receives no mutable HostContext or VM access. Invocation/scratch/context
metadata derive from the handler representation, preventing inconsistent claims.
The new profile is shared infrastructure, not a hash-namespace branch.
**Why:** deterministic, allocation and mutation flags describe separate concerns.
A deterministic function can still allocate scratch or mutate seeded state.
Purity metadata cannot make a buffered callback transactional. The invocation
interface and commit protocol must enforce the resource/ownership story.
**Trade-offs:** The profile deliberately supports bounded output replacement.
Unsupported capacities, ABI layouts and effect/cost combinations fail rather
than falling back to dynamic storage. Existing Host and VM-owned Random handlers
retain their established contract; they were not broadly migrated.
### Fault order and charging are part of semantics
**What:** Charge from safe carrier/Registry metadata before validation; preserve
both groups until complete validation and computation succeed. Validate left
before right even when a result seems obvious. String's known byte length is
charged before ownership refusal; overflow charges base and traps.
**Why:** Early false/null results can conceal malformed or stale references.
Popping operands before work makes failures change roots or drop String owners.
Partial fuel checks or duplicate generic INTRINSIC costs change deterministic
execution traces and compiler optimization obligations.
**Trade-offs:** An admitted instruction can overshoot positive fuel, and invalid
long Strings still pay traversal-sized virtual cost without being traversed.
The contract makes that explicit and testable. Zero fuel executes nothing.
## Patterns and algorithms
Reference identity is validated index plus generation, serialized as two LE u32s
for XXH64 seed zero. The hash excludes fields, captures, generator state, trait
metadata and native addresses. It is stable for a live object but creates no
root or persistent cross-session identity. GC may collect an object while an
Int64 hash remains; generation advancement still invalidates old handles.
Scalar hashing uses explicit LE messages. Float hashes binary64 bits, with both
zeros canonicalized, and rejects non-finite values. It never performs numerical
Float-to-integer conversion. String uses exact UTF-8 bytes, including NUL;
accepted absence returns zero directly and empty String hashes the empty message.
Signed Int64 carries the unchanged unsigned digest bits.
Schema 2 appends capability, nullability and cost fields to the original 18 CSV
columns. Runtime descriptors generate the catalog, validate consistency and feed
static per-entry nullability. Known null for hash.string does not relax older
String entries. Explicit legacy profile tokens document the existing contract
without claiming the bounded profile's guarantees for every intrinsic.
## Independent evidence
The Rust algorithm agrees with 118 vectors generated from the pinned official C
XXH64 reference. Raw instruction bytes are checked independently of round-trip
assembly. Serialized PBX exercises admission and actual VM dispatch; private
fault injection reaches stale handles, NaN payloads and deliberately broken
handlers that production admission prevents.
Ten warmed instruction regions each ran 1,000 iterations without native
allocation/deallocation or guest heap allocation. Resource refusal tests preserve
operands/owners/accounting. GC/reuse tests distinguish live identity, stale
identity and hashes that do not root their source. Distribution tests use reduced
buckets and deliberately observe collisions without substituting hash equality
for reference equality.
The default bytecode/VM suites passed 453 tests; the VM diagnostic suite passed
401; quality/layer checks passed 19; selected release suites passed 12. Local
target/toolchain, existing ignored tests, source fingerprints, catalog/constant
checks and exact commands are retained in the qualification record. Those
results do not assert cross-target or source frontend integration.
## Pitfalls
- Inferring no scratch, no context or purity from deterministic loses independent
capability information. Stateful Random is reproducible but still mutates.
- Comparing only a Trait receiver without validating its implementation pair
accepts malformed views; treating implementation zero as absence breaks valid views.
- Reusing physical HeapRef rules for String, Dynamic or arbitrary builtins expands
semantic domains without a contract. Eligibility needs its own precise predicate.
- Canonical stack null and HeapRef(0,0) have different validation behavior.
- Numerical conversion of Float, host-endian messages or native hashing defaults
breaks reproducible bit-level results.
- Allocation-free algorithms can still hide argument/result buffers in generic
invocation. Count the real instruction region, including reallocations.
- Updating a catalog mirror alone does not migrate the compiler or installed SDK.
Metadata, IR, emission, pinning, resources and normal/optimized source evidence
each need a named consumer acceptance target.
## Takeaways
Make the safe execution profile an implementation capability and validate its
metadata. Preserve original operands as roots through the last fallible step.
Separate identity, content and language equality policy. Qualify encoding,
algorithm, invocation, ownership and scheduling with independent evidence.
The runtime provider is complete independently of Studio source integration,
Set/Map, storage publication and future frontends. Consumer obligations remain
concrete handoff targets rather than an unbounded extension of this delivery.
@@ -0,0 +1,128 @@
---
id: LSN-0073
ticket: memcard-public-host-persistence
title: Public persistence is a process and ownership contract
created: 2026-10-30
tags: [memcard, persistence, headless, host, ownership]
---
## Context
The runtime now exposes media preparation, three explicit boot choices, native
observation, protected teardown and same-media recovery through its installed
headless protocol. The file backend has a single owner across compatible hosts,
including read-only opens. Runtime tests remain neutral PBX/ABI programs and do
not depend on a source-language frontend or another application's build.
Historical source: accepted decision DEC-0068, executed through PLN-0199 from
AGD-0071. Their workflow files are disposable. The published contracts are
[Save Memory and MEMCARD](../../../docs/specs/runtime/08-save-memory-and-memcard.md)
and [Headless Automation](../../../docs/specs/runtime/11a-headless-automation-protocol.md#memcard-controls).
This lesson explains those published results rather than defining new behavior.
## A native API is not an installed integration surface
Injecting storage into an in-process host is useful for controlled faults, but
does not establish that a consumer can configure the distributed executable.
Media preparation and player choice therefore became explicit operations of
the existing transport. The negotiated minor and capability identify support;
an executable version string alone does not. A client without the extension
continues using the original non-memcard shapes.
Preparing media separately from boot lets missing, corrupt, read-only and busy
files produce native domain errors before game initialization. Opening is not
creation. A persistent choice does not turn into fresh RAM after a failure.
These distinctions belong to the provider so every consumer sees the same
storage and admission policy.
## Result knowledge, RAM state and resource lifetime are separate
A retained terminal result is a statement about an attempt. It is not evidence
that a worker still owns the source, and absence of a mounted backend is not
evidence that the worker is active. In particular, reacquisition can fail after
the previous IO safely returned. An explicit worker-return observation separates
that case from an outstanding operation.
This distinction also matters after watchdog escalation. A late completion can
provide the original worker error and return its resources without rewriting the
terminal result already exposed to the game. Same-card reconciliation keeps that
original result available until guest release. It does not consume the result
to make media operations easier. Controlled tests exercise both a refusal before
publication and an uncertain attempt inside metadata publication.
Ending a session does not establish media health. An installed image with an
indeterminate publication stays write-blocked after reset, and a new persistent
admission cannot bypass the need for explicit revalidation.
RAM has its own state. A memory-only commit completes without a durability claim
and leaves modified RAM dirty. Teardown first waits for or cancels already
admitted IO, then reevaluates RAM. It can avoid an unnecessary discard prompt if
the save completes cleanly during that wait. If dirty data remains, refusal keeps
the process, session and channel available for a later explicit decision.
## A process boundary makes file ownership visible
Serializing one runtime's transactions does not exclude another process that
opened the same image from making decisions against an older map. The shared
file backend now attaches an exclusive OS lock to the open file, including
read-only access. Hardlink and symlink tests exercise identity rather than path
string equality. Creation locks its new file before publishing a non-replacing
name. Resource ownership continues through cancellation, result release and
blocked teardown until IO actually ceases or the owner process dies.
Recovery has to account for the lock held by the same host. Opening another
descriptor before relinquishing the safely quiescent backend can conflict with
that host's own lock. The recovery boundary transfers ownership, validates the
expected card identity before mutation and preserves local RAM on failure.
The selected path containing a different card is an identity error, not implicit
permission to register or load a replacement game record.
## Deterministic guest progress and asynchronous observation coexist
The headless owner polls native IO between commands. Completion and deadlines
can become observable while guest PC, stack, tick and frame remain unchanged.
Driving IO does not require inventing game frames or restarting initialization.
Two integration details were exposed by the first real memcard frame. A
controlled bootstrap slice can consume the runtime's step marker before a logical
frame closes; the host retains its requested advancement until the frame or an
explicit stop boundary. Also, a host dialog can reuse frame ID zero. Its producer
is excluded from canonical game capture, so an initial game frame is neither
mistaken for the dialog nor rejected merely for sharing that numeric ID.
A resident game waiting for external media action is paused rather than
terminated. Recovery preserves its continuation and admitted RAM. It does not
call bootstrap again. Explicit continuation in RAM uses the existing SO choice
and remains distinct from restarting a game with fresh memory.
## A readback oracle should be unable to save its own answer
The neutral writer stores bytes 0, 127, 128 and 255 and exposes the guest query
SUCCESS through public state inspection. A different process runs a reader with
no save or presentation import. It checks each prior byte, traps on a wrong or
missing payload and exposes a separate readback result. The entire image remains
unchanged by that reader. A further process changes app_version while retaining
the same uint32 app_id. Read-only loading into RAM is qualified independently.
The same process oracle runs through the public dispatcher from another working
directory against a real extracted archive produced by the distribution workflow.
That establishes something stronger than reopening a native object in one test
process or copying target/debug binaries into a directory labeled as an install.
Archive, binary, schema and source fingerprints identify the evidence precisely
even while the implementation is an uncommitted checkout.
## Evidence and ownership boundary
[Qualification evidence](evidence/summary.json) records 1,107 passing workspace
tests, 73 passing release tests, strict formatter/clippy checks, and both extracted
distribution tests passing. The generic workspace gate has 14 ignored manual or
installation tests; the two installation tests were separately run successfully.
Execution was qualified on macOS arm64. This is not a physical power-cut,
cross-target or storage-latency qualification.
The runtime delivery prepares a supported contract and its independent evidence.
No consumer source, configuration, SDK, workflow or tests were changed or run.
Future client/frontend integration uses the published surface and has its own
acceptance criteria. Its completion is neither claimed nor required to close
this provider work. This boundary prevents a provider plan from absorbing another
domain merely because that consumer originally discovered the missing interface.
@@ -0,0 +1,6 @@
Checking prometeu-system v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system)
Checking prometeu-firmware v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware)
Checking prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Checking prometeu-host-desktop-winit v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit)
Checking prometeu-cli v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/tools/prometeu-cli)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 5.02s
@@ -0,0 +1,44 @@
Generated VERSION.txt with version 0.1.0
Preparing dist-staging...
Preparing dist-staging/stable (existing archives are retained)...
building artifacts:
prometeu-cli-aarch64-apple-darwin.zip
prometeu-cli-aarch64-apple-darwin.zip.sha256
prometeu-host-desktop-winit-aarch64-apple-darwin.zip
prometeu-host-desktop-winit-aarch64-apple-darwin.zip.sha256
pbxgen-dummy-boy-aarch64-apple-darwin.zip
pbxgen-dummy-boy-aarch64-apple-darwin.zip.sha256
pbxgen-stress-aarch64-apple-darwin.zip
pbxgen-stress-aarch64-apple-darwin.zip.sha256
building aarch64-apple-darwin target, using cargo profile dist --workspace)
Compiling prometeu-system v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system)
Compiling prometeu-firmware v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware)
Compiling prometeu-host-desktop-winit v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit)
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Compiling prometeu-cli v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/tools/prometeu-cli)
Finished `dist` profile [optimized] target(s) in 39.63s
announcing v0.1.0
prometeu-cli 0.1.0
/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-cli-aarch64-apple-darwin.zip
[bin] prometeu
[bin] prometeu-headless
[bin] prometeu-runtime
[misc] 11a-headless-automation-protocol.md, LICENSE, README.md, headless-protocol
[checksum] /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-cli-aarch64-apple-darwin.zip.sha256
prometeu-host-desktop-winit 0.1.0
/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-host-desktop-winit-aarch64-apple-darwin.zip
[bin] prometeu-host-desktop-winit
[misc] LICENSE, README.md, VERSION.txt
[checksum] /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-host-desktop-winit-aarch64-apple-darwin.zip.sha256
pbxgen-dummy-boy 0.1.0
/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/pbxgen-dummy-boy-aarch64-apple-darwin.zip
[bin] pbxgen-dummy-boy
[misc] LICENSE, README.md
[checksum] /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/pbxgen-dummy-boy-aarch64-apple-darwin.zip.sha256
pbxgen-stress 0.1.0
/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/pbxgen-stress-aarch64-apple-darwin.zip
[bin] pbxgen-stress
[misc] LICENSE, README.md
[checksum] /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/pbxgen-stress-aarch64-apple-darwin.zip.sha256
Copying target/distrib content to dist-staging/stable...
@@ -0,0 +1,3 @@
# Historical baseline investigation
These files record the diagnosis at revision `dcf6561ea73446e0a3e1cf1c73eda20923b38df0`, before the public memcard interface and exclusive backend locking were implemented. The probe intentionally tests the old behavior and is not a current conformance runner. Current qualification, commands, artifact fingerprints and limits are recorded in [the provider evidence summary](../summary.json).
@@ -0,0 +1,95 @@
import json
from pathlib import Path
import subprocess
import tempfile
root = Path.cwd()
scratch = Path(tempfile.mkdtemp(prefix="runtime-memcard-review-"))
source = scratch / "image_access.rs"
source.write_text(r'''
use prometeu_drivers::memcard::FileMemcard;
use prometeu_hal::memcard::MemcardIoError;
use prometeu_system::memcard::{image::IMAGE_BYTES, transaction::Card};
fn main() {
let args: Vec<_> = std::env::args().collect();
let path = std::path::Path::new(&args[1]);
if args.get(2).is_some() {
let second = FileMemcard::open(path, false)
.map_err(|e| format!("{e:?}"))
.and_then(|io| Card::mount(Box::new(io)).map_err(|e| format!("{e:?}")));
match second {
Ok(card) => {
println!("second_process_rw_mount_accepted");
drop(card);
}
Err(error) => println!("second_process_rw_mount_rejected:{error}"),
}
return;
}
let io = FileMemcard::create(path, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
}).expect("create private probe image");
let first_card = Card::mount(Box::new(io)).expect("first mount");
let output = std::process::Command::new(std::env::current_exe().unwrap())
.arg(path).arg("child").output().expect("child process");
assert!(output.status.success());
print!("{}", String::from_utf8(output.stdout).unwrap());
drop(first_card);
}
''')
binary = scratch / "image-access"
command = ["rustc", "--edition=2024", str(source), "-o", str(binary),
"-L", "dependency=" + str(root / "target/debug/deps")]
for crate in ("prometeu_drivers", "prometeu_hal", "prometeu_system"):
rlib = max((root / "target/debug/deps").glob("lib" + crate + "-*.rlib"),
key=lambda p: p.stat().st_mtime_ns)
command += ["--extern", crate + "=" + str(rlib)]
subprocess.run(command, check=True, capture_output=True, text=True)
access = subprocess.run([str(binary), str(scratch / "probe.pmc")],
check=True, capture_output=True, text=True)
process = subprocess.Popen([str(root / "target/debug/prometeu"), "headless", "--stdio"],
stdin=subprocess.PIPE, stdout=subprocess.PIPE,
stderr=subprocess.PIPE, text=True)
hello = json.loads(process.stdout.readline())
def request(identity, command, params):
process.stdin.write(json.dumps({"requestId": identity, "command": command, "params": params}) + "\n")
process.stdin.flush()
return json.loads(process.stdout.readline())
required = request("probe-capability", "initialize", {
"protocolVersion": {"major": 1, "minor": 0}, "requiredCapabilities": ["memcard"]})
initialized = request("init", "initialize", {
"protocolVersion": {"major": 1, "minor": 0}, "requiredCapabilities": []})
invalid = request("probe-field", "boot", {"path": str(scratch), "memcard": {}})
state = request("state", "get_state", {})
shutdown = request("stop", "shutdown", {})
process.stdin.close()
process.wait(timeout=10)
assert process.returncode == 0
assert required["error"]["code"] == "unsupported_capability"
assert invalid["error"]["code"] == "invalid_params"
assert shutdown["result"] == {"closed": True}
report = {
"runtime_revision": subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip(),
"scope": "read-only diagnosis using checkout debug binaries and isolated disposable image; no installed-process persistence qualification",
"scratch_directory": str(scratch),
"file_access_probe": {
"backend": "FileMemcard + Card::mount on a valid freshly created image",
"first_process_holds_rw_card": True,
"second_process_result": access.stdout.strip(),
"payload_writes": False,
},
"wire_probe": {
"capabilities": hello["capabilities"],
"required_capability_memcard": required["error"],
"unknown_boot_field_memcard": invalid["error"],
"get_state_fields": sorted(state["result"]),
"shutdown": shutdown["result"],
"note": "The memcard capability/field names are intentionally unsupported test input, not a proposed public contract.",
},
}
report_path = scratch / "summary.json"
report_path.write_text(json.dumps(report, indent=2) + "\n")
print(json.dumps(report, indent=2))
print("report_path=" + str(report_path))
@@ -0,0 +1,68 @@
{
"runtime_revision": "dcf6561ea73446e0a3e1cf1c73eda20923b38df0",
"scope": "read-only diagnosis using checkout debug binaries and isolated disposable image; no installed-process persistence qualification",
"scratch_directory": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/runtime-memcard-review-qa13v648",
"file_access_probe": {
"backend": "FileMemcard + Card::mount on a valid freshly created image",
"first_process_holds_rw_card": true,
"second_process_result": "second_process_rw_mount_accepted",
"payload_writes": false
},
"wire_probe": {
"capabilities": [
"boot",
"reset",
"set_input",
"clear_input",
"advance",
"capture",
"get_state",
"get_fault",
"cancel",
"shutdown"
],
"required_capability_memcard": {
"code": "unsupported_capability",
"details": {},
"message": "required capability unavailable"
},
"unknown_boot_field_memcard": {
"code": "invalid_params",
"details": {},
"message": "unknown field `memcard`, expected `path`"
},
"get_state_fields": [
"appId",
"logicalFrameIndex",
"pc",
"stackTop",
"status",
"tickIndex"
],
"shutdown": {
"closed": true
},
"note": "The memcard capability/field names are intentionally unsupported test input, not a proposed public contract."
},
"date": "2026-10-29",
"platform": "macOS-27.0.1-arm64-arm-64bit-Mach-O",
"studio_revision": "3a3417eb44c2e99ca183ce6f3fbbfff738b70f87",
"reproduction": [
"cargo test -p prometeu-cli --test automation_process -- --test-threads=1",
"python3 discussion/workflow/agendas/AGD-0071-evidence/review_probe.py"
],
"automation_process_tests": {
"passed": 12,
"failed": 0,
"ignored": 1,
"ignored_test": "packaged_installation_smoke",
"ignored_reason": "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive",
"covers_memcard": false
},
"qualification_limits": [
"No Studio Gradle/native memcard suite was rerun; its summary was inspected as existing evidence.",
"No configured installed-runtime memcard persistence test was performed.",
"Two simultaneous valid RW mounts were accepted; no concurrent payload publication was attempted.",
"No product code, normative specs or Studio files were modified."
]
}
@@ -0,0 +1,13 @@
Compiling prometeu-system v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system)
Compiling prometeu-firmware v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware)
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Compiling prometeu-host-desktop-winit v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit)
Compiling prometeu-cli v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/tools/prometeu-cli)
Finished `test` profile [unoptimized + debuginfo] target(s) in 6.37s
Running tests/automation_process.rs (target/debug/deps/automation_process-018fadef87e61183)
running 2 tests
test memcard_process::packaged_memcard_process_persistence ... ok
test packaged_installation_smoke ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 20 filtered out; finished in 1.27s
@@ -0,0 +1,140 @@
Compiling prometeu-system v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system)
Compiling prometeu-firmware v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware)
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Compiling prometeu-host-desktop-winit v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit)
Compiling prometeu-cli v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/tools/prometeu-cli)
Finished `release` profile [optimized] target(s) in 39.83s
Running unittests src/lib.rs (target/release/deps/prometeu_cli-a2a569acb4d2123a)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/main.rs (target/release/deps/prometeu-233bd0c6f7dfd1c0)
running 4 tests
test tests::child_exit_code_preserves_non_zero_one ... ok
test tests::child_exit_code_preserves_non_zero_other ... ok
test tests::child_exit_code_preserves_zero ... ok
test tests::child_exit_code_rejects_status_without_numeric_code ... ok
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/bin/prometeu-headless.rs (target/release/deps/prometeu_headless-891734b93133c22e)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/bin/prometeu-runtime.rs (target/release/deps/prometeu_runtime-2d42636990523667)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running tests/automation_process.rs (target/release/deps/automation_process-48ae7cde6854c255)
running 22 tests
test malformed_fragmented_and_oversized_commands_do_not_desynchronize ... ok
test handshake_versions_capabilities_and_limits_are_explicit ... ok
test conflicting_work_is_rejected_and_cancellation_reports_partial_progress ... ok
test faults_and_boot_failures_are_structured_not_log_parsing ... ok
test lifecycle_and_capture_match_the_in_process_canonical_oracle ... ok
test idle_eof_and_truncated_eof_close_the_process ... ok
test dispatcher_works_from_a_relocated_installation_and_other_cwd ... ok
test memcard_process::packaged_memcard_process_persistence ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive
test independent_processes_match_pixels_ids_state_and_fault ... ok
test packaged_installation_smoke ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive
test memcard_process::desktop_dispatch_forwards_explicit_media_without_interpreting_player_policy ... ok
test memcard_process::memcard_creation_race_and_process_death_release_real_ownership ... ok
test memcard_process::memcard_access_denial_is_typed_and_does_not_create_or_modify_media ... ok
test memcard_process::memcard_media_errors_and_negotiation_never_select_a_fallback ... ok
test memcard_process::memcard_dirty_refusal_retains_channel_and_explicit_ram_has_no_save ... ok
test schemas_and_distributed_request_fixtures_are_consistent ... ok
test memcard_process::memcard_idle_observation_never_advances_guest_counters ... ok
test shutdown_and_eof_interrupt_active_work_without_resuming_it ... ok
test missing_binary_and_invalid_cli_limits_fail_explicitly ... ok
test memcard_process::memcard_process_ownership_covers_aliases_readers_and_release ... ok
test partial_guest_fault_and_host_watchdog_are_distinct_outcomes ... ok
test memcard_process::memcard_public_distinct_process_save_readback_and_version_identity ... ok
test result: ok. 20 passed; 0 failed; 2 ignored; 0 measured; 0 filtered out; finished in 0.66s
Running tests/registry_fault_schema.rs (target/release/deps/registry_fault_schema-2274560704287ef1)
running 2 tests
test published_load_schema_requires_tag_context_and_the_matching_init_payload ... ok
test published_schema_accepts_structured_resource_fields_and_rejects_unknown_or_negative_values ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s
Running unittests src/lib.rs (target/release/deps/prometeu_host_headless-751195d1585cd278)
running 13 tests
test automation::tests::bounded_lines_accept_fragmentation_and_recover_after_oversize ... ok
test automation::tests::response_limit_counts_the_complete_envelope_and_keeps_correlation ... ok
test automation::tests::input_snapshot_is_replacement_and_rejects_unknown_fields ... ok
test automation::tests::distributed_request_fixtures_are_accepted_by_the_actual_parser ... ok
test automation::wire::fault_tests::resource_trap_wire_preserves_native_fields_and_source_span ... ok
test automation::tests::capture_preserves_independent_ids_and_excludes_padding_without_channel_loss ... ok
test automation::wire::fault_tests::load_failure_wire_uses_shared_structured_serializer_and_no_runtime_pc ... ok
test automation::wire::fault_tests::executed_closure_quota_refusal_reaches_wire_with_machine_fields ... ok
test automation::wire::fault_tests::active_host_native_type_fault_preserves_wire_machine_fields ... ok
test host::tests::termination_during_frame_advance_clears_host_step_control ... ok
test host::memcard::tests::explicit_continue_in_ram_preserves_dirty_snapshot_and_uses_no_new_boot ... ok
test host::memcard::tests::same_media_recovery_rejects_replacement_and_preserves_ram_continuation ... ok
test host::memcard::tests::unceased_io_retains_lock_and_terminal_result_survives_late_return_and_reconcile ... ok
test result: ok. 13 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.09s
Running tests/deterministic_control.rs (target/release/deps/deterministic_control-98e9b0ea3dcb6c52)
running 25 tests
test headless_source_has_no_timing_wait_or_interactive_backend_dependency ... ok
test lifecycle_state_and_preconditions_are_structural ... ok
test instruction_step_fault_remains_structured ... ok
test batch_stops_early_on_fault_and_reports_partial_progress ... ok
test end_of_rom_completes_a_logical_frame ... ok
test advance_after_reset_reports_termination_without_ticking ... ok
test audio_play_does_not_need_a_device ... ok
test clear_input_drops_right ... ok
test injected_civil_clock_remains_the_runtime_source_across_lifecycle ... ok
test normalized_touch_edges_and_coordinates_use_the_same_input_surface ... ok
test one_frame_returns_and_captures_the_exact_published_frame ... ok
test normalized_button_press_hold_release_and_clear_are_observable ... ok
test right_hold_then_release_changes_pixels ... ok
test step_does_not_complete_a_logical_frame ... ok
test controlled_civil_time_is_independent_of_frames_pause_and_reset ... ok
test one_logical_frame_may_span_multiple_internal_ticks ... ok
test trap_is_structured ... ok
test stepping_frame_sync_is_not_a_fault_or_completed_runtime_frame ... ok
test vm_init_failure_is_returned_as_structured_boot_failure ... ok
test zero_frames_is_an_explicit_noop ... ok
test reset_matches_fresh_host ... ok
test two_runs_match_oracle ... ok
test three_hundred_frames_complete_without_realtime_pacing ... ok
test outer_frame_limit_is_a_host_error_and_finishes_paused ... ok
test audio_controls_quota_and_multiple_frames_are_device_independent ... ok
test result: ok. 25 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.18s
Running tests/input_queries.rs (target/release/deps/input_queries-2ee1672fd0295c9d)
running 4 tests
test catalogue_has_exact_names_ids_signatures_and_no_endpoint_aliases ... ok
test every_known_query_faults_when_unavailable_and_rejects_arguments ... ok
test vm_queries_charge_one_cycle_each_and_allocate_no_guest_objects ... ok
test every_button_uses_its_own_snapshot_and_queries_do_not_advance_frames ... ok
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s
Running tests/typed_runtime.rs (target/release/deps/typed_runtime-e31573f60bd59e2a)
running 5 tests
test typed_native_argument_fault_inside_callback_reaches_active_host ... ok
test active_host_preserves_removed_opcode_load_context_and_null_fn_trap ... ok
test sync_in_callee_or_closure_resumes_next_pc_with_locals_and_init_once ... ok
test budget_exhaustion_inside_fn_keeps_the_same_open_logical_frame ... ok
test regenerated_cartridges_run_six_complete_frames_on_production_host ... ok
test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.07s

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