# PINK Re-Architecture Specification (Implementation Blueprint)

Status: Approved-for-coding spec (no code in this document)
Date: 2026-05-19
Owner: Runtime/Infra
Target: Add isolated `PINK` testnet execution system with identical trading algorithm behavior to BLUE, while keeping BLUE undisturbed.

---

## 1. Executive Decision

### 1.1 Decision
Build `PINK` as an **isolated sidecar system** with dedicated namespaces and control surfaces, then optionally migrate that sidecar’s infra onto Podman+Quadlet+systemd.

### 1.2 Why this decision
- BLUE must remain undisturbed.
- Current codebase hard-routes many `prod*` paths into PRODGREEN sinks; a naive clone collides.
- BingX account journaling currently dominates data volume and must be controlled explicitly.

### 1.3 Non-negotiable invariant
The **trading algorithm logic must remain identical to BLUE** (signal math, thresholds, decision state machine semantics).

---

## 2. Hard Constraints (Must Hold)

1. No behavior change in core trading logic vs BLUE.
2. No write contamination across BLUE/GREEN/PINK CH databases.
3. No write contamination across BLUE/GREEN/PINK Hazelcast maps.
4. BLUE process manager and lifecycle remain unchanged during PINK buildout.
5. PINK must run BingX in VST/testnet mode only until explicit go-live gate.
6. Any infra re-architecture must be introduced to PINK first, never by replacing BLUE in-place.

---

## 3. Current-State Evidence (Reference Anchors)

### 3.1 Supervisord-first doctrine
- `prod/docs/SYSTEM_BIBLE_v7.md` states all dolphin services are supervisord-managed and warns against dual-management races.
- See:
  - `/mnt/dolphinng5_predict/prod/docs/SYSTEM_BIBLE_v7.md:11`
  - `/mnt/dolphinng5_predict/prod/docs/SYSTEM_BIBLE_v7.md:1339`
  - `/mnt/dolphinng5_predict/prod/docs/SYSTEM_BIBLE_v7.md:3377`

### 3.2 Namespace split already in doctrine
- BLUE: `dolphin`, `DOLPHIN_STATE_BLUE`, `DOLPHIN_PNL_BLUE`
- PRODGREEN: `dolphin_prodgreen`, `DOLPHIN_STATE_PRODGREEN`, `DOLPHIN_PNL_PRODGREEN`
- See:
  - `/mnt/dolphinng5_predict/prod/docs/SYSTEM_BIBLE_v7.md:11`
  - `/mnt/dolphinng5_predict/prod/docs/SYSTEM_BIBLE_v7.md:14`

### 3.3 Hardcoded routing that collides with new strategy names
- BLUE trader hardcoded map keys:
  - `/mnt/dolphinng5_predict/prod/nautilus_event_trader.py:1740`
  - `/mnt/dolphinng5_predict/prod/nautilus_event_trader.py:1741`
  - `/mnt/dolphinng5_predict/prod/nautilus_event_trader.py:1850`
  - `/mnt/dolphinng5_predict/prod/nautilus_event_trader.py:2806`
- `DolphinActor` routes `strategy.startswith("prod")` to PRODGREEN sink:
  - `/mnt/dolphinng5_predict/nautilus_dolphin/nautilus_dolphin/nautilus/dolphin_actor.py:179`
  - `/mnt/dolphinng5_predict/nautilus_dolphin/nautilus_dolphin/nautilus/dolphin_actor.py:180`
- BingX execution hardcodes PRODGREEN strategy/db:
  - `/mnt/dolphinng5_predict/prod/bingx/execution.py:263`
  - `/mnt/dolphinng5_predict/prod/bingx/execution.py:532`
- BingX journal maps `prod*` -> `dolphin_prodgreen`:
  - `/mnt/dolphinng5_predict/prod/bingx/journal.py:90`
  - `/mnt/dolphinng5_predict/prod/bingx/journal.py:91`

### 3.4 Current BingX poll cadence (main source of account-event volume)
- Poll loops:
  - open orders loop
  - positions loop
  - account loop
- See:
  - `/mnt/dolphinng5_predict/prod/bingx/execution.py:707`
  - `/mnt/dolphinng5_predict/prod/bingx/execution.py:723`
  - `/mnt/dolphinng5_predict/prod/bingx/execution.py:732`
  - `/mnt/dolphinng5_predict/prod/bingx/execution.py:741`
