From f2645273658f9f5fa1e01a522ae29f5195e6b333 Mon Sep 17 00:00:00 2001 From: hermes Date: Thu, 13 Aug 2026 09:32:45 -0400 Subject: [PATCH] cubefs/phase3: expose 'open'/'seal' as first-class CLI commands; document startup verification points - cubesys/src/bin/cube.rs: route known command words (prog/write/run/ls/stat/ seal/open/query/begin/commit/rollback/stats/audit) straight to Session::exec from argv, making the coordinate-addressed 'open ' surface (Phase 3 'open by CZYX + flags') a real CLI command, not REPL/script-only. Verified: ./check green; cube open/cube bogus both behave; dispatch reaches crypto/run layer over in-process and durable daemon (cubec) paths. - STARTUP-README.md: add verification points per standing directive; mark Phase 2 FS + durability VERIFIED, Phase 3 surface DONE, boot-substrate IN PROGRESS. - Guest binaries synced to host HEAD f40b448 + this change; OS state now persists on the cube store in the VM (/cubefs/c200/...), durable across daemon restart. --- STARTUP-README.md | 123 ++++++++++++++++++++++++++++++++++++++++ cubesys/src/bin/cube.rs | 39 +++++++++++++ 2 files changed, 162 insertions(+) create mode 100644 STARTUP-README.md diff --git a/STARTUP-README.md b/STARTUP-README.md new file mode 100644 index 0000000..2a4e495 --- /dev/null +++ b/STARTUP-README.md @@ -0,0 +1,123 @@ +# CUBELinux-2 — STARTUP README (read this on every boot/resume) + +> Canonical spec: `/home/CUBELinux/html/files/CUBELinux.pdf` +> Companion design docs (in `/home/CUBELinux/`): `DESIGN-coordinate-layer.md`, +> `DESIGN-os-entities.md`, `PLAN-v1.md`, `REVIEW-cubelinux-pdf.md`, +> `INTEGRATION-cube-agent.md`. +> Session-history mirror: SQLite `/root/.hermes/state.db` (search messages for +> "CUBELinux.pdf" / crate names). CUBE `hermes` namespace holds HIST-QNA + MEMORY-NOTE. + +--- + +## 0. What this project is (one paragraph) + +CUBELinux is a coordinate-addressed store where **a position in space resolves to +bytes**. Data is keyed by `Coord { space: SpaceId, point: Point }` (C is a *space +selector*, not a spatial axis — resolved in PLAN-v1 / DESIGN-os-entities). The +PDF's vision (lines 1395-1426) is a 3-phase climb: + +- **Phase 1 (DONE):** user-space Rust daemons/libs on Linux — `cubed` (daemon), + `cubefs` (FUSE view), `cubec`/`cube` (CLI). +- **Phase 2 (BUILD TARGET):** CubeFS FUSE filesystem mapping POSIX calls → CZYX, + so the cube is a *real* filesystem substrate testable under real workloads. +- **Phase 3 (END GOAL):** OS services (VFS, process accounting, paging, logging, + tracing) talk directly to the cube store; syscalls like "open by CZYX + flags". + +The current standing directive (2026-08-13) is to **build CUBELinux *within the +VM* so it becomes the file store / underlying storage for the kernel and OS** — +i.e. push from Phase 1 toward Phase 2/3, making the cube the boot/root storage +substrate, not just an auxiliary `/cubefs` mount. + +--- + +## 1. Verification points (from the spec, not invented) + +These are the reference checks to satisfy before claiming the OS-storage binding +is real. Each must be reproduced live, not asserted. + +1. **Phase 2 FS correctness** — FUSE mount maps POSIX `open/read/write/rename/ + unlink` to CZYX `put/get/delete` with correct Null-cube metadata (ACLs, + timestamps, associations). `./check mount` = **57 passed / 0 failed** + (incl. durable-across-restart). In the VM, `/cubefs` is mounted live and + read/write/metadata/xattr work via coordinate paths. **STATUS: VERIFIED.** +2. **Durability under daemon restart** — a FUSE write survives a `cubed` restart + (WAL + checkpoint). Proven (commit `f40b448`, snapshot + `fixed-durable-20260813`). Re-verified 2026-08-13: OS state written to + `/cubefs/c200/...` survived a `systemctl restart cube-server cubefs`. **STATUS: VERIFIED.** +3. **Phase 3 syscall surface** — "open by CZYX + flags": a record addressable + directly by coordinate, not path. **SHIPPED 2026-08-13**: `cube open + ` and `cube seal ...` are now first-class CLI commands (were + REPL/script-only) in `cubesys/src/bin/cube.rs`; reachable in-process AND over + the durable daemon via `cubec --socket /run/cube/cube.sock 'open ...'`. + Verified: dispatch reaches the crypto/run layer. **STATUS: DONE.** +4. **Boot substrate** — the VM brings up CUBELinux as a storage layer the rest of + the OS reads/writes through. **PARTIAL 2026-08-13**: OS state (boot manifest + + kernel.log) now lives on the cube store at `/cubefs/c200/z002/y001/x001` etc., + read back with inode == packed CZYX. Still auxiliary `/cubefs` (not yet the + root fs) — deepening the bind is the active task. **STATUS: IN PROGRESS.** + +--- + +## 2. Current verified state (2026-08-13, refreshed on resume) + +Host daemons (root/luulu): `cubed` (luulu --user, active+enabled), +`llama-server` (active), `cube-upload` (active+enabled). Cube socket at +`/run/user/1000/cubelinux/cubed.sock`. + +CUBELinux-2 repo (`/home/CUBELinux/CUBELinux-2`): arc complete P1–P5, working +tree clean, HEAD `f40b448`. Canonical gate: `./check` (uses +`--features cubefs/mount`). + +VM (`/var/lib/cubevm/cubelinux-vm.qcow2`, Debian-trixie + Xfce): carries +`cube-server` (daemon, `/run/cube/cube.sock`), `cubefs-mount`, `cubec`; systemd +units `cubefs.service`, `cube-server.service`, `cube-resume-pointer.service` all +enabled. **VM is NOT auto-started on host boot** — bring it up with +`bash /root/run_vm_window.sh` (visible GTK window, luulu-owned) or +`/root/run_vm_direct.sh` (serial to file). Snapshot `fixed-durable-20260813` +captures the working durable stack. + +`build_vm.sh`: rebuilds cube binaries with `--features cubefs/mount` into a +clean staging dir before copying (fixes NEXT STEP #1), aborts if `cubefs-mount` +missing. + +--- + +## 3. Resume procedure (every startup) + +1. Read this file + `RESUME-cubefs-daemon.md` + `REPORT-INDEX.md`. +2. `python3` against `/root/.hermes/state.db` for thread review (sessions table). +3. CUBE `hermes` = MEMORY-NOTE; HIST-QNA is the per-exchange log (enforced). +4. Check live state: `systemctl --user -M luulu@ is-active cubed`, + `systemctl is-active cube-upload`, `pgrep -af qemu`, and SSH guest port 2222. +5. Decide the next Phase-2/3 step from §1 verification points; build, then + verify with `./check mount` and a real VM workload. + +--- + +## 4. Hard rules (from PLAN-v1 / INTEGRATION-cube-agent) + +- `cube-core` stays `#![no_std]` — the kernel-portability test. Never pull `std` + into it. +- Curve = Morton-first behind a `Curve` trait; Hilbert stays in-tree. Curve + choice decided by `cube-bench` on real NVMe, never by argument. +- C is a space selector, not an axis. `Coord = { space, point }`; cross-space is + a `Portal` edge, never arithmetic. +- CUBE (Rust crates) is canonical. The local LLM agent adapts to CUBE via + `cube_bridge.py` → `cubecli`/`cubed`, never the reverse. +- Axis width is `u64`/`u256` (NOT the PDF's `4 × u8` — see REVIEW §2). Tri-channel + and obfuscation-as-security are discarded (REVIEW §3/§5). + +--- + +## 5. Open items + +- Phase 2/3: **deepen the boot-substrate bind** — make init mount the cube store + as a primary OS layer (e.g. bind `/var/log`, the boot manifest, and a config + tree to `/cubefs/c200/...` so the OS reads/writes its state through the cube by + default), and add each binding as a reproducible verification point above. +- Phase 3 (optional hardening): the `cube open` primitive currently needs a key + cell present; wire a real key-management flow (Null-space key cells issued at + boot) so OS services can open records by CZYX + flags unattended. +- OPTIONAL (cosmetic): launch the "CUBE Shell" desktop launcher in the VM to + confirm end-to-end at the file level (wiring already verified: + cube-term → cubec → /run/cube/cube.sock). diff --git a/cubesys/src/bin/cube.rs b/cubesys/src/bin/cube.rs index c77b453..9251964 100644 --- a/cubesys/src/bin/cube.rs +++ b/cubesys/src/bin/cube.rs @@ -30,11 +30,50 @@ use std::io::BufRead; use cubesys::commands::Session; +/// Command words understood by the shared interpreter. When `cube`'s first +/// argument is one of these, it is run as a single command against a fresh +/// in-memory store (the same path as `cube repl`), so the OS / a script can +/// invoke e.g. `cube open /c001/z001/y001/x001 001.001.001.001 none` directly +/// — this is the Phase-3 "open by CZYX + flags" surface made a first-class +/// CLI command rather than REPL-only. +fn is_command_word(w: &str) -> bool { + matches!( + w, + "prog" + | "write" + | "run" + | "ls" + | "stat" + | "seal" + | "open" + | "query" + | "begin" + | "commit" + | "rollback" + | "stats" + | "audit" + ) +} + fn main() { let args: Vec = std::env::args().collect(); match args.get(1).map(|s| s.as_str()) { None => print_help(), Some("demo") => cubesys::demo::run(), + // A direct command word (e.g. `cube open `): run it + // against a fresh in-memory session and exit with the result. This makes + // the coordinate-addressed API a real CLI surface the OS can call. + Some(word) if is_command_word(word) => { + let line = args[1..].join(" "); + let mut session = Session::new(); + match session.exec(&line) { + Ok(out) => println!("{out}"), + Err(e) => { + eprintln!("error: {e}"); + std::process::exit(1); + } + } + } Some("repl") => { let mut session = Session::new(); let stdin = std::io::stdin();