MH-3b ProposalWriter — Plan-Review

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

1 — Live-State Verification

2 — MH-3a-Konsumiertes Surface

Pattern-Referenz: trading/baseline_holdings_writer.py (600 LOC, RECON-2.1). Behält:

• tempfile.mkstemp + fsync + os.replace atomic-write
• MainnetBlockedError Exception
• ValidationError Exception
• ApplyResult frozen dataclass
• ALLOWED_ENVIRONMENTS = frozenset({"testnet"})
• restore_from_backup static helper

Unterschiede zum Baseline-Pattern:

• Proposal-Files sind immutable (per 01_foundation §3: „NIE überschrieben, NIE gelöscht"). Kein apply()-with-idempotency-skip — Writer refuses overwrite.
• Kein clear() Method — Proposals werden nur via separater TTL-Expiry-Cleanup-Job (MH-9) archive-moved, nicht direkt gelöscht.
• Kein canonical_hash für idempotency — proposal_id ist der natürliche Primärschlüssel.
• Per-File-Modell statt single-config-file: jeder Apply schreibt eine neue Datei <proposal_id>.json.
• Kein Backup-before-mutate (keine Mutation; nur erste Erzeugung).

3 — ProposalWriter Scope-Definition

3.1 — Target Layout

state/risk_proposals/
  └── <proposal_id>.json     ← eine Datei pro Engine-Output, immutable

3.2 — proposal_id Validierung (anti-path-traversal)

Validator-Regex (vorgeschlagen): ^[a-zA-Z0-9_-]{1,128}$ (akzeptiert UUID4 default + Engine custom-IDs).

Defense-in-Depth: nach Regex-Pass zusätzlich Path(filename).name == filename Check (PathLib normalisiert path; Identity-Check fängt Edge-Cases).

3.3 — Atomic Write Sequenz

1. Validate payload-dict shape (raises before IO):
   • proposal_id present + matches arg
   • proposal_version == 1
   • risk_model_version ∈ Whitelist (mindestens phase1-min-v1)
   • confidence.overall_score ∈ [0..1]
   • asset, generated_at, expires_at, generated_by present
2. Mainnet defense layer (Defense-in-Depth, unabhängig von Engine):
   • Settings.BINANCE_TESTNET != True → raise MainnetBlockedError
3. Ensure target_dir exists: os.makedirs(target_dir, exist_ok=True) (auto-create OK — keine Mutation existierender Files)
4. Collision check: if target_path.exists() → return ApplyResult(ok=False, error="proposal_id_collision"). Kein Overwrite, kein Backup-Move.
5. Atomic write:
   • tempfile.mkstemp(prefix=f"{proposal_id}.json.tmp.", dir=target_dir) (same FS → os.replace ist atomic)
   • json.dump(payload, f, indent=2, sort_keys=True, ensure_ascii=False)
   • f.flush() + os.fsync(f.fileno()) (Daten durable)
   • os.replace(tmp, target)
6. sha256 berechnen für ApplyResult (audit-relevant; analog Baseline-Writer)
7. Return ApplyResult(ok=True, target_path, sha256, written_at)

3.4 — Detailfragen

4 — Boundary-Contract

4.1 — Forbidden Imports (AST-pinned)

main · command_worker · live_trade · paper_trade · risk_manager

proposal_engine darf NICHT importiert werden (Writer ↛ Engine — sonst Zyklus). Writer akzeptiert plain dict-payload.

4.2 — Forbidden Source-Tokens (Grep-pinned)

• ccxt Order-API: create_market_*, create_order, cancel_order, edit_order, create_limit_order, cancel_all_orders
• File-Targets außerhalb risk_proposals: managed_state.json, baseline_holdings.json, runtime_config.json, live_portfolio.json, .env
• DB-Kopplung: INSERT INTO, execute(, cursor
• Network: kein ccxt-Import, kein requests, kein urllib

4.3 — Was Writer NICHT macht

5 — Integration mit MH-3a

Option A — Engine unverändert, Writer standalone (empfohlen)

• proposal_engine.py bleibt byte-identisch. dry_run=False raised weiter NotImplementedError.
• proposal_writer.py ist unabhängig instanziierbar.
• Caller-Pattern (für MH-6 worker handler):

  result = engine.generate(asset, operator_id, dry_run=True)
  if result.ok:
      apply_result = writer.apply(result.payload)

• Pro: Maximaler Scope-Lock; Engine bleibt byte-identical; Writer ist isoliert testbar; MH-3a Closure-Pin bleibt 1:1 gültig.
• Con: dry_run=False ist weiterhin „inaktiv". Erst MH-6 worker handler aktiviert den Full-Flow.

Option B — Engine bekommt optional writer-Konstruktor-Param

• Engine bekommt 1 neuen optionalen Kwarg: proposal_writer: Optional[ProposalWriter] = None.
• dry_run=False Pfad: wenn writer injected → writer.apply(payload); sonst weiter NotImplementedError.
• ProposalResult bekommt befüllte proposal_path + written_audit_event=False (audit-event bleibt Worker-Job).
• Pro: dry_run=False wird aktiv. Engine + Writer composable.
• Con: MH-3a Engine wird angefasst (kleine Mutation: 1 ctor-Param + 1 if-Branch). Engine-Tests müssen angepasst werden. AST-Boundary-Liste muss proposal_writer zulassen.

Option C — Engine ungenagelt, neue Compose-Methode in Writer

• Writer bekommt apply_from_engine_result(result: ProposalResult) Convenience-Methode.
• Engine bleibt unverändert.
• Pro: MH-3a Closure stays.
• Con: Subtile zirkuläre Type-Abhängigkeit (Writer kennt ProposalResult), Kohärenz schlechter als Option A.

Empfehlung: Option A

1. Klare Trennung von Computation vs. Persistence
2. Engine MH-3a closure bleibt zementiert
3. MH-6 worker handler ist die natürliche Orchestrierungs-Stelle
4. Tests für „dry_run=True schreibt nichts" bleiben byte-identisch — keine Re-Run-Diskussion

Dry-Run-Persistenz-Guarantee Test (Option A):

• test_dry_run_true_engine_does_not_call_writer: Mock-Writer in Test; Engine mit dry_run=True ruft Writer nie auf (Writer.apply call_count == 0). Bestätigt MH-3a Contract bleibt.
• Engine-Tests bleiben unverändert; kein NotImplementedError-Test-Anpassen nötig.

6 — Test-Plan

7 — Betroffene Dateien (Final-Inventory)

Erwartete Größenordnung: ~350-450 LOC Writer + ~700-850 LOC Tests = ~1100-1300 LOC total (analog MH-3a 1307 LOC).

8 — Stop-Regeln MH-3b

9 — Backup / Restart-Bedarf

→ MH-3b ist Code+Test+Commit auf master. Analog MH-2 / MH-3a.

10 — Identifizierte Risiken

11 — GO/NO-GO-Empfehlung

Empfehlung: GO Option A — Engine bleibt unverändert, ProposalWriter standalone.

Pre-Implementation-Q an Operator

1. Option A oder B? ← Empfehlung A (Engine untouched, max scope-lock)
2. proposal_id-Regex-Schwere: strict ASCII [a-zA-Z0-9_-]{1,128} oder erlaubt z.B. dots in der Mitte (für proposal_id-Namespacing wie org.eth.20260512)? ← Empfehlung strict ASCII no-dots, einfacher pin
3. fsync Directory zusätzlich zum file-fsync? ← Empfehlung nein (matches Baseline-Writer)
4. restore_from_backup Helper mit liefern (Symmetrie zu Baseline-Writer) obwohl proposals immutable sind und nie restored werden müssten? ← Empfehlung weglassen (YAGNI)
5. MH-3c Real-Testnet-Drill als separate Phase oder erst Teil von MH-6? ← Empfehlung MH-6 (Drill braucht Worker-Handler-Pfad, der Engine+Writer orchestriert)

Subschnitt

STOP vor Implementierung. Erwarte Operator-GO mit Option-A/B Wahl + Pre-Implementation-Q1-Q5-Approval.

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