septum 0.1.3 → 0.1.5

package/src/mcp/tools/get-environment-topology.ts

@@ -0,0 +1,141 @@
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
+import { EnvironmentDetector } from "../../core/topology/environment-detector.ts";
+import type { EnvironmentLayer, ResolveLayerInput, ResolveNodeInput } from "../../core/topology/types.ts";
+
+export interface GetEnvironmentTopologyArgs {
+  resolve?: ResolveLayerInput;
+  resolveNode?: ResolveNodeInput;
+  refresh?: boolean;
+}
+
+export function handleGetEnvironmentTopology(
+  repo: SeptumRepository,
+  _config: ValidatedSeptumConfig,
+  args: GetEnvironmentTopologyArgs,
+  workspaceRoot: string
+) {
+  // If layer resolution input is provided, persist into SQLite SSOT
+  if (args.resolve) {
+    const existing = repo.environment.getLayer(args.resolve.layer);
+    repo.environment.saveLayer({
+      layer: args.resolve.layer,
+      platform: args.resolve.platform,
+      canonical_tag: EnvironmentDetector.matchCanonicalTag(args.resolve.platform),
+      status: "VERIFIED",
+      constraints: args.resolve.constraints && args.resolve.constraints.length > 0 ? args.resolve.constraints : (existing?.constraints ?? []),
+      detected_from: ["Manual Developer Resolution via Septum"],
+    });
+  }
+
+  // If node resolution input is provided, persist node into SQLite SSOT
+  if (args.resolveNode) {
+    repo.environment.saveNode({
+      id: args.resolveNode.id,
+      layer: args.resolveNode.layer,
+      name: args.resolveNode.name,
+      platform: args.resolveNode.platform,
+      canonical_tag: args.resolveNode.canonical_tag || EnvironmentDetector.matchCanonicalTag(args.resolveNode.platform),
+      domain_or_ip: args.resolveNode.domain_or_ip,
+      role: args.resolveNode.role,
+      status: "VERIFIED",
+      detected_from: ["Manual Developer Resolution via Septum MCP"],
+      constraints: args.resolveNode.constraints ?? [],
+      connected_to: args.resolveNode.connected_to ?? [],
+    });
+  }
+
+  // Detect current topology merging heuristics with SQLite SSOT
+  const topology = EnvironmentDetector.detect(workspaceRoot, repo, args.refresh);
+
+  // Format into high-density Markdown output
+  let output = `### 🌐 Septum Environment & Topology Plane\n\n`;
+  output += `> **Overall Status:** \`${topology.overall_status}\`\n`;
+  output += `> **Topology Mode:** \`${topology.is_distributed ? "DISTRIBUTED MULTI-NODE GRAPH" : "MONOLITHIC SINGLE-NODE"}\`\n`;
+  output += `> **Architecture:** ${topology.architectural_summary}\n\n`;
+
+  // Section 1: Distributed Nodes Graph
+  if (topology.nodes.length > 0) {
+    output += `#### 📦 Distributed Topology Nodes (${topology.nodes.length} entities):\n`;
+    output += `| Node ID | Layer | Platform / Specs | Role | Domain / Host | Connected To | Status |\n`;
+    output += `| :--- | :--- | :--- | :--- | :--- | :--- | :--- |\n`;
+    for (const node of topology.nodes) {
+      const statusBadge = node.status === "VERIFIED" ? "✅ VERIFIED" : node.status === "DETECTED" ? "🔍 DETECTED" : "⚠️ " + node.status;
+      const domain = node.domain_or_ip ? `\`${node.domain_or_ip}\`` : "-";
+      const role = node.role ? `\`${node.role}\`` : "-";
+      const connected = node.connected_to && node.connected_to.length > 0 ? node.connected_to.join(", ") : "-";
+      output += `| **\`${node.id}\`** | ${node.layer.toUpperCase()} | ${node.platform} | ${role} | ${domain} | ${connected} | ${statusBadge} |\n`;
+    }
+    output += `\n`;
+  }
+
+  // Section 2: 6-Layer Summary
+  output += `#### 🗺️ 6-Layer Plane Summary:\n`;
+  output += `| Layer | Plane Domain | Platform / Setup | Status | Evidence / Files |\n`;
+  output += `| :--- | :--- | :--- | :--- | :--- |\n`;
+
+  const layerLabels: Record<EnvironmentLayer, string> = {
+    edge: "Perimeter & WAF",
+    gateway: "Ingress & Web Server",
+    host: "Deployment Platform",
+    runtime: "Application Engine",
+    storage: "Data & Cache",
+    telemetry: "Observability & Logs",
+  };
+
+  for (const layerKey of Object.keys(topology.layers) as EnvironmentLayer[]) {
+    const info = topology.layers[layerKey];
+    const evidence = info.detected_from && info.detected_from.length > 0 ? info.detected_from.join(", ") : "-";
+    const statusBadge = info.status === "VERIFIED" ? "✅ VERIFIED" : info.status === "DETECTED" ? "🔍 DETECTED" : "⚠️ " + info.status;
+    output += `| **${layerKey.toUpperCase()}** | ${layerLabels[layerKey]} | ${info.platform || "Not Defined"} | ${statusBadge} | ${evidence} |\n`;
+  }
+
+  // Section 3: Active Constraints
+  output += `\n#### 📌 Active Architectural Constraints:\n`;
+  let hasConstraints = false;
+  for (const node of topology.nodes) {
+    if (node.constraints && node.constraints.length > 0) {
+      hasConstraints = true;
+      output += `- **\`${node.id}\` (${node.platform}):**\n`;
+      for (const c of node.constraints) {
+        output += `  • ${c}\n`;
+      }
+    }
+  }
+  if (!hasConstraints) {
+    output += `*No specific node constraints recorded.*\n`;
+  }
+
+  // Section 4: Cross-Layer & Distributed Interplays
+  if (topology.interplays.length > 0) {
+    output += `\n#### ⚡ Cross-Layer & Distributed Invariants:\n`;
+    for (const interplay of topology.interplays) {
+      const nodeTrace = interplay.involved_node_ids && interplay.involved_node_ids.length > 0 ? ` (Nodes: \`${interplay.involved_node_ids.join(", ")}\`)` : "";
+      output += `- **${interplay.title}** (Layers: \`${interplay.involved_layers.join(" ➔ ")}\`)${nodeTrace}:\n`;
+      output += `  • *Invarian:* ${interplay.risk_or_rule}\n`;
+      output += `  • *Tindakan Wajib:* ${interplay.required_action}\n`;
+    }
+  }
+
+  // Section 5: Pending Inquiries
+  if (topology.pending_inquiries.length > 0) {
+    output += `\n#### ❓ Pending Architectural Inquiries (Self-Aware Inquiry Required):\n`;
+    output += `Terdapat layer atau node arsitektural yang belum terkonfirmasi. Sebelum mengeksekusi kode terkait deployment/throttling/cron/cookies, klarifikasikan hal berikut ke pengguna:\n`;
+    for (const q of topology.pending_inquiries) {
+      output += `- ${q}\n`;
+    }
+    output += `\n*Untuk mengunci jawaban pengguna ke SQLite SSOT, panggil kembali tool ini dengan argumen:*\n`;
+    output += `\`septum_get_environment_topology(resolve: { layer: "<layer_name>", platform: "<platform_name>" })\`\n`;
+    output += `*atau untuk entitas terdistribusi:*\n`;
+    output += `\`septum_get_environment_topology(resolveNode: { id: "<node_id>", layer: "<layer>", name: "<name>", platform: "<platform>", domain_or_ip: "<domain_or_ip>", role: "<role>" })\`\n`;
+  }
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: output,
+      },
+    ],
+  };
+}

