@blxzer/pactile 0.5.0 → 0.6.0-beta.2

package/dist/templates/pactile/scripts/common/codebase_retrieval_router.py

@@ -1,1339 +0,0 @@
-#!/usr/bin/env python3
-"""Host-neutral Pactile retrieval request, plan, and evidence contract.
-
-This is the Python mirror of the TypeScript V3 planner.  It describes intent,
-assurance, policy, evidence, budgets, and stop conditions; concrete capability
-binding belongs to the project resolver and its adapters.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import math
-import re
-import unicodedata
-from datetime import datetime
-from pathlib import Path
-from typing import Any, cast
-
-
-ROUTER_VERSION = 3
-RETRIEVAL_ABI_VERSION = ROUTER_VERSION
-
-INTENT_ORDER = ("exact", "semantic", "structural", "external")
-PROVIDER_INTENTS = ("semantic", "structural", "external")
-ASSURANCE_LEVELS = ("best-effort", "evidence-backed", "verified")
-PROVIDER_STATUSES = (
-    "resolution-required",
-    "ready",
-    "degraded",
-    "unavailable",
-    "unsupported",
-)
-PROVIDER_READINESS = ("ready", "degraded", "unavailable")
-CORROBORATION_KINDS = (
-    "source-reference",
-    "git-evidence",
-    "repeatable-test",
-)
-REASON_CODES = (
-    "invalid-plan",
-    "invalid-evidence",
-    "query-empty",
-    "provider-resolution-required",
-    "provider-degraded",
-    "provider-unavailable",
-    "provider-unsupported",
-    "candidate-missing",
-    "corroboration-required",
-    "required-evidence-missing",
-    "minimum-assurance-not-met",
-    "verified-provider-proof-required",
-    "repeatable-verification-required",
-    "budget-exhausted",
-)
-
-FILESYSTEM_CEILINGS = ("none", "read", "write")
-PROCESS_CEILINGS = ("none", "execute")
-NETWORK_CEILINGS = ("forbidden", "project-authorized")
-CREDENTIAL_CEILINGS = ("forbidden", "project-authorized")
-PRIVACY_CEILINGS = ("local-only", "project-approved-egress", "external")
-TELEMETRY_CEILINGS = ("forbidden", "local-only", "project-authorized")
-COST_CEILINGS = ("none", "free", "low", "medium", "high")
-
-DEFAULT_RETRIEVAL_BUDGET_V3: dict[str, int] = {
-    "maxSteps": 16,
-    "maxCandidatesPerStep": 50,
-}
-DEFAULT_RETRIEVAL_POLICY_V3: dict[str, object] = {
-    "filesystem": "read",
-    "process": "execute",
-    "network": "forbidden",
-    "credentials": "forbidden",
-    "privacy": "local-only",
-    "egressDestinations": [],
-    "telemetry": "local-only",
-    "cost": "free",
-}
-
-MAX_QUERY_BYTES = 16 * 1024
-MAX_SCOPE_HINTS = 128
-MAX_SCOPE_HINT_BYTES = 512
-MAX_EVIDENCE_KINDS = 64
-MAX_LOGICAL_ID_BYTES = 128
-LOGICAL_ID = re.compile(r"^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$")
-SEMVER = re.compile(
-    r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
-    r"(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?"
-    r"(?:\+[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?$"
-)
-RFC3339 = re.compile(
-    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$"
-)
-LOGICAL_REF = re.compile(
-    r"^(?:artifact|evidence|source|git|test)://"
-    r"([a-z0-9]+(?:[._-][a-z0-9]+)*(?:/[a-z0-9]+(?:[._-][a-z0-9]+)*)*)$"
-)
-SENSITIVE_REFERENCE_TERMS = frozenset(
-    {"credential", "credentials", "passwd", "password", "secret", "token"}
-)
-FORBIDDEN_JSON_KEYS = frozenset({"__proto__", "constructor", "prototype"})
-_MISSING_CONTEXT = object()
-
-EXACT_SIGNALS = (
-    "where is",
-    "defined",
-    "definition",
-    "symbol",
-    "path",
-    "file",
-    "literal",
-    "identifier",
-    "exact",
-    "grep",
-    "rg ",
-    "在哪里",
-    "定义",
-    "路径",
-    "文件",
-    "字面量",
-)
-SEMANTIC_SIGNALS = (
-    "concept",
-    "conceptual",
-    "semantic",
-    "behavior",
-    "behaviour",
-    "how does",
-    "unknown name",
-    "概念",
-    "语义",
-    "行为",
-    "如何工作",
-)
-STRUCTURAL_SIGNALS = (
-    "caller",
-    "callee",
-    "call graph",
-    "dependency",
-    "dependencies",
-    "impact",
-    "blast radius",
-    "structural",
-    "architecture",
-    "调用者",
-    "调用链",
-    "依赖",
-    "影响面",
-    "结构",
-    "架构",
-)
-EXTERNAL_SIGNALS = (
-    "latest",
-    "current version",
-    "release note",
-    "official docs",
-    "web",
-    "cve",
-    "external",
-    "remote system",
-    "最新",
-    "当前版本",
-    "发布说明",
-    "官方文档",
-    "外部",
-    "远端系统",
-)
-
-
-def _utf8_key(value: str) -> bytes:
-    return value.encode("utf-8")
-
-
-def _copy_policy(policy: dict[str, object]) -> dict[str, object]:
-    destinations = cast(list[str], policy["egressDestinations"])
-    return {**policy, "egressDestinations": list(destinations)}
-
-
-def _canonical_json(value: object) -> str:
-    return json.dumps(
-        value,
-        sort_keys=True,
-        ensure_ascii=False,
-        separators=(",", ":"),
-        allow_nan=False,
-    )
-
-
-def _is_plain_json_tree(
-    value: object,
-    *,
-    active: set[int] | None = None,
-    depth: int = 0,
-    counter: list[int] | None = None,
-) -> bool:
-    """Accept only finite builtin JSON trees and reject cycles/subclasses."""
-    if active is None:
-        active = set()
-    if counter is None:
-        counter = [0]
-    counter[0] += 1
-    if counter[0] > 100_000 or depth > 64:
-        return False
-    if value is None or type(value) in (str, bool, int):
-        return True
-    if type(value) is float:
-        return math.isfinite(value)
-    if type(value) not in (dict, list):
-        return False
-    identity = id(value)
-    if identity in active:
-        return False
-    active.add(identity)
-    try:
-        if type(value) is list:
-            items = cast(list[object], value)
-            return all(
-                _is_plain_json_tree(
-                    item, active=active, depth=depth + 1, counter=counter
-                )
-                for item in items
-            )
-        mapping = cast(dict[object, object], value)
-        if any(
-            type(key) is not str or key in FORBIDDEN_JSON_KEYS
-            for key in mapping
-        ):
-            return False
-        return all(
-            _is_plain_json_tree(
-                item, active=active, depth=depth + 1, counter=counter
-            )
-            for item in mapping.values()
-        )
-    finally:
-        active.remove(identity)
-
-
-def fingerprint_pactile_contract_v1(value: object) -> str:
-    digest = hashlib.sha256(_canonical_json(value).encode("utf-8")).hexdigest()
-    return f"sha256:{digest}"
-
-
-def _issue(
-    issues: list[dict[str, str]], code: str, path: str, message: str
-) -> None:
-    issues.append({"code": code, "path": path, "message": message})
-
-
-def _sorted_issues(issues: list[dict[str, str]]) -> list[dict[str, str]]:
-    return sorted(issues, key=lambda item: (_utf8_key(item["path"]), _utf8_key(item["code"])))
-
-
-def _record(
-    value: object,
-    path: str,
-    allowed: tuple[str, ...],
-    issues: list[dict[str, str]],
-) -> dict[str, object] | None:
-    if type(value) is not dict:
-        _issue(issues, "invalid-type", path, "must be an object")
-        return None
-    allowed_set = set(allowed)
-    output: dict[str, object] = {}
-    for key in sorted(value, key=_utf8_key):
-        if type(key) is not str:
-            _issue(issues, "unknown-field", path, "must contain only string fields")
-        elif key not in allowed_set:
-            _issue(issues, "unknown-field", path, "contains an unknown field")
-        else:
-            output[key] = value[key]
-    return output
-
-
-def _required(
-    record: dict[str, object] | None,
-    key: str,
-    path: str,
-    issues: list[dict[str, str]],
-) -> object:
-    if record is None or key not in record:
-        _issue(issues, "missing-field", f"{path}.{key}", "is required")
-        return None
-    return record[key]
-
-
-def _array(
-    value: object,
-    path: str,
-    issues: list[dict[str, str]],
-    max_items: int,
-) -> list[object]:
-    if type(value) is not list:
-        _issue(issues, "invalid-type", path, "must be an array")
-        return []
-    if len(value) > max_items:
-        _issue(issues, "limit-exceeded", path, f"must contain at most {max_items} items")
-    return list(value[:max_items])
-
-
-def _text(
-    value: object,
-    path: str,
-    issues: list[dict[str, str]],
-    *,
-    max_bytes: int,
-    collapse_whitespace: bool = False,
-    logical_id: bool = False,
-) -> str:
-    if type(value) is not str:
-        _issue(issues, "invalid-type", path, "must be a string")
-        return ""
-    try:
-        value.encode("utf-8")
-    except UnicodeEncodeError:
-        _issue(issues, "invalid-value", path, "must contain valid Unicode scalar values")
-        return ""
-    normalized = (
-        re.sub(r"\s+", " ", value).strip() if collapse_whitespace else value.strip()
-    )
-    normalized = unicodedata.normalize("NFC", normalized)
-    if not normalized:
-        _issue(issues, "invalid-value", path, "must not be empty")
-    if any(unicodedata.category(character) == "Cc" for character in normalized):
-        _issue(issues, "invalid-value", path, "must not contain control characters")
-    if len(normalized.encode("utf-8")) > max_bytes:
-        _issue(issues, "limit-exceeded", path, f"must be at most {max_bytes} UTF-8 bytes")
-    if logical_id and normalized and LOGICAL_ID.fullmatch(normalized) is None:
-        _issue(issues, "invalid-value", path, "must be a lowercase logical id")
-    return normalized
-
-
-def _enum(
-    value: object,
-    values: tuple[str, ...],
-    path: str,
-    issues: list[dict[str, str]],
-) -> str:
-    if type(value) is not str or value not in values:
-        _issue(issues, "invalid-value", path, f"must be one of: {', '.join(values)}")
-        return values[0]
-    return value
-
-
-def _integer(
-    value: object,
-    path: str,
-    issues: list[dict[str, str]],
-    minimum: int,
-    maximum: int,
-) -> int:
-    if type(value) is not int or value < minimum or value > maximum:
-        _issue(
-            issues,
-            "invalid-value",
-            path,
-            f"must be a safe integer from {minimum} through {maximum}",
-        )
-        return minimum
-    return value
-
-
-def _string_set(
-    value: object,
-    path: str,
-    issues: list[dict[str, str]],
-    *,
-    max_items: int,
-    max_bytes: int,
-    logical_id: bool = False,
-) -> list[str]:
-    raw = _array(value, path, issues, max_items)
-    normalized = [
-        _text(
-            item,
-            f"{path}[{index}]",
-            issues,
-            max_bytes=max_bytes,
-            logical_id=logical_id,
-        )
-        for index, item in enumerate(raw)
-    ]
-    seen: set[str] = set()
-    for index, item in enumerate(normalized):
-        if item in seen:
-            _issue(
-                issues,
-                "duplicate-value",
-                f"{path}[{index}]",
-                "must be unique after normalization",
-            )
-        seen.add(item)
-    return sorted(normalized, key=_utf8_key)
-
-
-def _policy(
-    value: object, path: str, issues: list[dict[str, str]]
-) -> dict[str, object]:
-    allowed = (
-        "filesystem",
-        "process",
-        "network",
-        "credentials",
-        "privacy",
-        "egressDestinations",
-        "telemetry",
-        "cost",
-    )
-    record = _record(value, path, allowed, issues)
-    policy: dict[str, object] = {
-        "filesystem": _enum(
-            _required(record, "filesystem", path, issues),
-            FILESYSTEM_CEILINGS,
-            f"{path}.filesystem",
-            issues,
-        ),
-        "process": _enum(
-            _required(record, "process", path, issues),
-            PROCESS_CEILINGS,
-            f"{path}.process",
-            issues,
-        ),
-        "network": _enum(
-            _required(record, "network", path, issues),
-            NETWORK_CEILINGS,
-            f"{path}.network",
-            issues,
-        ),
-        "credentials": _enum(
-            _required(record, "credentials", path, issues),
-            CREDENTIAL_CEILINGS,
-            f"{path}.credentials",
-            issues,
-        ),
-        "privacy": _enum(
-            _required(record, "privacy", path, issues),
-            PRIVACY_CEILINGS,
-            f"{path}.privacy",
-            issues,
-        ),
-        "egressDestinations": _string_set(
-            _required(record, "egressDestinations", path, issues),
-            f"{path}.egressDestinations",
-            issues,
-            max_items=64,
-            max_bytes=256,
-        ),
-        "telemetry": _enum(
-            _required(record, "telemetry", path, issues),
-            TELEMETRY_CEILINGS,
-            f"{path}.telemetry",
-            issues,
-        ),
-        "cost": _enum(
-            _required(record, "cost", path, issues),
-            COST_CEILINGS,
-            f"{path}.cost",
-            issues,
-        ),
-    }
-    if policy["network"] == "forbidden" and (
-        policy["privacy"] != "local-only" or policy["egressDestinations"]
-    ):
-        _issue(
-            issues,
-            "policy-violation",
-            f"{path}.privacy",
-            "network-forbidden policy cannot permit egress",
-        )
-    if (
-        policy["network"] == "project-authorized"
-        and policy["privacy"] != "local-only"
-        and not policy["egressDestinations"]
-    ):
-        _issue(
-            issues,
-            "policy-violation",
-            f"{path}.egressDestinations",
-            "external egress requires at least one destination",
-        )
-    if policy["network"] == "forbidden" and policy["telemetry"] == "project-authorized":
-        _issue(
-            issues,
-            "policy-violation",
-            f"{path}.telemetry",
-            "network-forbidden policy cannot permit remote telemetry",
-        )
-    return policy
-
-
-def _budget(
-    value: object, path: str, issues: list[dict[str, str]]
-) -> dict[str, int]:
-    record = _record(value, path, ("maxSteps", "maxCandidatesPerStep"), issues)
-    return {
-        "maxSteps": _integer(
-            _required(record, "maxSteps", path, issues),
-            f"{path}.maxSteps",
-            issues,
-            1,
-            32,
-        ),
-        "maxCandidatesPerStep": _integer(
-            _required(record, "maxCandidatesPerStep", path, issues),
-            f"{path}.maxCandidatesPerStep",
-            issues,
-            1,
-            1000,
-        ),
-    }
-
-
-def _intents(
-    value: object, path: str, issues: list[dict[str, str]]
-) -> list[str]:
-    raw = _array(value, path, issues, len(INTENT_ORDER))
-    if not raw:
-        _issue(issues, "invalid-value", path, "must contain at least one intent")
-    values = [
-        _enum(item, INTENT_ORDER, f"{path}[{index}]", issues)
-        for index, item in enumerate(raw)
-    ]
-    seen: set[str] = set()
-    for index, item in enumerate(values):
-        if item in seen:
-            _issue(issues, "duplicate-value", f"{path}[{index}]", "must be unique")
-        seen.add(item)
-    return [intent for intent in INTENT_ORDER if intent in seen]
-
-
-def parse_retrieval_request_v3(value: object) -> dict[str, object]:
-    """Strictly parse and canonicalize a V3 request."""
-    if type(value) is not dict or not _is_plain_json_tree(value):
-        return {
-            "success": False,
-            "issues": [
-                {
-                    "code": "invalid-type",
-                    "path": "$",
-                    "message": "must be a plain data value",
-                }
-            ],
-        }
-    issues: list[dict[str, str]] = []
-    try:
-        record = _record(
-            value,
-            "$",
-            (
-                "schemaVersion",
-                "query",
-                "intents",
-                "scopeHints",
-                "minimumAssurance",
-                "requestedPolicy",
-                "requiredEvidenceKinds",
-                "budget",
-            ),
-            issues,
-        )
-        schema_version = _required(record, "schemaVersion", "$", issues)
-        if type(schema_version) is not int or schema_version != RETRIEVAL_ABI_VERSION:
-            _issue(issues, "invalid-value", "$.schemaVersion", "must equal 3")
-        query = _text(
-            _required(record, "query", "$", issues),
-            "$.query",
-            issues,
-            max_bytes=MAX_QUERY_BYTES,
-            collapse_whitespace=True,
-        )
-        intents = _intents(_required(record, "intents", "$", issues), "$.intents", issues)
-        scope_hints = _string_set(
-            _required(record, "scopeHints", "$", issues),
-            "$.scopeHints",
-            issues,
-            max_items=MAX_SCOPE_HINTS,
-            max_bytes=MAX_SCOPE_HINT_BYTES,
-        )
-        minimum_assurance = _enum(
-            _required(record, "minimumAssurance", "$", issues),
-            ASSURANCE_LEVELS,
-            "$.minimumAssurance",
-            issues,
-        )
-        requested_policy = _policy(
-            _required(record, "requestedPolicy", "$", issues),
-            "$.requestedPolicy",
-            issues,
-        )
-        required_evidence_kinds = _string_set(
-            _required(record, "requiredEvidenceKinds", "$", issues),
-            "$.requiredEvidenceKinds",
-            issues,
-            max_items=MAX_EVIDENCE_KINDS,
-            max_bytes=MAX_LOGICAL_ID_BYTES,
-            logical_id=True,
-        )
-        if minimum_assurance != "best-effort" and not required_evidence_kinds:
-            _issue(
-                issues,
-                "policy-violation",
-                "$.requiredEvidenceKinds",
-                "evidence-backed and verified requests require evidence kinds",
-            )
-        budget = _budget(_required(record, "budget", "$", issues), "$.budget", issues)
-        if issues:
-            return {"success": False, "issues": _sorted_issues(issues)}
-        return {
-            "success": True,
-            "data": {
-                "schemaVersion": RETRIEVAL_ABI_VERSION,
-                "query": query,
-                "intents": intents,
-                "scopeHints": scope_hints,
-                "minimumAssurance": minimum_assurance,
-                "requestedPolicy": requested_policy,
-                "requiredEvidenceKinds": required_evidence_kinds,
-                "budget": budget,
-            },
-        }
-    except (AttributeError, KeyError, TypeError, UnicodeError, ValueError):
-        return {
-            "success": False,
-            "issues": [
-                {
-                    "code": "invalid-type",
-                    "path": "$",
-                    "message": "must be a plain data value",
-                }
-            ],
-        }
-
-
-def classify_codebase_retrieval_intents(query: str) -> list[str]:
-    """Return the four canonical intents in frozen order."""
-    normalized = unicodedata.normalize("NFC", re.sub(r"\s+", " ", query).strip()).lower()
-    matched: set[str] = set()
-    if any(signal in normalized for signal in EXACT_SIGNALS):
-        matched.add("exact")
-    if any(signal in normalized for signal in SEMANTIC_SIGNALS):
-        matched.add("semantic")
-    if any(signal in normalized for signal in STRUCTURAL_SIGNALS):
-        matched.add("structural")
-    if any(signal in normalized for signal in EXTERNAL_SIGNALS):
-        matched.add("external")
-    if not matched:
-        matched.add("exact")
-    return [intent for intent in INTENT_ORDER if intent in matched]
-
-
-def build_retrieval_request_v3(
-    query: str,
-    *,
-    intents: list[str] | tuple[str, ...] | None = None,
-    scope_hints: list[str] | tuple[str, ...] | None = None,
-    minimum_assurance: str = "evidence-backed",
-    requested_policy: dict[str, object] | None = None,
-    required_evidence_kinds: list[str] | tuple[str, ...] | None = None,
-    budget: dict[str, int] | None = None,
-) -> dict[str, object]:
-    candidate: dict[str, object] = {
-        "schemaVersion": RETRIEVAL_ABI_VERSION,
-        "query": query,
-        "intents": list(intents) if intents is not None else classify_codebase_retrieval_intents(query),
-        "scopeHints": list(scope_hints if scope_hints is not None else []),
-        "minimumAssurance": minimum_assurance,
-        "requestedPolicy": _copy_policy(
-            requested_policy
-            if requested_policy is not None
-            else DEFAULT_RETRIEVAL_POLICY_V3
-        ),
-        "requiredEvidenceKinds": list(
-            required_evidence_kinds
-            if required_evidence_kinds is not None
-            else ("source-reference",)
-        ),
-        "budget": dict(budget if budget is not None else DEFAULT_RETRIEVAL_BUDGET_V3),
-    }
-    parsed = parse_retrieval_request_v3(candidate)
-    if not parsed["success"]:
-        raise ValueError(
-            "PACTILE_RETRIEVAL_REQUEST_INVALID:" + _canonical_json(parsed["issues"])
-        )
-    return dict(cast(dict[str, object], parsed["data"]))
-
-
-def _parse_planning_context(value: object) -> dict[str, object]:
-    if type(value) is not dict or not _is_plain_json_tree(value):
-        return {
-            "success": False,
-            "issues": [
-                {
-                    "code": "invalid-type",
-                    "path": "$context",
-                    "message": "must be a plain data value",
-                }
-            ],
-        }
-    issues: list[dict[str, str]] = []
-    try:
-        record = _record(value, "$context", ("providerAvailability",), issues)
-        raw = record.get("providerAvailability", []) if record is not None else []
-        entries = _array(raw, "$context.providerAvailability", issues, 3)
-        output: list[dict[str, object]] = []
-        seen: set[str] = set()
-        for index, entry in enumerate(entries):
-            path = f"$context.providerAvailability[{index}]"
-            item = _record(entry, path, ("intent", "status", "readiness"), issues)
-            intent = _enum(
-                _required(item, "intent", path, issues),
-                PROVIDER_INTENTS,
-                f"{path}.intent",
-                issues,
-            )
-            status = _enum(
-                _required(item, "status", path, issues),
-                PROVIDER_STATUSES[1:],
-                f"{path}.status",
-                issues,
-            )
-            readiness_raw = item.get("readiness") if item is not None else None
-            readiness = (
-                None
-                if readiness_raw is None
-                else _enum(readiness_raw, PROVIDER_READINESS, f"{path}.readiness", issues)
-            )
-            if intent in seen:
-                _issue(issues, "duplicate-value", f"{path}.intent", "must be unique")
-            seen.add(intent)
-            if readiness is not None and status != "unsupported" and status != readiness:
-                _issue(
-                    issues,
-                    "policy-violation",
-                    f"{path}.readiness",
-                    "must agree with the neutral provider status",
-                )
-            if status == "unsupported" and readiness not in (None, "unavailable"):
-                _issue(
-                    issues,
-                    "policy-violation",
-                    f"{path}.readiness",
-                    "unsupported intent may only report unavailable readiness",
-                )
-            value_out: dict[str, object] = {"intent": intent, "status": status}
-            if readiness is not None:
-                value_out["readiness"] = readiness
-            output.append(value_out)
-        if issues:
-            return {"success": False, "issues": _sorted_issues(issues)}
-        ordered = [
-            entry
-            for intent in PROVIDER_INTENTS
-            for entry in output
-            if entry["intent"] == intent
-        ]
-        return {"success": True, "data": ordered}
-    except (AttributeError, KeyError, TypeError, UnicodeError, ValueError):
-        return {
-            "success": False,
-            "issues": [
-                {
-                    "code": "invalid-type",
-                    "path": "$context",
-                    "message": "must be a plain data value",
-                }
-            ],
-        }
-
-
-def _status_reason(intent: str, status: str) -> dict[str, object] | None:
-    codes = {
-        "resolution-required": "provider-resolution-required",
-        "degraded": "provider-degraded",
-        "unavailable": "provider-unavailable",
-        "unsupported": "provider-unsupported",
-    }
-    code = codes.get(status)
-    return None if code is None else {"code": code, "intent": intent, "blocking": True}
-
-
-def _build_plan(
-    request: dict[str, object], availability: list[dict[str, object]]
-) -> dict[str, object]:
-    request_intents = cast(list[str], request["intents"])
-    request_scope_hints = cast(list[str], request["scopeHints"])
-    requested_policy = cast(dict[str, object], request["requestedPolicy"])
-    required_evidence_kinds = cast(list[str], request["requiredEvidenceKinds"])
-    request_budget = cast(dict[str, int], request["budget"])
-    statuses = {str(entry["intent"]): str(entry["status"]) for entry in availability}
-    all_steps: list[dict[str, object]] = []
-    for index, raw_intent in enumerate(request_intents):
-        intent = str(raw_intent)
-        if intent == "exact":
-            all_steps.append(
-                {
-                    "order": index + 1,
-                    "intent": intent,
-                    "kind": "local-exact",
-                    "localToolHint": "rg",
-                    "providerRequirement": None,
-                    "outputRole": "candidate",
-                }
-            )
-            continue
-        status = statuses.get(intent, "resolution-required")
-        all_steps.append(
-            {
-                "order": index + 1,
-                "intent": intent,
-                "kind": "provider-request",
-                "localToolHint": None,
-                "providerRequirement": {
-                    "intent": intent,
-                    "minimumAssurance": request["minimumAssurance"],
-                    "requestedPolicy": _copy_policy(requested_policy),
-                    "requiredEvidenceKinds": list(required_evidence_kinds),
-                    "status": status,
-                },
-                "outputRole": "candidate",
-            }
-        )
-    steps = [
-        {**step, "order": index + 1}
-        for index, step in enumerate(all_steps[: request_budget["maxSteps"]])
-    ]
-    stop_reasons: list[dict[str, object]] = []
-    if len(steps) < len(all_steps):
-        stop_reasons.append({"code": "budget-exhausted", "intent": None, "blocking": True})
-    for step in steps:
-        requirement = step["providerRequirement"]
-        if type(requirement) is dict:
-            reason = _status_reason(str(requirement["intent"]), str(requirement["status"]))
-            if reason is not None:
-                stop_reasons.append(reason)
-    plan: dict[str, object] = {
-        "schemaVersion": RETRIEVAL_ABI_VERSION,
-        "query": request["query"],
-        "intents": list(request_intents),
-        "scopeHints": list(request_scope_hints),
-        "minimumAssurance": request["minimumAssurance"],
-        "requestedPolicy": _copy_policy(requested_policy),
-        "requiredEvidenceKinds": list(required_evidence_kinds),
-        "budget": dict(request_budget),
-        "steps": steps,
-        "verificationChain": [
-            {
-                "order": 1,
-                "stage": "candidate",
-                "required": True,
-                "acceptableEvidenceKinds": [],
-            },
-            *[
-                {
-                    "order": order,
-                    "stage": stage,
-                    "required": True,
-                    "acceptableEvidenceKinds": list(CORROBORATION_KINDS),
-                }
-                for order, stage in (
-                    (2, "corroborate"),
-                    (3, "classify-evidence"),
-                    (4, "check-assurance"),
-                    (5, "accept-or-stop"),
-                )
-            ],
-        ],
-        "stopReasons": stop_reasons,
-    }
-    plan["fingerprint"] = fingerprint_pactile_contract_v1(plan)
-    return plan
-
-
-def plan_retrieval_v3(
-    request: object, context: object = _MISSING_CONTEXT
-) -> dict[str, object]:
-    parsed = parse_retrieval_request_v3(request)
-    if not parsed["success"]:
-        return parsed
-    context_value: object = {} if context is _MISSING_CONTEXT else context
-    availability = _parse_planning_context(context_value)
-    if not availability["success"]:
-        return availability
-    return {
-        "success": True,
-        "data": _build_plan(
-            dict(cast(dict[str, object], parsed["data"])),
-            list(cast(list[dict[str, object]], availability["data"])),
-        ),
-    }
-
-
-def route_codebase_retrieval(
-    query: str,
-    *,
-    intents: list[str] | tuple[str, ...] | None = None,
-    scope_hints: list[str] | tuple[str, ...] | None = None,
-    minimum_assurance: str = "evidence-backed",
-    requested_policy: dict[str, object] | None = None,
-    required_evidence_kinds: list[str] | tuple[str, ...] | None = None,
-    budget: dict[str, int] | None = None,
-    provider_availability: list[dict[str, object]] | None = None,
-    **_compatibility_metadata: object,
-) -> dict[str, object]:
-    """Build a deterministic V3 plan; compatibility metadata has no effect."""
-    request = build_retrieval_request_v3(
-        query,
-        intents=intents,
-        scope_hints=scope_hints,
-        minimum_assurance=minimum_assurance,
-        requested_policy=requested_policy,
-        required_evidence_kinds=required_evidence_kinds,
-        budget=budget,
-    )
-    result = plan_retrieval_v3(
-        request,
-        {
-            "providerAvailability": list(provider_availability)
-            if provider_availability is not None
-            else []
-        },
-    )
-    if not result["success"]:
-        raise ValueError("PACTILE_RETRIEVAL_PLAN_INVALID:" + _canonical_json(result["issues"]))
-    return dict(cast(dict[str, object], result["data"]))
-
-
-def _normalized_refs(values: object) -> list[str] | None:
-    if type(values) is not list or len(values) > 1024:
-        return None
-    output: list[str] = []
-    for value in values:
-        if type(value) is not str or not _valid_logical_ref(value):
-            return None
-        output.append(value)
-    return sorted(set(output), key=_utf8_key)
-
-
-def _normalized_facts(values: object) -> list[dict[str, str]] | None:
-    if type(values) is not list or len(values) > 1024:
-        return None
-    output: list[dict[str, str]] = []
-    seen: set[tuple[str, str]] = set()
-    for value in values:
-        if type(value) is not dict or set(value) != {"kind", "ref"}:
-            return None
-        kind = value["kind"]
-        ref = value["ref"]
-        if (
-            type(kind) is not str
-            or LOGICAL_ID.fullmatch(kind) is None
-            or type(ref) is not str
-            or not _valid_logical_ref(ref)
-        ):
-            return None
-        identity = (kind, ref)
-        if identity not in seen:
-            seen.add(identity)
-            output.append({"kind": kind, "ref": ref})
-    return sorted(output, key=lambda item: (_utf8_key(item["kind"]), _utf8_key(item["ref"])))
-
-
-def _valid_plan(plan: object, intent: str) -> bool:
-    expected_keys = {
-        "schemaVersion",
-        "query",
-        "intents",
-        "scopeHints",
-        "minimumAssurance",
-        "requestedPolicy",
-        "requiredEvidenceKinds",
-        "budget",
-        "steps",
-        "verificationChain",
-        "stopReasons",
-        "fingerprint",
-    }
-    if (
-        type(plan) is not dict
-        or not _is_plain_json_tree(plan)
-        or set(plan) != expected_keys
-        or type(plan.get("intents")) is not list
-        or intent not in plan["intents"]
-        or type(plan.get("steps")) is not list
-    ):
-        return False
-    request = {
-        key: plan[key]
-        for key in (
-            "schemaVersion",
-            "query",
-            "intents",
-            "scopeHints",
-            "minimumAssurance",
-            "requestedPolicy",
-            "requiredEvidenceKinds",
-            "budget",
-        )
-    }
-    availability: list[dict[str, object]] = []
-    for candidate in cast(list[object], plan["steps"]):
-        if type(candidate) is not dict:
-            return False
-        requirement = candidate.get("providerRequirement")
-        if requirement is None:
-            continue
-        if type(requirement) is not dict:
-            return False
-        provider_intent = requirement.get("intent")
-        status = requirement.get("status")
-        if provider_intent not in PROVIDER_INTENTS or status not in PROVIDER_STATUSES:
-            return False
-        if status != "resolution-required":
-            availability.append(
-                {
-                    "intent": provider_intent,
-                    "status": status,
-                    "readiness": "unavailable" if status == "unsupported" else status,
-                }
-            )
-    replanned = plan_retrieval_v3(
-        request, {"providerAvailability": availability}
-    )
-    return bool(replanned.get("success") and replanned.get("data") == plan)
-
-
-def _valid_logical_ref(value: str) -> bool:
-    if len(value) > 256:
-        return False
-    match = LOGICAL_REF.fullmatch(value)
-    if match is None:
-        return False
-    return not any(
-        term in SENSITIVE_REFERENCE_TERMS
-        for term in re.split(r"[._/-]", match.group(1))
-    )
-
-
-def _valid_core_string_array(value: object) -> bool:
-    return (
-        type(value) is list
-        and all(type(item) is str and bool(item.strip()) for item in value)
-        and len(value) == len(set(value))
-    )
-
-
-def _valid_timestamp(value: object) -> bool:
-    if type(value) is not str or RFC3339.fullmatch(value) is None:
-        return False
-    try:
-        datetime.fromisoformat(value.replace("Z", "+00:00"))
-    except ValueError:
-        return False
-    return True
-
-
-def _parsed_policy(value: object) -> dict[str, object] | None:
-    issues: list[dict[str, str]] = []
-    parsed = _policy(value, "$policy", issues)
-    return None if issues else parsed
-
-
-def _policy_within(requested: dict[str, object], ceiling: dict[str, object]) -> bool:
-    dimensions = (
-        ("filesystem", FILESYSTEM_CEILINGS),
-        ("process", PROCESS_CEILINGS),
-        ("network", NETWORK_CEILINGS),
-        ("credentials", CREDENTIAL_CEILINGS),
-        ("privacy", PRIVACY_CEILINGS),
-        ("telemetry", TELEMETRY_CEILINGS),
-        ("cost", COST_CEILINGS),
-    )
-    try:
-        if any(
-            values.index(str(requested[key])) > values.index(str(ceiling[key]))
-            for key, values in dimensions
-        ):
-            return False
-        requested_destinations = cast(list[str], requested["egressDestinations"])
-        ceiling_destinations = cast(list[str], ceiling["egressDestinations"])
-        return all(destination in ceiling_destinations for destination in requested_destinations)
-    except (KeyError, TypeError, ValueError):
-        return False
-
-
-def _valid_resolution(plan: dict[str, object], intent: str, value: object) -> bool:
-    required_keys = {
-        "schemaVersion",
-        "intent",
-        "minimumAssurance",
-        "origin",
-        "providerId",
-        "providerVersion",
-        "assurance",
-        "readiness",
-        "requestedPolicy",
-        "effectivePolicy",
-        "evidenceRefs",
-        "freshness",
-        "probedAt",
-        "probeResult",
-        "fallbackFromProviderId",
-    }
-    if (
-        type(value) is not dict
-        or not _is_plain_json_tree(value)
-        or set(value) != required_keys
-    ):
-        return False
-    origin = value["origin"]
-    provider_id = value["providerId"]
-    provider_version = value["providerVersion"]
-    assurance = value["assurance"]
-    readiness = value["readiness"]
-    requested_policy = _parsed_policy(value["requestedPolicy"])
-    effective_policy = _parsed_policy(value["effectivePolicy"])
-    freshness = value["freshness"]
-    probed_at = value["probedAt"]
-    probe_result = value["probeResult"]
-    fallback = value["fallbackFromProviderId"]
-    if (
-        type(value["schemaVersion"]) is not int
-        or value["schemaVersion"] != 1
-        or value["intent"] not in INTENT_ORDER
-        or value["intent"] != intent
-        or value["minimumAssurance"] not in ASSURANCE_LEVELS
-        or value["minimumAssurance"] != plan["minimumAssurance"]
-        or origin not in ("native", "provider", "heuristic", "unsupported")
-        or readiness not in PROVIDER_READINESS
-        or freshness not in ("fresh", "stale", "unknown", "not-applicable")
-        or probe_result not in ("passed", "failed", "not-run")
-        or (provider_id is not None and (type(provider_id) is not str or LOGICAL_ID.fullmatch(provider_id) is None))
-        or (provider_version is not None and (type(provider_version) is not str or SEMVER.fullmatch(provider_version) is None))
-        or (assurance is not None and assurance not in ASSURANCE_LEVELS)
-        or (fallback is not None and (type(fallback) is not str or LOGICAL_ID.fullmatch(fallback) is None))
-        or requested_policy is None
-        or fingerprint_pactile_contract_v1(requested_policy)
-        != fingerprint_pactile_contract_v1(plan["requestedPolicy"])
-        or not _valid_core_string_array(value["evidenceRefs"])
-    ):
-        return False
-    if origin == "unsupported":
-        return False
-    if (
-        provider_id is None
-        or provider_version is None
-        or assurance is None
-        or effective_policy is None
-        or readiness != "ready"
-        or not _policy_within(effective_policy, requested_policy)
-        or ASSURANCE_LEVELS.index(assurance)
-        < ASSURANCE_LEVELS.index(str(plan["minimumAssurance"]))
-    ):
-        return False
-    if assurance in ("evidence-backed", "verified") and not value["evidenceRefs"]:
-        return False
-    if assurance == "verified" and (
-        freshness != "fresh"
-        or probe_result != "passed"
-        or not _valid_timestamp(probed_at)
-    ):
-        return False
-    if probed_at is not None and not _valid_timestamp(probed_at):
-        return False
-    if probe_result == "not-run" and probed_at is not None:
-        return False
-    if probe_result != "not-run" and probed_at is None:
-        return False
-    if provider_id is not None and fallback == provider_id:
-        return False
-    return True
-
-
-def _rejected(intent: str, reasons: list[str], evidence_refs: list[str] | None = None) -> dict[str, object]:
-    unique = set(reasons)
-    return {
-        "schemaVersion": RETRIEVAL_ABI_VERSION,
-        "intent": intent,
-        "accepted": False,
-        "achievedAssurance": None,
-        "evidenceRefs": list(evidence_refs or []),
-        "reasonCodes": [code for code in REASON_CODES if code in unique],
-    }
-
-
-def assess_retrieval_claim_v3(value: object) -> dict[str, object]:
-    """Assess facts without treating ranking confidence as evidence."""
-    intent = "exact"
-    try:
-        if (
-            type(value) is not dict
-            or not _is_plain_json_tree(value)
-            or any(
-                key
-                not in {
-                    "plan",
-                    "intent",
-                    "candidateRefs",
-                    "corroboration",
-                    "resolution",
-                    "providerScore",
-                }
-                for key in value
-            )
-        ):
-            return _rejected(intent, ["invalid-evidence"])
-        raw_intent = value.get("intent")
-        if raw_intent not in INTENT_ORDER:
-            return _rejected(intent, ["invalid-evidence"])
-        intent = cast(str, raw_intent)
-        plan = value.get("plan")
-        if intent not in INTENT_ORDER or not _valid_plan(plan, intent):
-            return _rejected(intent, ["invalid-plan"])
-        plan = cast(dict[str, object], plan)
-        required_evidence_kinds = cast(list[str], plan["requiredEvidenceKinds"])
-        plan_steps = cast(list[dict[str, object]], plan["steps"])
-        candidate_refs = _normalized_refs(value.get("candidateRefs"))
-        facts = _normalized_facts(value.get("corroboration"))
-        if candidate_refs is None or facts is None:
-            return _rejected(intent, ["invalid-evidence"])
-        evidence_refs = sorted(
-            set(candidate_refs + [fact["ref"] for fact in facts]), key=_utf8_key
-        )
-        reasons: list[str] = []
-        if not candidate_refs:
-            reasons.append("candidate-missing")
-        fact_kinds = {fact["kind"] for fact in facts}
-        if any(kind not in fact_kinds for kind in required_evidence_kinds):
-            reasons.append("required-evidence-missing")
-        has_corroboration = any(kind in CORROBORATION_KINDS for kind in fact_kinds)
-        has_repeatable_test = "repeatable-test" in fact_kinds
-        if intent != "exact" and not has_corroboration:
-            reasons.append("corroboration-required")
-        step = next((item for item in plan_steps if item.get("intent") == intent), None)
-        requirement = step.get("providerRequirement") if type(step) is dict else None
-        status = (
-            requirement.get("status")
-            if type(requirement) is dict
-            else None
-        )
-        status_reasons = {
-            "degraded": "provider-degraded",
-            "unavailable": "provider-unavailable",
-            "unsupported": "provider-unsupported",
-        }
-        if status in status_reasons:
-            reasons.append(status_reasons[status])
-        resolution_valid = intent == "exact" or _valid_resolution(
-            plan, intent, value.get("resolution")
-        )
-        if intent != "exact" and not resolution_valid:
-            reasons.append("minimum-assurance-not-met")
-        minimum = str(plan["minimumAssurance"])
-        achieved: str | None
-        if minimum == "best-effort":
-            achieved = "best-effort"
-        elif not has_corroboration:
-            achieved = None
-        elif minimum == "evidence-backed":
-            achieved = "evidence-backed"
-        else:
-            achieved = "verified" if has_repeatable_test else None
-        if achieved is None:
-            reasons.append(
-                "repeatable-verification-required"
-                if minimum == "verified"
-                else "minimum-assurance-not-met"
-            )
-        resolution = value.get("resolution")
-        if minimum == "verified" and intent != "exact" and (
-            not resolution_valid
-            or type(resolution) is not dict
-            or resolution.get("assurance") != "verified"
-        ):
-            reasons.append("verified-provider-proof-required")
-        if reasons or achieved is None:
-            return _rejected(intent, reasons, evidence_refs)
-        return {
-            "schemaVersion": RETRIEVAL_ABI_VERSION,
-            "intent": intent,
-            "accepted": True,
-            "achievedAssurance": achieved,
-            "evidenceRefs": evidence_refs,
-            "reasonCodes": [],
-        }
-    except (AttributeError, KeyError, TypeError, UnicodeError, ValueError):
-        return _rejected(intent, ["invalid-evidence"])
-
-
-def codebase_retrieval_selected_from_capabilities(
-    _capabilities: dict[str, Any] | None,
-) -> bool:
-    """Compatibility helper; V3 capability resolution is deferred."""
-    return True
-
-
-def load_capabilities_json(repo_root: Path | None) -> dict[str, Any] | None:
-    """Compatibility reader retained for callers that inspect project metadata."""
-    if repo_root is None:
-        return None
-    path = repo_root / ".pactile" / "capabilities.json"
-    if not path.is_file():
-        return None
-    try:
-        parsed = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError):
-        return None
-    return parsed if type(parsed) is dict else None
-
-
-def resolve_router_envelope(
-    _repo_root: Path | None,
-    *,
-    explicit_router: dict[str, Any] | None = None,
-    query: str | None = None,
-    **_compatibility_metadata: object,
-) -> dict[str, object] | None:
-    """Validate an explicit V3 request/plan or build a plan from a query."""
-    if type(explicit_router) is dict:
-        explicit_intents = explicit_router.get("intents")
-        first_intent = (
-            explicit_intents[0]
-            if type(explicit_intents) is list and explicit_intents
-            else "exact"
-        )
-        if _valid_plan(explicit_router, str(first_intent)):
-            return dict(explicit_router)
-        parsed = parse_retrieval_request_v3(explicit_router)
-        if parsed["success"]:
-            planned = plan_retrieval_v3(parsed["data"])
-            return (
-                dict(cast(dict[str, object], planned["data"]))
-                if planned["success"]
-                else None
-            )
-        explicit_query = explicit_router.get("query")
-        if type(explicit_query) is str and explicit_query.strip():
-            return route_codebase_retrieval(explicit_query)
-    normalized = re.sub(r"\s+", " ", query or "").strip()
-    return route_codebase_retrieval(normalized) if normalized else None