{
  "uid": "cogitave.learn.core-model-fundamentals.the-property-graph-substrate",
  "kind": "moduleUnit",
  "href": "/modules/core-model-fundamentals/the-property-graph-substrate/",
  "title": "The property-graph substrate",
  "summary": "",
  "type": null,
  "products": [],
  "roles": [],
  "levels": [],
  "subjects": [],
  "headings": [
    "The decision: ADR-0001",
    "The physical substrate: one process, four subsystems",
    "Why full-scratch here specifically"
  ],
  "source": "The previous unit took \"one typed property graph\" as given. This unit is\nabout why a **labeled property graph** specifically, and what makes that one\ngraph fast enough to be the read path for every product.\n\n## The decision: ADR-0001\n\n[ADR-0001](../../../../core/docs/decisions/0001-property-graph-as-substrate.md)\nframes the problem plainly: docs, an internal developer portal, governance and\ncompliance evidence, multi-cloud infra inventory, and agent knowledge all need\nto be *the same knowledge*, queryable by humans and agents alike. The default\nindustry shape - one store per domain (a docs CMS, an IDP catalog, a CMDB, a\nvector store) - guarantees drift and duplicated identity. Four options were\nweighed:\n\n| Option | Verdict |\n| --- | --- |\n| Single labeled property graph (LPG) | **Chosen** |\n| Relational schema + a separate graph view | Buries the graph actually being traversed |\n| RDF / triple store (SPARQL) | Higher-ceremony, weaker property ergonomics for faceting/ranking |\n| Document store per domain, federated at query time | Re-introduces the drift the decision exists to eliminate |\n\nThe LPG was chosen because it is now an **ISO standard** - GQL, ISO/IEC\n39075:2024, the first new ISO query-language standard since SQL in 1987 - with\na mature open lineage in openCypher, and because nodes and edges carrying\nproperties directly matches faceting and ranking needs without join\ngymnastics. That standard is authored against as a **spec, not a dependency**:\nCogitave's in-process engine is full-scratch, consistent with treating\noff-the-shelf systems as reference rather than something to depend on.\n\nThe trade-off is named honestly in the ADR too: a single model is a single\nblast radius, mitigated by content-addressing and a blocking validation gate;\nand a closed edge vocabulary needs governance to evolve, which is deliberate,\nto keep traversal and evidence stable.\n\n## The physical substrate: one process, four subsystems\n\nThe [substrate](../../../../core/docs/substrate.md) doc describes how the\ngraph is actually served. One Rust binary co-locates four subsystems in a\nsingle address space, so a query never crosses a network boundary mid-flight:\na **lexical** engine (BM25 over immutable, mergeable segments), a **vector**\nengine (in-process HNSW ANN), the **property graph** itself (typed adjacency\nplus Personalized-PageRank rerank), and the **MCP server** - stdio for\nlocal/CI, Streamable HTTP for the edge - embedded directly as the query layer,\nnot a process sitting in front of it.\n\nBuild and serve are deliberately decoupled: authoring, parsing, enrichment,\nembedding, and index emission run in the TypeScript (namzu) pipeline, which is\nallowed to be heavy because it is off the hot path; it hands the Rust serving\nprocess three immutable materializations behind a new content root. The only\ncontract between them is the content hash.\n\n## Why full-scratch here specifically\n\nTantivy-class BM25, HNSW libraries, and vector databases are cited as\n**reference implementations**, not dependencies. The reasoning is vertical\nintegration: co-locating lexical, vector, and graph retrieval behind one MCP\nserver with one snapshot model and one cache key is a property no assembled\nstack of separate services gives you - the \"one model, one query layer\"\nthesis, restated as an engineering consequence rather than an aspiration.\n",
  "partOf": "cogitave.learn.core-model-fundamentals",
  "durationInMinutes": 7,
  "quiz": null
}