feat(rectification): expose candidate result reports

scripts/active_rectification_events.py

@@ -108,6 +108,57 @@ class CandidateResult(TypedDict):
     stability_diagnostics: dict[str, Any]
     missing_layers: list[str]
     candidate_ranking_summary: NotRequired[list[dict[str, Any]]]
+    candidate_summary: NotRequired[dict[str, Any]]
+
+
+def build_candidate_result_summary(result: dict[str, Any]) -> dict[str, Any]:
+    """Project a candidate result into stable, non-confirmatory next steps."""
+    supported: dict[str, dict[str, Any]] = {}
+    unconfirmed: dict[str, dict[str, Any]] = {}
+    contradictory: dict[str, dict[str, Any]] = {}
+
+    for item in result.get("evidence", []):
+        if not isinstance(item, dict):
+            continue
+        domain = str(item.get("domain") or "unknown")
+        points = float(item.get("points") or 0)
+        bucket = supported if points > 0 else contradictory if points < 0 else unconfirmed
+        row = bucket.setdefault(domain, {"domain": domain, "event_count": 0, "total_points": 0.0, "rule_ids": set()})
+        row["event_count"] += 1
+        row["total_points"] += points
+        row["rule_ids"].update(str(rule_id) for rule_id in item.get("rule_ids", []))
+
+    def rows(bucket: dict[str, dict[str, Any]], *, include_points: bool) -> list[dict[str, Any]]:
+        output = []
+        for row in bucket.values():
+            item: dict[str, Any] = {
+                "domain": row["domain"],
+                "event_count": row["event_count"],
+                "rule_ids": sorted(row["rule_ids"]),
+            }
+            if include_points:
+                item["total_points"] = round(row["total_points"], 3)
+            output.append(item)
+        return sorted(output, key=lambda item: (-item.get("total_points", 0), item["domain"]))
+
+    segment = result.get("winning_segment")
+    next_steps: list[str] = []
+    if int(result.get("event_count") or 0) < 5:
+        next_steps.append("collect_at_least_five_events")
+    if float(result.get("margin_percent") or 0) <= 0 or "tied_leader" in (result.get("reasons") or []):
+        next_steps.append("resolve_candidate_tie_or_narrow_window")
+    if isinstance(segment, dict) and int(segment.get("width_minutes") or 0) > 5:
+        next_steps.append("narrow_window_before_minute_claim")
+    next_steps.append("do_not_apply_as_birth_time_truth")
+    return {
+        "claim_status": "candidate_range_not_birth_time_truth",
+        "candidate_range": segment,
+        "supporting_evidence": rows(supported, include_points=True),
+        "unconfirmed_evidence": rows(unconfirmed, include_points=False),
+        "contradictory_evidence": rows(contradictory, include_points=True),
+        "reasons": list(result.get("reasons") or []),
+        "next_step_codes": next_steps,
+    }
 
 
 def precision_weight(precision: EventPrecision) -> float:
@@ -347,4 +398,6 @@ def score_life_events(request: RectificationEventRequest) -> CandidateResult:
     """Compute actual candidate rows, then apply the versioned confidence gates."""
     from scripts.active_rectification_event_engine import compute_event_candidate_result
 
-    return compute_event_candidate_result(request)
+    result = compute_event_candidate_result(request)
+    result["candidate_summary"] = build_candidate_result_summary(result)
+    return result

scripts/rectification/api_service.py

@@ -1,10 +1,15 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Sequence
 from uuid import NAMESPACE_URL, uuid5
 
+from scripts.active_rectification_events import build_candidate_result_summary
 from scripts.rectification.candidate_feature_service import build_candidate_feature_snapshot
