@principal-ai/subsystems-react 0.53.6 → 0.54.0

package/src/subsystem/c4.ts

@@ -67,16 +67,22 @@ interface C4ElementBase {
   state: C4ElementState;
   /** Why this element is proposed as it is — shown in the confirm UI. */
   rationale?: string;
-  /** The component aliases this element groups. */
-  members?: string[];
-  /** Distinct constructs among the members, when resolved from a document. */
-  constructs?: string[];
-  /** Source model ids that contributed members, when attribution is supplied. */
-  models?: string[];
   /** When the state last changed (ISO). */
   decidedAt?: string;
 }
 
+/**
+ * The component aliases an element groups — the explicit member list.
+ *
+ * Only the kinds that have no `process` claim to resolve members from carry
+ * one: an external system (its few aliases) and an authored C4 component (the
+ * aliases it groups). A container's members are *derived* from its `process`
+ * claim against the model document, never stored here.
+ */
+interface C4MemberList {
+  members?: string[];
+}
+
 /**
  * What kind of thing a container is.
  *
@@ -112,7 +118,7 @@ export interface C4Container extends C4ElementBase {
  * split across containers (an RPC bridge with a renderer half and a host half),
  * which is precisely the case worth being able to state.
  */
-export interface C4Component extends C4ElementBase {
+export interface C4Component extends C4ElementBase, C4MemberList {
   kind: 'component';
   /** The id of the container this component sits inside. */
   container: string;
@@ -120,7 +126,7 @@ export interface C4Component extends C4ElementBase {
   technology: string;
 }
 /** A software system outside the boundary we are drawing. */
-export interface C4ExternalSystem extends C4ElementBase {
+export interface C4ExternalSystem extends C4ElementBase, C4MemberList {
   kind: 'external-system';
   /** Often unknown for a third-party system, so optional here. */
   technology?: string;
@@ -223,6 +229,21 @@ export function deriveC4Groups(
   return groups;
 }
 
+/**
+ * One trail contributing steps to a rolled-up C4 edge — the drill-down
+ * provenance that lets a line on the C4 diagram answer "which trail steps
+ * implement this?".
+ *
+ * Deliberately ids only: the host owns the trail document and can resolve
+ * titles, so this stays a pointer instead of duplicating content.
+ */
+export interface C4TrailRef {
+  /** Trail id in the subsystem model document, e.g. `tl-audit`. */
+  trailId: string;
+  /** Indices into `trail.steps` of the steps that cross this edge's endpoints. */
+  stepIndices: number[];
+}
+
 /**
  * A line between two elements. Authored, like the boxes.
  *
@@ -230,6 +251,12 @@ export function deriveC4Groups(
  * interaction (`protocol`), and the label is that plus the trail verbs where
  * known. `label` is what the chip shows; `protocol` and `mechanisms` are kept
  * separate so a caller can render either.
+ *
+ * `count` / `mechanisms` / `trailRefs` are the rolled-up view of the same line:
+ * how many component-level steps produced it (union of the referenced steps),
+ * which verbs they used, and — when a builder supplied provenance — exactly
+ * which trails/steps. All three are derived data riding an authored line, so
+ * they are optional: an authored edge may carry none until a rollup has run.
  */
 export interface C4Edge {
   id: string;
@@ -243,6 +270,12 @@ export interface C4Edge {
   mechanisms: string[];
   /** How many underlying steps this line rolled up. */
   count: number;
+  /**
+   * The trails whose steps cross this edge's endpoints. The drill-down bridge:
+   * a reader clicks the line, gets these refs, and jumps into the component
+   * graph's trail focus. Absent on an authored line no rollup has run over.
+   */
+  trailRefs?: C4TrailRef[];
 }
 
 /**

package/src/subsystem/declarationRef.ts

@@ -1,27 +1,31 @@
 /**
- * Declaration anchoring — start-line + single-line content hash.
+ * Source-span anchoring — a content-addressed range of source.
  *
- * Graphify emits `source_location: "L42"` (declaration start line). We capture
- * that line's normalized text as a fingerprint to detect drift without end-line
- * spans or graphify changes.
+ * A span is `startLine` + `endLine` + a hash of the normalized content across
+ * that range. The type is owned by `@principal-ai/subsystems-core` (the
+ * portable standard); this module re-exports it and provides the line helpers
+ * shared by the renderers and host-side hashing.
+ *
+ * Graphify emits `source_location: "L42"` (a start line only); the end line is
+ * derived by verification, and `hashContentRange` (host-side) produces the
+ * `contentHash`.
  */
 
-/** Persisted anchor for a subsystem component's source declaration. */
-export interface SubsystemDeclarationRef {
-  /** Repo-root-relative path (matches `component.file`). */
-  file: string;
-  /** 1-based declaration start line (from graphify `source_location`). */
-  startLine: number;
-  /** SHA-256 of {@link normalizeDeclarationLine} output, truncated to 32 hex chars. */
-  lineHash: string;
-  /** Graphify node id when captured from an exact anchor. */
-  graphifyNodeId?: string;
-  /** ISO timestamp when this ref was recorded. */
-  capturedAt: string;
-}
+import type { SubsystemSourceSpan } from '@principal-ai/subsystems-core';
 
-export type DeclarationFreshness =
-  | 'fresh'
+export type { SubsystemSourceSpan };
+
+/**
+ * How fresh an anchored span is, as computed by verification.
+ *
+ * - `full` — the span (start + end + hash) is present and live content matches.
+ * - `stale` — present, but the content or position drifted.
+ * - `missing` — present, but the range no longer resolves.
+ * - `unanchored` — no span captured yet.
+ * - `unchecked` — source unreadable / repo unresolved.
+ */
+export type SpanFreshness =
+  | 'full'
   | 'stale'
   | 'missing'
   | 'unanchored'
@@ -55,6 +59,11 @@ export function extractDeclarationLine(content: string, lineNumber: number): str
 export interface SubsystemOpenFileOptions {
   /** Scroll/highlight this 1-based line (declaration start or trail site). */
   startLine?: number;
+  /**
+   * End of the anchored span, when the owner carries one. Lets the snippet
+   * window show the construct's full extent instead of a single line.
+   */
+  endLine?: number;
   /**
    * When true with `startLine`, show the whole file scrolled to that line
    * instead of a focused snippet window.

package/src/subsystem/model.test.ts

@@ -61,7 +61,6 @@ const trails: SubsystemTrail[] = [
         to: 'reader',
         mechanism: 'calls',
         file: 'transcript.ts',
-        line: 1,
         purl: 'pkg:github/principal-ai/agent-monitoring#transcript.ts',
         symbol: 'transcript',
       },
@@ -70,7 +69,6 @@ const trails: SubsystemTrail[] = [
         to: 'host',
         mechanism: 'calls',
         file: 'SessionReader.ts',
-        line: 1,
         purl: 'pkg:github/principal-ai/agent-monitoring#SessionReader.ts',
         symbol: 'SessionReader',
       },
@@ -112,7 +110,7 @@ describe('subsystem graph model', () => {
       trails: [{
         id: 'w1',
         title: 'feed',
-        steps: [{ from: 'reader', to: 'proposed-watcher', mechanism: 'feeds', file: 'x.ts', line: 1 }],
+        steps: [{ from: 'reader', to: 'proposed-watcher', mechanism: 'feeds', file: 'x.ts' }],
       }],
     });
     expect(nodes.find((n) => n.id === 'proposed-watcher')).toBeDefined();
@@ -455,7 +453,7 @@ describe('subsystem graph model', () => {
       trails: [{
         id: 'w1',
         title: 'call',
-        steps: [{ from: 'a', to: 'b', mechanism: 'calls', file: 'a.ts', line: 1 }],
+        steps: [{ from: 'a', to: 'b', mechanism: 'calls', file: 'a.ts' }],
       }],
     });
     expect(regions.map((r) => r.key)).toEqual(['app/host']);
@@ -463,6 +461,30 @@ describe('subsystem graph model', () => {
     expect(nodes.find((n) => n.id === processGroupNodeId('app/lonely'))).toBeUndefined();
   });
 
+  test('codeProcessKeys marks a process region for package chrome without changing its identity', async () => {
+    const { regions, nodes } = await buildSubsystemGraph(
+      {
+        components: [
+          { 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' },
+          // Singleton, kept — the component graph passes showSingletonFrames
+          // true, and the fixture's real singleton (`subsystems-react/ui`)
+          // is exactly the demotion case.
+          { alias: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'lib/ui' },
+        ],
+        trails: [],
+      },
+      { showSingletonFrames: true, codeProcessKeys: new Set(['lib/ui']) },
+    );
+    const lib = regions.find((r) => r.key === 'lib/ui');
+    // Presentation only: kind stays 'process', so the group id and issue
+    // targeting still read the claim.
+    expect(lib?.kind).toBe('process');
+    expect(lib?.chrome).toBe('package');
+    expect(regions.find((r) => r.key === 'app/host')?.chrome).toBeUndefined();
+    expect(nodes.some((n) => n.id === processGroupNodeId('lib/ui'))).toBe(true);
+  });
+
   // NOTE: buildSubsystemGraph cannot assert ELK-built frames here — elkjs
   // constructs a Worker, which bun's test env lacks, so every call falls back
   // to manual positions. Frame existence is covered by planCompoundGroups
@@ -792,25 +814,24 @@ describe('subsystem graph model', () => {
     }
   });
 
-  test('subsystemGraphLayoutKey ignores declarationRef-only changes', () => {
+  test('subsystemGraphLayoutKey ignores declarationSpan-only changes', () => {
     const base = doc;
-    const withRef = {
+    const withSpan = {
       components: comps.map((c, i) =>
         i === 0
           ? {
               ...c,
-              declarationRef: {
-                file: c.file,
+              declarationSpan: {
                 startLine: 42,
-                lineHash: 'abc',
-                capturedAt: new Date(0).toISOString(),
+                endLine: 48,
+                contentHash: 'abc',
               },
             }
           : c,
       ),
       trails,
     };
-    expect(subsystemGraphLayoutKey(base)).toBe(subsystemGraphLayoutKey(withRef));
+    expect(subsystemGraphLayoutKey(base)).toBe(subsystemGraphLayoutKey(withSpan));
   });
 });
 
@@ -845,7 +866,6 @@ describe('isConstructsOnlyModel', () => {
                 to: 'reader',
                 mechanism: 'calls',
                 file: 'transcript.ts',
-                line: 1,
               },
             ],
           },

package/src/subsystem/model.ts

@@ -441,6 +441,15 @@ export interface SubsystemProcessRegion {
   label: string;
   /** Component ids that are members of this region. */
   memberAliases: string[];
+  /**
+   * Presentation override: `'package'` draws the frame with package chrome —
+   * rounded, dashed, transparent — instead of the solid runtime chrome
+   * process frames carry. For a process region the host judged code
+   * organisation (a library, an area, a proposal) rather than an accepted
+   * deployment unit. Presentation only: `kind`, node id, issue targeting and
+   * membership still read the claim as a process region.
+   */
+  chrome?: 'package';
 }
 
 /** Options for which boundary frames are kept. */
@@ -466,6 +475,15 @@ export interface BoundaryFrameOptions {
    *   and module frames.
    */
   moduleNesting?: 'exact' | 'path';
+  /**
+   * Process keys whose frames draw package chrome (rounded, dashed) instead
+   * of runtime chrome (square, solid) — the host's judgment that these claims
+   * group code organisation (a library, an area, a proposal), not an accepted
+   * deployment unit. Typically derived from the accepted C4 element set: a
+   * process no container or external backs is code, not a box. Presentation
+   * only — region identity and issue targeting are unchanged.
+   */
+  codeProcessKeys?: ReadonlySet<string>;
 }
 
 /** React Flow id for a process boundary group node. */
@@ -1830,7 +1848,7 @@ export function convertSubsystemToEdges(
   return edges;
 }
 
-/** Stable key for layout-affecting graph fields (ignores declarationRef, etc.). */
+/** Stable key for layout-affecting graph fields (ignores declarationSpan, etc.). */
 export function subsystemGraphLayoutKey(
   doc: Pick<SubsystemModelDocument, 'components' | 'trails'> & {
     graphifyRelations?: readonly SubsystemGraphifyRelation[];
@@ -1894,6 +1912,7 @@ export async function buildSubsystemGraph(
     moduleNesting,
     graphifyRelations,
     orderByLine = false,
+    codeProcessKeys,
   } = opts;
   const frameOpts: BoundaryFrameOptions = {
     showSingletonFrames,
@@ -1904,6 +1923,16 @@ export async function buildSubsystemGraph(
   const edges = convertSubsystemToEdges(doc, graphifyRelations);
   // Nested boundary tree: package → process → module → leaves.
   const layoutGroups = buildBoundaryLayoutGroups(doc, frameOpts);
+  // Demote host-judged code regions after grouping (both nesting variants
+  // return through this call), keeping `kind` intact so ids and issue
+  // targeting still read the process claim.
+  if (codeProcessKeys?.size) {
+    for (const g of layoutGroups) {
+      if (g.region.kind === 'process' && codeProcessKeys.has(g.region.key)) {
+        g.region = { ...g.region, chrome: 'package' };
+      }
+    }
+  }
   const regions = layoutGroups.map((g) => g.region);
   const regionIds = new Set(layoutGroups.map((g) => g.id));
   const byAlias = new Map(doc.components.map((c) => [c.alias, c]));

package/src/subsystem/nodes.group.test.tsx

@@ -63,6 +63,88 @@ describe('SubsystemGroupNode frame color', () => {
   });
 });
 
+describe('SubsystemGroupNode chrome', () => {
+  // Runtime chrome asserts "deployment unit": square, solid, tinted. A
+  // process region the host marked `chrome: 'package'` groups code
+  // organisation instead — a library, an area, a proposal — and draws as a
+  // package boundary: rounded, dashed, transparent.
+  test('a plain process region wears runtime chrome', () => {
+    const { container } = renderGroup({ region });
+    const frame = container.querySelector('div') as HTMLElement;
+    expect(frame.style.border).toContain('solid');
+    expect(frame.style.borderRadius).toBe('0px');
+    expect(frame.style.background).not.toBe('transparent');
+  });
+
+  test("chrome: 'package' draws the frame as a code boundary", () => {
+    const { container } = renderGroup({
+      region: { ...region, chrome: 'package' },
+    });
+    const frame = container.querySelector('div') as HTMLElement;
+    expect(frame.style.border).toContain('dashed');
+    expect(frame.style.borderRadius).toBe('12px');
+    expect(frame.style.background).toBe('transparent');
+  });
+
+  test('chrome does not change the region identity the frame renders', () => {
+    const { container } = renderGroup({
+      region: { ...region, chrome: 'package' },
+    });
+    // The badge still reads the label — kind is chrome's business alone.
+    expect(container.textContent).toContain('booking-web/server');
+  });
+});
+
+describe('SubsystemGroupNode package glyph', () => {
+  // A frame that renders as a package boundary wears the Package glyph: a
+  // real package (purl repo identity) or a process claim the host demoted to
+  // package chrome. Module/directory/plain-process frames stay text-only —
+  // the glyph is what tells the shared dashed chrome "code organisation, not
+  // a deployment unit".
+  test('a package-kind region wears the glyph', () => {
+    const { container } = renderGroup({
+      region: {
+        kind: 'package',
+        key: 'pkg:github/acme/app',
+        label: 'acme/app',
+        memberAliases: ['a', 'b'],
+      },
+    });
+    expect(container.querySelector('.lucide-package')).not.toBeNull();
+  });
+
+  test("a process region demoted to package chrome wears the glyph", () => {
+    const { container } = renderGroup({
+      region: { ...region, chrome: 'package' },
+    });
+    expect(container.querySelector('.lucide-package')).not.toBeNull();
+  });
+
+  test('plain process, module, and directory regions carry no glyph', () => {
+    expect(renderGroup({ region }).container.querySelector('.lucide-package')).toBeNull();
+    expect(
+      renderGroup({
+        region: {
+          kind: 'module',
+          key: 'src/bun/index.ts',
+          label: 'src/bun/index.ts',
+          memberAliases: ['a', 'b'],
+        },
+      }).container.querySelector('.lucide-package'),
+    ).toBeNull();
+    expect(
+      renderGroup({
+        region: {
+          kind: 'directory',
+          key: 'src/bun',
+          label: 'src/bun',
+          memberAliases: ['a', 'b'],
+        },
+      }).container.querySelector('.lucide-package'),
+    ).toBeNull();
+  });
+});
+
 describe('SubsystemGroupNode boundary badge', () => {
   // A boundary finding is a property of the region's shape, so it badges the
   // frame with its own icon rather than borrowing the verification-rung chips

package/src/subsystem/nodes.tsx

@@ -46,7 +46,7 @@ import {
 import { componentColor } from '../pierre/constructColors';
 import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
 import { ISSUE_KIND_ICON, ISSUE_RUNG_ICON } from './IssueList';
-import { Search } from 'lucide-react';
+import { Package, Search } from 'lucide-react';
 import type { LucideIcon } from 'lucide-react';
 
 export const CONSTRUCT_LABEL: Record<string, string> = {
@@ -592,7 +592,18 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
   // Directory frames (path-derived nesting) render like modules — dashed,
   // collapsible path badge.
   const isModule = region?.kind === 'module' || region?.kind === 'directory';
-  const isProcess = region?.kind === 'process';
+  // Runtime chrome asserts "deployment unit" — a process region the host
+  // marked `chrome: 'package'` groups code organisation instead (a library,
+  // an area, a proposal) and forgoes it, drawing like a package frame.
+  // Presentation only: `kind` still says process, so ids and issue targets
+  // key off the claim unchanged.
+  const isProcess = region?.kind === 'process' && region?.chrome !== 'package';
+  // A frame renders as a package boundary two ways: it IS a package (repo
+  // identity from `purl`) or the host demoted a process claim to package
+  // chrome (a library, an area, a proposal). Both wear the Package glyph, so
+  // "code organisation, not a deployment unit" reads off the canvas instead
+  // of hiding in the shared rounded/dashed chrome.
+  const isPackageFrame = region?.kind === 'package' || region?.chrome === 'package';
   const expanded = isModule && expandedLabel === label;
   const availableBadgeWidth = Math.max(0, (width ?? 400) - MODULE_BADGE_INSET * 2 - 4);
   const collapsedLabel = isModule ? moduleBadgeLabel(label, availableBadgeWidth) : label;
@@ -707,8 +718,25 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
                 maxWidth: expanded ? undefined : availableBadgeWidth,
               }
             : undefined),
+          ...(isPackageFrame
+            ? {
+                // Icon + key on one row: the Package glyph leads the label
+                // so package chrome reads as code organisation at a glance.
+                display: 'inline-flex',
+                alignItems: 'center',
+                gap: 5,
+              }
+            : undefined),
         }}
       >
+        {isPackageFrame && (
+          <Package
+            size={13}
+            strokeWidth={2}
+            aria-hidden="true"
+            style={{ flexShrink: 0 }}
+          />
+        )}
         {canToggle ? (
           <span style={{ whiteSpace: 'nowrap' }}>
             {expanded ? label : hover ? hoveredLabel : collapsedLabel}

package/src/subsystem/trailBrief.test.ts

@@ -11,7 +11,7 @@ const trail: SubsystemTrail = {
       to: 'api',
       mechanism: 'calls',
       file: 'src/ui/login.tsx',
-      line: 42,
+      span: { startLine: 42, endLine: 42, contentHash: 'h' },
       purl: 'pkg:github/acme/app',
       symbol: 'Login.submit',
     },
@@ -20,7 +20,7 @@ const trail: SubsystemTrail = {
       to: 'store',
       mechanism: 'writes',
       file: 'src/api/session.ts',
-      line: 7,
+      span: { startLine: 7, endLine: 7, contentHash: 'h' },
       purl: 'pkg:github/acme/app',
       symbol: 'Session.create',
       annotation: 'session row is written here',

package/src/subsystem/trailBrief.ts

@@ -31,7 +31,12 @@ export function buildStepBrief(
   lines.push(`- to: \`${step.to}\``);
   lines.push(`- mechanism: \`${step.mechanism}\``);
   lines.push(`- symbol: \`${step.symbol}\``);
-  lines.push(`- site: \`${step.file}:${step.line}\``);
+  const site = step.span
+    ? step.span.startLine === step.span.endLine
+      ? `${step.file}:${step.span.startLine}`
+      : `${step.file}:${step.span.startLine}-${step.span.endLine}`
+    : step.file;
+  lines.push(`- site: \`${site}\``);
   lines.push(`- purl: \`${step.purl}\``);
   if (step.annotation != null && step.annotation.length > 0) {
     lines.push(`- note: ${step.annotation}`);