siloqy/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS8.md

# 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 -- <files>` 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_<UTC>.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_<UTC>.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.