The knowledge graph

Everything Spine answers is grounded in a Provenance Knowledge Graph (PKG) — a deterministic fact model extracted from your code and your documentation.

Why a graph, not a chat log

Spine’s architecture forbids force-directed layouts: a picture that redraws differently for an identical commit can’t be diffed. Positions are computed once with a seeded layout, so the same commit renders the identical graph every time. Determinism is the feature, not a limitation.

8 node kinds

Node	What it is
Module	a file or package
Type	class, struct, interface
Function	a callable unit
Field	attribute or constant
Endpoint	HTTP route / handler
Entity	data-layer table
Doc	ingested documentation
Intent	the ticket a symbol was last changed for

11 edge kinds

IMPORTS · CONTAINS · CALLS · IMPLEMENTS · READS · WRITES · EXPOSES · CONSUMES · REFERENCES · MENTIONS · SERVES

Every edge carries a location. For example:

auth.validate   — CALLS →      models.get_user
models.get_user — READS →      password_hash
docs/auth.md    — MENTIONS →   auth.validate

Documentation is a first-class citizen

Spine ingests 9 document formats — .md .markdown .rst .txt .html .htm .pdf .docx .xlsx — and turns each into a Doc node linked to the symbols it MENTIONS. That’s what powers doc drift: detecting when a document claims a symbol that no longer exists, or says code is tested when it isn’t.

Boundaries

The deterministic build is text-only — no model ever runs in it. .pdf needs the [docs] extra; .docx/.xlsx need [office]. Image OCR ([media]) and audio/video transcription ([asr]) are opt-in and off by default — the model runs only in a separate orchestrator media extract, which commits a transcript the build then reads.

Measured, not asserted

“Grounded” is a number here, not an adjective. Graph accuracy is precision and recall per node and edge kind, for all 8 front-ends, against a published hand-labelled corpus:

orchestrator pkg accuracy            # precision/recall per kind
orchestrator pkg accuracy --check    # CI gate: fails when a gated number drops

Precision is 1.00 on every node kind and every edge kind, in all 8 languages. A committed baseline fails CI when a gated number regresses, so the graph can’t quietly get worse.

Across several repositories

Several repos can merge into one graph, so “what breaks if I change this?” can answer with a caller in a different repo. Declare the set in .spine/repos.yaml:

orchestrator pkg extract --repos
orchestrator investigate --repos      # cross-repo landing sites
orchestrator pkg joins --propose      # derive the join topology from evidence

The joins are derived from evidence, not drawn by hand — and what could not be joined is reported, because a missing cross-repo edge looks exactly like two uncoupled services.