oikos/docs/mbse/framework.md

# Oikos — MBSE Framework, Ontology & Viewpoints

> Companion to [the system Model](README.md). Where `README.md` **is** the
> Model — the populated Views — this document is the **Framework**: the
> template those Views were built from. It follows Jon Holt, *Systems
> Engineering Demystified* (2nd ed., 2023), Ch. 2, "Model-Based Systems
> Engineering," almost to the letter — the terms below (Model, View,
> Viewpoint, Notation, Ontology, Framework, Process Set, Compliance) are
> Holt's, not a paraphrase, because the whole point of adopting an Ontology
> is to stop each document inventing its own vocabulary.

> **Holt's core claim, stated once so it doesn't need restating per
> section:** *"When the Ontology and the Viewpoints are put together, they
> form what is known as a Framework. A Framework is created as a template,
> or blueprint, for a complete Model."* (Ch. 2, p. 40). Ontology is, in
> Holt's words, "arguably the single most important part of MBSE as all of
> the other elements that make up MBSE are ultimately traceable back to the
> Ontology" (p. 40).

## 1. MBSE in a Slide — applied to Oikos

Holt's book converges the whole chapter into one diagram known across the
Systems Engineering community as "MBSE in a slide" (Holt & Perry, 2019),
extended with Implementation and Compliance. Below is that same structure
with every box filled in for this specific repository, not left generic.

```mermaid
flowchart TB
    subgraph APPROACH["APPROACH \n what must be produced, and how"]
        FW["Framework \n Ontology + Viewpoints \n = this document"]
        PS["Process Set \n ADRs, plans, this repo's\nreview/CI conventions"]
    end

    subgraph GOAL["GOAL \n why any of this exists"]
        SYS["System \n the hubris homelab,\ngoverned by Oikos"]
        MDL["Model \n README.md \n the nine Views"]
    end

    subgraph VIS["VISUALIZATION \n how it is communicated"]
        NOT["Notation \n Markdown + Mermaid"]
        DIA["Diagrams \n flowchart, stateDiagram,\nsequenceDiagram, classDiagram"]
    end

    subgraph IMPL["IMPLEMENTATION"]
        TOOL["Tools \n git, a Markdown renderer,\nMermaid; no dedicated\nSysML tool"]
    end

    subgraph COMP["COMPLIANCE"]
        BP["Best Practice \n ISO 42010 viewpoint and view\nterminology, informally aligned,\nnot certified"]
    end

    FW --> MDL
    PS --> MDL
    MDL --> SYS
    NOT --> DIA
    DIA --> MDL
    TOOL --> NOT
    TOOL --> FW
    BP --> PS
    BP --> FW
```

| Holt's concept | Generic definition (Ch. 2) | Oikos instantiation |
|---|---|---|
| **System** | The thing Systems Engineering exists to develop | The **hubris homelab** — hosts, LXCs, VMs, services, network — *and* the Oikos control plane that governs it. See note below on the reflexive boundary. |
| **Model** | The abstraction of the System; the single source of truth for engineering knowledge about it | [README.md](README.md) — the nine-View system model |
| **View** | A validated collection of information within the Model | Each of README.md's nine numbered sections |
| **Viewpoint** | The template for a View — the stored answers to *which Stakeholders, why, what information* | §4 of this document — the Viewpoint catalog |
| **Ontology** | The domain-specific language every Viewpoint's content is expressed in | §3 of this document, and — distinctively for this system — literally implemented in code as `seeds/ontology.yaml` |
| **Notation** | The spoken/visual language used to communicate a View | Markdown prose + Mermaid diagrams (flowchart, stateDiagram-v2, sequenceDiagram, classDiagram) |
| **Diagram** | One rendering of a View through a Notation's lens | Each Mermaid block in README.md |
| **Framework** | Ontology + Viewpoints, together | This document |
| **Process Set** | The steps for developing and using the Framework — the "how" | This repo's ADR process ([docs/adr/](../adr/)), design-doc process (`plans/`), and the research-then-write method used to build README.md (see its own header note on verified vs. per-research-pass findings) |
| **Tool** | What implements the Notation and the Framework | Git + a Markdown/Mermaid renderer for the Notation; no dedicated MBSE tool enforces the Framework — see §6 for the honest gap this leaves |
| **Compliance** | Demonstrating the approach meets external best practice | §5 |

