@principal-ai/subsystems-react 0.42.0 → 0.43.0

package/src/stories/Subsystem/ComponentGraph/Appearance.stories.tsx

@@ -5,7 +5,7 @@ import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
 import type { GraphifyComponentDetail } from '../../../graphify';
-import { investigateOnlyComponents, investigateOnlyRelations, investigateOnlyWalkthroughs } from './fixtures';
+import { investigateOnlyComponents, investigateOnlyWalkthroughs } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Appearance',
@@ -32,7 +32,7 @@ export const NarrowMaxWidth: Story = {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={investigateOnlyComponents}
-        relations={investigateOnlyRelations} walkthroughs={investigateOnlyWalkthroughs}
+        walkthroughs={investigateOnlyWalkthroughs}
         maxNodeWidth={140}
       />
     </div>
@@ -101,7 +101,6 @@ export const NamingConventions: Story = {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={namingConventionComponents}
-        relations={[]}
         maxNodeWidth={180}
       />
     </div>
@@ -303,7 +302,6 @@ function KindVariationsDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={kindVariationComponents}
-        relations={[]}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>

package/src/stories/Subsystem/ComponentGraph/Basics.stories.tsx

@@ -4,7 +4,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
-import { components, graphSpecFromEdges } from './fixtures';
+import { components, graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Basics',
@@ -33,8 +33,8 @@ const twoNodeComponents = components([
   ['dst', 'SessionReader', 'class', 'SessionReader.ts', 'pkg:github/principal-ai/agent-monitoring', 'normalizes sessions into events'],
 ]);
 
-const twoNodeEdges = graphSpecFromEdges([
-  ['src', 'dst', 'method'],
+const twoNodeEdges = graphSpecFromHops([
+  ['src', 'dst', 'calls'],
 ]);
 
 function TwoNodeDemo({ showEdgeLabels = true }: { showEdgeLabels?: boolean }) {
@@ -44,7 +44,7 @@ function TwoNodeDemo({ showEdgeLabels = true }: { showEdgeLabels?: boolean }) {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={twoNodeComponents}
-        relations={twoNodeEdges.relations} walkthroughs={twoNodeEdges.walkthroughs}
+        walkthroughs={twoNodeEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
         showEdgeLabels={showEdgeLabels}
@@ -99,14 +99,14 @@ function PlaygroundDemo({ leftCount, rightCount, showEdgeLabels }: { leftCount:
 
   for (let i = 0; i < leftCount; i++) {
     for (let j = 0; j < rightCount; j++) {
-      edgeSpec.push([`l${i}`, `r${j}`, 'method']);
+      edgeSpec.push([`l${i}`, `r${j}`, 'calls']);
     }
   }
-  const graph = graphSpecFromEdges(edgeSpec);
+  const graph = graphSpecFromHops(edgeSpec);
 
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <SubsystemComponentGraph components={comps} relations={graph.relations} walkthroughs={graph.walkthroughs} showEdgeLabels={showEdgeLabels} />
+      <SubsystemComponentGraph components={comps} walkthroughs={graph.walkthroughs} showEdgeLabels={showEdgeLabels} />
     </div>
   );
 }
@@ -131,7 +131,7 @@ export const Playground: Story = {
 export const Empty: Story = {
   render: () => (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <SubsystemComponentGraph components={[]} relations={[]} />
+      <SubsystemComponentGraph components={[]} />
     </div>
   ),
 };

package/src/stories/Subsystem/ComponentGraph/Captures.stories.tsx

@@ -5,7 +5,7 @@ import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
 import type { GraphifyComponentDetail } from '../../../graphify';
-import { components, graphSpecFromEdges, readerDetail, investigateOnlyComponents, investigateOnlyRelations, investigateOnlyWalkthroughs } from './fixtures';
+import { components, graphSpecFromHops, readerDetail, investigateOnlyComponents, investigateOnlyWalkthroughs } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Captures',
@@ -37,15 +37,15 @@ const v2ReaderComponents = components([
   ['registry', 'supported-agents', 'function', 'supported-agents.ts', 'pkg:github/principal-ai/agent-monitoring', 'registry of supported agents (the shared seam)', 'registerAgent'],
 ]);
 
-const v2ReaderEdges = graphSpecFromEdges([
-  ['transcript', 'reader', 'method'],
-  ['paths', 'reader', 'method'],
+const v2ReaderEdges = graphSpecFromHops([
+  ['transcript', 'reader', 'calls'],
+  ['paths', 'reader', 'uses'],
   ['capture', 'reader', 'calls'],
-  ['reader', 'registry', 'registers-into', ['supported-agents.ts']],
+  ['reader', 'registry', 'registers-into'],
   // Consumer packages - cross-package edges leave the subgraph
-  ['reader', 'principal-studio-host', 'method'],
-  ['reader', 'core-sessions', 'method'],
-  ['reader', 'cli-session', 'method'],
+  ['reader', 'principal-studio-host', 'calls'],
+  ['reader', 'core-sessions', 'uses'],
+  ['reader', 'cli-session', 'uses'],
 ]);
 
 function V2ReaderDemo() {
@@ -55,7 +55,7 @@ function V2ReaderDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={v2ReaderComponents}
-        relations={v2ReaderEdges.relations} walkthroughs={v2ReaderEdges.walkthroughs}
+        walkthroughs={v2ReaderEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
       />
@@ -80,7 +80,7 @@ export const V2ReaderSubsystem: Story = {
 export const InvestigateOnly: Story = {
   render: () => (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <SubsystemComponentGraph components={investigateOnlyComponents} relations={investigateOnlyRelations} walkthroughs={investigateOnlyWalkthroughs} />
+      <SubsystemComponentGraph components={investigateOnlyComponents} walkthroughs={investigateOnlyWalkthroughs} />
     </div>
   ),
 };
@@ -98,10 +98,10 @@ const minimalComponents = components([
   ['transcript', 'transcript', 'function', 'transcript.ts', 'pkg:github/principal-ai/agent-monitoring', 'parses session records + type guards', 'transcript'],
 ]);
 
-const sharedEdges = graphSpecFromEdges([
-  ['transcript', 'record', 'method'],
-  ['reader', 'normalize', 'method'],
-  ['normalize', 'record', 'method'],
+const sharedEdges = graphSpecFromHops([
+  ['transcript', 'record', 'uses'],
+  ['reader', 'normalize', 'calls'],
+  ['normalize', 'record', 'uses'],
 ]);
 
 /** The same subsystem after `resolveSubsystemToGraphify` populates `detail`. */
@@ -137,7 +137,7 @@ function MinimalVsResolvedDemo({ resolved }: { resolved: boolean }) {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={resolved ? resolvedComponents : minimalComponents}
-        relations={sharedEdges.relations} walkthroughs={sharedEdges.walkthroughs}
+        walkthroughs={sharedEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -191,10 +191,10 @@ const investigationComponents: SubsystemComponent[] = [
   },
 ];
 
-const investigationEdges = graphSpecFromEdges([
-  ['adapter', 'contracts', 'method'],
+const investigationEdges = graphSpecFromHops([
+  ['adapter', 'contracts', 'uses'],
   ['ingestion', 'adapter', 'uses'],
-  ['ingestion', 'contracts', 'method'],
+  ['ingestion', 'contracts', 'uses'],
 ]);
 
 function InvestigationDemo() {
@@ -203,7 +203,7 @@ function InvestigationDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={investigationComponents}
-        relations={investigationEdges.relations} walkthroughs={investigationEdges.walkthroughs}
+        walkthroughs={investigationEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>

package/src/stories/Subsystem/ComponentGraph/Constructs.stories.tsx

@@ -260,7 +260,6 @@ function CatalogDemo({ hideSidebar = false }: { hideSidebar?: boolean }) {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={constructsOnly}
-        relations={[]}
         title="Constructs at a glance"
         description="Layer 1 — constructs only. Click a file path or L# to open the declaration source."
         hideSidebar={hideSidebar}

package/src/stories/Subsystem/ComponentGraph/CustomEntities.stories.tsx

@@ -5,7 +5,7 @@ import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
 import type { GraphifyCustomEntityDetail } from '../../../graphify';
-import { graphSpecFromEdges } from './fixtures';
+import { graphSpecFromHops } from './fixtures';
 
 /** Authored attributes surfaced in the declaration panel. */
 function entityDetail(attributes: Array<[string, string]>): GraphifyCustomEntityDetail {
@@ -143,7 +143,7 @@ const components: SubsystemComponent[] = [
   },
 ];
 
-const entityGraph = graphSpecFromEdges([
+const entityGraph = graphSpecFromHops([
   ['wr', 'store', 'feeds'],
   ['store', 'tech', 'feeds'],
   ['tech', 'sup', 'watches'],
@@ -178,7 +178,7 @@ export const NovaTechWorkRequests: Story = {
         title="Custom entities — NovaTech work-request chain"
         description="Persons, an agent, and a queue as `custom_entity` nodes (badge = entityKind). Actors keep the themed coral; the agent and queue wear authored `color` overrides. Click a node for its declaration — `entity 'Name' — kind` plus authored `attributes` (key: value)."
         components={components}
-        relations={entityGraph.relations} walkthroughs={entityGraph.walkthroughs}
+        walkthroughs={entityGraph.walkthroughs}
       />
     </div>
   ),

package/src/stories/Subsystem/ComponentGraph/DetailPanel.stories.tsx

@@ -207,7 +207,6 @@ function DetailKindsDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={detailKindComponents}
-        relations={[]}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -303,7 +302,6 @@ function DeclarationLineOpenDemo() {
         title="Declaration line open (Storybook)"
         description="Uses bundled ?raw fixtures + PierreSnippetView from this package. Select ComponentDeclaration, toggle file, click the path or L251."
         components={declarationOpenComponents}
-        relations={[]}
         renderFileViewer={renderFileViewer}
       />
     </div>

package/src/stories/Subsystem/ComponentGraph/Diagnostics.stories.tsx

@@ -7,7 +7,7 @@ import {
   SubsystemDiagnosticToggle,
   type SubsystemDiagnosticStatus,
 } from '../../../subsystem/DiagnosticToggle';
-import { components, graphSpecFromEdges } from './fixtures';
+import { components, graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Diagnostics',
@@ -34,7 +34,7 @@ const graphComponents = components([
   ['caller', 'Web client', 'external', '', 'external', undefined, undefined],
 ]);
 
-const graphEdges = graphSpecFromEdges([
+const graphEdges = graphSpecFromHops([
   ['caller', 'entry', 'calls'],
   ['entry', 'store', 'writes'],
   ['entry', 'stripe', 'calls'],
@@ -81,7 +81,6 @@ export const GraphClean: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        relations={graphEdges.relations}
         walkthroughs={graphEdges.walkthroughs}
         title="Checkout"
         description={GRAPH_DESCRIPTION}
@@ -96,7 +95,6 @@ export const GraphWithIssues: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        relations={graphEdges.relations}
         walkthroughs={graphEdges.walkthroughs}
         title="Checkout"
         description={GRAPH_DESCRIPTION}
@@ -112,7 +110,6 @@ export const GraphStale: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        relations={graphEdges.relations}
         walkthroughs={graphEdges.walkthroughs}
         title="Checkout"
         description={GRAPH_DESCRIPTION}
@@ -128,7 +125,6 @@ export const GraphChipOnly: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        relations={graphEdges.relations}
         walkthroughs={graphEdges.walkthroughs}
         title="Checkout"
         diagnostic={{ status: 'gaps', issueCount: 2, onToggle: () => {} }}

package/src/stories/Subsystem/ComponentGraph/EdgeViews.stories.tsx

@@ -3,8 +3,8 @@ import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import type { SubsystemEdgeView } from '../../../subsystem/model';
-import { components, relations, walkthroughFromHops } from './fixtures';
+import type { SubsystemEdgeView, SubsystemGraphifyRelation } from '../../../subsystem/model';
+import { components, walkthroughFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/EdgeViews',
@@ -26,11 +26,11 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 // ---------------------------------------------------------------------------
-// A graph that carries BOTH vocabularies between overlapping node pairs:
-//   svc --references--> reader (topology)
-//   svc --calls--> reader      (runtime hop)
-//   store --references--> db   (topology)
-//   store --calls--> db        (runtime hop)
+// A graph that carries BOTH edge sources between overlapping node pairs:
+//   svc --references--> reader  (graphify static edge)
+//   svc --calls--> reader       (runtime hop)
+//   store --references--> db    (graphify static edge)
+//   store --calls--> db         (runtime hop)
 // so switching the label view visibly changes which labels appear.
 // ---------------------------------------------------------------------------
 const labelViewComponents = components([
@@ -42,12 +42,12 @@ const labelViewComponents = components([
   ['db', 'PostgresStore', 'external', 'src/db/PostgresStore.ts', 'pkg:github/principal-ai/agent-monitoring', 'external persistence driver', 'PostgresStore'],
 ]);
 
-const labelViewRelations = relations([
-  ['svc', 'reader', 'method'],
-  ['svc', 'event', 'method'],
-  ['store', 'db', 'method'],
-  ['reader', 'event', 'method'],
-]);
+const labelViewGraphify: SubsystemGraphifyRelation[] = [
+  { id: 'g-svc-reader', from: 'svc', to: 'reader', relation: 'references' },
+  { id: 'g-svc-event', from: 'svc', to: 'event', relation: 'references' },
+  { id: 'g-store-db', from: 'store', to: 'db', relation: 'references' },
+  { id: 'g-reader-event', from: 'reader', to: 'event', relation: 'references' },
+];
 
 const labelViewWalkthroughs = [
   walkthroughFromHops('tl-capture', 'Capture session', [
@@ -63,12 +63,12 @@ const labelViewWalkthroughs = [
 ];
 
 const VIEWS: { value: SubsystemEdgeView; label: string }[] = [
-  { value: 'relations', label: 'Relations' },
+  { value: 'graphify', label: 'Graphify' },
   { value: 'walkthroughs', label: 'Walkthroughs' },
 ];
 
 function EdgeViewDemo() {
-  const [view, setView] = useState<SubsystemEdgeView>('relations');
+  const [view, setView] = useState<SubsystemEdgeView>('graphify');
   const [showEdgeLabels, setShowEdgeLabels] = useState(true);
 
   return (
@@ -118,10 +118,10 @@ function EdgeViewDemo() {
       <div style={{ flex: 1, minHeight: 0 }}>
         <SubsystemComponentGraph
           components={labelViewComponents}
-          relations={labelViewRelations}
+          graphifyRelations={labelViewGraphify}
           walkthroughs={labelViewWalkthroughs}
           title="edge views"
-          description="The relation and walkthrough vocabularies are disjoint and never shown together. Toggle the view: **Relations** draws `svc --references--> reader`; **Walkthroughs** draws `svc --calls--> reader`. The model is the same either way."
+          description="The graphify and walkthrough edge sources are disjoint and never shown together. Toggle the view: **Graphify** draws `svc --references--> reader`; **Walkthroughs** draws `svc --calls--> reader`. The model is the same either way."
           showEdgeLabels={showEdgeLabels}
           edgeView={view}
         />
@@ -130,7 +130,7 @@ function EdgeViewDemo() {
   );
 }
 
-/** Interactive toggle between the `relations` and `walkthroughs` edge views. */
+/** Interactive toggle between the `graphify` and `walkthroughs` edge views. */
 export const ToggleEdgeView: Story = {
   render: () => <EdgeViewDemo />,
 };
@@ -141,7 +141,7 @@ export const ViewControl: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={labelViewComponents}
-        relations={labelViewRelations}
+        graphifyRelations={labelViewGraphify}
         walkthroughs={labelViewWalkthroughs}
         showEdgeLabels={args.showEdgeLabels}
         edgeView={args.edgeView}
@@ -150,10 +150,10 @@ export const ViewControl: Story = {
   ),
   args: {
     showEdgeLabels: true,
-    edgeView: 'relations',
+    edgeView: 'graphify',
   },
   argTypes: {
     showEdgeLabels: { control: 'boolean' },
-    edgeView: { control: 'inline-radio', options: ['relations', 'walkthroughs'] },
+    edgeView: { control: 'inline-radio', options: ['graphify', 'walkthroughs'] },
   },
 };

package/src/stories/Subsystem/ComponentGraph/Flows.stories.tsx

@@ -192,7 +192,6 @@ function FlowsDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={drawingComponents}
-        relations={[]}
         walkthroughs={drawingWalkthroughs}
         title="drawing-files flow"
         description="Three walkthroughs over one graph — opening, saving, and deleting a drawing. The sidebar's **Walkthroughs** panel lists each step by **symbol**; clicking a step focuses that hop and scrolls the bottom CodeView to that snippet."
@@ -301,7 +300,6 @@ function ProposedMissingStepDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={proposedComponents}
-        relations={[]}
         walkthroughs={proposedWalkthroughs}
         title="proposed seam with a missing file"
         description="Expand **Associate a finished run with its model** and click either step. The proposed hop has no file in the checkout, so its snippet shows an inline *Proposed — … isn't in the local checkout yet.* placeholder instead of failing the whole flow."
@@ -518,7 +516,6 @@ function ClickableConstructsDemo() {
       <div style={{ flex: 1, minHeight: 0 }}>
         <SubsystemComponentGraph
           components={clickableComponents}
-          relations={[]}
           walkthroughs={clickableWalkthroughs}
           initialWalkthroughId="tl-load"
           title="clickable constructs"

package/src/stories/Subsystem/ComponentGraph/FrameworkStereotype.stories.tsx

@@ -2,7 +2,8 @@ import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import type { SubsystemComponent, SubsystemComponentEdge } from '../../../subsystem/model';
+import type { SubsystemComponent } from '../../../subsystem/model';
+import { walkthroughFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/FrameworkStereotype',
@@ -78,6 +79,19 @@ const reactUiComponents: SubsystemComponent[] = [
     process: 'principal-studio/renderer',
     layer: 2,
   },
+  {
+    alias: 'analysis-view',
+    name: 'AnalysisView',
+    construct: 'function',
+    file: 'packages/subsystems-studio/src/mainview/views/AnalysisView.tsx',
+    purl,
+    symbol: 'AnalysisView',
+    purpose: 'React component that consumes the graph document type',
+    framework: 'react',
+    stereotype: 'component',
+    process: 'principal-studio/renderer',
+    layer: 2,
+  },
   {
     alias: 'drawings-host',
     name: 'useDrawingsHost',
@@ -103,31 +117,13 @@ const reactUiComponents: SubsystemComponent[] = [
   },
 ];
 
-const reactUiEdges: SubsystemComponentEdge[] = [
-  {
-    id: 'http-to-create',
-    from: 'http-entry',
-    to: 'create-graph',
-    mechanism: 'calls',
-  },
-  {
-    id: 'sessions-uses-hook',
-    from: 'sessions-view',
-    to: 'drawings-host',
-    mechanism: 'uses',
-  },
-  {
-    id: 'analysis-uses-type',
-    from: 'analysis-view',
-    to: 'graph-doc-type',
-    mechanism: 'references',
-  },
-  {
-    id: 'sessions-to-analysis',
-    from: 'sessions-view',
-    to: 'analysis-view',
-    mechanism: 'feeds',
-  },
+const reactUiWalkthroughs = [
+  walkthroughFromHops('react-ui-hops', 'React UI hops', [
+    ['http-entry', 'create-graph', 'calls', 'packages/subsystems-studio/src/bun/http-server.ts', 1],
+    ['sessions-view', 'drawings-host', 'uses', 'packages/subsystems-studio/src/mainview/views/AgentSessions.tsx', 1],
+    ['analysis-view', 'graph-doc-type', 'uses', 'packages/subsystems-studio/src/mainview/views/AnalysisView.tsx', 1],
+    ['sessions-view', 'analysis-view', 'feeds', 'packages/subsystems-studio/src/mainview/views/AgentSessions.tsx', 2],
+  ]),
 ];
 
 export const ReactComponentsAndHooks: Story = {
@@ -137,7 +133,7 @@ export const ReactComponentsAndHooks: Story = {
         title="Framework + stereotype"
         description="construct stays language-shaped (function / type_alias). framework + stereotype label React units as component / hook without inventing a react_component construct. Empty fields mean language-only."
         components={reactUiComponents}
-        relations={reactUiEdges.relations} walkthroughs={reactUiEdges.walkthroughs}
+        walkthroughs={reactUiWalkthroughs}
       />
     </div>
   ),
@@ -196,10 +192,12 @@ const nestComponents: SubsystemComponent[] = [
   },
 ];
 
-const nestEdges: SubsystemComponentEdge[] = [
-  { id: 'mw-to-guard', from: 'logging-mw', to: 'auth-guard', mechanism: 'uses' },
-  { id: 'guard-to-ctrl', from: 'auth-guard', to: 'graphs-controller', mechanism: 'uses' },
-  { id: 'ctrl-to-svc', from: 'graphs-controller', to: 'graphs-service', mechanism: 'calls' },
+const nestWalkthroughs = [
+  walkthroughFromHops('nest-stack-hops', 'Nest controller stack hops', [
+    ['logging-mw', 'auth-guard', 'uses', 'src/logging/logging.middleware.ts', 1],
+    ['auth-guard', 'graphs-controller', 'uses', 'src/auth/auth.guard.ts', 1],
+    ['graphs-controller', 'graphs-service', 'calls', 'src/graphs/graphs.controller.ts', 1],
+  ]),
 ];
 
 export const NestControllerStack: Story = {
@@ -209,7 +207,7 @@ export const NestControllerStack: Story = {
         title="Nest framework stereotypes"
         description="Same optional fields work outside React: class/function constructs plus nestjs controller / guard / middleware / injectable stereotypes."
         components={nestComponents}
-        relations={nestEdges.relations} walkthroughs={nestEdges.walkthroughs}
+        walkthroughs={nestWalkthroughs}
       />
     </div>
   ),

package/src/stories/Subsystem/ComponentGraph/GraphTitle.stories.tsx

@@ -3,7 +3,7 @@ import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import { components, graphSpecFromEdges, relations } from './fixtures';
+import { components, graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/GraphTitle',
@@ -30,7 +30,7 @@ const graphOnlyComponents = components([
   ['caller', 'Web client', 'external', '', 'external', undefined, undefined],
 ]);
 
-const graphOnlyEdges = graphSpecFromEdges([
+const graphOnlyEdges = graphSpecFromHops([
   ['caller', 'entry', 'calls'],
   ['entry', 'store', 'writes'],
   ['entry', 'stripe', 'calls'],
@@ -41,7 +41,7 @@ function GraphOnly() {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphOnlyComponents}
-        relations={graphOnlyEdges.relations} walkthroughs={graphOnlyEdges.walkthroughs}
+        walkthroughs={graphOnlyEdges.walkthroughs}
         graphTitle="Checkout"
         hideSidebar
       />
@@ -60,7 +60,7 @@ export const WithSidebar: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphOnlyComponents}
-        relations={graphOnlyEdges.relations} walkthroughs={graphOnlyEdges.walkthroughs}
+        walkthroughs={graphOnlyEdges.walkthroughs}
         title="Checkout"
         description="A small e-commerce checkout subsystem: an HTTP entry point that writes to retained cart state and calls out to Stripe."
         graphTitle="Checkout"

package/src/stories/Subsystem/ComponentGraph/IssueOverlay.stories.tsx

@@ -21,7 +21,7 @@ import {
  * renderer picker → host RPC → background runner → maintain orchestrator →
  * opencode V2 session, plus the liveness-probe handshake. Its components and
  * three walkthroughs are reproduced verbatim below; the topology is carried by
- * the walkthroughs (`relations: []`), exactly as stored.
+ * the walkthroughs, exactly as stored.
  *
  * What this story exercises: the graph's diagnostics surface over the real
  * model — the title-row status chip, the grouped issue list, the per-node
@@ -482,30 +482,6 @@ const MAINTAIN_ISSUES: SubsystemIssue[] = [
     message: 'Graphify anchored the node but left the construct unclassified (store vs interface).',
     target: { kind: 'component', id: 'live-feed-store', label: 'OpencodeLiveFeedState store' },
   },
-  {
-    id: 'mr-endpoint',
-    severity: 'error',
-    kind: 'topology_broken_endpoint',
-    message: 'Relationship endpoint "maintain-background-runner" does not resolve to a component.',
-    target: {
-      kind: 'relation',
-      id: 'maintain-rpc-handler→maintain-background-runner',
-      label: 'maintainSubsystemModel RPC → maintainSubsystemModelInBackground',
-      detail: 'calls',
-    },
-  },
-  {
-    id: 'mr-hang',
-    severity: 'error',
-    kind: 'topology_broken_endpoint',
-    message: 'Run reaches the 15-minute deadline without an endpoint on the finish event.',
-    target: {
-      kind: 'relation',
-      id: 'session-runner→opencode-v2-server',
-      label: 'runOpencodeV2AgentSession → OpenCode V2 service',
-      detail: 'calls',
-    },
-  },
   {
     id: 'mr-boundary',
     severity: 'info',
@@ -580,7 +556,6 @@ function MaintainRunGraph({
       <div style={{ flex: 1, minHeight: 0 }}>
         <SubsystemComponentGraph
           components={MAINTAIN_COMPONENTS}
-          relations={[]}
           walkthroughs={MAINTAIN_WALKTHROUGHS}
           title="Maintain run"
           description="Fire-and-forget RPC, wait for the finish event — picker → RPC → background runner → orchestrator → opencode V2 session, plus the liveness-probe handshake."