plan synthetic and smart-flow phases

docs/implementation/synthetic-market-data/00-roadmap.md

@@ -0,0 +1,36 @@
+# Synthetic Market-Data Roadmap
+
+This roadmap breaks `docs/plans/synthetic-market-data-architecture-review.md` into implementation-sized phases. The recommended direction is still Option B: extract deterministic synthetic generation into a first-class reusable engine while keeping the useful NATS, ClickHouse, compute, API, replay, and web stack.
+
+## Core Constraints
+
+- Emit canonical market event types: `OptionPrint`, `OptionNBBO`, `EquityPrint`, and `EquityQuote`.
+- Do not create synthetic-only market event types for the main pipeline.
+- Keep hidden ground-truth labels separate from emitted market events.
+- Keep early quality gates infra-free: `bun test` should not require Docker, ClickHouse, NATS, or Redis.
+- Build deterministic foundations before demos, UI controls, or live synthetic service behavior.
+- Treat historical calibration as future work, not as a dependency for the MVP synthetic generator.
+
+## Phase Sequence
+
+| Phase | Beads issue | Depends on | Purpose |
+| --- | --- | --- | --- |
+| 01 - Deterministic spine | `islandflow-259.1` | None | Create the seeded generation foundation and canonical event output contract. |
+| 02 - Manifests, fixtures, CLI | `islandflow-259.2` | `islandflow-zxh.1` | Turn deterministic generation into durable fixtures and manifests. |
+| 03 - Scenarios, labels, expected outputs | `islandflow-259.3` | `islandflow-zxh.2` | Author named scenarios, separate labels, and expected derived outputs. |
+| 04 - Replay integration | `islandflow-259.4` | `islandflow-zxh.3` | Make replay consume synthetic runs with stable ordering and output comparison. |
+| 05 - Demo and load profiles | `islandflow-259.5` | `islandflow-zxh.4` | Expose named deterministic demo/load profiles after replay validation. |
+| 99 - Future historical calibration | `islandflow-259.6` | `islandflow-259.5` | Calibrate parameters from historical data later, after the MVP is stable. |
+
+## PR Split Notes
+
+Most phases are intended to fit in one focused PR. Phase 03 is already split into PR-sized Beads children because scenario authoring and expected-output comparison can grow quickly:
+
+- `islandflow-259.3.1` - Split synthetic phase 03a: scenario catalog and labels
+- `islandflow-259.3.2` - Split synthetic phase 03b: expected-output manifests
+
+If any other phase starts touching unrelated service, API, UI, and storage behavior in one PR, split it before implementation continues.
+
+## Matching Beads Epic
+
+- `islandflow-259` - Plan synthetic market-data implementation phases

docs/implementation/synthetic-market-data/01-deterministic-spine.md

