feat(node-ui): M2 option (b) — silent cross-subgraph switch on link follow

Enable the cross-subgraph auto-switch alongside S5. When following a
link to an entity that lives in a DIFFERENT sub-graph than the one in
scope, handleNavigate switches activeSubGraph to the target's sub-graph
via setActiveSubGraphSync (PR #793 Bug N) so the breadcrumb's React tree
sees it synchronously. The breadcrumb now makes the move visible
(Context Graph › <new subgraph> › Entity), which is what made option (b)
acceptable (the plan tied (b) to the breadcrumb existing).

Ground-truth note: there was no option-(a) "suppression branch" to
reverse — the prior handleNavigate did NO subgraph switching at all
(option (a) was the ABSENCE of a switch). So this ADDS the follow logic.

- primarySubGraphOf(entity): first non-meta subgraph slug (mirrors the
  SubGraphBadge rule); the follow decision input.
- entitiesRef mirrors rawMemory.entities so handleNavigate resolves the
  target's subgraph synchronously without churning its (deliberately
  stable) callback identity.
- The follow fires ONLY when already on a sub-graph page — opening an
  entity from a plain layer list does NOT spuriously jump into a
  sub-graph just because the entity belongs to one.
- The M2 origin snapshot is still captured at first open, so closing
  returns to the ORIGINATING page, not the followed-into one (the
  origin-restore overwrites any mid-open switch).

Tests: T14 (cross-subgraph follow switches activeSubGraph + breadcrumb
reflects + close returns to origin), T15 (plain-layer open does not jump
into a subgraph; M2 origin model intact), T16 (handleDetailClose serves
both detail kinds — covered by the entity + assertion close tests),
primarySubGraphOf unit truth table.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Jurij Skornik

packages/node-ui/src/ui/views/ProjectView.tsx

@@ -11,6 +11,7 @@ import {
   useMemoryEntities,
   type LayeredTriple,
   type TrustLevel,
+  type MemoryEntity,
 } from '../hooks/useMemoryEntities.js';
 import { useProjectProfile, ProjectProfileContext } from '../hooks/useProjectProfile.js';
 import { useAgents, AgentsContext } from '../hooks/useAgents.js';
@@ -21,7 +22,7 @@ import { ActivityFeed } from '../components/ActivityFeed.js';
 import { SubGraphBar } from '../components/SubGraphBar.js';
 import { CONTEXT_GRAPH_PRIMER_TAB } from '../lib/contextGraphPrimer.js';
 import { useTabsStore } from '../stores/tabs.js';
