sparda-mcp 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Turn any codebase into an MCP server with one command. Express & FastAPI → Claude-ready in 3 minutes.",
   "type": "module",
   "bin": {

package/src/generator/express.js

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { parse } from '@babel/parser';
 import { toolNameFor } from '../parser/express.js';
-import { carryOverManifest } from './manifest.js';
+import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const MARK_START = '// >>> sparda-injection (do not edit this block) >>>';
@@ -28,6 +28,28 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
   }
   const prev = carryOverManifest(cwd, tools);
 
+  // --- sparding safety memory & fingerprints
+  const sparding = defaultSpardingMemory(prev);
+  const oldFingerprints = sparding.toolFingerprints ?? {};
+  const newFingerprints = {};
+  for (const [name, t] of Object.entries(tools)) {
+    const raw = `${t.method}|${t.path}|${JSON.stringify(t.params)}`;
+    const fp = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 8);
+    newFingerprints[name] = fp;
+    const oldFp = oldFingerprints[name];
+    if (oldFp && oldFp !== fp) {
+      sparding.events.push({
+        ts: new Date().toISOString(),
+        tool: name,
+        decision: 'audit',
+        risk: 'medium',
+        reasons: [`route structure modified (fingerprint changed from ${oldFp} to ${fp})`],
+      });
+      if (sparding.events.length > 100) sparding.events.shift();
+    }
+  }
+  sparding.toolFingerprints = newFingerprints;
+
   // stable across re-runs so a running bridge/host pair never desyncs
   const localKey = prev?.localKey ?? crypto.randomUUID();
   const entryAbs = path.resolve(cwd, entryFile);
@@ -61,6 +83,7 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
 
   tpl = tpl
     .replace('__IMPORT_LINE__', importLine)
+    .replace('__SPARDING_POLICIES__', JSON.stringify(sparding.policies ?? {}))
     .replace('__ROUTER_DECL__', isESM
       ? 'export const spardaRouter = express.Router();'
       : 'const spardaRouter = express.Router();\nmodule.exports = { spardaRouter };')
@@ -98,6 +121,7 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     ...(prev?.semantic ? { semantic: prev.semantic } : {}),
     ...(prev?.immune ? { immune: prev.immune } : {}),
     ...(prev?.labs ? { labs: prev.labs } : {}),
+    sparding,
   };
   atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
 

package/src/generator/fastapi.js

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { toolNameFor } from '../parser/express.js';
-import { carryOverManifest } from './manifest.js';
+import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const MARK_START = '# >>> sparda-injection (do not edit this block) >>>';
@@ -28,6 +28,28 @@ export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, py
   }
   const prev = carryOverManifest(cwd, tools);
 
+  // --- sparding safety memory & fingerprints
+  const sparding = defaultSpardingMemory(prev);
+  const oldFingerprints = sparding.toolFingerprints ?? {};
+  const newFingerprints = {};
+  for (const [name, t] of Object.entries(tools)) {
+    const raw = `${t.method}|${t.path}|${JSON.stringify(t.params)}`;
+    const fp = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 8);
+    newFingerprints[name] = fp;
+    const oldFp = oldFingerprints[name];
+    if (oldFp && oldFp !== fp) {
+      sparding.events.push({
+        ts: new Date().toISOString(),
+        tool: name,
+        decision: 'audit',
+        risk: 'medium',
+        reasons: [`route structure modified (fingerprint changed from ${oldFp} to ${fp})`],
+      });
+      if (sparding.events.length > 100) sparding.events.shift();
+    }
+  }
+  sparding.toolFingerprints = newFingerprints;
+
   // stable across re-runs so a running bridge/host pair never desyncs
   const localKey = prev?.localKey ?? crypto.randomUUID();
   const entryAbs = path.resolve(cwd, entryFile);
@@ -41,6 +63,7 @@ export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, py
     // double-stringify: a JSON string literal is also a valid Python string literal,
     // and json.loads() in the template turns it into real Python values (E-009)
     .replace('__TOOLS_JSON__', JSON.stringify(JSON.stringify(tools)))
+    .replace('__SPARDING_POLICIES__', JSON.stringify(JSON.stringify(sparding.policies ?? {})))
     .replace('__LOCAL_KEY__', localKey)
     .replace('__PORT__', String(port));
 
@@ -67,6 +90,7 @@ export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, py
     ...(prev?.semantic ? { semantic: prev.semantic } : {}),
     ...(prev?.immune ? { immune: prev.immune } : {}),
     ...(prev?.labs ? { labs: prev.labs } : {}),
+    sparding,
   };
 
   atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');

package/src/generator/manifest.js

@@ -4,9 +4,9 @@ import path from 'node:path';
 
 // Re-running init must not wipe what the user (or the semantic/immune/Labs
 // passes) wrote into sparda.json: per-tool `enabled` overrides, the cached
