CUBELinux-2
35e5183193
Integrates Packages 3-5 over a single shared CubeStore, the literal CUBELinux premise (data addressed by coordinate, not path). Adds the cubesys crate (lib + cube CLI + cube-demo) proving two end-to-end properties: a cubefs path IS a runnable code cell at the same coordinate, and a sealed record reopens and runs on the same store. Two latent cross-crate bugs surfaced and fixed while integrating: - cubecoords: refresh_flags() now preserves out-of-band flag bits (8..=15), so cubecrypt's HEADER_FLAG_ENCRYPTED survives refresh. - cubestore: record codec now serializes raw flag bits (TLV tag 12) so the encrypted bit survives the store round-trip. All gates green (./check, incl. cubefs --features mount).
91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
# 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
|
||
```
|