feat: Neo4j entity graph (phase 9) — catalog sync, Dagster asset, S2 /graph endpoints

[oldhero5]

Summary

Builds the reserved phase-9 Neo4j entity graph: the what/who/connected layer over the instrument catalog. Numbers stay in ArcticDB — the graph mirrors identity only (instruments, balancing authorities, ERCOT hubs/load zones, NOAA regions, commodities, observed fuel types) plus curated cross-domain edges, per the original unified-platform spec's locked decision #8.

• energex.core.graph (pure): build_entity_graph() derives a GraphPlan from symbology + connector vocabularies + store-observed entities; compiles to batched idempotent UNWIND…MERGE Cypher with first_seen/last_seen provenance. The neo4j driver (6.2.0 as locked) is imported lazily in exactly one function; sync/queries duck-type the driver, so no test or graph-extra-less install ever imports it.
• Orchestration: Neo4jResource (EnvVar-bound, redacted errors), entity_graph asset with store-driven discovery (BAs from power.demand symbols, fuel types from power.generation_by_fuel tails — no hardcoded lists), entity_graph_instruments_resolve asset check, daily 06:10 ET schedule that probes reachability and skips (not fails) when the optional neo4j is absent.
• S2 read API: GET /graph/entities + GET /graph/related (semantic-rel traversal only), lazy connect with 15s backoff, 503 degradation, additive graph flag on /healthz; gated by the optional API key like every other data endpoint.
• Wiring/docs: api image gains the graph extra + NEO4J env; CI graph-gate job; .env.example NEO4J_AUTH/NEO4J_PASSWORD sync warning; new website/docs/entity-graph.md + contract-table additions.

Verification

• 296 tests green (41 graph tests, all offline via duck-typed fake drivers — no Neo4j in CI); ruff clean; docs site builds.
• Live-verified against neo4j:5.26.0-community: driver-6.x compatibility, idempotent re-sync (identical counts, stable first_seen), /graph/* end-to-end through uvicorn.
• Synced against the production store: 539 nodes / 1,332 edges from 73 discovered balancing authorities.
• A 20-agent adversarial review produced 10 confirmed findings, all fixed in fix(graph).

Notes for review

• Merge-order dependency: the entity-graph doc's fuel-mix note describes the in-flight fix for the pre-existing generation-by-fuel storage dedup collapse (discovered during this work's review; being fixed in a separate session/PR). If this PR merges first, the note is slightly ahead of reality until that fix lands; the graph's fuel discovery itself needs no change either way.
• /graph/* has no as_of by design — the graph is a current-state catalog with first_seen/last_seen provenance; anything time-series-shaped stays behind read_as_of.
• Rebased onto main after docs: rewrite all docs for the power-markets platform + publish to GitHub Pages #26–feat(observer): Data Observer Phase 2 — Catalog/Explorer + 4V Health dashboard #28; the api's new NEO4J_PASSWORD compose var follows main's required-var (:?) style.

Test plan

• CI: all gates including the new graph-gate
• docker compose --profile full up -d --build, materialize entity_graph in Dagster, browse http://localhost:7474
• curl localhost:8000/graph/related?instrument_id=ERCOT.SPP.HB_NORTH

🤖 Generated with Claude Code