@principal-ai/subsystems-react 0.51.4 → 0.53.0

package/src/subsystem/c4Evidence.ts

@@ -1,57 +1,29 @@
 /**
- * C4 evidence — what an agent needs in order to propose elements.
+ * C4 evidence — the pure read-side of proposing and verifying C4 containers.
  *
- * 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:
+ * This module does not decide anything. The proposing agent reads the
+ * subsystem diagrams, queries the existing containers, reasons, and writes
+ * its own rationale; what lives here is only the mechanical part of that
+ * loop:
  *
- *   - 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
+ *   - `proposeElements` — the proposal scaffold: skip keys containers
+ *     already claim, skip boundaries no container can be discerned from
+ *     (no runtime code behind them)
+ *   - `verifyProcessBoundaries` — a boundary's verification status, read
+ *     off the claiming container
+ *   - `verificationIssues` — those statuses as dynamic-topology findings,
+ *     so verification surfaces through the standard diagnostics pipeline
+ *   - `findUnassigned` — runtime components no `process` names at all
  *
- * The output is a set of concerns. Resolving one is the agent's job, and the
- * answer lands in an element's `rationale`.
+ * Judgements — is this the same unit under a different name? is one function
+ * a deployable unit? — belong to the agent and the human, never to a
+ * matcher.
  */
 
 import type { C4Container, C4ContainerKind, C4Element, C4ElementSet } from './c4';
+import type { SubsystemIssue } from './IssueList';
 
-/** 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. */
+/** The fields the propose/verify gates read off a component. */
 export interface C4MemberView {
   alias: string;
   construct: string;
@@ -76,122 +48,6 @@ 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.
  *
@@ -204,87 +60,158 @@ export function findUnassigned(members: readonly C4MemberView[]): C4MemberView[]
 }
 
 /**
- * Fold a decided merge into an element set.
+ * How far a process boundary has travelled toward being a container.
  *
- * 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.
+ * A boundary starts `unassigned` — no container claims it. Proposing an
+ * element for it (see `proposeElements`) assigns the boundary to a container,
+ * which reads as `proposed` until a human decides. `accepted` verifies the
+ * boundary: someone approved this run of code as one deployable unit.
+ * `rejected` means the proposal was wrong and the boundary should not be
+ * drawn as a box.
+ */
+export type C4ProcessVerification =
+  | 'unassigned'
+  | 'proposed'
+  | 'rejected'
+  | 'verified';
+
+/** One process boundary's assignment and its review state. */
+export interface C4ProcessBoundaryStatus {
+  /** The `process` key, e.g. `principal-studio/host`. */
+  key: string;
+  /** Aliases carrying this key in the model, when the caller supplied them. */
+  memberAliases: string[];
+  status: C4ProcessVerification;
+  /** The container whose state decided the status. Absent when `unassigned`. */
+  element?: C4Element;
+}
+
+/**
+ * Read a process boundary's verification off its container assignment.
  *
- * 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.
+ * The claimant is the container whose `process` equals the boundary's key —
+ * a plain string match, no indirection. Two keys that are one deployable unit
+ * under two names are fixed in the model document (a consolidation proposal
+ * rewrites the components' `process` fields), so the reader never sees a
+ * discrepancy to resolve. When several containers claim one key (a
+ * hand-edited set can do this), the decided one wins: accepted over rejected
+ * over proposed, so one reviewer's yes outranks another's no.
  *
- * Returns a new set; the input is untouched. Idempotent.
+ * Pure: the same rollup and elements always read the same. `rollup` accepts
+ * `SubsystemProcessRegion`s directly — only `key` and `memberAliases` are read.
  */
