oikos/docs/mbse/framework.md

Oikos — MBSE Framework, Ontology & Viewpoints

Companion to the system Model. 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.

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 — 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/), 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 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 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):

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 §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, Viewpoint 11 below. What follows here is the condensed version, sufficient only to make this section's point:

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	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	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); Viewpoint 11 produces four, once per ontology facet (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 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 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 — 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 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

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 for the Model's concern-based Views, components.md for its component-based Views, and 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.