{132.39} Concept-graph decision memo — native/extend vs fork-UA

{132.39} G-CONCEPT-GRAPH-UI — Decision-Gate Memo

Spike: Subtask {132.39} of Task id-132 (OKF concept producer). READ-ONLY. Date: 2026-07-17 Gate: adopt/fork-UA (add OKF format detector to the UA fork + embed its force-graph in /okf) vs native /okf build (extend the Next.js app; UA reference only). Recommendation: NATIVE / extend — decisively.

---

1. The finding that reframes the gate

The gate brief frames this as “native /okf build” vs adopt UA. That framing is stale. The native concept graph is already shipped and tested under {132.14} G-VIEWER (status done, verified live). It is not a build; it is an extend.

What already exists in canonical:

Asset	Path	State
Deterministic OKF parser	lib/okf/okf-document.ts (frontmatter/body split)	shipped
Concept-graph builder (TS port of reference generator.py)	lib/okf/bundle-graph.ts — frontmatter→node, citation-trailer .md links→edges, type/tags/size	shipped
Cytoscape force-graph component	components/okf/concept-graph.tsx — search, type-filter, 5 layouts (cose/concentric/breadthfirst/circle/grid), selection, reset	shipped + __tests__/components/okf/concept-graph.test.tsx
Three-region viewer	components/okf/bundle-viewer.tsx (nav rail + graph + detail/history tabs), backlinks	shipped
API route	app/api/okf/[bundleId]/graph/route.ts (authed, server-side build)	shipped
Per-type semantic-token colouring	lib/okf/concept-type-tokens.ts + --okf-concept-* / --okf-graph-* in app/styles/domain-tokens.css	shipped
Landing + bundle list	components/okf/okf-landing.tsx, bundle-list.tsx, lib/okf/enumerate-bundles.ts ({132.32})	shipped
Query wiring	lib/query/okf.ts, hooks/okf/use-bundle.ts (useBundleGraph)	shipped
cytoscape ^3.28.1 dependency	package.json	present

So a “concept-network visualization surfaced in the /okf explorer” — the {132.39} goal — is already live for the single-bundle case, natively, themed with Warm Meridian tokens, behind auth, with tests. The UA pilot explored an alternative viewer to something the app already has.

2. What the UA pilot actually proves (and disproves)

The pilot ran /understand-knowledge over the synthetic Platform bundle (git 54d3bb7d) → .ua/knowledge-graph.json: 64 nodes / 205 edges. Node-type breakdown:

article: 19   entity: 16   claim: 15   source: 8   topic: 6

