@principal-ai/subsystems-react 0.42.0 → 0.43.1

package/src/stories/Subsystem/ComponentGraph/Issues.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 { SubsystemIssueList, type SubsystemIssue } from '../../../subsystem/IssueList';
-import { components, graphSpecFromEdges } from './fixtures';
+import { components, graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Issues',
@@ -47,13 +47,6 @@ const ISSUES: SubsystemIssue[] = [
     message: 'Named parameter types are not present in the graphify cache.',
     target: { kind: 'component', id: 'entry', label: 'checkoutApi' },
   },
-  {
-    id: 'i4',
-    severity: 'error',
-    kind: 'topology_broken_endpoint',
-    message: 'Relationship endpoint "store" does not resolve to a component.',
-    target: { kind: 'relation', id: 'r1', label: 'checkoutApi → cartStore', detail: 'writes' },
-  },
   {
     id: 'i5',
     severity: 'info',
@@ -132,21 +125,7 @@ const ISSUES: SubsystemIssue[] = [
     message: 'Graphify cache missing for pkg:github/you/your-app — build it to verify constructs and anchors',
     target: { kind: 'repo', id: 'pkg:github/you/your-app', label: 'pkg:github/you/your-app' },
   },
-  {
-    id: 'i14',
-    severity: 'info',
-    kind: 'topology_import_unconfirmed',
-    message: 'No import edge from checkoutApi to cartStore found in Graphify.',
-    target: { kind: 'relation', id: 'r1', label: 'checkoutApi → cartStore', detail: 'references' },
-  },
-  {
-    id: 'i15',
-    severity: 'info',
-    kind: 'topology_relation_unconfirmed',
-    message: 'Graphify found no inheritance evidence for FileSessionStore → SessionStore.',
-    target: { kind: 'relation', id: 'r2', label: 'FileSessionStore → SessionStore', detail: 'extends' },
-  },
-];
+  ];
 
 const graphComponents = components([
   ['entry', 'checkoutApi', 'function', 'src/checkout/api.ts', 'pkg:github/you/your-app', 'Handles cart requests.', 'checkoutApi'],
@@ -154,7 +133,7 @@ const graphComponents = components([
   ['stripe', 'Stripe', 'external', '', 'external', undefined, undefined],
 ]);
 
-const graphEdges = graphSpecFromEdges([
+const graphEdges = graphSpecFromHops([
   ['entry', 'store', 'writes'],
   ['entry', 'stripe', 'calls'],
 ]);
@@ -187,7 +166,6 @@ export const GraphWithIssues: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphComponents}
-        relations={graphEdges.relations}
         walkthroughs={graphEdges.walkthroughs}
         title="Checkout"
         description="A small e-commerce checkout subsystem."

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

@@ -9,7 +9,7 @@ import type {
   SubsystemGraphNode,
   SubsystemProcessRegion,
 } from '../../../subsystem/model';
-import { graphSpecFromEdges } from './fixtures';
+import { graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/ModuleBadges',
@@ -102,12 +102,12 @@ const deepComponents: SubsystemComponent[] = [
   },
 ];
 
-const deepEdges = graphSpecFromEdges([
-  ['node-comp', 'group-comp', 'method'],
-  ['edge-comp', 'group-comp', 'method'],
-  ['model-view', 'layers', 'method'],
-  ['use-drawings', 'model-view', 'method'],
-  ['model-view', 'node-comp', 'method'],
+const deepEdges = graphSpecFromHops([
+  ['node-comp', 'group-comp', 'calls'],
+  ['edge-comp', 'group-comp', 'calls'],
+  ['model-view', 'layers', 'calls'],
+  ['use-drawings', 'model-view', 'calls'],
+  ['model-view', 'node-comp', 'calls'],
 ]);
 
 /** Collapsed module badges show `first/…/last`. Click one to expand the full
@@ -122,7 +122,6 @@ export const DeepModulePaths: Story = {
           'click the badge to expand the full path (the badge widens past the frame edge — the frame itself stays put), click again to collapse it back.'
         }
         components={deepComponents}
-        relations={deepEdges.relations}
         walkthroughs={deepEdges.walkthroughs}
       />
     </div>

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

@@ -0,0 +1,116 @@
+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 } from '../../../subsystem/model';
+
+/**
+ * Prototype for path-based module nesting: `module` is the file path, and
+ * `moduleNesting="path"` derives directory frames from the path segments and
+ * nests the module frames inside them.
+ *
+ * Compare `FilesFlat` (one module frame per file, the current "column") with
+ * `FilesByPath` (directory frames interposed) and `FolderModules` (the same
+ * model read with folders as modules instead of files).
+ */
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Module path nesting',
+  component: SubsystemComponentGraph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div style={{ width: '100%', height: '100vh' }}>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+  argTypes: {
+    moduleNesting: { control: 'inline-radio', options: ['exact', 'path'] },
+  },
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const PURL = 'pkg:github/you/scheduling-app';
+
+function fileModules(): SubsystemComponent[] {
+  return [
+    { alias: 'booking-page', name: 'BookingPage', construct: 'function', symbol: 'BookingPage', purl: PURL, file: 'app/book/page.tsx', module: 'app/book/page.tsx' },
+    { alias: 'list-open-slots', name: 'listOpenSlots', construct: 'function', symbol: 'listOpenSlots', purl: PURL, file: 'app/book/actions.ts', module: 'app/book/actions.ts' },
+    { alias: 'book-slot', name: 'bookSlot', construct: 'function', symbol: 'bookSlot', purl: PURL, file: 'app/book/actions.ts', module: 'app/book/actions.ts' },
+    { alias: 'cancel-slot', name: 'cancelSlot', construct: 'function', symbol: 'cancelSlot', purl: PURL, file: 'app/book/actions.ts', module: 'app/book/actions.ts' },
+    { alias: 'list-slots', name: 'listSlots', construct: 'function', symbol: 'listSlots', purl: PURL, file: 'lib/listSlots.ts', module: 'lib/listSlots.ts' },
+    { alias: 'create-booking', name: 'createBooking', construct: 'function', symbol: 'createBooking', purl: PURL, file: 'lib/createBooking.ts', module: 'lib/createBooking.ts' },
+    { alias: 'cancel-booking', name: 'cancelBooking', construct: 'function', symbol: 'cancelBooking', purl: PURL, file: 'lib/cancelBooking.ts', module: 'lib/cancelBooking.ts' },
+    { alias: 'capture-event', name: 'captureEvent', construct: 'function', symbol: 'captureEvent', purl: PURL, file: 'lib/captureEvent.ts', module: 'lib/captureEvent.ts' },
+  ];
+}
+
+/** Current behavior: one frame per file path — the "column". */
+export const FilesFlat: Story = {
+  args: {
+    title: 'File modules (exact)',
+    description: 'module = file path, moduleNesting="exact". One frame per file.',
+    components: fileModules(),
+    moduleNesting: 'exact',
+  },
+};
+
+/** Path-nested: directory frames wrap the file frames. */
+export const FilesByPath: Story = {
+  args: {
+    title: 'File modules (path nesting)',
+    description:
+      'module = file path, moduleNesting="path". `app/book` and `lib` directory frames wrap their file frames.',
+    components: fileModules(),
+    moduleNesting: 'path',
+  },
+};
+
+/** Deeper hierarchy: src → host/renderer/bun → file frames. */
+const deepComponents: SubsystemComponent[] = [
+  { alias: 'boot', name: 'boot', construct: 'function', symbol: 'boot', purl: 'pkg:github/p/app', file: 'src/host/main.ts', module: 'src/host/main.ts' },
+  { alias: 'create-host', name: 'createHost', construct: 'function', symbol: 'createHost', purl: 'pkg:github/p/app', file: 'src/host/main.ts', module: 'src/host/main.ts' },
+  { alias: 'session-store', name: 'SessionStore', construct: 'store', symbol: 'SessionStore', purl: 'pkg:github/p/app', file: 'src/host/store.ts', module: 'src/host/store.ts' },
+  { alias: 'bridge', name: 'bridge', construct: 'function', symbol: 'bridge', purl: 'pkg:github/p/app', file: 'src/renderer/bridge.ts', module: 'src/renderer/bridge.ts' },
+  { alias: 'trail-view', name: 'TrailView', construct: 'function', symbol: 'TrailView', framework: 'react', stereotype: 'component', purl: 'pkg:github/p/app', file: 'src/renderer/view.tsx', module: 'src/renderer/view.tsx' },
+  { alias: 'audit-store', name: 'auditStore', construct: 'store', symbol: 'auditStore', purl: 'pkg:github/p/app', file: 'src/bun/audit.ts', module: 'src/bun/audit.ts' },
+  { alias: 'audit-run', name: 'runAudit', construct: 'function', symbol: 'runAudit', purl: 'pkg:github/p/app', file: 'src/bun/audit.ts', module: 'src/bun/audit.ts' },
+  { alias: 'registry', name: 'registry', construct: 'store', symbol: 'registry', purl: 'pkg:github/p/app', file: 'src/bun/registry.ts', module: 'src/bun/registry.ts' },
+];
+
+export const DeepNesting: Story = {
+  args: {
+    title: 'Deep path nesting',
+    description:
+      'src → host / renderer / bun → file frames. Directories nest recursively by path segment.',
+    components: deepComponents,
+    moduleNesting: 'path',
+  },
+};
+
+/** Same shape, but `module` is the folder (no per-file frames). */
+const folderComponents: SubsystemComponent[] = [
+  { alias: 'booking-page', name: 'BookingPage', construct: 'function', symbol: 'BookingPage', purl: PURL, file: 'app/book/page.tsx', module: 'app/book' },
+  { alias: 'list-open-slots', name: 'listOpenSlots', construct: 'function', symbol: 'listOpenSlots', purl: PURL, file: 'app/book/actions.ts', module: 'app/book' },
+  { alias: 'book-slot', name: 'bookSlot', construct: 'function', symbol: 'bookSlot', purl: PURL, file: 'app/book/actions.ts', module: 'app/book' },
+  { alias: 'cancel-slot', name: 'cancelSlot', construct: 'function', symbol: 'cancelSlot', purl: PURL, file: 'app/book/actions.ts', module: 'app/book' },
+  { alias: 'list-slots', name: 'listSlots', construct: 'function', symbol: 'listSlots', purl: PURL, file: 'lib/listSlots.ts', module: 'lib' },
+  { alias: 'create-booking', name: 'createBooking', construct: 'function', symbol: 'createBooking', purl: PURL, file: 'lib/createBooking.ts', module: 'lib' },
+  { alias: 'cancel-booking', name: 'cancelBooking', construct: 'function', symbol: 'cancelBooking', purl: PURL, file: 'lib/cancelBooking.ts', module: 'lib' },
+  { alias: 'capture-event', name: 'captureEvent', construct: 'function', symbol: 'captureEvent', purl: PURL, file: 'lib/captureEvent.ts', module: 'lib' },
+];
+
+export const FolderModules: Story = {
+  args: {
+    title: 'Folder modules',
+    description:
+      'module = folder. Two folder frames hold the exports directly — no per-file frames.',
+    components: folderComponents,
+  },
+};

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

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent } from '../../../subsystem/model';
-import { graphSpecFromEdges } from './fixtures';
+import { graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Modules',
@@ -120,10 +120,10 @@ const moduleComponents: SubsystemComponent[] = [
   },
 ];
 
-const moduleEdges = graphSpecFromEdges([
-  ['parse', 'record', 'method'],
-  ['is-rollout', 'record', 'method'],
-  ['reader', 'normalize', 'method'],
+const moduleEdges = graphSpecFromHops([
+  ['parse', 'record', 'uses'],
+  ['is-rollout', 'record', 'uses'],
+  ['reader', 'normalize', 'calls'],
   ['normalize', 'parse', 'calls'],
   ['normalize', 'tool-name', 'calls'],
   ['normalize', 'file-path', 'calls'],
@@ -137,7 +137,6 @@ export const ModuleBoundaries: Story = {
         title="Module boundaries"
         description="Concrete exports keep their real construct. Shared `module` (the source path) draws the file as a dashed frame — not `construct: module`. Singleton modules (registerAgent) stay unframed."
         components={moduleComponents}
-        relations={moduleEdges.relations}
         walkthroughs={moduleEdges.walkthroughs}
       />
     </div>
@@ -260,10 +259,10 @@ const nestedComponents: SubsystemComponent[] = [
   },
 ];
 
-const nestedEdges = graphSpecFromEdges([
-  ['boot', 'write-session', 'method'],
-  ['trail-view', 'bridge', 'method'],
-  ['trail-view', 'use-trail', 'method'],
+const nestedEdges = graphSpecFromHops([
+  ['boot', 'write-session', 'calls'],
+  ['trail-view', 'bridge', 'calls'],
+  ['trail-view', 'use-trail', 'uses'],
   ['boot', 'create-host', 'calls'],
   ['create-host', 'write-session', 'calls'],
   ['write-session', 'session-store', 'writes'],
@@ -279,7 +278,6 @@ export const ProcessAndModuleNesting: Story = {
         title="Process × module nesting"
         description="process frames wrap module frames wrap exports. Leaves parent to module:; module groups parent to process: when every member shares that process."
         components={nestedComponents}
-        relations={nestedEdges.relations}
         walkthroughs={nestedEdges.walkthroughs}
       />
     </div>

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

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent } from '../../../subsystem/model';
-import { graphSpecFromEdges } from './fixtures';
+import { graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Packages',
@@ -80,7 +80,7 @@ const multiRepoComponents: SubsystemComponent[] = [
   },
 ];
 
-const multiRepoEdges = graphSpecFromEdges([
+const multiRepoEdges = graphSpecFromHops([
   ['dispatch', 'session', 'calls'],
   ['dispatch', 'parse', 'calls'],
   ['parse', 'normalize', 'calls'],
@@ -90,7 +90,6 @@ export const MultiRepoPackageFrames: Story = {
   name: 'Multi-repo package frames',
   args: {
     components: multiRepoComponents,
-    relations: multiRepoEdges.relations,
     walkthroughs: multiRepoEdges.walkthroughs,
   },
   render: (args) => (
@@ -107,7 +106,6 @@ export const SingleRepoNoPackageFrames: Story = {
   name: 'Single-repo (no package frames)',
   args: {
     components: singleRepo,
-    relations: multiRepoEdges.relations,
     walkthroughs: multiRepoEdges.walkthroughs,
   },
   render: (args) => (
@@ -220,7 +218,7 @@ const nestedComponents: SubsystemComponent[] = [
   },
 ];
 
-const nestedEdges = graphSpecFromEdges([
+const nestedEdges = graphSpecFromHops([
   ['boot', 'dispatch', 'calls'],
   ['dispatch', 'session', 'calls'],
   ['dispatch', 'parse', 'calls'],
@@ -231,7 +229,6 @@ export const PackageProcessModuleNesting: Story = {
   name: 'Package → process → module nesting',
   args: {
     components: nestedComponents,
-    relations: nestedEdges.relations,
     walkthroughs: nestedEdges.walkthroughs,
   },
   render: (args) => (

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

@@ -2,7 +2,7 @@ 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 { components, graphSpecFromEdges, relations } from './fixtures';
+import { components, graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Processes',
@@ -54,7 +54,7 @@ const processComponents = [
   },
 ];
 
-const processEdges = graphSpecFromEdges([
+const processEdges = graphSpecFromHops([
   ['main', 'store', 'writes'],
   ['main', 'bridge', 'calls'],
   ['bridge', 'view', 'feeds'],
@@ -69,7 +69,7 @@ export const ProcessBoundaries: Story = {
         title="Process boundaries"
         description="Host and renderer each render in their own ELK-aware boundary frame. The worker process holds a single node and still gets a frame (singleton frames default on). The telemetry service has no `process` and sits outside every boundary."
         components={processComponents}
-        relations={processEdges.relations} walkthroughs={processEdges.walkthroughs}
+        walkthroughs={processEdges.walkthroughs}
       />
     </div>
   ),

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

@@ -7,9 +7,9 @@ import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGr
 import { SubsystemComponentNode } from '../../../subsystem/nodes';
 import type {
   SubsystemComponent,
-  SubsystemComponentEdge,
   SubsystemGraphNode,
 } from '../../../subsystem/model';
+import { walkthroughFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Proposed',
@@ -225,10 +225,12 @@ const migrationComponents: SubsystemComponent[] = [
   },
 ];
 
-const migrationEdges: SubsystemComponentEdge[] = [
-  { id: 'e0', from: 'audit', to: 'maintain', mechanism: 'calls' },
-  { id: 'e1', from: 'maintain', to: 'lifecycle', mechanism: 'uses' },
-  { id: 'e2', from: 'lifecycle', to: 'cli', mechanism: 'calls' },
+const migrationWalkthroughs = [
+  walkthroughFromHops('migration-hops', 'Migration hops', [
+    ['audit', 'maintain', 'calls', 'src/bun/verify-subsystem-component.ts', 1],
+    ['maintain', 'lifecycle', 'uses', 'src/bun/maintain-model.ts', 1],
+    ['lifecycle', 'cli', 'calls', 'src/bun/opencode-v2.ts', 1],
+  ]),
 ];
 
 function MigrationDemo() {
@@ -237,7 +239,7 @@ function MigrationDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={migrationComponents}
-        relations={migrationEdges.relations} walkthroughs={migrationEdges.walkthroughs}
+        walkthroughs={migrationWalkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, padding: '0 12px', fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>

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

@@ -151,7 +151,6 @@ function ProposedWalkthroughsDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={components}
-        relations={[]}
         walkthroughs={walkthroughs}
         title="proposed-work marker"
         description="Walkthroughs that touch a **proposed** component get their title tinted darkgoldenrod in the flows panel; expand a row and each hop onto a proposed component is tinted too (index and title). Nodes for proposed components already draw dashed darkgoldenrod on the canvas."

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

@@ -137,7 +137,6 @@ function ReorderGraphDemo() {
       <div style={{ flex: 1, minHeight: 0 }}>
         <SubsystemComponentGraph
           components={components}
-          relations={[]}
           walkthroughs={walkthroughs}
           onReorderWalkthroughs={onReorder}
           title="drawing-files flows"

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

@@ -9,7 +9,7 @@ import type {
   SubsystemModelDocument,
 } from '../../../subsystem/model';
 import type { GraphifyComponentDetail } from '../../../graphify';
-import { components, graphSpecFromEdges, relations } from './fixtures';
+import { components, graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Scenarios',
@@ -92,11 +92,11 @@ const mermaidComponents: SubsystemComponent[] = [
   },
 ];
 
-const mermaidEdges = graphSpecFromEdges([
+const mermaidEdges = graphSpecFromHops([
   ['input', 'slide', 'feeds'],
   ['slide', 'chunk', 'produces'],
   ['chunk', 'lazy', 'feeds'],
-  ['lazy', 'diagram', 'wraps'],
+  ['lazy', 'diagram', 'uses'],
   ['diagram', 'helpers', 'uses'],
 ]);
 
@@ -106,7 +106,7 @@ function MermaidDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={mermaidComponents}
-        relations={mermaidEdges.relations} walkthroughs={mermaidEdges.walkthroughs}
+        walkthroughs={mermaidEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -137,10 +137,10 @@ const multiRepoComponents = components([
   ['rewire', 'extract.py', 'function', 'graphify/extract.py', graphifyPurl, 'corpus pass folding unique-label stubs onto definitions', '_rewire_unique_stub_nodes'],
 ]);
 
-const multiRepoEdges = graphSpecFromEdges([
-  ['detail', 'reftypes', 'method'],
-  ['resolver', 'reftypes', 'method'],
-  ['resolver', 'engine', 'method'],
+const multiRepoEdges = graphSpecFromHops([
+  ['detail', 'reftypes', 'uses'],
+  ['resolver', 'reftypes', 'uses'],
+  ['resolver', 'engine', 'calls'],
   ['rewire', 'resolver', 'calls'],
 ]);
 
@@ -151,7 +151,7 @@ function MultiRepoDemo() {
         title="Type-ref resolution across repos"
         description="Two repos → two file trees. Each tree is scoped to its repo's files and headed by the owner avatar + repo name. Cross-repo edges land on external stubs."
         components={multiRepoComponents}
-        relations={multiRepoEdges.relations} walkthroughs={multiRepoEdges.walkthroughs}
+        walkthroughs={multiRepoEdges.walkthroughs}
       />
     </div>
   );
@@ -354,7 +354,7 @@ const accessSurfaceComponents: SubsystemComponent[] = [
   },
 ];
 
-const accessSurfaceEdges = graphSpecFromEdges([
+const accessSurfaceEdges = graphSpecFromHops([
   ['agents', 'http-entry', 'calls'],
   ['http-entry', 'create', 'calls'],
   ['http-entry', 'update', 'calls'],
@@ -384,7 +384,7 @@ function AccessSurfacesDemo() {
         title="Access surfaces, roles, and process boundaries"
         description="Two process regions (host, renderer) + boundary entries; agents and the external service float outside every boundary. Hover for the role badge; click the store to drill into its state-only detail."
         components={accessSurfaceComponents}
-        relations={accessSurfaceEdges.relations} walkthroughs={accessSurfaceEdges.walkthroughs}
+        walkthroughs={accessSurfaceEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
         onEdgeSelect={(e) => setSelectedEdge(e)}
       />
@@ -534,7 +534,7 @@ const storeFlavorComponents: SubsystemComponent[] = [
   },
 ];
 
-const storeFlavorEdges = graphSpecFromEdges([
+const storeFlavorEdges = graphSpecFromHops([
   ['f1-create', 'f1-store', 'writes'],
   ['f1-get', 'f1-store', 'reads'],
   ['f2-cache', 'f2-store', 'writes'],
@@ -549,7 +549,7 @@ function StoreFlavorsDemo() {
         title="Store flavors"
         description="construct:= the node's verifiable anchor. Class-managed stores are TWO nodes: the manager class (declaration, methods) + the state (store block). Click any node to see its anchor-honest drill-down."
         components={storeFlavorComponents}
-        relations={storeFlavorEdges.relations} walkthroughs={storeFlavorEdges.walkthroughs}
+        walkthroughs={storeFlavorEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -637,7 +637,7 @@ const sharedStoreComponents: SubsystemComponent[] = [
   },
 ];
 
-const sharedStoreEdges = graphSpecFromEdges([
+const sharedStoreEdges = graphSpecFromHops([
   ['ss-load', 'ss-store', 'reads'],
   ['ss-save', 'ss-store', 'writes'],
   ['ss-watch', 'ss-store', 'watches'],
@@ -652,7 +652,7 @@ function SharedStoreDemo() {
         title="Shared store across processes"
         description="A store with no process sits outside every boundary; accessors from both processes reach across to it."
         components={sharedStoreComponents}
-        relations={sharedStoreEdges.relations} walkthroughs={sharedStoreEdges.walkthroughs}
+        walkthroughs={sharedStoreEdges.walkthroughs}
         onEdgeSelect={(e) => setSelectedEdge(e)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -919,7 +919,7 @@ const storeSpectrumComponents: SubsystemComponent[] = [
   },
 ];
 
-const storeSpectrumEdges = graphSpecFromEdges([
+const storeSpectrumEdges = graphSpecFromHops([
   ['load', 'db', 'reads'],
   ['create', 'graph-store', 'writes'],
   ['cache', 'cache-state', 'writes'],
@@ -938,7 +938,7 @@ function StoreStateSpectrumDemo() {
         title="State → Store spectrum, all modeled as store"
         description="Every holder here claims construct: 'store' (state-block anatomy). They differ only in what they hold and how long it lives. Which ones do you call a store? Where is the cut?"
         components={storeSpectrumComponents}
-        relations={storeSpectrumEdges.relations} walkthroughs={storeSpectrumEdges.walkthroughs}
+        walkthroughs={storeSpectrumEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -1114,12 +1114,12 @@ const typeSpectrumComponents: SubsystemComponent[] = [
   },
 ];
 
-const typeSpectrumEdges = graphSpecFromEdges([
+const typeSpectrumEdges = graphSpecFromHops([
   ['listener', 'subscriber', 'uses'],
-  ['subscriber', 'messages', 'method'],
+  ['subscriber', 'messages', 'uses'],
   ['state', 'listener', 'feeds'],
-  ['deep', 'record', 'method'],
-  ['rows', 'record', 'method'],
+  ['deep', 'record', 'uses'],
+  ['rows', 'record', 'uses'],
 ]);
 
 function TypeFamilySpectrumDemo() {
@@ -1130,7 +1130,7 @@ function TypeFamilySpectrumDemo() {
         title="Type-family — what a type can hold"
         description="Structured buckets: callable signature (generics + params), interface properties, enum members, union, plain alias reference. `rhs` = verbatim escape hatch for shapes that don't fit (mapped/conditional/template-literal). Click each to see the declaration."
         components={typeSpectrumComponents}
-        relations={typeSpectrumEdges.relations} walkthroughs={typeSpectrumEdges.walkthroughs}
+        walkthroughs={typeSpectrumEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -1209,7 +1209,7 @@ const queueComponents: SubsystemComponent[] = [
   },
 ];
 
-const queueEdges = graphSpecFromEdges([
+const queueEdges = graphSpecFromHops([
   ['q-producer', 'q-queue', 'writes'],
   ['q-worker', 'q-queue', 'reads'],
   ['q-worker', 'q-results', 'writes'],
@@ -1223,7 +1223,7 @@ function QueueAsStoreDemo() {
         title="Queue as store"
         description="Ordered retained state. Stores as pipeline stages: producer writes the queue, the worker reads it and writes results."
         components={queueComponents}
-        relations={queueEdges.relations} walkthroughs={queueEdges.walkthroughs}
+        walkthroughs={queueEdges.walkthroughs}
         onEdgeSelect={(e) => setSelectedEdge(e)}
       />
       <div style={{ marginTop: 8, fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>
@@ -1343,7 +1343,6 @@ const dataVizDoc: SubsystemModelDocument = {
       },
     },
   ],
-  relations: [],
   walkthroughs: [
     {
       id: 'data-viz-hops',
@@ -1369,8 +1368,8 @@ function DataVsVisualizationDemo() {
     setText(next);
     try {
       const parsed = JSON.parse(next) as SubsystemModelDocument;
-      if (!Array.isArray(parsed.components) || !Array.isArray(parsed.relations)) {
-        throw new Error('document needs `components` and `relations` arrays');
+      if (!Array.isArray(parsed.components)) {
+        throw new Error('document needs a `components` array');
       }
       setDoc(parsed);
       setError(null);
@@ -1431,7 +1430,6 @@ function DataVsVisualizationDemo() {
           title="the visualization"
           description="Same document, rendered: construct:→ node anatomy, role → topology glyph, process → boundary region, mechanism → edge color/style."
           components={doc.components}
-          relations={doc.relations}
           walkthroughs={doc.walkthroughs}
         />
       </div>

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

@@ -197,7 +197,6 @@ export const AutoplayFocus: Story = {
       <SubsystemComponentGraph
         {...args}
         components={components}
-        relations={[]}
         walkthroughs={walkthroughs}
         hideSidebar
         hideDrawer

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

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
 import type { SubsystemComponent } from '../../../subsystem/model';
-import { graphSpecFromEdges } from './fixtures';
+import { graphSpecFromHops } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/WorkspacePackages',
@@ -114,7 +114,7 @@ const components: SubsystemComponent[] = [
   },
 ];
 
-const spec = graphSpecFromEdges([
+const spec = graphSpecFromHops([
   ['read-file', 'get-model', 'calls'],
   ['model-view', 'component-graph', 'uses'],
   ['component-graph', 'file-drawer', 'calls'],
@@ -125,7 +125,6 @@ export const PackageOwnedProcess: Story = {
   name: 'Package-owned process · library outside',
   args: {
     components,
-    relations: spec.relations,
     walkthroughs: spec.walkthroughs,
     graphTitle: 'Opening a file — app package owns the process',
   },