@principal-ai/subsystems-react 0.20.6 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-react",
-  "version": "0.20.6",
+  "version": "0.21.0",
   "description": "React UI for Subsystem Models — graph, Pierre code views, and session-event feeds",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,7 +37,7 @@
   "peerDependencies": {
     "@pierre/diffs": ">=1.1.20",
     "@principal-ade/industry-theme": "^0.1.7",
-    "@principal-ai/subsystems-core": ">=0.30.0",
+    "@principal-ai/subsystems-core": ">=0.32.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
@@ -45,7 +45,7 @@
     "@pierre/diffs": "1.3.6",
     "@principal-ade/industry-theme": "0.1.7",
     "@principal-ai/agent-monitoring": "^0.3.38",
-    "@principal-ai/subsystems-core": "0.31.0",
+    "@principal-ai/subsystems-core": "0.32.0",
     "@storybook/addon-docs": "10.1.2",
     "@storybook/addon-links": "10.1.2",
     "@storybook/addon-onboarding": "10.1.2",

package/src/graphify/anchor.test.ts

@@ -5,7 +5,7 @@ import {
 	makeGraphifyId,
 	normalizeGraphifyId,
 } from './ids';
-import { resolveComponentAnchor, symbolLabelVariants } from './anchor';
+import { resolveComponentAnchor, symbolLabelVariants, findUniqueDefinitionBySymbol } from './anchor';
 
 function node(
 	id: string,
@@ -31,7 +31,7 @@ describe('makeGraphifyId', () => {
 			'packages/subsystems-studio/src/mainview/views/SubsystemModelView',
 		);
 		expect(makeGraphifyId(stem, 'SubsystemModelView')).toBe(
-			'packages_trail_viewer_src_mainview_views_subsystemmodelview_subsystemmodelview',
+			'packages_subsystems_studio_src_mainview_views_subsystemmodelview_subsystemmodelview',
 		);
 	});
 
@@ -122,3 +122,32 @@ describe('resolveComponentAnchor', () => {
 		expect(r.resolution).toBe('missing');
 	});
 });
+
+describe('findUniqueDefinitionBySymbol', () => {
+	test('unique when one defining file', () => {
+		const nodes = [
+			node('a', 'HostInfo', 'src/a.ts', 'L1'),
+			node('b', 'Other', 'src/b.ts', 'L1'),
+		];
+		const r = findUniqueDefinitionBySymbol(nodes, 'HostInfo');
+		expect(r.status).toBe('unique');
+		if (r.status === 'unique') expect(r.node.source_file).toBe('src/a.ts');
+	});
+
+	test('ambiguous when same symbol in two files', () => {
+		const nodes = [
+			node('a', 'Foo()', 'src/a.ts', 'L1'),
+			node('b', 'Foo()', 'src/b.ts', 'L1'),
+		];
+		const r = findUniqueDefinitionBySymbol(nodes, 'Foo');
+		expect(r.status).toBe('ambiguous');
+	});
+
+	test('none when symbol absent', () => {
+		const r = findUniqueDefinitionBySymbol(
+			[node('a', 'Bar', 'src/a.ts')],
+			'Foo',
+		);
+		expect(r.status).toBe('none');
+	});
+});

package/src/graphify/anchor.ts

@@ -158,3 +158,49 @@ export function resolveComponentAnchor(
 		triedIds,
 	};
 }
+
+export type UniqueDefinitionBySymbolResult =
+	| { status: 'unique'; node: GraphifyNode }
+	| { status: 'ambiguous'; candidates: GraphifyNode[] }
+	| { status: 'none' };
+
+/**
+ * Corpus-wide definition lookup by symbol label only (no claimed file).
+ * Used when the model’s file path is missing and we want a deterministic
+ * relocate if exactly one defining file still declares the symbol.
+ *
+ * Unique means a single `source_file` among matching definition nodes.
+ */
+export function findUniqueDefinitionBySymbol(
+	nodes: readonly GraphifyNode[],
+	symbol: string,
+): UniqueDefinitionBySymbolResult {
+	const trimmed = symbol.trim();
+	if (!trimmed) return { status: 'none' };
+
+	const hits: GraphifyNode[] = [];
+	for (const node of nodes) {
+		if (!isDefinition(node)) continue;
+		if (!labelMatchesSymbol(String(node.label ?? ''), trimmed)) continue;
+		hits.push(node);
+	}
+	if (hits.length === 0) return { status: 'none' };
+
+	const byFile = new Map<string, GraphifyNode[]>();
+	for (const n of hits) {
+		const sf = normalizeSourcePath(String(n.source_file ?? ''));
+		if (!sf) continue;
+		const list = byFile.get(sf) ?? [];
+		list.push(n);
+		byFile.set(sf, list);
+	}
+	if (byFile.size === 0) return { status: 'none' };
+	if (byFile.size > 1) {
+		return {
+			status: 'ambiguous',
+			candidates: hits.slice(0, 12),
+		};
+	}
+	const only = [...byFile.values()][0]!;
+	return { status: 'unique', node: only[0]! };
+}

