diff --git a/benchmarks/tc1_real/spatial_planning/fixtures/provider_representation_proof_v0_1.json b/benchmarks/tc1_real/spatial_planning/fixtures/provider_representation_proof_v0_1.json new file mode 100644 index 0000000..d6746cc --- /dev/null +++ b/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." +} diff --git a/benchmarks/tc1_real/spatial_planning/provider_representation_proof.py b/benchmarks/tc1_real/spatial_planning/provider_representation_proof.py new file mode 100644 index 0000000..21882af --- /dev/null +++ b/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, + ) diff --git a/docs/reference/task-context-provider-representation-proof-v0.1.md b/docs/reference/task-context-provider-representation-proof-v0.1.md new file mode 100644 index 0000000..c0f1ba2 --- /dev/null +++ b/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. diff --git a/tests/test_tc1_real_provider_representation_proof.py b/tests/test_tc1_real_provider_representation_proof.py new file mode 100644 index 0000000..3d5a017 --- /dev/null +++ b/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)