@principal-ai/subsystems-react 0.50.0 → 0.51.1

package/src/subsystem/c4Evidence.ts

@@ -0,0 +1,329 @@
+/**
+ * C4 evidence — what an agent needs in order to propose elements.
+ *
+ * This module does not decide anything. It answers "what is worth asking
+ * about?" so an agent can go and read the source, then propose a
+ * `C4Element` with a rationale. The questions come from the C4 notation
+ * rules the document cannot satisfy on its own:
+ *
+ *   - every container needs a technology
+ *   - every element needs a description
+ *   - a container is a runtime boundary, so a library is not one
+ *   - a container cannot straddle two software systems
+ *
+ * The output is a set of concerns. Resolving one is the agent's job, and the
+ * answer lands in an element's `rationale`.
+ */
+
+import type { C4Container, C4ContainerKind, C4Element, C4ElementSet } from './c4';
+
+/** What a concern is about — a derived key, or an existing element id. */
+export interface C4Concern {
+  /** The process key, module path, or element id this concerns. */
+  target: string;
+  kind: C4ConcernKind;
+  message: string;
+  /** Aliases that triggered it. */
+  members?: string[];
+}
+
+/**
+ * The questions worth a human's attention.
+ *
+ * Each maps to something an agent cannot settle by reading a string — it has
+ * to open the source, or ask the user.
+ */
+export type C4ConcernKind =
+  /** two or more process keys may be the same deployable unit */
+  | 'merge_candidate'
+  /** exactly one member — a lone function is not a deployable unit */
+  | 'singleton'
+  /** no member executes at runtime — a library is not a container */
+  | 'library_shaped'
+  /** a store whose storage kind was never decided */
+  | 'store_unclassified'
+  /** members claim more than one repo — a container cannot straddle systems */
+  | 'spans_repos'
+  /** an external with no resolvable identity */
+  | 'external_unidentified'
+  /** a runtime component with no process at all */
+  | 'unassigned'
+  /** C4 requires technology on every container */
+  | 'missing_technology';
+
+/** The fields a concern check reads off a component. */
+export interface C4MemberView {
+  alias: string;
+  construct: string;
+  purl: string;
+  process?: string;
+  framework?: string;
+  module?: string;
+  role?: string;
+  declaration?: unknown;
+}
+
+/** Constructs that execute at runtime — the only things a container can be. */
+const RUNTIME_CONSTRUCTS = new Set(['function', 'class', 'custom_entity']);
+
+function storageOf(m: C4MemberView): string | undefined {
+  const d = m.declaration as { kind?: string; storage?: string } | undefined;
+  return d?.kind === 'store' ? d.storage : undefined;
+}
+
+/** True when a component runs, and so can be part of a deployable unit. */
+export function isRuntimeConstruct(construct: string): boolean {
+  return RUNTIME_CONSTRUCTS.has(construct);
+}
+
+/**
+ * Derive the questions worth asking about one candidate element.
+ *
+ * Pure over the rollup, so it runs identically against a single model, the 40
+ * composed models, or a fixture. Pure *questions* — it never proposes an
+ * answer, because the answers are architectural.
+ */
+export function deriveConcerns(
+  key: string,
+  members: readonly C4MemberView[],
+  tech: { frameworks: readonly string[] } = { frameworks: [] },
+): C4Concern[] {
+  const out: C4Concern[] = [];
+  const aliases = members.map((m) => m.alias);
+  const runtime = members.filter((m) => isRuntimeConstruct(m.construct));
+
+  if (members.length === 1) {
+    out.push({
+      target: key,
+      kind: 'singleton',
+      message: `process "${key}" has exactly one member (${aliases[0]}) — a lone function is not a deployable unit`,
+      members: aliases,
+    });
+  }
+
+  // No member executes at runtime ⇒ this cannot be a deployable unit,
+  // regardless of how many members it has. A lone interface and a package of
+  // interfaces fail the same way.
+  if (members.length > 0 && runtime.length === 0) {
+    out.push({
+      target: key,
+      kind: 'library_shaped',
+      message: `process "${key}" has ${members.length} member(s) but none execute at runtime (${[...new Set(members.map((m) => m.construct))].join(', ')}) — this reads as a library, not a container`,
+      members: aliases,
+    });
+  }
+
+  if (runtime.length > 0 && tech.frameworks.length === 0) {
+    out.push({
+      target: key,
+      kind: 'missing_technology',
+      message: `container "${key}" has no framework signal — C4 requires a technology on every container`,
+      members: aliases,
+    });
+  }
+
+  const repos = new Set(
+    members
+      .map((m) => (m.purl ?? '').split('#')[0])
+      .filter((r) => r && !r.startsWith('external:')),
+  );
+  if (repos.size > 1) {
+    out.push({
+      target: key,
+      kind: 'spans_repos',
+      message: `process "${key}" spans ${repos.size} repo keys (${[...repos].join(', ')}) — a C4 container cannot straddle a system boundary`,
+      members: aliases,
+    });
+  }
+
+  const unclassified = members.filter((m) => m.construct === 'store' && !storageOf(m));
+  if (unclassified.length > 0) {
+    out.push({
+      target: key,
+      kind: 'store_unclassified',
+      message: `${unclassified.length} store(s) in "${key}" declare no storage kind (${unclassified.map((m) => m.alias).join(', ')}) — decide whether each is a C4 data store or an internal detail`,
+      members: unclassified.map((m) => m.alias),
+    });
+  }
+
+  const unidentified = members.filter(
+    (m) => m.construct === 'external' && (!m.purl || m.purl === 'external' || m.purl.startsWith('external:proposed')),
+  );
+  if (unidentified.length > 0) {
+    out.push({
+      target: key,
+      kind: 'external_unidentified',
+      message: `${unidentified.length} external(s) have no resolvable identity (${unidentified.map((m) => m.alias).join(', ')}) — a C4 box named "external" is not a diagram`,
+      members: unidentified.map((m) => m.alias),
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Suggest merges between keys that share a trailing role.
+ *
+ * `subsystems-studio/host` and `principal-studio/host` are the same role under
+ * two app names. This is a *question*, never a merge — only the user knows
+ * whether they are one process or two.
+ */
+export function suggestMerges(
+  rollup: ReadonlyArray<{ key: string; memberCount: number }>,
+): Array<{ role: string; keys: string[]; reason: string }> {
+  const byRole = new Map<string, string[]>();
+  for (const { key } of rollup) {
+    const slash = key.lastIndexOf('/');
+    if (slash <= 0) continue; // a bare key has no app/role shape
+    const role = key.slice(slash + 1);
+    const list = byRole.get(role) ?? [];
+    list.push(key);
+    byRole.set(role, list);
+  }
+  const out: Array<{ role: string; keys: string[]; reason: string }> = [];
+  for (const [role, keys] of [...byRole].sort((a, b) => a[0].localeCompare(b[0]))) {
+    if (keys.length < 2) continue;
+    out.push({
+      role,
+      keys: [...keys].sort(),
+      reason: `${keys.length} process keys end in "/${role}" (${[...keys].sort().join(', ')}) — one deployable unit under two names, or two units?`,
+    });
+  }
+  return out;
+}
+
+/**
+ * Runtime components that state no `process` at all.
+ *
+ * These are the components an agent cannot place by inference, because there
+ * is nothing to infer from. They are a standing question, not a per-element
+ * concern.
+ */
+export function findUnassigned(members: readonly C4MemberView[]): C4MemberView[] {
+  return members.filter((m) => !m.process && isRuntimeConstruct(m.construct));
+}
+
+/**
+ * Fold a decided merge into an element set.
+ *
+ * Two process keys that are really one container become ONE element holding
+ * both sets of members. The survivor keeps the id, label, and confirmed
+ * attributes; the other disappears and its members move across.
+ *
+ * Which side survives is the **evidence-heavy** one — the element holding more
+ * members — because folding the 113-member host into the 1-member one would
+ * leave the box labelled after an almost-empty process and lose its confirmed
+ * technology. Pass `preferId` to override.
+ *
+ * Returns a new set; the input is untouched. Idempotent.
+ */
+export function mergeElements(
+  elements: readonly C4Element[],
+  derivedFromKeys: readonly string[],
+  preferId?: string,
+  memberCountByKey?: ReadonlyMap<string, number>,
+): C4Element[] {
+  const wanted = new Set(derivedFromKeys.map((k) => k.trim()).filter(Boolean));
+  if (wanted.size < 2) return [...elements];
+
+  const involved = elements.filter((e) => e.derivedFrom?.some((k) => wanted.has(k)));
+  if (involved.length < 2) return [...elements];
+  // Only containers merge. A component has a required `container` field, and
+  // folding one into another would silently repoint it at a new parent.
+  if (involved.some((e) => e.kind !== 'container')) return [...elements];
+
+  const weight = (e: C4Element): number => {
+    if (memberCountByKey) {
+      let n = 0;
+      for (const k of e.derivedFrom ?? []) n += memberCountByKey.get(k) ?? 0;
+      return n;
+    }
+    return e.members.length;
+  };
+
+  const survivor =
+    (preferId ? involved.find((e) => e.id === preferId) : undefined) ??
+    [...involved].sort((a, b) => weight(b) - weight(a) || a.id.localeCompare(b.id))[0]!;
+
+  const absorbed = involved.filter((e) => e.id !== survivor.id);
+  const absorbedIds = new Set(absorbed.map((e) => e.id));
+
+  const merged: C4Container = {
+    ...(survivor as C4Container),
+    members: [...new Set([...survivor.members, ...absorbed.flatMap((e) => e.members)])],
+    derivedFrom: [
+      ...new Set([...(survivor.derivedFrom ?? []), ...absorbed.flatMap((e) => e.derivedFrom ?? [])]),
+    ],
+    rationale:
+      [survivor.rationale, ...absorbed.map((e) => e.rationale)].filter(Boolean).join(' | ') ||
+      undefined,
+  };
+
+  return [...elements.filter((e) => e.id !== survivor.id && !absorbedIds.has(e.id)), merged].sort(
+    (a, b) => a.id.localeCompare(b.id),
+  );
+}
+
+/**
+ * A starting point for an agent: one proposed element per derived key, shaped
+ * by the mechanical evidence, with the open questions in the rationale.
+ *
+ * Every element comes back `proposed`. This is a scaffold to edit and argue
+ * with — not an answer, and never `accepted`.
+ */
+export function proposeElements(
+  options: {
+    repoKey: string;
+    rollup: ReadonlyArray<{ key: string; members: readonly C4MemberView[]; frameworks: readonly string[] }>;
+    author?: string;
+  },
+): C4ElementSet {
+  const elements = options.rollup.map(({ key, members, frameworks }) => {
+    const concerns = deriveConcerns(key, members, { frameworks });
+    return {
+      id: `container:${key}`,
+      kind: 'container' as const,
+      members: members.map((m) => m.alias),
+      derivedFrom: [key],
+      label: key,
+      containerKind: suggestContainerKind(members),
+      // C4 requires a technology on every container. With no framework signal
+      // the honest value is empty and `summarizeElements` reports the gap —
+      // inventing "TypeScript" here would be exactly the derivation this
+      // module stopped doing.
+      technology: frameworks.length > 0 ? frameworks.join(' + ') : '',
+      state: 'proposed' as const,
+      rationale: concerns.map((c) => c.message).join(' ') || undefined,
+      author: options.author,
+    };
+  });
+
+  return {
+    repoKey: options.repoKey,
+    elements: elements.sort((a, b) => a.id.localeCompare(b.id)),
+  };
+}
+
+/**
+ * A first guess at what sort of container this is, offered as a *default* for
+ * the agent to override.
+ *
+ * Note there is no `library` answer, even for a library-shaped group. C4 says
+ * a module "typically" is not an element at all, so the honest response to a
+ * library is a review comment: the `library_shaped` concern carries the
+ * question, and the element is proposed as `application` for a person to
+ * reject or demote. There is deliberately no `concerns` parameter here for the
+ * caller to consult — passing one would only invite a fifth kind back into the
+ * vocabulary.
+ *
+ * The store split is deliberately conservative: only durable storage becomes
+ * `data-store`, because over-claiming that is the more damaging error.
+ */
+export function suggestContainerKind(members: readonly C4MemberView[]): C4ContainerKind {
+  const stores = members.filter((m) => m.construct === 'store');
+  if (stores.length > 0) {
+    const persists = stores.some((m) => storageOf(m) === 'external' || storageOf(m) === 'disk');
+    return persists ? 'data-store' : 'application';
+  }
+  return 'application';
+}

package/src/subsystem/model.ts

@@ -20,7 +20,10 @@ import {
 import { computeElkLayout, calculatePathLength } from '../utils/elkLayout';
 import { EDGE_LABEL_SIDE_PADDING, EDGE_ARROW_INSET } from '../utils/edgeLabel';
 import type { GraphifyComponentDetail } from '../graphify';
-import type { SubsystemConstructDeclaration } from '@principal-ai/subsystems-core';
+import type {
+  SubsystemConstructDeclaration,
+  SubsystemComponentRemoval,
+} from '@principal-ai/subsystems-core';
 import type { SubsystemDeclarationRef } from './declarationRef';
 import { purlOwnerName, purlRepoKey } from './paths';
 
@@ -242,6 +245,15 @@ export interface SubsystemComponent {
    * `construct` (intended shape) and `role` (topology).
    */
   proposed?: boolean;
+  /**
+   * The claim was real but its source is gone upstream — deleted or renamed.
+   * The inverse of `proposed`; verification skips source checks the same way.
+   * Renders with a slate border and a `deprecated` badge that opens the removal
+   * provenance. Transitional — a cleanup pass removes the node.
+   */
+  deprecated?: boolean;
+  /** Which commit removed this claim's source, and why. Present when deprecated. */
+  removedIn?: SubsystemComponentRemoval;
   /**
    * Semantic role — where the node sits in the topology (boundary element,
    * external system), orthogonal to `construct` (what it is). Drives the
@@ -312,12 +324,8 @@ export interface SubsystemComponent {
    */
   declaration?: SubsystemConstructDeclaration;
   /**
-   * Where the structured `declaration` came from. `verified` = extracted from
-   * source by tooling (graphify AST, signature extraction) — may be trusted
-   * as matching the code. `authored` = written by the authoring agent/human
-   * to highlight specific inputs/outputs — informative, not checked against
-   * source. Declaration without provenance is treated as `authored`; only
-   * tooling may claim `verified`.
+   * @deprecated No longer used — verification now tracks at the model level
+   * via `verifiedAtCommits`. Keeping the field temporarily for migration.
    */
   declarationProvenance?: SubsystemDeclarationProvenance;
   /**
@@ -1706,6 +1714,25 @@ export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
 /** Right-badge accent for `proposed: true` (no role, or combined with role). */
 export const PROPOSED_COLOR = '#b8860b'; // darkgoldenrod — not-yet-in-source
 
+/**
+ * Border accent for `deprecated: true` — the claim was real, its source is gone.
+ * A desaturated slate rather than true silver: role badges already own silver
+ * (`ROLE_COLOR.entry`), and a retired claim should not read as a boundary
+ * element. Transitional state — a cleanup pass removes the node.
+ */
+export const DEPRECATED_COLOR = '#6b7280'; // slate — retired, awaiting removal
+
+/** Right-badge label + accent for `deprecated: true`; null when not deprecated. */
+export function deprecatedBadgeLabel(component: { deprecated?: boolean }): string | null {
+  return component.deprecated === true ? 'deprecated' : null;
+}
+
+export function deprecatedBadgeColor(component: {
+  deprecated?: boolean;
+}): string | null {
+  return component.deprecated === true ? DEPRECATED_COLOR : null;
+}
+
 /**
  * Top-right badge label: proposed wins over role when both are set
  * (proposed is the temporary exception to scan for; role stays on the model).
@@ -1851,6 +1878,7 @@ export function nodeMinWidthForBadges(component: {
   stereotype?: string;
   role?: SubsystemComponentRole;
   proposed?: boolean;
+  deprecated?: boolean;
   entityKind?: string;
   declaration?: AnyComponentDetail;
 }): number {
@@ -1858,6 +1886,7 @@ export function nodeMinWidthForBadges(component: {
   const rightBadges = [
     storageBadgeLabel(component),
     rightBadgeLabel(component),
+    deprecatedBadgeLabel(component),
   ].filter((l): l is string => l != null);
   if (rightBadges.length === 0) {
     return Math.max(

package/src/subsystem/nodes.tsx

@@ -19,7 +19,10 @@ import { useTheme } from '@principal-ade/industry-theme';
 import {
   edgeColor,
   edgeStrokeStyle,
+  DEPRECATED_COLOR,
   PROPOSED_COLOR,
+  deprecatedBadgeColor,
+  deprecatedBadgeLabel,
   constructBadgeColor,
   constructBadgeLabel,
   rightBadgeLabel,
@@ -217,6 +220,13 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   // Store retention backing badge — memory/disk/db, beside role (orthogonal).
   const storageLabel = storageBadgeLabel(c);
   const storageColor = storageBadgeColor(c);
+  // Deprecated badge — clickable, unlike every other badge here (they opt out
+  // of pointer events so clicks fall through to the node). Clicking opens the
+  // removal provenance, which is the whole reason the badge exists.
+  const deprecatedLabel = deprecatedBadgeLabel(c);
+  const deprecatedColor = deprecatedBadgeColor(c);
+  const removal = c.removedIn;
+  const [showRemoval, setShowRemoval] = useState(false);
   // Set while a file is open in the drawer: true → spotlight, false → dim,
   // absent (no file open) → neutral.
   const fileMatch = data.fileMatch as boolean | undefined;
@@ -225,13 +235,17 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   const nodeBg = theme.colors.backgroundSecondary ?? theme.colors.background;
   const hoverBg =
     theme.colors.backgroundHover ?? theme.colors.backgroundTertiary ?? nodeBg;
-  // Border: proposed uses the goldenrod accent (dashed); construct color stays
-  // on the left badge. File-open spotlight still wins with primary.
+  // Border: proposed uses the goldenrod accent (dashed), deprecated the slate
+  // accent (dotted, same family as issue) since both mean "not a live claim";
+  // construct color stays on the left badge. File-open spotlight still wins
+  // with primary.
   const borderColor = fileMatch
     ? theme.colors.primary
     : c.proposed
       ? PROPOSED_COLOR
-      : color;
+      : c.deprecated
+        ? DEPRECATED_COLOR
+        : color;
   // Selection is stamped into data by the graph component — React Flow's own
   // `selected` never updates because the node stops click propagation.
   const isSelected = selected || (data.isSelected as boolean | undefined) === true;
@@ -252,7 +266,16 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   // The border keeps its construct color; the severity rides on the chip.
   // Verification skips `proposed` nodes, so the two rarely stack — issue wins.
   const hasIssue = data.issue != null;
-  const borderStyle = hasIssue ? 'dotted' : c.proposed ? 'dashed' : 'solid';
+  // Deprecated is dotted like issue but slate rather than construct-colored:
+  // "this claim was retired" is closer to a diagnostic than to a placeholder,
+  // and verification skips deprecated nodes so the two never stack in practice.
+  const borderStyle = hasIssue
+    ? 'dotted'
+    : c.proposed
+      ? 'dashed'
+      : c.deprecated
+        ? 'dotted'
+        : 'solid';
 
   return (
     <div
@@ -326,7 +349,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
           orthogonal to topology. Persistent; pointer-events pass through.
           Sits astride the bottom edge, centered (mirroring the top construct
           badge's straddle), so the top edge stays free for the construct tag. */}
-      {(topRightLabel != null || storageLabel != null) && (
+      {(topRightLabel != null || storageLabel != null || deprecatedLabel != null) && (
         <div
           style={{
             position: 'absolute',
@@ -375,6 +398,102 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
               {topRightLabel}
             </span>
           )}
+          {deprecatedLabel != null && deprecatedColor != null && (
+            // Its own click target: stops propagation so opening the provenance
+            // doesn't also select the node, and toggles a popover rather than
+            // leaning on a title tooltip (which truncates the commit subject).
+            <span
+              role="button"
+              tabIndex={0}
+              aria-expanded={showRemoval}
+              aria-label={
+                removal
+                  ? `Deprecated — removed in ${removal.commit}. Show removal details.`
+                  : 'Deprecated — show removal details.'
+              }
+              onClick={(e) => {
+                e.stopPropagation();
+                setShowRemoval((v) => !v);
+              }}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                  e.stopPropagation();
+                  e.preventDefault();
+                  setShowRemoval((v) => !v);
+                }
+              }}
+              style={{
+                position: 'relative',
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[1],
+                letterSpacing: 0.5,
+                textTransform: 'uppercase',
+                lineHeight: '17px',
+                color: deprecatedColor,
+                background: nodeBg,
+                border: `2px solid ${deprecatedColor}`,
+                borderRadius: badgeRadius,
+                padding: '2px 8px',
+                cursor: 'pointer',
+              }}
+            >
+              {deprecatedLabel}
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Removal provenance popover — anchored above the deprecated badge, so it
+          opens away from the node body and stays inside the canvas. */}
+      {showRemoval && deprecatedLabel != null && (
+        <div
+          role="dialog"
+          aria-label="Removal provenance"
+          onClick={(e) => e.stopPropagation()}
+          style={{
+            position: 'absolute',
+            bottom: '100%',
+            left: '50%',
+            transform: 'translateX(-50%)',
+            marginBottom: 6,
+            zIndex: 20,
+            width: 260,
+            padding: '8px 10px',
+            borderRadius: 6,
+            background: nodeBg,
+            border: `1px solid ${DEPRECATED_COLOR}`,
+            boxShadow: '0 6px 20px rgba(0,0,0,0.35)',
+            fontFamily: theme.fonts.body,
+            fontSize: theme.fontSizes[1],
+            color: theme.colors.text,
+            textAlign: 'left',
+            whiteSpace: 'normal',
+            cursor: 'default',
+          }}
+        >
+          <div
+            style={{
+              fontWeight: 600,
+              marginBottom: 4,
+              color: DEPRECATED_COLOR,
+            }}
+          >
+            Deprecated
+          </div>
+          {removal ? (
+            <>
+              <div style={{ fontFamily: theme.fonts.monospace, marginBottom: 4 }}>
+                removed in {removal.commit}
+              </div>
+              {removal.reason && (
+                <div style={{ color: theme.colors.textSecondary }}>{removal.reason}</div>
+              )}
+            </>
+          ) : (
+            <div style={{ color: theme.colors.textSecondary }}>
+              This claim's source was removed upstream.
+            </div>
+          )}
         </div>
       )}
 

package/dist/stories/Subsystem/C4Graph/c4Fixture.d.ts

@@ -1,3 +0,0 @@
-import type { SubsystemModelDocument } from "../../../subsystem/model";
-export declare const c4FixtureModel: SubsystemModelDocument;
-//# sourceMappingURL=c4Fixture.d.ts.map

package/dist/stories/Subsystem/C4Graph/c4Fixture.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"c4Fixture.d.ts","sourceRoot":"","sources":["../../../../src/stories/Subsystem/C4Graph/c4Fixture.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,eAAO,MAAM,cAAc,EAAE,sBAE5B,CAAC"}