Eve library

@oshun/product-graph

Other

Revision 1

On this page

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 split
  • src/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 + composeVersion
  • src/queries.ts — cross-representation lenses (whatTouchesRoute)
  • src/compilers/ — one pure compiler per source
  • src/curation/ — the reviewed alias/waiver tables (code, PR-gated)
  • src/compose.ts + src/artifact.ts — composer and artifact reader/writer
  • src/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#

bash
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.

bash
# 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.