siloqy/prod/docs/VIOLET_FULL_SYSTEM_ASSESSMENT.md

# VIOLET Full System Assessment

This is the current source-faithful assessment of how the full VIOLET system works in this checkout, mapped against the BLUE doctrine in `prod/docs/SYSTEM_BIBLE_v7.md` and the VIOLET spec files. The current `SYSTEM_BIBLE_v7.md` file is a `v7.2` document in this tree; the BLUE v7 / v7.1 lineage is treated here as the same doctrinal source family.

Scope:
- start from launcher and invocation points
- trace the BLUE-equivalent layers through the current VIOLET codepaths
- identify exactly where DITAv2 executes
- isolate ASEx involvement
- list the data inputs and input sites
- describe the VIOLET-only support systems
- record worktree provenance for the files and file-groups that implement the path

What follows is a map of the live code, not a proposal.

## 1. Canonical sources

BLUE doctrine and system behavior:
- `prod/docs/SYSTEM_BIBLE_v7.md`
- `prod/docs/DITA_V2_KERNEL_REFERENCE.md`

VIOLET doctrine and rollout intent:
- `prod/docs/VIOLET_DEV_SPEC_AND_PLAN.md`
- `prod/docs/VIOLET_DEV_SPEC_AND_PLAN_SOAK.md`
- `prod/docs/VIOLET_DEV_SPEC_AND_PLAN_SOAK__DEV_STATUS_20260627.md`
- `prod/docs/VIOLET_PASS_MM1_V4_READINESS_REPORTER.md`
- `prod/docs/ASEx_INTEGRATION_STATUS.md`
- `prod/docs/DITA_V2_OPERATOR_PLAYBOOK.md`

Key implementation files:
- `prod/launch_dolphin_violet.py`
- `prod/launch_dolphin_violet_v4.py`
- `prod/clean_arch/violet/v4_execution_runner.py`
- `prod/clean_arch/violet/v4_arming.py`
- `prod/clean_arch/violet/v4_readiness.py`
- `prod/clean_arch/violet/shadow_live_factors.py`
- `prod/clean_arch/violet/live_blue_source.py`
- `prod/clean_arch/violet/live_factor_source.py`
- `prod/clean_arch/violet/shadow_journal.py`
- `prod/clean_arch/violet/divergence.py`
- `prod/clean_arch/violet/observe_guard.py`
- `prod/clean_arch/violet/pass2_8_soak_runner.py`
- `prod/clean_arch/violet/layer_parity_harness.py`
- `prod/clickhouse/violet/apply_violet_ddl.py`
- `prod/clickhouse/violet/*.sql`
- `prod/clean_arch/dita_v2/launcher.py`
- `prod/clean_arch/dita_v2/rust_backend.py`
- `prod/clean_arch/dita_v2/bingx_venue.py`
- `prod/clean_arch/dita_v2/mock_venue.py`
- `prod/clean_arch/dita_v2/control.py`
- `prod/clean_arch/dita_v2/projection.py`
- `prod/clean_arch/dita_v2/hazelcast_projection.py`
- `prod/supervisor/dolphin-supervisord.conf`
- `prod/supervisor/run_with_dolphin_env.sh`

## 2. Invocation points

### 2.1 Observe-only VIOLET

Primary entrypoint:
- `prod/launch_dolphin_violet.py`

What it does:
- fixes the VIOLET namespace before anything else reads env
- preflights all `dolphin_violet.*` tables with `SELECT 0 ... LIMIT 0`
- if tables are missing, it idles dark and names the DDL applier
- builds a DITAv2 launcher bundle, then wraps the venue in `ObserveOnlyVenue`
- writes VIOLET persistence and Hazelcast state into VIOLET-only maps and tables
- starts a divergence monitor and an optional muted shadow path
- never calls the execution kernel for live order placement

Observed behavior:
- `dolphin_violet` is the observe-only runtime
- it is designed to be safe when BLUE is present because it reads BLUE state but does not write BLUE tables

### 2.2 VIOLET live V4 execution

Wrapper entrypoint:
- `prod/launch_dolphin_violet_v4.py`

Live runner:
- `prod/clean_arch/violet/v4_execution_runner.py`

What it does:
- consumes NG7 scans from Hazelcast
- converts scans into VIOLET decisions
- converts decisions into `ExecIntent`
- converts `ExecIntent` into DITAv2 `KernelIntent`
- submits the kernel intent to the DITAv2 execution kernel
- requires arming gates and VST-only settings before live execution is allowed

