Zum Inhalt

Execution Chains

Stand: 2026-05-26

Ziel

Execution Chains erweitern den Controlled Execution Layer von Einzelaktionen auf mehrstufige, nachvollziehbare Workflows. Sie sind aktuell fuer Mock-/Dry-Run-Chains und eine eng begrenzte produktionsnahe Proxmox-Test-Chain aktiv.

Status

Bereich Status
Live-Infrastruktur-Writes nur proxmox_test_chain_v1 fuer LXC 121
Mock-Chain-Ausfuehrung aktiv
Step-Audit aktiv
Chain-Summary aktiv
Abort bei Fehler aktiv
Resumable Flag aktiv
Rollback-Planung aktiv
Cleanup-Preflight aktiv, plan-only

API-Endpunkte:

  • GET /execution-chains/policy
  • POST /execution-chains/mock-execute
  • POST /execution-chains/preflight

Preflight- und Execute-Antworten enthalten fuer OpenCode zusaetzlich:

  • operator_summary
  • unified_operator_response
  • changeplan_artifact
  • lock_candidates
  • lock_conflicts
  • execution_allowed
  • blocked_reason
  • backup_summary
  • rollback_plan
  • verification_summary
  • audit_reference

Damit kann OpenCode eine Chain als Changeplan anzeigen, ohne Roh-JSON interpretieren zu muessen.

unified_operator_response ist der bevorzugte Block fuer die Operations-Konsole. Er enthaelt Workflow-State, Action Classification, Human Decision Points, Timeline Summary, Suggested Actions, Warnings und Blockers.

Chain-Schema

Pflichtfelder:

  • chain_id
  • approval_id
  • requested_by
  • risk_level
  • steps

Step-Pflichtfelder:

  • step_id
  • target_system
  • action_type
  • requested_action

Governance-Felder:

Feld Zweck
parent_run_id gemeinsame Run-Referenz fuer alle Steps
execution_order Reihenfolge der Ausfuehrung
rollback_order Rueckbau-Reihenfolge
chain_status completed oder aborted
partial_failure_state Fehlerzustand fuer Resume/Rollback
resumable zeigt, ob ein Chain-Resume moeglich ist

Erlaubte Mock-Actions

  • mock:mock_noop_change
  • mock:mock_fail_after_backup
  • mock:mock_partial_rollback

Erlaubte produktionsnahe Test-Chain

proxmox_test_chain_v1 ist die erste echte, aber minimale Chain:

  1. proxmox:config_export
  2. proxmox:set_lxc_description

Einschraenkungen:

  • nur Node pve
  • nur LXC 121
  • nur Beschreibung Execution Chain Validation Test
  • keine Netz-, Storage-, Ressourcen- oder Guest-Lifecycle-Aenderungen
  • Rollback wird nur geplant und braucht eine separate Approval-ID

Alle anderen echten Zielsysteme wie NetBox, NPM, DNS, AD, Exchange, Intune oder Firewall bleiben fuer Chains deaktiviert, bis jede Step-Action separat scoped, verifiziert und freigegeben wurde.

Verhalten

  1. Jeder Step erzeugt ein eigenes Backup-Artefakt.
  2. Jeder Step schreibt einen eigenen Audit-Eintrag.
  3. Jeder Step braucht Verification.
  4. Beim ersten Fehler stoppt die Chain.
  5. Folge-Steps werden nicht ausgefuehrt.
  6. Rollback wird nur fuer erfolgreich abgeschlossene Steps geplant.
  7. Rollback-Reihenfolge ist umgekehrt zur Ausfuehrungsreihenfolge.

Tests

Durchgefuehrt am 2026-05-26:

Test Ergebnis
erfolgreiche Mock-Chain mit zwei Steps completed, steps_completed=2
fehlgeschlagene Mock-Chain aborted, steps_completed=1, resumable=true
Rollback-Plan nach Partial Failure ein Rollback-Step fuer den erfolgreichen Step
API Policy mock_dry_run_enabled
proxmox_test_chain_v1 completed, steps_completed=2, LXC 121 Beschreibung gesetzt
Replay derselben Chain-Approval aborted, Step config-export, Meldung approval_id was already consumed by a successful execution

Produktionsnaher Chain-Test:

  • Chain-Approval: appr-chain-proxmox-test-chain-v1-20260526-123850
  • Ziel: LXC 121
  • Beschreibung: Execution Chain Validation Test
  • Backup Step 1: /var/lib/lanstyle-agent/controlled-execution/backups/proxmox/20260526-102803-run-proxmox_test_chain_v1-20260526-102803-step1-config_export.json
  • Backup Step 2: /var/lib/lanstyle-agent/controlled-execution/backups/proxmox/20260526-102803-run-proxmox_test_chain_v1-20260526-102803-step2-set_lxc_description.json
  • Chain Audit: /var/log/lanstyle-agent/execution-chains.jsonl
  • Rollback Status: ready_requires_separate_approval
  • Dauer: 104 ms