@@ -0,0 +1,68 @@
+# Synthetic Market-Data Phase 01: Deterministic Spine
+
+## Purpose
+
+Create the reusable deterministic foundation for synthetic market data. This phase should define the package/API shape for seeded generation, stable run identity, profile inputs, canonical event outputs, and provenance metadata.
+
+## Why this phase comes now
+
+Everything else depends on reproducible raw events. Manifests, labels, replay, demos, and smart-flow tests are only trustworthy if the same seed/profile bundle produces the same canonical market event stream every time.
+
+## Dependencies on earlier phases
+
+None. This is the first synthetic phase.
+
+## Likely files/modules touched
+
+- Future `packages/synthetic-market/` workspace or equivalent package boundary
+- `packages/types/src/events.ts`
+- Synthetic logic currently embedded in `services/ingest-options/` and `services/ingest-equities/`
+- Shared package manifests such as `package.json`, `bunfig.toml`, or workspace config if a new package is added
+- Infra-free unit tests under the new package or nearby package test folders
+
+## In-scope work
+
+- Define `SyntheticRun`, `SeedBundle`, `ParameterSnapshot`, `SymbolProfile`, `LiquidityProfile`, `VolatilityRegime`, `OptionChainProfile`, and `GeneratedEventBatch` shapes.
+- Pick and wrap a deterministic PRNG so fixed inputs produce stable output.
+- Emit canonical `OptionPrint`, `OptionNBBO`, `EquityPrint`, and `EquityQuote` events.
+- Attach provenance such as `source_kind`, `run_id`, `parameter_snapshot_hash`, and optional `scenario_id`.
+- Preserve compatibility with the existing pipeline's raw market event contracts.
+- Add fast deterministic tests that run in plain `bun test`.
+
+## Explicitly out-of-scope work
+
+- Scenario catalogs and ground-truth label records.
+- Manifest generation and CLI workflows.
+- Replay service integration.
+- Hosted demo controls or live synthetic emitters.
+- Historical calibration from real market data.
+- Docker, ClickHouse, NATS, or Redis integration tests.
+
+## Acceptance criteria
+
+- A fixed seed/profile bundle produces byte-stable or hash-stable event output.
+- Generated events use canonical market event contracts, not synthetic-only pipeline event types.
+- Hidden labels are not embedded in emitted market events.
+- Provenance metadata is available for downstream filtering and auditing.
+- Tests cover determinism, tick validity, quote/trade invariants, and basic profile normalization without requiring infrastructure.
+
+## Test strategy
+
+Use infra-free Bun tests. Cover PRNG repeatability, profile parsing, event ordering within generated batches, option quote/print validity, equity quote/print validity, and provenance field stability. Avoid any test that needs Docker, ClickHouse, NATS, or Redis.
+
+## Risks / design traps
+
+- Hiding wall-clock timers or random calls inside the generator will break determinism.
+- Creating synthetic-only market event types will fork the pipeline contract.
+- Embedding labels directly on market events will leak ground truth into production-like paths.
+- Over-designing a full market simulator now will slow down the MVP.
+
+## Suggested future Codex implementation prompt
+
+```text
+Implement docs/implementation/synthetic-market-data/01-deterministic-spine.md for Beads issue islandflow-259.1. Stay inside the deterministic synthetic market-data foundation only. Do not add scenario labels, manifests, replay integration, demos, or historical calibration. Emit canonical market event types and keep early tests infra-free.
+```
+
+## Matching Beads issue title/id
+
+- `islandflow-259.1` - Synthetic market-data phase 01: deterministic spine

docs/implementation/synthetic-market-data/02-manifests-fixtures-cli.md

@@ -0,0 +1,68 @@
+# Synthetic Market-Data Phase 02: Manifests, Fixtures, and CLI
+
+## Purpose
+
+Turn the deterministic generator into reusable artifacts: fixture files, run manifests, and a CLI that can produce repeatable synthetic runs for tests, replay, demos, and later evaluation.
+
+## Why this phase comes now
+
+The deterministic spine gives the repo stable raw events. The next step is to make those events durable and addressable so downstream phases can reference exact generated runs instead of recreating ad hoc local randomness.
+
+## Dependencies on earlier phases
+
+- `islandflow-259.1` - Synthetic deterministic spine
+- `islandflow-zxh.1` - Smart-flow contracts and vocabulary, so manifest expectations can align with the emerging evidence/hypothesis language
+
+## Likely files/modules touched
+
+- Future `packages/synthetic-market/` CLI entrypoints
+- Fixture directories under a package or service test area
+- Manifest schemas, likely JSON or YAML
+- `package.json` scripts if a repo command is added
+- Tests for manifest parsing and fixture generation
+
+## In-scope work
+
+- Define `ExpectedOutputManifest`, `ReplayPlan`, and generated fixture artifact layout.
+- Add a CLI command that accepts seed bundle, profile, scenario/run name, output directory, and deterministic generation options.
+- Write manifests that pin generator version, seed bundle, parameter snapshot hash, generated event hashes, replay ordering, and run metadata.
+- Add fixture helpers for tests to load generated batches without infrastructure.
+- Keep labels as separate records or future manifest sections, not market-event fields.
+
+## Explicitly out-of-scope work
+
+- Full scenario catalog authoring.
+- Smart-flow expected output comparisons.
+- Replay service source selection.
+- ClickHouse fixture materialization.
+- UI demo selection.
+- Historical calibration.
+
+## Acceptance criteria
+
+- A CLI can generate repeatable fixtures and manifests from fixed inputs.
+- Manifests include generator version, seed/profile identity, parameter hash, event hashes, and replay ordering.
+- Fixture helpers can load generated event batches in infra-free tests.
+- Generated artifacts do not embed hidden labels into canonical market events.
+- Re-running generation with the same inputs produces stable manifests or an intentional diff.
+
+## Test strategy
+
+Use plain Bun tests for CLI argument parsing, manifest schema parsing, deterministic fixture output, and fixture-loader helpers. Golden files should be small and intentionally reviewed. Do not require Docker, ClickHouse, NATS, or Redis.
+
+## Risks / design traps
+
+- Manifests that omit generator version or parameter hashes will become hard to audit.
+- Large generated fixtures can create noisy reviews; keep early fixtures tiny.
+- A CLI that silently uses defaults will make tests look deterministic while hiding input drift.
+- Mixing expected smart-flow outputs too early can couple this phase to unfinished classifier changes.
+
+## Suggested future Codex implementation prompt
+
+```text
+Implement docs/implementation/synthetic-market-data/02-manifests-fixtures-cli.md for Beads issue islandflow-259.2. Build manifest, fixture, and CLI support on top of the deterministic spine. Keep tests infra-free and do not implement scenario labels, replay integration, demo profiles, or historical calibration.
+```
+
+## Matching Beads issue title/id
+
+- `islandflow-259.2` - Synthetic market-data phase 02: manifests, fixtures, and CLI

