Repository Public
1# Architecture — MacLustr Command Center (MCC)23État décrit : dépôt au commit `45f0d03` (version `0.1.0`), déploiement du 2026-11-18.4Ce document décrit ce que le code fait. Quand il s'écarte de `DESIGN-BRIEF.md`, c'est le code qui est décrit et5l'écart est signalé. Les faits de production marqués **[prod]** ont été observés par le responsable du6déploiement le 2026-11-18 et ne sont pas vérifiables depuis ce dépôt.78Documents liés : [SECURITY.md](SECURITY.md) · [OPERATIONS.md](OPERATIONS.md) · [API.md](API.md) ·9[AGENT-PROTOCOL.md](AGENT-PROTOCOL.md) · [METRICS-CATALOG.md](METRICS-CATALOG.md) ·10[ACCEPTANCE.md](ACCEPTANCE.md) · [DECISIONS/](DECISIONS/README.md) · [APPLE-APPS.md](APPLE-APPS.md) (rédigé séparément).1112## 1. Contexte (C4 niveau 1)1314MCC est un poste de pilotage d'infrastructure : il observe les machines d'un cluster (télémétrie, inventaire,15services, serveurs d'inférence, volumes) et permet d'y lancer des **actions typées**. Il est écrit à partir d'un16dépôt vide et cohabite avec l'ancien produit sans le lire ni le modifier ([ADR 0001](DECISIONS/0001-new-product-no-reuse.md)).1718```mermaid19flowchart LR20 owner["Propriétaire / opérateurs<br/>(navigateur, apps Apple)"]21 host_admin["Administrateur hôte<br/>(SSH + mccctl)"]22 subgraph mcc["MacLustr Command Center"]23 cp["Plan de contrôle<br/>(nœud hôte unique)"]24 ag["mcc-agent<br/>(un par machine)"]25 end26 gw["Passerelle publique existante<br/>(Caddy TLS + WireGuard)"]27 nodes["Machines du cluster<br/>(macOS, 1 Linux)"]28 apns["APNs (Apple)<br/>inactif : aucune clé"]29 backup["Second nœud<br/>(copie des sauvegardes)"]30 mld["mld<br/>(outil de déploiement existant)"]3132 owner -- "HTTPS clustr.spboucher.ai" --> gw --> cp33 ag -- "HTTPS sortant, requêtes signées" --> gw34 ag -- "lit (sans root)" --> nodes35 host_admin -- "hors bande" --> cp36 cp -. "push (non actif)" .-> apns37 cp -- "rsync restreint, 03:40" --> backup38 mld -- "place et supervise (PM2)" --> cp39```4041Acteurs et systèmes externes :4243| Élément | Rôle | Source |44|---|---|---|45| Utilisateurs (owner, admin, operator, viewer) | consultation, actions, administration | `services/internal/authz/authz.go` |46| Administrateur hôte | amorçage, récupération, sauvegarde, gel d'urgence, via `mccctl` en SSH | `services/cmd/mccctl/` |47| Passerelle publique | termine TLS, route `clustr.spboucher.ai` vers le port 8800 du nœud hôte | `infra/deploy/mld-manifest.json` (`tunnel`) |48| `mld` | outil existant utilisé « comme un opérateur » pour placer l'app et router le domaine | ADR 0001, 0009 |49| APNs | notifications push ; fournisseur implémenté, **inactif** faute de clé | `services/internal/notify/apns.go` |5051## 2. Conteneurs (C4 niveau 2)5253```mermaid54flowchart TB55 subgraph internet["Internet"]56 browser["Navigateur"]57 apple["Apps macOS / iOS<br/>(voir APPLE-APPS.md)"]58 agents["mcc-agent × N"]59 end60 gw["Passerelle (Caddy TLS)"]61 subgraph host["Nœud hôte (M4M64c en production)"]62 api["control-api (Go)<br/>0.0.0.0:8800<br/>REST /api/v1, SSE, WebAuthn, AASA,<br/>relais /agent/v1, proxy web"]63 web["web (Next.js standalone)<br/>127.0.0.1:8803"]64 ingest["telemetry-ingest (Go)<br/>8804 requêtes signées (HTTP loopback)<br/>8801 mTLS · 8805 santé"]65 orch["action-orchestrator (Go)<br/>127.0.0.1:8802 (santé)<br/>actions, jobs, alertes, notifications,<br/>calendrier d'entretien, ménage"]66 pg[("PostgreSQL 17<br/>base mcc, 127.0.0.1:5432")]67 secrets[/"~/.config/mcc<br/>AC agents, clés de signature,<br/>clé CSRF, clé de sauvegarde"/]68 ctl["mccctl (CLI hors bande)"]69 bk["mcc-backup (cron 03:40)"]70 end71 browser --> gw72 apple --> gw73 agents --> gw74 gw --> api75 api -- "tout sauf /api, /agent, AASA" --> web76 api -- "/agent/v1/* (relais, sans identifiants utilisateur)" --> ingest77 api --> pg78 ingest --> pg79 orch --> pg80 ctl --> pg81 bk --> pg82 ingest -. "agent-ca.key" .-> secrets83 orch -. "command-signing.key" .-> secrets84 api -. "csrf.key, audit-signing.key" .-> secrets85 bk -. "backup.key" .-> secrets86```8788| Conteneur | Binaire / source | Écoute en production **[prod]** | Défaut de développement (`services/internal/config/config.go`) |89|---|---|---|---|90| `control-api` | `services/cmd/control-api` | `0.0.0.0:8800` (seul port routé par la passerelle) | `127.0.0.1:8730` |91| `telemetry-ingest` | `services/cmd/telemetry-ingest` | `127.0.0.1:8801` (mTLS), `127.0.0.1:8804` (requêtes signées), `127.0.0.1:8805` (santé) | `8731`, `8734`, `8741` |92| `action-orchestrator` | `services/cmd/action-orchestrator` | `127.0.0.1:8802` (santé seulement) | `127.0.0.1:8732` |93| `web` | `apps/web` (Next.js 16, sortie `standalone`) | `127.0.0.1:8803` | `127.0.0.1:8733` |94| `mccctl` | `services/cmd/mccctl`, lanceur `scripts/mccctl` | — | — |95| `mcc-agent` | `services/cmd/mcc-agent`, `services/internal/agent/` | aucune écoute | — |96| PostgreSQL 17 | — | base `mcc` | `mcc_dev` |9798Écarts avec `DESIGN-BRIEF.md` §1 : les ports de production sont 8800–8805 (le brief donne les défauts 8730–8733) ;99`telemetry-ingest` écoute en **loopback** en production (le brief annonçait `0.0.0.0:8731` sur le LAN) parce que le100transport par défaut est devenu la requête signée relayée par `control-api`101([ADR 0004, amendement](DECISIONS/0004-agent-transport-mtls-lan.md)).102103Tous les services Go forment un seul module (`services/go.mod`, `go 1.26`). La coordination entre services passe104uniquement par PostgreSQL : tables durables et `LISTEN/NOTIFY` (canaux `mcc_events`, `mcc_commands`,105`mcc_command_updates`, `mcc_actions` — `services/internal/events/events.go`, `services/internal/actions/store.go`).106Il n'y a ni Redis ni file de messages ([ADR 0003](DECISIONS/0003-postgresql-native-timeseries.md)).107108## 3. Composants (C4 niveau 3)109110### 3.1 `control-api`111112```mermaid113flowchart TB114 req["Requête HTTP"] --> ctx["httpx.WithRequestContext<br/>id de corrélation, IP cliente (proxys de confiance)"]115 ctx --> log["AccessLog → Recover → SecurityHeaders"]116 log --> mux{"routage"}117 mux -- "/api/v1/events" --> sse["serveEvents (SSE)"]118 mux -- "/api/v1/*" --> strict["serveur strict généré (gen.go)"]119 mux -- "/agent/v1/*" --> relay["agentProxy → telemetry-ingest"]120 mux -- "/.well-known/apple-app-site-association" --> aasa["serveAASA"]121 mux -- "reste" --> webp["proxy inverse → web"]122 strict --> admit["core.admit (server.go)<br/>identifiants → limites → CSRF → permission → step-up"]123 sse --> admit124 admit --> h1["identityHandlers"]125 admit --> h2["adminHandlers"]126 admit --> h3["clusterHandlers"]127 admit --> h4["opsHandlers"]128 h1 --> idsvc["identity.Service<br/>WebAuthn, sessions, invitations"]129 h2 & h3 & h4 --> authz["authz.Decide / DecideFacets"]130 h4 --> actions["actions (catalogue, pré-vérifications, verrous)"]131 h1 & h2 & h3 & h4 --> audit["audit.Append (chaîne de hachage)"]132 audit --> outbox["events.Publish → events_outbox"]133```134135- **Contrat d'abord** ([ADR 0006](DECISIONS/0006-contract-first-three-clients.md)) : `packages/api-contracts/openapi.yaml`136 (132 opérations) génère `services/internal/api/gen.go` (types + serveur strict), `ops_gen.go` (table137 `Operations` : méthode, chemin, mode d'authentification, permission, step-up) et `unimplemented_gen.go`138 (réponse 501 par défaut). `tools/gen-api.py` produit ces fichiers ; `make gen-check` échoue s'ils sont périmés.139- **Application centrale de la sécurité** : `core.admit` (`services/internal/api/server.go`) refuse toute opération140 absente de `Operations`. Les handlers ajoutent les contrôles liés à la ressource (`core.authorize`) ou au contenu141 (`core.requireStepUp`, par exemple pour une action de criticité `high`).142- **Groupes de handlers** (`services/internal/api/groups.go`) : identité (`identity_handlers.go`), administration143 (`admin_*.go`), lecture du cluster (`cluster_*.go`), opérations (`ops_*.go`). Le test144 `TestEveryClusterAndAdminOperationIsImplemented` (`admin_test.go`) vérifie que les opérations cluster/admin ne145 tombent pas sur le 501 ; un recoupement fait pour ce document montre que les 132 opérations ont un handler146 (`StreamEvents` est servi hors du serveur généré, par `events_stream.go`).147- **Relais des agents** (`agent_proxy.go`) : retransmet `/agent/v1/*` vers l'écoute « requêtes signées » de148 `telemetry-ingest`, en supprimant `Cookie`, `Authorization` et l'en-tête `X-Forwarded-For` entrant (remplacé par149 l'adresse résolue par `control-api`). Il n'authentifie pas les agents.150151### 3.2 `telemetry-ingest`152153| Composant | Fichier | Rôle |154|---|---|---|155| Authentification mTLS | `services/internal/ingest/server.go` | certificat client de l'AC privée, numéro de série recherché dans `agents` (cache ≤ 5 s) |156| Authentification par requête signée | `services/internal/ingest/signed.go` | certificat + horodatage + nonce + signature ECDSA ; fenêtre ±90 s, cache de nonces en mémoire |157| Enrôlement, renouvellement | `enroll.go`, `services/internal/pki/pki.go` | jeton à usage unique, CSR, certificat 30 jours |158| Rapports | `report.go` | validation stricte, idempotence `(agent, seq)`, écriture en une transaction |159| Transport des commandes | `commands.go` | long-poll, accusé, sortie, résultat ; ne signe rien |160| Tâches de fond | `maintenance.go` | partitions, agrégats 1 min / 1 h, rétention, `events.Prune`, battement |161162### 3.3 `action-orchestrator`163164`services/cmd/action-orchestrator/main.go` héberge une boucle principale et cinq tâches périodiques, chacune sous un165verrou consultatif PostgreSQL (`orchestrator.Leader`) pour ne jamais tourner deux fois en même temps :166167| Tâche | Période | Paquet |168|---|---|---|169| Actions (expiration d'approbation, émission, réconciliation) | sur notification + balayage toutes les 2 s | `services/internal/orchestrator` |170| Jobs (placement, tentatives, planifications) | 2 s | `services/internal/jobs` |171| Alertes (évaluation des règles) | 15 s | `services/internal/alerts` |172| Notifications (file `alert_notifications` → APNs) | 5 s | `services/internal/notify` |173| Calendrier d'entretien (début/fin des fenêtres) | 10 s | `services/internal/maintenance` |174| Ménage (événements d'actions terminées, notifications livrées) | 1 h | `services/internal/orchestrator/housekeeping.go` |175176L'orchestrateur est le **seul** détenteur de la clé de signature des commandes (`command-signing.key`,177`services/internal/orchestrator/signer.go`) ; seule la clé publique est écrite en base (`command_keys`).178179### 3.4 `mcc-agent`180181| Paquet (`services/internal/agent/…`) | Rôle |182|---|---|183| `collect` (`platform_darwin.go`, `platform_linux.go`, `parsers.go`) | métriques et inventaire, sans cgo ni root |184| `services` | découverte PM2, launchd, systemd, docker ; serveurs d'inférence (`inference.go`) |185| `client` | transports (URL = requêtes signées, `host:port` = mTLS), bascule entre points d'accès |186| `spool` | tampon disque hors ligne (6 h / 20 Mio) |187| `policy` | liste blanche locale `policy.json` |188| `nonce`, `journal` | anti-rejeu persistant, journal des commandes (reprise après crash) |189| `executor`, `runcmd` | exécution sans shell, délais, plafonds de sortie, expurgation |190| `state` | répertoire d'état (`~/.mcc-agent`, 0700) |191192Détail du protocole : [AGENT-PROTOCOL.md](AGENT-PROTOCOL.md).193194### 3.5 `web`195196Next.js 16 (App Router, React 19, TypeScript strict), sortie `standalone`, servie derrière `control-api`197(même origine). Aucune récupération de données côté serveur : chaque page est une coquille rendue côté client qui198n'appelle que `/api/v1` (`apps/web/next.config.ts`). `apps/web/src/proxy.ts` pose une CSP à nonce par requête.199Types générés depuis le contrat (`apps/web/src/api/schema.d.ts`), bibliothèque de composants propre200(`apps/web/DESIGN-SYSTEM.md`), langues fr/en (`apps/web/src/i18n/`), jetons de design partagés201(`packages/ui-tokens/`). Captures : `docs/screenshots/web/`.202203## 4. Flux de données204205### 4.1 Télémétrie206207```mermaid208sequenceDiagram209 participant A as mcc-agent210 participant G as Passerelle (TLS)211 participant C as control-api (relais)212 participant I as telemetry-ingest213 participant P as PostgreSQL214 participant U as Client (SSE)215 loop toutes les 10 s (ReportAck.interval_s)216 A->>A: collecte (échantillons, disponibilité, services…)217 A->>G: POST /agent/v1/report (cert, ts, nonce, signature)218 G->>C: HTTP219 C->>I: relais (sans Cookie ni Authorization)220 I->>I: chaîne AC, validité, révocation, fenêtre ±90 s, signature, nonce221 I->>P: 1 transaction : samples_raw, node_state, services, volumes, inventaire, events_outbox222 I-->>A: ReportAck {seq, interval_s, want_inventory, renew_cert…}223 P-->>C: NOTIFY mcc_events224 C-->>U: event: node.state225 end226 Note over A: hors ligne : rapport écrit dans spool/, rejoué dans l'ordre (buffered=true)227 Note over I,P: toutes les 20 s : agrégats raw → 1 min → 1 h (verrou consultatif)228```229230Règles importantes (`services/internal/ingest/report.go`) : un rapport en double est acquitté sans être réappliqué ;231un rapport `buffered` ou plus ancien que l'état stocké n'apporte que des échantillons et n'écrase jamais l'état232courant ; une métrique non mesurable est déclarée dans `availability` et ne produit aucun échantillon233([ADR 0007](DECISIONS/0007-unprivileged-agent.md)). La fraîcheur (`fresh` < 30 s, `stale` 30–120 s, `offline` au-delà)234est calculée par le serveur à la lecture (`MCC_FRESH_AFTER`, `MCC_OFFLINE_AFTER`).235236### 4.2 Commande (action)237238```mermaid239sequenceDiagram240 participant U as Utilisateur241 participant C as control-api242 participant P as PostgreSQL243 participant O as action-orchestrator244 participant I as telemetry-ingest245 participant A as mcc-agent246 U->>C: POST /actions (Idempotency-Key)247 C->>C: permission sur la cible, step-up, confirmation, justification, pré-vérifications248 C->>P: INSERT actions (+ action_locks) + audit, NOTIFY mcc_actions249 C-->>U: 201 Action (queued ou pending_approval)250 opt criticité critical251 U->>C: POST /actions/{id}/approve (autre personne, step-up)252 end253 O->>P: prend l'action (FOR UPDATE SKIP LOCKED), refait les pré-vérifications254 O->>O: signe l'enveloppe (Ed25519, validité 90 s, nonce)255 O->>P: INSERT agent_commands (1 par action) + état dispatched, NOTIFY mcc_commands256 A->>I: GET /agent/v1/commands?wait=25 (long-poll)257 I-->>A: SignedCommand (remise une seule fois)258 A->>A: FREEZE ? signature, destinataire, expiration, nonce, politique locale, paramètres259 A->>I: POST …/ack {accepted}260 A->>I: POST …/events (sortie expurgée)261 A->>I: POST …/result262 I->>P: agent_commands, action_events, NOTIFY mcc_command_updates263 O->>P: réconcilie : succeeded / failed / timed_out (+ outcome_unknown), libère le verrou264 P-->>C: NOTIFY mcc_events265 C-->>U: event: action.changed / action.output266```267268Propriété centrale ([ADR 0010](DECISIONS/0010-at-most-once-commands.md)) : une action émet **au plus une** commande269(index unique `agent_commands_one_per_action`, migration `0006_ops.sql`) et rien ne la ré-émet. Une commande jamais270remise finit `failed / agent_unreachable` ; une commande remise sans résultat avant l'échéance finit271`timed_out` avec `result.outcome_unknown=true` (`services/internal/orchestrator/orchestrator.go`).272Les types `node.maintenance.set` et `job.cancel` sont exécutés par l'orchestrateur lui-même, sans commande agent273(`ServerSide` dans `services/internal/actions/catalog.go`).274275### 4.3 Événements temps réel276277```mermaid278sequenceDiagram279 participant S as Service producteur280 participant P as PostgreSQL281 participant H as events.Hub (control-api)282 participant C as Client283 S->>P: dans la transaction métier : INSERT events_outbox (seq) + pg_notify('mcc_events')284 P-->>H: NOTIFY à la validation (et réveil de sécurité toutes les 5 s)285 C->>H: GET /api/v1/events (Last-Event-ID: n)286 H-->>C: retry: 3000 / event: hello {head}287 H->>P: SELECT … WHERE seq > n288 H-->>C: id: seq / event: topic / data: payload (filtré par permission)289 H-->>C: ": ping" toutes les 15 s290 Note over H,C: position purgée (rétention 1 h) → event: resync, le client recharge par REST291 Note over H,C: flux fermé après 30 min ; session revérifiée chaque minute292```293294L'événement est écrit dans la même transaction que le changement d'état : un client ne voit jamais un événement295non validé, et une coupure retarde les événements sans les perdre (dans la limite d'une heure). Formes des charges296utiles et écarts avec le contrat : [API.md §5](API.md#5-flux-dévénements-sse).297298### 4.4 Authentification299300```mermaid301sequenceDiagram302 participant B as Navigateur303 participant C as control-api304 participant P as PostgreSQL305 Note over B,C: Invitation (lien /setup#jeton, le fragment ne quitte pas le navigateur)306 B->>C: POST /invitations/exchange {token}307 C->>P: UPDATE invitations SET consumed_at … WHERE consumed_at IS NULL (atomique)308 C-->>B: cookie mcc_setup (10 min)309 B->>C: POST /auth/webauthn/registration/begin310 C-->>B: défi (5 min, usage unique)311 B->>C: POST …/registration/finish {credential}312 C->>P: 1 transaction : compte, passkey, invitation terminée, session, audit313 C-->>B: cookie mcc_session + csrf_token314 Note over B,C: Connexion ultérieure (sans nom d'utilisateur)315 B->>C: POST /auth/webauthn/authentication/begin316 B->>C: POST …/authentication/finish {challenge_id, credential, client}317 C->>C: défi consommé, origine, RP ID, UV, compteur de signature318 C-->>B: cookie mcc_session + csrf_token (web) ou jetons d'accès/rafraîchissement (natif)319```320321Détails et politiques : [SECURITY.md §3–§5](SECURITY.md#3-passkeys--webauthn), exemples : [API.md §3](API.md#3-authentification).322323## 5. Frontières de confiance324325```mermaid326flowchart LR327 subgraph z0["Zone 0 — Internet (non fiable)"]328 c["Clients"]329 a["Agents (chaque nœud = sa propre zone)"]330 end331 subgraph z1["Zone 1 — Passerelle (termine TLS)"]332 gw["Caddy"]333 end334 subgraph z2["Zone 2 — Nœud hôte"]335 api["control-api"]336 ing["telemetry-ingest"]337 orch["action-orchestrator"]338 db[("PostgreSQL")]339 sec[/"~/.config/mcc"/]340 end341 c --> gw --> api342 a --> gw343 api --> ing344 api --> db345 ing --> db346 orch --> db347 orch -.-> sec348```349350| Frontière | Ce qui est vérifié au passage | Ce qu'un composant compromis en amont ne peut pas faire |351|---|---|---|352| Internet → `control-api` | session ou jeton, CSRF + `Origin`, permission, step-up, limites de débit | — |353| `control-api` → `telemetry-ingest` | rien (relais) ; l'ingestion vérifie elle-même chaque requête d'agent | `control-api` ne peut pas forger une requête d'agent (pas de clé d'agent) |354| `telemetry-ingest` → agent | l'agent vérifie la signature Ed25519 de l'orchestrateur, le destinataire, l'expiration, le nonce, puis sa politique locale | l'ingestion (ou la passerelle) peut retarder ou jeter une commande, pas en forger, en modifier ni en rejouer |355| Agent → `telemetry-ingest` | certificat de l'AC privée, non révoqué, preuve de possession par requête | un agent ne voit que les commandes qui lui sont adressées (`404 command_not_found` sinon) |356| Hôte (SSH) → base | accès direct ; opérations `mccctl` auditées avec `actor_kind=cli` | — |357358Limite assumée : le nœud hôte est une seule zone. Un attaquant ayant le compte du service sur l'hôte lit la base et359`~/.config/mcc`, donc toutes les clés (voir [SECURITY.md §14](SECURITY.md#14-lacunes-connues)).360361## 6. Modèle de données362363Schéma : `services/internal/db/migrations/0001_init.sql` à `0006_ops.sql`, appliqué au démarrage par `control-api`364et `action-orchestrator` (`db.Migrate` : un fichier par transaction, verrou consultatif, somme de contrôle — une365migration déjà appliquée puis modifiée est refusée). Toutes les clés primaires sont des UUID v7366(`services/internal/ids`). Les horodatages sont lus en UTC (`services/internal/db/db.go`).367368```mermaid369erDiagram370 users ||--o{ passkeys : "possède"371 users ||--o{ devices : "possède"372 devices ||--o{ sessions : "porte"373 sessions ||--o{ refresh_tokens : "rotation (natif)"374 users ||--o{ invitations : "crée"375 invitations ||--o{ invitation_transactions : "ouvre"376 nodes ||--o| agents : "1 agent actif"377 nodes ||--o| node_state : "dernier état"378 nodes ||--o{ services : "héberge"379 nodes ||--o{ inference_servers : "héberge"380 nodes ||--o{ volumes : "monte"381 nodes ||--o{ samples_raw : "mesure"382 alert_rules ||--o{ alerts : "déclenche"383 incidents ||--o{ alerts : "regroupe"384 actions ||--o| agent_commands : "au plus 1"385 actions ||--o{ action_events : "journalise"386 actions ||--o| action_locks : "verrouille"387 jobs ||--o{ actions : "1 par tentative"388 job_schedules ||--o{ jobs : "planifie"389 maintenance_windows ||--o{ maintenance_window_nodes : "vise"390```391392| Domaine | Tables | Remarques |393|---|---|---|394| Identité | `users`, `passkeys`, `webauthn_challenges`, `devices`, `sessions`, `refresh_tokens`, `invitations`, `invitation_transactions` | jetons stockés hachés (SHA-256) uniquement |395| Autorisation | `policy_grants` | `allow` / `deny` par sujet (utilisateur ou rôle), permission, ressource |396| Audit | `audit_log` | chaîne de hachage ; déclencheurs refusant `UPDATE`, `DELETE`, `TRUNCATE` |397| Inventaire | `nodes`, `agents`, `agent_enrollment_tokens`, `node_state`, `services`, `service_events`, `inference_servers`, `volumes`, `nas_targets`, `nas_observations`, `backups` | un seul agent actif par nœud (index partiel `agents_one_active_per_node`) |398| Séries temporelles | `metric_catalog`, `samples_raw`, `samples_1m`, `samples_1h`, `rollup_state`, `rollup_dirty`, `agent_report_seqs` | partitions par plage de temps |399| Alertes | `alert_rules`, `alerts`, `incidents`, `timeline_events`, `silences`, `alert_notifications` | une alerte ouverte par empreinte (index `alerts_open_fingerprint`) |400| Entretien | `maintenance_windows`, `maintenance_window_nodes`, `maintenance_notes` | |401| Actions et jobs | `actions`, `action_locks`, `action_events`, `agent_commands`, `command_keys`, `jobs`, `job_schedules` | |402| Plateforme | `events_outbox`, `settings`, `service_heartbeats`, `user_dashboards`, `schema_migrations` | `settings` ne contient aucun secret |403404La table `rate_limits` existe dans `0001_init.sql` mais n'est référencée par aucun code Go : les limites de débit405sont en mémoire (`services/internal/httpx/ratelimit.go`).406407## 7. Choix techniques408409| Choix | Raison résumée | ADR |410|---|---|---|411| Produit neuf, aucune reprise de l'ancien | mandat | [0001](DECISIONS/0001-new-product-no-reuse.md) |412| Go pour les services et l'agent (binaire statique, `CGO_ENABLED=0`) | 8 Macs sans Homebrew ni Node ; passerelle linux/amd64 ; protocole partagé à la compilation | [0002](DECISIONS/0002-go-backend-and-agent.md) |413| PostgreSQL partitionné, pas de TimescaleDB ni de Redis | extension absente partout ; volume modeste | [0003](DECISIONS/0003-postgresql-native-timeseries.md) |414| Agents en sortie seulement ; requêtes signées via l'origine publique par défaut ; commandes signées par l'orchestrateur | confidentialité du réseau local de macOS mesurée sur m4ml | [0004](DECISIONS/0004-agent-transport-mtls-lan.md) |415| Passkeys seulement, sessions opaques, récupération hors bande | révocation immédiate, pas de secret partagé | [0005](DECISIONS/0005-passkeys-only-identity.md) |416| OpenAPI 3.1 comme contrat unique, clients générés | une seule vérité pour trois clients | [0006](DECISIONS/0006-contract-first-three-clients.md) |417| Agent sans root, métriques non mesurables déclarées | sudo sans mot de passe sur 7 Macs seulement | [0007](DECISIONS/0007-unprivileged-agent.md) |418| Catalogue d'actions typées, pas de shell distant | moindre privilège | [0008](DECISIONS/0008-no-arbitrary-shell.md) |419| Hôte unique derrière la passerelle existante | robustesse par simplicité ; pas de réplication | [0009](DECISIONS/0009-hosting-and-exposure.md) |420| Au plus une commande par action ; issue inconnue = état, jamais une relance | sûreté des opérations sur des machines réelles | [0010](DECISIONS/0010-at-most-once-commands.md) |421422## 8. Modes dégradés et comportement en panne423424| Situation | Comportement (source) | Preuve |425|---|---|---|426| **Base indisponible — ingestion** | toutes les routes répondent `503` avec `Retry-After` ; le service reste en marche et attend la base au démarrage (`cmd/telemetry-ingest/main.go`) ; les agents tamponnent | `TestDatabaseOutage` (`services/internal/ingest/integration_test.go`) |427| **Base indisponible — orchestrateur** | attend la base au démarrage (`connect`) ; les passes échouent, reprennent avec recul, puis tout est réconcilié depuis les tables | `TestSurvivesDatabaseConnectionLoss` (`services/internal/orchestrator/orchestrator_test.go`) |428| **Base indisponible — `control-api`** | `GET /health/ready` répond `503 unavailable` ; un flux SSE ouvert est fermé (le client se reconnecte avec son dernier id) ; `GET /admin/status` rapporte `database: down`. Au **démarrage**, `control-api` n'attend pas la base : `db.Open` échoue, le processus sort et c'est PM2 (`autorestart`) qui le relance | lecture du code (`identity_handlers.go`, `events_stream.go`, `admin_settings.go`, `cmd/control-api/main.go`) ; **pas de test automatisé dédié** à une coupure de base côté API |429| **Ingestion arrêtée** | le relais répond `503 unavailable` + `Retry-After: 15` ; les agents tamponnent (6 h / 20 Mio) puis rejouent sans doublon ; les nœuds passent `stale` puis `offline` ; `/admin/status` montre l'ingestion `degraded` (> 30 s) puis `down` (> 120 s) | `TestOfflineBufferingAndReplay` (ingest), `admComponent` (`admin_settings.go`) |430| **Chemin Internet coupé** (passerelle ou tunnel) | même effet que ci-dessus pour les agents ; l'interface est elle aussi injoignable puisqu'elle passe par la même entrée (compromis assumé, ADR 0004). Au-delà de 6 h, les rapports les plus anciens sont perdus | lecture de `services/internal/agent/spool/spool.go`, `TestBounds` |431| **Agent hors ligne** | nœud `offline` après 120 s ; règle intégrée « Node offline » ; une action demandée est refusée `422 agent_offline` ; une action déjà émise et jamais remise finit `failed / agent_unreachable` | `TestAbsenceRule` (alerts), `TestCreateActionRefusals` (api), `TestUndeliveredCommandIsAgentUnreachable` (orchestrator) |432| **Redémarrage de l'orchestrateur** | aucun état en mémoire ; aucune seconde commande n'est émise ; les actions en vol sont réconciliées | `TestCrashRestartNeverIssuesASecondCommand`, `TestTwoInstancesNoDuplicates`, `TestLeaderRunsOnce` |433| **Crash de l'agent pendant une commande** | au redémarrage, commande rapportée `failed` avec `outcome_unknown=true`, jamais relancée | `TestUnresolvedAfterCrash` (agent/journal), `TestUnknownOutcomeAfterAgentCrash` (ingest) |434| **Redémarrage de l'ingestion** | cache de nonces des requêtes perdu : protection anti-rejeu réduite à la fenêtre ±90 s (appels idempotents) | documenté dans `signed.go` ; non testé en tant que tel |435| **Redémarrage de `control-api`** | les sessions survivent (elles sont en base) ; le client SSE reprend avec `Last-Event-ID` | test Playwright « the connection indicator reacts to a backend restart… » (`apps/web/e2e/specs/04-realtime.spec.ts`) |436| **Web (Next) arrêté** | `control-api` répond `503 unavailable` pour les pages ; l'API reste disponible | lecture de `server.go` (`rp.ErrorHandler`) |437| **Gel d'urgence** (`orchestrator.frozen`) | aucune commande émise ; `POST /actions` répond `503 orchestrator_frozen` ; les actions déjà en file attendent | `TestFreezeHoldsQueuedActions`, `TestCancelAndFreeze` |438439## 9. Capacité et rétention440441| Donnée | Rétention | Mécanisme | Réglage |442|---|---|---|---|443| `samples_raw` (10 s) | 7 jours | partitions journalières supprimées | `MCC_RETAIN_RAW` |444| `samples_1m` | 30 jours | partitions mensuelles + suppression | `MCC_RETAIN_1M` |445| `samples_1h` | 400 jours | idem | `MCC_RETAIN_1H` |446| `events_outbox` | 1 heure | `events.Prune` toutes les 5 min | constante `events.Retention` |447| `action_events` d'actions terminées | 90 jours | ménage horaire | réglage `retention.action_events_days` (lu par `housekeeping.go`, **non exposé** par l'API d'administration) |448| `alert_notifications` livrées | 30 jours | ménage horaire | — |449| `audit_log` | illimitée | jamais purgé | — |450| `agent_report_seqs`, `rollup_dirty` | rétention brute + 1 jour | `Server.Retention` | — |451| `nas_observations` | 24 heures | `Server.Retention` | — |452| Sauvegardes locales | 14 fichiers | `mccctl backup --keep 14` | manifeste `mld` |453454- **Volume attendu** : l'ordre de grandeur retenu à la conception est ≈ 6 M lignes brutes par jour pour 29 nœuds455 (ADR 0003). Ce chiffre est une estimation ; le volume réel en production n'a pas été relevé pour ce document.456- **Cardinalité bornée par rapport** (`report.go`) : ≤ 400 échantillons, ≤ 8 interfaces, ≤ 12 volumes,457 ≤ 15 processus, ≤ 200 services ; corps ≤ 1 Mio compressé, ≤ 4 Mio décompressé.458- **Charge de l'agent** : ≈ 0 % CPU et ≈ 25 Mo de mémoire résidente mesurés sur le nœud pilote **[prod]** ;459 23 Mo et 0,2 % d'un cœur dans le relevé local `docs/pilot/2026-11-18/evidence-signed.txt`. Plafond460 `GOMEMLIMIT=64MiB` dans les fichiers launchd/systemd.461- **Processus** : `max_memory_restart` 600 Mo (services Go) et 700 Mo (web) dans `infra/deploy/mld-manifest.json`.462- **Limites connues** : les réglages `retention.raw_days`, `retention.1m_days`, `retention.1h_days` modifiables463 dans l'interface d'administration **ne sont pas lus** par `telemetry-ingest`, qui applique sa configuration de464 démarrage. Seuil de révision du choix PostgreSQL natif : ≈ 50 M lignes/jour (ADR 0003).465466## 10. Limites / non vérifié467468- Aucune réplication de base ni bascule automatique : l'objectif de reprise est « restaurer la sauvegarde de la469 nuit sur un autre nœud, les agents rejouent leur tampon » ([OPERATIONS.md §9](OPERATIONS.md#9-déplacer-le-plan-de-contrôle-vers-un-autre-nœud)).470- Le comportement de `control-api` pendant une coupure de base n'est couvert par aucun test automatisé.471- `go test -race` n'a pas été exécuté sur les paquets `ingest` et `agent`.472- Les formes de plusieurs événements SSE émis diffèrent du contrat ([API.md §8](API.md#8-écarts-connus-entre-contrat-et-implémentation)).473- Les versions rapportées par `telemetry-ingest` et `action-orchestrator` ne sont pas estampillées par474 `make build` (les `-ldflags` ne visent que `internal/api`) : elles affichent `0.1.0-dev` et `dev`.475- Les applications natives ne sont pas décrites ici : voir [APPLE-APPS.md](APPLE-APPS.md).476