speclock 4.5.7 → 5.0.1

package/src/mcp/http-server.js

@@ -36,6 +36,22 @@ import {
   overrideLock,
   getOverrideHistory,
   semanticAudit,
+  addTypedLock,
+  updateTypedLockThreshold,
+  checkAllTypedConstraints,
+  getEnforcementConfig,
+  CONSTRAINT_TYPES,
+  OPERATORS,
+  checkTypedConstraint,
+  formatTypedLockText,
+  compileSpec,
+  compileAndApply,
+  buildGraph,
+  getOrBuildGraph,
+  getBlastRadius,
+  mapLocksToFiles,
+  getModules,
+  getCriticalPaths,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -91,7 +107,7 @@ import { fileURLToPath } from "url";
 import _path from "path";
 
 const PROJECT_ROOT = process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
-const VERSION = "4.5.7";
+const VERSION = "5.0.0";
 const AUTHOR = "Sandeep Roy";
 const START_TIME = Date.now();
 
@@ -512,6 +528,101 @@ function createSpecLockServer() {
     return { content: [{ type: "text", text: `Overrides (${result.total}):\n${lines}` }] };
   });
 
+  // ========================================
+  // TYPED CONSTRAINTS — Autonomous Systems Governance (v5.0)
+  // ========================================
+
+  // Tool 29: speclock_add_typed_lock
+  server.tool("speclock_add_typed_lock", "Add a typed constraint for autonomous systems governance.", {
+    constraintType: z.enum(["numerical", "range", "state", "temporal"]),
+    metric: z.string().optional(),
+    operator: z.enum(["<", "<=", "==", "!=", ">=", ">"]).optional(),
+    value: z.number().optional(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+    unit: z.string().optional(),
+    entity: z.string().optional(),
+    forbidden: z.array(z.object({ from: z.string(), to: z.string() })).optional(),
+    requireApproval: z.boolean().optional(),
+    description: z.string().optional(),
+    tags: z.array(z.string()).default([]),
+    source: z.enum(["user", "agent"]).default("user"),
+  }, async (params) => {
+    const constraint = {
+      constraintType: params.constraintType,
+      ...(params.metric && { metric: params.metric }),
+      ...(params.operator && { operator: params.operator }),
+      ...(params.value !== undefined && { value: params.value }),
+      ...(params.min !== undefined && { min: params.min }),
+      ...(params.max !== undefined && { max: params.max }),
+      ...(params.unit && { unit: params.unit }),
+      ...(params.entity && { entity: params.entity }),
+      ...(params.forbidden && { forbidden: params.forbidden }),
+      ...(params.requireApproval !== undefined && { requireApproval: params.requireApproval }),
+    };
+    const result = addTypedLock(PROJECT_ROOT, constraint, params.tags, params.source, params.description);
+    if (result.error) return { content: [{ type: "text", text: `Error: ${result.error}` }], isError: true };
+    return { content: [{ type: "text", text: `Typed lock added (${params.constraintType}): ${result.lockId}` }] };
+  });
+
+  // Tool 30: speclock_check_typed
+  server.tool("speclock_check_typed", "Check a proposed value or state transition against typed constraints.", {
+    metric: z.string().optional(),
+    entity: z.string().optional(),
+    value: z.number().optional(),
+    from: z.string().optional(),
+    to: z.string().optional(),
+  }, async (params) => {
+    const brain = ensureInit(PROJECT_ROOT);
+    const proposed = {
+      ...(params.metric && { metric: params.metric }),
+      ...(params.entity && { entity: params.entity }),
+      ...(params.value !== undefined && { value: params.value }),
+      ...(params.from && { from: params.from }),
+      ...(params.to && { to: params.to }),
+    };
+    const result = checkAllTypedConstraints(brain.specLock?.items || [], proposed);
+    if (result.hasConflict) {
+      const enforcement = getEnforcementConfig(PROJECT_ROOT);
+      const isHard = enforcement.mode === "hard";
+      const topConf = result.conflictingLocks[0]?.confidence || 0;
+      return {
+        content: [{ type: "text", text: `VIOLATION: ${result.analysis}` }],
+        isError: isHard && topConf >= enforcement.blockThreshold,
+      };
+    }
+    return { content: [{ type: "text", text: result.analysis }] };
+  });
+
+  // Tool 31: speclock_list_typed_locks
+  server.tool("speclock_list_typed_locks", "List all typed constraints.", {}, async () => {
+    const brain = ensureInit(PROJECT_ROOT);
+    const typed = (brain.specLock?.items || []).filter(l => l.active !== false && l.constraintType);
+    if (typed.length === 0) return { content: [{ type: "text", text: "No typed constraints. Use speclock_add_typed_lock to add." }] };
+    const lines = typed.map(l => `[${l.constraintType}] ${l.id}: ${l.text}`).join("\n");
+    return { content: [{ type: "text", text: `Typed Constraints (${typed.length}):\n${lines}` }] };
+  });
+
+  // Tool 32: speclock_update_threshold
+  server.tool("speclock_update_threshold", "Update a typed lock threshold.", {
+    lockId: z.string().min(1),
+    value: z.number().optional(),
+    operator: z.enum(["<", "<=", "==", "!=", ">=", ">"]).optional(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+    forbidden: z.array(z.object({ from: z.string(), to: z.string() })).optional(),
+  }, async (params) => {
+    const updates = {};
+    if (params.value !== undefined) updates.value = params.value;
+    if (params.operator) updates.operator = params.operator;
+    if (params.min !== undefined) updates.min = params.min;
+    if (params.max !== undefined) updates.max = params.max;
+    if (params.forbidden) updates.forbidden = params.forbidden;
+    const result = updateTypedLockThreshold(PROJECT_ROOT, params.lockId, updates);
+    if (result.error) return { content: [{ type: "text", text: `Error: ${result.error}` }], isError: true };
+    return { content: [{ type: "text", text: `Updated ${params.lockId}: ${JSON.stringify(result.newValues)}` }] };
+  });
+
   return server;
 }
 
@@ -770,7 +881,7 @@ app.get("/health", (req, res) => {
     status: "healthy",
     version: VERSION,
     uptime: Math.floor((Date.now() - START_TIME) / 1000),
-    tools: 28,
+    tools: 35,
     auditChain: auditStatus,
     authEnabled: isAuthEnabled(PROJECT_ROOT),
     rateLimit: { limit: RATE_LIMIT, windowMs: RATE_WINDOW_MS },
@@ -784,8 +895,8 @@ app.get("/", (req, res) => {
     name: "speclock",
     version: VERSION,
     author: AUTHOR,
-    description: "AI Constraint Engine with Policy-as-Code DSL, OAuth/OIDC SSO, admin dashboard, telemetry, API key auth, RBAC, AES-256-GCM encryption, hard enforcement, semantic pre-commit, HMAC audit chain, SOC 2/HIPAA compliance. 31 MCP tools. Enterprise platform.",
-    tools: 31,
+    description: "AI Constraint Engine for autonomous systems governance. Typed constraints (numerical, range, state, temporal) + REST API v2 with batch checking & SSE streaming. Python SDK + ROS2 integration. Policy-as-Code, OAuth/OIDC SSO, admin dashboard, telemetry, RBAC, AES-256-GCM encryption, hard enforcement, HMAC audit chain, SOC 2/HIPAA compliance. 35 MCP tools.",
+    tools: 35,
     mcp_endpoint: "/mcp",
     health_endpoint: "/health",
     npm: "https://www.npmjs.com/package/speclock",
@@ -799,7 +910,7 @@ app.get("/.well-known/mcp/server-card.json", (req, res) => {
   res.json({
     name: "SpecLock",
     version: VERSION,
-    description: "AI Constraint Engine — memory + enforcement for AI coding tools. Hybrid heuristic + Gemini LLM for universal domain coverage. Policy-as-Code DSL, OAuth/OIDC SSO, admin dashboard, telemetry, API key auth, RBAC, AES-256-GCM encryption, hard enforcement, semantic pre-commit, HMAC audit chain, SOC 2/HIPAA compliance. 31 MCP tools + CLI. Works with Claude Code, Cursor, Windsurf, Cline, Bolt.new, Lovable.",
+    description: "AI Constraint Engine for autonomous systems governance. Typed constraints + REST API v2 with batch checking & SSE streaming. Python SDK (pip install speclock) + ROS2 Guardian Node. Hybrid heuristic + Gemini LLM. Policy-as-Code, OAuth/OIDC SSO, admin dashboard, telemetry, RBAC, AES-256-GCM encryption, hard enforcement, HMAC audit chain, SOC 2/HIPAA compliance. 35 MCP tools + CLI. Works with Claude Code, Cursor, Windsurf, Cline, Bolt.new, Lovable.",
     author: {
       name: "Sandeep Roy",
       url: "https://github.com/sgroy10",
@@ -808,7 +919,7 @@ app.get("/.well-known/mcp/server-card.json", (req, res) => {
     homepage: "https://sgroy10.github.io/speclock/",
     license: "MIT",
     capabilities: {
-      tools: 31,
+      tools: 35,
       categories: [
         "Memory Management",
         "Change Tracking",
@@ -820,6 +931,11 @@ app.get("/.well-known/mcp/server-card.json", (req, res) => {
         "Hard Enforcement",
         "Policy-as-Code",
         "Telemetry",
+        "Typed Constraints",
+        "REST API v2",
+        "Real-Time Streaming",
+        "Robotics / ROS2",
+        "Python SDK",
       ],
     },
     keywords: [
@@ -827,6 +943,8 @@ app.get("/.well-known/mcp/server-card.json", (req, res) => {
       "sso", "oauth", "rbac", "encryption", "audit", "compliance",
       "soc2", "hipaa", "dashboard", "telemetry", "claude-code",
       "cursor", "bolt-new", "lovable", "enterprise",
+      "robotics", "ros2", "autonomous-systems", "iot", "typed-constraints",
+      "real-time", "sse", "batch-api", "python-sdk", "safety",
     ],
   });
 });
@@ -922,6 +1040,475 @@ app.post("/policy", async (req, res) => {
   }
 });
 
+// ========================================
+// REST API v2 — Real-Time Constraint Checking (v5.0)
+// For robotics, IoT, autonomous systems, trading platforms.
+// Sub-millisecond local checks, batch operations, SSE streaming.
+// Developed by Sandeep Roy (https://github.com/sgroy10)
+// ========================================
+
+// --- v2: Check a single typed constraint ---
+app.post("/api/v2/check-typed", (req, res) => {
+  setCorsHeaders(res);
+  const clientIp = req.headers["x-forwarded-for"]?.split(",")[0]?.trim() || req.socket?.remoteAddress || "unknown";
+  if (!checkRateLimit(clientIp)) {
+    return res.status(429).json({ error: "Rate limit exceeded." });
+  }
+
+  const start = performance.now();
+  const { metric, entity, value, from_state, to_state } = req.body || {};
+
+  if (!metric && !entity) {
+    return res.status(400).json({ error: "Required: metric (string) or entity (string)" });
+  }
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const brain = readBrain(PROJECT_ROOT);
+    const locks = brain?.specLock?.items || [];
+
+    const proposed = {};
+    if (metric) proposed.metric = metric;
+    if (entity) proposed.entity = entity;
+    if (value !== undefined) proposed.value = value;
+    if (from_state) proposed.from = from_state;
+    if (to_state) proposed.to = to_state;
+
+    const result = checkAllTypedConstraints(locks, proposed);
+    const elapsed = performance.now() - start;
+
+    return res.json({
+      ...result,
+      response_time_ms: Number(elapsed.toFixed(3)),
+      api_version: "v2",
+    });
+  } catch (err) {
+    return res.status(500).json({ error: err.message });
+  }
+});
+
+// --- v2: Batch check multiple values at once ---
+// Single HTTP call for all sensor readings in a tick.
+// Body: { checks: [{ metric, value }, { entity, from_state, to_state }, ...] }
+app.post("/api/v2/check-batch", (req, res) => {
+  setCorsHeaders(res);
+  const clientIp = req.headers["x-forwarded-for"]?.split(",")[0]?.trim() || req.socket?.remoteAddress || "unknown";
+  if (!checkRateLimit(clientIp)) {
+    return res.status(429).json({ error: "Rate limit exceeded." });
+  }
+
+  const start = performance.now();
+  const { checks } = req.body || {};
+
+  if (!Array.isArray(checks) || checks.length === 0) {
+    return res.status(400).json({ error: "Required: checks (non-empty array)" });
+  }
+  if (checks.length > 100) {
+    return res.status(400).json({ error: "Too many checks (max 100 per batch)" });
+  }
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const brain = readBrain(PROJECT_ROOT);
+    const locks = brain?.specLock?.items || [];
+
+    const results = [];
+    let totalViolations = 0;
+    let criticalCount = 0;
+
+    for (const check of checks) {
+      const proposed = {};
+      if (check.metric) proposed.metric = check.metric;
+      if (check.entity) proposed.entity = check.entity;
+      if (check.value !== undefined) proposed.value = check.value;
+      if (check.from_state) proposed.from = check.from_state;
+      if (check.to_state) proposed.to = check.to_state;
+
+      const result = checkAllTypedConstraints(locks, proposed);
+      if (result.hasConflict) {
+        totalViolations++;
+        const topConfidence = result.conflictingLocks?.[0]?.confidence || 0;
+        if (topConfidence >= 90) criticalCount++;
+      }
+
+      results.push({
+        input: check,
+        ...result,
+      });
+    }
+
+    const elapsed = performance.now() - start;
+
+    return res.json({
+      batch_size: checks.length,
+      total_violations: totalViolations,
+      critical_violations: criticalCount,
+      emergency_stop: criticalCount > 0,
+      results,
+      response_time_ms: Number(elapsed.toFixed(3)),
+      avg_check_ms: Number((elapsed / checks.length).toFixed(3)),
+      api_version: "v2",
+    });
+  } catch (err) {
+    return res.status(500).json({ error: err.message });
+  }
+});
+
+// --- v2: Add typed constraint via REST ---
+app.post("/api/v2/constraints", (req, res) => {
+  setCorsHeaders(res);
+  const auth = authenticateRequest(req);
+  if (auth.authEnabled && (!auth.valid || !checkPermission(auth.role, "speclock_add_lock"))) {
+    return res.status(auth.valid ? 403 : 401).json({ error: "Write permission required." });
+  }
+
+  const { constraint_type, description, tags, ...kwargs } = req.body || {};
+
+  if (!CONSTRAINT_TYPES.includes(constraint_type)) {
+    return res.status(400).json({
+      error: `Invalid constraint_type. Must be one of: ${CONSTRAINT_TYPES.join(", ")}`,
+    });
+  }
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const lockId = addTypedLock(PROJECT_ROOT, { constraintType: constraint_type, ...kwargs }, tags || [], "user", description);
+    return res.json({ success: true, lock_id: lockId, constraint_type });
+  } catch (err) {
+    return res.status(400).json({ error: err.message });
+  }
+});
+
+// --- v2: List typed constraints ---
+app.get("/api/v2/constraints", (req, res) => {
+  setCorsHeaders(res);
+  try {
+    ensureInit(PROJECT_ROOT);
+    const brain = readBrain(PROJECT_ROOT);
+    const locks = (brain?.specLock?.items || []).filter(
+      (l) => l.active !== false && CONSTRAINT_TYPES.includes(l.constraintType)
+    );
+
+    const byType = {};
+    for (const ct of CONSTRAINT_TYPES) byType[ct] = 0;
+    for (const l of locks) byType[l.constraintType]++;
+
+    return res.json({
+      total: locks.length,
+      by_type: byType,
+      constraints: locks.map((l) => ({
+        id: l.id,
+        type: l.constraintType,
+        metric: l.metric,
+        entity: l.entity,
+        text: l.text || formatTypedLockText(l),
+        tags: l.tags || [],
+        created: l.createdAt,
+      })),
+      api_version: "v2",
+    });
+  } catch (err) {
+    return res.status(500).json({ error: err.message });
+  }
+});
+
+// --- v2: Update constraint threshold ---
+app.put("/api/v2/constraints/:lockId", (req, res) => {
+  setCorsHeaders(res);
+  const auth = authenticateRequest(req);
+  if (auth.authEnabled && (!auth.valid || !checkPermission(auth.role, "speclock_add_lock"))) {
+    return res.status(auth.valid ? 403 : 401).json({ error: "Write permission required." });
+  }
+
+  const { lockId } = req.params;
+  const updates = req.body || {};
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const result = updateTypedLockThreshold(PROJECT_ROOT, lockId, updates);
+    return res.json({ success: true, ...result });
+  } catch (err) {
+    return res.status(400).json({ error: err.message });
+  }
+});
+
+// --- v2: Delete constraint ---
+app.delete("/api/v2/constraints/:lockId", (req, res) => {
+  setCorsHeaders(res);
+  const auth = authenticateRequest(req);
+  if (auth.authEnabled && (!auth.valid || !checkPermission(auth.role, "speclock_add_lock"))) {
+    return res.status(auth.valid ? 403 : 401).json({ error: "Write permission required." });
+  }
+
+  const { lockId } = req.params;
+  try {
+    ensureInit(PROJECT_ROOT);
+    removeLock(PROJECT_ROOT, lockId);
+    return res.json({ success: true, removed: lockId });
+  } catch (err) {
+    return res.status(400).json({ error: err.message });
+  }
+});
+
+// --- v2: SSE Stream for real-time constraint status ---
+// Clients connect once and receive constraint violation events in real-time.
+// Usage: const evtSource = new EventSource("/api/v2/stream");
+const sseClients = new Set();
+
+app.get("/api/v2/stream", (req, res) => {
+  setCorsHeaders(res);
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.flushHeaders();
+
+  // Send initial status
+  try {
+    ensureInit(PROJECT_ROOT);
+    const brain = readBrain(PROJECT_ROOT);
+    const locks = (brain?.specLock?.items || []).filter(
+      (l) => l.active !== false && CONSTRAINT_TYPES.includes(l.constraintType)
+    );
+    const initData = {
+      type: "connected",
+      typed_constraints: locks.length,
+      total_locks: (brain?.specLock?.items || []).filter((l) => l.active !== false).length,
+      timestamp: new Date().toISOString(),
+    };
+    res.write(`event: status\ndata: ${JSON.stringify(initData)}\n\n`);
+  } catch {
+    res.write(`event: status\ndata: ${JSON.stringify({ type: "connected", typed_constraints: 0 })}\n\n`);
+  }
+
+  // Register client
+  const client = { res, id: Date.now() };
+  sseClients.add(client);
+
+  // Keep alive every 15 seconds
+  const keepAlive = setInterval(() => {
+    res.write(`:keepalive ${new Date().toISOString()}\n\n`);
+  }, 15_000);
+
+  req.on("close", () => {
+    sseClients.delete(client);
+    clearInterval(keepAlive);
+  });
+});
+
+// --- v2: Push a check and broadcast violations via SSE ---
+// POST /api/v2/stream/check — check constraints AND push violations to all SSE clients
+app.post("/api/v2/stream/check", (req, res) => {
+  setCorsHeaders(res);
+  const clientIp = req.headers["x-forwarded-for"]?.split(",")[0]?.trim() || req.socket?.remoteAddress || "unknown";
+  if (!checkRateLimit(clientIp)) {
+    return res.status(429).json({ error: "Rate limit exceeded." });
+  }
+
+  const start = performance.now();
+  const { checks } = req.body || {};
+
+  // Accept single check or batch
+  const checkList = Array.isArray(checks) ? checks : [req.body];
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const brain = readBrain(PROJECT_ROOT);
+    const locks = brain?.specLock?.items || [];
+    const violations = [];
+
+    for (const check of checkList) {
+      const proposed = {};
+      if (check.metric) proposed.metric = check.metric;
+      if (check.entity) proposed.entity = check.entity;
+      if (check.value !== undefined) proposed.value = check.value;
+      if (check.from_state) proposed.from = check.from_state;
+      if (check.to_state) proposed.to = check.to_state;
+
+      const result = checkAllTypedConstraints(locks, proposed);
+      if (result.hasConflict) {
+        const violation = {
+          type: "violation",
+          input: check,
+          conflicts: result.conflictingLocks,
+          analysis: result.analysis,
+          timestamp: new Date().toISOString(),
+        };
+        violations.push(violation);
+
+        // Broadcast to all SSE clients
+        for (const client of sseClients) {
+          try {
+            client.res.write(`event: violation\ndata: ${JSON.stringify(violation)}\n\n`);
+          } catch {
+            sseClients.delete(client);
+          }
+        }
+      }
+    }
+
+    const elapsed = performance.now() - start;
+    return res.json({
+      checked: checkList.length,
+      violations: violations.length,
+      emergency_stop: violations.some(
+        (v) => v.conflicts?.some((c) => c.confidence >= 90)
+      ),
+      details: violations,
+      sse_clients: sseClients.size,
+      response_time_ms: Number(elapsed.toFixed(3)),
+      api_version: "v2",
+    });
+  } catch (err) {
+    return res.status(500).json({ error: err.message });
+  }
+});
+
+// --- v2: Real-time system status ---
+app.get("/api/v2/status", (req, res) => {
+  setCorsHeaders(res);
+  try {
+    ensureInit(PROJECT_ROOT);
+    const brain = readBrain(PROJECT_ROOT);
+    const allLocks = (brain?.specLock?.items || []).filter((l) => l.active !== false);
+    const typedLocks = allLocks.filter((l) => CONSTRAINT_TYPES.includes(l.constraintType));
+    const textLocks = allLocks.filter((l) => !l.constraintType);
+
+    const byType = {};
+    for (const ct of CONSTRAINT_TYPES) byType[ct] = 0;
+    for (const l of typedLocks) byType[l.constraintType]++;
+
+    // Unique metrics and entities being monitored
+    const metrics = [...new Set(typedLocks.filter((l) => l.metric).map((l) => l.metric))];
+    const entities = [...new Set(typedLocks.filter((l) => l.entity).map((l) => l.entity))];
+
+    return res.json({
+      status: "active",
+      version: VERSION,
+      uptime: Math.floor((Date.now() - START_TIME) / 1000),
+      constraints: {
+        typed: typedLocks.length,
+        text: textLocks.length,
+        total: allLocks.length,
+        by_type: byType,
+      },
+      monitoring: {
+        metrics,
+        entities,
+        sse_clients: sseClients.size,
+      },
+      violations: (brain?.state?.violations || []).length,
+      goal: brain?.goal?.text || "",
+      api_version: "v2",
+    });
+  } catch (err) {
+    return res.status(500).json({ error: err.message });
+  }
+});
+
+// ========================================
+// SPEC COMPILER ENDPOINTS (v5.0)
+// ========================================
+
+app.post("/api/v2/compiler/compile", async (req, res) => {
+  setCorsHeaders(res);
+  const clientIp = req.headers["x-forwarded-for"]?.split(",")[0]?.trim() || req.socket?.remoteAddress || "unknown";
+  if (!checkRateLimit(clientIp)) {
+    return res.status(429).json({ error: "Rate limit exceeded", api_version: "v2" });
+  }
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const { text, autoApply } = req.body || {};
+    if (!text || typeof text !== "string") {
+      return res.status(400).json({ error: "Missing or invalid 'text' field", api_version: "v2" });
+    }
+
+    const result = autoApply
+      ? await compileAndApply(PROJECT_ROOT, text)
+      : await compileSpec(PROJECT_ROOT, text);
+
+    if (!result.success) {
+      return res.status(400).json({ error: result.error, api_version: "v2" });
+    }
+
+    return res.json({
+      success: true,
+      locks: result.locks,
+      typedLocks: result.typedLocks,
+      decisions: result.decisions,
+      notes: result.notes,
+      summary: result.summary || "",
+      applied: result.applied || null,
+      totalApplied: result.totalApplied || 0,
+      api_version: "v2",
+    });
+  } catch (err) {
+    return res.status(500).json({ error: err.message, api_version: "v2" });
+  }
+});
+
+// ========================================
+// CODE GRAPH ENDPOINTS (v5.0)
+// ========================================
+
+app.get("/api/v2/graph", (req, res) => {
+  setCorsHeaders(res);
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const graph = getOrBuildGraph(PROJECT_ROOT);
+    return res.json({ ...graph, api_version: "v2" });
+  } catch (err) {
+    return res.status(500).json({ error: err.message, api_version: "v2" });
+  }
+});
+
+app.post("/api/v2/graph/build", (req, res) => {
+  setCorsHeaders(res);
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const graph = buildGraph(PROJECT_ROOT, { force: true });
+    return res.json({
+      success: true,
+      stats: graph.stats,
+      builtAt: graph.builtAt,
+      api_version: "v2",
+    });
+  } catch (err) {
+    return res.status(500).json({ error: err.message, api_version: "v2" });
+  }
+});
+
+app.get("/api/v2/graph/blast-radius", (req, res) => {
+  setCorsHeaders(res);
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const file = req.query?.file;
+    if (!file) {
+      return res.status(400).json({ error: "Missing 'file' query parameter", api_version: "v2" });
+    }
+
+    const result = getBlastRadius(PROJECT_ROOT, file);
+    return res.json({ ...result, api_version: "v2" });
+  } catch (err) {
+    return res.status(500).json({ error: err.message, api_version: "v2" });
+  }
+});
+
+app.get("/api/v2/graph/lock-map", (req, res) => {
+  setCorsHeaders(res);
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const mappings = mapLocksToFiles(PROJECT_ROOT);
+    return res.json({ mappings, count: mappings.length, api_version: "v2" });
+  } catch (err) {
+    return res.status(500).json({ error: err.message, api_version: "v2" });
+  }
+});
+
 // ========================================
 // SSO ENDPOINTS (v3.5)
 // ========================================
@@ -962,5 +1549,7 @@ app.post("/auth/sso/logout", (req, res) => {
 const PORT = parseInt(process.env.PORT || "3000", 10);
 app.listen(PORT, "0.0.0.0", () => {
   console.log(`SpecLock MCP HTTP Server v${VERSION} running on port ${PORT} — Developed by ${AUTHOR}`);
-  console.log(`  Dashboard: http://localhost:${PORT}/dashboard`);
+  console.log(`  Dashboard:    http://localhost:${PORT}/dashboard`);
+  console.log(`  REST API v2:  http://localhost:${PORT}/api/v2/status`);
+  console.log(`  SSE Stream:   http://localhost:${PORT}/api/v2/stream`);
 });