-import { shouldFetchSwmAttribution, type LayerView, type LayerContentTab, type SubGraphTab } from './project/helpers.js';
+import { shouldFetchSwmAttribution, primarySubGraphOf, type LayerView, type LayerContentTab, type SubGraphTab } from './project/helpers.js';
 import {
   ProjectHeaderStrip,
   LayerSwitcher,
@@ -224,6 +225,11 @@ export function ProjectView({ contextGraphId }: ProjectViewProps) {
   // open without listing the state in its deps.
   const selectedAssertionRef = useRef<AssertionInfo | null>(null);
   useEffect(() => { selectedAssertionRef.current = selectedAssertion; }, [selectedAssertion]);
+  // M2 option (b) — mirror the full entity map so `handleNavigate` can
+  // resolve a navigated entity's primary sub-graph synchronously
+  // (to decide whether to follow a cross-subgraph link) WITHOUT listing
+  // the map in its deps and churning the callback identity.
+  const entitiesRef = useRef<ReadonlyMap<string, MemoryEntity>>(new Map());
   const [layerContentTabs, setLayerContentTabs] = useState<Record<MemoryLayerView, LayerContentTab>>(
     DEFAULT_LAYER_TABS,
   );
@@ -391,6 +397,9 @@ export function ProjectView({ contextGraphId }: ProjectViewProps) {
   // DashboardView caller, which already opts in for the same
   // failed-vs-empty-distinct reason.
   const rawMemory = useMemoryEntities(contextGraphId, { signalErrors: true });
+  // M2 option (b) — keep the entity-map ref in sync so `handleNavigate`
+  // can resolve a navigated entity's sub-graph synchronously.
+  useEffect(() => { entitiesRef.current = rawMemory.entities; }, [rawMemory.entities]);
   // SWM attribution drives the SWM graph's agent-tint legend (its
   // sole remaining consumer). PR #694 review — the Overview no
   // longer reads this stream (lifecycle source replaced it), so the
@@ -658,22 +667,43 @@ export function ProjectView({ contextGraphId }: ProjectViewProps) {
     setSubGraphTabs(prev => prev[slug] === tab ? prev : { ...prev, [slug]: tab });
   }, []);
 
-  // M2 keeps the user's origin stable: linked entities open in the detail
-  // pane, but the underlying layer/sub-graph page does not silently change
-  // until S5 adds breadcrumbs that can make that movement visible.
-  //
   // Intent: a brand-new top-level open (no selected entity yet) resets
   // the layer context; in-detail navigation (a click inside an open
   // detail) keeps the prior layer context. We read both `selectedUri`
   // (via ref) and the prior `selectedLayerContext` (via the setter
   // `prev` argument) so the callback identity stays stable — listing
   // them in deps would re-create `handleNavigate` on every navigation
   // and rebuild every downstream memo / callback that consumes it.
+  //
+  // M2 option (b) — silent cross-subgraph switch, ENABLED alongside S5.
+  // When following a link to an entity that lives in a DIFFERENT
+  // sub-graph than the one currently in scope, switch `activeSubGraph`
+  // to the target's sub-graph. Pre-S5 this was suppressed (option (a):
+  // no switch) because the move was invisible; now the breadcrumb makes
+  // it visible (`Context Graph › <new subgraph> › Entity`), so the
+  // switch is acceptable. Routed through `setActiveSubGraphSync` (PR
+  // #793 Bug N) so the breadcrumb's React tree — and the ref-keyed
+  // discriminators — see the new subgraph synchronously. The M2 origin
+  // snapshot was captured at the FIRST open, so closing still returns to
+  // the originating page, not the followed-into one.
+  //
+  // Only fires when ALREADY in a sub-graph page (`activeSubGraphRef`):
+  // opening an entity from a plain layer list must NOT spuriously jump
+  // into a sub-graph just because the entity happens to belong to one.
   const handleNavigate = useCallback((uri: string, originScrollKey?: string, layerContext?: MemoryLayerView) => {
     const hadSelection = selectedUriRef.current != null;
     openEntityDetail(uri, originScrollKey);
     setSelectedLayerContext(prev => layerContext ?? (hadSelection ? prev : null));
-  }, [openEntityDetail]);
+    const currentSubGraph = activeSubGraphRef.current;
+    if (currentSubGraph) {
+      const targetSubGraph = primarySubGraphOf(
+        entitiesRef.current.get(uri) ?? entitiesRef.current.get(canonicalEntityUri(uri)),
+      );
+      if (targetSubGraph && targetSubGraph !== currentSubGraph) {
+        setActiveSubGraphSync(targetSubGraph);
+      }
+    }
+  }, [openEntityDetail, setActiveSubGraphSync]);
 
   const handleDetailClose = useCallback(() => {
     const origin = detailOriginRef.current;

packages/node-ui/src/ui/views/project/helpers.ts

@@ -1006,6 +1006,21 @@ export function buildAssertionTrail(
   }));
 }
 
+/**
+ * The primary (first non-`meta`) sub-graph slug an entity has triples
+ * in, or null when it lives only in the root bucket / meta. Mirrors the
+ * `SubGraphBadge` rule (lowest-rank binding wins; most entities live in
+ * exactly one sub-graph). Used by M2 option (b) to decide whether a
+ * cross-subgraph entity jump should switch `activeSubGraph`.
+ */
+export function primarySubGraphOf(entity: MemoryEntity | undefined | null): string | null {
+  if (!entity) return null;
+  for (const s of entity.subGraphs) {
+    if (s !== 'meta') return s;
+  }
+  return null;
+}
+
 // ─── S5 Breadcrumb navigation ───────────────────────────────
 // `Context Graph › {Layer | Subgraph} › {Entity | Assertion}`. Lives
 // inline in the persistent ProjectHeaderStrip. Hop content rules

packages/node-ui/test/assertion-detail-helpers.test.ts

@@ -5,7 +5,17 @@ import {
   assertionSubgraphLine,
   buildAssertionTrail,
   buildBreadcrumbHops,
+  primarySubGraphOf,
 } from '../src/ui/views/project/helpers.js';
+import type { MemoryEntity } from '../src/ui/hooks/useMemoryEntities.js';
+
+function entity(subGraphs: string[]): MemoryEntity {
+  return {
+    uri: 'urn:e', label: 'E', types: [], trustLevel: 'working',
+    layers: new Set(['working']), subGraphs: new Set(subGraphs),
+    properties: new Map(), connections: [],
+  };
+}
 
 // S4 — pure helpers behind the assertion detail view. These pin the
 // lifecycle-trail tone mapping (T01), the Promote CTA visibility
