# 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. **DONE (systemd-managed, 2026-08-13)**: units `cube-os-state.service` (oneshot, writes boot manifest + machine identity + boot history to `/cubefs/c200/z001|z002|z003`) and `cube-os-klog.service` (streams kernel ring buffer to `/cubefs/c200/z004`) run at boot; both enabled + active; state survives a FULL power cycle (verified 2026-08-13: rebooted the VM, boot history showed pre- + post-reboot lines, manifest unchanged). **STATUS: DONE (auxiliary layer; not yet the root fs).** --- ## 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 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. - Boot substrate (next deepening): bind a real OS tree (e.g. `/var/log`, `/etc` config, the boot manifest) so the OS reads/writes through the cube by default — currently the cube holds OS *state* (manifest/identity/klog) but the root fs is still ext4. The magic-prefix "open by CZYX" FUSE passthrough is the natural next step (a path like `/cubefs/.czyx/200.1.1.1` resolves directly to the coordinate). - 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).