septum 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shironim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# Septum
+
+> **Deterministic Bounded-Context & Anti-Poisoning Architecture Guard for AI Coding Agents.**
+
+[![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.
+
+---
+
+## Installation
+
+Install Septum globally using [Bun](https://bun.sh):
+
+```bash
+bun add -g septum
+```
+
+> **Note:** You can also run commands on-the-fly without global installation using `bunx septum <command>`.
+
+---
+
+## Quick Start
+
+### 1. Initialize in Any Project
+
+```bash
+septum init
+# or zero-install via bunx:
+bunx septum init
+```
+*Auto-detects project topology (Monorepos, Laravel, Next.js, Go, NestJS), registers domains, and ingests AST symbols into `.septum/septum.db`.*
+
+### 2. Connect to AI Agent (MCP Server)
+
+Add Septum to your MCP client (`mcp.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "septum": {
+      "command": "septum",
+      "args": ["serve"]
+    }
+  }
+}
+```
+*(Or use `"command": "bunx", "args": ["septum", "serve"]` if running without global installation).*
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `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 check --strict` | CI/CD gate: verify boundary integrity & fail on violations |
+| `septum query [domain]` | Inspect domain catalog, archetypes, and public signatures |
+| `septum feature status\|clear` | Manage active feature lease and editing scope |
+| `septum serve` | Launch stdio MCP server for AI coding agents |
+
+---
+
+## Core Capabilities & MCP Tools
+
+All tools expose typed schemas automatically via the Model Context Protocol:
+
+- **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.
+- **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.
+- **Dynamic Topology (`septum_register_domain`):** Registers or updates domains and boundary rules on-the-fly.
+
+---
+
+## Development & Contributing
+
+```bash
+# Clone and install dependencies
+git clone https://github.com/shironim/septum.git
+cd septum
+bun install
+
+# Run test suite & build
+bun test
+bun run build
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © shironim

package/bin/septum.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCLI } from "../src/cli/index.ts";
+
+runCLI(process.argv);

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "septum",
+  "version": "0.1.0",
+  "description": "Deterministic Bounded-Context, Structural File Catalog & Anti-Poisoning Partition for AI Agents",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "septum": "./bin/septum.ts"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "start": "bun run bin/septum.ts",
+    "serve": "bun run bin/septum.ts serve",
+    "ingest": "bun run bin/septum.ts ingest",
+    "sync": "bun run bin/septum.ts sync",
+    "check": "bun run bin/septum.ts check",
+    "test": "bun test",
+    "build": "bun build ./bin/septum.ts --compile --outfile dist/septum",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.5.0",
+    "web-tree-sitter": "^0.24.0",
+    "yaml": "^2.7.0",
+    "zod": "^3.24.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shironim/septum.git"
+  },
+  "homepage": "https://github.com/shironim/septum#readme",
+  "bugs": {
+    "url": "https://github.com/shironim/septum/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bounded-context",
+    "architecture",
+    "ai-agent",
+    "tree-sitter",
+    "clean-architecture",
+    "domain-driven-design",
+    "codebase-catalog",
+    "antigravity"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "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

@@ -0,0 +1,161 @@
+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";
+
+export interface CheckCommandOptions {
+  strict?: boolean;
+  staged?: boolean;
+  feature?: string;
+}
+
+export async function handleCheckCommand(
+  optionsOrStrict?: boolean | CheckCommandOptions
+): Promise<void> {
+  const options: CheckCommandOptions =
+    typeof optionsOrStrict === "boolean" ? { strict: optionsOrStrict } : optionsOrStrict || {};
+
+  console.log(
+    options.staged
+      ? "[Septum] Auditing git staged files against domain boundaries..."
+      : "[Septum] Running codebase boundary integrity check..."
+  );
+
+  const config = ConfigLoader.load();
+  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);
+    }
+
+    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);
+
+      for (const dep of parsed.dependencies) {
+        if (dep.is_external) continue;
+
+        const targetDomain = evaluator.resolveTargetDomain(
+          dep.target,
+          config,
+          relPath
+        );
+
+        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
+    }
+  }
+
+  return violations;
+}

package/src/cli/commands/hook.ts

@@ -0,0 +1,188 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { BoundaryEvaluator } from "../../core/boundary/evaluator.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 { SessionManager } from "../../core/session/session-manager.ts";
+
+export interface ToolPayload {
+  tool_name: string;
+  tool_input: {
+    TargetFile?: string;
+    file_path?: string;
+    ReplacementContent?: string;
+    CodeContent?: string;
+    feature_key?: string;
+  };
+}
+
+export async function handleHookCommand(args: string[]): Promise<void> {
+  const subHook = args[1] || "pre-write";
+
+  if (subHook === "pre-write") {
+    await runPreWriteHook();
+  } else {
+    process.exit(0);
+  }
+}
+
+async function runPreWriteHook(): Promise<void> {
+  // If .septum/septum.db does not exist, pass through
+  const dbPath = path.resolve(process.cwd(), ".septum", "septum.db");
+  if (!fs.existsSync(dbPath)) {
+    process.exit(0);
+  }
+
+  // Read JSON payload from stdin
+  const stdinData = await readStdin();
+  if (!stdinData.trim()) {
+    process.exit(0);
+  }
+
+  let payload: ToolPayload;
+  try {
+    payload = JSON.parse(stdinData);
+  } catch {
+    // Non-JSON stdin, pass through
+    process.exit(0);
+  }
+
+  const toolInput = payload.tool_input || {};
+  const targetFile = toolInput.TargetFile || toolInput.file_path;
+  const content = toolInput.ReplacementContent || toolInput.CodeContent || "";
+
+  if (!targetFile) {
+    process.exit(0);
+  }
+
+  const config = ConfigLoader.load();
+  const db = new SeptumDatabase(config.settings.db_path);
+  const repo = new SeptumRepository(db.raw);
+  const evaluator = new BoundaryEvaluator(repo);
+
+  try {
+    const sourceDomain = evaluator.resolveSourceDomain(targetFile, config);
+
+    // If file is not inside any domain, allow or check feature scope
+    if (sourceDomain) {
+      // -------------------------------------------------------------
+      // GATE 3: Mandatory Catalog Consultation
+      // Verify that the AI has consulted the domain catalog before writing
+      // -------------------------------------------------------------
+      const accessLogPath = path.resolve(process.cwd(), ".septum/catalog_access.json");
+      let hasConsulted = false;
+
+      if (fs.existsSync(accessLogPath)) {
+        try {
+          const rawAccess = JSON.parse(fs.readFileSync(accessLogPath, "utf-8"));
+          const domainAccessedAt = rawAccess.domains?.[sourceDomain];
+          if (domainAccessedAt) {
+            hasConsulted = true;
+          }
+        } catch {
+          // ignore parse error
+        }
+      }
+
+      if (!hasConsulted) {
+        console.error(
+          `\n[SEPTUM GATE 3 VIOLATION - Mandatory Consultation Required]\n` +
+            `✕ Operation blocked: You are attempting to write to domain '${sourceDomain}' (${targetFile}) ` +
+            `without inspecting its authoritative catalog first.\n` +
+            `▶ REQUIRED ACTION: Call tool 'septum_get_domain_catalog(domain: "${sourceDomain}")' ` +
+            `or 'septum_get_feature_context' before writing code.\n`
+        );
+        db.close();
+        process.exit(1);
+      }
+    }
+
+    // -------------------------------------------------------------
+    // 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;
+
+    if (activeFeatureKey && features[activeFeatureKey]) {
+      const touchpointViolations = evaluator.checkFeatureTouchpoints(
+        activeFeatureKey,
+        targetFile,
+        config
+      );
+
+      if (touchpointViolations.length > 0) {
+        console.error(
+          `\n[SEPTUM GATE 1 VIOLATION - Scope Touchpoint Lock]\n` +
+            `✕ Operation blocked: File '${targetFile}' is outside the declared allowed_touchpoints for feature '${activeFeatureKey}'.\n` +
+            `▶ REASON: ${touchpointViolations[0].message}\n` +
+            `▶ REQUIRED ACTION: Only modify files declared in allowed_touchpoints for this feature.\n`
+        );
+        db.close();
+        process.exit(1);
+      }
+    }
+
+    // -------------------------------------------------------------
+    // GATE 2: Real-time AST Import Interception
+    // Extract imports from proposed content and check for boundary leaks
+    // -------------------------------------------------------------
+    if (content && sourceDomain) {
+      const astEngine = new ASTParserEngine();
+      const parsed = await astEngine.parseFile(targetFile, content);
+
+      const proposedImports = parsed.dependencies.map((d) => d.target);
+      const boundaryViolations = evaluator.checkProposedChanges(
+        targetFile,
+        proposedImports,
+        config
+      );
+
+      if (boundaryViolations.length > 0) {
+        const v = boundaryViolations[0];
+        console.error(
+          `\n[SEPTUM GATE 2 VIOLATION - Forbidden Cross-Domain Import]\n` +
+            `✕ Operation blocked: Proposed code imports forbidden domain '${v.target_domain}' from '${v.source_domain}'.\n` +
+            `▶ OFFENDING IMPORT: ${v.imported_target}\n` +
+            `▶ RULE: ${v.rule}\n` +
+            `▶ MESSAGE: ${v.message}\n` +
+            `▶ REQUIRED ACTION: Decouple this dependency. Use an authorized Interface, Event, or Shared Kernel.\n`
+        );
+        db.close();
+        process.exit(1);
+      }
+    }
+
+    db.close();
+    process.exit(0);
+  } catch (err) {
+    db.close();
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`\x1b[31m[Septum Hook Error]\x1b[0m ${message}`);
+    process.exit(1);
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = "";
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => {
+      resolve(data);
+    });
+    process.stdin.on("error", () => {
+      resolve("");
+    });
+  });
+}

package/src/cli/commands/ingest.ts

@@ -0,0 +1,29 @@
+import { ConfigLoader } from "../../core/config/loader.ts";
+import { SeptumDatabase } from "../../core/database/client.ts";
+import { SeptumRepository } from "../../core/database/repository.ts";
+import { IngestionPipeline } from "../../core/ingestion/pipeline.ts";
+
+export async function handleIngestCommand(): Promise<void> {
+  console.log("[Septum] Starting codebase structural ingestion...");
+
+  const config = ConfigLoader.load();
+  const db = new SeptumDatabase(config.settings.db_path);
+  const repo = new SeptumRepository(db.raw);
+  const pipeline = new IngestionPipeline(repo);
+
+  const metrics = await pipeline.run(config);
+
+  console.log("=========================================");
+  console.log("  Septum Ingestion Complete");
+  console.log("=========================================");
+  console.log(`  Domains Processed:     ${metrics.domains_processed}`);
+  console.log(`  Files Scanned:         ${metrics.files_scanned}`);
+  console.log(`  Files Updated/Added:   ${metrics.files_updated}`);
+  console.log(`  Files Cached/Skipped:  ${metrics.files_skipped}`);
+  console.log(`  Symbols Indexed:       ${metrics.symbols_indexed}`);
+  console.log(`  Dependencies Indexed:  ${metrics.dependencies_indexed}`);
+  console.log(`  Execution Time:        ${metrics.duration_ms} ms`);
+  console.log("=========================================");
+
+  db.close();
+}