Phase 7A+7C: Subsystem aggregator + Flow tracer (post-review fixes)

test/fixtures/system-docs/architecture.md

@@ -0,0 +1,17 @@
+# Mock Architecture Documentation
+
+## Purpose
+This is a test fixture simulating a real repo's architecture.md file.
+
+## Layered Architecture
+The system follows a layered architecture:
+- **Channels** receive inbound messages from external platforms
+- **Gateway** manages sessions and routes requests
+- **Agents** execute AI model interactions
+- **Config** provides centralized configuration
+- **Utils** provides shared infrastructure (logging, crypto, filesystem)
+
+## Design Decisions
+- Gateway and Agents have a deliberate circular dependency for session refresh workflows
+- Config is loaded lazily and cached in memory
+- Utils are stateless pure functions with no domain logic

test/fixtures/system-docs/expected-contracts.json

@@ -0,0 +1,104 @@
+{
+  "contracts": [
+    {
+      "id": "gateway/types.ts:GatewayConfig",
+      "type": "Interface",
+      "name": "GatewayConfig",
+      "extends": ["BaseConfig"],
+      "fields": [
+        { "name": "sessionKey", "type": "string" },
+        { "name": "timeout", "type": "number" }
+      ]
+    },
+    {
+      "id": "gateway/types.ts:SessionEntry",
+      "type": "Interface",
+      "name": "SessionEntry",
+      "fields": [
+        { "name": "key", "type": "string" },
+        { "name": "agentId", "type": "string" },
+        { "name": "model", "type": "string" }
+      ]
+    },
+    {
+      "id": "agents/scope.ts:AgentScope",
+      "type": "Interface",
+      "name": "AgentScope",
+      "fields": [
+        { "name": "agentId", "type": "string" },
+        { "name": "tools", "type": "string[]" }
+      ]
+    },
+    {
+      "id": "agents/types.ts:AgentConfig",
+      "type": "Interface",
+      "name": "AgentConfig",
+      "fields": [
+        { "name": "agentId", "type": "string" },
+        { "name": "model", "type": "string" },
+        { "name": "maxTokens", "type": "number" }
+      ]
+    },
+    {
+      "id": "agents/types.ts:AgentResult",
+      "type": "Interface",
+      "name": "AgentResult",
+      "fields": [
+        { "name": "output", "type": "string" },
+        { "name": "tokensUsed", "type": "number" },
+        { "name": "duration", "type": "number" }
+      ]
+    },
+    {
+      "id": "agents/types.ts:AgentStatus",
+      "type": "TypeAlias",
+      "name": "AgentStatus"
+    },
+    {
+      "id": "config/types.ts:BaseConfig",
+      "type": "Interface",
+      "name": "BaseConfig",
+      "fields": [
+        { "name": "defaultAgent", "type": "string" },
+        { "name": "model", "type": "string" },
+        { "name": "debug", "type": "boolean" }
+      ]
+    },
+    {
+      "id": "config/types.ts:ProviderConfig",
+      "type": "Interface",
+      "name": "ProviderConfig",
+      "fields": [
+        { "name": "name", "type": "string" },
+        { "name": "apiKey", "type": "string" },
+        { "name": "baseUrl", "type": "string" }
+      ]
+    },
+    {
+      "id": "config/types.ts:LogLevel",
+      "type": "Enum",
+      "name": "LogLevel",
+      "members": ["Debug", "Info", "Warn", "Error"]
+    },
+    {
+      "id": "config/schema.ts:SchemaDefinition",
+      "type": "Interface",
+      "name": "SchemaDefinition",
+      "fields": [
+        { "name": "name", "type": "string" },
+        { "name": "version", "type": "string" },
+        { "name": "fields", "type": "SchemaField[]" }
+      ]
+    },
+    {
+      "id": "config/schema.ts:SchemaField",
+      "type": "Interface",
+      "name": "SchemaField",
+      "fields": [
+        { "name": "name", "type": "string" },
+        { "name": "type", "type": "string" },
+        { "name": "required", "type": "boolean" }
+      ]
+    }
+  ]
+}

test/fixtures/system-docs/expected-deps.json

