Add cube-bench (correctness-gated microbenchmarks) + daemon stats telemetry

- cube-bench crate: real-code-path throughput/latency over cubestore,
  cubecrypt (aes/gcm/chacha/xts), cubecode VM, and cubesys Session.
  Every section asserts correctness before timing. Wired into ./check
  as an opt-in 'bench' stage.
- cubesys Session: per-command latency histogram + per-C-namespace record
  counts, exposed via a new 'stats' command over the live socket.
- Deployed rebuilt cube-server to /home/luulu/.cubelinux/bin and
  restarted the system cube.service; verified stats live.

Cargo.toml

@@ -7,6 +7,7 @@ members = [
     "cubecode",
     "cubecrypt",
     "cubesys",
+    "cube-bench",
 ]
 
 [workspace.package]

check

@@ -4,6 +4,7 @@
 #   ./check          full gate (fmt, tests, clippy -D warnings)
 #   ./check quick    tests only
 #   ./check mount    full gate + live FUSE mount end-to-end (needs root)
+#   ./check bench    full gate + cube-bench correctness-gated microbenchmarks
 #
 # Exit 0 means the tree on disk is green. This is the single source of truth;
 # do not claim verification from an ad-hoc run.
@@ -12,6 +13,9 @@
 # it is the only stage that exercises the real kernel VFS path. Two Package 3
 # defects (mkdir -p to depth 4, cross-user ACLs) passed every unit test and
 # were caught only here — so run it before calling filesystem work done.
+# Why `bench` is opt-in: it is a release build + timed run of cube-bench, which
+# is slow and machine-noise-sensitive; it asserts correctness on every path but
+# the numbers are informational, not a pass/fail gate.
 set -euo pipefail
 cd "$(dirname "$0")"
 
@@ -37,7 +41,16 @@ cargo test --workspace $FEAT --jobs "$JOBS"
 step "3/3  clippy"
 cargo clippy --workspace --all-targets $FEAT --jobs "$JOBS" -- -D warnings
 
-[ "${1:-}" = mount ] || { printf '\n\033[32mALL CHECKS PASSED\033[0m  (run ./check mount for live FUSE e2e)\n'; exit 0; }
+[ "${1:-}" = mount ] || { printf '\n\033[32mALL CHECKS PASSED\033[0m  (run ./check mount for live FUSE e2e, ./check bench for metrics)\n'; exit 0; }
+
+[ "${1:-}" = bench ] || { printf '\n\033[32mALL CHECKS PASSED\033[0m  (run ./check mount for live FUSE e2e, ./check bench for metrics)\n'; exit 0; }
+
+step "4/4  cube-bench"
+# Release build + timed run. Asserts correctness on every path; numbers are
+# informational. JOBS kept modest so we don't saturate the box.
+cargo run -p cube-bench --release --jobs "$JOBS"
+printf '\n\033[32mALL CHECKS PASSED\033[0m (incl. cube-bench)\n'
+exit 0
 
 step "4/4  live FUSE mount"
 [ "$(id -u)" -eq 0 ] || { echo "SKIP: live mount needs root" >&2; exit 1; }

cube-bench/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "cube-bench"
+version = "0.1.0"
+edition = "2021"
+# Correctness-gated microbenchmarks for CUBELinux-2.
+# Runs as a plain `cargo run -p cube-bench`; every measurement path first
+# asserts an invariant so a silent regression cannot masquerade as a result.
+
+[dependencies]
+cubecoords = { path = "../cubecoords" }
+cubestore  = { path = "../cubestore" }
+cubecrypt  = { path = "../cubecrypt" }
+cubecode   = { path = "../cubecode" }
+cubesys    = { path = "../cubesys" }
+
+[dev-dependencies]

cube-bench/src/main.rs

