@principal-ai/subsystems-react 0.51.1 → 0.51.2

package/src/stories/Subsystem/C4Graph/C4NodeGallery.stories.tsx

@@ -6,6 +6,7 @@ import {
   nodeStyle,
   nodeSubtitle,
   nodeTag,
+  nodeTypeLabel,
   nodeShape,
   nodeSize,
   nodeMissing,
@@ -147,13 +148,13 @@ const VARIANTS: Array<{ group: string; note: string; node: C4Node }> = [
   },
   {
     group: '',
-    note: '',
+    note: 'A queue or topic is a data store, not its own kind. C4 says an individual queue is a bucket of messages — a data store — and that the message bus itself is not a container at all. The queue-ness lives in the label and technology.',
     node: node({
       id: 'b2',
       label: 'Audit correction queue',
       members: ['s2'],
       constructs: ['store'],
-      containerKind: 'queue',
+      containerKind: 'data-store',
       technology: 'agent session transport',
       description: 'Proposals awaiting a human decision.',
       state: 'accepted',
@@ -333,7 +334,7 @@ function Gallery() {
 
       <div style={{ fontFamily: 'monospace', fontSize: 11, marginBottom: 26, lineHeight: 1.9 }}>
         <div style={{ display: 'flex', gap: 20, flexWrap: 'wrap' }}>
-          <span style={{ color: '#e8e8ea' }}>KIND — shape and border weight</span>
+          <span style={{ color: '#e8e8ea' }}>KIND — shape, icon, and border weight</span>
         </div>
         <div style={{ display: 'flex', gap: 18, flexWrap: 'wrap', marginTop: 4 }}>
           {KINDS.map((kind) => {
@@ -384,7 +385,9 @@ function Gallery() {
                 </div>
               )}
               <Case
-                caption={`${v.node.id} · "${nodeTag(v.node)}" · ${v.node.state} · ${nodeShape(v.node).kind} ${
+                caption={`${v.node.id} · "${nodeTag(v.node)}"${
+                  nodeTypeLabel(v.node) ? ` / ${nodeTypeLabel(v.node)}` : ''
+                } · ${v.node.state} · ${nodeShape(v.node).kind} ${
                   nodeSize(v.node).width
                 }×${nodeSize(v.node).height} · ${nodeSubtitle(v.node)}${
                   nodeMissing(v.node).length ? ` · missing ${nodeMissing(v.node).join('+')}` : ''

package/src/stories/Subsystem/ComponentGraph/Issues.stories.tsx

@@ -61,8 +61,34 @@ const ISSUES: SubsystemIssue[] = [
     message: 'Step 2 references a line that moved (was :42).',
     target: {
       kind: 'step',
-      id: 'flow-1',
-      label: 'Checkout',
+      id: 'story-steps',
+      label: 'Story steps',
+      detail: 'step 2',
+      stepIndex: 1,
+    },
+  },
+  {
+    id: 'i20',
+    severity: 'info',
+    kind: 'step_unconfirmed',
+    message: 'Trail "Story steps" step 1: call site not verified (entry → store via writes)',
+    target: {
+      kind: 'step',
+      id: 'story-steps',
+      label: 'Story steps',
+      detail: 'step 1',
+      stepIndex: 0,
+    },
+  },
+  {
+    id: 'i21',
+    severity: 'info',
+    kind: 'step_stale',
+    message: 'Trail "Story steps" step 2: call site changed since verification (lines 42-44 in src/checkout/api.ts)',
+    target: {
+      kind: 'step',
+      id: 'story-steps',
+      label: 'Story steps',
       detail: 'step 2',
       stepIndex: 1,
     },
@@ -181,3 +207,143 @@ export const GraphWithIssues: Story = {
     </div>
   ),
 };
+
+/** Trail step verification findings — unconfirmed and stale call sites. */
+const TRAIL_STEP_ISSUES: SubsystemIssue[] = [
+  {
+    id: 'ts1',
+    severity: 'info',
+    kind: 'step_unconfirmed',
+    message: 'Trail "Add to Cart" step 1: call site not verified (addToCart → cartStore via writes)',
+    target: {
+      kind: 'step',
+      id: 'add-to-cart',
+      label: 'Add to Cart',
+      detail: 'step 1',
+      stepIndex: 0,
+    },
+  },
+  {
+    id: 'ts2',
+    severity: 'info',
+    kind: 'step_unconfirmed',
+    message: 'Trail "Add to Cart" step 2: call site not verified (cartStore → inventoryService via calls)',
+    target: {
+      kind: 'step',
+      id: 'add-to-cart',
+      label: 'Add to Cart',
+      detail: 'step 2',
+      stepIndex: 1,
+    },
+  },
+  {
+    id: 'ts3',
+    severity: 'info',
+    kind: 'step_stale',
+    message: 'Trail "Checkout" step 1: call site changed since verification (lines 42-44 in src/checkout/api.ts)',
+    target: {
+      kind: 'step',
+      id: 'checkout',
+      label: 'Checkout',
+      detail: 'step 1',
+      stepIndex: 0,
+    },
+  },
+  {
+    id: 'ts4',
+    severity: 'info',
+    kind: 'step_stale',
+    message: 'Trail "Checkout" step 3: call site changed since verification (lines 78-82 in src/checkout/api.ts)',
+    target: {
+      kind: 'step',
+      id: 'checkout',
+      label: 'Checkout',
+      detail: 'step 3',
+      stepIndex: 2,
+    },
+  },
+];
+
+/** Trail step verification: shows unconfirmed and stale call site findings. */
+export const TrailStepVerification: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', width: 380, height: '100vh', borderRight: '1px solid #333' }}>
+      <SubsystemIssueList
+        issues={TRAIL_STEP_ISSUES}
+        focusCategory="trail"
+        onSelectIssue={() => {}}
+      />
+    </div>
+  ),
+};
+
+/** Trail step verification badges on graph edges. */
+const stepVerificationComponents = components([
+  ['api', 'checkoutApi', 'function', 'src/checkout/api.ts', 'pkg:github/you/your-app', 'Handles cart requests.', 'checkoutApi'],
+  ['store', 'cartStore', 'store', 'src/checkout/cartStore.ts', 'pkg:github/you/your-app', 'Retained cart state.', 'cartStore'],
+  ['payment', 'PaymentService', 'class', 'src/payment/service.ts', 'pkg:github/you/your-app', 'Processes payments.', 'PaymentService'],
+]);
+
+const stepVerificationTrails = [
+  {
+    id: 'checkout-flow',
+    title: 'Checkout',
+    steps: [
+      { from: 'api', to: 'store', mechanism: 'writes' as const },
+      { from: 'store', to: 'payment', mechanism: 'calls' as const },
+    ],
+  },
+];
+
+const stepVerificationIssues: SubsystemIssue[] = [
+  {
+    id: 'sv1',
+    severity: 'info',
+    kind: 'step_unconfirmed',
+    message: 'Trail "Checkout" step 1: call site not verified (checkoutApi → cartStore via writes)',
+    target: {
+      kind: 'step',
+      id: 'checkout-flow',
+      label: 'Checkout',
+      detail: 'step 1',
+      stepIndex: 0,
+    },
+  },
+  {
+    id: 'sv2',
+    severity: 'info',
+    kind: 'step_stale',
+    message: 'Trail "Checkout" step 2: call site changed since verification (lines 42-44 in src/checkout/api.ts)',
+    target: {
+      kind: 'step',
+      id: 'checkout-flow',
+      label: 'Checkout',
+      detail: 'step 2',
+      stepIndex: 1,
+    },
+  },
+];
+
+/** Graph with trail step verification badges on edges — ? for unconfirmed, clock for stale. */
+export const GraphWithStepVerificationBadges: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={stepVerificationComponents}
+        trails={stepVerificationTrails}
+        initialTrailId="checkout-flow"
+        title="Checkout with Step Verification"
+        description="Shows edge badges for step verification status: question mark (?) for unconfirmed call sites, clock for stale call sites."
+        diagnostic={{
+          status: 'issues',
+          issueCount: stepVerificationIssues.length,
+          onToggle: () => {},
+        }}
+        issues={stepVerificationIssues}
+        showIssues
+        onSelectIssue={() => {}}
+        onApplyIssueFix={() => {}}
+      />
+    </div>
+  ),
+};

package/src/subsystem/C4NodeCard.test.ts

@@ -3,6 +3,8 @@ import {
   nodeStyle,
   nodeSubtitle,
   nodeTag,
+  nodeKindIcon,
+  nodeTypeLabel,
   nodeShape,
   nodeMissing,
   NODE_W,
@@ -111,6 +113,36 @@ describe('nodeTag — what the box IS', () => {
   });
 });
 
+describe('nodeKindIcon — the kind as a glyph, not a word', () => {
+  test('every kind has its own icon', () => {
+    const icons = (['container', 'component', 'external-system', 'person'] as const).map((kind) =>
+      nodeKindIcon(node({ kind })),
+    );
+    for (const icon of icons) expect(icon).toBeDefined();
+    // Different kinds must not share a glyph, or the icon says nothing.
+    expect(new Set(icons).size).toBe(4);
+  });
+
+  test('the icon does not depend on confirmation state', () => {
+    expect(nodeKindIcon(node({ state: 'proposed' }))).toBe(
+      nodeKindIcon(node({ state: 'accepted' })),
+    );
+  });
+});
+
+describe('nodeTypeLabel — the one word in the icon row', () => {
+  test('a container names its kind', () => {
+    expect(nodeTypeLabel(node({ containerKind: 'application' }))).toBe('application');
+    expect(nodeTypeLabel(node({ containerKind: 'data-store' }))).toBe('data-store');
+  });
+
+  test('the other three kinds have no subtype, so no word', () => {
+    for (const kind of ['component', 'external-system', 'person'] as const) {
+      expect(nodeTypeLabel(node({ kind }))).toBeUndefined();
+    }
+  });
+});
+
 describe('nodeShape — kind without relying on colour or dash', () => {
   test('a container is a sharp rectangle', () => {
     const s = nodeShape(node());
@@ -142,14 +174,19 @@ describe('nodeShape — kind without relying on colour or dash', () => {
 });
 
 describe('nodeSubtitle', () => {
-  test('shows the container kind and technology', () => {
-    expect(
-      nodeSubtitle(node({ containerKind: 'application', technology: 'Bun + Electrobun' })),
-    ).toBe('application · Bun + Electrobun');
+  test('shows the technology, and does not repeat the container kind', () => {
+    const s = nodeSubtitle(
+      node({ containerKind: 'application', technology: 'Bun + Electrobun' }),
+    );
+    expect(s).toBe('Bun + Electrobun');
+    expect(s).not.toContain('application');
   });
 
-  test('shows a data store with no technology as just the kind', () => {
-    expect(nodeSubtitle(node({ containerKind: 'data-store', technology: '' }))).toBe('data-store');
+  test('a container with no technology falls back to its construct breakdown', () => {
+    const s = nodeSubtitle(
+      node({ containerKind: 'data-store', technology: '', constructs: ['store'], members: ['a'] }),
+    );
+    expect(s).toBe('1 store · 1 component');
   });
 
   test('falls back to the construct breakdown when neither is stated', () => {
@@ -286,16 +323,16 @@ describe('card metrics', () => {
 });
 
 describe('container kinds', () => {
-  test('every container kind renders as a subtitle without special-casing', () => {
-    const kinds = ['application', 'data-store', 'queue'] as const;
+  test('every container kind renders as the icon-row label without special-casing', () => {
+    const kinds = ['application', 'data-store'] as const;
     for (const containerKind of kinds) {
-      expect(nodeSubtitle(node({ containerKind, technology: '' }))).toBe(containerKind);
+      expect(nodeTypeLabel(node({ containerKind }))).toBe(containerKind);
     }
   });
 
   test('a library is not one of them', () => {
     // C4 says a module "typically" is not an element at all, so there is no
     // kind to render. A library-shaped group is a review comment.
-    expect(['application', 'data-store', 'queue']).not.toContain('library');
+    expect(['application', 'data-store']).not.toContain('library');
   });
 });

package/src/subsystem/C4NodeCard.tsx

@@ -13,6 +13,8 @@
  */
 
 import { useTheme } from '@principal-ade/industry-theme';
+import { Cloud, Component, Container, UserRound } from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
 import { describeConstructBreakdown } from './model';
 import type { C4Node } from './c4';
 
@@ -102,14 +104,14 @@ function baseName(path: string): string {
 /**
  * The kind + technology line under the label.
  *
- * A container shows its `containerKind` (application / data-store / queue);
- * C4 has no kind for the other three, so they show technology or nothing.
+ * The container kind moved up to the icon row (see `nodeTypeLabel`), so it is
+ * not repeated here. Technology is the remaining confirmed attribute; without
+ * one we fall back to what the document told us.
  */
 export function nodeSubtitle(node: C4Node): string {
-  const parts = [node.containerKind, node.technology].filter(Boolean);
-  if (parts.length > 0) return parts.join(' · ');
+  if (node.technology) return node.technology;
 
-  // No confirmed attributes: fall back to what the document told us.
+  // No stated technology: fall back to what the document told us.
   if (node.kind === 'component') {
     return `${node.component?.construct ?? 'code'}${node.component?.file ? ` · ${baseName(node.component.file)}` : ''}`;
   }
@@ -127,6 +129,34 @@ export function nodeTag(node: C4Node): string {
   return node.kind;
 }
 
+/**
+ * The glyph for the C4 kind, shown in place of a word. The kind is already
+ * carried by the box shape (see `nodeShape`); the icon lets the top row spend
+ * its one piece of text on the container's kind instead of repeating
+ * "container".
+ */
+export function nodeKindIcon(node: C4Node): LucideIcon {
+  switch (node.kind) {
+    case 'container':
+      return Container;
+    case 'component':
+      return Component;
+    case 'external-system':
+      return Cloud;
+    case 'person':
+      return UserRound;
+  }
+}
+
+/**
+ * The word beside the kind icon: what sort of container this is — C4's two,
+ * `application` or `data-store`. The other three kinds have no such subtype,
+ * so they show nothing; the icon and shape are the whole label.
+ */
+export function nodeTypeLabel(node: C4Node): string | undefined {
+  return node.kind === 'container' ? node.containerKind : undefined;
+}
+
 /** How a box is drawn. Shape carries the C4 kind, independent of colour. */
 export type C4ShapeKind = 'rect' | 'square' | 'pill';
 
@@ -150,8 +180,8 @@ export interface NodeShape {
  * An external system is separated from a container by radius alone, which is
  * a weak cue. That is deliberate rather than an oversight: the border dash is
  * the only channel that could say "outside our control" loudly, and it is
- * already spent on proposed-vs-accepted. The kind tag says it in words, and
- * the frame position says it structurally.
+ * already spent on proposed-vs-accepted. The kind icon says it, and the frame
+ * position says it structurally.
  */
 export function nodeShape(node: C4Node): NodeShape {
   switch (node.kind) {
@@ -197,6 +227,8 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
   const style = nodeStyle(node, theme, selected);
   const shape = nodeShape(node);
   const missing = nodeMissing(node);
+  const Icon = nodeKindIcon(node);
+  const typeLabel = nodeTypeLabel(node);
 
   const size = nodeSize(node);
 
@@ -223,23 +255,42 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
         fontFamily: theme.fonts.body,
       }}
     >
-      {/* The kind is what the box IS. Confirmation state is carried by the
-          border (see `nodeStyle`), not by a word: the card says what it is,
-          and the styling says who vouched for it. */}
+      {/* The kind is carried by the icon and the box shape; the one word here
+          is the container's kind. Confirmation state is carried by the border
+          (see `nodeStyle`), not by a word. */}
       <span
         style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 6,
           fontFamily: theme.fonts.monospace,
           fontSize: theme.fontSizes[0],
           color: style.color,
-          fontWeight: 600,
           letterSpacing: 0.5,
           textTransform: 'uppercase',
-          whiteSpace: 'nowrap',
-          overflow: 'hidden',
-          textOverflow: 'ellipsis',
+          minWidth: 0,
         }}
       >
-        {nodeTag(node)}
+        <span
+          title={nodeTag(node)}
+          aria-label={nodeTag(node)}
+          style={{ display: 'inline-flex', flexShrink: 0 }}
+        >
+          <Icon size={13} strokeWidth={2.25} />
+        </span>
+        {typeLabel && (
+          <span
+            style={{
+              fontWeight: 600,
+              whiteSpace: 'nowrap',
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+              minWidth: 0,
+            }}
+          >
+            {typeLabel}
+          </span>
+        )}
       </span>
       {/* Two lines rather than an ellipsis: a truncated label hides the very
           thing that distinguishes two containers from each other. The fixed

package/src/subsystem/IssueList.tsx

@@ -17,10 +17,12 @@ import {
   ChevronDown,
   ChevronRight,
   CircleCheck,
+  CircleHelp,
   Component,
   FileX,
   FolderGit2,
   Footprints,
+  History,
   MapPin,
   Network,
   Route,
@@ -104,6 +106,8 @@ const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   boundary_module_file_mismatch: 'static-topology',
   boundary_process_nest_disagree: 'dynamic-topology',
   trail: 'trail',
+  step_unconfirmed: 'trail',
+  step_stale: 'trail',
 };
 
 /**
@@ -164,6 +168,9 @@ export const ISSUE_KIND_ICON: Record<string, LucideIcon> = {
   // One module, more than one claimed process parent — a containment that can't
   // be drawn, which is why the region sits at the root instead of nested.
   boundary_process_nest_disagree: Split,
+  // Trail step verification: unconfirmed = no augmentation yet, stale = code changed
+  step_unconfirmed: CircleHelp,
+  step_stale: History,
 };
 
 /**
@@ -244,6 +251,8 @@ const KIND_LABEL: Record<string, string> = {
   boundary_module_file_mismatch: 'Declaration file outside module',
   boundary_process_nest_disagree: 'Module spans multiple process contexts',
   trail: 'Step issue',
+  step_unconfirmed: 'Call site not verified',
+  step_stale: 'Call site changed',
 };
 
 /** Label for an issue's kind. Explicit `kindLabel` wins; unknown kinds humanize. */
@@ -275,8 +284,10 @@ const KIND_ORDER: Record<string, number> = {
   boundary_module_file_mismatch: 23,
   // Runtime topology — process containment
   boundary_process_nest_disagree: 30,
-  // Trail
+  // Trail — mechanical issues first, then step verification
   trail: 40,
+  step_unconfirmed: 41,
+  step_stale: 42,
 };
 
 const KIND_ORDER_FALLBACK = 100;

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -1184,6 +1184,37 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     return map;
   }, [issues]);
 
+  // Per-edge step verification badge: maps edge IDs to step verification status.
+  // Keyed by the React Flow edge id (from → mechanism → to). An edge can have
+  // multiple steps with issues; we show the worst status (stale > unconfirmed).
+  const stepIssueBadgeByEdgeId = useMemo(() => {
+    const map = new Map<string, { kind: 'step_unconfirmed' | 'step_stale'; severity: 'info' | 'error'; count: number }>();
+    if (!issues?.length || !trails?.length) {
+      console.log('[stepIssueBadge] early return: issues=', issues?.length, 'trails=', trails?.length);
+      return map;
+    }
+    for (const issue of issues) {
+      if (issue.kind !== 'step_unconfirmed' && issue.kind !== 'step_stale') continue;
+      const stepInfo = issueStep(issue);
+      console.log('[stepIssueBadge] issue', issue.id, 'kind=', issue.kind, 'stepInfo=', stepInfo);
+      if (!stepInfo) continue;
+      const step = stepInfo.trail.steps[stepInfo.stepIndex];
+      if (!step) continue;
+      const edgeId = trailStepGraphEdgeId(step);
+      console.log('[stepIssueBadge] -> edgeId=', edgeId);
+      const prev = map.get(edgeId);
+      // step_stale is worse than step_unconfirmed
+      const isWorse = issue.kind === 'step_stale' && prev?.kind !== 'step_stale';
+      map.set(edgeId, {
+        kind: isWorse || !prev ? issue.kind as 'step_unconfirmed' | 'step_stale' : prev.kind,
+        severity: prev?.severity === 'error' || issue.severity === 'error' ? 'error' : 'info',
+        count: (prev?.count ?? 0) + 1,
+      });
+    }
+    console.log('[stepIssueBadge] final map size=', map.size);
+    return map;
+  }, [issues, trails, issueStep]);
+
   // Expanded verification layers in the diagnostics list. When any layer with
   // findings is expanded, the canvas dims everything that layer does not
   // implicate (see `issueFocus`). The list publishes this through
@@ -2452,7 +2483,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
   // doesn't intercept pointer events). Uses ELK-computed label midpoints from
   // the actual edge path (not node-center approximations).
   const edgeLabels = useMemo(() => {
-    return dispEdges
+    const labels = dispEdges
       .filter((e) => {
         if (e.hidden) return false;
         const d = e?.data as { dimmed?: boolean } | undefined;
@@ -2467,6 +2498,8 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
           labelY?: number;
           pathLength?: number;
         } | undefined;
+        const stepIssue = stepIssueBadgeByEdgeId.get(e.id);
+        console.log('[edgeLabels] edge', e.id, 'stepIssue=', stepIssue);
         return {
           id: e.id,
           mechanism: d?.mechanism ?? 'uses',
@@ -2476,9 +2509,12 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
           midY: d?.labelY ?? 0,
           pathLength: d?.pathLength ?? 0,
           stepNos: selectedFlowStepNos?.get(e.id),
+          stepIssue,
         };
       });
-  }, [dispEdges, selectedFlowStepNos]);
+    console.log('[edgeLabels] total labels=', labels.length, 'with stepIssue=', labels.filter(l => l.stepIssue).length);
+    return labels;
+  }, [dispEdges, selectedFlowStepNos, stepIssueBadgeByEdgeId]);
 
   // Unique source files across components → sidebar file trees.
   const treeFilePaths = treeFiles;
@@ -2958,6 +2994,53 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
               >
                 {text}
               </span>
+              {lbl.stepIssue && (() => {
+                const StepIssueIcon = ISSUE_KIND_ICON[lbl.stepIssue.kind];
+                // Match IssueList: error severity = red, info severity = amber
+                const issueColor = lbl.stepIssue.severity === 'error'
+                  ? (theme.colors.error ?? '#e5534b')
+                  : (theme.colors.warning ?? '#d4a017');
+                const badgeBg = theme.colors.backgroundSecondary ?? theme.colors.background;
+                return (
+                  <span
+                    aria-hidden
+                    title={lbl.stepIssue.kind === 'step_stale'
+                      ? 'Call site changed since verification'
+                      : 'Call site not yet verified'}
+                    style={{
+                      position: 'absolute',
+                      right: -7,
+                      bottom: -6,
+                      zIndex: 2,
+                      display: 'inline-flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      gap: 3,
+                      minWidth: 18,
+                      padding: '2px 4px',
+                      borderRadius: 4,
+                      border: `1.5px solid ${issueColor}`,
+                      background: badgeBg,
+                      pointerEvents: 'none',
+                    }}
+                  >
+                    {StepIssueIcon && (
+                      <StepIssueIcon size={12} color={issueColor} />
+                    )}
+                    {lbl.stepIssue.count > 1 && (
+                      <span style={{
+                        color: issueColor,
+                        fontFamily: theme.fonts.monospace,
+                        fontSize: 10,
+                        fontWeight: 700,
+                        lineHeight: 1,
+                      }}>
+                        {lbl.stepIssue.count}
+                      </span>
+                    )}
+                  </span>
+                );
+              })()}
             </div>
           );
         })}

package/src/subsystem/c4.ts

@@ -83,12 +83,13 @@ interface C4ElementBase {
 /**
  * What kind of thing a container is.
  *
- * `application` is a deployable program; the other two are storage that the
- * system reads or writes. Note c4model is explicit that an individual *queue*
- * is a data store, not the bus: "model the message bus as a container" is
- * listed as incorrect.
+ * C4 recognises exactly two: an `application` (a deployable program) or a
+ * `data-store` (something the system reads or writes). There is deliberately
+ * no `queue` kind — c4model is explicit that an individual queue or topic *is*
+ * a data store, and that the message bus itself is not a container at all, so
+ * a queue is a `data-store` whose technology/label say "queue".
  */
-export type C4ContainerKind = 'application' | 'data-store' | 'queue';
+export type C4ContainerKind = 'application' | 'data-store';
 
 /** A deployable unit or a store — the C4 level 2 box. */
 export interface C4Container extends C4ElementBase {
@@ -161,7 +162,7 @@ export interface C4Node {
   technology?: string;
   description?: string;
   state: C4ElementState;
-  /** `application` / `data-store` / `queue`. Set on containers only. */
+  /** `application` / `data-store`. Set on containers only. */
   containerKind?: C4ContainerKind;
   /** Provenance, when the element consolidated several derived keys. */
   derivedFrom?: string[];

package/src/subsystem/c4Evidence.test.ts

@@ -196,10 +196,10 @@ describe('suggestContainerKind', () => {
   });
 
   test('there is no library answer, even for a library-shaped group', () => {
-    // The kinds are application | data-store | queue. 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.
+    // 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.
     const members = [member({ alias: 'a', construct: 'interface' })];
     expect(deriveConcerns('x', members).some((c) => c.kind === 'library_shaped')).toBe(true);
     expect(suggestContainerKind(members)).toBe('application');