Make the tape feel alive, not scheduled.

Simplified Overview

The current synthetic system is strong at coverage and weaker at realism. It can produce the categories, but the tape often reveals the machinery: option bursts appear on a rhythm, quotes are too consistently clean, equities and options are only loosely related, and the market context around a labeled event is not convincing enough.

The redesign introduces a shared market regime engine. Instead of “emit a category-shaped burst now,” the system will model a believable session state first, then let both options and equities express that state. That keeps the smart-money demo behavior while making the experience feel more grounded.

Scope

Services Affected

Locked Decisions

Full Architecture

1. Replace the burst pulse with a shared regime engine

Expand packages/types/src/synthetic-market.ts into the shared deterministic engine used by both ingest services.

Shared functions:

• getSyntheticSessionState(ts, control)
• getSyntheticUnderlyingState(symbol, ts, control, sessionState)
• getSyntheticScenarioWeights(symbol, ts, control, sessionState)
• getSyntheticCoverageBoost(profileId, coverageState, control)

sessionState includes:

• session_phase: open | midday | power_hour | after_event
• regime: trend_up | trend_down | mean_revert | retail_chase | event_ramp | dealer_gamma | arb_calm
• volatility_level
• liquidity_level
• quote_cleanliness
• focus_symbols
• event_symbols
• seed_bucket

2. Add hosted synthetic control state

Add internal control schemas in packages/types:

• SyntheticControlPresetId
• SyntheticControlState
• SyntheticProfileWeightMap
• SyntheticCoverageConfig
• SyntheticDerivedStatus

type SyntheticControlState = {
  preset_id: "balanced_demo" | "event_day" | "dealer_day" | "retail_chase" | "quiet_range";
  coverage_assist: boolean;
  coverage_window_minutes: 10 | 20 | 30;
  shared_seed: number;
  profile_weights: {
    institutional_directional: 0.6 | 1.0 | 1.6;
    retail_whale: 0.6 | 1.0 | 1.6;
    event_driven: 0.6 | 1.0 | 1.6;
    vol_seller: 0.6 | 1.0 | 1.6;
    arbitrage: 0.6 | 1.0 | 1.6;
    hedge_reactive: 0.6 | 1.0 | 1.6;
  };
  updated_at: number;
  updated_by: string;
};

Defaults: preset_id: balanced_demo, coverage_assist: true, coverage_window_minutes: 20, all profile weights 1.0.

3. Persist and distribute control state through NATS

• Use JetStream KV bucket synthetic_control
• Use key global
• services/api reads and writes the KV entry
• services/ingest-options loads on boot and watches for updates
• services/ingest-equities does the same

4. Rebuild options scenarios as hidden subtype families

• institutional_directional: call_sweep, put_sweep, ask_lift_accumulation, far_dated_conviction
• retail_whale: 0dte_call_chase, short_dated_put_panic, attention_contract_spike
• event_driven: earnings_vol_probe, pre_event_directional_ramp, post_gap_followthrough
• vol_seller: covered_call_overwrite, cash_secured_put_write, short_straddle_harvest
• arbitrage: parity_vertical, conversion_reversal, box_spread
• hedge_reactive: gamma_pinch_call_hedge, reactive_put_wall, dealer_unwind
• neutral_noise: single_print_mid, two_sided_scalp, stale_quote_noise

Hidden subtype labels remain internal and test-only. They should never appear on emitted option prints or public smart-money events.

5. Make equities and options react to the same latent state

6. Add soft coverage accounting

• Track rolling coverage debt per public profile inside each ingest service
• Maintain a rolling counter across the selected coverage_window_minutes
• Only public profiles count toward coverage
• Missing profiles get a bounded weight boost
• Noise and low-key scenarios continue to appear between labeled bursts

7. Add internal hosted control endpoints

Add routes in services/api/src/index.ts:

• GET /admin/synthetic/status
• GET /admin/synthetic/control
• PUT /admin/synthetic/control

{
  enabled: boolean;
  backend_mode: "synthetic" | "mixed" | "live";
  adapters: {
    options: string;
    equities: string;
  };
  control: SyntheticControlState | null;
  derived: {
    session_phase: string;
    regime: string;
    focus_symbols: string[];
    profile_hit_counts: Record<SmartMoneyProfileId, number>;
    coverage_window_minutes: number;
  } | null;
  disabled_reason?: string;
}

Behavior: return 404 when admin mode is disabled, return 409 when hosted adapters are not synthetic, validate full payloads on PUT, and keep public smart-money interfaces unchanged.

8. Keep secrets out of the browser with Next.js proxy routes

• apps/web/app/api/admin/synthetic/status/route.ts
• apps/web/app/api/admin/synthetic/control/route.ts

The proxy reads server-only SYNTHETIC_ADMIN_TOKEN, forwards to NEXT_PUBLIC_API_URL, returns 404 when the internal UI flag is off, and never exposes the token client-side.

9. Add an internal control surface

UI rules for the first pass:

• Small floating gear in the bottom-right corner
• Opens a right-edge non-modal drawer
• Internal-only visibility
• Preset dropdown: Balanced Demo, Event Day, Dealer Day, Retail Chase, Quiet Range
• Coverage assist toggle
• Coverage window selector: 10m, 20m, 30m
• Six profile-weight controls: Low, Normal, High
• Read-only live status: regime, session phase, focus symbols, rolling hit counts, backend state
• Optimistic updates with rollback on error
• Debounced writes at 250ms
• Status polling every 5s, no admin websocket in v1

Interfaces and Environment

Implementation Phases

1. Phase 1. Shared types and regime engine

   Touch packages/types/src/synthetic-market.ts and related exports and tests. Deliver control schemas, preset definitions, deterministic session and regime functions, and coverage boost helpers.

2. Phase 2. Hosted control plane

   Touch services/api/src/index.ts and NATS or KV helpers as needed. Deliver admin endpoints, KV persistence, status payloads, and disabled or error behavior.

3. Phase 3. Ingest service coupling

   Touch both ingest services and their synthetic adapters. Deliver boot-time control loading, KV watch updates, shared regime-driven generation, and removal of visibly scripted fixed sequences.

4. Phase 4. Internal control UI

   Touch apps/web/app/terminal.tsx and the internal admin proxy routes. Deliver the floating gear, non-modal drawer, polling, optimistic updates, and disabled state.

5. Phase 5. Regression and realism tests

   Deliver determinism tests, control API tests, scenario coverage tests, UI visibility tests, and classifier-alignment tests for hidden subtype families.

Tests and Acceptance

Assumptions and Defaults

• Hosted synthetic control applies only when both options and equities ingest adapters are synthetic.
• No general settings page, user-info work, or token-spend work is in scope here.
• Hidden subtype labels remain internal and test-only and never attach to emitted prints.
• The first pass uses polling for admin status rather than a new admin websocket.
• The default operator experience is Balanced Demo with soft coverage on and a 20-minute window.
• The repo currently lacks local PRODUCT.md, DESIGN.md, and the local impeccable loader path. This version therefore follows the spirit of the terminal shell and impeccable product-UI principles rather than project-specific design-context files.