MH-4b-2 ProposalService::createApproveCommand — Plan-Review

Projekt: Steve-TradingBot · Phase: RECON-MH-4b-2 · Author: claude-opus-4-7[1m]
Generated: 2026-05-12 19:57 UTC · master HEAD: 3fd7846 (MH-4b-1 closed)
Status: NO CODE Plan-Review only — Operator-GO erforderlich vor MH-4b-2 Code-Phase

1 — Live-State Verification

2 — Konsumierte Artefakte

Pattern-Source: gui/app/Services/Apply/Baseline/ApplyBaselineService::createApplyCommand (Idempotency-Pre-Check, DB::transaction, writeAudit) + gui/app/Services/Apply/Baseline/BaselineHoldingsAllowlist::buildHardConfirmString (Hard-Confirm-Pattern <count>:<sha8>).

3 — MH-4b-2 Scope-Definition

Approve-Lebenszyklus-Stelle

Operator-Wizard (MH-5)
  ↓ submit final step
ProposalService::createApproveCommand()                ← MH-4b-2
  ↓
DB::transaction:
   - READ managed_proposals row (validation)
   - READ existing commands with idempotency-key (decide-pattern)
   - INSERT commands (status='pending', payload, key)
   - INSERT audit_events (managed.asset_promote_requested)
  ↓
==================== Service boundary ====================
  ↓
Worker --once / Daemon                                  ← MH-6
  ↓
_handle_approve_managed_proposal:
   - re-validate proposal_sha256 against on-disk file
   - Two-File-Atomic (managed_state.json + baseline_holdings.json)
   - UPDATE managed_proposals SET state='managed_active', decided_at=...
   - INSERT managed_assets_history
   - audit managed.asset_promoted

Welche States dürfen approved werden?

Erlaubt:

• risk_proposed — der einzige State, in dem approve_managed_proposal semantisch Sinn macht (Worker hat Engine + Writer ausgeführt, proposal_json + sha256 + file_path sind gesetzt)

Verboten (jeweils mit klarer Exception):

Plus die DB-Cache-Integrity-Checks:

proposal_sha256 + proposal_file_path Behandlung

Service liest beide aus managed_proposals row und echoed sie in den approve-Payload als Integrity-Snapshot:

{
  "proposal_sha256":    "sha256:abc...",
  "proposal_file_path": "/home/node/.openclaw/.../risk_proposals/<id>.json"
}

Vorteile:

• Worker MH-6 kann beim Execute den on-disk file lesen + sha256 neu berechnen + gegen payload.proposal_sha256 vergleichen → fängt Tampering zwischen Engine-Run und Worker-Execute ab
• Audit-Trail enthält den exakten hash der approved Variante
• Hard-Confirm-Trail: was Operator approved hatte ist sha-hash-verifiziert nachvollziehbar

proposal_id Validierung

Strict-ASCII Regex ^[a-zA-Z0-9_-]{1,128}$ (1:1 mirror MH-3b PROPOSAL_ID_REGEX). Service-internes private const + Parity-Test (analog ManagedProposalStateEnumTest).

Hard-Confirm-Format

Operator-pinned in MH-4b Plan-Review:

• Format: <asset>:<variant>
• z.B. "ETH:recommended" oder "BTC:conservative"
• case-sensitive (HardConfirmMismatchException bei case-mismatch)
• Build-Helper: ProposalService::buildHardConfirmString($asset, $variant)
• Filament-Wizard zeigt erwarteten String und Operator muss exakt eintippen

Confidence-Override-Logik

score = managed_proposals.proposal_json.confidence.overall_score
threshold = 0.50  // CONFIDENCE_THRESHOLD, parity mit MH-3a engine

if score < threshold AND confidenceOverride !== true:
    throw ConfidenceOverrideRequiredException(score, threshold)

if score < threshold AND confidenceOverride === true:
    payload['confidence_override_used'] = true
    audit.metadata['confidence_override_used'] = true
    // weiter mit approve

if score >= threshold:
    payload['confidence_override_used'] = false
    // confidenceOverride wird ignoriert (kein Effekt)

Idempotency-Pattern (Shared-Key mh:decide:<pid>)

Wichtig: Service muss existing->command_type prüfen, NICHT nur Existence. Bei Mismatch → explicit exception (kein silent return des falschen Typs).

Was wird gelesen vs. geschrieben

READ (SELECT):

• managed_proposals row by proposal_id
• commands row by idempotency_key (existing-decide check)

WRITE (INSERT):

• commands (new approve command, status=pending)
• audit_events (managed.asset_promote_requested)

NEVER WRITE/UPDATE:

• managed_proposals (Worker MH-6)
• managed_assets_history (Worker MH-6)
• jede File (no FS write)

4 — Strict Boundary

5 — Sonder-Anforderungen geprüft

6 — Empfohlene Lieferung

Service-API

ProposalService::createApproveCommand(
    string  $proposalId,         // ^[a-zA-Z0-9_-]{1,128}$
    int     $userId,             // > 0
    string  $variant,            // ∈ {recommended, conservative, aggressive}
    array   $overrides,          // optional, whitelist [stop_loss, take_profit, max_allocation_usdt, trailing_stop_enabled]
    string  $hardConfirm,        // exact match "<asset>:<variant>"
    bool    $confidenceOverride = false,
): Command

ProposalService::buildHardConfirmString(string $asset, string $variant): string
    // returns "<asset>:<variant>"

Erlaubte Service-Methoden

