@principal-ai/principal-view-react 0.16.55 → 0.16.57

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

@@ -0,0 +1,129 @@
+import type {
+  SubsystemComponent,
+  SubsystemComponentEdge,
+} from '../../../subsystem/model';
+import type { GraphifyComponentDetail } from '../../../graphify';
+
+// ---------------------------------------------------------------------------
+// Build a subsystem graph from a compact spec - helpers
+// ---------------------------------------------------------------------------
+export function components(
+  spec: Array<[id: string, name: string, construct: SubsystemComponent['construct'], file: string, purl: string, purpose?: string, symbol?: string, detail?: GraphifyComponentDetail]>,
+): SubsystemComponent[] {
+  return spec.map(([id, name, construct, file, purl, purpose, symbol, detail]) => ({
+    id,
+    name,
+    construct,
+    file,
+    purl,
+    purpose,
+    symbol,
+    detail,
+  }));
+}
+
+export function edges(
+  spec: Array<[from: string, to: string, mechanism: SubsystemComponentEdge['mechanism'], refs?: string[]]>,
+): SubsystemComponentEdge[] {
+  return spec.map(([from, to, mechanism, refs], i) => ({
+    id: `e${i}`,
+    from,
+    to,
+    mechanism,
+    refs,
+  }));
+}
+
+export const readerDetail: GraphifyComponentDetail = {
+  kind: 'class',
+  methods: [
+    { nodeId: 'm1', name: 'normalize', returnType: 'SessionEvent[]' },
+    { nodeId: 'm2', name: 'readSession', parameters: [{ type: 'string' }], returnType: 'SessionRecord' },
+    { nodeId: 'm3', name: 'toUniversalEvents', returnType: 'UniversalEvent[]' },
+  ],
+  properties: [{ name: 'sessionId', type: 'string' }],
+  extends: [],
+  implements: ['SessionReaderLike'],
+  instantiations: [{ nodeId: 'caller1', name: 'capture-session' }],
+  references: [{ nodeId: 'ref1', name: 'supported-agents', context: 'type' }],
+};
+
+// ---------------------------------------------------------------------------
+// Single package (no consumers) - the investigate-and-pin pattern.
+// Conveys the idea via LAYERS: readers (input) → accumulator (processing).
+// ---------------------------------------------------------------------------
+export const investigateOnlyComponents: SubsystemComponent[] = [
+  {
+    id: 'v1',
+    name: 'V1EventBridgeProcessor',
+    construct: 'class',
+    file: 'src/event-processing/V1EventBridge.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'normalizes V1 DB rows into universal events',
+    symbol: 'V1EventBridgeProcessor',
+  },
+  {
+    id: 'v2',
+    name: 'V2EventBridgeProcessor',
+    construct: 'class',
+    file: 'src/event-processing/V2EventBridge.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'normalizes V2 durable events into universal events',
+    symbol: 'V2EventBridgeProcessor',
+  },
+  {
+    id: 'input',
+    name: 'RepoNormalizedUniversalAgentSessionEvent',
+    construct: 'interface',
+    file: 'types/RepoNormalizedUniversalAgentSessionEvent.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'the subsystem\u2019s input type — a repo-normalized universal event the readers produce and the accumulator consumes',
+    symbol: 'RepoNormalizedUniversalAgentSessionEvent',
+    detail: {
+      kind: 'type',
+      properties: [
+        { name: 'eventType', type: 'NormalizedEventType' },
+        { name: 'sessionId', type: 'string' },
+        { name: 'timestamp', type: 'number' },
+      ],
+      usedBy: [{ nodeId: 'acc', name: 'accumulateToAgentSessionEvents', context: 'parameter_type' }],
+      implementors: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'acc',
+    name: 'accumulateToAgentSessionEvents',
+    construct: 'function',
+    file: 'src/event-processing/accumulator.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'accumulates normalized events into agent session events',
+    symbol: 'accumulateToAgentSessionEvents',
+  },
+  {
+    id: 'out',
+    name: 'AgentSessionEvent',
+    construct: 'interface',
+    file: 'src/event-processing/accumulator.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'the subsystem\u2019s output type — an accumulated agent-session event',
+    symbol: 'AgentSessionEvent',
+    detail: {
+      kind: 'type',
+      properties: [
+        { name: 'sessionName', type: 'string' },
+        { name: 'operation', type: 'AgentSessionEventOperation' },
+        { name: 'description', type: 'string' },
+      ],
+      usedBy: [{ nodeId: 'acc', name: 'accumulateToAgentSessionEvents', context: 'return_type' }],
+      implementors: [],
+    } satisfies GraphifyComponentDetail,
+  },
+];
+
+export const investigateOnlyEdges: SubsystemComponentEdge[] = edges([
+  // Concept-level data flow — the LLM's semantic intent.
+  ['v1', 'input', 'produces'],
+  ['v2', 'input', 'produces'],
+  ['input', 'acc', 'feeds'],
+  ['acc', 'out', 'produces'],
+]);

package/src/subsystem/ComponentDeclaration.tsx

@@ -1,6 +1,6 @@
 /**
  * ComponentDeclaration — the selected subsystem component rendered as it would
- * appear in code: a file-path comment + doc comment, then the kind's
+ * appear in code: a file-path comment + doc comment, then the construct's
  * declaration (`class X extends Y { ... }`, `function f(): T`, ...) with its
  * members as signatures. Graphify relationship drill-downs appear as trailing
  * comments. File content lives in the bottom FileDrawer, not here.
@@ -9,8 +9,8 @@
 import { useEffect, useRef, useState, type ReactNode } from 'react';
 import { AlignLeft, FileText, ShieldCheck } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
+import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
 import {
-  KIND_COLOR,
   formatPurl,
   type SubsystemComponent,
   type SubsystemDeclTokenKind,
@@ -18,6 +18,7 @@ import {
 import type { SubsystemOpenFileOptions } from './declarationRef';
 import { parseSourceLocation } from './declarationRef';
 import { tokenizeComponent } from './tokenizeComponent';
+import { constructColorsFromPierreTheme } from '../pierre/constructColors';
 
 /** Live / result state for the declaration-panel Verify control. */
 export type ComponentVerificationPhase =
@@ -48,7 +49,7 @@ export interface ComponentVerificationState {
     source_location?: string;
     candidates?: Array<{ nodeId: string; label: string; source_file?: string }>;
   };
-  kind?: {
+  construct?: {
     claimed: string;
     inferred: string;
     match: boolean;
@@ -162,11 +163,11 @@ function verificationSummary(
         ? ` · declaration ${declFresh}${v.declaration?.ref ? ` L${v.declaration.ref.startLine}` : ''}`
         : '';
     const anchorBit = `exact → ${v.anchor?.label ?? v.anchor?.nodeId ?? 'node'}${loc}${declBit}`;
-    if (v.kind && !v.kind.match) {
+    if (v.construct && !v.construct.match) {
       const why =
-        v.kind.inferred === 'unknown'
-          ? `kind unknown (claimed ${v.kind.claimed})`
-          : `kind mismatch: claimed ${v.kind.claimed}, inferred ${v.kind.inferred}`;
+        v.construct.inferred === 'unknown'
+          ? `construct unknown (claimed ${v.construct.claimed})`
+          : `construct mismatch: claimed ${v.construct.claimed}, inferred ${v.construct.inferred}`;
       return {
         text: [...bits, anchorBit, why].join(' · '),
         color: '#e5534b',
@@ -181,7 +182,7 @@ function verificationSummary(
         text: [
           ...bits,
           anchorBit,
-          v.kind?.match ? `kind ${v.kind.inferred}` : undefined,
+          v.construct?.match ? `construct ${v.construct.inferred}` : undefined,
           `signature mismatch: params [${cParams}]≠[${iParams}] return [${cRet}]≠[${iRet}]`,
         ]
           .filter(Boolean)
@@ -189,8 +190,8 @@ function verificationSummary(
         color: '#e5534b',
       };
     }
-    const kindBit =
-      v.kind?.match ? `kind ${v.kind.inferred}` : undefined;
+    const constructBit =
+      v.construct?.match ? `construct ${v.construct.inferred}` : undefined;
     const inlineBit =
       v.signature?.inlineParameters
         ? `${v.signature.inlineParameters} inline param${v.signature.inlineParameters === 1 ? '' : 's'} verified`
@@ -209,7 +210,7 @@ function verificationSummary(
         text: [
           ...bits,
           anchorBit,
-          ...(kindBit ? [kindBit] : []),
+          ...(constructBit ? [constructBit] : []),
           ...(inlineBit ? [inlineBit] : []),
           v.signature.skipCode
             ? `params/return not fully checked — ${skipPhrase[v.signature.skipCode] ?? v.signature.skipCode}`
@@ -221,7 +222,7 @@ function verificationSummary(
     const sigBit =
       v.signature && v.signature.match ? 'params/return ok' : undefined;
     return {
-      text: [...bits, anchorBit, ...(kindBit ? [kindBit] : []), ...(sigBit ? [sigBit] : [])].join(' · '),
+      text: [...bits, anchorBit, ...(constructBit ? [constructBit] : []), ...(sigBit ? [sigBit] : [])].join(' · '),
       color: ok,
     };
   }
@@ -256,12 +257,13 @@ export function ComponentDeclaration({
   onVerify,
   verification,
 }: ComponentDeclarationProps) {
-  const { theme } = useTheme();
+  const { theme, mode } = useTheme();
+  const pierreSyntaxTheme = resolvePierreSyntaxThemeName(mode);
   const [fileHovered, setFileHovered] = useState(false);
   const [showFile, setShowFile] = useState(false);
   const [showPurpose, setShowPurpose] = useState(false);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
-  const color = KIND_COLOR[component.kind] ?? '#888';
+  const color = constructColorsFromPierreTheme(pierreSyntaxTheme)[component.construct];
   const okColor = '#3d9a5f';
   const warnColor = theme.colors.textSecondary;
 
@@ -274,6 +276,8 @@ export function ComponentDeclaration({
     string: theme.colors.success,
     newline: '',
   };
+  /** Fallback when wire tokens omit Shiki colors. */
+  const declarationTextColor = muted;
 
   const declarationStartLine =
     component.declarationRef?.startLine ??
@@ -305,10 +309,26 @@ export function ComponentDeclaration({
       </DetailLink>
     ) : null;
 
-  const line = (children: ReactNode, key?: string, indent?: boolean | number) => {
+  const line = (
+    children: ReactNode,
+    key?: string,
+    indent?: boolean | number,
+    wrap: 'pre' | 'pre-wrap' | 'normal' = 'pre-wrap',
+  ) => {
     const paddingLeft = typeof indent === 'number' ? indent : indent ? 16 : 0;
     return (
-      <div key={key} style={{ display: 'flex', alignItems: 'center', whiteSpace: 'pre', minHeight: 18, ...(paddingLeft ? { paddingLeft } : {}) }}>
+      <div
+        key={key}
+        style={{
+          display: 'flex',
+          alignItems: wrap === 'normal' ? 'flex-start' : 'center',
+          whiteSpace: wrap,
+          overflowWrap: 'anywhere',
+          minWidth: 0,
+          minHeight: 18,
+          ...(paddingLeft ? { paddingLeft } : {}),
+        }}
+      >
         {children}
       </div>
     );
@@ -327,7 +347,8 @@ export function ComponentDeclaration({
     fontFamily: theme.fonts.body,
     fontSize: theme.fontSizes[1],
     lineHeight: 1.5,
-    maxWidth: '52ch',
+    minWidth: 0,
+    flex: 1,
   } as const;
 
   const lines: ReactNode[] = [];
@@ -540,13 +561,13 @@ export function ComponentDeclaration({
       return;
     }
     let cancelled = false;
-    tokenizeComponent(component, printWidth).then((t) => {
+    tokenizeComponent(component, printWidth, pierreSyntaxTheme).then((t) => {
       if (!cancelled) setTokens(t);
     });
     return () => {
       cancelled = true;
     };
-  }, [component, printWidth]);
+  }, [component, printWidth, pierreSyntaxTheme]);
   const declLines: ReactNode[][] = [[]];
   let di = 0;
   for (const tok of tokens) {
@@ -556,7 +577,10 @@ export function ComponentDeclaration({
       continue;
     }
     declLines[di].push(
-      <span key={`${di}-${declLines[di].length}`} style={{ color: tokenColor[tok.kind] }}>
+      <span
+        key={`${di}-${declLines[di].length}`}
+        style={{ color: tok.color ?? tokenColor[tok.kind] ?? declarationTextColor }}
+      >
         {tok.text}
       </span>,
     );
@@ -564,21 +588,33 @@ export function ComponentDeclaration({
   for (let li = 0; li < declLines.length; li++) {
     if (declLines[li].length === 0) continue;
     lines.push(
-      <div key={`decl-${li}`} style={{ display: 'flex', alignItems: 'center', whiteSpace: 'pre', minHeight: 18 }}>
+      <div
+        key={`decl-${li}`}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          whiteSpace: 'pre-wrap',
+          overflowWrap: 'anywhere',
+          minWidth: 0,
+          minHeight: 18,
+        }}
+      >
         {declLines[li]}
       </div>,
     );
   }
 
   if (showPurpose && component.purpose) {
-    lines.push(line(<div style={{ height: 6 }} />, 'purpose-gap'));
+    lines.push(line(<div style={{ height: 6 }} />, 'purpose-gap', false, 'normal'));
     component.purpose.split('\n').forEach((purposeLine, i) =>
       lines.push(
         line(
-          <span style={{ ...purposeStyle, display: 'block' }} key={`purpose${i}`}>
+          <span style={purposeStyle} key={`purpose${i}`}>
             {purposeLine.trim()}
           </span>,
           `purpose${i}`,
+          false,
+          'normal',
         ),
       ),
     );
@@ -588,14 +624,16 @@ export function ComponentDeclaration({
     <div
       ref={containerRef}
       style={{
+        width: '100%',
+        minWidth: 0,
+        boxSizing: 'border-box',
         background: theme.colors.backgroundSecondary,
         padding: '10px 12px',
         fontFamily: theme.fonts.monospace,
         fontSize: theme.fontSizes[1],
         lineHeight: 1.7,
-        ...(maxWidth != null
-          ? { maxWidth, wordBreak: 'break-word' }
-          : { overflowX: 'auto' }),
+        overflowWrap: 'anywhere',
+        ...(maxWidth != null ? { maxWidth } : {}),
       }}
     >
       {lines}

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -181,11 +181,19 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     measuredDimsRef.current = new Map();
     prevMeasuredSigRef.current = '';
     const doc = { components: componentsRef.current, edges: edgesRef.current };
-    void buildSubsystemGraph(doc, { maxNodeWidth, showEdgeLabels }).then(({ nodes, edges: e }) => {
-      if (!alive) return;
-      setBuilt({ nodes, edges: e as Edge[] });
-      setLayoutReady(false);
-    });
+    void buildSubsystemGraph(doc, { maxNodeWidth, showEdgeLabels })
+      .then(({ nodes, edges: e }) => {
+        if (!alive) return;
+        setBuilt({ nodes, edges: e as Edge[] });
+        setLayoutReady(false);
+      })
+      .catch((err) => {
+        console.warn('[subsystem-graph] initial layout failed:', err);
+        if (!alive) return;
+        // Reveal the cover even on failure so the UI is not stuck forever.
+        setBuilt({ nodes: [], edges: [] });
+        setLayoutReady(true);
+      });
     return () => { alive = false; };
   }, [layoutKey, maxNodeWidth, showEdgeLabels]);
 
@@ -426,6 +434,18 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     [onFileSelect],
   );
 
+  // Filename-badge clicks on nodes open the drawer through the same path as
+  // the declaration panel's file link (toggle + tree sync, no start line).
+  useEffect(() => {
+    SUBSYSTEM_CALLBACKS.onOpenFile = (componentId: string) => {
+      const comp = components.find((c) => c.id === componentId);
+      if (comp?.file) onOpenDeclarationFile(comp.file);
+    };
+    return () => {
+      SUBSYSTEM_CALLBACKS.onOpenFile = undefined;
+    };
+  }, [components, onOpenDeclarationFile]);
+
   // Detail-panel links: related-name clicks select the matching component —
   // resolved by id, name, or symbol (call labels may carry a trailing `()`).
   const resolveRelatedComponent = useCallback(
@@ -734,7 +754,7 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
               top: 10,
               right: 10,
               zIndex: 8,
-              maxWidth: 'min(560px, 70%)',
+              width: 'min(560px, 70%)',
               maxHeight: '46%',
               overflowY: 'auto',
               background: theme.colors.background,

package/src/subsystem/formatDeclaration.ts

@@ -7,32 +7,46 @@
  * handles all formatting.
  */
 
-import type { SubsystemComponent } from './model';
+import type { SubsystemComponent, SubsystemComponentConstruct } from './model';
 import type { GraphifyComponentDetail } from '../graphify';
 
+const TYPE_FAMILY_CONSTRUCTS: ReadonlySet<string> = new Set([
+  'interface',
+  'type_alias',
+  'enum',
+]);
+
 export function generateDeclarationString(component: SubsystemComponent): string {
   const detail = component.detail;
-  const kind = detail?.kind ?? component.kind;
+  // Type-family constructs own their rendering even when the detail payload
+  // is the shared `type` shape — the construct says which keyword is honest.
+  const construct = TYPE_FAMILY_CONSTRUCTS.has(component.construct)
+    ? component.construct
+    : detail?.kind ?? component.construct;
   const rawName = component.symbol || component.name || 'untitled';
   // Strip class/object prefix from dotted symbols (e.g. "SessionReader.normalize" → "normalize").
   const name = rawName.includes('.') ? rawName.split('.').pop()! : rawName;
 
-  switch (kind) {
+  switch (construct) {
     case 'class':
       return generateClass(name, detail);
     case 'function':
       return generateFunction(name, detail);
     case 'method':
       return generateMethod(name, detail);
-    case 'type':
-      return generateType(name, detail);
+    case 'interface':
+    case 'type_alias':
+    case 'enum':
+      return generateType(name, component.construct, detail);
     case 'module':
       return generateModule(detail);
+    case 'store':
+      return generateStore(name, detail);
     case 'external':
       // Not valid TypeScript — caller should handle formatting.
       return `external '${detail?.kind === 'external' ? detail.label : name}'`;
     default:
-      return `${kind} ${name}`;
+      return `${construct} ${name}`;
   }
 }
 
@@ -48,7 +62,7 @@ function formatParams(params: { name?: string; type: string }[]): string {
 }
 
 // ---------------------------------------------------------------------------
-// Per-kind generators
+// Per-construct generators
 // ---------------------------------------------------------------------------
 
 function generateClass(name: string, detail?: GraphifyComponentDetail): string {
@@ -98,16 +112,31 @@ function generateMethod(name: string, detail?: GraphifyComponentDetail): string
   return `class ${hostClass} {\n  ${name}(${params})${ret};\n}`;
 }
 
-function generateType(name: string, detail?: GraphifyComponentDetail): string {
+function generateType(
+  name: string,
+  construct: SubsystemComponentConstruct,
+  detail?: GraphifyComponentDetail,
+): string {
+  // The type-family constructs render their declaration keyword honestly —
+  // the construct itself says interface / type (alias) / enum / variable.
   const tpe = detail?.kind === 'type' ? detail : undefined;
   const props = (tpe?.properties ?? [])
     .map((p) => `  ${p.name}${p.type ? `: ${p.type}` : ''};`)
     .join('\n');
 
-  if (props) {
-    return `interface ${name} {\n${props}\n}`;
+  switch (construct) {
+    case 'enum':
+      return `enum ${name} { ${(tpe?.properties ?? []).map((p) => p.name).join(', ')} }`;
+    case 'type_alias':
+      return props
+        ? `type ${name} = {\n${props}\n};`
+        : `type ${name} = unknown;`;
+    default:
+      if (props) {
+        return `interface ${name} {\n${props}\n}`;
+      }
+      return `interface ${name} {}`;
   }
-  return `interface ${name} {}`;
 }
 
 function generateModule(detail?: GraphifyComponentDetail): string {
@@ -126,3 +155,20 @@ function generateModule(detail?: GraphifyComponentDetail): string {
 
   return parts.join('\n') || `module {}`;
 }
+
+/**
+ * A store renders as its retained state — ambient `declare const` lines for
+ * the state members, never a class/method stub. The node's name labels the
+ * block; the access mechanism lives in separate accessor nodes.
+ */
+function generateStore(name: string, detail?: GraphifyComponentDetail): string {
+  const store = detail?.kind === 'store' ? detail : undefined;
+  const props = (store?.properties ?? [])
+    .map((p) => `declare const ${p.name}${p.type ? `: ${p.type}` : ''};`)
+    .join('\n');
+
+  if (!props) {
+    return `// store: ${name} — no captured state members`;
+  }
+  return `// store: ${name}\n${props}`;
+}

package/src/subsystem/model.test.ts

@@ -36,11 +36,30 @@ describe('subsystem graph model', () => {
     expect(converted[0].target).toBe('reader');
   });
 
+  test('buildSubsystemGraph tolerates external components with no file', async () => {
+    const withExternal: SubsystemComponent[] = [
+      ...comps,
+      {
+        id: "proposed-watcher",
+        name: "watchDir",
+        kind: "external",
+        // Intentionally omit file/purl — agents often leave these off for externals.
+        file: undefined as unknown as string,
+        purl: undefined as unknown as string,
+      },
+    ];
+    const { nodes } = await buildSubsystemGraph({
+      components: withExternal,
+      edges: [{ id: 'e3', from: 'reader', to: 'proposed-watcher', mechanism: 'feeds' }],
+    });
+    expect(nodes.find((n) => n.id === 'proposed-watcher')).toBeDefined();
+  });
+
   test('buildSubsystemGraph creates external stub nodes for non-component targets', async () => {
     const { nodes, edges: gEdges } = await buildSubsystemGraph({ components: comps, edges });
     const external = nodes.find((n) => n.id === 'external:host');
     expect(external).toBeDefined();
-    expect(external!.data.component.kind).toBe('external');
+    expect(external!.data.component.construct).toBe('external');
     const crossEdge = gEdges.find((e) => e.target === 'external:host');
     expect(crossEdge).toBeDefined();
   });
@@ -62,14 +81,27 @@ describe('subsystem graph model', () => {
   });
 
   test('deriveNameFromSymbol is consistent per kind', () => {
-    // class/type/module/function use the symbol as-is.
-    expect(deriveNameFromSymbol('SessionReader', 'class')).toBe('SessionReader');
-    expect(deriveNameFromSymbol('SessionRecord', 'type')).toBe('SessionRecord');
-    // falls back to existing name when no symbol.
-    expect(deriveNameFromSymbol(undefined, 'class', 'SessionReader')).toBe('SessionReader');
+    // brace-bodied constructs wear {}; module uses the symbol as-is.
+    expect(deriveNameFromSymbol('SessionReader', 'class')).toBe('SessionReader {}');
+    expect(deriveNameFromSymbol('SessionRecord', 'type_alias')).toBe('SessionRecord {}');
+    expect(deriveNameFromSymbol('transcript', 'module')).toBe('transcript');
+    // falls back to existing name when no symbol (still brace-decorated).
+    expect(deriveNameFromSymbol(undefined, 'class', 'SessionReader')).toBe('SessionReader {}');
     expect(deriveNameFromSymbol('', 'external', 'trail-viewer-host')).toBe('trail-viewer-host');
   });
 
+  test('executable constructs wear () on the node', () => {
+    expect(deriveNameFromSymbol('createSubsystemGraph', 'function')).toBe('createSubsystemGraph()');
+    // methods keep the dotted ownership symbol and wear the parens
+    expect(deriveNameFromSymbol('SessionCache.put', 'method')).toBe('SessionCache.put()');
+    // already-parenthesized labels don't double up
+    expect(deriveNameFromSymbol('run()', 'function')).toBe('run()');
+    // data-shaped constructs stay bare
+    expect(deriveNameFromSymbol('ROOT', 'store')).toBe('ROOT');
+    // brace bodies don't double up
+    expect(deriveNameFromSymbol('Foo {}', 'class')).toBe('Foo {}');
+  });
+
   test('deriveNameFromSymbol falls back to file basename for modules', () => {
     expect(deriveNameFromSymbol(undefined, 'module', undefined, 'transcript.ts')).toBe('transcript');
     expect(deriveNameFromSymbol(undefined, 'module', undefined, 'src/event-processors/index.ts')).toBe('index');