@principal-ai/subsystems-react 0.53.6 → 0.55.0

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

@@ -72,9 +72,9 @@ const ISSUES: SubsystemIssue[] = [
   },
   {
     id: 'i20',
-    severity: 'info',
-    kind: 'step_unconfirmed',
-    message: 'Trail "Story steps" step 1: call site not verified (entry → store via writes)',
+    severity: 'error',
+    kind: 'step_span_unconfirmed',
+    message: 'Trail "Story steps" step 1: step span not captured (entry → store via writes)',
     target: {
       kind: 'step',
       id: 'story-steps',
@@ -86,8 +86,8 @@ const ISSUES: SubsystemIssue[] = [
   {
     id: 'i21',
     severity: 'info',
-    kind: 'step_stale',
-    message: 'Trail "Story steps" step 2: call site changed since verification (lines 42-44 in src/checkout/api.ts)',
+    kind: 'step_span_stale',
+    message: 'Trail "Story steps" step 2: step span changed since verification (lines 42-44 in src/checkout/api.ts)',
     target: {
       kind: 'step',
       id: 'story-steps',
@@ -120,8 +120,8 @@ const ISSUES: SubsystemIssue[] = [
   },
   {
     id: 'i9',
-    severity: 'error',
-    kind: 'stale_declaration',
+    severity: 'info',
+    kind: 'construct_span_stale',
     message: 'Declaration moved since capture — recorded start line 42, now 57.',
     target: { kind: 'component', id: 'session-store', label: 'SessionStore' },
     fix: { label: 'Re-pin declaration' },
@@ -133,6 +133,13 @@ const ISSUES: SubsystemIssue[] = [
     message: 'Graphify anchored the node but left the construct unclassified (interface vs type alias).',
     target: { kind: 'component', id: 'host-info', label: 'HostInfo' },
   },
+  {
+    id: 'i22',
+    severity: 'error',
+    kind: 'construct_span_unconfirmed',
+    message: 'HostInfo has no captured source span — its declaration extent is unpinned until an agent proposes start/end lines.',
+    target: { kind: 'component', id: 'host-info', label: 'HostInfo' },
+  },
   {
     id: 'i11',
     severity: 'error',
@@ -216,7 +223,7 @@ const TRAIL_STEP_ISSUES: SubsystemIssue[] = [
   {
     id: 'ts1',
     severity: 'info',
-    kind: 'step_unconfirmed',
+    kind: 'step_span_unconfirmed',
     message: 'Trail "Add to Cart" step 1: call site not verified (addToCart → cartStore via writes)',
     target: {
       kind: 'step',
@@ -229,7 +236,7 @@ const TRAIL_STEP_ISSUES: SubsystemIssue[] = [
   {
     id: 'ts2',
     severity: 'info',
-    kind: 'step_unconfirmed',
+    kind: 'step_span_unconfirmed',
     message: 'Trail "Add to Cart" step 2: call site not verified (cartStore → inventoryService via calls)',
     target: {
       kind: 'step',
@@ -242,7 +249,7 @@ const TRAIL_STEP_ISSUES: SubsystemIssue[] = [
   {
     id: 'ts3',
     severity: 'info',
-    kind: 'step_stale',
+    kind: 'step_span_stale',
     message: 'Trail "Checkout" step 1: call site changed since verification (lines 42-44 in src/checkout/api.ts)',
     target: {
       kind: 'step',
@@ -255,7 +262,7 @@ const TRAIL_STEP_ISSUES: SubsystemIssue[] = [
   {
     id: 'ts4',
     severity: 'info',
-    kind: 'step_stale',
+    kind: 'step_span_stale',
     message: 'Trail "Checkout" step 3: call site changed since verification (lines 78-82 in src/checkout/api.ts)',
     target: {
       kind: 'step',
@@ -302,7 +309,7 @@ const stepVerificationIssues: SubsystemIssue[] = [
   {
     id: 'sv1',
     severity: 'info',
-    kind: 'step_unconfirmed',
+    kind: 'step_span_unconfirmed',
     message: 'Trail "Checkout" step 1: call site not verified (checkoutApi → cartStore via writes)',
     target: {
       kind: 'step',
@@ -315,7 +322,7 @@ const stepVerificationIssues: SubsystemIssue[] = [
   {
     id: 'sv2',
     severity: 'info',
-    kind: 'step_stale',
+    kind: 'step_span_stale',
     message: 'Trail "Checkout" step 2: call site changed since verification (lines 42-44 in src/checkout/api.ts)',
     target: {
       kind: 'step',
@@ -646,7 +653,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'maintain-rpc-handler',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/mainview/components/MaintainModelPickerModal.tsx',
-        line: 116,
+        span: { startLine: 116, endLine: 116, contentHash: 'fixture' },
         symbol: 'MaintainModelPickerModal',
         purl: `${PURL}#packages/subsystems-studio/src/mainview/components/MaintainModelPickerModal.tsx`,
         annotation: 'Fire the maintainSubsystemModel RPC with the selected model.',
@@ -656,7 +663,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'maintain-background-runner',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/index.ts',
-        line: 2522,
+        span: { startLine: 2522, endLine: 2522, contentHash: 'fixture' },
         symbol: 'maintainSubsystemModelInBackground',
         purl: `${PURL}#packages/subsystems-studio/src/bun/index.ts`,
         annotation: 'RPC returns started:true immediately and hands off to the guarded runner.',
@@ -666,7 +673,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'maintain-orchestrator',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/index.ts',
-        line: 3160,
+        span: { startLine: 3160, endLine: 3160, contentHash: 'fixture' },
         symbol: 'maintainSubsystemModelInBackground',
         purl: `${PURL}#packages/subsystems-studio/src/bun/index.ts`,
         annotation: 'Run the full install → audit → route-by-verdict → brief pipeline.',
@@ -676,7 +683,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'maintain-agent-launcher',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/maintain-model.ts',
-        line: 854,
+        span: { startLine: 854, endLine: 854, contentHash: 'fixture' },
         symbol: 'runMaintainAgent',
         purl: `${PURL}#packages/subsystems-studio/src/bun/maintain-model.ts`,
         annotation: 'Resolve the model then launch the agent run, retrying once on the credentialed fallback if unusable.',
@@ -686,7 +693,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'session-runner',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/maintain-model.ts',
-        line: 742,
+        span: { startLine: 742, endLine: 742, contentHash: 'fixture' },
         symbol: 'runOpencodeV2AgentSession',
         purl: `${PURL}#packages/subsystems-studio/src/bun/maintain-model.ts`,
         annotation: 'Hand the brief, agent, and directory to the V2 session runner.',
@@ -696,7 +703,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'events-tab',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/index.ts',
-        line: 3164,
+        span: { startLine: 3164, endLine: 3164, contentHash: 'fixture' },
         symbol: 'maintainSubsystemModelInBackground',
         purl: `${PURL}#packages/subsystems-studio/src/bun/index.ts`,
         annotation: 'Open the live feed tab the instant the session id exists.',
@@ -712,7 +719,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'sse-feed-reader',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 355,
+        span: { startLine: 355, endLine: 355, contentHash: 'fixture' },
         symbol: 'runOpencodeV2AgentSession',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: 'Open the /api/event subscription before creating the session.',
@@ -722,7 +729,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'opencode-v2-server',
         mechanism: 'watches',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 222,
+        span: { startLine: 222, endLine: 222, contentHash: 'fixture' },
         symbol: 'readSse',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: "Stream the single SSE feed that carries every session's events.",
@@ -732,7 +739,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'service-ensurer',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 326,
+        span: { startLine: 326, endLine: 326, contentHash: 'fixture' },
         symbol: 'runOpencodeV2AgentSession',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: 'Ensure the opencode2 daemon is healthy, starting the service if it is not.',
@@ -742,7 +749,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'opencode-v2-server',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 384,
+        span: { startLine: 384, endLine: 384, contentHash: 'fixture' },
         symbol: 'runOpencodeV2AgentSession',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: 'POST /api/session creates the session with a 15s HTTP timeout.',
@@ -752,7 +759,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'opencode-v2-server',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 428,
+        span: { startLine: 428, endLine: 428, contentHash: 'fixture' },
         symbol: 'runOpencodeV2AgentSession',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: 'POST /api/session/{id}/prompt feeds the maintain brief with a 15s HTTP timeout.',
@@ -762,7 +769,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'terminal-matcher',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 365,
+        span: { startLine: 365, endLine: 365, contentHash: 'fixture' },
         symbol: 'readSse',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: 'Flag sawTerminal when the event is an execution finish or session idle.',
@@ -772,7 +779,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'session-runner',
         mechanism: 'feeds',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 469,
+        span: { startLine: 469, endLine: 469, contentHash: 'fixture' },
         symbol: 'runOpencodeV2AgentSession',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: 'Wait loop polls every 400ms until sawTerminal or the 15-minute deadline.',
@@ -782,7 +789,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'maintain-probe-registry',
         mechanism: 'reads',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 484,
+        span: { startLine: 484, endLine: 484, contentHash: 'fixture' },
         symbol: 'runOpencodeV2AgentSession',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: "Confirm the model's first tool call landed the liveness probe; abort as unusable on timeout.",
@@ -792,7 +799,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'live-feed-store',
         mechanism: 'writes',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 529,
+        span: { startLine: 529, endLine: 529, contentHash: 'fixture' },
         symbol: 'runOpencodeV2AgentSession',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: 'Stamp the feed done (or error) when the wait loop exits.',
@@ -802,7 +809,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'maintain-picker',
         mechanism: 'feeds',
         file: 'packages/subsystems-studio/src/bun/index.ts',
-        line: 3187,
+        span: { startLine: 3187, endLine: 3187, contentHash: 'fixture' },
         symbol: 'maintainSubsystemModelInBackground',
         purl: `${PURL}#packages/subsystems-studio/src/bun/index.ts`,
         annotation: 'Broadcast done/error so the Maintain row flips off Running.',
@@ -818,7 +825,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'probe-route',
         mechanism: 'calls',
         file: 'packages/subsystems-studio/src/bun/http-server.ts',
-        line: 314,
+        span: { startLine: 314, endLine: 314, contentHash: 'fixture' },
         symbol: 'handleSubsystemModelRequest',
         purl: `${PURL}#packages/subsystems-studio/src/bun/http-server.ts`,
         annotation: "The agent's step-0 tool call curls POST /api/maintainer/probe with the run token.",
@@ -828,7 +835,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'maintain-probe-registry',
         mechanism: 'writes',
         file: 'packages/subsystems-studio/src/bun/http-server.ts',
-        line: 318,
+        span: { startLine: 318, endLine: 318, contentHash: 'fixture' },
         symbol: 'getMaintainerProbeRegistry',
         purl: `${PURL}#packages/subsystems-studio/src/bun/http-server.ts`,
         annotation: 'mark(runId) records when the probe landed.',
@@ -838,7 +845,7 @@ const MAINTAIN_TRAILS: SubsystemTrail[] = [
         to: 'maintain-probe-registry',
         mechanism: 'reads',
         file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts',
-        line: 484,
+        span: { startLine: 484, endLine: 484, contentHash: 'fixture' },
         symbol: 'runOpencodeV2AgentSession',
         purl: `${PURL}#packages/subsystems-studio/src/bun/opencode-v2-live.ts`,
         annotation: 'Each loop tick checks whether the token landed before the probe deadline.',
@@ -875,7 +882,7 @@ const MAINTAIN_ISSUES: SubsystemIssue[] = [
   {
     id: 'mr-decl',
     severity: 'error',
-    kind: 'stale_declaration',
+    kind: 'construct_span_stale',
     message: 'Declaration moved since capture — recorded start line 2522, now 2588.',
     target: {
       kind: 'component',

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

@@ -92,7 +92,7 @@ const trails: SubsystemTrail[] = [
         to: 'maintain',
         mechanism: 'calls',
         file: 'src/bun/verify-subsystem-component.ts',
-        line: 1,
+        span: { startLine: 1, endLine: 1, contentHash: 'fixture' },
         symbol: 'auditSubsystemModel',
         annotation: 'Live-only trail — no proposed badge.',
       },
@@ -107,7 +107,7 @@ const trails: SubsystemTrail[] = [
         to: 'maintain',
         mechanism: 'calls',
         file: 'src/bun/verify-subsystem-component.ts',
-        line: 1,
+        span: { startLine: 1, endLine: 1, contentHash: 'fixture' },
         symbol: 'auditSubsystemModel',
       },
       {
@@ -115,7 +115,7 @@ const trails: SubsystemTrail[] = [
         to: 'lifecycle',
         mechanism: 'uses',
         file: 'src/bun/maintain-model.ts',
-        line: 1,
+        span: { startLine: 1, endLine: 1, contentHash: 'fixture' },
         symbol: 'runMaintainModel',
         annotation: 'Step onto the proposed lifecycle — step index is tinted.',
       },
@@ -124,7 +124,7 @@ const trails: SubsystemTrail[] = [
         to: 'cli',
         mechanism: 'calls',
         file: 'src/bun/maintain-model.ts',
-        line: 1,
+        span: { startLine: 1, endLine: 1, contentHash: 'fixture' },
         symbol: 'OpenCodeV2Lifecycle.ensure',
       },
     ],
@@ -138,7 +138,7 @@ const trails: SubsystemTrail[] = [
         to: 'cache',
         mechanism: 'writes',
         file: 'src/bun/maintain-model.ts',
-        line: 1,
+        span: { startLine: 1, endLine: 1, contentHash: 'fixture' },
         symbol: 'LifecycleProbeCache.set',
         annotation: 'Both endpoints are proposed.',
       },
@@ -153,7 +153,7 @@ const trails: SubsystemTrail[] = [
         to: 'cli',
         mechanism: 'uses',
         file: 'src/bun/verify-subsystem-component.ts',
-        line: 1,
+        span: { startLine: 1, endLine: 1, contentHash: 'fixture' },
         symbol: 'probeCliVersion',
         // Step-level proposed: BOTH endpoints are real components — the
         // seam itself is what is planned. The edge label draws dashed on

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

@@ -87,7 +87,7 @@ const trails: SubsystemTrail[] = [
         to: 'api',
         mechanism: 'calls',
         file: 'src/ui/BookingPage.tsx',
-        line: 42,
+        span: { startLine: 42, endLine: 42, contentHash: 'fixture' },
         purl: stepPurl('src/ui/BookingPage.tsx'),
         symbol: 'BookingPage.submit',
         annotation: 'Submit hands the picked slot to the API.',
@@ -97,7 +97,7 @@ const trails: SubsystemTrail[] = [
         to: 'store',
         mechanism: 'writes',
         file: 'src/api/checkout.ts',
-        line: 18,
+        span: { startLine: 18, endLine: 18, contentHash: 'fixture' },
         purl: stepPurl('src/api/checkout.ts'),
         symbol: 'checkoutApi.book',
         annotation: 'API writes the booking into the store.',
@@ -107,7 +107,7 @@ const trails: SubsystemTrail[] = [
         to: 'db',
         mechanism: 'writes',
         file: 'src/store/bookingStore.ts',
-        line: 27,
+        span: { startLine: 27, endLine: 27, contentHash: 'fixture' },
         purl: stepPurl('src/store/bookingStore.ts'),
         symbol: 'BookingStore.commit',
         annotation: 'Store commits the row.',
@@ -117,7 +117,7 @@ const trails: SubsystemTrail[] = [
         to: 'ui',
         mechanism: 'produces',
         file: 'src/api/checkout.ts',
-        line: 24,
+        span: { startLine: 24, endLine: 24, contentHash: 'fixture' },
         purl: stepPurl('src/api/checkout.ts'),
         symbol: 'checkoutApi.respond',
         annotation: 'API returns the confirmed booking.',
@@ -133,7 +133,7 @@ const trails: SubsystemTrail[] = [
         to: 'api',
         mechanism: 'calls',
         file: 'src/ui/BookingPage.tsx',
-        line: 61,
+        span: { startLine: 61, endLine: 61, contentHash: 'fixture' },
         purl: stepPurl('src/ui/BookingPage.tsx'),
         symbol: 'BookingPage.cancel',
       },
@@ -142,7 +142,7 @@ const trails: SubsystemTrail[] = [
         to: 'store',
         mechanism: 'writes',
         file: 'src/api/checkout.ts',
-        line: 33,
+        span: { startLine: 33, endLine: 33, contentHash: 'fixture' },
         purl: stepPurl('src/api/checkout.ts'),
         symbol: 'checkoutApi.cancel',
       },
@@ -151,7 +151,7 @@ const trails: SubsystemTrail[] = [
         to: 'db',
         mechanism: 'writes',
         file: 'src/store/bookingStore.ts',
-        line: 41,
+        span: { startLine: 41, endLine: 41, contentHash: 'fixture' },
         purl: stepPurl('src/store/bookingStore.ts'),
         symbol: 'BookingStore.remove',
       },

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

@@ -134,32 +134,32 @@ const drawingTrails: SubsystemTrail[] = [
     id: 'tl-open-drawing',
     title: 'Open drawing',
     steps: [
-      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.scan', annotation: 'Lists the drawings directory; each row feeds an open intent.' },
-      { from: 'panel', to: 'host', mechanism: 'produces', file: 'src/panels/DrawingsLeftPanel.tsx', line: 85, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.openDrawing', annotation: 'Emits the open intent up to the host.' },
-      { from: 'host', to: 'storage', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 45, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.openDrawing', annotation: 'Host resolves the path and delegates to storage.' },
-      { from: 'host', to: 'shell', mechanism: 'produces', file: 'src/workspace/WorkspaceShell.tsx', line: 369, purl: stepPurl('src/workspace/WorkspaceShell.tsx'), symbol: 'WorkspaceShell.openTab', annotation: 'Asks the shell to surface the drawing as a tab.' },
-      { from: 'shell', to: 'tab', mechanism: 'feeds', file: 'src/workspace/WorkspaceShell.tsx', line: 372, purl: stepPurl('src/workspace/WorkspaceShell.tsx'), symbol: 'WorkspaceShell.mountTab' },
-      { from: 'storage', to: 'fs', mechanism: 'calls', file: 'src/storage/drawingsStorage.ts', line: 90, purl: stepPurl('src/storage/drawingsStorage.ts'), symbol: 'DrawingsStorage.read', annotation: 'Reads the file through the sandboxed fs service.' },
-      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 83, purl: stepPurl('src/components/DrawingTabContent.tsx'), symbol: 'DrawingTabContent.load' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', span: { startLine: 56, endLine: 56, contentHash: 'fixture' }, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.scan', annotation: 'Lists the drawings directory; each row feeds an open intent.' },
+      { from: 'panel', to: 'host', mechanism: 'produces', file: 'src/panels/DrawingsLeftPanel.tsx', span: { startLine: 85, endLine: 85, contentHash: 'fixture' }, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.openDrawing', annotation: 'Emits the open intent up to the host.' },
+      { from: 'host', to: 'storage', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', span: { startLine: 45, endLine: 45, contentHash: 'fixture' }, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.openDrawing', annotation: 'Host resolves the path and delegates to storage.' },
+      { from: 'host', to: 'shell', mechanism: 'produces', file: 'src/workspace/WorkspaceShell.tsx', span: { startLine: 369, endLine: 369, contentHash: 'fixture' }, purl: stepPurl('src/workspace/WorkspaceShell.tsx'), symbol: 'WorkspaceShell.openTab', annotation: 'Asks the shell to surface the drawing as a tab.' },
+      { from: 'shell', to: 'tab', mechanism: 'feeds', file: 'src/workspace/WorkspaceShell.tsx', span: { startLine: 372, endLine: 372, contentHash: 'fixture' }, purl: stepPurl('src/workspace/WorkspaceShell.tsx'), symbol: 'WorkspaceShell.mountTab' },
+      { from: 'storage', to: 'fs', mechanism: 'calls', file: 'src/storage/drawingsStorage.ts', span: { startLine: 90, endLine: 90, contentHash: 'fixture' }, purl: stepPurl('src/storage/drawingsStorage.ts'), symbol: 'DrawingsStorage.read', annotation: 'Reads the file through the sandboxed fs service.' },
+      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', span: { startLine: 83, endLine: 83, contentHash: 'fixture' }, purl: stepPurl('src/components/DrawingTabContent.tsx'), symbol: 'DrawingTabContent.load' },
     ],
   },
   {
     id: 'tl-save-drawing',
     title: 'Save drawing',
     steps: [
-      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 112, purl: stepPurl('src/components/DrawingTabContent.tsx'), symbol: 'DrawingTabContent.save' },
-      { from: 'tab', to: 'host', mechanism: 'produces', file: 'src/components/DrawingTabContent.tsx', line: 121, purl: stepPurl('src/components/DrawingTabContent.tsx'), symbol: 'DrawingTabContent.emitSaved' },
-      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 64, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.onSaved' },
-      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.scan' },
+      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', span: { startLine: 112, endLine: 112, contentHash: 'fixture' }, purl: stepPurl('src/components/DrawingTabContent.tsx'), symbol: 'DrawingTabContent.save' },
+      { from: 'tab', to: 'host', mechanism: 'produces', file: 'src/components/DrawingTabContent.tsx', span: { startLine: 121, endLine: 121, contentHash: 'fixture' }, purl: stepPurl('src/components/DrawingTabContent.tsx'), symbol: 'DrawingTabContent.emitSaved' },
+      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', span: { startLine: 64, endLine: 64, contentHash: 'fixture' }, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.onSaved' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', span: { startLine: 56, endLine: 56, contentHash: 'fixture' }, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.scan' },
     ],
   },
   {
     id: 'tl-delete-drawing',
     title: 'Delete drawing',
     steps: [
-      { from: 'host', to: 'fs', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 64, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.deleteDrawing' },
-      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 66, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.refreshList' },
-      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.scan' },
+      { from: 'host', to: 'fs', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', span: { startLine: 64, endLine: 64, contentHash: 'fixture' }, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.deleteDrawing' },
+      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', span: { startLine: 66, endLine: 66, contentHash: 'fixture' }, purl: stepPurl('src/hooks/useDrawingsHost.ts'), symbol: 'useDrawingsHost.refreshList' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', span: { startLine: 56, endLine: 56, contentHash: 'fixture' }, purl: stepPurl('src/panels/DrawingsLeftPanel.tsx'), symbol: 'DrawingsLeftPanel.scan' },
     ],
   },
 ];
@@ -255,7 +255,7 @@ const proposedTrails: SubsystemTrail[] = [
         to: 'storage',
         mechanism: 'calls',
         file: 'src/hooks/useDrawingsHost.ts',
-        line: 45,
+        span: { startLine: 45, endLine: 45, contentHash: 'fixture' },
         purl: stepPurl('src/hooks/useDrawingsHost.ts'),
         symbol: 'useDrawingsHost.openDrawing',
         annotation: 'Live step — its snippet still renders.',
@@ -265,7 +265,7 @@ const proposedTrails: SubsystemTrail[] = [
         to: 'runs',
         mechanism: 'writes',
         file: 'src/runs/subsystemModelRuns.ts',
-        line: 1,
+        span: { startLine: 1, endLine: 1, contentHash: 'fixture' },
         purl: stepPurl('src/runs/subsystemModelRuns.ts'),
         symbol: 'SubsystemModelRunStore.write',
         annotation: 'Proposed seam — the file is not in the checkout yet.',
@@ -350,11 +350,10 @@ const clickableComponents: SubsystemComponent[] = [
     symbol: 'LoadPanel',
     purpose: 'loads the drawing list and hands rows to the render surface',
     process: 'draw-list',
-    declarationRef: {
-      file: 'src/load/LoadPanel.tsx',
+    declarationSpan: {
       startLine: 3,
-      lineHash: 'story',
-      capturedAt: '2026-01-01T00:00:00.000Z',
+      endLine: 3,
+      contentHash: 'story',
     },
     declaration: {
       kind: 'function',
@@ -374,11 +373,10 @@ const clickableComponents: SubsystemComponent[] = [
     symbol: 'DrawingStore.list',
     purpose: 'lists stored drawings for the panel',
     process: 'draw-list',
-    declarationRef: {
-      file: 'src/store/DrawingStore.ts',
+    declarationSpan: {
       startLine: 4,
-      lineHash: 'story',
-      capturedAt: '2026-01-01T00:00:00.000Z',
+      endLine: 4,
+      contentHash: 'story',
     },
     declaration: {
       kind: 'method',
@@ -397,11 +395,10 @@ const clickableComponents: SubsystemComponent[] = [
     symbol: 'RenderSurface',
     purpose: 'paints a drawing into a surface',
     process: 'draw-host',
-    declarationRef: {
-      file: 'src/render/RenderSurface.ts',
+    declarationSpan: {
       startLine: 3,
-      lineHash: 'story',
-      capturedAt: '2026-01-01T00:00:00.000Z',
+      endLine: 3,
+      contentHash: 'story',
     },
     declaration: {
       kind: 'class',
@@ -454,7 +451,7 @@ const clickableTrails: SubsystemTrail[] = [
         to: 'drawing-store-list',
         mechanism: 'calls',
         file: 'src/load/LoadPanel.tsx',
-        line: 4,
+        span: { startLine: 4, endLine: 4, contentHash: 'fixture' },
         purl: stepPurl('src/load/LoadPanel.tsx'),
         symbol: 'LoadPanel.load',
         annotation:
@@ -465,7 +462,7 @@ const clickableTrails: SubsystemTrail[] = [
         to: 'render-surface',
         mechanism: 'calls',
         file: 'src/store/DrawingStore.ts',
-        line: 5,
+        span: { startLine: 5, endLine: 5, contentHash: 'fixture' },
         purl: stepPurl('src/store/DrawingStore.ts'),
         symbol: 'DrawingStore.list',
         annotation: 'list reads through RenderSurface — click RenderSurface.',

package/src/stories/Subsystem/ComponentGraph/fixtures.ts

@@ -38,7 +38,7 @@ export function trailFromSteps(
       to,
       mechanism,
       file,
-      line,
+      span: { startLine: line, endLine: line, contentHash: 'fixture' },
       purl: `pkg:github/storybook/fixture#${file}`,
       symbol: symbol ?? from,
     })),
@@ -54,7 +54,6 @@ export function graphSpecFromSteps(
     to,
     mechanism: mechanism as SubsystemTrailMechanism,
     file: 'story-placeholder.ts',
-    line: 1,
     purl: 'pkg:github/storybook/fixture#story-placeholder.ts',
     symbol: from,
   }));

package/src/stories/Subsystem/ConstructsCatalog.stories.tsx

@@ -43,11 +43,10 @@ const components: SubsystemComponent[] = [
     process: 'notes-api/server',
     file: 'src/api/submitNote.ts',
     purpose: 'HTTP/handler entry — validates and hands off to the service.',
-    declarationRef: {
-      file: 'src/api/submitNote.ts',
+    declarationSpan: {
       startLine: 7,
-      lineHash: 'storybook-placeholder',
-      capturedAt: new Date(0).toISOString(),
+      endLine: 7,
+      contentHash: 'storybook-placeholder',
     },
     declaration: {
       kind: 'function',
@@ -69,11 +68,10 @@ const components: SubsystemComponent[] = [
     process: 'notes-api/server',
     file: 'src/NoteService.ts',
     purpose: 'Owns intake rules; methods are separate nodes when they matter.',
-    declarationRef: {
-      file: 'src/NoteService.ts',
+    declarationSpan: {
       startLine: 3,
-      lineHash: 'storybook-placeholder',
-      capturedAt: new Date(0).toISOString(),
+      endLine: 3,
+      contentHash: 'storybook-placeholder',
     },
     declaration: {
       kind: 'class',
@@ -101,11 +99,10 @@ const components: SubsystemComponent[] = [
     process: 'notes-api/server',
     file: 'src/NoteService.ts',
     purpose: 'Instance method on NoteService — written as its own construct.',
-    declarationRef: {
-      file: 'src/NoteService.ts',
+    declarationSpan: {
       startLine: 14,
-      lineHash: 'storybook-placeholder',
-      capturedAt: new Date(0).toISOString(),
+      endLine: 14,
+      contentHash: 'storybook-placeholder',
     },
     declaration: {
       kind: 'method',
@@ -337,7 +334,7 @@ function renderFileViewer(file: string, opts?: SubsystemOpenFileOptions) {
         filePath={file}
         fileName={file.split('/').pop() ?? file}
         startLine={startLine}
-        endLine={startLine}
+        endLine={opts?.endLine ?? startLine}
         focusLine={startLine}
         contextLines={12}
         readFile={readStoryFile}

package/src/stories/Subsystem/EgoGraph/EgoGraph.stories.tsx

@@ -151,11 +151,10 @@ function toComponent(
     ...(line != null ? { line } : {}),
     ...(line != null
       ? {
-          declarationRef: {
-            file: node.source_file ?? '',
+          declarationSpan: {
             startLine: line,
-            lineHash: 'ego-fixture',
-            capturedAt: new Date(0).toISOString(),
+            endLine: line,
+            contentHash: 'ego-fixture',
           },
         }
       : {}),