@principal-ai/subsystems-react 0.42.0 → 0.43.0

package/src/subsystem/model.test.ts

@@ -48,13 +48,35 @@ const comps: SubsystemComponent[] = [
   { alias: 'transcript', name: 'transcript', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
 ];
 
-const relations = [
-  { id: 'e1', from: 'transcript', to: 'reader', relationType: 'method' as const },
-  // 'host' is NOT a component — this is the cross-package external case.
-  { id: 'e2', from: 'reader', to: 'host', relationType: 'method' as const, refs: ['bun/index.ts'] },
+// 'host' is NOT a component — this is the cross-package external case.
+const walkthroughs: SubsystemWalkthrough[] = [
+  {
+    id: 'wt',
+    title: 'flow',
+    steps: [
+      {
+        from: 'transcript',
+        to: 'reader',
+        mechanism: 'calls',
+        file: 'transcript.ts',
+        line: 1,
+        purl: 'pkg:github/principal-ai/agent-monitoring#transcript.ts',
+        symbol: 'transcript',
+      },
+      {
+        from: 'reader',
+        to: 'host',
+        mechanism: 'calls',
+        file: 'SessionReader.ts',
+        line: 1,
+        purl: 'pkg:github/principal-ai/agent-monitoring#SessionReader.ts',
+        symbol: 'SessionReader',
+      },
+    ],
+  },
 ];
 
-const doc = { components: comps, relations };
+const doc = { components: comps, walkthroughs };
 
 describe('subsystem graph model', () => {
   test('converts all components to flat component nodes', () => {
@@ -85,7 +107,6 @@ describe('subsystem graph model', () => {
     ];
     const { nodes } = await buildSubsystemGraph({
       components: withExternal,
-      relations: [],
       walkthroughs: [{
         id: 'w1',
         title: 'feed',
@@ -294,7 +315,6 @@ describe('subsystem graph model', () => {
         },
         { alias: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
       ],
-      relations: [],
     });
     expect((nodes.find((n) => n.id === 'a') as { parentId?: string }).parentId).toBe(
       moduleGroupNodeId('src/a.ts'),
@@ -308,7 +328,6 @@ describe('subsystem graph model', () => {
         { 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: [],
     });
     expect((nodes.find((n) => n.id === 'a') as { parentId?: string }).parentId).toBe(
       processGroupNodeId('app/host'),
@@ -404,7 +423,6 @@ describe('subsystem graph model', () => {
           symbol: 'SessionStore',
         },
       ],
-      relations: [],
     });
     expect(regions.map((r) => r.key).sort()).toEqual(
       ['app/host', 'src/main.ts', 'src/store.ts'].sort(),
@@ -432,7 +450,6 @@ describe('subsystem graph model', () => {
         { 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: [{
         id: 'w1',
         title: 'call',
@@ -566,7 +583,6 @@ describe('subsystem graph model', () => {
           symbol: 'lonely',
         },
       ],
-      relations: [],
     });
     expect(regions.map((r) => r.key)).toEqual(['src/session/transcript.ts']);
     expect(regions[0]!.kind).toBe('module');
@@ -701,7 +717,6 @@ describe('subsystem graph model', () => {
           module: 'src/b.ts',
         },
       ],
-      relations: [],
     });
     const pkgA = nodes.find((n) => n.id === packageGroupNodeId('pkg:github/acme/app'));
     const proc = nodes.find((n) => n.id === processGroupNodeId('app/host'));
@@ -791,7 +806,7 @@ describe('subsystem graph model', () => {
             }
           : c,
       ),
-      relations,
+      walkthroughs,
     };
     expect(subsystemGraphLayoutKey(base)).toBe(subsystemGraphLayoutKey(withRef));
   });
@@ -799,7 +814,7 @@ describe('subsystem graph model', () => {
 
 describe('isConstructsOnlyModel', () => {
   test('true when components exist and there are no edges', () => {
-    expect(isConstructsOnlyModel({ components: comps, relations: [], walkthroughs: [] })).toBe(true);
+    expect(isConstructsOnlyModel({ components: comps, walkthroughs: [] })).toBe(true);
     expect(isConstructsOnlyModel({ components: comps })).toBe(true);
   });
 
@@ -812,13 +827,12 @@ describe('isConstructsOnlyModel', () => {
     ).toBe(false);
   });
 
-  test('false when empty, or when relations or walkthrough hops exist', () => {
-    expect(isConstructsOnlyModel({ components: [], relations: [] })).toBe(false);
-    expect(isConstructsOnlyModel({ components: comps, relations })).toBe(false);
+  test('false when empty, or when walkthrough hops exist', () => {
+    expect(isConstructsOnlyModel({ components: [] })).toBe(false);
+    expect(isConstructsOnlyModel({ components: comps, walkthroughs })).toBe(false);
     expect(
       isConstructsOnlyModel({
         components: comps,
-        relations: [],
         walkthroughs: [
           {
             id: 'wt',
@@ -993,7 +1007,6 @@ describe('reorderTargetIndex', () => {
 describe('graphify-native edges', () => {
   const doc = {
     components: comps,
-    relations: [],
   };
   const graphify = [
     { id: 'g1', from: 'reader', to: 'dst', relation: 'imports' },
@@ -1006,12 +1019,12 @@ describe('graphify-native edges', () => {
     expect(e.mechanism).toBe('imports');
   });
 
-  test('subsystem relations keep no graphify provenance', () => {
+  test('walkthrough edges keep no graphify provenance', () => {
     const [e] = deriveGraphEdges({
-      relations: [{ id: 'r', from: 'reader', to: 'dst', relationType: 'method' }],
+      walkthroughs: [walkthroughs[0]!],
     });
     expect(e.provenance).toBeUndefined();
-    expect(e.mechanism).toBe('method');
+    expect(e.mechanism).toBe('calls');
   });
 
   test('graphify edges color from the separate palette', () => {
@@ -1019,7 +1032,7 @@ describe('graphify-native edges', () => {
       GRAPHIFY_RELATION_COLOR.imports,
     );
     expect(edgeColor({ mechanism: 'imports', provenance: 'graphify' })).not.toBe(
-      MECHANISM_COLOR.method,
+      MECHANISM_COLOR.calls,
     );
   });
 
@@ -1030,7 +1043,7 @@ describe('graphify-native edges', () => {
   });
 
   test('subsystem mechanism color is unaffected by the graphify palette', () => {
-    expect(edgeColor({ mechanism: 'method' })).toBe(MECHANISM_COLOR.method);
+    expect(edgeColor({ mechanism: 'calls' })).toBe(MECHANISM_COLOR.calls);
   });
 
   test('graphify edges all share the graphify stroke style', () => {

package/src/subsystem/model.ts

@@ -108,17 +108,6 @@ export interface SubsystemDeclToken {
   color?: string;
 }
 
-/**
- * Topology relation type — structural / module / type claims.
- * Belongs on `relations[]`, not on walkthrough hops.
- */
-export type SubsystemRelationType =
-  | 'extends'
-  | 'inherits'
-  | 'implements'
-  | 'mixes_in'
-  | 'method';
-
 /**
  * Walkthrough hop mechanism — runtime seams with a `file:line` site.
  */
@@ -132,24 +121,21 @@ export type SubsystemWalkthroughMechanism =
   | 'watches'
   | 'registers-into';
 
-/** Union for derived graph-edge styling (relationType or hop mechanism). */
-export type SubsystemEdgeMechanism =
-  | SubsystemRelationType
-  | SubsystemWalkthroughMechanism;
+/** Union for derived graph-edge styling — the walkthrough hop mechanism. */
+export type SubsystemEdgeMechanism = SubsystemWalkthroughMechanism;
 
 /**
- * Which edge vocabulary the canvas draws. The two vocabularies are disjoint;
- * a view shows only edges (and their labels) from the selected source.
- * - `relations`: only topology relation edges (`extends`, `implements`, …)
+ * Which edge source the canvas draws. The two sources are disjoint; a view
+ * shows only edges (and their labels) from the selected source.
+ * - `graphify`: only graphify-native static edges (`imports`, `contains`, …)
  * - `walkthroughs`: only walkthrough hop edges (`calls`, `feeds`, …)
  */
-export type SubsystemEdgeView = 'relations' | 'walkthroughs';
+export type SubsystemEdgeView = 'graphify' | 'walkthroughs';
 
 /**
  * Where a display edge came from.
  *
- * - `subsystem` (default): a verb from the authored vocabularies
- *   (`SubsystemRelationType` / `SubsystemWalkthroughMechanism`), colored from
+ * - `subsystem` (default): a walkthrough hop mechanism verb, colored from
  *   `MECHANISM_COLOR`.
  * - `graphify`: a raw relation read off graphify's static symbol graph
  *   (`imports`, `contains`, `re_exports`, …). These are DERIVED, never authored,
@@ -162,10 +148,8 @@ export type SubsystemEdgeProvenance = 'subsystem' | 'graphify';
  * A graphify-native topology edge — a raw graphify relation that has no
  * subsystem mechanism equivalent.
  *
- * Kept structurally separate from `SubsystemRelation`: those are authored into
- * a portable model and validated against a closed vocabulary, whereas these are
- * derived from a graphify run and carry graphify's own (open) verb set. They are
- * a display input only — never written back into a `SubsystemModelDocument`.
+ * Derived from a graphify run and carry graphify's own (open) verb set. They
+ * are a display input only — never written back into a `SubsystemModelDocument`.
  */
 export interface SubsystemGraphifyRelation {
   id: string;
@@ -192,8 +176,8 @@ export interface SubsystemGraphifyRelation {
 /** A component node — the named unit, construct-tagged; `file` is its location. */
 export interface SubsystemComponent {
   /**
-   * Model-local stable alias, unique per model. Referenced by relation /
-   * walkthrough `from` / `to`; edges point at the alias, not the location.
+   * Model-local stable alias, unique per model. Referenced by 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.
    */
@@ -330,19 +314,9 @@ export interface SubsystemComponent {
   declarationRef?: SubsystemDeclarationRef;
 }
 
-/** A topology relation between components (structural / module / type). */
-export interface SubsystemRelation {
-  id: string;
-  from: string;
-  to: string;
-  relationType: SubsystemRelationType;
-  /** Concrete file/symbol refs backing the relation. */
-  refs?: string[];
-}
-
 /**
- * Derived / display graph edge used by renderers. Built from `relations`
- * and/or walkthrough hops — not authored as its own document field.
+ * Derived / display graph edge used by renderers. Built from walkthrough hops
+ * (and graphify-native relations) — not authored as its own document field.
  */
 export interface SubsystemComponentEdge {
   id: string;
@@ -352,8 +326,8 @@ export interface SubsystemComponentEdge {
    * The edge verb. For `provenance: 'subsystem'` (the default) this is a
    * `SubsystemEdgeMechanism`; for `provenance: 'graphify'` it is the raw
    * graphify relation. Typed as `string` because the display edge is a derived
-   * structure and graphify's verb set is open — the authored vocabularies
-   * (`SubsystemRelationType` / `SubsystemWalkthroughMechanism`) stay closed.
+   * structure and graphify's verb set is open — the walkthrough vocabulary
+   * (`SubsystemWalkthroughMechanism`) stays closed.
    */
   mechanism: string;
   /** Origin of the edge; absent means `'subsystem'`. */
@@ -414,13 +388,11 @@ export interface SubsystemWalkthrough {
 
 export interface SubsystemModelDocument {
   components: SubsystemComponent[];
-  /** Topology relations (structural / module / type). May be empty. */
-  relations: SubsystemRelation[];
   /** Ordered runtime walkthroughs (one per named behavior). */
   walkthroughs?: SubsystemWalkthrough[];
 }
 
-/** Stable id for a derived graph edge from a relation or walkthrough hop. */
+/** Stable id for a derived graph edge from a walkthrough hop. */
 export function derivedGraphEdgeId(
   from: string,
   to: string,
@@ -429,10 +401,6 @@ export function derivedGraphEdgeId(
   return `${from}--${mechanism}-->${to}`;
 }
 
-/**
- * Build display edges for the graph canvas from topology relations and
- * walkthrough hops (deduped by from/to/mechanism).
- */
 /** React Flow / canvas edge id for a walkthrough hop. */
 export function walkthroughStepGraphEdgeId(
   step: Pick<SubsystemWalkthroughStep, 'from' | 'to' | 'mechanism'>,
@@ -472,23 +440,10 @@ export function reorderTargetIndex(boundary: number, from: number): number {
 }
 
 export function deriveGraphEdges(doc: {
-  relations?: readonly SubsystemRelation[];
   walkthroughs?: readonly SubsystemWalkthrough[];
   graphifyRelations?: readonly SubsystemGraphifyRelation[];
 }): SubsystemComponentEdge[] {
   const byId = new Map<string, SubsystemComponentEdge>();
-  for (const r of doc.relations ?? []) {
-    const id = r.id || derivedGraphEdgeId(r.from, r.to, r.relationType);
-    if (!byId.has(id)) {
-      byId.set(id, {
-        id,
-        from: r.from,
-        to: r.to,
-        mechanism: r.relationType,
-        refs: r.refs,
-      });
-    }
-  }
   for (const w of doc.walkthroughs ?? []) {
     for (const step of w.steps) {
       const id = derivedGraphEdgeId(step.from, step.to, step.mechanism);
@@ -522,18 +477,16 @@ export function deriveGraphEdges(doc: {
 }
 
 /**
- * True when the model has components but no topology or walkthrough edges.
+ * True when the model has components but no walkthrough or graphify edges.
  * Those snapshots are a catalog of declarations, not a graph.
  */
 export function isConstructsOnlyModel(doc: {
   components: readonly { alias: string }[];
-  relations?: readonly SubsystemRelation[];
   walkthroughs?: readonly SubsystemWalkthrough[];
   graphifyRelations?: readonly SubsystemGraphifyRelation[];
 }): boolean {
   if (doc.components.length === 0) return false;
   return deriveGraphEdges({
-    relations: doc.relations,
     walkthroughs: doc.walkthroughs,
     graphifyRelations: doc.graphifyRelations,
   }).length === 0;
@@ -1131,19 +1084,6 @@ export interface SubsystemGraphEdgeData extends Record<string, unknown> {
 
 export type SubsystemGraphEdge = Edge<SubsystemGraphEdgeData>;
 
-/**
- * Runtime vocabulary of relation types — mirrors `SubsystemRelationType`.
- * Used to split derived display edges into their relation vs walkthrough
- * source (the two unions are disjoint).
- */
-export const SUBSYSTEM_RELATION_TYPES = [
-  'extends',
-  'inherits',
-  'implements',
-  'mixes_in',
-  'method',
-] as const satisfies readonly SubsystemRelationType[];
-
 /** Runtime vocabulary of walkthrough hop mechanisms — mirrors `SubsystemWalkthroughMechanism`. */
 export const SUBSYSTEM_WALKTHROUGH_MECHANISMS = [
   'calls',
@@ -1156,18 +1096,10 @@ export const SUBSYSTEM_WALKTHROUGH_MECHANISMS = [
   'registers-into',
 ] as const satisfies readonly SubsystemWalkthroughMechanism[];
 
-const RELATION_TYPE_SET: ReadonlySet<string> = new Set(SUBSYSTEM_RELATION_TYPES);
 const WALKTHROUGH_MECHANISM_SET: ReadonlySet<string> = new Set(
   SUBSYSTEM_WALKTHROUGH_MECHANISMS,
 );
 
-/** True when a mechanism belongs to the topology relation vocabulary. */
-export function isRelationMechanism(
-  mechanism: string,
-): mechanism is SubsystemRelationType {
-  return RELATION_TYPE_SET.has(mechanism);
-}
-
 /** True when a mechanism belongs to the walkthrough hop vocabulary. */
 export function isWalkthroughMechanism(
   mechanism: string,
@@ -1177,12 +1109,7 @@ export function isWalkthroughMechanism(
 
 export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
   calls: '#22c55e', // green
-  extends: '#b48ead', // purple
-  inherits: '#9b6fd0', // purple
-  implements: '#c586c0', // magenta
-  mixes_in: '#d474a8', // pink-magenta
   uses: '#e3b341', // gold
-  method: '#c586c0', // magenta
   feeds: '#4ec9b0', // teal — data-flow into a processor
   produces: '#a78bfa', // violet — emits an output type
   writes: '#e8853a', // orange — mutates retained state
@@ -1193,12 +1120,7 @@ export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
 
 export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed' | 'dotted'> = {
   calls: 'solid',
-  extends: 'dashed',
-  inherits: 'dashed',
-  implements: 'dashed',
-  mixes_in: 'dashed',
   uses: 'solid',
-  method: 'solid',
   feeds: 'solid',
   produces: 'solid',
   writes: 'solid',
@@ -1363,12 +1285,7 @@ export function boundaryFill(color: string, alpha = '1f'): string {
  *  directly verifiable" styling of edge labels. */
 export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][] = [
   ['calls', 'function/method call (call graph edge)', true],
-  ['extends', 'class inheritance', true],
-  ['inherits', 'class inheritance', true],
-  ['implements', 'implements interface / protocol', true],
-  ['mixes_in', 'applies mixin', true],
   ['uses', 'general dependency (import, call, or reference)', false],
-  ['method', 'structural: has method / member', true],
   ['feeds', 'data flow: output feeds into input', false],
   ['produces', 'data flow: produces / outputs', false],
   ['writes', 'state access: mutates retained state', true],
@@ -1733,7 +1650,7 @@ export function convertSubsystemToEdges(
 
 /** Stable key for layout-affecting graph fields (ignores declarationRef, etc.). */
 export function subsystemGraphLayoutKey(
-  doc: Pick<SubsystemModelDocument, 'components' | 'relations' | 'walkthroughs'> & {
+  doc: Pick<SubsystemModelDocument, 'components' | 'walkthroughs'> & {
     graphifyRelations?: readonly SubsystemGraphifyRelation[];
   },
 ): string {

package/src/subsystem/toC4.test.ts

@@ -18,17 +18,12 @@ const doc: SubsystemModelDocument = {
     { alias: 'x', name: 'Gist API', construct: 'external', file: '', purl: 'external:api.github.com/gists' },
     { alias: 'agent', name: 'Maintenance agent', construct: 'custom_entity', file: '', purl: 'external' },
   ],
-  relations: [
-    { id: 'r1', from: 'a', to: 'b', relationType: 'method' }, // intra p1
-    { id: 'r2', from: 'a', to: 'c', relationType: 'method' },
-    { id: 'r3', from: 'b', to: 'c', relationType: 'method' },
-    { id: 'r4', from: 'a', to: 'x', relationType: 'method' },
-  ],
   walkthroughs: [
     {
       id: 'w1',
       title: 'flow',
       steps: [
+        { from: 'a', to: 'b', mechanism: 'calls', file: 'src/a.ts', line: 1, purl: `${REPO}#src/a.ts`, symbol: 'Alpha' },
         { from: 'b', to: 'c', mechanism: 'calls', file: 'src/b.ts', line: 1, purl: `${REPO}#src/b.ts`, symbol: 'Beta' },
         { from: 'a', to: 'c', mechanism: 'calls', file: 'src/a.ts', line: 2, purl: `${REPO}#src/a.ts`, symbol: 'Alpha' },
         { from: 'a', to: 'agent', mechanism: 'calls', file: 'src/a.ts', line: 3, purl: `${REPO}#src/a.ts`, symbol: 'Alpha' },
@@ -77,18 +72,16 @@ describe('container view', () => {
     expect(model.groups[0]!.memberIds.sort()).toEqual(['container:p1', 'container:p2']);
   });
 
-  test('edges roll up and intra-container edges drop', () => {
+  test('flow edges roll up to containers; only flow edges exist', () => {
     const byId = Object.fromEntries(model.edges.map((e) => [e.id, e]));
     // a->b is intra-p1 — dropped.
     expect(model.edges.some((e) => e.source === e.target)).toBe(false);
-    const rel = byId['relationship:container:p1\u0000container:p2']!;
-    expect(rel.kind).toBe('relationship');
-    expect(rel.count).toBe(2); // r2 + r3
     const flow = byId['flow:container:p1\u0000container:p2']!;
+    expect(flow.kind).toBe('flow');
     expect(flow.count).toBe(2); // a->c + b->c
-    expect(byId['relationship:container:p1\u0000external:external:api.github.com/gists']).toBeDefined();
     expect(byId['flow:container:p1\u0000actor:agent']).toBeDefined();
-    expect(model.edges).toHaveLength(4);
+    expect(model.edges.every((e) => e.kind === 'flow')).toBe(true);
+    expect(model.edges).toHaveLength(2);
   });
 });
 

package/src/subsystem/toC4.ts

@@ -2,8 +2,8 @@
  * toC4 — project a subsystem-model (or a composition of them) onto C4 levels.
  *
  * The stored document is flat: `components[]` carry `process` (runtime unit),
- * `purl` (repo/package), `construct`, `role`, `module`, plus `relations[]`
- * (static) and `walkthroughs[]` (dynamic). C4 wants a hierarchy above the
+ * `purl` (repo/package), `construct`, `role`, `module`, plus `walkthroughs[]`
+ * (dynamic). C4 wants a hierarchy above the
  * component — system → container → component — with externals and actors
  * outside it. This module derives that hierarchy without inventing data:
  *
@@ -59,12 +59,12 @@ export interface C4Group {
   memberIds: string[];
 }
 
-/** A rolled-up collaboration. `relationship` = static, `flow` = walkthrough. */
+/** A rolled-up collaboration — a walkthrough flow between owners. */
 export interface C4Edge {
   id: string;
   source: string;
   target: string;
-  kind: 'relationship' | 'flow';
+  kind: 'flow';
   label: string;
   mechanisms: string[];
   count: number;
@@ -234,7 +234,6 @@ export function toC4(doc: SubsystemModelDocument, options: ToC4Options = {}): C4
   }
 
   // --- Edges: roll each endpoint up to its owner at this view -------------
-  const relEdges = new Map<string, C4Edge>();
   const flowEdges = new Map<string, C4Edge>();
 
   const addEdge = (
@@ -255,16 +254,13 @@ export function toC4(doc: SubsystemModelDocument, options: ToC4Options = {}): C4
     if (!edge.mechanisms.includes(mechanism)) edge.mechanisms.push(mechanism);
   };
 
-  for (const r of doc.relations ?? []) {
-    addEdge(relEdges, ownerOf.get(r.from), ownerOf.get(r.to), 'relationship', r.relationType);
-  }
   for (const w of doc.walkthroughs ?? []) {
     for (const s of w.steps ?? []) {
       addEdge(flowEdges, ownerOf.get(s.from), ownerOf.get(s.to), 'flow', s.mechanism);
     }
   }
 
-  const edges = [...relEdges.values(), ...flowEdges.values()];
+  const edges = [...flowEdges.values()];
   for (const e of edges) e.label = [...e.mechanisms].sort().join(' + ');
 
   return {