# CUBELinux-2 system integration (`cubesys`)

This crate is the composition layer the PDF implies but does not name as a
"Package 6". It binds Packages 3-5 (cubefs, cubecode, cubecrypt) into one
running system over a **single shared `CubeStore`**, which is the literal
CUBELinux premise: *data addressed by coordinate, not path.*

## The one invariant

> The cube is the single source of truth. cubefs is a *view* of it, cubecode
> is a *kind* of record in it, cubecrypt is a *transform* applied to records
> in it. None of them own storage.

That is what makes the integration real instead of three crates side by side:
every layer operates on the same backend, so a write through one is visible to
the others at the same coordinate.

## What binds to what

| Layer        | Role in the system                                   | Shares via                       |
|--------------|------------------------------------------------------|----------------------------------|
| `cubefs`     | POSIX namespace; a path `C/Z/Y/X` is a coordinate    | `CubeStore`, `path_to_czyx`      |
| `cubecode`   | code cells stored *as records*; VM runs them         | `CubeStore`, `CodeCell`          |
| `cubecrypt`  | seals records under a `CubeEnv`; key in Null cubes    | `CubeStore`, `CubeEnv`           |

Two primitives in this crate do the binding:

* `path_to_czyx(path)` — the single bijection (re-exported from `cubefs`) so
  path and coordinate never disagree.
* `load_code_cell(store, path)` — reads the record at a path's coordinate and
  decodes it as cubevm bytecode. A cubefs file **is** a runnable VM cell.

## End-to-end properties proved by the tests

1. **A path is a function.** Writing bytecode at `/c012/z001/y001/x021` makes
   cubefs list it as a file *and* the VM run it at `Czyx::new(12,1,1,21)` —
   same coordinate, two views. (Note: an axis value of `0` is Null control
   space and is rejected as a path component, so every user path maps to a
   coordinate with all axes in `1..=255`; keys and metadata live in Null
   space and are addressed directly by `C.Z.Y.X`.)
2. **Seal then run is the same record.** `CubeEnv::put_encrypted` at a
   coordinate leaves the cube carrying an encrypted body (encrypted flag set);
   the raw body no longer decodes as bytecode. To *execute* a sealed record the
   system decrypts it back into a plaintext record at the same coordinate, then
   runs the VM (the VM runs code located by coordinate; reading the envelope
   directly would fail decode). `open` + `CodeCell::from_record` + `Vm::run`
   recovers and executes it on the *same* store.

## Bugs found and fixed while integrating (real, cross-crate)

Building the integration turned up two latent cross-crate bugs that the
per-package test suites never exercised:

* **`CubeHeader::refresh_flags()` dropped out-of-band flag bits.** It recomputed
  `flags` only from structured fields (bits 0–7), so `cubecrypt`'s
  `HEADER_FLAG_ENCRYPTED` (bit 12), which is set out-of-band, was wiped on every
  refresh. `put_encrypted` calls `refresh_flags` before storing, so an encrypted
  record lost its flag. Fixed by preserving spare bits (8..=15) in
  `refresh_flags`. (`cubecoords`)
* **The record codec never serialized `flags`.** `record_codec::encode_header`
  wrote only structured fields, and `decode_header` rebuilt `flags` from them —
  so even a correctly-set encrypted bit was lost on the store round-trip. Added
  tag `12` (raw flag bits) to the TLV codec so out-of-band bits survive.
  (`cubestore`)

Both are now guarded by `cubesys` integration tests.

## Why this, and not a "Package 6"

The PDF arc ends at cubecrypt; the only named next package is `cubeai`, which
the directive explicitly excluded (hardware cannot run it). Integration is the
honest completion: it turns five isolated crates into the coherent
coordinate-addressed system the design describes, without inventing a package
the spec never defined.

## Binaries

* `cube-demo` — self-contained tour (write two linked cells, run; seal a
  record, reopen + run). Prints evidence at each step.
* `cube` — CLI: `write`, `run`, `ls`, `stat`, `seal`, `open` over one store,
  interactively (`repl`), from a file (`script`), or as the demo (`demo`).

## Building / testing

```sh
cd /home/CUBELinux/CUBELinux-2
./check quick      # fmt + clippy -D warnings + tests (the gate)
./check mount      # also builds cubefs --features mount (FUSE adapter)
cargo run -p cubesys --bin cube-demo
```