@principal-ai/subsystems-react 0.37.12 → 0.39.0

package/src/subsystem/formatDeclaration.test.ts

@@ -2,6 +2,70 @@ import { describe, expect, test } from 'bun:test';
 import { generateDeclarationString, resolveComponentDeclaration } from './formatDeclaration';
 import type { SubsystemComponent } from './model';
 
+describe('generateDeclarationString — store', () => {
+  const base: Omit<SubsystemComponent, 'declaration'> = {
+    id: 'st',
+    name: 'feeds',
+    construct: 'store',
+    symbol: 'feeds',
+    file: 'src/live.ts',
+    purl: 'pkg:github/acme/app',
+  };
+
+  test('renders a declared valueType as the store signature', () => {
+    const component: SubsystemComponent = {
+      ...base,
+      declaration: {
+        kind: 'store',
+        storage: 'memory',
+        properties: [],
+        valueType: 'Map<string, OpencodeLiveFeedState>',
+      },
+    };
+    expect(generateDeclarationString(component)).toBe(
+      '// store: feeds — Map<string, OpencodeLiveFeedState>\n// backing: memory',
+    );
+  });
+
+  test('named members render as a body under the valueType', () => {
+    const component: SubsystemComponent = {
+      ...base,
+      declaration: {
+        kind: 'store',
+        storage: 'memory',
+        valueType: 'Map<string, { width: number }>',
+        properties: [{ name: 'current', type: 'Map<string, { width: number }>' }],
+      },
+    };
+    expect(generateDeclarationString(component)).toBe(
+      '// store: feeds — Map<string, { width: number }>\n// backing: memory\n  current: Map<string, { width: number }>;',
+    );
+  });
+
+  test('members without a valueType still render as declare const lines', () => {
+    const component: SubsystemComponent = {
+      ...base,
+      declaration: {
+        kind: 'store',
+        properties: [{ name: 'ROOT', type: 'string' }],
+      },
+    };
+    expect(generateDeclarationString(component)).toBe(
+      '// store: feeds\ndeclare const ROOT: string;',
+    );
+  });
+
+  test('a store with neither valueType nor members says so explicitly', () => {
+    const component: SubsystemComponent = {
+      ...base,
+      declaration: { kind: 'store', storage: 'memory', properties: [] },
+    };
+    expect(generateDeclarationString(component)).toBe(
+      '// store: feeds — no declared type (no valueType or state members)\n// backing: memory',
+    );
+  });
+});
+
 describe('generateDeclarationString — custom_entity', () => {
   test('renders entity identity + entityKind, no attributes when none authored', () => {
     const component: SubsystemComponent = {

package/src/subsystem/formatDeclaration.ts

@@ -223,19 +223,34 @@ function generateType(
 }
 
 /**
- * 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.
+ * A store renders as its retained state — the declaration of what it holds,
+ * the way every other construct renders its signature. The node's name labels
+ * the block; the access mechanism lives in separate accessor nodes.
+ *
+ * Order: the backing comment, then the store's own typed declaration
+ * (`valueType` when declared, otherwise the named members as a body), then any
+ * remaining members. A store that declares neither says so explicitly rather
+ * than rendering as an empty block.
  */
 function generateStore(name: string, declaration?: GraphifyComponentDetail): string {
   const store = declaration?.kind === 'store' ? declaration : undefined;
   const backing = store?.storage ? `\n// backing: ${store.storage}` : '';
-  const props = (store?.properties ?? [])
+  const members = store?.properties ?? [];
+  const props = members
     .map((p) => `declare const ${p.name}${p.type ? `: ${p.type}` : ''};`)
     .join('\n');
 
+  if (store?.valueType) {
+    const named = members.length
+      ? `\n${members
+          .map((p) => `  ${p.name}${p.type ? `: ${p.type}` : ''};`)
+          .join('\n')}`
+      : '';
+    return `// store: ${name} — ${store.valueType}${backing}${named}`;
+  }
+
   if (!props) {
-    return `// store: ${name} — no captured state members${backing}`;
+    return `// store: ${name} — no declared type (no valueType or state members)${backing}`;
   }
   return `// store: ${name}${backing}\n${props}`;
 }

package/src/subsystem/model.test.ts

@@ -2,6 +2,13 @@ import { describe, expect, test } from 'bun:test';
 import {
   convertSubsystemToNodes,
   convertSubsystemToEdges,
+  deriveGraphEdges,
+  edgeColor,
+  edgeStrokeStyle,
+  MECHANISM_COLOR,
+  GRAPHIFY_RELATION_COLOR,
+  GRAPHIFY_RELATION_FALLBACK_COLOR,
+  GRAPHIFY_RELATION_STYLE,
   convertSubsystemToGroups,
   getSubsystemRegions,
   getSubsystemModuleRegions,
@@ -42,9 +49,9 @@ const comps: SubsystemComponent[] = [
 ];
 
 const relations = [
-  { id: 'e1', from: 'transcript', to: 'reader', relationType: 'references' as const },
+  { 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: 'references' as const, refs: ['bun/index.ts'] },
+  { id: 'e2', from: 'reader', to: 'host', relationType: 'method' as const, refs: ['bun/index.ts'] },
 ];
 
 const doc = { components: comps, relations };
@@ -796,6 +803,15 @@ describe('isConstructsOnlyModel', () => {
     expect(isConstructsOnlyModel({ components: comps })).toBe(true);
   });
 
+  test('false when only graphify-native edges exist', () => {
+    expect(
+      isConstructsOnlyModel({
+        components: comps,
+        graphifyRelations: [{ id: 'g', from: 'reader', to: 'transcript', relation: 'imports' }],
+      }),
+    ).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);
@@ -973,3 +989,60 @@ describe('reorderTargetIndex', () => {
     expect(reorderWalkthroughs(wts, 0, target).map((w) => w.id)).toEqual(['b', 'a', 'c']);
   });
 });
+
+describe('graphify-native edges', () => {
+  const doc = {
+    components: comps,
+    relations: [],
+  };
+  const graphify = [
+    { id: 'g1', from: 'reader', to: 'dst', relation: 'imports' },
+    { id: 'g2', from: 'reader', to: 'dst', relation: 'contains' },
+  ];
+
+  test('deriveGraphEdges tags graphify relations with provenance + raw verb', () => {
+    const [e] = deriveGraphEdges({ ...doc, graphifyRelations: graphify });
+    expect(e.provenance).toBe('graphify');
+    expect(e.mechanism).toBe('imports');
+  });
+
+  test('subsystem relations keep no graphify provenance', () => {
+    const [e] = deriveGraphEdges({
+      relations: [{ id: 'r', from: 'reader', to: 'dst', relationType: 'method' }],
+    });
+    expect(e.provenance).toBeUndefined();
+    expect(e.mechanism).toBe('method');
+  });
+
+  test('graphify edges color from the separate palette', () => {
+    expect(edgeColor({ mechanism: 'imports', provenance: 'graphify' })).toBe(
+      GRAPHIFY_RELATION_COLOR.imports,
+    );
+    expect(edgeColor({ mechanism: 'imports', provenance: 'graphify' })).not.toBe(
+      MECHANISM_COLOR.method,
+    );
+  });
+
+  test('unknown graphify verb falls back, never undefined', () => {
+    expect(edgeColor({ mechanism: 'brand_new_verb', provenance: 'graphify' })).toBe(
+      GRAPHIFY_RELATION_FALLBACK_COLOR,
+    );
+  });
+
+  test('subsystem mechanism color is unaffected by the graphify palette', () => {
+    expect(edgeColor({ mechanism: 'method' })).toBe(MECHANISM_COLOR.method);
+  });
+
+  test('graphify edges all share the graphify stroke style', () => {
+    expect(edgeStrokeStyle({ mechanism: 'imports', provenance: 'graphify' })).toBe(
+      GRAPHIFY_RELATION_STYLE,
+    );
+  });
+
+  test('convertSubsystemToEdges carries provenance into edge data', () => {
+    const edges = convertSubsystemToEdges(doc, graphify);
+    const g = edges.find((e) => e.id === 'g1');
+    expect((g?.data as { provenance?: string })?.provenance).toBe('graphify');
+    expect((g?.data as { mechanism?: string })?.mechanism).toBe('imports');
+  });
+});

package/src/subsystem/model.ts

@@ -117,8 +117,7 @@ export type SubsystemRelationType =
   | 'inherits'
   | 'implements'
   | 'mixes_in'
-  | 'method'
-  | 'references';
+  | 'method';
 
 /**
  * Walkthrough hop mechanism — runtime seams with a `file:line` site.
@@ -146,6 +145,50 @@ export type SubsystemEdgeMechanism =
  */
 export type SubsystemEdgeView = 'relations' | 'walkthroughs';
 
+/**
+ * Where a display edge came from.
+ *
+ * - `subsystem` (default): a verb from the authored vocabularies
+ *   (`SubsystemRelationType` / `SubsystemWalkthroughMechanism`), colored from
+ *   `MECHANISM_COLOR`.
+ * - `graphify`: a raw relation read off graphify's static symbol graph
+ *   (`imports`, `contains`, `re_exports`, …). These are DERIVED, never authored,
+ *   and are colored from `GRAPHIFY_RELATION_COLOR` so a reader can tell a
+ *   graphify fact apart from a subsystem claim at a glance.
+ */
+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`.
+ */
+export interface SubsystemGraphifyRelation {
+  id: string;
+  /** Source component alias. */
+  from: string;
+  /** Target component alias. */
+  to: string;
+  /** Raw graphify relation verb (e.g. `imports`, `contains`, `re_exports`). */
+  relation: string;
+  /** Concrete file/symbol refs backing the relation. */
+  refs?: string[];
+  /**
+   * 1-based source line of the relation site. Optional — available on
+   * `calls`/`references`-style edges; used to order an ego graph's callees by
+   * call site when a host opts into line-ordered layering.
+   */
+  line?: number;
+  /** graphify's provenance tag (`EXTRACTED` / `INFERRED` / `AMBIGUOUS`). */
+  confidence?: string;
+  /** Reference context on `references` edges (e.g. `return_type`, `field`). */
+  context?: string;
+}
+
 /** A component node — the named unit, construct-tagged; `file` is its location. */
 export interface SubsystemComponent {
   /**
@@ -305,9 +348,28 @@ export interface SubsystemComponentEdge {
   id: string;
   from: string; // component alias
   to: string; // component alias or external target label
-  mechanism: SubsystemEdgeMechanism;
+  /**
+   * 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.
+   */
+  mechanism: string;
+  /** Origin of the edge; absent means `'subsystem'`. */
+  provenance?: SubsystemEdgeProvenance;
   /** Concrete file/symbol refs backing the edge (the seam). */
   refs?: string[];
+  /**
+   * 1-based source line of the RELATION SITE — where the edge's verb was
+   * observed (e.g. a `calls` edge's call-site line inside the caller), NOT
+   * where the target is declared.
+   */
+  line?: number;
+  /** graphify's provenance tag (`EXTRACTED` / `INFERRED` / `AMBIGUOUS`). */
+  confidence?: string;
+  /** Reference context on `references` edges (e.g. `return_type`, `field`). */
+  context?: string;
 }
 
 /**
@@ -362,7 +424,7 @@ export interface SubsystemModelDocument {
 export function derivedGraphEdgeId(
   from: string,
   to: string,
-  mechanism: SubsystemEdgeMechanism,
+  mechanism: string,
 ): string {
   return `${from}--${mechanism}-->${to}`;
 }
@@ -412,6 +474,7 @@ 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 ?? []) {
@@ -439,6 +502,22 @@ export function deriveGraphEdges(doc: {
       }
     }
   }
+  for (const g of doc.graphifyRelations ?? []) {
+    const id = g.id || derivedGraphEdgeId(g.from, g.to, g.relation);
+    if (!byId.has(id)) {
+      byId.set(id, {
+        id,
+        from: g.from,
+        to: g.to,
+        mechanism: g.relation,
+        provenance: 'graphify',
+        refs: g.refs,
+        line: g.line,
+        confidence: g.confidence,
+        context: g.context,
+      });
+    }
+  }
   return [...byId.values()];
 }
 
@@ -450,11 +529,13 @@ 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;
 }
 
@@ -957,6 +1038,50 @@ export interface SubsystemGraphNodeData extends Record<string, unknown> {
   fileMatch?: boolean;
   /** True while this node is on an opened-but-unselected flow. */
   dimmed?: boolean;
+  /** Diagnostics badge — see `SubsystemNodeIssue`. Absent when no findings. */
+  issue?: SubsystemNodeIssue;
+}
+
+/**
+ * The per-construct verification ladder, in order. A finding's rung is the
+ * earliest step it fails: file → symbol → declaration → type → signature.
+ */
+export type SubsystemIssueRung =
+  | 'file'
+  | 'symbol'
+  | 'declaration'
+  | 'type'
+  | 'signature';
+
+/**
+ * Per-node diagnostics badge — the proposed issue overlay (severity ring +
+ * earliest-rung corner chip). The graph derives one per component from the
+ * audit issues whose component target resolves to that node. Absent when the
+ * node has no rung-mapped findings.
+ */
+export interface SubsystemNodeIssue {
+  /** Worst severity on the node — `error` (contradicts source) beats `info`. */
+  severity: 'error' | 'info';
+  /** Earliest failing rung across the node's findings. */
+  rung: SubsystemIssueRung;
+  /** Total findings on this node. */
+  count: number;
+}
+
+/**
+ * Per-frame diagnostics badge — a finding about the BOUNDARY itself (its
+ * containment / nesting), not about any member construct. Separate from
+ * `SubsystemNodeIssue` because these have no construct rung to report: the
+ * fault is the region's shape, which is also why it badges the frame rather
+ * than a leaf. `kind` selects the icon (see `ISSUE_KIND_ICON`).
+ */
+export interface SubsystemRegionIssue {
+  /** Worst severity across the region's findings — `error` beats `info`. */
+  severity: 'error' | 'info';
+  /** The kind that supplies the badge icon. */
+  kind: string;
+  /** Total findings on this region. */
+  count: number;
 }
 
 export interface SubsystemGroupNodeData extends Record<string, unknown> {
@@ -965,6 +1090,8 @@ export interface SubsystemGroupNodeData extends Record<string, unknown> {
   dimmed?: boolean;
   /** Host-supplied frame color override; falls back to the derived color. */
   color?: string;
+  /** Boundary diagnostics badge — see `SubsystemRegionIssue`. */
+  issue?: SubsystemRegionIssue;
 }
 
 export type SubsystemGraphNode =
@@ -972,8 +1099,17 @@ export type SubsystemGraphNode =
   | Node<SubsystemGroupNodeData, 'subsystem-group'>;
 
 export interface SubsystemGraphEdgeData extends Record<string, unknown> {
-  mechanism: SubsystemEdgeMechanism;
+  /** The edge verb (subsystem mechanism, or raw graphify relation). */
+  mechanism: string;
+  /** Origin of the edge; absent means `'subsystem'`. */
+  provenance?: SubsystemEdgeProvenance;
   refs?: string[];
+  /** 1-based source line of the relation site (graphify edges when known). */
+  line?: number;
+  /** graphify's provenance tag (`EXTRACTED` / `INFERRED` / `AMBIGUOUS`). */
+  confidence?: string;
+  /** Reference context on `references` edges (e.g. `return_type`, `field`). */
+  context?: string;
   /** True while another edge is selected — render this edge (and its label)
    *  dimmed to focus the selected relationship. */
   dimmed?: boolean;
@@ -1006,7 +1142,6 @@ export const SUBSYSTEM_RELATION_TYPES = [
   'implements',
   'mixes_in',
   'method',
-  'references',
 ] as const satisfies readonly SubsystemRelationType[];
 
 /** Runtime vocabulary of walkthrough hop mechanisms — mirrors `SubsystemWalkthroughMechanism`. */
@@ -1048,7 +1183,6 @@ export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
   mixes_in: '#d474a8', // pink-magenta
   uses: '#e3b341', // gold
   method: '#c586c0', // magenta
-  references: '#3b82f6', // blue
   feeds: '#4ec9b0', // teal — data-flow into a processor
   produces: '#a78bfa', // violet — emits an output type
   writes: '#e8853a', // orange — mutates retained state
@@ -1065,7 +1199,6 @@ export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed'
   mixes_in: 'dashed',
   uses: 'solid',
   method: 'solid',
-  references: 'dotted',
   feeds: 'solid',
   produces: 'solid',
   writes: 'solid',
@@ -1074,6 +1207,77 @@ export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed'
   'registers-into': 'dashed',
 };
 
+/** Fallback hue for a mechanism outside the closed palette (defensive — the
+ *  vocabulary is closed, so this only guards an unexpected verb from rendering
+ *  an undefined stroke). */
+export const MECHANISM_FALLBACK_COLOR = '#888888';
+
+/**
+ * graphify-native relation hues — a palette deliberately SEPARATE from
+ * `MECHANISM_COLOR`.
+ *
+ * graphify edges are derived from a static symbol graph, not authored subsystem
+ * semantics, so they get their own (cooler, desaturated) family and their own
+ * stroke treatment. Keeping the hue variables separate means a graphify fact
+ * can never be mistaken for a subsystem claim, and a new graphify verb can
+ * never accidentally inherit a mechanism hue.
+ *
+ * Keyed by graphify's relation verbs. Open-ended: graphify adds verbs, so an
+ * unlisted verb falls back to `GRAPHIFY_RELATION_FALLBACK_COLOR`.
+ */
+export const GRAPHIFY_RELATION_COLOR: Record<string, string> = {
+  contains: '#5c6b7a', // slate — structural containment
+  defines: '#6e7d8c', // steel — defines a member
+  imports: '#4c7fb5', // steel blue — module import
+  imports_from: '#6699cc', // lighter steel blue
+  re_exports: '#7b7fd4', // indigo — barrel re-export
+  dynamic_import: '#4f9aa8', // steel cyan — lazy import
+  indirect_call: '#8494a4', // grey — non-direct call
+  calls: '#3f9e78', // muted green — call-graph edge
+  uses: '#b0924e', // muted gold
+  references: '#5f7fa6', // dusty blue
+  extends: '#8c74b0', // muted violet
+  inherits: '#7a68a6', // muted violet (darker)
+  implements: '#a4739e', // muted mauve
+  method: '#a4739e', // muted mauve
+  decorator: '#b57fa0', // muted rose
+  rationale_for: '#bda15e', // muted ochre
+  semantically_similar_to: '#9a80bf', // muted lavender
+};
+
+/** Fallback hue for a graphify verb absent from `GRAPHIFY_RELATION_COLOR`. */
+export const GRAPHIFY_RELATION_FALLBACK_COLOR = '#7d8794';
+
+/**
+ * graphify-native edges share one stroke treatment so provenance still reads
+ * even where a hue happens to sit near a mechanism hue. Mirrors the
+ * `MECHANISM_STYLE` value space.
+ */
+export const GRAPHIFY_RELATION_STYLE: 'solid' | 'dashed' | 'dotted' = 'dashed';
+
+/** Resolve an edge's stroke color from its provenance + verb. */
+export function edgeColor(
+  edge: Pick<SubsystemComponentEdge, 'mechanism' | 'provenance'>,
+): string {
+  if (edge.provenance === 'graphify') {
+    return (
+      GRAPHIFY_RELATION_COLOR[edge.mechanism] ?? GRAPHIFY_RELATION_FALLBACK_COLOR
+    );
+  }
+  return (
+    MECHANISM_COLOR[edge.mechanism as SubsystemEdgeMechanism] ??
+    MECHANISM_FALLBACK_COLOR
+  );
+}
+
+/** Resolve an edge's dash treatment from its provenance + verb. */
+export function edgeStrokeStyle(
+  edge: Pick<SubsystemComponentEdge, 'mechanism' | 'provenance'>,
+): 'solid' | 'dashed' | 'dotted' {
+  if (edge.provenance === 'graphify') return GRAPHIFY_RELATION_STYLE;
+  return MECHANISM_STYLE[edge.mechanism as SubsystemEdgeMechanism] ?? 'solid';
+}
+
 /**
  * Region colors for process boundaries in the aggregate graph. Kept separate
  * from MECHANISM_COLOR on purpose: that palette encodes edge semantics on thin
@@ -1165,7 +1369,6 @@ export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][]
   ['mixes_in', 'applies mixin', true],
   ['uses', 'general dependency (import, call, or reference)', false],
   ['method', 'structural: has method / member', true],
-  ['references', 'type / symbol reference (not a call)', true],
   ['feeds', 'data flow: output feeds into input', false],
   ['produces', 'data flow: produces / outputs', false],
   ['writes', 'state access: mutates retained state', true],
@@ -1489,13 +1692,16 @@ export function convertSubsystemToGroups(
  * 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[] {
+export function convertSubsystemToEdges(
+  doc: SubsystemModelDocument,
+  graphifyRelations: readonly SubsystemGraphifyRelation[] = [],
+): SubsystemGraphEdge[] {
   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];
+  for (const e of deriveGraphEdges({ ...doc, graphifyRelations })) {
+    const color = edgeColor(e);
+    const style = edgeStrokeStyle(e);
     // If `to` is a real component, connect directly; otherwise point at a stub node.
     const isExternal = !compAliases.has(e.to);
     const targetId = isExternal ? `external:${e.to}` : e.to;
@@ -1504,7 +1710,14 @@ export function convertSubsystemToEdges(doc: SubsystemModelDocument): SubsystemG
       id: e.id,
       source: e.from,
       target: targetId,
-      data: { mechanism: e.mechanism, refs: e.refs },
+      data: {
+        mechanism: e.mechanism,
+        provenance: e.provenance,
+        refs: e.refs,
+        line: e.line,
+        confidence: e.confidence,
+        context: e.context,
+      },
       type: 'subsystem-edge',
       markerEnd: { type: MarkerType.ArrowClosed, color, width: 32, height: 32 },
       style: { color, stroke: color, strokeDasharray: style === 'dashed' ? '6 4' : undefined },
@@ -1520,7 +1733,9 @@ export function convertSubsystemToEdges(doc: SubsystemModelDocument): SubsystemG
 
 /** Stable key for layout-affecting graph fields (ignores declarationRef, etc.). */
 export function subsystemGraphLayoutKey(
-  doc: Pick<SubsystemModelDocument, 'components' | 'relations' | 'walkthroughs'>,
+  doc: Pick<SubsystemModelDocument, 'components' | 'relations' | 'walkthroughs'> & {
+    graphifyRelations?: readonly SubsystemGraphifyRelation[];
+  },
 ): string {
   const components = doc.components
     .map(({ alias, purl, name, symbol, construct, file, purpose, process, module }) =>
@@ -1546,6 +1761,18 @@ export async function buildSubsystemGraph(
     showEdgeLabels?: boolean;
     measuredWidths?: Map<string, number>;
     measuredHeights?: Map<string, number>;
+    /** graphify-native relations to merge into the display graph, drawn with
+     *  the separate graphify palette. Display-only; never authored. */
+    graphifyRelations?: readonly SubsystemGraphifyRelation[];
+    /**
+     * Order same-layer nodes by `component.line` (ascending) instead of ELK's
+     * crossing-minimizer. Only meaningful when components carry a `line` — and
+     * callers are expected to stamp `line` with the RELEVANT site for their
+     * graph (e.g. an ego graph stamps each callee with the center's call-site
+     * line, not the callee's declaration line).
+     * @default false
+     */
+    orderByLine?: boolean;
   } & BoundaryFrameOptions = {},
 ): Promise<{
   nodes: SubsystemGraphNode[];
@@ -1565,10 +1792,12 @@ export async function buildSubsystemGraph(
     measuredHeights,
     showSingletonFrames,
     packageFrames,
+    graphifyRelations,
+    orderByLine = false,
   } = opts;
   const frameOpts: BoundaryFrameOptions = { showSingletonFrames, packageFrames };
   const nodes = convertSubsystemToNodes(doc, { maxNodeWidth });
-  const edges = convertSubsystemToEdges(doc);
+  const edges = convertSubsystemToEdges(doc, graphifyRelations);
   // Nested boundary tree: package → process → module → leaves.
   const layoutGroups = buildBoundaryLayoutGroups(doc, frameOpts);
   const regions = layoutGroups.map((g) => g.region);
@@ -1602,7 +1831,7 @@ export async function buildSubsystemGraph(
   // cross-package edges have something to land on.
   const realAliases = new Set(doc.components.map((c) => c.alias));
   const externalIds: string[] = [];
-  for (const e of deriveGraphEdges(doc)) {
+  for (const e of deriveGraphEdges({ ...doc, graphifyRelations })) {
     if (!realAliases.has(e.to)) {
       const extId = `external:${e.to}`;
       if (!externalIds.includes(extId)) externalIds.push(extId);
@@ -1669,6 +1898,7 @@ export async function buildSubsystemGraph(
         interLayerSpacing: showEdgeLabels === false ? 120 : EDGE_LABEL_SIDE_PADDING,
         endpointInset: EDGE_ARROW_INSET,
         preserveNodePositions: false,
+        orderByLine,
         edgeLabels: showEdgeLabels === false ? { enabled: false } : { enabled: true, placement: 'CENTER' },
         groups: layoutGroups.map((g) => ({
           id: g.id,