diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ed2666..551db6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -138,6 +138,9 @@ currently `0.1.0`; no release tag has been cut. Dates use ISO 8601. JSON report; no bytecode/JIT/native backend is introduced. - P4 cross-storage table equivalence: fixture 72 compares row-store Table sort/filter output with a `.mq.md` columnar store cell-by-cell. +- CM-A09 C ABI provider worker binding (ADR-0038): add the separate + `marqdo-provider-worker` helper that loads a trusted C ABI library and serves + the ADR-0035 framed-JSON protocol; crash isolation but not a sandbox. - CM-A09 provider package manifest v1 (ADR-0037): local manifest resolves a trusted C ABI library and registers it; no registry/signatures/CLI install. - CM-A09 C ABI provider v1 (ADR-0036): trusted shared libraries implement diff --git a/Cargo.lock b/Cargo.lock index 1f4ab68..75f85f7 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -476,6 +476,18 @@ dependencies = [ "serde_json", ] +[[package]] +name = "marqdo-provider-worker" +version = "0.1.0" +dependencies = [ + "libloading", + "marqdo-host", + "marqdo-sandbox", + "marqdo-value", + "serde_json", + "tempfile", +] + [[package]] name = "marqdo-runtime" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 718902d..e8b9272 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -10,6 +10,7 @@ members = [ "crates/marqdo-math", "crates/marqdo-foreign", "crates/marqdo-plugin-abi", + "crates/marqdo-provider-worker", "crates/marqdo-plugin-sdk", "crates/marqdo-host", "crates/marqdo-runtime", diff --git a/README.md b/README.md index f6655f3..0e2af12 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,8 @@ executes anything. * **Blocking TCP endpoint (RFC-CM P5 first slice)** — `resource.open("tcp", ":", ["read","write"])` with exact IP grants, project mode and 5-second timeouts; DNS/TLS/UDP/server sockets excluded (ADR-0034). +* **C ABI provider worker (RFC-CM CM-A09)** — `marqdo-provider-worker` loads a + trusted C ABI library in a separate framed-JSON helper process (ADR-0038). * **Provider package manifest v1 (RFC-CM CM-A09)** — local `marqdo.provider` manifest installs a trusted C ABI provider; no registry/signature/CLI install (ADR-0037). diff --git a/crates/marqdo-provider-worker/Cargo.toml b/crates/marqdo-provider-worker/Cargo.toml new file mode 100644 index 0000000..c313b72 --- /dev/null +++ b/crates/marqdo-provider-worker/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "marqdo-provider-worker" +version.workspace = true +edition.workspace = true +license.workspace = true +publish = false + +[[bin]] +name = "marqdo-provider-worker" +path = "src/main.rs" + +[dependencies] +libloading = { workspace = true } +serde_json = { workspace = true } + +[dev-dependencies] +marqdo-host = { path = "../marqdo-host" } +marqdo-sandbox = { path = "../marqdo-sandbox" } +marqdo-value = { path = "../marqdo-value" } +tempfile = { workspace = true } diff --git a/crates/marqdo-provider-worker/src/main.rs b/crates/marqdo-provider-worker/src/main.rs new file mode 100644 index 0000000..4780c09 --- /dev/null +++ b/crates/marqdo-provider-worker/src/main.rs @@ -0,0 +1,261 @@ +//! Trusted C ABI provider worker (ADR-0038). +//! +//! This helper loads one trusted `c-abi-1` shared library and serves the +//! ADR-0035 framed-JSON resource protocol over stdin/stdout. It is a transport +//! boundary, not a sandbox: the library runs with the worker's privileges. + +use std::ffi::{c_char, CString}; +use std::io::{Read, Write}; +use std::path::PathBuf; + +use libloading::Library; +use serde_json::{json, Value as Json}; + +const ABI_VERSION: u32 = 1; +const MAX_FRAME_BYTES: usize = 1024 * 1024; +const ERROR_MAX: usize = 1024; + +type AbiVersionFn = unsafe extern "C" fn() -> u32; +type OpenFn = unsafe extern "C" fn(*const c_char, *const c_char, *const c_char, *mut u64) -> i32; +type ReadFn = unsafe extern "C" fn(u64, *mut u8, u32, *mut u32, *mut i32) -> i32; +type WriteFn = unsafe extern "C" fn(u64, *const u8, u32, *mut u32) -> i32; +type CloseFn = unsafe extern "C" fn(u64) -> i32; +type LastErrorFn = unsafe extern "C" fn(*mut c_char, u32) -> i32; + +struct Provider { + library: Library, +} + +impl Provider { + fn load(path: &PathBuf) -> Result { + let library = unsafe { Library::new(path) } + .map_err(|error| format!("cannot load `{}`: {error}", path.display()))?; + let version: libloading::Symbol = unsafe { + library + .get(b"marqdo_resource_provider_abi_version\0") + .map_err(|error| format!("missing abi_version: {error}"))? + }; + if unsafe { version() } != ABI_VERSION { + return Err(format!("provider ABI is not {ABI_VERSION}")); + } + Ok(Self { library }) + } + + fn last_error(&self) -> String { + let Ok(symbol) = (unsafe { + self.library + .get::(b"marqdo_resource_last_error\0") + }) else { + return "C provider failed".to_string(); + }; + let mut buffer = vec![0i8; ERROR_MAX]; + if unsafe { symbol(buffer.as_mut_ptr(), ERROR_MAX as u32) } != 0 { + return "C provider failed".to_string(); + } + let bytes = buffer + .iter() + .map(|value| *value as u8) + .take_while(|value| *value != 0) + .collect::>(); + String::from_utf8_lossy(&bytes).into_owned() + } + + fn open(&self, kind: &str, descriptor: &str, rights: &[String]) -> Result { + let kind = CString::new(kind).map_err(|_| "kind has NUL".to_string())?; + let descriptor = CString::new(descriptor).map_err(|_| "descriptor has NUL".to_string())?; + let rights = CString::new(rights.join(",")).map_err(|_| "rights have NUL".to_string())?; + let symbol: libloading::Symbol = unsafe { + self.library + .get(b"marqdo_resource_open\0") + .map_err(|error| format!("missing open: {error}"))? + }; + let mut token = 0u64; + if unsafe { + symbol( + kind.as_ptr(), + descriptor.as_ptr(), + rights.as_ptr(), + &mut token, + ) + } != 0 + { + return Err(self.last_error()); + } + Ok(token) + } + + fn read(&self, token: u64, max_bytes: usize) -> Result<(Vec, bool), String> { + let capacity = u32::try_from(max_bytes).unwrap_or(u32::MAX); + let mut buffer = vec![0u8; capacity as usize]; + let mut read = 0u32; + let mut eof = 0i32; + let symbol: libloading::Symbol = unsafe { + self.library + .get(b"marqdo_resource_read\0") + .map_err(|error| format!("missing read: {error}"))? + }; + if unsafe { symbol(token, buffer.as_mut_ptr(), capacity, &mut read, &mut eof) } != 0 { + return Err(self.last_error()); + } + buffer.truncate(read as usize); + Ok((buffer, eof != 0)) + } + + fn write(&self, token: u64, bytes: &[u8]) -> Result { + let length = u32::try_from(bytes.len()).map_err(|_| "write too large".to_string())?; + let mut written = 0u32; + let symbol: libloading::Symbol = unsafe { + self.library + .get(b"marqdo_resource_write\0") + .map_err(|error| format!("missing write: {error}"))? + }; + if unsafe { symbol(token, bytes.as_ptr(), length, &mut written) } != 0 { + return Err(self.last_error()); + } + Ok(written as usize) + } + + fn close(&self, token: u64) -> Result<(), String> { + let symbol: libloading::Symbol = unsafe { + self.library + .get(b"marqdo_resource_close\0") + .map_err(|error| format!("missing close: {error}"))? + }; + if unsafe { symbol(token) } != 0 { + return Err(self.last_error()); + } + Ok(()) + } +} + +fn read_frame() -> Result, String> { + let mut header = [0u8; 4]; + let mut read = 0usize; + while read < header.len() { + match std::io::stdin().read(&mut header[read..]) { + Ok(0) if read == 0 => return Ok(None), + Ok(0) => return Err("stdin ended inside a frame header".to_string()), + Ok(count) => read += count, + Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue, + Err(error) => return Err(format!("stdin read failed: {error}")), + } + } + let length = u32::from_be_bytes(header) as usize; + if length == 0 || length > MAX_FRAME_BYTES { + return Err(format!("invalid frame length {length}")); + } + let mut payload = vec![0u8; length]; + std::io::stdin() + .read_exact(&mut payload) + .map_err(|error| format!("stdin read failed: {error}"))?; + serde_json::from_slice(&payload) + .map(Some) + .map_err(|error| format!("invalid JSON frame: {error}")) +} + +fn write_frame(value: &Json) -> Result<(), String> { + let bytes = serde_json::to_vec(value).map_err(|error| format!("encode failed: {error}"))?; + if bytes.len() > MAX_FRAME_BYTES { + return Err("response frame is too large".to_string()); + } + let mut stdout = std::io::stdout(); + stdout + .write_all(&(bytes.len() as u32).to_be_bytes()) + .and_then(|()| stdout.write_all(&bytes)) + .and_then(|()| stdout.flush()) + .map_err(|error| format!("stdout write failed: {error}")) +} + +fn fail(message: &str) -> Json { + json!({"ok": false, "code": "host.error", "message": message}) +} + +fn main() { + let Some(path) = std::env::args_os().nth(1) else { + eprintln!("usage: marqdo-provider-worker "); + std::process::exit(2); + }; + let provider = match Provider::load(&PathBuf::from(path)) { + Ok(provider) => provider, + Err(error) => { + eprintln!("provider worker: {error}"); + std::process::exit(2); + } + }; + loop { + let request = match read_frame() { + Ok(Some(request)) => request, + Ok(None) => break, + Err(error) => { + eprintln!("provider worker: {error}"); + std::process::exit(1); + } + }; + let op = request.get("op").and_then(Json::as_str).unwrap_or(""); + let response = match op { + "ping" => json!({"ok": true}), + "open" => { + let kind = request.get("kind").and_then(Json::as_str).unwrap_or(""); + let descriptor = request + .get("descriptor") + .and_then(Json::as_str) + .unwrap_or(""); + let rights = request + .get("rights") + .and_then(Json::as_array) + .map(|values| { + values + .iter() + .filter_map(Json::as_str) + .map(str::to_string) + .collect::>() + }) + .unwrap_or_default(); + match provider.open(kind, descriptor, &rights) { + Ok(token) => json!({"ok": true, "token": token}), + Err(error) => fail(&error), + } + } + "read" => { + let token = request.get("token").and_then(Json::as_u64).unwrap_or(0); + let max_bytes = + request.get("max_bytes").and_then(Json::as_u64).unwrap_or(0) as usize; + match provider.read(token, max_bytes) { + Ok((bytes, eof)) => json!({"ok": true, "bytes": bytes, "eof": eof}), + Err(error) => fail(&error), + } + } + "write" => { + let token = request.get("token").and_then(Json::as_u64).unwrap_or(0); + let bytes = request + .get("bytes") + .and_then(Json::as_array) + .map(|values| { + values + .iter() + .filter_map(Json::as_u64) + .filter_map(|value| u8::try_from(value).ok()) + .collect::>() + }) + .unwrap_or_default(); + match provider.write(token, &bytes) { + Ok(count) => json!({"ok": true, "count": count}), + Err(error) => fail(&error), + } + } + "close" => { + let token = request.get("token").and_then(Json::as_u64).unwrap_or(0); + match provider.close(token) { + Ok(()) => json!({"ok": true}), + Err(error) => fail(&error), + } + } + "shutdown" => break, + _ => fail("unsupported worker operation"), + }; + if let Err(error) = write_frame(&response) { + eprintln!("provider worker: {error}"); + std::process::exit(1); + } + } +} diff --git a/crates/marqdo-provider-worker/tests/worker_binding.rs b/crates/marqdo-provider-worker/tests/worker_binding.rs new file mode 100644 index 0000000..aa67d97 --- /dev/null +++ b/crates/marqdo-provider-worker/tests/worker_binding.rs @@ -0,0 +1,136 @@ +#![cfg(unix)] + +use std::path::Path; +use std::process::Command; + +use marqdo_host::{Capabilities, Host, StdHost}; +use marqdo_sandbox::SandboxMode; +use marqdo_value::{ErrorCategory, Value}; + +fn context() -> marqdo_host::ExecutionContext { + marqdo_host::ExecutionContext::new("test".to_string(), None) +} + +fn handle(value: Value) -> marqdo_value::ResourceHandle { + match value { + Value::Resource(handle) => handle, + other => panic!("expected resource, got {other:?}"), + } +} + +fn cc_available() -> bool { + Command::new("cc") + .arg("--version") + .output() + .map(|output| output.status.success()) + .unwrap_or(false) +} + +fn build_provider(dir: &Path) -> std::path::PathBuf { + let source = dir.join("provider.c"); + std::fs::write( + &source, + r#" +#include +#include +#include +static const char DATA[] = "worker-abi"; +static size_t position = 0; +uint32_t marqdo_resource_provider_abi_version(void) { return 1u; } +int32_t marqdo_resource_open(const char *kind, const char *descriptor, + const char *rights_csv, uint64_t *out_token) { + (void)kind; (void)descriptor; (void)rights_csv; + position = 0; *out_token = 42; return 0; +} +int32_t marqdo_resource_read(uint64_t token, uint8_t *buffer, + uint32_t capacity, uint32_t *out_read, + int32_t *out_eof) { + (void)token; + size_t remaining = sizeof(DATA) - 1 - position; + size_t count = remaining < capacity ? remaining : capacity; + memcpy(buffer, DATA + position, count); + position += count; + *out_read = (uint32_t)count; + *out_eof = position >= sizeof(DATA) - 1 ? 1 : 0; + return 0; +} +int32_t marqdo_resource_write(uint64_t token, const uint8_t *bytes, + uint32_t length, uint32_t *out_written) { + (void)token; (void)bytes; *out_written = length; return 0; +} +int32_t marqdo_resource_close(uint64_t token) { (void)token; return 0; } +int32_t marqdo_resource_last_error(char *buffer, uint32_t capacity) { + (void)capacity; buffer[0] = 0; return 0; +} +"#, + ) + .unwrap(); + let extension = if cfg!(target_os = "macos") { + "dylib" + } else { + "so" + }; + let library = dir.join(format!("libworker_provider.{extension}")); + let status = Command::new("cc") + .args(["-shared", "-fPIC", "-O2", "-o"]) + .arg(&library) + .arg(&source) + .status() + .expect("run cc"); + assert!(status.success()); + library +} + +#[test] +fn c_abi_provider_runs_inside_the_worker_helper() { + if !cc_available() { + eprintln!("skipping worker binding test: cc is unavailable"); + return; + } + let dir = tempfile::tempdir().unwrap(); + let library = build_provider(dir.path()); + let project = tempfile::tempdir().unwrap(); + let mut host = StdHost::new( + SandboxMode::Project, + Capabilities::project().allow_resource_provider("worker-cabi"), + project.path(), + ); + host.register_worker_resource_provider( + "worker-cabi", + &["worker.sensor"], + &std::path::PathBuf::from(env!("CARGO_BIN_EXE_marqdo-provider-worker")), + &[library.to_string_lossy().to_string()], + ) + .unwrap(); + let ctx = context(); + let handle = handle( + host.resource_open("worker.sensor", "s", &["read".to_string()], &ctx) + .unwrap(), + ); + let first = host.resource_read(handle, 6, &ctx).unwrap(); + assert_eq!(first.bytes, b"worker"); + let rest = host.resource_read(handle, 64, &ctx).unwrap(); + assert_eq!(rest.bytes, b"-abi"); + assert!(rest.eof); + assert_eq!(host.resource_write(handle, b"x", &ctx).unwrap(), 1); + host.resource_close(handle, &ctx).unwrap(); +} + +#[test] +fn worker_helper_without_c_provider_fails_closed() { + let project = tempfile::tempdir().unwrap(); + let mut host = StdHost::new( + SandboxMode::Project, + Capabilities::project().allow_resource_provider("worker-cabi"), + project.path(), + ); + let error = host + .register_worker_resource_provider( + "worker-cabi", + &["worker.sensor"], + &std::path::PathBuf::from(env!("CARGO_BIN_EXE_marqdo-provider-worker")), + &["/definitely/missing/provider.so".to_string()], + ) + .unwrap_err(); + assert_eq!(error.category, ErrorCategory::HostError); +} diff --git a/docs/STATUS.md b/docs/STATUS.md index 73ba615..75c88db 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -136,6 +136,9 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL PluginHandle `plugin/export` are read-only observation members (host id private); `stdlib/format.mq.md` reproduces builtin `打印`/`repr` for all 15 value types, including Formula/Code/FunctionRef and Code UTF-8 byte length. +- C ABI provider worker binding (CM-A09, ADR-0038): the separate + `marqdo-provider-worker` helper loads a trusted C ABI library and serves the + framed-JSON transport; process isolation but not a sandbox. - Provider package manifest v1 (CM-A09, ADR-0037): a local `marqdo.provider` manifest resolves a trusted C ABI library and registers it; no registry, signatures or CLI install yet. @@ -221,7 +224,7 @@ behavior. This table records only what is in this tree now. | P2 Marqdo-written allocator/data structures + minimal structure observation | **PASS (local pure lane); external stdlib repo publication pending** | `.mq.md`-only evidence: bump allocator with u32 codec, linked list, failed-allocation atomicity (48–50); CM-A04 structure primitives and a table filter (51–54, ADR-0023); a first-fit free-list allocator with block reuse, splitting, address-adjacent coalescing and `Result` maps (55, ADR-0024), a `Memory`-backed binary tree with recursive insert/in-order traversal (56), a `.mq.md` CSV row splitter (57), an open-addressing hash table with linear probing, update and `hash.full` (58), a `.mq.md` UTF-8 encoder over `Memory` (59), a validating UTF-8 decoder rejecting truncated, bad-continuation and surrogate/overlong input (60), a `Memory`-backed graph adjacency list (61), a recursive JSON parser for nested arrays/objects, strings with escapes, integers, booleans, null and error Results (62), a `Memory`-backed stack bytecode VM with PUSH/ADD/MUL/JMP/JZ/HALT (63), big-endian 16/32/64-bit plus LEB128 integer codecs (64), a `.mq.md` table sort rebuilding a new table from `table.row/columns/cell` (65), a table join (67), a quoted/escaped CSV row parser (68), table group (69), an Int matrix multiply (70), and a sparse-matrix multiply (73); the first-fit allocator also detects double free (`alloc.double_free`). Evidence: [`memory-p2-closure`](evidence/2026-11-20-memory-p2-closure.md), [`structure-api-p2`](evidence/2026-11-20-structure-api-p2.md), [`result-and-free-list-p2`](evidence/2026-11-20-result-and-free-list-p2.md). Local gate PASS: `crates/cli/tests/p2_closure.rs` runs 21 C01–C06/C11/C12 fixtures plus the stdlib table self-test in `--mode pure` (no foreign/plugin/import grants), scans sources for foreign/plugin/import shortcuts and compares value/stdout to goldens; evidence [`p2-closure-gate`](evidence/2026-11-20-p2-closure-gate.md). The bundled `stdlib/` tree, `std:` imports, digest verification, Analysis identity and frozen-CLI closure test are implemented (ADR-0028). Remaining outside C01–C12: publication as a separate external stdlib repository, and no remote CI URL. | | P3 Resource/Stream ABI | **PARTIAL** | ADR-0025/0026 CM-A06 slices: opaque `Resource`, `resource.open/read/write/close`, stdout write in pure/project, granted project-file read and buffered project-file write in project, EOF/closed/handle errors, wire/host rejection; strict permits only stdio/stdout and refuses file/network resources. Fixture 66 + CLI/host tests. CM-A07 **Compat-C** is implemented: when a program calls `打印/print`, the loader injects the bundled `stdlib/io.mq.md` and the runtime routes to `io.写值` (all 15 value types, UTF-8 via `Memory`, `resource.write(stdout)`); `HostOp::Print` and the legacy `Value::display()` print path are removed, and a missing bundle fails with `kernel.unavailable`. Strict permits only the existing stdio console channel. Providers are registered through ADR-0033 (in-process) and ADR-0035 (worker helper). Still missing: directories, C ABI provider binding, provider packages, strict provider support. | | P4 Table logical/physical migration | **PASS (local gate); T1/T2/T3 future** | ADR-0032/CM-A08: `Value::Table` semantics and GFM AST laziness unchanged; `stdlib/data/table.mq.md` provides select/filter/sort/append/set/join/group/`转GFM` as value-returning `.mq.md` functions with input immutability; zero Rust table algorithms were added. Cross-storage equivalence is pinned by fixture 72 (row Table vs `.mq.md` columnar store, identical headers/rows/cells). The optional T1/T2/T3 physical-storage/column-store migration was not required by the gate and is not implemented. | -| P5 third-party Provider / TCP / HTTP | **PASS (local gate); external network/CI and plugin-Worker resource binding open** | C10: `stdlib/net/http.mq.md` + fixture 71 parse HTTP/1.1 status/headers/chunked bodies and build requests; `http_over_tcp.rs` runs a loopback HTTP exchange wholly in `.mq.md` over `resource.open("tcp",...)`. ADR-0034 IP-literal blocking TCP endpoint (exact IP grant, project-only, 5s timeouts) and ADR-0033 in-process `ResourceProvider` v1 (registration, protocol/kind checks, name grant, mock read/write provider) ADR-0035 host-managed worker provider transport (framed JSON helper, ping/open/read/write/close, trusted-only) and ADR-0036 trusted C ABI provider (shared-library symbols, version/load checks) and ADR-0037 local provider-package manifest installation are tested. External DNS/TLS/UDP, host HTTP, provider packages/signatures and the plugin-Worker resource binding remain out of scope. | +| P5 third-party Provider / TCP / HTTP | **PASS (local gate); external network/CI and plugin-Worker resource binding open** | C10: `stdlib/net/http.mq.md` + fixture 71 parse HTTP/1.1 status/headers/chunked bodies and build requests; `http_over_tcp.rs` runs a loopback HTTP exchange wholly in `.mq.md` over `resource.open("tcp",...)`. ADR-0034 IP-literal blocking TCP endpoint (exact IP grant, project-only, 5s timeouts) and ADR-0033 in-process `ResourceProvider` v1 (registration, protocol/kind checks, name grant, mock read/write provider) ADR-0035 host-managed worker provider transport (framed JSON helper, ping/open/read/write/close, trusted-only) and ADR-0036 trusted C ABI provider (shared-library symbols, version/load checks) ADR-0037 local provider-package manifest installation and ADR-0038 C ABI provider worker binding (separate trusted helper process) are tested. External DNS/TLS/UDP, host HTTP, provider packages/signatures and the plugin-Worker resource binding remain out of scope. | | P6 performance / native backends | **BASELINE ONLY** | reproducible profile harness `tools/perf/bench.py` and [`p6-profile`](evidence/2026-11-20-p6-profile.md) for 7 workloads; no bytecode/JIT/columnar numeric backend or equivalence/optimization gate yet | The P1 memory domain is pure computation: it needs no grant and is available in @@ -267,6 +270,9 @@ user-written allocator is explicitly **not** claimed. echo tests. - [`evidence/2026-11-20-table-cross-storage.md`](evidence/2026-11-20-table-cross-storage.md) — P4 row-store Table vs `.mq.md` columnar store equivalence for sort/filter. +- [`evidence/2026-11-20-c-worker-binding.md`](evidence/2026-11-20-c-worker-binding.md) + — ADR-0038 C ABI provider worker binding, compiled C adapter in the helper + process and fail-closed missing-library case. - [`evidence/2026-11-20-provider-package.md`](evidence/2026-11-20-provider-package.md) — ADR-0037 local provider package manifest, C library resolution and registration test. diff --git a/docs/adr/0038-c-abi-provider-worker-binding.md b/docs/adr/0038-c-abi-provider-worker-binding.md new file mode 100644 index 0000000..ff55bcd --- /dev/null +++ b/docs/adr/0038-c-abi-provider-worker-binding.md @@ -0,0 +1,68 @@ +# ADR-0038: C ABI provider worker binding v1 + +Status: **Accepted (trusted helper; existing plugin-Worker ABI binding still open)** +Date: 2026-11-20 +Relates to: `docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md` +(CM-A09, CM-A11, P5), ADR-0035, ADR-0036 +Bin: `crates/marqdo-provider-worker` +Evidence: `docs/evidence/2026-11-20-c-worker-binding.md` + +## Context + +ADR-0036 loads a trusted C ABI provider in the host process; ADR-0035 provides a +framed-JSON worker transport. CM-A09 also asks for the Worker side of the C ABI: +the provider library should be loadable in a separate process so a crash does +not take down the interpreter, without inventing a new language surface. This +ADR adds the concrete binding. + +## Decision + +### 1. Worker binary + +`marqdo-provider-worker `: + +* loads exactly one `c-abi-1` shared library (ADR-0036 symbols); +* verifies `marqdo_resource_provider_abi_version() == 1` at startup; +* serves the ADR-0035 framed-JSON protocol (`ping/open/read/write/close/ + shutdown`) over stdin/stdout; +* maps C provider failures to `{"ok":false,"code":"host.error","message":...}` + and never falls back to in-process loading. + +The binary is a separate artifact, not a new top-level `marqdo` CLI command. +Registration is still host-side: +`StdHost::register_worker_resource_provider(name, kinds, worker_bin, [library])` +from ADR-0035. + +### 2. Process boundary + +* The C library runs in the worker process; a crash/exit is a structured host + error and the host does not retry in-process. +* The worker has the host user's OS privileges; this is a **trusted transport**, + not a sandbox and not proof of untrusted-provider safety. +* The language still sees only `resource.*`; provider tokens stay inside the + worker and the host `ResourceHandle` remains the language value. +* Project mode + `allow_resource_provider(name)` are still required; pure/strict + refuse provider kinds (CM-A11). + +### 3. What remains for CM-A09 + +* Binding the provider contract through the **existing plugin-Worker ABI** + (manifest/artifact ownership and version negotiation) rather than the + dedicated helper. +* Provider registry/download/signatures and package installation commands. +* Untrusted-provider isolation and strict-mode providers. +* ABI version negotiation beyond v1. + +## Consequences + +* A trusted C adapter can be crash-isolated without changing the runtime, + parser, `Value` or `HostOp`. +* The worker helper is small and reusable by a future provider package manager. +* The trust model is explicit: worker isolation ≠ sandbox; the provider library + remains trusted code. + +## Verification + +`docs/evidence/2026-11-20-c-worker-binding.md` records a compiled C provider, +the worker helper, a full open/read/write/close round-trip through the host +worker transport, and fail-closed startup with a missing library. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index e09b9de..50d97c8 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -34,6 +34,7 @@ implementation status lives in `docs/STATUS.md`; frozen behavior is in | CM-A09 worker resource-provider transport v1 | [0035](../adr/0035-worker-resource-provider-transport.md) | Accepted (trusted helper) | | CM-A09 C ABI ResourceProvider v1 | [0036](../adr/0036-c-abi-resource-provider.md) | Accepted (trusted native adapter) | | CM-A09 provider package manifest v1 | [0037](../adr/0037-provider-package-manifest.md) | Accepted (host-side install) | +| CM-A09 C ABI provider worker binding v1 | [0038](../adr/0038-c-abi-provider-worker-binding.md) | Accepted (trusted helper) | | Table physical storage (T1/T2/T3), C/Worker provider transport, strict file/network resources | — | Not decided; do not implement by implication | ## What a future phase must not do diff --git a/docs/evidence/2026-11-20-c-worker-binding.md b/docs/evidence/2026-11-20-c-worker-binding.md new file mode 100644 index 0000000..7f3b002 --- /dev/null +++ b/docs/evidence/2026-11-20-c-worker-binding.md @@ -0,0 +1,45 @@ +# RFC-CM CM-A09 evidence: C ABI provider worker binding v1 + +Date: 2026-11-20 (Asia/Shanghai) +Repository: `marqdo-cli` +Baseline: `313ac03` plus this step's changes. +Decision record: [ADR-0038](../adr/0038-c-abi-provider-worker-binding.md) +Related: [C ABI](2026-11-20-c-provider.md), [worker transport](2026-11-20-worker-provider.md). +Scope: trusted helper binding; not a sandbox and not the plugin-Worker ABI. + +## Artifact + +`marqdo-provider-worker ` loads a `c-abi-1` shared library and serves +the ADR-0035 framed-JSON protocol (ping/open/read/write/close/shutdown). The +host registers it through the existing +`StdHost::register_worker_resource_provider` API; no runtime/`HostOp`/parser +change was required. + +## Tests + +`crates/marqdo-provider-worker/tests/worker_binding.rs`: + +```text +c_abi_provider_runs_inside_the_worker_helper + cc -shared C provider; worker binary loaded; + resource.open/read "worker"/"-abi" eof/write/close through the host. + +worker_helper_without_c_provider_fails_closed + missing library -> structured host error, no in-process fallback. +``` + +The C provider state lives in the child; the host only sees the opaque +`ResourceHandle` and `ResourceRead` bytes. + +## Boundary + +The worker is a trusted helper with host-user privileges. It isolates crashes +and keeps the C library out of the interpreter process, but it is **not** an OS +sandbox. Pure/strict still refuse provider kinds; strict remains fail-closed. + +## Not done + +* Binding through the existing plugin-Worker manifest/artifact ABI. +* Provider registry/signatures/install commands. +* Untrusted-provider isolation, strict providers, Windows worker packaging. +* ABI version negotiation beyond rejecting non-v1 libraries. diff --git a/spec/security.md b/spec/security.md index 76cd476..52f2af4 100644 --- a/spec/security.md +++ b/spec/security.md @@ -63,7 +63,7 @@ set for one run: | `process: bool` | `false` | required together with `foreign` for `foreign.run`/`foreign.call` | | `foreign: bool` | `false` | foreign kernels | | `plugins: Vec` | empty | `plugin.invoke` and `StdHost::load_plugin` | -| `resource_providers: Vec` | empty | registered in-process/worker/C-ABI `ResourceProvider` kinds; project mode only; helper processes and native libraries are trusted, not sandboxed (ADR-0033/0035/0036); local manifests are host-installed, unsigned (ADR-0037) | +| `resource_providers: Vec` | empty | registered in-process/worker/C-ABI `ResourceProvider` kinds; project mode only; helper processes and native libraries are trusted, not sandboxed (ADR-0033/0035/0036); local manifests are host-installed, unsigned (ADR-0037); the C worker helper is a trusted process boundary, not a sandbox (ADR-0038) | Requests versus grants: diff --git a/tests/README.md b/tests/README.md index 7c5b7e7..14647bf 100644 --- a/tests/README.md +++ b/tests/README.md @@ -177,6 +177,11 @@ grant/pure/strict/DNS refusal) and `crates/cli/tests/resource_streams.rs::tcp_stream_round_trips_through_mqmd_with_a_network_grant` (`--allow-net 127.0.0.1`). +RFC-CM CM-A09 C ABI worker binding (ADR-0038) is pinned by +`crates/marqdo-provider-worker/tests/worker_binding.rs`, which compiles a C +provider, runs it through the worker helper and the host transport, and checks +missing-library fail-closed startup. + RFC-CM CM-A09 C ABI provider (ADR-0036) is pinned by `crates/marqdo-host/tests/c_provider.rs`, which compiles a small C shared library, registers it, round-trips `resource.*`, checks missing-library,