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.
This commit is contained in:
cube-agent
@@ -7,6 +7,7 @@ members = [
|
||||
"cubecode",
|
||||
"cubecrypt",
|
||||
"cubesys",
|
||||
"cube-bench",
|
||||
]
|
||||
|
||||
[workspace.package]
|
||||
|
||||
@@ -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; }
|
||||
|
||||
@@ -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]
|
||||
@@ -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 ===");
|
||||
}
|
||||
+89
-1
@@ -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();
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user