feat(esof): rename NEUTRAL→UNKNOWN + backward-compat alias

The mid-band advisory label (constituent signals in conflict) was called
NEUTRAL, implying "benign middle" — but retrospective data (637 trades)
shows it is empirically the worst-ROI regime. Renaming to UNKNOWN makes
the semantics explicit for regime-gate consumers.

- esof_advisor.py: emits UNKNOWN; LABEL_COLOR keeps NEUTRAL alias for
  historical CH rows / stale HZ snapshots
- esof_gate.py: S6_MULT, IRP_PARAMS, Strategy A mult_map all keyed on
  UNKNOWN with NEUTRAL alias (values identical → replays unaffected)
- prod/docs/ESOF_LABEL_MIGRATION.md: migration note, CH/HZ impact,
  rollback procedure

Plan ref: Task 4 — NEUTRAL→UNKNOWN is load-bearing for the EsoF gate
in the orchestrator (0.25× sizing vs 1.0× under old label semantics).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
hjnormey
2026-04-22 06:07:30 +02:00
parent 0da46d8635
commit af5156f52d
3 changed files with 43 additions and 8 deletions

View File

@@ -0,0 +1,26 @@
# EsoF Label Migration — `NEUTRAL` → `UNKNOWN`
Landed in `exp/green-s6-esof-aem-shadow-2026-04-21` on 2026-04-21.
## What changed
`Observability/esof_advisor.py` emits `UNKNOWN` where it previously emitted `NEUTRAL` (mid-band, `-0.05 < advisory_score <= 0.05`). All downstream consumers keep a `NEUTRAL` alias so historical CH rows and replays continue to resolve.
## Why
Findings from the 637-trade EsoF retrospective (`prod/docs/EsoF_BLUE_IMPLEMENTATION_CURR_AND_RESEARCH.md`) show the mid-band isn't a benign middle — it's the **worst-ROI regime**, corresponding to states where the constituent liq/session/DoW/slot/cell signals are **in conflict**. "NEUTRAL" connoted "no strong read, probably fine"; the data says the opposite. The orchestrator-top EsoF gate uses `UNKNOWN``0.25x` sizer mult to encode "stand mostly aside" instead of "trade normally".
## Touched files
- `Observability/esof_advisor.py` — emitter renamed; `LABEL_COLOR` carries both keys.
- `Observability/esof_gate.py``S6_MULT`, `IRP_PARAMS`, Strategy A mult map all keyed on `UNKNOWN` with a `NEUTRAL` alias entry.
- `nautilus_dolphin/nautilus_dolphin/nautilus/esf_alpha_orchestrator.py` — new GREEN-only `esof_sizing_table` looks up by label; missing/None label defaults to `UNKNOWN`.
## CH / HZ
- CH `dolphin.trade_events`, `dolphin.esof_advisory_log`: no DDL change (labels are strings). Historical rows keep `NEUTRAL`; new rows get `UNKNOWN`. Any dashboard/query filtering on the label needs to `IN ('NEUTRAL','UNKNOWN')` or be migrated.
- HZ `DOLPHIN_FEATURES.esof_advisor_latest`: next advisor tick overwrites with `UNKNOWN`. Consumers reading stale snapshots across the cutover should treat both as equivalent.
## Rollback
Revert the three files above. The `NEUTRAL` alias means a partial rollback (advisor only) is safe without cascading breakage.