@@ -0,0 +1,17 @@
+{
+  "edges": [
+    { "from": "gateway", "to": "agents", "type": "CALLS", "via": ["gateway/session.ts:refreshSession→agents/runner.ts:runAgent"] },
+    { "from": "gateway", "to": "config", "type": "IMPORTS", "via": ["gateway/session.ts→config/config.ts", "gateway/types.ts→config/types.ts"] },
+    { "from": "gateway", "to": "utils", "type": "CALLS", "via": ["gateway/middleware.ts:applyMiddleware→utils/logger.ts:log", "gateway/utils.ts:formatSessionKey→utils/logger.ts:log"] },
+    { "from": "agents", "to": "gateway", "type": "CALLS", "via": ["agents/runner.ts:reloadAgent→gateway/session.ts:loadSession"] },
+    { "from": "agents", "to": "config", "type": "IMPORTS", "via": ["agents/scope.ts→config/config.ts"] },
+    { "from": "agents", "to": "utils", "type": "CALLS", "via": ["agents/runner.ts:runAgent→utils/logger.ts:log", "agents/scope.ts:createAgentScope→utils/logger.ts:log", "agents/tools.ts→utils/logger.ts:log"] },
+    { "from": "channels", "to": "gateway", "type": "CALLS", "via": ["channels/telegram.ts:onTelegramMessage→gateway/server.ts:handleRequest", "channels/discord.ts:onDiscordMessage→gateway/server.ts:handleRequest"] },
+    { "from": "channels", "to": "utils", "type": "CALLS", "via": ["channels/telegram.ts→utils/logger.ts:log", "channels/discord.ts→utils/logger.ts:log"] },
+    { "from": "config", "to": "utils", "type": "CALLS", "via": ["config/config.ts:loadConfigFromDisk→utils/logger.ts:log"] },
+    { "from": "utils", "to": "utils", "type": "CALLS", "via": ["utils/fs-helpers.ts→utils/logger.ts:log"] }
+  ],
+  "cycles": [
+    { "subsystems": ["gateway", "agents"], "via": "gateway/session.ts↔agents/runner.ts" }
+  ]
+}

test/fixtures/system-docs/expected-flows.json

@@ -0,0 +1,26 @@
+{
+  "flows": [
+    {
+      "entryPoint": "channels/telegram.ts:onTelegramMessage",
+      "subsystemSequence": ["channels", "gateway", "agents"],
+      "flow": [
+        { "subsystem": "channels", "entity": "channels/telegram.ts:onTelegramMessage", "depth": 0 },
+        { "subsystem": "gateway", "entity": "gateway/server.ts:handleRequest", "depth": 1, "crossedVia": "CALLS" },
+        { "subsystem": "gateway", "entity": "gateway/session.ts:loadSession", "depth": 1.5, "crossedVia": "CALLS" }
+      ],
+      "cyclesDetected": []
+    },
+    {
+      "entryPoint": "gateway/session.ts:refreshSession",
+      "subsystemSequence": ["gateway", "agents"],
+      "flow": [
+        { "subsystem": "gateway", "entity": "gateway/session.ts:refreshSession", "depth": 0 },
+        { "subsystem": "gateway", "entity": "gateway/session.ts:loadSession", "depth": 0.5, "crossedVia": "CALLS" },
+        { "subsystem": "agents", "entity": "agents/runner.ts:runAgent", "depth": 1, "crossedVia": "CALLS" }
+      ],
+      "cyclesDetected": [
+        { "at": "agents/runner.ts:reloadAgent", "backEdgeTo": "gateway/session.ts:loadSession" }
+      ]
+    }
+  ]
+}

test/fixtures/system-docs/expected-subsystems.json

@@ -0,0 +1,52 @@
+{
+  "subsystems": [
+    {
+      "name": "gateway",
+      "kind": "domain",
+      "files": [
+        "gateway/server.ts",
+        "gateway/session.ts",
+        "gateway/middleware.ts",
+        "gateway/types.ts",
+        "gateway/utils.ts"
+      ]
+    },
+    {
+      "name": "agents",
+      "kind": "domain",
+      "files": [
+        "agents/runner.ts",
+        "agents/scope.ts",
+        "agents/tools.ts",
+        "agents/types.ts",
+        "agents/defaults.ts"
+      ]
+    },
+    {
+      "name": "channels",
+      "kind": "domain",
+      "files": [
+        "channels/telegram.ts",
+        "channels/discord.ts"
+      ]
+    },
+    {
+      "name": "config",
+      "kind": "cross-cutting",
+      "files": [
+        "config/config.ts",
+        "config/types.ts",
+        "config/schema.ts"
+      ]
+    },
+    {
+      "name": "utils",
+      "kind": "cross-cutting",
+      "files": [
+        "utils/logger.ts",
+        "utils/crypto.ts",
+        "utils/fs-helpers.ts"
+      ]
+    }
+  ]
+}

test/fixtures/system-docs/src/agents/defaults.ts

@@ -0,0 +1,12 @@
+// Fixture: agents/defaults.ts — default agent configuration
+import { AgentConfig } from './types';
+
+export const DEFAULT_AGENT: AgentConfig = {
+  agentId: 'default',
+  model: 'claude-sonnet-4',
+  maxTokens: 4096,
+};
+
+export function getDefaultAgent(): AgentConfig {
+  return { ...DEFAULT_AGENT };
+}