Current runtime note:
- in this checkout the observe-only service is running
- the V4 execution service is registered but remains stopped because arming is not GO

### 2.3 DITAv2 operator surface

General DITAv2 launcher:
- `prod/launch_dita_v2.py`

Operator playbook:
- `prod/docs/DITA_V2_OPERATOR_PLAYBOOK.md`

This is the lower-level DITAv2 surface. VIOLET uses the same launcher bundle construction, but VIOLET adds its own scan ingestion, decision logic, shadow journal, arming gate, and execution wrapper on top.

## 3. BLUE layers and VIOLET equivalents

The BLUE system bible describes a layered trading stack. VIOLET mirrors that structure, but with its own namespaces and additional arming/execution scaffolding.

| BLUE layer / concern | VIOLET equivalent | Main files | Input sites | Effect |
|---|---|---|---|---|
| Invocation / process control | VIOLET launcher and supervisor surface | `prod/launch_dolphin_violet.py`, `prod/launch_dolphin_violet_v4.py`, `prod/supervisor/dolphin-supervisord.conf`, `prod/supervisor/run_with_dolphin_env.sh` | env, supervisor, shell wrapper | selects observe-only or live V4 posture |
| Scan ingest / feature feed | Hazelcast NG7 scan source | `prod/clean_arch/violet/v4_execution_runner.py`, `prod/clean_arch/violet/live_blue_source.py` | `DOLPHIN_FEATURES.latest_eigen_scan` | provides scan payloads and BLUE live factors |
| Posture / capital sensing | BLUE posture and capital readback | `prod/clean_arch/violet/live_blue_source.py`, `prod/clean_arch/violet/live_factor_source.py` | `DOLPHIN_STATE_BLUE.latest_nautilus`, `DOLPHIN_STATE_BLUE.engine_snapshot` | feeds posture-aware factorization |
| Alpha / conviction / sizing | VIOLET decision engine and sizing helpers | `prod/clean_arch/violet/decision_engine.py`, `prod/clean_arch/violet/sizing.py`, `prod/clean_arch/violet/alpha_wrappers.py`, `prod/clean_arch/violet/v4_execution_runner.py` | scan payload, live BLUE factor source | produces `ExecIntent` from BLUE-faithful decision logic |
| Shadow audit / decision logging | Shadow journal and parity surfaces | `prod/clean_arch/violet/shadow_journal.py`, `prod/clean_arch/violet/parity_report.py` | decision rows, scan numbers | writes `dolphin_violet.violet_decisions` |
| Divergence / feed hygiene | VIOLET feed divergence monitor | `prod/clean_arch/violet/divergence.py` | scan stream and runtime samples | writes `dolphin_violet.violet_feed_divergence` |
| Execution boundary | DITAv2 kernel bridge | `prod/clean_arch/violet/v4_execution_runner.py`, `prod/clean_arch/dita_v2/launcher.py`, `prod/clean_arch/dita_v2/rust_backend.py`, `prod/clean_arch/dita_v2/bingx_venue.py` | `ExecIntent`, arming report, BingX env | runs actual DITAv2 execution path |
| Safety / no-touch guard | Observe-only venue wrapper | `prod/clean_arch/violet/observe_guard.py` | venue object | prevents any order placement in dark mode |
| Schema / persistence | VIOLET-only ClickHouse schema | `prod/clickhouse/violet/*.sql`, `prod/clickhouse/violet/apply_violet_ddl.py` | DDL files, table probes | creates and verifies `dolphin_violet.*` only |
| Readiness / arming | V4 arming gate | `prod/clean_arch/violet/v4_readiness.py`, `prod/clean_arch/violet/v4_arming.py` | soak reports, env, keys | decides whether V4 may arm |

## 4. Exact execution flow

### 4.1 Observe-only launcher flow

`prod/launch_dolphin_violet.py` does this in order:
1. applies VIOLET env names
2. probes `dolphin_violet` tables
3. if tables are missing, logs and idles dark
4. if dark divergence is enabled or keys exist, starts the divergence task
5. if no VIOLET keys are present, idles dark
6. otherwise constructs a DITAv2 launcher bundle
7. wraps the venue in `ObserveOnlyVenue`
8. wires VIOLET persistence and Hazelcast state writers
9. builds the muted shadow path
10. runs the observe-only loop