- Default intervals:
  - `/mnt/dolphinng5_predict/prod/bingx/config.py:58`
  - `/mnt/dolphinng5_predict/prod/bingx/config.py:59`
  - `/mnt/dolphinng5_predict/prod/bingx/config.py:60`

### 3.5 Data volumes measured (14 complete days; 2026-05-05 to 2026-05-18)
- BLUE-like CH outgoing payload estimate: ~4.17 MB/day avg, ~12.01 MB/day p95-day.
- BLUE-like HZ outgoing payload estimate: ~100.03 MB/day avg, ~301.53 MB/day p95-day.
- PRODGREEN-style BingX `account_events` stream estimate: ~7.41 GB/day avg, ~18.57 GB/day p95-day.

---

## 4. Scope

## 4.1 In scope
1. Introduce first-class `PINK` namespace contract across CH/HZ/control-plane.
2. Preserve algorithm semantics exactly.
3. Isolate PINK execution in BingX VST.
4. Add explicit friction/cost characterization outputs.
5. Add infra spec for Podman+Quadlet+systemd deployment of PINK stack.

## 4.2 Out of scope
1. Any change to signal formula/thresholds/risk decision logic.
2. Any BLUE teardown or manager migration in this phase.
3. Any LIVE mainnet enablement for PINK.

---

## 5. Naming and Namespace Contract

## 5.1 Strategy naming
- Strategy name for new instance: `pink` (lowercase).
- Disallowed for this phase: names with `prod` prefix (e.g., `prodpink`) because current routing treats `prod*` specially.

## 5.2 ClickHouse namespace
- New DB: `dolphin_pink`.
- Required tables (minimum):
  - `trade_events`
  - `trade_reconstruction`
  - `trade_exit_legs`
  - `v7_decision_events`
  - `adaptive_exit_shadow`
  - `account_events`
  - `status_snapshots`
- Optional parity tables if needed by downstream tooling:
  - `sc_threshold_advisor_shadow`
  - `sc_bucket_gauge_shadow`
  - `inverse_ars_bounce_shadow`

## 5.3 Hazelcast namespace
- Maps:
  - `DOLPHIN_STATE_PINK`
  - `DOLPHIN_PNL_PINK`
- Control-plane runtime command queue key:
  - `pink_runtime_commands`
- Capital mirror key:
  - `pink_capital_update_latest`

## 5.4 Trader identity
- Trader ID default:
  - `DOLPHIN-PINK-001`

---

## 6. Required File-Level Changes (Coding Agent Worklist)

Important: This section is prescriptive. Implement all items unless explicitly marked optional.

## 6.1 Sink/routing abstraction

### 6.1.1 `prod/ch_writer.py`
Current state exposes only `_writer`, `_writer_green`, `_writer_prodgreen` and corresponding functions.
- Source anchor: `/mnt/dolphinng5_predict/prod/ch_writer.py:302`

Required:
1. Add `_writer_pink = _CHWriter(db="dolphin_pink")`.
2. Add `ch_put_pink(table: str, row: dict) -> None`.
3. Do not modify behavior of existing sink functions.

Acceptance:
- Unit test asserts writes called via `ch_put_pink` target `dolphin_pink` only.

### 6.1.2 `prod/bingx/journal.py`
Current `_db_for_strategy` routes `prod*` to `dolphin_prodgreen`.
- Anchor: `/mnt/dolphinng5_predict/prod/bingx/journal.py:88`

Required:
1. Replace ad-hoc prefix routing with explicit strategy->db map.
2. Add explicit `pink -> dolphin_pink` mapping.
3. Keep existing `blue`, `green`, `prodgreen` compatibility.
4. Update sink selection to include `ch_put_pink`.

Acceptance:
- For `strategy='pink'`, both journal snapshot writes and lookup reads use only `dolphin_pink`.

### 6.1.3 `prod/bingx/execution.py`
Current code hardcodes:
- `self._journal_strategy = "prodgreen"`
- account-events insert URL database `dolphin_prodgreen`
- Anchors:
  - `/mnt/dolphinng5_predict/prod/bingx/execution.py:263`
  - `/mnt/dolphinng5_predict/prod/bingx/execution.py:532`

