@principal-ai/subsystems-react 0.51.0 → 0.51.1

package/src/stories/Subsystem/C4Graph/c4ProposedElements.fixture.ts

@@ -0,0 +1,366 @@
+/**
+ * A proposed C4 element set — what an agent's output looks like.
+ *
+ * Hand-authored on purpose. The previous fixture was *generated* from live
+ * store data by converting each `process` value into a container, which is the
+ * thing we no longer believe: `process` says where code runs, not which runs
+ * of code are one deployable unit.
+ *
+ * Everything below is a claim, and each carries a `rationale` saying why. All
+ * of it is `proposed` — accepting is a human's decision.
+ *
+ * Three of these are deliberately wrong, and `c4OpenQuestions` surfaces them:
+ * `container:shared-ui` is a library pretending to be a deployable unit,
+ * `container:in-memory-state` is process-lifetime state pretending to be a
+ * container, and `external:opencode-db` is a boundary two models disagree on.
+ */
+import type { C4Element } from '../../../subsystem/c4';
+
+const author = 'c4-proposer';
+
+export const c4ProposedElements: C4Element[] = [
+  // --- deployable units ----------------------------------------------------
+  {
+    id: 'container:studio-host',
+    kind: 'container',
+    label: 'Subsystem Studio — host',
+    derivedFrom: ['subsystems-studio/host'],
+    // Only the aliases with no component of their own. The store I/O and the
+    // audit runner name their own members below, and `buildC4Model` rolls
+    // those up into this container rather than counting them twice.
+    members: [
+      'resolve-root', 'http-put', 'http-propose', 'tab-registry',
+      'live-feed-store', 'maintain-probe-registry', 'run-store',
+      'graphify-store', 'proposal-create', 'proposal-accept',
+      'maintain-orchestrator', 'run-maintain-agent', 'ensure-graphify',
+      'close-tab', 'open-tab',
+    ],
+    containerKind: 'application',
+    technology: 'Bun + Electrobun host',
+    description:
+      'Owns the model store on disk, runs graphify-backed verification, and serves the renderer over RPC.',
+    state: 'proposed',
+    rationale: 'The Electron main process, holding 113 components in the live corpus.',
+    author,
+  },
+  {
+    id: 'container:legacy-host',
+    kind: 'container',
+    label: 'Principal Studio — host',
+    // The other half of the merge question. `subsystems-studio/host` (113
+    // components) and `principal-studio/host` (1) are either one process or
+    // two, and no amount of reading the keys decides it — `mergeElements`
+    // exists for exactly this, and the story shows the button.
+    derivedFrom: ['principal-studio/host'],
+    members: ['register-roots'],
+    containerKind: 'application',
+    technology: 'Electrobun host',
+    description: "The same Electron main process under the app's former name.",
+    state: 'proposed',
+    rationale:
+      'One member, and the same process as container:studio-host. Merged or kept separate, one deployable unit under two app names or two units?',
+    author,
+  },
+  {
+    id: 'container:studio-renderer',
+    kind: 'container',
+    label: 'Subsystem Studio — renderer',
+    // `file-panel` is not repeated here: component:file-viewer owns it, and
+    // the build rolls it up. An alias belongs to exactly one element.
+    derivedFrom: ['subsystems-studio/renderer'],
+    members: [
+      'subsystems-view', 'model-view', 'regular-audit-view', 'list-view',
+      'rpc-bridge', 'reload-subs', 'regular-audit-subscribers',
+      'tab-strip', 'graph-view', 'detail-graph', 'is-model-viewed',
+      'preloadHighlighter', 'SharedHighlighter', 'CodeView',
+    ],
+    containerKind: 'application',
+    technology: 'React 19 in an Electron renderer',
+    description: 'Renders subsystem models and talks to the host over the Electrobun RPC bridge.',
+    state: 'proposed',
+    rationale: 'The Electron renderer process, holding 41 components in the live corpus.',
+    author,
+  },
+  {
+    id: 'container:legacy-renderer',
+    kind: 'container',
+    label: 'Principal Studio — renderer',
+    // The other half of the renderer merge question, mirroring legacy-host.
+    derivedFrom: ['principal-studio/renderer'],
+    members: ['app-shell'],
+    containerKind: 'application',
+    technology: 'React 19',
+    description: "The same React bundle under the app's former name.",
+    state: 'proposed',
+    rationale:
+      'One member, and the same process as container:studio-renderer. One deployable unit under two app names or two units?',
+    author,
+  },
+  {
+    id: 'container:cli',
+    kind: 'container',
+    label: 'Subsystem Modeling CLI',
+    derivedFrom: ['principal-studio-cli'],
+    members: ['cli-create'],
+    containerKind: 'application',
+    technology: 'Node',
+    description: 'Creates and updates models from the terminal.',
+    state: 'proposed',
+    rationale: 'A standalone binary is a deployable unit even with one command.',
+    author,
+  },
+
+  // --- the shape questions -------------------------------------------------
+  {
+    id: 'container:shared-ui',
+    kind: 'container',
+    label: 'subsystems-react (proposed container?)',
+    members: ['measured-dims'],
+    containerKind: 'application',
+    technology: 'React',
+    description: 'Shared graph UI, published as an npm package.',
+    state: 'proposed',
+    // Proposed as a container so the question is visible. There is no `library`
+    // kind to fall back on: c4model says a JAR/assembly/module "typically" is
+    // not an element at all, so a published package has to earn its box or be
+    // demoted into the containers that import it.
+    rationale:
+      'MEMBER OF THE COMPANION LIBRARY, not a runtime unit — no process of its own, imported by both renderers. Expected to be rejected or demoted.',
+    author,
+  },
+  {
+    id: 'container:model-store',
+    kind: 'container',
+    label: 'Subsystem model store',
+    members: ['model-disk-store', 'proposals-store'],
+    containerKind: 'data-store',
+    technology: 'JSON files under ~/.principal',
+    description: 'Every stored model and the correction queue, on local disk.',
+    state: 'proposed',
+    // The open Q2 decision: is this one C4 data-store container, or internals
+    // of the host that owns them?
+    rationale:
+      'Disk-backed and shared across the host and the CLI, which reads it. Whether C4 wants one data-store container or internals of the host is unresolved.',
+    author,
+  },
+  {
+    id: 'container:in-memory-state',
+    kind: 'container',
+    label: 'In-memory renderer state (proposed container?)',
+    // Two aliases nothing else claims. Rejecting this element is what makes
+    // them reappear in `unmapped` — which is the point: rejecting an element
+    // orphans whatever was in it, and the build says so out loud.
+    members: ['renderer-probe-cache', 'tab-order-cache'],
+    containerKind: 'application',
+    // Required by the type on every container, and empty on purpose: this is
+    // the shape the C4 notation forbids (process-lifetime state has no
+    // technology), and `summarizeElements` reports exactly this gap.
+    technology: '',
+    description: 'Module-level Sets and Maps that do not outlive the process.',
+    state: 'proposed',
+    rationale:
+      'Process-lifetime state, not durable storage. Belongs inside the renderer container as components, not beside it as its own container. Expected to be rejected.',
+    author,
+  },
+
+  // --- outside the boundary ----------------------------------------------
+  {
+    id: 'external:opencode2',
+    kind: 'external-system',
+    label: 'OpenCode v2 service',
+    members: ['opencode-v2-service'],
+    technology: 'HTTP',
+    description: 'Runs the maintain agent sessions this model is edited by.',
+    state: 'proposed',
+    rationale: 'Another system we call out to — a C4 software system, not one of our containers.',
+    author,
+  },
+  {
+    id: 'external:gists',
+    kind: 'external-system',
+    label: 'GitHub Gists API',
+    members: ['github-gists-api'],
+    technology: 'REST',
+    description: 'Publishes the portable model JSON as a gist.',
+    state: 'proposed',
+    author,
+  },
+  {
+    id: 'external:opencode-db',
+    kind: 'external-system',
+    label: 'opencode.db',
+    members: ['session-v2', 'event', 'session-message'],
+    // No technology field at all: C4 makes technology optional for an
+    // external system, and for a SQLite file the honest answer is "on disk".
+    description: 'Agent session transcripts, read by the host to build the timeline.',
+    state: 'proposed',
+    // Two models disagree about this: one claims these tables inside our
+    // system, another marks them external. Flagged rather than resolved.
+    rationale:
+      'CONFLICT — one stored model claims these tables inside the system, another marks the same tables external. Needs the user.',
+    author,
+  },
+  {
+    id: 'person:maintainer',
+    kind: 'person',
+    label: 'Maintain operator',
+    members: ['maintain-agent'],
+    description: 'Reviews and accepts the correction proposals this subsystem model accumulates.',
+    state: 'proposed',
+    rationale:
+      'C4 Person — no technology, by the notation. The only actor in the corpus; entityKind was never set on the underlying custom_entity.',
+    author,
+  },
+
+  // --- component level ----------------------------------------------------
+  {
+    id: 'component:boundary-layout',
+    kind: 'component',
+    label: 'Boundary layout builder',
+    members: ['build-boundary-layout', 'nest-groups'],
+    // Naming `container:shared-ui` as the parent is itself part of the open
+    // question: if that container is rejected, this component has no home and
+    // `buildC4Model` reports `unknown_container`.
+    container: 'container:shared-ui',
+    technology: 'React + ELK',
+    description: 'Turns module and process claims into nested compound frames.',
+    state: 'proposed',
+    author,
+  },
+  {
+    id: 'component:file-viewer',
+    kind: 'component',
+    label: 'Pierre file viewer',
+    members: ['file-panel'],
+    container: 'container:studio-renderer',
+    technology: 'React',
+    description: 'Opens the source slice a trail step points at.',
+    state: 'proposed',
+    author,
+  },
+  {
+    id: 'component:model-store-io',
+    kind: 'component',
+    label: 'Model store I/O',
+    members: ['store-create', 'store-list', 'read-file', 'store-file'],
+    container: 'container:studio-host',
+    technology: 'Bun fs',
+    description: 'Reads and writes model JSON under ~/.principal.',
+    state: 'proposed',
+    author,
+  },
+  {
+    id: 'component:audit-runner',
+    kind: 'component',
+    label: 'Audit runner',
+    members: ['audit-model', 'verify-files'],
+    // Deliberately dangling: points at a container that is not in this set, so
+    // the story shows what `unknown_container` looks like.
+    container: 'container:verifier',
+    technology: 'Bun',
+    description: 'Verifies every component claim in a model.',
+    state: 'proposed',
+    rationale: 'Named a container that does not exist yet — shows the build problem report.',
+    author,
+  },
+];
+
+/**
+ * A small document the elements above can be drawn against: the member aliases
+ * resolved, plus one trail so there is a line to draw.
+ *
+ * Only members named by an element appear. A component nobody claimed is
+ * deliberately absent — `buildC4Model` reports those as `unmapped` instead of
+ * inventing a home for them.
+ */
+export const c4FixtureDocument = {
+  components: [
+    { alias: 'store-create', name: 'createSubsystemModel', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/subsystem-model-store.ts' },
+    { alias: 'store-list', name: 'listSubsystemModels', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/subsystem-model-store.ts' },
+    { alias: 'verify-files', name: 'verifyModelFiles', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/subsystem-model-store.ts' },
+    { alias: 'resolve-root', name: 'resolveRepoRootForComponent', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/subsystem-model-store.ts' },
+    { alias: 'audit-model', name: 'auditSubsystemModel', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/verify-subsystem-component.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/verify-subsystem-component.ts' },
+    { alias: 'http-put', name: 'handleSubsystemModelRequest', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/http-server.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/http-server.ts' },
+    { alias: 'http-propose', name: 'postSubsystemModelProposal', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/proposal-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/proposal-store.ts' },
+    { alias: 'register-roots', name: 'registerRepoRoots', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/alexandria.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/alexandria.ts' },
+    { alias: 'tab-registry', name: 'tabs', construct: 'store' as const, file: 'packages/subsystems-studio/src/bun/index.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/index.ts', declaration: { kind: 'store' as const, storage: 'memory' as const, properties: [] } },
+    { alias: 'live-feed-store', name: 'OpencodeLiveFeedState', construct: 'store' as const, file: 'packages/subsystems-studio/src/bun/opencode-v2-live.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/opencode-v2-live.ts', declaration: { kind: 'store' as const, storage: 'memory' as const, properties: [] } },
+    { alias: 'maintain-probe-registry', name: 'MaintainerProbeRegistry', construct: 'store' as const, file: 'packages/subsystems-studio/src/bun/maintainer-probe.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/maintainer-probe.ts', declaration: { kind: 'store' as const, storage: 'memory' as const, properties: [] } },
+    { alias: 'run-store', name: 'SubsystemModelRunStore', construct: 'store' as const, file: 'packages/subsystems-studio/src/bun/subsystem-model-runs.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/subsystem-model-runs.ts', declaration: { kind: 'store' as const, storage: 'disk' as const, properties: [] } },
+    { alias: 'graphify-store', name: 'ensureCaches', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/graphify-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/graphify-store.ts' },
+    { alias: 'proposal-create', name: 'createSubsystemModelProposal', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/proposal-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/proposal-store.ts' },
+    { alias: 'proposal-accept', name: 'acceptSubsystemModelProposal', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/proposal-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/proposal-store.ts' },
+    { alias: 'maintain-orchestrator', name: 'maintainSubsystemModel', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/maintain-model.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/maintain-model.ts' },
+    { alias: 'run-maintain-agent', name: 'runMaintainAgent', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/maintain-model.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/maintain-model.ts' },
+    { alias: 'ensure-graphify', name: 'ensureCaches', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/graphify-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/graphify-store.ts' },
+    { alias: 'store-file', name: 'writeFile', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/subsystem-model-store.ts' },
+    { alias: 'read-file', name: 'readSubsystemFile', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/index.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/index.ts' },
+    { alias: 'close-tab', name: 'closeTabById', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/index.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/index.ts' },
+    { alias: 'open-tab', name: 'openSubsystemModelTab', construct: 'function' as const, file: 'packages/subsystems-studio/src/bun/index.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/index.ts' },
+
+    { alias: 'subsystems-view', name: 'SubsystemsModelsView', construct: 'function' as const, file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx' },
+    { alias: 'model-view', name: 'SubsystemModelView', construct: 'function' as const, file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx' },
+    { alias: 'regular-audit-view', name: 'RegularAuditView', construct: 'function' as const, file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx' },
+    { alias: 'list-view', name: 'listView', construct: 'function' as const, file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx' },
+    { alias: 'file-panel', name: 'FilePanel', construct: 'function' as const, file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx' },
+    { alias: 'rpc-bridge', name: 'electrobun', construct: 'store' as const, file: 'packages/subsystems-studio/src/mainview/rpc.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/rpc.ts', declaration: { kind: 'store' as const, properties: [] } },
+    { alias: 'reload-subs', name: 'reloadSubscribers', construct: 'store' as const, file: 'packages/subsystems-studio/src/mainview/rpc.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/rpc.ts', declaration: { kind: 'store' as const, properties: [] } },
+    { alias: 'regular-audit-subscribers', name: 'regularAuditChangeSubscribers', construct: 'store' as const, file: 'packages/subsystems-studio/src/mainview/rpc.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/rpc.ts', declaration: { kind: 'store' as const, properties: [] } },
+    { alias: 'app-shell', name: 'App', construct: 'function' as const, file: 'packages/subsystems-studio/src/mainview/App.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/App.tsx' },
+    { alias: 'tab-strip', name: 'TabStrip', construct: 'function' as const, file: 'packages/subsystems-studio/src/mainview/components/TabStrip.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/components/TabStrip.tsx' },
+    { alias: 'graph-view', name: 'SubsystemComponentGraph', construct: 'function' as const, file: 'packages/subsystems-react/src/subsystem/SubsystemComponentGraph.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-react/src/subsystem/SubsystemComponentGraph.tsx' },
+    { alias: 'detail-graph', name: 'DetailGraph', construct: 'function' as const, file: 'packages/subsystems-react/src/subsystem/SubsystemComponentGraph.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-react/src/subsystem/SubsystemComponentGraph.tsx' },
+    { alias: 'is-model-viewed', name: 'isModelViewed', construct: 'function' as const, file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx' },
+    { alias: 'preloadHighlighter', name: 'preloadHighlighter', construct: 'external' as const, file: '', purl: 'pkg:npm/@pierre/diffs' },
+    { alias: 'SharedHighlighter', name: 'SharedHighlighter', construct: 'external' as const, file: '', purl: 'pkg:npm/@pierre/diffs' },
+    { alias: 'CodeView', name: 'CodeView', construct: 'external' as const, file: '', purl: 'pkg:npm/@pierre/diffs' },
+
+    { alias: 'cli-create', name: 'create', construct: 'function' as const, file: 'packages/principal-studio-cli/src/commands/subsystem-model.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/principal-studio-cli/src/commands/subsystem-model.ts' },
+
+    { alias: 'nest-groups', name: 'nestCompoundGroups', construct: 'function' as const, file: 'packages/subsystems-react/src/utils/elkLayout.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-react/src/utils/elkLayout.ts' },
+    { alias: 'build-boundary-layout', name: 'buildBoundaryLayoutGroups', construct: 'function' as const, file: 'packages/subsystems-react/src/subsystem/model.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-react/src/subsystem/model.ts' },
+    { alias: 'measured-dims', name: 'measuredDimsRef', construct: 'store' as const, file: 'packages/subsystems-react/src/subsystem/SubsystemComponentGraph.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-react/src/subsystem/SubsystemComponentGraph.tsx', declaration: { kind: 'store' as const, properties: [] } },
+
+    { alias: 'model-disk-store', name: '~/.principal/subsystem-models', construct: 'store' as const, file: '', purl: 'external:file:~/.principal/subsystem-models', declaration: { kind: 'store' as const, storage: 'disk' as const, properties: [] } },
+    { alias: 'proposals-store', name: 'SubsystemModelProposalStore', construct: 'store' as const, file: 'packages/subsystems-studio/src/bun/proposal-store.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/proposal-store.ts', declaration: { kind: 'store' as const, storage: 'disk' as const, properties: [] } },
+
+    { alias: 'opencode-v2-service', name: 'OpenCode v2 service', construct: 'external' as const, file: '', purl: 'external:opencode/v2-service' },
+    { alias: 'github-gists-api', name: 'GitHub Gists API', construct: 'external' as const, file: '', purl: 'external:api.github.com/gists' },
+    { alias: 'session-v2', name: 'session_v2', construct: 'external' as const, file: '', purl: 'external:opencode.db/session-v2' },
+    { alias: 'event', name: 'event', construct: 'external' as const, file: '', purl: 'external:opencode.db/event' },
+    { alias: 'session-message', name: 'session_message', construct: 'external' as const, file: '', purl: 'external:opencode.db/session-message' },
+    { alias: 'renderer-probe-cache', name: 'rendererProbeCache', construct: 'store' as const, file: 'packages/subsystems-studio/src/mainview/rpc.ts', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/rpc.ts', declaration: { kind: 'store' as const, storage: 'memory' as const, properties: [] } },
+    { alias: 'tab-order-cache', name: 'tabOrderCache', construct: 'store' as const, file: 'packages/subsystems-studio/src/mainview/components/TabStrip.tsx', purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/components/TabStrip.tsx', declaration: { kind: 'store' as const, storage: 'memory' as const, properties: [] } },
+
+    { alias: 'maintain-agent', name: 'Maintenance agent (OpenCode) session', construct: 'custom_entity' as const, file: '', purl: 'external' },
+  ],
+  trails: [
+    {
+      id: 'tl-audit',
+      title: 'Run a dry-run audit from the Audit button',
+      steps: [
+        { from: 'model-view', to: 'audit-model', mechanism: 'calls' as const, file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx', line: 443, purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/views/SubsystemModelView.tsx', symbol: 'SubsystemModelView' },
+        { from: 'audit-model', to: 'model-disk-store', mechanism: 'writes' as const, file: 'packages/subsystems-studio/src/bun/verify-subsystem-component.ts', line: 950, purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/verify-subsystem-component.ts', symbol: 'auditSubsystemModel' },
+        { from: 'subsystems-view', to: 'model-view', mechanism: 'feeds' as const, file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx', line: 1152, purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx', symbol: 'openSubsystemModel' },
+        { from: 'subsystems-view', to: 'file-panel', mechanism: 'uses' as const, file: 'packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx', line: 958, purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/mainview/views/SubsystemModelsView.tsx', symbol: 'onShowAuditReport' },
+      ],
+    },
+    {
+      id: 'tl-maintain',
+      title: 'Maintain run posts a correction proposal',
+      steps: [
+        { from: 'maintain-orchestrator', to: 'run-maintain-agent', mechanism: 'calls' as const, file: 'packages/subsystems-studio/src/bun/maintain-model.ts', line: 854, purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/maintain-model.ts', symbol: 'maintainSubsystemModel' },
+        { from: 'run-maintain-agent', to: 'opencode-v2-service', mechanism: 'calls' as const, file: 'packages/subsystems-studio/src/bun/maintain-model.ts', line: 651, purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/maintain-model.ts', symbol: 'runMaintainAgent' },
+        { from: 'opencode-v2-service', to: 'maintain-agent', mechanism: 'feeds' as const, file: 'packages/subsystems-studio/src/bun/maintain-model.ts', line: 650, purl: 'external:opencode/v2-service#packages/subsystems-studio/src/bun/maintain-model.ts', symbol: 'runMaintainAgent' },
+        { from: 'http-propose', to: 'proposal-create', mechanism: 'calls' as const, file: 'packages/subsystems-studio/src/bun/http-server.ts', line: 404, purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/http-server.ts', symbol: 'handleSubsystemModelRequest' },
+        { from: 'proposal-create', to: 'proposals-store', mechanism: 'writes' as const, file: 'packages/subsystems-studio/src/bun/proposal-store.ts', line: 554, purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/proposal-store.ts', symbol: 'createSubsystemModelProposal' },
+        { from: 'maintain-orchestrator', to: 'run-store', mechanism: 'writes' as const, file: 'packages/subsystems-studio/src/bun/maintain-model.ts', line: 892, purl: 'pkg:github/acme/subsystem-modeling#packages/subsystems-studio/src/bun/maintain-model.ts', symbol: 'noteSubsystemModelRunStart' },
+      ],
+    },
+  ],
+} as const;
+
+/** Elements the author is asking a question about, surfaced in the story. */
+export const c4OpenQuestions = c4ProposedElements
+  .filter((a) => a.rationale && /(CONFLICT|not a|Expected to be|whether|Needs|one deployable unit)/.test(a.rationale))
+  .map((a) => ({ id: a.id, label: a.label, rationale: a.rationale! }));

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

@@ -469,7 +469,7 @@ const MAINTAIN_ISSUES: SubsystemIssue[] = [
   },
   {
     id: 'mr-symbol-unmatched',
-    severity: 'info',
+    severity: 'error',
     kind: 'symbol_unmatched',
     message:
       'No graphify node matches symbol readSse in packages/subsystems-studio/src/bun/opencode-v2-live.ts',

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

@@ -84,7 +84,7 @@ const ISSUES: SubsystemIssue[] = [
   },
   {
     id: 'i18',
-    severity: 'info',
+    severity: 'error',
     kind: 'symbol_unmatched',
     message: 'No Graphify node matches symbol persistSession in src/session/SessionStore.ts',
     target: { kind: 'component', id: 'session-store', label: 'SessionStore' },

package/src/subsystem/C4Graph.tsx

@@ -1,7 +1,7 @@
 /**
  * C4Graph — a C4 projection of a (composed) subsystem model on React Flow.
  *
- * Prototype test case: feed it a `C4Model` from `toC4()` and it draws the
+ * Feed it a `C4Model` from `buildC4Model()` and it draws the
  * system as a compound frame, its containers (or components) as boxes, and
  * externals/actors outside the system. `trail` steps render as flow
  * edges. Click a box to list the source components it rolled up.
@@ -26,9 +26,9 @@ import {
 import { useTheme } from '@principal-ade/industry-theme';
 import { computeElkLayout } from '../utils/elkLayout';
 import { MECHANISM_COLOR } from './model';
-import { C4NodeCard, NODE_H, NODE_W, nodeStyle } from './C4NodeCard';
+import { C4NodeCard, NODE_H, NODE_W, nodeSize, nodeStyle } from './C4NodeCard';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
-import type { C4Model, C4Node } from './toC4';
+import type { C4Model, C4Node } from './c4';
 
 export interface C4GraphProps {
   model: C4Model;
@@ -130,15 +130,24 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     setReady(false);
     setSelectedId(null);
 
-    const rfNodes: Node[] = model.nodes.map((n, i) => ({
-      id: n.id,
-      type: 'c4-node',
-      position: { x: (i % 5) * (NODE_W + 44), y: Math.floor(i / 5) * (NODE_H + 44) },
-      width: NODE_W,
-      height: NODE_H,
-      ...(n.parentId ? { parentId: n.parentId } : {}),
-      data: { node: n, selected: false },
-    }));
+    // Per-node size, so a square component is laid out as a square. Feeding the
+    // container dimensions for everything would make ELK reserve 210x138 of
+    // space around a 132x132 box and space the component view twice as far
+    // apart as it needs.
+    const rfNodes: Node[] = model.nodes.map((n, i) => {
+      const size = nodeSize(n);
+      return {
+        id: n.id,
+        type: 'c4-node',
+        // Fallback grid pitch uses the container box — the largest, so the
+        // pre-layout positions never overlap. ELK replaces them on success.
+        position: { x: (i % 5) * (NODE_W + 44), y: Math.floor(i / 5) * (NODE_H + 44) },
+        width: size.width,
+        height: size.height,
+        ...(n.parentId ? { parentId: n.parentId } : {}),
+        data: { node: n, selected: false },
+      };
+    });
 
     const groups = model.groups.map((g) => ({
       id: g.id,
@@ -147,8 +156,8 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     }));
 
     const rfEdges: Edge[] = model.edges.map((e) => {
-      const flow = e.kind === 'flow';
-      const color = flow ? edgeColor(e.mechanisms[0], muted) : (theme.colors.border ?? '#666');
+      // Every edge here came from a trail step, so the mechanism colours apply.
+      const color = edgeColor(e.mechanisms[0], muted);
       return {
         id: e.id,
         source: e.source,
@@ -159,7 +168,7 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
         style: {
           stroke: color,
           strokeWidth: 1 + Math.min(e.count, 6) * 0.4,
-          ...(flow ? { strokeDasharray: '6 4' } : {}),
+          strokeDasharray: '6 4',
         },
         markerEnd: { type: MarkerType.ArrowClosed, color, width: 18, height: 18 },
         data: { edge: e },
@@ -241,7 +250,10 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [layoutKey]);
 
-  const selected = useMemo(() => model.nodes.find((n) => n.id === selectedId) ?? null, [model, selectedId]);
+  const selected = useMemo(
+    () => model.nodes.find((n) => n.id === selectedId) ?? null,
+    [model, selectedId],
+  );
 
   const displayNodes = useMemo(
     () =>
@@ -254,7 +266,9 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
   );
 
   const runtime = model.nodes.filter((n) => n.kind === 'container' || n.kind === 'component').length;
-  const outside = model.nodes.filter((n) => n.kind === 'external' || n.kind === 'actor').length;
+  const outside = model.nodes.filter(
+    (n) => n.kind === 'external-system' || n.kind === 'person',
+  ).length;
 
   return (
     <div style={{ position: 'relative', width: '100%', height: '100%', background: theme.colors.background }}>
@@ -369,22 +383,23 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
               }}
             >
               <span style={{ color: nodeStyle(selected, theme).color }}>
-                {selected.decoration?.state ?? 'unconfirmed'} · {selected.decoration?.type ?? 'no type'}
+                {selected.state}
+                {selected.containerKind ? ` · ${selected.containerKind}` : ` · ${selected.kind}`}
               </span>
-              {selected.decoration?.technology ? (
-                <span>technology: {selected.decoration.technology}</span>
+              {selected.technology ? (
+                <span>technology: {selected.technology}</span>
               ) : (
                 <span style={{ color: theme.colors.warning ?? '#e8a33a' }}>technology: not stated</span>
               )}
-              {selected.decoration?.description ? (
-                <span style={{ whiteSpace: 'normal', lineHeight: 1.4 }}>{selected.decoration.description}</span>
+              {selected.description ? (
+                <span style={{ whiteSpace: 'normal', lineHeight: 1.4 }}>{selected.description}</span>
               ) : (
                 <span style={{ color: theme.colors.warning ?? '#e8a33a' }}>description: not stated</span>
               )}
               {/* A merge hides its inputs, so always show what it absorbed. */}
-              {selected.sourceKeys && selected.sourceKeys.length > 1 && (
+              {selected.derivedFrom && selected.derivedFrom.length > 1 && (
                 <span style={{ whiteSpace: 'normal', lineHeight: 1.4 }}>
-                  merged from: {selected.sourceKeys.join(', ')}
+                  consolidated from: {selected.derivedFrom.join(', ')}
                 </span>
               )}
             </div>