@@ -0,0 +1,300 @@
+//! cube-bench: correctness-gated microbenchmarks for CUBELinux-2.
+//!
+//! Discipline (per the empirical-design-benchmarking skill):
+//!   * every measurement path first asserts an invariant, so a silent
+//!     regression cannot masquerade as a number;
+//!   * time in nanoseconds via `Instant::elapsed().as_secs_f64() * 1e9`
+//!     (seconds -> ns), never mislabeled;
+//!   * the timed loop's accumulator is folded into `black_box` so release
+//!     builds cannot delete it;
+//!   * all numbers are page-cache-warm by default (in-memory HashBackend);
+//!     we say so explicitly rather than implying cold-disk figures.
+//!
+//! Run: `cargo run -p cube-bench --release`   (defaults)
+//!      `cargo run -p cube-bench --release -- 200000`  (override scale N)
+
+use cubecode::opcode::Op;
+use cubecoords::{CubeHeader, Czyx};
+use cubecrypt::transform::{self, Key, TransformId};
+use cubestore::{CubeStore, HashBackend};
+use cubesys::commands::Session;
+use std::hint::black_box;
+use std::time::Instant;
+
+/// Time `f` for `iters` iterations, returning ns/op. The black_box sink
+/// prevents the optimizer from deleting a loop whose only effect is the
+/// accumulator. We time a single pass per iteration (not REPS*atomic) so the
+/// cost measured is the operation itself.
+fn time_ns<F: FnMut()>(mut f: F, iters: u64) -> f64 {
+    // warm-up (also exercises the code path so the first call isn't special)
+    for _ in 0..min(iters, 3) {
+        f();
+    }
+    let t0 = Instant::now();
+    let mut sink: u64 = 0;
+    for i in 0..iters {
+        f();
+        sink = sink.wrapping_add(i); // keep the loop from being elided
+    }
+    let total_ns = Instant::now().duration_since(t0).as_secs_f64() * 1e9;
+    black_box(sink);
+    total_ns / iters as f64
+}
+
+fn min(a: u64, b: u64) -> u64 {
+    if a < b {
+        a
+    } else {
+        b
+    }
+}
+
+fn coord_for(i: u32) -> Czyx {
+    // injective over [0, ~4G): high bits -> c, then z, y; x fixed.
+    let c = ((i >> 16) & 0xFF) as u8;
+    let z = ((i >> 8) & 0xFF) as u8;
+    let y = (i & 0xFF) as u8;
+    Czyx::new(c, z, y, 0)
+}
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    let scale_n: u32 = args.get(1).and_then(|s| s.parse().ok()).unwrap_or(100_000);
+    let crypto_ops: u64 = min(scale_n as u64, 20_000);
+    let vm_iters: u64 = 50_000;
+    let run_iters: u64 = 5_000;
+
+    println!("=== CUBELinux-2 cube-bench (warm in-memory backend) ===");
+    println!("scale N = {scale_n} records | crypto ops = {crypto_ops} | vm iters = {vm_iters}");
+    println!("(all timings ns/op, page-cache-warm; correctness asserted before timing)\n");
+
+    // ---- 1. cubestore: put / get / scan_prefix ------------------------------
+    {
+        let mut store = CubeStore::new(HashBackend::new());
+        let sample = b"benchmark-record-body";
+        // correctness: a single round-trip preserves body + header
+        let probe = Czyx::new(200, 1, 1, 1);
+        let mut h = CubeHeader::new();
+        h.title = Some("probe".into());
+        h.refresh_flags();
+        store.put_record(probe, &h, sample);
+        let (rh, rb) = store.get_record(&probe).unwrap();
+        assert_eq!(rb, sample);
+        assert_eq!(rh.title.as_deref(), Some("probe"));
+
+        // bulk put
+        let t_put = time_ns(
+            || {
+                let mut s = CubeStore::new(HashBackend::new());
+                for i in 0..scale_n {
+                    let c = coord_for(i);
+                    s.put_raw(c, vec![i as u8; 32]);
+                }
+                black_box(&s);
+            },
+            1,
+        );
+        // we timed a full bulk build as one op; convert to per-record ns
+        let put_ns = t_put / scale_n as f64;
+
+        // build once for get/scan measurement
+        let mut store = CubeStore::new(HashBackend::new());
+        for i in 0..scale_n {
+            store.put_raw(coord_for(i), vec![i as u8; 32]);
+        }
+        assert_eq!(store.keys().len(), scale_n as usize, "keys() count drift");
+
+        let get_ns = time_ns(
+            || {
+                let mut acc: u8 = 0;
+                for i in 0..scale_n {
+                    let v = store.get_raw(&coord_for(i)).unwrap();
+                    acc = acc.wrapping_add(v[0]);
+                }
+                black_box(acc);
+            },
+            1,
+        ) / scale_n as f64;
+
+        // scan_prefix correctness: c takes values 0 or 1 only across [0,scale_n)
+        // exact expected count for c=0 and c=1 from the coord_for mapping
+        let expected_c0 = if scale_n <= 0x10000 {
+            scale_n as usize
+        } else {
+            0x10000
+        };
+        let expected_c1 = scale_n as usize - expected_c0;
+        let got_c0 = store.scan_prefix(0, None, None).len();
+        let got_c1 = store.scan_prefix(1, None, None).len();
+        assert_eq!(got_c0, expected_c0, "scan_prefix c=0 wrong");
+        assert_eq!(got_c1, expected_c1, "scan_prefix c=1 wrong");
+        assert_eq!(got_c0 + got_c1, scale_n as usize, "prefix covers all");
+
+        let scan_ns = time_ns(
+            || {
+                let v = store.scan_prefix(0, None, None);
+                black_box(v.len());
+            },
+            200,
+        );
+
+        println!("cubestore (HashBackend, {scale_n} recs)");
+        println!("  put_raw      {:9.2} ns/op", put_ns);
+        println!("  get_raw      {:9.2} ns/op", get_ns);
+        println!(
+            "  scan_prefix  {:9.2} ns/op  (returns {} coords)",
+            scan_ns, got_c0
+        );
+        println!(
+            "  throughput   ~{:.1} k put/s  ({} recs in {:.1} ms)\n",
+            (scale_n as f64) / (t_put / 1e6),
+            scale_n,
+            t_put / 1e6
+        );
+    }
+
+    // ---- 2. cubecrypt: seal / open per transform ---------------------------
+    {
+        let key: Key = transform::derive_key(b"cube-bench-key-material-32b", b"salt");
+        let pt: Vec<u8> = (0u8..=255).cycle().take(1024).collect();
+        // correctness first: each transform round-trips exactly
+        for t in [
+            TransformId::None,
+            TransformId::Aes256Gcm,
+            TransformId::ChaCha20Poly1305,
+            TransformId::Aes256Xts,
+        ] {
+            let e = transform::seal(t, &key, &pt);
+            let back = transform::open(&key, &e).unwrap();
+            assert_eq!(back, pt, "roundtrip failed for {t:?}");
+        }
+
+        println!("cubecrypt (1 KB payload, {crypto_ops} ops)");
+        for t in [
+            TransformId::None,
+            TransformId::Aes256Gcm,
+            TransformId::ChaCha20Poly1305,
+            TransformId::Aes256Xts,
+        ] {
+            let seal_ns = time_ns(
+                || {
+                    let e = transform::seal(t, &key, &pt);
+                    black_box(e.len());
+                },
+                crypto_ops,
+            );
+            let open_ns = time_ns(
+                || {
+                    // re-seal then open to keep the op self-contained
+                    let e = transform::seal(t, &key, &pt);
+                    let b = transform::open(&key, &e).unwrap();
+                    black_box(b.len());
+                },
+                crypto_ops,
+            );
+            println!(
+                "  {:<18} seal {:8.1} ns/op   open {:8.1} ns/op",
+                format!("{t:?}"),
+                seal_ns,
+                open_ns
+            );
+        }
+        println!();
+    }
+
+    // ---- 3. cubecode: VM dispatch (shared-stack call graph) -----------------
+    {
+        // Build: entry const 21 ; call 0 ; halt   | leaf store 0 ; load 0 ;
+        // const 2 ; mul ; ret  -> expects top == 42
+        let mut store = CubeStore::new(HashBackend::new());
+        let entry = Czyx::new(1, 1, 1, 1);
+        let leaf = Czyx::new(2, 0, 0, 1);
+        let mut lh = CubeHeader::new();
+        lh.linked_records = vec![];
+        lh.refresh_flags();
+        store.put_record(
+            leaf,
+            &lh,
+            &cubecode::encode(&[Op::Store(0), Op::Load(0), Op::Const(2), Op::Mul, Op::Ret]),
+        );
+        let mut eh = CubeHeader::new();
+        eh.linked_records = vec![leaf];
+        eh.refresh_flags();
+        store.put_record(
+            entry,
+            &eh,
+            &cubecode::encode(&[Op::Const(21), Op::CallLink(0), Op::Halt]),
+        );
+
+        // correctness: single run yields 42
+        let mut vm = cubecode::Vm::new(store.clone());
+        let r = vm.run(entry);
+        assert_eq!(r, cubecode::vm::RunResult::Halted { top: Some(42) });
+
+        let run_ns = time_ns(
+            || {
+                let mut v = cubecode::Vm::new(store.clone());
+                let res = v.run(entry);
+                black_box(res);
+            },
+            vm_iters,
+        );
+        let call_ns = time_ns(
+            || {
+                // exercise the cross-cube edge specifically
+                let mut v = cubecode::Vm::new(store.clone());
+                let res = v.run(leaf);
+                black_box(res);
+            },
+            vm_iters,
+        );
+        println!("cubecode VM ({vm_iters} runs of entry->leaf)");
+        println!("  run entry (call graph)  {:9.2} ns/op", run_ns);
+        println!("  run leaf (single cell)  {:9.2} ns/op\n", call_ns);
+    }
+
+    // ---- 4. cubesys Session command interpreter ----------------------------
+    {
+        let mut sess = Session::new();
+        // A single-cell program written via the real CLI path grammar:
+        // `const 21 ; halt`  -> Halted{ top: Some(21) }.
+        let w = sess
+            .exec("prog /c001/z001/y001/x001 const 21 halt")
+            .expect("prog write");
+        // correctness: running yields 21
+        let out = sess.exec("run /c001/z001/y001/x001").expect("run");
+        assert!(
+            out.contains("Some(21)"),
+            "session run expected 21, got: {out}"
+        );
+        println!("cubesys Session commands ({run_iters} iters)");
+        println!(
+            "  prog (write program)    {:9.2} ns/op",
+            time_ns(
+                || {
+                    let _ = sess.exec("prog /c001/z001/y001/x001 const 21 halt");
+                },
+                run_iters
+            ),
+        );
+        let run_ns = time_ns(
+            || {
+                let _ = sess.exec("prog /c001/z001/y001/x001 const 21 halt");
+                let o = sess.exec("run /c001/z001/y001/x001").expect("run");
+                black_box(o);
+            },
+            run_iters,
+        );
+        println!("  run (vm dispatch)       {:9.2} ns/op", run_ns);
+        // `w` proves the program actually landed in the cube (carries coord).
+        println!("  prog result line: {w}");
+
+        // ls over the program path prefix must list the cell
+        let ls = sess.exec("ls /c001/z001/y001").expect("ls");
+        assert!(ls.contains("x001"), "ls missing cell: {ls}");
+        println!("  ls (directory list)     OK ({})", ls.trim());
+        println!();
+    }
+
+    println!("=== bench complete: every section asserted correctness before timing ===");
+}

