# ADR-0011 — Governed Production Knowledge Graph and GraphRAG - **Status:** Accepted; local projection and hybrid retrieval implemented - **Date:** 2026-08-04 - **Related:** ADR-0001 (RAG), ADR-0003 (Code Intelligence), ADR-0010 (Event Spine) ## Decision Forge adds a rebuildable Production Knowledge Graph read projection. It federates, rather than replaces, the existing graph systems: - **Graphify** remains the revision-bound AST call/dependency graph provider. - **Forge workflow DAGs** remain executable workflow definitions. - **The Canonical Event Spine** remains the authoritative execution-fact record. - **Item lineage** remains authoritative checkpoint metadata. - **Fabric RAG** remains semantic/lexical retrieval and gains optional graph-proximity reranking. The Production Graph connects code with domains Graphify does not parse: Jira tickets, Perforce art, Unity GUID assets, Forge workflows/runs/stages, artifacts, builds, incidents, owners and decisions. It is explicitly a read projection: it cannot execute, authorize, approve or acknowledge work. ## Contract Entities have stable workspace/game-scoped identity, source identity, revision, trust class and properties. Relations are typed and directional with origin, confidence, revision and trust. Trust classes are: 1. `authoritative` — directly parsed or emitted by an authority. 2. `derived` — deterministic structural inference such as Graphify proximity. 3. `hypothesis` — model or heuristic proposal, investigation-only. The local implementation is SQLite. Hosted Forge uses the PostgreSQL adapter and migration 014, with transaction-scoped workspace/game identity and row-level security. Storage remains behind the same repository contract. A dedicated graph database is not required until measured traversal workloads justify it. Local entity resolution uses an external-content SQLite FTS5 index maintained by database triggers; packages without FTS5 retain the correctness-first scan fallback. Unchanged projection rows are not rewritten. Status has a two-second cache, graph quality has a thirty-second cache, mutations invalidate both, and rebuild completion prewarms quality asynchronously off the request path. The local store runs in WAL mode with a single repository writer lock, a five-second busy timeout, passive checkpoint/optimize maintenance, integrity inspection and SQLite online backup. Current tables remain optimized for reads; append-only entity and relation history records prior snapshots, valid-time bounds and an Event Spine sequence when available. Local APIs support bounded `as_of` state and two-time graph diffs. For retained facts that predate history-table deployment, a one-time local backfill copies signed Event Spine records into an indexed temporal archive. Historical replay projects only those copied facts into an isolated temporary graph; it never calls an adapter, resumes a run or repeats an effect. Replay results identify their scope as `signed-event-projection`, because they cannot claim historical Graphify or Unity state that was not retained. Graphify projection keeps a revision/file fingerprint and per-source-file digest manifest. An unchanged bound graph file is not parsed; when it changes, only changed/removed file groups and their incident cross-file edges are reconciled. Removed derived entities are deleted from the current projection after their last state is retained in history. Graphify and Unity projections also retain revision-bound source manifests independently of the current entity projection. This allows operators to distinguish a faithful historical source snapshot from a reconstruction based only on signed events. Snapshot revisions are bounded by the local retention policy. ## GraphRAG flow ```text query → semantic/lexical candidate retrieval → entity resolution → bounded typed-edge expansion → graph-proximity reranking → budgeted excerpts + provenance → model ``` Graph retrieval is optional and fail-soft in local mode. It cannot invent missing semantic evidence. Agent access is through bounded domain operations (`ticket_implementation`, `asset_consumers`, `artifact_origin`, `change_blast_radius`, `related_incidents`, `build_contents`, `owner`), not unrestricted Cypher generated by a model. Traversal enforces independent depth, node, edge and per-node fan-out budgets. Generic traversal does not expand through a non-seed supernode; a capped seed returns its prioritized immediate neighbors as terminal nodes. Typed domain operations may expand capped nodes, but remain subject to the edge and fan-out ceilings. Every capped response sets `truncated`, names its truncation reasons and returns the applied budgets, so bounded evidence is never presented as a complete graph. A deterministic query planner selects semantic-only, graph-first, hybrid or temporal retrieval and records its matched intent. Common typed neighborhoods are persisted against a graph epoch and prewarmed after rebuild. Results include compact and raw provenance paths. Structural peer search uses a local sparse typed-neighborhood vector with cosine similarity; its results are always `derived` and never identity facts. Outcome feedback updates workspace-scoped relationship ranking weights only. It records success and failure counts, remains bounded between 0.5 and 1.5, is reversible, and cannot alter entities, relationships, validation or execution authority. Evaluation reports retrieval recall/MRR together with task success, token delta and answer-faithfulness fields from labelled cases. Explicit terminal workflow outcomes can apply the same bounded update when the event names the exact graph relations used to make the decision. Ambiguous or non-terminal events are ignored; outcome learning never creates or deletes graph facts. ## Runtime graph intelligence Forge and Fabric share a bounded runtime intelligence layer with four distinct graph roles: - The Production Graph supplies current and temporal production evidence. - The Capability Graph maps agents to stages, capabilities, tools, permissions, models and runtime environments; assignment hard-filters permissions before considering historical reliability. - The Fabric Execution Graph persists stage dependencies, state transitions, checkpoints and artifact lineage for resume and visual debugging. It projects only state-changing events and is fail-soft with respect to the authoritative run journal. - The Learning Graph observes validated outcomes in shadow mode. A relation needs a minimum sample count and a non-regressing evaluation metric before its bounded weight can affect retrieval; regression rolls the shadow weight back to the active value. Workspace Context is compiled after hybrid retrieval. The compiler deduplicates excerpts, applies a confidence floor, accounts for authority/freshness/revision, preserves the prompt budget and labels revision or claim conflicts rather than silently merging them. The model must cite evidence and surface unresolved conflicts. Graph evidence remains advisory. Graph planning is also advisory. It derives bounded impact evidence, identifies code and asset work, computes deterministic dependency batches for parallel stages, and always terminates in validation and approval. Counterfactual impact simulation is read-only and confidence decays with graph distance. Neither service invokes a tool. ## Projection sources - Graphify `graph.json` nodes and edges. - Signed Event Spine facts. - Deterministic item lineage. - Jira ticket text and exact `//GoT_Match/...` depot paths. - Unity `.meta` GUID identities and YAML GUID dependencies. - Explicit artifact/build manifests. File roots accepted by the rebuild service are confined to the Forge repository, configured Code Intelligence cache, and configured Unity project. Projection failure cannot trigger connector work. ## HTTP surface - `GET /api/production-graph/status` - `GET /api/production-graph/query?operation=asset_consumers&subject=...&depth=2` - `GET /api/production-graph/quality` - `POST /api/production-graph/rebuild` - `POST /api/production-graph/evaluate` - `GET /api/production-graph/smart-query` - `GET /api/production-graph/similarity` - `GET /api/production-graph/temporal` - `POST /api/production-graph/feedback` - `POST /api/production-graph/maintain` - `GET /api/production-graph/temporal/replay` - `POST /api/production-graph/temporal/backfill` - `POST /api/production-graph/local-qualification` - `POST /api/production-graph/retention` - `POST /api/production-graph/recovery-drill` - `GET /api/production-graph/capabilities` - `GET /api/production-graph/impact` - `GET|POST /api/production-graph/executions` - `POST /api/production-graph/executions/observe` - `POST /api/production-graph/context/compile` - `POST /api/production-graph/agents/assign` - `POST /api/production-graph/plan` - `POST /api/production-graph/learning/shadow` - `POST /api/production-graph/evaluation-lab` - `GET /api/production-graph/temporal/sources` The rebuild route is classified as governed `run`; both reads remain subject to Forge's existing read gate and workspace identity. Rebuild runs in a single-admission background worker and exposes `queued → graphify → event-spine → unity-assets? → ticket-assets? → artifact-manifests? → compaction → complete|failed`. The default refresh projects the current Graphify index and signed Event Spine without blocking the HTTP server. Unity indexing is explicit because walking a production project is materially more expensive. Event Spine projection is incremental per workspace/game. The last signed sequence is persisted in the selected graph store and only newer events are projected. Signed production facts create typed cross-system edges for ticket/run/workflow, PR/commit/file, build/artifact, incident/build, Perforce-art/Unity-import and validation/asset relationships. Explicit source deletion or revocation creates a tombstone: the entity leaves search and traversal but its retained evidence is not erased; a later authoritative observation reactivates it. Backend startup registers a best-effort notifier on the signed Event Spine. Durable appends debounce into one incremental projection refresh per workspace; projection failure can never fail or roll back the authoritative event. Operators retain the explicit rebuild control for repair and Unity scans. A relation's stable identity is `(source, target, type, origin, workspace, game)`; revision is mutable evidence metadata, not part of that identity. Re-observing a relation therefore advances its revision in place. The compaction phase removes parallel rows produced by the earlier revision-keyed representation while retaining the most recently observed evidence. Queries accept an optional exact `revision` filter. Quality inspection reports bounded full-corpus orphan counts, referential defects, cross-provider identity candidates, missing revisions, stale Graphify snapshots, tombstones and signed-event projection lag. Filename-based identity candidates are advisory only; they are never promoted to `SAME_AS` without exact source evidence or review. `POST /api/production-graph/identity/confirm` accepts 2–10 current-workspace entities plus a review reason and records symmetric, authoritative `SAME_AS` edges with reviewer provenance. This changes only the rebuildable read projection and grants no execution authority. The Train Fabric surface includes a read-only Production Knowledge Graph explorer. It invokes only the bounded domain operations, renders a capped node/edge view, and exposes provider, revision and trust metadata in an accessible evidence table. It does not accept a query language. Workspace Context attaches the same bounded node/edge evidence to graph-assisted retrieval packages. When semantic evidence exists and budget remains, a compact trust-labelled relationship path is included for Weave, planning, drafting, review and validation consumers. Graph-only findings do not violate the existing no-RAG-evidence contract and remain separately inspectable metadata. ## Evaluation gates Before graph influence is raised or used by additional agent consumers, fixed cases must measure entity resolution, edge/path precision, stale-revision behavior, workspace isolation, authorization leakage, token delta and task success against vector-only retrieval. Structural evidence remains advisory; compile, validation, policy and approval gates retain authority. The implemented deterministic evaluator reports baseline vs graph-guided recall@k and reciprocal rank, per-case rank delta and regression count. Evaluation is read-only and accepts at most 500 bounded cases per request. Local qualification records repeated p50/p95 measurements for indexed search, maximum-hub depth-2 traversal, materialized domain lookup and structural similarity. Fixed p95 ceilings are 5 ms, 25 ms, 5 ms and 15 ms respectively. Every run is persisted with its pass/fail outcome so local performance regressions remain auditable instead of relying on one-off console measurements. Significant incremental refreshes automatically schedule this qualification off the rebuild request path, with one in-flight qualification per workspace. Local retention prunes only rebuildable history, old qualification reports, stale structural embeddings, excess source-manifest revisions and excess online backups by default. Signed Event Spine archives are never age-pruned unless an operator explicitly supplies a non-zero event window; even then, incident and deployment evidence is preserved. The recovery drill restores the latest online backup into an isolated temporary database, checks SQLite integrity, counts and indexed search, and emits a SHA-256 certificate without modifying the live graph.