trading-system-docs/a4

Red Queen — A4: Bounded Orchestrator (V1)

Der Bounded Orchestrator verbindet erstmals kontrolliert die A1-Architektur, den A2 Mission/WP-State (missions.db, autoritativ für Transitionen), den A3 Deterministic Safety Layer (safety.db, verbindliche Safety-Decision) und die Hermes-native delegate_task-Sub-Agenten (Planner/Maker/Checker) zu einer expliziten, garantiert endenden Build-Pipeline:

MISSION → VALIDATE STATE → VALIDATE SAFETY → PLAN → VALIDATE PLAN
  → CREATE WORK PACKAGES → SELECT RUNNABLE WP → MAKER → TEST
  → FRESH CHECKER → SAFETY DECISION → STATE UPDATE → NEXT BOUNDED STEP
  → FINALIZE / STOP

WICHTIG: A4 ist KEIN 24/7-System. Kein Heartbeat, kein Mission-Cron, kein dauerhafter Worker, kein while-True-Agentloop, kein Background-Daemon, kein Self-Improvement-Automation, keine automatische Rain-Eskalation. A4 läuft nur nach einem expliziten Start und endet garantiert (bounded).

---

Architektur-Prinzip

Red Queen (ein Hermes-Agent) ist der Orchestrator. Der echte Sub-Agenten-Versand (Planner/Maker/Checker) läuft über die Hermes-native delegate_task-Engine — ein Python-Prozess kann diese NICHT aufrufen. Deshalb implementiert A4 die deterministische Orchestrierungs-Logik als reine, inaktive Python-Library (Orchestrator), die Red Queen als Entscheidungs- und State-Maschine importiert und ansteuert:

• Die Library entscheidet deterministisch: was ist runnable, Safety-Gate, Risk>Size, Approval-Gate, Completion-Gate, Bounded-Run-Limits, Repair-Flow, idempotente Wiederaufnahme, Restart-Persistenz.
• Red Queen selbst startet die tatsächlichen Child-Agenten (Planner/Maker/Checker) über delegate_task, übergibt ihnen das von der Library erzeugte Dispatch-Contract und führt das Ergebnis über apply_child_result zurück.
• Für Tests wird ein simuliertes ChildDispatcher-Callable injiziert — die Library selbst startet nichts und läuft nie zyklisch.

---

Datenfluss & Gates

Schritt	Mechanik	Verbindlich
1. Plan erhalten	von Planner	Output-Format laut AGENT_CONTRACTS
2. Plan-Validierung	PlanValidator.validate()	§6; ungültig → REJECT, keine Ausführung
3. WP-Anlage	A2 MissionStore	kein direkter SQL außerhalb A2-APIs
4. Runnable-Selection	select_runnable()	§8; DONE-Deps + READY + Safety CLOSED + Scope erlaubt
5. Consistency-Gate	_consistency_gate()	§9: A2-State + A3-Check vor JEDER Mutation
6. Risk-Klassifikation	classify_risk()	§26/27: RISK überschreibt SIZE
7. Approval-Gate	requires_approval()	§25: CRITICAL/Approval-Target → APPROVAL_REQUIRED
8. Dispatch	build_maker_contract / build_checker_contract	Minimum-Necessary-Context
9. Safety-Decision	A3 evaluate_next_action	verbindlich
10. Repair-Flow	RETRY max 3 / gleiche Error-Sig max 2	SAFETY_CONTRACT
11. Circuit-Enforcement	Circuit OPEN → NO MUTATION	§19
12. Completion-Gate	mission_completion_gate()	§20 + Final-Review-Gate
13. Bounded-Run	run_bounded()	§22: endet garantiert

---

A2/A3-Integration

A4 importiert und nutzt die bestehenden Module (kein Duplikat):

from a2.rq_mission import MissionStore   # autoritativ für Mission-/WP-Transitions
from a3.rq_safety  import SafetyStore      # verbindliche Safety-Decision

• A2 (missions.db) ist die autoritative Quelle für Mission-/WP-State und erlaubte Transitionen.
• A3 (safety.db) ist die verbindliche Safety-Decision (evaluate_next_action, check_safety_state, record_attempt, open_circuit).
• A4 selbst hält keine neue zentrale DB; Run-Flags/Sub-Agent-Evidence werden über A2/A3-APIs bzw. den A3-Safety-Evidence-Mechanismus persistiert.
• Import-Lösung: sys.path wird um Repo-Root und a4/ ergänzt (Path(__file__).resolve().parent.parent).

---

Planner/Maker/Checker-Contract

