Plan ยท Standard HTML Version

Hosted Synthetic Tape Redesign

This plan redesigns the hosted synthetic market so the tape feels more like a real market session while still surfacing all six smart-money categories during a demo window. It keeps the public labels stable, adds richer hidden scenario families underneath them, and introduces an internal control surface for shaping the hosted simulator.

Main outcome More believable synthetic options, equities, quotes, and smart-money events, with softer coverage guarantees and stronger cross-asset coupling.
User-facing change An internal-only bottom-right gear opens a compact synthetic-control drawer for operators.
Public API impact No change to existing smart-money event types or public smart-money endpoints.
Why it matters The current tape reaches the categories, but it looks too templated and too clean in ways that weaken the demo.

Simplified Summary

Today the simulator does the important part mechanically: it hits the categories. The problem is that the surrounding market behavior does not always look convincing. Options bursts, equity prints, quote quality, and event timing can feel loosely stitched together instead of driven by one believable market state.

The redesign fixes that by introducing a shared regime engine. Both synthetic options and synthetic equities will respond to the same session conditions, such as event ramps, dealer-gamma chop, retail chase, quiet range trading, and neutral arbitrage-heavy periods. The result should be a tape that still teaches the product, but no longer feels obviously scripted.

The public smart-money taxonomy stays the same: institutional_directional, retail_whale, event_driven, vol_seller, arbitrage, and hedge_reactive.

Scope

In scope
  • Hosted synthetic market regime engine
  • Options and equities synthetic generator redesign
  • Hidden subtype scenario families
  • Soft coverage logic
  • Internal control API and UI
  • Documentation and tests for the new behavior
Out of scope
  • Changing public smart-money profile IDs
  • General settings page work
  • User profile or token-spend features
  • Live market feed changes
  • Public-facing simulator controls

Services Affected

Area Primary files Role in the redesign
Shared types packages/types/src/synthetic-market.ts, packages/types/src/events.ts Add the shared regime model and internal synthetic-control schemas.
Hosted API services/api/src/index.ts Add internal control endpoints and expose hosted simulator status.
Options ingest services/ingest-options/src/index.ts, services/ingest-options/src/adapters/synthetic.ts Adopt the new regime engine, scenario families, and soft coverage logic.
Equities ingest services/ingest-equities/src/index.ts, services/ingest-equities/src/adapters/synthetic.ts Synchronize synthetic quotes and prints with the same latent market regime.
Web and Electron shell apps/web/app/terminal.tsx, apps/web/app/api/admin/synthetic/* Add the internal gear-triggered control drawer and server-side proxy routes.
Tests services/ingest-options/tests/synthetic.test.ts, web tests, API tests Protect classification alignment, determinism, coverage behavior, and control-plane behavior.

Full Plan Contents

  1. Product decisions locked
  2. Architecture
  3. Public and internal interfaces
  4. Implementation sequence
  5. Test cases and scenarios
  6. Assumptions and defaults

Product Decisions Locked

Architecture

1. Replace the simple burst pulse with a shared regime engine

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

Shared functions:

sessionState includes:

2. Add hosted synthetic control state

Add internal control schemas in packages/types:

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:

3. Persist and distribute control state through NATS

4. Rebuild options scenarios as hidden subtype families

Keep public profiles the same, but generate them through richer hidden subtype families.

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

Equities changes:

Options changes:

6. Add soft coverage accounting

7. Add internal hosted control endpoints

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

{
  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:

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

Add server-side proxy routes:

Proxy behavior:

9. Add an internal control surface

UI surface:

Drawer sections:

Controls:

Public and Internal Interfaces

Public contracts unchanged

New internal contracts

New internal endpoints

New environment variables

Backend:

Web:

Implementation Sequence

  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.

Test Cases and Scenarios

Shared engine

Cross-asset coupling

Coverage behavior

Classification alignment

Admin API and UI

Assumptions and Defaults