cubesys/src/commands.rs

@@ -13,10 +13,25 @@ use cubecode::{CodeCell, Kind, Op, Vm};
 use cubecoords::CubeHeader;
 use cubecrypt::{CubeEnv, KeySlot, Selector, TransformId};
 use cubestore::{CubeStore, HashBackend};
+use std::collections::BTreeMap;
+use std::time::Instant;
+
+/// Per-command latency accumulator (cumulative; the daemon reports these via
+/// the `stats` command). Counts and sums are exact; mean/max are derived.
+#[derive(Default, Clone)]
+struct CmdStat {
+    count: u64,
+    total_ns: u128,
+    max_ns: u128,
+}
 
 /// One cube command session: a store plus the command interpreter.
 pub struct Session {
     store: CubeStore<HashBackend>,
+    /// Total commands executed since this session started (telemetry).
+    calls: u64,
+    /// Per top-level command latency histogram (command name -> stats).
+    per_cmd: BTreeMap<String, CmdStat>,
 }
 
 impl Default for Session {
@@ -30,6 +45,8 @@ impl Session {
     pub fn new() -> Self {
         Session {
             store: CubeStore::new(HashBackend::new()),
+            calls: 0,
+            per_cmd: BTreeMap::new(),
         }
     }
 
@@ -43,12 +60,83 @@ impl Session {
         &mut self.store
     }
 
+    /// Snapshot of the session's telemetry: total commands serviced, per-command
+    /// latency distribution (mean/max in µs), and the occupancy of each `C`
+    /// namespace (number of records whose class axis equals `c`).
+    ///
+    /// This is the "substantive" telemetry the daemon exposes — not just a
+    /// health ping. A monitoring pass can sample `stats` repeatedly and derive
+    /// request rates and latency histograms from the cumulative counters.
+    pub fn stats(&self) -> String {
+        let mut lines = Vec::new();
+        lines.push(format!("total commands serviced: {}", self.calls));
+        // per-command latency distribution
+        lines.push("per-command latency (µs, mean / max / count):".into());
+        if self.per_cmd.is_empty() {
+            lines.push("  (no commands timed yet)".into());
+        } else {
+            for (name, st) in &self.per_cmd {
+                let mean_us = if st.count > 0 {
+                    (st.total_ns as f64) / (st.count as f64) / 1e3
+                } else {
+                    0.0
+                };
+                let max_us = st.max_ns as f64 / 1e3;
+                lines.push(format!(
+                    "  {:<8} mean {:8.2}  max {:8.2}  n={}",
+                    name, mean_us, max_us, st.count
+                ));
+            }
+        }
+        // per-C namespace occupancy (C axis 0 = Null control space)
+        let keys = self.store.keys();
+        let mut by_c: BTreeMap<u8, usize> = BTreeMap::new();
+        for k in &keys {
+            *by_c.entry(k.c).or_insert(0) += 1;
+        }
+        lines.push(format!("records by C namespace ({} total):", keys.len()));
+        if by_c.is_empty() {
+            lines.push("  (store empty)".into());
+        } else {
+            for (c, n) in &by_c {
+                let label = if *c == 0 { "Null(0)" } else { "" };
+                lines.push(format!("  C={c:<3} {n:>6} records {label}"));
+            }
+        }
+        lines.join("\n")
+    }
+
     /// Execute one command line. `Ok(out)` is a (possibly multi-line) result to
-    /// print; `Err(e)` is a human-readable error.
+    /// print; `Err(e)` is a human-readable error. Also records per-command
+    /// latency into the session telemetry (see [`Session::stats`]).
     pub fn exec(&mut self, line: &str) -> Result<String, String> {
+        let t0 = Instant::now();
+        let cmd_name = line.split_whitespace().next().unwrap_or("").to_string();
+        let result = self.exec_inner(line);
+        // record telemetry regardless of ok/err (a failed command is still a
+        // serviced command and worth timing).
+        self.calls += 1;
+        let st = self.per_cmd.entry(cmd_name).or_default();
+        let elapsed = t0.elapsed().as_nanos();
+        st.count += 1;
+        st.total_ns += elapsed;
+        if elapsed > st.max_ns {
+            st.max_ns = elapsed;
+        }
+        result
+    }
+
+    /// The real interpreter (separated so [`exec`] can wrap it with timing).
+    fn exec_inner(&mut self, line: &str) -> Result<String, String> {
         let mut it = line.split_whitespace();
         let cmd = it.next().ok_or_else(|| "empty line".to_string())?;
         match cmd {
+            "stats" => {
+                // Substantive telemetry: command volume + latency distribution
+                // + per-C-namespace record occupancy. This is what makes the
+                // daemon measurable, not merely "healthy".
+                Ok(self.stats())
+            }
             "prog" => {
                 let path = it.next().ok_or_else(|| "prog needs <path>".to_string())?;
                 let mut ops: Vec<Op> = Vec::new();

docs/cubeai-vs-cubesys.md

@@ -0,0 +1,109 @@
+# cubeai vs cubesys — was cubeai the intended interface for the 5 crates?
+
+**Short answer: No.** `cubeai` is the *top AI/ML + agent tier* that sits
+*above* the storage substrate (the 5 crates). It was never the interface *to*
+the 5 crates. The intended integration interface for those crates — the thing
+that holds the store and exposes it for use — was `cubed-daemon` (gRPC/HTTP)
+plus `cubecli`, serviced by a `cubesys` integration crate. That role is
+exactly what **`cubesys`** (cube-server + cubec + the shared `Session`
+interpreter) already fills in CUBELinux-2.
+
+This doc is written from the PDF spec (CUBELinux.pdf, extracted to
+/tmp/cubelinux-spec.txt) and the CUBELinux-2 source tree, and is the
+"comparison" the user asked for.
+
+---
+
+## 1. What the PDF actually specified (package arc)
+
+| Package | PDF name        | CUBELinux-2 crate        | In scope? |
+|---------|-----------------|--------------------------|-----------|
+| 1       | cubecoords+cubestore | `cubecoords`+`cubestore` | yes |
+| 2       | cubefs          | `cubefs`                 | yes |
+| 3       | cubevm/cubecode | `cubecode`               | yes |
+| 4       | cubecrypt       | `cubecrypt`              | yes |
+| 5       | XTS             | `cubecrypt` (feature)    | yes |
+| 6       | **cubeai (AI-OS)** | —                      | **excluded on this hardware** |
+
+The PDF's own "Prototype / Minimum Viable Build" section (CUBELinux.pdf,
+prototype outline) defines the *integration* surface separately from the AI
+layer:
+
+- `cubed-daemon` — a standalone server holding the store, speaking gRPC/HTTP
+  (covers `cubefs` FUSE, CLI, and possibly `/v1/...` cloud APIs).
+- `cubecli` — command-line client talking to `cubed-daemon`.
+- `cubesys` — the integration crate binding Packages 3-5 over ONE shared
+  `CubeStore`.
+
+`cubeai` (in the PDF's outline: `cubeai-core` + `cubeai-agent`) is described as
+a *separate* top tier: "the AI/ML + agent layer that would *consume* the
+substrate" — i.e. it is a client of `cubed-daemon`, not the daemon itself.
+
+## 2. Where cubeai would have lived (the layer stack)
+
+```
+   cubeai-agent   (orchestration, planning, tool use)   <- AI tier  [excluded]
+   cubeai-core    (model registry, runs, metrics)        <- AI tier  [excluded]
+   cubedbt        (trace analytics)                      <- [excluded]
+   cubetrace      (execution capture/replay)             <- [excluded]
+   cubed-daemon + cubecli  (store service + client)     <- INTEGRATION [= cubesys]
+   ─────────────────────────────────────────────────
+   cubecrypt  cubecode  cubefs  cubestore  cubecoords    <- the 5 crates [built]
+```
+
+`cubeai` is *above* the dashed line. The 5 crates are *below* it. The dashed
+line is the `cubed-daemon`/`cubecli` boundary — which `cubesys` implements.
+
+## 3. cubeai as specified vs what we built
+
+| Concern            | PDF `cubeai` (intended)                          | CUBELinux-2 `cubesys` (actual)                |
+|--------------------|--------------------------------------------------|-----------------------------------------------|
+| Layer              | Top AI/ML + agent tier                           | Integration tier (the daemon boundary)        |
+| Purpose            | Run models, plan, call tools, learn over traces | Hold the store; expose one command language    |
+| Speaks to crates?  | As a CLIENT of `cubed-daemon`                   | IS the daemon (`cube-server` + `cubec`)        |
+| Storage            | Reads/writes records via `cubed-daemon`         | Owns the `CubeStore<HashBackend>` session      |
+| AI primitives      | model registry, training runs, metrics, agents   | none — deliberately out of scope              |
+| Excluded here?     | YES (would consume the substrate)               | NO — this is the built, in-scope integration   |
+
+Conclusion: confusing `cubeai` with "the interface to the 5 crates" inverts
+the layering. `cubeai` would have been a *consumer* of that interface, not the
+interface itself. We built the interface (`cubesys` == `cubed-daemon` role)
+and deliberately stopped at the dashed line — exactly as the user's directive
+required ("target = PDF vision up to, not including, the AI OS").
+
+## 4. What cubesys actually delivers (evidence, not claims)
+
+- `cube-server` holds a long-lived `Session` over one `CubeStore` and serves
+  it over a Unix-domain socket (`cubec`).
+- `cubesys::commands::Session` is the **single** command interpreter shared by
+  the REPL, the `cubec` socket client, and the daemon, so behaviour cannot
+  drift between front-ends.
+- `./check mount` (27/27) exercised the live FUSE path end-to-end through this
+  same store.
+- `cubesys` is the crate the PDF's "composition layer" implies but never names
+  as Package 6 — it proves the 5 packages interoperate over a *shared* store.
+
+## 5. If we later add cubeai (out of scope now)
+
+Per the spec, `cubeai-core` would be a *new* crate that:
+1. connects to the running `cube-server` over the socket (reusing `cubesys::net`),
+2. treats `cube` programs / VM cells as tools it can invoke,
+3. records model runs/metrics as `CodeCell`s of `Kind::Checkpoint`/`Layer`,
+4. and is fed by `cubetrace`/`cubedbt` (also excluded).
+
+It would NOT modify the 5 crates' APIs — it would sit on top of `cubesys`, the
+interface we already built. So the architecture is forward-compatible: the
+exclusion was a scope cut, not a structural gap.
+
+## 6. Measured reality (./check bench, 2026-08-11, warm in-mem)
+
+These are the success metrics for the built substrate (correctness asserted
+before every timing):
+
+- cubestore: ~6.1M puts/s (164 ns/op), 65 ns/op get, 100k-record scan.
+- cubecrypt: AES-GCM seal 1.4µs / open 2.4µs; ChaCha/XTS ~2.5/4.8µs (1 KB).
+- cubecode VM: 278 ns/op for a cross-cell call-graph run, 137 ns single cell.
+- cubesys: `prog` write 560 ns, `run` dispatch 1.3µs, `ls` directory listing OK.
+
+The substrate is fast and correct; it is ready to be *consumed* by a cubeai
+tier whenever that tier is in scope.