spacedb-query 0.7.2

SpaceDB Layer 4 — compute-to-data: run a deterministic, fuel/memory-bounded WASM function next to the data and return a verifiable, corroboratable result. The query travels to the data; only the answer travels back. Phase 1 SpaceDB Mission, M6.
Documentation

spacedb-query

crates.io docs.rs License: MIT OR Apache-2.0 Remade With Rust By Mata Network

SpaceDB Layer 4 — compute-to-data.

The environment forbids hauling data to a central brain, so SpaceDB inverts it: the query travels to the data; only the answer travels back. A query is a deterministic, fuel- and memory-bounded WASM function that runs on the node holding the data — and because the runtime is deterministic, the result is corroboratable: a host that returns a different answer than its peers is caught.

Part of SpaceDB. Dual-licensed MIT OR Apache-2.0.

[dependencies]
spacedb-query = "0.7"

Run a function next to the data

use spacedb_query::{FunctionRuntime, RunLimits};
let module_wasm: Vec<u8> = Vec::new();   // a real deterministic WASM module
let input_bytes: Vec<u8> = Vec::new();

let runtime = FunctionRuntime::new().unwrap();
let limits = RunLimits { max_fuel: 100_000_000, max_mem_mb: 64 };

let exec = runtime.run(&module_wasm, &input_bytes, &limits).unwrap();
println!("{:?} fuel={}", exec.output, exec.run.fuel_used);

The runtime is wasmtime with no WASI: no clock, no filesystem, no network, no randomness. A function that cannot observe anything nondeterministic cannot produce a nondeterministic answer — which is what makes the next section work. Fuel exhaustion and the memory ceiling are hard stops, so an untrusted function cannot pin a home's CPU or RAM.

Corroboration

Every run yields a FunctionRun attestation: workload_hash, input_digest, output_digest, fuel_used, mem_peak_mb.

use spacedb_query::{corroborate, Corroboration, FunctionRun};

// Two independent hosts ran the same (workload, input) — so every field must match.
let run_a = FunctionRun {
    workload_hash: [1u8; 32],
    input_digest: [2u8; 32],
    output_digest: [3u8; 32],
    fuel_used: 12_345,
    mem_peak_mb: 1,
};
let run_b = run_a.clone();

assert_eq!(corroborate(&run_a, &run_b), Corroboration::Agree);

Honest runs of the same (workload, input) agree on every field. A wrong output, or a padded fuel count billed for work not done, is Disagree. Fanning that comparison across independent marketplace hosts is the MATA seam; the runtime, the attestation, and the comparison are here.

Pinned snapshots and rights

Snapshot::pin(bytes, frontier) freezes exactly what a query reads, and its hash() goes into the attestation — so two hosts corroborating a result are provably comparing the same input state, not two different moments in time.

FunctionCtx carries that snapshot plus CtxRights { read, write } and an explicit denied set: collections whose ciphertext the host holds but provably cannot compute on. Serving those to server-side code would break the zero-knowledge promise, so the context refuses them. Accumulated writes are exposed as a writes_digest rather than applied behind the caller's back.

Partition-aware map-reduce

use spacedb_query::{run_query, FunctionRuntime, QueryPlan, RunLimits, Shard, Snapshot};

let runtime = FunctionRuntime::new().unwrap();
let plan = QueryPlan {
    map_wasm: &map_wasm,
    reduce_wasm: &reduce_wasm,
    limits: RunLimits::default(),
};
let shards = vec![
    Shard::new("home-1", Snapshot::pin(snapshot_a, frontier_a)),
    Shard::new("home-2", Snapshot::pin(snapshot_b, frontier_b)).unreachable(),
];

let outcome = run_query(&runtime, &plan, &shards).unwrap();
if !outcome.coverage.is_complete() {
    // honest: N shards were unreachable — this is a partial answer
    eprintln!("{} shard(s) missing", outcome.coverage.missing());
}

The planner maps over reachable shards and reduces the partials, and reports Coverage honestly. A partial answer is labeled partial; it is never rounded up to complete.

Open-core boundary

Built on wasmtime directly — the same engine MATA's maestro-fn-runtime wraps — with no MATA dependency.

Performance (0.7.2)

Measured on exact instruction counts (callgrind) with deterministic drivers whose outputs did not change; release build, 0.7.1 -> 0.7.2: ir_query 33.4M -> 27.4M (-18.0%).

  • PinnedRecords shares a snapshot and its hash across runs (FunctionCtx::with_pinned).
  • A query hashes each module once and reuses the snapshot's digest (FunctionRuntime::run_prehashed).
  • The Database-Function linker is built once per runtime.

Performance (0.7.0)

Measured on exact instruction counts (callgrind) with this crate's deterministic driver, examples/ir_query.rs; outputs unchanged by every change. Release build, 0.6.0 -> 0.7.0: 280.9M -> 33.4M instructions (-88.1%).

  • Compiled modules are cached by workload hash (a map-reduce used to compile its two modules once per shard and per reduce step).
  • Host calls borrow op and payload from guest memory, resolve memory and alloc once per instance, and reuse one lookup key and one response buffer per run; the query op reads its collection as a key range.
  • The reduce fold moves partials and frames them in one reused buffer.

Testing

The workspace defaults to wasm32; this crate is native. Test on your host triple:

cargo test -p spacedb-query --target aarch64-apple-darwin   # or your host triple

Suites: runtime.rs (determinism, fuel/memory limits, module validation), functions.rs (context, rights, denied collections), planner.rs (map-reduce, coverage under partition).

License

MIT OR Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.