Vor dem erfolgreichen Lauf gab es mehrere fail-closed Abbrueche ohne Write:

  • fehlender Python-Pfad fuer lanstyle_infra_mcp
  • fehlende lokale httpx-Abhaengigkeit im CLI-Kontext
  • nicht geladene Proxmox-Token-Umgebung
  • Proxmox TLS-Verifikation gegen internes Zertifikat

Die Korrekturen waren technische Runtime-Haertungen. Der erste erfolgreiche Write erfolgte erst nach geladenem Runtime-Environment und expliziter TLS-Policy fuer den internen Proxmox-API-Pfad.

Naechste Ausbaustufe

Vor echten Multi-Step-Infrastruktur-Changes braucht jede Step-Klasse:

  • eigene scoped Action
  • eigenes Backup
  • eigene Verification
  • eigenen Rollback-Pfad
  • klare Approval-Vererbung oder eigene Approval-ID pro Step
  • Test gegen Mock/Lab-Objekte

Golden Paths standardisieren diese Vorarbeit als wiederverwendbare Workflow-Templates. Sie erzeugen Preflight-/Mock-/Operator-Workflow-Artefakte, aber noch keine produktiven Writes. Details: Golden Paths.

Multi-System-Preflight lanstyle-ce-test-01

Der erste vorbereitete Multi-System-Orchestrierungsworkflow ist nur als Preflight aktiv.

Ziel:

  • Name: lanstyle-ce-test-01
  • CTID: 124
  • Node: pve
  • Storage: local-zfs
  • VLAN: 70
  • IP-Konzept: 10.222.70.124/24
  • Gateway: 10.222.70.1

Geplanter Workflow, noch nicht live:

  1. proxmox:create_lxc
  2. proxmox:set_resources
  3. proxmox:attach_vlan
  4. proxmox:set_lxc_description
  5. netbox:create_vm_object
  6. mkdocs:create_doc_stub
  7. Verification
  8. Audit
  9. Rollback-Planung

Aktiv umgesetzt ist nur:

  • POST /execution-chains/preflight
  • Config: agent-runtime/configs/lanstyle-ce-test-01-preflight.json
  • Live-Write: false

Preflight-Status am 2026-05-26:

  • CTID 124 ist nach Proxmox-Liste frei.
  • lanstyle-ce-test-01 ist in NetBox nicht vorhanden.
  • 10.222.70.124 ist nicht in NetBox reserviert und antwortet nicht auf Ping.
  • local-zfs hat ausreichend freie Kapazitaet.
  • Keine DNS-, NPM- oder Firewall-Aenderung ist Bestandteil von v1.

Proxmox-Create-Chain lanstyle-ce-test-01

Am 2026-05-26 wurde die erste echte Proxmox-Create-Chain mit der Approval-ID appr-chain-lanstyle-ce-test-01-create-20260526-134137 ausgefuehrt.

Scope:

  1. proxmox:create_lxc
  2. proxmox:set_resources
  3. proxmox:attach_vlan
  4. proxmox:set_lxc_description
  5. Verification
  6. Audit
  7. Rollback-Planung

Nicht im Scope:

  • NetBox Write
  • MkDocs Write
  • DNS
  • NPM
  • Firewall
  • freie Shell
  • Softwareinstallation

Ergebnis:

  • Chain-Status: completed
  • Steps: 4/4
  • Ziel: LXC 124, lanstyle-ce-test-01
  • Status nach Erstellung: stopped
  • Ressourcen: 1 vCPU, 1024 MiB RAM, 512 MiB Swap, 8 GiB Disk
  • Netzwerk: VLAN 70, 10.222.70.124/24, Gateway 10.222.70.1
  • Beschreibung: Controlled Execution Chain Test LXC
  • Rollback Status: ready_requires_separate_approval
  • Dauer: 4270 ms

Backups:

  • create-lxc: /var/lib/lanstyle-agent/controlled-execution/backups/proxmox/20260526-114721-run-lanstyle_ce_test_01_create-20260526-114721-step1-create_lxc.json
  • set-resources: /var/lib/lanstyle-agent/controlled-execution/backups/proxmox/20260526-114725-run-lanstyle_ce_test_01_create-20260526-114725-step2-set_resources.json
  • attach-vlan: /var/lib/lanstyle-agent/controlled-execution/backups/proxmox/20260526-114725-run-lanstyle_ce_test_01_create-20260526-114725-step3-attach_vlan.json
  • set-description: /var/lib/lanstyle-agent/controlled-execution/backups/proxmox/20260526-114725-run-lanstyle_ce_test_01_create-20260526-114725-step4-set_lxc_description.json

Replay-Schutz:

  • Eine erneute Ausfuehrung mit derselben Approval-ID wurde beim ersten Step blockiert.
  • Fehler: approval_id was already consumed by a successful execution

Folgezustand:

  • Kein NetBox-Objekt fuer lanstyle-ce-test-01.
  • Keine NetBox-IP 10.222.70.124/32.
  • Kein MkDocs-Doc-Stub.