-// `semantic` enrichment, the `immune` memory (antibodies) and the `labs`
-// state (opt-in flags + observed circuits) survive as long as the tool's
-// method+path are unchanged.
+// `semantic` enrichment, the `immune` memory (antibodies), the `labs`
+// state (opt-in flags + observed circuits), and the `sparding` security
+// memory survive as long as the tool's method+path are unchanged.
 export function carryOverManifest(cwd, tools) {
   let prev = null;
   try {
@@ -22,3 +22,18 @@ export function carryOverManifest(cwd, tools) {
   }
   return prev;
 }
+
+export function defaultSpardingMemory(prev) {
+  return prev?.sparding ?? {
+    version: 1,
+    policies: {
+      reads: 'allow',
+      writes: 'require_human',
+      deletes: 'block',
+      requireProofAfterWrite: true,
+    },
+    events: [],
+    failures: {},
+    toolFingerprints: {},
+  };
+}

package/src/parser/express.js

@@ -110,7 +110,7 @@ export function parseExpressProject(cwd, entryFile) {
         }
 
         const fullPath = joinPath(prefix, pathArg.value);
-        if (fullPath.startsWith('/mcp')) {
+        if (fullPath === '/mcp' || fullPath.startsWith('/mcp/')) {
           skipped.push({ reason: `self-referential path ${fullPath} blocked`, file: rel(absFile), line: p.node.loc?.start.line });
           return;
         }

package/src/parser/fastapi_extract.py

@@ -27,6 +27,77 @@ class RouteSpecExtractor:
         lines = [line.strip() for line in doc.splitlines()]
         return " ".join([l for l in lines[:3] if l]).strip()
 
+    def _is_depends(self, default_node):
+        """Returns True if the default value is a Depends(...) call."""
+        return (
+            isinstance(default_node, ast.Call) and
+            ((isinstance(default_node.func, ast.Name) and default_node.func.id == 'Depends') or
+             (isinstance(default_node.func, ast.Attribute) and default_node.func.attr == 'Depends'))
+        )
+
+    def _collect_all_imports(self, start_file):
+        to_visit = [start_file]
+        collected = set()
+        visited_imports = set()
+        
+        while to_visit:
+            curr = to_visit.pop(0)
+            if curr in visited_imports:
+                continue
+            visited_imports.add(curr)
+            
+            if not os.path.exists(curr):
+                continue
+            
+            try:
+                with open(curr, 'r', encoding='utf-8') as f:
+                    src = f.read()
+                tree = ast.parse(src, filename=curr)
+            except:
+                continue
+                
+            for node in ast.walk(tree):
+                resolved = None
+                if isinstance(node, ast.ImportFrom):
+                    dots = '.' * node.level if node.level > 0 else ''
+                    module_with_dots = f"{dots}{node.module}" if node.module else dots
+                    
+                    for name_node in node.names:
+                        if node.module:
+                            full_mod = f"{module_with_dots}.{name_node.name}"
+                        else:
+                            full_mod = f"{module_with_dots}{name_node.name}"
+                        resolved = self.resolve_import(curr, full_mod)
+                        if resolved and resolved not in collected:
+                            collected.add(resolved)
+                            to_visit.append(resolved)
+                    
+                    resolved = self.resolve_import(curr, module_with_dots)
+                    if resolved and resolved not in collected:
+                        collected.add(resolved)
+                        to_visit.append(resolved)
+                        
+                elif isinstance(node, ast.Import):
+                    for name_node in node.names:
+                        resolved = self.resolve_import(curr, name_node.name)
+                        if resolved and resolved not in collected:
+                            collected.add(resolved)
+                            to_visit.append(resolved)
+                            
+        return collected
+
+    def preload_models(self):
+        """Pre-scan all reachable files for Pydantic models before route extraction."""
+        for abs_path in self._collect_all_imports(self.entry_file):
+            if abs_path not in self.models:
+                try:
+                    with open(abs_path, 'r', encoding='utf-8') as f:
+                        src = f.read()
+                    tree = ast.parse(src, filename=abs_path)
+                    self.extract_pydantic_models(tree, abs_path)
+                except:
+                    pass
+
     def resolve_import(self, from_file, module_name):
         if not module_name:
             return None
@@ -176,10 +247,22 @@ class RouteSpecExtractor:
         for node in tree.body:
             # from x import y
             if isinstance(node, ast.ImportFrom):
-                resolved = self.resolve_import(abs_file, node.module)
-                if resolved:
-                    for name_node in node.names:
-                        local_name = name_node.asname or name_node.name
+                dots = '.' * node.level if node.level > 0 else ''
+                module_with_dots = f"{dots}{node.module}" if node.module else dots
+                
+                for name_node in node.names:
+                    local_name = name_node.asname or name_node.name
+                    
+                    if node.module:
+                        full_mod = f"{module_with_dots}.{name_node.name}"
+                    else:
+                        full_mod = f"{module_with_dots}{name_node.name}"
+                        
+                    resolved = self.resolve_import(abs_file, full_mod)
+                    if not resolved:
+                        resolved = self.resolve_import(abs_file, module_with_dots)
+                        
+                    if resolved:
                         import_map[local_name] = resolved
 
             # import x
@@ -221,36 +304,46 @@ class RouteSpecExtractor:
             if isinstance(node, ast.Expr) and isinstance(node.value, ast.Call):
                 call = node.value
                 if isinstance(call.func, ast.Attribute) and call.func.attr == 'include_router':
-                    # First arg is the router variable
-                    if len(call.args) >= 1 and isinstance(call.args[0], ast.Name):
-                        router_name = call.args[0].id
-                        mount_prefix = ""
-                        for kw in call.keywords:
-                            if kw.arg == 'prefix':
-                                val = self.get_lit_value(kw.value)
-                                if val is not None:
-                                    mount_prefix = val
-                        
-                        resolved_file = import_map.get(router_name)
-                        # Reconstruct cumulative prefix
-                        # parent prefix + mount prefix
-                        cum_prefix = (prefix + mount_prefix).replace('//', '/')
-                        if resolved_file:
-                            self.mounts.append((cum_prefix, resolved_file, router_name))
-                        else:
-                            # If it's a locally defined router
-                            if router_name in router_vars:
-                                local_r_prefix = router_prefixes.get(router_name, "")
-                                self.mounts.append((cum_prefix + local_r_prefix, abs_file, router_name))
+                    # First arg is the router variable (can be ast.Name or ast.Attribute like users.router)
+                    if len(call.args) >= 1:
+                        arg0 = call.args[0]
+                        router_name = None
+                        is_attribute = False
+                        if isinstance(arg0, ast.Name):
+                            router_name = arg0.id
+                        elif isinstance(arg0, ast.Attribute) and isinstance(arg0.value, ast.Name):
+                            router_name = arg0.value.id
+                            is_attribute = True
+                            
+                        if router_name:
+                            mount_prefix = ""
+                            for kw in call.keywords:
+                                if kw.arg == 'prefix':
+                                    val = self.get_lit_value(kw.value)
+                                    if val is not None:
+                                        mount_prefix = val
+                            
+                            resolved_file = import_map.get(router_name)
+                            # Reconstruct cumulative prefix
+                            # parent prefix + mount prefix
+                            cum_prefix = (prefix + mount_prefix).replace('//', '/')
+                            if resolved_file:
+                                # If it was users.router, we mount the resolved file with the module's router name
+                                self.mounts.append((cum_prefix, resolved_file, router_name))
                             else:
-                                self.skipped.append({
-                                    'reason': f"Router '{router_name}' source file not resolved",
-                                    'file': self.get_rel_path(abs_file),
-                                    'line': node.lineno
-                                })
+                                # If it's a locally defined router
+                                if not is_attribute and router_name in router_vars:
+                                    local_r_prefix = router_prefixes.get(router_name, "")
+                                    self.mounts.append((cum_prefix + local_r_prefix, abs_file, router_name))
+                                else:
+                                    self.skipped.append({
+                                        'reason': f"Router '{router_name}' source file not resolved",
+                                        'file': self.get_rel_path(abs_file),
+                                        'line': node.lineno
+                                    })
 
             # FunctionDef decorated with app/router decorators
-            elif isinstance(node, ast.FunctionDef):
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                 for dec in node.decorator_list:
                     if isinstance(dec, ast.Call) and isinstance(dec.func, ast.Attribute):
                         obj_node = dec.func.value
@@ -283,7 +376,7 @@ class RouteSpecExtractor:
                                         full_path = '/' + full_path
 
                                     # Anti-loop skip
-                                    if full_path.startswith('/mcp'):
+                                    if full_path == '/mcp' or full_path.startswith('/mcp/'):
                                         self.skipped.append({
                                             'reason': f"self-referential path {full_path} blocked",
                                             'file': self.get_rel_path(abs_file),
@@ -327,6 +420,10 @@ class RouteSpecExtractor:
                                             
                                         # Check if it has a default value
                                         has_default = idx >= defaults_start_idx
+                                        if has_default:
+                                            default_val = node.args.defaults[idx - defaults_start_idx]
+                                            if self._is_depends(default_val):
+                                                continue
                                         
                                         # Parse type annotation
                                         arg_type, type_req = self.parse_type_annotation(arg.annotation)
@@ -403,6 +500,9 @@ class RouteSpecExtractor:
             self.entry_app_vars = list(app_vars)
 
     def run(self):
+        # Pre-load Pydantic models from all imported files
+        self.preload_models()
+        
         # 1st pass: parse entry file
         self.parse_file(self.entry_file, '', 0)
 

package/src/server/stdio.js

@@ -44,7 +44,7 @@ export async function startStdioBridge({ cwd, portOverride }) {
   const disabled = () => Object.entries(toolSpecs).filter(([, t]) => !t.enabled);
 
   const server = new Server(
-    { name: `sparda-${path.basename(cwd)}`, version: '0.4.0' },
+    { name: `sparda-${path.basename(cwd)}`, version: '0.5.0' },
     { capabilities: { tools: { listChanged: true }, prompts: { listChanged: true }, logging: {} } },
   );
 
@@ -229,6 +229,7 @@ export async function startStdioBridge({ cwd, portOverride }) {
             lifetime: { antibodyHits, tokensAvoidedEst: antibodyHits * DIAGNOSIS_TOKENS },
           },
         },
+        sparding: manifest.sparding ?? {},
         labs: { recordSequences: Boolean(recorder), compositeTools: [...composites.keys()], circuits: manifest.labs?.circuits ?? {} },
         hint: 'runtime.quarantine lists tools temporarily blocked by the immune system (503 until cooldown). immuneMemory maps failure signatures (source|tool|status) to cached diagnoses — same failure later costs zero tokens. recycling measures how much compute/intelligence was served from SPARDA\'s own memory instead of being paid again. runtime.purity classifies each route by observation: pure = same args keep returning the same response (recyclable), volatile = it changed, erasing = writes. labs.circuits are observed call sequences where one tool\'s output fed the next one\'s input.',
       }, null, 2));
@@ -265,15 +266,39 @@ export async function startStdioBridge({ cwd, portOverride }) {
         },
       }).catch(() => null);
       if (!answer || answer.action !== 'accept' || answer.content?.confirm !== true) {
+        const mockProof = {
+          version: 'sparding-proof/v0.1',
+          risk: 'blocked',
+          decision: 'block',
+          reasons: ['Write declined by user'],
+        };
+        recordSparding(manifestPath, manifest, name, mockProof);
         return { content: [{ type: 'text', text: `Write declined by user: ${spec.method} ${spec.path} was NOT executed.` }], isError: true };
       }
     }
 
     const payload = await invoke(base, key, name, args);
     if (payload === null) {
+      const mockProof = {
+        version: 'sparding-proof/v0.1',
+        risk: 'blocked',
+        decision: 'block',
+        reasons: ['Host app error or unreachable'],
+      };
+      recordSparding(manifestPath, manifest, name, mockProof);
       return { content: [{ type: 'text', text: `Host app error. Check that your server is still running on :${port}.` }], isError: true };
     }
 
