Zum Inhalt

State Management

Stand: 2026-05-26

Ziel

Der Infrastructure State Layer trennt gewuenschten Zustand, beobachteten Zustand, Execution-Kontext und Drift-Bewertung. Er ist read-only und fuehrt keine Reconciliation aus.

State-Modell

Pflichtfelder:

Feld Zweck
object_id stabile Objektkennung
source_system Quellsystem, z. B. Proxmox, NetBox, NPM
created_by_chain wurde das Objekt durch eine Execution Chain erzeugt
approval_reference Approval-/Change-Referenz
backup_reference Backup-/Export-Referenz
current_state_hash Hash des beobachteten Zustands
desired_state_hash Hash des Sollzustands
last_verified_at letzter Pruefzeitpunkt
drift_detected Abweichung erkannt
rollback_possible Rollback technisch moeglich
cleanup_state Cleanup-/Lifecycle-Status

State-Kategorien

  • desired_state: dokumentierter Sollzustand aus Chain, Approval, NetBox oder Runtime-Konfiguration
  • observed_state: aktuell gelesener Zustand aus Zielsystem
  • execution_state: Approval, Backup, Rollback und Chain-Kontext
  • drift_state: Abweichungen zwischen Soll und Ist

Unterstuetzte Objektklassen

  • Proxmox LXCs
  • NetBox Objekte
  • NPM Proxy Hosts
  • VLAN-Zuordnungen
  • AI Runtime Services

API

  • GET /state/policy
  • GET /state/lxc-124-desired
  • POST /state/drift-check
  • GET /scheduled-workflows/trends
  • GET /ops/state-timeline/lxc-124

Alle Endpunkte sind read-only. POST /state/drift-check nimmt Soll/Ist entgegen und liefert Hashes, Drift und einen Plan-only Reconciliation-Vorschlag.

Scheduled Workflows nutzen den State Layer für drift_visibility_v1. Der aktuelle Stand erzeugt nur Trend- und Drift-Sichtbarkeit, keine Reconciliation und keine automatische Korrektur.

Timeline und Historie

GET /ops/state-timeline/lxc-124 korreliert State, Approval, Backup, Rollback und Drift für das kontrollierte Testobjekt.

Die Antwort enthält:

  • state_version
  • change_versions
  • Approval-Korrelation
  • Rollback-Korrelation
  • Drift-Status
  • Hash-Integrity-Check

Auto-Reconciliation bleibt deaktiviert.

LXC 124

lanstyle-ce-test-01 ist das erste kontrollierte State-Testobjekt.

Sollzustand:

  • CTID 124
  • Hostname lanstyle-ce-test-01
  • Status stopped
  • 1 vCPU
  • 1024 MiB RAM
  • 512 MiB Swap
  • 8 GiB Disk
  • VLAN 70
  • IP 10.222.70.124/24
  • Gateway 10.222.70.1
  • Beschreibung Controlled Execution Chain Test LXC

Ownership:

  • chain_created=true
  • managed_by_controlled_execution=true
  • Approval: appr-chain-lanstyle-ce-test-01-create-20260526-134137

Lock-Felder

State Records zeigen zusaetzlich:

  • object_locked
  • lock_id
  • lock_owner
  • pending_chain
  • cleanup_pending
  • reconciliation_pending

Damit kann OpenCode sehen, ob ein Objekt gerade durch Execution, Cleanup oder Reconciliation reserviert ist.

Orphaned oder failed-release Locks duerfen nicht automatisch ignoriert werden. Sie zeigen an, dass ein Chain-Lauf nicht sauber abgeschlossen wurde und manuelle Pruefung erforderlich ist.

Der State Layer liest aktive Lock-Informationen aus SQLite. Dadurch zeigen object_locked, lock_owner und pending_chain den operationalen Zustand, nicht nur historische JSONL-Events.

Bei Lock Recovery muss der State Layer vorab genutzt werden, um Objektkonsistenz und Drift-Status zu pruefen. Ein Lock darf nicht released werden, nur weil er alt ist.

Operator-Artefakte

State-/Drift-Ausgaben koennen in Changeplan-Artefakte eingebettet werden. Fuer OpenCode sind besonders relevant:

  • state_summary
  • drift_summary
  • lock_summary
  • cleanup_prepare_summary
  • risk_summary

Fuer LXC 124 existiert ein Beispiel-Endpunkt:

GET /changeplan-artifacts/lxc-124-examples

Der Endpoint erzeugt nur Artefaktdateien und fuehrt keine Proxmox-, NetBox-, DNS-, NPM- oder Firewall-Aenderung aus.