Cleanup-Preflight lanstyle-ce-test-01

Vor weiteren echten Infrastructure-Creates wurde ein eigener Cleanup-/Destroy-Governance-Pfad ergaenzt.

Chain:

lanstyle_ce_test_01_cleanup_prepare

Config:

agent-runtime/configs/lanstyle-ce-test-01-cleanup-prepare.json

Plan-only Scope:

  1. proxmox:stop_lxc
  2. proxmox:archive_lxc_config
  3. proxmox:plan_remove_lxc
  4. netbox:plan_remove_vm_object
  5. mkdocs:plan_remove_doc_stub

Wichtig:

  • live_write_performed=false
  • remove_lxc_enabled=false
  • rollback_possible_after_remove_lxc=false
  • mandatory_cooldown_minutes=15
  • mandatory_double_confirmation=true
  • requires_separate_cleanup_approval=true

Die Actions sind bewusst als Preflight-/Plan-Schritte klassifiziert. Sie erzeugen keinen Destroy, keinen NetBox-Write und keinen MkDocs-Write.

Dependency-Befund fuer LXC 124:

  • LXC 124 existiert und ist gestoppt.
  • Kein NetBox-VM-Objekt lanstyle-ce-test-01.
  • Keine NetBox-IP 10.222.70.124/32.
  • Kein MkDocs-Doc-Stub.
  • Keine DNS-/NPM-/Firewall-Abhaengigkeiten in dieser Chain.

Der echte Destroy bleibt forbidden, bis es eine separate cleanup_execute-Approval, Cooldown, Double Confirmation, finalen Archiv-Export und explizite Operator-Freigabe gibt.

Policy-/Risk-Bewertung

Execution Chains koennen vor Execute durch die Policy-/Risk-Engine bewertet werden.

OpenCode- und API-Ausgaben sollen enthalten:

  • risk_badge
  • blast_radius_summary
  • maintenance_window
  • policy_violations
  • blocked_execution_reason
  • approval_escalation_required
  • dependency_lock_active

Die Bewertung ist read-only. Sie fuehrt keine Chain aus und erzeugt keine Approval-ID.

Dependency Locks

Vor jeder spaeteren echten Chain muss ein Lock-Check erfolgen.

Blockiert wird bei:

  • aktivem Write Lock auf demselben Objekt
  • aktivem Destructive Lock auf demselben Objekt
  • Global Lock auf dem Source System
  • Emergency Hold
  • Stale Lock ohne Manual Review

Eine Chain darf ihren eigenen Lock weiterverwenden, wenn chain_id und approval_id exakt passen. Alle anderen parallelen Chains werden blockiert. Es gibt in v1 keinen Queue-Mechanismus und keine automatische Fortsetzung nach Lock-Freigabe. Der Operator plant spaeter neu und fuehrt die Validierung erneut aus.

Lock Lifecycle

Vor jedem echten execute_chain wird automatisch ein Dependency Lock acquired.

Ergebnisregeln:

  • erfolgreicher Chain-Lauf: Lock wird nach Verification/Audit released
  • Chain-Failure nach Lock-Acquire: Lock wird als orphaned markiert
  • Release-Fehler: Lock wird als failed_release markiert
  • Lock-Konflikt vor Step 1: Chain bricht ohne Infrastruktur-Write ab
  • stale/expired aktiver Lock: Chain bricht ohne Infrastruktur-Write ab und verlangt Recovery-Preflight

Preflight liefert lock_candidates, lock_conflicts, execution_allowed, blocked_reason und lock_recommendation. Dauerhafte Preflight-Locks sind nur erlaubt, wenn sie explizit angefordert werden.

Der Lock-Store ist SQLite-basiert und nutzt atomare Transaktionen. Replay Protection greift vor Lock-Acquire, damit wiederholte Approval-IDs keinen neuen Lock erzeugen.

Wenn ein Chain-Lauf einen Lock als orphaned oder failed_release hinterlaesst, darf die naechste Chain nicht automatisch fortfahren. Zuerst muss Lock Recovery mit eigener Approval-ID abgeschlossen werden.

Lifecycle-Actions wie proxmox:start_lxc und proxmox:stop_lxc brauchen vor Execute mindestens einen Proxmox Config Export:

  • backup_required=true
  • backup_type=proxmox_config_export
  • kein Snapshot-Zwang fuer reine Start-/Stop-Aktionen

Timeline-Artefakte

Jede Chain-Antwort ist timeline-ready. Die Standardereignisse sind:

  1. planned
  2. approved
  3. lock_acquired
  4. backup_created
  5. step_started
  6. step_completed
  7. verification_completed
  8. audit_written
  9. lock_released
  10. completed, failed oder blocked

Die Markdown-/JSON-Artefakte liegen unter /var/lib/lanstyle-agent/controlled-execution/artifacts/ und werden in changeplan_artifact referenziert.