Knowledge Graph Source of Truth

Status: working memory Date: 2026-05-20

The shared graph is durable in repo artifacts, not in FalkorDB. FalkorDB is a projection/cache for traversal, query, and UI speed. If FalkorDB disappears, the graph should be rebuildable from Git-backed files plus live operational ledgers where those ledgers are the actual source of a runtime fact.

Core Rule

Nodes are backed by artifacts. Edges are backed by claims.

If an idea is no longer backed by Markdown, it ceases to exist in the projected graph. If an implementation has no code artifact, it ceases to exist in the projected graph. If a relationship is no longer claimed by any artifact, that edge disappears from the graph.

One Graph, Many Projections

There is one all-encompassing project graph. Wiki, QA, and Ops are not separate ontologies. They are projections for humans and AIs around that same graph.

The nine hub kinds are the ontology:

• idea
• behaviour
• implementation
• suite
• test
• anomaly
• infra
• event
• journal

Everything else is a surface, projection, artifact, source, action, or inspection mode. The old UI words are not trash; they were the precursor to the current graph. They should survive where they help people and agents operate, but they must not masquerade as graph node kinds.

Wiki owns meaning and memory around the graph. This sprint focuses on four active projections:

• Atlas is the map and navigation projection over all nine hubs.
• Canon presents ideas, architecture, principles, vocabulary, and their nearby behaviours and implementations.
• Codebook presents implementation nodes and the files, symbols, APIs, MCP tools, routes, workers, schemas, and packages that back them.
• Librarian is the assistant/query projection over the graph, not its own node kind.

Journal is the Wiki temporal projection and a graph hub kind. It is deferred from the current tab work, not demoted out of Wiki. Journal nodes interpret events and connect them back to anomalies, infra, implementations, behaviours, suites, tests, and ideas.

QA owns verification around the graph:

• Behaviour, Suites, and Tests are real hub kinds and form QA's primary slice: behaviour -> suite -> test.
• QA dashboard/API/MCP design should treat Behaviour, Suite, and Test pages as object POVs governed by these relationships. The active design note is wiki/content/working-memory/qa-object-pov-dashboard-design.md.
• Queue, queue items, run records, quality gates, flakes, dispatch evidence, and runner state are execution evidence and action surfaces. They attach to tests, suites, behaviours, implementations, infra, events, and anomalies; they are not competing graph node kinds.
• Investigate is a traversal/action projection: given a changed file, implementation, event, anomaly, or behaviour, it finds affected behaviours/suites/tests and can trigger the right checks.

Ops owns operation around the graph:

• Anomaly is the judgement projection: is observed user or system behaviour expected, or is there a harmful mismatch against an idea or behaviour?
• Infra is the substrate and forecast projection: will provider, quota, usage, cost, capacity, outage, or internal service pressure create an event before the month/runway/system fails?
• Event is the operational event pool and event-tape projection.
• Inspector is a graph-neighborhood projection for workspaces, services, events, anomalies, infra, implementations, and connected QA/Wiki context.
• Sysadmin is the response projection: what should L1, L2, or L3 do based on journal memory, affected implementations, tests, infra, events, and ideas?
• Status is a public trust projection. It exposes a thin, sanitized operational readout; it is not a separate graph ontology.

Those Ops projections are real, but they are out of scope for the current Wiki and QA renovation pass.

This means terms such as Codebook, Infra forecasts, Queue, Investigate, Atlas, or Librarian are valid product surfaces. They are not valid node kinds in the canonical graph. A file, page, route, provider URL, CI run, or source URL should enter the graph as artifact/evidence/properties behind one or more of the nine hub kinds, unless the domain discussion explicitly promotes it into one of those hub kinds.

Bottom-Up Construction

Every meaningful artifact is a typed atom. It declares what it is part of from its own point of view, and nothing more. A source file is not a relationship manager and should not try to describe the wider world.

Every descriptive or load-bearing file needs direct graph coverage. It is not enough for a parent folder, package, module, or broad implementation claim to roughly cover the area. The file must either carry its own claim or appear in a nearby owned declaration as an explicit backing artifact. This applies to code, tests, migrations, IaC, scripts, config, API contracts, and Markdown knowledge. Pure build output, vendored dependencies, caches, and generated files are excluded from this rule.

A single artifact claim has one node kind. All nodes in that claim are of that same kind. A code artifact can belong to one or more implementation nodes. A test artifact can belong to one or more test nodes. A Markdown artifact can belong to one or more idea, behaviour, or journal nodes, but each claim stays typed.

Edges are unlabeled outward connections to other nodes that are directly evidenced by the artifact. The relationship meaning is defined by the two node kinds, not by a free-form relation label. There is no self-edge for membership.

The source annotation syntax is deliberately smaller than the compiled graph. A source annotation is artifact-local: it carries only kind, nodes, an optional summary, optional symbols, and a links block keyed by hub kind. Comment-capable source files embed it in a @graph / @endgraph block; Markdown files use top-level frontmatter:

kind: implementation
nodes:
  - wiki-atlas
