@principal-ai/subsystems-react 0.51.4 → 0.53.0

package/src/subsystem/c4.ts

@@ -12,6 +12,12 @@
  * supplies the drawable model directly rather than having trails converted into
  * lines.
  *
+ * The element set is an umbrella over a model, not a standalone artifact: what
+ * sits inside a box resolves from the model document's `process` fields, folded
+ * to the claiming container's key by accepted consolidation records (see
+ * `c4Evidence`). Nothing here stores membership, so nothing here can drift from
+ * the model it organizes.
+ *
  * ## Why a union and not one type with two axes
  *
  * C4's vocabulary is closed: software system, container, component, code —
@@ -32,8 +38,6 @@
  * [C4 notation]: https://c4model.com/diagrams/notation
  */
 
-import type { SubsystemComponent } from './model';
-
 /**
  * Has anyone signed off on this element yet?
  *
@@ -53,27 +57,22 @@ interface C4ElementBase {
   /** Display name. */
   label: string;
   /**
-   * The component aliases that live directly inside this element.
-   *
-   * Named explicitly rather than derived from a `process` value, because two
-   * runs of code being one container is a judgement, not a lookup.
-   *
-   * Each alias belongs to exactly one element.
+   * Nesting parent. A component's container, or a container's system frame.
+   * Absent on an external system or a person — both are outside the boundary:
+   * an external is someone else's system, a person is never part of one.
    */
-  members: string[];
-  /**
-   * The `process` values this element consolidated, when it came from more than
-   * one. Purely provenance — it lets the confirm UI show "this box absorbed
-   * principal-studio/host". Never used to infer membership.
-   */
-  derivedFrom?: string[];
+  parentId?: string;
   /** C4 asks every element to carry a one-line responsibility. */
   description?: string;
   state: C4ElementState;
   /** Why this element is proposed as it is — shown in the confirm UI. */
   rationale?: string;
-  /** Who or what authored it. */
-  author?: 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;
 }
@@ -96,6 +95,12 @@ export interface C4Container extends C4ElementBase {
   containerKind: C4ContainerKind;
   /** C4 requires a technology on every container. */
   technology: string;
+  /**
+   * The `process` key this container claims — the boundary it verifies,
+   * matched exactly against the model document's keys. Not a member list:
+   * the components inside resolve from the model document.
+   */
+  process?: string;
 }
 
 /**
@@ -114,7 +119,6 @@ export interface C4Component extends C4ElementBase {
   /** C4 requires a technology on every component. */
   technology: string;
 }
-
 /** A software system outside the boundary we are drawing. */
 export interface C4ExternalSystem extends C4ElementBase {
   kind: 'external-system';
@@ -130,7 +134,14 @@ export interface C4Person extends C4ElementBase {
 /** One element. Four kinds, no fifth. */
 export type C4Element = C4Container | C4Component | C4ExternalSystem | C4Person;
 
-/** A whole authored element list, for one repo or composed graph. */
+/**
+ * A whole authored element list, for one repo or composed graph. This is the
+ * shape the durable element store persists (`~/.principal/c4-elements/<purl>.json`):
+ * **accepted elements only** — the set is the approved architecture, not a
+ * history. `proposed` exists only on in-memory proposal scaffolds and is never
+ * persisted; a rejected proposal stays remembered by the proposal store, which
+ * is where proposing agents consult prior rejections.
+ */
 export interface C4ElementSet {
   /** Repo key this set describes, e.g. `pkg:github/owner/name`. */
   repoKey: string;
@@ -142,38 +153,6 @@ export interface C4ElementSet {
 /** Which level to draw. Determines which frames are drawn. */
 export type C4View = 'container' | 'component';
 
-/**
- * A flattened element, as the renderer reads it.
- *
- * The union above is what an author writes; this is the one shape every box
- * draws with, so the card does not branch on kind to find a label.
- */
-export interface C4Node {
-  id: string;
-  kind: C4Element['kind'];
-  /**
-   * Nesting parent: a component's container, a container or external system's
-   * frame, and nothing for a person — C4 puts people outside every system.
-   */
-  parentId?: string;
-  label: string;
-  technology?: string;
-  description?: string;
-  state: C4ElementState;
-  /** `application` / `data-store`. Set on containers only. */
-  containerKind?: C4ContainerKind;
-  /** Provenance, when the element consolidated several derived keys. */
-  derivedFrom?: string[];
-  /** Resolved members, when a document was supplied. A container's list includes its components'. */
-  members: string[];
-  /** Distinct constructs among resolved members. */
-  constructs: string[];
-  /** Present at component level when the document resolved it. */
-  component?: SubsystemComponent;
-  /** Source model ids that contributed members, when attribution is supplied. */
-  models?: string[];
-}
-
 /** A compound frame: the system, or a container holding its components. */
 export interface C4Group {
   id: string;
@@ -205,11 +184,56 @@ export interface C4Edge {
   count: number;
 }
 
+/**
+ * Protocol hues, keyed by a canonical protocol token.
+ *
+ * C4's notation is colour-free, so this is a local choice — but on a container
+ * diagram the protocol is what a reader wants to distinguish at a glance
+ * (in-process RPC vs HTTP vs file I/O), more than the trail verb the line came
+ * from. Keys are lowercase, matched loosely (see `protocolColor`).
+ */
+export const PROTOCOL_COLOR: Record<string, string> = {
+  rpc: '#22c55e', // green — in-process call across a boundary
+  http: '#e8853a', // orange — network request
+  https: '#e8853a',
+  rest: '#e8853a',
+  graphql: '#e061a3', // pink
+  fs: '#0ea5e9', // sky — disk
+  'file i/o': '#0ea5e9',
+  sql: '#a78bfa', // violet — a database
+  sqlite: '#a78bfa',
+  postgres: '#a78bfa',
+  'json-rpc': '#22c55e',
+  ws: '#e3b341', // gold — stream/socket
+  websocket: '#e3b341',
+  mcp: '#4ec9b0', // teal — agent/tool transport
+  stdin: '#9ca3af', // gray — process boundary
+  stdout: '#9ca3af',
+};
+
+/** Fallback hue for an edge whose protocol we have no colour for (or none). */
+export const PROTOCOL_COLOR_FALLBACK = '#9ca3af';
+
+/**
+ * Colour for an edge's protocol. Matches the longest known token contained in
+ * the (lowercased) protocol string, so `Electrobun RPC` finds `rpc` and
+ * `JSON-RPC` finds the `json-rpc` entry before `rpc`.
+ */
+export function protocolColor(protocol: string | undefined): string {
+  if (!protocol) return PROTOCOL_COLOR_FALLBACK;
+  const p = protocol.toLowerCase();
+  let best = '';
+  for (const key of Object.keys(PROTOCOL_COLOR)) {
+    if (key.length > best.length && p.includes(key)) best = key;
+  }
+  return best ? PROTOCOL_COLOR[best]! : PROTOCOL_COLOR_FALLBACK;
+}
+
 /** A drawable C4 projection. Authored, not derived. */
 export interface C4Model {
   view: C4View;
   system: { id: string; label: string; repoKey?: string };
-  nodes: C4Node[];
+  nodes: C4Element[];
   groups: C4Group[];
   edges: C4Edge[];
 }