+    const proofForRecord = payload.spardingProof ? { ...payload.spardingProof } : { version: 'sparding-proof/v0.1', decision: 'allow', risk: 'low', reasons: [] };
+    if (payload.upstreamStatus !== undefined && payload.upstreamStatus >= 400) {
+      proofForRecord.isExecutionError = true;
+      proofForRecord.reasons = [...(proofForRecord.reasons || []), `upstream error status ${payload.upstreamStatus}`];
+    } else if (payload.error) {
+      proofForRecord.isExecutionError = true;
+      proofForRecord.reasons = [...(proofForRecord.reasons || []), `invocation error: ${payload.error}`];
+    }
+    recordSparding(manifestPath, manifest, name, proofForRecord);
+
     // condenser tap (Labs): only AI-driven calls that succeeded feed the current —
     // internal read-backs and failures are not workflow steps
     if (recorder && payload.upstreamStatus !== undefined && payload.upstreamStatus < 400) {
@@ -415,6 +440,66 @@ function persistImmune(manifestPath, manifest) {
   } catch { /* disk briefly unavailable — the antibody stays in memory */ }
 }
 
+function recordSparding(manifestPath, manifest, tool, proof) {
+  try {
+    manifest.sparding ??= { version: 1, policies: {}, events: [], failures: {}, toolFingerprints: {} };
+    manifest.sparding.events ??= [];
+    manifest.sparding.failures ??= {};
+
+    const event = {
+      ts: new Date().toISOString(),
+      tool,
+      decision: proof.decision,
+      risk: proof.risk,
+      reasons: proof.reasons || [],
+    };
+    manifest.sparding.events.push(event);
+    if (manifest.sparding.events.length > 100) {
+      manifest.sparding.events.shift();
+    }
+
+    const isBlock = proof.decision === 'block';
+    const isError = proof.isExecutionError;
+    if (isBlock || isError) {
+      const reasonCode = proof.reasons && proof.reasons[0] ? proof.reasons[0].replace(/\s+/g, '_').toLowerCase() : 'unknown_error';
+      const sig = `${tool}|${reasonCode}`;
+      const prevFail = manifest.sparding.failures[sig] || { count: 0, lesson: '' };
+      
+      let lesson = `Execution failed for tool: ${tool}.`;
+      if (reasonCode.includes('quarantined')) {
+        lesson = `Tool ${tool} was quarantined due to repeated failures.`;
+      } else if (reasonCode.includes('disabled')) {
+        lesson = `Tool ${tool} is disabled by write-safety policies.`;
+      } else if (reasonCode.includes('missing_path_param') || reasonCode.includes('missing_path')) {
+        lesson = `Client omitted a required path parameter on route ${tool}.`;
+      } else if (reasonCode.includes('declined')) {
+        lesson = `Human user declined confirmation for write tool ${tool}.`;
+      } else if (reasonCode.includes('policy_blocks')) {
+        lesson = `Security policies blocked the execution of ${tool}.`;
+      } else if (reasonCode.includes('upstream')) {
+        lesson = `Host application returned an error status code on route ${tool}.`;
+      }
+
+      manifest.sparding.failures[sig] = {
+        count: prevFail.count + 1,
+        lastSeen: new Date().toISOString(),
+        lesson,
+      };
+    }
+    persistSparding(manifestPath, manifest);
+  } catch (err) {
+    console.error(`[sparda] failed to record sparding proof: ${err.message}`);
+  }
+}
+
+function persistSparding(manifestPath, manifest) {
+  try {
+    const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    onDisk.sparding = manifest.sparding;
+    fs.writeFileSync(manifestPath, JSON.stringify(onDisk, null, 2) + '\n');
+  } catch { /* disk briefly unavailable */ }
+}
+
 function persistLabs(manifestPath, manifest) {
   try {
     const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

package/templates/express-router.txt

@@ -5,6 +5,7 @@
 __IMPORT_LINE__
 
 const SPARDA_TOOLS = __TOOLS_JSON__;
+const SPARDA_POLICIES = __SPARDING_POLICIES__;
 
 const SPARDA_LOCAL_KEY = "__LOCAL_KEY__";
 const SPARDA_PORT = __PORT__;
@@ -61,6 +62,134 @@ function spardaEvent(source__ANY_TYPE__, tool__ANY_TYPE__, status__ANY_TYPE__, m
 // observe-only: uncaughtExceptionMonitor never changes the host app's crash behavior
 process.on('uncaughtExceptionMonitor', (err__ANY_TYPE__) => spardaEvent('process', null, null, err && err.message ? err.message : err));
 
+function spardaProof(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE__) {
+  const checks = {
+    knownTool: spec !== undefined,
+    enabled: spec ? spec.enabled : false,
+    loopSafe: spec ? !spec.path.startsWith('/mcp') : false,
+    methodClass: spec ? (spec.method === 'GET' ? 'read' : 'write') : 'read',
+    pathParamsPresent: true,
+    hasBodyForWrite: true,
+    reversibleHint: false,
+    quarantineSafe: true,
+  };
+
+  const reasons = [];
+
+  if (!checks.knownTool) {
+    reasons.push('unknown tool');
+    return {
+      version: 'sparding-proof/v0.1',
+      risk: 'blocked',
+      decision: 'block',
+      reasons,
+      checks,
+    };
+  }
+
+  if (!checks.enabled) {
+    reasons.push('tool disabled (write-safety)');
+  }
+  if (!checks.loopSafe) {
+    reasons.push('self-referential tool blocked (loop protection)');
+  }
+
+  const quarantined = SPARDA_QUARANTINE[tool];
+  if (quarantined) {
+    if (Date.now() < quarantined.until) {
+      checks.quarantineSafe = false;
+      reasons.push(`tool quarantined (immune system): ${quarantined.reason}`);
+    } else {
+      delete SPARDA_QUARANTINE[tool];
+      if (SPARDA_STATS[tool]) SPARDA_STATS[tool].consecutive5xx = 2;
+    }
+  }
+
+  for (const name of spec.pathParams ?? []) {
+    if (args[name] === undefined) {
+      checks.pathParamsPresent = false;
+      reasons.push(`missing path param: ${name}`);
+    }
+  }
+
+  if (checks.methodClass === 'write') {
+    if (args.body === undefined) {
+      checks.hasBodyForWrite = false;
+    }
+  }
+
+  if (spec.method === 'GET') {
+    checks.reversibleHint = true;
+  } else {
+    checks.reversibleHint = Object.values(SPARDA_TOOLS).some((t__ANY_TYPE__) => t.method === 'GET' && t.path === spec.path);
+  }
+
+  let risk = 'low';
+  let decision = 'allow';
+
+  if (!checks.enabled || !checks.loopSafe || !checks.quarantineSafe || !checks.pathParamsPresent) {
+    decision = 'block';
+    risk = 'blocked';
+    return {
+      version: 'sparding-proof/v0.1',
+      risk,
+      decision,
+      reasons,
+      checks,
+    };
+  }
+
+  const policies = SPARDA_POLICIES ?? {};
+  if (checks.methodClass === 'read') {
+    const readPolicy = policies.reads ?? 'allow';
+    if (readPolicy === 'block') {
+      decision = 'block';
+      risk = 'blocked';
+      reasons.push('read policy blocks execution');
+    } else if (readPolicy === 'require_human') {
+      decision = 'require_human';
+      risk = 'medium';
+      reasons.push('read policy requires human confirmation');
+    }
+  } else {
+    const isDelete = spec.method === 'DELETE';
+    const deletePolicy = policies.deletes ?? 'block';
+    const writePolicy = policies.writes ?? 'require_human';
+
+    if (isDelete && deletePolicy === 'block') {
+      decision = 'block';
+      risk = 'blocked';
+      reasons.push('delete policy blocks execution');
+    } else if (isDelete && deletePolicy === 'require_human') {
+      decision = 'require_human';
+      risk = 'high';
+      reasons.push('delete operation requires human confirmation');
+    } else if (isDelete && deletePolicy === 'allow') {
+      decision = 'allow';
+      risk = 'low';
+    } else if (writePolicy === 'block') {
+      decision = 'block';
+      risk = 'blocked';
+      reasons.push('write policy blocks execution');
+    } else if (writePolicy === 'require_human') {
+      decision = 'require_human';
+      risk = 'medium';
+      reasons.push('write operation requires human confirmation');
+    } else {
+      decision = 'allow';
+      risk = 'low';
+    }
+  }
+
+  return {
+    version: 'sparding-proof/v0.1',
+    risk,
+    decision,
+    reasons,
+    checks,
+  };
+}
+
 __ROUTER_DECL__
 
 spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) => {
@@ -83,27 +212,46 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE_
   const { tool, args = {} } = req.body ?? {};
   const t0 = Date.now();
   const spec = SPARDA_TOOLS[tool];
-  if (!spec) return res.status(404).json({ error: `unknown tool: ${tool}` });
-  if (!spec.enabled) {
-    return res.status(403).json({ error: `tool disabled (write-safety): ${tool}`, hint: 'Enable it in sparda.json, then re-run: npx sparda-mcp init' });
-  }
-  if (spec.path.startsWith('/mcp')) {
-    return res.status(400).json({ error: 'self-referential tool blocked (loop protection)' });
-  }
-  const quarantined = SPARDA_QUARANTINE[tool];
-  if (quarantined) {
-    if (Date.now() < quarantined.until) {
-      SPARDA_RECYCLE.servedByCircle += 1; // answered from immune memory — the doomed host call was never paid
-      return res.status(503).json({ error: `tool quarantined (immune system): ${tool}`, reason: quarantined.reason, retryInMs: quarantined.until - Date.now() });
+
+  const proof = spardaProof(tool, spec, args);
+
+  if (proof.decision === 'block') {
+    let status = 400;
+    let error = 'bad request';
+    if (!proof.checks.knownTool) {
+      status = 404;
+      error = `unknown tool: ${tool}`;
+    } else if (!proof.checks.enabled) {
+      status = 403;
+      error = `tool disabled (write-safety): ${tool}`;
+      return res.status(status).json({ error, hint: 'Enable it in sparda.json, then re-run: npx sparda-mcp init', spardingProof: proof });
+    } else if (!proof.checks.loopSafe) {
+      status = 400;
+      error = 'self-referential tool blocked (loop protection)';
+    } else if (!proof.checks.quarantineSafe) {
+      status = 503;
+      const quarantined = SPARDA_QUARANTINE[tool];
+      error = `tool quarantined (immune system): ${tool}`;
+      SPARDA_RECYCLE.servedByCircle += 1;
+      return res.status(status).json({
+        error,
+        reason: quarantined ? quarantined.reason : '',
+        retryInMs: quarantined ? Math.max(0, quarantined.until - Date.now()) : 0,
+        spardingProof: proof
+      });
+    } else {
+      status = 400;
+      error = proof.reasons[0] || 'blocked';
+      if (proof.reasons.some((r__ANY_TYPE__) => r.includes('policy blocks execution'))) {
+        status = 403;
+      }
     }
-    // half-open: cooldown elapsed — allow one probe; a single new 5xx re-quarantines
-    delete SPARDA_QUARANTINE[tool];
-    if (SPARDA_STATS[tool]) SPARDA_STATS[tool].consecutive5xx = 2;
+    return res.status(status).json({ error, spardingProof: proof });
   }
+
   try {
     let url = spec.path.replace(/:(\w+)/g, (_, name) => {
       const v = args[name];
-      if (v === undefined) throw Object.assign(new Error(`missing path param: ${name}`), { status: 400 });
       return encodeURIComponent(String(v));
     });
     const query = [];
@@ -128,11 +276,11 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE_
       spardaObservePurity(tool, JSON.stringify(Object.entries(args).filter((e__ANY_TYPE__) => e[1] !== undefined).sort()), text);
     }
     if (upstream.status >= 500) spardaEvent('invoke', tool, upstream.status, text.slice(0, 200));
-    return res.status(200).json({ upstreamStatus: upstream.status, data });
+    return res.status(200).json({ upstreamStatus: upstream.status, data, spardingProof: proof });
   } catch (err__ANY_TYPE__) {
     spardaRecord(tool, err.status ?? 502, Date.now() - t0);
     spardaEvent('invoke', tool, err.status ?? 502, err.message);
-    return res.status(err.status ?? 502).json({ error: err.message });
+    return res.status(err.status ?? 502).json({ error: err.message, spardingProof: proof });
   }
 });
 

package/templates/fastapi-router.txt

@@ -17,6 +17,7 @@ import zlib
 
 # json.loads, not a Python literal: JSON true/false/null are not valid Python (E-009)
 SPARDA_TOOLS = json.loads(__TOOLS_JSON__)
+SPARDA_POLICIES = json.loads(__SPARDING_POLICIES__)
 SPARDA_LOCAL_KEY = "__LOCAL_KEY__"
 SPARDA_PORT = __PORT__
 
@@ -110,6 +111,120 @@ def sparda_record(tool, status, ms):
         }
         sparda_event("immune", tool, 503, f"quarantined after {st['consecutive5xx']} consecutive 5xx (cooldown {SPARDA_QUARANTINE_MS}ms)")
 
+def sparda_proof(tool, spec, args):
+    checks = {
+        "knownTool": spec is not None,
+        "enabled": spec.get("enabled", False) if spec else False,
+        "loopSafe": not spec.get("path", "").startswith("/mcp") if spec else False,
+        "methodClass": "read" if spec and spec.get("method") == "GET" else "write",
+        "pathParamsPresent": True,
+        "hasBodyForWrite": True,
+        "reversibleHint": False,
+        "quarantineSafe": True,
+    }
+
+    reasons = []
+
+    if not checks["knownTool"]:
+        reasons.append("unknown tool")
+        return {
+            "version": "sparding-proof/v0.1",
+            "risk": "blocked",
+            "decision": "block",
+            "reasons": reasons,
+            "checks": checks,
+        }
+
+    if not checks["enabled"]:
+        reasons.append("tool disabled (write-safety)")
+    if not checks["loopSafe"]:
+        reasons.append("self-referential tool blocked (loop protection)")
+
+    quarantined = SPARDA_QUARANTINE.get(tool)
+    if quarantined:
+        if (time.time() * 1000) < quarantined["until"]:
+            checks["quarantineSafe"] = False
+            reasons.append(f"tool quarantined (immune system): {quarantined['reason']}")
+        else:
+            del SPARDA_QUARANTINE[tool]
+            if tool in SPARDA_STATS:
+                SPARDA_STATS[tool]["consecutive5xx"] = 2
+
+    for name in spec.get("pathParams", []):
+        if args.get(name) is None:
+            checks["pathParamsPresent"] = False
+            reasons.append(f"missing path param: {name}")
+
+    if checks["methodClass"] == "write":
+        if args.get("body") is None:
+            checks["hasBodyForWrite"] = False
+
+    if spec.get("method") == "GET":
+        checks["reversibleHint"] = True
+    else:
+        checks["reversibleHint"] = any(t.get("method") == "GET" and t.get("path") == spec.get("path") for t in SPARDA_TOOLS.values())
+
+    risk = "low"
+    decision = "allow"
+
+    if not checks["enabled"] or not checks["loopSafe"] or not checks["quarantineSafe"] or not checks["pathParamsPresent"]:
+        decision = "block"
+        risk = "blocked"
+        return {
+            "version": "sparding-proof/v0.1",
+            "risk": risk,
+            "decision": decision,
+            "reasons": reasons,
+            "checks": checks,
+        }
+
+    policies = SPARDA_POLICIES or {}
+    if checks["methodClass"] == "read":
+        read_policy = policies.get("reads", "allow")
+        if read_policy == "block":
+            decision = "block"
+            risk = "blocked"
+            reasons.append("read policy blocks execution")
+        elif read_policy == "require_human":
+            decision = "require_human"
+            risk = "medium"
+            reasons.append("read policy requires human confirmation")
+    else:
+        is_delete = spec.get("method") == "DELETE"
+        delete_policy = policies.get("deletes", "block")
+        write_policy = policies.get("writes", "require_human")
+
+        if is_delete and delete_policy == "block":
+            decision = "block"
+            risk = "blocked"
+            reasons.append("delete policy blocks execution")
+        elif is_delete and delete_policy == "require_human":
+            decision = "require_human"
+            risk = "high"
+            reasons.append("delete operation requires human confirmation")
+        elif is_delete and delete_policy == "allow":
+            decision = "allow"
+            risk = "low"
+        elif write_policy == "block":
+            decision = "block"
+            risk = "blocked"
+            reasons.append("write policy blocks execution")
+        elif write_policy == "require_human":
+            decision = "require_human"
+            risk = "medium"
+            reasons.append("write operation requires human confirmation")
+        else:
+            decision = "allow"
+            risk = "low"
+
+    return {
+        "version": "sparding-proof/v0.1",
+        "risk": risk,
+        "decision": decision,
+        "reasons": reasons,
+        "checks": checks,
+    }
+
 sparda_router = APIRouter()
 executor = concurrent.futures.ThreadPoolExecutor(max_workers=10)
 
@@ -162,43 +277,51 @@ async def invoke_tool(request: Request):
     args = body.get("args", {})
     
     spec = SPARDA_TOOLS.get(tool)
-    if not spec:
-        return JSONResponse(status_code=404, content={"error": f"unknown tool: {tool}"})
+    proof = sparda_proof(tool, spec, args)
 
-    if not spec.get("enabled"):
-        return JSONResponse(status_code=403, content={
-            "error": f"tool disabled (write-safety): {tool}",
-            "hint": "Enable it in sparda.json, then re-run: npx sparda-mcp init"
-        })
-
-    path = spec.get("path")
-    if path.startswith("/mcp"):
-        return JSONResponse(status_code=400, content={"error": "self-referential tool blocked (loop protection)"})
-
-    quarantined = SPARDA_QUARANTINE.get(tool)
-    if quarantined:
-        now_ms = time.time() * 1000
-        if now_ms < quarantined["until"]:
-            SPARDA_RECYCLE["servedByCircle"] += 1  # answered from immune memory — the doomed host call was never paid
-            return JSONResponse(status_code=503, content={
-                "error": f"tool quarantined (immune system): {tool}",
-                "reason": quarantined["reason"],
-                "retryInMs": round(quarantined["until"] - now_ms),
+    if proof["decision"] == "block":
+        status = 400
+        error = "bad request"
+        if not proof["checks"]["knownTool"]:
+            status = 404
+            error = f"unknown tool: {tool}"
+        elif not proof["checks"]["enabled"]:
+            status = 403
+            error = f"tool disabled (write-safety): {tool}"
+            return JSONResponse(status_code=status, content={
+                "error": error,
+                "hint": "Enable it in sparda.json, then re-run: npx sparda-mcp init",
+                "spardingProof": proof
+            })
+        elif not proof["checks"]["loopSafe"]:
+            status = 400
+            error = "self-referential tool blocked (loop protection)"
+        elif not proof["checks"]["quarantineSafe"]:
+            status = 503
+            quarantined = SPARDA_QUARANTINE.get(tool)
+            error = f"tool quarantined (immune system): {tool}"
+            SPARDA_RECYCLE["servedByCircle"] += 1
+            return JSONResponse(status_code=status, content={
+                "error": error,
+                "reason": quarantined["reason"] if quarantined else "",
+                "retryInMs": round(quarantined["until"] - time.time() * 1000) if quarantined else 0,
+                "spardingProof": proof
             })
-        # half-open: cooldown elapsed — allow one probe; a single new 5xx re-quarantines
-        del SPARDA_QUARANTINE[tool]
-        if tool in SPARDA_STATS:
-            SPARDA_STATS[tool]["consecutive5xx"] = 2
+        else:
+            status = 400
+            error = proof["reasons"][0] if proof["reasons"] else "blocked"
+            if any("policy blocks execution" in r for r in proof["reasons"]):
+                status = 403
+        return JSONResponse(status_code=status, content={"error": error, "spardingProof": proof})
 
     t0 = time.time()
     try:
         path_params = spec.get("pathParams", [])
+        path = spec.get("path")
 
         def repl(match):
             name = match.group(1)
             val = args.get(name)
-            if val is None:
-                raise HTTPException(status_code=400, detail=f"missing path param: {name}")
             return urllib.parse.quote(str(val))
 
         resolved_path = re.sub(r'\{(\w+)\}', repl, path)
@@ -241,12 +364,8 @@ async def invoke_tool(request: Request):
             sparda_observe_purity(tool, argsig, data_bytes)
         if status >= 500:
             sparda_event("invoke", tool, status, text_data[:200])
-        return {"upstreamStatus": status, "data": data}
-    except HTTPException as e:
-        sparda_record(tool, e.status_code, round((time.time() - t0) * 1000))
-        sparda_event("invoke", tool, e.status_code, e.detail)
-        return JSONResponse(status_code=e.status_code, content={"error": e.detail})
+        return {"upstreamStatus": status, "data": data, "spardingProof": proof}
     except Exception as e:
         sparda_record(tool, 502, round((time.time() - t0) * 1000))
         sparda_event("invoke", tool, 502, str(e))
-        return JSONResponse(status_code=502, content={"error": str(e)})
+        return JSONResponse(status_code=502, content={"error": str(e), "spardingProof": proof})