@principal-ai/subsystems-react 0.25.0 → 0.25.1

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

@@ -149,7 +149,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: type_alias — a type alias',
     note: 'the `type` keyword form: `type X = { … }` or a union — anything `=`-assigned',
     component: {
-      id: 'alias-status',
+      alias: 'alias-status',
       name: 'AnalysisStatus',
       construct: 'type_alias',
       file: 'packages/subsystems-studio/src/bun/analysis.ts',
@@ -170,7 +170,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'role: entry on construct: type — contract as entry',
     note: 'same role, different inherited anatomy — entries are topology, not shape',
     component: {
-        id: 'ipc-entry',
+        alias: 'ipc-entry',
       name: 'StudioMessages',
       construct: 'interface',
       file: 'packages/subsystems-studio/src/shared/contract.ts',
@@ -183,7 +183,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: enum — runtime values + a type',
     note: 'the one type-family form that exists at runtime; members render in the drill-down',
     component: {
-      id: 'enum-phase',
+      alias: 'enum-phase',
       name: 'VerificationPhase',
       construct: 'enum',
       file: 'packages/subsystems-studio/src/bun/verify.ts',
@@ -201,7 +201,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: function — plain accessor',
     note: 'indigo; the default for anchored behavior',
     component: {
-      id: 'create',
+      alias: 'create',
       name: 'createSubsystemModel',
       construct: 'function',
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
@@ -213,7 +213,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'framework: react · stereotype: component — still construct: function',
     note: 'badge reads "react · component"; name renders bare ; color stays function',
     component: {
-      id: 'analysis-view',
+      alias: 'analysis-view',
       name: 'AnalysisView',
       construct: 'function',
       file: 'packages/subsystems-studio/src/mainview/views/AnalysisView.tsx',
@@ -228,7 +228,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'framework: react · stereotype: hook',
     note: 'same construct, different stereotype — badge "react · hook", keeps ()',
     component: {
-      id: 'drawings-host',
+      alias: 'drawings-host',
       name: 'useDrawingsHost',
       construct: 'function',
       file: 'packages/subsystems-studio/src/mainview/hooks/useDrawingsHost.ts',
@@ -242,7 +242,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'role: entry on construct: function — boundary element',
     note: 'orange overrides construct:color; anatomy inherited from the function',
     component: {
-      id: 'http-entry',
+      alias: 'http-entry',
       name: 'HTTP bridge :3045',
       construct: 'function',
       file: 'packages/subsystems-studio/src/bun/http-server.ts',
@@ -255,7 +255,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: class — declaration anatomy',
     note: 'blue; drill-down renders the real class stub with its methods',
     component: {
-      id: 'cache',
+      alias: 'cache',
       name: 'SessionCache',
       construct: 'class',
       file: 'src/session/SessionCache.ts',
@@ -276,7 +276,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: method — a function bound to its class',
     note: 'dotted symbol (SessionCache.put) is the identity; drill-down renders it inside a host-class stub',
     component: {
-      id: 'method-put',
+      alias: 'method-put',
       name: 'put',
       construct: 'method',
       file: 'src/session/SessionCache.ts',
@@ -293,7 +293,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: store — state-block anatomy',
     note: 'green = the store construct:color; drill-down renders declare const state, never a class stub',
     component: {
-      id: 'store',
+      alias: 'store',
       name: 'Graph Store',
       construct: 'store',
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
@@ -306,7 +306,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'construct: external — actor outside every boundary',
     note: 'purple; no process → drawn outside all regions',
     component: {
-      id: 'agents',
+      alias: 'agents',
       name: 'agent clients',
       construct: 'external',
       file: '',
@@ -317,7 +317,7 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
     label: 'role: service on construct: external — far-side boundary element',
     note: 'colored by its construct (external); identity via purl, no source at all',
     component: {
-      id: 'github',
+      alias: 'github',
       name: 'api.github.com',
       construct: 'external',
       file: '',
@@ -332,7 +332,7 @@ function NodeSpotlightsDemo() {
   const { mode } = useTheme();
   const constructColors = constructColorsFromPierreTheme(resolvePierreSyntaxThemeName(mode));
   const [activeIds, setActiveIds] = useState<Set<string>>(
-    () => new Set(nodeSpotlights.map((n) => n.component.id)),
+    () => new Set(nodeSpotlights.map((n) => n.component.alias)),
   );
   const toggle = (id: string) =>
     setActiveIds((prev) => {
@@ -344,7 +344,7 @@ function NodeSpotlightsDemo() {
       }
       return next;
     });
-  const visible = nodeSpotlights.filter((n) => activeIds.has(n.component.id));
+  const visible = nodeSpotlights.filter((n) => activeIds.has(n.component.alias));
 
   return (
     <div style={{ padding: 20, overflow: 'auto', height: '100vh', boxSizing: 'border-box', background: '#0f1216' }}>
@@ -358,7 +358,7 @@ function NodeSpotlightsDemo() {
           show:
         </span>
         {nodeSpotlights.map(({ component }) => {
-          const on = activeIds.has(component.id);
+          const on = activeIds.has(component.alias);
           const color = constructColors[component.construct];
           const chip = component.stereotype
             ? component.framework
@@ -369,9 +369,9 @@ function NodeSpotlightsDemo() {
               : component.construct;
           return (
             <button
-              key={component.id}
+              key={component.alias}
               type="button"
-              onClick={() => toggle(component.id)}
+              onClick={() => toggle(component.alias)}
               style={{
                 fontFamily: 'monospace',
                 fontSize: 11,
@@ -390,7 +390,7 @@ function NodeSpotlightsDemo() {
         })}
         <button
           type="button"
-          onClick={() => setActiveIds(new Set(nodeSpotlights.map((n) => n.component.id)))}
+          onClick={() => setActiveIds(new Set(nodeSpotlights.map((n) => n.component.alias)))}
           style={{ fontFamily: 'monospace', fontSize: 11, cursor: 'pointer', padding: '4px 10px', borderRadius: 999, border: '1px solid #2c313a', background: 'transparent', color: '#9ca3af' }}
         >
           all
@@ -410,7 +410,7 @@ function NodeSpotlightsDemo() {
         </div>
       )}
       {visible.map(({ label, component, note }) => (
-        <div key={component.id}>
+        <div key={component.alias}>
           <div style={{ fontFamily: 'monospace', fontSize: 11, color: '#6b7280', margin: '10px 2px 6px' }}>
             {label} — {note}
           </div>
@@ -490,7 +490,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'store detail → state block',
     note: 'declare const lines — honest to module-level state; no class stub, no methods',
     component: {
-      id: 'store',
+      alias: 'store',
       name: 'Graph Store',
       construct: 'store',
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
@@ -510,7 +510,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'class detail → class stub',
     note: 'the verifiable access mechanism — methods with typed params + returns',
     component: {
-      id: 'cache',
+      alias: 'cache',
       name: 'SessionCache',
       construct: 'class',
       file: 'src/session/SessionCache.ts',
@@ -534,7 +534,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'function detail → signature',
     note: 'params + return type, callers/callees intentionally not rendered (edges carry them)',
     component: {
-      id: 'get',
+      alias: 'get',
       name: 'getSubsystemModel',
       construct: 'function',
       file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
@@ -553,7 +553,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'type detail → interface fields',
     note: 'the IPC contract as an entry: anatomy inherited from the type',
     component: {
-        id: 'ipc-entry',
+        alias: 'ipc-entry',
       name: 'StudioMessages',
       construct: 'interface',
       file: 'packages/subsystems-studio/src/shared/contract.ts',
@@ -575,7 +575,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'method detail → method in host-class stub',
     note: 'the class is context, the method is the node — same anatomy a standalone function gets, plus the owning class',
     component: {
-      id: 'anatomy-method',
+      alias: 'anatomy-method',
       name: 'put',
       construct: 'method',
       file: 'src/session/SessionCache.ts',
@@ -593,7 +593,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'type_alias detail → braced alias',
     note: 'the alias renders as `type X = { … }` — the honest keyword form',
     component: {
-      id: 'anatomy-alias',
+      alias: 'anatomy-alias',
       name: 'AnalysisStatus',
       construct: 'type_alias',
       file: 'packages/subsystems-studio/src/bun/analysis.ts',
@@ -611,7 +611,7 @@ const anatomyComponents: Array<{ label: string; component: SubsystemComponent; n
     label: 'enum detail → enum declaration',
     note: 'members render inline — the runtime type',
     component: {
-      id: 'anatomy-enum',
+      alias: 'anatomy-enum',
       name: 'VerificationPhase',
       construct: 'enum',
       file: 'packages/subsystems-studio/src/bun/verify.ts',
@@ -634,7 +634,7 @@ function AnatomySpotlightsDemo() {
         anatomy spotlights — data (left) → the drill-down panel you get on click (right).
       </div>
       {anatomyComponents.map(({ label, component, note }) => (
-        <div key={component.id}>
+        <div key={component.alias}>
           <div style={{ fontFamily: 'monospace', fontSize: 11, color: '#6b7280', margin: '10px 2px 6px' }}>
             {label} — {note}
           </div>

package/src/subsystem/model.test.ts

@@ -626,6 +626,52 @@ describe('subsystem graph model', () => {
     expect(groups.filter((g) => g.region.kind === 'package')).toHaveLength(1);
   });
 
+  test('mixed-process module members live only in the module frame', () => {
+    // Same file framed under two processes (composed-model vocabulary drift):
+    // the module cannot nest, so its members must not also sit directly in
+    // the process frames — ELK throws on double-parented leaves.
+    const groups = buildBoundaryLayoutGroups({
+      components: [
+        { alias: 'a1', name: 'a1', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', module: 'src/a.ts', process: 'app/host' },
+        { alias: 'a2', name: 'a2', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', module: 'src/a.ts', process: 'app/renderer' },
+        { alias: 'b1', name: 'b1', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+      ],
+    });
+    const leafHits = new Map<string, string[]>();
+    for (const g of groups) {
+      for (const id of g.memberAliases) {
+        // Nested group ids legitimately appear in parents; only leaves count.
+        if (groups.some((h) => h.id === id)) continue;
+        leafHits.set(id, [...(leafHits.get(id) ?? []), g.id]);
+      }
+    }
+    for (const [leaf, owners] of leafHits) {
+      expect(`${leaf} in ${owners.length} groups: ${owners.join(',')}`).toBe(`${leaf} in 1 groups: ${owners[0]}`);
+    }
+    const mod = groups.find((g) => g.region.kind === 'module');
+    expect(mod?.memberAliases).toEqual(['a1', 'a2']);
+  });
+
+  test('module-less leaf in a mixed-package process lives only in the process frame', () => {
+    const groups = buildBoundaryLayoutGroups({
+      components: [
+        { alias: 'x', name: 'x', construct: 'function', file: 'x.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'y', name: 'y', construct: 'function', file: 'y.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'z', name: 'z', construct: 'function', file: 'z.ts', purl: 'pkg:github/other/lib', process: 'app/host' },
+      ],
+    });
+    const leafHits = new Map<string, string[]>();
+    for (const g of groups) {
+      for (const id of g.memberAliases) {
+        if (groups.some((h) => h.id === id)) continue;
+        leafHits.set(id, [...(leafHits.get(id) ?? []), g.id]);
+      }
+    }
+    for (const [leaf, owners] of leafHits) {
+      expect(owners).toHaveLength(1);
+    }
+  });
+
   test('subsystemGraphLayoutKey ignores declarationRef-only changes', () => {
     const base = doc;
     const withRef = {

package/src/subsystem/model.ts

@@ -717,6 +717,30 @@ export function buildBoundaryLayoutGroups(
   );
   const keptProcessKeys = new Set(processes.map((r) => r.key));
 
+  // Leaves owned by a multi-member module belong to that module's frame
+  // exclusively. Multi-member modules are always built by ELK (never skipped
+  // as singletons), so letting a process/package group also list them
+  // directly would parent the same leaf twice and ELK throws
+  // ("value already present"). Mixed-process modules (common in composed
+  // graphs, where models frame one file under different processes) never
+  // nest — without this claim they land in both frames.
+  const claimedByModule = new Set<string>();
+  for (const r of modules) {
+    if (r.memberAliases.length >= 2) {
+      for (const alias of r.memberAliases) claimedByModule.add(alias);
+    }
+  }
+  // Same rule one level up: a leaf owned by a multi-member process frame
+  // must not also sit directly in a package frame. (Singleton processes
+  // never claim — ELK skips them and promotes the member upward, so the
+  // member has to stay reachable through its package or ungrouped.)
+  const claimedByProcess = new Set<string>();
+  for (const r of processes) {
+    if (r.memberAliases.length >= 2) {
+      for (const alias of r.memberAliases) claimedByProcess.add(alias);
+    }
+  }
+
   const moduleGroups: BoundaryLayoutGroup[] = modules.map((r) => {
     const processesOfMembers = new Set<string>();
     const packagesOfMembers = new Set<string>();
@@ -749,6 +773,7 @@ export function buildBoundaryLayoutGroups(
     const nestedModules = moduleGroups.filter((m) => m.parentId === processId);
     const nestedModuleKeys = new Set(nestedModules.map((m) => m.region.key));
     const directLeaves = r.memberAliases.filter((alias) => {
+      if (claimedByModule.has(alias)) return false;
       const mod = byAlias.get(alias)?.module?.trim();
       if (!mod) return true;
       return !nestedModuleKeys.has(mod);
@@ -785,7 +810,12 @@ export function buildBoundaryLayoutGroups(
     for (const m of nestedModules) {
       for (const alias of m.region.memberAliases) claimed.add(alias);
     }
-    const directLeaves = r.memberAliases.filter((alias) => !claimed.has(alias));
+    const directLeaves = r.memberAliases.filter(
+      (alias) =>
+        !claimed.has(alias) &&
+        !claimedByModule.has(alias) &&
+        !claimedByProcess.has(alias),
+    );
     return {
       id: packageId,
       memberAliases: [