From 78f601f9f5afaad6ac159dd655fd05c1e8547023 Mon Sep 17 00:00:00 2001
From: 732642856 <732642856@qq.com>
Date: Sat, 18 Jul 2026 02:44:18 +0800
Subject: [PATCH] feat: disclose public case coverage gaps

---
 frontend/src/mastra/index.ts                  |  1 +
 frontend/tests/consultation-context.test.ts   |  1 +
 scripts/reference_transparency_contract.py    | 19 +++++++++++++++++++
 tests/test_reference_transparency_contract.py |  5 +++++
 4 files changed, 26 insertions(+)

diff --git a/frontend/src/mastra/index.ts b/frontend/src/mastra/index.ts
index 420cc387..0cebd28c 100644
--- a/frontend/src/mastra/index.ts
+++ b/frontend/src/mastra/index.ts
@@ -112,6 +112,7 @@ Treat consumer_context as the authoritative answer policy:
 When reference_transparency is present:
 - Present candidate_windows and exact_triggers when relevant, but describe exact_triggers as technical trigger points, never guaranteed events.
 - Share a public case only when similar_public_cases.status is high_similarity_public_references_available. State the listed matching factors, dissimilar factors, event source URL, and that the case is reference-only.
+- When similar_public_cases.coverage.requested_uncovered_domains is non-empty, say the current public-case catalog does not yet cover those themes; do not infer that no comparable real-world case exists.
 - When method_variants applies, present parallel methods and their source paths rather than silently picking one result as the only truth.
 - If should_lead_with_limitations is false, do not lead with limitations. If a limitation is relevant, put it in one short sentence at the end.
 - Only say the chart calculation failed when hard_blockers is non-empty.
diff --git a/frontend/tests/consultation-context.test.ts b/frontend/tests/consultation-context.test.ts
index c5bd6fc8..8d2568db 100644
--- a/frontend/tests/consultation-context.test.ts
+++ b/frontend/tests/consultation-context.test.ts
@@ -7,5 +7,6 @@ test("passes transparent public-case references into the agent context", () => {
 
   assert.match(source, /reference_transparency:\s*record\(data\.reference_transparency\)/);
   assert.match(source, /high_similarity_public_references_available/);
+  assert.match(source, /requested_uncovered_domains/);
   assert.match(source, /exact_triggers as technical trigger points/);
 });
diff --git a/scripts/reference_transparency_contract.py b/scripts/reference_transparency_contract.py
index dbebfc37..e8b115af 100644
--- a/scripts/reference_transparency_contract.py
+++ b/scripts/reference_transparency_contract.py
@@ -122,6 +122,24 @@ def _load_cases(manifest_path: Path) -> list[dict[str, Any]]:
     return [case for case in cases if isinstance(case, dict)] if isinstance(cases, list) else []
 
 
+def _coverage(cases: list[dict[str, Any]], themes: list[str]) -> dict[str, list[str]]:
+    domains: set[str] = set()
+    for case in cases:
+        replay = case.get("replay")
+        if not isinstance(replay, dict) or replay.get("outcome_replay_status") != "replayed":
+            continue
+        if replay.get("do_not_use_for_prediction") is True:
+            continue
+        for event in case.get("event_outcomes", []):
+            if isinstance(event, dict) and isinstance(event.get("domain"), str):
+                domains.add(event["domain"])
+    available = sorted(domains)
+    return {
+        "available_event_domains": available,
+        "requested_uncovered_domains": sorted(set(themes) - domains),
+    }
+
+
 def select_similar_public_cases(
     user_chart: dict[str, Any],
     themes: list[str],
@@ -172,6 +190,7 @@ def select_similar_public_cases(
         "manifest": "references/real_case_calibration/replay_manifest.json",
         "public_figures_only": True,
         "does_not_predict_user_outcome": True,
+        "coverage": _coverage(candidates, themes),
         "boundary": "公开案例用于比较与理解，不表示用户会复现该事件。",
     }
 
diff --git a/tests/test_reference_transparency_contract.py b/tests/test_reference_transparency_contract.py
index 2be6f1b3..2cb62883 100644
--- a/tests/test_reference_transparency_contract.py
+++ b/tests/test_reference_transparency_contract.py
@@ -53,6 +53,10 @@ def test_select_similar_cases_shares_only_high_similarity_same_domain() -> None:
     assert selected["cases"][0]["similarity"]["score"] == 1.0
     assert selected["cases"][0]["event_source"]["url"] == "https://example.com/event"
     assert selected["does_not_predict_user_outcome"] is True
+    assert selected["coverage"] == {
+        "available_event_domains": ["career", "marriage"],
+        "requested_uncovered_domains": [],
+    }
 
 
 def test_reference_contract_preserves_dates_and_discloses_parallel_methods() -> None:
@@ -67,6 +71,7 @@ def test_reference_contract_preserves_dates_and_discloses_parallel_methods() ->
     assert contract["external_engine_observations"]["VedAstro hosted"]["deployment_identity"] == "not_publicly_proven"
     assert contract["method_variants"]["display"] == "show_parallel_methods_with_sources"
     assert contract["similar_public_cases"]["status"] == "no_high_similarity_public_reference"
+    assert contract["similar_public_cases"]["coverage"]["requested_uncovered_domains"] == ["career"]
 
 
 def test_default_public_manifest_can_surface_a_matching_replayed_case() -> None: