cubelinux-2/STARTUP-README.md

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 <path> <K.Z.Y.X> <tf> 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).