V10.507 接入 Webcrumbs 並收斂 writer approval gate

services/market_intel/deployment_readiness.py

@@ -111,6 +111,9 @@ from services.market_intel.mcp_fetch_candidate_queue_writer_review_inventory imp
 from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision import (
     build_mcp_fetch_candidate_queue_writer_review_decision_preview,
 )
+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_manual_fetch_handoff import (
     build_mcp_manual_fetch_handoff_preview,
 )
@@ -295,6 +298,11 @@ PRODUCTION_SMOKE_TARGETS = (
     + ("/api/market_intel/mcp_fetch_candidate_queue_writer_review_decision",)
     + PRODUCTION_SMOKE_TARGETS[-1:]
 )
+PRODUCTION_SMOKE_TARGETS = (
+    PRODUCTION_SMOKE_TARGETS[:-1]
+    + ("/api/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval",)
+    + PRODUCTION_SMOKE_TARGETS[-1:]
+)
 
 
 def _run_review_preview_safe(payload, mode):
@@ -398,6 +406,11 @@ def build_deployment_readiness_preview(*, service, market_intel_tables, schema_s
             phase=service.phase,
         )
     )
+    mcp_fetch_candidate_queue_writer_review_decision_approval = (
+        build_mcp_fetch_candidate_queue_writer_review_decision_approval_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()
@@ -1412,6 +1425,88 @@ def build_deployment_readiness_preview(*, service, market_intel_tables, schema_s
                 "candidate_review_state_updated"
             ]
         ),
