# cubeai vs cubesys — was cubeai the intended interface for the 5 crates?

**Short answer: No.** `cubeai` is the *top AI/ML + agent tier* that sits
*above* the storage substrate (the 5 crates). It was never the interface *to*
the 5 crates. The intended integration interface for those crates — the thing
that holds the store and exposes it for use — was `cubed-daemon` (gRPC/HTTP)
plus `cubecli`, serviced by a `cubesys` integration crate. That role is
exactly what **`cubesys`** (cube-server + cubec + the shared `Session`
interpreter) already fills in CUBELinux-2.

This doc is written from the PDF spec (CUBELinux.pdf, extracted to
/tmp/cubelinux-spec.txt) and the CUBELinux-2 source tree, and is the
"comparison" the user asked for.

---

## 1. What the PDF actually specified (package arc)

| Package | PDF name        | CUBELinux-2 crate        | In scope? |
|---------|-----------------|--------------------------|-----------|
| 1       | cubecoords+cubestore | `cubecoords`+`cubestore` | yes |
| 2       | cubefs          | `cubefs`                 | yes |
| 3       | cubevm/cubecode | `cubecode`               | yes |
| 4       | cubecrypt       | `cubecrypt`              | yes |
| 5       | XTS             | `cubecrypt` (feature)    | yes |
| 6       | **cubeai (AI-OS)** | —                      | **excluded on this hardware** |

The PDF's own "Prototype / Minimum Viable Build" section (CUBELinux.pdf,
prototype outline) defines the *integration* surface separately from the AI
layer:

- `cubed-daemon` — a standalone server holding the store, speaking gRPC/HTTP
  (covers `cubefs` FUSE, CLI, and possibly `/v1/...` cloud APIs).
- `cubecli` — command-line client talking to `cubed-daemon`.
- `cubesys` — the integration crate binding Packages 3-5 over ONE shared
  `CubeStore`.

`cubeai` (in the PDF's outline: `cubeai-core` + `cubeai-agent`) is described as
a *separate* top tier: "the AI/ML + agent layer that would *consume* the
substrate" — i.e. it is a client of `cubed-daemon`, not the daemon itself.

## 2. Where cubeai would have lived (the layer stack)

```
   cubeai-agent   (orchestration, planning, tool use)   <- AI tier  [excluded]
   cubeai-core    (model registry, runs, metrics)        <- AI tier  [excluded]
   cubedbt        (trace analytics)                      <- [excluded]
   cubetrace      (execution capture/replay)             <- [excluded]
   cubed-daemon + cubecli  (store service + client)     <- INTEGRATION [= cubesys]
   ─────────────────────────────────────────────────
   cubecrypt  cubecode  cubefs  cubestore  cubecoords    <- the 5 crates [built]
```

`cubeai` is *above* the dashed line. The 5 crates are *below* it. The dashed
line is the `cubed-daemon`/`cubecli` boundary — which `cubesys` implements.

## 3. cubeai as specified vs what we built

| Concern            | PDF `cubeai` (intended)                          | CUBELinux-2 `cubesys` (actual)                |
|--------------------|--------------------------------------------------|-----------------------------------------------|
| Layer              | Top AI/ML + agent tier                           | Integration tier (the daemon boundary)        |
| Purpose            | Run models, plan, call tools, learn over traces | Hold the store; expose one command language    |
| Speaks to crates?  | As a CLIENT of `cubed-daemon`                   | IS the daemon (`cube-server` + `cubec`)        |
| Storage            | Reads/writes records via `cubed-daemon`         | Owns the `CubeStore<HashBackend>` session      |
| AI primitives      | model registry, training runs, metrics, agents   | none — deliberately out of scope              |
| Excluded here?     | YES (would consume the substrate)               | NO — this is the built, in-scope integration   |

Conclusion: confusing `cubeai` with "the interface to the 5 crates" inverts
the layering. `cubeai` would have been a *consumer* of that interface, not the
interface itself. We built the interface (`cubesys` == `cubed-daemon` role)
and deliberately stopped at the dashed line — exactly as the user's directive
required ("target = PDF vision up to, not including, the AI OS").

## 4. What cubesys actually delivers (evidence, not claims)

- `cube-server` holds a long-lived `Session` over one `CubeStore` and serves
  it over a Unix-domain socket (`cubec`).
- `cubesys::commands::Session` is the **single** command interpreter shared by
  the REPL, the `cubec` socket client, and the daemon, so behaviour cannot
  drift between front-ends.
- `./check mount` (27/27) exercised the live FUSE path end-to-end through this
  same store.
- `cubesys` is the crate the PDF's "composition layer" implies but never names
  as Package 6 — it proves the 5 packages interoperate over a *shared* store.

## 5. If we later add cubeai (out of scope now)

Per the spec, `cubeai-core` would be a *new* crate that:
1. connects to the running `cube-server` over the socket (reusing `cubesys::net`),
2. treats `cube` programs / VM cells as tools it can invoke,
3. records model runs/metrics as `CodeCell`s of `Kind::Checkpoint`/`Layer`,
4. and is fed by `cubetrace`/`cubedbt` (also excluded).

It would NOT modify the 5 crates' APIs — it would sit on top of `cubesys`, the
interface we already built. So the architecture is forward-compatible: the
exclusion was a scope cut, not a structural gap.

## 6. Measured reality (./check bench, 2026-08-11, warm in-mem)

These are the success metrics for the built substrate (correctness asserted
before every timing):

- cubestore: ~6.1M puts/s (164 ns/op), 65 ns/op get, 100k-record scan.
- cubecrypt: AES-GCM seal 1.4µs / open 2.4µs; ChaCha/XTS ~2.5/4.8µs (1 KB).
- cubecode VM: 278 ns/op for a cross-cell call-graph run, 137 ns single cell.
- cubesys: `prog` write 560 ns, `run` dispatch 1.3µs, `ls` directory listing OK.

The substrate is fast and correct; it is ready to be *consumed* by a cubeai
tier whenever that tier is in scope.