feat(planner): knowledge-aware routing — temporal representation (Whitepaper v4)

[arybach]

Knowledge-aware execution planning (v4 groundwork)

Shifts the planner's decision from which retrieval algorithm to which knowledge representation answers the request — and makes temporal (bi-temporal) a first-class routable representation. Fully backward compatible; full suite green.

The idea

The planner already routes multi_hop → graph (HippoRAG). This generalizes that pattern: a request maps to a knowledge representation (document / graph / temporal / analytical / community / code / multimodal), and the concrete retrieval method is a specialization within it. Retrieval becomes one family of knowledge access, not the whole of it.

What's in this PR

• types.py — temporal IntentBucket + a KnowledgeRepresentation taxonomy.
• planner/representations.py (new) — retrieval-method → representation map + helpers.
• planner/rules.py — temporal intent cues (as of / what changed / superseded / point-in-time), placed before multi_hop; BUCKET_DEFAULTS/BUCKET_TIERS emit a temporal candidate plus a hybrid fallback (the cost model picks).
• adapters/store_router.py — optional temporal slot with empty-fallback: routes to the bi-temporal store only when one is bound and a fact matches; otherwise falls back to single-hop. The new constructor param defaults to None, so every existing caller (incl. the control plane) is unchanged.
• costmodel/estimators.py — temporal recall + a temporal-bucket edge so the planner prefers the bi-temporal store for time-dependent questions (mirrors how multi_hop prefers graph).
• tests/test_temporal_routing.py (new) — 8 tests: intent routing, cost edge, router dispatch + fallback, bi-temporal point-in-time (as_of) & what-changed (changes), taxonomy, end-to-end run.

Open-core boundary (deliberate)

This PR ships the abstraction + routing scaffold + the in-memory reference plugins only. The differentiated engines stay optional/enterprise bindings behind the same RetrieverPlugin seam:

• Temporal: reference = the in-memory TemporalStore already in the tree; a real Graphiti engine + bi-temporal ingestion pipeline bind at construction time.
• Graph: already routes end-to-end; the real HippoRAG backend is an optional dep bound at the graph slot.
• Heavier representations (OLAP/ClickHouse/Doris, SQL) are future plugins on the same interface.

Notes

• Backward compatible: HopRouterRetriever(single_hop, graph, community=None, temporal=None).
• No control-plane behavior change: with no temporal store wired, temporal-classified queries fall back to hybrid exactly as today.

🤖 Generated with Claude Code