-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];
+export function verifyProcessBoundaries(options: {
+  rollup: ReadonlyArray<{ key: string; memberAliases?: readonly string[] }>;
+  elements: readonly C4Element[];
+}): C4ProcessBoundaryStatus[] {
+  const byKey = new Map<string, C4Element[]>();
+  for (const e of options.elements) {
+    if (e.kind !== 'container' || !e.process) continue;
+    const list = byKey.get(e.process) ?? [];
+    list.push(e);
+    byKey.set(e.process, list);
+  }
 
-  const weight = (e: C4Element): number => {
-    if (memberCountByKey) {
-      let n = 0;
-      for (const k of e.derivedFrom ?? []) n += memberCountByKey.get(k) ?? 0;
-      return n;
+  const precedence = { accepted: 0, rejected: 1, proposed: 2 } as const;
+  return options.rollup.map(({ key, memberAliases }) => {
+    const aliases = [...(memberAliases ?? [])];
+    const claimants = byKey.get(key) ?? [];
+    if (claimants.length === 0) {
+      return { key, memberAliases: aliases, status: 'unassigned' as const };
     }
-    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,
-  };
+    const decided = [...claimants].sort(
+      (a, b) => precedence[a.state] - precedence[b.state] || a.id.localeCompare(b.id),
+    )[0]!;
+    const status = decided.state === 'accepted' ? ('verified' as const) : decided.state;
+    return { key, memberAliases: aliases, status, element: decided };
+  });
+}
 
-  return [...elements.filter((e) => e.id !== survivor.id && !absorbedIds.has(e.id)), merged].sort(
-    (a, b) => a.id.localeCompare(b.id),
-  );
+/**
+ * Verification statuses as diagnostics findings — the dynamic-topology layer
+ * of the issues list. One finding per boundary that is NOT verified: an
+ * unclaimed boundary is the absence a proposing agent run resolves, a
+ * `proposed` one awaits the human's decision, a `rejected` one records that
+ * the decision was no. `verified` reports nothing — the audit reports
+ * absence only, and silence is the good state.
+ *
+ * The findings ride the existing pipeline untouched: they badge the process
+ * frame (target kind `process`), list under Dynamic topology, focus their
+ * members on click, and carry the fix the decision needs. Pure over its
+ * input, like the rest of this module.
+ */
+export function verificationIssues(
+  statuses: readonly C4ProcessBoundaryStatus[],
+): SubsystemIssue[] {
+  const out: SubsystemIssue[] = [];
+  for (const { key, status, element } of statuses) {
+    if (status === 'verified') continue;
+    const label = element?.label ?? key;
+    out.push({
+      id: `process-verification:${key}`,
+      severity: 'info',
+      kind: `boundary_process_${status}`,
+      message:
+        status === 'unassigned'
+          ? `No C4 container claims this process boundary yet — a proposing agent run would scaffold one.`
+          : status === 'proposed'
+            ? `Container "${label}" claims this boundary and awaits a decision.`
+            : `Container "${label}" was rejected for this boundary — it stays unclaimed until a container is accepted.`,
+      target: { kind: 'process', id: key, label: key },
+      fix:
+        status === 'unassigned'
+          ? { label: 'Propose container' }
+          : status === 'proposed'
+            ? { label: 'Accept container' }
+            : undefined,
+    });
+  }
+  return out;
 }
 
 /**
- * A starting point for an agent: one proposed element per derived key, shaped
- * by the mechanical evidence, with the open questions in the rationale.
+ * A starting point for an agent, shaped by the two questions that matter when
+ * assessing a process boundary:
  *
- * Every element comes back `proposed`. This is a scaffold to edit and argue
- * with — not an answer, and never `accepted`.
+ *   1. **Does a container already exist for it?** (`elements`) — a key one
+ *      already claims is never re-proposed; proposing another would be
+ *      exactly the duplicate this module exists to prevent. The exact claim
+ *      is a fact and skipped here; whether a *similarly named* container is
+ *      the same unit is a judgement, so it belongs to the agent querying the
+ *      container list — the fix there is a consolidation proposal, not a
+ *      second box.
+ *   2. **Can the boundary be discerned into a container?** — code that never
+ *      runs cannot be, so a library-shaped group gets no proposal; that
+ *      fact is the agent's to report, not the scaffold's.
+ *
+ * For boundaries passing both, one `proposed` container per key. The
+ * rationale is the proposing agent's own reasoning, written on the proposal
+ * it POSTs — this scaffold does not fabricate one. 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 {
+export function proposeElements(options: {
+  repoKey: string;
+  rollup: ReadonlyArray<{
+    key: string;
+    members: readonly C4MemberView[];
+    frameworks: readonly string[];
+  }>;
+  /** Containers that already exist (from the element store), by `process` claim. */
+  elements?: readonly C4Element[];
+}): C4ElementSet {
+  const existing = options.elements ?? [];
+  const claimed = new Set(existing.flatMap((e) => (e.kind === 'container' && e.process ? [e.process] : [])));
+
+  const elements: C4Container[] = [];
+  for (const { key, members, frameworks } of options.rollup) {
+    if (claimed.has(key)) continue; // already covered — exact claim, a fact
+    const runtime = members.filter((m) => isRuntimeConstruct(m.construct));
+    if (members.length > 0 && runtime.length === 0) continue; // not discernible: code that never runs
+
+    elements.push({
       id: `container:${key}`,
-      kind: 'container' as const,
-      members: members.map((m) => m.alias),
-      derivedFrom: [key],
+      kind: 'container',
+      process: key,
       label: key,
       containerKind: suggestContainerKind(members),
       // C4 requires a technology on every container. With no framework signal
@@ -292,11 +219,9 @@ export function proposeElements(
       // 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,
-    };
-  });
+      state: 'proposed',
+    });
+  }
 
   return {
     repoKey: options.repoKey,