test/fixtures/system-docs/src/agents/runner.ts

@@ -0,0 +1,23 @@
+// Fixture: agents/runner.ts — agent execution (circular dep with gateway/session.ts)
+import { loadSession } from '../gateway/session';
+import { AgentScope } from './scope';
+import { log } from '../utils/logger';
+
+export function runAgent(session: { key: string; agentId: string; model: string }): string {
+  log('running agent ' + session.agentId);
+  const scope = createScope(session.agentId);
+  return executeAgent(scope, session.model);
+}
+
+function createScope(agentId: string): AgentScope {
+  return { agentId, tools: getDefaultTools() };
+}
+
+function executeAgent(scope: AgentScope, model: string): string {
+  return `result from ${scope.agentId} on ${model}`;
+}
+
+export function reloadAgent(key: string): string {
+  const session = loadSession(key);  // circular: agents calls gateway
+  return runAgent(session);
+}

test/fixtures/system-docs/src/agents/scope.ts

@@ -0,0 +1,18 @@
+// Fixture: agents/scope.ts — agent scope management
+import { getConfig } from '../config/config';
+import { log } from '../utils/logger';
+
+export interface AgentScope {
+  agentId: string;
+  tools: string[];
+}
+
+export function createAgentScope(agentId: string): AgentScope {
+  log('creating scope for ' + agentId);
+  const config = getConfig();
+  return { agentId, tools: getDefaultTools() };
+}
+
+export function getDefaultTools(): string[] {
+  return ['read', 'write', 'exec', 'web_search'];
+}

test/fixtures/system-docs/src/agents/tools.ts

@@ -0,0 +1,15 @@
+// Fixture: agents/tools.ts — tool registry
+import { log } from '../utils/logger';
+
+export function registerTool(name: string, handler: Function): void {
+  log('registering tool: ' + name);
+}
+
+export function executeTool(name: string, args: Record<string, unknown>): unknown {
+  log('executing tool: ' + name);
+  return null;
+}
+
+export function listTools(): string[] {
+  return ['read', 'write', 'exec', 'web_search', 'browser'];
+}

test/fixtures/system-docs/src/agents/types.ts

@@ -0,0 +1,14 @@
+// Fixture: agents/types.ts — agent type definitions
+export interface AgentConfig {
+  agentId: string;
+  model: string;
+  maxTokens: number;
+}
+
+export interface AgentResult {
+  output: string;
+  tokensUsed: number;
+  duration: number;
+}
+
+export type AgentStatus = 'idle' | 'running' | 'done' | 'error';

test/fixtures/system-docs/src/channels/discord.ts

@@ -0,0 +1,12 @@
+// Fixture: channels/discord.ts — Discord channel adapter
+import { handleRequest } from '../gateway/server';
+import { log } from '../utils/logger';
+
+export function onDiscordMessage(guildId: string, channelId: string, text: string): void {
+  log('discord message in ' + guildId);
+  const session = handleRequest('discord:' + guildId + ':' + channelId);
+}
+
+export function sendDiscordReply(channelId: string, message: string): void {
+  log('sending discord reply to ' + channelId);
+}

test/fixtures/system-docs/src/channels/telegram.ts

@@ -0,0 +1,12 @@
+// Fixture: channels/telegram.ts — Telegram channel adapter
+import { handleRequest } from '../gateway/server';
+import { log } from '../utils/logger';
+
+export function onTelegramMessage(chatId: string, text: string): void {
+  log('telegram message from ' + chatId);
+  const session = handleRequest('telegram:' + chatId);
+}
+
+export function sendTelegramReply(chatId: string, message: string): void {
+  log('sending reply to ' + chatId);
+}

test/fixtures/system-docs/src/config/config.ts

@@ -0,0 +1,22 @@
+// Fixture: config/config.ts — central configuration
+import { BaseConfig } from './types';
+import { log } from '../utils/logger';
+
+let _config: BaseConfig | null = null;
+
+export function getConfig(): BaseConfig {
+  if (!_config) {
+    _config = loadConfigFromDisk();
+  }
+  return _config;
+}
+
+function loadConfigFromDisk(): BaseConfig {
+  log('loading config from disk');
+  return { defaultAgent: 'default', model: 'claude-sonnet-4', debug: false };
+}
+
+export function reloadConfig(): void {
+  _config = null;
+  getConfig();
+}

test/fixtures/system-docs/src/config/schema.ts

@@ -0,0 +1,18 @@
+// Fixture: config/schema.ts — ORPHAN FILE (no inbound edges, only exports)
+// This file is imported by nobody — tests orphan handling
+
+export interface SchemaDefinition {
+  name: string;
+  version: string;
+  fields: SchemaField[];
+}
+
+export interface SchemaField {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'object';
+  required: boolean;
+}
+
+export function validateSchema(schema: SchemaDefinition): boolean {
+  return schema.fields.length > 0 && schema.version.length > 0;
+}