Required:
1. Add config-driven `journal_strategy` and `journal_db` fields.
2. Default for existing prodgreen path remains unchanged.
3. PINK launcher passes `journal_strategy='pink'`, `journal_db='dolphin_pink'`.
4. Remove any remaining hardcoded `dolphin_prodgreen` in account-event path.

Acceptance:
- No writes from PINK execution appear in `dolphin_prodgreen.account_events`.

## 6.2 Actor and launcher namespace configurability

### 6.2.1 `prod/launch_dolphin_live.py`
Current defaults are prodgreen-centric:
- state/pnl maps and strategy name.
- Anchors:
  - `/mnt/dolphinng5_predict/prod/launch_dolphin_live.py:78`
  - `/mnt/dolphinng5_predict/prod/launch_dolphin_live.py:79`
  - `/mnt/dolphinng5_predict/prod/launch_dolphin_live.py:132`

Required:
1. Introduce generic env-driven namespace fields:
   - `DOLPHIN_STRATEGY_NAME`
   - `DOLPHIN_STATE_MAP`
   - `DOLPHIN_PNL_MAP`
   - `DOLPHIN_ADAPTIVE_EXIT_DB`
   - `DOLPHIN_V7_JOURNAL_DB`
2. Keep prodgreen defaults backward-compatible.
3. Add dedicated PINK launcher module or mode wrapper with PINK defaults.

Acceptance:
- Running PINK launcher without overrides lands in PINK namespaces only.

### 6.2.2 `nautilus_dolphin/nautilus/.../dolphin_actor.py`
Current default + routing:
- `strategy_name='prodgreen'`
- `startswith("prod")` sink logic
- state/pnl defaults map to PRODGREEN
- Anchors:
  - `/mnt/dolphinng5_predict/nautilus_dolphin/nautilus_dolphin/nautilus/dolphin_actor.py:179`
  - `/mnt/dolphinng5_predict/nautilus_dolphin/nautilus_dolphin/nautilus/dolphin_actor.py:180`
  - `/mnt/dolphinng5_predict/nautilus_dolphin/nautilus_dolphin/nautilus/dolphin_actor.py:181`
  - `/mnt/dolphinng5_predict/nautilus_dolphin/nautilus_dolphin/nautilus/dolphin_actor.py:185`
  - `/mnt/dolphinng5_predict/nautilus_dolphin/nautilus_dolphin/nautilus/dolphin_actor.py:189`

Required:
1. Replace prefix-based sink selection with explicit strategy mapping.
2. Add first-class `pink` mapping for CH sink + default shadow db.
3. Keep old strategy names functional.
4. Ensure aliases do not include BLUE keys in PINK mode.

Acceptance:
- Actor in `pink` mode never writes to `DOLPHIN_STATE_PRODGREEN`, `DOLPHIN_PNL_PRODGREEN`, or `dolphin_prodgreen`.

## 6.3 Control-plane keys and capital surfaces

### 6.3.1 `prod/nautilus_event_trader.py` (if PINK reuses this path)
Current BLUE hardcoding includes:
- `DOLPHIN_STATE_BLUE`, `DOLPHIN_PNL_BLUE`, `blue_runtime_commands`
- Anchors:
  - `/mnt/dolphinng5_predict/prod/nautilus_event_trader.py:1740`
  - `/mnt/dolphinng5_predict/prod/nautilus_event_trader.py:1741`
  - `/mnt/dolphinng5_predict/prod/nautilus_event_trader.py:1850`
  - `/mnt/dolphinng5_predict/prod/nautilus_event_trader.py:2806`

Required (only if this file is used for PINK runtime):
1. Parameterize map names and runtime queue key.
2. Preserve BLUE defaults exactly.
3. Add PINK equivalents via env/config.

Acceptance:
- `SET_CAPITAL` / `CAPITAL_UPDATE` for PINK only affects PINK state surfaces.

Note: Preferred approach is to keep BLUE runtime on this file untouched and run PINK through launcher/actor path first.

## 6.4 Ops scripts and tooling