Only the 19 article nodes correspond to actual OKF concept files. The other 45 nodes (entities like “Priya Anand”, claims, source nodes, topic clusters) and the bulk of the 205 edges are LLM-extracted by UA’s Karpathy analyzer — implicit relationships, entity extraction, topic clustering. That extra density is precisely the non-citation-grade content the ratified doctrine rejects UA as a producer for. The “deterministic OKF repair shim” the pilot needed (frontmatter→node, directory→taxonomy, citation-trailer→related/cites, canonical://→source) was an attempt to coerce UA’s parser back toward OKF semantics — and even after it, UA still emitted 16 entity + 15 claim nodes off-spec.

The native bundle-graph.ts already does the faithful thing the shim was chasing — and more faithfully (no LLM noise). Its LINK_RE already turns the concept’s # Citations trailer (bundle-path .md links such as products/greencycle-furniture-programme.md) into edges; canonical:// pointers are correctly excluded as opaque non-concept anchors. The graph is a pure, deterministic projection of the bundle’s own asserted structure.

Consequence for the gate’s “cost the parser under BOTH paths” instruction: the premise that the OKF-native parser is a common cost is false. Under native it is already built and faithful (sunk). Under fork-UA it must be re-implemented in a foreign codebase while suppressing UA’s producer behaviour — a net liability, not a shared cost.

3. Doctrine deltas (what native genuinely still lacks)

Ratified bundle-doctrine (2026-07-16) requires more than the shipped single-bundle viewer. The gaps are the same under both paths except where noted:

1. Multi-bundle UNION. buildBundleGraph + the graph route assume one resolved bundleId. Doctrine requires a deployment-level union of sibling bundles under OKF_BUNDLE_ROOT (client business + canonical-okf-system baseline). enumerate-bundles.ts already lists sibling roots, so the enumeration primitive is half-there; the builder must accept N roots, namespace node ids by bundle, and carry a per-node bundleClass.
2. Per-class styling. Node border/shape (or hue family) by bundle class + a legend.
3. A19 confidence → node opacity. confidence is a producer-emitted categorical field {strong, partial, no-content, needs-SME} (bl-477, validated in producer/validator.py). Zero app-side rendering today. Cheap: the opaque parser already surfaces it; map 4 values → opacity tiers + legend.
4. bl-457 @context / IRI projection. Concept-type→IRI colouring and relationship-typed edges (cites vs related vs categorized_under). The citation trailer already yields edges; typing them means splitting the trailer by pointer form (canonical:// = source/cites, bundle-path = related). The opaque parseOkfDocument already captures any @context frontmatter/sidecar for free. (Note: the pilot bundle at 54d3bb7d carries no context.jsonld/@context on disk yet — both paths must tolerate the field arriving later; native’s opaque capture does so for free.)

None of these is unique to the fork path. Multi-bundle union is net-new under UA too — the pilot analyzed a single repo.

4. Cost (rough person-session units)

Work item	Native / extend	Fork-UA / adopt
OKF-faithful parser	0 — shipped & faithful (bundle-graph.ts)	2.5–3 — re-implement in fork + suppress Karpathy LLM pipeline (shim proved this is a coercion battle)
Force-graph + search/filter/layout/select	0 — shipped (concept-graph.tsx)	0 — UA has one (foreign graph lib + shape)
Multi-bundle union + namespacing	1–1.5	1.5 (in UA’s {nodes,edges,layers,tour} shape)
Per-class styling + legend	0.5	0.5–1
A19 confidence → opacity + legend	0.5	1 (foreign shape + renderer)
bl-457 IRI / relationship-typed edges	1–1.5	1.5
Surface as deployment-union view in /okf landing	0.5	2–3 — embed (iframe standalone Vite build or extract React graph comp + re-wire)
Re-skin to Warm Meridian tokens	0 — native already tokenised	1 — UA ships a hardcoded palette (the Reframe-A problem {132.14} already solved once)
Subtotal (delta)	~3.5–4.5	~10–13
Ongoing maintenance	in-house, one stack (Next/bun/Vitest)	permanent fork-drift tax; foreign Astro/Vite/plugin toolchain
Risk	LOW (extend shipped, tested code)	MED-HIGH (foreign toolchain, coercion battle, theming re-do, discards {132.14})

5. Recommendation

Adopt the NATIVE path. Extend the shipped {132.14} concept graph to the multi-bundle union with per-class styling, A19 confidence opacity, and IRI/relationship-typed edges. Keep UA as a reference only. The fork-UA path re-implements a parser the app already owns (while fighting UA’s doctrine-rejected LLM producer behaviour), re-does the Warm Meridian theming {132.14} already solved, imposes a permanent fork-maintenance tax, and its one genuine differentiator — the denser 64-node graph — is denser because it surfaces the non-citation-grade entity/claim nodes the doctrine forbids. For a citation-grade product that density is a liability, not a feature.

One idea worth cherry-picking from UA later (native, not a fork): the guided tour / walkthrough affordance (UA’s tour array). It is genuinely additive and cheap to build natively on top of the existing graph; propose as a separate backlog item, not part of this gate.

6. Proposed follow-on subtask (winning path)

New implementation Subtask under id-132, sibling to {132.39}:

{132.N} G-CONCEPT-GRAPH-UNION — Extend lib/okf/bundle-graph.ts + app/api/okf/.../graph from single-bundle to a deployment-level multi-bundle union: accept N sibling roots via enumerate-bundles.ts, namespace node ids by bundleId, carry per-node bundleClass (client vs canonical-okf-system baseline) with per-class styling + legend; widen node data with A19 confidence → opacity tiers; split the citation trailer into relationship-typed edges (cites/source vs related) and project bl-457 @context type IRIs into node colouring; surface a “whole-deployment” union graph view in the /okf landing ({132.32}) alongside the existing per-bundle viewer. Reuse the shipped <ConceptGraph> / <BundleViewer> — no new graph library. Tests: union namespacing, confidence-opacity mapping, edge-typing, empty/one-bundle fallbacks. Est. ~3.5–4.5 sessions, risk LOW.

Author {132.N}‘s TECH slice against the ratified bundle-doctrine + the {132.14} G-VIEWER surface. This gate does not auto-adopt — owner ratification required.