oikos/docs/adr/0014-entity-model.md

ADR 0014 — Entity model: types, relationships & interactions

Status: Accepted Date: 2026-07-08 Scope: Full inventory of every entity type, relationship, state machine, and cognition pipeline — with clear markers for what is code-real vs schema-only.

---

1. Entity Type Hierarchy (56 types)

graph TD
    subgraph meta["layer: meta"]
        entity["★ entity"]
    end

    subgraph infrastructure["layer: infrastructure"]
        subgraph physical["domain: physical"]
            site
            ups
            sensor
            peripheral
        end

        subgraph compute["domain: compute"]
            ce["★ compute-entity"]
            machine["★ machine"]
            proxmox-host
            standalone-server
            workstation
            appliance
            vm
            container["★ container"]
            lxc
            docker-container
            hypervisor
        end

        subgraph network["domain: network"]
            net["★ network"]
            lan
            mesh
            vlan
            network-interface
            dns-zone
            dns-record
            ingress-route
            certificate
            firewall-rule
        end

        subgraph storage["domain: storage"]
            storage-pool
            volume
            backup-target
            dataset
        end

        subgraph software["domain: software"]
            service
            application
            config-repo
            deploy-pipeline
            package-set
            cluster
            compose-stack
        end

        subgraph external["domain: external"]
            domain-registration
            cloud-service
            isp-link
            vendor-dependency
        end
    end

    subgraph governance["layer: governance"]
        subgraph identity["domain: identity"]
            person
            agent
            identity-provider
            account
            secret
            key
            access-grant
        end
    end

    subgraph cognition["layer: cognition"]
        check
        signal
        classification
        execution
        feedback
        pattern
        skill
        approval
        document
        runbook
        investigation
    end

    entity --> ce
    entity --> machine
    entity --> net
    entity --> container
    entity --> site
    entity --> ups
    entity --> sensor
    entity --> peripheral
    entity --> vm
    entity --> hypervisor
    entity --> network-interface
    entity --> dns-zone
    entity --> dns-record
    entity --> ingress-route
    entity --> certificate
    entity --> firewall-rule
    entity --> storage-pool
    entity --> volume
    entity --> backup-target
    entity --> dataset
    entity --> service
    entity --> application
    entity --> config-repo
    entity --> deploy-pipeline
    entity --> package-set
    entity --> cluster
    entity --> compose-stack
    entity --> domain-registration
    entity --> cloud-service
    entity --> isp-link
    entity --> vendor-dependency
    entity --> person
    entity --> agent
    entity --> identity-provider
    entity --> account
    entity --> secret
    entity --> key
    entity --> access-grant
    entity --> check
    entity --> signal
    entity --> classification
    entity --> execution
    entity --> feedback
    entity --> pattern
    entity --> skill
    entity --> approval
    entity --> document
    entity --> runbook
    entity --> investigation

    ce --> machine
    ce --> container
    machine --> proxmox-host
    machine --> standalone-server
    machine --> workstation
    machine --> appliance
    container --> lxc
    container --> docker-container
    net --> lan
    net --> mesh
    net --> vlan

★ = abstract (cannot be instantiated; polymorphic target for relationships)

Concrete instances (88 active entities)

Type	Count	Examples
lxc	19	jellyfin, caddy, dns, gitea, nextcloud, matrix, arriman…
service	25	caddy, authentik, dns, jellyfin, paperless, matrix…
ingress-route	21	*.hubris.network
config-repo	6	caddy-conf, gitea-customizations, mule-image…
proxmox-host	2	hubris, strong
workstation	2	mac-mini, republic-laptop
standalone-server	1	netbird-vps
vm	2	zimaos, haos
storage-pool	3	local-lvm-hubris, library-hubris, ludo-lvm
volume	2	library, media-local
+ sites, networks, agents, documents, destroyed…

---

2. Core Sequence: Machine Onboarding