### 6.4.1 `prod/ops/prodgreen_ctl.py`
Current script is hardcoded to PRODGREEN namespaces.
- Anchors:
  - `/mnt/dolphinng5_predict/prod/ops/prodgreen_ctl.py:23`
  - `/mnt/dolphinng5_predict/prod/ops/prodgreen_ctl.py:24`
  - `/mnt/dolphinng5_predict/prod/ops/prodgreen_ctl.py:42`

Required:
1. Create `pink_ctl.py` OR generalize into namespace-aware ctl tool.
2. Required commands: status, healthcheck, start, stop, restart, mode-verify.
3. Must not invoke BLUE program names by default.

Acceptance:
- `pink_ctl status` reports PINK CH/HZ surfaces only.

---

## 7. ClickHouse Schema Plan for `dolphin_pink`

## 7.1 Strategy
Clone `prodgreen` schema set as baseline for PINK to preserve execution-profile columns.

Reference DDLs:
- `/mnt/dolphinng5_predict/prod/clickhouse/prodgreen/00_create_database.sql`
- `/mnt/dolphinng5_predict/prod/clickhouse/prodgreen/account_events.sql`
- `/mnt/dolphinng5_predict/prod/clickhouse/prodgreen/status_snapshots.sql`
- `/mnt/dolphinng5_predict/prod/clickhouse/prodgreen/trade_events.sql`
- `/mnt/dolphinng5_predict/prod/clickhouse/prodgreen/v7_decision_events.sql`
- `/mnt/dolphinng5_predict/prod/clickhouse/prodgreen/adaptive_exit_shadow.sql`
- `/mnt/dolphinng5_predict/prod/clickhouse/prodgreen/02_create_trade_reconstruction.sql`
- `/mnt/dolphinng5_predict/prod/clickhouse/prodgreen/03_create_trade_exit_legs.sql`

## 7.2 Required migration artifacts
Create new folder:
- `prod/clickhouse/pink/`

Include:
1. `00_create_database.sql` -> `CREATE DATABASE IF NOT EXISTS dolphin_pink;`
2. Full table DDL scripts mirroring prodgreen table structures.
3. Apply script with idempotent checks.

## 7.3 Guardrails
1. No schema mutation to existing `dolphin` or `dolphin_prodgreen` in this phase.
2. No historical retagging/movement required for initial PINK bring-up.

---

## 8. Hazelcast Map and Key Contract

## 8.1 Required map names
- `DOLPHIN_STATE_PINK`
- `DOLPHIN_PNL_PINK`

## 8.2 Required keys in `DOLPHIN_STATE_PINK`
- `engine_snapshot`
- `capital_checkpoint`
- `latest_nautilus`
- optional replay/control keys mirrored from blue contract if PINK runtime supports same capital workflows

## 8.3 Control-plane keys
- Runtime command queue: `pink_runtime_commands`
- Latest capital update mirror: `pink_capital_update_latest`

## 8.4 Isolation validation rule
A PINK process must never read/write keys under `DOLPHIN_STATE_BLUE` or `DOLPHIN_PNL_BLUE` except explicitly allowed read-only analytics queries.

---

## 9. BingX VST Behavior Contract

## 9.1 Environment
- `DOLPHIN_BINGX_ENV=VST`
- `DOLPHIN_BINGX_ALLOW_MAINNET=0`

## 9.2 Expected data venue / exec venue
- Initial recommended mode:
  - data venue: BINANCE (same sensing stream as BLUE)
  - exec venue: BINGX VST

## 9.3 Leverage/sizing mode
- Use existing sizing-mode mechanisms.
- No strategy-logic change permitted.

---

## 10. Data Resource Budget and Controls

## 10.1 Baseline estimates (from measured data)

### CH + HZ for BLUE-like write path
- CH: ~4.17 MB/day avg, ~12.01 MB/day p95-day
- HZ: ~100.03 MB/day avg, ~301.53 MB/day p95-day

### BingX journal risk stream
- `account_events`: ~7.41 GB/day avg, ~18.57 GB/day p95-day if current high-rate snapshots remain.

## 10.2 Mandatory control for `account_events`
Implement at least one, preferably multiple:
1. Snapshot delta suppression beyond fingerprint-only (field-level sampling and minimum emission interval).
2. `ACCOUNT_REFRESH` write interval floor (e.g., min 2s, then tune).
3. Separate high-granularity debug table optional; production `account_events` should be rate-limited.
4. Configurable hard cap alert on rows/minute.

