septum 0.1.2 → 0.1.4

package/src/mcp/server.ts

@@ -41,10 +41,12 @@ import {
 import { handleGetSymbol } from "./tools/get-symbol.ts";
 import { handleGetSymbolImpact } from "./tools/get-symbol-impact.ts";
 import { handleRegisterDomain } from "./tools/register-domain.ts";
+import { handleGetEnvironmentTopology } from "./tools/get-environment-topology.ts";
 import type { GetSymbolArgs, GetSymbolImpactArgs } from "../types/index.ts";
 import {
   CheckBoundarySchema,
   GetDomainCatalogSchema,
+  GetEnvironmentTopologySchema,
   GetFeatureContextSchema,
   GetSymbolHotspotsSchema,
   GetSymbolImpactSchema,
@@ -54,12 +56,51 @@ import {
   TraceVerticalSliceSchema,
 } from "./schemas.ts";
 import { SEPTUM_VERSION } from "../version.ts";
+import { resolveWorkspaceRoot } from "../core/resolver/path-resolver.ts";
+import type { ValidatedSeptumConfig } from "../core/config/schema.ts";
 
-export async function runMCPServer(): Promise<void> {
-  const config = ConfigLoader.load();
+interface WorkspaceContext {
+  root: string;
+  config: ValidatedSeptumConfig;
+  db: SeptumDatabase;
+  repo: SeptumRepository;
+  evaluator: BoundaryEvaluator;
+  pipeline: IngestionPipeline;
+}
+
+const workspaceContextCache = new Map<string, WorkspaceContext>();
+
+function extractPathHint(args: Record<string, any> | undefined): string | undefined {
+  if (!args) return undefined;
+  if (typeof args.workspace_path === "string" && args.workspace_path) return args.workspace_path;
+  if (typeof args.target_path === "string" && args.target_path) return args.target_path;
+  if (typeof args.project_root === "string" && args.project_root) return args.project_root;
+  if (typeof args.file_path === "string" && args.file_path) return args.file_path;
+  if (Array.isArray(args.file_paths) && args.file_paths[0]) return args.file_paths[0];
+  if (typeof args.root === "string" && args.root) return args.root;
+  return undefined;
+}
+
+function getWorkspaceContext(pathHint?: string): WorkspaceContext {
+  const root = resolveWorkspaceRoot(pathHint);
+  let ctx = workspaceContextCache.get(root);
+  if (ctx) {
+    return ctx;
+  }
+
+  const config = ConfigLoader.load(undefined, root);
   const db = new SeptumDatabase(config.settings.db_path);
   const repo = new SeptumRepository(db.raw);
   const evaluator = new BoundaryEvaluator(repo);
+  const pipeline = new IngestionPipeline(repo, root);
+
+  ctx = { root, config, db, repo, evaluator, pipeline };
+  workspaceContextCache.set(root, ctx);
+  return ctx;
+}
+
+export async function runMCPServer(): Promise<void> {
+  const initialCtx = getWorkspaceContext();
 
   const server = new Server(
     {
@@ -141,7 +182,7 @@ export async function runMCPServer(): Promise<void> {
         {
           name: "septum_get_symbol_hotspots",
           description:
-            "Discovers oversized functions, methods, and classes exceeding a specified line count threshold (default: 30 lines). Essential for Single Responsibility Principle (SRP) enforcement, finding God Functions, and isolating refactoring targets deterministically without reading raw files.",
+            "Discovers oversized functions, methods, and classes exceeding a specified line count threshold or cyclomatic control flow nesting depth (> 4). Essential for Single Responsibility Principle (SRP) enforcement, finding God Functions / bug magnets, and isolating refactoring targets deterministically without reading raw files.",
           inputSchema: {
             type: "object",
             properties: {
@@ -149,6 +190,10 @@ export async function runMCPServer(): Promise<void> {
                 type: "number",
                 description: "Minimum physical lines of code (LoC) threshold (default: 30).",
               },
+              min_nesting: {
+                type: "number",
+                description: "Minimum control-flow nesting depth (e.g. nested if/for/while/try > 4).",
+              },
               kind: {
                 type: "string",
                 description: "Filter by symbol kind ('function', 'method', 'class', 'struct', 'interface').",
@@ -161,6 +206,11 @@ export async function runMCPServer(): Promise<void> {
                 type: "number",
                 description: "Maximum results to return (default: 30).",
               },
+              sort_by: {
+                type: "string",
+                enum: ["lines", "nesting", "risk_score"],
+                description: "Sorting criteria: 'risk_score' (combines lines & nesting depth), 'nesting', or 'lines'. Default: 'risk_score'.",
+              },
             },
           },
         },
@@ -290,6 +340,41 @@ export async function runMCPServer(): Promise<void> {
             required: ["name", "root"],
           },
         },
+        {
+          name: "septum_get_environment_topology",
+          description:
+            "Self-Aware Production Topology Engine: Maps and verifies the 6-layer environment topology (Edge/WAF, Gateway/Web Server, Host Platform, Runtime, Storage/Cache, Telemetry). Identifies cross-layer constraints (e.g. Cloudflare + LiteSpeed + Laravel throttle), surfaces pending architectural inquiries if layers are ambiguous, and allows recording verified environment answers to SQLite SSOT.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              resolve: {
+                type: "object",
+                properties: {
+                  layer: {
+                    type: "string",
+                    enum: ["edge", "gateway", "host", "runtime", "storage", "telemetry"],
+                    description: "Target layer to manually resolve/verify",
+                  },
+                  platform: {
+                    type: "string",
+                    description: "Confirmed platform name (e.g. 'Hostinger Shared Hosting', 'Cloudflare WAF', 'LiteSpeed')",
+                  },
+                  constraints: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional list of architectural constraints for this layer",
+                  },
+                },
+                required: ["layer", "platform"],
+                description: "Optional argument to record and verify a specific layer into SQLite SSOT",
+              },
+              refresh: {
+                type: "boolean",
+                description: "Force re-detection from codebase files, ignoring cached status",
+              },
+            },
+          },
+        },
       ],
     };
   });