-from scripts.rectification.contracts import EVENT_CONTRACT_VERSION, RectificationRequest
+from scripts.rectification.contracts import (
+    EVENT_CONTRACT_VERSION,
+    RectificationRequest,
+    is_primary_scoreable_event,
+)
 from scripts.rectification.decision_policy import (
     EXECUTION_LEDGER_VERSION,
     POLICY_VERSION,
@@ -23,6 +28,130 @@ from scripts.rectification.scoring_service import (
 )
 
 
+def _clock_minutes(value: str) -> int:
+    hour, minute = value[:5].split(":", 1)
+    return int(hour) * 60 + int(minute)
+
+
+def _window_width(start_time: str, end_time: str) -> int:
+    return (_clock_minutes(end_time) - _clock_minutes(start_time)) % 1_440 + 1
+
+
+def _report_candidate_range(
+    request: RectificationRequest,
+    candidate_scores: Sequence[dict[str, Any]],
+    representative_time: str | None,
+) -> dict[str, Any]:
+    top_score = max((float(row.get("score") or 0) for row in candidate_scores), default=None)
+    top_times = [
+        str(row.get("time"))[:5]
+        for row in candidate_scores
+        if top_score is not None and float(row.get("score") or 0) == top_score
+    ]
+    if not top_times:
+        return {
+            "start_time": request["start_time"],
+            "end_time": request["end_time"],
+            "representative_time": representative_time,
+            "width_minutes": _window_width(request["start_time"], request["end_time"]),
+            "representative_is_unique": False,
+        }
+    return {
+        "start_time": top_times[0],
+        "end_time": top_times[-1],
+        "representative_time": representative_time or top_times[len(top_times) // 2],
+        "width_minutes": len(top_times),
+        "representative_is_unique": False,
+    }
+
+
+def _report_evidence(
+    request: RectificationRequest,
+    built: dict[str, Any],
+    representative_time: str | None,
+) -> list[dict[str, Any]]:
+    matrix = built.get("matrix") or {}
+    rows: list[dict[str, Any]] = []
+    for event in request.get("events") or []:
+        if not is_primary_scoreable_event(event):
+            continue
+        contribution = (matrix.get(event["id"]) or {}).get(representative_time or "")
+        contribution = contribution if isinstance(contribution, dict) else {}
+        points = float(contribution.get("points") or 0)
+        status = "supporting" if points > 0 else "contradictory" if points < 0 else "unconfirmed"
+        rows.append({
+            "event_id": event["id"],
+            "summary": str(event.get("summary") or "").strip(),
+            "domain": event["domain"],
+            "date": {
+                "start": event["date_start"],
+                "end": event["date_end"],
+                "precision": event["precision"],
+            },
+            "status": status,
+            "supports_candidate_time": representative_time if status == "supporting" else None,
+            "methods": sorted({str(layer) for layer in contribution.get("technique_layers") or []}),
+        })
+    return rows
+
+
+def _report_excluded_candidates(
+    candidate_decisions: Sequence[dict[str, Any]],
+    representative_time: str | None,
+) -> list[dict[str, Any]]:
+    return [
+        {
+            "time": str(candidate.get("time") or "")[:5],
+            "reason": "not_the_leading_candidate",
+            "representative_time": representative_time,
+        }
+        for candidate in candidate_decisions
+        if str(candidate.get("time") or "")[:5] != (representative_time or "")
+    ]
+
+
+def _confirmation_blockers(receipt: dict[str, Any]) -> list[dict[str, str]]:
+    allowed = {"VedAstro 分钟级校验", "唯一分钟确认"}
+    return [
+        {
+            "technique": str(row.get("technique")),
+            "status": str(row.get("status")),
+            "user_meaning": str(row.get("note") or ""),
+        }
+        for row in receipt.get("technique_audit_table") or []
+        if isinstance(row, dict)
+        and str(row.get("technique")) in allowed
+        and str(row.get("status")) != "executed"
+    ]
+
+
+def _rectification_report(
+    request: RectificationRequest,
+    built: dict[str, Any],
+    candidate_scores: Sequence[dict[str, Any]],
+    candidate_decisions: Sequence[dict[str, Any]],
+    receipt: dict[str, Any],
+) -> dict[str, Any]:
+    representative_time = str(receipt.get("representative_time") or "")[:5] or None
+    blockers = _confirmation_blockers(receipt)
+    candidate_range = _report_candidate_range(request, candidate_scores, representative_time)
+    limitations = [item["user_meaning"] for item in blockers if item["user_meaning"]]
+    if not limitations:
+        limitations.append("本会话以代表性时间收口，不确认唯一分钟。")
+    return {
+        "candidate_range": candidate_range,
+        "representative_time": representative_time,
+        "representative_label": "代表性候选，不是唯一解",
+        "confidence": receipt.get("overall_confidence", "low"),
+        "evidence": _report_evidence(request, built, representative_time),
+        "excluded_candidates": _report_excluded_candidates(candidate_decisions, representative_time),
+        "next_step_codes": [],
+        "confirmation_gate_blockers": blockers,
+        "limitations": limitations,
+        "claim_status": "candidate_range_not_birth_time_truth",
+    }
+
+
 def candidate_features(request: RectificationRequest) -> dict[str, Any]:
     spec = calculation_spec(request)
     spec_hash = sha256(spec)
@@ -55,6 +184,35 @@ def score_candidates(request: RectificationRequest) -> dict[str, Any]:
     decision_receipt = build_decision_receipt(request, candidate_decisions, built, diagnostic_values)
     execution_ledger = build_execution_ledger(request, built, diagnostic_values, candidate_decisions)
     representative = candidate_decisions[0] if candidate_decisions else None
+    representative_time = str(representative.get("time") or "")[:5] if representative else None
+    report_range = _report_candidate_range(request, rows, representative_time)
+    report_evidence = _report_evidence(request, built, representative_time)
+    summary_evidence = [
+        {
+            "event_id": item["event_id"],
+            "domain": item["domain"],
+            "candidate_time": representative_time or "",
+            "rule_ids": item["methods"],
+            "points": 1 if item["status"] == "supporting" else -1 if item["status"] == "contradictory" else 0,
+        }
+        for item in report_evidence
+    ]
+    candidate_summary = build_candidate_result_summary({
+        "winning_segment": report_range,
+        "event_count": len(scoring_request.get("events", [])),
+        "margin_percent": decision_receipt.get("margin_percent", 0),
+        "reasons": decision_receipt.get("reasons", []),
+        "evidence": summary_evidence,
+    })
+    candidate_summary["stability"] = {"label": decision_receipt.get("overall_confidence", "low")}
+    rectification_report = _rectification_report(
+        request, built, [{
+            "time": row["time"],
+            "score": row["score"],
+        } for row in rows], candidate_decisions, decision_receipt,
+    )
+    rectification_report["next_step_codes"] = candidate_summary["next_step_codes"]
+    candidate_summary["report"] = rectification_report
     return {
         "result_id": result_id,
         "algorithm_version": ALGORITHM_VERSION,
@@ -78,6 +236,10 @@ def score_candidates(request: RectificationRequest) -> dict[str, Any]:
             scoring_request, spec_hash, built.get("static_contexts")
         ),
         "diagnostics": diagnostic_values,
+        "candidate_summary": candidate_summary,
+        "next_step_codes": candidate_summary["next_step_codes"],
+        "stability": candidate_summary["stability"],
+        "rectification_report": rectification_report,
         "robustness": {
             "neighbor_support_minutes": diagnostic_values.get("neighbor_support_minutes", 0),
             "leave_one_out_retention_rate": diagnostic_values.get("leave_one_event_out_retention_rate", 0),
@@ -112,6 +274,10 @@ def diagnostics(request: RectificationRequest) -> dict[str, Any]:
         "execution_ledger_version": scored["execution_ledger_version"],
         "execution_ledger": scored["execution_ledger"],
         "diagnostics": scored["diagnostics"],
+        "candidate_summary": scored.get("candidate_summary", {"next_step_codes": ["do_not_apply_as_birth_time_truth"]}),
+        "next_step_codes": scored.get("next_step_codes", ["do_not_apply_as_birth_time_truth"]),
+        "stability": scored.get("stability", {"label": scored.get("overall_confidence", "low")}),
+        "rectification_report": scored.get("rectification_report", {}),
         "missing_layers": scored["missing_layers"],
         "display_allowed": scored["display_allowed"],
         "selection_allowed": scored["selection_allowed"],

scripts/rectification/contracts.py

@@ -156,8 +156,8 @@ def normalize_rectification_request(body: Any, *, today: date | None = None) ->
     if not isinstance(end_time, str) or not _CLOCK.fullmatch(end_time):
         raise ValueError("end_time must be HH:MM")
     events = body.get("events")
-    if not isinstance(events, list) or not 1 <= len(events) <= 100:
-        raise ValueError("events must contain between 1 and 100 items")
+    if not isinstance(events, list) or not 0 <= len(events) <= 100:
+        raise ValueError("events must contain between 0 and 100 items")
     upper_date = today or date.today()
     cleaned_events: list[LifeEvent] = []
     for index, raw_event in enumerate(events):