package/src/mcp/tools/get-feature-context.ts

@@ -1,116 +1,212 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
-import type { SeptumRepository } from "../../core/database/repository.ts";
-import { SessionManager } from "../../core/session/session-manager.ts";
-import type { FeatureContextResponse } from "../../types/index.ts";
-
-export interface GetFeatureContextArgs {
-  feature: string;
-}
-
-export function handleClearFeatureContext(workspaceRoot: string = process.cwd()): boolean {
-  return SessionManager.clearActiveSession(workspaceRoot);
-}
-
-export function handleGetFeatureContext(
-  repo: SeptumRepository,
-  config: ValidatedSeptumConfig,
-  args: GetFeatureContextArgs
-) {
-  if (!args.feature) {
-    throw new Error("Missing required argument: 'feature'");
-  }
-
-  const features = config.features ?? {};
-  const featureConfig = features[args.feature];
-
-  if (!featureConfig) {
-    const available = Object.keys(features).join(", ") || "none";
-    throw new Error(
-      `Feature '${args.feature}' not found in configuration. Available features: [${available}]`
-    );
-  }
-
-  // Record Active Feature Session Lease (.septum/session.json)
-  SessionManager.saveActiveSession(process.cwd(), {
-    feature_key: args.feature,
-    domain: featureConfig.domain,
-    touchpoints: featureConfig.allowed_touchpoints ?? [],
-    locked_at: new Date().toISOString(),
-  });
-
-  // Deterministically fetch signatures, methods, and properties for reuse_symbols from SQLite
-  const reuseSymbolsWithMeta: FeatureContextResponse["reuse_symbols"] = [];
-  const requestedSymbols = featureConfig.reuse_symbols ?? [];
-
-  for (const symName of requestedSymbols) {
-    const record = repo.findSymbolWithMembers(symName);
-    if (record) {
-      reuseSymbolsWithMeta.push({
-        name: record.symbol_name,
-        kind: record.kind,
-        signature: record.signature,
-        methods: record.methods.length > 0 ? record.methods : undefined,
-        properties: record.properties.length > 0 ? record.properties : undefined,
-        file_path: record.file_path,
-        domain: record.domain_name,
-      });
-    } else {
-      reuseSymbolsWithMeta.push({
-        name: symName,
-        kind: "unknown",
-        domain: featureConfig.domain,
-      });
-    }
-  }
-
-  const response: FeatureContextResponse = {
-    feature: args.feature,
-    domain: featureConfig.domain,
-    description: featureConfig.description,
-    allowed_touchpoints: featureConfig.allowed_touchpoints,
-    reuse_symbols: reuseSymbolsWithMeta,
-    input_contract: (featureConfig.input_contract as Record<string, unknown>) ?? {},
-    output_contract: (featureConfig.output_contract as Record<string, unknown>) ?? {},
-    governance_directives: [
-      "DO NOT modify or edit any files outside allowed_touchpoints.",
-      "DO NOT create duplicate helpers/services; reuse the existing symbols and methods declared in reuse_symbols.",
-      "DO NOT emit or expect phantom payload fields outside input_contract and output_contract.",
-      "DO NOT import cross-domain modules without declared allowed_dependencies in Septum domain boundaries.",
-    ],
-  };
-
-  recordFeatureAccess(featureConfig.domain, args.feature);
-
-  return {
-    content: [
-      {
-        type: "text" as const,
-        text: JSON.stringify(response, null, 2),
-      },
-    ],
-  };
-}
-
-function recordFeatureAccess(domain: string, feature: string): void {
-  try {
-    const septumDir = path.resolve(process.cwd(), ".septum");
-    if (!fs.existsSync(septumDir)) {
-      fs.mkdirSync(septumDir, { recursive: true });
-    }
-    const logPath = path.join(septumDir, "catalog_access.json");
-    let log: { domains?: Record<string, string>; features?: Record<string, string> } = {};
-    if (fs.existsSync(logPath)) {
-      try {
-        log = JSON.parse(fs.readFileSync(logPath, "utf-8"));
-      } catch {}
-    }
-    log.domains = log.domains || {};
-    log.features = log.features || {};
-    const now = new Date().toISOString();
-    log.domains[domain] = now;
-    log.features[feature] = now;
-    fs.writeFileSync(logPath, JSON.stringify(log, null, 2), "utf-8");
-  } catch {}
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
+import { SessionManager } from "../../core/session/session-manager.ts";
+import type { FeatureContextResponse } from "../../types/index.ts";
+
+export interface GetFeatureContextArgs {
+  feature_key?: string;
+  feature?: string;
+  workspace_path?: string;
+}
+
+export function handleClearFeatureContext(workspaceRoot: string = process.cwd()): boolean {
+  return SessionManager.clearActiveSession(workspaceRoot);
+}
+
+export function handleGetFeatureContext(
+  repo: SeptumRepository,
+  config: ValidatedSeptumConfig,
+  args: GetFeatureContextArgs,
+  workspaceRoot: string = process.cwd()
+) {
+  const featureKey = (args.feature_key || args.feature || "").trim();
+  const features = config.features ?? {};
+
+  // ZERO-ARGUMENT GRACEFUL FALLBACK: Guide the agent instead of throwing validation errors
+  if (!featureKey) {
+    const available = Object.keys(features);
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(
+            {
+              status: "prompt",
+              message: "No feature specified. Please specify 'feature_key' from the registered features below or trace routes.",
+              available_features: available.length > 0 ? available : [],
+              instructions: "Call 'septum_get_feature_context({ feature_key: \"<name>\" })' or register a new feature with 'septum_register_feature'.",
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+
+  let featureConfig = features[featureKey];
+  let isInferred = false;
+
+  if (!featureConfig) {
+    // Attempt auto-derive from vertical slices or domain symbols
+    const searchTerm = featureKey.toLowerCase();
+    const allSlices = typeof repo.getAllVerticalSlices === "function" ? repo.getAllVerticalSlices() : [];
+    const fromRepoSearch = typeof repo.findVerticalSlices === "function" ? repo.findVerticalSlices(searchTerm) : [];
+    const matchingSlices = [
+      ...fromRepoSearch,
+      ...allSlices.filter(
+        (s) =>
+          s.route_uri.toLowerCase().includes(searchTerm) ||
+          (s.route_name && s.route_name.toLowerCase().includes(searchTerm)) ||
+          s.controller_class.toLowerCase().includes(searchTerm) ||
+          (s.feature_key && s.feature_key.toLowerCase().includes(searchTerm))
+      ),
+    ];
+
+    const uniqueSlices = Array.from(
+      new Map(matchingSlices.map((s) => [`${s.http_method}:${s.route_uri}`, s])).values()
+    );
+
+    if (uniqueSlices.length > 0) {
+      isInferred = true;
+      const candidateTouchpoints = new Set<string>();
+      const candidateSymbols = new Set<string>();
+      let detectedDomain = "app";
+
+      if (config.domains && config.domains[featureKey]) {
+        detectedDomain = featureKey;
+      }
+
+      for (const slice of uniqueSlices) {
+        if (slice.controller_file) {
+          candidateTouchpoints.add(slice.controller_file);
+        }
+        candidateSymbols.add(slice.controller_class);
+        if (slice.action_name) {
+          candidateSymbols.add(`${slice.controller_class}@${slice.action_name}`);
+        }
+
+        if (slice.execution_chain_json) {
+          try {
+            const chain = JSON.parse(slice.execution_chain_json);
+            if (Array.isArray(chain)) {
+              for (const node of chain) {
+                if (node.file) candidateTouchpoints.add(node.file);
+                if (node.symbol) candidateSymbols.add(node.symbol);
+              }
+            }
+          } catch {}
+        }
+      }
+
+      featureConfig = {
+        domain: detectedDomain,
+        description: `[Auto-Derived] Feature context inferred from ${uniqueSlices.length} vertical slices matching '${featureKey}'`,
+        allowed_touchpoints: Array.from(candidateTouchpoints),
+        reuse_symbols: Array.from(candidateSymbols).slice(0, 10),
+        input_contract: {},
+        output_contract: {},
+      };
+    } else {
+      const available = Object.keys(features);
+      const availableStr = available.length > 0 ? available.join(", ") : "none";
+      const recoveryMessage = [
+        `Feature '${featureKey}' not found in configuration. Available features: [${availableStr}].`,
+        `No matching vertical slices found for auto-derivation.`,
+        ``,
+        `▶ RECOVERY OPTIONS:`,
+        `1. Register this feature on-the-fly:`,
+        `   septum_register_feature({ feature_key: "${featureKey}", domain: "<domain_name>", allowed_touchpoints: ["path/to/file"] })`,
+        `2. Or discover available routes / vertical slices first:`,
+        `   septum_trace_vertical_slice({ entry_file: "routes/web.php" })`,
+      ].join("\n");
+      throw new Error(recoveryMessage);
+    }
+  }
+
+  // Record Active Feature Session Lease (.septum/session.json)
+  SessionManager.saveActiveSession(workspaceRoot, {
+    feature_key: featureKey,
+    domain: featureConfig.domain,
+    touchpoints: featureConfig.allowed_touchpoints ?? [],
+    locked_at: new Date().toISOString(),
+  });
+
+  // Deterministically fetch signatures, methods, and properties for reuse_symbols from SQLite
+  const reuseSymbolsWithMeta: FeatureContextResponse["reuse_symbols"] = [];
+  const requestedSymbols = featureConfig.reuse_symbols ?? [];
+
+  for (const symName of requestedSymbols) {
+    const record = repo.findSymbolWithMembers(symName);
+    if (record) {
+      reuseSymbolsWithMeta.push({
+        name: record.symbol_name,
+        kind: record.kind,
+        signature: record.signature,
+        methods: record.methods.length > 0 ? record.methods : undefined,
+        properties: record.properties.length > 0 ? record.properties : undefined,
+        file_path: record.file_path,
+        domain: record.domain_name,
+      });
+    } else {
+      reuseSymbolsWithMeta.push({
+        name: symName,
+        kind: "unknown",
+        domain: featureConfig.domain,
+      });
+    }
+  }
+
+  const response: FeatureContextResponse = {
+    feature_key: featureKey,
+    feature: featureKey,
+    domain: featureConfig.domain,
+    description: featureConfig.description,
+    allowed_touchpoints: featureConfig.allowed_touchpoints,
+    reuse_symbols: reuseSymbolsWithMeta,
+    input_contract: (featureConfig.input_contract as Record<string, unknown>) ?? {},
+    output_contract: (featureConfig.output_contract as Record<string, unknown>) ?? {},
+    governance_directives: [
+      "DO NOT modify or edit any files outside allowed_touchpoints.",
+      "DO NOT create duplicate helpers/services; reuse the existing symbols and methods declared in reuse_symbols.",
+      "DO NOT emit or expect phantom payload fields outside input_contract and output_contract.",
+      "DO NOT import cross-domain modules without declared allowed_dependencies in Septum domain boundaries.",
+    ],
+    ...(isInferred ? { is_inferred: true } : {}),
+  };
+
+  recordFeatureAccess(featureConfig.domain, featureKey);
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(response, null, 2),
+      },
+    ],
+  };
+}
+
+function recordFeatureAccess(domain: string, feature: string): void {
+  try {
+    const septumDir = path.resolve(process.cwd(), ".septum");
+    if (!fs.existsSync(septumDir)) {
+      fs.mkdirSync(septumDir, { recursive: true });
+    }
+    const logPath = path.join(septumDir, "catalog_access.json");
+    let log: { domains?: Record<string, string>; features?: Record<string, string> } = {};
+    if (fs.existsSync(logPath)) {
+      try {
+        log = JSON.parse(fs.readFileSync(logPath, "utf-8"));
+      } catch {}
+    }
+    log.domains = log.domains || {};
+    log.features = log.features || {};
+    const now = new Date().toISOString();
+    log.domains[domain] = now;
+    log.features[feature] = now;
+    fs.writeFileSync(logPath, JSON.stringify(log, null, 2), "utf-8");
+  } catch {}
+}

package/src/mcp/tools/get-symbol-hotspots.ts

@@ -1,49 +1,60 @@
-import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
-import type { DatabaseRepository } from "../../core/database/repository.ts";
-import type { SymbolKind } from "../../types/index.ts";
-
-export interface GetSymbolHotspotsArgs {
-  min_lines?: number;
-  kind?: SymbolKind;
-  domain?: string;
-  limit?: number;
-}
-
-export function handleGetSymbolHotspots(
-  repo: DatabaseRepository,
-  _config: ValidatedSeptumConfig,
-  args: GetSymbolHotspotsArgs
-) {
-  const minLines = args.min_lines ?? 30;
-  const limit = args.limit ?? 30;
-
-  const hotspots = repo.getHotspotSymbols({
-    minLines,
-    kind: args.kind,
-    domain: args.domain,
-    limit,
-  });
-
-  const payload = {
-    total_found: hotspots.length,
-    threshold_min_lines: minLines,
-    hotspots: hotspots.map((h) => ({
-      name: h.name,
-      kind: h.kind,
-      line_count: h.line_count,
-      line_span: `${h.line_start}-${h.line_end}`,
-      file_path: h.file_path,
-      domain: h.domain_name,
-      signature: h.signature,
-    })),
-  };
-
-  return {
-    content: [
-      {
-        type: "text" as const,
-        text: JSON.stringify(payload, null, 2),
-      },
-    ],
-  };
-}
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { DatabaseRepository } from "../../core/database/repository.ts";
+import type { SymbolKind } from "../../types/index.ts";
+
+export interface GetSymbolHotspotsArgs {
+  min_lines?: number;
+  min_nesting?: number;
+  kind?: SymbolKind | string;
+  domain?: string;
+  limit?: number;
+  sort_by?: "lines" | "nesting" | "risk_score";
+}
+
+export function handleGetSymbolHotspots(
+  repo: DatabaseRepository,
+  _config: ValidatedSeptumConfig,
+  args: GetSymbolHotspotsArgs,
+  _workspaceRoot?: string
+) {
+  const minLines = args.min_lines ?? (args.min_nesting ? 0 : 30);
+  const minNesting = args.min_nesting ?? 1;
+  const limit = args.limit ?? 30;
+  const sortBy = args.sort_by ?? "risk_score";
+
+  const hotspots = repo.getHotspotSymbols({
+    minLines,
+    minNesting,
+    kind: args.kind as SymbolKind | undefined,
+    domain: args.domain,
+    limit,
+    sortBy,
+  });
+
+  const payload = {
+    total_found: hotspots.length,
+    threshold_min_lines: minLines,
+    threshold_min_nesting: minNesting,
+    sort_by: sortBy,
+    hotspots: hotspots.map((h) => ({
+      name: h.name,
+      kind: h.kind,
+      line_count: h.line_count,
+      nesting_depth: (h as any).nesting_depth ?? 1,
+      risk_score: (h as any).risk_score ?? h.line_count,
+      line_span: `${h.line_start}-${h.line_end}`,
+      file_path: h.file_path,
+      domain: h.domain_name,
+      signature: h.signature,
+    })),
+  };
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}

package/src/mcp/tools/get-symbol-impact.ts

@@ -1,26 +1,28 @@
-import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
-import type { SeptumRepository } from "../../core/database/repository.ts";
-import type { GetSymbolImpactArgs } from "../../types/index.ts";
-
-export function handleGetSymbolImpact(
-  repo: SeptumRepository,
-  _config: ValidatedSeptumConfig,
-  args: GetSymbolImpactArgs
-) {
-  if (!args.symbol) {
-    throw new Error(
-      "Missing required argument: 'symbol' (e.g. 'OrderService::cancelOrder', 'OrderService', or 'cancelOrder')"
-    );
-  }
-
-  const impact = repo.getSymbolImpact(args.symbol);
-
-  return {
-    content: [
-      {
-        type: "text" as const,
-        text: JSON.stringify(impact, null, 2),
-      },
-    ],
-  };
-}
+import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
+import type { GetSymbolImpactArgs } from "../../types/index.ts";
+
+export function handleGetSymbolImpact(
+  repo: SeptumRepository,
+  _config: ValidatedSeptumConfig,
+  args: GetSymbolImpactArgs,
+  _workspaceRoot?: string
+) {
+  const symbol = (args.symbol || (args as unknown as Record<string, unknown>).query || "").toString().trim();
+  if (!symbol) {
+    throw new Error(
+      "Missing required argument: 'symbol' (e.g. 'OrderService::cancelOrder', 'OrderService', or 'cancelOrder')"
+    );
+  }
+
+  const impact = repo.getSymbolImpact(symbol);
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(impact, null, 2),
+      },
+    ],
+  };
+}