package/src/graphify/consolidated.ts

@@ -161,6 +161,25 @@ export interface GraphifyFunctionDetail {
   callees: GraphifyCallInfo[];
 }
 
+/** One generic type parameter, e.g. `T` or `K extends keyof StudioMessages`. */
+export interface GraphifyTypeParamInfo {
+  name: string;
+  /** Constraint written after `extends` (or language equivalent). */
+  constraint?: string;
+}
+
+/** A callable/function type: `(params) => returnType`. */
+export interface GraphifyCallableTypeInfo {
+  parameters?: GraphifyParamInfo[];
+  returnType?: string;
+}
+
+/** One enum member, with its optional literal value. */
+export interface GraphifyEnumMemberInfo {
+  name: string;
+  value?: string;
+}
+
 /** A type-like node (interface/struct): revealed by incoming `implements` edges. */
 export interface GraphifyTypeDetail {
   kind: 'type';
@@ -170,6 +189,22 @@ export interface GraphifyTypeDetail {
   usedBy: GraphifyReferenceInfo[];
   /** Nodes that `inherits`/`implements` this type. */
   implementors: string[];
+  /** Generic type parameters, e.g. `<K extends keyof StudioMessages>`. */
+  generics?: GraphifyTypeParamInfo[];
+  /** Callable type — `(params) => returnType` (TS/Go/Rust fn, Java lambda). */
+  signature?: GraphifyCallableTypeInfo;
+  /** Enum members (name, optional literal value). */
+  enumMembers?: GraphifyEnumMemberInfo[];
+  /** Alias whose RHS is a plain reference, e.g. `StudioMessages[K]`. */
+  aliasOf?: string;
+  /** Simple union of alternatives, e.g. `'started' | 'stopped'`. */
+  unionOf?: string[];
+  /**
+   * Verbatim RHS — the escape hatch for shapes the structured fields can't
+   * express (mapped/conditional/template-literal/infer types, `typeof`/utility
+   * compositions, C pointers, Rust trait objects). Wins over every shape above.
+   */
+  rhs?: string;
 }
 
 /** A module/file-like node: a `contains` target with a filename label. */
@@ -221,6 +256,13 @@ export interface GraphifyStoreDetail {
   kind: 'store';
   /** The retained state members (module-level consts or class fields). */
   properties: GraphifyPropertyInfo[];
+  /**
+   * Where the retained state physically lives / who mediates access. Authored
+   * — graphify cannot infer it: `memory` = process-lifetime RAM, `disk` =
+   * this process reads/writes the filesystem, `external` = mediated by another
+   * system (db/service; carries no `process`).
+   */
+  storage?: 'memory' | 'disk' | 'external';
 }
 
 /** A standalone method selected from its owning class. */
@@ -235,7 +277,7 @@ export interface GraphifyMethodDetail {
 }
 
 /**
- * The drill-down payload for a subsystem component.
+ * The structured declaration payload for a subsystem component (click panel).
  *
  * The discriminant is derived from graph structure, not read off the node:
  * method edges → class; `()` label + no method edges → function; incoming

package/src/index.ts

@@ -86,7 +86,7 @@ export type { UseElkLayoutOptions, UseElkLayoutResult } from './hooks/useElkLayo
 
 // Subsystem component graph
 export { SubsystemComponentGraph } from './subsystem/SubsystemComponentGraph';
-export type { SubsystemComponentGraphProps, ThroughlineViewerContext } from './subsystem/SubsystemComponentGraph';
+export type { SubsystemComponentGraphProps, WalkthroughViewerContext } from './subsystem/SubsystemComponentGraph';
 export type {
   ComponentVerificationState,
   ComponentVerificationPhase,
@@ -114,14 +114,19 @@ export type { GraphLayoutCoverProps } from './subsystem/GraphLayoutCover';
 export type {
   SubsystemComponent,
   SubsystemComponentEdge,
-  SubsystemThroughline,
-  SubsystemThroughlineStep,
+  SubsystemRelation,
+  SubsystemRelationType,
+  SubsystemWalkthrough,
+  SubsystemWalkthroughStep,
+  SubsystemWalkthroughMechanism,
   SubsystemModelDocument,
   SubsystemComponentConstruct,
   SubsystemComponentRole,
   SubsystemFramework,
   SubsystemStereotype,
   SubsystemEdgeMechanism,
+  SubsystemConstructDeclaration,
+  SubsystemDeclarationProvenance,
 } from './subsystem/model';
 export {
   constructBadgeLabel,
@@ -129,6 +134,9 @@ export {
   rightBadgeColor,
   deriveNameFromSymbol,
   nodeMinWidthForBadges,
+  deriveGraphEdges,
+  derivedGraphEdgeId,
+  walkthroughStepGraphEdgeId,
   ROLE_COLOR,
   ROLE_LABEL,
   PROPOSED_COLOR,
@@ -146,11 +154,11 @@ export {
 } from './subsystem/declarationRef';
 
 // Pierre code views (@pierre/diffs wrappers)
-export { PierreFileView, PierreSnippetView, PierreThroughlineCodeView, sliceSnippetWindow, resolvePierreSyntaxThemeName } from './pierre';
+export { PierreFileView, PierreSnippetView, PierreWalkthroughCodeView, sliceSnippetWindow, resolvePierreSyntaxThemeName } from './pierre';
 export type {
   PierreFileViewProps,
   PierreSnippetViewProps,
-  PierreThroughlineCodeViewProps,
+  PierreWalkthroughCodeViewProps,
   SnippetSlice,
   PierreSyntaxThemeName,
 } from './pierre';

package/src/pierre/{PierreThroughlineCodeView.tsx → PierreWalkthroughCodeView.tsx}

@@ -1,7 +1,7 @@
 /**
- * PierreThroughlineCodeView — multi-file step snippets via `@pierre/diffs` CodeView.
+ * PierreWalkthroughCodeView — multi-file step snippets via `@pierre/diffs` CodeView.
  *
- * Renders one sliced window per throughline step in a single virtualized
+ * Renders one sliced window per walkthrough step in a single virtualized
  * scroll; when `stepIndex` changes, scrolls that step's site line into view
  * and highlights it via CodeView `selectedLines` (same mechanism as
  * `PierreSnippetView`).
@@ -22,10 +22,10 @@ type CodeViewLineSelection = {
   id: string;
   range: { start: number; end: number };
 };
-/** Metadata carried on a throughline step's line annotation. */
-type ThroughlineStepAnnotation = { text: string };
+/** Metadata carried on a walkthrough step's line annotation. */
+type WalkthroughStepAnnotation = { text: string };
 import { useTheme } from '@principal-ade/industry-theme';
-import type { SubsystemThroughline } from '../subsystem/model';
+import type { SubsystemWalkthrough } from '../subsystem/model';
 import { buildPierreOptions, PIERRE_FILE_STYLE } from './pierreBackground';
 import {
   pierreCodeViewFileName,
@@ -34,8 +34,8 @@ import {
 import { resolvePierreSyntaxThemeName } from './pierreSyntaxTheme';
 import { sliceSnippetWindow, type SnippetSlice } from './sliceSnippet';
 
-export interface PierreThroughlineCodeViewProps {
-  throughline: SubsystemThroughline;
+export interface PierreWalkthroughCodeViewProps {
+  walkthrough: SubsystemWalkthrough;
   /** Focused step; `null` shows all snippets without scrolling to a step. */
   stepIndex: number | null;
   readFile: (path: string) => Promise<string>;
@@ -50,31 +50,31 @@ type FileLoadState =
   | { status: 'error'; message: string }
   | { status: 'ready'; byPath: Map<string, string> };
 
-function stepItemId(throughlineId: string, index: number): string {
-  return `${throughlineId}:${index}`;
+function stepItemId(walkthroughId: string, index: number): string {
+  return `${walkthroughId}:${index}`;
 }
 
-export function PierreThroughlineCodeView({
-  throughline,
+export function PierreWalkthroughCodeView({
+  walkthrough,
   stepIndex,
   readFile,
   contextLines = 8,
   background,
-}: PierreThroughlineCodeViewProps) {
+}: PierreWalkthroughCodeViewProps) {
   const { theme, mode } = useTheme();
   const viewRef = useRef<CodeViewHandle<undefined>>(null);
   const [load, setLoad] = useState<FileLoadState>({ status: 'loading' });
 
   const pathsKey = useMemo(() => {
-    const paths = [...new Set(throughline.steps.map((s) => s.file))];
+    const paths = [...new Set(walkthrough.steps.map((s) => s.file))];
     paths.sort();
     return paths.join('\0');
-  }, [throughline.steps]);
+  }, [walkthrough.steps]);
 
   useEffect(() => {
     let cancelled = false;
     setLoad({ status: 'loading' });
-    const paths = [...new Set(throughline.steps.map((s) => s.file))];
+    const paths = [...new Set(walkthrough.steps.map((s) => s.file))];
     void Promise.all(
       paths.map(async (path) => {
         const contents = await readFile(path);
@@ -95,11 +95,11 @@ export function PierreThroughlineCodeView({
     return () => {
       cancelled = true;
     };
-  }, [throughline.id, pathsKey, readFile]);
+  }, [walkthrough.id, pathsKey, readFile]);
 
   const slices = useMemo((): SnippetSlice[] => {
     if (load.status !== 'ready') return [];
-    return throughline.steps.map((step) => {
+    return walkthrough.steps.map((step) => {
       const contents = load.byPath.get(step.file) ?? '';
       return sliceSnippetWindow(
         contents,
@@ -109,15 +109,15 @@ export function PierreThroughlineCodeView({
         step.line,
       );
     });
-  }, [load, throughline.steps, contextLines]);
+  }, [load, walkthrough.steps, contextLines]);
 
-const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
+const items = useMemo((): CodeViewItem<WalkthroughStepAnnotation>[] => {
     if (load.status !== 'ready' || slices.length === 0) return [];
-    return throughline.steps.map((step, index) => {
+    return walkthrough.steps.map((step, index) => {
       const slice = slices[index]!;
       const focus = slice.focusOffset;
       const annotations:
-        | LineAnnotation<ThroughlineStepAnnotation>[]
+        | LineAnnotation<WalkthroughStepAnnotation>[]
         | undefined =
         step.annotation != null && step.annotation.length > 0 && focus != null
           ? [
@@ -128,26 +128,20 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
             ]
           : undefined;
       return {
-        id: stepItemId(throughline.id, index),
+        id: stepItemId(walkthrough.id, index),
         type: 'file' as const,
         version: 1,
         annotations,
         file: {
-          // Unique per-step name: many throughline steps share one path
-          // (e.g. seven sites in main.cpp), and identical `name`s have
-          // correlated with WebKit renderer traps in CodeView.
           name: pierreCodeViewFileName(step.file, index),
           contents: slice.contents,
-          // C-family → plain text: cpp Shiki still traps WebKit even with
-          // unique names (reproduced on 0.16.67).
           lang: pierreLangForPath(step.file),
-          cacheKey: `${throughline.id}:${index}:${step.file}:${step.line}:${slice.sliceStart}-${slice.sliceEnd}`,
+          cacheKey: `${walkthrough.id}:${index}:${step.file}:${step.line}:${slice.sliceStart}-${slice.sliceEnd}`,
         },
       };
     });
-  }, [load, slices, throughline.id, throughline.steps]);
+  }, [load, slices, walkthrough.id, walkthrough.steps]);
 
-  /** Highlight the focused step's site line (1-based within its sliced window). */
   const selectedLines = useMemo((): CodeViewLineSelection | null => {
     if (stepIndex == null || stepIndex < 0 || stepIndex >= slices.length) {
       return null;
@@ -155,15 +149,15 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
     const focus = slices[stepIndex]?.focusOffset;
     if (focus == null) return null;
     return {
-      id: stepItemId(throughline.id, stepIndex),
+      id: stepItemId(walkthrough.id, stepIndex),
       range: { start: focus, end: focus },
     };
-  }, [stepIndex, slices, throughline.id]);
+  }, [stepIndex, slices, walkthrough.id]);
 
   const renderHeaderPrefix = useMemo(() => {
     return (item: CodeViewItem) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      const step = throughline.steps[index];
+      const step = walkthrough.steps[index];
       if (!step) return null;
       const label =
         step.symbol != null && step.symbol.length > 0
@@ -182,12 +176,12 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
         </span>
       );
     };
-  }, [throughline.steps, theme]);
+  }, [walkthrough.steps, theme]);
 
   const renderHeaderMetadata = useMemo(() => {
     return (item: CodeViewItem) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      const step = throughline.steps[index];
+      const step = walkthrough.steps[index];
       if (!step) return null;
       return (
         <span
@@ -202,17 +196,17 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
         </span>
       );
     };
-  }, [throughline.steps, theme]);
+  }, [walkthrough.steps, theme]);
 
   const renderAnnotation = useMemo(() => {
     return (
       annotation:
-        | LineAnnotation<ThroughlineStepAnnotation>
-        | DiffLineAnnotation<ThroughlineStepAnnotation>,
-      item: CodeViewItem<ThroughlineStepAnnotation>,
+        | LineAnnotation<WalkthroughStepAnnotation>
+        | DiffLineAnnotation<WalkthroughStepAnnotation>,
+      item: CodeViewItem<WalkthroughStepAnnotation>,
     ) => {
       const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
-      const step = throughline.steps[index];
+      const step = walkthrough.steps[index];
       const text = annotation.metadata?.text;
       if (!text || !step) return null;
       return (
@@ -230,7 +224,7 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
         </span>
       );
     };
-  }, [throughline.steps, theme]);
+  }, [walkthrough.steps, theme]);
 
   const options = useMemo((): CodeViewReactOptions => {
     return {
@@ -248,11 +242,10 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
 
   useEffect(() => {
     if (load.status !== 'ready' || stepIndex == null) return;
-    if (stepIndex < 0 || stepIndex >= throughline.steps.length) return;
+    if (stepIndex < 0 || stepIndex >= walkthrough.steps.length) return;
     const focus = slices[stepIndex]?.focusOffset;
     if (focus == null) return;
-    // Defer until CodeView has laid out items.
-    const id = stepItemId(throughline.id, stepIndex);
+    const id = stepItemId(walkthrough.id, stepIndex);
     const t = window.setTimeout(() => {
       viewRef.current?.scrollTo({
         type: 'line',
@@ -265,8 +258,8 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
   }, [
     load.status,
     stepIndex,
-    throughline.id,
-    throughline.steps.length,
+    walkthrough.id,
+    walkthrough.steps.length,
     slices,
     items.length,
   ]);
@@ -286,7 +279,6 @@ const items = useMemo((): CodeViewItem<ThroughlineStepAnnotation>[] => {
     );
   }
 
-  // Pierre's CodeView prop / item unions blow past TS's complexity limit.
   const CodeViewLoose = CodeView as unknown as (props: Record<string, unknown>) => ReactElement;
 
   return (

package/src/pierre/index.ts

@@ -2,8 +2,8 @@ export { PierreFileView } from './PierreFileView';
 export type { PierreFileViewProps } from './PierreFileView';
 export { PierreSnippetView } from './PierreSnippetView';
 export type { PierreSnippetViewProps } from './PierreSnippetView';
-export { PierreThroughlineCodeView } from './PierreThroughlineCodeView';
-export type { PierreThroughlineCodeViewProps } from './PierreThroughlineCodeView';
+export { PierreWalkthroughCodeView } from './PierreWalkthroughCodeView';
+export type { PierreWalkthroughCodeViewProps } from './PierreWalkthroughCodeView';
 export { sliceSnippetWindow } from './sliceSnippet';
 export type { SnippetSlice } from './sliceSnippet';
 export {

package/src/pierre/pierreFileLang.ts

@@ -7,7 +7,7 @@
  * `file.name`s — so we force plain text for those paths until Pierre/WebKit
  * is safe with them.
  *
- * Distinct throughline slices of the same path still need unique `file.name`s
+ * Distinct walkthrough slices of the same path still need unique `file.name`s
  * (see `pierreCodeViewFileName`).
  */
 

package/src/stories/Pierre/CodeView.stories.tsx

@@ -1,7 +1,7 @@
 /**
  * Demo: Pierre CodeView with snippets from different files.
  *
- * Throughlines want many short windows across files in one scroll —
+ * Walkthroughs want many short windows across files in one scroll —
  * CodeView is the Pierre primitive for that (virtualized list of file items).
  */
 import React, { useMemo, useRef } from 'react';
@@ -54,7 +54,7 @@ const SNIPPETS: SnippetSpec[] = [
     startLine: 216,
     endLine: 250,
     focusLine: 216,
-    label: '3 · Throughline types',
+    label: '3 · Walkthrough types',
   },
 ];
 
@@ -159,7 +159,7 @@ function MultiFileSnippetsDemo() {
         }}
       >
         <div style={{ fontSize: 13, fontWeight: 600, marginBottom: 4 }}>
-          Throughline steps
+          Walkthrough steps
         </div>
         <div style={{ fontSize: 12, color: theme.colors.textSecondary, marginBottom: 8 }}>
           Click a step to scroll + highlight its site line.

package/src/stories/Subsystem/ComponentDeclarationAudit.stories.tsx

@@ -43,7 +43,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/event-processing/sink.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'flush',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [],
       } satisfies GraphifyComponentDetail,
@@ -58,7 +58,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/session/SessionReader.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionReader.normalize',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [{ name: 'session', type: 'SessionRecord' }],
         returnType: 'SessionEvent[]',
@@ -74,7 +74,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/event-processing/normalize.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'normalizeSession',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [
           { name: 'session', type: 'SessionRecord' },
@@ -93,7 +93,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/session/merge.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'mergeSessions',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [
           { name: 'sessions', type: 'SessionRecord[]' },
@@ -114,7 +114,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/empty.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'EmptyClass',
-      detail: {
+      declaration: {
         kind: 'class',
       } satisfies GraphifyComponentDetail,
     },
@@ -128,7 +128,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/config.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'Config',
-      detail: {
+      declaration: {
         kind: 'class',
         properties: [
           { name: 'host', type: 'string' },
@@ -147,7 +147,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/event-processing/EventProcessor.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'EventProcessor',
-      detail: {
+      declaration: {
         kind: 'class',
         methods: [
           { name: 'process', parameters: [{ type: 'RawEvent' }, { type: 'ProcessingOptions' }], returnType: 'ProcessedEvent' },
@@ -174,7 +174,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/session/transcript.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionRecord',
-      detail: {
+      declaration: {
         kind: 'type',
         properties: [
           { name: 'id', type: 'string' },
@@ -192,7 +192,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/types.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'BrandedId',
-      detail: {
+      declaration: {
         kind: 'type',
       } satisfies GraphifyComponentDetail,
     },
@@ -206,7 +206,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/index.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'index',
-      detail: {
+      declaration: {
         kind: 'module',
         imports: [
           { name: './session/SessionReader' },
@@ -237,7 +237,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: '',
       purl: 'pkg:npm/@principal-ai/subsystems-studio',
       symbol: '',
-      detail: {
+      declaration: {
         kind: 'external',
         label: 'pkg:npm/@principal-ai/subsystems-studio',
       } satisfies GraphifyComponentDetail,
@@ -251,7 +251,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       construct: 'function',
       file: 'src/helpers.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
-      detail: {
+      declaration: {
         kind: 'function',
         parameters: [{ name: 'input', type: 'string' }],
         returnType: 'void',
@@ -267,7 +267,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/session/SessionReader.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'SessionReader.normalize',
-      detail: {
+      declaration: {
         kind: 'method',
         hostClass: 'SessionReader',
         parameters: [{ name: 'session', type: 'SessionRecord' }],
@@ -284,7 +284,7 @@ const cases: { label: string; component: SubsystemComponent }[] = [
       file: 'src/event-processing/EventProcessor.ts',
       purl: 'pkg:github/principal-ai/agent-monitoring',
       symbol: 'EventProcessor.dispose',
-      detail: {
+      declaration: {
         kind: 'method',
         hostClass: 'EventProcessor',
       } satisfies GraphifyComponentDetail,