{
  "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: choosing a graph substrate",
    "The physical substrate: one process, four subsystems",
    "Why co-locate, and why Cogitave goes full-scratch"
  ],
  "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 in your estate.\n\n## The decision: choosing a graph substrate\n\nAny org picking this substrate faces the same problem: docs, an internal\ndeveloper portal, governance and compliance evidence, multi-cloud infra\ninventory, and agent knowledge all need to be *the same knowledge*, queryable\nby humans and agents alike. The default industry shape - one store per domain\n(a docs CMS, an IDP catalog, a CMDB, a vector store) - guarantees drift and\nduplicated identity. Cogitave records its own answer in\n[ADR-0001](../../../../core/docs/decisions/0001-property-graph-as-substrate.md),\nwhich frames the problem plainly and weighs four options:\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\nIn that ADR the LPG wins 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. Notably, the standard is authored against as a **spec, not a\ndependency**: Cogitave's in-process engine is full-scratch, consistent with a\nhouse style that treats off-the-shelf systems as reference rather than\nsomething to depend on. That is Cogitave's stance, not a requirement of the\npattern - you could pick the same LPG model and run it on an off-the-shelf\ngraph database.\n\nThe trade-off is named honestly, and it is inherent to the pattern: a single\nmodel is a single blast radius, mitigated (in Cogitave's case) by\ncontent-addressing and a blocking validation gate; and a closed edge vocabulary\nneeds governance to evolve, which is deliberate, to keep traversal and evidence\nstable.\n\n## The physical substrate: one process, four subsystems\n\nHow the graph is actually served is an implementation choice, and Cogitave's\n[substrate](../../../../core/docs/substrate.md) doc describes one concrete\nanswer. One Rust binary co-locates four subsystems in a single address space,\nso a query never crosses a network boundary mid-flight: a **lexical** engine\n(BM25 over immutable, mergeable segments), a **vector** engine (in-process HNSW\nANN), the **property graph** itself (typed adjacency plus Personalized-PageRank\nrerank), and the **MCP server** - stdio for local/CI, Streamable HTTP for the\nedge - embedded directly as the query layer, not a process sitting in front of\nit.\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 co-locate, and why Cogitave goes full-scratch\n\nCo-locating lexical, vector, and graph retrieval behind one query layer, with\none snapshot model and one cache key, is a property no assembled stack of\nseparate services gives you - the \"one model, one query layer\" thesis restated\nas an engineering consequence rather than an aspiration. That payoff is the\ntransferable lesson. Cogitave then takes it to the limit: Tantivy-class BM25,\nHNSW libraries, and vector databases are cited as **reference implementations**,\nnot dependencies, and the engine is built full-scratch for vertical\nintegration. That last step is one org's answer for maximum sovereignty, not\nsomething the pattern forces on you.\n",
  "partOf": "cogitave.learn.core-model-fundamentals",
  "durationInMinutes": 7,
  "quiz": null
}