siloqy/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS7.md

VIOLET — partial spec for another agent, PASS 7 (OA TODO): V5 SELECTION + MULTI-ASSET SLOTS + CAPITAL ALLOCATION

Date: 2026-06-17. Continues PASS 1–6 (same V0→V6 plan). PASS 7 is the V5 layer of the ladder: faithful IRP/ARS asset RANKING, MULTI-ASSET SLOT management (concurrent positions), and CAPITAL ALLOCATION across slots. Everything DARK and as independent, separately-testable units sharing the contracts_v3 vocabulary.

⚠️ Relevance to CRITICAL #1 (read VIOLET_TODO_CRITICAL.md). The disappointing live parity (pick-match 1.5%, no-pick 86%, but sizing near-identical when assets align) points squarely at SELECTION/TIMING, i.e. THIS layer. PASS 7 BUILDS the faithful selection machinery and pins the ranking bit-for-bit to BLUE's AlphaAssetSelector (Task 36). That is COMPLEMENTARY to — not a substitute for — the live-aggregate parity root-cause, which remains Claude's job (the live join/alignment in parity_report.py is the other suspect). Do NOT attempt the live root-cause here; build the units + the unit-level bit-identity pin.

Read first (authoritative references — READ ONLY):

• nautilus_dolphin/nautilus_dolphin/nautilus/alpha_asset_selector.py — AlphaAssetSelector.rank_assets (IRP selection, ARS scoring, BIBLE §5) — the ranking authority.
• prod/docs/SYSTEM_BIBLE.md §5 (selection), §490 "OB Sub-1: ARS adjusted ±5%/10% by per-asset OB depth quality before sorting", §735 OB sub-systems. (BIBLE is directionally right but can be outdated — verify against the kernel code.)
• prod/clean_arch/violet/alpha_wrappers.py (VioletAssetSelector, the single-pick wrapper) + decision_engine.py (how a pick + ars_score flow today) + sizing.py (notional model) — READ, do NOT edit (in-flight).
• ENGINE_KWARGS selection knobs (nautilus_event_trader.py:127+): use_asset_selection=True, min_irp_alignment=0.0 ("gold spec: no IRP filter"), max_slots (launcher venue config).
• Stablecoin exclusion: decision_engine.STABLECOIN_SYMBOLS (must match BLUE's set).

---

0. HARD RULES (identical to PASS 1–6 — 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 — selection/slots/allocation are pure logic over scan + factor inputs; no orders, no venue, no service/HZ control.
• V-TYPES on all new code; faithful poison-guards only; NO arbitrary caps.
• NEW-FILE-ONLY under prod/clean_arch/violet/selection/ (+ extend contracts_v3.py). Do NOT modify in-flight files (alpha_wrappers.py, decision_engine.py, sizing.py, live_blue_source.py, the PASS-5/6 exec files, cadence.py, clock.py). READ + IMPORT them.

0a. COMMIT / BRANCH POLICY (3 shared-index collisions on 2026-06-16 — non-negotiable)

Own git worktree (git worktree add ../vp-oa7 -b agent/oa-violet7) 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..6 types. ADD the selection/slot vocabulary (all StrictModel / Annotated):

1. AssetRank — asset: Symbol, ars_score: float (finite), ob_adjusted_score: float (finite), irp_alignment: float, irp_passed: bool, rank: int (ge=0), excluded_reason: str = "" (e.g. "STABLECOIN"/"IRP_FILTER"/"" ).
2. SlotState — slot_id: int (ge=0), asset: Optional[Symbol], status: str ("FREE"/"HELD"/"PENDING"), held_since_ns: Optional[MonoNs].
3. CapitalAllocation — slot_id: int, asset: Symbol, allocated_capital: float (ge=0), notional_fraction: float (ge=0), conviction_leverage: float (ge=0).
4. SlotPolicy — max_slots: Annotated[int, Field(ge=1)], hysteresis_bars: Annotated[int, Field(ge=0)] (anti-churn), allow_reentry: bool.

If a task needs another field, ADD it here and note it.

---

TASK 31 — Selection contracts + SlotPolicy

Why. The shared selection/slot vocabulary everything else imports. Affected files (NEW): extend contracts_v3.py (the §I types); prod/clean_arch/violet/selection/__init__.py; prod/clean_arch/violet/selection/test_violet_selection_contracts.py. Pass criteria. All types construct + poison-reject (non-finite scores, negative capital, max_slots ≥ 1); excluded_reason enumerated values documented. No edits outside the new/extended files.

TASK 32 — ARS ranking pipeline (faithful to AlphaAssetSelector + OB Sub-1 + IRP filter)

Why. The heart of selection: reproduce BLUE's full ranking — ARS score → OB Sub-1 adjustment → IRP alignment filter → stablecoin exclusion → sort. The single-pick VioletAssetSelector covers part of this; PASS 7 builds the FULL multi-asset ranking on top WITHOUT editing it. Affected files (NEW): prod/clean_arch/violet/selection/rank_pipeline.py, prod/clean_arch/violet/selection/test_violet_rank_pipeline.py. Interface/approach. rank_assets(market_data: dict[Symbol, list[float]], *, regime_direction: int, ob_market=None, min_irp_alignment: float, stablecoins: frozenset[str]) -> list[AssetRank]:

• Compute the base ARS exactly as AlphaAssetSelector (WRAP/transcribe — cite file:line).
• OB Sub-1 (BIBLE §490): adjust ARS ±5%/10% by per-asset OB depth quality BEFORE sorting (read the kernel for the exact factors/percentages; if ob_market is None, skip the adjustment, as the no-OB path does).
• IRP alignment filter: drop assets with alignment < min_irp_alignment (default 0.0 = no filter, per gold spec) → mark irp_passed/excluded_reason.
• Stablecoin exclusion: any asset in stablecoins → excluded (must equal decision_engine.STABLECOIN_SYMBOLS; assert in test).
• Sort descending by ob_adjusted_score; assign rank. Pure function, deterministic, V-TYPES out. Pass criteria. On crafted market data the ranked order + ARS/ob_adjusted scores match a direct AlphaAssetSelector computation; stablecoins always excluded; IRP filter respected; OB-off path equals base ARS. No edits outside the 2 files.

TASK 33 — Multi-asset slot manager (max_slots, assignment, hysteresis)

Why. BLUE/VIOLET hold up to max_slots concurrent positions; the slot manager decides which ranked assets occupy slots, with no double-occupancy and anti-churn hysteresis. Affected files (NEW): prod/clean_arch/violet/selection/slot_manager.py, prod/clean_arch/violet/selection/test_violet_slot_manager.py. Interface/approach. SlotManager(policy: SlotPolicy) holding list[SlotState]. assign(ranked: list[AssetRank], held: dict[Symbol, OpenPositionView], now_ns) -> list[SlotState]: keep currently HELD assets in their slots; fill FREE slots from the top of ranked (excluding already-held and excluded assets); never assign the same asset to two slots; respect hysteresis_bars (do not evict a freshly-taken slot to chase a higher rank within the hysteresis window). READ how BLUE/the trader manages max_slots (launcher venue config + engine) and transcribe the rule; if BLUE is single-slot today (max_slots=1), the manager must still be correct + generalize to N. Pass criteria. Held assets retained; free slots filled by rank; no double-occupancy; hysteresis prevents churn; max_slots respected. Hypothesis: |HELD slots| ≤ max_slots always; no asset in two slots. No edits outside the 2 files.

TASK 34 — Capital allocation across slots

Why. Turn slot occupancy + conviction into per-slot capital + notional, honoring BLUE's sizing convention (notional = base_fraction × conviction × capital) and the margin-study findings. Affected files (NEW): prod/clean_arch/violet/selection/capital_allocator.py, prod/clean_arch/violet/selection/test_violet_capital_allocator.py. Interface/approach. First READ how BLUE allocates capital across concurrent slots (shared pool vs per-slot; the margin study blue_margin_envelope_study + sizing.py are the references — notional = 0.20 × conviction × capital; capital under-utilized at 1 slot was DELIBERATE). Define allocate(slots: list[SlotState], convictions: dict[Symbol, float], *, capital: float, base_fraction: float) -> list[CapitalAllocation] reproducing that convention EXACTLY (cite the source). Do NOT invent a normalization BLUE doesn't do. Pass criteria. Per-slot notional == base_fraction × conviction × capital (the documented model); sum-of-notionals behavior matches BLUE's (shared-capital, not artificially normalized, unless BLUE normalizes — verify); poison guards reject non-finite/negative. Cite the allocation source. No edits outside the 2 files.

TASK 35 — Selection→slot→intent multi-asset flow harness (DARK)

Why. Compose the V5 path end-to-end: rank_pipeline → slot_manager → capital_allocator → (existing sizing) → ExecIntent per occupied slot (PASS-4 Task 17), DARK. Affected files (NEW): prod/clean_arch/violet/selection/multi_asset_flow.py, prod/clean_arch/violet/selection/test_violet_multi_asset_flow.py. Interface/approach. run_selection_cycle(market_data, held, *, factors, capital, policy, ...) -> list[ExecIntent] wiring the four units. Reuse sizing.VioletSizer for conviction (import, don't fork). DARK: emits intents, never orders. Deterministic. Pass criteria. A multi-asset scenario yields one intent per occupied slot with correct asset/qty/notional; held assets not re-entered (unless allow_reentry); max_slots respected end-to-end; deterministic. No edits outside the 2 files.

TASK 36 — Ranking bit-identity gate vs the real AlphaAssetSelector

Why. Pin the ranking to BLUE's actual AlphaAssetSelector over a sampled grid — the unit-level parity that, once green, removes selection-math as a suspect for CRITICAL #1 (leaving timing/join as the remaining live-aggregate suspect for Claude). Affected files (NEW): prod/clean_arch/violet/selection/test_violet_rank_parity_gate.py; gate report → prod/VIOLET_dev/reports/violet_rank_parity_<UTC>.json. Interface/approach. Over many synthetic universes (varied asset counts, price histories, directions, with/without OB), assert rank_pipeline.rank_assets produces the SAME ordering + the SAME ARS/ob_adjusted scores (==) as a direct AlphaAssetSelector run on the same inputs. Record mismatch count (must be 0). Pass criteria (@pytest.mark.gate). ≥ 200 universes, zero ranking/score mismatches; report archived. If mismatches appear, that IS a finding — report them, do not loosen. No edits outside the new file.

---

Composition map

contracts_v3 (+AssetRank/SlotState/CapitalAllocation/SlotPolicy)
   32 rank_pipeline(market, ob, irp, stables) → [AssetRank]   (faithful to AlphaAssetSelector + OB Sub-1)
   33 slot_manager(ranked, held, policy)       → [SlotState]   (max_slots, hysteresis, no double-occ)
   34 capital_allocator(slots, convictions, cap)→ [CapitalAllocation]  (BLUE notional convention)
   35 multi_asset_flow: 32→33→34→ sizing → [ExecIntent]        (DARK V5 cycle)
   36 rank_parity_gate: rank_pipeline == AlphaAssetSelector (bit-identity)   ← narrows CRITICAL #1

Integration (running the V5 cycle on the live reactor, wiring intents to the PASS-5/6 exec stack) is the OWNER's job later.

Recommended order

31 (contracts) → 32 (rank pipeline) → 36 (rank parity gate) → 33 (slots) → 34 (allocation) → 35 (flow harness). 36 right after 32 so the ranking is pinned before building on it.

Still NOT in scope (operator/owner only, or Claude)

• The live BLUE↔VIOLET aggregate parity root-cause (CRITICAL #1) — Claude's job; this pass only pins ranking-math + builds V5 units.
• Alpha re-timing / sub-second actuation of entries — VBT re-certification (research), not a unit.
• DARK soak start; V4 live execution; HZ-bridge; VIBRISS.
• Any edit to in-flight / shared files in §0.