feat: cross-namespace refs — materialized ccg:// links, federated reads, cross-repo analysis

[tae2089]

What

Turns annotation-declared ccg:// references into a first-class cross-repository (cross-namespace) system, in three layers:

1. Materialization — new cross_refs table (migration 000015, SQLite + PostgreSQL). Every @see ccg://{namespace}/{path}#{symbol} tag becomes a row with a symbolic target plus derived state (resolved_node_id, status: resolved|dead, source). A sync hook after every build/update rebuilds outbound rows and re-resolves inbound rows, so links survive replace-style rebuilds (webhook Replace: true regenerates node ids), go dead when the target symbol disappears, and recover when it returns. Resolution shares one matcher with ccg lint, so dead-ref findings and cross_refs status can never disagree.
2. Federated reads — search, query_graph, list_graph_stats, search_docs accept namespaces: [] and fan out per namespace at the handler layer. Results are labeled per namespace; single-namespace responses are byte-identical to before. Store query paths keep their single-namespace invariant.
3. Cross-repo analysis — get_impact_radius / trace_flow accept cross_namespace: true: a namespace-agnostic reader merges resolved refs into traversal as synthetic cross_ref edges (never persisted), so the existing BFS/trace algorithms run unchanged across repo boundaries. New list_cross_refs tool exposes the repository-level dependency map (tool count 17 → 18).

Also fixes the Postgres integration suite, broken on main since 5404e24: the compose file's --allow-repo=*/* is rejected by that commit's multi-owner collision guard, so ccg-server refused to start. Pinned to testadmin/* (the suite's Gitea admin).

Why

Namespaces fully isolate per-repository graphs; the only cross-namespace primitive was list_namespaces. Cross-repo dependencies declared via @see ccg:// were plain tag text — not queryable, not traversable, no reverse lookup. Annotation refs were chosen over import-based linking because they are language-agnostic (polyglot service boundaries have no imports) and reuse the existing parser/lint/wiki infrastructure. The source column leaves room for future import-derived signals without schema rework.

Reviewer notes

• Commits are split Tidy First: one structural refactor (shared ref matcher extraction), then three behavioral commits (materialization → federated reads → analysis), docs, and the integration fix.

• cross_refs is derived state: fully rebuildable from annotations, deleted/re-created per source namespace inside one transaction. No raw SQL outside migration files; both backends get the same 000015.

• The synthetic cross_ref edge kind never reaches the edges table; the flow tracer accepts it as a continuation only because regular stores never emit it.

• query_graph federation isolates per-namespace node not found as a per-namespace error entry instead of failing the whole call; file_summary still returns a zero summary for missing files (pre-existing behavior).

• The integration suite gained Phase 13: a real webhook push of a ccg:// annotation, then list_cross_refs (outbound/inbound), cross_namespace: true impact with namespace labels, default-scoped impact, and federated search — all verified against PostgreSQL. Banner now reports 16/18.

• Known tradeoff (reviewed, deliberately kept): cross-ref sync runs post-commit and fails hard. A sync failure after a committed build makes build_or_update_graph report total failure (skipping FTS/flow postprocess and cache flush) and skips webhook cache invalidation. Accepted because the failure is rare, cross_refs is self-healing derived state (webhook retry / cache TTL / next build), and softening it would change the Build/Update result contract late in the PR. Revisit if sync failures are observed in practice.

Verification

• CGO_ENABLED=1 go test -tags "fts5" ./... -count=1 — all 43 packages green. Includes an end-to-end test: Go source comment @see ccg://… → tree-sitter build → resolved cross_refs row → target rebuild → id remap / dead / revive.
• ./scripts/integration-test.sh (Gitea + PostgreSQL + ccg Docker) — PASSED after the allow-repo fix: webhook push → clone → build → Postgres store pipeline, migrations incl. 000015, MCP tool phases.

🤖 Generated with Claude Code