@principal-ai/subsystems-react 0.51.4 → 0.52.0

package/src/subsystem/c4Evidence.test.ts

@@ -1,12 +1,11 @@
 import { describe, expect, test } from 'bun:test';
 import {
-  deriveConcerns,
-  suggestMerges,
   findUnassigned,
   isRuntimeConstruct,
   suggestContainerKind,
   proposeElements,
-  mergeElements,
+  verificationIssues,
+  verifyProcessBoundaries,
 } from './c4Evidence';
 import type { C4MemberView } from './c4Evidence';
 import type { C4Container, C4Element } from './c4';
@@ -31,136 +30,6 @@ describe('isRuntimeConstruct', () => {
   });
 });
 
-describe('deriveConcerns — questions, not answers', () => {
-  test('flags a lone member as a singleton', () => {
-    const out = deriveConcerns('graphify/extract', [member({ alias: 'x' })]);
-    expect(out.some((c) => c.kind === 'singleton')).toBe(true);
-  });
-
-  test('flags a group with no runtime member as library-shaped', () => {
-    const out = deriveConcerns(
-      'subsystems-core',
-      [
-        member({ alias: 'a', construct: 'interface' }),
-        member({ alias: 'b', construct: 'type_alias' }),
-      ],
-      { frameworks: [] },
-    );
-    expect(out.some((c) => c.kind === 'library_shaped')).toBe(true);
-  });
-
-  test('a single non-runtime member is also library-shaped', () => {
-    const out = deriveConcerns('shared', [member({ alias: 'a', construct: 'type_alias' })]);
-    expect(out.some((c) => c.kind === 'library_shaped')).toBe(true);
-  });
-
-  test('flags a runtime container with no technology signal', () => {
-    const out = deriveConcerns('p2', [member({ alias: 'c' })], { frameworks: [] });
-    expect(out.some((c) => c.kind === 'missing_technology')).toBe(true);
-  });
-
-  test('does not demand technology once a framework is present', () => {
-    const out = deriveConcerns(
-      'p1',
-      [member({ alias: 'a' }), member({ alias: 'b' })],
-      { frameworks: ['react'] },
-    );
-    expect(out.some((c) => c.kind === 'missing_technology')).toBe(false);
-  });
-
-  test('flags members spanning two repo keys', () => {
-    const out = deriveConcerns('p1', [
-      member({ alias: 'a' }),
-      member({ alias: 'z', purl: 'pkg:github/other/thing#z.ts' }),
-    ]);
-    expect(out.some((c) => c.kind === 'spans_repos')).toBe(true);
-  });
-
-  test('flags a store with no storage kind', () => {
-    const out = deriveConcerns('p1', [
-      member({ alias: 'a' }),
-      member({ alias: 's', construct: 'store', declaration: { kind: 'store', properties: [] } }),
-    ]);
-    expect(out.some((c) => c.kind === 'store_unclassified')).toBe(true);
-  });
-
-  test('does not flag a store that declared its storage', () => {
-    const out = deriveConcerns('p1', [
-      member({ alias: 'a' }),
-      member({ alias: 's', construct: 'store', declaration: { kind: 'store', storage: 'memory' } }),
-    ]);
-    expect(out.some((c) => c.kind === 'store_unclassified')).toBe(false);
-  });
-
-  test('flags an external with no resolvable identity', () => {
-    const out = deriveConcerns('p1', [
-      member({ alias: 'a' }),
-      member({ alias: 'x', construct: 'external', purl: 'external' }),
-    ]);
-    expect(out.some((c) => c.kind === 'external_unidentified')).toBe(true);
-  });
-
-  test('does not flag an external that has a real purl', () => {
-    const out = deriveConcerns('p1', [
-      member({ alias: 'a' }),
-      member({ alias: 'x', construct: 'external', purl: 'pkg:npm/some-pkg' }),
-    ]);
-    expect(out.some((c) => c.kind === 'external_unidentified')).toBe(false);
-  });
-
-  test('a healthy container raises nothing', () => {
-    const out = deriveConcerns(
-      'subsystems-studio/host',
-      [
-        member({ alias: 'a' }),
-        member({ alias: 'b' }),
-        member({ alias: 's', construct: 'store', declaration: { kind: 'store', storage: 'memory' } }),
-      ],
-      { frameworks: ['bun'] },
-    );
-    expect(out).toHaveLength(0);
-  });
-
-  test('never returns a decision — only concerns', () => {
-    const out = deriveConcerns('graphify/extract', [member({ alias: 'x' })]);
-    // Every field describes something to look at, never a verdict.
-    for (const c of out) {
-      expect(typeof c.kind).toBe('string');
-      expect(c.message.length).toBeGreaterThan(0);
-      expect(c.message).not.toMatch(/^\s*(is|use)\b/i);
-    }
-  });
-});
-
-describe('suggestMerges', () => {
-  test('groups keys that share a trailing role', () => {
-    const out = suggestMerges([
-      { key: 'subsystems-studio/host', memberCount: 9 },
-      { key: 'principal-studio/host', memberCount: 1 },
-      { key: 'subsystems-studio/renderer', memberCount: 5 },
-    ]);
-    expect(out).toHaveLength(1);
-    expect(out[0]!.role).toBe('host');
-    expect(out[0]!.keys).toEqual(['principal-studio/host', 'subsystems-studio/host']);
-  });
-
-  test('ignores a bare key with no app/role shape', () => {
-    const out = suggestMerges([
-      { key: 'subsystems-react', memberCount: 2 },
-      { key: 'subsystems-core', memberCount: 1 },
-    ]);
-    expect(out).toHaveLength(0);
-  });
-
-  test('frames the finding as a question', () => {
-    const out = suggestMerges([
-      { key: 'a/host', memberCount: 1 },
-      { key: 'b/host', memberCount: 1 },
-    ]);
-    expect(out[0]!.reason).toContain('or two units?');
-  });
-});
-
 describe('findUnassigned', () => {
   test('returns runtime components that state no process', () => {
     const out = findUnassigned([
@@ -197,11 +66,9 @@ describe('suggestContainerKind', () => {
 
   test('there is no library answer, even for a library-shaped group', () => {
     // The kinds are application | data-store. A package of interfaces still
-    // comes back `application`, with the question left to a person in the
-    // `library_shaped` concern. Returning `library` here would put a non-C4
-    // concept into the vocabulary.
+    // comes back `application`; the library verdict is the propose gate's
+    // business (no proposal at all), not this function's.
     const members = [member({ alias: 'a', construct: 'interface' })];
-    expect(deriveConcerns('x', members).some((c) => c.kind === 'library_shaped')).toBe(true);
     expect(suggestContainerKind(members)).toBe('application');
   });
 });
@@ -223,164 +90,237 @@ describe('proposeElements', () => {
     },
   ];
 
-  test('proposes one element per derived key, never accepted', () => {
+  test('a library-shaped boundary gets no proposal — it cannot be discerned into a container', () => {
+    // Question 1: code that never runs is not a deployable unit. The concern
+    // stands for review; no box is proposed for a person to reject.
     const set = proposeElements({ repoKey: REPO, rollup });
-    expect(set.elements).toHaveLength(2);
-    expect(set.elements.every((e) => e.state === 'proposed')).toBe(true);
+    expect(set.elements.map((e) => e.id)).toEqual(['container:subsystems-studio/host']);
   });
 
-  test('every proposal is a container, since a key names a process', () => {
+  test('every proposal is a container claiming its key via `process`, never accepted', () => {
     const set = proposeElements({ repoKey: REPO, rollup });
     expect(set.elements.every((e) => e.kind === 'container')).toBe(true);
+    expect(set.elements.every((e) => e.state === 'proposed')).toBe(true);
+    expect(set.elements.map((e) => (e as C4Container).process)).toEqual(['subsystems-studio/host']);
   });
 
-  test('every proposal carries the open questions as its rationale', () => {
-    const set = proposeElements({ repoKey: REPO, rollup });
-    const core = set.elements.find((e) => e.derivedFrom?.includes('subsystems-core'))!;
-    expect(core.rationale).toContain('library');
+  test('a key a container already claims is skipped — no duplicates', () => {
+    // Question 2: the container exists; proposing another would be the
+    // duplicate this module exists to prevent.
+    const existing: C4Element[] = [
+      {
+        kind: 'container',
+        containerKind: 'application',
+        technology: 'Bun',
+        id: 'container:subsystems-studio/host',
+        process: 'subsystems-studio/host',
+        label: 'studio host',
+        state: 'accepted',
+      },
+    ];
+    const set = proposeElements({ repoKey: REPO, rollup, elements: existing });
+    expect(set.elements).toHaveLength(0);
+  });
+
+  test('the scaffold fabricates no rationale — that is the proposing agent\'s to write', () => {
+    const set = proposeElements({
+      repoKey: REPO,
+      rollup: [{ key: 'app/worker', frameworks: ['bun'], members: [member({ alias: 'w' })] }],
+    });
+    expect(set.elements[0]!.rationale).toBeUndefined();
   });
 
-  test('a healthy key gets no rationale, because there is nothing to ask', () => {
+  test('proposes strictly one container per key — folding lives in the model, not here', () => {
+    // Two keys that are one deployable unit are a model discrepancy: a
+    // consolidation proposal rewrites the components' `process` fields first,
+    // and proposeElements then naturally proposes one container. The read
+    // side never folds.
     const set = proposeElements({
       repoKey: REPO,
       rollup: [
+        rollup[0]!,
         {
-          key: 'app/host',
-          frameworks: ['bun'],
-          members: [member({ alias: 'a' }), member({ alias: 'b' })],
+          key: 'principal-studio/host',
+          frameworks: ['electrobun'],
+          members: [member({ alias: 'z' })],
         },
       ],
     });
-    expect(set.elements[0]!.rationale).toBeUndefined();
-  });
-
-  test('members are named, not inferred from the key', () => {
-    const set = proposeElements({ repoKey: REPO, rollup });
-    const host = set.elements.find((e) => e.derivedFrom?.includes('subsystems-studio/host'))!;
-    expect(host.members).toEqual(['a', 's']);
+    expect(set.elements).toHaveLength(2);
   });
 
   test('a key with no framework signal gets an empty technology, not a guess', () => {
-    // `technology` is required by the type, and an empty one is reported.
+    // `technology` is required by the type, and an empty one is reported as a
     // gap. Writing "TypeScript" here would be the derivation this module does
     // not do.
-    const set = proposeElements({ repoKey: REPO, rollup });
-    const core = set.elements.find((e) => e.derivedFrom?.includes('subsystems-core'))!;
-    expect((core as C4Container).technology).toBe('');
+    const set = proposeElements({
+      repoKey: REPO,
+      rollup: [{ key: 'app/host', frameworks: [], members: [member({ alias: 'a' })] }],
+    });
+    expect((set.elements[0]! as C4Container).technology).toBe('');
   });
 
   test('the set is sorted by id, so a review list is stable', () => {
-    const set = proposeElements({ repoKey: REPO, rollup });
-    expect(set.elements.map((e) => e.id)).toEqual([...set.elements.map((e) => e.id)].sort());
+    const set = proposeElements({
+      repoKey: REPO,
+      rollup: [
+        { key: 'b/host', frameworks: ['bun'], members: [member({ alias: 'a' })] },
+        { key: 'a/host', frameworks: ['bun'], members: [member({ alias: 'b' })] },
+      ],
+    });
+    expect(set.elements.map((e) => e.id)).toEqual(['container:a/host', 'container:b/host']);
   });
 });
 
-describe('mergeElements', () => {
-  function container(over: Partial<C4Container> & { id: string }): C4Container {
+describe('verifyProcessBoundaries', () => {
+  function container(over: Partial<C4Container> & { id: string; process: string }): C4Container {
     return {
       kind: 'container',
       containerKind: 'application',
       technology: 'Bun',
-      members: [],
       label: over.id,
       state: 'proposed',
       ...over,
     };
   }
 
-  const set: C4Element[] = [
-    container({ id: 'container:big', derivedFrom: ['subsystems-studio/host'], members: ['a', 'b', 'c'] }),
-    container({ id: 'container:small', derivedFrom: ['principal-studio/host'], members: ['z'] }),
-    container({ id: 'container:other', derivedFrom: ['site/web'], members: ['w'] }),
+  const rollup = [
+    { key: 'app/host', memberAliases: ['a', 'b'] },
+    { key: 'app/store', memberAliases: ['s'] },
+    { key: 'app/orphan' },
   ];
 
-  test('folds the named keys into one element holding both member sets', () => {
-    const out = mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
-    expect(out).toHaveLength(2);
-    const host = out.find((e) => e.id === 'container:big')!;
-    expect(host.members.sort()).toEqual(['a', 'b', 'c', 'z']);
-    expect(host.derivedFrom!.sort()).toEqual(['principal-studio/host', 'subsystems-studio/host']);
+  test('a key no container claims is unassigned', () => {
+    const out = verifyProcessBoundaries({ rollup: [rollup[0]!], elements: [] });
+    expect(out[0]).toMatchObject({ key: 'app/host', status: 'unassigned' });
+    expect(out[0]!.element).toBeUndefined();
   });
 
-  test('the evidence-heavy side survives by default', () => {
-    // container:big holds 3 members and container:small holds 1.
-    const out = mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
-    expect(out.some((e) => e.id === 'container:big')).toBe(true);
-    expect(out.some((e) => e.id === 'container:small')).toBe(false);
+  test('memberAliases pass through for the confirm UI', () => {
+    const out = verifyProcessBoundaries({ rollup, elements: [] });
+    expect(out[0]!.memberAliases).toEqual(['a', 'b']);
+    expect(out[2]!.memberAliases).toEqual([]);
   });
 
-  test('a caller can override which side survives', () => {
-    const out = mergeElements(
-      set,
-      ['subsystems-studio/host', 'principal-studio/host'],
-      'container:small',
-    );
-    expect(out.some((e) => e.id === 'container:small')).toBe(true);
+  test('a proposal assigns the boundary and reads as proposed', () => {
+    const set = proposeElements({
+      repoKey: REPO,
+      rollup: [
+        { key: 'app/host', frameworks: ['bun'], members: [member({ alias: 'a' }), member({ alias: 'b' })] },
+      ],
+    });
+    const out = verifyProcessBoundaries({
+      rollup: [{ key: 'app/host', memberAliases: ['a', 'b'] }],
+      elements: set.elements,
+    });
+    expect(out[0]).toMatchObject({ key: 'app/host', status: 'proposed' });
+    expect(out[0]!.element!.id).toBe('container:app/host');
   });
 
-  test('leaves unrelated elements alone', () => {
-    const out = mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
-    expect(out.some((e) => e.id === 'container:other')).toBe(true);
+  test('an accepted container verifies the boundary', () => {
+    const out = verifyProcessBoundaries({
+      rollup: [rollup[0]!],
+      elements: [container({ id: 'container:app/host', process: 'app/host', state: 'accepted' })],
+    });
+    expect(out[0]).toMatchObject({ key: 'app/host', status: 'verified' });
   });
 
-  test('a merge with nothing to absorb is a no-op', () => {
-    expect(mergeElements(set, ['subsystems-studio/host'])).toHaveLength(3);
+  test('a rejected container marks the boundary rejected', () => {
+    const out = verifyProcessBoundaries({
+      rollup: [rollup[0]!],
+      elements: [container({ id: 'container:app/host', process: 'app/host', state: 'rejected' })],
+    });
+    expect(out[0]).toMatchObject({ key: 'app/host', status: 'rejected' });
   });
 
-  test('is a no-op when only one side is present', () => {
-    expect(mergeElements(set, ['nope/nothing', 'site/web'])).toHaveLength(3);
+  test('a boundary matches its container by key, nothing else', () => {
+    // A near-miss key is not a claimant: no redirect, no fold — if the model
+    // says two keys are one unit, the model gets rewritten, not the lookup.
+    const out = verifyProcessBoundaries({
+      rollup: [{ key: 'legacy/host', memberAliases: ['z'] }],
+      elements: [container({ id: 'container:app/host', process: 'app/host', state: 'accepted' })],
+    });
+    expect(out[0]).toMatchObject({ key: 'legacy/host', status: 'unassigned' });
   });
 
-  test('refuses to fold a component into another element', () => {
-    // A component has a required `container`, so absorbing one would silently
-    // repoint it at a parent the caller never agreed to.
-    const withComponent: C4Element[] = [
-      container({ id: 'container:a', derivedFrom: ['x/host'], members: ['a'] }),
-      {
-        kind: 'component',
-        container: 'container:a',
-        technology: 'React',
-        members: ['b'],
-        label: 'component:b',
-        state: 'proposed',
-        derivedFrom: ['y/host'],
-      },
-    ];
-    expect(mergeElements(withComponent, ['x/host', 'y/host'])).toHaveLength(2);
+  test('accepted outranks rejected when two containers claim one key', () => {
+    const out = verifyProcessBoundaries({
+      rollup: [rollup[0]!],
+      elements: [
+        container({ id: 'container:a', process: 'app/host', state: 'rejected' }),
+        container({ id: 'container:b', process: 'app/host', state: 'accepted' }),
+      ],
+    });
+    expect(out[0]).toMatchObject({ status: 'verified', element: { id: 'container:b' } });
   });
 
-  test('does not touch the input set', () => {
-    mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
-    expect(set).toHaveLength(3);
+  test('a non-container never claims a boundary', () => {
+    // Only containers carry a `process` claim; components point at their
+    // parent and cannot verify anything.
+    const component: C4Element = {
+      kind: 'component',
+      container: 'container:app/host',
+      technology: 'React',
+      label: 'component:a',
+      state: 'accepted',
+    };
+    const out = verifyProcessBoundaries({ rollup: [rollup[0]!], elements: [component] });
+    expect(out[0]).toMatchObject({ status: 'unassigned' });
+  });
+});
+
+describe('verificationIssues — statuses as dynamic-topology findings', () => {
+  test('a verified boundary reports nothing — absence only', () => {
+    const out = verificationIssues([
+      { key: 'app/host', memberAliases: ['a'], status: 'verified' },
+    ]);
+    expect(out).toHaveLength(0);
   });
 
-  test('is idempotent', () => {
-    const once = mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
-    expect(mergeElements(once, ['subsystems-studio/host', 'principal-studio/host'])).toEqual(once);
+  test('an unclaimed boundary is a finding whose fix proposes a container', () => {
+    const out = verificationIssues([
+      { key: 'app/worker', memberAliases: ['w'], status: 'unassigned' },
+    ]);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatchObject({
+      id: 'process-verification:app/worker',
+      severity: 'info',
+      kind: 'boundary_process_unassigned',
+      target: { kind: 'process', id: 'app/worker' },
+      fix: { label: 'Propose container' },
+    });
   });
 
-  test('keeps the confirmed attributes of the survivor', () => {
-    const withTech = set.map((e) =>
-      e.id === 'container:big' ? { ...e, technology: 'Electrobun', state: 'accepted' as const } : e,
-    );
-    const out = mergeElements(withTech, ['subsystems-studio/host', 'principal-studio/host']);
-    expect(out.find((e) => e.id === 'container:big')).toMatchObject({
-      technology: 'Electrobun',
-      state: 'accepted',
+  test('a proposed boundary awaits the decision; its fix accepts the container', () => {
+    const out = verificationIssues([
+      {
+        key: 'app/renderer',
+        memberAliases: ['v'],
+        status: 'proposed',
+        element: { id: 'container:app/renderer', label: 'Studio renderer' } as C4Element,
+      },
+    ]);
+    expect(out[0]).toMatchObject({
+      kind: 'boundary_process_proposed',
+      fix: { label: 'Accept container' },
     });
+    expect(out[0]!.message).toContain('Studio renderer');
   });
 
-  test('both rationales survive, so the decision is still readable', () => {
-    const annotated = set.map((e) =>
-      e.id === 'container:big'
-        ? { ...e, rationale: 'two app names, one process' }
-        : e.id === 'container:small'
-          ? { ...e, rationale: 'one member' }
-          : e,
-    );
-    const out = mergeElements(annotated, ['subsystems-studio/host', 'principal-studio/host']);
-    const host = out.find((e) => e.id === 'container:big')!;
-    expect(host.rationale).toContain('two app names');
-    expect(host.rationale).toContain('one member');
+  test('a rejected boundary records the declined container and offers no fix', () => {
+    const out = verificationIssues([
+      {
+        key: 'app/worker',
+        memberAliases: ['w'],
+        status: 'rejected',
+        element: { id: 'container:app/worker', label: 'Studio worker' } as C4Element,
+      },
+    ]);
+    expect(out[0]).toMatchObject({
+      kind: 'boundary_process_rejected',
+      target: { kind: 'process', id: 'app/worker' },
+    });
+    expect(out[0]!.fix).toBeUndefined();
+    expect(out[0]!.message).toContain('rejected');
   });
-});
+});