septum 0.1.6 → 0.1.7

package/README.md

@@ -2,13 +2,13 @@
 
 > **Deterministic Bounded-Context & Anti-Poisoning Architecture Guard for AI Coding Agents.**
 
-[![Version: 0.1.5](https://img.shields.io/badge/Version-0.1.5-blue)](package.json)
+[![Version: 0.1.7](https://img.shields.io/badge/Version-0.1.7-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/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
 
-Septum stops **context poisoning** in AI coding agents. It indexes your codebase into an embedded SQLite SSOT (`.septum/septum.db`), enforces strict bounded-context domains, and intercepts unauthorized cross-domain edits before they hit disk.
+Septum helps AI coding agents navigate code and respect declared architectural boundaries. It indexes your codebase into an embedded SQLite SSOT (`.septum/septum.db`), enforces strict bounded-context domains, and intercepts unauthorized cross-domain edits before they hit disk.
 
 ---
 
@@ -59,7 +59,7 @@ Add Septum to your MCP client (`mcp.json` or `claude_desktop_config.json`):
 |---|---|
 | `septum init` | Detect topology, scaffold boundary guards, and build initial catalog |
 | `septum ingest` | Full AST re-indexing into `.septum/septum.db` |
-| `septum sync` | Fast incremental delta sync (< 15ms) for modified files |
+| `septum sync` | Incremental synchronization of modified files 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 |
@@ -103,3 +103,23 @@ bun run build
 ## License
 
 [MIT](LICENSE) © shironim
+
+## Reliability and Scope
+
+`septum check --strict` enables strict dependency rules before evaluating the codebase. A full check synchronizes the index first. CLI and MCP staged checks read Git index blobs, so unstaged edits cannot hide a violation in the proposed commit. Staged checks also evaluate dependency cycles using indexed dependencies with staged imports overlaid.
+
+Domain ownership uses the most specific normalized root in both full and single-file ingestion. Feature touchpoints are normalized against the workspace; `/*` permits immediate children and `/**` permits descendants.
+
+Each active MCP workspace has a watcher. Changes to multiple files are batched without dropping earlier paths; deletion and directory moves reconcile the catalog. If a native watcher is unavailable, Septum falls back to polling and synchronizes before answering queries. Catalog responses expose `index_status.watcher_mode` and `index_status.unsupported_files`. Single-file updates invalidate cached execution slices; the next trace rebuilds them.
+
+Tree-sitter grammars are runtime dependencies and are embedded in compiled executables. The active extractors cover TypeScript/JavaScript, PHP/Blade, Python, Go, and script extraction from Vue/Svelte/Astro. Rust, Java, C#, and Ruby do not yet have active extractors. Unsupported files are reported explicitly; an incomplete audit does not receive a clean approval. Unindexed symbols return `risk_level: "unknown"`.
+
+Feature sessions have a single owner per workspace. The default owner is the MCP process; set `SEPTUM_SESSION_ID` when several commands intentionally share the same owner. Another owner cannot replace or release the active session. Use `septum feature clear --force` for explicit recovery after a process exits or for a legacy session without ownership metadata.
+
+Run the real-server integration checks with Python 3:
+
+```bash
+bun run test:integration
+```
+
+These checks exercise live rule changes, Git staged blobs, multiple workspaces, rapid edits, directory moves, and unsupported-file diagnostics. The normal `bun test` suite includes a standalone-binary regression for forbidden multiline imports.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "septum",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Deterministic Bounded-Context, Structural File Catalog & Anti-Poisoning Partition for AI Agents",
   "type": "module",
   "main": "src/index.ts",
@@ -18,13 +18,15 @@
     "check": "bun run bin/septum.ts check",
     "test": "bun test",
     "build": "bun build ./bin/septum.ts --compile --outfile dist/septum",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test:integration": "python3 tests/integration/mcp-reliability.py"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.5.0",
     "web-tree-sitter": "^0.24.0",
     "yaml": "^2.7.0",
-    "zod": "^3.24.2"
+    "zod": "^3.24.2",
+    "tree-sitter-wasms": "^0.1.13"
   },
   "license": "MIT",
   "repository": {
@@ -56,8 +58,6 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/node": "^22.13.4",
-    "tree-sitter-wasms": "^0.1.13",
     "typescript": "^5.7.3"
   }
 }
-

package/src/cli/commands/check.ts

@@ -1,13 +1,10 @@
-import { execSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
 import { BoundaryEvaluator } from "../../core/boundary/evaluator.ts";
-import type { ValidatedSeptumConfig } from "../../core/config/schema.ts";
 import { ConfigLoader } from "../../core/config/loader.ts";
 import { SeptumDatabase } from "../../core/database/client.ts";
 import { SeptumRepository } from "../../core/database/repository.ts";
-import { ASTParserEngine } from "../../core/parser/tree-sitter.ts";
 import type { BoundaryViolation } from "../../types/index.ts";
+import { IngestionPipeline } from "../../core/ingestion/pipeline.ts";
+import { auditStagedFiles } from "../../core/boundary/staged-auditor.ts";
 
 export interface CheckCommandOptions {
   strict?: boolean;
@@ -28,134 +25,47 @@ export async function handleCheckCommand(
   );
 
   const config = ConfigLoader.load();
+  if (options.strict) config.settings.enforcement = "strict";
   const db = new SeptumDatabase(config.settings.db_path);
   const repo = new SeptumRepository(db.raw);
   const evaluator = new BoundaryEvaluator(repo);
 
-  let violations: BoundaryViolation[] = [];
-
-  if (options.staged) {
-    violations = await auditStagedFiles(evaluator, config, options.feature);
-  } else {
-    violations = evaluator.auditCodebase(config);
-  }
-
-  if (violations.length === 0) {
-    console.log("✓ All domain boundaries are clean. Zero cross-domain leaks detected.");
-    db.close();
-    return;
-  }
-
-  console.error(`\n[Septum Boundary Violation] Found ${violations.length} boundary violation(s):\n`);
-
-  for (const v of violations) {
-    console.error(`  ✕ [${v.rule.toUpperCase()}] at ${v.file}:${v.line}`);
-    console.error(`    Source Domain:  ${v.source_domain}`);
-    console.error(`    Target Domain:  ${v.target_domain}`);
-    console.error(`    Import Target:  ${v.imported_target}`);
-    console.error(`    Message:        ${v.message}\n`);
-  }
-
-  db.close();
-
-  const isStrict = options.strict || config.settings.enforcement === "strict";
-  if (isStrict) {
-    console.error("[Septum Failure] Process terminated with exit code 1 due to boundary violations.");
-    process.exit(1);
-  }
-}
-
-async function auditStagedFiles(
-  evaluator: BoundaryEvaluator,
-  config: ValidatedSeptumConfig,
-  featureKey?: string
-): Promise<BoundaryViolation[]> {
-  const violations: BoundaryViolation[] = [];
-  let stagedFiles: string[] = [];
-
   try {
-    const gitOutput = execSync("git diff --cached --name-only --diff-filter=ACM", {
-      encoding: "utf-8",
-      timeout: 5000,
-      maxBuffer: 10 * 1024 * 1024,
-    });
-    stagedFiles = gitOutput
-      .split("\n")
-      .map((f) => f.trim())
-      .filter(Boolean);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.warn(`[Septum Warning] Could not retrieve git staged files: ${msg}`);
-    return violations;
-  }
-
-  if (stagedFiles.length === 0) {
-    console.log("  Notice: No staged files found in git repository.");
-    return violations;
-  }
-
-  const astEngine = new ASTParserEngine();
-
-  for (const relPath of stagedFiles) {
-    const fullPath = path.resolve(process.cwd(), relPath);
-    if (!fs.existsSync(fullPath)) continue;
-
-    // 1. Feature touchpoint check if featureKey provided
-    if (featureKey) {
-      const tpViolations = evaluator.checkFeatureTouchpoints(featureKey, relPath, config);
-      violations.push(...tpViolations);
+    let violations: BoundaryViolation[] = [];
+
+    if (options.staged) {
+      violations = (await auditStagedFiles(evaluator, config, process.cwd(), options.feature, repo)).violations;
+    } else {
+      await new IngestionPipeline(repo).run(config, { verifyContent: true });
+      const unsupported = JSON.parse(repo.getMeta("unsupported_files") || "[]") as string[];
+      if (unsupported.length > 0) {
+        throw new Error(`Cannot complete boundary audit: unsupported source files: ${unsupported.join(", ")}`);
+      }
+      violations = evaluator.auditCodebase(config);
     }
 
-    const sourceDomain = evaluator.resolveSourceDomain(relPath, config);
-    if (!sourceDomain) continue;
-
-    const sourceConfig = config.domains[sourceDomain];
-    if (!sourceConfig) continue;
-
-    const forbidden = sourceConfig.forbidden_dependencies ?? [];
-    const allowed = sourceConfig.allowed_dependencies ?? [];
-
-    try {
-      const content = fs.readFileSync(fullPath, "utf-8");
-      const parsed = await astEngine.parseFile(fullPath, content);
+    if (violations.length === 0) {
+      console.log("✓ All domain boundaries are clean. Zero cross-domain leaks detected.");
+      return;
+    }
 
-      for (const dep of parsed.dependencies) {
-        if (dep.is_external) continue;
+    console.error(`\n[Septum Boundary Violation] Found ${violations.length} boundary violation(s):\n`);
 
-        const targetDomain = evaluator.resolveTargetDomain(
-          dep.target,
-          config,
-          relPath
-        );
+    for (const v of violations) {
+      console.error(`  ✕ [${v.rule.toUpperCase()}] at ${v.file}:${v.line}`);
+      console.error(`    Source Domain:  ${v.source_domain}`);
+      console.error(`    Target Domain:  ${v.target_domain}`);
+      console.error(`    Import Target:  ${v.imported_target}`);
+      console.error(`    Message:        ${v.message}\n`);
+    }
 
-        if (!targetDomain || targetDomain === sourceDomain) continue;
 
-        if (forbidden.includes(targetDomain)) {
-          violations.push({
-            file: relPath,
-            line: dep.line_number,
-            source_domain: sourceDomain,
-            target_domain: targetDomain,
-            imported_target: dep.target,
-            rule: "forbidden_dependency",
-            message: `Illegal import: Domain '${sourceDomain}' is strictly prohibited from importing domain '${targetDomain}'.`,
-          });
-        } else if (config.settings.enforcement === "strict" && !allowed.includes(targetDomain)) {
-          violations.push({
-            file: relPath,
-            line: dep.line_number,
-            source_domain: sourceDomain,
-            target_domain: targetDomain,
-            imported_target: dep.target,
-            rule: "disallowed_dependency",
-            message: `Disallowed dependency: '${targetDomain}' is not declared in allowed_dependencies for domain '${sourceDomain}'.`,
-          });
-        }
-      }
-    } catch {
-      // Ignore unparseable files
+    const isStrict = options.strict || config.settings.enforcement === "strict";
+    if (isStrict) {
+      console.error("[Septum Failure] Process terminated with exit code 1 due to boundary violations.");
+      process.exitCode = 1;
     }
+  } finally {
+    db.close();
   }
-
-  return violations;
 }

package/src/cli/commands/hook.ts

@@ -130,12 +130,14 @@ async function runPreWriteHook(): Promise<void> {
     // -------------------------------------------------------------
     // GATE 1: Hard Touchpoint Lock (if features are defined)
     // -------------------------------------------------------------
-    const features = config.features ?? {};
     const session = SessionManager.getActiveSession(process.cwd());
-    const activeFeatureKey =
-      toolInput.feature_key || process.env.SEPTUM_ACTIVE_FEATURE || session?.feature_key;
+    const requestedFeatureKey = toolInput.feature_key || process.env.SEPTUM_ACTIVE_FEATURE;
+    if (session && requestedFeatureKey && requestedFeatureKey !== session.feature_key) {
+      throw new Error(`Requested feature '${requestedFeatureKey}' does not own the active scope '${session.feature_key}'.`);
+    }
+    const activeFeatureKey = session?.feature_key || requestedFeatureKey;
 
-    if (activeFeatureKey && features[activeFeatureKey]) {
+    if (activeFeatureKey) {
       const touchpointViolations = evaluator.checkFeatureTouchpoints(
         activeFeatureKey,
         targetFile,
@@ -161,6 +163,9 @@ async function runPreWriteHook(): Promise<void> {
     if (content && sourceDomain) {
       const astEngine = new ASTParserEngine();
       const parsed = await astEngine.parseFile(targetFile, content);
+      if (ASTParserEngine.isSourceFile(targetFile) && (parsed.status === "unsupported" || parsed.status === "degraded")) {
+        throw new Error(`Cannot reliably check imports in '${targetFile}': parser status is ${parsed.status}.`);
+      }
 
       const proposedImports = parsed.dependencies.map((d) => d.target);
       const boundaryViolations = evaluator.checkProposedChanges(

package/src/cli/index.ts

@@ -132,7 +132,7 @@ export async function runCLI(argv: string[]): Promise<void> {
       case "feature": {
         const sub = positionals[1];
         if (sub === "clear") {
-          const cleared = SessionManager.clearActiveSession(process.cwd());
+          const cleared = SessionManager.clearActiveSession(process.cwd(), undefined, Boolean(flags.force));
           if (cleared) {
             console.log("✓ Active feature session successfully cleared.");
           } else {
@@ -203,6 +203,7 @@ COMMANDS:
     check                 Audit codebase for cross-domain boundary violations
                           Flags: --strict, --staged, --feature <name>
     feature [status|clear] View or release active feature context session lock
+                          Flags: --force (explicit recovery of another owner's session)
     hook [subhook]        Internal pre-tool guardrail hook (e.g. pre-write)
 
   Environment & Topology:

package/src/core/boundary/evaluator.ts

@@ -1,4 +1,4 @@
-import { posix } from "node:path";
+import { posix, relative, resolve, isAbsolute } from "node:path";
 import type { BoundaryViolation } from "../../types/index.ts";
 import type { ValidatedSeptumConfig } from "../config/schema.ts";
 import { ConfigLoader } from "../config/loader.ts";
@@ -105,7 +105,8 @@ export class BoundaryEvaluator {
       target: string;
       statement: string;
       is_external: boolean;
-    }>
+    }>,
+    relevantFiles?: ReadonlySet<string>
   ): BoundaryViolation[] {
     const violations: BoundaryViolation[] = [];
     const allDependencies = preloadedDeps ?? this.repo.getAllDependenciesWithDomains();
@@ -158,6 +159,7 @@ export class BoundaryEvaluator {
     };
 
     type EdgeMeta = {
+      files: Set<string>;
       file: string;
       line: number;
       source_domain: string;
@@ -182,6 +184,7 @@ export class BoundaryEvaluator {
         }
         if (!outMap.has(targetDomain)) {
           outMap.set(targetDomain, {
+            files: new Set([dep.source_file]),
             file: dep.source_file,
             line: dep.line_number,
             source_domain: dep.source_domain,
@@ -189,6 +192,7 @@ export class BoundaryEvaluator {
             target: dep.target,
           });
         }
+        outMap.get(targetDomain)!.files.add(dep.source_file);
       }
 
       // 2. File-to-file edge
@@ -201,6 +205,7 @@ export class BoundaryEvaluator {
         }
         if (!outMap.has(targetFile)) {
           outMap.set(targetFile, {
+            files: new Set([dep.source_file]),
             file: dep.source_file,
             line: dep.line_number,
             source_domain: dep.source_domain,
@@ -245,6 +250,8 @@ export class BoundaryEvaluator {
               if (cycleStartIndex !== -1) {
                 const cycleNodes = stack.slice(cycleStartIndex);
                 const sig = canonicalizeCycle(cycleNodes);
+                const cycleEdges = cycleNodes.map((source, index) => graph.get(source)?.get(cycleNodes[(index + 1) % cycleNodes.length]));
+                if (relevantFiles && !cycleEdges.some(edge => edge && [...edge.files].some(file => relevantFiles.has(file)))) continue;
                 if (!reportedCycles.has(sig)) {
                   reportedCycles.add(sig);
                   const firstNode = cycleNodes[0];
@@ -378,39 +385,28 @@ export class BoundaryEvaluator {
       return violations;
     }
 
-    const normalizedTarget = targetFilePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    const root = this.resolver.getProjectRoot();
+    const normalizedTarget = relative(root, resolve(root, targetFilePath.replace(/\\/g, "/"))).replace(/\\/g, "/");
     const allowedTouchpoints = featureConfig.allowed_touchpoints.map((tp) =>
-      tp.replace(/\\/g, "/").replace(/^\.\//, "")
+      isAbsolute(tp) ? relative(root, tp).replace(/\\/g, "/") : posix.normalize(tp.replace(/\\/g, "/"))
     );
 
     const domainCfg = config.domains[featureConfig.domain];
     const domainRoot = domainCfg?.root ? domainCfg.root.replace(/\\/g, "/").replace(/^\.\//, "") : "";
 
-    const isAllowed = allowedTouchpoints.some((pattern) => {
+    const matches = (pattern: string): boolean => {
       if (pattern.endsWith("/**")) {
-        const prefix = pattern.slice(0, -3);
-        return normalizedTarget.startsWith(prefix);
+        return normalizedTarget.startsWith(pattern.slice(0, -3) + "/");
       }
       if (pattern.endsWith("/*")) {
-        const prefix = pattern.slice(0, -2);
-        return normalizedTarget.startsWith(prefix);
+        const prefix = pattern.slice(0, -2) + "/";
+        return normalizedTarget.startsWith(prefix) && !normalizedTarget.slice(prefix.length).includes("/");
       }
-      if (normalizedTarget === pattern) return true;
-
-      if (
-        domainRoot &&
-        (normalizedTarget === `${domainRoot}/${pattern}` ||
-          normalizedTarget.startsWith(`${domainRoot}/${pattern}`))
-      ) {
-        return true;
-      }
-
-      if (pattern.includes("/") && normalizedTarget.endsWith("/" + pattern)) {
-        return true;
-      }
-
-      return false;
-    });
+      return normalizedTarget === pattern;
+    };
+    const isAllowed = allowedTouchpoints.some(pattern =>
+      matches(pattern) || Boolean(domainRoot && matches(posix.normalize(`${domainRoot}/${pattern}`)))
+    );
 
     if (!isAllowed) {
       violations.push({

package/src/core/boundary/staged-auditor.ts

@@ -0,0 +1,47 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import type { BoundaryViolation } from "../../types/index.ts";
+import type { ValidatedSeptumConfig } from "../config/schema.ts";
+import { ASTParserEngine } from "../parser/tree-sitter.ts";
+import type { SeptumRepository } from "../database/repository.ts";
+import type { BoundaryEvaluator } from "./evaluator.ts";
+
+export async function auditStagedFiles(
+  evaluator: BoundaryEvaluator,
+  config: ValidatedSeptumConfig,
+  workspaceRoot: string,
+  featureKey?: string,
+  repo?: SeptumRepository
+): Promise<{ files: string[]; violations: BoundaryViolation[] }> {
+  const output = execFileSync("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR", "-z"], {
+    cwd: workspaceRoot, encoding: "utf-8", timeout: 5000, maxBuffer: 10 * 1024 * 1024,
+  });
+  const files = output.split("\0").filter(Boolean);
+  const deletedOutput = execFileSync("git", ["diff", "--cached", "--name-only", "--diff-filter=D", "-z"], {
+    cwd: workspaceRoot, encoding: "utf-8", timeout: 5000, maxBuffer: 10 * 1024 * 1024,
+  });
+  const deleted = deletedOutput.split("\0").filter(Boolean);
+  const violations: BoundaryViolation[] = [];
+  if (featureKey) for (const file of deleted) violations.push(...evaluator.checkFeatureTouchpoints(featureKey, file, config));
+  const stagedDependencies: ReturnType<SeptumRepository["getAllDependenciesWithDomains"]> = [];
+  const parser = new ASTParserEngine();
+  for (const file of files) {
+    if (featureKey) violations.push(...evaluator.checkFeatureTouchpoints(featureKey, file, config));
+    if (!ASTParserEngine.isSourceFile(file) || !evaluator.resolveSourceDomain(file, config)) continue;
+    const content = execFileSync("git", ["show", `:${file}`], {
+      cwd: workspaceRoot, encoding: "utf-8", timeout: 5000, maxBuffer: 10 * 1024 * 1024,
+    });
+    const parsed = await parser.parseFile(resolve(workspaceRoot, file), content);
+    if (parsed.status === "unsupported" || parsed.status === "degraded") {
+      throw new Error(`Cannot reliably parse staged file '${file}': ${parsed.status}.`);
+    }
+    for (const dependency of parsed.dependencies) {
+      stagedDependencies.push({ source_file: file, source_domain: evaluator.resolveSourceDomain(file, config)!, target: dependency.target, statement: dependency.statement, line_number: dependency.line_number, is_external: dependency.is_external });
+      violations.push(...evaluator.checkProposedChanges(file, [dependency.target], config).map(violation => ({ ...violation, line: dependency.line_number })));
+    }
+  }
+  const staged = new Set([...files, ...deleted]);
+  const baseline = (repo?.getAllDependenciesWithDomains() || []).filter(dependency => !staged.has(dependency.source_file));
+  violations.push(...evaluator.detectCircularDependencies(config, [...baseline, ...stagedDependencies], staged));
+  return { files, violations };
+}

package/src/core/config/loader.ts

@@ -65,20 +65,23 @@ export class ConfigLoader {
   public static loadFromRepository(repo: SeptumRepository): ValidatedSeptumConfig {
     const config = ConfigLoader.getDefaultConfig();
     if (repo && typeof repo.getAllDomains === "function") {
-      try {
-        const rows = repo.getAllDomains();
-        for (const r of rows) {
-          config.domains[r.name] = {
-            root: r.root_path,
-            allowed_dependencies: JSON.parse(r.allowed_deps_json || "[]"),
-            forbidden_dependencies: JSON.parse(r.forbidden_deps_json || "[]"),
-            archetypes: JSON.parse(r.archetypes_json || "{}"),
-          };
-        }
-      } catch {
-        // Fallback gracefully to default config
+      const rows = repo.getAllDomains();
+      for (const row of rows) {
+        config.domains[row.name] = {
+          root: row.root_path,
+          allowed_dependencies: JSON.parse(row.allowed_deps_json || "[]"),
+          forbidden_dependencies: JSON.parse(row.forbidden_deps_json || "[]"),
+          archetypes: JSON.parse(row.archetypes_json || "{}"),
+        };
       }
     }
+
+    if (typeof repo?.getMeta === "function") {
+      const features = repo.getMeta("features_json");
+      if (features) config.features = JSON.parse(features);
+      const settings = repo.getMeta("settings_json");
+      if (settings) Object.assign(config.settings, JSON.parse(settings));
+    }
     return config;
   }
 
@@ -95,20 +98,14 @@ export class ConfigLoader {
           )
           .get("domains");
 
-        if (tables) {
-          const rows = db.query<any, []>("SELECT * FROM domains").all();
-          for (const r of rows) {
-            config.domains[r.name] = {
-              root: r.root_path,
-              allowed_dependencies: JSON.parse(r.allowed_deps_json || "[]"),
-              forbidden_dependencies: JSON.parse(r.forbidden_deps_json || "[]"),
-              archetypes: JSON.parse(r.archetypes_json || "{}"),
-            };
-          }
+        try {
+          if (tables) Object.assign(config, ConfigLoader.loadFromRepository(new SeptumRepository(db)));
+          config.settings.db_path = dbPath;
+        } finally {
+          db.close();
         }
-        db.close();
       } catch {
-        // Fallback gracefully to default config
+        throw new Error(`Cannot load Septum configuration from '${dbPath}'.`);
       }
     }
 

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

@@ -258,7 +258,7 @@ export class DependencyRepository {
         warning: "Empty symbol query provided.",
         impact_summary: {
           total_dependents: 0,
-          risk_level: "low",
+          risk_level: "unknown",
           affected_files_count: 0,
         },
         inbound_callers: [],
@@ -463,7 +463,7 @@ export class DependencyRepository {
     const foundInIndex = targetSymRows.length > 0 || depRows.length > 0;
     const warning = foundInIndex
       ? undefined
-      : `Symbol '${trimmed}' was not found in Septum index (neither in declared symbols nor tracked dependencies). Risk assessment defaults to low (0 callers) due to unindexed status.`;
+      : `Symbol '${trimmed}' was not found in Septum index (neither in declared symbols nor tracked dependencies). Risk cannot be assessed without index evidence.`;
 
     return {
       target_symbol: trimmed,
@@ -471,7 +471,7 @@ export class DependencyRepository {
       warning,
       impact_summary: {
         total_dependents: inboundCallers.length,
-        risk_level: riskLevel,
+        risk_level: foundInIndex ? riskLevel : "unknown",
         affected_files_count: affectedFiles.size,
       },
       inbound_callers: inboundCallers,

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

@@ -5,6 +5,8 @@ import type {
   ExtractedSymbol,
   FileRecord,
   GetSymbolDetailsResponse,
+  ResolvedOutboundCall,
+  SymbolComplexitySmell,
   SymbolKind,
   SymbolRecord,
 } from "../../../types/index.ts";
@@ -460,6 +462,73 @@ export class SymbolRepository {
     const depRepo = new DependencyRepository(this.db);
     const connectedFiles = depRepo.getFileConnections(row.file_path);
 
+    // 4. Resolve Outbound Calls to target symbol line ranges
+    const resolvedOutboundCalls: ResolvedOutboundCall[] = [];
+    const lookupStmt = this.db.query<
+      {
+        name: string;
+        line_start: number;
+        line_end: number;
+        line_count: number;
+        file_path: string;
+        domain_name: string;
+      },
+      [string, string, string, string]
+    >(`
+      SELECT 
+        s.name, 
+        s.line_start, 
+        s.line_end, 
+        s.line_count, 
+        f.path AS file_path, 
+        d.name AS domain_name
+      FROM symbols s
+      JOIN files f ON s.file_id = f.id
+      JOIN domains d ON f.domain_id = d.id
+      WHERE (s.name = ? OR s.name LIKE ? OR s.name LIKE ?)
+      ORDER BY CASE WHEN s.name = ? THEN 1 ELSE 2 END, s.line_start ASC
+      LIMIT 1
+    `);
+
+    for (const call of outboundCalls) {
+      try {
+        const target = lookupStmt.get(call, `%::${call}`, `${call}::%`, call);
+        if (target) {
+          resolvedOutboundCalls.push({
+            symbol: call,
+            target_file: target.file_path,
+            target_range: {
+              start_line: target.line_start,
+              end_line: target.line_end,
+              total_lines: target.line_count,
+            },
+            domain: target.domain_name,
+            is_resolved: true,
+          });
+        } else {
+          resolvedOutboundCalls.push({
+            symbol: call,
+            is_resolved: false,
+          });
+        }
+      } catch {
+        resolvedOutboundCalls.push({
+          symbol: call,
+          is_resolved: false,
+        });
+      }
+    }
+
+    const complexitySmell: SymbolComplexitySmell | undefined =
+      row.line_count > 300
+        ? {
+            is_high_complexity: true,
+            threshold: 300,
+            total_lines: row.line_count,
+            warning: `Symbol '${row.name}' spans ${row.line_count} lines (exceeds 300-line threshold). Candidate for decomposition/refactoring.`,
+          }
+        : undefined;
+
     return {
       symbol: row.name,
       kind: row.kind,
@@ -474,6 +543,8 @@ export class SymbolRepository {
       visibility: row.visibility,
       dependencies_injected: Array.from(dependenciesInjected),
       outbound_calls: Array.from(outboundCalls),
+      resolved_outbound_calls: resolvedOutboundCalls.length > 0 ? resolvedOutboundCalls : undefined,
+      complexity_smell: complexitySmell,
       sibling_methods: siblingMethods.length > 0 ? siblingMethods : undefined,
       connected_files: connectedFiles,
     };