feat(graph): reintroduce query-time graph expansion via Apache AGE (follow-up)

[mfittko]

Context

graphExpand query-time expansion was removed while graph strategy is being redesigned. We now plan to use Apache AGE on Postgres: https://age.apache.org/

Goal

Reintroduce optional graph-assisted query expansion on top of the current Postgres + pgvector stack, implemented via Apache AGE.

Scope (proposed)

• Keep current vector retrieval path as default and stable.
• Add feature-flagged AGE integration for graph traversal.
• Reintroduce optional query-time expansion behavior (graphExpand or renamed equivalent).
• Ensure graceful fallback to vector-only retrieval when AGE is disabled/unavailable.

Proposed phases

1. Foundation
   • Add AGE extension support in DB runtime/migrations.
   • Add session bootstrap (LOAD 'age', search_path handling) in API data access path.
2. Graph storage + traversal
   • Define graph schema/mapping for entities and relationships.
   • Add traversal query primitives for 1–2 hop expansion from extracted entities.
3. API/CLI integration
   • Add optional expansion flag to query path.
   • Return expansion metadata in response (when enabled).
4. Hardening
   • Integration tests for vector-only, vector+graph, and fallback paths.
   • Performance guardrails and timeout caps for graph traversal.

Acceptance criteria

• AGE and pgvector run in the same Postgres deployment used by raged.
• Query endpoint supports optional graph-assisted expansion behind a feature flag.
• Vector-only retrieval behavior is unchanged when graph expansion is off.
• API/CLI docs are updated with configuration and behavior.
• Integration tests cover success and fallback scenarios.

Notes

• Validate AGE/Postgres version compatibility before implementation.
• Prefer minimal API contract changes; keep existing clients compatible by default.