diff --git a/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS8.md b/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS8.md new file mode 100644 index 00000000..be4b1157 --- /dev/null +++ b/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS8.md @@ -0,0 +1,179 @@ +# VIOLET — partial spec for another agent, PASS 8 (OA TODO): V6 BIBLE LAYERS (POSTURE / MARAS / REGIME) + CADENCE TELEMETRY + +Date: 2026-06-17. Continues PASS 1–7 (same V0→V6 plan). PASS 8 is the **V6** bible layer. V6 = +"full bible layers (ACB / MARAS / posture / vol) + sub-second SL guard." Of those: +- **ACB** (boost/beta) is DONE (`live_blue_source.py`, bit-identical to `get_dynamic_boost_from_hz`). +- **vol** gate is PASS-4 Task 14; **sub-second SL guard** is PASS-3 Task 10. +- **REMAINING for PASS 8: POSTURE (the 5-state effects), MARAS (fingerprint consumer), and the + REGIME read-model that composes them — plus the CADENCE shadow-actuation telemetry** the plan + requires before any Q loosening. + +All DARK; independent, separately-testable units sharing the `contracts_v3` vocabulary. + +**Crucial framing:** VIOLET **CONSUMES** posture/MARAS — it does NOT decide them. BLUE's +meta-health service (MHS) sets posture; VIOLET reads it from HZ (already sourced via +`live_blue_source` → `engine_snapshot['posture']` / `DOLPHIN_SAFETY.latest.posture`). These units +APPLY the published posture/MARAS EFFECTS faithfully; they do NOT run the MHS state machine. + +**Read first (authoritative references — READ ONLY):** +- `nautilus_dolphin/nautilus_dolphin/nautilus/esf_alpha_orchestrator.py` — `_day_posture` handling: + `:365` HIBERNATE_HALT (force EXIT), `:613` STALKER structural ceiling, `:918-978` begin_day + posture wiring; and the `regime_dd_halt` set on `mc_red or posture in ['TURTLE','HIBERNATE']`. +- `prod/clean_arch/violet/sizing.py` — the STALKER `clamped_max=min(clamped_max, 2.0)` already in + `compose` (READ; do NOT edit; the posture *size-cap* lives there — PASS 8 owns the *entry-gate* + + observability, not the sizing math). +- **MARAS:** grep the kernels for `maras` / `MARAS` / `maras_fingerprint` (memory references + "maras_fingerprint columns"); determine its EXACT role in the decision/sizing path. The BIBLE + may mention it (directionally right, possibly outdated — verify against code). +- `prod/clean_arch/violet/cadence.py` (`CadenceControlPlane`, `Action`) + PASS-3 + `cadence_schedule.py` — READ; PASS 8 extends the telemetry, does not edit them. +- `live_blue_source.py` (posture sourcing) + `decision_engine.py` (how `posture` enters `factors`). + +--- + +## 0. HARD RULES (identical to PASS 1–7 — summarized) +- **Never edit shared files** (`prod/nautilus_event_trader.py`, `clean_arch/dita_v2/**`, + `dita/decision.py`, `nautilus_dolphin/**`, `blue_parity.py`, `prod/bingx/leverage.py`). READ only. +- **VIOLET DARK** — pure consumers over published posture/MARAS/regime inputs; no orders, no venue, + no service/HZ control, no PROGREEN. +- **V-TYPES on all new code**; faithful poison-guards only; NO arbitrary caps. +- **NEW-FILE-ONLY** under `prod/clean_arch/violet/regime/` (+ extend `contracts_v3.py`). Do NOT + modify in-flight files (`sizing.py`, `decision_engine.py`, `live_blue_source.py`, `cadence.py`, + `clock.py`, the PASS-5/6/7 files). READ + IMPORT them. + +## 0a. COMMIT / BRANCH POLICY (3 shared-index collisions on 2026-06-16 — non-negotiable) +Own `git worktree` (`git worktree add ../vp-oa8 -b agent/oa-violet8`) strongly preferred. Else +never `git add -A`; `git commit -F msg -- ` with explicit pathspec; verify +`git show --stat --format="" HEAD` lists ONLY your files. One commit/task, prefix `VIOLET OA:`, +Co-Authored-By trailer. Tests on `/home/dolphin/siloqy_env/bin/python3`. `git grep` only. + +--- + +## I. SHARED INTERFACE EXTENSIONS (add to `contracts_v3.py`; never fork a parallel type) +Reuse PASS-3..7 types. ADD the V6 regime vocabulary (all `StrictModel` / `Annotated`): +1. **`Posture`** = Literal["APEX","STALKER","RESTORED","TURTLE","HIBERNATE"] (must equal + `sizing.Posture`). +2. **`PostureEffect`** — `posture: Posture`, `entry_allowed: bool`, `force_flatten: bool`, + `size_cap: Optional[float]` (e.g. 2.0 for STALKER; None = no extra cap), `regime_dd_halt: bool`. +3. **`MarasFingerprint`** — the published MARAS state (fields TBD by Task 39 after reading the + kernel; at minimum a typed wrapper with finite/typed fields + a `regime_label: str`). +4. **`RegimeView`** — read-model composing the live regime: `posture: Posture`, `boost: float`, + `beta: float`, `mc_scale: float`, `vol_ok: Optional[bool]`, `maras: Optional[MarasFingerprint]`, + `regime_dd_halt: bool`, `ts_ns: MonoNs`. Observability/divergence only — NOT a sizing path. +5. **`ActionCadenceDelta`** — `action: str`, `evaluations: int (ge=0)`, `actuations: int (ge=0)`, + `suppressed: int (ge=0)` — the shadow-delta per action. + +If a task needs another field, ADD it here and note it. + +--- + +## TASK 37 — Regime/posture contracts +**Why.** The shared V6 vocabulary. +**Affected files (NEW):** extend `contracts_v3.py` (the §I types); +`prod/clean_arch/violet/regime/__init__.py`; +`prod/clean_arch/violet/regime/test_violet_regime_contracts.py`. +**Pass criteria.** All types construct + poison-reject; `Posture` literal equals `sizing.Posture` +(assert in test); `size_cap` optional/finite. No edits outside the new/extended files. + +## TASK 38 — Posture effects engine (the 5-state EFFECTS, faithful) +**Why.** Apply each posture's documented EFFECT on the decision path — the entry-gate + flatten + +size-cap — exactly as BLUE. (The STALKER size-cap of 2.0 already lives in `sizing.compose`; this +unit owns the ENTRY-GATE + FLATTEN + the typed effect, NOT the sizing math.) +**Affected files (NEW):** `prod/clean_arch/violet/regime/posture_effects.py`, +`prod/clean_arch/violet/regime/test_violet_posture_effects.py`. +**Interface/approach.** `posture_effect(posture: Posture) -> PostureEffect`, transcribed from the +orchestrator (cite file:line): +- **APEX / RESTORED:** `entry_allowed=True`, no flatten, no extra cap. +- **STALKER:** `entry_allowed=True`, `size_cap=2.0` (the `:613` structural ceiling), no flatten. +- **TURTLE:** `regime_dd_halt=True` → `entry_allowed=False` (halt new entries), no forced flatten of + existing (verify the exact TURTLE behaviour in the kernel). +- **HIBERNATE:** `entry_allowed=False`, `force_flatten=True` (`:365` HIBERNATE_HALT forces EXIT), + `regime_dd_halt=True`. +Verify each against the kernel; if any differs, follow the CODE (BIBLE may be outdated). +**Pass criteria.** Each posture maps to the cited effect; HIBERNATE flattens + blocks entry; TURTLE +blocks entry; STALKER caps at 2.0; APEX/RESTORED normal. A test asserts the STALKER cap equals the +2.0 used in `sizing.compose`. No edits outside the 2 files. + +## TASK 39 — MARAS fingerprint consumer +**Why.** MARAS is named in V6 ("full bible layers ACB/MARAS/posture/vol"). Build the faithful +consumer of the published MARAS fingerprint. +**Affected files (NEW):** `prod/clean_arch/violet/regime/maras_consumer.py`, +`prod/clean_arch/violet/regime/test_violet_maras_consumer.py`. +**Interface/approach.** FIRST establish MARAS's real role: grep the kernels + the HZ publishers for +`maras`/`maras_fingerprint`; find (a) WHERE MARAS is published (which HZ map/key), (b) WHETHER it +modulates sizing/gating in the live path or is observability-only. Then: +- If MARAS modulates the decision: build `consume_maras(raw) -> MarasFingerprint` (wrap BLUE's + parser if one exists; else V-TYPES the published fields) + the effect it applies, transcribed + + cited. +- If MARAS is observability-only (NOT in the live decision path): build the read-only typed + accessor + DOCUMENT explicitly that it does not modulate decisions today (honest — do NOT invent + a modulation BLUE doesn't apply). +**Pass criteria.** `MarasFingerprint` parses the real published payload shape (captured-fixture +test); the consumer's role (modulating vs observability) is determined from the code and +documented with citations. No invented effect. No edits outside the 2 files. + +## TASK 40 — Regime composite read-model +**Why.** A single typed `RegimeView` composing posture + ACB(boost/beta) + mc_scale + vol + MARAS +for observability and divergence — NOT a new sizing path (sizing.py owns the math). +**Affected files (NEW):** `prod/clean_arch/violet/regime/regime_view.py`, +`prod/clean_arch/violet/regime/test_violet_regime_view.py`. +**Interface/approach.** `build_regime_view(*, posture, boost, beta, mc_scale, vol_ok=None, +maras=None, now_ns) -> RegimeView` — pure assembly + `regime_dd_halt` derived from posture +(Task 38) and mc state. Read-only; emits the view for a future divergence/observability sink. MUST +NOT recompute or alter any sizing factor. +**Pass criteria.** View assembled correctly; `regime_dd_halt` matches the posture effect; no sizing +recomputation (a test asserts inputs pass through unchanged). No edits outside the 2 files. + +## TASK 41 — Cadence shadow-actuation telemetry harness +**Why.** The plan's cadence doctrine: "evaluate at fastest cadence (shadow-log would-be actions), +actuate at Q; measure shadow deltas before promoting." PASS-3 Task 13 added the Q-schedule + a +telemetry recorder; THIS unit runs the evaluate/actuate loop and produces per-action +`ActionCadenceDelta`s — the shadow evidence required before stepping any Q down. +**Affected files (NEW):** `prod/clean_arch/violet/regime/cadence_telemetry_harness.py`, +`prod/clean_arch/violet/regime/test_violet_cadence_telemetry_harness.py`, report → +`prod/VIOLET_dev/reports/violet_cadence_shadow_.json`. +**Interface/approach.** Compose PASS-3 `cadence_schedule` + `CadenceControlPlane` (READ; import, +don't edit). Drive a synthetic action stream where each action EVALUATES every tick but ACTUATES +only when its Q is due; record `evaluations` / `actuations` / `suppressed` per action and emit the +deltas. This quantifies, e.g., "how many would-be SL exits fire at fast cadence vs the scan-Q +actuations" — the promote/loosen evidence. +**Pass criteria.** For a known stream, evaluations > actuations per fast action; per-action Q +honored; deltas match a hand-computed expectation; report archived. No edits outside the new files. + +## TASK 42 — Posture/regime parity gate vs BLUE +**Why.** Pin the posture EFFECTS (and MARAS, if modulating) to BLUE's actual gating over a replay — +bit-identity where applicable. +**Affected files (NEW):** `prod/clean_arch/violet/regime/test_violet_regime_parity_gate.py`; report +→ `prod/VIOLET_dev/reports/violet_regime_parity_.json`. +**Interface/approach.** For each posture (+ MARAS state if it modulates), assert VIOLET's +`posture_effect` / consumer reproduces BLUE's entry-allowed / flatten / cap / halt decision (drive +the orchestrator's relevant branch, or assert against the cited constants). Record mismatches +(must be 0). +**Pass criteria (`@pytest.mark.gate`).** Every posture's effect matches BLUE; HIBERNATE/TURTLE halts +reproduced; STALKER 2.0 cap matches; zero mismatches; report archived. No edits outside the new file. + +--- + +## Composition map +``` +contracts_v3 (+Posture/PostureEffect/MarasFingerprint/RegimeView/ActionCadenceDelta) + 38 posture_effects(posture) → PostureEffect (entry gate / flatten / cap / dd_halt) + 39 maras_consumer(raw) → MarasFingerprint (+ effect, IFF it modulates; else read-only) + 40 regime_view(posture,acb,mc,vol,maras) → RegimeView (observability/divergence; NOT sizing) + 41 cadence_telemetry_harness → [ActionCadenceDelta] (shadow evidence before Q loosening) + 42 regime_parity_gate: effects == BLUE gating (bit-identity) +``` +Integration (wiring posture-gating into the live decision path, the regime view into a divergence +sink, the cadence deltas into the Q-promotion decision) is the OWNER's job later. Posture/MARAS +remain CONSUMED, never decided (MHS owns them). + +## Recommended order +**37 (contracts) → 38 (posture effects) → 42 (regime parity gate) → 39 (MARAS) → 40 (regime view) → +41 (cadence telemetry)**. 42 right after 38 to pin posture before composing. + +## Still NOT in scope (operator/owner only, or Claude) +- **Running the MHS / DECIDING posture** — BLUE owns it; VIOLET consumes. +- **Q loosening / sub-second actuation of alpha exits** — needs VBT re-cert (research), not a unit. +- **The live BLUE↔VIOLET aggregate parity root-cause (CRITICAL #1)** — Claude's job. +- **DARK soak start; V4 live execution; HZ-bridge; VIBRISS.** +- Any edit to in-flight / shared files in §0. diff --git a/prod/docs/VIOLET_TODO_CRITICAL.md b/prod/docs/VIOLET_TODO_CRITICAL.md index 21c61bf9..558c9cf8 100644 --- a/prod/docs/VIOLET_TODO_CRITICAL.md +++ b/prod/docs/VIOLET_TODO_CRITICAL.md @@ -76,6 +76,12 @@ ranking bit-identity gate vs AlphaAssetSelector. NOTE: this layer is the suspect #1 — PASS 7 PINS the ranking math (narrowing the suspect to timing/join), but the live-aggregate root-cause stays Claude's job. Review when done. +**PASS 8**: `VIOLET_PART_SPEC_OA_TODO_PASS8.md` (issued 2026-06-17) — V6 bible CONSUMERS: posture +effects engine (5-state entry-gate/flatten/cap), MARAS fingerprint consumer (role TBD from code — +no invented modulation), regime read-model, cadence shadow-actuation telemetry, posture/regime +parity gate. VIOLET CONSUMES posture/MARAS (MHS owns them); ACB/vol/SL-guard already covered +elsewhere. Review when done. + **Action:** review each pass for correctness, BLUE-algo compliance, V-TYPES, no-shared-edits, real (non-vacuous) tests. **Owner: Claude (me), later.**