docs/implementation/synthetic-market-data/03-scenarios-labels-expected-outputs.md

@@ -0,0 +1,71 @@
+# Synthetic Market-Data Phase 03: Scenarios, Labels, and Expected Outputs
+
+## Purpose
+
+Author named deterministic scenarios, separate ground-truth labels, and expected-output manifests that downstream smart-flow logic can use for positive, negative, abstention, and false-positive validation.
+
+## Why this phase comes now
+
+The generator and manifest layers should exist before scenario authoring. Smart-flow evidence clustering should also define enough vocabulary for expected outputs to describe evidence requirements without leaking labels into emitted market events.
+
+## Dependencies on earlier phases
+
+- `islandflow-259.1` - Synthetic deterministic spine
+- `islandflow-zxh.1` - Smart-flow contracts and vocabulary
+- `islandflow-259.2` - Manifests, fixtures, and CLI
+- `islandflow-zxh.2` - Evidence clustering and features
+
+## Likely files/modules touched
+
+- Future scenario catalog files under `packages/synthetic-market/`
+- Label schema definitions
+- Manifest expected-output sections
+- Fixture generation tests
+- Smart-flow fixture expectations in compute test areas, once available
+
+## In-scope work
+
+- Define `ScenarioInjection` and `GroundTruthLabel` records.
+- Add named scenario profiles for institutional directional flow, retail-attention flow, event/noise flow, volatility-seller behavior, hedge-reactive flow, arbitrage-like structure, and no-alert negatives.
+- Keep labels keyed by `run_id`, `scenario_id`, event IDs or trace IDs, expected class, expected direction, confidence band, required evidence, forbidden evidence, and false-positive penalties.
+- Extend manifests with expected derived events, alert/no-alert expectations, and evidence requirements.
+- Make generated scenario outputs reviewable and deterministic.
+
+## Explicitly out-of-scope work
+
+- Emitting labels on market events.
+- Building a live synthetic service.
+- Adding UI scenario controls.
+- Implementing historical calibration.
+- Rewriting smart-flow scoring behavior beyond what is needed to express expected outputs.
+
+## Acceptance criteria
+
+- Scenario fixtures are named, deterministic, and small enough for review.
+- Labels remain separate from emitted market events.
+- Expected-output manifests include positive expectations, no-alert expectations, evidence requirements, forbidden evidence, and false-positive penalties.
+- The phase can test both "should detect" and "should abstain or suppress" cases.
+- Existing issue `islandflow-9dz` is treated as related scenario-tuning context, not as the broad phase tracker.
+
+## Test strategy
+
+Use fixture-generation and manifest-validation tests first. Add focused golden comparisons only where the smart-flow contract is ready. Keep the default test path infra-free. Optional service-backed scenario loading can wait for a later integration phase.
+
+## Risks / design traps
+
+- Labels leaking into canonical event payloads will invalidate evaluation.
+- Only authoring positive scenarios will make the classifier overfit demos.
+- Broad scenario catalogs can become too large for one PR.
+- Expected outputs that name legacy "smart money" certainty can undermine the new evidence/hypothesis model.
+
+## Suggested future Codex implementation prompt
+
+```text
+Implement docs/implementation/synthetic-market-data/03-scenarios-labels-expected-outputs.md for Beads issue islandflow-259.3. Split the work using islandflow-259.3.1 and islandflow-259.3.2 if needed. Keep labels separate from emitted events, include negative/no-alert expectations, and avoid demos or live service work.
+```
+
+## Matching Beads issue title/id
+
+- `islandflow-259.3` - Synthetic market-data phase 03: scenarios, labels, and expected outputs
+- PR split: `islandflow-259.3.1` - Split synthetic phase 03a: scenario catalog and labels
+- PR split: `islandflow-259.3.2` - Split synthetic phase 03b: expected-output manifests

