Fix portable KAG MCP canonical reads

[8Dionysus]

Outcome

Restore the aoa-kag-mcp canonical fallback after the repository-family v3 rollout. The MCP now resolves a tracked portable-family manifest when the logical v2 source_surface_index.json coordinate is intentionally absent, while preserving the existing five-tool / nine-resource ABI.

Root cause

query_repo_local_kag.load_family() already understood v3 manifests and shards, but the MCP adapter refused to call it unless the physical v2 source-index monolith existed. Structural ABI validation therefore passed while a real canonical search failed at runtime.

Changes

• resolve canonical input from the physical v2 source index when present, otherwise from the contained v3 portable_family.manifest_ref
• key the canonical query cache and owner digest off that resolved family boundary
• add traversal-containment, digest, and v3-without-v2 regression tests
• make service validation perform an executable canonical portable read
• document the v3 fallback and refresh the repo-local KAG family with an explicit generated-delta budget receipt

Validation

• focused aoa-kag-mcp: 7 passed
• actual MCP search + record read through canonical-repo-local over v3 shards: passed
• service contract: 24 providers, 5 tools, 9 resources, canonical portable owner aoa-kag
• source-fast: nested AGENTS 45 docs, stack/local-stats validators, 52 authority tests
• full release gate: 846 passed, 2 skipped, 144 subtests
• KAG family: 715 shards, 21,724,495 tracked bytes, digest 4ffb2d1168d791e23ebc6a62ca5f1a91f54475a5f3c6b1e949249e09cae1624a

Decision: aoa-kag:docs/decisions/AOA-KAG-D-0017-portable-content-addressed-repository-family.md

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b9c4ccc182

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Validate portable metadata through the provider-map fallback

When a valid provider map keeps repo_local_index only in its supported top-level provider_repo_local_indexes fallback (which AoAKagMCPState.repo_local_index() explicitly resolves), this loop sees None and skips the provider. If every v3 provider uses that representation, the newly added service validator exits with “found no readable portable KAG provider” even though canonical reads work; retrieve the packet through state.repo_local_index(repo) here.

Useful? React with 👍 / 👎.