Architecture Overview

Architecture Overview

Genesis OS is an operating system for cognition, built in layers. The value is in the contracts between layers: replace any one layer, honour its contract, and the rest of the system does not notice.

flowchart TB
    A["① Interface · Apps — user-facing surfaces"]
    B["② OS Core · Genesis OS — IPC bus · permissions/audit · services"]
    C["③ Cognitive Kernel · ABI v0.2 — 9 services, the quality gate"]
    D["④ Policy Hook Surface — PRE_PLAN … PRE_RESPONSE"]
    E["⑤ Cognitive Subsystems — memory · planning · validation · execution · governance"]
    F["⑥ Runtime Kernel — drivers · model pools · sessions"]
    G["⑦ Runtimes · Hardware — local LLMs · execution sandbox"]
    A -->|syscall| B -->|dispatch| C -->|enforce| D -->|allow/deny| E -->|infer| F -->|execute| G

Loading

The seven layers, briefly

Layer	Role	Holds authority?
① Interface · Apps	chat / council / dashboards; issues syscalls, renders results	none
② OS Core · Genesis OS	IPC bus, permissions/audit, sandboxed workspace, services	owns side effects, via audited permissions
③ Cognitive Kernel	event spine, token budget, scheduler, the ABI; 9 services	the quality gate everything crosses
④ Policy Hook Surface	fail-closed allow/deny at each lifecycle step	enforces the current rules
⑤ Cognitive Subsystems	the thinking parts, each conforming to the ABI	reason/plan/act, but only via the kernel
⑥ Runtime Kernel	drivers, model pools, sessions; binds a provider to a model	compute management
⑦ Runtimes · Hardware	local LLMs, sandboxes, GPUs/CPUs	computes; decides nothing

Authority decreases as you go down. The interface has none; the hardware just computes. An exploit or hallucination low in the stack cannot escalate, because the layer above gates every step.

Why layer it this way

• Replaceability — each boundary is a seam. Swap the UI (①), the model runtime (⑥/⑦), or add a subsystem (⑤) without touching the others.
• Containment — a single point (③ + ④) polices every action; nothing skips the kernel.
• Auditability — because everything crosses the kernel and the hook surface, there is one place where "what the system did and why" is written.

Migration is first-class

Layers carry an explicit conformance status — migrated (conforms ✓), live (legacy), or planned (spec). The architecture is honest about how much of itself actually obeys the current contract, so it can be migrated (strangler-fig) without pretending it is already finished.

---

📖 Full document: docs/01 — Layered Architecture → Next: Cognitive Kernel ABI