--- name: robco-os-architecture description: "The owner-approved DESIGN PHILOSOPHY for RobCo U.O.S. — OS-first/campaign-second, the taxonomy, the core subsystems, and the rulings that constrain how they get built." metadata: node_type: project originSessionId: robco-os-architecture --- **Owner-approved 2026-07-01 (from an external architecture review round). This is the guiding design PHILOSOPHY the roadmap converged on — not features, the frame that makes the whole thing coherent.** It aligns with [[player-control-principle]] + the save↔terminal-meta boundary + diegetic-first. > **What is NOT in this file, on purpose:** which of these subsystems have shipped, what version they landed in, and any measurement of the codebase. Those are in `CHANGELOG.md`, `QUEUE.md`, `library/CODE_MAP.md` and the test output, and every copy of them here rotted. This file holds the *decisions and the reasoning*, which don't drift unless the owner changes his mind. ## TOP-LEVEL PRINCIPLE — OS first, campaign second RobCo U.O.S. is a **fictional operating system that happens to manage Fallout campaigns** — not primarily a Fallout companion. The clean split: the **OS layer** (the terminal itself — would RobCo have manufactured this in 2077?) vs the **campaign layer** (tracking your playthrough). **The test for where any future idea belongs:** "Would this make sense if RobCo actually built this terminal in 2077?" → yes = OS layer; "only because it's tracking a Fallout playthrough" → campaign layer. Reinforces the hardware↔campaign-state boundary. ## TAXONOMY — nothing is a "feature" Everything is a **command · document · device · or service** (no "feature / panel / mode" in user-facing language). Renames (examples): Quest Tracker → **QUEST DATABASE**; Combat Log → **AFTER ACTION REPORT**; Settings → **SYSTEM CONFIGURATION**. This is the backbone of the diegetic house standard ([[parked-diegetic-audit]]). ⚠ Bounded by the owner's clarity veto recorded there: in-theme but never confusing — *"do not rename inventory to manifest."* ## ★ FOUNDATIONAL — the terminal STATE MACHINE (the single biggest architectural idea) The terminal has **operating states**: `OFF → COLD BOOT → READY → ACTIVE → IDLE → STANDBY → (ACTIVE) → SHUTDOWN → OFF`. Hardware Life, WASTELAND UPLINK, day/night, weather, radio, idle behaviors, shutdown are NOT independent systems with their own timers — they are **observers that react to state transitions.** (Radio changes because the terminal entered ACTIVE; idle messages because it entered IDLE; fan spins down because SHUTDOWN.) One common **heartbeat**, many observers, instead of dozens of timers. The terminal's OPERATING state is distinct from GAME state (respects the boundary). Keep it lightweight — the value is the one-tick/observer pattern, not FSM ceremony. ## THE CORE OS SUBSYSTEMS (each has ONE job — this is what keeps many metaphors from becoming soup) - **Ambient Runtime = State Machine + Scheduler.** State machine = what MODE the terminal is in; **RobCo Scheduler** (not user-visible) = WHEN timed events fire (broadcasts, anniversaries, weather, maintenance, welcome-back, daily boot). Together they ARE the "one heartbeat." All ambient systems subscribe. - **Launcher + Command Language = how you INVOKE things.** The launcher gets a **Norton-Commander / DOS-Shell** feel (SYSTEM > DATA/WORLD/COMBAT/CHARACTER/SERVICES/HARDWARE, arrow-keys, instant, never scrolling). And **commands become a first-class LANGUAGE** so power users stop touching the launcher — very Fallout. ⚠️ **GUARDRAIL: the command language is ADDITIVE (power path); the touch/launcher path stays first-class** (mobile + accessibility + game-agnostic). - **Filesystem = how documents/content are organized + navigated** (SYSTEM/, ARCHIVES/, INTERCEPTS/, MANUALS/, USER/, LOGS/). **Manuals live here** — `HELP` opens `SYSTEM/MANUALS/`, not a separate place. - **Module Bay = INTERNAL capabilities** (boards you install — the diegetic Settings). vs… - **★ Peripheral Bus = EXTERNAL connected devices** (owner's favorite new system — *"explains features instead of adding them"*). Weather, signal-scan, Pip-Boy sync, radio, TTS, share-target, gyro, ambient-light all become **DEVICES on the bus, not random capabilities.** This solves the "gyro feels like a phone gimmick" problem (it's the terminal's orientation SENSOR peripheral), and the **Pip-Boy — identity anchor #1 — is literally the marquee peripheral.** - **★ RobCo Distribution Network = how content/updates ARRIVE** (merge of remote transmissions, expansion packs, firmware, roadmap, manual updates, intercept packs, seasonal broadcasts). ONE update channel, many payload types. **The free/offline invariant holds** — ships offline/local by default; the network is the optional live-delivery channel ([[project-must-stay-free]]). - **Terminal Record = the ONE canonical history** (campaign + hardware views; gameplay-history in the save, hardware-history in the meta-store). - **System Status = the ONE machine-health home** (System Stats + Diagnostics + Maintenance + Condition + Telemetry merged). ## MERGES / CUTS folded in - **Signal Scanner → a command inside INTERCEPT** (scanning is how you OBTAIN intercepts, not its own system). - **Manuals → filesystem** (`HELP` → `SYSTEM/MANUALS/`). - **Corporate handshake → part of COLD BOOT, once** (commissioning the machine; never a separate step). - **RENAME "Expansion Packs"** (too game-y for hardware) → **Data Cartridges**, a payload type under the Distribution Network. - **Macros** — optional local terminal automation riding on the command language. Nice-to-have, low priority, additive. ## ⭐ RULINGS THAT CONSTRAIN THE BUILD (owner, 2026-07-08) These are the parts that must survive; the shipped-state inventory that used to sit here has been removed as derivable. - **ADAPTATION — extend, never re-invent.** The command-language plan must EXTEND the already-shipped native-command and TERMINAL-mode grammar. The launcher must COEXIST with the shipped bezel nav (additive power-path; the bezel stays first-class). System Status is already reorganized — don't re-merge it. The Peripheral Bus should ABSORB the shipped OCR/Visual-Upload as an "optical scanner" device. The Filesystem should house the manuals, changelog and reference content that already exist. - **⚠ HARD CONSTRAINT — reframing must not relocate.** Reframing OCR as a Peripheral-Bus device must **NOT** remove it from the UPLINK composer. The Visual-Upload `[+]` scan must REMAIN usable in the UPLINK tab. It is exposed in BOTH places. Additive reframe, never a relocation that breaks an existing entry point. - **ADD-IDEAS — ALL APPROVED** (*"add all of those to the OS round"*): a real command PROMPT/CLI; Peripheral Bus devices; DATA CARTRIDGES; MACROS; in-universe REFERENCE DOCS in the filesystem ([[docked-ideas]]); an INTERCEPTS INBOX; a BOOTLOG document. - **⭐ CONFIRMED — the bezel DIR keycap FORMALLY BECOMES THE FILESYSTEM HOME.** DIR evolves from the flat subsystem-nav fallback into the real filesystem BROWSER. **Rule of thumb, locked: if you READ it, it's a file under DIR** (manuals, reference/lore, glitches ref, INTERCEPTS inbox, BOOTLOG, holotape logs); **if you OPERATE it, it's its own surface** (command prompt, Peripheral Bus, Distribution Network, macros). - **⭐ REPURPOSED — the old flat "jump to any subsystem" directory becomes the SCHEMATIC VIEW**, added to every tab/subsystem: a flat/compact alternative representation preserving the old mental model, muscle memory, accessibility, and the `[0]`/DIRECTORY hotkey. See [[per-game-device-form]]. **Net: this round adds essentially NO net features** — it CONSOLIDATES the roadmap into a small set of clean OS subsystems plus a philosophy. Everything already planned now has a precise architectural home. --- # ⭐⭐ THE ENGINEERING HALF — added 2026-07-13 by [[architecture-review-2026-07-13]] **Everything above is the FICTION of an operating system** — features that LOOK like an OS. The owner separately proposed an "Architecture Modernization Initiative" (service ownership, event decoupling, one scheduler, one state owner, per-subsystem diagnostics, plugin game registration) — that is the **ENGINEERING of an operating system.** ⇒ **VERDICT: they are ONE initiative, two views. Not two projects. Do NOT open a second roadmap** — the engineering work is *subtractive* (closing leaks, standardising), so a parallel "modernization roadmap" would be a roadmap to add nothing. ⚠⚠ **THE RISK THIS ROUND MUST NOT REALISE:** *the OS round becomes "add OS features" when it should be "formalize the engineering principles that already emerged."* If those drift apart, the round ships OS-flavoured features on unchanged internals and the engineering work is needed anyway, later, at higher cost. ## ⇒ WHY A HARDENING PASS RUNS BEFORE THE NEW SERVICES **Every headline feature above is a NEW SERVICE** (the CLI, the Filesystem, the Peripheral Bus, the Distribution Network) — and **each one is aimed directly at a spot that was already weak.** The argument for closing these first is about *multiplication*, not about any particular count: 1. ⭐ **The UI↔services cycles belong on the event bus.** Services call view render functions directly, and the render layer writes saves — so the render layer became a second state manager. Correct shape: **service mutates → EMITS; view LISTENS and repaints itself.** The bus already exists and was already used for feedback fan-out; it was simply never pointed at the repaint path. ⚠ **If the four new services are built like the existing ones, they don't inherit the cycles — they MULTIPLY them, and hard-wire "services are the second UI controller" into the marquee architecture.** 2. **State encapsulation:** direct `state.x =` writes in feature code. **The specced CLI ("edit any stat, run any tool") points a large number of NEW uncontrolled writes at exactly this.** Drain toward intent functions — evolutionary, never a freeze. 3. **Boot isolation:** boot phases run under ONE outer `try/catch` with no per-phase isolation. Three new OS boot surfaces land here; any one throwing silently amputates everything after it. Fix = a phase registry. No behaviour change. 4. **Event bus gaps:** no `off` / `once` / dedup — correctness rests on an unenforced "wire once" convention — plus a silent `catch (_)`. 5. **The Scheduler is ALREADY BUILT** — the "one heartbeat" idea shipped. Watch for escaped intervals, and **fix any comment in `runtime.js` / `ui-core.js` still claiming the module owns no timers.** **✅ Protocol 23 IS enforced.** Suite 236 (`tests/arch-conformance-check.js`) has guarded it since 2026-07-18, with the existing violations baselined so the number can only shrink. *This file previously claimed Protocol 23 had no gate guard, and that false claim was the stated justification for a prerequisite hardening gate — corrected 2026-07-20.* The guard was the right shape and matches [[self-improving-code]]: fix a class, then add a ratchet so it can't recur. **The ratchet does not by itself do the inversion work** — it stops new edges, it doesn't remove old ones, so items 1–4 above remain reasoning worth acting on; check `QUEUE.md` for whether they're still queued. **Framework: CLOSED on arithmetic.** The great majority of the test suites are static source-analysis, so a bundler/transpiler would invalidate most of the gate. And note — **a framework would NOT have fixed the cycles anyway**; they live in the data flow, not the rendering technology.