Important point:
- it does not submit live orders
- it does not execute `runtime.step()`
- it is a read-mostly / audit / shadow surface, not the live trading boundary

### 4.2 Live V4 execution flow

`prod/clean_arch/violet/v4_execution_runner.py` is the live boundary. The chain is:
1. `run_live()` loads env and runtime options
2. it applies VIOLET runtime env and optimizations
3. it builds the real DITAv2 bundle
4. it builds the shadow/live-factor source
5. it connects to Hazelcast NG7 scan source
6. it waits for a scan payload from `DOLPHIN_FEATURES.latest_eigen_scan`
7. `process_scan_payload()` parses and validates the payload
8. the scan number is deduplicated in guarded state
9. live factors are read from BLUE state and feature maps
10. the decision step produces a VIOLET decision
11. the decision is transformed to `ExecIntent`
12. the intent may be capped by configured notional limits
13. `ExecIntent` becomes DITAv2 `KernelIntent`
14. the runner mutates submission state
15. `bundle.kernel.process_intent_async(kernel_intent)` is awaited
16. the runner records outcome or error in guarded state

The exact DITAv2 execution point is step 15. That is where VIOLET hands off from its own decision plane into DITAv2 execution.

### 4.3 Where DITAv2 runs

DITAv2 is constructed by `prod/clean_arch/dita_v2/launcher.py` as a launcher bundle:
- kernel
- control plane
- projection
- zinc plane
- venue adapter

In VIOLET dark mode:
- the venue is wrapped in `ObserveOnlyVenue`
- the kernel exists, but the venue refuses live order placement

In V4 execution mode:
- the same bundle is built with BingX VST configuration
- the intent is submitted through the kernel into the venue adapter
- that is the only place VIOLET is allowed to reach live execution

## 5. Input data and input sites

### 5.1 BLUE live inputs consumed by VIOLET

VIOLET reads these BLUE surfaces as inputs:
- `DOLPHIN_STATE_BLUE.latest_nautilus`
- fallback `DOLPHIN_STATE_BLUE.engine_snapshot`
- `DOLPHIN_FEATURES.esof_latest`
- fallback `DOLPHIN_FEATURES.esof_advisor_latest`
- `DOLPHIN_FEATURES.mc_forewarner_latest`
- `DOLPHIN_FEATURES.latest_eigen_scan`

These are read-only input sites. VIOLET should not mutate BLUE state maps.

### 5.2 VIOLET scan input

The active scan input for VIOLET is:
- Hazelcast map `DOLPHIN_FEATURES`
- key `latest_eigen_scan`

That is the scan source the live runner consumes. The older scan bridge path is superseded in this layout.

### 5.3 VIOLET persistence inputs

VIOLET writes into:
- `dolphin_violet.policy_events`
- `dolphin_violet.trade_reconstruction`
- `dolphin_violet.trade_exit_legs`
- `dolphin_violet.position_state`
- `dolphin_violet.anomaly_events`
- `dolphin_violet.account_events`
- `dolphin_violet.status_snapshots`
- `dolphin_violet.trade_events`
- `dolphin_violet.v7_decision_events`
- `dolphin_violet.violet_feed_divergence`
- `dolphin_violet.violet_decisions`

These are VIOLET-only tables. They are not BLUE tables and should not be used to backfill BLUE state directly.

## 6. ASEx involvement

ASEx exists in the tree, but the current VIOLET mainline use is narrow.

Confirmed current VIOLET codepath:
- `prod/clean_arch/violet/v4_execution_runner.py` optionally imports:
  - `asex.guarded.ASExGuardedState`
  - `asex.worker.ASExWorker`
- if ASEx is unavailable, the runner falls back to a local guarded state implementation
- the ASEx wrapper is used for guarded serial state around scan/order lifecycle counters

What this means:
- ASEx is not the execution engine
- ASEx is not the DITAv2 kernel
- ASEx is not the default VIOLET decision path
- it is an optional serial-state wrapper in the live runner boundary

Cross-check from the integration status doc:
- ASEx is installed as an editable package
- VIOLET main has zero ASEx imports outside the live runner boundary
- DITAv2 main has zero ASEx imports
- the earlier PASS9 adapter work exists in another worktree and is not merged here

