Implement A5 fundamentals cutover activation

docs/fundamentals-deployment.md

@@ -1,13 +1,15 @@
 # Fundamentals production deployment
 
 This is the one-time production setup for the Dolt earnings and SEC fundamentals
-imports. Both imports remain shadow inputs until the separate A5 scoring-cutover
-approval. Do not add OS cron entries: the application scheduler owns both jobs.
+imports. The A5 scoring cutover was approved on 2026-07-24; the compat-cache write
+path is still default-off until the explicit production switch below is set. Do
+not add OS cron entries: the application scheduler owns both jobs.
 
 ## What the deployment adds
 
 - `Dolt Earnings Import (shadow)` runs daily at 02:30 America/New_York.
-- `SEC Fundamentals Import (shadow)` runs daily at 04:00 America/New_York.
+- `SEC Fundamentals Import` runs daily at 04:00 America/New_York. Its local
+  `fundamental_data` refresh runs only when the A5 switch is enabled.
 - `Fundamentals Parity Report (read-only)` runs daily at 05:30 America/New_York.
 - Both jobs are visible, toggleable, and manually triggerable in Admin → Jobs.
 - Cron expressions are editable in Admin → Schedule.
@@ -75,7 +77,7 @@ In Admin → Jobs, wait until no other job is running, then:
 
 1. Trigger **Dolt Earnings Import (shadow)**. Expect `completed` with import
    status `promoted`; a repeat without an upstream change should report `no_op`.
-2. Trigger **SEC Fundamentals Import (shadow)**. The first run performs the
+2. Trigger **SEC Fundamentals Import**. The first run performs the
    tracked-universe history backfill and can take materially longer than a daily
    incremental run. Expect `completed` with import status `promoted`.
 3. Check Admin → System Events. There should be no new import error.
@@ -154,10 +156,69 @@ Expect `OK: source lock is busy`. This is the remaining live-PostgreSQL
 mutual-exclusion check; SQLite unit tests cannot exercise PostgreSQL advisory
 locks. A second Admin trigger should independently report the job as busy.
 
+## A5 production activation (approved 2026-07-24)
+
+The write path is controlled by the SystemSetting
+`fundamental_data_sec_dolt_cutover_enabled`. An absent value, `false`, or any
+value other than `true` leaves `fundamental_data` untouched. Before enabling it,
+confirm the normal PostgreSQL backup containing `fundamental_data` is current.
+
+Enable the cutover in PostgreSQL:
+
+```sql
+INSERT INTO system_settings (key, value, updated_at)
+VALUES ('fundamental_data_sec_dolt_cutover_enabled', 'true', now())
+ON CONFLICT (key) DO UPDATE
+SET value = EXCLUDED.value, updated_at = now();
+```
+
+Then trigger **SEC Fundamentals Import** once in Admin → Jobs. The import may be
+`promoted` or `no_op`; either result runs the local refresh. Once enabled, the
+same refresh also runs after an SEC network/validation failure or a source-lock
+skip, because it reads only PostgreSQL snapshots, earnings events, and closes.
+The job message appends the cache row count and changed score-input count when
+the import itself completed successfully.
+
+Verify the switch and refreshed rows:
+
+```sql
+SELECT key, value, updated_at
+FROM system_settings
+WHERE key = 'fundamental_data_sec_dolt_cutover_enabled';
+
+SELECT count(*) AS rows,
+       max(fetched_at) AS refreshed_at,
+       count(pe_ratio) AS pe_available,
+       count(revenue_growth) AS growth_available,
+       count(earnings_surprise) AS surprise_available,
+       count(next_earnings_date) AS next_date_available
+FROM fundamental_data;
+
+SELECT dimension, is_stale, count(*)
+FROM dimension_scores
+WHERE dimension = 'fundamental'
+GROUP BY dimension, is_stale;
+
+SELECT is_stale, count(*)
+FROM composite_scores
+GROUP BY is_stale;
+```
+
+The first refresh intentionally marks affected fundamental and composite score
+caches stale. The normal 15:30 near-close scanner recomputes them before using
+the rankings; until then, reads truthfully expose the stale state. Observe at
+least several scheduled cycles before A6 removes the legacy providers.
+
 ## Failure and rollback
 
-- Disable the failing shadow job in Admin → Jobs. This stops scheduled imports
-  without changing existing data or the legacy scoring path.
+- To stop the A5 cache writes without stopping SEC snapshot ingestion, set
+  `fundamental_data_sec_dolt_cutover_enabled` back to `false` with the SQL above
+  (changing only the value). This prevents the next local refresh but does not
+  restore rows already replaced. Restore `fundamental_data` from the pre-cutover
+  database backup, or—before A6—manually run the legacy Fundamental Collector if
+  its provider keys and quota are still available.
+- Disable a failing source-import job in Admin → Jobs only when ingestion itself
+  must stop. Existing promoted snapshots/events remain available.
 - Inspect the job runtime, latest `data_import_runs.validation_json`, service
   logs, and Admin → System Events before retrying.
 - Re-run `sudo -u deploy bash ./deploy/provision_fundamentals.sh --check` for
@@ -165,8 +226,8 @@ locks. A second Admin trigger should independently report the job as busy.
 - The Dolt clone is a reproducible cache and does not need a bespoke backup.
   PostgreSQL (including `earnings_events`, `fundamental_snapshots`, and import
   audit rows) must remain covered by the normal production database backup.
-- Do not proceed to A5 while either shadow feed is unhealthy or the parity gate
-  has not received explicit approval.
+- Do not proceed to A6 until the activated cache has completed the observation
+  window and the forward earnings calendar remains timely.
 - If report generation fails, inspect Admin → System Events and verify
   `FUNDAMENTALS_PARITY_REPORT_DIR` exists and is writable by `deploy`. Existing
   reports and all live data remain untouched.