## 10.3 Acceptance thresholds
1. PINK `account_events` sustained rate must stay below agreed cap (set initial policy: <= 5 rows/sec average over 15 min unless debug mode explicitly enabled).
2. Alert if exceeds cap for > 3 consecutive windows.

---

## 11. Observability and ROI/Friction Outputs

## 11.1 Required KPI outputs
1. Realized ROI (closed trades).
2. Open-equity ROI (mark-to-market).
3. Cost-adjusted ROI.
4. Latency decomposition:
   - decision->submit
   - submit->ack
   - ack->first_fill
   - first_fill->done
5. Slippage decomposition (bps against decision/arrival references).
6. Fee/funding components.

## 11.2 Storage location
- PINK metrics rows in `dolphin_pink.trade_events` payload columns and/or dedicated execution quality table.

## 11.3 TUI policy
Current TUI is BLUE-hardcoded in places (`DOLPHIN_STATE_BLUE`, `dolphin.trade_events`, `blue_runtime_commands`).
- Anchors:
  - `/mnt/dolphinng5_predict/Observability/dolphin_status.py:513`
  - `/mnt/dolphinng5_predict/Observability/dolphin_status.py:558`
  - `/mnt/dolphinng5_predict/Observability/dolphin_status.py:1164`
  - `/mnt/dolphinng5_predict/Observability/dolphin_status.py:212`

Required:
1. Do not break BLUE TUI.
2. Add either:
   - separate `dolphin_status_pink.py`, or
   - namespace-parameterized TUI mode.

---

## 12. Podman + Quadlet + systemd Adoption Plan

## 12.1 Strategy
Apply only to PINK stack first.

## 12.2 Preflight checks (must pass before coding)
1. Podman availability on host (`podman --version`).
2. systemd user/service model chosen (rootless preferred unless operationally blocked).
3. Persistent volume paths and permissions validated.
4. ClickHouse config/users mounts parity with current docker-compose pattern.

Current host note: Podman not currently installed (`which podman` returned no result).

## 12.3 Unit boundaries
- BLUE stays under supervisord + current docker compose infra.
- PINK gets independent unit set.
- Do not dual-manage same runtime process with supervisord and systemd.

## 12.4 Quadlet file set for PINK
Create under dedicated path (example):
- `datastack-pink.pod`
- `hazelcast-pink.container` (or reuse cluster only if explicitly designed shared)
- `clickhouse-pink.container` (or shared CH with separate DB if accepted)
- `prefect-pink.container` (if needed)
- `pink-worker.container`

## 12.5 Shared vs dedicated infra policy
Decision required before implementation:
1. Option A (preferred first): shared HZ+CH infra, isolated logical namespaces.
2. Option B: dedicated PINK HZ/CH containers.

Given HZ volatility risk and operational complexity, start with Option A unless a strict physical isolation requirement is imposed.

---

## 13. Algorithm Identity Assurance (Critical)

## 13.1 Required parity harness
Implement deterministic parity checks between BLUE decision path and PINK decision path on identical input replay.

## 13.2 Comparison granularity
At each scan/bar compare tuple hash of:
- signal fired boolean
- selected asset
- side
- leverage intent
- entry/exit action
- reason code
- bars_held progression

No tolerance except for fields explicitly dependent on execution venue acknowledgements.

## 13.3 Fail criteria
Any divergence in pure strategy decisions is a release blocker.

---

## 14. Test Plan (Implementation Exit Criteria)

## 14.1 Unit tests
1. Routing tests for strategy->DB and strategy->HZ map.
2. Sink tests (`ch_put_pink` path).
3. Control key tests (`pink_runtime_commands`).
4. Account-event rate-limit logic tests.

## 14.2 Integration tests
1. Start PINK in VST and verify:
   - CH writes only into `dolphin_pink.*`
   - HZ writes only into `DOLPHIN_STATE_PINK` / `DOLPHIN_PNL_PINK`
2. Verify no new rows in `dolphin_prodgreen.account_events` during PINK-only test run.
3. Verify BLUE process and metrics unaffected.

