adr: convert all diagrams to Mermaid (sequenceDiagram, stateDiagram-v2, flowchart, erDiagram, graph)
0013-signal-triggers.md: - Thermals query: sequenceDiagram (Nomos→API→Scheduler→Hubris→TimescaleDB) - Script deployment: sequenceDiagram - Signal lifecycle: stateDiagram-v2 - DB data flow: flowchart 0014-entity-model.md: - Entity type hierarchy: graph (56 types, 3 layers, 7 domains) - Machine onboarding: sequenceDiagram - OODA loop (5 phases): flowchart with color-coded subgraphs - Infrastructure topology: graph - Network relationships: graph - Service dependencies: graph - Cognition OODA edges: graph - Governance: graph - Infrastructure lifecycle: stateDiagram-v2 - Signal lifecycle: stateDiagram-v2 - Execution lifecycle: stateDiagram-v2 - Approval lifecycle: stateDiagram-v2 - DB physical schema: erDiagram - Thermals query trace: sequenceDiagram
This commit is contained in:
@@ -4,40 +4,28 @@
|
||||
|
||||
When Nomos is asked "what are the thermals of hubris?", here is exactly what happens:
|
||||
|
||||
```
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ Nomos │ │ Oikos │ │Scheduler │ │ Hubris │
|
||||
│ (Agent) │ │ API │ │ (Docker) │ │(Proxmox) │
|
||||
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
|
||||
│ │ │ │
|
||||
│ query_metrics │ │ │
|
||||
│────────────────>│ │ │
|
||||
│ │ │ │
|
||||
│ ← cpu_pct=2.5 │ SELECT FROM │ │
|
||||
│ cpu_temp=48 │ metric_samples│ │
|
||||
│<────────────────│ │ │
|
||||
│ │ │ │
|
||||
│ │ │ │
|
||||
══════ Every 60s (autonomous loop) ══════ │
|
||||
│ │ │ │
|
||||
│ │ │ SSH exec │
|
||||
│ │ │─────────────────>│
|
||||
│ │ │ /opt/oikos/ │
|
||||
│ │ │ checks/ │
|
||||
│ │ │ cpu_check.sh │
|
||||
│ │ │ │
|
||||
│ │ │ {"health":"ok", │
|
||||
│ │ │ "metrics": │
|
||||
│ │ │ {"cpu_pct":2.5, │
|
||||
│ │ │ "cpu_temp":48}}│
|
||||
│ │ │<─────────────────│
|
||||
│ │ │ │
|
||||
│ │ │ INSERT │
|
||||
│ │ │ metric_samples │
|
||||
│ │ │ │
|
||||
│ │ │ UPSERT signal │
|
||||
│ │ │ (dedup) │
|
||||
│ │ │ │
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant N as Nomos (Agent)
|
||||
participant A as Oikos API
|
||||
participant S as Scheduler (Docker)
|
||||
participant H as Hubris (Proxmox)
|
||||
participant T as TimescaleDB
|
||||
|
||||
Note over S,H: Every 60s (autonomous loop)
|
||||
S->>H: SSH exec /opt/oikos/checks/cpu_check.sh
|
||||
H-->>S: {"health":"ok","metrics":{"cpu_pct":2.5,"cpu_temp":48}}
|
||||
S->>T: INSERT metric_samples (cpu_pct, cpu_temp)
|
||||
S->>T: UPSERT entity_status (health)
|
||||
alt unhealthy
|
||||
S->>T: UPSERT signal (dedup by target+kind)
|
||||
end
|
||||
|
||||
Note over N,T: User asks "what are the thermals of hubris?"
|
||||
N->>A: MCP query_metrics(metric=["cpu_pct","cpu_temp"])
|
||||
A->>T: SELECT time_bucket(…) FROM metric_samples
|
||||
T-->>A: cpu_pct=15%, cpu_temp=48°C
|
||||
A-->>N: {avg, min, max} per bucket
|
||||
```
|
||||
|
||||
## Two Paths
|
||||
@@ -105,22 +93,18 @@ or on failure:
|
||||
|
||||
## Script Deployment
|
||||
|
||||
```
|
||||
Git Push Sync Timer (5min) Target Host
|
||||
┌────────┐ ┌────────────────┐ ┌──────────┐
|
||||
│ git push│ │ git pull │ │ │
|
||||
│ origin │───────────────>│ homelab-context│ │ │
|
||||
│ main │ │ │ │ │
|
||||
└────────┘ │ post-pull.sh │ │ │
|
||||
│ → tools/ │ │ │
|
||||
│ setup- │ │ │
|
||||
│ checks.sh │ │ │
|
||||
│ → checks/ │ │ │
|
||||
│ install.sh│ │ │
|
||||
│ │──cp *.sh ─>│ /opt/ │
|
||||
│ │ │ oikos/ │
|
||||
│ │ │ checks/ │
|
||||
└────────────────┘ └──────────┘
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant R as Git Repo
|
||||
participant T as Sync Timer (5min)
|
||||
participant H as Target Host
|
||||
|
||||
Note over R,T: Operator pushes scripts
|
||||
R->>T: git pull (homelab-context)
|
||||
T->>T: tools/post-pull.sh
|
||||
T->>T: → tools/setup-checks.sh
|
||||
T->>T: → checks/install.sh
|
||||
T->>H: cp *.sh → /opt/oikos/checks/
|
||||
```
|
||||
|
||||
## Defining a Check
|
||||
@@ -145,12 +129,26 @@ curl -X POST http://oikos:8090/api/v1/checks \
|
||||
|
||||
## Signal Lifecycle
|
||||
|
||||
```
|
||||
raised ──> acknowledged ──> acting ──> resolved
|
||||
│ │ │
|
||||
├── muted ├── muted ├── raised (retry)
|
||||
│ │ │
|
||||
└── resolved └── resolved └── failed
|
||||
```mermaid
|
||||
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 remaining
|
||||
acting --> failed
|
||||
|
||||
failed --> acknowledged: operator retry
|
||||
|
||||
muted --> raised: mute_until expired
|
||||
|
||||
resolved --> [*]
|
||||
```
|
||||
|
||||
Signals deduplicate: **one open signal per (target_entity_id, kind)**.
|
||||
@@ -177,24 +175,17 @@ Severity mapping:
|
||||
|
||||
## Data Flow (DB Tables)
|
||||
|
||||
```
|
||||
check_defs ──(scheduler reads)──> executeCheck()
|
||||
│ │
|
||||
│ ├── healthy? → resolve signal, upsert entity_status
|
||||
│ │
|
||||
│ └── unhealthy? → UpsertSignal(), insert metric_samples
|
||||
│
|
||||
▼
|
||||
signals ◄──── UpsertSignal (dedup by target+kind)
|
||||
│
|
||||
▼
|
||||
entity_status ◄── upsert (health, last_check_at)
|
||||
|
||||
metric_samples ◄── INSERT (every cycle, healthy or not)
|
||||
│
|
||||
▼
|
||||
metric_rollups_1h ◄── continuous aggregate
|
||||
metric_rollups_1d ◄── continuous aggregate
|
||||
```mermaid
|
||||
flowchart TD
|
||||
CD[check_defs] -->|scheduler reads| EC[executeCheck]
|
||||
EC -->|healthy?| RS[resolve signal + upsert entity_status]
|
||||
EC -->|unhealthy?| US[UpsertSignal dedup by target+kind]
|
||||
EC -->|every cycle| IM[INSERT metric_samples]
|
||||
US --> S[signals]
|
||||
RS --> ES[entity_status]
|
||||
IM --> MS[(metric_samples)]
|
||||
MS --> R1H[metric_rollups_1h continuous aggregate]
|
||||
MS --> R1D[metric_rollups_1d continuous aggregate]
|
||||
```
|
||||
|
||||
## Prerequisites for SSH Checks
|
||||
|
||||
Reference in New Issue
Block a user