septum 0.1.2 → 0.1.4

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

@@ -17,12 +17,13 @@ export class SymbolRepository {
     if (symbols.length === 0) return;
 
     const stmt = this.db.query(
-      `INSERT INTO symbols (file_id, name, kind, signature, visibility, line_start, line_end, line_count) 
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+      `INSERT INTO symbols (file_id, name, kind, signature, visibility, line_start, line_end, line_count, nesting_depth) 
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
     );
 
     for (const sym of symbols) {
       const lineCount = sym.line_count ?? Math.max(1, sym.line_end - sym.line_start + 1);
+      const nestingDepth = sym.nesting_depth ?? 1;
       stmt.run(
         fileId,
         sym.name,
@@ -31,7 +32,8 @@ export class SymbolRepository {
         sym.visibility,
         sym.line_start,
         sym.line_end,
-        lineCount
+        lineCount,
+        nestingDepth
       );
     }
   }
@@ -98,6 +100,7 @@ export class SymbolRepository {
           line_start: r.line_start,
           line_end: r.line_end,
           line_count: r.line_count ?? (r.line_end - r.line_start + 1),
+          nesting_depth: r.nesting_depth ?? 1,
         },
       }));
     }
@@ -225,12 +228,16 @@ export class SymbolRepository {
 
   public getHotspotSymbols(options: {
     minLines?: number;
+    minNesting?: number;
     kind?: SymbolKind;
     domain?: string;
     limit?: number;
-  } = {}): Array<SymbolRecord & { file_path: string; domain_name: string }> {
-    const minLines = options.minLines ?? 30;
+    sortBy?: "lines" | "nesting" | "risk_score";
+  } = {}): Array<SymbolRecord & { file_path: string; domain_name: string; risk_score: number }> {
+    const minLines = options.minLines ?? 0;
+    const minNesting = options.minNesting ?? 1;
     const limit = options.limit ?? 50;
+    const sortBy = options.sortBy ?? "risk_score";
 
     let sql = `
       SELECT 
@@ -243,15 +250,16 @@ export class SymbolRepository {
         s.line_start,
         s.line_end,
         s.line_count,
+        s.nesting_depth,
         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.line_count >= ?
+      WHERE s.line_count >= ? AND s.nesting_depth >= ?
     `;
 
-    const params: any[] = [minLines];
+    const params: any[] = [minLines, minNesting];
 
     if (options.kind) {
       sql += " AND s.kind = ?";
@@ -263,10 +271,21 @@ export class SymbolRepository {
       params.push(options.domain);
     }
 
-    sql += " ORDER BY s.line_count DESC, s.name ASC LIMIT ?";
+    if (sortBy === "nesting") {
+      sql += " ORDER BY s.nesting_depth DESC, s.line_count DESC, s.name ASC LIMIT ?";
+    } else if (sortBy === "lines") {
+      sql += " ORDER BY s.line_count DESC, s.nesting_depth DESC, s.name ASC LIMIT ?";
+    } else {
+      sql += " ORDER BY (s.line_count * (1.0 + s.nesting_depth * 0.3)) DESC, s.nesting_depth DESC, s.name ASC LIMIT ?";
+    }
     params.push(limit);
 
-    return this.db.query<any, any[]>(sql).all(...params);
+    const rows = this.db.query<any, any[]>(sql).all(...params);
+    return rows.map((r) => ({
+      ...r,
+      nesting_depth: r.nesting_depth ?? 1,
+      risk_score: Math.round((r.line_count ?? 1) * (1.0 + (r.nesting_depth ?? 1) * 0.3)),
+    }));
   }
 
   public getSymbolDetails(

package/src/core/database/repository.ts

@@ -32,6 +32,7 @@ export type {
 } from "../../types/index.ts";
 import { DependencyRepository } from "./repositories/dependency.repository.ts";
 import { DomainRepository } from "./repositories/domain.repository.ts";
+import { EnvironmentRepository } from "./repositories/environment.repository.ts";
 import { FileRepository } from "./repositories/file.repository.ts";
 import { MetaRepository } from "./repositories/meta.repository.ts";
 import { SymbolRepository } from "./repositories/symbol.repository.ts";
@@ -44,6 +45,7 @@ export class SeptumRepository {
   public readonly symbols: SymbolRepository;
   public readonly dependencies: DependencyRepository;
   public readonly meta: MetaRepository;
+  public readonly environment: EnvironmentRepository;
 
   constructor(private db: Database) {
     this.domains = new DomainRepository(db);
@@ -51,6 +53,7 @@ export class SeptumRepository {
     this.symbols = new SymbolRepository(db);
     this.dependencies = new DependencyRepository(db);
     this.meta = new MetaRepository(db);
+    this.environment = new EnvironmentRepository(db);
   }
 
   public runInTransaction<T>(fn: () => T): T {
@@ -75,6 +78,10 @@ export class SeptumRepository {
     return this.files.getFileByPath(path);
   }
 
+  public countFiles(): number {
+    return this.files.countFiles();
+  }
+
   public getFilesByDomain(domainId: number): FileRecord[] {
     return this.files.getFilesByDomain(domainId);
   }
@@ -208,10 +215,12 @@ export class SeptumRepository {
 
   public getHotspotSymbols(options: {
     minLines?: number;
+    minNesting?: number;
     kind?: SymbolKind;
     domain?: string;
     limit?: number;
-  } = {}): Array<SymbolRecord & { file_path: string; domain_name: string }> {
+    sortBy?: "lines" | "nesting" | "risk_score";
+  } = {}): Array<SymbolRecord & { file_path: string; domain_name: string; risk_score: number }> {
     return this.symbols.getHotspotSymbols(options);
   }
 
@@ -226,6 +235,15 @@ export class SeptumRepository {
     return this.dependencies.getSymbolImpact(symbolName);
   }
 
+  public getFileInboundImpact(filePath: string): {
+    direct_dependents_count: number;
+    top_consumers: string[];
+    symbols_count: number;
+    risk_level: "low" | "medium" | "high";
+  } {
+    return this.dependencies.getFileInboundImpact(filePath);
+  }
+
   // --- Metadata Methods ---
   public getMeta(key: string): string | null {
     return this.meta.getMeta(key);

package/src/core/database/schema.ts

@@ -1,120 +1,153 @@
-import type { Database } from "bun:sqlite";
-
-export const CURRENT_SCHEMA_VERSION = 2;
-
-export const TABLE_STATEMENTS = [
-  `CREATE TABLE IF NOT EXISTS domains (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL UNIQUE,
-    root_path TEXT NOT NULL,
-    allowed_deps_json TEXT NOT NULL DEFAULT '[]',
-    forbidden_deps_json TEXT NOT NULL DEFAULT '[]',
-    archetypes_json TEXT NOT NULL DEFAULT '{}',
-    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS files (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    domain_id INTEGER NOT NULL,
-    path TEXT NOT NULL UNIQUE,
-    archetype TEXT NOT NULL DEFAULT 'unknown',
-    content_hash TEXT NOT NULL,
-    line_count INTEGER NOT NULL DEFAULT 0,
-    mtime_ms INTEGER NOT NULL DEFAULT 0,
-    size_bytes INTEGER NOT NULL DEFAULT 0,
-    last_scanned_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (domain_id) REFERENCES domains(id) ON DELETE CASCADE
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS symbols (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    file_id INTEGER NOT NULL,
-    name TEXT NOT NULL,
-    kind TEXT NOT NULL,
-    signature TEXT NOT NULL,
-    visibility TEXT NOT NULL DEFAULT 'public',
-    line_start INTEGER NOT NULL DEFAULT 0,
-    line_end INTEGER NOT NULL DEFAULT 0,
-    line_count INTEGER NOT NULL DEFAULT 1,
-    FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS dependencies (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    source_file_id INTEGER NOT NULL,
-    target_symbol_or_path TEXT NOT NULL,
-    import_statement TEXT NOT NULL,
-    line_number INTEGER NOT NULL DEFAULT 0,
-    is_external BOOLEAN NOT NULL DEFAULT 0,
-    FOREIGN KEY (source_file_id) REFERENCES files(id) ON DELETE CASCADE
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS vertical_slices (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    domain_id INTEGER,
-    feature_key TEXT,
-    http_method TEXT NOT NULL,
-    route_uri TEXT NOT NULL,
-    route_name TEXT,
-    controller_class TEXT NOT NULL,
-    action_name TEXT NOT NULL,
-    controller_file TEXT,
-    controller_line INTEGER DEFAULT 0,
-    architecture_style TEXT NOT NULL DEFAULT 'clean',
-    entry_kind TEXT NOT NULL DEFAULT 'http_route',
-    execution_chain_json TEXT NOT NULL,
-    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (domain_id) REFERENCES domains(id) ON DELETE CASCADE
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS repo_meta (
-    key TEXT PRIMARY KEY,
-    value TEXT NOT NULL,
-    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
-  );`,
-];
-
-export const INDEX_STATEMENTS = [
-  "CREATE INDEX IF NOT EXISTS idx_domains_name ON domains(name);",
-  "CREATE INDEX IF NOT EXISTS idx_files_domain_id ON files(domain_id);",
-  "CREATE INDEX IF NOT EXISTS idx_files_path ON files(path);",
-  "CREATE INDEX IF NOT EXISTS idx_symbols_file_id ON symbols(file_id);",
-  "CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);",
-  "CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);",
-  "CREATE INDEX IF NOT EXISTS idx_symbols_line_count ON symbols(kind, line_count DESC);",
-  "CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_file_id);",
-  "CREATE INDEX IF NOT EXISTS idx_dependencies_target ON dependencies(target_symbol_or_path);",
-  "CREATE INDEX IF NOT EXISTS idx_slices_route_uri ON vertical_slices(route_uri);",
-  "CREATE INDEX IF NOT EXISTS idx_slices_route_name ON vertical_slices(route_name);",
-  "CREATE INDEX IF NOT EXISTS idx_slices_controller ON vertical_slices(controller_class, action_name);",
-];
-
-const DROP_ALL_TABLES = `
-  DROP TABLE IF EXISTS repo_meta;
-  DROP TABLE IF EXISTS vertical_slices;
-  DROP TABLE IF EXISTS dependencies;
-  DROP TABLE IF EXISTS symbols;
-  DROP TABLE IF EXISTS files;
-  DROP TABLE IF EXISTS domains;
-`;
-
-export function initializeDatabaseSchema(db: Database): void {
-  const versionRow = db.query<{ user_version: number }, []>("PRAGMA user_version;").get();
-  const userVersion = versionRow?.user_version ?? 0;
-
-  if (userVersion !== 0 && userVersion !== CURRENT_SCHEMA_VERSION) {
-    // Zero-kludge cache invalidation: outdated schema versions are cleanly dropped and recreated
-    db.run(DROP_ALL_TABLES);
-  }
-
-  for (const tableSql of TABLE_STATEMENTS) {
-    db.run(tableSql);
-  }
-
-  for (const indexSql of INDEX_STATEMENTS) {
-    db.run(indexSql);
-  }
-
-  db.run(`PRAGMA user_version = ${CURRENT_SCHEMA_VERSION};`);
-}
+import type { Database } from "bun:sqlite";
+
+export const CURRENT_SCHEMA_VERSION = 4;
+
+export const TABLE_STATEMENTS = [
+  `CREATE TABLE IF NOT EXISTS domains (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE,
+    root_path TEXT NOT NULL,
+    allowed_deps_json TEXT NOT NULL DEFAULT '[]',
+    forbidden_deps_json TEXT NOT NULL DEFAULT '[]',
+    archetypes_json TEXT NOT NULL DEFAULT '{}',
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS files (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    domain_id INTEGER NOT NULL,
+    path TEXT NOT NULL UNIQUE,
+    archetype TEXT NOT NULL DEFAULT 'unknown',
+    content_hash TEXT NOT NULL,
+    line_count INTEGER NOT NULL DEFAULT 0,
+    mtime_ms INTEGER NOT NULL DEFAULT 0,
+    size_bytes INTEGER NOT NULL DEFAULT 0,
+    last_scanned_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (domain_id) REFERENCES domains(id) ON DELETE CASCADE
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS symbols (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    file_id INTEGER NOT NULL,
+    name TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    signature TEXT NOT NULL,
+    visibility TEXT NOT NULL DEFAULT 'public',
+    line_start INTEGER NOT NULL DEFAULT 0,
+    line_end INTEGER NOT NULL DEFAULT 0,
+    line_count INTEGER NOT NULL DEFAULT 1,
+    nesting_depth INTEGER NOT NULL DEFAULT 1,
+    FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS dependencies (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_file_id INTEGER NOT NULL,
+    target_symbol_or_path TEXT NOT NULL,
+    import_statement TEXT NOT NULL,
+    line_number INTEGER NOT NULL DEFAULT 0,
+    is_external BOOLEAN NOT NULL DEFAULT 0,
+    FOREIGN KEY (source_file_id) REFERENCES files(id) ON DELETE CASCADE
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS vertical_slices (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    domain_id INTEGER,
+    feature_key TEXT,
+    http_method TEXT NOT NULL,
+    route_uri TEXT NOT NULL,
+    route_name TEXT,
+    controller_class TEXT NOT NULL,
+    action_name TEXT NOT NULL,
+    controller_file TEXT,
+    controller_line INTEGER DEFAULT 0,
+    architecture_style TEXT NOT NULL DEFAULT 'clean',
+    entry_kind TEXT NOT NULL DEFAULT 'http_route',
+    execution_chain_json TEXT NOT NULL,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (domain_id) REFERENCES domains(id) ON DELETE CASCADE
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS repo_meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS environment_topology (
+    layer TEXT PRIMARY KEY,
+    platform TEXT,
+    status TEXT NOT NULL,
+    detected_from_json TEXT NOT NULL DEFAULT '[]',
+    constraints_json TEXT NOT NULL DEFAULT '[]',
+    unresolved_inquiry TEXT,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS environment_nodes (
+    id TEXT PRIMARY KEY,
+    layer TEXT NOT NULL,
+    name TEXT NOT NULL,
+    platform TEXT NOT NULL,
+    canonical_tag TEXT NOT NULL DEFAULT 'unspecified',
+    domain_or_ip TEXT,
+    role TEXT,
+    status TEXT NOT NULL,
+    detected_from_json TEXT NOT NULL DEFAULT '[]',
+    constraints_json TEXT NOT NULL DEFAULT '[]',
+    connected_to_json TEXT NOT NULL DEFAULT '[]',
+    unresolved_inquiry TEXT,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+  );`,
+];
+
+export const INDEX_STATEMENTS = [
+  "CREATE INDEX IF NOT EXISTS idx_domains_name ON domains(name);",
+  "CREATE INDEX IF NOT EXISTS idx_files_domain_id ON files(domain_id);",
+  "CREATE INDEX IF NOT EXISTS idx_files_path ON files(path);",
+  "CREATE INDEX IF NOT EXISTS idx_symbols_file_id ON symbols(file_id);",
+  "CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);",
+  "CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);",
+  "CREATE INDEX IF NOT EXISTS idx_symbols_line_count ON symbols(kind, line_count DESC);",
+  "CREATE INDEX IF NOT EXISTS idx_symbols_nesting_depth ON symbols(nesting_depth DESC);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_file_id);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_target ON dependencies(target_symbol_or_path);",
+  "CREATE INDEX IF NOT EXISTS idx_slices_route_uri ON vertical_slices(route_uri);",
+  "CREATE INDEX IF NOT EXISTS idx_slices_route_name ON vertical_slices(route_name);",
+  "CREATE INDEX IF NOT EXISTS idx_slices_controller ON vertical_slices(controller_class, action_name);",
+  "CREATE INDEX IF NOT EXISTS idx_env_topology_status ON environment_topology(status);",
+  "CREATE INDEX IF NOT EXISTS idx_env_nodes_layer ON environment_nodes(layer);",
+  "CREATE INDEX IF NOT EXISTS idx_env_nodes_status ON environment_nodes(status);",
+];
+
+const DROP_ALL_TABLES = `
+  DROP TABLE IF EXISTS environment_nodes;
+  DROP TABLE IF EXISTS environment_topology;
+  DROP TABLE IF EXISTS repo_meta;
+  DROP TABLE IF EXISTS vertical_slices;
+  DROP TABLE IF EXISTS dependencies;
+  DROP TABLE IF EXISTS symbols;
+  DROP TABLE IF EXISTS files;
+  DROP TABLE IF EXISTS domains;
+`;
+
+export function initializeDatabaseSchema(db: Database): void {
+  const versionRow = db.query<{ user_version: number }, []>("PRAGMA user_version;").get();
+  const userVersion = versionRow?.user_version ?? 0;
+
+  if (userVersion !== 0 && userVersion !== CURRENT_SCHEMA_VERSION) {
+    // Zero-kludge cache invalidation: outdated schema versions are cleanly dropped and recreated
+    db.run(DROP_ALL_TABLES);
+  }
+
+  for (const tableSql of TABLE_STATEMENTS) {
+    db.run(tableSql);
+  }
+
+  for (const indexSql of INDEX_STATEMENTS) {
+    db.run(indexSql);
+  }
+
+  db.run(`PRAGMA user_version = ${CURRENT_SCHEMA_VERSION};`);
+}

package/src/core/discovery/topology-detector.ts

@@ -43,8 +43,74 @@ export class TopologyDetector {
     ".idea",
     ".agents",
     "bin",
+    "locales",
+    "resources",
+    "public",
+    "assets",
+    "static",
+    ".output",
+    ".nuxt",
+    ".next",
+    ".turbo",
+    ".cache",
   ]);
 
+  private static readonly SOURCE_EXTENSIONS = new Set([
+    ".ts",
+    ".js",
+    ".tsx",
+    ".jsx",
+    ".php",
+    ".py",
+    ".go",
+    ".rs",
+    ".vue",
+  ]);
+
+  /**
+   * Reads compilerOptions.paths from tsconfig.json or jsconfig.json.
+   */
+  public static readTsConfigPaths(projectRoot: string): Record<string, string[]> {
+    for (const file of ["tsconfig.json", "jsconfig.json"]) {
+      const fullPath = path.join(projectRoot, file);
+      if (fs.existsSync(fullPath)) {
+        try {
+          const raw = fs.readFileSync(fullPath, "utf-8");
+          const stripped = raw.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, "");
+          const parsed = JSON.parse(stripped);
+          if (parsed.compilerOptions?.paths) {
+            return parsed.compilerOptions.paths;
+          }
+        } catch {
+          // Ignore tsconfig parse error
+        }
+      }
+    }
+    return {};
+  }
+
+  /**
+   * Checks whether a directory recursively contains any source code files.
+   */
+  private static hasSourceFiles(dir: string): boolean {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".") || this.IGNORED_DIRS.has(entry.name)) continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isFile()) {
+          const ext = path.extname(entry.name).toLowerCase();
+          if (this.SOURCE_EXTENSIONS.has(ext)) return true;
+        } else if (entry.isDirectory()) {
+          if (this.hasSourceFiles(full)) return true;
+        }
+      }
+    } catch {
+      // Ignore read errors
+    }
+    return false;
+  }
+
   /**
    * Detects project topology, classifies project type & architecture style, and maps domains.
    */