**On the System's boundary being reflexive.** Most MBSE textbook examples
model a System that is wholly separate from the engineering process
describing it (a car, a radar). Oikos is not: the System being modeled
*is* an autonomous control system, and the Model describing it (this
documentation) sits outside a boundary that the System itself polices with
its own internal "model" — the Postgres database, which
[ADR-0003](../adr/0003-db-native-ontology-yaml-seeds.md) calls the runtime
single source of truth. These are two different, non-competing uses of
"model": the **engineering Model** (this doc set) is Holt's sense — a
human-facing abstraction for realizing the System successfully. The
**runtime database** is an operational sense — the System's own record of
its current state, which the engineering Model *describes* but does not
*replace*. Conflating the two would suggest this documentation is
authoritative over live state, which it explicitly is not — README.md's
own verification discipline (verified vs. per-research-pass) exists
precisely because the engineering Model can drift from what the database
and code actually do.

## 2. The Goal — System and Model, made concrete

**The System**, enumerated (this is "taking all the components of the
system," per Holt's instruction that a valid View must be traceable to
real Stakeholders and real information — not an abstract diagram):

| Component | Role |
|---|---|
| `oikos api` (`internal/httpapi`, `internal/mcp`) | REST + MCP server, the decision/execution gate |
| `oikos scheduler` (`internal/scheduler`) | Observe loop — probes, signals |
| `oikos notifier` (`internal/notifier`) | Approval delivery — Matrix, token issuance |
| `nomos` (`cmd/nomos`) | The AI agent — MCP client, task/plan orchestration |
| `web` (Svelte 5 SPA) | Control-room UI |
| PostgreSQL/TimescaleDB | The System's own runtime source of truth |
| The managed fleet | Hosts, LXCs, VMs, services under Oikos's governance |
| `internal/actuator`, `internal/learning` | Compiled into the System, **not** currently part of its running behavior — see README.md §9.2 |

