Draft: prove task-appropriate provider representation

benchmarks/tc1_real/spatial_planning/fixtures/provider_representation_proof_v0_1.json

@@ -0,0 +1,27 @@
+{
+  "scenario": "Phoenix public-library service-coverage context preparation",
+  "source_family": "City of Phoenix Growth Projections",
+  "joined_representation": {
+    "layer_id": 2,
+    "name": "FinalLUAUs_PopEmp",
+    "complete_feature_count": 118190,
+    "unique_planning_unit_count": 471,
+    "network_bytes": 172127458,
+    "page_count": 119,
+    "complete": true
+  },
+  "base_representation": {
+    "layer_id": 4,
+    "name": "FinalLUAUs",
+    "complete_feature_count": 471,
+    "unique_planning_unit_count": 471,
+    "network_bytes": 24237,
+    "request_count": 2,
+    "complete": true
+  },
+  "relationship": {
+    "population_table_id": 13,
+    "key": "newluau"
+  },
+  "provenance_note": "Values are copied from the frozen TC1-Real planning diagnostic and compact spatial measurement. The two representations do not carry identical semantics; network byte ratios must not be reported as compression savings."
+}

benchmarks/tc1_real/spatial_planning/provider_representation_proof.py

@@ -0,0 +1,57 @@
+"""Offline proof that provider completeness is not enough when representation is wrong.
+
+This benchmark helper uses already-recorded TC1-Real Phoenix evidence. It does
+not access the live provider and it does not treat cross-representation byte
+ratios as compression savings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+
+@dataclass(frozen=True)
+class ProviderRepresentationProof:
+    joined_feature_count: int
+    unique_planning_unit_count: int
+    base_feature_count: int
+    joined_records_per_unit: float
+    base_is_one_feature_per_unit: bool
+    byte_ratio_scoreable: bool
+
+
+def analyze_provider_representation(
+    evidence: Mapping[str, object],
+) -> ProviderRepresentationProof:
+    joined = evidence["joined_representation"]
+    base = evidence["base_representation"]
+    if not isinstance(joined, Mapping) or not isinstance(base, Mapping):
+        raise ValueError("representation evidence must contain mapping records")
+
+    if joined.get("complete") is not True or base.get("complete") is not True:
+        raise ValueError("both representations must have complete acquisition evidence")
+
+    joined_count = int(joined["complete_feature_count"])
+    unique_count = int(joined["unique_planning_unit_count"])
+    base_count = int(base["complete_feature_count"])
+    base_unique_count = int(base["unique_planning_unit_count"])
+    if min(joined_count, unique_count, base_count, base_unique_count) <= 0:
+        raise ValueError("representation counts must be > 0")
+    if unique_count != base_unique_count:
+        raise ValueError("joined and base evidence must refer to the same unique unit set")
+
+    note = str(evidence.get("provenance_note", ""))
+    byte_ratio_scoreable = not (
+        "do not carry identical semantics" in note
+        or "must not be reported as compression savings" in note
+    )
+
+    return ProviderRepresentationProof(
+        joined_feature_count=joined_count,
+        unique_planning_unit_count=unique_count,
+        base_feature_count=base_count,
+        joined_records_per_unit=joined_count / unique_count,
+        base_is_one_feature_per_unit=base_count == base_unique_count,
+        byte_ratio_scoreable=byte_ratio_scoreable,
+    )

docs/reference/task-context-provider-representation-proof-v0.1.md

@@ -0,0 +1,63 @@
+# TC1-Real Provider Representation Proof v0.1
+
+**Status:** method proof candidate
+
+## Question
+
+After provider completeness is proven, can the complete record count itself be treated as task-context burden without first checking whether the chosen source representation matches the task's physical-world entities?
+
+## Recorded Phoenix evidence
+
+The first complete IDs-first acquisition used joined Growth layer 2 (`FinalLUAUs_PopEmp`). It returned:
+
+```text
+complete features        118,190
+unique newluau units          471
+network bytes        172,127,458
+pages                         119
+```
+
+The public service also exposes base planning-unit layer 4 (`FinalLUAUs`). The compact complete measurement for the same frozen broad region recorded:
+
+```text
+complete base units          471
+unique newluau units         471
+network bytes             24,237
+requests                       2
+```
+
+Population semantics are related separately through table 13 (`New_Pop_Emp_Data`) using `newluau`.
+
+## Interpretation
+
+The joined representation repeats planning-unit geometry across related Pop/Emp records. Its complete feature cardinality is therefore not the task's minimal physical-world entity cardinality.
+
+```text
+118,190 joined features / 471 unique planning units
+= about 250.9 feature records per unique planning unit
+```
+
+This is retained as **wrong-representation evidence**, not as a large R0 baseline from which GeoTask may advertise a compression rate.
+
+The network-byte contrast must also remain non-scoring: joined layer 2 and base layer 4 do not carry identical semantics or fields. The evidence supports a representation-selection correction, not a 7,000x compression claim.
+
+## Method rule
+
+```text
+Task requirement
+  -> identify the physical-world entity/semantic unit actually required
+  -> choose the least-duplicative source representation that preserves it
+  -> prove provider completeness
+  -> prove semantic/entity coverage
+  -> only then compare scope/context burden
+```
+
+## Narrow conclusion
+
+> Context cost can be dominated by the representation chosen before any task-scope reduction occurs.
+
+A complete provider response can still be the wrong Task Context representation.
+
+## Core boundary
+
+This proof does not promote a generic `Representation` schema or source optimizer into GeoTask Core. It is benchmark/method evidence for a later cross-domain promotion review.

tests/test_tc1_real_provider_representation_proof.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from benchmarks.tc1_real.spatial_planning.provider_representation_proof import (
+    analyze_provider_representation,
+)
+
+
+FIXTURE = (
+    Path(__file__).parents[1]
+    / "benchmarks"
+    / "tc1_real"
+    / "spatial_planning"
+    / "fixtures"
+    / "provider_representation_proof_v0_1.json"
+)
+
+
+def _evidence() -> dict[str, object]:
+    return json.loads(FIXTURE.read_text(encoding="utf-8"))
+
+
+def test_joined_representation_repeats_base_planning_units() -> None:
+    result = analyze_provider_representation(_evidence())
+
+    assert result.joined_feature_count == 118190
+    assert result.unique_planning_unit_count == 471
+    assert result.base_feature_count == 471
+    assert result.base_is_one_feature_per_unit is True
+    assert result.joined_records_per_unit == pytest.approx(250.9342, rel=1e-4)
+
+
+def test_cross_representation_network_bytes_are_not_a_compression_claim() -> None:
+    result = analyze_provider_representation(_evidence())
+    assert result.byte_ratio_scoreable is False
+
+
+def test_population_semantics_remain_related_separately() -> None:
+    evidence = _evidence()
+    relation = evidence["relationship"]
+    assert relation == {"population_table_id": 13, "key": "newluau"}
+
+
+def test_incomplete_representation_evidence_fails_closed() -> None:
+    evidence = _evidence()
+    evidence["joined_representation"]["complete"] = False
+    with pytest.raises(ValueError, match="complete acquisition evidence"):
+        analyze_provider_representation(evidence)
+
+
+def test_mismatched_unique_unit_sets_fail_closed() -> None:
+    evidence = _evidence()
+    evidence["base_representation"]["unique_planning_unit_count"] = 470
+    with pytest.raises(ValueError, match="same unique unit set"):
+        analyze_provider_representation(evidence)