sequenceDiagram
    participant O as Operator
    participant A as Oikos API
    participant D as DB
    participant S as Scheduler
    participant T as Target Machine

    O->>A: POST /api/v1/entities {type:proxmox-host, slug:host:new, …}
    A->>D: INSERT INTO entities
    A->>A: ensureDefaultChecks().resolveHost() → lan_ip
    A->>D: INSERT check_defs × 6 (target_id set)
    A-->>O: 201 Created

    Note over S,T: 30s scheduler tick
    S->>D: ListEnabledCheckDefs
    S->>T: SSH exec /opt/oikos/checks/cpu_check.sh
    T-->>S: {"health":"ok","metrics":{"cpu_pct":2.5,"cpu_temp":48}}
    S->>D: INSERT metric_samples
    S->>D: UPSERT entity_status (health)

What's code-real here:

• CreateEntity() at internal/httpapi/impl.go:811 — handles POST, validates type, calls ensureDefaultChecks()
• ensureDefaultChecks() → internal/checkdefaults/defaults.go:144 — resolves host IP, SSH user, creates 6 check_defs rows with target_id
• Scheduler at internal/scheduler/scheduler.go:26 — loads ListEnabledCheckDefs, dispatches by kind, writes metrics + signals

---

3. Core Sequence: The OODA Loop (observe → orient → decide → act → learn)

flowchart TB
    subgraph OBSERVE["🔍 OBSERVE (Scheduler every 30s)"]
        direction TB
        S1["ListEnabledCheckDefs"]
        S2["ping → exec.Command(ping, host)"]
        S3["http → http.Get(url)"]
        S4["tcp → net.DialTimeout(tcp, addr)"]
        S5["disk → unix.Statfs(path)"]
        S6["cert-expiry → tls.Dial + cert.NotAfter"]
        S7["ssh-script → exec.Command(ssh, host, script)"]
        S8["checkResult{health, signalKind, evidence, metrics}"]
        S1 --> S2 & S3 & S4 & S5 & S6 & S7
        S2 & S3 & S4 & S5 & S6 & S7 --> S8
        S8 -->|INSERT| MS[("metric_samples")]
        S8 -->|UPSERT| SG["signals (dedup by target+kind)"]
        S8 -->|UPSERT| ES["entity_status (health)"]
    end

    subgraph ORIENT["🧭 ORIENT (Classification)"]
        direction TB
        C1["policy.ClassifySignal(signal, entity, blast_radius)"]
        C2["read_only → route: auto_act"]
        C3["reversible_low → route: auto_act"]
        C4["config_mutation → route: escalate"]
        C5["destructive → route: hold"]
        C1 --> C2 & C3 & C4 & C5
    end

    subgraph DECIDE["⚖️ DECIDE (Approval Gate)"]
        direction TB
        D1["auto_act → execute immediately"]
        D2["escalate → INSERT approval (pending)"]
        D3["notifier → Matrix alert + HMAC token"]
        D4["operator replies ✅ or ❌"]
        D5["hold → queued, never auto-executed"]
        D2 --> D3 --> D4
    end

    subgraph ACT["⚡ ACT (Execution)"]
        direction TB
        A1["Nomos → MCP request_execution"]
        A2["actuator.Execute() → SSH exec"]
        A3["systemctl restart / apt upgrade / pct exec"]
        A1 --> A2 --> A3
    end

    subgraph LEARN["🧠 LEARN (Patterns + Skills)"]
        direction TB
        L1["execution → produces → feedback"]
        L2["feedback → contributes-to → pattern"]
        L3["pattern → informs → skill"]
        L1 --> L2 --> L3
    end

    SG --> ORIENT
    ORIENT --> DECIDE
    DECIDE --> ACT
    ACT --> LEARN

    style OBSERVE fill:#e3f2fd
    style ORIENT fill:#fff3e0
    style DECIDE fill:#fce4ec
    style ACT fill:#e8f5e9
    style LEARN fill:#f3e5f5

What's code-real in the OODA loop

Phase	Table	Code	Status
Observe	check_defs, metric_samples	scheduler.go:26-215	✅ fully wired, 6 probe kinds
Observe → Orient	signals	scheduler.go:130-141 (UpsertSignal)	✅ dedup, severity, events
Orient	classifications	policy/classify.go (function exists)	⚠ function defined but scheduler never calls it
Decide	approvals	server.go:311-367 (request_execution)	✅ escalation gate works
Act	executions	actuator/exec.go (SSH exec)	✅ systemctl, apt, pct
Learn	feedback, patterns, skills	tables + list endpoints only	⚠ schema only, no write path