@@ -297,7 +382,10 @@ export async function runMCPServer(): Promise<void> {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const startTime = performance.now();
-    const activeSession = SessionManager.getActiveSession(process.cwd());
+    const pathHint = extractPathHint(args as Record<string, any>);
+    const ctx = getWorkspaceContext(pathHint);
+
+    const activeSession = SessionManager.getActiveSession(ctx.root);
     const sessionPayload = activeSession
       ? { feature_key: activeSession.feature_key, domain: activeSession.domain }
       : null;
@@ -316,7 +404,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetDomainCatalog(repo, config, parsed.data);
+        return handleGetDomainCatalog(ctx.repo, ctx.config, parsed.data, ctx.root);
       } else if (name === "septum_get_feature_context") {
         const parsed = GetFeatureContextSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -330,7 +418,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetFeatureContext(repo, config, parsed.data);
+        return handleGetFeatureContext(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_locate_symbol") {
         const parsed = LocateSymbolSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -344,7 +432,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleLocateSymbol(repo, config, parsed.data);
+        return await handleLocateSymbol(ctx.repo, ctx.config, parsed.data, ctx.pipeline, ctx.root);
       } else if (name === "septum_get_symbol") {
         const parsed = GetSymbolSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -358,7 +446,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetSymbol(repo, config, parsed.data);
+        return handleGetSymbol(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_get_symbol_impact") {
         const parsed = GetSymbolImpactSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -372,7 +460,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetSymbolImpact(repo, config, parsed.data);
+        return handleGetSymbolImpact(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_trace_vertical_slice") {
         const parsed = TraceVerticalSliceSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -386,7 +474,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleTraceVerticalSlice(repo, config, parsed.data);
+        return handleTraceVerticalSlice(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_clear_feature_context") {
         const cleared = handleClearFeatureContext();
         return {
@@ -412,7 +500,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleCheckBoundary(evaluator, config, parsed.data);
+        return handleCheckBoundary(ctx.evaluator, ctx.config, parsed.data, ctx.repo);
       } else if (name === "septum_get_symbol_hotspots") {
         const parsed = GetSymbolHotspotsSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -426,7 +514,7 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return handleGetSymbolHotspots(repo, config, parsed.data);
+        return handleGetSymbolHotspots(ctx.repo, ctx.config, parsed.data);
       } else if (name === "septum_register_domain") {
         const parsed = RegisterDomainSchema.safeParse(args ?? {});
         if (!parsed.success) {
@@ -440,7 +528,21 @@ export async function runMCPServer(): Promise<void> {
             ],
           };
         }
-        return await handleRegisterDomain(repo, config, parsed.data);
+        return await handleRegisterDomain(ctx.repo, ctx.config, parsed.data);
+      } else if (name === "septum_get_environment_topology") {
+        const parsed = GetEnvironmentTopologySchema.safeParse(args ?? {});
+        if (!parsed.success) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `[Septum Validation Error] Invalid arguments for ${name}: ${parsed.error.message}`,
+              },
+            ],
+          };
+        }
+        return handleGetEnvironmentTopology(ctx.repo, ctx.config, parsed.data, ctx.root);
       } else {
         throw new Error(`Unknown tool: '${name}'`);
       }
