V10.509 接入 Webcrumbs 同源資產代理與 writer preflight gate

services/market_intel/deployment_readiness.py

@@ -114,6 +114,9 @@ from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision impo
 from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_approval import (
     build_mcp_fetch_candidate_queue_writer_review_decision_approval_preview,
 )
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight import (
+    build_mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_preview,
+)
 from services.market_intel.mcp_manual_fetch_handoff import (
     build_mcp_manual_fetch_handoff_preview,
 )
@@ -303,6 +306,13 @@ PRODUCTION_SMOKE_TARGETS = (
     + ("/api/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval",)
     + PRODUCTION_SMOKE_TARGETS[-1:]
 )
+PRODUCTION_SMOKE_TARGETS = (
+    PRODUCTION_SMOKE_TARGETS[:-1]
+    + (
+        "/api/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight",
+    )
+    + PRODUCTION_SMOKE_TARGETS[-1:]
+)
 
 
 def _run_review_preview_safe(payload, mode):
@@ -411,6 +421,11 @@ def build_deployment_readiness_preview(*, service, market_intel_tables, schema_s
             phase=service.phase,
         )
     )
+    mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight = (
+        build_mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_preview(
+            phase=service.phase,
+        )
+    )
     scheduler_plan = service.build_scheduler_plan()
     manual_sample_plan = service.build_manual_sample_plan()
     manual_sample_acceptance = service.build_manual_sample_acceptance()
@@ -1507,6 +1522,10 @@ def build_deployment_readiness_preview(*, service, market_intel_tables, schema_s
                 "candidate_review_state_updated"
             ]
         ),
