# ORACLE-OS-GUEST-NODE-FEDERATION-GOAL.md | | | |---|---| | **Status** | P0+P1 shipped (v9.10.267); P2+P3+P4 **v0 shipped** (v9.10.268). Not full internet-scale mesh. | | **Author** | kai-engineer (owner vision, 2026-07-10) | | **Scope** | Multi-tenant CLOUD Oracle-OS: a stripped "guest view", a KAI **node federation** so separate fleets share knowledge in real time, and rolling **LoRA maintenance windows** that fold new data into the existing model. | | **Relationship to existing tracks** | Extends **`ORACLE-OS-ROLE-SEPARATION-GOAL.md`** (Track F), **`RELEASE-READINESS.md`**, **`KAI-MEMORY-SCALEOUT-GOAL.md`**, **`RSHL-LLM-TRAINING-READINESS.md`** (§6-7), and the **`training/cloud-bitnet/`** finetuner. This is NOT a KAIVERSE task and touches none of the flight controls/pacer. | --- ## The vision (as the owner described it) Oracle-OS will eventually run in the **cloud**. Other people create an account and get a **secondary "guest view"** — a duplicate of the Oracle-OS dashboard with **all admin secrets and server info stripped out**. A guest only sees **their own machine's data** in the dashboard *when they are hosting a KAI **node***. A **node** = a KAI process that connects, from an external machine, into **another person's Fleet Command Center** (the host enables it). This lets KAI gain knowledge across areas/fleets in **real time**, so the AIs in the system get smarter from many sources. Users will *feel* the difference over time because the info is current and **reinforced by many people's feedback loops** on the same/related topics. Model upkeep happens on **weekly LoRA fine-tuning "maintenance windows"**, scheduled per the **time zone the server runs in** (like scheduled maintenance). This **updates the current model(s) instead of retraining from scratch** — the old version is carried forward into the new one via LoRA, not thrown away. --- ## What already exists vs. what's greenfield (grounded in the repo) ### Workstream A — Guest view / role separation · **~60% designed & partly coded** There is already a real owner/admin/member/viewer model, so the "guest view" is an *extension*, not a from-scratch build. - **`ORACLE-OS-ROLE-SEPARATION-GOAL.md`** (Track F) is the source-of-truth plan: split the one dashboard into an owner/admin Command Center and a member/viewer portal; role decided **server-side** and enforced twice. Core doctrine: *"CSS/JS hiding is UX, not security. Every gate is enforced twice."* - **`command-center-server.mjs`** already has: `ROLES = ['owner','admin','member','viewer']`, `ROLE_RANK`, `ROLE_DEFAULT_PERMS`; a users registry (`state/cc_users.json`); tokens stored hashed (`sha256(salt+token)`); owner seeded from env **`CC_CONTROL_TOKEN`**; `currentUser(req)` role resolution; `requireRole`/`requireControl`/`requireOwner` gates; `/api/me` reporting `role/isOwner/isAdmin`. Control + user-management endpoints are already role-gated. - **`oracle.html`** already defaults to least privilege: `` with `body.scope-member [data-needs="admin"]{display:none}` and a Humans/Guests panel that defaults unknown users to **"Lattice Guest."** - **Open hardening (the part that matters most for a public cloud guest):** several read endpoints still leak host/server info to any authenticated user — `/api/system-stats` (full CPU/RAM/GPU/disk/host), `/api/logs`, `/api/tests` are not role-filtered. A cloud guest view MUST filter these **server-side**, not with CSS. ### Workstream B — Nodes / federation · **Greenfield (does not exist)** There is **no** peer-to-peer / node / cross-fleet networking today. Everything is local or an outbound client to a cloud LLM API. - `PEER_SETUP.md` "peers" = external **LLM providers** (Gemini/Grok/Groq/Ollama), not machines. - `Connect-KAI-Brain.ps1` = toggles local BitNet brain env vars; not remote. - `connectivity.mjs` = "are we online?" TCP probe only. `realtime-bridge.mjs` = outbound WS client to OpenAI Realtime. `fleet-protocol.mjs` = Ryan controlling **his own** fleet from his phone via Discord. `/ws/voice` = same-origin browser↔server audio. - **No federation/gossip/mesh/handshake/peer-server anywhere.** The whole node concept — a KAI process authenticating into someone else's command center and exchanging knowledge — is net-new and is the largest and most security-sensitive build here. ### Workstream C — Cross-node knowledge reinforcement · **Single-node reinforcement exists; cross-node aggregation is new** The "reinforced by many people's feedback loops" mechanism partly exists — but only within one machine. - `overnight_pipeline.py` already does **error-weighted reinforcement**: `base_strength = 0.5 + error * 2.5`, weak areas get a retention boost. The Rust CLS layer (`hippocampus.rs` `consolidate_into_universe()`) **reinforces an existing cell instead of re-storing** when it already knows something (cosine > 0.65), and a **survival-count** gate means repeated exposure over time strengthens memory; `sleep.rs` does replay/downscaling. - Per-user memory exists (`/api/oracle-turn` with `user_id`, `user-warehouse.mjs`) but user isolation is only partial (shared lattice cross-talk risk noted in `RELEASE-READINESS.md`). - **Missing:** any aggregation of knowledge/feedback **across nodes**, and the trust/spam/consensus controls you need before letting many external fleets write into a shared knowledge picture. This rides entirely on Workstream B existing first. ### Workstream D — LoRA maintenance windows · **Real machinery exists; scheduler + one correction needed** - `training/cloud-bitnet/finetune_bitnet.py` — real BitNet b1.58 finetuner with a **`--mode lora`** path (PEFT, `--lora-r/--lora-alpha`), exports back to ternary GGUF the Rust engine loads. - `training/cloud-bitnet/auto_finetuner.py` — an **"Everlasting Auto Finetuner"** *skeleton*: buffer-watch → assemble {new batch + replay} → **LoRA finetune (base untouched)** → **eval-gate vs served model** → promote by merge+requantize+hot-swap **only if no regression, else discard the adapter**. Exactly the "fold new data in, don't retrain from scratch, keep the old version" idea. Forgetting guards (`LORA_LR=1e-4`, `LORA_EPOCHS=1`). - `RSHL-LLM-TRAINING-READINESS.md` §6-7 already frames this as a nightly maintenance window ("pretrain is capex you rent once; consolidation is opex you run at home"), eval-gated, rollback-able adapters. - **Two gaps:** (1) it's a non-auto-running skeleton — merge/requantize/hot-swap is `# TODO(wire)`, and it relies on an **external** cron/Task Scheduler; there is **no per-timezone / weekly scheduler** yet. (2) **Important correction to the mental model — see below.** > **⚠️ Correction the owner should know: LoRA does NOT apply to the RSHL lattice.** KAI's core RSHL lattice is genuinely non-transformer with **zero neural weights** (`SparseVec::encode` is a fixed hash — not differentiable, "you cannot backprop the lattice"). A LoRA can only apply to the **BitNet/LLM "brain" module** (`src/cognition/bitnet_llama.rs`, mounted when `KAI_NATIVE_BRAIN=1`) — the optional language model, not the memory substrate. So the plan is: **the lattice keeps reinforcing itself** (Workstream C, already real); **its consolidated memory becomes the replay/training data** for a **weekly LoRA on the BitNet brain** (Workstream D). Two different mechanisms, and that's the correct design per the readiness docs. --- ## Security model (the part you get one chance to get right) A cloud, multi-tenant, federated system inverts KAI's current trust assumptions (today it trusts its own box). Non-negotiables: 1. **Server-side redaction, always.** The guest view must be a *different server response*, not the same data hidden with CSS. Guests never receive admin tokens, `.env`-derived config, host telemetry, logs, transcripts of other tenants, or control endpoints. Enforce on every endpoint by role (close the `/api/system-stats` / `/api/logs` / `/api/tests` leaks first). 2. **Tenant data isolation.** "Their machine's data only" means every read is scoped to the caller's tenant/node ID at the query layer — not filtered client-side. A guest hosting a node sees *their* node's telemetry; never another tenant's. 3. **Node authentication + authorization.** A node joining someone's command center needs a mutual handshake (issued node credential, not a shared secret), an explicit host **enable/allow** step, capability scoping (what a node may read/share), rate limits, and instant revocation. 4. **Federated-knowledge trust.** Incoming knowledge from external nodes must be treated as **untrusted**: provenance-tagged, quarantined, consensus/again-seen-weighted before it can reinforce anything, and never able to overwrite owner-verified beliefs. Poisoning/spam defense is a first-class requirement, not an afterthought. 5. **Secrets never leave the owner's machine.** Per the existing hard rule — the guest/cloud path must be architected so `tools/oracle-discord/.env` values are never serializable into any tenant-facing response or node exchange. --- ## Phased plan (each phase flag-gated, reversible, independently shippable) **P0 — Guest-view hardening (extends existing Track F; no federation needed; safe to start now).** Close the server-side read leaks: role-filter `/api/system-stats`, `/api/logs`, `/api/tests`; guarantee a guest response contains no host/admin fields. Add a "cloud guest" role tier below `viewer`. Deliverable: a guest can log in and see a sanitized dashboard with **zero** server/admin info. Verifiable by diffing owner vs. guest API responses. **P1 — Multi-tenant account + data scoping.** Real accounts (the registry already exists), tenant IDs, and query-layer scoping so a tenant only ever reads their own data. Still single-server; no nodes yet. This is the backbone the guest view needs to be true multi-tenant. **P2 — Node protocol v0 (the big one).** Design + build the node handshake and transport: a KAI process on machine B authenticates into machine A's command center (host must explicitly enable it), with credentialed auth, capability scoping, heartbeat, and revocation. **Start read-only** (a node can register + report *its own* telemetry to the host it joined) before any knowledge write. This is greenfield and the security-critical core — design doc + threat model before code. **P3 — Federated knowledge exchange.** On top of P2: nodes share *consolidated, provenance-tagged* knowledge. Incoming knowledge is quarantined and only reinforces via the existing cosine-gated / survival-count machinery once corroborated. Add feedback-loop weighting across nodes with poisoning defenses. This is where "users feel it get smarter over time" becomes real. **P4 — Weekly per-timezone LoRA maintenance windows.** Wire the `auto_finetuner.py` skeleton's TODOs (merge/requantize/hot-swap), add a **scheduler** keyed to the server's time zone with a weekly cadence, feeding **lattice-consolidated replay data** (Workstream C) into an **eval-gated LoRA on the BitNet brain** (Workstream D), with versioned rollback. Old model → new model via adapter, never a from-scratch retrain. **Suggested order:** P0 → P1 → P2 → P3 → P4. P0/P1 are low-risk extensions of shipped code and deliver a usable sanitized guest view early. P2/P3 are the ambitious, security-heavy, multi-month greenfield. P4 can proceed in parallel with P1-P3 since its machinery is separate. --- ## Honest feasibility This is a **major, multi-month architecture** — realistically the biggest single initiative in the project — not a quick build. The good news: **~half of it has scaffolding already** (roles, hashed tokens, per-user memory, error-weighted reinforcement, a real LoRA finetuner + continual-update skeleton, and a written plan for the nightly-window model). The genuinely hard, genuinely new parts are **B (node federation)** and **its security/trust model** — those are greenfield and must be designed carefully before any code, because a mistake there leaks one person's machine/secrets to another. Compute-wise the guest/cloud/dashboard side is light; the LoRA windows need a real GPU on the cloud host (the docs already assume cloud pretrain + home adapt). ## Costs / dependencies to decide before building - **Cloud hosting** for the multi-tenant server (and a **GPU** host for P4 LoRA windows). - **Node transport choice** (authenticated WebSocket vs. something like libp2p) — a P2 design decision. - **Reuse vs. rebuild:** `OpenJarvis-main/` contains a separate third-party LoRA/scheduler stack — it is NOT KAI-native RSHL code; decide deliberately before borrowing from it. - No new paid API is required for P0/P1 (they extend existing code). ## Not done here (per convention) Investigation + plan only. No shipped code edited, no restart, no version bump. Building starts with **P0** (guest-view server-side redaction) once you confirm — it's the safe, high-value first slice and needs no federation.