@@ -468,7 +570,7 @@ export async function runMCPServer(): Promise<void> {
         input: (args as Record<string, any>) ?? {},
         metrics: { bytes_out: bytesOut, lines_out: linesOut },
         session: sessionPayload,
-        status: response?.isError ? "error" : "success",
+        status: (response as { isError?: boolean } | undefined)?.isError ? "error" : "success",
       });
 
       return response;
@@ -522,7 +624,7 @@ export async function runMCPServer(): Promise<void> {
   ]);
 
   try {
-    const bgPipeline = new IngestionPipeline(repo);
+    const bgPipeline = initialCtx.pipeline;
     const cwd = process.cwd();
 
     fsWatcher = watch(cwd, { recursive: true }, (_event, filename) => {
@@ -569,13 +671,14 @@ export async function runMCPServer(): Promise<void> {
         // Ignore watcher close errors during shutdown
       }
     }
-    try {
-      db.close();
-      console.error("[Septum MCP] Database connection closed cleanly.");
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(`[Septum MCP] Error closing database during cleanup: ${msg}`);
+    for (const ctx of workspaceContextCache.values()) {
+      try {
+        ctx.db.close();
+      } catch (err) {
+        // Ignore close error during shutdown
+      }
     }
+    console.error("[Septum MCP] All database connections closed cleanly.");
     process.exit(0);
   };
 
@@ -590,11 +693,12 @@ export async function runMCPServer(): Promise<void> {
         // Ignore watcher close errors
       }
     }
-    try {
-      db.close();
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(`[Septum MCP] Error closing database on beforeExit: ${msg}`);
+    for (const ctx of workspaceContextCache.values()) {
+      try {
+        ctx.db.close();
+      } catch {
+        // Ignore close error
+      }
     }
   });
 

package/src/mcp/tools/check-boundary.ts

@@ -1,23 +1,44 @@
 import type { BoundaryEvaluator } from "../../core/boundary/evaluator.ts";
 import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
