sparda-mcp 0.3.0 → 0.4.0

package/README.md

@@ -45,6 +45,12 @@ Your app learns what "self" looks like — and defends itself:
 - **Immune memory.** Diagnoses are cached as antibodies in `sparda.json` (git-versioned): the same failure later is diagnosed instantly, zero tokens. Your app accumulates antibodies as it lives — cloning the code doesn't clone its immune system.
 - **`sparda_get_context`.** One tool call gives the AI the full living context: tools, workflows, runtime telemetry, quarantine state, immune memory. Every AI session resumes where the last one stopped.
 
+## v0.4 — the recycling economy + first Labs organ
+- **Recycling gauge (zero config).** The router counts calls answered from SPARDA's own knowledge vs calls that paid the host route (`GET /mcp/stats → recycle`), and the bridge counts the sampling calls its cached knowledge avoided. Day 1 it reads 0% — the circle fills with usage. A measure, never a promise.
+- **Idle harvester.** All of SPARDA's internal work (analysis, persistence) runs only when the event loop is quiet, one job per tick. Perceived saturation: zero.
+- **Sequence condenser (Labs, opt-in, default OFF).** Set `"labs": { "recordSequences": true }` in `sparda.json` (or `SPARDA_RECORD_SEQUENCES=1` for one session) and SPARDA observes when one tool's output feeds the next tool's input, recording the *circuit* — structure only (tool names, arg names, counts), never your data. Deterministic, zero LLM.
+- **Crystallization: tools nobody wrote.** A read-only circuit observed 3× is born as a *composite tool*, announced mid-session via `tools/list_changed`: one call runs the whole chain, auto-feeding each linked argument from the previous step's real response. Your AI names it (MCP sampling, sanitized) or a deterministic name ships without any LLM. Write routes are never absorbed — their per-call confirmation stands.
+
 Where this is going: [ROADMAP.md](./ROADMAP.md).
 
 ## v0 supports

package/package.json

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

package/src/commands/hook.js

@@ -27,3 +27,25 @@ export async function runHook(opts) {
   fs.chmodSync(hookPath, 0o755);
   console.error('[sparda] sentinel installed: routes re-sync after every commit (post-commit hook).');
 }
+
+// Uninstall exactly what runHook installed (hard rule #4 applied to .git/hooks):
+// delete the file if we created it whole, strip our exact block if we appended,
+// line-filter as a last resort if the user edited around it. Returns whether
+// anything was removed so `remove` can report it.
+export function removeHook(cwd) {
+  const hookPath = path.join(cwd, '.git', 'hooks', 'post-commit');
+  let content;
+  try { content = fs.readFileSync(hookPath, 'utf8'); } catch { return false; }
+  if (!content.includes(MARKER)) return false;
+  const block = `${MARKER}\nnpx --no-install sparda-mcp sync --quiet || true\n`;
+  if (content === `#!/bin/sh\n${block}`) {
+    fs.rmSync(hookPath);
+    return true;
+  }
+  let out = content.includes(`\n${block}`) ? content.replace(`\n${block}`, '') : content.replace(block, '');
+  if (out.includes(MARKER)) {
+    out = out.split('\n').filter((l) => l !== MARKER && l !== 'npx --no-install sparda-mcp sync --quiet || true').join('\n');
+  }
+  fs.writeFileSync(hookPath, out);
+  return true;
+}

package/src/commands/init.js

@@ -8,13 +8,14 @@ import { parseFastAPIProject } from '../parser/fastapi.js';
 import { sanitizeDescription } from '../security/sanitize.js';
 import { generateExpress } from '../generator/express.js';
 import { generateFastAPI } from '../generator/fastapi.js';