docs/implementation/synthetic-market-data/04-replay-integration.md

@@ -0,0 +1,69 @@
+# Synthetic Market-Data Phase 04: Replay Integration
+
+## Purpose
+
+Make replay consume synthetic runs deterministically, either directly from generated fixtures or from materialized storage rows, while preserving the same ordering semantics the real replay path uses.
+
+## Why this phase comes now
+
+Replay should not be wired to synthetic data until the generator, manifests, labels, and smart-flow hypothesis pipeline have stable semantics. At this point, replay can become a serious acceptance gate instead of a demo convenience.
+
+## Dependencies on earlier phases
+
+- `islandflow-259.1` - Synthetic deterministic spine
+- `islandflow-259.2` - Manifests, fixtures, and CLI
+- `islandflow-259.3` - Scenarios, labels, and expected outputs
+- `islandflow-zxh.3` - Hypothesis scoring and abstention
+
+## Likely files/modules touched
+
+- `services/replay/src/`
+- API replay routes in `services/api/`
+- Replay-related shared types in `packages/types/`
+- Optional fixture materialization helpers in `packages/storage/`
+- Replay tests or golden comparison helpers
+
+## In-scope work
+
+- Add replay source/run selectors for synthetic runs.
+- Support fixture-backed replay without infrastructure where practical.
+- Preserve ordering by event time, ingest time, sequence, and stable event ID.
+- Compare replayed derived outputs against manifest signatures or expected-output sections.
+- Keep optional ClickHouse/NATS materialized replay tests behind non-default gates.
+
+## Explicitly out-of-scope work
+
+- Building new scenario labels.
+- Reworking smart-flow scoring policy.
+- Demo profile controls.
+- Load testing.
+- Historical calibration.
+
+## Acceptance criteria
+
+- Replay can select a synthetic source and `run_id`.
+- Fixture-backed replay respects manifest ordering.
+- Derived output signatures can be compared with expected manifests.
+- Fast replay tests remain infra-free by default.
+- Optional infra-backed tests are clearly named and gated.
+
+## Test strategy
+
+Start with fixture-backed replay ordering tests and manifest-signature comparisons. Add optional service-container or ClickHouse materialization tests only after the fast path is stable, and do not make those tests part of the default `bun test` requirement.
+
+## Risks / design traps
+
+- Creating a synthetic-only replay path with different ordering will hide bugs.
+- Letting optional infra tests become default will slow or destabilize CI.
+- Comparing full raw payloads everywhere may make tests brittle; use stable signatures where better.
+- Replay selectors that are not run-scoped can mix synthetic and live data.
+
+## Suggested future Codex implementation prompt
+
+```text
+Implement docs/implementation/synthetic-market-data/04-replay-integration.md for Beads issue islandflow-259.4. Add synthetic source/run replay support with stable ordering and manifest comparison. Do not add demo controls, load profiles, or historical calibration, and keep the fast test path infra-free.
+```
+
+## Matching Beads issue title/id
+
+- `islandflow-259.4` - Synthetic market-data phase 04: replay integration

docs/implementation/synthetic-market-data/05-demo-load-profiles.md

