mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/local_contracts.py

@@ -0,0 +1,2880 @@
+"""Versioned, immutable Harness-private execution contracts.
+
+These types describe local agent proposals and deterministic execution inputs.  They deliberately
+exclude Studio tenancy, authorization, persistence, and release fields; cross-repository values
+are mapped to Studio's generated client only at the hosted boundary.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import PurePosixPath
+from typing import Any, ClassVar
+from urllib.parse import parse_qsl, unquote_plus, urlsplit, urlunsplit
+
+from mostlyright.data_harness.canonical import canonical_json_bytes, canonical_sha256
+from mostlyright.data_harness.formats import PLAN_DATA_FORMATS
+from mostlyright.data_harness.operation_registry import (
+    GRAPH_OPERATION_CONTRACT_VERSION,
+    RETIRED_OPERATIONS,
+    OperationRegistryError,
+    resolve_operation,
+    thaw_parameter,
+)
+from mostlyright.data_harness.units import (
+    NO_UNIT,
+    Unit,
+    UnitError,
+    is_count_unit,
+    legacy_aliases,
+    resolve_declared_unit,
+)
+
+QUESTION_SCHEMA_VERSION = "local-question.v1"
+OUTPUT_GRAIN_SCHEMA_VERSION = "local-output-grain.v1"
+REQUIREMENTS_SCHEMA_VERSION = "local-requirements.v1"
+SOURCE_PROPOSAL_SCHEMA_VERSION = "local-source-proposal.v2"
+PLAN_SCHEMA_VERSION = "local-table-plan.v1"
+_LEGACY_PLAN_SCHEMA_VERSION = "local-plan.v1"
+OPERATION_CONTRACT_VERSION = "local-operations.v1"
+GRAPH_PLAN_SCHEMA_VERSION = "local-graph-table-plan.v1"
+VALIDATION_POLICY_VERSION = "local-validation.v1"
+# The first semantics generation carries the fifteen hand-grown tokens and nothing else; the
+# second carries a unit code, which is any expression the grammar in :mod:`units` resolves against
+# its pinned table. The two are read side by side forever: a document sealed under the first
+# generation says what vocabulary its author was writing against, and re-reading it must not widen
+# that. New documents are authored at the second.
+TABLE_SEMANTICS_V1 = "table-semantics.v1"
+TABLE_SEMANTICS_V2 = "table-semantics.v2"
+TABLE_SEMANTICS_VERSIONS = (TABLE_SEMANTICS_V1, TABLE_SEMANTICS_V2)
+TABLE_SEMANTICS_VERSION = TABLE_SEMANTICS_V2
+
+MAX_IDENTIFIER_LENGTH = 64
+MAX_COLUMN_COUNT = 256
+MAX_SOURCE_COUNT = 64
+MAX_OPERATION_COUNT = 256
+MAX_GRAPH_NODE_COUNT = 512
+MAX_TEXT_LENGTH = 16_384
+MAX_SHORT_TEXT_LENGTH = 2_000
+MAX_PATH_LENGTH = 1_024
+MAX_EVIDENCE_COUNT = 64
+MAX_OUTPUT_ROWS = 100_000
+GRAPH_MAX_OUTPUT_ROWS = 1_000_000
+
+_IDENTIFIER = re.compile(r"^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$")
+_COLUMN = re.compile(r"^[a-z][a-z0-9_]{0,62}$")
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+_UTC_TIMESTAMP = re.compile(
+    r"^(?P<date>[0-9]{4}-[0-9]{2}-[0-9]{2})"
+    r"T(?P<time>[0-9]{2}:[0-9]{2}:[0-9]{2})"
+    r"(?P<fraction>\.[0-9]{1,6})?Z$"
+)
+_SENSITIVE_LOCATOR_QUERY_KEY = re.compile(
+    r"(?:^|[_-])(?:api[_-]?key|authorization|bearer|credential|password|private[_-]?key|"
+    r"secret|sig|signature|signed|token)(?:$|[_-])",
+    re.IGNORECASE,
+)
+_SECRET_LOCATOR_VALUE = re.compile(
+    r"^(?:Bearer\s+|Basic\s+|sk[-_]|gh[opusr]_|AIza|AKIA|ASIA|eyJ[A-Za-z0-9_-]*\.)",
+    re.IGNORECASE,
+)
+
+# The complete set of boundaries Python's text renderer treats as a new line. Tabs and ordinary
+# Unicode remain valid within a line; U+009B and bidi controls are deliberately not decided here.
+# This is structural line safety, not a terminal-control policy.
+_DISPLAY_LINE_BOUNDARIES = frozenset(
+    {"\n", "\r", "\v", "\f", "\x1c", "\x1d", "\x1e", "\x85", "\u2028", "\u2029"}
+)
+
+_QUESTION_FIELDS = frozenset({"schema_version", "question_id", "text", "created_at"})
+_TARGET_POLICIES = frozenset({"none", "required_if_supportable"})
+_FEASIBILITY_DECISIONS = frozenset({"supportable", "supportable_with_limits", "unsupported"})
+_FEASIBILITY_REASONS = frozenset(
+    {
+        "sufficient_evidence",
+        "limited_coverage",
+        "unacceptable_delay",
+        "rights_unclear",
+        "no_reliable_source",
+        "target_not_observable",
+    }
+)
+# Narrower than the model's coarse family; see the vocabulary map in sources/contracts.py.
+_SOURCE_CLASSES = frozenset(
+    {
+        "external_adapter",
+        "user_file",
+        "user_url",
+        "user_api",
+        "database_extract",
+        "webhook",
+        "stream",
+    }
+)
+_LOCATOR_KINDS = frozenset({"relative_path", "https_url", "artifact_reference"})
+# Mixes encodings with access shapes; see the vocabulary map in sources/contracts.py.
+# This is the plan-contract set, not the wire-format set: dropping to DATA_FORMATS here
+# would silently remove api and stream from plan validation.
+_DATA_FORMATS = PLAN_DATA_FORMATS
+# No unknown state here, unlike model liveness; see the vocabulary map in sources/contracts.py.
+_LIVE_ENDPOINTS = frozenset({"live", "degraded", "delayed", "dead", "not_applicable"})
+# Same spelling in all three layers; see the vocabulary map in sources/contracts.py.
+_PROPOSAL_RIGHTS = frozenset({"approved", "conditional", "unclear", "prohibited"})
+# Stage-specific triplet; see the vocabulary map in sources/contracts.py.
+_FITNESS_DECISIONS = frozenset({"selected", "eligible", "rejected"})
+
+# Rights basis a build reads a file under, not a rights adjudication: this unknown is not
+# _PROPOSAL_RIGHTS.unclear.  See the vocabulary map in sources/contracts.py.
+_RIGHTS_STATUSES = frozenset(
+    {
+        "project_owned",
+        "public_domain",
+        "permissive_license",
+        "authorized_internal",
+        "user_authorized",
+        "unknown",
+        "prohibited",
+    }
+)
+_PERMISSIONS = frozenset({"local_use", "redistribute", "host"})
+_ACQUISITION_METHODS = frozenset({"checked_in_fixture", "user_upload", "authorized_export"})
+_OUTPUT_INTENTS = frozenset({"local_use", "redistribute", "host"})
+# The one authoritative logical-type vocabulary shared by Recipe declarations and the
+# deterministic local transform path. ``_CAST_TYPES`` remains as a private compatibility alias
+# for callers that inspect the plan contract, but every accepted logical type is executable.
+LOGICAL_TYPES = frozenset({"string", "int64", "float64", "boolean", "date", "timestamp_utc"})
+_CAST_TYPES = LOGICAL_TYPES
+_CLEANING_OPERATIONS = frozenset({"trim", "empty_to_null", "rename", "cast"})
+# The whole of what a ``local-plan.v1`` join may declare, frozen at one kind by the ruling in
+# ``docs/TRANSFORMS.md``. It is written out as a name rather than left inline because the set is a
+# decision about sealed meaning and not a list that grows: the v1 join rule is named in the
+# ``mandatory_gates`` list ``validation_policy_digest`` hashes, and every approved v1 Recipe is
+# bound to that digest. ``JoinSpec`` below says why each of the graph's other two kinds is refused
+# here; join-kind growth happens in ``operation_registry.GRAPH_JOIN_KINDS`` instead.
+JOIN_KINDS = frozenset({"left"})
+_JOIN_CARDINALITIES = frozenset({"one_to_one", "many_to_one"})
+SEMANTIC_TYPES = frozenset(
+    {"identifier", "entity", "category", "measure", "dimension", "target", "other"}
+)
+# The fifteen tokens the hand-grown list held. They are no longer the vocabulary: a declared unit
+# is a code the grammar resolves, and these fourteen names plus ``none`` are read as the codes they
+# always meant. What they still are is the whole of what ``table-semantics.v1`` may declare, and
+# a frozen generation cannot be a function of a data file that a later change might extend -- so
+# the fifteen are written out here, and the equality below binds them to the pinned alias table.
+# Adding an alias to that table without deciding what it means for the frozen generation is an
+# explicit import-time failure rather than a silent widening of sealed meaning.
+UNITS = frozenset(
+    {
+        "none",
+        "count",
+        "ratio",
+        "percent",
+        "celsius",
+        "fahrenheit",
+        "kelvin",
+        "meter",
+        "kilometer",
+        "mile",
+        "microgram_per_cubic_meter",
+        "second",
+        "minute",
+        "hour",
+        "hectopascal",
+    }
+)
+assert UNITS == frozenset({NO_UNIT}) | frozenset(legacy_aliases())
+UNIT_STATES = frozenset({"declared", "normalized", "not_applicable", "unknown"})
+NORMALIZATIONS = frozenset(
+    {"z_score", "min_max", "unit_interval", "percent_of_total", "index_100", "log", "other"}
+)
+CATEGORY_STATUSES = frozenset({"complete", "partial", "not_applicable", "unknown"})
+SEMANTIC_EVIDENCE_KINDS = frozenset({"source_id"})
+
+
+class ContractError(ValueError):
+    """A typed private-contract validation failure with an exact field path."""
+
+    def __init__(self, path: str, code: str, detail: str) -> None:
+        self.path = path
+        self.code = code
+        self.detail = detail
+        super().__init__(f"{path}: {detail} [{code}]")
+
+
+class _CanonicalContract:
+    """Common deterministic serialization behavior for private contracts."""
+
+    schema_version: str
+    EXPECTED_SCHEMA_VERSION: ClassVar[str]
+
+    def to_dict(self) -> dict[str, Any]:  # pragma: no cover - abstract-by-convention
+        raise NotImplementedError
+
+    @property
+    def canonical_bytes(self) -> bytes:
+        return canonical_json_bytes(self.to_dict())
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+
+@dataclass(frozen=True)
+class LocalQuestion(_CanonicalContract):
+    """A local question proposal without hosted identity or authorization fields."""
+
+    question_id: str
+    text: str
+    created_at: str
+    schema_version: str = QUESTION_SCHEMA_VERSION
+
+    EXPECTED_SCHEMA_VERSION: ClassVar[str] = QUESTION_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        _version(self.schema_version, QUESTION_SCHEMA_VERSION, "question.schema_version")
+        _identifier(self.question_id, "question.question_id")
+        _text(self.text, "question.text", minimum=1, maximum=12_000)
+        _utc_timestamp(self.created_at, "question.created_at")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "question_id": self.question_id,
+            "text": self.text,
+            "created_at": self.created_at,
+        }
+
+    @classmethod
+    def from_value(cls, value: Any) -> LocalQuestion:
+        data = _object(value, "question")
+        _exact_fields(data, _QUESTION_FIELDS, "question")
+        return cls(
+            schema_version=_required_text(
+                data["schema_version"],
+                "question.schema_version",
+                maximum=64,
+            ),
+            question_id=_required_text(
+                data["question_id"],
+                "question.question_id",
+                maximum=MAX_IDENTIFIER_LENGTH,
+            ),
+            text=_required_text(data["text"], "question.text", maximum=12_000),
+            created_at=_required_text(
+                data["created_at"],
+                "question.created_at",
+                maximum=32,
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class OutputGrain(_CanonicalContract):
+    """Ordered local output key definition."""
+
+    columns: tuple[str, ...]
+    description: str
+    schema_version: str = OUTPUT_GRAIN_SCHEMA_VERSION
+
+    EXPECTED_SCHEMA_VERSION: ClassVar[str] = OUTPUT_GRAIN_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        _version(
+            self.schema_version,
+            OUTPUT_GRAIN_SCHEMA_VERSION,
+            "output_grain.schema_version",
+        )
+        _column_tuple(
+            self.columns,
+            "output_grain.columns",
+            nonempty=True,
+            maximum=16,
+        )
+        _text(
+            self.description,
+            "output_grain.description",
+            minimum=1,
+            maximum=1_000,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "columns": list(self.columns),
+            "description": self.description,
+        }
+
+    @classmethod
+    def from_value(cls, value: Any, path: str = "output_grain") -> OutputGrain:
+        data = _object(value, path)
+        _exact_fields(data, {"schema_version", "columns", "description"}, path)
+        return cls(
+            schema_version=_required_text(
+                data["schema_version"],
+                f"{path}.schema_version",
+                maximum=64,
+            ),
+            columns=_parse_column_array(
+                data["columns"],
+                f"{path}.columns",
+                nonempty=True,
+                maximum=16,
+            ),
+            description=_required_text(
+                data["description"],
+                f"{path}.description",
+                maximum=1_000,
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class TimeRange:
+    """A half-open UTC time range used by private requirements and proposals."""
+
+    start_inclusive: str
+    end_exclusive: str
+
+    def __post_init__(self) -> None:
+        start = _utc_timestamp(self.start_inclusive, "time_range.start_inclusive")
+        end = _utc_timestamp(self.end_exclusive, "time_range.end_exclusive")
+        if start >= end:
+            raise ContractError(
+                "time_range.end_exclusive",
+                "RANGE_ORDER",
+                "must be later than time_range.start_inclusive",
+            )
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "start_inclusive": self.start_inclusive,
+            "end_exclusive": self.end_exclusive,
+        }
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> TimeRange:
+        data = _object(value, path)
+        _exact_fields(data, {"start_inclusive", "end_exclusive"}, path)
+        start = _required_text(
+            data["start_inclusive"],
+            f"{path}.start_inclusive",
+            maximum=32,
+        )
+        end = _required_text(
+            data["end_exclusive"],
+            f"{path}.end_exclusive",
+            maximum=32,
+        )
+        try:
+            return cls(start_inclusive=start, end_exclusive=end)
+        except ContractError as exc:
+            if exc.path.startswith("time_range."):
+                suffix = exc.path.removeprefix("time_range.")
+                raise ContractError(f"{path}.{suffix}", exc.code, exc.detail) from None
+            raise
+
+
+@dataclass(frozen=True)
+class Feasibility:
+    """Deterministically bounded feasibility proposal."""
+
+    decision: str
+    reason_codes: tuple[str, ...]
+    narrative: str
+
+    def __post_init__(self) -> None:
+        _choice(self.decision, _FEASIBILITY_DECISIONS, "feasibility.decision")
+        _choice_tuple(
+            self.reason_codes,
+            _FEASIBILITY_REASONS,
+            "feasibility.reason_codes",
+            maximum=16,
+        )
+        _text(
+            self.narrative,
+            "feasibility.narrative",
+            minimum=1,
+            maximum=4_000,
+        )
+        if self.decision == "supportable" and "sufficient_evidence" not in self.reason_codes:
+            raise ContractError(
+                "feasibility.reason_codes",
+                "MISSING_REASON",
+                "supportable feasibility requires sufficient_evidence",
+            )
+        if self.decision == "unsupported" and not self.reason_codes:
+            raise ContractError(
+                "feasibility.reason_codes",
+                "EMPTY_COLLECTION",
+                "unsupported feasibility requires at least one reason code",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "decision": self.decision,
+            "reason_codes": list(self.reason_codes),
+            "narrative": self.narrative,
+        }
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> Feasibility:
+        data = _object(value, path)
+        _exact_fields(data, {"decision", "reason_codes", "narrative"}, path)
+        try:
+            return cls(
+                decision=_required_text(
+                    data["decision"],
+                    f"{path}.decision",
+                    maximum=64,
+                ),
+                reason_codes=_parse_choice_array(
+                    data["reason_codes"],
+                    f"{path}.reason_codes",
+                    _FEASIBILITY_REASONS,
+                    nonempty=False,
+                    maximum=16,
+                ),
+                narrative=_required_text(
+                    data["narrative"],
+                    f"{path}.narrative",
+                    maximum=4_000,
+                ),
+            )
+        except ContractError as exc:
+            if exc.path.startswith("feasibility."):
+                suffix = exc.path.removeprefix("feasibility.")
+                raise ContractError(f"{path}.{suffix}", exc.code, exc.detail) from None
+            raise
+
+
+@dataclass(frozen=True)
+class LocalRequirements(_CanonicalContract):
+    """Question-derived local dataset requirements."""
+
+    requirements_id: str
+    question_id: str
+    population: str
+    time_range: TimeRange
+    output_grain: OutputGrain
+    required_fields: tuple[str, ...]
+    target_policy: str
+    success_criteria: tuple[str, ...]
+    feasibility: Feasibility
+    created_at: str
+    schema_version: str = REQUIREMENTS_SCHEMA_VERSION
+
+    EXPECTED_SCHEMA_VERSION: ClassVar[str] = REQUIREMENTS_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        _version(
+            self.schema_version,
+            REQUIREMENTS_SCHEMA_VERSION,
+            "requirements.schema_version",
+        )
+        _identifier(self.requirements_id, "requirements.requirements_id")
+        _identifier(self.question_id, "requirements.question_id")
+        _text(
+            self.population,
+            "requirements.population",
+            minimum=1,
+            maximum=MAX_SHORT_TEXT_LENGTH,
+        )
+        if not isinstance(self.time_range, TimeRange):
+            raise ContractError(
+                "requirements.time_range",
+                "TYPE",
+                "must be a TimeRange",
+            )
+        if not isinstance(self.output_grain, OutputGrain):
+            raise ContractError(
+                "requirements.output_grain",
+                "TYPE",
+                "must be an OutputGrain",
+            )
+        _column_tuple(
+            self.required_fields,
+            "requirements.required_fields",
+            nonempty=True,
+            maximum=MAX_COLUMN_COUNT,
+        )
+        missing_grain = set(self.output_grain.columns) - set(self.required_fields)
+        if missing_grain:
+            raise ContractError(
+                "requirements.required_fields",
+                "GRAIN_FIELD_MISSING",
+                f"must contain output-grain columns {sorted(missing_grain)}",
+            )
+        _choice(self.target_policy, _TARGET_POLICIES, "requirements.target_policy")
+        _text_tuple(
+            self.success_criteria,
+            "requirements.success_criteria",
+            nonempty=True,
+            maximum=64,
+            item_maximum=1_000,
+        )
+        if not isinstance(self.feasibility, Feasibility):
+            raise ContractError(
+                "requirements.feasibility",
+                "TYPE",
+                "must be Feasibility",
+            )
+        _utc_timestamp(self.created_at, "requirements.created_at")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "requirements_id": self.requirements_id,
+            "question_id": self.question_id,
+            "population": self.population,
+            "time_range": self.time_range.to_dict(),
+            "output_grain": self.output_grain.to_dict(),
+            "required_fields": list(self.required_fields),
+            "target_policy": self.target_policy,
+            "success_criteria": list(self.success_criteria),
+            "feasibility": self.feasibility.to_dict(),
+            "created_at": self.created_at,
+        }
+
+    @classmethod
+    def from_value(cls, value: Any) -> LocalRequirements:
+        path = "requirements"
+        data = _object(value, path)
+        _exact_fields(
+            data,
+            {
+                "schema_version",
+                "requirements_id",
+                "question_id",
+                "population",
+                "time_range",
+                "output_grain",
+                "required_fields",
+                "target_policy",
+                "success_criteria",
+                "feasibility",
+                "created_at",
+            },
+            path,
+        )
+        return cls(
+            schema_version=_required_text(
+                data["schema_version"],
+                f"{path}.schema_version",
+                maximum=64,
+            ),
+            requirements_id=_required_text(
+                data["requirements_id"],
+                f"{path}.requirements_id",
+                maximum=MAX_IDENTIFIER_LENGTH,
+            ),
+            question_id=_required_text(
+                data["question_id"],
+                f"{path}.question_id",
+                maximum=MAX_IDENTIFIER_LENGTH,
+            ),
+            population=_required_text(
+                data["population"],
+                f"{path}.population",
+                maximum=MAX_SHORT_TEXT_LENGTH,
+            ),
+            time_range=TimeRange.from_value(data["time_range"], f"{path}.time_range"),
+            output_grain=OutputGrain.from_value(
+                data["output_grain"],
+                f"{path}.output_grain",
+            ),
+            required_fields=_parse_column_array(
+                data["required_fields"],
+                f"{path}.required_fields",
+                nonempty=True,
+                maximum=MAX_COLUMN_COUNT,
+            ),
+            target_policy=_required_text(
+                data["target_policy"],
+                f"{path}.target_policy",
+                maximum=64,
+            ),
+            success_criteria=_parse_text_array(
+                data["success_criteria"],
+                f"{path}.success_criteria",
+                nonempty=True,
+                maximum=64,
+                item_maximum=1_000,
+            ),
+            feasibility=Feasibility.from_value(data["feasibility"], f"{path}.feasibility"),
+            created_at=_required_text(
+                data["created_at"],
+                f"{path}.created_at",
+                maximum=32,
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class EvidenceReference:
+    """One immutable, non-secret source-proposal evidence reference."""
+
+    uri: str
+    observed_at: str
+    content_sha256: str
+
+    def __post_init__(self) -> None:
+        _evidence_uri(self.uri, "evidence.uri")
+        _utc_timestamp(self.observed_at, "evidence.observed_at")
+        _sha256(self.content_sha256, "evidence.content_sha256")
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "uri": self.uri,
+            "observed_at": self.observed_at,
+            "content_sha256": self.content_sha256,
+        }
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> EvidenceReference:
+        data = _object(value, path)
+        _exact_fields(data, {"uri", "observed_at", "content_sha256"}, path)
+        try:
+            return cls(
+                uri=_required_text(data["uri"], f"{path}.uri", maximum=2_048),
+                observed_at=_required_text(
+                    data["observed_at"],
+                    f"{path}.observed_at",
+                    maximum=32,
+                ),
+                content_sha256=_required_text(
+                    data["content_sha256"],
+                    f"{path}.content_sha256",
+                    maximum=64,
+                ),
+            )
+        except ContractError as exc:
+            if exc.path.startswith("evidence."):
+                suffix = exc.path.removeprefix("evidence.")
+                raise ContractError(f"{path}.{suffix}", exc.code, exc.detail) from None
+            raise
+
+
+@dataclass(frozen=True)
+class SourceProposal(_CanonicalContract):
+    """A bounded agent proposal; it is never an acquisition authorization."""
+
+    proposal_id: str
+    question_id: str
+    source_id: str
+    source_class: str
+    display_name: str
+    locator_kind: str
+    locator: str
+    data_format: str
+    observed_at: str
+    historical_coverage: TimeRange
+    live_endpoint: str
+    publication_delay_seconds: int
+    rights_status: str
+    fitness_decision: str
+    evidence: tuple[EvidenceReference, ...]
+    schema_version: str = SOURCE_PROPOSAL_SCHEMA_VERSION
+
+    EXPECTED_SCHEMA_VERSION: ClassVar[str] = SOURCE_PROPOSAL_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        _version(
+            self.schema_version,
+            SOURCE_PROPOSAL_SCHEMA_VERSION,
+            "source_proposal.schema_version",
+        )
+        _identifier(self.proposal_id, "source_proposal.proposal_id")
+        _identifier(self.question_id, "source_proposal.question_id")
+        _identifier(self.source_id, "source_proposal.source_id")
+        _choice(self.source_class, _SOURCE_CLASSES, "source_proposal.source_class")
+        _text(
+            self.display_name,
+            "source_proposal.display_name",
+            minimum=1,
+            maximum=200,
+        )
+        _choice(self.locator_kind, _LOCATOR_KINDS, "source_proposal.locator_kind")
+        validate_source_locator(self.locator, self.locator_kind, "source_proposal.locator")
+        _choice(self.data_format, _DATA_FORMATS, "source_proposal.data_format")
+        _utc_timestamp(self.observed_at, "source_proposal.observed_at")
+        if not isinstance(self.historical_coverage, TimeRange):
+            raise ContractError(
+                "source_proposal.historical_coverage",
+                "TYPE",
+                "must be a TimeRange",
+            )
+        _choice(self.live_endpoint, _LIVE_ENDPOINTS, "source_proposal.live_endpoint")
+        _bounded_int(
+            self.publication_delay_seconds,
+            "source_proposal.publication_delay_seconds",
+            minimum=0,
+            maximum=10 * 365 * 24 * 60 * 60,
+        )
+        _choice(self.rights_status, _PROPOSAL_RIGHTS, "source_proposal.rights_status")
+        _choice(
+            self.fitness_decision,
+            _FITNESS_DECISIONS,
+            "source_proposal.fitness_decision",
+        )
+        _typed_tuple(
+            self.evidence,
+            EvidenceReference,
+            "source_proposal.evidence",
+            nonempty=True,
+            maximum=MAX_EVIDENCE_COUNT,
+        )
+        evidence_keys = tuple(
+            (item.uri, item.observed_at, item.content_sha256) for item in self.evidence
+        )
+        _require_unique(evidence_keys, "source_proposal.evidence")
+        if self.fitness_decision == "selected" and self.rights_status not in {
+            "approved",
+            "conditional",
+        }:
+            raise ContractError(
+                "source_proposal.rights_status",
+                "RIGHTS_NOT_SELECTABLE",
+                "selected proposals require approved or conditional rights",
+            )
+        if self.fitness_decision == "selected" and self.live_endpoint in {"dead", "delayed"}:
+            raise ContractError(
+                "source_proposal.live_endpoint",
+                "ENDPOINT_NOT_SELECTABLE",
+                "selected proposals cannot have a dead or delayed endpoint",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "proposal_id": self.proposal_id,
+            "question_id": self.question_id,
+            "source_id": self.source_id,
+            "source_class": self.source_class,
+            "display_name": self.display_name,
+            "locator_kind": self.locator_kind,
+            "locator": self.locator,
+            "data_format": self.data_format,
+            "observed_at": self.observed_at,
+            "historical_coverage": self.historical_coverage.to_dict(),
+            "live_endpoint": self.live_endpoint,
+            "publication_delay_seconds": self.publication_delay_seconds,
+            "rights_status": self.rights_status,
+            "fitness_decision": self.fitness_decision,
+            "evidence": [item.to_dict() for item in self.evidence],
+        }
+
+    @classmethod
+    def from_value(cls, value: Any) -> SourceProposal:
+        path = "source_proposal"
+        data = _object(value, path)
+        _exact_fields(
+            data,
+            {
+                "schema_version",
+                "proposal_id",
+                "question_id",
+                "source_id",
+                "source_class",
+                "display_name",
+                "locator_kind",
+                "locator",
+                "data_format",
+                "observed_at",
+                "historical_coverage",
+                "live_endpoint",
+                "publication_delay_seconds",
+                "rights_status",
+                "fitness_decision",
+                "evidence",
+            },
+            path,
+        )
+        evidence = tuple(
+            EvidenceReference.from_value(item, f"{path}.evidence[{index}]")
+            for index, item in enumerate(
+                _array(
+                    data["evidence"],
+                    f"{path}.evidence",
+                    nonempty=True,
+                    maximum=MAX_EVIDENCE_COUNT,
+                )
+            )
+        )
+        return cls(
+            schema_version=_required_text(
+                data["schema_version"],
+                f"{path}.schema_version",
+                maximum=64,
+            ),
+            proposal_id=_required_text(
+                data["proposal_id"],
+                f"{path}.proposal_id",
+                maximum=MAX_IDENTIFIER_LENGTH,
+            ),
+            question_id=_required_text(
+                data["question_id"],
+                f"{path}.question_id",
+                maximum=MAX_IDENTIFIER_LENGTH,
+            ),
+            source_id=_required_text(
+                data["source_id"],
+                f"{path}.source_id",
+                maximum=MAX_IDENTIFIER_LENGTH,
+            ),
+            source_class=_required_text(
+                data["source_class"],
+                f"{path}.source_class",
+                maximum=64,
+            ),
+            display_name=_required_text(
+                data["display_name"],
+                f"{path}.display_name",
+                maximum=200,
+            ),
+            locator_kind=_required_text(
+                data["locator_kind"],
+                f"{path}.locator_kind",
+                maximum=64,
+            ),
+            locator=_required_text(
+                data["locator"],
+                f"{path}.locator",
+                maximum=MAX_PATH_LENGTH,
+            ),
+            data_format=_required_text(
+                data["data_format"],
+                f"{path}.data_format",
+                maximum=64,
+            ),
+            observed_at=_required_text(
+                data["observed_at"],
+                f"{path}.observed_at",
+                maximum=32,
+            ),
+            historical_coverage=TimeRange.from_value(
+                data["historical_coverage"],
+                f"{path}.historical_coverage",
+            ),
+            live_endpoint=_required_text(
+                data["live_endpoint"],
+                f"{path}.live_endpoint",
+                maximum=64,
+            ),
+            publication_delay_seconds=_integer(
+                data["publication_delay_seconds"],
+                f"{path}.publication_delay_seconds",
+            ),
+            rights_status=_required_text(
+                data["rights_status"],
+                f"{path}.rights_status",
+                maximum=64,
+            ),
+            fitness_decision=_required_text(
+                data["fitness_decision"],
+                f"{path}.fitness_decision",
+                maximum=64,
+            ),
+            evidence=evidence,
+        )
+
+
+@dataclass(frozen=True)
+class RightsSpec:
+    """The rights basis claimed for one source and the uses it permits."""
+
+    status: str
+    evidence: str
+    permissions: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        _choice(self.status, _RIGHTS_STATUSES, "rights.status")
+        _text(self.evidence, "rights.evidence", minimum=1, maximum=MAX_TEXT_LENGTH)
+        _choice_tuple(
+            self.permissions,
+            _PERMISSIONS,
+            "rights.permissions",
+            maximum=len(_PERMISSIONS),
+            nonempty=True,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "evidence": self.evidence,
+            "permissions": list(self.permissions),
+        }
+
+
+@dataclass(frozen=True)
+class SourceSpec:
+    """One input file the build reads.
+
+    Carries the source identifier, the path relative to the build input root, the format,
+    the stated origin, how the file was acquired, and the rights it is read under.
+    """
+
+    source_id: str
+    path: str
+    format: str
+    origin: str
+    acquisition_method: str
+    rights: RightsSpec
+
+    def __post_init__(self) -> None:
+        _identifier(self.source_id, "source.id")
+        _relative_posix_path(self.path, "source.path")
+        # Build input encoding, narrower than _DATA_FORMATS; see sources/contracts.py.
+        _choice(self.format, frozenset({"csv"}), "source.format")
+        _text(self.origin, "source.origin", minimum=1, maximum=4_000)
+        _choice(
+            self.acquisition_method,
+            _ACQUISITION_METHODS,
+            "source.acquisition_method",
+        )
+        if not isinstance(self.rights, RightsSpec):
+            raise ContractError("source.rights", "TYPE", "must be a RightsSpec")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.source_id,
+            "path": self.path,
+            "format": self.format,
+            "origin": self.origin,
+            "acquisition_method": self.acquisition_method,
+            "rights": self.rights.to_dict(),
+        }
+
+
+@dataclass(frozen=True)
+class CleaningStep:
+    """One cleaning operation applied to named columns of one source.
+
+    ``trim`` and ``empty_to_null`` take plain column names. ``rename`` and ``cast`` take
+    ``(column, target)`` pairs, where the target is the new column name or the cast type.
+    """
+
+    source_id: str
+    operation: str
+    columns: tuple[str, ...] | tuple[tuple[str, str], ...]
+
+    def __post_init__(self) -> None:
+        _identifier(self.source_id, "cleaning.source")
+        _choice(self.operation, _CLEANING_OPERATIONS, "cleaning.operation")
+        if not isinstance(self.columns, tuple) or not self.columns:
+            raise ContractError(
+                "cleaning.columns",
+                "TYPE",
+                "must be a non-empty immutable tuple",
+            )
+        if self.operation in {"trim", "empty_to_null"}:
+            _column_tuple(
+                self.columns,
+                "cleaning.columns",
+                nonempty=True,
+                maximum=MAX_COLUMN_COUNT,
+            )
+            return
+        pairs = self.columns
+        if len(pairs) > MAX_COLUMN_COUNT:
+            raise ContractError(
+                "cleaning.columns",
+                "COLLECTION_LIMIT",
+                f"exceeds {MAX_COLUMN_COUNT} entries",
+            )
+        sources: list[str] = []
+        targets: list[str] = []
+        for index, pair in enumerate(pairs):
+            if (
+                not isinstance(pair, tuple)
+                or len(pair) != 2
+                or not all(isinstance(item, str) for item in pair)
+            ):
+                raise ContractError(
+                    f"cleaning.columns[{index}]",
+                    "TYPE",
+                    "must be a (column, value) string pair",
+                )
+            source, target = pair
+            _column_name(source, f"cleaning.columns[{index}].source")
+            if self.operation == "rename":
+                _column_name(target, f"cleaning.columns[{index}].target")
+            else:
+                _choice(target, _CAST_TYPES, f"cleaning.columns[{index}].type")
+            sources.append(source)
+            targets.append(target)
+        _require_unique(sources, "cleaning.columns.sources")
+        if self.operation == "rename":
+            _require_unique(targets, "cleaning.columns.targets")
+
+    def to_dict(self) -> dict[str, Any]:
+        columns: Any
+        if self.operation in {"rename", "cast"}:
+            columns = dict(self.columns)
+        else:
+            columns = list(self.columns)
+        return {
+            "source": self.source_id,
+            "operation": self.operation,
+            "columns": columns,
+        }
+
+
+@dataclass(frozen=True)
+class JoinSpec:
+    """The single join a v1 plan performs.
+
+    Names two distinct sources, the key columns, the join kind, and the cardinality. The
+    build enforces the declared cardinality rather than inferring it.
+
+    ``kind`` is ``left`` and stays ``left``, while the graph vocabulary carries ``left``, ``inner``
+    and ``anti``. That is a settled ruling rather than an omission or a pending edit, and
+    ``docs/TRANSFORMS.md`` records it. ``pipeline._join`` refuses the first unmatched left row and
+    any row multiplier other than one, unconditionally, because a v1 plan has no way to declare
+    anything else.
+
+    Under that rule ``inner`` cannot differ from ``left`` by a single row, so it would be a second
+    spelling of one behaviour: two names an author would have to choose between with nothing to
+    choose on, and no capability behind either. Admitting it would touch no digest, which makes it
+    cheap rather than worth doing.
+
+    ``anti`` is the stronger case, and it starts from the fact that nothing here dispatches on
+    ``kind`` at all. ``pipeline._join`` and both backends ignore it; its only reader in the whole
+    software is ``ux.approve._join_sentence``, which renders it into the sentence a person is shown
+    before approving. So widening this set alone would neither produce an anti join nor refuse one:
+    the run would be the left join it always was, the word would be sealed into the plan bytes, and
+    the approval sentence would say ``(anti join)`` about a result that is nothing of the kind.
+    That is fail-open, and it lands on the one surface a person is asked to read.
+
+    Making the kind mean what it says requires withdrawing the v1 rule, because an anti join's
+    output is exactly the rows that rule refuses. That rule is named in the ``mandatory_gates``
+    list ``validation_policy_digest`` hashes, which every approved v1 Recipe is bound to.
+    Withdrawing a name retires all of them; leaving the name in place while changing what it
+    governs would silently change what they meant, which is worse.
+
+    Plans that need those kinds use the ``local-graph-table-plan.v1`` graph, where the join is a
+    node carrying its own declared ``unmatched_policy`` and the same question is answered per node.
+    """
+
+    left: str
+    right: str
+    on: tuple[str, ...]
+    kind: str
+    cardinality: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.left, "join.left")
+        _identifier(self.right, "join.right")
+        if self.left == self.right:
+            raise ContractError("join.right", "SAME_SOURCE", "must differ from join.left")
+        _column_tuple(self.on, "join.on", nonempty=True, maximum=16)
+        _choice(self.kind, JOIN_KINDS, "join.kind")
+        _choice(self.cardinality, _JOIN_CARDINALITIES, "join.cardinality")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "left": self.left,
+            "right": self.right,
+            "on": list(self.on),
+            "kind": self.kind,
+            "cardinality": self.cardinality,
+        }
+
+
+@dataclass(frozen=True)
+class QualitySpec:
+    """The gates the joined output must pass.
+
+    A minimum row count, plus the columns that must contain no nulls.
+    """
+
+    min_rows: int
+    not_null: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        _bounded_int(
+            self.min_rows,
+            "quality.min_rows",
+            minimum=1,
+            maximum=GRAPH_MAX_OUTPUT_ROWS,
+        )
+        _column_tuple(
+            self.not_null,
+            "quality.not_null",
+            nonempty=False,
+            maximum=MAX_COLUMN_COUNT,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"min_rows": self.min_rows, "not_null": list(self.not_null)}
+
+
+@dataclass(frozen=True)
+class SemanticEvidenceRef:
+    """A bounded pointer to one source sealed alongside a semantic claim."""
+
+    kind: str
+    ref: str
+
+    def __post_init__(self) -> None:
+        _choice(self.kind, SEMANTIC_EVIDENCE_KINDS, "semantics.columns.evidence_refs.kind")
+        _text(
+            self.ref,
+            "semantics.columns.evidence_refs.ref",
+            minimum=1,
+            maximum=128,
+        )
+        _identifier(self.ref, "semantics.columns.evidence_refs.ref")
+
+    def to_dict(self) -> dict[str, str]:
+        return {"kind": self.kind, "ref": self.ref}
+
+
+@dataclass(frozen=True)
+class CategoryDefinition:
+    """One bounded code-to-label definition from declared source semantics."""
+
+    code: str
+    label: str
+
+    def __post_init__(self) -> None:
+        _text(self.code, "semantics.columns.categories.code", minimum=1, maximum=64)
+        _text(self.label, "semantics.columns.categories.label", minimum=1, maximum=120)
+        if not is_single_plain_line(self.code) or not is_single_plain_line(self.label):
+            raise ContractError(
+                "semantics.columns.categories",
+                "NONCANONICAL_TEXT",
+                "codes and labels must each be one plain line",
+            )
+
+    def to_dict(self) -> dict[str, str]:
+        return {"code": self.code, "label": self.label}
+
+
+@dataclass(frozen=True)
+class SemanticCoverage:
+    """Declared dataset coverage without inferred temporal or population facts."""
+
+    start_inclusive: str | None
+    end_exclusive: str | None
+    population: str
+    completeness_note: str
+
+    def __post_init__(self) -> None:
+        if (self.start_inclusive is None) != (self.end_exclusive is None):
+            raise ContractError(
+                "semantics.coverage.time_range",
+                "FIELDS",
+                "start_inclusive and end_exclusive must both be set or both be null",
+            )
+        for name, value in (
+            ("start_inclusive", self.start_inclusive),
+            ("end_exclusive", self.end_exclusive),
+        ):
+            if value is not None:
+                _text(value, f"semantics.coverage.time_range.{name}", minimum=1, maximum=128)
+                if not is_single_plain_line(value):
+                    raise ContractError(
+                        f"semantics.coverage.time_range.{name}",
+                        "NONCANONICAL_TEXT",
+                        "must be one plain line",
+                    )
+        _text(self.population, "semantics.coverage.population", minimum=1, maximum=2_000)
+        _text(
+            self.completeness_note,
+            "semantics.coverage.completeness_note",
+            minimum=1,
+            maximum=1_000,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "time_range": None
+            if self.start_inclusive is None
+            else {
+                "start_inclusive": self.start_inclusive,
+                "end_exclusive": self.end_exclusive,
+            },
+            "population": self.population,
+            "completeness_note": self.completeness_note,
+        }
+
+
+@dataclass(frozen=True)
+class ColumnSemantics:
+    """Sealed human-readable meaning of exactly one selected physical column."""
+
+    name: str
+    display_label: str
+    description: str
+    semantic_type: str
+    unit: str
+    unit_state: str
+    normalization: str | None
+    reversible: bool | None
+    categories: tuple[CategoryDefinition, ...] | None
+    categories_status: str
+    evidence_refs: tuple[SemanticEvidenceRef, ...]
+
+    def __post_init__(self) -> None:
+        _column_name(self.name, "semantics.columns.name")
+        _text(self.display_label, "semantics.columns.display_label", minimum=1, maximum=120)
+        if not is_single_plain_line(self.display_label):
+            raise ContractError(
+                "semantics.columns.display_label",
+                "NONCANONICAL_TEXT",
+                "must be one plain line",
+            )
+        _text(self.description, "semantics.columns.description", minimum=1, maximum=1_000)
+        _choice(self.semantic_type, SEMANTIC_TYPES, "semantics.columns.semantic_type")
+        resolved = _declared_unit(self.unit, "semantics.columns.unit")
+        _choice(self.unit_state, UNIT_STATES, "semantics.columns.unit_state")
+        if self.normalization is not None:
+            _choice(
+                self.normalization,
+                NORMALIZATIONS,
+                "semantics.columns.normalization",
+            )
+        if self.reversible is not None and type(self.reversible) is not bool:
+            raise ContractError("semantics.columns.reversible", "TYPE", "must be a boolean or null")
+
+        if self.unit_state == "declared":
+            if (
+                self.unit == NO_UNIT
+                or self.normalization is not None
+                or self.reversible is not None
+            ):
+                raise ContractError(
+                    "semantics.columns.unit_state",
+                    "ENUM",
+                    "declared units require a physical unit and no normalization fields",
+                )
+        elif self.unit_state == "normalized":
+            if (
+                self.unit != NO_UNIT
+                or self.normalization is None
+                or type(self.reversible) is not bool
+            ):
+                raise ContractError(
+                    "semantics.columns.unit_state",
+                    "ENUM",
+                    "normalized values require unit none, a normalization, and reversible boolean",
+                )
+        elif self.unit != NO_UNIT or self.normalization is not None or self.reversible is not None:
+            raise ContractError(
+                "semantics.columns.unit_state",
+                "ENUM",
+                "not_applicable and unknown require unit none and no normalization fields",
+            )
+        if self.semantic_type == "measure" and self.unit_state == "not_applicable":
+            raise ContractError(
+                "semantics.columns.unit_state",
+                "ENUM",
+                "measure fields require a declared, normalized, or unknown unit state",
+            )
+        # The rule is about the unit rather than about the spelling of it. ``count`` and
+        # ``{count}`` are one unit under two names, and a dimensionless ratio is a different one,
+        # so the question asked here is which unit the code resolved to.
+        if (
+            self.semantic_type not in {"measure", "target"}
+            and self.unit_state == "declared"
+            and resolved is not None
+            and not is_count_unit(resolved)
+        ):
+            raise ContractError(
+                "semantics.columns.unit",
+                "ENUM",
+                "non-measure and non-target fields may declare only count units",
+            )
+
+        _choice(
+            self.categories_status,
+            CATEGORY_STATUSES,
+            "semantics.columns.categories_status",
+        )
+        if self.categories is not None:
+            _typed_tuple(
+                self.categories,
+                CategoryDefinition,
+                "semantics.columns.categories",
+                nonempty=True,
+                maximum=64,
+            )
+            _require_unique(
+                (item.code for item in self.categories),
+                "semantics.columns.categories.code",
+            )
+        if self.categories_status in {"complete", "partial"} and not self.categories:
+            raise ContractError(
+                "semantics.columns.categories",
+                "ENUM",
+                "complete or partial category status requires definitions",
+            )
+        if self.categories_status in {"not_applicable", "unknown"} and self.categories is not None:
+            raise ContractError(
+                "semantics.columns.categories",
+                "ENUM",
+                "not_applicable or unknown category status cannot carry definitions",
+            )
+        _typed_tuple(
+            self.evidence_refs,
+            SemanticEvidenceRef,
+            "semantics.columns.evidence_refs",
+            nonempty=True,
+            maximum=8,
+        )
+        _require_unique(
+            ((item.kind, item.ref) for item in self.evidence_refs),
+            "semantics.columns.evidence_refs",
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "display_label": self.display_label,
+            "description": self.description,
+            "semantic_type": self.semantic_type,
+            "unit": self.unit,
+            "unit_state": self.unit_state,
+            "normalization": self.normalization,
+            "reversible": self.reversible,
+            "categories": None
+            if self.categories is None
+            else [item.to_dict() for item in sorted(self.categories, key=lambda item: item.code)],
+            "categories_status": self.categories_status,
+            "evidence_refs": [
+                item.to_dict()
+                for item in sorted(self.evidence_refs, key=lambda item: (item.kind, item.ref))
+            ],
+        }
+
+
+@dataclass(frozen=True)
+class TableSemantics(_CanonicalContract):
+    """One complete, digestable semantic document for a selected Table shape."""
+
+    summary: str
+    grain_statement: str
+    coverage: SemanticCoverage
+    limitations: tuple[str, ...]
+    columns: tuple[ColumnSemantics, ...]
+    schema_version: str = TABLE_SEMANTICS_VERSION
+
+    EXPECTED_SCHEMA_VERSION: ClassVar[str] = TABLE_SEMANTICS_VERSION
+
+    def __post_init__(self) -> None:
+        _choice_version(self.schema_version, TABLE_SEMANTICS_VERSIONS, "semantics.schema_version")
+        _text(self.summary, "semantics.summary", minimum=1, maximum=1_000)
+        _text(self.grain_statement, "semantics.grain_statement", minimum=1, maximum=400)
+        if not isinstance(self.coverage, SemanticCoverage):
+            raise ContractError("semantics.coverage", "TYPE", "must be SemanticCoverage")
+        _text_tuple(
+            self.limitations,
+            "semantics.limitations",
+            nonempty=False,
+            maximum=32,
+            item_maximum=1_000,
+        )
+        _typed_tuple(
+            self.columns,
+            ColumnSemantics,
+            "semantics.columns",
+            nonempty=True,
+            maximum=MAX_COLUMN_COUNT,
+        )
+        _require_unique((item.name for item in self.columns), "semantics.columns.name")
+        if self.schema_version == TABLE_SEMANTICS_V1:
+            # The first generation's vocabulary is closed and stays closed. Widening it in place
+            # would rewrite what a sealed document meant, which is the one thing a version is for.
+            for index, column in enumerate(self.columns):
+                if column.unit not in UNITS:
+                    raise ContractError(
+                        f"semantics.columns[{index}].unit",
+                        "UNIT_UNSUPPORTED_IN_VERSION",
+                        f"{TABLE_SEMANTICS_V1} carries only {sorted(UNITS)}; a unit code "
+                        f"requires {TABLE_SEMANTICS_V2}",
+                    )
+
+    def validate_for_select(self, select: tuple[str, ...]) -> None:
+        if tuple(item.name for item in self.columns) != select:
+            raise ContractError(
+                "semantics.columns",
+                "REFERENCE_MISMATCH",
+                "must follow the exact selected-column order",
+            )
+
+    def validate_for_sources(self, source_ids: tuple[str, ...]) -> None:
+        """Bind every semantic citation to a source in the sealed plan/Recipe."""
+
+        allowed = frozenset(source_ids)
+        for column in self.columns:
+            for evidence in column.evidence_refs:
+                if evidence.ref not in allowed:
+                    raise ContractError(
+                        "semantics.columns.evidence_refs.ref",
+                        "REFERENCE_MISMATCH",
+                        "must reference a source sealed in the same plan or Recipe",
+                    )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "summary": self.summary,
+            "grain_statement": self.grain_statement,
+            "coverage": self.coverage.to_dict(),
+            "limitations": list(self.limitations),
+            "columns": [item.to_dict() for item in self.columns],
+        }
+
+
+@dataclass(frozen=True)
+class TablePlan(_CanonicalContract):
+    """The complete plan a build executes.
+
+    Names the question, the output intent, the output grain, at least two sources, the
+    cleaning steps, exactly one join, the selected output columns, and the quality gates.
+    The output intent is one of ``local_use``, ``redistribute``, or ``host``, and it gates
+    the rights check: a build refuses unless every source permits that intent. The plan is
+    closed: a build derives every derived member from this value and the raw source bytes
+    alone, which is what lets verification replay the derivation and compare bytes.
+    """
+
+    question: str
+    output_intent: str
+    grain: tuple[str, ...]
+    sources: tuple[SourceSpec, ...]
+    cleaning: tuple[CleaningStep, ...]
+    join: JoinSpec
+    select: tuple[str, ...]
+    quality: QualitySpec
+    schema_version: str = PLAN_SCHEMA_VERSION
+
+    EXPECTED_SCHEMA_VERSION: ClassVar[str] = PLAN_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        _version(self.schema_version, PLAN_SCHEMA_VERSION, "plan.schema_version")
+        _text(self.question, "plan.question", minimum=1, maximum=MAX_TEXT_LENGTH)
+        _choice(self.output_intent, _OUTPUT_INTENTS, "plan.output_intent")
+        _column_tuple(self.grain, "plan.grain", nonempty=True, maximum=16)
+        _typed_tuple(
+            self.sources,
+            SourceSpec,
+            "plan.sources",
+            nonempty=True,
+            minimum=2,
+            maximum=MAX_SOURCE_COUNT,
+        )
+        source_ids = tuple(source.source_id for source in self.sources)
+        _require_unique(source_ids, "plan.sources.id")
+        _typed_tuple(
+            self.cleaning,
+            CleaningStep,
+            "plan.cleaning",
+            nonempty=False,
+            maximum=MAX_OPERATION_COUNT,
+        )
+        unknown_cleaning_sources = sorted(
+            {step.source_id for step in self.cleaning} - set(source_ids)
+        )
+        if unknown_cleaning_sources:
+            raise ContractError(
+                "plan.cleaning",
+                "UNKNOWN_SOURCE",
+                f"references unknown sources {unknown_cleaning_sources}",
+            )
+        if not isinstance(self.join, JoinSpec):
+            raise ContractError("plan.join", "TYPE", "must be a JoinSpec")
+        if self.join.left not in source_ids:
+            raise ContractError("plan.join.left", "UNKNOWN_SOURCE", "is not in plan.sources")
+        if self.join.right not in source_ids:
+            raise ContractError("plan.join.right", "UNKNOWN_SOURCE", "is not in plan.sources")
+        _column_tuple(
+            self.select,
+            "plan.select",
+            nonempty=True,
+            maximum=MAX_COLUMN_COUNT,
+        )
+        missing_grain = sorted(set(self.grain) - set(self.select))
+        if missing_grain:
+            raise ContractError(
+                "plan.grain",
+                "GRAIN_NOT_SELECTED",
+                f"contains columns absent from plan.select: {missing_grain}",
+            )
+        if not isinstance(self.quality, QualitySpec):
+            raise ContractError("plan.quality", "TYPE", "must be a QualitySpec")
+        _bounded_int(
+            self.quality.min_rows,
+            "plan.quality.min_rows",
+            minimum=1,
+            maximum=MAX_OUTPUT_ROWS,
+        )
+        if not isinstance(self.quality, QualitySpec):
+            raise ContractError("plan.quality", "TYPE", "must be a QualitySpec")
+        missing_quality = sorted(set(self.quality.not_null) - set(self.select))
+        if missing_quality:
+            raise ContractError(
+                "plan.quality.not_null",
+                "QUALITY_COLUMN_NOT_SELECTED",
+                f"contains columns absent from plan.select: {missing_quality}",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "question": self.question,
+            "output_intent": self.output_intent,
+            "grain": list(self.grain),
+            "sources": [source.to_dict() for source in self.sources],
+            "cleaning": [step.to_dict() for step in self.cleaning],
+            "join": self.join.to_dict(),
+            "select": list(self.select),
+            "quality": self.quality.to_dict(),
+        }
+
+    @classmethod
+    def from_value(cls, value: Any) -> TablePlan:
+        return parse_table_plan(value)
+
+
+@dataclass(frozen=True)
+class GraphNode:
+    """One ordered node in a closed table-plan graph."""
+
+    node_id: str
+    operation: str
+    operation_version: str
+    inputs: tuple[str, ...]
+    parameters: tuple[tuple[str, Any], ...]
+
+    def __post_init__(self) -> None:
+        _identifier(self.node_id, "plan.nodes.id")
+        _text(self.operation, "plan.nodes.operation", minimum=1, maximum=64)
+        _text(self.operation_version, "plan.nodes.operation_version", minimum=1, maximum=32)
+        _text_tuple(
+            self.inputs,
+            "plan.nodes.inputs",
+            nonempty=False,
+            maximum=MAX_GRAPH_NODE_COUNT,
+            item_maximum=MAX_IDENTIFIER_LENGTH,
+        )
+        for index, value in enumerate(self.inputs):
+            _identifier(value, f"plan.nodes.inputs[{index}]")
+        if not isinstance(self.parameters, tuple) or any(
+            not isinstance(item, tuple) or len(item) != 2 or not isinstance(item[0], str)
+            for item in self.parameters
+        ):
+            raise ContractError("plan.nodes.parameters", "TYPE", "must be frozen parameter pairs")
+
+    def parameter(self, name: str) -> Any:
+        return dict(self.parameters)[name]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.node_id,
+            "operation": self.operation,
+            "operation_version": self.operation_version,
+            "inputs": list(self.inputs),
+            "parameters": thaw_parameter(self.parameters),
+        }
+
+
+@dataclass(frozen=True)
+class GraphTablePlan(_CanonicalContract):
+    """A versioned ordered DAG with one declared terminal Table node."""
+
+    operation_contract_version: str
+    question: str
+    output_intent: str
+    grain: tuple[str, ...]
+    sources: tuple[SourceSpec, ...]
+    nodes: tuple[GraphNode, ...]
+    terminal: str
+    output_columns: tuple[str, ...]
+    quality: QualitySpec
+    schema_version: str = GRAPH_PLAN_SCHEMA_VERSION
+
+    EXPECTED_SCHEMA_VERSION: ClassVar[str] = GRAPH_PLAN_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        _version(self.schema_version, GRAPH_PLAN_SCHEMA_VERSION, "plan.schema_version")
+        _version(
+            self.operation_contract_version,
+            GRAPH_OPERATION_CONTRACT_VERSION,
+            "plan.operation_contract_version",
+        )
+        _text(self.question, "plan.question", minimum=1, maximum=MAX_TEXT_LENGTH)
+        _choice(self.output_intent, _OUTPUT_INTENTS, "plan.output_intent")
+        _column_tuple(self.grain, "plan.grain", nonempty=True, maximum=16)
+        _typed_tuple(
+            self.sources,
+            SourceSpec,
+            "plan.sources",
+            nonempty=True,
+            maximum=MAX_SOURCE_COUNT,
+        )
+        source_ids = tuple(source.source_id for source in self.sources)
+        _require_unique(source_ids, "plan.sources.id")
+        _typed_tuple(
+            self.nodes,
+            GraphNode,
+            "plan.nodes",
+            nonempty=True,
+            maximum=MAX_GRAPH_NODE_COUNT,
+        )
+        node_ids = tuple(node.node_id for node in self.nodes)
+        if len(set(node_ids)) != len(node_ids):
+            raise ContractError("plan.nodes.id", "GRAPH_NODE_DUPLICATE", "must be unique")
+        _identifier(self.terminal, "plan.terminal")
+        if self.terminal not in set(node_ids):
+            raise ContractError("plan.terminal", "GRAPH_TERMINAL_UNKNOWN", "is not a graph node")
+        _column_tuple(
+            self.output_columns,
+            "plan.output_columns",
+            nonempty=True,
+            maximum=MAX_COLUMN_COUNT,
+        )
+        missing_grain = sorted(set(self.grain) - set(self.output_columns))
+        if missing_grain:
+            raise ContractError(
+                "plan.grain",
+                "GRAIN_NOT_SELECTED",
+                f"contains columns absent from plan.output_columns: {missing_grain}",
+            )
+        if not isinstance(self.quality, QualitySpec):
+            raise ContractError("plan.quality", "TYPE", "must be a QualitySpec")
+        missing_quality = sorted(set(self.quality.not_null) - set(self.output_columns))
+        if missing_quality:
+            raise ContractError(
+                "plan.quality.not_null",
+                "QUALITY_COLUMN_NOT_SELECTED",
+                f"contains columns absent from plan.output_columns: {missing_quality}",
+            )
+        self._validate_graph(source_ids)
+
+    @property
+    def select(self) -> tuple[str, ...]:
+        """Compatibility name used by Recipe output-semantic validation."""
+
+        return self.output_columns
+
+    def _validate_graph(self, source_ids: tuple[str, ...]) -> None:
+        seen: set[str] = set()
+        source_bindings: list[str] = []
+        node_by_id = {node.node_id: node for node in self.nodes}
+        for index, node in enumerate(self.nodes):
+            try:
+                operation = resolve_operation(node.operation, node.operation_version)
+            except OperationRegistryError as exc:
+                raise ContractError(
+                    f"plan.nodes[{index}].operation", exc.code, exc.detail
+                ) from None
+            minimum, maximum = operation.input_arity
+            if not minimum <= len(node.inputs) <= maximum:
+                raise ContractError(
+                    f"plan.nodes[{index}].inputs",
+                    "OPERATION_ARITY",
+                    f"requires {minimum}..{maximum} inputs",
+                )
+            unknown = [input_id for input_id in node.inputs if input_id not in seen]
+            if unknown:
+                raise ContractError(
+                    f"plan.nodes[{index}].inputs",
+                    "GRAPH_INPUT_ORDER",
+                    f"must reference earlier nodes; unavailable={unknown}",
+                )
+            if node.operation == "source":
+                source_id = node.parameter("source")
+                if not isinstance(source_id, str) or source_id not in set(source_ids):
+                    raise ContractError(
+                        f"plan.nodes[{index}].parameters.source",
+                        "GRAPH_SOURCE_UNKNOWN",
+                        "must bind one declared source",
+                    )
+                source_bindings.append(source_id)
+            if node.operation == "prediction_label":
+                if node.node_id != self.terminal:
+                    raise ContractError(
+                        f"plan.nodes[{index}]",
+                        "PREDICTION_LABEL_POSITION",
+                        "prediction_label must be the terminal node so its future value cannot "
+                        "feed another transform",
+                    )
+                output_column = node.parameter("output_column")
+                if output_column not in self.output_columns:
+                    raise ContractError(
+                        f"plan.nodes[{index}].parameters.output_column",
+                        "PREDICTION_LABEL_OUTPUT",
+                        "must be selected as an output column",
+                    )
+            seen.add(node.node_id)
+        if len(set(source_bindings)) != len(source_bindings):
+            raise ContractError(
+                "plan.nodes.parameters.source",
+                "GRAPH_SOURCE_DUPLICATE",
+                "a declared source may have only one source node",
+            )
+        if set(source_bindings) != set(source_ids):
+            raise ContractError(
+                "plan.nodes.parameters.source",
+                "GRAPH_SOURCE_SET",
+                "source nodes must bind every declared source exactly once",
+            )
+        reachable: set[str] = set()
+
+        def visit(node_id: str) -> None:
+            if node_id in reachable:
+                return
+            reachable.add(node_id)
+            for input_id in node_by_id[node_id].inputs:
+                visit(input_id)
+
+        visit(self.terminal)
+        unreachable = sorted(set(node_by_id) - reachable)
+        if unreachable:
+            raise ContractError(
+                "plan.nodes",
+                "GRAPH_NODE_UNREACHABLE",
+                f"nodes are outside terminal ancestry: {unreachable}",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "operation_contract_version": self.operation_contract_version,
+            "question": self.question,
+            "output_intent": self.output_intent,
+            "grain": list(self.grain),
+            "sources": [source.to_dict() for source in self.sources],
+            "nodes": [node.to_dict() for node in self.nodes],
+            "terminal": self.terminal,
+            "output_columns": list(self.output_columns),
+            "quality": self.quality.to_dict(),
+        }
+
+    @classmethod
+    def from_value(cls, value: Any) -> GraphTablePlan:
+        return parse_graph_table_plan(value)
+
+
+def is_single_plain_line(value: object) -> bool:
+    """Return whether text contains no boundary that renders as another display line.
+
+    This deliberately answers only the structural question. A tab remains part of one line, and
+    U+009B and bidi controls remain outside this rule pending an explicit terminal-safety policy.
+    """
+
+    return isinstance(value, str) and not any(
+        boundary in value for boundary in _DISPLAY_LINE_BOUNDARIES
+    )
+
+
+def parse_question(value: Any) -> LocalQuestion:
+    return LocalQuestion.from_value(value)
+
+
+def parse_requirements(value: Any) -> LocalRequirements:
+    return LocalRequirements.from_value(value)
+
+
+def parse_source_proposal(value: Any) -> SourceProposal:
+    return SourceProposal.from_value(value)
+
+
+def parse_table_semantics(value: Any) -> TableSemantics:
+    """Parse the closed human-readable semantics document without inferring any claim."""
+
+    path = "semantics"
+    data = _object(value, path)
+    _exact_fields(
+        data,
+        {"schema_version", "summary", "grain_statement", "coverage", "limitations", "columns"},
+        path,
+    )
+    coverage_data = _object(data["coverage"], f"{path}.coverage")
+    _exact_fields(
+        coverage_data,
+        {"time_range", "population", "completeness_note"},
+        f"{path}.coverage",
+    )
+    time_range = coverage_data["time_range"]
+    start_inclusive: str | None = None
+    end_exclusive: str | None = None
+    if time_range is not None:
+        time_data = _object(time_range, f"{path}.coverage.time_range")
+        _exact_fields(
+            time_data,
+            {"start_inclusive", "end_exclusive"},
+            f"{path}.coverage.time_range",
+        )
+        start_inclusive = _required_text(
+            time_data["start_inclusive"],
+            f"{path}.coverage.time_range.start_inclusive",
+            maximum=128,
+        )
+        end_exclusive = _required_text(
+            time_data["end_exclusive"],
+            f"{path}.coverage.time_range.end_exclusive",
+            maximum=128,
+        )
+
+    columns: list[ColumnSemantics] = []
+    for index, raw_column in enumerate(
+        _array(data["columns"], f"{path}.columns", nonempty=True, maximum=MAX_COLUMN_COUNT)
+    ):
+        column_path = f"{path}.columns[{index}]"
+        column = _object(raw_column, column_path)
+        _exact_fields(
+            column,
+            {
+                "name",
+                "display_label",
+                "description",
+                "semantic_type",
+                "unit",
+                "unit_state",
+                "normalization",
+                "reversible",
+                "categories",
+                "categories_status",
+                "evidence_refs",
+            },
+            column_path,
+        )
+        categories: tuple[CategoryDefinition, ...] | None = None
+        if column["categories"] is not None:
+            parsed_categories: list[CategoryDefinition] = []
+            for category_index, raw_category in enumerate(
+                _array(
+                    column["categories"],
+                    f"{column_path}.categories",
+                    nonempty=True,
+                    maximum=64,
+                )
+            ):
+                category_path = f"{column_path}.categories[{category_index}]"
+                category = _object(raw_category, category_path)
+                _exact_fields(category, {"code", "label"}, category_path)
+                parsed_categories.append(
+                    CategoryDefinition(
+                        code=_required_text(category["code"], f"{category_path}.code", maximum=64),
+                        label=_required_text(
+                            category["label"], f"{category_path}.label", maximum=120
+                        ),
+                    )
+                )
+            categories = tuple(parsed_categories)
+
+        evidence_refs: list[SemanticEvidenceRef] = []
+        for evidence_index, raw_evidence in enumerate(
+            _array(
+                column["evidence_refs"],
+                f"{column_path}.evidence_refs",
+                nonempty=False,
+                maximum=8,
+            )
+        ):
+            evidence_path = f"{column_path}.evidence_refs[{evidence_index}]"
+            evidence = _object(raw_evidence, evidence_path)
+            _exact_fields(evidence, {"kind", "ref"}, evidence_path)
+            evidence_refs.append(
+                SemanticEvidenceRef(
+                    kind=_required_text(evidence["kind"], f"{evidence_path}.kind", maximum=64),
+                    ref=_required_text(evidence["ref"], f"{evidence_path}.ref", maximum=128),
+                )
+            )
+
+        reversible = column["reversible"]
+        if reversible is not None and type(reversible) is not bool:
+            raise ContractError(f"{column_path}.reversible", "TYPE", "must be a boolean or null")
+        normalization = column["normalization"]
+        if normalization is not None and not isinstance(normalization, str):
+            raise ContractError(f"{column_path}.normalization", "TYPE", "must be a string or null")
+        columns.append(
+            ColumnSemantics(
+                name=_required_text(column["name"], f"{column_path}.name", maximum=64),
+                display_label=_required_text(
+                    column["display_label"], f"{column_path}.display_label", maximum=120
+                ),
+                description=_required_text(
+                    column["description"], f"{column_path}.description", maximum=1_000
+                ),
+                semantic_type=_required_text(
+                    column["semantic_type"], f"{column_path}.semantic_type", maximum=64
+                ),
+                unit=_required_text(column["unit"], f"{column_path}.unit", maximum=64),
+                unit_state=_required_text(
+                    column["unit_state"], f"{column_path}.unit_state", maximum=64
+                ),
+                normalization=normalization,
+                reversible=reversible,
+                categories=categories,
+                categories_status=_required_text(
+                    column["categories_status"],
+                    f"{column_path}.categories_status",
+                    maximum=64,
+                ),
+                evidence_refs=tuple(evidence_refs),
+            )
+        )
+
+    return TableSemantics(
+        schema_version=_required_text(data["schema_version"], f"{path}.schema_version", maximum=64),
+        summary=_required_text(data["summary"], f"{path}.summary", maximum=1_000),
+        grain_statement=_required_text(
+            data["grain_statement"], f"{path}.grain_statement", maximum=400
+        ),
+        coverage=SemanticCoverage(
+            start_inclusive=start_inclusive,
+            end_exclusive=end_exclusive,
+            population=_required_text(
+                coverage_data["population"], f"{path}.coverage.population", maximum=2_000
+            ),
+            completeness_note=_required_text(
+                coverage_data["completeness_note"],
+                f"{path}.coverage.completeness_note",
+                maximum=1_000,
+            ),
+        ),
+        limitations=_parse_text_array(
+            data["limitations"],
+            f"{path}.limitations",
+            nonempty=False,
+            maximum=32,
+            item_maximum=1_000,
+        ),
+        columns=tuple(columns),
+    )
+
+
+def parse_table_plan(value: Any) -> TablePlan:
+    """Parse an untrusted JSON-compatible value into the closed execution plan."""
+
+    path = "plan"
+    data = _object(value, path)
+    _exact_fields(
+        data,
+        {
+            "schema_version",
+            "question",
+            "output_intent",
+            "grain",
+            "sources",
+            "cleaning",
+            "join",
+            "select",
+            "quality",
+        },
+        path,
+    )
+    sources = tuple(
+        _parse_source(item, f"{path}.sources[{index}]")
+        for index, item in enumerate(
+            _array(
+                data["sources"],
+                f"{path}.sources",
+                nonempty=True,
+                minimum=2,
+                maximum=MAX_SOURCE_COUNT,
+            )
+        )
+    )
+    _require_unique((source.source_id for source in sources), f"{path}.sources.id")
+    source_ids = frozenset(source.source_id for source in sources)
+    cleaning = tuple(
+        _parse_cleaning(item, f"{path}.cleaning[{index}]", source_ids)
+        for index, item in enumerate(
+            _array(
+                data["cleaning"],
+                f"{path}.cleaning",
+                nonempty=False,
+                maximum=MAX_OPERATION_COUNT,
+            )
+        )
+    )
+    return TablePlan(
+        schema_version=_required_text(
+            data["schema_version"],
+            f"{path}.schema_version",
+            maximum=64,
+        ),
+        question=_required_text(
+            data["question"],
+            f"{path}.question",
+            maximum=MAX_TEXT_LENGTH,
+        ),
+        output_intent=_required_text(
+            data["output_intent"],
+            f"{path}.output_intent",
+            maximum=64,
+        ),
+        grain=_parse_column_array(
+            data["grain"],
+            f"{path}.grain",
+            nonempty=True,
+            maximum=16,
+        ),
+        sources=sources,
+        cleaning=cleaning,
+        join=_parse_join(data["join"], f"{path}.join", source_ids),
+        select=_parse_column_array(
+            data["select"],
+            f"{path}.select",
+            nonempty=True,
+            maximum=MAX_COLUMN_COUNT,
+        ),
+        quality=_parse_quality(data["quality"], f"{path}.quality"),
+    )
+
+
+def parse_graph_table_plan(value: Any) -> GraphTablePlan:
+    """Parse an untrusted v2 graph without executing any node."""
+
+    path = "plan"
+    data = _object(value, path)
+    _exact_fields(
+        data,
+        {
+            "schema_version",
+            "operation_contract_version",
+            "question",
+            "output_intent",
+            "grain",
+            "sources",
+            "nodes",
+            "terminal",
+            "output_columns",
+            "quality",
+        },
+        path,
+    )
+    operation_contract = _required_text(
+        data["operation_contract_version"],
+        f"{path}.operation_contract_version",
+        maximum=64,
+    )
+    if operation_contract != GRAPH_OPERATION_CONTRACT_VERSION:
+        raise ContractError(
+            f"{path}.operation_contract_version",
+            "PLAN_OPERATION_PAIR",
+            f"{GRAPH_PLAN_SCHEMA_VERSION} requires {GRAPH_OPERATION_CONTRACT_VERSION}",
+        )
+    sources = tuple(
+        _parse_source(item, f"{path}.sources[{index}]")
+        for index, item in enumerate(
+            _array(data["sources"], f"{path}.sources", nonempty=True, maximum=MAX_SOURCE_COUNT)
+        )
+    )
+    nodes: list[GraphNode] = []
+    for index, item in enumerate(
+        _array(data["nodes"], f"{path}.nodes", nonempty=True, maximum=MAX_GRAPH_NODE_COUNT)
+    ):
+        node_path = f"{path}.nodes[{index}]"
+        node_data = _object(item, node_path)
+        _exact_fields(
+            node_data,
+            {"id", "operation", "operation_version", "inputs", "parameters"},
+            node_path,
+        )
+        operation_name = _required_text(
+            node_data["operation"], f"{node_path}.operation", maximum=64
+        )
+        operation_version = _required_text(
+            node_data["operation_version"], f"{node_path}.operation_version", maximum=32
+        )
+        try:
+            operation = resolve_operation(operation_name, operation_version)
+            parameters = operation.validate_parameters(
+                node_data["parameters"], path=f"{node_path}.parameters"
+            )
+        except OperationRegistryError as exc:
+            raise ContractError(exc.path, exc.code, exc.detail) from None
+        nodes.append(
+            GraphNode(
+                node_id=_required_text(node_data["id"], f"{node_path}.id", maximum=64),
+                operation=operation_name,
+                operation_version=operation_version,
+                inputs=tuple(
+                    _required_text(value, f"{node_path}.inputs[{input_index}]", maximum=64)
+                    for input_index, value in enumerate(
+                        _array(
+                            node_data["inputs"],
+                            f"{node_path}.inputs",
+                            nonempty=False,
+                            maximum=MAX_GRAPH_NODE_COUNT,
+                        )
+                    )
+                ),
+                parameters=parameters,
+            )
+        )
+    return GraphTablePlan(
+        schema_version=_required_text(data["schema_version"], f"{path}.schema_version", maximum=64),
+        operation_contract_version=operation_contract,
+        question=_required_text(data["question"], f"{path}.question", maximum=MAX_TEXT_LENGTH),
+        output_intent=_required_text(data["output_intent"], f"{path}.output_intent", maximum=64),
+        grain=_parse_column_array(data["grain"], f"{path}.grain", nonempty=True, maximum=16),
+        sources=sources,
+        nodes=tuple(nodes),
+        terminal=_required_text(data["terminal"], f"{path}.terminal", maximum=64),
+        output_columns=_parse_column_array(
+            data["output_columns"],
+            f"{path}.output_columns",
+            nonempty=True,
+            maximum=MAX_COLUMN_COUNT,
+        ),
+        quality=_parse_quality(data["quality"], f"{path}.quality"),
+    )
+
+
+def parse_plan_document(value: Any) -> TablePlan | GraphTablePlan:
+    """Dispatch exactly one accepted plan generation by its schema version.
+
+    This is the reader for a plan of any age, including one read back out of a sealed Build, so it
+    understands every operation the registry still holds. :func:`parse_fresh_plan_document` is the
+    entry point for newly authored bytes.
+    """
+
+    data = _object(value, "plan")
+    schema_version = data.get("schema_version")
+    if schema_version == PLAN_SCHEMA_VERSION:
+        return parse_table_plan(value)
+    if schema_version == GRAPH_PLAN_SCHEMA_VERSION:
+        return parse_graph_table_plan(value)
+    if schema_version == _LEGACY_PLAN_SCHEMA_VERSION:
+        detail = (
+            f"found {schema_version!r}, supported {PLAN_SCHEMA_VERSION!r} (renamed in V3); "
+            f"set plan.schema_version to {PLAN_SCHEMA_VERSION!r} and retry"
+        )
+    else:
+        detail = (
+            f"found {schema_version!r}, supported one of "
+            f"{[PLAN_SCHEMA_VERSION, GRAPH_PLAN_SCHEMA_VERSION]}"
+        )
+    raise ContractError("plan.schema_version", "VERSION", detail)
+
+
+def refuse_retired_operations(plan: TablePlan | GraphTablePlan) -> None:
+    """Refuse a plan that names an operation the graph vocabulary has retired.
+
+    A retired operation is one the admission contract in ``docs/TRANSFORMS.md`` no longer admits.
+    It stays in the registry because a Build sealed with it, and a Recipe approved with it, both
+    re-parse their stored plan through that table to verify -- dropping the entry would make
+    already-sealed bytes unreadable, which is a worse thing than the operation continuing to
+    exist. So the line is drawn by age of the bytes rather than by the table: this is called on
+    newly authored bytes and on nothing else, exactly as
+    :func:`mostlyright.data_harness.recipe.parse_fresh_recipe` calls
+    ``require_resolvable_reader`` for a Reader pin whose implementation has since been retired.
+    """
+
+    if not isinstance(plan, GraphTablePlan):
+        return
+    for index, node in enumerate(plan.nodes):
+        if node.operation in RETIRED_OPERATIONS:
+            raise ContractError(
+                f"plan.nodes[{index}].operation",
+                "OPERATION_RETIRED",
+                f"operation {node.operation!r} is retired and cannot be named by a new plan",
+            )
+
+
+def refuse_retired_operation_names(value: Any) -> None:
+    """Say "retired" about a node before saying anything else about it.
+
+    The structural rules a retired operation still carries -- where it may sit, what it must
+    select -- fire during the parse, ahead of the retirement check that runs after it. Their advice
+    is to correct the offending field and run the command again, which for a node that cannot be in
+    a new plan at all sends the author round a loop that ends here anyway, and the author is
+    frequently an agent that will act on it. So the retirement is read off the raw document first.
+
+    Anything that is not a well-formed node list is left alone, so a malformed document still gets
+    the ordinary parse error that describes its actual shape rather than this one.
+    """
+
+    if not isinstance(value, Mapping):
+        return
+    nodes = value.get("nodes")
+    if not isinstance(nodes, list):
+        return
+    for index, node in enumerate(nodes):
+        if not isinstance(node, Mapping):
+            continue
+        operation = node.get("operation")
+        if isinstance(operation, str) and operation in RETIRED_OPERATIONS:
+            raise ContractError(
+                f"plan.nodes[{index}].operation",
+                "OPERATION_RETIRED",
+                f"operation {operation!r} is retired and cannot be named by a new plan",
+            )
+
+
+def refuse_inconsistent_units(plan: TablePlan | GraphTablePlan) -> None:
+    """Refuse a plan whose declared units contradict each other or the arithmetic on them.
+
+    This is on the authoring path and on nothing else, for the same reason the retirement check is.
+    The analysis reads a declaration that did not exist before it, so nothing already sealed can
+    trip it today -- but it is an analysis rather than a table, and a later pass that sees more will
+    refuse more. Running it where sealed bytes are read would make that later pass retroactive:
+    a plan sealed under this version would stop verifying under the next one, which is the outcome
+    the age-of-the-bytes line exists to prevent.
+    """
+
+    if not isinstance(plan, GraphTablePlan):
+        return
+    from mostlyright.data_harness.unit_flow import UnitFlowError
+    from mostlyright.data_harness.unit_flow import refuse_inconsistent_units as _refuse
+
+    try:
+        _refuse(plan)
+    except UnitFlowError as exc:
+        raise ContractError(exc.path, exc.code, exc.detail) from None
+
+
+def parse_fresh_plan_document(value: Any) -> TablePlan | GraphTablePlan:
+    """Parse a plan entering the authoring lifecycle, and hold it to the checks age decides.
+
+    Three checks, in this order. The first reads retired names off the raw document so retirement
+    is what the author is told; the second holds for a caller that passes an already-parsed plan
+    through :func:`refuse_retired_operations` instead; the third is the two unit gates, which read
+    a declaration and the arithmetic on it. All three are refusals for newly authored bytes and for
+    nothing else.
+    """
+
+    refuse_retired_operation_names(value)
+    plan = parse_plan_document(value)
+    refuse_retired_operations(plan)
+    refuse_inconsistent_units(plan)
+    return plan
+
+
+def _parse_source(value: Any, path: str) -> SourceSpec:
+    data = _object(value, path)
+    _exact_fields(
+        data,
+        {"id", "path", "format", "origin", "acquisition_method", "rights"},
+        path,
+    )
+    rights_path = f"{path}.rights"
+    rights_data = _object(data["rights"], rights_path)
+    _exact_fields(rights_data, {"status", "evidence", "permissions"}, rights_path)
+    try:
+        rights = RightsSpec(
+            status=_required_text(
+                rights_data["status"],
+                f"{rights_path}.status",
+                maximum=64,
+            ),
+            evidence=_required_text(
+                rights_data["evidence"],
+                f"{rights_path}.evidence",
+                maximum=MAX_TEXT_LENGTH,
+            ),
+            permissions=_parse_choice_array(
+                rights_data["permissions"],
+                f"{rights_path}.permissions",
+                _PERMISSIONS,
+                nonempty=True,
+                maximum=len(_PERMISSIONS),
+            ),
+        )
+    except ContractError as exc:
+        if exc.path.startswith("rights."):
+            suffix = exc.path.removeprefix("rights.")
+            raise ContractError(f"{rights_path}.{suffix}", exc.code, exc.detail) from None
+        raise
+    try:
+        return SourceSpec(
+            source_id=_required_text(
+                data["id"],
+                f"{path}.id",
+                maximum=MAX_IDENTIFIER_LENGTH,
+            ),
+            path=_required_text(data["path"], f"{path}.path", maximum=MAX_PATH_LENGTH),
+            format=_required_text(data["format"], f"{path}.format", maximum=16),
+            origin=_required_text(data["origin"], f"{path}.origin", maximum=4_000),
+            acquisition_method=_required_text(
+                data["acquisition_method"],
+                f"{path}.acquisition_method",
+                maximum=64,
+            ),
+            rights=rights,
+        )
+    except ContractError as exc:
+        if exc.path.startswith("source."):
+            suffix = exc.path.removeprefix("source.")
+            raise ContractError(f"{path}.{suffix}", exc.code, exc.detail) from None
+        raise
+
+
+def _parse_cleaning(
+    value: Any,
+    path: str,
+    source_ids: frozenset[str],
+) -> CleaningStep:
+    data = _object(value, path)
+    _exact_fields(data, {"source", "operation", "columns"}, path)
+    source_id = _required_text(
+        data["source"],
+        f"{path}.source",
+        maximum=MAX_IDENTIFIER_LENGTH,
+    )
+    if source_id not in source_ids:
+        raise ContractError(
+            f"{path}.source",
+            "UNKNOWN_SOURCE",
+            f"must be one of {sorted(source_ids)}",
+        )
+    operation = _required_text(
+        data["operation"],
+        f"{path}.operation",
+        maximum=64,
+    )
+    _choice(operation, _CLEANING_OPERATIONS, f"{path}.operation")
+    if operation in {"trim", "empty_to_null"}:
+        columns: tuple[str, ...] | tuple[tuple[str, str], ...] = _parse_column_array(
+            data["columns"],
+            f"{path}.columns",
+            nonempty=True,
+            maximum=MAX_COLUMN_COUNT,
+        )
+    else:
+        mapping = _object(data["columns"], f"{path}.columns")
+        if not mapping:
+            raise ContractError(
+                f"{path}.columns",
+                "EMPTY_COLLECTION",
+                "cannot be empty",
+            )
+        if len(mapping) > MAX_COLUMN_COUNT:
+            raise ContractError(
+                f"{path}.columns",
+                "COLLECTION_LIMIT",
+                f"exceeds {MAX_COLUMN_COUNT} entries",
+            )
+        pairs: list[tuple[str, str]] = []
+        for key, item in mapping.items():
+            source_column = _column_name(key, f"{path}.columns.<key>")
+            target = _required_text(
+                item,
+                f"{path}.columns[{key!r}]",
+                maximum=MAX_IDENTIFIER_LENGTH,
+            )
+            if operation == "rename":
+                _column_name(target, f"{path}.columns[{key!r}]")
+            else:
+                _choice(target, _CAST_TYPES, f"{path}.columns[{key!r}]")
+            pairs.append((source_column, target))
+        columns = tuple(pairs)
+    try:
+        return CleaningStep(source_id=source_id, operation=operation, columns=columns)
+    except ContractError as exc:
+        if exc.path.startswith("cleaning."):
+            suffix = exc.path.removeprefix("cleaning.")
+            raise ContractError(f"{path}.{suffix}", exc.code, exc.detail) from None
+        raise
+
+
+def _parse_join(value: Any, path: str, source_ids: frozenset[str]) -> JoinSpec:
+    data = _object(value, path)
+    _exact_fields(data, {"left", "right", "on", "kind", "cardinality"}, path)
+    left = _required_text(data["left"], f"{path}.left", maximum=MAX_IDENTIFIER_LENGTH)
+    right = _required_text(data["right"], f"{path}.right", maximum=MAX_IDENTIFIER_LENGTH)
+    if left not in source_ids:
+        raise ContractError(
+            f"{path}.left",
+            "UNKNOWN_SOURCE",
+            f"must be one of {sorted(source_ids)}",
+        )
+    if right not in source_ids:
+        raise ContractError(
+            f"{path}.right",
+            "UNKNOWN_SOURCE",
+            f"must be one of {sorted(source_ids)}",
+        )
+    try:
+        return JoinSpec(
+            left=left,
+            right=right,
+            on=_parse_column_array(
+                data["on"],
+                f"{path}.on",
+                nonempty=True,
+                maximum=16,
+            ),
+            kind=_required_text(data["kind"], f"{path}.kind", maximum=32),
+            cardinality=_required_text(
+                data["cardinality"],
+                f"{path}.cardinality",
+                maximum=32,
+            ),
+        )
+    except ContractError as exc:
+        if exc.path.startswith("join."):
+            suffix = exc.path.removeprefix("join.")
+            raise ContractError(f"{path}.{suffix}", exc.code, exc.detail) from None
+        raise
+
+
+def _parse_quality(value: Any, path: str) -> QualitySpec:
+    data = _object(value, path)
+    _exact_fields(data, {"min_rows", "not_null"}, path)
+    try:
+        return QualitySpec(
+            min_rows=_integer(data["min_rows"], f"{path}.min_rows"),
+            not_null=_parse_column_array(
+                data["not_null"],
+                f"{path}.not_null",
+                nonempty=False,
+                maximum=MAX_COLUMN_COUNT,
+            ),
+        )
+    except ContractError as exc:
+        if exc.path.startswith("quality."):
+            suffix = exc.path.removeprefix("quality.")
+            raise ContractError(f"{path}.{suffix}", exc.code, exc.detail) from None
+        raise
+
+
+def _object(value: Any, path: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value):
+        raise ContractError(path, "TYPE", "must be an object with string keys")
+    return value
+
+
+def _array(
+    value: Any,
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+    minimum: int = 0,
+) -> Sequence[Any]:
+    if not isinstance(value, list):
+        raise ContractError(path, "TYPE", "must be an array")
+    if nonempty and not value:
+        raise ContractError(path, "EMPTY_COLLECTION", "cannot be empty")
+    if len(value) < minimum:
+        raise ContractError(path, "COLLECTION_MINIMUM", f"must contain at least {minimum} entries")
+    if len(value) > maximum:
+        raise ContractError(path, "COLLECTION_LIMIT", f"exceeds {maximum} entries")
+    return value
+
+
+def _exact_fields(data: Mapping[str, Any], expected: Iterable[str], path: str) -> None:
+    expected_set = frozenset(expected)
+    missing = sorted(expected_set - data.keys())
+    extra = sorted(data.keys() - expected_set)
+    if missing or extra:
+        raise ContractError(
+            path,
+            "FIELDS",
+            f"fields invalid; missing={missing}, unknown={extra}",
+        )
+
+
+def _required_text(value: Any, path: str, *, maximum: int) -> str:
+    if not isinstance(value, str):
+        raise ContractError(path, "TYPE", "must be a string")
+    _text(value, path, minimum=1, maximum=maximum)
+    return value
+
+
+def _text(value: Any, path: str, *, minimum: int, maximum: int) -> str:
+    if not isinstance(value, str):
+        raise ContractError(path, "TYPE", "must be a string")
+    if value != value.strip():
+        raise ContractError(path, "NONCANONICAL_TEXT", "must not have surrounding whitespace")
+    if len(value) < minimum:
+        raise ContractError(path, "STRING_MINIMUM", f"must contain at least {minimum} characters")
+    if len(value) > maximum:
+        raise ContractError(path, "STRING_LIMIT", f"exceeds {maximum} characters")
+    for char in value:
+        if ord(char) < 0x20 and char not in {"\t", "\n", "\r"}:
+            raise ContractError(path, "CONTROL_CHARACTER", "contains a control character")
+    return value
+
+
+def _identifier(value: Any, path: str) -> str:
+    text = _text(
+        value,
+        path,
+        minimum=1,
+        maximum=MAX_IDENTIFIER_LENGTH,
+    )
+    if not _IDENTIFIER.fullmatch(text):
+        raise ContractError(
+            path,
+            "IDENTIFIER",
+            "must be a canonical lowercase identifier",
+        )
+    return text
+
+
+def _column_name(value: Any, path: str) -> str:
+    text = _text(
+        value,
+        path,
+        minimum=1,
+        maximum=MAX_IDENTIFIER_LENGTH,
+    )
+    if not _COLUMN.fullmatch(text):
+        raise ContractError(
+            path,
+            "COLUMN_IDENTIFIER",
+            "must be a canonical lowercase snake-case column name",
+        )
+    return text
+
+
+def _version(value: Any, expected: str, path: str) -> str:
+    text = _text(value, path, minimum=1, maximum=64)
+    if text != expected:
+        raise ContractError(path, "VERSION", f"must be {expected!r}")
+    return text
+
+
+def _choice_version(value: Any, accepted: tuple[str, ...], path: str) -> str:
+    """Pin a schema version to one of the generations still read."""
+
+    text = _text(value, path, minimum=1, maximum=64)
+    if text not in accepted:
+        raise ContractError(path, "VERSION", f"must be one of {list(accepted)}")
+    return text
+
+
+def _choice(value: Any, choices: frozenset[str], path: str) -> str:
+    if not isinstance(value, str) or value not in choices:
+        raise ContractError(path, "ENUM", f"must be one of {sorted(choices)}")
+    return value
+
+
+def _declared_unit(value: Any, path: str) -> Unit | None:
+    """Accept ``none`` or one unit code the grammar resolves, and refuse anything else by name.
+
+    Returning the resolved unit rather than the string is what lets the rules above ask what the
+    code means instead of how it was spelled. ``none`` resolves to nothing on purpose: it is the
+    absence of a unit, not a dimensionless one.
+    """
+
+    text = _text(value, path, minimum=1, maximum=64)
+    if text == NO_UNIT:
+        return None
+    try:
+        return resolve_declared_unit(text)
+    except UnitError as exc:
+        raise ContractError(
+            path, "UNIT_CODE", f"{text!r} is not a unit code: {exc.detail}"
+        ) from None
+
+
+def _integer(value: Any, path: str) -> int:
+    if type(value) is not int:
+        raise ContractError(path, "INTEGER", "must be an integer (booleans are not integers)")
+    return value
+
+
+def _bounded_int(value: Any, path: str, *, minimum: int, maximum: int) -> int:
+    integer = _integer(value, path)
+    if integer < minimum or integer > maximum:
+        raise ContractError(
+            path,
+            "INTEGER_RANGE",
+            f"must be between {minimum} and {maximum}",
+        )
+    return integer
+
+
+def _utc_timestamp(value: Any, path: str) -> datetime:
+    text = _text(value, path, minimum=1, maximum=32)
+    if not _UTC_TIMESTAMP.fullmatch(text):
+        raise ContractError(
+            path,
+            "UTC_TIMESTAMP",
+            "must be a zero-padded RFC 3339 UTC timestamp ending in Z",
+        )
+    try:
+        parsed = datetime.fromisoformat(text.removesuffix("Z") + "+00:00")
+    except ValueError:
+        raise ContractError(path, "UTC_TIMESTAMP", "must be a valid UTC timestamp") from None
+    if parsed.utcoffset() is None or parsed.utcoffset().total_seconds() != 0:
+        raise ContractError(path, "UTC_TIMESTAMP", "must use UTC Z")
+    return parsed
+
+
+def _sha256(value: Any, path: str) -> str:
+    if not isinstance(value, str) or not _SHA256.fullmatch(value):
+        raise ContractError(path, "SHA256", "must be a lowercase 64-character SHA-256 digest")
+    return value
+
+
+def _relative_posix_path(value: Any, path: str) -> str:
+    text = _text(value, path, minimum=1, maximum=MAX_PATH_LENGTH)
+    pure = PurePosixPath(text)
+    if (
+        "\\" in text
+        or "\x00" in text
+        or pure.is_absolute()
+        or not pure.parts
+        or any(part in {"", ".", ".."} for part in pure.parts)
+        or pure.as_posix() != text
+        or text.endswith("/")
+        or (pure.parts and ":" in pure.parts[0])
+    ):
+        raise ContractError(
+            path,
+            "POSIX_PATH",
+            "must be canonical normalized relative POSIX text",
+        )
+    return text
+
+
+def _decoded_query_component(value: str) -> str:
+    """Bound repeated decoding so concealed credential keys cannot enter durable evidence."""
+
+    decoded = value
+    for _ in range(3):
+        replacement = unquote_plus(decoded)
+        if replacement == decoded:
+            break
+        decoded = replacement
+    return decoded
+
+
+def validate_source_locator(value: Any, kind: str, path: str) -> str:
+    """Validate a durable source locator without admitting credentials or signed URLs."""
+
+    text = _text(value, path, minimum=1, maximum=MAX_PATH_LENGTH)
+    if kind == "relative_path":
+        return _relative_posix_path(text, path)
+    if kind == "artifact_reference":
+        if not text.startswith("artifact://") or len(text) <= len("artifact://"):
+            raise ContractError(path, "ARTIFACT_REFERENCE", "must be an artifact:// reference")
+        if any(char.isspace() for char in text):
+            raise ContractError(path, "ARTIFACT_REFERENCE", "must not contain whitespace")
+        try:
+            parsed_artifact = urlsplit(text)
+        except ValueError as error:
+            raise ContractError(
+                path, "ARTIFACT_REFERENCE", "must be a valid artifact:// reference"
+            ) from error
+        if (
+            parsed_artifact.username is not None
+            or parsed_artifact.password is not None
+            or parsed_artifact.fragment
+        ):
+            raise ContractError(
+                path,
+                "ARTIFACT_REFERENCE",
+                "must not contain embedded credentials or a fragment",
+            )
+        for query_key, query_value in parse_qsl(parsed_artifact.query, keep_blank_values=True):
+            if _SENSITIVE_LOCATOR_QUERY_KEY.search(
+                _decoded_query_component(query_key)
+            ) or _SECRET_LOCATOR_VALUE.search(_decoded_query_component(query_value)):
+                raise ContractError(
+                    path,
+                    "ARTIFACT_REFERENCE",
+                    "must not contain credentials or signed/secret query material",
+                )
+        return text
+    try:
+        parsed = urlsplit(text)
+    except ValueError as error:
+        raise ContractError(path, "HTTPS_URL", "must be a valid canonical HTTPS URL") from error
+    try:
+        port = parsed.port
+    except ValueError:
+        port = None
+        invalid_port = True
+    else:
+        invalid_port = False
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.fragment
+        or parsed.hostname != parsed.hostname.lower()
+        or invalid_port
+        or port == 443
+    ):
+        raise ContractError(
+            path,
+            "HTTPS_URL",
+            "must be a credential-free canonical HTTPS URL without a fragment",
+        )
+    for query_key, query_value in parse_qsl(parsed.query, keep_blank_values=True):
+        decoded_key = _decoded_query_component(query_key)
+        decoded_value = _decoded_query_component(query_value)
+        if _SENSITIVE_LOCATOR_QUERY_KEY.search(decoded_key) or _SECRET_LOCATOR_VALUE.search(
+            decoded_value
+        ):
+            raise ContractError(
+                path,
+                "HTTPS_URL",
+                "must not contain credentials or signed/secret query material",
+            )
+    return text
+
+
+def source_locator_identity(kind: str, locator: str) -> tuple[str, str]:
+    """Return a stable identity for already-validated proposal locators."""
+
+    validate_source_locator(locator, kind, "source_proposal.locator")
+    if kind != "https_url":
+        return kind, locator
+    parsed = urlsplit(locator)
+    normalized = urlunsplit((parsed.scheme, parsed.netloc, parsed.path or "/", parsed.query, ""))
+    return kind, normalized
+
+
+def _evidence_uri(value: Any, path: str) -> str:
+    text = _text(value, path, minimum=1, maximum=2_048)
+    parsed = urlsplit(text)
+    if parsed.scheme not in {"https", "fixture"} or not parsed.netloc:
+        raise ContractError(path, "EVIDENCE_URI", "must be an https:// or fixture:// URI")
+    if parsed.username is not None or parsed.password is not None:
+        raise ContractError(path, "EVIDENCE_URI", "must not embed credentials")
+    return text
+
+
+def _require_unique(values: Iterable[Any], path: str) -> None:
+    items = tuple(values)
+    if len(items) != len(set(items)):
+        raise ContractError(path, "DUPLICATE", "must contain unique entries")
+
+
+def _column_tuple(
+    values: Any,
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+) -> tuple[str, ...]:
+    if not isinstance(values, tuple):
+        raise ContractError(path, "TYPE", "must be an immutable tuple")
+    if nonempty and not values:
+        raise ContractError(path, "EMPTY_COLLECTION", "cannot be empty")
+    if len(values) > maximum:
+        raise ContractError(path, "COLLECTION_LIMIT", f"exceeds {maximum} entries")
+    for index, item in enumerate(values):
+        _column_name(item, f"{path}[{index}]")
+    _require_unique(values, path)
+    return values
+
+
+def _text_tuple(
+    values: Any,
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+    item_maximum: int,
+) -> tuple[str, ...]:
+    if not isinstance(values, tuple):
+        raise ContractError(path, "TYPE", "must be an immutable tuple")
+    if nonempty and not values:
+        raise ContractError(path, "EMPTY_COLLECTION", "cannot be empty")
+    if len(values) > maximum:
+        raise ContractError(path, "COLLECTION_LIMIT", f"exceeds {maximum} entries")
+    for index, item in enumerate(values):
+        _text(item, f"{path}[{index}]", minimum=1, maximum=item_maximum)
+    _require_unique(values, path)
+    return values
+
+
+def _choice_tuple(
+    values: Any,
+    choices: frozenset[str],
+    path: str,
+    *,
+    maximum: int,
+    nonempty: bool = False,
+) -> tuple[str, ...]:
+    if not isinstance(values, tuple):
+        raise ContractError(path, "TYPE", "must be an immutable tuple")
+    if nonempty and not values:
+        raise ContractError(path, "EMPTY_COLLECTION", "cannot be empty")
+    if len(values) > maximum:
+        raise ContractError(path, "COLLECTION_LIMIT", f"exceeds {maximum} entries")
+    for index, item in enumerate(values):
+        _choice(item, choices, f"{path}[{index}]")
+    _require_unique(values, path)
+    return values
+
+
+def _typed_tuple(
+    values: Any,
+    expected_type: type[Any],
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+    minimum: int = 0,
+) -> tuple[Any, ...]:
+    if not isinstance(values, tuple):
+        raise ContractError(path, "TYPE", "must be an immutable tuple")
+    if nonempty and not values:
+        raise ContractError(path, "EMPTY_COLLECTION", "cannot be empty")
+    if len(values) < minimum:
+        raise ContractError(path, "COLLECTION_MINIMUM", f"must contain at least {minimum} entries")
+    if len(values) > maximum:
+        raise ContractError(path, "COLLECTION_LIMIT", f"exceeds {maximum} entries")
+    for index, item in enumerate(values):
+        if not isinstance(item, expected_type):
+            raise ContractError(
+                f"{path}[{index}]",
+                "TYPE",
+                f"must be {expected_type.__name__}",
+            )
+    return values
+
+
+def _parse_column_array(
+    value: Any,
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+) -> tuple[str, ...]:
+    items = _array(value, path, nonempty=nonempty, maximum=maximum)
+    result = tuple(_column_name(item, f"{path}[{index}]") for index, item in enumerate(items))
+    _require_unique(result, path)
+    return result
+
+
+def _parse_text_array(
+    value: Any,
+    path: str,
+    *,
+    nonempty: bool,
+    maximum: int,
+    item_maximum: int,
+) -> tuple[str, ...]:
+    items = _array(value, path, nonempty=nonempty, maximum=maximum)
+    result = tuple(
+        _required_text(item, f"{path}[{index}]", maximum=item_maximum)
+        for index, item in enumerate(items)
+    )
+    _require_unique(result, path)
+    return result
+
+
+def _parse_choice_array(
+    value: Any,
+    path: str,
+    choices: frozenset[str],
+    *,
+    nonempty: bool,
+    maximum: int,
+) -> tuple[str, ...]:
+    items = _array(value, path, nonempty=nonempty, maximum=maximum)
+    result: list[str] = []
+    for index, item in enumerate(items):
+        text = _required_text(item, f"{path}[{index}]", maximum=64)
+        _choice(text, choices, f"{path}[{index}]")
+        result.append(text)
+    _require_unique(result, path)
+    return tuple(result)