+        "mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_preview_safe": _run_review_preview_safe(
+            mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight,
+            "mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_preview",
+        ),
         "candidate_queue_writer_postwrite_smoke_planned_safe": bool(
             candidate_queue_writer_postwrite_smoke["mode"]
             == "candidate_queue_writer_postwrite_smoke_planned"
@@ -1837,6 +1856,7 @@ def build_deployment_readiness_preview(*, service, market_intel_tables, schema_s
         "mcp_fetch_candidate_queue_writer_review_inventory": mcp_fetch_candidate_queue_writer_review_inventory,
         "mcp_fetch_candidate_queue_writer_review_decision": mcp_fetch_candidate_queue_writer_review_decision,
         "mcp_fetch_candidate_queue_writer_review_decision_approval": mcp_fetch_candidate_queue_writer_review_decision_approval,
+        "mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight": mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight,
         "scheduler_plan": scheduler_plan,
         "manual_sample_plan": manual_sample_plan,
         "manual_sample_acceptance": manual_sample_acceptance,

services/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight.py

@@ -0,0 +1,575 @@
+"""市場情報 MCP review decision approval writer preflight。
+
+本模組只審核人工 approval 後的 writer preflight 摘要；
+API/UI 不讀 approval token、不執行 CLI、不開 DB、不寫 preflight record、
+不更新 review_state、不寫 decision/match、不補 queue、不掛 scheduler。
+"""
+
+from services.market_intel.mcp_fetch_candidate_queue_writer_preflight import TARGET_TABLE
+from services.market_intel.mcp_fetch_candidate_queue_writer_run_readiness import (
+    ARTIFACT_PREFIX,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_post_closeout_inventory_review import (
+    FORBIDDEN_SECRET_KEYS,
+    SAFE_SECRET_METADATA_KEYS,
+    _as_dict,
+    _as_list,
+    _blocked_side_effects,
+    _contains_forbidden_key,
+    _safe_int,
+    _safe_path,
+    _safe_text,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_approval import (
+    build_mcp_fetch_candidate_queue_writer_review_decision_approval_preview,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_gates import (
+    ALLOWED_PREFLIGHT_MODES,
+    ALLOWED_PREFLIGHT_SCOPES,
+    TARGET_OPERATION,
+    build_approval_writer_preflight_gates,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_sample import (
+    build_sample_writer_review_decision_approval_writer_preflight_package,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_gates import (
+    ALLOWED_REVIEW_DECISIONS,
+)
+
+
+_PREFLIGHT_BLOCKED_SIDE_EFFECT_KEYS = (
+    "allow_api_candidate_review_update",
+    "allow_api_execution",
+    "allow_api_file_write",
+    "allow_api_match_write",
+    "allow_api_queue_insert",
+    "allow_api_queue_write",
+    "allow_cli_execution",
+    "allow_database_write",
+    "api_candidate_review_update_executed",
+    "api_created_writer_preflight_file",
+    "api_executes_review_state_writer",
+    "api_review_state_update_executed",
+    "api_updates_review_state",
+    "api_write_allowed",
+    "api_writes_approval_record",
+    "api_writes_decision_record",
+    "api_writes_match_result",
+    "api_writes_preflight_record",
+    "candidate_queue_review_decision_approval_writer_preflight_file_written",
+    "candidate_queue_review_decision_approval_writer_preflight_persisted",
+    "decision_record_written",
+    "market_product_match_written",
+    "match_result_written",
+    "preflight_record_written",
+    "review_state_update_executed",
+    "writer_preflight_file_written",
+    "writer_preflight_persisted",
+)
+
+
+def _blocked_preflight_side_effects(payload):
+    found = list(_blocked_side_effects(payload))
+
+    def visit(value, path):
+        if isinstance(value, dict):
+            for key, item in value.items():
+                normalized_key = str(key).lower()
+                key_path = f"{path}.{key}" if path else key
+                if (
+                    normalized_key in _PREFLIGHT_BLOCKED_SIDE_EFFECT_KEYS
+                    and bool(item)
+                ):
+                    found.append(key_path)
+                visit(item, key_path)
+        elif isinstance(value, list):
+            for index, item in enumerate(value):
+                visit(item, f"{path}[{index}]")
+
+    visit(payload, "")
+    return sorted(set(found))
+
+
+def _approval_from_inputs(approval_package, approval_result, phase):
+    if isinstance(approval_result, dict) and approval_result:
+        return approval_result
+
+    approval_package = _as_dict(approval_package)
+    return build_mcp_fetch_candidate_queue_writer_review_decision_approval_preview(
+        writer_review_decision_package=(
+            approval_package.get("writer_review_decision_package")
+            or approval_package.get("candidate_queue_writer_review_decision")
+            or approval_package.get("writer_review_decision")
+            or approval_package.get("review_decision_package")
+            or approval_package.get("review_decision")
+            or {}
+        ),
+        writer_review_decision_result=(
+            approval_package.get("writer_review_decision_result")
+            or approval_package.get(
+                "mcp_fetch_candidate_queue_writer_review_decision"
+            )
+        ),
+        operator_review_decision_approval=(
+            approval_package.get("operator_review_decision_approval")
+            or approval_package.get("operator_review_approval")
+            or approval_package.get("candidate_queue_review_decision_approval")
+            or approval_package.get("writer_review_decision_approval")
+            or approval_package.get("approval_payload")
+            or approval_package.get("approval")
+        ),
+        phase=phase,
+    )
+
+
+def _approval_summary(approval_result):
+    approval_result = _as_dict(approval_result)
+    approval = _as_dict(
+        approval_result.get("operator_review_decision_approval_summary")
+        or approval_result.get("operator_review_approval_summary")
+    )
+    side_effects_clear = bool(
+        not approval_result.get("payload_persisted")
+        and not approval_result.get("review_decision_approval_persisted")
+        and not approval_result.get("candidate_queue_review_decision_approval_persisted")
+        and not approval_result.get("candidate_queue_review_decision_approval_file_written")
+        and not approval_result.get("approval_record_written")
+        and not approval_result.get("decision_record_written")
+        and not approval_result.get("match_result_written")
+        and not approval_result.get("api_executes_cli")
+        and not approval_result.get("api_reads_approval_token")
+        and not approval_result.get("api_opens_database_connection")
+        and not approval_result.get("api_writes_database")
+        and not approval_result.get("api_writes_file")
+        and not approval_result.get("api_updates_review_state")
+        and not approval_result.get("api_writes_approval_record")
+        and not approval_result.get("api_writes_decision_record")
+        and not approval_result.get("api_writes_match_result")
+        and not approval_result.get("database_write_executed")
+        and not approval_result.get("database_commit_executed")
+        and not approval_result.get("cli_executed")
+        and not approval_result.get("file_written")
+        and not approval_result.get("scheduler_attached")
+        and not approval_result.get("candidate_queue_persisted")
+        and not approval_result.get("candidate_review_state_updated")
+    )
+    return {
+        "mode": approval_result.get("mode"),
+        "accepted": bool(
+            approval_result.get(
+                "mcp_fetch_candidate_queue_writer_review_decision_approval_accepted"
+            )
+        ),
+        "ready_for_candidate_queue_review_decision_writer_preflight": bool(
+            approval_result.get(
+                "ready_for_candidate_queue_review_decision_writer_preflight"
+            )
+        ),
+        "approval_id": _safe_text(approval.get("approval_id"), 160),
+        "review_decision_id": _safe_text(approval.get("review_decision_id"), 160),
+        "review_inventory_id": _safe_text(approval.get("review_inventory_id"), 160),
+        "handoff_id": _safe_text(approval.get("handoff_id"), 160),
+        "inventory_review_id": _safe_text(approval.get("inventory_review_id"), 160),
+        "closeout_id": _safe_text(approval.get("closeout_id"), 160),
+        "run_package_id": _safe_text(approval.get("run_package_id"), 160),
+        "receipt_id": _safe_text(approval.get("receipt_id"), 160),
+        "target_table": _safe_text(approval.get("target_table"), 160),
+        "approved_row_count": _safe_int(
+            approval.get("approved_row_count") or approval.get("approval_row_count")
+        ),
+        "expected_dedupe_keys": [
+            _safe_text(item, 160)
+            for item in _as_list(approval.get("expected_dedupe_keys"))
+            if _safe_text(item, 160)
+        ],
+        "approval_rows": _as_list(
+            approval.get("approved_rows") or approval.get("approval_rows")
+        ),
+        "review_queue_artifact_path": _safe_text(
+            approval.get("review_queue_artifact_path")
+        ),
+        "review_inventory_artifact_path": _safe_text(
+            approval.get("review_inventory_artifact_path")
+        ),
+        "review_decision_artifact_path": _safe_text(
+            approval.get("review_decision_artifact_path")
+        ),
+        "approval_artifact_path": _safe_text(
+            approval.get("approval_artifact_path")
+            or approval.get("review_decision_approval_artifact_path")
+        ),
+        "side_effects_clear": side_effects_clear,
+        "blocked_reasons": approval_result.get("blocked_reasons", []),
+    }
+
+
+def _preflight_row_summary(row):
+    row = _as_dict(row)
+    decision_evidence_ref = _safe_text(row.get("decision_evidence_ref"))
+    approval_evidence_ref = _safe_text(row.get("approval_evidence_ref"))
+    preflight_evidence_ref = _safe_text(
+        row.get("preflight_evidence_ref") or row.get("evidence_ref")
+    )
+    return {
+        "dedupe_key": _safe_text(row.get("dedupe_key"), 160),
+        "current_review_state": _safe_text(row.get("current_review_state"), 80),
+        "approved_review_decision": _safe_text(
+            row.get("approved_review_decision"), 80
+        ),
+        "target_review_state": _safe_text(row.get("target_review_state"), 80),
+        "statement_type": _safe_text(row.get("statement_type"), 80),
+        "operation": _safe_text(row.get("operation"), 80),
+        "writer_action": _safe_text(row.get("writer_action"), 120),
+        "evidence_lane": _safe_text(row.get("evidence_lane"), 120),
+        "decision_evidence_ref": decision_evidence_ref,
+        "approval_evidence_ref": approval_evidence_ref,
+        "preflight_evidence_ref": preflight_evidence_ref,
+        "decision_evidence_ref_safe": _safe_path(
+            decision_evidence_ref,
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "approval_evidence_ref_safe": _safe_path(
+            approval_evidence_ref,
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "preflight_evidence_ref_safe": _safe_path(
+            preflight_evidence_ref,
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "preflight_notes_present": bool(_safe_text(row.get("preflight_notes"))),
+        "hard_veto_present": bool(row.get("hard_veto_present")),
+        "stronger_existing_match_conflict": bool(
+            row.get("stronger_existing_match_conflict")
+        ),
+        "false_positive_guard_passed": bool(row.get("false_positive_guard_passed")),
+        "variant_conflict_checked": bool(row.get("variant_conflict_checked")),
+        "overwrite_protection_checked": bool(row.get("overwrite_protection_checked")),
+        "exact_identity_confirmed": bool(row.get("exact_identity_confirmed")),
+    }
+
+
+def _operator_preflight_summary(operator_preflight):
+    operator_preflight = _as_dict(operator_preflight)
+    confirmations = _as_dict(operator_preflight.get("operator_confirmations"))
+    rows = [
+        _preflight_row_summary(row)
+        for row in _as_list(operator_preflight.get("preflight_rows"))
+    ]
+    expected_dedupe_keys = [
+        _safe_text(item, 160)
+        for item in _as_list(operator_preflight.get("expected_dedupe_keys"))
+        if _safe_text(item, 160)
+    ]
+    return {
+        "provided_keys": sorted(operator_preflight.keys()),
+        "writer_preflight_id": _safe_text(
+            operator_preflight.get("writer_preflight_id")
+            or operator_preflight.get("preflight_id"),
+            160,
+        ),
+        "approval_id": _safe_text(operator_preflight.get("approval_id"), 160),
+        "review_decision_id": _safe_text(
+            operator_preflight.get("review_decision_id"), 160
+        ),
+        "review_inventory_id": _safe_text(
+            operator_preflight.get("review_inventory_id"), 160
+        ),
+        "handoff_id": _safe_text(operator_preflight.get("handoff_id"), 160),
+        "inventory_review_id": _safe_text(
+            operator_preflight.get("inventory_review_id"), 160
+        ),
+        "closeout_id": _safe_text(operator_preflight.get("closeout_id"), 160),
+        "run_package_id": _safe_text(operator_preflight.get("run_package_id"), 160),
+        "receipt_id": _safe_text(operator_preflight.get("receipt_id"), 160),
+        "target_table": _safe_text(operator_preflight.get("target_table"), 160),
+        "target_operation": _safe_text(
+            operator_preflight.get("target_operation"), 160
+        ),
+        "preflight_scope": _safe_text(
+            operator_preflight.get("preflight_scope"), 160
+        ),
+        "preflight_mode": _safe_text(
+            operator_preflight.get("preflight_mode"), 160
+        ),
+        "expected_current_review_state": _safe_text(
+            operator_preflight.get("expected_current_review_state"), 80
+        ),
+        "preflight_row_count": _safe_int(
+            operator_preflight.get("preflight_row_count")
+        ),
+        "expected_preflight_row_count": _safe_int(
+            operator_preflight.get("expected_preflight_row_count")
+            or operator_preflight.get("preflight_row_count")
+        ),
+        "expected_dedupe_keys": expected_dedupe_keys,
+        "preflight_rows": rows,
+        "review_queue_artifact_path": _safe_text(
+            operator_preflight.get("review_queue_artifact_path")
+        ),
+        "review_inventory_artifact_path": _safe_text(
+            operator_preflight.get("review_inventory_artifact_path")
+        ),
+        "review_decision_artifact_path": _safe_text(
+            operator_preflight.get("review_decision_artifact_path")
+        ),
+        "approval_artifact_path": _safe_text(
+            operator_preflight.get("approval_artifact_path")
+            or operator_preflight.get("review_decision_approval_artifact_path")
+        ),
+        "writer_preflight_artifact_path": _safe_text(
+            operator_preflight.get("writer_preflight_artifact_path")
+            or operator_preflight.get("preflight_artifact_path")
+        ),
+        "review_queue_artifact_path_safe": _safe_path(
+            operator_preflight.get("review_queue_artifact_path"),
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "review_inventory_artifact_path_safe": _safe_path(
+            operator_preflight.get("review_inventory_artifact_path"),
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "review_decision_artifact_path_safe": _safe_path(
+            operator_preflight.get("review_decision_artifact_path"),
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "approval_artifact_path_safe": _safe_path(
+            operator_preflight.get("approval_artifact_path")
+            or operator_preflight.get("review_decision_approval_artifact_path"),
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "writer_preflight_artifact_path_safe": _safe_path(
+            operator_preflight.get("writer_preflight_artifact_path")
+            or operator_preflight.get("preflight_artifact_path"),
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "approval_checked": bool(confirmations.get("approval_checked")),
+        "writer_preflight_is_cli_only": bool(
+            confirmations.get("writer_preflight_is_cli_only")
+        ),
+        "manual_record_required": bool(confirmations.get("manual_record_required")),
+        "no_approval_token_payload": bool(
+            confirmations.get("no_approval_token_payload")
+        ),
+        "no_api_cli_execution": bool(confirmations.get("no_api_cli_execution")),
+        "no_api_database_write": bool(confirmations.get("no_api_database_write")),
+        "no_api_review_state_update": bool(
+            confirmations.get("no_api_review_state_update")
+        ),
+        "no_api_decision_record_write": bool(
+            confirmations.get("no_api_decision_record_write")
+        ),
+        "no_api_match_write": bool(confirmations.get("no_api_match_write")),
+        "no_api_queue_insert": bool(confirmations.get("no_api_queue_insert")),
+        "no_api_file_write": bool(confirmations.get("no_api_file_write")),
+        "no_scheduler_attach": bool(confirmations.get("no_scheduler_attach")),
+        "rows_match_approval": bool(confirmations.get("rows_match_approval")),
+        "schema_preflight_required": bool(
+            confirmations.get("schema_preflight_required")
+        ),
+        "status_transition_reviewed": bool(
+            confirmations.get("status_transition_reviewed")
+        ),
+        "stronger_existing_match_guard_preserved": bool(
+            confirmations.get("stronger_existing_match_guard_preserved")
+        ),
+        "false_positive_guard_completed": bool(
+            confirmations.get("false_positive_guard_completed")
+        ),
+        "variant_sensitive_review_completed": bool(
+            confirmations.get("variant_sensitive_review_completed")
+        ),
+        "hard_veto_respected": bool(confirmations.get("hard_veto_respected")),
+        "api_execution_allowed": bool(operator_preflight.get("api_execution_allowed")),
+        "real_write_allowed_by_api": bool(
+            operator_preflight.get("real_write_allowed_by_api")
+        ),
+        "api_candidate_review_allowed": bool(
+            operator_preflight.get("api_candidate_review_allowed")
+        ),
+        "api_updates_review_state": bool(
+            operator_preflight.get("api_updates_review_state")
+        ),
+        "api_writes_preflight_record": bool(
+            operator_preflight.get("api_writes_preflight_record")
+        ),
+        "api_writes_approval_record": bool(
+            operator_preflight.get("api_writes_approval_record")
+        ),
+        "api_writes_decision_record": bool(
+            operator_preflight.get("api_writes_decision_record")
+        ),
+        "api_writes_match_result": bool(
+            operator_preflight.get("api_writes_match_result")
+        ),
+        "secret_or_token_submitted_to_api": _contains_forbidden_key(
+            operator_preflight,
+            FORBIDDEN_SECRET_KEYS,
+            safe_keys=SAFE_SECRET_METADATA_KEYS,
+        ),
+        "blocked_side_effects": _blocked_preflight_side_effects(operator_preflight),
+    }
+
+
+def build_mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_preview(
+    *,
+    writer_review_decision_approval_package=None,
+    writer_review_decision_approval_result=None,
+    operator_review_decision_approval_writer_preflight=None,
+    operator_writer_preflight=None,
+    phase=None,
+):
+    """建立 approval writer preflight；不執行查詢、寫檔或寫入。"""
+    if operator_review_decision_approval_writer_preflight is None:
+        operator_review_decision_approval_writer_preflight = operator_writer_preflight
+    writer_review_decision_approval_package = _as_dict(
+        writer_review_decision_approval_package
+    )
+    approval_result_received = bool(
+        isinstance(writer_review_decision_approval_result, dict)
+        and writer_review_decision_approval_result
+    )
+    preflight_valid_object = (
+        isinstance(operator_review_decision_approval_writer_preflight, dict)
+        if operator_review_decision_approval_writer_preflight is not None
+        else True
+    )
+    preflight_payload = _as_dict(
+        operator_review_decision_approval_writer_preflight
+    )
+    approval_received = bool(
+        writer_review_decision_approval_package or approval_result_received
+    )
+    approval_result = (
+        _approval_from_inputs(
+            writer_review_decision_approval_package,
+            writer_review_decision_approval_result,
+            phase,
+        )
+        if approval_received
+        else {}
+    )
+    payload_received = bool(
+        approval_received
+        or preflight_payload
+        or operator_review_decision_approval_writer_preflight is not None
+    )
+    preflight_received = bool(preflight_payload)
+    approval = _approval_summary(approval_result)
+    preflight = _operator_preflight_summary(preflight_payload)
+    gates = build_approval_writer_preflight_gates(
+        approval_received=approval_received,
+        preflight_received=preflight_received and preflight_valid_object,
+        approval=approval,
+        preflight=preflight,
+    )
+    blocked_reasons = [gate["key"] for gate in gates if not gate["passed"]]
+    if not preflight_valid_object:
+        blocked_reasons.append(
+            "operator_review_decision_approval_writer_preflight_valid_object"
+        )
+    accepted = bool(payload_received and not blocked_reasons)
+
+    return {
+        "mode": (
+            "mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight"
+            if payload_received
+            else "mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_preview"
+        ),
+        "phase": phase,
+        "writer_review_decision_approval_writer_preflight_payload_received": (
+            payload_received
+        ),
+        "writer_review_decision_approval_received": approval_received,
+        "operator_writer_preflight_received": preflight_received,
+        "operator_writer_preflight_valid_object": preflight_valid_object,
+        "writer_review_decision_approval_accepted": approval["accepted"],
+        "mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_accepted": accepted,
+        "candidate_queue_writer_review_decision_approval_writer_preflight_ready": accepted,
+        "ready_for_candidate_queue_review_decision_writer_cli_review": accepted,
+        "ready_for_candidate_queue_review_state_writer": False,
+        "ready_for_api_review_state_update": False,
+        "ready_for_api_database_write": False,
+        "ready_for_api_decision_record_write": False,
+        "ready_for_api_match_write": False,
+        "ready_for_real_write": False,
+        "ready_for_scheduler_attach": False,
+        "network_request_allowed": False,
+        "api_executes_cli": False,
+        "api_reads_approval_token": False,
+        "api_opens_database_connection": False,
+        "api_writes_database": False,
+        "api_writes_file": False,
+        "api_uses_external_network": False,
+        "api_updates_review_state": False,
+        "api_writes_preflight_record": False,
+        "api_writes_approval_record": False,
+        "api_writes_decision_record": False,
+        "api_writes_match_result": False,
+        "payload_row_count": preflight["preflight_row_count"],
+        "gate_count": len(gates),
+        "passed_gate_count": sum(1 for gate in gates if gate["passed"]),
+        "blocked_reasons": blocked_reasons,
+        "gates": gates,
+        "writer_review_decision_approval_summary": approval,
+        "operator_writer_preflight_summary": preflight,
+        "preflight_rows": preflight["preflight_rows"],
+        "writer_preflight_contract": {
+            "target_table": TARGET_TABLE,
+            "target_operation": TARGET_OPERATION,
+            "expected_current_state": "needs_review",
+            "allowed_next_states": list(ALLOWED_REVIEW_DECISIONS),
+            "allowed_preflight_modes": list(ALLOWED_PREFLIGHT_MODES),
+            "allowed_preflight_scopes": list(ALLOWED_PREFLIGHT_SCOPES),
+            "manual_cli_writer_required": True,
+            "next_gate": "candidate_queue_review_decision_writer_cli_review",
+            "forbidden_api_actions": [
+                "update_review_state",
+                "write_preflight_record",
+                "write_approval_record",
+                "write_decision_record",
+                "write_match_result",
+                "insert_missing_queue_row",
+                "attach_scheduler",
+            ],
+        },
+        "sample_writer_review_decision_approval_writer_preflight_package": (
+            build_sample_writer_review_decision_approval_writer_preflight_package()
+        ),
+        "next_operator_steps": [
+            "Writer preflight 通過後，只代表可進入 CLI review / run package 設計",
+            "API/UI 仍不得自動寫 review_state、decision record、approval record 或 match result",
+            "正式寫入仍必須走 shell-only token、read-only preflight、receipt 與 post-write smoke",
+        ],
+        "payload_persisted": False,
+        "writer_preflight_persisted": False,
+        "candidate_queue_review_decision_approval_writer_preflight_persisted": False,
+        "candidate_queue_review_decision_approval_writer_preflight_file_written": False,
+        "preflight_record_written": False,
+        "preflight_record_file_written": False,
+        "approval_record_written": False,
+        "decision_record_written": False,
+        "match_result_written": False,
+        "market_product_match_written": False,
+        "package_artifact_created": False,
+        "database_connection_opened": False,
+        "database_session_created": False,
+        "database_commit_executed": False,
+        "database_write_executed": False,
+        "external_network_executed": False,
+        "cli_executed": False,
+        "file_written": False,
+        "writes_executed": False,
+        "would_write_database": False,
+        "scheduler_attached": False,
+        "candidate_queue_created": False,
+        "candidate_queue_persisted": False,
+        "candidate_review_state_updated": False,
+    }

services/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_gates.py

@@ -0,0 +1,272 @@
+"""Gate checks for review decision approval writer preflight."""
+
+from services.market_intel.mcp_fetch_candidate_queue_writer_preflight import TARGET_TABLE
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_gates import (
+    ALLOWED_REVIEW_DECISIONS,
+)
+
+ALLOWED_PREFLIGHT_MODES = ("cli_only_writer_preflight_preview",)
+ALLOWED_PREFLIGHT_SCOPES = (
+    "candidate_queue_review_decision_approval_writer_preflight",
+)
+TARGET_OPERATION = "update_review_state_from_approved_decision"
+
+
+def _row_keys_match_expected(preflight):
+    row_keys = [row["dedupe_key"] for row in preflight["preflight_rows"]]
+    expected_keys = preflight["expected_dedupe_keys"]
+    return bool(
+        row_keys
+        and len(row_keys) == len(set(row_keys))
+        and set(row_keys) == set(expected_keys)
+    )
+
+
+def _preflight_rows_match_approval(approval, preflight):
+    approval_rows = {
+        row["dedupe_key"]: row for row in approval["approval_rows"]
+    }
+    if not approval_rows or not preflight["preflight_rows"]:
+        return False
+    for row in preflight["preflight_rows"]:
+        source = approval_rows.get(row["dedupe_key"])
+        if not source:
+            return False
+        if row["current_review_state"] != source["current_review_state"]:
+            return False
+        if row["approved_review_decision"] != source["approved_review_decision"]:
+            return False
+        if row["target_review_state"] != source["approved_review_decision"]:
+            return False
+        if row["decision_evidence_ref"] != source["decision_evidence_ref"]:
+            return False
+        if row["approval_evidence_ref"] != source["approval_evidence_ref"]:
+            return False
+    return True
+
+
+def _all_rows_have_allowed_transitions(preflight):
+    return bool(
+        preflight["preflight_rows"]
+        and all(
+            row["current_review_state"] == "needs_review"
+            and row["approved_review_decision"] in ALLOWED_REVIEW_DECISIONS
+            and row["target_review_state"] in ALLOWED_REVIEW_DECISIONS
+            and row["approved_review_decision"] == row["target_review_state"]
+            and row["statement_type"] == "update_review_state"
+            and row["operation"] == "update"
+            for row in preflight["preflight_rows"]
+        )
+    )
+
+
+def _all_rows_have_preflight_evidence(preflight):
+    return bool(
+        preflight["preflight_rows"]
+        and all(
+            row["preflight_notes_present"]
+            and row["decision_evidence_ref_safe"]
+            and row["approval_evidence_ref_safe"]
+            and row["preflight_evidence_ref_safe"]
+            for row in preflight["preflight_rows"]
+        )
+    )
+
+
+def _matched_rows_keep_identity_guards(preflight):
+    matched_rows = [
+        row
+        for row in preflight["preflight_rows"]
+        if row["target_review_state"] == "matched"
+    ]
+    if not matched_rows:
+        return True
+    return all(
+        row["evidence_lane"] == "exact_identity"
+        and row["exact_identity_confirmed"]
+        and not row["hard_veto_present"]
+        and not row["stronger_existing_match_conflict"]
+        and row["false_positive_guard_passed"]
+        and row["variant_conflict_checked"]
+        and row["overwrite_protection_checked"]
+        for row in matched_rows
+    )
+
+
+def build_approval_writer_preflight_gates(
+    *, approval_received, preflight_received, approval, preflight
+):
+    operator_confirmed_boundaries = bool(
+        preflight["approval_checked"]
+        and preflight["writer_preflight_is_cli_only"]
+        and preflight["manual_record_required"]
+        and preflight["no_approval_token_payload"]
+        and preflight["no_api_cli_execution"]
+        and preflight["no_api_database_write"]
+        and preflight["no_api_review_state_update"]
+        and preflight["no_api_decision_record_write"]
+        and preflight["no_api_match_write"]
+        and preflight["no_api_queue_insert"]
+        and preflight["no_api_file_write"]
+        and preflight["no_scheduler_attach"]
+        and preflight["rows_match_approval"]
+        and preflight["schema_preflight_required"]
+        and preflight["status_transition_reviewed"]
+        and preflight["stronger_existing_match_guard_preserved"]
+        and preflight["false_positive_guard_completed"]
+        and preflight["variant_sensitive_review_completed"]
+        and preflight["hard_veto_respected"]
+    )
+    return [
+        {
+            "key": "candidate_queue_review_decision_approval_payload_or_result_received",
+            "label": "已提供 review decision approval package 或已審核結果",
+            "passed": approval_received,
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_accepted",
+            "label": "review decision approval gate 必須已通過",
+            "passed": approval["accepted"],
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_ready_for_preflight",
+            "label": "approval 必須只放行到 writer preflight",
+            "passed": approval["ready_for_candidate_queue_review_decision_writer_preflight"],
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_side_effect_free",
+            "label": "approval 未顯示 API 寫 DB、寫 approval、寫 decision、寫 match 或更新 review_state",
+            "passed": approval["side_effects_clear"],
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_payload_received",
+            "label": "已提供 operator writer preflight 摘要",
+            "passed": preflight_received,
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_identity_recorded",
+            "label": "writer preflight 必須記錄 preflight_id 與上游 identity",
+            "passed": bool(
+                preflight["writer_preflight_id"]
+                and preflight["approval_id"]
+                and preflight["review_decision_id"]
+                and preflight["review_inventory_id"]
+                and preflight["handoff_id"]
+                and preflight["inventory_review_id"]
+                and preflight["closeout_id"]
+                and preflight["run_package_id"]
+                and preflight["receipt_id"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_identity_matches_approval",
+            "label": "writer preflight identity 必須對齊 approval",
+            "passed": bool(
+                preflight["approval_id"] == approval["approval_id"]
+                and preflight["review_decision_id"] == approval["review_decision_id"]
+                and preflight["review_inventory_id"] == approval["review_inventory_id"]
+                and preflight["handoff_id"] == approval["handoff_id"]
+                and preflight["inventory_review_id"] == approval["inventory_review_id"]
+                and preflight["closeout_id"] == approval["closeout_id"]
+                and preflight["run_package_id"] == approval["run_package_id"]
+                and preflight["receipt_id"] == approval["receipt_id"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_target_table_safe",
+            "label": "target table 必須是 market_alert_review_queue",
+            "passed": preflight["target_table"] == TARGET_TABLE,
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_scope_safe",
+            "label": "writer preflight 僅能是 CLI-only preview",
+            "passed": bool(
+                preflight["preflight_scope"] in ALLOWED_PREFLIGHT_SCOPES
+                and preflight["preflight_mode"] in ALLOWED_PREFLIGHT_MODES
+                and preflight["target_operation"] == TARGET_OPERATION
+                and preflight["expected_current_review_state"] == "needs_review"
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_row_count_matches_approval",
+            "label": "writer preflight row count 必須對齊 approval row count",
+            "passed": bool(
+                preflight["expected_preflight_row_count"]
+                and preflight["preflight_row_count"]
+                == preflight["expected_preflight_row_count"]
+                == approval["approved_row_count"]
+                and len(preflight["preflight_rows"]) == approval["approved_row_count"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_rows_match_approval",
+            "label": "writer preflight rows 必須逐列對齊 approval rows",
+            "passed": bool(
+                _row_keys_match_expected(preflight)
+                and _preflight_rows_match_approval(approval, preflight)
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_transitions_allowed",
+            "label": "writer preflight 只能產生允許的 review_state update preview",
+            "passed": _all_rows_have_allowed_transitions(preflight),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_row_evidence_complete",
+            "label": "每列 writer preflight 必須保留 decision、approval 與 preflight evidence",
+            "passed": _all_rows_have_preflight_evidence(preflight),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_matched_rows_keep_identity_guards",
+            "label": "matched preflight rows 必須保留 exact identity、variant 與 overwrite guard",
+            "passed": _matched_rows_keep_identity_guards(preflight),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_artifact_paths_safe",
+            "label": "review queue、inventory、decision、approval 與 preflight artifact paths 必須安全並對齊",
+            "passed": bool(
+                preflight["review_queue_artifact_path_safe"]
+                and preflight["review_inventory_artifact_path_safe"]
+                and preflight["review_decision_artifact_path_safe"]
+                and preflight["approval_artifact_path_safe"]
+                and preflight["writer_preflight_artifact_path_safe"]
+                and preflight["review_queue_artifact_path"]
+                == approval["review_queue_artifact_path"]
+                and preflight["review_inventory_artifact_path"]
+                == approval["review_inventory_artifact_path"]
+                and preflight["review_decision_artifact_path"]
+                == approval["review_decision_artifact_path"]
+                and preflight["approval_artifact_path"]
+                == approval["approval_artifact_path"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_operator_boundaries_confirmed",
+            "label": "操作員確認 API 未執行 CLI/DB/file/review_state/decision/match/scheduler",
+            "passed": operator_confirmed_boundaries,
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_no_api_execution_or_real_write",
+            "label": "writer preflight payload 不得允許 API execution、real write、review update、decision write 或 match write",
+            "passed": bool(
+                not preflight["api_execution_allowed"]
+                and not preflight["real_write_allowed_by_api"]
+                and not preflight["api_candidate_review_allowed"]
+                and not preflight["api_updates_review_state"]
+                and not preflight["api_writes_preflight_record"]
+                and not preflight["api_writes_approval_record"]
+                and not preflight["api_writes_decision_record"]
+                and not preflight["api_writes_match_result"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_no_secret_or_token_key",
+            "label": "writer preflight payload 不得包含 secret、cookie、password 或 token key",
+            "passed": not preflight["secret_or_token_submitted_to_api"],
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_writer_preflight_side_effect_free",
+            "label": "writer preflight payload 不得要求 API 寫檔、執行、寫 DB、補 queue、寫 match 或掛 scheduler",
+            "passed": not preflight["blocked_side_effects"],
+        },
+    ]

services/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_sample.py

@@ -0,0 +1,149 @@
+"""Sample payload for the review decision approval writer preflight gate."""
+
+from copy import deepcopy
+
+from services.market_intel.mcp_fetch_candidate_queue_writer_preflight import TARGET_TABLE
+from services.market_intel.mcp_fetch_candidate_queue_writer_run_readiness import (
+    ARTIFACT_PREFIX,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_approval import (
+    build_mcp_fetch_candidate_queue_writer_review_decision_approval_preview,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight_gates import (
+    TARGET_OPERATION,
+)
+
+
+_SAMPLE_APPROVAL_WRITER_PREFLIGHT_PACKAGE = None
+
+
+def build_sample_writer_review_decision_approval_writer_preflight_package():
+    global _SAMPLE_APPROVAL_WRITER_PREFLIGHT_PACKAGE
+    if _SAMPLE_APPROVAL_WRITER_PREFLIGHT_PACKAGE is not None:
+        return deepcopy(_SAMPLE_APPROVAL_WRITER_PREFLIGHT_PACKAGE)
+
+    approval_preview = (
+        build_mcp_fetch_candidate_queue_writer_review_decision_approval_preview()
+    )
+    approval_package = approval_preview["sample_writer_review_decision_approval_package"]
+    approval_result = (
+        build_mcp_fetch_candidate_queue_writer_review_decision_approval_preview(
+            writer_review_decision_package=approval_package[
+                "writer_review_decision_package"
+            ],
+            writer_review_decision_result=approval_package[
+                "writer_review_decision_result"
+            ],
+            operator_review_decision_approval=approval_package[
+                "operator_review_decision_approval"
+            ],
+        )
+    )
+    approval = approval_result["operator_review_decision_approval_summary"]
+    preflight_rows = []
+    for row in approval["approved_rows"]:
+        preflight_rows.append(
+            {
+                "dedupe_key": row["dedupe_key"],
+                "current_review_state": row["current_review_state"],
+                "approved_review_decision": row["approved_review_decision"],
+                "target_review_state": row["approved_review_decision"],
+                "statement_type": "update_review_state",
+                "operation": "update",
+                "writer_action": "prepare_cli_review_state_update",
+                "evidence_lane": row["evidence_lane"],
+                "decision_evidence_ref": row["decision_evidence_ref"],
+                "approval_evidence_ref": row["approval_evidence_ref"],
+                "preflight_evidence_ref": (
+                    ARTIFACT_PREFIX
+                    + "candidate-queue-review-decision-approval-writer-preflight-"
+                    + f"{row['dedupe_key']}.json"
+                ),
+                "preflight_notes": (
+                    "approved review decision mapped to CLI-only writer preflight"
+                ),
+                "hard_veto_present": row["hard_veto_present"],
+                "stronger_existing_match_conflict": row[
+                    "stronger_existing_match_conflict"
+                ],
+                "false_positive_guard_passed": row["false_positive_guard_passed"],
+                "variant_conflict_checked": row["variant_conflict_checked"],
+                "overwrite_protection_checked": row[
+                    "overwrite_protection_checked"
+                ],
+                "exact_identity_confirmed": row["exact_identity_confirmed"],
+            }
+        )
+
+    operator_writer_preflight = {
+        "writer_preflight_id": (
+            "market-intel-candidate-writer-review-decision-approval-preflight-sample"
+        ),
+        "approval_id": approval["approval_id"],
+        "review_decision_id": approval["review_decision_id"],
+        "review_inventory_id": approval["review_inventory_id"],
+        "handoff_id": approval["handoff_id"],
+        "inventory_review_id": approval["inventory_review_id"],
+        "closeout_id": approval["closeout_id"],
+        "run_package_id": approval["run_package_id"],
+        "receipt_id": approval["receipt_id"],
+        "target_table": TARGET_TABLE,
+        "target_operation": TARGET_OPERATION,
+        "preflight_scope": (
+            "candidate_queue_review_decision_approval_writer_preflight"
+        ),
+        "preflight_mode": "cli_only_writer_preflight_preview",
+        "expected_current_review_state": "needs_review",
+        "preflight_row_count": len(preflight_rows),
+        "expected_preflight_row_count": approval["approved_row_count"],
+        "expected_dedupe_keys": approval["expected_dedupe_keys"],
+        "review_queue_artifact_path": approval["review_queue_artifact_path"],
+        "review_inventory_artifact_path": approval[
+            "review_inventory_artifact_path"
+        ],
+        "review_decision_artifact_path": approval["review_decision_artifact_path"],
+        "approval_artifact_path": approval["approval_artifact_path"],
+        "writer_preflight_artifact_path": (
+            ARTIFACT_PREFIX
+            + "candidate-queue-review-decision-approval-writer-preflight-sample.json"
+        ),
+        "preflight_rows": preflight_rows,
+        "operator_confirmations": {
+            "approval_checked": True,
+            "writer_preflight_is_cli_only": True,
+            "manual_record_required": True,
+            "no_approval_token_payload": True,
+            "no_api_cli_execution": True,
+            "no_api_database_write": True,
+            "no_api_review_state_update": True,
+            "no_api_decision_record_write": True,
+            "no_api_match_write": True,
+            "no_api_queue_insert": True,
+            "no_api_file_write": True,
+            "no_scheduler_attach": True,
+            "rows_match_approval": True,
+            "schema_preflight_required": True,
+            "status_transition_reviewed": True,
+            "stronger_existing_match_guard_preserved": True,
+            "false_positive_guard_completed": True,
+            "variant_sensitive_review_completed": True,
+            "hard_veto_respected": True,
+        },
+        "api_execution_allowed": False,
+        "real_write_allowed_by_api": False,
+        "api_candidate_review_allowed": False,
+        "api_updates_review_state": False,
+        "api_writes_preflight_record": False,
+        "api_writes_approval_record": False,
+        "api_writes_decision_record": False,
+        "api_writes_match_result": False,
+    }
+    _SAMPLE_APPROVAL_WRITER_PREFLIGHT_PACKAGE = {
+        "writer_review_decision_approval_package": approval_package,
+        "writer_review_decision_approval_result": approval_result,
+        "operator_writer_preflight": operator_writer_preflight,
+        "operator_review_decision_approval_writer_preflight": (
+            operator_writer_preflight
+        ),
+    }
+    return deepcopy(_SAMPLE_APPROVAL_WRITER_PREFLIGHT_PACKAGE)

services/market_intel/phase.py

@@ -1,3 +1,3 @@
 """市場情報 rollout phase 單一來源。"""
 
-MARKET_INTEL_PHASE = "phase_138_market_intel_mcp_fetch_candidate_queue_writer_review_decision_approval"
+MARKET_INTEL_PHASE = "phase_139_market_intel_mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight"