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.

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.
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.
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.
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 multiple boots, manifest unchanged). ALSO (2026-08-13): real OS operational data — cube-os-snapshot.service + cube-os-snapshot.timer (every 5 min + 30s after boot) write genuine OS state (running units, network, resources, journal) into /cubefs/c200/z010/y001/xNNN (rolling 3-digit counter, x-axis is u16→3-digit per cubefs path model). Verified: snapshot survives daemon restart; the OS wrote a NEW snapshot on a fresh boot after a full power cycle; inode == packed CZYX. 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)

Read this file + RESUME-cubefs-daemon.md + REPORT-INDEX.md.
python3 against /root/.hermes/state.db for thread review (sessions table).
CUBE hermes = MEMORY-NOTE; HIST-QNA is the per-exchange log (enforced).
Check live state: systemctl --user -M luulu@ is-active cubed, systemctl is-active cube-upload, pgrep -af qemu, and SSH guest port 2222.
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): make the cube the OS's default storage for a real tree — e.g. have a service write /etc or /var/log operational files through the cube by default. Currently the cube holds OS state (manifest/ identity/klog/snapshots) 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), and a loop/overlay over a cube-backed file would let the OS treat the cube as a real block device.
IMAGE PROVISIONING CAVEAT: the systemd units + scripts live in the VM guest filesystem, NOT in the CUBELinux-2 git repo. If build_vm.sh bakes a fresh image, re-add these units (cube-os-state, cube-os-klog, cube-os-snapshot + timer) to the image provisioning, or they won't survive a from-scratch rebuild.
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).

7.4 KiB Raw Blame History Unescape Escape