+        "mcp_fetch_candidate_queue_writer_review_decision_approval_preview_safe": bool(
+            mcp_fetch_candidate_queue_writer_review_decision_approval["mode"]
+            == "mcp_fetch_candidate_queue_writer_review_decision_approval_preview"
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "payload_persisted"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "review_decision_approval_persisted"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "candidate_queue_review_decision_approval_persisted"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "candidate_queue_review_decision_approval_file_written"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "approval_record_written"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "approval_record_file_written"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "decision_record_written"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "match_result_written"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "package_artifact_created"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "api_writes_file"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "api_executes_cli"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "api_reads_approval_token"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "api_opens_database_connection"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "api_writes_database"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "api_updates_review_state"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "api_writes_approval_record"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "api_writes_decision_record"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "api_writes_match_result"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "database_write_executed"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "database_commit_executed"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "database_connection_opened"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "cli_executed"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "file_written"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "scheduler_attached"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "candidate_queue_persisted"
+            ]
+            and not mcp_fetch_candidate_queue_writer_review_decision_approval[
+                "candidate_review_state_updated"
+            ]
+        ),
         "candidate_queue_writer_postwrite_smoke_planned_safe": bool(
             candidate_queue_writer_postwrite_smoke["mode"]
             == "candidate_queue_writer_postwrite_smoke_planned"
@@ -1741,6 +1836,7 @@ def build_deployment_readiness_preview(*, service, market_intel_tables, schema_s
         "mcp_fetch_candidate_queue_writer_review_handoff": mcp_fetch_candidate_queue_writer_review_handoff,
         "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,
         "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.py

@@ -0,0 +1,560 @@
+"""市場情報 MCP fetch candidate queue writer review decision approval。
+
+本模組只審核 review decision 後的人工 approval 摘要；
+API/UI 不讀 approval token、不執行 CLI、不開 DB、不寫 decision record、
+不更新 review_state、不寫 match result、不補 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 import (
+    build_mcp_fetch_candidate_queue_writer_review_decision_preview,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_gates import (
+    ALLOWED_REVIEW_DECISIONS,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_approval_gates import (
+    ALLOWED_APPROVAL_RESULTS,
+    build_review_decision_approval_gates,
+)
+from services.market_intel.mcp_fetch_candidate_queue_writer_review_decision_approval_sample import (
+    build_sample_writer_review_decision_approval_package,
+)
+
+
+_APPROVAL_BLOCKED_SIDE_EFFECT_KEYS = (
+    "allow_api_candidate_review_update",
+    "allow_api_decision_record_write",
+    "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_review_decision_file",
+    "api_review_decision_persisted",
+    "api_review_state_update_executed",
+    "api_write_allowed",
+    "api_updates_review_state",
+    "api_writes_approval_record",
+    "api_writes_decision_record",
+    "api_writes_match_result",
+    "candidate_queue_review_decision_approval_file_written",
+    "candidate_queue_review_decision_approval_persisted",
+    "decision_approval_file_written",
+    "decision_approval_persisted",
+    "decision_record_written",
+    "market_product_match_written",
+    "match_result_written",
+    "review_state_update_executed",
+)
+
+
+def _blocked_approval_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 _APPROVAL_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 _decision_from_inputs(decision_package, decision_result, phase):
+    if isinstance(decision_result, dict) and decision_result:
+        return decision_result
+
+    decision_package = _as_dict(decision_package)
+    return build_mcp_fetch_candidate_queue_writer_review_decision_preview(
+        writer_review_inventory_package=(
+            decision_package.get("writer_review_inventory_package")
+            or decision_package.get("candidate_queue_writer_review_inventory")
+            or decision_package.get("writer_review_inventory")
+            or decision_package.get("review_inventory_package")
+            or {}
+        ),
+        writer_review_inventory_result=(
+            decision_package.get("writer_review_inventory_result")
+            or decision_package.get(
+                "mcp_fetch_candidate_queue_writer_review_inventory"
+            )
+        ),
+        operator_review_decision=(
+            decision_package.get("operator_review_decision")
+            or decision_package.get("candidate_queue_review_decision")
+            or decision_package.get("writer_review_decision")
+            or decision_package.get("review_decision_payload")
+            or decision_package.get("decision_payload")
+            or decision_package.get("decision")
+        ),
+        phase=phase,
+    )
+
+
+def _decision_summary(decision_result):
+    decision_result = _as_dict(decision_result)
+    decision = _as_dict(decision_result.get("operator_review_decision_summary"))
+    side_effects_clear = bool(
+        not decision_result.get("payload_persisted")
+        and not decision_result.get("review_decision_persisted")
+        and not decision_result.get("candidate_queue_review_decision_persisted")
+        and not decision_result.get("candidate_queue_review_decision_file_written")
+        and not decision_result.get("decision_record_written")
+        and not decision_result.get("decision_record_file_written")
+        and not decision_result.get("api_executes_cli")
+        and not decision_result.get("api_reads_approval_token")
+        and not decision_result.get("api_opens_database_connection")
+        and not decision_result.get("api_writes_database")
+        and not decision_result.get("api_writes_file")
+        and not decision_result.get("api_updates_review_state")
+        and not decision_result.get("api_writes_decision_record")
+        and not decision_result.get("api_writes_match_result")
+        and not decision_result.get("database_write_executed")
+        and not decision_result.get("database_commit_executed")
+        and not decision_result.get("cli_executed")
+        and not decision_result.get("file_written")
+        and not decision_result.get("scheduler_attached")
+        and not decision_result.get("candidate_queue_persisted")
+        and not decision_result.get("candidate_review_state_updated")
+    )
+    return {
+        "mode": decision_result.get("mode"),
+        "accepted": bool(
+            decision_result.get(
+                "mcp_fetch_candidate_queue_writer_review_decision_accepted"
+            )
+        ),
+        "ready_for_candidate_queue_review_decision_approval": bool(
+            decision_result.get("ready_for_candidate_queue_review_decision_approval")
+        ),
+        "review_decision_id": _safe_text(
+            decision.get("review_decision_id"), 160
+        ),
+        "review_inventory_id": _safe_text(decision.get("review_inventory_id"), 160),
+        "handoff_id": _safe_text(decision.get("handoff_id"), 160),
+        "inventory_review_id": _safe_text(decision.get("inventory_review_id"), 160),
+        "closeout_id": _safe_text(decision.get("closeout_id"), 160),
+        "run_package_id": _safe_text(decision.get("run_package_id"), 160),
+        "receipt_id": _safe_text(decision.get("receipt_id"), 160),
+        "target_table": _safe_text(decision.get("target_table"), 160),
+        "decision_scope": _safe_text(decision.get("decision_scope"), 120),
+        "decision_mode": _safe_text(decision.get("decision_mode"), 120),
+        "decision_row_count": _safe_int(decision.get("decision_row_count")),
+        "expected_dedupe_keys": [
+            _safe_text(item, 160)
+            for item in _as_list(decision.get("expected_dedupe_keys"))
+            if _safe_text(item, 160)
+        ],
+        "decision_rows": _as_list(decision.get("decision_rows")),
+        "review_queue_artifact_path": _safe_text(
+            decision.get("review_queue_artifact_path")
+        ),
+        "review_inventory_artifact_path": _safe_text(
+            decision.get("review_inventory_artifact_path")
+        ),
+        "review_decision_artifact_path": _safe_text(
+            decision.get("review_decision_artifact_path")
+        ),
+        "side_effects_clear": side_effects_clear,
+        "blocked_reasons": decision_result.get("blocked_reasons", []),
+    }
+
+
+def _approval_row_summary(row):
+    row = _as_dict(row)
+    original_proposed_review_decision = _safe_text(
+        row.get("proposed_review_decision"),
+        80,
+    )
+    approved_review_decision = _safe_text(
+        row.get("approved_review_decision") or original_proposed_review_decision,
+        80,
+    )
+    proposed_review_decision = approved_review_decision
+    decision_evidence_ref = _safe_text(
+        row.get("decision_evidence_ref") or row.get("evidence_ref")
+    )
+    approval_evidence_ref = _safe_text(
+        row.get("approval_evidence_ref")
+        or row.get("approval_evidence_path")
+        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),
+        "approval_result": _safe_text(row.get("approval_result"), 80),
+        "original_proposed_review_decision": original_proposed_review_decision,
+        "proposed_review_decision": proposed_review_decision,
+        "approved_review_decision": approved_review_decision,
+        "approval_bucket": _safe_text(row.get("approval_bucket"), 120),
+        "evidence_lane": _safe_text(row.get("evidence_lane"), 120),
+        "evidence_ref": decision_evidence_ref,
+        "decision_evidence_ref": decision_evidence_ref,
+        "approval_evidence_ref": approval_evidence_ref,
+        "evidence_ref_safe": _safe_path(
+            decision_evidence_ref,
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "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",),
+        ),
+        "approval_notes_present": bool(_safe_text(row.get("approval_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_approval_summary(operator_approval):
+    operator_approval = _as_dict(operator_approval)
+    confirmations = _as_dict(operator_approval.get("operator_confirmations"))
+    rows = [
+        _approval_row_summary(row)
+        for row in _as_list(
+            operator_approval.get("approved_rows")
+            or operator_approval.get("approval_rows")
+        )
+    ]
+    expected_dedupe_keys = [
+        _safe_text(item, 160)
+        for item in _as_list(operator_approval.get("expected_dedupe_keys"))
+        if _safe_text(item, 160)
+    ]
+    return {
+        "provided_keys": sorted(operator_approval.keys()),
+        "approval_id": _safe_text(
+            operator_approval.get("approval_id")
+            or operator_approval.get("review_decision_approval_id"),
+            160,
+        ),
+        "review_decision_id": _safe_text(
+            operator_approval.get("review_decision_id"), 160
+        ),
+        "review_inventory_id": _safe_text(
+            operator_approval.get("review_inventory_id"), 160
+        ),
+        "handoff_id": _safe_text(operator_approval.get("handoff_id"), 160),
+        "inventory_review_id": _safe_text(
+            operator_approval.get("inventory_review_id"), 160
+        ),
+        "closeout_id": _safe_text(operator_approval.get("closeout_id"), 160),
+        "run_package_id": _safe_text(operator_approval.get("run_package_id"), 160),
+        "receipt_id": _safe_text(operator_approval.get("receipt_id"), 160),
+        "target_table": _safe_text(operator_approval.get("target_table"), 160),
+        "approval_scope": _safe_text(operator_approval.get("approval_scope"), 120),
+        "approval_mode": _safe_text(operator_approval.get("approval_mode"), 120),
+        "expected_decision_scope": _safe_text(
+            operator_approval.get("expected_decision_scope"), 120
+        ),
+        "expected_current_review_state": _safe_text(
+            operator_approval.get("expected_current_review_state"), 80
+        ),
+        "approval_row_count": _safe_int(
+            operator_approval.get("approval_row_count")
+            or operator_approval.get("approved_row_count")
+        ),
+        "approved_row_count": _safe_int(
+            operator_approval.get("approved_row_count")
+            or operator_approval.get("approval_row_count")
+        ),
+        "expected_approved_row_count": _safe_int(
+            operator_approval.get("expected_approved_row_count")
+            or operator_approval.get("expected_approval_row_count")
+            or operator_approval.get("approved_row_count")
+            or operator_approval.get("approval_row_count")
+        ),
+        "expected_dedupe_keys": expected_dedupe_keys,
+        "approval_rows": rows,
+        "approved_rows": rows,
+        "review_queue_artifact_path": _safe_text(
+            operator_approval.get("review_queue_artifact_path")
+        ),
+        "review_inventory_artifact_path": _safe_text(
+            operator_approval.get("review_inventory_artifact_path")
+        ),
+        "review_decision_artifact_path": _safe_text(
+            operator_approval.get("review_decision_artifact_path")
+        ),
+        "approval_artifact_path": _safe_text(
+            operator_approval.get("approval_artifact_path")
+            or operator_approval.get("review_decision_approval_artifact_path")
+        ),
+        "review_decision_approval_artifact_path": _safe_text(
+            operator_approval.get("review_decision_approval_artifact_path")
+            or operator_approval.get("approval_artifact_path")
+        ),
+        "review_queue_artifact_path_safe": _safe_path(
+            operator_approval.get("review_queue_artifact_path"),
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "review_inventory_artifact_path_safe": _safe_path(
+            operator_approval.get("review_inventory_artifact_path"),
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "review_decision_artifact_path_safe": _safe_path(
+            operator_approval.get("review_decision_artifact_path"),
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "approval_artifact_path_safe": _safe_path(
+            operator_approval.get("approval_artifact_path")
+            or operator_approval.get("review_decision_approval_artifact_path"),
+            prefixes=(ARTIFACT_PREFIX,),
+            suffixes=(".json",),
+        ),
+        "review_decision_checked": bool(confirmations.get("review_decision_checked")),
+        "approval_is_human_only": bool(
+            confirmations.get("approval_is_human_only")
+            or confirmations.get("human_approval_only")
+        ),
+        "manual_record_required": bool(
+            confirmations.get("manual_record_required")
+            or confirmations.get("approval_record_manual_only")
+        ),
+        "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")),
+        "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")),
+        "decision_rows_match_review_decision": bool(
+            confirmations.get("decision_rows_match_review_decision")
+        ),
+        "api_execution_allowed": bool(operator_approval.get("api_execution_allowed")),
+        "real_write_allowed_by_api": bool(
+            operator_approval.get("real_write_allowed_by_api")
+        ),
+        "api_candidate_review_allowed": bool(
+            operator_approval.get("api_candidate_review_allowed")
+        ),
+        "api_updates_review_state": bool(
+            operator_approval.get("api_updates_review_state")
+        ),
+        "api_writes_approval_record": bool(
+            operator_approval.get("api_writes_approval_record")
+        ),
+        "api_writes_decision_record": bool(
+            operator_approval.get("api_writes_decision_record")
+        ),
+        "api_writes_match_result": bool(
+            operator_approval.get("api_writes_match_result")
+        ),
+        "secret_or_token_submitted_to_api": _contains_forbidden_key(
+            operator_approval,
+            FORBIDDEN_SECRET_KEYS,
+            safe_keys=SAFE_SECRET_METADATA_KEYS,
+        ),
+        "blocked_side_effects": _blocked_approval_side_effects(operator_approval),
+    }
+
+
+def build_mcp_fetch_candidate_queue_writer_review_decision_approval_preview(
+    *,
+    writer_review_decision_package=None,
+    writer_review_decision_result=None,
+    operator_review_decision_approval=None,
+    operator_review_approval=None,
+    phase=None,
+):
+    """建立 writer review decision approval；不執行查詢、寫檔或寫入。"""
+    if operator_review_decision_approval is None:
+        operator_review_decision_approval = operator_review_approval
+    writer_review_decision_package = _as_dict(writer_review_decision_package)
+    decision_result_received = bool(
+        isinstance(writer_review_decision_result, dict)
+        and writer_review_decision_result
+    )
+    approval_valid_object = (
+        isinstance(operator_review_decision_approval, dict)
+        if operator_review_decision_approval is not None
+        else True
+    )
+    approval_payload = _as_dict(operator_review_decision_approval)
+    decision_received = bool(
+        writer_review_decision_package or decision_result_received
+    )
+    decision_result = (
+        _decision_from_inputs(
+            writer_review_decision_package,
+            writer_review_decision_result,
+            phase,
+        )
+        if decision_received
+        else {}
+    )
+    payload_received = bool(
+        decision_received
+        or approval_payload
+        or operator_review_decision_approval is not None
+    )
+    approval_received = bool(approval_payload)
+    decision = _decision_summary(decision_result)
+    approval = _operator_approval_summary(approval_payload)
+    gates = build_review_decision_approval_gates(
+        decision_received=decision_received,
+        approval_received=approval_received and approval_valid_object,
+        decision=decision,
+        approval=approval,
+    )
+    blocked_reasons = [gate["key"] for gate in gates if not gate["passed"]]
+    if not approval_valid_object:
+        blocked_reasons.append("operator_review_decision_approval_payload_valid_object")
+    accepted = bool(payload_received and not blocked_reasons)
+
+    return {
+        "mode": (
+            "mcp_fetch_candidate_queue_writer_review_decision_approval"
+            if payload_received
+            else "mcp_fetch_candidate_queue_writer_review_decision_approval_preview"
+        ),
+        "phase": phase,
+        "writer_review_decision_approval_payload_received": payload_received,
+        "approval_payload_received": payload_received,
+        "writer_review_decision_received": decision_received,
+        "operator_review_decision_approval_received": approval_received,
+        "operator_review_decision_approval_valid_object": approval_valid_object,
+        "operator_review_approval_received": approval_received,
+        "operator_review_approval_valid_object": approval_valid_object,
+        "writer_review_decision_accepted": decision["accepted"],
+        "mcp_fetch_candidate_queue_writer_review_decision_approval_accepted": accepted,
+        "candidate_queue_writer_review_decision_approval_ready": accepted,
+        "ready_for_candidate_queue_review_decision_writer_preflight": accepted,
+        "ready_for_candidate_queue_review_decision_approval": False,
+        "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_approval_record": False,
+        "api_writes_decision_record": False,
+        "api_writes_match_result": False,
+        "payload_row_count": approval["approval_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_summary": decision,
+        "operator_review_decision_approval_summary": approval,
+        "operator_review_approval_summary": approval,
+        "approval_rows": approval["approval_rows"],
+        "approved_rows": approval["approved_rows"],
+        "approval_contract": {
+            "expected_current_state": "needs_review",
+            "allowed_next_states": list(ALLOWED_REVIEW_DECISIONS),
+            "allowed_approval_results": list(ALLOWED_APPROVAL_RESULTS),
+            "manual_approval_required": True,
+            "next_gate": "candidate_queue_review_decision_writer_preflight",
+            "approval_scope": "candidate_queue_review_decision_approval",
+            "forbidden_api_actions": [
+                "update_review_state",
+                "write_decision_record",
+                "write_match_result",
+                "insert_missing_queue_row",
+                "attach_scheduler",
+            ],
+        },
+        "sample_writer_review_decision_approval_package": (
+            build_sample_writer_review_decision_approval_package()
+        ),
+        "next_operator_steps": [
+            "Approval 通過後，只代表可進入 CLI-only writer preflight 設計",
+            "API/UI 仍不得自動寫 review_state、decision record 或 match result",
+            "matched approval 必須保留 exact identity、variant、false-positive 與 overwrite guard",
+        ],
+        "payload_persisted": False,
+        "review_decision_approval_persisted": False,
+        "candidate_queue_review_decision_approval_persisted": False,
+        "candidate_queue_review_decision_approval_file_written": False,
+        "approval_record_written": False,
+        "approval_record_file_written": False,
+        "decision_approval_file_written": False,
+        "decision_record_written": False,
+        "decision_record_file_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_gates.py

@@ -0,0 +1,257 @@
+"""Gate checks for market intel review decision approval."""
+
+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_APPROVAL_RESULTS = ("approved_for_writer_preflight",)
+
+
+def _row_keys_match_expected(approval):
+    row_keys = [row["dedupe_key"] for row in approval["approval_rows"]]
+    expected_keys = approval["expected_dedupe_keys"]
+    return bool(
+        row_keys
+        and len(row_keys) == len(set(row_keys))
+        and set(row_keys) == set(expected_keys)
+    )
+
+
+def _approval_rows_match_decision(decision, approval):
+    decision_rows = {
+        row["dedupe_key"]: row for row in decision["decision_rows"]
+    }
+    if not decision_rows or not approval["approval_rows"]:
+        return False
+    for row in approval["approval_rows"]:
+        source = decision_rows.get(row["dedupe_key"])
+        if not source:
+            return False
+        if row["current_review_state"] != source["current_review_state"]:
+            return False
+        if row["proposed_review_decision"] != source["proposed_review_decision"]:
+            return False
+        if row["approved_review_decision"] != source["proposed_review_decision"]:
+            return False
+        if row["decision_evidence_ref"] != source["evidence_ref"]:
+            return False
+    return True
+
+
+def _all_rows_have_allowed_decisions(approval):
+    return bool(
+        approval["approval_rows"]
+        and all(
+            row["proposed_review_decision"] in ALLOWED_REVIEW_DECISIONS
+            and row["approved_review_decision"] in ALLOWED_REVIEW_DECISIONS
+            and row["approval_result"] in ALLOWED_APPROVAL_RESULTS
+            for row in approval["approval_rows"]
+        )
+    )
+
+
+def _all_rows_have_approval_evidence(approval):
+    return bool(
+        approval["approval_rows"]
+        and all(
+            row["approval_notes_present"]
+            and row["decision_evidence_ref_safe"]
+            and row["approval_evidence_ref_safe"]
+            for row in approval["approval_rows"]
+        )
+    )
+
+
+def _matched_rows_keep_identity_guards(approval):
+    matched_rows = [
+        row
+        for row in approval["approval_rows"]
+        if row["approved_review_decision"] == "matched"
+        or row.get("proposed_review_decision") == "matched"
+        or row.get("original_proposed_review_decision") == "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_review_decision_approval_gates(
+    *, decision_received, approval_received, decision, approval
+):
+    operator_confirmed_boundaries = bool(
+        approval["review_decision_checked"]
+        and approval["approval_is_human_only"]
+        and approval["manual_record_required"]
+        and approval["no_approval_token_payload"]
+        and approval["no_api_cli_execution"]
+        and approval["no_api_database_write"]
+        and approval["no_api_review_state_update"]
+        and approval["no_api_decision_record_write"]
+        and approval["no_api_match_write"]
+        and approval["no_api_queue_insert"]
+        and approval["no_api_file_write"]
+        and approval["no_scheduler_attach"]
+        and approval["stronger_existing_match_guard_preserved"]
+        and approval["false_positive_guard_completed"]
+        and approval["variant_sensitive_review_completed"]
+        and approval["hard_veto_respected"]
+        and approval["decision_rows_match_review_decision"]
+    )
+    return [
+        {
+            "key": "candidate_queue_review_decision_payload_or_result_received",
+            "label": "已提供 review decision package 或已審核結果",
+            "passed": decision_received,
+        },
+        {
+            "key": "candidate_queue_review_decision_accepted",
+            "label": "review decision gate 必須已通過",
+            "passed": decision["accepted"],
+        },
+        {
+            "key": "candidate_queue_review_decision_ready_for_approval",
+            "label": "decision 必須只放行到 approval gate",
+            "passed": decision["ready_for_candidate_queue_review_decision_approval"],
+        },
+        {
+            "key": "candidate_queue_review_decision_side_effect_free",
+            "label": "decision 未顯示 API 執行、寫 DB、寫 decision、更新 review_state 或掛 scheduler",
+            "passed": decision["side_effects_clear"],
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_payload_received",
+            "label": "已提供 operator approval 摘要",
+            "passed": approval_received,
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_identity_recorded",
+            "label": "approval 必須記錄 approval_id 與上游 identity",
+            "passed": bool(
+                approval["approval_id"]
+                and approval["review_decision_id"]
+                and approval["review_inventory_id"]
+                and approval["handoff_id"]
+                and approval["inventory_review_id"]
+                and approval["closeout_id"]
+                and approval["run_package_id"]
+                and approval["receipt_id"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_identity_matches_decision",
+            "label": "approval identity 必須對齊 review decision",
+            "passed": bool(
+                approval["review_decision_id"] == decision["review_decision_id"]
+                and approval["review_inventory_id"] == decision["review_inventory_id"]
+                and approval["handoff_id"] == decision["handoff_id"]
+                and approval["inventory_review_id"] == decision["inventory_review_id"]
+                and approval["closeout_id"] == decision["closeout_id"]
+                and approval["run_package_id"] == decision["run_package_id"]
+                and approval["receipt_id"] == decision["receipt_id"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_target_table_safe",
+            "label": "target table 必須是 market_alert_review_queue",
+            "passed": approval["target_table"] == TARGET_TABLE,
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_scope_safe",
+            "label": "approval 僅能是 human approval only",
+            "passed": bool(
+                approval["approval_scope"] == "candidate_queue_review_decision_approval"
+                and approval["approval_mode"] == "human_approval_only"
+                and approval["expected_decision_scope"]
+                == "candidate_queue_review_decision"
+                and approval["expected_current_review_state"] == "needs_review"
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_row_count_matches_decision",
+            "label": "approval row count 必須對齊 decision row count",
+            "passed": bool(
+                approval["expected_approved_row_count"]
+                and approval["approval_row_count"]
+                == approval["expected_approved_row_count"]
+                == decision["decision_row_count"]
+                and len(approval["approval_rows"]) == decision["decision_row_count"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_rows_match_decision",
+            "label": "approval rows 必須逐列對齊 decision rows",
+            "passed": bool(
+                _row_keys_match_expected(approval)
+                and _approval_rows_match_decision(decision, approval)
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_values_allowed",
+            "label": "approval 只能批准允許的決策集合",
+            "passed": _all_rows_have_allowed_decisions(approval),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_row_evidence_complete",
+            "label": "每列 approval 必須保留 evidence ref 與 notes",
+            "passed": _all_rows_have_approval_evidence(approval),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_matched_rows_keep_identity_guards",
+            "label": "matched approvals 必須保留 exact identity、variant 與 overwrite guard",
+            "passed": _matched_rows_keep_identity_guards(approval),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_artifact_paths_safe",
+            "label": "review queue、inventory、decision 與 approval artifact paths 必須安全並對齊",
+            "passed": bool(
+                approval["review_queue_artifact_path_safe"]
+                and approval["review_inventory_artifact_path_safe"]
+                and approval["review_decision_artifact_path_safe"]
+                and approval["approval_artifact_path_safe"]
+                and approval["review_queue_artifact_path"]
+                == decision["review_queue_artifact_path"]
+                and approval["review_inventory_artifact_path"]
+                == decision["review_inventory_artifact_path"]
+                and approval["review_decision_artifact_path"]
+                == decision["review_decision_artifact_path"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_operator_boundaries_confirmed",
+            "label": "操作員確認 API 未執行 CLI/DB/file/review_state/decision/match/scheduler",
+            "passed": operator_confirmed_boundaries,
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_no_api_execution_or_real_write",
+            "label": "approval payload 不得允許 API execution、real write、review update、decision write 或 match write",
+            "passed": bool(
+                not approval["api_execution_allowed"]
+                and not approval["real_write_allowed_by_api"]
+                and not approval["api_candidate_review_allowed"]
+                and not approval["api_updates_review_state"]
+                and not approval["api_writes_approval_record"]
+                and not approval["api_writes_decision_record"]
+                and not approval["api_writes_match_result"]
+            ),
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_no_secret_or_token_key",
+            "label": "approval payload 不得包含 secret、cookie、password 或 token key",
+            "passed": not approval["secret_or_token_submitted_to_api"],
+        },
+        {
+            "key": "candidate_queue_review_decision_approval_side_effect_free",
+            "label": "approval payload 不得要求 API 寫檔、執行、寫 DB、補 queue、寫 match 或掛 scheduler",
+            "passed": not approval["blocked_side_effects"],
+        },
+    ]

services/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval_sample.py

@@ -0,0 +1,140 @@
+"""Sample payload for the market intel review decision approval 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 import (
+    build_mcp_fetch_candidate_queue_writer_review_decision_preview,
+)
+
+
+_SAMPLE_WRITER_REVIEW_DECISION_APPROVAL_PACKAGE = None
+
+
+def build_sample_writer_review_decision_approval_package():
+    global _SAMPLE_WRITER_REVIEW_DECISION_APPROVAL_PACKAGE
+    if _SAMPLE_WRITER_REVIEW_DECISION_APPROVAL_PACKAGE is not None:
+        return deepcopy(_SAMPLE_WRITER_REVIEW_DECISION_APPROVAL_PACKAGE)
+
+    decision_preview = (
+        build_mcp_fetch_candidate_queue_writer_review_decision_preview()
+    )
+    decision_package = decision_preview["sample_writer_review_decision_package"]
+    decision_result = build_mcp_fetch_candidate_queue_writer_review_decision_preview(
+        writer_review_inventory_package=decision_package[
+            "writer_review_inventory_package"
+        ],
+        writer_review_inventory_result=decision_package[
+            "writer_review_inventory_result"
+        ],
+        operator_review_decision=decision_package["operator_review_decision"],
+    )
+    decision = decision_result["operator_review_decision_summary"]
+    inventory = decision_result["writer_review_inventory_summary"]
+    approval_rows = []
+    for row in decision["decision_rows"]:
+        approval_rows.append(
+            {
+                "dedupe_key": row["dedupe_key"],
+                "current_review_state": row["current_review_state"],
+                "approval_result": "approved_for_writer_preflight",
+                "proposed_review_decision": row["proposed_review_decision"],
+                "approved_review_decision": row["proposed_review_decision"],
+                "approval_bucket": row["decision_bucket"],
+                "evidence_lane": row["evidence_lane"],
+                "evidence_ref": row["evidence_ref"],
+                "decision_evidence_ref": row["evidence_ref"],
+                "approval_evidence_ref": (
+                    ARTIFACT_PREFIX
+                    + f"candidate-queue-review-decision-approval-{row['dedupe_key']}.json"
+                ),
+                "approval_notes": "human approval confirms decision row is ready for next gate",
+                "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_approval = {
+        "review_decision_approval_id": (
+            "market-intel-candidate-writer-review-decision-approval-sample"
+        ),
+        "approval_id": "market-intel-candidate-writer-review-decision-approval-sample",
+        "review_decision_id": decision["review_decision_id"],
+        "review_inventory_id": decision["review_inventory_id"],
+        "handoff_id": decision["handoff_id"],
+        "inventory_review_id": decision["inventory_review_id"],
+        "closeout_id": decision["closeout_id"],
+        "run_package_id": decision["run_package_id"],
+        "receipt_id": decision["receipt_id"],
+        "target_table": TARGET_TABLE,
+        "approval_scope": "candidate_queue_review_decision_approval",
+        "approval_mode": "human_approval_only",
+        "expected_decision_scope": "candidate_queue_review_decision",
+        "expected_current_review_state": "needs_review",
+        "approval_row_count": len(approval_rows),
+        "approved_row_count": len(approval_rows),
+        "expected_approval_row_count": decision["decision_row_count"],
+        "expected_approved_row_count": decision["decision_row_count"],
+        "expected_dedupe_keys": decision["expected_dedupe_keys"],
+        "review_queue_artifact_path": decision["review_queue_artifact_path"],
+        "review_inventory_artifact_path": decision[
+            "review_inventory_artifact_path"
+        ],
+        "review_decision_artifact_path": decision["review_decision_artifact_path"],
+        "approval_artifact_path": (
+            ARTIFACT_PREFIX
+            + "candidate-queue-review-decision-approval-sample.json"
+        ),
+        "review_decision_approval_artifact_path": (
+            ARTIFACT_PREFIX
+            + "candidate-queue-review-decision-approval-sample.json"
+        ),
+        "approval_rows": approval_rows,
+        "approved_rows": approval_rows,
+        "operator_confirmations": {
+            "review_decision_checked": True,
+            "approval_is_human_only": True,
+            "human_approval_only": True,
+            "manual_record_required": True,
+            "approval_record_manual_only": 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,
+            "stronger_existing_match_guard_preserved": True,
+            "false_positive_guard_completed": True,
+            "variant_sensitive_review_completed": True,
+            "hard_veto_respected": True,
+            "decision_rows_match_review_decision": True,
+        },
+        "api_execution_allowed": False,
+        "real_write_allowed_by_api": False,
+        "api_candidate_review_allowed": False,
+        "api_updates_review_state": False,
+        "api_writes_approval_record": False,
+        "api_writes_decision_record": False,
+        "api_writes_match_result": False,
+    }
+    _SAMPLE_WRITER_REVIEW_DECISION_APPROVAL_PACKAGE = {
+        "writer_review_decision_package": decision_package,
+        "writer_review_decision_result": decision_result,
+        "operator_review_approval": operator_approval,
+        "operator_review_decision_approval": operator_approval,
+    }
+    return deepcopy(_SAMPLE_WRITER_REVIEW_DECISION_APPROVAL_PACKAGE)

services/market_intel/phase.py

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