sparda-mcp 0.3.0 → 0.5.0

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.5.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,16 @@ 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 },
+          },
+        },
+        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));
     }
     if (name === 'sparda_list_disabled_tools') {
@@ -129,6 +240,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';
 
@@ -143,15 +266,45 @@ 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) {
+      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 +325,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 +365,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 +380,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 +415,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 +440,74 @@ 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'));
+    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 +523,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 +555,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 ?? []) {