---

4. Relationship Types — The Edge Catalog (34 edges)

Infrastructure Topology

graph LR
    HH["host:hubris"] -->|hosts| LX1["lxc:jellyfin"]
    HH -->|hosts| LX2["lxc:caddy"]
    HH -->|hosts| LX3["lxc:dns"]
    HH -->|hosts| LX4["lxc:gitea"]
    HH -->|hosts| LX5["lxc:…"]
    HS["host:strong"] -->|hosts| LX6["lxc:jellyfin"]
    HS -->|hosts| LX7["lxc:arriman"]
    HH -->|member-of| CL["cluster:homelab"]
    HS -->|member-of| CL
    LX2 -->|provides| SV1["service:caddy"]
    LX4 -->|provides| SV2["service:gitea"]
    LX3 -->|provides| SV3["service:dns"]
    HH -->|mounts| VL["volume:library"]
    HH -->|stores-on| PL["pool:library-hubris"]

Network

graph LR
    IG["ingress:paperless.hubris.network"] -->|routes-to| SP["service:paperless"]
    IG -->|secured-by| IDP["idp:authentik"]
    IG -->|uses-certificate| CRT["cert:*.hubris.network"]
    SJ["service:jellyfin"] -->|authenticates-via| IDP
    DNS["dns:paperless"] -->|in-zone| ZN["zone:hubris.network"]
    DNS -->|resolves-to| LX["lxc:caddy"]
    HH["host:hubris"] -->|connects-via| LL["lan:lab"]
    HS["host:strong"] -->|connects-via| LH["lan:household"]

Service Dependencies (feeds blast_radius CTE)

graph LR
    JF["service:jellyfin"] -->|depends-on| AK["service:authentik"]
    PP["service:paperless"] -->|depends-on| AK
    AR["service:arr-stack"] -->|depends-on| JF
    AK -->|depends-on| CD["service:caddy"]
    AK -->|depends-on| DNS["service:dns"]

Cognition (OODA edges)

graph LR
    CK["check:ssh-script:d419257d"] -->|checks| HH["host:hubris"]
    CK -->|raises| SG["signal:cpu-pressure"]
    SG -->|about| HH
    CL["classification:xyz"] -->|classifies| SG
    CL -->|precedes| EX["execution:restart-xyz"]
    EX -->|targets| HH
    EX -->|performs| AG["agent:nomos"]

Governance

graph LR
    DT["person:dtoro"] -->|owns| NO["agent:nomos"]
    DT -->|decides| AP["approval:xyz"]
    AK["idp:authentik"] -->|authenticates| DT

---

5. Lifecycle State Machines

Infrastructure (15 concrete types use this)

stateDiagram-v2
    [*] --> planned
    planned --> provisioning
    planned --> destroyed: cancelled

    provisioning --> active
    provisioning --> failed

    active --> migrating
    active --> failed
    active --> deprecated

    migrating --> active: post-verify
    migrating --> failed

    failed --> active: recovery verified
    failed --> deprecated: write-off

    deprecated --> active: un-deprecate
    deprecated --> destroyed

    destroyed --> [*]

Real precondition checks (code in impl.go:1494-1579):

Transition	Precondition	How it's checked
provisioning→active	health-check-answering	SELECT health FROM entity_status WHERE entity_id=$1 — must be healthy
provisioning→active	age-key-enrolled-if-needed	Checks attributes->>'age_pubkey' (workstation only)
provisioning→active	mesh-joined-if-needed	Checks attributes->>'mesh_ip' (workstation only)
provisioning→active	doc-page-complete	SELECT count(*) FROM relationships WHERE target_id=$1 AND type='documents'
deprecated→destroyed	no-inbound-edges	SELECT count(*) FROM relationships WHERE target_id=$1 AND valid_to IS NULL
any → terminated	backups-verified	Checks flag in entity attributes
any → terminated	secrets-revoked	Checks flag in entity attributes

Soft preconditions (always pass — operator-confirmed): inventory-entry, ip-reserved, preflight-passed, backup-verified, replacement-live, caddy-backends-checked, un-deprecate-note, etc.