test/fixtures/system-docs/src/config/types.ts

@@ -0,0 +1,19 @@
+// Fixture: config/types.ts — base config types (imported by gateway/types.ts)
+export interface BaseConfig {
+  defaultAgent: string;
+  model: string;
+  debug: boolean;
+}
+
+export interface ProviderConfig {
+  name: string;
+  apiKey: string;
+  baseUrl: string;
+}
+
+export enum LogLevel {
+  Debug = 'debug',
+  Info = 'info',
+  Warn = 'warn',
+  Error = 'error',
+}

test/fixtures/system-docs/src/gateway/middleware.ts

@@ -0,0 +1,12 @@
+// Fixture: gateway/middleware.ts — request middleware
+import { log } from '../utils/logger';
+import { SessionEntry } from './types';
+
+export function applyMiddleware(session: SessionEntry): void {
+  log('applying middleware for ' + session.key);
+  validateSession(session);
+}
+
+function validateSession(session: SessionEntry): boolean {
+  return session.key.length > 0;
+}

test/fixtures/system-docs/src/gateway/server.ts

@@ -0,0 +1,18 @@
+// Fixture: gateway/server.ts — main gateway entry point
+import { loadSession, saveSession } from './session';
+import { applyMiddleware } from './middleware';
+import { GatewayConfig, SessionEntry } from './types';
+
+export function startGateway(config: GatewayConfig): void {
+  const session = loadSession(config.sessionKey);
+  applyMiddleware(session);
+}
+
+export function handleRequest(sessionKey: string): SessionEntry {
+  const session = loadSession(sessionKey);
+  return session;
+}
+
+export function shutdownGateway(): void {
+  // cleanup
+}

test/fixtures/system-docs/src/gateway/session.ts

@@ -0,0 +1,19 @@
+// Fixture: gateway/session.ts — session management (has circular dep with agents/runner.ts)
+import { getConfig } from '../config/config';
+import { runAgent } from '../agents/runner';
+import { SessionEntry } from './types';
+
+export function loadSession(key: string): SessionEntry {
+  const config = getConfig();
+  return { key, agentId: config.defaultAgent, model: config.model };
+}
+
+export function saveSession(entry: SessionEntry): void {
+  // persist
+}
+
+export function refreshSession(key: string): SessionEntry {
+  const session = loadSession(key);
+  runAgent(session);  // circular: gateway calls agents, agents call gateway
+  return session;
+}

test/fixtures/system-docs/src/gateway/types.ts

@@ -0,0 +1,15 @@
+// Fixture: gateway/types.ts — re-exports from config/types + gateway-specific types
+import { BaseConfig } from '../config/types';
+
+export interface GatewayConfig extends BaseConfig {
+  sessionKey: string;
+  timeout: number;
+}
+
+export interface SessionEntry {
+  key: string;
+  agentId: string;
+  model: string;
+}
+
+export { BaseConfig } from '../config/types';

test/fixtures/system-docs/src/gateway/utils.ts

@@ -0,0 +1,7 @@
+// Fixture: gateway/utils.ts — gateway-specific helpers
+import { log } from '../utils/logger';
+
+export function formatSessionKey(prefix: string, id: string): string {
+  log('formatting key');
+  return `${prefix}:${id}`;
+}

test/fixtures/system-docs/src/utils/crypto.ts

@@ -0,0 +1,13 @@
+// Fixture: utils/crypto.ts — crypto helpers
+export function hashString(input: string): string {
+  return Buffer.from(input).toString('base64');
+}
+
+export function generateToken(length: number): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return result;
+}

test/fixtures/system-docs/src/utils/fs-helpers.ts

@@ -0,0 +1,15 @@
+// Fixture: utils/fs-helpers.ts — file system helpers
+import { log } from './logger';
+
+export function readFileSync(path: string): string {
+  log('reading ' + path);
+  return '';
+}
+
+export function writeFileSync(path: string, content: string): void {
+  log('writing ' + path);
+}
+
+export function fileExists(path: string): boolean {
+  return false;
+}

test/fixtures/system-docs/src/utils/logger.ts

@@ -0,0 +1,14 @@
+// Fixture: utils/logger.ts — cross-cutting utility (high fan-in)
+// Imported by almost every other module — tests cross-cutting detection
+
+export function log(message: string): void {
+  console.log(`[${new Date().toISOString()}] ${message}`);
+}
+
+export function warn(message: string): void {
+  console.warn(`[WARN] ${message}`);
+}
+
+export function error(message: string, err?: Error): void {
+  console.error(`[ERROR] ${message}`, err?.message || '');
+}