+import { c, gradient, colorizeJson } from '../ui/style.js';
 
 
 const VERSION = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
 
 export async function runInit(opts) {
   const t0 = Date.now();
-  p.intro(`SPARDA v${VERSION}`);
+  p.intro(`${gradient('SPARDA')} ${c.dim(`v${VERSION}`)}`);
 
   const s = p.spinner();
   s.start('Scanning project...');
@@ -25,13 +26,13 @@ export async function runInit(opts) {
     const res = parseExpressProject(opts.cwd, stack.entryFile);
     routes = res.routes;
     skipped = res.skipped;
-    s.stop(`Stack detected: Express (${stack.moduleType.toUpperCase()}) — entry: ${stack.entryFile}, port: ${stack.port}`);
+    s.stop(`Stack detected: ${c.cyan(`Express (${stack.moduleType.toUpperCase()})`)} — entry: ${stack.entryFile}, port: ${stack.port}`);
   } else if (stack.framework === 'fastapi') {
     const res = parseFastAPIProject(opts.cwd, stack.entryFile, stack.pythonCmd);
     routes = res.routes;
     skipped = res.skipped;
     entryAppVars = res.entryAppVars;
-    s.stop(`Stack detected: FastAPI — entry: ${stack.entryFile}, port: ${stack.port}`);
+    s.stop(`Stack detected: ${c.cyan('FastAPI')} — entry: ${stack.entryFile}, port: ${stack.port}`);
   }
 
   if (routes.length === 0) {
@@ -49,9 +50,9 @@ export async function runInit(opts) {
   p.log.info(`${routes.length} routes found — ${high} high confidence, ${routes.length - high} partial`);
 
   const preview = routes.slice(0, 8).map((r) =>
-    `${r.mutating ? '✗' : '✓'} ${r.method.toUpperCase().padEnd(6)} ${r.path}${r.mutating ? '   (disabled: write-safety)' : ''}`
+    `${r.mutating ? c.red('✗') : c.green('✓')} ${r.method.toUpperCase().padEnd(6)} ${r.path}${r.mutating ? c.dim('   (disabled: write-safety)') : ''}`
   ).join('\n');
-  p.note(preview + (routes.length > 8 ? `\n... (+${routes.length - 8} more)` : ''), 'TOOLS TO GENERATE');
+  p.note(preview + (routes.length > 8 ? c.dim(`\n... (+${routes.length - 8} more)`) : ''), 'TOOLS TO GENERATE');
 
   if (flaggedCount) p.log.warn(`${flaggedCount} suspicious docstring(s) purged (prompt-injection defense)`);
   if (skipped.length) p.log.warn(`${skipped.length} route(s) skipped — details in .sparda/scan-report.json`);
@@ -84,15 +85,15 @@ export async function runInit(opts) {
   p.log.success('Wrote sparda.json');
 
   const cfg = JSON.stringify({ [path.basename(opts.cwd)]: { command: 'npx', args: ['sparda-mcp', 'dev'], cwd: opts.cwd } }, null, 2);
-  p.outro(`Done in ${((Date.now() - t0) / 1000).toFixed(1)}s.
+  p.outro(`${c.green(`Done in ${((Date.now() - t0) / 1000).toFixed(1)}s.`)}
 
    Next steps:
-   1. Start your app:        ${stack.framework === 'express' ? 'npm run dev' : 'fastapi dev'}
-   2. Start the MCP bridge:  npx sparda-mcp dev
+   1. Start your app:        ${c.cyan(stack.framework === 'express' ? 'npm run dev' : 'fastapi dev')}
+   2. Start the MCP bridge:  ${c.cyan('npx sparda-mcp dev')}
    3. Add to Claude Desktop config (claude_desktop_config.json):
 
-${cfg.split('\n').map((l) => '   ' + l).join('\n')}
+${colorizeJson(cfg).split('\n').map((l) => '   ' + l).join('\n')}
 
-   Write tools (POST/PUT/DELETE) are disabled by default.
-   Enable them in sparda.json, then re-run \`npx sparda-mcp init --yes\`.`);
+   ${c.dim('Write tools (POST/PUT/DELETE) are disabled by default.')}
+   ${c.dim('Enable them in sparda.json, then re-run')} ${c.cyan('`npx sparda-mcp init --yes`')}${c.dim('.')}`);
 }

package/src/commands/remove.js

@@ -5,6 +5,7 @@ import * as p from '@clack/prompts';
 import { removeInjection as removeExpress } from '../generator/express.js';
 import { removeInjection as removeFastAPI } from '../generator/fastapi.js';
 import { detectStack } from '../detect.js';
+import { removeHook } from './hook.js';
 
 export async function runRemove(opts) {
   const manifestPath = path.join(opts.cwd, 'sparda.json');
@@ -43,6 +44,7 @@ export async function runRemove(opts) {
     if (fs.existsSync(abs)) { fs.rmSync(abs); console.log(`✓ Deleted ${f}`); }
   }
   if (revertGitignore(opts.cwd, manifest.gitignore)) console.log('✓ Reverted .gitignore edit');
+  if (removeHook(opts.cwd)) console.log('✓ Uninstalled post-commit sentinel hook');
   fs.rmSync(manifestPath);
   fs.rmSync(path.join(opts.cwd, '.sparda'), { recursive: true, force: true });
   console.log('✓ Deleted sparda.json and .sparda/');

package/src/generator/express.js

@@ -97,6 +97,7 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     ...(gitignore ? { gitignore } : {}),
     ...(prev?.semantic ? { semantic: prev.semantic } : {}),
     ...(prev?.immune ? { immune: prev.immune } : {}),
+    ...(prev?.labs ? { labs: prev.labs } : {}),
   };
   atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
 

package/src/generator/fastapi.js

@@ -66,6 +66,7 @@ export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, py
     ...(gitignore ? { gitignore } : {}),
     ...(prev?.semantic ? { semantic: prev.semantic } : {}),
     ...(prev?.immune ? { immune: prev.immune } : {}),
+    ...(prev?.labs ? { labs: prev.labs } : {}),
   };
 
   atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');

package/src/generator/manifest.js

@@ -2,10 +2,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-// Re-running init must not wipe what the user (or the semantic/immune passes)
-// wrote into sparda.json: per-tool `enabled` overrides, the cached `semantic`
-// enrichment and the `immune` memory (antibodies) survive as long as the
-// tool's method+path are unchanged.
+// 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.
 export function carryOverManifest(cwd, tools) {
   let prev = null;
   try {

package/src/parser/express.js

@@ -129,6 +129,14 @@ export function parseExpressProject(cwd, entryFile) {
 
         const mutating = method !== 'get';
         const params = [...pathParams];
+        // query params: handlers reveal them as req.query.X / destructured req.query —
+        // without this the AI cannot discover ?limit=… filters at all (E2E P2 finding)
+        const taken = new Set(params.map((x) => x.name));
+        for (const q of queryParamsOf(p)) {
+          if (taken.has(q)) continue;
+          taken.add(q);
+          params.push({ name: q, in: 'query', type: 'string', required: false, description: 'query parameter' });
+        }
         let confidence = 'high';
         if (mutating) {
           params.push({ name: 'body', in: 'body', type: 'object', required: false, description: 'JSON body — schema not statically detected' });
@@ -172,6 +180,40 @@ export function parseExpressProject(cwd, entryFile) {
   }
 }
 
+// Query params are invisible in a route's signature; only the handler body
+// reveals them. Covers the two canonical shapes — req.query.x / req.query['x']
+// and `const { x } = req.query` — on inline handlers only (an Identifier
+// handler lives elsewhere; guessing is worse than staying silent). Bounded.
+function queryParamsOf(callPath) {
+  const reqNames = new Set();
+  for (const a of callPath.node.arguments) {
+    if ((a.type === 'ArrowFunctionExpression' || a.type === 'FunctionExpression') && a.params[0]?.type === 'Identifier') {
+      reqNames.add(a.params[0].name);
+    }
+  }
+  const found = [];
+  if (!reqNames.size) return found;
+  const isReqQuery = (n) => n?.type === 'MemberExpression' && !n.computed &&
+    n.object?.type === 'Identifier' && reqNames.has(n.object.name) &&
+    n.property?.type === 'Identifier' && n.property.name === 'query';
+  callPath.traverse({
+    MemberExpression(q) {
+      const n = q.node;
+      if (!isReqQuery(n.object) || found.length >= 15) return;
+      if (!n.computed && n.property.type === 'Identifier') found.push(n.property.name);
+      else if (n.computed && n.property.type === 'StringLiteral') found.push(n.property.value);
+    },
+    VariableDeclarator(q) {
+      if (q.node.id.type !== 'ObjectPattern' || !isReqQuery(q.node.init)) return;
+      for (const prop of q.node.id.properties) {
+        if (found.length >= 15) break;
+        if (prop.type === 'ObjectProperty' && prop.key.type === 'Identifier') found.push(prop.key.name);
+      }
+    },
+  });
+  return [...new Set(found)];
+}
+
 function joinPath(prefix, p) {
   const joined = `${prefix ?? ''}${p === '/' && prefix ? '' : p}`.replace(/\/{2,}/g, '/');
   return joined.startsWith('/') ? joined : `/${joined}`;

package/src/server/condenser.js

@@ -0,0 +1,145 @@
+// server/condenser.js — ROADMAP round 2, brick 1: call-sequence recording (Labs).
+// Deterministic, zero LLM, default OFF. Observes the session's current of tool
+// calls and detects circuits — an output value of call A feeding an argument of
+// a later call B. Persists STRUCTURE only (tool names, arg names, counts) into
+// sparda.json: payload values can be PII and the manifest is committed to git.
+import fs from 'node:fs';
+
+const WINDOW = 20;       // calls remembered per session (ring)
+const MAX_VALUES = 50;   // scalars kept per payload
+const MAX_NODES = 200;   // payload walk budget — nothing heavy, ever
+const MAX_DEPTH = 4;
+const MAX_CHAIN = 5;     // a circuit longer than this is noise, not a workflow
+const MAX_LINKS = 10;
+const MAX_CIRCUITS = 30; // bounded memory, same philosophy as antibodies (ADR-010)
+// an emergent capability is a suggestion only after N observations (survival rule)
+export const CIRCUIT_OBSERVED_THRESHOLD = 3;
+
+// Labs gate: explicit opt-in in sparda.json, or env override for one session.
+export function sequenceRecordingEnabled(manifest, env = process.env) {
+  return manifest?.labs?.recordSequences === true || env.SPARDA_RECORD_SEQUENCES === '1';
+}
+
+export function createSequenceRecorder({ manifest, manifestPath, harvester, onCircuit }) {
+  manifest.labs ??= {};
+  manifest.labs.circuits ??= {};
+  const ring = [];
+
+  // hot path stays free: capture references, walk + match in idle (R4.4)
+  function record(tool, args, output) {
+    harvester.enqueue(() => analyze(tool, args, output));
+  }
+
+  function analyze(tool, args, output) {
+    const argEntries = extractArgEntries(args);
+    let link = null;
+    // most recent producer wins: the freshest output is the likeliest source
+    outer:
+    for (let i = ring.length - 1; i >= 0; i--) {
+      for (const [argName, value] of argEntries) {
+        if (ring[i].outValues.has(value)) {
+          // fromKey = where the value lived in the producer's output — the structure
+          // crystallization needs to re-feed the same arg at composite run time
+          link = { from: ring[i], arg: argName, fromKey: ring[i].outValues.get(value) };
+          break outer;
+        }
+      }
+    }
+    const chain = link ? [...link.from.chain.slice(-(MAX_CHAIN - 1)), tool] : [tool];
+    ring.push({ tool, chain, outValues: extractValues(output) });
+    if (ring.length > WINDOW) ring.shift();
+    if (!link) return;
+
+    const sig = chain.join('>');
+    const now = new Date().toISOString();
+    const circuits = manifest.labs.circuits;
+    const c = circuits[sig] ?? (circuits[sig] = { steps: chain, links: [], seen: 0, firstSeen: now, lastSeen: now });
+    c.seen += 1;
+    c.lastSeen = now;
+    if (c.links.length < MAX_LINKS &&
+        !c.links.some((l) => l.from === link.from.tool && l.to === tool && l.arg === link.arg)) {
+      c.links.push({ from: link.from.tool, to: tool, arg: link.arg, fromKey: link.fromKey });
+    }
+    evict(circuits);
+    persist();
+    if (c.seen === CIRCUIT_OBSERVED_THRESHOLD) onCircuit?.(sig, c);
+  }
+
+  // least-observed circuits make room first; among equals, the stalest
+  function evict(circuits) {
+    const keys = Object.keys(circuits);
+    if (keys.length <= MAX_CIRCUITS) return;
+    keys
+      .sort((a, b) => (circuits[a].seen - circuits[b].seen) || circuits[a].lastSeen.localeCompare(circuits[b].lastSeen))
+      .slice(0, keys.length - MAX_CIRCUITS)
+      .forEach((k) => delete circuits[k]);
+  }
+
+  // merge-write like persistImmune: never clobber fields written by others
+  function persist() {
+    try {
+      const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      onDisk.labs = { ...onDisk.labs, circuits: manifest.labs.circuits };
+      fs.writeFileSync(manifestPath, JSON.stringify(onDisk, null, 2) + '\n');
+    } catch { /* disk briefly unavailable — circuits stay in memory */ }
+  }
+
+  return { record, circuits: () => manifest.labs.circuits };
+}
+
+// A scalar is link-worthy when it can plausibly be an identifier. Small ints
+// (counts, pages, flags) and 1-char strings are the noise floor — excluded,
+// unless a single digit sits under an id-ish key (id, userId, orderId…).
+function candidateValue(key, v) {
+  if (typeof v === 'string') {
+    const s = v.trim();
+    if (s.length < 2 || s.length > 200) return null;
+    if (['true', 'false', 'null', 'undefined'].includes(s.toLowerCase())) return null;
+    return s;
+  }
+  if (typeof v === 'number' && Number.isFinite(v)) {
+    if (Math.abs(v) >= 10 || /id$/i.test(key ?? '')) return String(v);
+  }
+  return null;
+}
+
+// bounded iterative walk; array elements inherit the parent key (indices carry no
+// meaning). Shared with crystallize.js (findByKey) — same budget everywhere.
+export function walkPayload(node, visit) {
+  const stack = [[null, node, 0]];
+  let seen = 0;
+  while (stack.length && seen < MAX_NODES) {
+    const [key, v, depth] = stack.pop();
+    seen += 1;
+    if (v && typeof v === 'object') {
+      if (depth >= MAX_DEPTH) continue;
+      for (const [k, child] of Object.entries(v)) {
+        stack.push([Array.isArray(v) ? key : k, child, depth + 1]);
+      }
+      continue;
+    }
+    if (visit(key, v) === false) return;
+  }
+}
+
+// value → key it lived under (first sighting wins): has() drives link detection,
+// get() gives crystallization its fromKey
+function extractValues(output) {
+  const values = new Map();
+  walkPayload(output, (key, v) => {
+    const c = candidateValue(key, v);
+    if (c !== null && !values.has(c)) values.set(c, key ?? null);
+    return values.size < MAX_VALUES;
+  });
+  return values;
+}
+
+function extractArgEntries(args) {
+  const entries = [];
+  walkPayload(args, (key, v) => {
+    const c = candidateValue(key, v);
+    if (c !== null && key) entries.push([key, c]);
+    return entries.length < 20;
+  });
+  return entries;
+}

package/src/server/crystallize.js

@@ -0,0 +1,89 @@
+// server/crystallize.js — ROADMAP round 2, brick 2: observation freezes state.
+// A circuit observed enough times crystallizes into a composite tool: one MCP
+// call that runs the whole chain, auto-feeding each linked argument from the
+// previous step's output (by fromKey — structure recorded at observation time,
+// never values). GET-only on purpose: a write inside a circuit keeps its own
+// per-call confirmation (ADR-004); composites never bypass it.
+import { walkPayload } from './condenser.js';
+
+// crystallizable = every step is an enabled GET and every link knows where to
+// re-feed from. Re-checked at every bridge start: tools change, circuits stay.
+export function eligibleForCrystallization(circuit, toolSpecs) {
+  return Array.isArray(circuit.steps) && circuit.steps.length >= 2 &&
+    circuit.steps.every((s) => toolSpecs[s]?.enabled && toolSpecs[s].method === 'GET') &&
+    Array.isArray(circuit.links) && circuit.links.length > 0 &&
+    circuit.links.every((l) => typeof l.fromKey === 'string' && l.fromKey.length > 0);
+}
+
+// graceful degradation (survival rule): no sampling → a deterministic name and
+// an honest description, built only from structure the manifest already holds
+export function fallbackComposite(circuit) {
+  const flow = circuit.links
+    .map((l) => `'${l.arg}' of ${l.to} comes from '${l.fromKey}' of ${l.from}`)
+    .join('; ');
+  return {
+    name: `circuit_${circuit.steps.join('_then_')}`.slice(0, 60).replace(/_+$/, ''),
+    description: `Runs ${circuit.steps.join(', then ')} as one call — ${flow}.`,
+    source: 'deterministic',
+  };
+}
+
+// a sampled name is untrusted input: normalize hard, reject anything shapeless
+export function normalizeCompositeName(raw) {
+  const n = String(raw ?? '').toLowerCase().trim()
+    .replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 40);
+  return /^[a-z][a-z0-9_]{2,}$/.test(n) ? n : null;
+}
+
+// the composite exposes the union of its steps' params, minus the auto-fed ones
+export function compositeSchema(circuit, toolSpecs) {
+  const autoFed = new Set(circuit.links.map((l) => `${l.to}:${l.arg}`));
+  const properties = {};
+  const required = [];
+  for (const step of circuit.steps) {
+    for (const p of toolSpecs[step]?.params ?? []) {
+      if (autoFed.has(`${step}:${p.name}`) || properties[p.name]) continue;
+      properties[p.name] = { type: p.type === 'unknown' ? 'string' : p.type, description: `${p.description ?? p.in} (for ${step})` };
+      if (p.required) required.push(p.name);
+    }
+  }
+  return { type: 'object', properties, ...(required.length ? { required } : {}) };
+}
+
+// first scalar living under `key` in a payload — same bounded walk as detection,
+// so what was observable is exactly what is re-feedable
+export function findByKey(node, key) {
+  let found;
+  walkPayload(node, (k, v) => {
+    if (k === key) { found = v; return false; }
+  });
+  return found;
+}
+
+// run the chain. The truth is always the real call (survival rule): every step
+// hits the live route through the router, and the trace reports what happened.
+export async function runComposite({ circuit, args, toolSpecs, invokeFn }) {
+  const outputs = {};
+  const trace = [];
+  let data = null;
+  for (const step of circuit.steps) {
+    const stepArgs = {};
+    for (const p of toolSpecs[step]?.params ?? []) {
+      if (args[p.name] !== undefined) stepArgs[p.name] = args[p.name];
+    }
+    for (const l of circuit.links) {
+      if (l.to !== step) continue;
+      const v = findByKey(outputs[l.from], l.fromKey);
+      if (v !== undefined) stepArgs[l.arg] = v;
+    }
+    const payload = await invokeFn(step, stepArgs);
+    const status = payload?.upstreamStatus;
+    trace.push({ tool: step, upstreamStatus: status ?? null, ...(payload?.error ? { error: payload.error } : {}) });
+    if (!payload || payload.error !== undefined || status === undefined || status >= 400) {
+      return { ok: false, trace }; // honest failure: stop the chain, show where
+    }
+    outputs[step] = payload.data;
+    data = payload.data;
+  }
+  return { ok: true, trace, data };
+}

package/src/server/idle.js

@@ -0,0 +1,42 @@
+// server/idle.js — the idle harvester (ROADMAP R4.4): SPARDA's internal work
+// (condensation, persistence, future organs) runs only when the event loop is
+// quiet. One job per tick — a drip, never a burst: perceived saturation stays
+// at zero even while the organism digests.
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+
+export function createIdleHarvester({ tickMs = 250, busyLagMs = 25, maxWaitMs = 5000, maxQueue = 200 } = {}) {
+  const resolutionMs = 10;
+  const histogram = monitorEventLoopDelay({ resolution: resolutionMs });
+  histogram.enable();
+  const queue = [];
+
+  const timer = setInterval(() => {
+    if (!queue.length) return;
+    // recorded delays hover around the sampling resolution on a quiet loop —
+    // the lag is what exceeds it. NaN (no samples yet) counts as quiet.
+    const lagMs = histogram.mean / 1e6 - resolutionMs;
+    histogram.reset();
+    const starving = Date.now() - queue[0].ts > maxWaitMs; // never wait forever on a loaded box
+    if (Number.isFinite(lagMs) && lagMs > busyLagMs && !starving) return;
+    const job = queue.shift();
+    try { job.fn(); } catch (e) { console.error(`[sparda] idle job failed (dropped): ${e.message}`); }
+  }, tickMs);
+  timer.unref?.();
+
+  return {
+    enqueue(fn) {
+      if (queue.length >= maxQueue) return false; // bounded, like every SPARDA buffer
+      queue.push({ fn, ts: Date.now() });
+      return true;
+    },
+    // synchronous drain for shutdown: pending knowledge must reach disk
+    flush() {
+      while (queue.length) {
+        const job = queue.shift();
+        try { job.fn(); } catch (e) { console.error(`[sparda] idle job failed (dropped): ${e.message}`); }
+      }
+    },
+    stop() { clearInterval(timer); histogram.disable(); },
+    pending: () => queue.length,
+  };
+}

package/src/server/stdio.js

@@ -9,8 +9,16 @@ import {
   ListPromptsRequestSchema, GetPromptRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { sanitizeDescription } from '../security/sanitize.js';
+import { createIdleHarvester } from './idle.js';
+import { createSequenceRecorder, sequenceRecordingEnabled } from './condenser.js';
+import { eligibleForCrystallization, fallbackComposite, normalizeCompositeName, compositeSchema, runComposite } from './crystallize.js';
 
 const EVENT_POLL_MS = Number(process.env.SPARDA_EVENT_POLL_MS ?? 5000);
+// the sampling budgets below are also what the recycling gauge counts as "avoided"
+// when cached knowledge short-circuits a call — the estimate is honest by construction
+const DIAGNOSIS_TOKENS = 120;
+const SEMANTIC_TOKENS = 1500;
+const CRYSTAL_TOKENS = 150; // naming a crystallized circuit: once per circuit, ever
 
 export async function startStdioBridge({ cwd, portOverride }) {
   // pitfall #1: neutralize any stray console.log from deps
@@ -36,10 +44,89 @@ 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.3.0' },
+    { name: `sparda-${path.basename(cwd)}`, version: '0.4.0' },
     { capabilities: { tools: { listChanged: true }, prompts: { listChanged: true }, logging: {} } },
   );
 
+  // R4.1, intelligence side of the gauge: sampling calls NOT spent because cached
+  // knowledge (semantic pass, antibodies) answered instead. Compute side lives in
+  // the router (/mcp/stats.recycle).
+  const intel = { samplingAvoided: 0, tokensAvoidedEst: 0 };
+
+  // R4.4: every internal organ works only when the event loop is quiet
+  const harvester = createIdleHarvester();
+  // R2.1 (Labs, default OFF): record the current of calls, detect circuits;
+  // R2.2: at the observation threshold a circuit crystallizes into a composite tool
+  const composites = new Map(); // composite tool name -> { sig, circuit }
+  const recorder = sequenceRecordingEnabled(manifest)
+    ? createSequenceRecorder({
+        manifest, manifestPath, harvester,
+        onCircuit: (sig, c) => { crystallizeCircuit(sig, c).catch((e) => console.error(`[sparda] crystallization skipped: ${e.message}`)); },
+      })
+    : null;
+
+  const compositeNameTaken = (n) => Boolean(toolSpecs[n]) || composites.has(n) ||
+    ['sparda_info', 'sparda_list_disabled_tools', 'sparda_get_context'].includes(n);
+  const uniqueCompositeName = (base) => {
+    if (!compositeNameTaken(base)) return base;
+    for (let i = 2; ; i++) if (!compositeNameTaken(`${base}_${i}`)) return `${base}_${i}`;
+  };
+
+  async function crystallizeCircuit(sig, circuit) {
+    if (circuit.composite || !eligibleForCrystallization(circuit, toolSpecs)) {
+      // observed but not crystallizable (write step, missing fromKey…): say so, once
+      await server.sendLoggingMessage({
+        level: 'info', logger: 'sparda',
+        data: { source: 'condenser', circuit: sig, seen: circuit.seen, note: `circuit observed ${circuit.seen}× — not crystallized (composites are GET-only and need a traceable data flow)` },
+      }).catch(() => {});
+      return;
+    }
+    // the client's LLM names the newborn (one call, ever); no sampling → deterministic name
+    let named = null;
+    if (server.getClientCapabilities()?.sampling) {
+      try {
+        const flow = circuit.links.map((l) => `'${l.arg}' of ${l.to} comes from '${l.fromKey}' in the response of ${l.from}`).join('; ');
+        const res = await server.createMessage({
+          messages: [{
+            role: 'user',
+            content: {
+              type: 'text',
+              text: `A repeated tool-call sequence was observed ${circuit.seen}× in a live ${manifest.framework} app:\nsteps: ${circuit.steps.join(' -> ')}\ndata flow: ${flow}\ntools:\n${circuit.steps.map((s) => `- ${s}: ${toolSpecs[s].method} ${toolSpecs[s].path}`).join('\n')}\n\nReply with ONLY a JSON object {"name": "<snake_case verb_noun, max 40 chars>", "description": "<one sentence: what this combined operation achieves in business terms>"}.`,
+            },
+          }],
+          maxTokens: CRYSTAL_TOKENS,
+        });
+        const raw = res?.content?.type === 'text' ? res.content.text : '';
+        const parsed = JSON.parse(raw.replace(/^```(json)?\s*/i, '').replace(/```\s*$/, ''));
+        const name = normalizeCompositeName(parsed.name);
+        const { text: desc, flagged } = sanitizeDescription(String(parsed.description ?? ''), '');
+        if (name && desc && !flagged) named = { name, description: desc, source: 'mcp-sampling' };
+      } catch { /* graceful degradation: deterministic naming below */ }
+    }
+    const comp = named ?? fallbackComposite(circuit);
+    comp.name = uniqueCompositeName(comp.name);
+    comp.createdAt = new Date().toISOString();
+    circuit.composite = comp;
+    persistLabs(manifestPath, manifest);
+    composites.set(comp.name, { sig, circuit });
+    await server.sendToolListChanged().catch(() => {});
+    await server.sendLoggingMessage({
+      level: 'info', logger: 'sparda',
+      data: { source: 'condenser', circuit: sig, composite: comp.name, note: `circuit observed ${circuit.seen}× — crystallized as composite tool '${comp.name}' (born mid-session, see tools/list)` },
+    }).catch(() => {});
+    console.error(`[sparda] condenser: circuit ${sig} crystallized as ${comp.name}`);
+  }
+
+  // composites born in past sessions wake up with the bridge — re-validated
+  // against today's tools (a route may have changed or been disabled since)
+  if (recorder) {
+    for (const [sig, c] of Object.entries(manifest.labs?.circuits ?? {})) {
+      if (c.composite?.name && eligibleForCrystallization(c, toolSpecs)) {
+        composites.set(uniqueCompositeName(c.composite.name), { sig, circuit: c });
+      }
+    }
+  }
+
   const descFor = (name, t) => {
     const semantic = manifest.semantic?.descriptions?.[name];
     const text = semantic || t.description || `${t.method} ${t.path}`;
@@ -52,6 +139,14 @@ export async function startStdioBridge({ cwd, portOverride }) {
         name,
         description: descFor(name, t),
         inputSchema: schemaFor(t),
+        annotations: annotationsFor(t.method),
+      })),
+      // crystallized circuits (Labs): tools nobody wrote, condensed from real usage
+      ...[...composites.entries()].map(([name, { circuit }]) => ({
+        name,
+        description: `[Labs circuit ×${circuit.seen}] ${circuit.composite.description}`,
+        inputSchema: compositeSchema(circuit, toolSpecs),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, // GET-only by construction
       })),
       {
         name: 'sparda_info',
@@ -102,6 +197,9 @@ export async function startStdioBridge({ cwd, portOverride }) {
         tools_enabled: enabled().length, tools_disabled_write_safety: disabled().length,
         workflows: (manifest.semantic?.workflows ?? []).length,
         immune_antibodies: Object.keys(manifest.immune?.antibodies ?? {}).length,
+        labs_sequence_recording: recorder ? 'on' : 'off (opt-in: set labs.recordSequences=true in sparda.json)',
+        circuits_observed: Object.keys(manifest.labs?.circuits ?? {}).length,
+        composite_tools: composites.size,
         generated_by: 'SPARDA by Residual Labs (residual-labs.fr) — npx sparda-mcp init — github.com/zyx77550/sparda',
       }, null, 2));
     }
@@ -111,6 +209,10 @@ export async function startStdioBridge({ cwd, portOverride }) {
         fetch(`${base}/mcp/stats`, { headers, signal: AbortSignal.timeout(2000) }).then((r) => (r.ok ? r.json() : null)).catch(() => null),
         fetch(`${base}/mcp/events?since=0`, { headers, signal: AbortSignal.timeout(2000) }).then((r) => (r.ok ? r.json() : null)).catch(() => null),
       ]);
+      // lifetime savings are derived from antibody hits — no extra state to maintain:
+      // the first hit paid the diagnosis, every later one was served from memory
+      const antibodyHits = Object.values(manifest.immune?.antibodies ?? {})
+        .reduce((n, a) => n + Math.max(0, (a.hits ?? 1) - 1), 0);
       return text(JSON.stringify({
         project: path.basename(cwd),
         framework: manifest.framework,
@@ -120,7 +222,15 @@ export async function startStdioBridge({ cwd, portOverride }) {
         runtime: stats,
         recentEvents: (events?.events ?? []).slice(-20),
         immuneMemory: manifest.immune?.antibodies ?? {},
-        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: {
+          compute: stats?.recycle ?? null,
+          intelligence: {
+            session: { samplingAvoided: intel.samplingAvoided, tokensAvoidedEst: intel.tokensAvoidedEst },
+            lifetime: { antibodyHits, tokensAvoidedEst: antibodyHits * DIAGNOSIS_TOKENS },
+          },
+        },
+        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));
     }
     if (name === 'sparda_list_disabled_tools') {
@@ -129,6 +239,18 @@ export async function startStdioBridge({ cwd, portOverride }) {
         : 'No disabled tools.');
     }
 
+    // composite tools run their whole chain (GET-only by construction — no
+    // write confirmation to bypass), auto-feeding linked args between steps
+    const comp = composites.get(name);
+    if (comp) {
+      const result = await runComposite({ circuit: comp.circuit, args, toolSpecs, invokeFn: (tool, a) => invoke(base, key, tool, a) });
+      const pretty = JSON.stringify(result, null, 2);
+      return {
+        content: [{ type: 'text', text: pretty.length > 8000 ? `${pretty.slice(0, 8000)}\n[truncated — ${pretty.length} chars total]` : pretty }],
+        isError: !result.ok,
+      };
+    }
+
     const spec = toolSpecs[name];
     const isWrite = spec && spec.method !== 'GET';
 
@@ -152,6 +274,12 @@ export async function startStdioBridge({ cwd, portOverride }) {
       return { content: [{ type: 'text', text: `Host app error. Check that your server is still running on :${port}.` }], isError: true };
     }
 
+    // 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) {
+      recorder.record(name, args, payload.data);
+    }
+
     // proof-after-write: re-read the same path so the AI sees the effect of its write
     let proof = null;
     if (isWrite && payload.upstreamStatus < 400) {
@@ -172,14 +300,20 @@ export async function startStdioBridge({ cwd, portOverride }) {
 
   let pollTimer = null;
   server.oninitialized = () => {
-    pollTimer = startEventPolling(server, base, key, manifest, manifestPath);
+    // a session resumed on a cached semantic pass skipped the enrichment sampling call
+    if (manifest.semantic) { intel.samplingAvoided += 1; intel.tokensAvoidedEst += SEMANTIC_TOKENS; }
+    pollTimer = startEventPolling(server, base, key, manifest, manifestPath, intel);
     runSemanticEnrichment({ server, manifest, manifestPath, toolSpecs }).catch((e) => console.error(`[sparda] semantic pass skipped: ${e.message}`));
   };
-  server.onclose = () => { if (pollTimer) clearInterval(pollTimer); };
+  server.onclose = () => {
+    if (pollTimer) clearInterval(pollTimer);
+    harvester.flush(); // pending knowledge must reach disk before the lights go out
+    harvester.stop();
+  };
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error(`[sparda] MCP bridge running. ${enabled().length} tools enabled, ${disabled().length} disabled (write-safety). Host: ${base}`);
+  console.error(`[sparda] MCP bridge running. ${enabled().length} tools enabled, ${disabled().length} disabled (write-safety).${recorder ? ' Labs: sequence recording ON.' : ''} Host: ${base}`);
 }
 
 async function invoke(base, key, tool, args) {
@@ -206,7 +340,7 @@ function pickPathArgs(spec, args) {
 // live error feed: host app errors reach the AI as MCP logging notifications.
 // immune memory: known failure signatures carry their cached diagnosis (zero tokens);
 // new signatures wake the client's LLM once, and the antibody is stored in sparda.json.
-function startEventPolling(server, base, key, manifest, manifestPath) {
+function startEventPolling(server, base, key, manifest, manifestPath, intel) {
   let lastSeq = null; // first poll sets the baseline; only NEW errors are reported
   const timer = setInterval(async () => {
     try {
@@ -221,6 +355,8 @@ function startEventPolling(server, base, key, manifest, manifestPath) {
         if (antibody) {
           antibody.hits = (antibody.hits ?? 0) + 1;
           antibody.lastSeen = ev.ts;
+          intel.samplingAvoided += 1;            // this diagnosis would have been a sampling call
+          intel.tokensAvoidedEst += DIAGNOSIS_TOKENS;
           persistImmune(manifestPath, manifest);
           await server.sendLoggingMessage({ level: 'error', logger: 'sparda', data: { ...ev, diagnosis: antibody.diagnosis } }).catch(() => {});
         } else {
@@ -254,7 +390,7 @@ async function diagnoseAndRemember({ server, manifest, manifestPath, ev, sig })
           text: `A tool of a live ${manifest.framework} app just failed.\nTool: ${ev.tool ?? 'n/a'}\nSource: ${ev.source}\nStatus: ${ev.status ?? 'n/a'}\nError message: ${ev.message}\n\nReply with ONE short sentence (max 140 chars): most likely root cause and fix direction. No preamble.`,
         },
       }],
-      maxTokens: 120,
+      maxTokens: DIAGNOSIS_TOKENS,
     });
     const raw = res?.content?.type === 'text' ? res.content.text.trim() : '';
     const { text: clean, flagged } = sanitizeDescription(raw, '');
@@ -279,6 +415,14 @@ function persistImmune(manifestPath, manifest) {
   } catch { /* disk briefly unavailable — the antibody stays in memory */ }
 }
 
+function persistLabs(manifestPath, manifest) {
+  try {
+    const onDisk = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    onDisk.labs = { ...onDisk.labs, circuits: manifest.labs.circuits };
+    fs.writeFileSync(manifestPath, JSON.stringify(onDisk, null, 2) + '\n');
+  } catch { /* disk briefly unavailable — the circuit stays in memory */ }
+}
+
 // semantic pass: uses the CLIENT's own model via MCP sampling — zero key, zero cost.
 // Runs once, result cached in sparda.json (and preserved across re-init).
 async function runSemanticEnrichment({ server, manifest, manifestPath, toolSpecs }) {
@@ -294,7 +438,7 @@ async function runSemanticEnrichment({ server, manifest, manifestPath, toolSpecs
         text: `These are API tools extracted from a ${manifest.framework} codebase:\n${inventory}\n\nReply with ONLY a JSON object, no prose, shaped as {"descriptions": {"<tool>": "<one clear sentence of what it does in business terms>"}, "workflows": [{"name": "<snake_case>", "description": "<goal>", "steps": ["<tool>", ...]}]}. Include 1-3 workflows that chain tools toward a realistic business goal. Use only the tool names listed above.`,
       },
     }],
-    maxTokens: 1500,
+    maxTokens: SEMANTIC_TOKENS,
   });
 
   const raw = res?.content?.type === 'text' ? res.content.text : '';
@@ -326,6 +470,17 @@ async function runSemanticEnrichment({ server, manifest, manifestPath, toolSpecs
   console.error(`[sparda] semantic pass done: ${Object.keys(descriptions).length} descriptions, ${workflows.length} workflows (cached in sparda.json)`);
 }
 
+// MCP annotations: without them clients assume the scariest defaults and show
+// destructive-looking hints on plain reads (E2E P2 finding). HTTP maps 1:1.
+function annotationsFor(method) {
+  return {
+    readOnlyHint: method === 'GET',
+    destructiveHint: method === 'DELETE',
+    idempotentHint: method === 'GET' || method === 'PUT' || method === 'DELETE',
+    openWorldHint: false, // a local API behind the router, not the open internet
+  };
+}
+
 function schemaFor(t) {
   const properties = {}; const required = [];
   for (const p of t.params ?? []) {

package/src/ui/style.js

@@ -0,0 +1,66 @@
+// ui/style.js — zero-dep ANSI styling for the HUMAN commands (init, remove,
+// doctor). Never import this from the bridge path: there, stdout is the MCP
+// protocol (hard rule #2) and stderr must stay grep-able plain text.
+
+// SPARDA identity: violet → cyan, same stops as the brand gradient
+const VIOLET = [192, 132, 252]; // #c084fc
+const CYAN = [103, 232, 249];   // #67e8f9
+const RESET = '\x1b[0m';
+
+// evaluated per call so tests (and runtime env changes) see the truth;
+// honors https://no-color.org and the FORCE_COLOR convention
+function enabled() {
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0') return true;
+  if (process.env.NO_COLOR !== undefined) return false;
+  return Boolean(process.stdout.isTTY) && process.env.TERM !== 'dumb';
+}
+
+function truecolor() {
+  return /truecolor|24bit/i.test(process.env.COLORTERM ?? '') ||
+    ['iTerm.app', 'vscode', 'WezTerm', 'ghostty'].includes(process.env.TERM_PROGRAM ?? '') ||
+    Boolean(process.env.WT_SESSION);
+}
+
+const sgr = (open) => (s) => (enabled() ? `\x1b[${open}m${s}${RESET}` : String(s));
+
+export const c = {
+  dim: sgr('2'),
+  bold: sgr('1'),
+  green: sgr('32'),
+  yellow: sgr('33'),
+  red: sgr('31'),
+  cyan: sgr('38;5;117'),
+  violet: sgr('38;5;177'),
+};
+
+// the brand banner: per-character violet→cyan interpolation in truecolor,
+// a stepped 256-color ramp elsewhere, plain text when colors are off
+export function gradient(text) {
+  if (!enabled()) return text;
+  const chars = [...text];
+  if (truecolor()) {
+    const body = chars.map((ch, i) => {
+      const t = chars.length === 1 ? 0 : i / (chars.length - 1);
+      const [r, g, b] = VIOLET.map((v, k) => Math.round(v + (CYAN[k] - v) * t));
+      return `\x1b[1m\x1b[38;2;${r};${g};${b}m${ch}`;
+    }).join('');
+    return body + RESET;
+  }
+  const ramp = [177, 141, 147, 153, 117];
+  const body = chars.map((ch, i) => {
+    const step = ramp[Math.min(ramp.length - 1, Math.floor((i / chars.length) * ramp.length))];
+    return `\x1b[1m\x1b[38;5;${step}m${ch}`;
+  }).join('');
+  return body + RESET;
+}
+
+// single-pass JSON highlighter (keys violet, strings cyan, punctuation dim) —
+// one pass on purpose: a second regex pass would chew the ANSI escapes of the first
+export function colorizeJson(json) {
+  if (!enabled()) return json;
+  return json.replace(/("(?:[^"\\]|\\.)*")(\s*:)?|([{}[\],])/g, (m, str, colon, punct) => {
+    if (punct) return c.dim(punct);
+    if (colon !== undefined) return c.violet(str) + c.dim(colon);
+    return c.cyan(str);
+  });
+}

package/templates/express-router.txt

@@ -15,6 +15,45 @@ let SPARDA_SEQ = 0;
 // immune system: tools that keep failing are quarantined so the AI can't hammer a broken route
 const SPARDA_QUARANTINE__STATS_TYPE__ = {};
 const SPARDA_QUARANTINE_MS = Number(process.env.SPARDA_QUARANTINE_MS ?? 60000);
+// recycling gauge: calls answered from SPARDA's own knowledge vs calls that paid the host route.
+// Day 1 it reads 0% — the circle fills with usage (a measure, never a promise).
+const SPARDA_RECYCLE__STATS_TYPE__ = { servedByCircle: 0, paidFull: 0 };
+function spardaRecycleRate() {
+  const total = SPARDA_RECYCLE.servedByCircle + SPARDA_RECYCLE.paidFull;
+  return total ? Math.round((SPARDA_RECYCLE.servedByCircle * 100) / total) : 0;
+}
+// thermodynamic route classification: a GET whose repeated identical args keep
+// returning identical bodies is observed-pure (its result pre-exists — recyclable);
+// writes erase by definition. Observation only, never a guess.
+const SPARDA_PURITY__STATS_TYPE__ = {};
+function spardaHash(s__ANY_TYPE__) {
+  let h = 0x811c9dc5; // FNV-1a, capped: a fingerprint, not a checksum of megabytes
+  for (let i = 0; i < s.length && i < 65536; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+  return h;
+}
+function spardaObservePurity(tool__ANY_TYPE__, argsig__ANY_TYPE__, body__ANY_TYPE__) {
+  const pu = SPARDA_PURITY[tool] ?? (SPARDA_PURITY[tool] = { sigs: {}, repeats: 0, mismatches: 0 });
+  const h = spardaHash(body);
+  const known = pu.sigs[argsig];
+  if (known === undefined) {
+    if (Object.keys(pu.sigs).length >= 20) return; // bounded: enough sigs to judge
+    pu.sigs[argsig] = h;
+  } else if (known === h) pu.repeats += 1;
+  else { pu.mismatches += 1; pu.sigs[argsig] = h; } // the latest real answer is the truth
+}
+function spardaPuritySnapshot() {
+  const out__STATS_TYPE__ = {};
+  for (const [name, spec] of Object.entries(SPARDA_TOOLS)) {
+    if (spec.method !== 'GET') { out[name] = { class: 'erasing', repeats: 0, mismatches: 0 }; continue; }
+    const pu = SPARDA_PURITY[name];
+    out[name] = {
+      class: !pu ? 'unknown' : pu.mismatches > 0 ? 'volatile' : pu.repeats >= 3 ? 'pure' : 'unknown',
+      repeats: pu ? pu.repeats : 0,
+      mismatches: pu ? pu.mismatches : 0,
+    };
+  }
+  return out;
+}
 function spardaEvent(source__ANY_TYPE__, tool__ANY_TYPE__, status__ANY_TYPE__, message__ANY_TYPE__) {
   SPARDA_EVENTS.push({ seq: ++SPARDA_SEQ, ts: new Date().toISOString(), source, tool, status, message: String(message ?? '').slice(0, 500) });
   if (SPARDA_EVENTS.length > 100) SPARDA_EVENTS.shift();
@@ -33,7 +72,7 @@ spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) => {
 
 spardaRouter.get('/tools', (_req__REQ_TYPE__, res__RES_TYPE__) => res.json(SPARDA_TOOLS));
 
-spardaRouter.get('/stats', (_req__REQ_TYPE__, res__RES_TYPE__) => res.json({ uptimeSec: Math.round(process.uptime()), stats: SPARDA_STATS, quarantine: SPARDA_QUARANTINE }));
+spardaRouter.get('/stats', (_req__REQ_TYPE__, res__RES_TYPE__) => res.json({ uptimeSec: Math.round(process.uptime()), stats: SPARDA_STATS, quarantine: SPARDA_QUARANTINE, recycle: { servedByCircle: SPARDA_RECYCLE.servedByCircle, paidFull: SPARDA_RECYCLE.paidFull, ratePct: spardaRecycleRate() }, purity: spardaPuritySnapshot() }));
 
 spardaRouter.get('/events', (req__REQ_TYPE__, res__RES_TYPE__) => {
   const since = Number(req.query.since ?? 0) || 0;
@@ -54,6 +93,7 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE_
   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() });
     }
     // half-open: cooldown elapsed — allow one probe; a single new 5xx re-quarantines
@@ -78,10 +118,15 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE_
       init.headers['content-type'] = 'application/json';
       init.body = JSON.stringify(args.body);
     }
+    SPARDA_RECYCLE.paidFull += 1; // the host route is about to be exercised — full price
     const upstream = await fetch(`http://127.0.0.1:${SPARDA_PORT}${url}`, { ...init, signal: AbortSignal.timeout(30_000) });
     const text = await upstream.text();
     let data; try { data = JSON.parse(text); } catch { data = text; }
     spardaRecord(tool, upstream.status, Date.now() - t0);
+    if (spec.method === 'GET' && upstream.status === 200) {
+      // canonical argsig: sorted entries, so the AI's argument order never splits a signature
+      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 });
   } catch (err__ANY_TYPE__) {
@@ -92,14 +137,16 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE_
 });
 
 function spardaRecord(tool__ANY_TYPE__, status__ANY_TYPE__, ms__ANY_TYPE__) {
-  const st = SPARDA_STATS[tool] ?? (SPARDA_STATS[tool] = { calls: 0, errors: 0, totalMs: 0, lastStatus: null, lastTs: null, consecutive5xx: 0 });
+  const st = SPARDA_STATS[tool] ?? (SPARDA_STATS[tool] = { calls: 0, errors: 0, clientErrors: 0, totalMs: 0, lastStatus: null, lastTs: null, consecutive5xx: 0 });
   // innate immunity: latency far beyond the learned baseline is an antigen
   if (st.calls >= 5 && ms > Math.max((st.totalMs / st.calls) * 10, 200)) {
     spardaEvent('immune', tool, status, `latency anomaly: ${ms}ms vs ~${Math.round(st.totalMs / st.calls)}ms baseline`);
   }
   st.calls += 1;
   st.totalMs += ms;
-  if (status >= 400) st.errors += 1;
+  // 5xx = server failure (feeds the immune system); 4xx = a valid client answer (404 etc), tracked apart so the count doesn't lie
+  if (status >= 500) st.errors += 1;
+  else if (status >= 400) st.clientErrors += 1;
   st.lastStatus = status;
   st.lastTs = new Date().toISOString();
   if (status >= 500) st.consecutive5xx += 1;

package/templates/fastapi-router.txt

@@ -13,6 +13,7 @@ import asyncio
 import time
 import datetime
 import os
+import zlib
 
 # json.loads, not a Python literal: JSON true/false/null are not valid Python (E-009)
 SPARDA_TOOLS = json.loads(__TOOLS_JSON__)
@@ -26,6 +27,50 @@ SPARDA_START = time.time()
 # immune system: tools that keep failing are quarantined so the AI can't hammer a broken route
 SPARDA_QUARANTINE = {}
 SPARDA_QUARANTINE_MS = int(os.environ.get("SPARDA_QUARANTINE_MS", "60000"))
+# recycling gauge: calls answered from SPARDA's own knowledge vs calls that paid the host route.
+# Day 1 it reads 0% — the circle fills with usage (a measure, never a promise).
+SPARDA_RECYCLE = {"servedByCircle": 0, "paidFull": 0}
+
+def sparda_recycle_rate():
+    total = SPARDA_RECYCLE["servedByCircle"] + SPARDA_RECYCLE["paidFull"]
+    return round(SPARDA_RECYCLE["servedByCircle"] * 100 / total) if total else 0
+
+# thermodynamic route classification: a GET whose repeated identical args keep
+# returning identical bodies is observed-pure (its result pre-exists — recyclable);
+# writes erase by definition. Observation only, never a guess.
+SPARDA_PURITY = {}
+
+def sparda_observe_purity(tool, argsig, body_bytes):
+    pu = SPARDA_PURITY.setdefault(tool, {"sigs": {}, "repeats": 0, "mismatches": 0})
+    h = zlib.crc32(body_bytes[:65536])  # a fingerprint, not a checksum of megabytes
+    known = pu["sigs"].get(argsig)
+    if known is None:
+        if len(pu["sigs"]) >= 20:  # bounded: enough sigs to judge
+            return
+        pu["sigs"][argsig] = h
+    elif known == h:
+        pu["repeats"] += 1
+    else:
+        pu["mismatches"] += 1
+        pu["sigs"][argsig] = h  # the latest real answer is the truth
+
+def sparda_purity_snapshot():
+    out = {}
+    for name, spec in SPARDA_TOOLS.items():
+        if spec.get("method") != "GET":
+            out[name] = {"class": "erasing", "repeats": 0, "mismatches": 0}
+            continue
+        pu = SPARDA_PURITY.get(name)
+        if not pu:
+            cls = "unknown"
+        elif pu["mismatches"] > 0:
+            cls = "volatile"
+        elif pu["repeats"] >= 3:
+            cls = "pure"
+        else:
+            cls = "unknown"
+        out[name] = {"class": cls, "repeats": pu["repeats"] if pu else 0, "mismatches": pu["mismatches"] if pu else 0}
+    return out
 
 def sparda_event(source, tool, status, message):
     global SPARDA_SEQ
@@ -40,14 +85,17 @@ def sparda_event(source, tool, status, message):
         SPARDA_EVENTS.pop(0)
 
 def sparda_record(tool, status, ms):
-    st = SPARDA_STATS.setdefault(tool, {"calls": 0, "errors": 0, "totalMs": 0, "lastStatus": None, "lastTs": None, "consecutive5xx": 0})
+    st = SPARDA_STATS.setdefault(tool, {"calls": 0, "errors": 0, "clientErrors": 0, "totalMs": 0, "lastStatus": None, "lastTs": None, "consecutive5xx": 0})
     # innate immunity: latency far beyond the learned baseline is an antigen
     if st["calls"] >= 5 and ms > max((st["totalMs"] / st["calls"]) * 10, 200):
         sparda_event("immune", tool, status, f"latency anomaly: {ms}ms vs ~{round(st['totalMs'] / st['calls'])}ms baseline")
     st["calls"] += 1
     st["totalMs"] += ms
-    if status >= 400:
+    # 5xx = server failure (feeds the immune system); 4xx = a valid client answer (404 etc), tracked apart so the count doesn't lie
+    if status >= 500:
         st["errors"] += 1
+    elif status >= 400:
+        st["clientErrors"] += 1
     st["lastStatus"] = status
     st["lastTs"] = datetime.datetime.now(datetime.timezone.utc).isoformat()
     if status >= 500:
@@ -88,7 +136,7 @@ async def get_tools(request: Request):
 async def get_stats(request: Request):
     if request.headers.get("x-sparda-key") != SPARDA_LOCAL_KEY:
         return JSONResponse(status_code=401, content={"error": "unauthorized"})
-    return {"uptimeSec": round(time.time() - SPARDA_START), "stats": SPARDA_STATS, "quarantine": SPARDA_QUARANTINE}
+    return {"uptimeSec": round(time.time() - SPARDA_START), "stats": SPARDA_STATS, "quarantine": SPARDA_QUARANTINE, "recycle": {**SPARDA_RECYCLE, "ratePct": sparda_recycle_rate()}, "purity": sparda_purity_snapshot()}
 
 @sparda_router.get("/events")
 async def get_events(request: Request):
@@ -131,6 +179,7 @@ async def invoke_tool(request: Request):
     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"],
@@ -173,6 +222,7 @@ async def invoke_tool(request: Request):
             headers["content-type"] = "application/json"
             body_bytes = json.dumps(args["body"]).encode("utf-8")
 
+        SPARDA_RECYCLE["paidFull"] += 1  # the host route is about to be exercised — full price
         loop = asyncio.get_running_loop()
         status, content_type, data_bytes = await loop.run_in_executor(
             executor, sync_fetch, url, method, headers, body_bytes
@@ -185,6 +235,10 @@ async def invoke_tool(request: Request):
             data = text_data
 
         sparda_record(tool, status, round((time.time() - t0) * 1000))
+        if method == "GET" and status == 200:
+            # canonical argsig: sorted items, so the AI's argument order never splits a signature
+            argsig = json.dumps(sorted((k, str(v)) for k, v in args.items() if v is not None))
+            sparda_observe_purity(tool, argsig, data_bytes)
         if status >= 500:
             sparda_event("invoke", tool, status, text_data[:200])
         return {"upstreamStatus": status, "data": data}