Signal

stateDiagram-v2
    [*] --> raised
    raised --> acknowledged
    raised --> muted: mute_until set
    raised --> resolved: condition cleared

    acknowledged --> acting: classification exists
    acknowledged --> muted
    acknowledged --> resolved

    acting --> resolved: verification passed
    acting --> raised: retry budget
    acting --> failed

    failed --> acknowledged: operator retry

    muted --> raised: mute_until expired

    resolved --> [*]

Implemented preconditions:

• raised → muted: requires mute_until set (MuteSignal handler, impl.go:615-689)
• acting → resolved: requires verification-passed (soft — operator confirms)

Dedup mechanism: UNIQUE INDEX uq_signals_open ON signals(target_entity_id, kind) WHERE state NOT IN ('resolved','failed') — at most one open signal per (entity, kind). Repeated failures call UpsertSignal which increments occurrence_count on the existing row.

Execution

stateDiagram-v2
    [*] --> proposed
    proposed --> approved
    proposed --> auto_approved
    proposed --> denied
    proposed --> expired

    approved --> executing
    auto_approved --> executing
    expired --> [*]
    denied --> [*]

    executing --> verified
    executing --> failed
    executing --> timed_out

    failed --> rolled_back
    rolled_back --> verified
    rolled_back --> rollback_failed

    verified --> [*]
    rollback_failed --> [*]
    timed_out --> [*]

Approval

stateDiagram-v2
    [*] --> pending
    pending --> approved
    pending --> denied
    approved --> revoked
    approved --> expired

    denied --> [*]
    revoked --> [*]
    expired --> [*]

---

6. What's Code-Real vs Schema-Only

✅ Fully Implemented (code exists, running in production)

Component	File(s)	What it does
Entity CRUD	impl.go:811-966	Create, read, patch, list entities
Lifecycle transitions	impl.go:1494-1579	Precondition checks + state transitions
Relationship management	seed.go (ingest)	Create edges with valid_from/valid_to
Client enrollment	impl.go:1134-1236	POST /clients/enroll — age keypair, Infisical, state: provisioning
Check definitions	phase3.go:265-376	CreateCheck, ListChecks, PatchCheck
Scheduler observe	scheduler.go:26-215	6 probe kinds, metric_samples, signals, entity_status
Signals	scheduler.go:81-161	UpsertSignal (dedup), ResolveSignal, severity evaluation
Executions	server.go:286-411	request_execution MCP tool — reversible_low/config_mutation/destructive
Approvals	server.go:970-1052	createApproval, DecideApproval → executeApprovedAction
Notifier	notifier/notifier.go	Matrix alerts for pending approvals
Patterns	phase3.go:1100+	ListPatterns, PatchPattern (status/quarantine)
Skills	phase3.go:1300+	ListSkills, PatchSkill, ListSkillVersions
Default checks	checkdefaults/defaults.go	Auto-create checks on entity creation/enrollment/seed
TimescaleDB metrics	metric_samples table	Hypertable with 1h/1d continuous aggregates, 90-day retention
Events + SSE	events table + pg_notify	Real-time UI updates via SSE endpoint
Audit log	audit_log hypertable	Every mutation with actor + action
Knowledge entities	knowledge_entities	Documents, runbooks, investigations with FTS
MCP tools	server.go	24 tools for observe/orient/decide/act
Blast radius	blast_radius() fn	Recursive CTE — depends-on + hosts + routes-to edges

⚠ Schema Defined, Not Yet Wired (table exists, no active code path creates rows)

Component	What's Missing
classifications auto-creation	policy.ClassifySignal() exists but scheduler never calls it. Signals are raised but never automatically classified.
feedback records	No code writes to the feedback table. Execution results are not analyzed for patterns.
Pattern auto-learning	No code transitions patterns from hypothesized → validated. Requires evidence-count≥5 + confidence≥0.7 but no aggregation runs.
Skill execution	Skill entities carry a JSON procedure field but no execution engine reads or runs it.
drift check kind	Defined in OpenAPI and check_defs.kind enum, but no scheduler implementation exists.

📋 Defined in Seeds Only (ontology.yaml references, no DB schema)

