septum 0.1.2 → 0.1.4

package/README.md

@@ -2,6 +2,7 @@
 
 > **Deterministic Bounded-Context & Anti-Poisoning Architecture Guard for AI Coding Agents.**
 
+[![Version: 0.1.4](https://img.shields.io/badge/Version-0.1.4-blue)](package.json)
 [![Runtime: Bun](https://img.shields.io/badge/Runtime-Bun-black?logo=bun)](https://bun.sh)
 [![Protocol: Model Context Protocol](https://img.shields.io/badge/Protocol-MCP-green)](https://modelcontextprotocol.io/)
 [![Database: SQLite WAL](https://img.shields.io/badge/Database-SQLite%20(bun:sqlite)-003B57?logo=sqlite)](https://sqlite.org/)
@@ -61,6 +62,9 @@ Add Septum to your MCP client (`mcp.json` or `claude_desktop_config.json`):
 | `septum sync` | Fast incremental delta sync (< 15ms) for modified files |
 | `septum check --strict` | CI/CD gate: verify boundary integrity & fail on violations |
 | `septum query [domain]` | Inspect domain catalog, archetypes, and public signatures |
+| `septum locate <query>` | Locate symbol, class, interface, method, or error source |
+| `septum slice <route\|intent>` | Trace end-to-end vertical execution slice for route/intent |
+| `septum topology [action]` | Inspect 6-layer environment topology plane & distributed nodes |
 | `septum feature status\|clear` | Manage active feature lease and editing scope |
 | `septum serve` | Launch stdio MCP server for AI coding agents |
 
@@ -70,12 +74,13 @@ Add Septum to your MCP client (`mcp.json` or `claude_desktop_config.json`):
 
 All tools expose typed schemas automatically via the Model Context Protocol:
 
+- **Self-Aware Environment Topology (`septum_get_environment_topology`):** Maps and verifies the 6-layer production architecture (Edge/WAF, Gateway/Web Server, Host, Runtime, Storage/Cache, Telemetry) and distributed entities with cross-layer invariants.
 - **Whole-Project Telescope (`septum_get_domain_catalog`):** Returns macro architecture maps in < 400 tokens.
-- **Vertical Slice Tracer (`septum_trace_vertical_slice`):** Traces execution chains (*Ingress ➔ Validation ➔ Orchestration ➔ Domain ➔ Egress*) across frameworks.
+- **Omni-Trigger Vertical Slice Tracer (`septum_trace_vertical_slice`):** Traces execution chains across HTTP routes, queue jobs, console commands, and event listeners (*Ingress ➔ Validation ➔ Orchestration ➔ Domain ➔ Egress*).
 - **Pre-Flight Boundary Guard (`septum_check_boundary`):** Validates proposed edits and imports against bounded-context rules.
 - **Scope Locking (`septum_get_feature_context` / `septum_clear_feature_context`):** Locks active feature scope to eliminate context drift.
 - **Symbol & Blast Radius (`septum_locate_symbol`, `septum_get_symbol`, `septum_get_symbol_impact`):** Resolves call chains, signatures, and refactoring impact.
-- **God Function Detector (`septum_get_symbol_hotspots`):** Surfaces oversized functions/methods by physical lines-of-code.
+- **God Function & Nesting Detector (`septum_get_symbol_hotspots`):** Surfaces oversized functions/methods ranked by physical lines, cyclomatic nesting depth, and composite risk score.
 - **Dynamic Topology (`septum_register_domain`):** Registers or updates domains and boundary rules on-the-fly.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "septum",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Deterministic Bounded-Context, Structural File Catalog & Anti-Poisoning Partition for AI Agents",
   "type": "module",
   "main": "src/index.ts",

package/src/cli/commands/slice.ts

@@ -20,57 +20,15 @@ export async function handleSliceCommand(
       return;
     }
 
-    if (result.found && result.slice) {
-      const s = result.slice;
-      console.log(`\n=================================================`);
-      console.log(`  VERTICAL SLICE: ${s.route.method} ${s.route.uri}`);
-      console.log(`=================================================`);
-      if (s.route.name) {
-        console.log(`  • Route Name:   ${s.route.name}`);
-      }
-
-      if (s.request) {
-        console.log(`\n  • Request Validation:`);
-        console.log(`      Class: ${s.request.class} (${s.request.file || "inline"})`);
-        const rules = Object.keys(s.request.rules);
-        if (rules.length > 0) {
-          console.log(`      Rules:`);
-          for (const r of rules) {
-            console.log(`        - ${r}: ${s.request.rules[r]}`);
-          }
-        }
-      }
-
-      console.log(`\n  • Controller Action:`);
-      console.log(`      Class:  ${s.controller.class}@${s.controller.action}`);
-      console.log(`      Target: ${s.controller.file || "unknown"}:${s.controller.line}`);
-
-      if (s.model) {
-        console.log(`\n  • Model:`);
-        console.log(`      Class:    ${s.model.class} (${s.model.file || "unknown"})`);
-        if (s.model.fillable && s.model.fillable.length > 0) {
-          console.log(`      Fillable: [${s.model.fillable.join(", ")}]`);
-        }
-        if (s.model.casts && Object.keys(s.model.casts).length > 0) {
-          console.log(`      Casts:    ${JSON.stringify(s.model.casts)}`);
-        }
-      }
-
-      if (s.frontend) {
-        console.log(`\n  • Frontend Target:`);
-        console.log(`      Page:  ${s.frontend.target}`);
-        if (s.frontend.props.length > 0) {
-          console.log(`      Props: [${s.frontend.props.join(", ")}]`);
-        }
-      }
-
+    if (result.found) {
+      console.log(`\n${result.message}\n`);
       if (result.alternatives && result.alternatives.length > 0) {
-        console.log(`\n  • Alternative Matches:`);
+        console.log(`  • Alternative Matches:`);
         for (const alt of result.alternatives) {
           console.log(`      - ${alt.method} ${alt.uri} -> ${alt.controller}@${alt.action}`);
         }
+        console.log(``);
       }
-      console.log(`\n=================================================\n`);
     } else {
       console.log(`\n❌ Vertical Slice Not Found:`);
       console.log(`   Query:   ${result.query}`);

package/src/cli/commands/topology.ts

@@ -0,0 +1,119 @@
+import { SeptumDatabase } from "../../core/database/client.ts";
+import { SeptumRepository } from "../../core/database/repository.ts";
+import { EnvironmentDetector } from "../../core/topology/environment-detector.ts";
+import type { EnvironmentLayer, TopologyNode } from "../../core/topology/types.ts";
+
+export async function handleTopologyCommand(
+  subcommand?: string,
+  arg1?: string,
+  arg2?: string,
+  arg3?: string,
+  arg4?: string
+): Promise<void> {
+  const cwd = process.cwd();
+  const db = new SeptumDatabase();
+  const repo = new SeptumRepository(db.raw);
+
+  if (subcommand === "resolve" && arg1 && arg2) {
+    const layer = arg1.toLowerCase() as EnvironmentLayer;
+    const platform = arg2;
+    // Fix: Preserve existing constraints instead of overwriting with empty array
+    const existing = repo.environment.getLayer(layer);
+    repo.environment.saveLayer({
+      layer,
+      platform,
+      canonical_tag: EnvironmentDetector.matchCanonicalTag(platform),
+      status: "VERIFIED",
+      detected_from: ["CLI Manual Resolution"],
+      constraints: existing?.constraints && existing.constraints.length > 0 ? existing.constraints : [
+        `Configured manually as '${platform}'.`
+      ],
+    });
+    console.log(`[Septum Topology] Layer '${layer}' successfully verified as '${platform}' in SQLite SSOT.\n`);
+  } else if (subcommand === "add-node" && arg1 && arg2 && arg3) {
+    const nodeId = arg1;
+    const layer = arg2.toLowerCase() as EnvironmentLayer;
+    const platform = arg3;
+    const domainOrIp = arg4;
+
+    const node: TopologyNode = {
+      id: nodeId,
+      layer,
+      name: nodeId,
+      platform,
+      canonical_tag: EnvironmentDetector.matchCanonicalTag(platform),
+      domain_or_ip: domainOrIp,
+      status: "VERIFIED",
+      detected_from: ["CLI Manual Node Resolution"],
+      constraints: [`Node added manually with platform '${platform}'.`],
+    };
+    repo.environment.saveNode(node);
+    console.log(`[Septum Topology] Node '${nodeId}' (${layer.toUpperCase()}) added to distributed topology graph.\n`);
+  } else if (subcommand === "remove-node" && arg1) {
+    repo.environment.deleteNode(arg1);
+    console.log(`[Septum Topology] Node '${arg1}' removed from distributed topology graph.\n`);
+  } else if (subcommand === "clear") {
+    repo.environment.clearAll();
+    console.log("[Septum Topology] Cleared environment topology and nodes in SQLite SSOT.\n");
+  }
+
+  const topology = EnvironmentDetector.detect(cwd, repo);
+
+  console.log("================================================================================");
+  console.log("🌐 SEPTUM SELF-AWARE ENVIRONMENT TOPOLOGY PLANE");
+  console.log("================================================================================");
+  console.log(`Overall Status:   ${topology.overall_status}`);
+  console.log(`Topology Mode:    ${topology.is_distributed ? "DISTRIBUTED MULTI-NODE GRAPH" : "MONOLITHIC SINGLE-NODE"}`);
+  console.log(`Summary:          ${topology.architectural_summary}\n`);
+
+  if (topology.nodes.length > 0) {
+    console.log("--- DISTRIBUTED TOPOLOGY NODES ---");
+    for (const node of topology.nodes) {
+      const statusIcon = node.status === "VERIFIED" ? "✓ [VERIFIED]" : node.status === "DETECTED" ? "• [DETECTED]" : "? [AMBIGUOUS]";
+      const domainStr = node.domain_or_ip ? ` @ ${node.domain_or_ip}` : "";
+      const roleStr = node.role ? ` [Role: ${node.role}]` : "";
+      console.log(`  ${statusIcon} ${node.id.padEnd(20)} (${node.layer.toUpperCase()}): ${node.platform}${domainStr}${roleStr}`);
+      if (node.connected_to && node.connected_to.length > 0) {
+        console.log(`      ➔ Connected to: ${node.connected_to.join(", ")}`);
+      }
+      if (node.constraints && node.constraints.length > 0) {
+        for (const c of node.constraints) {
+          console.log(`      - ${c}`);
+        }
+      }
+    }
+    console.log("");
+  }
+
+  console.log("--- 6-LAYER PRODUCTION SUMMARY PLANE ---");
+  for (const [layerKey, info] of Object.entries(topology.layers)) {
+    const statusIcon = info.status === "VERIFIED" ? "✓ [VERIFIED]" : info.status === "DETECTED" ? "• [DETECTED]" : "? [AMBIGUOUS]";
+    console.log(`  ${statusIcon} ${layerKey.toUpperCase().padEnd(10)}: ${info.platform || "Unresolved"}`);
+  }
+
+  if (topology.interplays.length > 0) {
+    console.log("\n--- CROSS-LAYER & DISTRIBUTED INVARIANTS ---");
+    for (const interplay of topology.interplays) {
+      console.log(`  ⚡ ${interplay.title} (${interplay.involved_layers.join(" ➔ ")})`);
+      console.log(`     Rule:   ${interplay.risk_or_rule}`);
+      console.log(`     Action: ${interplay.required_action}`);
+    }
+  }
+
+  if (topology.pending_inquiries.length > 0) {
+    console.log("\n--- PENDING ARCHITECTURAL INQUIRIES ---");
+    console.log("Action Required: Please clarify these ambiguous layers/nodes for your AI Agent:\n");
+    for (const inquiry of topology.pending_inquiries) {
+      console.log(`  ❓ ${inquiry}`);
+    }
+    console.log("\nTip: To resolve an inquiry or add distributed nodes, run:");
+    console.log("  septum topology resolve <layer> \"<Platform Name>\"");
+    console.log("  septum topology add-node <id> <layer> \"<Platform Name>\" [domain_or_ip]");
+    console.log("Example:");
+    console.log("  septum topology add-node host:vps-worker host \"Ubuntu 24.04 (Dedicated Worker)\" 10.0.0.6");
+  }
+
+  console.log("================================================================================\n");
+
+  db.close();
+}

package/src/cli/index.ts

@@ -5,6 +5,7 @@ import { handleCheckCommand } from "./commands/check.ts";
 import { handleHookCommand } from "./commands/hook.ts";
 import { handleIngestCommand } from "./commands/ingest.ts";
 import { handleInitCommand } from "./commands/init.ts";
+import { handleTopologyCommand } from "./commands/topology.ts";
 import { handleLocateCommand } from "./commands/locate.ts";
 import { handleQueryCommand } from "./commands/query.ts";
 import { handleServeCommand } from "./commands/serve.ts";
@@ -112,6 +113,12 @@ export async function runCLI(argv: string[]): Promise<void> {
         break;
       }
 
+      case "topology":
+      case "env": {
+        await handleTopologyCommand(positionals[1], positionals[2], positionals[3], positionals[4], positionals[5]);
+        break;
+      }
+
       case "feature": {
         const sub = positionals[1];
         if (sub === "clear") {
@@ -188,6 +195,10 @@ COMMANDS:
     feature [status|clear] View or release active feature context session lock
     hook [subhook]        Internal pre-tool guardrail hook (e.g. pre-write)
 
+  Environment & Topology:
+    topology [action]     Inspect 6-layer environment topology & distributed nodes
+                          Subcommands: resolve <layer> <platform>, add-node, remove-node, clear
+
   Daemon & Protocol:
     serve                 Start Model Context Protocol (MCP) server over stdio
 

package/src/cli/templates/skill.ts

@@ -25,11 +25,14 @@ Skill ini berakar langsung pada riset rekayasa perangkat lunak terkemuka:
 
 ## 2. Kapan Wajib Menggunakan (Trigger Moments)
 
-Gunakan skill ini saat:
-1. Menghubungkan Septum pertama kali ke repositori baru atau codebase yang belum terpetakan.
+> [!NOTE] Zero-Config Default (\`septum init\`)
+> Untuk mayoritas proyek (library kecil/menengah, layered monolith standar, MVC, CLI, MCP tools), pengguna atau agen **cukup menjalankan \`septum init\`** di terminal. Perintah \`septum init\` secara default berjalan 100% otomatis tanpa wawancara manual (zero-config heuristic auto-detect & auto-ingest).
+
+Gunakan alur 4 langkah skill ini HANYA saat:
+1. Memetakan domain bisnis kustom / modular DDD enterprise yang kompleks di mana batasan dependency non-standar perlu disepakati bersama Tech Lead.
 2. Memetakan ulang domain bisnis setelah terjadi refactoring arsitektur besar (*re-mapping*).
-3. Mengonfigurasi fitur baru (\`features\` session) untuk mengunci daftar file yang boleh dimodifikasi (*allowed_touchpoints*) dan simbol yang wajib dipakai ulang (*reuse_symbols*).
-4. Pengguna meminta inisialisasi cerdas berbasis pemahaman AI pada struktur proyek.
+3. Mengonfigurasi sesi fitur baru (\`features\` session) untuk mengunci daftar file yang boleh dimodifikasi (*allowed_touchpoints*) dan simbol yang wajib dipakai ulang (*reuse_symbols*).
+4. Pengguna secara eksplisit meminta konsultasi desain domain boundary interaktif.
 
 ---
 

package/src/core/config/loader.ts

@@ -1,31 +1,44 @@
 import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import { Database } from "bun:sqlite";
 import type { ValidatedSeptumConfig } from "./schema.ts";
 import { TopologyDetector } from "../discovery/topology-detector.ts";
 import { SeptumDatabase } from "../database/client.ts";
 import { SeptumRepository } from "../database/repository.ts";
+import { resolveWorkspaceRoot, isAppHostDirectory } from "../resolver/path-resolver.ts";
 
 export class ConfigLoader {
   /**
    * Loads configuration with SQLite as the Single Source of Truth (SSOT).
    * Automatically executes Zero-Config TopologyDetector if the database has no domains.
    */
-  public static load(dbPath: string = ".septum/septum.db"): ValidatedSeptumConfig {
+  public static load(
+    dbPath?: string,
+    projectRoot?: string
+  ): ValidatedSeptumConfig {
+    const root = resolveWorkspaceRoot(projectRoot);
+    const resolvedDbPath = dbPath
+      ? (isAbsolute(dbPath) ? dbPath : join(root, dbPath))
+      : join(root, ".septum", "septum.db");
+
     // 1. If database exists and has registered domains, load directly from SQLite SSOT
-    if (existsSync(dbPath)) {
-      const dbConfig = ConfigLoader.loadFromDatabaseOrDefaults(dbPath);
+    if (existsSync(resolvedDbPath)) {
+      const dbConfig = ConfigLoader.loadFromDatabaseOrDefaults(resolvedDbPath);
       if (Object.keys(dbConfig.domains).length > 0) {
         return dbConfig;
       }
     }
 
     // 2. Zero-Config Auto-Discovery: Discover project topology and persist to SQLite
-    const septumDb = new SeptumDatabase(dbPath);
-    const repo = new SeptumRepository(septumDb.raw);
-    TopologyDetector.discoverAndPersist(repo, process.cwd());
-    septumDb.close();
+    // Guard against running auto-discovery inside MCP host / IDE installation folders
+    if (!isAppHostDirectory(root)) {
+      const septumDb = new SeptumDatabase(resolvedDbPath);
+      const repo = new SeptumRepository(septumDb.raw);
+      TopologyDetector.discoverAndPersist(repo, root);
+      septumDb.close();
+    }
 
-    return ConfigLoader.loadFromDatabaseOrDefaults(dbPath);
+    return ConfigLoader.loadFromDatabaseOrDefaults(resolvedDbPath);
   }
 
   public static getDefaultConfig(): ValidatedSeptumConfig {

package/src/core/database/repositories/dependency.repository.ts

@@ -276,4 +276,74 @@ export class DependencyRepository {
     };
   }
 
+  public getFileInboundImpact(filePath: string): {
+    direct_dependents_count: number;
+    top_consumers: string[];
+    symbols_count: number;
+    risk_level: "low" | "medium" | "high";
+  } {
+    const cleanPath = filePath.replace(/\\/g, "/");
+    const baseName = cleanPath.split("/").pop()?.replace(/\.[^.]+$/, "") || "";
+
+    const symbols = this.db
+      .query<{ name: string }, [string, string]>(
+        `SELECT s.name 
+         FROM symbols s 
+         JOIN files f ON s.file_id = f.id 
+         WHERE f.path = ? OR f.path LIKE ?`
+      )
+      .all(cleanPath, `%${cleanPath}`);
+
+    const matchedFiles = new Set<string>();
+
+    if (baseName.length >= 3) {
+      const depRows = this.db
+        .query<{ file: string }, [string, string, string]>(
+          `SELECT DISTINCT f.path AS file
+           FROM dependencies d
+           JOIN files f ON d.source_file_id = f.id
+           WHERE (d.target_symbol_or_path LIKE ? OR d.target_symbol_or_path LIKE ?)
+             AND f.path NOT LIKE ?`
+        )
+        .all(`%${cleanPath}%`, `%${baseName}%`, `%${cleanPath}`);
+
+      for (const row of depRows) {
+        matchedFiles.add(row.file);
+      }
+    }
+
+    for (const sym of symbols.slice(0, 8)) {
+      const symName = sym.name.split("::").pop() || sym.name;
+      if (symName.length >= 4) {
+        const symDeps = this.db
+          .query<{ file: string }, [string, string]>(
+            `SELECT DISTINCT f.path AS file
+             FROM dependencies d
+             JOIN files f ON d.source_file_id = f.id
+             WHERE d.target_symbol_or_path LIKE ?
+               AND f.path NOT LIKE ?
+             LIMIT 10`
+          )
+          .all(`%${symName}%`, `%${cleanPath}`);
+        for (const r of symDeps) {
+          matchedFiles.add(r.file);
+        }
+      }
+    }
+
+    const consumerList = Array.from(matchedFiles);
+    let riskLevel: "low" | "medium" | "high" = "low";
+    if (consumerList.length >= 5) {
+      riskLevel = "high";
+    } else if (consumerList.length >= 2) {
+      riskLevel = "medium";
+    }
+
+    return {
+      direct_dependents_count: consumerList.length,
+      top_consumers: consumerList.slice(0, 5),
+      symbols_count: symbols.length,
+      risk_level: riskLevel,
+    };
+  }
 }

package/src/core/database/repositories/environment.repository.ts

@@ -0,0 +1,207 @@
+import type { Database } from "bun:sqlite";
+import type { CanonicalPlatformTag, EnvironmentLayer, EnvironmentLayerInfo, TopologyNode } from "../../topology/types.ts";
+
+export class EnvironmentRepository {
+  constructor(private db: Database) {}
+
+  public getLayer(layer: EnvironmentLayer): EnvironmentLayerInfo | null {
+    const row = this.db
+      .query<{
+        layer: string;
+        platform: string | null;
+        status: string;
+        detected_from_json: string;
+        constraints_json: string;
+        unresolved_inquiry: string | null;
+      }, [string]>("SELECT * FROM environment_topology WHERE layer = ?")
+      .get(layer);
+
+    if (!row) return null;
+    return {
+      layer: row.layer as EnvironmentLayer,
+      platform: row.platform ?? undefined,
+      status: row.status as any,
+      detected_from: JSON.parse(row.detected_from_json || "[]"),
+      constraints: JSON.parse(row.constraints_json || "[]"),
+      unresolved_inquiry: row.unresolved_inquiry ?? undefined,
+    };
+  }
+
+  public getAllLayers(): Record<EnvironmentLayer, EnvironmentLayerInfo> {
+    const rows = this.db
+      .query<{
+        layer: string;
+        platform: string | null;
+        status: string;
+        detected_from_json: string;
+        constraints_json: string;
+        unresolved_inquiry: string | null;
+      }, []>("SELECT * FROM environment_topology")
+      .all();
+
+    const result: Partial<Record<EnvironmentLayer, EnvironmentLayerInfo>> = {};
+    for (const row of rows) {
+      result[row.layer as EnvironmentLayer] = {
+        layer: row.layer as EnvironmentLayer,
+        platform: row.platform ?? undefined,
+        status: row.status as any,
+        detected_from: JSON.parse(row.detected_from_json || "[]"),
+        constraints: JSON.parse(row.constraints_json || "[]"),
+        unresolved_inquiry: row.unresolved_inquiry ?? undefined,
+      };
+    }
+    return result as Record<EnvironmentLayer, EnvironmentLayerInfo>;
+  }
+
+  public saveLayer(info: EnvironmentLayerInfo): void {
+    this.db
+      .query(
+        `INSERT INTO environment_topology (
+          layer, platform, status, detected_from_json, constraints_json, unresolved_inquiry, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+        ON CONFLICT(layer) DO UPDATE SET
+          platform = excluded.platform,
+          status = excluded.status,
+          detected_from_json = excluded.detected_from_json,
+          constraints_json = excluded.constraints_json,
+          unresolved_inquiry = excluded.unresolved_inquiry,
+          updated_at = CURRENT_TIMESTAMP`
+      )
+      .run(
+        info.layer,
+        info.platform ?? null,
+        info.status,
+        JSON.stringify(info.detected_from ?? []),
+        JSON.stringify(info.constraints ?? []),
+        info.unresolved_inquiry ?? null
+      );
+  }
+
+  public clearAll(): void {
+    this.db.run("DELETE FROM environment_topology");
+    this.db.run("DELETE FROM environment_nodes");
+  }
+
+  // Node CRUD operations for Multi-Node Topology
+  public getNode(id: string): TopologyNode | null {
+    const row = this.db
+      .query<{
+        id: string;
+        layer: string;
+        name: string;
+        platform: string;
+        canonical_tag: string;
+        domain_or_ip: string | null;
+        role: string | null;
+        status: string;
+        detected_from_json: string;
+        constraints_json: string;
+        connected_to_json: string;
+        unresolved_inquiry: string | null;
+      }, [string]>("SELECT * FROM environment_nodes WHERE id = ?")
+      .get(id);
+
+    if (!row) return null;
+    return this.mapNodeRow(row);
+  }
+
+  public getAllNodes(): TopologyNode[] {
+    const rows = this.db
+      .query<{
+        id: string;
+        layer: string;
+        name: string;
+        platform: string;
+        canonical_tag: string;
+        domain_or_ip: string | null;
+        role: string | null;
+        status: string;
+        detected_from_json: string;
+        constraints_json: string;
+        connected_to_json: string;
+        unresolved_inquiry: string | null;
+      }, []>("SELECT * FROM environment_nodes ORDER BY layer, id")
+      .all();
+
+    return rows.map((r) => this.mapNodeRow(r));
+  }
+
+  public getNodesByLayer(layer: EnvironmentLayer): TopologyNode[] {
+    const rows = this.db
+      .query<{
+        id: string;
+        layer: string;
+        name: string;
+        platform: string;
+        canonical_tag: string;
+        domain_or_ip: string | null;
+        role: string | null;
+        status: string;
+        detected_from_json: string;
+        constraints_json: string;
+        connected_to_json: string;
+        unresolved_inquiry: string | null;
+      }, [string]>("SELECT * FROM environment_nodes WHERE layer = ? ORDER BY id")
+      .all(layer);
+
+    return rows.map((r) => this.mapNodeRow(r));
+  }
+
+  public saveNode(node: TopologyNode): void {
+    this.db
+      .query(
+        `INSERT INTO environment_nodes (
+          id, layer, name, platform, canonical_tag, domain_or_ip, role, status,
+          detected_from_json, constraints_json, connected_to_json, unresolved_inquiry, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+        ON CONFLICT(id) DO UPDATE SET
+          layer = excluded.layer,
+          name = excluded.name,
+          platform = excluded.platform,
+          canonical_tag = excluded.canonical_tag,
+          domain_or_ip = excluded.domain_or_ip,
+          role = excluded.role,
+          status = excluded.status,
+          detected_from_json = excluded.detected_from_json,
+          constraints_json = excluded.constraints_json,
+          connected_to_json = excluded.connected_to_json,
+          unresolved_inquiry = excluded.unresolved_inquiry,
+          updated_at = CURRENT_TIMESTAMP`
+      )
+      .run(
+        node.id,
+        node.layer,
+        node.name,
+        node.platform,
+        node.canonical_tag || "unspecified",
+        node.domain_or_ip ?? null,
+        node.role ?? null,
+        node.status,
+        JSON.stringify(node.detected_from ?? []),
+        JSON.stringify(node.constraints ?? []),
+        JSON.stringify(node.connected_to ?? []),
+        node.unresolved_inquiry ?? null
+      );
+  }
+
+  public deleteNode(id: string): void {
+    this.db.query("DELETE FROM environment_nodes WHERE id = ?").run(id);
+  }
+
+  private mapNodeRow(row: any): TopologyNode {
+    return {
+      id: row.id,
+      layer: row.layer as EnvironmentLayer,
+      name: row.name,
+      platform: row.platform,
+      canonical_tag: (row.canonical_tag as CanonicalPlatformTag) || "unspecified",
+      domain_or_ip: row.domain_or_ip ?? undefined,
+      role: row.role ?? undefined,
+      status: row.status as any,
+      detected_from: JSON.parse(row.detected_from_json || "[]"),
+      constraints: JSON.parse(row.constraints_json || "[]"),
+      connected_to: JSON.parse(row.connected_to_json || "[]"),
+      unresolved_inquiry: row.unresolved_inquiry ?? undefined,
+    };
+  }
+}

package/src/core/database/repositories/file.repository.ts

@@ -22,6 +22,13 @@ export class FileRepository {
       .all(domainId);
   }
 
+  public countFiles(): number {
+    const row = this.db
+      .query<{ count: number }, []>("SELECT COUNT(*) as count FROM files")
+      .get();
+    return row?.count ?? 0;
+  }
+
   public upsertFile(
     domainId: number,
     path: string,