Strategic Shift Rollout

This document defines the strategic migration tracks and phased rollout sequence without changing runtime behavior today.

Read this page as a rollout clipboard

If you need…	Start here
The current state in one glance	Current state
The work lanes for future changes	Strategic tracks
The rollout order	Phased rollout plan
The placeholder flags	Flag-to-track mapping

Coaching note: Every flag listed here defaults to false. This page is a rollout clipboard for sequencing work, not an activation guide.

Item	Current position
Active phase	Phase 0 — Scaffolding only
Runtime behavior change	None
Feature flag defaults	All listed flags remain `false`
Purpose of this page	Sequence future work before implementation starts

The strategic shift is split into parallel tracks so future migrations can land incrementally:

Track	What moves in this lane
Ingestion track	Source extraction and upstream fetch orchestration updates
Storage track	Data persistence and file/database layout migration
Schema track	Validation and model evolution for new data contracts
Serving track	Downstream access patterns and consumer compatibility

The phased rollout is intentionally low-risk and backward-compatible:

Phase	What happens	Expected behavior
Phase 0 — Scaffolding only (current)	Add config placeholders and documentation artifacts	No behavior changes
Phase 1 — Shadow mode	Enable parallel reads/comparisons behind flags	No production writes
Phase 2 — Dual-write / controlled cutover	Write to both legacy and strategic paths, validate parity, then route traffic gradually	Controlled overlap with parity validation
Phase 3 — Legacy retirement	Remove fallback paths after sustained parity and operational sign-off	Strategic path becomes the only path

Future migrations can be enabled per track or phase using these placeholders:

Area	Placeholder flag
Ingestion track	`NBADB_STRATEGIC_TRACK_INGESTION_V2_ENABLED`
Storage track	`NBADB_STRATEGIC_TRACK_STORAGE_V2_ENABLED`
Schema track	`NBADB_STRATEGIC_TRACK_SCHEMA_V2_ENABLED`
Serving track	`NBADB_STRATEGIC_TRACK_SERVING_V2_ENABLED`
Phase 1 shadow mode	`NBADB_STRATEGIC_PHASE_1_SHADOW_MODE_ENABLED`
Phase 2 dual-write	`NBADB_STRATEGIC_PHASE_2_DUAL_WRITE_ENABLED`

All flags default to false, preserving current behavior until explicitly enabled.

Land flags and documentation before behavior changes.
Keep parity checks in front of cutover decisions.
Treat legacy retirement as the last possession, not the first sign of momentum.
Use this page to coordinate sequencing, not to imply that any future phase is already active.