links:
  idea:
    - shared-knowledge-graph
  behaviour:
    - navigate-project-knowledge
  infra:
    - falkordb

Authors do not write scope, from, to, relation, kind inside node IDs, fromKind, or toKind in a source annotation. The compiler derives prefixed IDs and typed edges from the source kind and the target link bucket. The materialized graph may keep denormalized endpoint kinds because Falkor, validators, and UI projections need fast labels; source annotations must not duplicate that information.

If a file declares that it is part of A, B, and C, and C does not exist yet, then C exists by virtue of that declaration. Validation then decides which required links are missing.

There are two contracts:

• The artifact contract checks local truth. A file only claims the nodes and direct edges visible from that file. It must not invent missing context just to satisfy the broader graph.
• The aggregate contract checks graph health. Once all artifacts are scanned, each assembled node is judged against the stricter domain shape.

The difference between those contracts is intentional. If local evidence passes but the aggregate node is incomplete, the graph has found a review target: missing documentation, missing annotation, unrecorded behaviour, old cruft, or a real implementation/product mismatch.

Source-Backed Grounding

The five source-backed hubs are validated before we talk about Ops ledgers:

• idea must have an owning Markdown artifact.
• behaviour must have an owning Markdown or Gherkin .feature artifact.
• implementation must have owning code or config: code, schema, migration, IaC, package config, or similar load-bearing implementation material.
• suite must have an owning suite definition artifact and must contain at least two tests. One-test "suites" are review targets, not healthy suites, unless we later create an explicit exception type.
• test must have an owning test/spec artifact and must connect to both a suite and an implementation.

Owning artifacts are source, evidence, symbol, or unrole-tagged artifacts. reference artifacts explain why a node was mentioned, but they do not ground the node.

QA suite definitions live in qa/suites/*.yaml. The behaviour-index builder reads those files as source-backed suite nodes, resolves selection.test_paths and exact selection.glob entries through the generated test catalog, and stores source_path in the semantic index so API/MCP/UI graph projections can point a suite node back to its owning file. Suite files that point at archived or intentionally skipped catalogs remain review targets instead of being silently treated as healthy.

Node Backing

The canonical nine all enter the same graph, but not all of them are edited through file-backed metadata.

The file-backed metadata UI should start with the seven Yes rows. anomaly and event should be created and reconciled as Ops DB-backed objects first; promotion to Markdown or journal can make selected records file-backed later. The API/MCP/editor contract lives in GRAPH-METADATA-EDITOR.md.

Ops Sources

Events and anomalies are not Git-native files. They live in the Ops database. Raw tools such as Axiom, provider logs, CI logs, and Cloudflare dashboards are evidence sources. We mediate them into our own records before they enter the graph.

• anomaly: a DB record for a harmful expectation mismatch.
• event: a DB record for a promoted operational occurrence, forecast, alert, incident, deploy fact, audit fact, or similar occurrence.
• journal: a Markdown synthesis that references one or more events and makes sense of them.

Events are the upward-flow hub from Ops into the rest of the graph. An event must originate from either anomaly or infra. Journal then aggregates and interprets events.

Sanctioned Relationships

The graph is typed and constrained. Nodes do not accept arbitrary edges. Each hub kind has sanctioned adjacent kinds, and some are mandatory.

Same-kind links are always sanctioned. One idea can relate to another idea, one implementation can relate to another implementation, one test can relate to another test, and so on. These same-kind links are the graph's auto-connections: they express that two nodes in the same hub should be reviewed, understood, changed, or navigated together.

The table below lists the cross-kind relationships.

idea
  may connect to: behaviour, implementation, anomaly, journal

behaviour
  must connect to: idea
  may connect to: implementation, suite, anomaly, journal

implementation
  must connect to: idea or behaviour
  may connect to: infra, test, anomaly, journal

suite
  must connect to: behaviour, at least two tests

test
  must connect to: suite, implementation

anomaly
  must connect to: idea or behaviour
  must connect to: event
  may connect to: implementation, infra, journal

infra
  must connect to: idea, implementation
  may connect to: anomaly, event, journal

event
  must connect to: anomaly or infra
  may connect to: idea, behaviour, implementation, suite, test, journal

journal
  must connect to: event
  may connect to: anomaly, infra, implementation, behaviour, idea, suite, test

Evidence Dimension

The visible graph is the two-dimensional map of nodes and edges. Each node also has an evidence layer behind it: files, symbols, Markdown pages, DB rows, provider records, generated projections, and other backing artifacts.

This evidence layer is the third dimension of the graph. It answers where a node comes from, which artifacts constitute it, and which local claims created its edges. Traversal happens on the node graph; inspection drops into the evidence behind a node or edge.

Infra Decision

Infra should enforce IaC as the canonical source where possible. Provider readouts, usage, cost, quota, latency, outages, and current state are live enrichment. They attach events, metrics, anomalies, and journal context to the IaC-defined infra node.

Purely provider-discovered infra can create a node bottom-up, but if it becomes architecturally meaningful it should be promoted into an IaC or repo-backed declaration.