@@ -174,3 +184,20 @@ describe('buildBreadcrumbHops — cross-subgraph update (T05)', () => {
     expect(after[2].label).toBe('Entity B');
   });
 });
+
+describe('primarySubGraphOf — M2(b) cross-subgraph follow decision (T14)', () => {
+  it('returns the first non-meta subgraph slug', () => {
+    expect(primarySubGraphOf(entity(['demo']))).toBe('demo');
+    expect(primarySubGraphOf(entity(['meta', 'research']))).toBe('research');
+  });
+
+  it('returns null for a root-only / meta-only entity', () => {
+    expect(primarySubGraphOf(entity([]))).toBeNull();
+    expect(primarySubGraphOf(entity(['meta']))).toBeNull();
+  });
+
+  it('returns null for a missing entity', () => {
+    expect(primarySubGraphOf(undefined)).toBeNull();
+    expect(primarySubGraphOf(null)).toBeNull();
+  });
+});

packages/node-ui/test/project-view-navigation.test.ts

@@ -684,28 +684,59 @@ describe('ProjectView entity detail navigation', () => {
     expect(query('overview-card').dataset.participantsStatus).toBe('loading');
   });
 
-  it('keeps the originating subgraph stable while following cross-subgraph entity links', async () => {
+  // M2 option (b) — ENABLED alongside S5. Following a link to an entity
+  // in a DIFFERENT sub-graph switches activeSubGraph (the breadcrumb
+  // makes the move visible); closing still returns to the ORIGINATING
+  // sub-graph page (the M2 origin captured at first open). (T14 / T15)
+  it('follows a cross-subgraph entity link → activeSubGraph switches; close returns to origin', async () => {
     await click('switch-subgraphs');
     await click('select-subgraph-demo');
     await click('subgraph-tab-graph');
     expect(query('active-subgraph').textContent).toBe('demo');
     expect(query('subgraph-detail').dataset.tab).toBe('graph');
 
+    // Open an entity that lives in the CURRENT subgraph — no switch.
     await click('open-subgraph-entity');
     expect(query('entity-detail').dataset.entity).toBe('urn:entity:demo');
     expect(query('active-subgraph').textContent).toBe('demo');
 
+    // Follow a link to urn:entity:other (subGraphs: {'other'}) — M2(b)
+    // switches activeSubGraph to 'other'; the breadcrumb reflects it via
+    // the active-subgraph mirror.
     await click('open-related-entity');
     expect(query('entity-detail').dataset.entity).toBe('urn:entity:other');
-    expect(query('active-subgraph').textContent).toBe('demo');
+    expect(query('active-subgraph').textContent).toBe('other');
+    // The breadcrumb's trailing hop tracks the followed entity.
+    expect(query('project-strip').dataset.detailLabel).toBe('Other entity');
 
+    // Close — origin restore returns to the ORIGINATING subgraph (demo),
+    // not the followed-into one (other). (T15 — origin model intact.)
     await click('detail-back');
     await flush();
-
     expect(query('subgraph-detail').dataset.slug).toBe('demo');
     expect(query('subgraph-detail').dataset.tab).toBe('graph');
   });
 
+  // T15 — the M2 ORIGINAL behavior (no cross-subgraph involved) is
+  // untouched: open from a layer list → close → same layer / subtab /
+  // scroll, and opening from a plain layer does NOT spuriously jump into
+  // a subgraph just because the entity belongs to one.
+  it('opening an entity from a plain layer list does NOT switch into a subgraph (M2(b) guard)', async () => {
+    await click('switch-wm');
+    // urn:entity:overlap has subGraphs {'demo'} but we open it from the
+    // WM layer list (no active subgraph) — must stay layer-scoped.
+    await click('open-layer-overlap-entity');
+    await flush();
+    expect(query('entity-detail').dataset.entity).toBe('urn:entity:overlap');
+    // No subgraph page was entered.
+    expect(query('active-subgraph').textContent).toBe('none');
+
+    await click('detail-back');
+    await flush();
+    expect(query('layer-detail').dataset.layer).toBe('wm');
+    expect(document.querySelector('[data-testid="subgraph-detail"]')).toBeNull();
+  });
+
   it('clears stale detail origin when the selected entity disappears', async () => {
     await click('switch-swm');
     await click('open-layer-overlap-entity');