Rolle	Output	Gate
Planner	WORK_PACKAGES / DEPENDENCIES / RISK_CLASS / ORDER / TEST_REQUIREMENTS	Red Queen validiert deterministisch (§6)
Maker	IMPLEMENTATION_SUMMARY / FILES_CHANGED / TESTS_RUN / TEST_RESULTS	Nie final PASS
Checker	PASS / FAIL / Verdict	FRESH Child, ohne Maker-Argumentation

build_maker_contract und build_checker_contract erzeugen die Minimum-Necessary-Context-Contracts. Der Checker-Contract enthält bewusst keine Maker-Rechtfertigung (AGENT_CONTRACTS §3). Werte werden secret-redacted.

---

Bounded Run (Limits aus Konstanten)

MAX_WORK_PACKAGES_PER_RUN = 12
MAX_REPAIR_CYCLES          = 3     # entspricht A3 MAX_MAKER_CHECKER_REPAIRS
MAX_CHILDREN_ACTIVE        = 3
MAX_BOUNDED_RUNTIME        = 1000  # Sekunden / Steps

run_one_step() führt GENAU EINEN deterministischen Schritt aus und endet garantiert (keine Rekursion). run_bounded() stoppt bei MISSION_COMPLETED / BLOCKED / ESCALATED / CIRCUIT_OPEN / NO_RUNNABLE_WP / RUN_BUDGET_REACHED / ERROR — kein self-reschedule.

---

Approval Gates

WP, die laut ROOT_SSH_GATE einen kritischen Bereich berühren (SSH, Firewall, Auth, Secrets, Recovery, Red Queen Runtime, Circuit Breaker, Root Policy, Live Trading) → ST_APPROVAL_REQUIRED, keine Ausführung. Red Queen legt den Antrag im EXTERNAL_REVIEW-Format vor und wartet auf Christian.

---

Failure Handling / Idempotenz

• Failure: evaluate_next_action-Decision wird verbindlich befolgt (RETRY / DEBUG / SECOND_OPINION / BLOCK / CIRCUIT_BREAK). Repair max 3, gleiche Error-Signatur max 2. Kein implizit PASS, kein endlos Spawn.
• SECOND_OPINION → KEIN automatisches Rain (nur interner frischer Child oder BLOCK; Rain ausschließlich Christian-gated, EXTERNAL_REVIEW_CONTRACT).
• Idempotenz: DONE-WP wird nie erneut Maker; bereits registrierter Attempt nicht doppelt; COMPLETED-Mission nie erneut; gleiche Child-Task-ID nie doppelt gewertet.
• Restart: State in A2/A3-DBs persistent; nach Restart wird der Zustand gelesen, ohne doppelte WP-Ausführung oder verlorene Attempts.

---

Sub-Agent-Evidence (§30)

make_child_evidence() erzeugt einen maschinenlesbaren Evidence-Record (Child Role, Child Task ID, Mission ID, WP ID, Start, Result, Verdict) — KEINE Chain-of-Thought. Credentials werden redactiert (nur EXISTS/LENGTH/redacted).

---

CLI

rq_orchestrator_cli.py — --json, Exit-Code 2 bei OrchestratorError (A2/A3-Muster):

plan             Plan validieren + WP-Anlage
run-one-step     Einen deterministischen Schritt ausführen
run-bounded      Begrenzter Run (endet garantiert)
complete         Completion-Gate prüfen / Final-Review
status           Status abfragen
evaluate         A3-Safety-Decision
approve          Approval registrieren

---

Test Harness

python3 a4/test_a4.py — isolierte, deterministische Tests (temp-DBs, kein Netz, kein hermes). Injiziert simulierte ChildDispatcher. Exit-Code 0 = PASS. Deckt A4 §6–§33 ab: Plan-/Dependency-Validierung, Runnable-Selection, A2/A3- Consistency-Gate, Maker/Checker-Contract, Checker-Pass/Fail, Retry allowed/denied, Retry-4-Impossible, Circuit-open-blocks-Maker, Approval-Gate, Risk-overrides-Size, No-Runnable-Stop, Completion-/Final-Review-Gate, Idempotent-WP, Restart-Resume, Child-Failure, Reason-Codes, Secret-safe-Logging.

---

Known Limitations

• A4 selbst führt keine echte delegate_task aus (das macht Red Queen).
• Kein automatisches Rain; kein Heartbeat/Cron/Daemon.
• DEBUG ist als Schnittpunkt implementiert (leitet an A5-Debugger/Strategiewechsel weiter), erzwingt aber keine interne Debugger-Logik.