Item	Notes
Relationship type cluster	Mentioned in inventory but not in ontology relationship_types
certificate entity type	Referenced in uses-certificate edges but no concrete certificates in inventory
Relationship type powers / monitors	Not defined in relationship_types

---

7. Database Physical Schema

erDiagram
    lifecycle_defs ||--o{ entity_types : "lifecycle_id FK"
    entity_types ||--o{ entities : "type FK"
    entity_types ||--o| entity_types : "parent_type FK (self-ref)"

    entities ||--o| entity_status : "dual entity (shared PK)"
    entities ||--o| check_defs : "dual entity (shared PK)"
    entities ||--o| signals : "dual entity (shared PK)"
    entities ||--o| classifications : "dual entity (shared PK)"
    entities ||--o| executions : "dual entity (shared PK)"
    entities ||--o| feedback : "dual entity (shared PK)"
    entities ||--o| patterns : "dual entity (shared PK)"
    entities ||--o| skills : "dual entity (shared PK)"
    entities ||--o| approvals : "dual entity (shared PK)"
    entities ||--o| knowledge_entities : "dual entity (shared PK)"

    entities ||--o{ relationships : "source_id FK"
    entities ||--o{ relationships : "target_id FK"

    check_defs }o--|| entities : "target_id FK"
    signals }o--|| entities : "target_entity_id FK"
    executions }o--|| entities : "target_entity_id FK"
    approvals }o--|| entities : "subject_entity_id FK"

    entity_types ||--o{ relationship_types : "source_type FK"
    entity_types ||--o{ relationship_types : "target_type FK"
    relationship_types ||--o{ relationships : "type FK"

    entity_types ||--o{ approval_rules : "entity_type FK"

    signals ||--o| check_defs : "check_id FK"

Key architectural patterns:

• Dual entities: check_defs, signals, classifications, executions, feedback, patterns, skills, approvals, knowledge_entities — all have entity_id UUID PK REFERENCES entities(id). Every row is also an entity.
• Partial unique indexes: relationships (current edges), signals (open signals), patterns (per-type action) — all use WHERE clauses for snapshot semantics.
• TimescaleDB hypertables: metric_samples, events, audit_log, agent_activity — with continuous aggregates and retention policies.
• SSE fan-out: pg_notify('oikos_events', ...) trigger on events INSERT → Go listener fan-out → SSE connections.

---

8. How Nomos Queries Thermals — End-to-End Trace

sequenceDiagram
    participant U as User
    participant N as Nomos (Agent)
    participant A as Oikos API
    participant T as TimescaleDB
    participant S as Scheduler
    participant H as Hubris

    Note over S,H: Autonomous collection (every 60s)
    S->>H: SSH exec cpu_check.sh
    H-->>S: {"metrics":{"cpu_pct":15,"cpu_temp":48}}
    S->>T: INSERT metric_samples (cpu_pct, cpu_temp)

    Note over U,N: User asks question
    U->>N: "what are the thermals of hubris?"
    N->>A: MCP query_metrics(metric=["cpu_pct","cpu_temp"])
    A->>T: SELECT time_bucket('1h', ts) … FROM metric_samples
    T-->>A: {avg:15, min:2, max:40} (cpu_pct)
    T-->>A: {avg:48, min:42, max:85} (cpu_temp)
    A-->>N: time-bucketed metrics
    N-->>U: "CPU at 15%, temp 48°C — normal range"

What made this possible (chronologically):

1. scheduler.go refactored to return metrics map → checkResult{metrics}
2. ssh-script check kind implemented → SSH exec to remote host
3. cpu_check.sh deployed to hubris → returns {"metrics":{"cpu_pct":2.5,"cpu_temp":48}}
4. Check created: POST /checks {"kind":"ssh-script","target":"host:hubris","config":{"host":"192.168.8.77","script":"cpu_check.sh"}}
5. Fixed: InsertMetricSample missing ts column → now() literal
6. Fixed: SSH port/user parsing bugs
7. Fixed: SSH warnings polluting JSON output
8. Scheduler loop → metrics written to TimescaleDB every 60s
9. MCP query_metrics reads from TimescaleDB → Nomos gets live data