• createRequestCommand(...) (MH-4b-1, existing)
• createApproveCommand(...) (MH-4b-2, neu)
• private validateProposalId(string)
• private validateVariant(string)
• private validateOverrides(array) (whitelist)
• private validateHardConfirm(string $hc, string $asset, string $variant)
• private validateConfidence(array $proposalJson, bool $override): bool
• private loadProposal(string $pid): ManagedProposal (returns row or throws)
• private assertApprovable(ManagedProposal $p) (state + decided_at + json/sha/path null-checks)
• private assertIdempotencyAvailable(string $key) (decide-pattern check)
• static buildHardConfirmString(string $asset, string $variant): string
• private writeAudit(...) (existing helper)

Verbotene Service-Methoden

• Command::update() — Worker setzt status; Service nur INSERT-pending
• ManagedProposal::create() / ->save() / ->update() — Worker MH-6 only
• ManagedAssetHistory::* — Worker MH-6 only
• File-IO (file_get_contents(, file_put_contents(, fopen(, fwrite(, fputs()
• Subprocess (exec(, shell_exec(, proc_open(, passthru(, system(, popen()
• environment != 'testnet' Akzeptanz

Exception-Liste

Operator hatte 4 Exceptions spezifiziert. Empfehlung: 5 Exceptions für maximale Caller-Klarheit:

Alternative (4 Exceptions, operator-original): ProposalNotFound wird in ProposalAlreadyDecidedException gefoldet mit detail='not_found'. → Operator entscheidet.

Payload-Schema (commands.payload_json)

{
  "environment":                "testnet",
  "proposal_id":                "<pid>",
  "asset":                      "<asset>",
  "variant":                    "recommended|conservative|aggressive",
  "overrides":                  { /* optional whitelisted keys */ },
  "hard_confirm":               "<asset>:<variant>",
  "confidence_override_used":   false,
  "confidence_score_at_decide": 0.65,
  "proposal_sha256":            "sha256:abc...",
  "proposal_file_path":         "/home/node/.../<pid>.json",
  "decided_by":                 <userId>,
  "expires_at":                 "<iso8601-z>"
}

overrides Whitelist:

• stop_loss (number)
• take_profit (number)
• max_allocation_usdt (number, positive)
• trailing_stop_enabled (bool)
• NICHT erlaubt: strategy_group, variant, confidence_threshold, andere keys → InvalidCommandPayloadException

7 — Test-Plan

8 — Stop-Regeln MH-4b-2

9 — Backup / Migration / Restart-Bedarf

→ MH-4b-2 = Reine Code+Test+Commit Phase.

10 — Risiken-Übersicht

11 — Kleinste sichere Code-Phase + GO/NO-GO Empfehlung

Subschnitt-Optionen

Empfehlung: MH-4b-2-monolithic

Begründung dieses Mal MONOLITHISCH (anders als MH-4b-1):

1. Approve ist atomar in der Logik — alle 5 Exceptions + Hard-Confirm + Confidence + Overrides bauen auf demselben Eingangs-Validation-Stack auf. Sub-Cuts würden den Validations-Stack unvollständig deployen → erhöhtes Bug-Risiko bei intermediate-state.
2. Pattern bereits etabliert — ApplyBaselineService::createApplyCommand ist die Vorlage; alle Sub-Mechaniken (DB::transaction, audit, idempotency) sind bewährt. Kein Pattern-Discovery in MH-4b-2.
3. Test-Vollständigkeit — Approve hat den größten Validation-Stack im gesamten MH-Service-Layer. Sub-Cuts würden Coverage-Lücken hinterlassen (z.B. Hard-Confirm würde in b fehlen wenn a deployed ist).
4. R5 / R6 / R10 nur durch volles Set abdeckbar — Race-Schutz, Stale-Cache und Atomicity sind kein add-on, sondern integral.
5. Rollback-Cost minimal — alles in einem Commit git revert-bar; DB hat 0 Rows im managed_proposals → 0 Side-Effect-Risiko.

Falls Operator dennoch Sub-Cut bevorzugt → MH-4b-2-a (Skelett + happy-path + ProposalNotFoundException) als Erstcommit ist die sicherste Variante (etablisiert das loadProposal-Helper-Pattern).

Pre-Implementation-Q an Operator

1. MH-4b-2-monolithic oder MH-4b-2-a (Skelett)? ← Empfehlung monolithisch
2. 5 oder 4 Exceptions? ProposalNotFound als 5. eigene Exception, oder in ProposalAlreadyDecidedException gefoldet? ← Empfehlung 5 separate Exceptions (Caller-Klarheit)
3. Hard-Confirm exakt <asset>:<variant> oder <asset>:<variant>:<sha8>? ← Empfehlung <asset>:<variant> (Operator-Original; sha256 ist im Payload separat)
4. Overrides-Whitelist: 4 keys (stop_loss / take_profit / max_allocation_usdt / trailing_stop_enabled) — alle akzeptieren? ← Empfehlung JA (Q-MH-3 Operator-Override-Scope)
5. CONFIDENCE_THRESHOLD = 0.50 als Service-Konstante mit Parity-Test gegen MH-3a — bestätigen? ← Empfehlung JA (Defense-in-Depth durch Parity-Pin)
6. Audit-event_type: managed.asset_promote_requested (Service-Layer-Event distinct von Worker-Success-Event managed.asset_promoted)? ← Empfehlung JA

Scope-Größe + Risiko-Bewertung MH-4b-2-monolithic

STOP vor Implementierung. Erwarte Operator-GO mit Subschnitt-Wahl (monolithisch empfohlen) + Q1-Q6-Approval.

© Steve-TradingBot · RECON-MH-4b-2 · Plan-Review (no-code phase)