+import type { SeptumRepository } from "../../core/database/repository.ts";
 
 export interface CheckBoundaryArgs {
   file_path?: string;
+  filePath?: string;
+  file?: string;
+  path?: string;
   file_paths?: string[];
+  filePaths?: string[];
+  files?: string[];
+  paths?: string[];
   proposed_imports?: string[];
+  proposedImports?: string[];
+  imports?: string[];
   feature_key?: string;
+  featureKey?: string;
+  feature?: string;
 }
 
 export function handleCheckBoundary(
   evaluator: BoundaryEvaluator,
   config: ValidatedSeptumConfig,
-  args: CheckBoundaryArgs
+  args: CheckBoundaryArgs,
+  repo?: SeptumRepository
 ) {
+  const rawFilePaths = args.file_paths ?? args.filePaths ?? args.files ?? args.paths;
+  const rawFilePath = args.file_path ?? args.filePath ?? args.file ?? args.path;
+  const proposedImports = args.proposed_imports ?? args.proposedImports ?? args.imports ?? [];
+  const featureKey = args.feature_key ?? args.featureKey ?? args.feature;
+
   const filesToCheck: string[] = [];
-  if (args.file_paths && Array.isArray(args.file_paths) && args.file_paths.length > 0) {
-    filesToCheck.push(...args.file_paths);
-  } else if (args.file_path) {
-    filesToCheck.push(args.file_path);
+  if (rawFilePaths && Array.isArray(rawFilePaths) && rawFilePaths.length > 0) {
+    filesToCheck.push(...rawFilePaths);
+  } else if (rawFilePath) {
+    if (Array.isArray(rawFilePath)) {
+      filesToCheck.push(...rawFilePath);
+    } else {
+      filesToCheck.push(rawFilePath);
+    }
   } else {
     throw new Error("Missing required argument: specify either 'file_path' or 'file_paths'");
   }
@@ -25,11 +46,20 @@ export function handleCheckBoundary(
   // Multi-file batch evaluation
   if (filesToCheck.length > 1) {
     const results = filesToCheck.map((filePath) => {
-      const violations = evaluator.evaluate(filePath, args.proposed_imports ?? [], args.feature_key, config);
+      const violations = evaluator.evaluate(filePath, proposedImports, featureKey, config);
+      const impact = repo?.getFileInboundImpact(filePath);
       return {
         file: filePath,
         status: violations.length > 0 ? "rejected" : "approved",
         violations,
+        impact_summary: impact
+          ? {
+              direct_dependents: impact.direct_dependents_count,
+              top_consumers: impact.top_consumers,
+              symbols_count: impact.symbols_count,
+              risk_level: impact.risk_level,
+            }
+          : undefined,
       };
     });
 
@@ -60,7 +90,8 @@ export function handleCheckBoundary(
 
   // Single file evaluation (backward-compatible output)
   const singleFile = filesToCheck[0];
-  const violations = evaluator.evaluate(singleFile, args.proposed_imports ?? [], args.feature_key, config);
+  const violations = evaluator.evaluate(singleFile, proposedImports, featureKey, config);
+  const impact = repo?.getFileInboundImpact(singleFile);
 
   if (violations.length > 0) {
     return {
@@ -73,6 +104,14 @@ export function handleCheckBoundary(
               file: singleFile,
               violations_count: violations.length,
               violations,
+              impact_summary: impact
+                ? {
+                    direct_dependents: impact.direct_dependents_count,
+                    top_consumers: impact.top_consumers,
+                    symbols_count: impact.symbols_count,
+                    risk_level: impact.risk_level,
+                  }
+                : undefined,
               message: "Boundary violation detected. Proposed imports violate bounded context architecture.",
             },
             null,
@@ -91,7 +130,18 @@ export function handleCheckBoundary(
           {
             status: "approved",
             file: singleFile,
-            message: "No boundary violations detected. Proposed imports are permissible.",
+            impact_summary: impact
+              ? {
+                  direct_dependents: impact.direct_dependents_count,
+                  top_consumers: impact.top_consumers,
+                  symbols_count: impact.symbols_count,
+                  risk_level: impact.risk_level,
+                }
+              : undefined,
+            message:
+              impact && impact.direct_dependents_count > 0
+                ? `No boundary violations detected. Caution: ${impact.direct_dependents_count} dependent file(s) consume this file.`
+                : "No boundary violations detected. Proposed imports are permissible.",
           },
           null,
           2

package/src/mcp/tools/get-domain-catalog.ts

@@ -6,15 +6,45 @@ import type { SeptumRepository } from "../../core/database/repository.ts";
 export interface GetDomainCatalogArgs {
   domain?: string;
   archetype_filter?: string;
+  workspace_path?: string;
 }
 
 export function handleGetDomainCatalog(
   repo: SeptumRepository,
   config: ValidatedSeptumConfig,
-  args: GetDomainCatalogArgs
+  args: GetDomainCatalogArgs,
+  workspaceRoot?: string
 ) {
   if (!args.domain) {
     const allDomains = repo.getAllDomains();
+    if (allDomains.length === 0) {
+      const root = workspaceRoot || process.cwd();
+      const diagnostic = {
+        status: "NOT_INDEXED",
+        total_domains: 0,
+        message: `Workspace '${root}' belum memiliki domain terdaftar dalam Septum catalog.`,
+        suggested_action: {
+          tool: "septum_register_domain",
+          params: {
+            name: "core",
+            root: "src",
+            ingest_now: true,
+          },
+        },
+        agent_guidance:
+          "Panggil tool 'septum_register_domain(name: \"core\", root: \"src\", ingest_now: true)' untuk mendaftarkan dan mengindeks domain utama secara otomatis, atau jalankan 'septum init' di terminal workspace.",
+      };
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(diagnostic, null, 2),
+          },
+        ],
+        metadata: diagnostic,
+      };
+    }
+
     const projectType = repo.getMeta("project_type") || "generic";
     const framework = repo.getMeta("framework") || "unknown";
     const archStyle = repo.getMeta("architecture_style") || "modular";

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-symbol-hotspots.ts

@@ -4,9 +4,11 @@ import type { SymbolKind } from "../../types/index.ts";
 
 export interface GetSymbolHotspotsArgs {
   min_lines?: number;
-  kind?: SymbolKind;
+  min_nesting?: number;
+  kind?: SymbolKind | string;
   domain?: string;
   limit?: number;
+  sort_by?: "lines" | "nesting" | "risk_score";
 }
 
 export function handleGetSymbolHotspots(
@@ -14,23 +16,31 @@ export function handleGetSymbolHotspots(
   _config: ValidatedSeptumConfig,
   args: GetSymbolHotspotsArgs
 ) {
-  const minLines = args.min_lines ?? 30;
+  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,
-    kind: args.kind,
+    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,