Operational conclusion:
- ASEx is currently peripheral, not foundational, in this checkout
- the only current VIOLET runtime touchpoint is the guarded state wrapper inside `v4_execution_runner.py`

## 7. VIOLET-only support systems

### 7.1 Read-only dark guard

`prod/clean_arch/violet/observe_guard.py` implements `ObserveOnlyVenue`.

Purpose:
- wraps a venue
- raises on order placement
- allows the launcher to run a full decision stack without touching a live venue

### 7.2 Shadow journal

`prod/clean_arch/violet/shadow_journal.py`

Purpose:
- persists executed shadow decisions to `dolphin_violet.violet_decisions`
- keeps the shadow path auditable
- matches the ClickHouse DDL in `prod/clickhouse/violet/22_violet_decisions.sql`

### 7.3 Feed divergence monitor

`prod/clean_arch/violet/divergence.py`

Purpose:
- records feed divergence into `dolphin_violet.violet_feed_divergence`
- gives VIOLET its own drift surface separate from BLUE

### 7.4 V4 readiness and arming

`prod/clean_arch/violet/v4_readiness.py`
`prod/clean_arch/violet/v4_arming.py`

Purpose:
- combine soak readiness, credential checks, namespace isolation, and launcher mode checks
- fail closed when the readiness report is not GO
- keep V4 from arming unless the environment says it may

Current observed behavior in this checkout:
- arming is not GO
- the live runner therefore remains stopped

### 7.5 Soak runner and parity harness

`prod/clean_arch/violet/pass2_8_soak_runner.py`
`prod/clean_arch/violet/layer_parity_harness.py`

Purpose:
- run the DARK -> MOCK -> VST canary progression used in VIOLET soak work
- compare VIOLET behavior against the expected layer parity surface
- keep execution preparation separate from the live V4 runner

## 8. Storage and schema

`prod/clickhouse/violet/apply_violet_ddl.py` is the schema applier for VIOLET.

Important characteristics:
- it only targets `dolphin_violet`
- it probes table existence before use
- it does not create BLUE tables
- it applies each SQL file as a separate statement path

Relevant SQL set:
- `00_create_database.sql`
- `01_policy_events.sql`
- `02_trade_reconstruction.sql`
- `03_trade_exit_legs.sql`
- `04_position_state.sql`
- `05_anomaly_events.sql`
- `06_account_events.sql`
- `07_status_snapshots.sql`
- `08_trade_events.sql`
- `09_v7_decision_events.sql`
- `10_adaptive_exit_shadow.sql`
- `11_fee_settled_events.sql`
- `12_sc_bucket_gauge_shadow.sql`
- `13_sc_threshold_advisor_shadow.sql`
- `20_violet_feed_divergence.sql`
- `22_violet_decisions.sql`

The important storage boundary is simple:
- VIOLET uses `dolphin_violet.*`
- BLUE uses `dolphin.*` and `DOLPHIN_*` control/state maps
- VIOLET should not write into BLUE storage

## 9. BLUE-equivalent layer mapping, expanded

### 9.1 Data / scan layer

BLUE uses `DOLPHIN_FEATURES.latest_eigen_scan` as the canonical scan source.

VIOLET uses the same scan feed as its input, but via the live runner and shadow source:
- `prod/clean_arch/violet/v4_execution_runner.py`
- `prod/clean_arch/violet/shadow_live_factors.py`
- `prod/clean_arch/violet/live_blue_source.py`

### 9.2 Signal / conviction layer

BLUE has a large signal layer family in the system bible.

VIOLET's equivalent is:
- `decision_engine.py`
- `sizing.py`
- `alpha_wrappers.py`
- `shadow_live_factors.py`
- `live_factor_source.py`

This is where the BLUE-like live factors are folded into VIOLET conviction and sizing.

### 9.3 Execution / accounting layer

BLUE's execution/accounting boundary is the DITA family in the bible.

VIOLET's equivalent is:
- `prod/clean_arch/dita_v2/launcher.py`
- `prod/clean_arch/dita_v2/rust_backend.py`
- `prod/clean_arch/dita_v2/bingx_venue.py`
- `prod/clean_arch/dita_v2/mock_venue.py`
- `prod/clean_arch/violet/v4_execution_runner.py`

This is the actual order-facing path when V4 is armed.

### 9.4 Observability / divergence

