cubelinux-2/docs/cubeai-vs-cubesys.md

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 CodeCells 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.