@@ -213,9 +279,11 @@ export class TopologyDetector {
       }
     }
 
-    // 5. Fallback: Top-level directories
+    // 5. Fallback: Top-level directories that contain source code
     if (Object.keys(domains).length === 0) {
-      const topDirs = this.getSubdirectories(projectRoot);
+      const topDirs = this.getSubdirectories(projectRoot).filter((d) =>
+        this.hasSourceFiles(path.join(projectRoot, d))
+      );
       for (const d of topDirs) {
         domains[d.toLowerCase()] = {
           root: d,
@@ -384,8 +452,8 @@ export class TopologyDetector {
       return "generic-php";
     }
     if (language === "typescript" || language === "javascript") {
+      const pkgJson = path.join(projectRoot, "package.json");
       try {
-        const pkgJson = path.join(projectRoot, "package.json");
         if (fs.existsSync(pkgJson)) {
           const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
           const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };

package/src/core/ingestion/pipeline.ts

@@ -291,6 +291,19 @@ export class IngestionPipeline {
           middleware: "app/Http/Middleware/**",
         },
       };
+
+      if (existsSync(join(projectRoot, "resources/views"))) {
+        domains["views"] = {
+          root: "resources/views",
+          description: "Laravel Blade Templates and UI Views (auto-discovered)",
+          allowed_dependencies: [],
+          forbidden_dependencies: [],
+          archetypes: {
+            view: "resources/views/**/*.blade.php",
+          },
+        };
+      }
+
       return domains;
     }
 
@@ -433,6 +446,90 @@ export class IngestionPipeline {
   }
 
   private isSourceFile(path: string): boolean {
-    return /\.(ts|tsx|js|jsx|mjs|cjs|php|py|go|rs)$/i.test(path);
+    return /\.(ts|tsx|js|jsx|mjs|cjs|php|py|go|rs|vue|astro|svelte)$/i.test(path);
+  }
+
+  /**
+   * JIT single-file ingestion: quickly verifies and updates a single file's AST,
+   * symbols, and dependencies in SQLite if its mtime or content hash has changed.
+   * Runs in < 5ms for rapid delta sync without full project scans.
+   */
+  public async ingestFile(targetFilePath: string, config: ValidatedSeptumConfig): Promise<boolean> {
+    const fullPath = resolve(targetFilePath);
+    if (!existsSync(fullPath)) return false;
+
+    let stat;
+    try {
+      stat = statSync(fullPath);
+      if (!stat.isFile() || !this.isSourceFile(fullPath)) return false;
+    } catch {
+      return false;
+    }
+
+    const mtimeMs = Math.round(stat.mtimeMs);
+    const sizeBytes = stat.size;
+
+    const projectRoot = this.customWorkspaceRoot || process.cwd();
+    const relPath = relative(projectRoot, fullPath).replace(/\\/g, "/");
+
+    let targetDomainName: string | null = null;
+    let targetDomainCfg = null;
+
+    for (const [dName, dCfg] of Object.entries(config.domains)) {
+      const absRoot = resolve(projectRoot, dCfg.root).replace(/\\/g, "/");
+      const normFullPath = fullPath.replace(/\\/g, "/");
+      if (normFullPath === absRoot || normFullPath.startsWith(absRoot + "/")) {
+        targetDomainName = dName;
+        targetDomainCfg = dCfg;
+        break;
+      }
+    }
+
+    if (!targetDomainName || !targetDomainCfg) {
+      targetDomainName = "core";
+      targetDomainCfg = { root: ".", allowed_dependencies: [], forbidden_dependencies: [], archetypes: {} };
+    }
+
+    const domainId = this.repo.upsertDomain(targetDomainName, targetDomainCfg);
+    const existingFile = this.repo.getFileByPath(relPath);
+
+    // Tier 1: Fast OS metadata check
+    if (
+      existingFile &&
+      existingFile.mtime_ms === mtimeMs &&
+      existingFile.size_bytes === sizeBytes
+    ) {
+      return false; // Completely up to date
+    }
+
+    const content = readFileSync(fullPath, "utf-8");
+    const currentHash = computeContentHash(content);
+
+    // Tier 2: Hash verification
+    if (existingFile && existingFile.content_hash === currentHash) {
+      this.repo.updateFileMetadataOnly(existingFile.id, mtimeMs, sizeBytes);
+      return false;
+    }
+
+    const lineCount = content.split("\n").length;
+    const archetype = detectArchetype(relPath, targetDomainCfg.archetypes ?? {});
+    const ast = await this.parserEngine.parseFile(fullPath, content);
+
+    this.repo.runInTransaction(() => {
+      const fileId = this.repo.upsertFile(
+        domainId,
+        relPath,
+        archetype,
+        currentHash,
+        lineCount,
+        mtimeMs,
+        sizeBytes
+      );
+      this.repo.replaceFileSymbols(fileId, ast.symbols);
+      this.repo.replaceFileDependencies(fileId, ast.dependencies);
+    });
+
+    return true;
   }
 }
+