@@ -0,0 +1,70 @@
+# Synthetic Market-Data Phase 05: Demo and Load Profiles
+
+## Purpose
+
+Expose deterministic synthetic runs as named demo and load profiles after the generation, manifest, scenario, and replay foundations are in place.
+
+## Why this phase comes now
+
+Demos are useful only after the underlying data can be trusted. This phase deliberately waits until replay and golden evaluation prove the event semantics, so hosted controls do not become a front door to ambient randomness.
+
+## Dependencies on earlier phases
+
+- `islandflow-259.1` - Synthetic deterministic spine
+- `islandflow-259.2` - Manifests, fixtures, and CLI
+- `islandflow-259.3` - Scenarios, labels, and expected outputs
+- `islandflow-259.4` - Replay integration
+- `islandflow-zxh.4` - Smart-flow replay evaluation and golden tests
+
+## Likely files/modules touched
+
+- Thin synthetic emitters in `services/ingest-options/` and `services/ingest-equities/`
+- Demo/run selection API surfaces in `services/api/`
+- Web demo controls in `apps/web/`
+- Load profile definitions in the synthetic package
+- Tests for profile selection and rate scaling
+
+## In-scope work
+
+- Add named `DemoProfile` and `LoadProfile` definitions.
+- Make live/demo emitters thin consumers of deterministic synthetic runs.
+- Let demo controls select named runs/scenarios rather than changing hidden random behavior.
+- Ensure load profiles scale event rates without changing event semantics.
+- Document local demo usage once implemented.
+
+## Explicitly out-of-scope work
+
+- Foundation generator work.
+- New smart-flow scoring policy.
+- Replacing replay evaluation with UI-only checks.
+- Historical calibration.
+- Production provider configuration decisions.
+
+## Acceptance criteria
+
+- Demo profiles are deterministic and named.
+- Load profiles scale rate or volume without mutating scenario semantics.
+- Hosted or local controls select known runs/scenarios.
+- Live/demo emitters remain thin and do not own generator policy.
+- The UI does not expose synthetic controls before the backing deterministic runs exist.
+
+## Test strategy
+
+Use unit tests for profile parsing, profile selection, and rate-scaling semantics. Add replay-driven smoke checks for named demo runs. Manual UI validation is appropriate only after automated replay/golden checks pass.
+
+## Risks / design traps
+
+- Demo controls can pressure the codebase back into wall-clock randomness.
+- Load profiles may accidentally change business semantics while changing only rate was intended.
+- UI-first implementation can hide missing run provenance.
+- Reusing production config for synthetic demos can make operator behavior ambiguous.
+
+## Suggested future Codex implementation prompt
+
+```text
+Implement docs/implementation/synthetic-market-data/05-demo-load-profiles.md for Beads issue islandflow-259.5. Add named deterministic demo/load profiles and thin emitter/control integration only after replay validation exists. Do not implement historical calibration or change production provider policy.
+```
+
+## Matching Beads issue title/id
+
+- `islandflow-259.5` - Synthetic market-data phase 05: demo and load profiles

docs/implementation/synthetic-market-data/99-future-historical-calibration.md

@@ -0,0 +1,64 @@
+# Synthetic Market-Data Phase 99: Future Historical Calibration
+
+## Purpose
+
+Plan future calibration of synthetic generator parameters from historical market data without making historical data a dependency for the MVP generator.
+
+## Why this phase comes now
+
+It is useful to name the future work now so early designs keep calibration hooks in mind. It should not come before deterministic generation, manifests, scenarios, replay, or demo profiles.
+
+## Dependencies on earlier phases
+
+- `islandflow-259.5` - Synthetic demo and load profiles
+
+## Likely files/modules touched
+
+- Future calibration tools under the synthetic package
+- Historical data import or sampling utilities
+- Parameter fitting scripts
+- Documentation for data provenance and licensing constraints
+- Optional research notebooks or reports if the repo later adopts them
+
+## In-scope work
+
+- Define calibration datasets and constraints.
+- Specify how historical distributions map to `ParameterSnapshot`, liquidity, volatility, and option-chain profiles.
+- Preserve deterministic replay from calibrated parameters.
+- Document privacy, licensing, and provenance requirements for historical data.
+
+## Explicitly out-of-scope work
+
+- MVP synthetic generator requirements.
+- Early tests and fixture generation.
+- Live synthetic demos.
+- Smart-flow scoring changes.
+- Any assumption that historical data is needed to start implementation.
+
+## Acceptance criteria
+
+- Historical calibration remains outside the MVP blocker chain.
+- Calibration inputs and ownership constraints are documented before implementation.
+- Fitted parameters can still be pinned into deterministic seed/profile bundles.
+- Calibration does not require emitted synthetic events to diverge from canonical market event contracts.
+
+## Test strategy
+
+When this future phase is implemented, use small public or licensed calibration samples with deterministic parameter fitting tests. Add regression checks that calibrated profiles still produce stable manifests. Do not retrofit historical data into earlier infra-free tests.
+
+## Risks / design traps
+
+- Treating calibration as necessary for MVP will delay foundational work.
+- Historical data licensing can constrain what can be committed or shared.
+- Overfitting synthetic profiles to a tiny period can produce misleading demos.
+- Calibration tools can accidentally leak proprietary or sensitive data into fixtures.
+
+## Suggested future Codex implementation prompt
+
+```text
+Implement docs/implementation/synthetic-market-data/99-future-historical-calibration.md for Beads issue islandflow-259.6 only after MVP synthetic phases are complete. Keep calibration optional, documented, and deterministic. Do not make historical data a dependency for earlier synthetic tests or demos.
+```
+
+## Matching Beads issue title/id
+
+- `islandflow-259.6` - Future synthetic market-data phase 99: historical calibration