perf(retrieval): drive frequency lookup from token hash

[suguanYang]

Summary

• Fix retrieval frequency lookups that timed out on large namespaces by driving the query from matching channel + token_hash rows instead of scanning scoped map units first.
• Apply the same token-hash-driven lookup to classic retrieval and the agentic map-nav loader while preserving user, namespace, and revision scoping.
• No API, worker, prompt, migration, or backfill changes. Existing token-hash data and indexes are used.
• Related task: production retrieval frequency-query statement timeout.

Verification

• 42 retrieval contract tests passed.
• Ruff passed.
• git diff --check passed.
• Targeted source Pyright passed.
• Production read-only database equivalent SQL was inspected with EXPLAIN ANALYZE: the plan uses idx_document_map_unit_tokens_lookup, performs token lookup first, and completed in approximately 12 ms on the reproduced query shape.
• No production data was modified and no production backfill was run.

Deployment Notes

• No new or changed environment variables.
• No database migration, queue, or storage change.
• No namespace snapshot or map-unit backfill is required for this code change; it consumes the existing token-hash index/data.
• The change is backwards compatible with existing persisted revisions. Rollback is the previous application image/commit.
• After deployment, monitor retrieval statement timeouts and query latency for both classic and map-nav routes.

Checklist

• Tests were added or updated when behavior changed
• Public docs, examples, or OpenAPI contracts were updated when needed
• Database migrations are idempotent and safe to deploy
• Logs, errors, and validation paths avoid leaking secrets or user data
• The pull request description explains any breaking or user-visible change