**The Model** is [README.md](README.md) in full: nine Views (Mission,
Requirements, Functional Architecture, Physical Architecture, Interfaces,
Behavior, Verification & Validation, Risk & Safety, Roadmap &
Traceability). Per Holt's consistency test (p. 35): *"If there is a set of
Views where each View is consistent with all other Views, then it is a
Model. If there is a set of Views where each View is not consistent with
all other Views, then it is data."* README.md's own cross-referencing
(§8.1's kill-switch finding surfaced in §2's requirement, §3's function
table, and §9's roadmap alike) is what keeps it a Model rather than nine
unrelated documents.

## 3. The Ontology — Oikos's domain-specific language

Holt's Ontology has two jobs: it is the vocabulary every Viewpoint's
content must be expressed in, and it is what makes Views from different
parts of the Model comparable rather than coincidentally similar-looking.
Oikos needs this at two levels, and — unusually for a Holt-style
exercise — one of them was **already built in code**, not invented for
this documentation pass.

### 3.1 Layer A — the SE meta-ontology (concepts used to talk *about* the Model)

This is the vocabulary this Framework document and README.md are written
in. It is Holt's own vocabulary, restated as a concept diagram rather than
prose, per his own example in the book (a Need Description View "visualized
using UML Notation — specifically, a Diagram known as the class diagram,
where each need is represented as a UML class," p. 38):

```mermaid
classDiagram
    class System
    class Model {
      +isSingleSourceOfTruth bool
    }
    class View {
      +stakeholders
      +value
      +information
    }
    class Viewpoint {
      +stakeholderQuestion
      +valueQuestion
      +informationQuestion
    }
    class Notation
    class Diagram
    class Ontology
    class Framework
    class ProcessSet
    class Stakeholder

    Model "1" --> "1" System : abstracts
    Model "1" o-- "many" View : is made up of
    View ..|> Viewpoint : conforms to
    View "1" --> "1..many" Diagram : visualized through
    Diagram "many" --> "1" Notation : belongs to
    Viewpoint "many" --> "1" Ontology : traces terminology to
    Framework "1" o-- "1" Ontology : contains
    Framework "1" o-- "many" Viewpoint : contains
    Stakeholder "many" --> "many" Viewpoint : interested in
```

### 3.2 Layer B — the Oikos domain ontology (the concepts inside the Views)

This is the part that already exists as running code, not something this
documentation pass invented: `seeds/ontology.yaml` (952 lines, ingested by
migration `001_ontology.up.sql` into the `entity_types`/`relationship_types`
tables) *is* Holt's Ontology for this System — a machine-enforced
domain-specific language that every Signal, Execution, Approval, and Task
discussed anywhere in the Model traces back to. The full treatment — all 60
entity types, the complete 47-relationship catalog (verified directly
against the seed file; [ADR-0014](../adr/0014-entity-model.md) §1/§4
records an earlier 2026-07-08 snapshot of 56 types and 34 relationships,
since grown), and all six registered lifecycle state machines — is
[ontology.md](ontology.md), Viewpoint 11 below. What follows here is the
condensed version, sufficient only to make this section's point:

```mermaid
classDiagram
    class Entity {
      +UUID id
      +string slug
      +string type
      +string state
    }
    class ComputeEntity
    class Network
    class Container
    class Service
    class Agent
    class Signal {
      +string kind
      +string severity
      +string state
    }
    class Classification {
      +string riskClass
      +string route
    }
    class Execution {
      +string status
    }
    class Approval {
      +string status
    }
    class Pattern {
      +float confidence
      +string status
    }
    class Skill
    class Task {
      +string goal
      +string status
      +string outcome
    }
    class KnowledgeEntity

    Entity <|-- ComputeEntity
    Entity <|-- Network
    Entity <|-- Container
    Entity <|-- Service
    Entity <|-- Agent
    Entity <|-- Signal
    Entity <|-- Classification
    Entity <|-- Execution
    Entity <|-- Approval
    Entity <|-- Pattern
    Entity <|-- Skill
    Entity <|-- Task
    Entity <|-- KnowledgeEntity

    Signal "many" --> "1" Entity : about
    Classification "1" --> "1" Signal : classifies
    Classification "1" --> "1" Execution : precedes
    Execution "many" --> "1" Entity : targets
    Execution "many" --> "1" Agent : performs
    Approval "1" --> "1" Execution : decides
    Task "1" --> "many" Execution : requests via run
    Task "many" --> "many" Entity : involves
    KnowledgeEntity "many" --> "many" Entity : about
    KnowledgeEntity "many" --> "1" Task : outcome_of
    Pattern "1" --> "many" Execution : informed_by
```

**This is the elegant accident worth naming plainly:** Oikos was not built
by someone following Holt's method, yet its own architecture independently
arrived at "the domain concepts are an Ontology, ingested once, and
everything else traces back to it" — `seeds/ontology.yaml` → DB tables →
every entity, signal, execution, and relationship in the system. That is
Holt's Ontology principle, implemented as infrastructure rather than as a
documentation artifact. The gap is not that the Ontology is missing; it's
that, until this document, nothing had stated the correspondence between
"the ontology" as oikos's engineers already use the word and "the Ontology"
as Holt's MBSE method uses it. They are the same thing, at the domain
layer.

### 3.3 Where Layer A and Layer B meet

Layer A (SE meta-ontology) is what makes README.md's Views *disciplined* —
each one answers Holt's three questions (§4 below). Layer B (the Oikos
domain ontology) is what makes README.md's Views *say the same thing
consistently* — "risk class," "entity," "signal," and "execution" mean one
thing throughout the whole Model because they mean one thing in
`seeds/ontology.yaml`, not because nine separately-written documents
happened to agree.

## 4. The Viewpoint Catalog — the Framework's template for Views

Per Holt (p. 39-40), a Viewpoint stores the answers to three questions —
*which Stakeholders, why (what value), what information* — plus a fourth,
*what Notation* — so that every View built from it is automatically
consistent. Below is that template applied retroactively to each of
README.md's nine Views, which is itself a useful audit: a View that can't
honestly answer these four questions is not a valid View by Holt's own
test (p. 35), and is a candidate for removal.

| Viewpoint | Which Stakeholders (§1.2) | Why — what value | What information | Notation |
|---|---|---|---|---|
| **1. Mission & Context** | Operator; future engineers/agents onboarding | Establishes why design choices elsewhere aren't arbitrary; sets the system boundary so later Views don't have to re-litigate scope | Mission statement, stakeholder table, mission drivers, boundary diagram, operational concept | Prose + flowchart |
| **2. Requirements** | Operator; anyone implementing against a requirement | Traces every "the system shall" back to a source and forward to an implementation status, so intent and reality can be compared | Requirement ID, statement, source, status, organized by OODA phase + NFRs | Structured table |
| **3. Functional Architecture** | Engineers extending decision/execution logic | Prevents the single most expensive mistake in this codebase — extending the wrong package because it has the right name | Function decomposition, function-to-component allocation (expected vs. actual owner), the `run` gate flow, the Task lifecycle | flowchart + allocation table |
| **4. Physical Architecture** | Operator deploying/debugging the stack; on-call | Answers "what is actually running and where" independent of what the code *could* do | Component block diagram, deployment topology, trust zones, external couplings | flowchart |
| **5. Interfaces (ICD)** | Anyone integrating a new MCP client, or reading/writing the API | A single place to find every tool/route/event without reading source | MCP tool catalog, REST groups, SSE event types, auth model | Tables |
| **6. Behavior** | Engineers reasoning about a specific flow (an approval, a task) end to end | State machines and sequences are where "is this actually enforced" questions get answered, not functional prose | Signal/Execution/Approval state machines, `run`-gate sequence, auto-continuation sequence, Task sequence | stateDiagram-v2 + sequenceDiagram |
| **7. Verification & Validation** | Operator deciding whether to trust a change; anyone auditing test coverage | Distinguishes "we checked this" from "we assume this" | CI pipeline, evals, health checks as continuous verification, deploy/rollback, explicit list of what's *not* covered | Prose + flowchart |
| **8. Risk & Safety** | Operator; anyone reasoning about blast radius of agent autonomy | The single highest-consequence question this Model answers: what actually stops a bad action | Kill-switch gap finding, defense-in-depth layers, threat model, known open gaps, what's structurally guaranteed | Prose + tables |
| **9. Roadmap & Traceability** | Operator planning what to fix next; future documentation maintainers | The authoritative status matrix every other View's ✅/⚠/❌ marker derives from | North-star status, code-real/dead-code/schema-only matrix, doc/code divergences, suggested next steps | Tables |
| **10. Component** *(repeating Viewpoint — one View per component)* | An engineer about to change a specific package | Prevents extending the wrong implementation of something that exists twice (§9.2's dead-code/live-code pairs), or missing a known issue local to that package | Internal structure (files, key functions, file:line), behavior specific to that component, interfaces it owns, known issues — instantiated once per component in [components.md](components.md) | flowchart + tables |
| **11. Ontology** *(repeating Viewpoint — one View per ontology facet)* | An engineer adding/changing an entity or relationship type; anyone checking whether a term used elsewhere in the Model traces back to something real | Is the check against Holt's own biggest MBSE risk (p. 35) applied to the Ontology itself — prevents treating the domain vocabulary as informal prose when it's actually a machine-enforced schema with real transition gates | Entity type hierarchy, relationship catalog, lifecycle state machines with their `requires:` gates, concrete population — instantiated as four Views in [ontology.md](ontology.md) | graph + stateDiagram-v2 + tables |

**Three things this table makes visible that weren't visible before:**

1. Every Viewpoint's "why" is stated in terms of a **decision or mistake it
   prevents**, not merely a topic it covers — closer to Holt's requirement
   that a View "must add value" (p. 35) than a topic-based table of
   contents would be.
2. Viewpoints 10 and 11 are structurally different from 1-9: each is a
   **repeating Viewpoint** — one template, instantiated multiple times.
   Viewpoint 10 produces eight Views, once per component
   ([components.md](components.md)); Viewpoint 11 produces four, once per
   ontology facet ([ontology.md](ontology.md)). Holt's method doesn't
   forbid this; a Viewpoint is a template, and nothing says a template can
   only be used once.
3. There is still no Viewpoint in this catalog for "document every class
   exhaustively regardless of whether anyone asked" — Viewpoints 10 and 11
   are scoped to named, narrow Stakeholder questions ("an engineer about to
   change this component," "an engineer adding a new type"), not a blanket
   documentation mandate.
   Per Holt's own worked example (the Need Description View, p. 38-39), a
   collection of information that can't name an interested Stakeholder is
   not a View; it would just be generated documentation nobody reads,
   which is the exact failure mode Holt calls out as the biggest risk in
   adopting MBSE (p. 35).

## 5. Compliance

Holt names three categories of best-practice source (p. 46) a Framework
can be checked against. Being direct about which apply here and which
don't, rather than implying certification that doesn't exist:

| Category | Holt's examples | Oikos's position |
|---|---|---|
| **Process-based standards** (how work is done) | ISO 15288 | Not formally adopted. This repo's own process conventions (ADRs, `plans/`, PR review) are the de facto Process Set — informally rigorous, not standards-mapped. |
| **Framework-based standards** (what information is produced) | ISO 42010, MODAF, DoDAF, NAF, UAF, Zachman | **Informally aligned, not certified.** This Framework borrows ISO 42010's Viewpoint/View vocabulary (which Holt's own method is built on) but has not been checked against the standard's actual conformance clauses. Say this plainly rather than imply an audit that hasn't happened. |
| **Application-based standards** (domain-specific: safety, security, usability) | — | Partially present in spirit: [Risk & Safety](README.md#8-risk--safety) documents a real threat model and known gaps, but there is no adopted external security standard (e.g., no formal threat-modeling framework like STRIDE was used — the threat model in ADR-0007 is bespoke). |

The honest summary: this Framework's compliance posture is **methodological
alignment with ISO 42010's core idea (Stakeholders → concerns → Viewpoints
→ Views), not standards certification.** Claiming more than that would
itself violate the documentation set's own governing discipline (state
verified findings as verified, not aspirational ones as achieved).

## 6. Tools — Implementation, and its honest limit

Holt is specific that a good MBSE tool does two things: it *implements the
Notation* (enforces SysML's syntax/semantics the way a word processor
enforces spelling) and it *implements the Framework* (has the Ontology and
Viewpoints "programmed into it" as a profile, p. 44-45).

Neither is true here, and it matters to say so:

- **Notation tooling**: Markdown + Mermaid, rendered by GitHub/a Markdown
  viewer. Mermaid's flowchart/stateDiagram/sequenceDiagram/classDiagram
  grammars are enforced (a malformed diagram fails to render — as
  happened once already in this documentation effort and was fixed), but
  there is no semantic check that, say, a state machine diagram in
  [§6](README.md#6-behavior) actually matches the Go code's real
  transitions. That check was done by hand, once, for this pass — it will
  drift the moment the code changes and nobody re-verifies it.
- **Framework tooling**: there is no tool with this Ontology or these
  Viewpoints "programmed in." Nothing prevents a future edit to README.md
  from adding a View that fails Holt's three-question test, or from
  introducing a term that doesn't trace back to `seeds/ontology.yaml`.
  The only enforcement mechanism is a human (or an agent) re-reading this
  Framework document before extending the Model — which is precisely why
  this document needed to exist as a separate, explicit artifact rather
  than staying implicit in how README.md happened to get organized.

## 7. Process Set — how this Framework is developed and used

Holt separates Framework (what) from Process Set (how) specifically so
that different projects can share one Framework under different levels of
rigor (p. 41-42). For this repository, the Process Set is:

1. **Establishing a new Viewpoint**: propose it here in §4, answering all
   four questions before writing the View it justifies. If it can't answer
   them, per Holt's own rule (p. 35), it doesn't get written.
2. **Extending the Ontology**: changes to `seeds/ontology.yaml` are the
   authoritative act — this document's §3.2 is a description of that file,
   not an independent source, and must be re-derived from it if it drifts.
3. **Updating a View**: per README.md's own closing section ("Keeping this
   model current"), a code change updates the View whose Viewpoint claims
   that information, and — if it resolves or introduces a finding in
   [§9 Roadmap & Traceability](README.md#9-roadmap--traceability) — that
   matrix is updated in the same pass.
4. **Compliance review**: informal, human-in-the-loop (§5) — there is no
   scheduled re-audit; drift is caught opportunistically, the same way the
   kill-switch gap in [§8.1](README.md#81-the-kill-switch-gap-verified-most-important-finding-in-this-model)
   was caught by direct verification during a documentation pass rather
   than by a standing process designed to catch it.

## 8. Relationship between this Framework and the Model

```mermaid
flowchart LR
    ONT["Ontology \n seeds and ADR-0014"] --> FW["Framework \n this document"]
    VP["Viewpoint catalog \n Section 4 of this document"] --> FW
    FW --> MDL["Model \n README.md, Viewpoints 1 to 9"]
    FW --> CV["Model \n components.md, Viewpoint 10\nrepeated per component"]
    FW --> OV["Model \n ontology.md, Viewpoint 11\nrepeated per ontology facet"]
    MDL --> V1["View 1..9"]
    CV --> V2["View 10a..10h"]
    OV --> V3["View 11a..11d"]
```

Read [README.md](README.md) for the Model's concern-based Views,
[components.md](components.md) for its component-based Views, and
[ontology.md](ontology.md) for the Ontology's own full treatment (the
sketch in §3 above is deliberately condensed). Read this document when you
are deciding whether a new View belongs in any of the three, when a term in
the Model feels like it's drifted from what `seeds/ontology.yaml` actually
defines, or when onboarding someone who needs to understand not just *what
the system is* but *why this documentation is shaped the way it is*.