Mission should model persisted code-intelligence graph data with one canonical node table and one canonical edge table instead of proliferating normal tables for each graph concept.

Context

ADR-0004.03 established that Mission’s code intelligence index is a daemon-owned, rebuildable SurrealDB-backed read model generated from Mission-owned Zod schemas and @flying-pillow/zod-surreal metadata.

That decision did not fully settle the simplest durable graph shape. The current implementation direction still carries separate normal tables such as code_file, code_symbol, and code_relation, with relationship semantics partly encoded in query code and foreign-key-like string fields. That shape is workable for a first load path, but it is not the cleanest graph authority and makes future graph expansion noisier than necessary.

Mission needs one explicit answer to these questions:

  • what is the minimal persisted graph shape for code intelligence;
  • how are nodes distinguished without one table per node kind;
  • how are edges distinguished without generic flat relation rows;
  • how is one graph snapshot anchored without ambiguous names such as indexId.

Decision

Mission will model persisted code-intelligence graph data with two canonical storage families:

  • code_object: every persisted graph node;
  • code_relation: every persisted graph edge.

Both families are generated from Mission-owned Zod schemas annotated with @flying-pillow/zod-surreal metadata. Hand-maintained SurrealQL is not the source of truth.

code_object is a typed node table. It is not an unstructured JSON bag. Every row must declare a canonical objectKind that identifies the node family it belongs to. Initial objectKind values may include:

  • root
  • file
  • symbol

Additional node kinds such as route, tool, process, or cluster may be added later through the same schema-owned vocabulary.

code_relation is a typed edge table. Every row must declare a canonical relationKind that identifies the relationship vocabulary it belongs to. Initial relationKind values may include:

  • contains
  • defines
  • imports
  • calls

Additional relation kinds may be added later through the same schema-owned vocabulary.

code_relation is the canonical place for graph edges. Graph links must not remain modeled as ordinary normal-table rows with only ad hoc foreign-key strings once this model is adopted.

Graph snapshot ownership must use explicit snapshot vocabulary. Use snapshotId for the reference to the owning code-index snapshot. Do not use indexId as the durable canonical name because it is ambiguous between index definition, active snapshot, and indexing process.

The indexer contract is part of this decision. The indexer must emit canonical node and edge records for the graph store rather than specialized table-shaped outputs such as code_file or code_symbol rows.

Markdown and other non-code text files may be indexed at file/document node level by default. Optional Agent-assisted semantic enrichment for those files may be added behind the indexer as a separate provider capability, but it must remain disabled by default and must not become required for baseline indexing.

Consequences

  • Mission gets one simple graph core that can grow without one table per node type.
  • Graph DDL, type vocabulary, and traversal semantics stay schema-owned.
  • Snapshot ownership becomes explicit and less ambiguous.
  • Existing code-intelligence schemas and store logic will need a structural migration from code_file / code_symbol / code_relation normal tables to code_object / code_relation node-edge storage.
  • Query code can stop reconstructing graph meaning from flat tables and instead traverse canonical edges.

Rules

  • code_object rows must expose canonical id and objectKind.
  • code_relation rows must expose canonical id, relationKind, in, and out.
  • snapshotId is the canonical ownership reference from nodes and edges to the code-index snapshot that owns them.
  • Node-specific or edge-specific optional fields are allowed, but they must remain schema-defined and bounded by kind semantics.
  • code_object must not become a mixed-content bucket with opaque per-row shape drift.
  • code_relation must not be replaced by plain string link fields when the relationship is graph-native and first-class.

Relationship To Other Decisions

  • ADR-0004.03 remains the authority for why Mission owns a SurrealDB-backed, rebuildable code-intelligence index.
  • ADR-0001.08 remains the authority for the general OGM/storage/view law across Entity and related storage families.
  • This ADR is the focused decision for the minimal persisted graph shape of the code-intelligence domain.