siloqy/prod/docs/PINK_PODMAN_QUADLET_REARCH_SPEC_2026-05-19.md

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.