feat(rfc-cm): baseline P0-P3 compute machine, stdlib and resource slices

Implements the first vertical slices of RFC-CM-0001/0002 on top of a113d89:

- P1: opaque Memory regions (64 KiB pages, budgets, grow-only), byte
  read/write, Memory-index place assignment, wire/host-boundary rejection.
- CM-A04/A05: value-semantics List/Map/Text/Table primitives and the
  recoverable Result map convention.
- CM-A06: opaque Resource handles, resource.open/read/write/close, stdout
  write, granted project-file read and buffered write, strict fail-closed.
- CM-A07 Compat-A: explicit .mq.md format/utf8/io chain matching builtin
  print for the covered value types; builtin remains default.
- P2 fixtures: allocators, list/tree/graph/hash, integer codecs, UTF-8
  encode/decode, CSV/JSON subsets, table filter/sort/join, bytecode VM.
- ADRs 0022-0027, spec updates, evidence reports and 68 semantic goldens.

Gate: cargo fmt --check, clippy -D warnings, 407 tests passed.
This commit is contained in:
cflmy committed 2026-11-20 21:16:54 +08:00
1 parent a113d89496
commit 92bfbf2568
127 files changed
+11351 -141

No files matched your search

+16 -1
View File
@@ -23,8 +23,19 @@ pub enum ErrorCategory {
NotCallable,
/// A map key or record field does not exist.
UnknownField,
/// A list/map index is out of bounds.
/// A list/map/memory index is out of bounds.
IndexOutOfBounds,
/// An addressable-memory operation failed for a reason other than a plain
/// out-of-bounds read: invalid page counts, an unknown/stale handle, or an
/// arithmetic overflow in an address.
MemoryFault,
/// A resource handle is forged, cross-run or stale.
ResourceFault,
/// A resource operation used an already-closed handle (recoverable as a
/// `Result` by the builtin).
ResourceClosed,
/// The requested resource kind/descriptor/rights are not implemented.
ResourceUnsupported,
/// A resource budget was exhausted (fuel, stack, output size).
ResourceExhausted,
/// A capability check denied the operation.
@@ -60,6 +71,10 @@ impl ErrorCategory {
ErrorCategory::NotCallable => "call.not_callable",
ErrorCategory::UnknownField => "runtime.unknown_field",
ErrorCategory::IndexOutOfBounds => codes::RUNTIME_INDEX,
ErrorCategory::MemoryFault => "runtime.memory",
ErrorCategory::ResourceFault => "runtime.resource",
ErrorCategory::ResourceClosed => "resource.closed",
ErrorCategory::ResourceUnsupported => "resource.unsupported",
ErrorCategory::ResourceExhausted => codes::RESOURCE_EXHAUSTED,
ErrorCategory::PermissionDenied => codes::PERMISSION_DENIED,
ErrorCategory::KernelUnavailable => codes::KERNEL_UNAVAILABLE,
+1 -1
View File
@@ -15,6 +15,6 @@ pub use error::{CallFrame, ErrorCategory, RuntimeError};
pub use marqdo_span::{LineCol, Span};
pub use value::{
bigint_to_exact_f64, float_to_bigint, format_float, CodeValue, FormulaValue, FunctionRef,
PluginHandle, Table, Value,
MemoryHandle, PluginHandle, ResourceHandle, Table, Value,
};
pub use wire::{from_wire, to_wire, WireError, WIRE_VERSION};
+139
View File
@@ -75,6 +75,88 @@ pub struct PluginHandle {
pub id: u64,
}
/// Opaque identity of one runtime-managed byte region (ADR-0022).
///
/// A handle is issued only by the runtime's `MemoryStore`. Copying a `Memory`
/// value or passing it as an argument preserves this identity, so two names
/// can observe each other's writes. The fields are deliberately not part of
/// any wire format: [`crate::wire`] rejects the `memory` tag on decode, and no
/// public constructor accepts untrusted data. There is no `usize` address in
/// the language value; offsets are region-relative integers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct MemoryHandle {
run: u64,
region: u64,
generation: u64,
}
impl MemoryHandle {
/// Create a handle. Only the runtime store may call this; users cannot
/// construct one from a number, a document or wire data.
#[doc(hidden)]
pub const fn from_runtime(run: u64, region: u64, generation: u64) -> Self {
Self {
run,
region,
generation,
}
}
/// Run identity this region belongs to.
pub const fn run_id(&self) -> u64 {
self.run
}
/// Region identity within the run.
pub const fn region_id(&self) -> u64 {
self.region
}
/// Generation of the region slot (guards a future reuse policy).
pub const fn generation(&self) -> u64 {
self.generation
}
}
/// Opaque host-issued handle to an external resource/stream (ADR-0025).
///
/// Fields are private and the constructor is host-only. A handle is never
/// built from wire data or a user integer; it is a different domain from
/// `Memory` and cannot be indexed.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ResourceHandle {
run: u64,
resource: u64,
generation: u64,
}
impl ResourceHandle {
/// Host-only constructor.
#[doc(hidden)]
pub const fn from_host(run: u64, resource: u64, generation: u64) -> Self {
Self {
run,
resource,
generation,
}
}
/// Host run identity.
pub const fn run_id(&self) -> u64 {
self.run
}
/// Resource slot identity.
pub const fn resource_id(&self) -> u64 {
self.resource
}
/// Slot generation.
pub const fn generation(&self) -> u64 {
self.generation
}
}
/// A Marqdo runtime value.
#[derive(Debug, Clone, PartialEq)]
pub enum Value {
@@ -104,6 +186,11 @@ pub enum Value {
FunctionRef(FunctionRef),
/// Host-owned plugin handle.
PluginHandle(PluginHandle),
/// Runtime-owned addressable byte region (RFC-CM-0001). Copies share the
/// same region identity; they are not byte snapshots.
Memory(MemoryHandle),
/// Host-owned external resource/stream handle (ADR-0025).
Resource(ResourceHandle),
}
impl Value {
@@ -123,6 +210,8 @@ impl Value {
Value::Code(_) => "Code",
Value::FunctionRef(_) => "FunctionRef",
Value::PluginHandle(_) => "PluginHandle",
Value::Memory(_) => "Memory",
Value::Resource(_) => "Resource",
}
}
@@ -200,6 +289,44 @@ impl Value {
Value::Code(c) => format!("Code({:?}, {} bytes)", c.language, c.source.len()),
Value::FunctionRef(r) => format!("FunctionRef({}::{})", r.module, r.name),
Value::PluginHandle(h) => format!("PluginHandle({}::{})", h.plugin, h.export),
// Never render the runtime handle: internal region identity is not
// observable program data (RFC-CM-0001 §8).
Value::Memory(_) => "Memory".to_string(),
// Resource identity is host-private and never program data.
Value::Resource(_) => "Resource".to_string(),
}
}
/// Whether this value contains a live `Memory` handle anywhere.
///
/// Used at the host/plugin/foreign boundary, which must reject handles
/// instead of serializing them.
pub fn contains_memory(&self) -> bool {
match self {
Value::Memory(_) => true,
Value::List(items) => items.iter().any(Value::contains_memory),
Value::Map(entries) => entries.values().any(Value::contains_memory),
Value::Table(table) => table
.rows
.iter()
.flat_map(|row| row.iter())
.any(Value::contains_memory),
_ => false,
}
}
/// Whether this value contains a live `Resource` handle anywhere.
pub fn contains_resource(&self) -> bool {
match self {
Value::Resource(_) => true,
Value::List(items) => items.iter().any(Value::contains_resource),
Value::Map(entries) => entries.values().any(Value::contains_resource),
Value::Table(table) => table
.rows
.iter()
.flat_map(|row| row.iter())
.any(Value::contains_resource),
_ => false,
}
}
@@ -325,6 +452,18 @@ mod tests {
);
}
#[test]
fn memory_display_never_leaks_the_runtime_handle() {
let memory = Value::Memory(MemoryHandle::from_runtime(41, 7, 1));
assert_eq!(memory.type_name(), "Memory");
assert_eq!(memory.display(), "Memory");
assert_eq!(memory.repr(), "Memory");
assert!(!memory.display().contains("41"));
assert!(!memory.repr().contains('7'));
assert!(memory.contains_memory());
assert!(Value::List(vec![memory]).contains_memory());
}
#[test]
fn big_integers_are_arbitrary_precision() {
let big: BigInt = "123456789012345678901234567890".parse().unwrap();
+40
View File
@@ -145,6 +145,12 @@ fn encode(value: &Value) -> Json {
"export": handle.export,
"id": handle.id,
}),
// Active memory handles never cross the wire (RFC-CM-0001 §8).
// The tag is emitted so an accidental transfer is visible instead of
// silently becoming a number; decoding it is a hard error.
Value::Memory(_) => json!({"type": "memory"}),
// Resource handles are host-private; same non-transferable rule.
Value::Resource(_) => json!({"type": "resource"}),
}
}
@@ -321,6 +327,12 @@ fn decode(json: &Json, depth: usize, limits: &WireLimits) -> Result<Value, WireE
.as_u64()
.ok_or_else(|| WireError::Invalid("plugin_handle.id must be an integer".into()))?,
})),
"memory" => Err(WireError::Invalid(
"Memory handles cannot cross the wire; copy bytes explicitly".into(),
)),
"resource" => Err(WireError::Invalid(
"Resource handles cannot cross the wire".into(),
)),
other => Err(WireError::UnknownType(other.to_string())),
}
}
@@ -393,6 +405,34 @@ mod tests {
assert!(matches!(decoded, Value::Float(f) if f == f64::NEG_INFINITY));
}
#[test]
fn memory_handles_are_not_transferable() {
let value = Value::Memory(crate::MemoryHandle::from_runtime(1, 2, 1));
let wire = to_wire(&value);
assert_eq!(wire, json!({"type": "memory"}));
assert_eq!(
from_wire(&wire),
Err(WireError::Invalid(
"Memory handles cannot cross the wire; copy bytes explicitly".into()
))
);
// A hand-written fake handle is rejected by the same tag rule.
assert!(from_wire(&json!({"type": "memory", "region": 2})).is_err());
}
#[test]
fn resource_handles_are_not_transferable() {
let value = Value::Resource(crate::ResourceHandle::from_host(1, 2, 1));
let wire = to_wire(&value);
assert_eq!(wire, json!({"type": "resource"}));
assert_eq!(
from_wire(&wire),
Err(WireError::Invalid(
"Resource handles cannot cross the wire".into()
))
);
}
#[test]
fn untrusted_wire_is_validated() {
assert_eq!(