## 14.3 Soak tests
1. 24h soak with PINK live in VST.
2. Monitor:
   - row rates
   - CH insert error rates
   - HZ heartbeat age
   - control-plane responsiveness

## 14.4 Regression tests
Run existing relevant suites for:
- bingx journaling/accounting
- actor routing
- launch paths
- MHS basic health checks for BLUE unaffectedness

---

## 15. Deployment Sequence (Phased)

## Phase 0: Namespace groundwork
1. Add sink and routing abstractions.
2. Add PINK CH schema migration artifacts.
3. Add PINK launcher and env contract.

Gate 0:
- Compile/tests pass.
- Static grep verifies no hardcoded fallback from `pink` to `prodgreen`.

## Phase 1: PINK logical bring-up (same infra)
1. Start PINK process under current management (or controlled runner) with VST.
2. Verify strict namespace isolation.
3. Run parity harness with replay feed.

Gate 1:
- No contamination.
- Parity pass.

## Phase 2: Data-volume control tuning
1. Tune account-event emission controls.
2. Verify row-rate caps and KPI completeness.

Gate 2:
- Resource budgets stable.

## Phase 3: Optional Podman+Quadlet packaging for PINK
1. Build PINK quadlet units.
2. Validate independent lifecycle.
3. Keep BLUE unchanged.

Gate 3:
- PINK can be fully operated without impacting BLUE.

---

## 16. Rollback Plan

## 16.1 Soft rollback
1. Stop PINK process/unit only.
2. Leave BLUE untouched.
3. Preserve PINK CH/HZ artifacts for postmortem.

## 16.2 Hard rollback
1. Revert routing patches that introduced PINK mapping.
2. Keep PINK DB as historical archive or drop only after approval.

## 16.3 Explicit no-rollback targets
Do not alter BLUE capital/state surfaces during PINK rollback.

---

## 17. Security and Safety

1. PINK VST keys isolated from BLUE credentials.
2. No mainnet enable unless separate approval gate flips `DOLPHIN_BINGX_ALLOW_MAINNET=1`.
3. Validate no accidental propagation of PINK credentials into shared logs.

---

## 18. Deliverables Checklist (Coding Agent Must Produce)

1. Code changes implementing explicit strategy/namespace routing for PINK.
2. `dolphin_pink` CH schema files in `prod/clickhouse/pink/`.
3. PINK launcher/config entrypoint.
4. PINK ops control script or generalized namespace-aware ctl tool.
5. Unit + integration tests for routing/isolation.
6. Parity harness and parity report artifact.
7. Data-rate monitor/report for `account_events` and major tables.
8. Optional: Quadlet unit files for PINK stack (if Phase 3 in scope).

---

## 19. Coding Prohibitions (Strict)

1. Do not alter algorithm constants or decision logic behavior.
2. Do not remove or repurpose BLUE maps/tables.
3. Do not bind PINK to names beginning with `prod` in this phase.
4. Do not change BLUE process manager/runtime flow as part of PINK implementation.

---

## 20. Open Decisions Requiring Explicit Operator Choice

1. PINK infra physical model:
   - shared CH/HZ vs dedicated CH/HZ.
2. PINK manager in early phases:
   - supervised process first vs direct Quadlet rollout.
3. Account-event rate cap values:
   - initial thresholds and alert policy.

If decisions are not provided, default choices are:
- shared CH/HZ with strict logical isolation,
- supervised PINK process before Quadlet migration,
- account-events cap <= 5 rows/sec sustained (debug off).

---

## 21. Minimal Go/No-Go Matrix

Go only if all true:
1. Strategy parity = exact pass.
2. Namespace contamination tests = zero leaks.
3. Data-rate caps respected during soak.
4. BLUE observability and trade loop unchanged.

No-Go if any true:
1. `pink` rows appear in `dolphin_prodgreen` or `dolphin` unexpectedly.
2. BLUE map/table writes change baseline rates materially.
3. Decision parity drifts.
4. VST safety flags not enforced.

---

## 22. Final Operator Notes

- This spec intentionally separates **architecture modernization** from **algorithm behavior**.
- PINK is the safe proving ground for infra re-architecture.
- BLUE remains production reference and must not be structurally disturbed until PINK completes parity + soak + resource gates.