The unified product-knowledge property graph: ONE typed node/edge/provenance vocabulary covering every compiled product representation — curated feature catalog, e2e journeys and checks, docs-center reader pages, TODOS checkbox tasks, architecture/design/proposal/review documents, anchors, tours, invocation points, and routes — with one validator, one Merkle version, and queryable projections in Postgres and Neo4j.
The rule that keeps everything honest#
The checked-in composed artifact is the single source of truth. Postgres and Neo4j are PROJECTIONS of it — rebuildable from the artifact at any time, never hand-edited, never authoritative. Nothing writes to the knowledge plane at runtime; the graph only changes when a PR changes the sources and the artifact recompiles.
Layout#
src/types.ts— node/edge/provenance model, knowledge/intent plane splitsrc/validate.ts— kind-aware validator (endpoint rules, containment forest, DFS-block order, plane discipline, route integrity, supersedes acyclicity)src/traverse.ts— index-backed traversal (children/ancestors/descendants/edgesFrom/edgesTo/subgraph/propagateUp)src/hash.ts— canonical-JSON content addressing +composeVersionsrc/queries.ts— cross-representation lenses (whatTouchesRoute)src/compilers/— one pure compiler per sourcesrc/curation/— the reviewed alias/waiver tables (code, PR-gated)src/compose.ts+src/artifact.ts— composer and artifact reader/writersrc/generated/— the checked-in artifact (manifest + per-section JSONL; the todos bulk is a gitignored derived cache, hash-pinned by the manifest)
Building the artifact#
node tools/build-product-graph.mjs
Deterministic; CI's staleness gate (src/__tests__/artifact-gates.spec.ts)
fails when the artifact on disk differs from a fresh recompile. Commit any merge
FIRST, then regenerate, then commit the artifact.
Postgres projection (phase 6)#
Tables product_graph_node / product_graph_edge in oshun_dev (Prisma
migration 20260804140000_product_graph_projection). Loaded by transactional
full-replace per graph version — see
apps/oshun/bff/src/assistant/product-graph-pg.ts; boot sync behind
OSHUN_PRODUCT_GRAPH_PG_SYNC=1. The tested SQL pack lives in
apps/oshun/bff/src/assistant/product-graph-pg.integration.spec.ts and asserts
EXACT kernel-computed answers (descendants CTE, coverage rollup, TOTALITY
restated in SQL, repo-backlog-through-the-graph).
Neo4j projection (phase 7)#
Analysis surface only — never a serving dependency.
# 1. Bring up the graph profile (override the Kalika-sized memory defaults
# on RAM-constrained machines):
KALIKA_NEO4J_MEM_LIMIT=2500m KALIKA_NEO4J_HEAP_MAX=1G \
KALIKA_NEO4J_PAGECACHE=512m KALIKA_NEO4J_TX_MEMORY_MAX=512m \
docker compose -f docker/docker-compose.dev.yml --profile graph up -d
# 2. Build the kernel once (the loader reads the compiled dist):
pnpm --dir libs/oshun/product-graph build
# 3. Load (full replace, scoped to the :ProductGraph label):
node tools/load-product-graph-neo4j.mjs
Node label per kind (:Flow, :Journey, :Route, …) plus the common
:ProductGraph label; relationship type per edge kind (:CONTAINS,
:VERIFIES, :DOCUMENTS, :VISITS, :TRACKS, …); provenance + version as
properties on both. The unique ProductGraph.id constraint and per-kind id
indexes are created and asserted BEFORE any load.
The Cypher query pack (src/__tests__/neo4j-query-pack.integration.spec.ts) is
gated: it skips with a not_configured message when Neo4j is down and runs for
real under the graph profile — domain coverage rollup matching the TypeScript
analyzer exactly, shortest path feature→journey→route, the orphan scan, the
/tara route join, and a cross-source neighborhood traversal.
Connection env (see root .env.example): OSHUN_PRODUCT_GRAPH_NEO4J_URL /
_USER / _PASSWORD / _DB.
Two planes#
Knowledge (everything above) is compiled from the repo and read-only at runtime.
Intent (work items, decisions, threads, content briefs) is born in conversation,
lives in Postgres, and reaches this graph only as intent- provenance
projections — never the artifact. Promotion travels through code: an agent or
human lands a PR, the artifact recompiles, and the new nodes/edges appear.
Cross-plane queries (phase 15)#
node tools/load-product-graph-neo4j.mjs also syncs the intent plane when
Postgres is reachable (plane: 'intent' nodes: :WorkItem/:Decision/
:Thread with :TRACKS/:DECIDES/:SUPERSEDES/:DISCUSSES into the same
graph); --intent-only refreshes just that projection and REFUSES when the
knowledge plane is missing or at a stale artifact version. In Postgres the
work_item_graph_refs view (migration 20260804230000) unnests refs for joins
against product_graph_node/_edge.
The cross-plane pack lives in
apps/oshun/bff/src/workbench/cross-plane.integration.spec.ts: open work
touching /tara (containment closure + route prefix), accepted decisions on
UNVERIFIED curated flows, and the repo-backlog vs live-backlog reconciliation
(unchecked TODOS tasks none of whose refs any live work item touches) — answered
by the TypeScript kernel, SQL, and Cypher with EXACTLY matching sets, never just
matching counts.