BLUE's observability surfaces are mirrored in VIOLET by:
- `shadow_journal.py`
- `divergence.py`
- `v4_readiness.py`
- `v4_arming.py`
- `parity_report.py`

These keep the VIOLET branch auditable without mutating BLUE.

## 10. Provenance appendix

Worktree state here means the current checkout state observed during this assessment.

| File group | Worktree status | Last-known committer | Responsible actor |
|---|---|---|---|
| `prod/launch_dolphin_violet.py` | modified | Codex, `fb344318aa849fde13b934bdba7337819cc42743` | current local edit in this session |
| `prod/clickhouse/violet/apply_violet_ddl.py` | modified | Codex, `99e529c32ab353027fd8e53e5219d5c949ec06ce` | current local edit in this session |
| `prod/supervisor/dolphin-supervisord.conf` | modified | Codex, `02ecc55c1670019682b193a239c72ab0f66ab1fc` | current local edit in this session |
| `prod/clean_arch/violet/v4_execution_runner.py` | untracked | new file in worktree | Codex |
| `prod/clean_arch/violet/v4_arming.py` | untracked | new file in worktree | Codex |
| `prod/launch_dolphin_violet_v4.py` | untracked in this checkout view | new file in worktree | Codex |
| `prod/launch_dita_v2.py` | untracked in this checkout view | new file in worktree | Codex |
| `prod/supervisor/run_with_dolphin_env.sh` | untracked in this checkout view | new file in worktree | Codex |
| `prod/clean_arch/dita_v2/launcher.py` | clean in this worktree during this assessment | not revalidated here | upstream DITAv2 owner / baseline |
| `prod/clean_arch/dita_v2/rust_backend.py` | clean in this worktree during this assessment | not revalidated here | upstream DITAv2 owner / baseline |
| `prod/clean_arch/dita_v2/bingx_venue.py` | clean in this worktree during this assessment | not revalidated here | upstream DITAv2 owner / baseline |
| `prod/clean_arch/dita_v2/mock_venue.py` | clean in this worktree during this assessment | not revalidated here | upstream DITAv2 owner / baseline |
| `prod/clean_arch/violet/shadow_live_factors.py` | clean in this worktree during this assessment | not revalidated here | upstream VIOLET owner / baseline |
| `prod/clean_arch/violet/live_blue_source.py` | clean in this worktree during this assessment | not revalidated here | upstream VIOLET owner / baseline |
| `prod/clean_arch/violet/live_factor_source.py` | clean in this worktree during this assessment | not revalidated here | upstream VIOLET owner / baseline |
| `prod/clean_arch/violet/shadow_journal.py` | clean in this worktree during this assessment | not revalidated here | upstream VIOLET owner / baseline |
| `prod/clean_arch/violet/divergence.py` | clean in this worktree during this assessment | not revalidated here | upstream VIOLET owner / baseline |
| `prod/clean_arch/violet/observe_guard.py` | clean in this worktree during this assessment | not revalidated here | upstream VIOLET owner / baseline |
| `prod/clean_arch/violet/v4_readiness.py` | clean in this worktree during this assessment | not revalidated here | upstream VIOLET owner / baseline |
| `prod/docs/SYSTEM_BIBLE_v7.md` | clean in this worktree during this assessment | not revalidated here | doctrine baseline |
| `prod/docs/DITA_V2_KERNEL_REFERENCE.md` | clean in this worktree during this assessment | not revalidated here | doctrine baseline |
| `prod/docs/VIOLET_DEV_SPEC_AND_PLAN*.md` | clean in this worktree during this assessment | not revalidated here | doctrine baseline |

Notes:
- for files modified or added in this session, the responsible actor is the current local worktree edit path
- for clean baseline files, I did not re-resolve the exact last commit for every single file in this pass
- the assessment is still source-faithful because the runtime path is anchored to the specific files above and the current worktree status is explicit

## 11. Bottom line

VIOLET in this checkout is a BLUE-faithful, VIOLET-namespaced stack with three distinct surfaces:
- observe-only VIOLET, which mirrors the full decision plane but blocks venue writes
- shadow / readiness / divergence, which audit and gate behavior
- live V4 execution, which feeds scan payloads into DITAv2 only after arming passes

The decisive boundary is the handoff from `ExecIntent` into `KernelIntent` and then `bundle.kernel.process_intent_async(...)`.
That is where VIOLET stops being analysis and becomes actual execution through DITAv2.