@principal-ai/subsystems-react 0.24.27 → 0.25.0

package/src/subsystem/model.test.ts

@@ -32,8 +32,8 @@ import {
 import type { SubsystemComponent, SubsystemComponentEdge } from './model';
 
 const comps: SubsystemComponent[] = [
-  { id: 'reader', name: 'SessionReader', construct: 'class', file: 'SessionReader.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
-  { id: 'transcript', name: 'transcript', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
+  { alias: 'reader', name: 'SessionReader', construct: 'class', file: 'SessionReader.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
+  { alias: 'transcript', name: 'transcript', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
 ];
 
 const relations = [
@@ -63,7 +63,7 @@ describe('subsystem graph model', () => {
     const withExternal: SubsystemComponent[] = [
       ...comps,
       {
-        id: "proposed-watcher",
+        alias: "proposed-watcher",
         name: "watchDir",
         construct: "external",
         // Intentionally omit file/purl — agents often leave these off for externals.
@@ -240,24 +240,24 @@ describe('subsystem graph model', () => {
   test('getSubsystemRegions groups by process, skipping process-less nodes', () => {
     const regions = getSubsystemRegions({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/acme/app', process: 'app/renderer' },
-        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/acme/app', process: 'app/renderer' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
       ],
     });
     expect(regions.map((r) => r.key)).toEqual(['app/host', 'app/renderer']);
     expect(regions.every((r) => r.kind === 'process')).toBe(true);
-    expect(regions[0]!.memberIds).toEqual(['a', 'b']);
+    expect(regions[0]!.memberAliases).toEqual(['a', 'b']);
   });
 
   test('getSubsystemModuleRegions groups by module, skipping module-less nodes', () => {
     const regions = getSubsystemModuleRegions({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
-        { id: 'b', name: 'b', construct: 'type_alias', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
-        { id: 'c', name: 'c', construct: 'function', file: 'paths.ts', purl: 'pkg:github/acme/app', module: 'src/session/paths.ts' },
-        { id: 'd', name: 'd', construct: 'function', file: 'other.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
+        { alias: 'b', name: 'b', construct: 'type_alias', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
+        { alias: 'c', name: 'c', construct: 'function', file: 'paths.ts', purl: 'pkg:github/acme/app', module: 'src/session/paths.ts' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'other.ts', purl: 'pkg:github/acme/app' },
       ],
     });
     expect(regions.map((r) => r.key)).toEqual([
@@ -265,14 +265,14 @@ describe('subsystem graph model', () => {
       'src/session/paths.ts',
     ]);
     expect(regions.every((r) => r.kind === 'module')).toBe(true);
-    expect(regions[0]!.memberIds).toEqual(['a', 'b']);
+    expect(regions[0]!.memberAliases).toEqual(['a', 'b']);
   });
 
   test('convertSubsystemToNodes prefers module parentId over process', () => {
     const nodes = convertSubsystemToNodes({
       components: [
         {
-          id: 'a',
+          alias: 'a',
           name: 'a',
           construct: 'function',
           file: 'a.ts',
@@ -280,7 +280,7 @@ describe('subsystem graph model', () => {
           process: 'app/host',
           module: 'src/a.ts',
         },
-        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
       ],
       relations: [],
     });
@@ -293,8 +293,8 @@ describe('subsystem graph model', () => {
   test('convertSubsystemToNodes stamps parentId for process members only', () => {
     const nodes = convertSubsystemToNodes({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
       ],
       relations: [],
     });
@@ -307,8 +307,8 @@ describe('subsystem graph model', () => {
   test('convertSubsystemToGroups emits one parent per process', () => {
     const groups = convertSubsystemToGroups({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
       ],
     });
     expect(groups).toHaveLength(1);
@@ -320,7 +320,7 @@ describe('subsystem graph model', () => {
     const groups = convertSubsystemToGroups({
       components: [
         {
-          id: 'a',
+          alias: 'a',
           name: 'a',
           construct: 'function',
           file: 'a.ts',
@@ -329,7 +329,7 @@ describe('subsystem graph model', () => {
           module: 'src/a.ts',
         },
         {
-          id: 'b',
+          alias: 'b',
           name: 'b',
           construct: 'function',
           file: 'a.ts',
@@ -352,7 +352,7 @@ describe('subsystem graph model', () => {
     const { nodes, regions } = await buildSubsystemGraph({
       components: [
         {
-          id: 'boot',
+          alias: 'boot',
           name: 'boot',
           construct: 'function',
           file: 'main.ts',
@@ -362,7 +362,7 @@ describe('subsystem graph model', () => {
           symbol: 'boot',
         },
         {
-          id: 'create',
+          alias: 'create',
           name: 'createHost',
           construct: 'function',
           file: 'main.ts',
@@ -372,7 +372,7 @@ describe('subsystem graph model', () => {
           symbol: 'createHost',
         },
         {
-          id: 'write',
+          alias: 'write',
           name: 'writeSession',
           construct: 'function',
           file: 'store.ts',
@@ -382,7 +382,7 @@ describe('subsystem graph model', () => {
           symbol: 'writeSession',
         },
         {
-          id: 'store',
+          alias: 'store',
           name: 'SessionStore',
           construct: 'store',
           file: 'store.ts',
@@ -416,9 +416,9 @@ describe('subsystem graph model', () => {
   test('buildSubsystemGraph drops singleton process frames (no parentId, no group)', async () => {
     const { nodes, regions } = await buildSubsystemGraph({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
       ],
       relations: [],
       walkthroughs: [{
@@ -436,7 +436,7 @@ describe('subsystem graph model', () => {
     const { nodes, regions } = await buildSubsystemGraph({
       components: [
         {
-          id: 'rec',
+          alias: 'rec',
           name: 'CodexRolloutRecord',
           construct: 'type_alias',
           file: 'transcript.ts',
@@ -445,7 +445,7 @@ describe('subsystem graph model', () => {
           symbol: 'CodexRolloutRecord',
         },
         {
-          id: 'parse',
+          alias: 'parse',
           name: 'parseTranscript',
           construct: 'function',
           file: 'transcript.ts',
@@ -454,7 +454,7 @@ describe('subsystem graph model', () => {
           symbol: 'parseTranscript',
         },
         {
-          id: 'solo',
+          alias: 'solo',
           name: 'lonely',
           construct: 'function',
           file: 'solo.ts',
@@ -477,10 +477,10 @@ describe('subsystem graph model', () => {
   test('getSubsystemPackageRegions groups by purl repo key, skipping externals', () => {
     const regions = getSubsystemPackageRegions({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app#a.ts' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
-        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
-        { id: 'ext', name: 'Stripe', construct: 'external', file: '', purl: 'pkg:npm/stripe' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app#a.ts' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
+        { alias: 'ext', name: 'Stripe', construct: 'external', file: '', purl: 'pkg:npm/stripe' },
       ],
     });
     expect(regions.map((r) => r.key).sort()).toEqual([
@@ -494,8 +494,8 @@ describe('subsystem graph model', () => {
   test('buildBoundaryLayoutGroups skips package frames for single-repo graphs', () => {
     const groups = buildBoundaryLayoutGroups({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
       ],
     });
     expect(groups.filter((g) => g.region.kind === 'package')).toHaveLength(0);
@@ -504,10 +504,10 @@ describe('subsystem graph model', () => {
   test('buildBoundaryLayoutGroups frames packages when multi-repo', () => {
     const groups = buildBoundaryLayoutGroups({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
-        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
-        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/other/lib' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/other/lib' },
       ],
     });
     const pkgs = groups.filter((g) => g.region.kind === 'package');
@@ -521,7 +521,7 @@ describe('subsystem graph model', () => {
     const groups = buildBoundaryLayoutGroups({
       components: [
         {
-          id: 'a',
+          alias: 'a',
           name: 'a',
           construct: 'function',
           file: 'a.ts',
@@ -529,7 +529,7 @@ describe('subsystem graph model', () => {
           process: 'app/host',
         },
         {
-          id: 'b',
+          alias: 'b',
           name: 'b',
           construct: 'function',
           file: 'b.ts',
@@ -537,7 +537,7 @@ describe('subsystem graph model', () => {
           process: 'app/host',
         },
         {
-          id: 'c',
+          alias: 'c',
           name: 'c',
           construct: 'function',
           file: 'c.ts',
@@ -545,7 +545,7 @@ describe('subsystem graph model', () => {
           process: 'lib/worker',
         },
         {
-          id: 'd',
+          alias: 'd',
           name: 'd',
           construct: 'function',
           file: 'd.ts',
@@ -562,7 +562,7 @@ describe('subsystem graph model', () => {
     const { nodes } = await buildSubsystemGraph({
       components: [
         {
-          id: 'a1',
+          alias: 'a1',
           name: 'a1',
           construct: 'function',
           file: 'a.ts',
@@ -571,7 +571,7 @@ describe('subsystem graph model', () => {
           module: 'src/a.ts',
         },
         {
-          id: 'a2',
+          alias: 'a2',
           name: 'a2',
           construct: 'function',
           file: 'a.ts',
@@ -580,7 +580,7 @@ describe('subsystem graph model', () => {
           module: 'src/a.ts',
         },
         {
-          id: 'b1',
+          alias: 'b1',
           name: 'b1',
           construct: 'function',
           file: 'b.ts',
@@ -589,7 +589,7 @@ describe('subsystem graph model', () => {
           module: 'src/b.ts',
         },
         {
-          id: 'b2',
+          alias: 'b2',
           name: 'b2',
           construct: 'function',
           file: 'b.ts',
@@ -617,8 +617,8 @@ describe('subsystem graph model', () => {
     const groups = buildBoundaryLayoutGroups(
       {
         components: [
-          { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
-          { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+          { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+          { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
         ],
       },
       { packageFrames: 'always' },

package/src/subsystem/model.ts

@@ -127,7 +127,13 @@ export type SubsystemEdgeView = 'relations' | 'walkthroughs';
 
 /** A component node — the named unit, construct-tagged; `file` is its location. */
 export interface SubsystemComponent {
-  id: string;
+  /**
+   * Model-local stable alias, unique per model. Referenced by relation /
+   * walkthrough `from` / `to`; edges point at the alias, not the location.
+   * Code identity (for composed multi-model views) lives on
+   * `purl` + `file` + `symbol`, not here.
+   */
+  alias: string;
   name: string;
   /**
    * The node's construct — what it IS as a declaration (class, function,
@@ -268,8 +274,8 @@ export interface SubsystemRelation {
  */
 export interface SubsystemComponentEdge {
   id: string;
-  from: string; // component id
-  to: string; // component id or external target label
+  from: string; // component alias
+  to: string; // component alias or external target label
   mechanism: SubsystemEdgeMechanism;
   /** Concrete file/symbol refs backing the edge (the seam). */
   refs?: string[];
@@ -374,7 +380,7 @@ export function deriveGraphEdges(doc: {
  * Those snapshots are a catalog of declarations, not a graph.
  */
 export function isConstructsOnlyModel(doc: {
-  components: readonly { id: string }[];
+  components: readonly { alias: string }[];
   relations?: readonly SubsystemRelation[];
   walkthroughs?: readonly SubsystemWalkthrough[];
 }): boolean {
@@ -473,7 +479,7 @@ export interface SubsystemProcessRegion {
   /** Display label for the boundary frame. */
   label: string;
   /** Component ids that are members of this region. */
-  memberIds: string[];
+  memberAliases: string[];
 }
 
 /** Options for which boundary frames are kept. */
@@ -598,14 +604,14 @@ export function getSubsystemRegions(
     const p = c.process?.trim();
     if (!p) continue;
     const list = byProcess.get(p) ?? [];
-    list.push(c.id);
+    list.push(c.alias);
     byProcess.set(p, list);
   }
-  return [...byProcess.entries()].map(([key, memberIds]) => ({
+  return [...byProcess.entries()].map(([key, memberAliases]) => ({
     kind: 'process' as const,
     key,
     label: key,
-    memberIds,
+    memberAliases,
   }));
 }
 
@@ -621,14 +627,14 @@ export function getSubsystemModuleRegions(
     const m = c.module?.trim();
     if (!m) continue;
     const list = byModule.get(m) ?? [];
-    list.push(c.id);
+    list.push(c.alias);
     byModule.set(m, list);
   }
-  return [...byModule.entries()].map(([key, memberIds]) => ({
+  return [...byModule.entries()].map(([key, memberAliases]) => ({
     kind: 'module' as const,
     key,
     label: key,
-    memberIds,
+    memberAliases,
   }));
 }
 
@@ -645,14 +651,14 @@ export function getSubsystemPackageRegions(
     const key = componentPackageKey(c);
     if (!key) continue;
     const list = byPackage.get(key) ?? [];
-    list.push(c.id);
+    list.push(c.alias);
     byPackage.set(key, list);
   }
-  return [...byPackage.entries()].map(([key, memberIds]) => ({
+  return [...byPackage.entries()].map(([key, memberAliases]) => ({
     kind: 'package' as const,
     key,
     label: packageRegionLabel(key),
-    memberIds,
+    memberAliases,
   }));
 }
 
@@ -662,7 +668,7 @@ export function getSubsystemPackageRegions(
  */
 export interface BoundaryLayoutGroup {
   id: string;
-  memberIds: string[];
+  memberAliases: string[];
   /** When set, this group is a child of another boundary group. */
   parentId?: string;
   region: SubsystemProcessRegion;
@@ -672,7 +678,7 @@ function keepRegion(
   r: SubsystemProcessRegion,
   showSingletons: boolean,
 ): boolean {
-  return showSingletons || r.memberIds.length >= 2;
+  return showSingletons || r.memberAliases.length >= 2;
 }
 
 /**
@@ -689,7 +695,7 @@ export function buildBoundaryLayoutGroups(
 ): BoundaryLayoutGroup[] {
   const showSingletons = opts.showSingletonFrames === true;
   const packageMode = opts.packageFrames ?? 'multi-repo';
-  const byId = new Map(doc.components.map((c) => [c.id, c]));
+  const byAlias = new Map(doc.components.map((c) => [c.alias, c]));
 
   const allPackages = getSubsystemPackageRegions(doc);
   const packageEligible =
@@ -714,8 +720,8 @@ export function buildBoundaryLayoutGroups(
   const moduleGroups: BoundaryLayoutGroup[] = modules.map((r) => {
     const processesOfMembers = new Set<string>();
     const packagesOfMembers = new Set<string>();
-    for (const id of r.memberIds) {
-      const c = byId.get(id);
+    for (const alias of r.memberAliases) {
+      const c = byAlias.get(alias);
       const p = c?.process?.trim();
       if (p) processesOfMembers.add(p);
       const pkg = c ? componentPackageKey(c) : undefined;
@@ -732,7 +738,7 @@ export function buildBoundaryLayoutGroups(
     }
     return {
       id: moduleGroupNodeId(r.key),
-      memberIds: [...r.memberIds],
+      memberAliases: [...r.memberAliases],
       parentId,
       region: r,
     };
@@ -742,15 +748,15 @@ export function buildBoundaryLayoutGroups(
     const processId = processGroupNodeId(r.key);
     const nestedModules = moduleGroups.filter((m) => m.parentId === processId);
     const nestedModuleKeys = new Set(nestedModules.map((m) => m.region.key));
-    const directLeaves = r.memberIds.filter((id) => {
-      const mod = byId.get(id)?.module?.trim();
+    const directLeaves = r.memberAliases.filter((alias) => {
+      const mod = byAlias.get(alias)?.module?.trim();
       if (!mod) return true;
       return !nestedModuleKeys.has(mod);
     });
 
     const packagesOfMembers = new Set<string>();
-    for (const id of r.memberIds) {
-      const c = byId.get(id);
+    for (const alias of r.memberAliases) {
+      const c = byAlias.get(alias);
       const pkg = c ? componentPackageKey(c) : undefined;
       if (pkg) packagesOfMembers.add(pkg);
     }
@@ -762,7 +768,7 @@ export function buildBoundaryLayoutGroups(
 
     return {
       id: processId,
-      memberIds: [...nestedModules.map((m) => m.id), ...directLeaves],
+      memberAliases: [...nestedModules.map((m) => m.id), ...directLeaves],
       parentId,
       region: r,
     };
@@ -774,15 +780,15 @@ export function buildBoundaryLayoutGroups(
     const nestedModules = moduleGroups.filter((m) => m.parentId === packageId);
     const claimed = new Set<string>();
     for (const p of nestedProcesses) {
-      for (const id of p.region.memberIds) claimed.add(id);
+      for (const alias of p.region.memberAliases) claimed.add(alias);
     }
     for (const m of nestedModules) {
-      for (const id of m.region.memberIds) claimed.add(id);
+      for (const alias of m.region.memberAliases) claimed.add(alias);
     }
-    const directLeaves = r.memberIds.filter((id) => !claimed.has(id));
+    const directLeaves = r.memberAliases.filter((alias) => !claimed.has(alias));
     return {
       id: packageId,
-      memberIds: [
+      memberAliases: [
         ...nestedProcesses.map((p) => p.id),
         ...nestedModules.map((m) => m.id),
         ...directLeaves,
@@ -1209,7 +1215,7 @@ export function convertSubsystemToNodes(
           ? processGroupNodeId(processKey)
           : undefined;
       nodes.push({
-        id: c.id,
+        id: c.alias,
         type: 'subsystem-component',
         ...(parentId ? { parentId } : {}),
         position: { x: PAD + col * COL_W, y: cursorY + row * ROW_H },
@@ -1245,18 +1251,18 @@ export function convertSubsystemToGroups(
 
 /**
  * Convert a subsystem graph document into React Flow edges. Edges whose target
- * is an external label (not a component id) point at a synthetic stub so the
+ * is an external label (not a component alias) point at a synthetic stub so the
  * relationship is visible without a member node.
  */
 export function convertSubsystemToEdges(doc: SubsystemModelDocument): SubsystemGraphEdge[] {
-  const compIds = new Set(doc.components.map((c) => c.id));
+  const compAliases = new Set(doc.components.map((c) => c.alias));
   const edges: SubsystemGraphEdge[] = [];
 
   for (const e of deriveGraphEdges(doc)) {
     const color = MECHANISM_COLOR[e.mechanism];
     const style = MECHANISM_STYLE[e.mechanism];
     // If `to` is a real component, connect directly; otherwise point at a stub node.
-    const isExternal = !compIds.has(e.to);
+    const isExternal = !compAliases.has(e.to);
     const targetId = isExternal ? `external:${e.to}` : e.to;
 
     edges.push({
@@ -1282,8 +1288,8 @@ export function subsystemGraphLayoutKey(
   doc: Pick<SubsystemModelDocument, 'components' | 'relations' | 'walkthroughs'>,
 ): string {
   const components = doc.components
-    .map(({ id, purl, name, symbol, construct, file, purpose, process, module }) =>
-      [id, purl, name, symbol ?? '', construct, file, purpose ?? '', process ?? '', module ?? ''].join('\0'))
+    .map(({ alias, purl, name, symbol, construct, file, purpose, process, module }) =>
+      [alias, purl, name, symbol ?? '', construct, file, purpose ?? '', process ?? '', module ?? ''].join('\0'))
     .sort()
     .join('\n');
   const edgeKey = deriveGraphEdges(doc)
@@ -1326,7 +1332,7 @@ export async function buildSubsystemGraph(
   const layoutGroups = buildBoundaryLayoutGroups(doc, frameOpts);
   const regions = layoutGroups.map((g) => g.region);
   const regionIds = new Set(layoutGroups.map((g) => g.id));
-  const byId = new Map(doc.components.map((c) => [c.id, c]));
+  const byAlias = new Map(doc.components.map((c) => [c.alias, c]));
 
   // Resolve leaf parentIds against kept frames: module → process → package.
   // Stamp package parents here (not in convertSubsystemToNodes) so single-repo
@@ -1335,7 +1341,7 @@ export async function buildSubsystemGraph(
     if (n.type !== 'subsystem-component') continue;
     const parentId = (n as { parentId?: string }).parentId;
     if (parentId && regionIds.has(parentId)) continue;
-    const comp = (n.data as SubsystemGraphNodeData).component ?? byId.get(n.id);
+    const comp = (n.data as SubsystemGraphNodeData).component ?? byAlias.get(n.id);
     const processKey = comp?.process?.trim();
     const processId = processKey ? processGroupNodeId(processKey) : undefined;
     if (processId && regionIds.has(processId)) {
@@ -1353,10 +1359,10 @@ export async function buildSubsystemGraph(
 
   // External edge targets that aren't real components → create stub nodes so
   // cross-package edges have something to land on.
-  const realIds = new Set(doc.components.map((c) => c.id));
+  const realAliases = new Set(doc.components.map((c) => c.alias));
   const externalIds: string[] = [];
   for (const e of deriveGraphEdges(doc)) {
-    if (!realIds.has(e.to)) {
+    if (!realAliases.has(e.to)) {
       const extId = `external:${e.to}`;
       if (!externalIds.includes(extId)) externalIds.push(extId);
     }
@@ -1372,7 +1378,7 @@ export async function buildSubsystemGraph(
       height: 60,
       data: {
         component: {
-          id: extId,
+          alias: extId,
           name: label,
           construct: 'external',
           purl: 'external',
@@ -1416,7 +1422,7 @@ export async function buildSubsystemGraph(
         edgeLabels: showEdgeLabels === false ? { enabled: false } : { enabled: true, placement: 'CENTER' },
         groups: layoutGroups.map((g) => ({
           id: g.id,
-          memberIds: g.memberIds,
+          memberIds: g.memberAliases,
           parentId: g.parentId,
           minWidth: g.region.kind === 'module' ? moduleMinWidthForBadge(g.region.label) : undefined,
         })),

package/src/subsystem/nodes.tsx

@@ -69,14 +69,14 @@ function breakWords(s: string): string {
 
 export interface SubsystemGraphCallbacks {
   /** Click a component — open its file/entry point. */
-  onSelect?: (componentId: string) => void;
+  onSelect?: (componentAlias: string) => void;
   /** Click the filename badge — open that component's file in the drawer
    *  (same path as clicking the file link in the declaration panel). */
-  onOpenFile?: (componentId: string) => void;
+  onOpenFile?: (componentAlias: string) => void;
   /** Click an edge (or its label) — select the relationship. */
   onEdgeSelect?: (edgeId: string) => void;
   /** Hover a component (null on leave) — associates it with the file tree. */
-  onHover?: (componentId: string | null) => void;
+  onHover?: (componentAlias: string | null) => void;
   /** Upper bound for node width; nodes grow with content up to this, then wrap. */
   maxNodeWidth?: number;
 }
@@ -131,7 +131,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
     <div
       onMouseEnter={() => {
         setHover(true);
-        SUBSYSTEM_CALLBACKS.onHover?.(c.id);
+        SUBSYSTEM_CALLBACKS.onHover?.(c.alias);
       }}
       onMouseLeave={() => {
         setHover(false);
@@ -139,7 +139,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
       }}
       onClick={(e) => {
         e.stopPropagation();
-        SUBSYSTEM_CALLBACKS.onSelect?.(c.id);
+        SUBSYSTEM_CALLBACKS.onSelect?.(c.alias);
       }}
       style={{
         position: 'relative',
@@ -275,7 +275,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
           onClick={(e) => {
             // Open the file directly; don't also toggle node selection.
             e.stopPropagation();
-            SUBSYSTEM_CALLBACKS.onOpenFile?.(c.id);
+            SUBSYSTEM_CALLBACKS.onOpenFile?.(c.alias);
           }}
         >
           {c.file.split('/').pop()}