CUBE-OS

The coordinate substrate of CUBELinux: a store addressed by coordinate, a command language over it, the boundary that turns names into coordinates at the edge — and, since this tree grew its half of it, a kernel that holds the store and answers cube(2). The userspace crates are below; the kernel driver is kernel/CUBELinux/drivers/cube/, and the plan it implements is PLAN-kernel-cubelinux.md.

Two products live under this name, and they are not the same thing. This tree is CUBE-OS (the kernel owns the store; cube(2) #548; the v3 addressed image; the workspace suite in crates/). CUBELINUX-2 is the older one — a userspace daemon holding the store, with the cube-mvw/cubetrace/ballindex work — and it lives elsewhere. A claim about "CUBELinux" is ambiguous until it says which; the website's front page currently carries CUBELINUX-2's.

coordinate substrate (§5)          the boundary                    the edge
cube-core  cube-store  cube-header  cube-command  cube-daemon      cube-names
cube-index cube-crypt  cube-store-raw cube-client cube-cli         (name -> coordinate)
cube-format cube-kernel cube-store-seal

The shape of it

• A coordinate is SpaceId (256-bit) + Point (three u64). Nothing here is addressed by name or path. czyx:c,z,y,x is the published four-axis spelling of a subregion, not a second model.
• The language (cube-command) is one implementation shared by every front-end: put, get, del, cell put|get|del, range, list, spaces, hdr, link, out, follow, keys, seal, open, czyx, checkpoint. A value is text, or hex:<digits> for bytes.
• The daemon (cubed) holds one store and serves the language over a Unix socket; a mutation is acknowledged only once it is durable in the write-ahead log. One writer, one store — that is why a daemon exists at all.
• The client (cube-client) is the other half of the socket, and DaemonStore presents the daemon's store through the Store contract.
• The kernel (cube-kernel over cube(2)) presents the kernel's store through the same Store contract, so code written against Store addresses the kernel without knowing it.
• The name tier (cube-names) accepts the name-addressed protocol the machine's older services speak, maps it with Coord::named, and runs the command against the daemon. It is the edge, not the substrate — and, with the FUSE view, the shape the path-based compatibility layer takes. Why it is at the edge rather than in the core is a decision, not a stage: DESIGN-cube-interface.md §2.

Quickstart

cargo build --release --workspace

# serve a store (write-ahead log beside the image is the default)
./target/release/cubed --store /tmp/demo.store --socket /tmp/demo.sock

# talk to it — the same verbs a local store runs
./target/release/cubecli --socket /tmp/demo.sock put root:1,2,3 hello
./target/release/cubecli --socket /tmp/demo.sock get root:1,2,3
./target/release/cubecli --socket /tmp/demo.sock put czyx:2,3,4,5 hex:001bff
./target/release/cubecli --socket /tmp/demo.sock list root

The gates (run before calling it done)

cargo test --release --workspace          # 183 tests
cargo clippy --release --workspace --all-targets   # 0 warnings
bash kernel/run-all-gates.sh              # every gate, one verdict, claims named
./target/release/cube-image verify /root/workspace/cube-snapshot.img
cargo build --release -p cube-core --target thumbv7em-none-eabihf
python3 cube_duratest.py                  # acknowledged writes survive SIGKILL
bash deploy/verify-name-tier.sh           # the full name-tier path, on /tmp sockets

kernel/run-all-gates.sh is the one that answers "is it done": it runs every verify-*.sh, reports each gate against the claim it makes, and reports a gate it cannot run as skipped with the reason rather than as a pass. A gate whose verdict lives only in someone's terminal scroll is not a gate, which is why the cost numbers below name the gate that produces them.

The crate map

Crate	Role
cube-core	Coord, SpaceId, Point, curves, Czyx, WordFlags/TriWord/HeaderFlags
cube-store	the Store contract, MemStore, FileBackedStore, the write-ahead log
cube-store-raw	the pinned 24-byte-key image format
cube-format	the store's byte format, including the kernel driver's own cube_format.rs — one file both builds compile, so the two cannot drift
cube-header	CubeHeader, HeaderStore, association edges
cube-index	AdjacencyIndex, portals
cube-crypt	sealing, the OS keystore
cube-store-seal	a store whose records are sealed, transparently
cube-command	the command language, one implementation for CLI and daemon
cube-daemon	cubed — one store, served over a socket
cube-client	the client half of the socket; DaemonStore
cube-cli	cubecli — the operator CLI, local or --socket
cube-kernel	the Store contract over cube(2) — the kernel's store, same verbs
cube-names	the name tier at the edge (name → coordinate)
cube-image	reads/writes/verifies the pinned image
cube-bench	block-read benchmarks, the on-ramp for the kernel read path

What the website claims, checked against this tree

The website says the coordinate layer is wired into the VFS and that the OS stores itself. The first of those is not a claim this project makes, and has not been since DESIGN-cube-interface.md §2 rejected a mount in the core; the second is true of the store and not of every record. The wording is a known open item, tracked at the bottom of this file.

Shipped and verified. cube(2) is syscall #548, with PUT, GET, DEL, SYNC and the cursor walk (ENUM/SPACES, versioned by the size of its argument block). The image is addressed — a space table, a fixed-stride index sorted by key, values packed in index order — so a coordinate is not only a way to name a record but a way to reach one: the index is a binary search over arithmetic offsets, and a power-of-two-aligned region is one contiguous run of it. The kernel's listing and userspace's listing of the same bytes agree record for record. The fold that converted the live 69,638-record store to the addressed layout preserved every value — identical fnv1a64=341dc1e38791052d before and after.

What the numbers are, and where they come from. Every figure here is produced by a gate in kernel/, on request, rather than remembered:

claim	gate	measured
a walk costs what it returns, not what the store holds	verify-enum-cost.sh	listing the same 10 records in a 500-record and a 20,000-record store: 5.46 ms → 6.24 ms (1.1×, store grew 40×)
reaching a coordinate is cheap and stays cheap	verify-enum-cost.sh	get 2.45 ms → 2.17 ms; a coordinate that is not there 2.39 ms → 1.76 ms
the box's own store is walked through cube(2)	verify-enum-live.sh	11 spaces, 69,638 records; the kernel's walk and userspace's agree line for line

Those are VM figures (QEMU, q35, -m 1024), and they are a syscall round trip on a durable store — a different contract from the nanosecond numbers the website still quotes, which came from an in-process, memory-resident store in a daemon that no longer holds it. The store is opened per call, which is where the remaining milliseconds are.

The kernel records its own boot. As of build #52 the kernel can append a record of itself — its own version banner, the wall-clock time, and the store device it resolved — at its first write of a boot, into the reserved space 0xFC, addressed by the name boot. Nothing in userspace writes it: the gate writes once to trigger it, reads it back through cube(2), and then reads the same bytes out of the folded image with cubecli, so the record is a record in the shared format rather than a kernel-private side channel. It is off unless the boot asks for it (cube_boot_record=1), and that is an invariant rather than caution: the gates' method is that the store the kernel produces is comparable byte for byte with userspace's, and an unrequested injected record would end those comparisons. kernel/verify-boot-record.sh is the gate. It is not installed — /boot still carries build #50 — so this is a capability with a gate, not yet a deployed behaviour.

Not shipped, stated so it is not mistaken for done. The store is not sealed at rest: 0 of its 69,638 records are sealed, so their text is readable with or without any password (kernel/kill/README.md says this plainly, and it is the honest state of the switch). The kill switch is built, rehearsed and unarmed. And the boot marker in service is still a userspace write through the name tier — while the kernel's own record above is opt-in and deployed nowhere. Be precise about which file, because there are two and only one of them runs: this tree's deploy/boot_marker.sh writes the coordinate boot:0,0,0, but the installed cube-agent-boot.service actually executes /home/luulu/.cubelinux-agent/boot_marker.sh, which POSTs {"cmd":"write","namespace":"memory","name":"last_boot"} to cubed-names.sock. So the marker in service is a name-tier write by a file that is not in this repository, and the coordinate version here is not the one running. Two things remain, and they are different: the unit should point at a path the tree owns, and somebody has to decide whether the kernel's record supersedes the client's marker or answers a different question beside it.

The kernel that is running, which is the one claim here most easily got wrong. Build #50, 6.19.3-cubelinux0.6+, is built from this tree, is installed at /boot/vmlinuz-6.19.3-cubelinux0.6+ (sha256 beb6f38f8eb5937e…, identical to the tree's bzImage), and booted the box with cube_store=/var/lib/cubelinux/store.img — which is where every gate above was green. But GRUB's default entry is deliberately a different kernel, the older 6.19.3-cube+, so the machine is always recoverable and an ordinary reboot lands back on it. That older kernel carries no CUBELINUX configuration at all: no cube_store=, no /dev/cubelinux, and no cube symbol in /proc/kallsyms. On a boot like that there is no cube(2) to refuse anything — a spaces through the live socket answers ENOSYS, Function not implemented, because there is no interface there rather than a closed one. So: read /proc/cmdline for cube_store= before believing any sentence about "the kernel", including the ones above.