feat: add guarded production Flow v2 authoritative simulation

app/opportunity_next_action_service.py

@@ -376,13 +376,24 @@ def get_opportunity_next_actions(opportunity_ids: Iterable[str]) -> Dict[str, Di
     if not ids:
         return {}
 
-    if _flow_v2_mode() == "authoritative":
-        return _get_authoritative_opportunity_decisions(ids)
+    return get_opportunity_next_actions_for_mode(ids, flow_mode=_flow_v2_mode())
+
+
+def get_opportunity_next_actions_for_mode(
+    opportunity_ids: Iterable[str], *, flow_mode: str, connection: Any = None,
+) -> Dict[str, Dict[str, Any]]:
+    """Explicit-mode read boundary used by the read-only cutover simulation."""
+    ids = list(dict.fromkeys(str(value).strip() for value in opportunity_ids if str(value).strip()))
+    if not ids:
+        return {}
+    if flow_mode == "authoritative":
+        return _get_authoritative_opportunity_decisions(ids, connection=connection)
 
     # Read path only: schema creation belongs to startup/migrations.  In
     # particular, GET /operations must never perform DDL while calculating its
     # canonical projection.
-    with engine.begin() as conn:
+    from contextlib import nullcontext
+    with (nullcontext(connection) if connection is not None else engine.begin()) as conn:
         opportunities = _bulk_rows(conn, """
             SELECT id::text, stage, status, title,
                    local_customer_id::text AS fiscal_customer_id,
@@ -453,13 +464,15 @@ def get_opportunity_next_actions(opportunity_ids: Iterable[str]) -> Dict[str, Di
             company_profile="blif",
         )
         decisions[oid] = decide_opportunity_next_action(evidence, profile).to_dict()
-    _observe_flow_v2(decisions)
+    if flow_mode == "compare":
+        _observe_flow_v2(decisions)
     return decisions
 
 
-def _get_authoritative_opportunity_decisions(ids: list[str]) -> Dict[str, Dict[str, Any]]:
+def _get_authoritative_opportunity_decisions(ids: list[str], *, connection: Any = None) -> Dict[str, Dict[str, Any]]:
     """Read-only set-oriented adapter input loader; never derives or persists V2."""
-    with engine.connect() as conn:
+    from contextlib import nullcontext
+    with (nullcontext(connection) if connection is not None else engine.connect()) as conn:
         projections = _bulk_rows(conn, """
             SELECT opportunity_id::text, material_process_key,
                    canonical_opportunity_id::text, is_duplicate_representation,