skynet-graph 1.2.0

package/lib/sg/log-sinks.js

@@ -0,0 +1,214 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * CLI log sinks — live in lib/sg/ because they touch fs/TTY and must stay out of
+ * the fs-free engine core. A sink is fn(record); attach with graph.logger.addSink.
+ *
+ *   plain     : one clean line per record, no cursor control (pipe/CI friendly)
+ *   dashboard : a fixed top stats pane + a scrolling log region (TTY only, zero-dep
+ *               ANSI via a DECSTBM scroll region). Degrades to plain off a TTY.
+ *   file      : append to a journal (.jsonl -> JSON lines, else formatted text)
+ *
+ * Per-sink level: the graph logger threshold is set to the MOST permissive level any
+ * sink needs (records below it never reach any sink); each sink then drops what is
+ * below its own level. This lets the file journal be verbose while the console is info.
+ */
+const fs = require('fs');
+const util = require('util');
+const { LEVELS } = require('../graph/log.js');
+
+const PALETTE = { error: 31, warn: 33, log: 37, info: 36, verbose: 90 }; // ANSI fg codes
+
+function passes ( level, threshold ) { return LEVELS[level] <= LEVELS[threshold]; }
+function mostPermissive ( names ) { return names.reduce(function ( a, b ) { return LEVELS[b] > LEVELS[a] ? b : a; }); }
+
+function two ( n ) { return (n < 10 ? '0' : '') + n; }
+function hhmmss ( ts ) { var d = new Date(ts); return two(d.getHours()) + ':' + two(d.getMinutes()) + ':' + two(d.getSeconds()); }
+
+function ctxStr ( ctx ) {
+	if ( !ctx ) return '';
+	var bits = [];
+	if ( ctx.concept ) bits.push(ctx.concept);
+	if ( ctx.target )  bits.push((ctx.type ? ctx.type[0] + ':' : '') + ctx.target);
+	return bits.length ? '·' + bits.join('/') : '';
+}
+
+// Render msg + args the way console does (printf %s/%d/%j, leftover args appended),
+// so the engine's existing printf-style messages format correctly. Sanitized Errors
+// ({message,stack}) are shown as their stack string rather than an inline object.
+function formatBody ( rec ) {
+	var args = (rec.args || []).map(function ( a ) { return (a && a.stack) ? a.stack : a; });
+	return util.format.apply(util, [rec.msg].concat(args));
+}
+
+function formatLine ( rec, color ) {
+	var head = hhmmss(rec.ts) + ' ' + rec.level.toUpperCase().padEnd(7) + ' [' + rec.label + ctxStr(rec.ctx) + '] ';
+	var line = head + formatBody(rec);
+	if ( color && PALETTE[rec.level] ) return '\x1b[' + PALETTE[rec.level] + 'm' + line + '\x1b[0m';
+	return line;
+}
+
+function createPlainSink ( opts ) {
+	opts = opts || {};
+	var stream = opts.stream || process.stdout;
+	var color  = opts.color != null ? opts.color : !!stream.isTTY;
+	var min    = opts.level || 'verbose';
+	return function ( rec ) { if ( passes(rec.level, min) ) stream.write(formatLine(rec, color) + '\n'); };
+}
+
+function createFileSink ( opts ) {
+	var fd    = fs.openSync(opts.path, 'a');
+	var jsonl = /\.jsonl$/i.test(opts.path);
+	var min   = opts.level || 'verbose';
+	return function ( rec ) {
+		if ( !passes(rec.level, min) ) return;
+		fs.writeSync(fd, (jsonl ? JSON.stringify(rec) : formatLine(rec, false)) + '\n');
+	};
+}
+
+// Live snapshot of the graph's engine state for the status bar (pure / read-only).
+function graphStats ( g ) {
+	g = g || {};
+	var unstable = g._unstable || [], nodes = 0, segs = 0, other = 0;
+	for ( var i = 0 ; i < unstable.length ; i++ ) {
+		var u = unstable[i], e = u && (u._etty ? u._etty._ : u._);
+		if ( e && e.Node ) nodes++; else if ( e && e.Segment ) segs++; else other++;
+	}
+	// the main loop is _loopTF driven by _taskFlow; its pending work = queued tasks
+	var tf = g._taskFlow || {};
+	var queue = (tf.doAfter ? tf.doAfter.length : 0) + (tf.todo ? Math.max(0, tf.todo.length - (tf._pos || 0)) : 0);
+	var stats = g._statsByProvider || {}, provMs = 0;
+	for ( var k in stats ) provMs += stats[k];
+	return {
+		state   : g._stabilizing ? 'stabilizing' : (unstable.length ? 'pending' : 'stable'),
+		unstable: unstable.length, nodes: nodes, segments: segs, other: other,
+		pending : (g._pending || []).length, stable: (g._stable || []).length,
+		queue   : queue, locks: tf.locks || 0,
+		rev     : g._rev || 0, applies: g._applyId || 0, provMs: provMs
+	};
+}
+
+// One-line status text (no positioning ANSI), padded/truncated to `width`.
+function formatStatusBar ( g, width, elapsedS ) {
+	var s = graphStats(g);
+	var dot = s.state === 'stable' ? '●' : '◐';
+	var parts = [
+		dot + ' ' + s.state,
+		'obj ' + (s.stable + s.unstable + s.pending),
+		'unstable ' + s.unstable + ' (N' + s.nodes + '/S' + s.segments + (s.other ? '/?' + s.other : '') + ')',
+		'queue ' + s.queue,
+		'rev ' + s.rev,
+		'applies ' + s.applies
+	];
+	if ( s.provMs )            parts.push('prov ' + (Math.round(s.provMs / 100) / 10) + 's');
+	if ( elapsedS != null )    parts.push(elapsedS + 's');
+	var line = ' ' + parts.join('  │  ') + ' ';
+	width = width || 80;
+	return line.length > width ? line.slice(0, width) : line + ' '.repeat(width - line.length);
+}
+
+// Styled boot banner: "SKYNET·GRAPH vX" + tagline (cyan/bold; plain if !color).
+function banner ( version, color ) {
+	var lines = [
+		'  ⛓  SKYNET · GRAPH   v' + (version || '?'),
+		'  rule-driven knowledge-graph reasoning substrate'
+	];
+	var w = Math.max(lines[0].length, lines[1].length) + 2;
+	var bar = '─'.repeat(w);
+	if ( !color ) return ['┌' + bar + '┐', '│' + lines[0] + ' '.repeat(w - lines[0].length) + '│',
+		'│' + lines[1] + ' '.repeat(w - lines[1].length) + '│', '└' + bar + '┘'].join('\n');
+	var C = '\x1b[1;36m', R = '\x1b[0m', D = '\x1b[2m';
+	return [
+		C + '┌' + bar + '┐' + R,
+		C + '│' + R + lines[0] + ' '.repeat(w - lines[0].length) + C + '│' + R,
+		C + '│' + R + D + lines[1] + R + ' '.repeat(w - lines[1].length) + C + '│' + R,
+		C + '└' + bar + '┘' + R
+	].join('\n');
+}
+
+/**
+ * TTY dashboard: a live STATUS BAR kept at the bottom of the output over normal
+ * COLORED scrolling logs (graph state, unstable nodes/segments, main-loop queue,
+ * rev, applies, provider time, elapsed).
+ *
+ * Robust "reprint-in-place" technique (like npm/cargo progress bars) — NO scroll
+ * region, NO absolute cursor positioning, NO save/restore (all of which are flaky
+ * across WSL/tmux/embedded terminals and were flooding the scrollback): the bar is
+ * always the LAST thing written and never gets a trailing newline, so the cursor
+ * stays parked on it. To log: erase the bar line (`\r ESC[2K`), write the log line +
+ * `\n` (the terminal scrolls naturally), then reprint the bar on the new last line.
+ * A timer refreshes the bar in place. Off a TTY it degrades to a plain sink.
+ */
+function createDashboardSink ( opts ) {
+	// either a static `graph` or a `getGraph()` (studio has many sessions → the active one)
+	var getGraph = opts.getGraph || function () { return opts.graph; };
+	var stream   = opts.stream || process.stdout;
+	var min      = opts.level || 'verbose';
+	if ( !stream.isTTY ) return createPlainSink({ stream: stream, level: min });   // degrade
+
+	var start = Date.now(), timer = null, active = false;
+	function cols () { return stream.columns || 80; }
+
+	function barText () {
+		var w = cols(), g = getGraph();
+		var elapsed = Math.round((Date.now() - start) / 100) / 10;
+		var line;
+		if ( g ) line = formatStatusBar(g, w, elapsed);
+		else { line = ' ◌ idle — no graph loaded   ' + elapsed + 's'; line = line.length > w ? line.slice(0, w) : line + ' '.repeat(w - line.length); }
+		return '\x1b[7m' + line + '\x1b[0m';
+	}
+	function clearBarLine () { stream.write('\r\x1b[2K'); }            // col 0 + erase the whole line
+	function drawBar () { clearBarLine(); stream.write(barText() + '\r'); }   // bar, cursor parked at its start (no newline)
+
+	function mount () { active = true; drawBar(); timer = setInterval(drawBar, 250); if ( timer.unref ) timer.unref(); }
+
+	function sink ( rec ) {
+		if ( !active ) mount();
+		if ( !passes(rec.level, min) ) return;
+		clearBarLine();                               // wipe the bar off the last line
+		stream.write(formatLine(rec, true) + '\n');   // print the log; the terminal scrolls
+		drawBar();                                    // reprint the bar on the new last line
+	}
+	sink.close = function () {
+		if ( timer ) { clearInterval(timer); timer = null; }
+		if ( active ) { clearBarLine(); active = false; }   // remove the bar, leave a clean line
+	};
+	return sink;
+}
+
+// Log-only mode has no fixed bar, so stats are emitted into the log stream instead:
+// a periodic info line with the same fields. (In dashboard mode the bar owns the stats
+// and this is NOT used — stats never appear in the logs there.) Returns the timer.
+function startStatsLogger ( logger, getGraph, intervalMs ) {
+	var t = setInterval(function () {
+		var g = getGraph && getGraph();
+		if ( !g ) return;
+		var s = graphStats(g);
+		logger.info('stats — %s | unstable %s (N%s/S%s) | queue %s | rev %s | applies %s',
+			s.state, s.unstable, s.nodes, s.segments, s.queue, s.rev, s.applies);
+	}, intervalMs || 2000);
+	if ( t.unref ) t.unref();
+	return t;
+}
+
+module.exports = {
+	createPlainSink, createFileSink, createDashboardSink, startStatsLogger,
+	formatLine, formatBody, ctxStr, hhmmss, mostPermissive, passes,
+	graphStats, formatStatusBar, banner
+};

package/lib/sg/mcp.js

@@ -0,0 +1,395 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * `sg mcp` — the MCP (Model Context Protocol) TOOLS server (roadmap FINIR, F2): the agentic surface where the
+ * TYPED capabilities become tools an agent host (Claude Code, any MCP client) consumes. Where `sg serve` sells
+ * the economy behind a generic chat wire, THIS surface exposes the differentiators STRUCTURED:
+ *   • `ask` — answer OR the TYPED REFUSAL as data ({status:'refused', reason, missing:[…]} — a refusal is a
+ *     typed ANSWER that names the missing requirement, never an error string);
+ *   • `drift` / `metrics` — anti-drift invalidation + the economy readout (proxy mode);
+ *   • `lattice_load` — LEARNING THROUGH THE GATE: a `.sgc kind:'lattice'` bundle grows the held registry via
+ *     `loadLattice` (version-gated, conflicting rings REJECTED by the confluence-checked merge). There is NO
+ *     tool that writes the stock or the registry directly — enrichment is ask-escalation or this gated load;
+ *   • `methods_describe` / `lattice_rings` — the explorer bricks à nu (pure file reads, no model);
+ *   • `trace_tail` — the debug contract: the shared logger's ring buffer, filterable {level, concept, applyId}.
+ *
+ * THIN assembly (doctrine): `createMcpServer` is a PURE JSON-RPC dispatcher (stub-testable, no pipe),
+ * `defaultTools` wires tools onto the existing combos/bricks, `startMcpStdio` is the zero-dep stdio transport
+ * (one JSON-RPC message per line — the MCP stdio framing). GPU-bound model resolution stays in cli.js.
+ * stdout is the PROTOCOL channel: a host process must log to stderr only.
+ *
+ * Register with an MCP host, e.g.:  claude mcp add sg -- node bin/sg mcp --frontier-model <gguf> --store ./stock.json
+ */
+
+var fs = require('fs');
+
+var PROTOCOL_VERSION = '2024-11-05';
+
+/** Read + parse a JSON artifact (a `.sgc` bundle or a bare JSON file). Throws a plain Error on failure. */
+function readJson( file ) {
+	return JSON.parse(fs.readFileSync(String(file), 'utf8'));
+}
+
+/**
+ * The default tool set over the existing bricks. Every tool is { name, description, inputSchema, call(args) };
+ * `call` returns the STRUCTURED result (the server wraps it in MCP content). Wire what the host resolved:
+ * @param w.proxy      a createProxyCache instance (proxy mode: ask/drift/metrics/lattice_load).
+ * @param w.appliance  a createAppliance instance (typed-QA mode: ask returns answer OR the typed refusal).
+ * @param w.logger     the shared logger (trace_tail). Optional.
+ */
+function defaultTools( w ) {
+	w = w || {};
+	var tools = [];
+	var q = { type: 'object', properties: { query: { type: 'string', description: 'the question' } }, required: ['query'] };
+
+	if ( w.appliance || w.proxy ) tools.push({
+		name: 'ask',
+		description: w.appliance
+			? 'Typed QA: answer from the declared domain, or a TYPED REFUSAL naming the missing requirement ({status, answer?, reason?, missing?[]}). A refusal is data, not an error.'
+			: 'Local-first proxy ask: a covered query is served from the verified local stock (0 frontier calls), a miss escalates to the frontier and enriches the stock ({answer, source, cached, cost}).',
+		inputSchema: q,
+		call: async function ( a ) {
+			if ( w.appliance ) return await w.appliance.answer(String(a.query));
+			var r = await w.proxy.answer(String(a.query));
+			return { answer: r.answer, source: r.source, cached: !!r.cached, cost: r.cost };
+		}
+	});
+
+	if ( w.proxy ) {
+		tools.push({
+			name: 'drift',
+			description: 'Anti-drift: invalidate the stock entry covering this query — the next ask re-escalates to the frontier.',
+			inputSchema: q,
+			call: async function ( a ) { await w.proxy.drift(String(a.query)); return { drifted: true, query: String(a.query) }; }
+		});
+		tools.push({
+			name: 'metrics',
+			description: 'The proxy economy readout: served/local/frontier counts, coverage, stock size/reuse.',
+			inputSchema: { type: 'object', properties: {} },
+			call: async function () { return w.proxy.metrics(); }
+		});
+		if ( w.proxy.library && typeof w.proxy.library.loadLattice === 'function' ) tools.push({
+			name: 'lattice_load',
+			description: 'LEARN THROUGH THE GATE: load a `.sgc kind:\'lattice\'` bundle — the held registry grows via the version-gated admission merge (a conflicting ring is REJECTED, never merged). The only registry write path.',
+			inputSchema: { type: 'object', properties: { file: { type: 'string', description: 'path to a .sgc lattice bundle' } }, required: ['file'] },
+			call: async function ( a ) { return w.proxy.library.loadLattice(readJson(a.file)); }
+		});
+	}
+
+	// C9 — the external CRITICAL MIND as a tool (design A5, rhetoric lanes). The host LLM supplies the
+	// topic (+ optional statements/viewpoints); the lib runs ITS local model through the witness-gated
+	// loop and returns the typed LEDGER + a certification-aware verdict. The frame status
+	// (FREE/MATERIAL/DECLARED) is ALWAYS in the payload; below the measured margin bound the verdict is
+	// an honest UNDECIDED — the ledger + counts are the deliverable, never a fake weighing.
+	if ( typeof w.critiqueAsk === 'function' ) tools.push({
+		name: 'critique',
+		description: 'Run the external critical mind on a question: declared viewpoints established through a witness gate over a statement pool, anchored generation of missing theses (0-fabrication), typed ledger, per-side synthesis, and a certification-aware verdict (mechanical only at the measured margin bound; otherwise UNDECIDED with counts). Supply `statements` ("PRO: ..."/"CON: ..." lines) to critique YOUR material (frame MATERIAL) and/or `viewpoints` to declare the frame (DECLARED); with neither, the pool is model-brainstormed and the payload SAYS so (frame FREE).',
+		inputSchema: { type: 'object', properties: {
+			topic: { type: 'string', description: 'the question under critique' },
+			statements: { type: 'array', items: { type: 'string' }, description: 'optional pool, one statement per entry, each prefixed "PRO: " or "CON: "' },
+			viewpoints: { type: 'array', items: { type: 'string' }, description: 'optional declared viewpoints (the decision frame becomes DECLARED)' },
+			polish: { type: 'boolean', description: 'add a presentation-only rewrite of the prose (content-locked)' },
+		}, required: ['topic'] },
+		call: async function ( a ) {
+			if ( !w._criticalMind ) w._criticalMind = require('../combos/critique.js').createCriticalMind({ ask: w.critiqueAsk });
+			var r = await w._criticalMind.run({ topic: String(a.topic), statements: a.statements, viewpoints: a.viewpoints, polish: !!a.polish });
+			// The ITERATION CONTRACT (the server cannot reach the web/host tools — YOU can): OPEN points
+			// and a sub-threshold margin are a TYPED REQUEST FOR DATA. Gather real statements that bear
+			// on them (web, docs, your context), then call `critique` again with `statements` — the frame
+			// upgrades to MATERIAL and the loop converges at the host level (bounded rounds are yours).
+			var open = (r.ledger || []).filter(function ( e ) { return e.status === 'open'; });
+			var advice = null;
+			if ( r.error ) advice = 'pool too small: supply `statements` ("PRO: ..."/"CON: ..." entries).';
+			else if ( open.length || r.verdict === 'UNDECIDED' ) advice = 'This is a typed data request, not a dead end: '
+				+ (open.length ? 'gather statements that genuinely bear on the OPEN points [' + open.map(function ( e ) { return e.text.slice(0, 50); }).join(' · ') + '] ' : '')
+				+ (r.verdict === 'UNDECIDED' ? 'and/or on whichever side you believe is under-evidenced ' : '')
+				+ 'from sources YOU can reach (web/docs), then call critique again with statements=[...] — the frame becomes MATERIAL and the margin can move honestly.';
+			return { frameStatus: r.frameStatus, verdict: r.verdict, basis: r.basis, norm: r.norm, counts: r.counts, margin: r.margin, threshold: r.threshold,
+				ledger: r.ledger, synthesis: r.synthesis, prose: r.polished || r.prose, advice: advice, error: r.error };
+		}
+	});
+
+	// ── the ASSISTANT lanes (design 2026-07-10, owner-approved): the lib as the LLM's assistant. TWO EXPLICIT
+	// LANES — SOFT (advisory, no guarantee, says so) and HARD (gated, typed verdict, NON-BYPASSABLE: forcing
+	// downgrades PROVENANCE, never the admission) — plus the INSTANCES lane (the P3 shared-instance pool).
+
+	// SOFT: `hint` — the orientation menu (certified shapes, slot-glossed). Score lever, no guarantee attached.
+	if ( w.hints && Array.isArray(w.hints.certifiedShapes) ) tools.push({
+		name: 'hint',
+		description: 'SOFT lane (advisory, no guarantee): the certified-shape menu for this query, slot-glossed — orientation lifts the score (+13 to +36 pts measured) but admission is a separate, gated step (`propose`).',
+		inputSchema: q,
+		call: async function ( a ) {
+			var qualifyMenu = require('../combos/mixture-serve.js').qualifyMenu;
+			var shapes = (typeof w.hints.proposeMenu === 'function' && w.hints.proposeMenu(String(a.query))) || w.hints.certifiedShapes;
+			return { menu: w.hints.gloss ? qualifyMenu(shapes, w.hints.gloss) : shapes.slice(), advisory: true, certified: true };
+		}
+	});
+
+	// HARD: `propose` — the negotiate step exposed (the LLM host IS the proposer; bounded rounds are its discipline).
+	if ( w.gate && typeof w.gate.check === 'function' ) tools.push({
+		name: 'propose',
+		description: 'HARD lane (the gate NEVER yields): submit a typed proposal — admitted, or refused with blame + the admissible options ENUMERATED THROUGH the gate (tested, never guessed). force=true does NOT admit: it records the result as untrusted provenance (traced, auditable, outside the certified layer).',
+		inputSchema: { type: 'object', properties: {
+			proposal: { type: 'object', description: 'the typed proposal (domain-shaped)' },
+			force: { type: 'boolean', description: 'insist despite a refusal — recorded untrusted, never admitted' }
+		}, required: ['proposal'] },
+		call: async function ( a ) {
+			var v = await w.gate.check(a.proposal);
+			if ( v && v.ok ) return { status: 'admitted', certified: true };
+			var blame = (v && v.blame) || 'refused';
+			if ( a.force ) {
+				if ( typeof w.gate.record === 'function' ) w.gate.record(a.proposal, { forced: true, blame: blame });
+				return { status: 'recorded-untrusted', certified: false, blame: blame };
+			}
+			var options = [];
+			if ( typeof w.gate.optionsOf === 'function' ) {
+				var cands = (await w.gate.optionsOf(a.proposal)) || [];
+				for ( var i = 0; i < cands.length && options.length < 8; i++ ) {
+					var ov = await w.gate.check(cands[i]);
+					if ( ov && ov.ok ) options.push(cands[i]);
+				}
+			}
+			return { status: 'refused', blame: blame, options: options };
+		}
+	});
+
+	// SOFT: `state_recall` + gated `state_note` — the CERTIFIED TASK-STATE (synthesized by stabilization/JTMS,
+	// bounded projection — not an append log). `note` posts a TYPED fact through the host's SEQUENCED ingest.
+	if ( w.state && typeof w.state.recall === 'function' ) tools.push({
+		name: 'state_recall',
+		description: 'SOFT lane (advisory read): the synthesized task-state — typed facts with provenance + the open frontier, bounded projection (Σ_sep). A drifted premise RETRACTS its facts (JTMS), it does not rot.',
+		inputSchema: { type: 'object', properties: {} },
+		call: async function () { return w.state.recall(); }
+	});
+	if ( w.state && typeof w.state.note === 'function' ) tools.push({
+		name: 'state_note',
+		description: 'Post ONE typed fact ({key, value}) to the task-state through the sequenced ingest (never an out-of-band write); the graph synthesizes — the note lands with provenance and is retractable.',
+		inputSchema: { type: 'object', properties: { key: { type: 'string' }, value: {} }, required: ['key'] },
+		call: async function ( a ) { return await w.state.note({ key: String(a.key), value: a.value }); }
+	});
+
+	// INSTANCES: the P3 shared-instance pool — invoke a concept-method by contract key; list/release instances.
+	if ( w.pool && typeof w.pool.invoke === 'function' ) {
+		tools.push({
+			name: 'graph_invoke',
+			description: 'Invoke a concept-method on its SHARED instance (P3 pool, keyed by contract): stabilizes the seed on a fresh graph in the worker and returns ONLY the bounded projection (summaryFacts + write-footprint) — a refusal (frontier drift / post-violation) is a typed answer.',
+			inputSchema: { type: 'object', properties: {
+				libraryKey: { type: 'string', description: 'the contract/dispatch key' },
+				seed: { type: 'object', description: 'the case seed (slot bindings included)' }
+			}, required: ['libraryKey'] },
+			call: async function ( a ) { return await w.pool.invoke(String(a.libraryKey), { seed: a.seed }); }
+		});
+		tools.push({
+			name: 'graph_instances',
+			description: 'The instance lifecycle: list the pooled graph instances (keys, uses) or release one (`release`: its next invoke re-creates it fresh — deactivation, not deletion of anything learned).',
+			inputSchema: { type: 'object', properties: { release: { type: 'string', description: 'optional key to release' } } },
+			call: async function ( a ) {
+				a = a || {};
+				if ( a.release ) { var okE = w.pool.evict(String(a.release)); return { released: a.release, ok: okE !== false }; }
+				var st = w.pool.stats();
+				return { keys: w.pool.keys(), instances: st.instances, uses: st.uses };
+			}
+		});
+	}
+
+	// SOFT: `plan_sync` — the graph plan mirrored onto the HOST's native task list, AT THE HOST'S CHOICE
+	// (pull-based: the LLM calls it when it wants a mirror, or never). MCP cannot invoke host tools, so the
+	// graph EMITS a typed delta the host applies verbatim (TaskCreate/TaskUpdate, TodoWrite, …).
+	if ( w.plan && typeof w.plan.snapshot === 'function' ) ( function () {
+		var mirrorState = null;
+		tools.push({
+			name: 'plan_sync',
+			description: 'SOFT lane, OPTIONAL (your choice, pull-based): the typed delta between the graph\'s multistep plan and the last sync — apply the ops VERBATIM to your native task system (create/update/complete/reopen). `complete` means GATE-ADMITTED (not claimed); `reopen` fires when a completed step\'s premise DRIFTED (JTMS retraction). reset=true resends the full state.',
+			inputSchema: { type: 'object', properties: { reset: { type: 'boolean', description: 'resend the full plan state' } } },
+			call: async function ( a ) {
+				if ( a && a.reset ) mirrorState = null;
+				var r = require('../authoring/task-mirror.js').diffPlanToTaskOps(await w.plan.snapshot(), mirrorState);
+				mirrorState = r.mirror;
+				return { taskOps: r.ops };
+			}
+		});
+	} )();
+
+	// the explorer bricks à nu — pure file reads, standalone value (no model, no graph).
+	tools.push({
+		name: 'methods_describe',
+		description: 'Describe a concept-method population from a `.sgc kind:\'methods\'` bundle (or a bare library JSON): titles/categories, class distribution, openness (entropy/singletons), coverage vs a declared vocabulary.',
+		inputSchema: { type: 'object', properties: { file: { type: 'string' }, registry: { type: 'string', description: 'optional .sgc lattice file for coverage' } }, required: ['file'] },
+		call: async function ( a ) {
+			var describeLibrary = require('../authoring/method-explorer.js').describeLibrary;
+			var art = readJson(a.file);
+			var source = (art && art.format === 'sgc' && art.kind === 'methods') ? (art.methods || []) : art;
+			var opts = {};
+			if ( a.registry ) { var rf = readJson(a.registry); opts.registry = rf && rf.registry ? rf.registry : rf; }
+			return describeLibrary(source, opts);
+		}
+	});
+	tools.push({
+		name: 'lattice_rings',
+		description: 'List the admitted synonym-ring aliases of a `.sgc kind:\'lattice\'` bundle ({key, member, alias} rows), optionally filtered by member or alias substring.',
+		inputSchema: { type: 'object', properties: { file: { type: 'string' }, filter: { type: 'string', description: 'optional substring over key/member/alias' } }, required: ['file'] },
+		call: async function ( a ) {
+			var lp = require('../authoring/lattice-pack.js');
+			var art = readJson(a.file);
+			var reg;
+			try { reg = lp.unpackLattice(art).registry; }        // a .sgc lattice bundle…
+			catch ( e ) { reg = (art && art.registry) || art; }  // …or a bare registry JSON (à-nu)
+			var rows = lp.ringsOf(reg);
+			if ( a.filter ) {
+				var f = String(a.filter).toLowerCase();
+				rows = rows.filter(function ( r ) { return (r.key + ' ' + r.member + ' ' + r.alias).toLowerCase().indexOf(f) !== -1; });
+			}
+			return { rings: rows, count: rows.length };
+		}
+	});
+
+	if ( w.logger && typeof w.logger.tail === 'function' ) tools.push({
+		name: 'trace_tail',
+		description: 'Debug: the last N records of the shared log ring buffer, filterable by level/concept/target/applyId — the same records `sg trace` joins by applyId.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				n: { type: 'number', description: 'max records (default 20)' },
+				level: { type: 'string' }, concept: { type: 'string' }, target: { type: 'string' }, applyId: { type: 'string' }
+			}
+		},
+		call: async function ( a ) {
+			a = a || {};
+			var filter = {};
+			['level', 'concept', 'target', 'applyId'].forEach(function ( k ) { if ( a[k] != null ) filter[k] = a[k]; });
+			return { records: w.logger.tail(a.n || 20, Object.keys(filter).length ? filter : undefined) };
+		}
+	});
+
+	return tools;
+}
+
+/**
+ * The PURE MCP server: JSON-RPC 2.0 dispatch over a tool set (no pipe — stub-testable; the transport writes
+ * whatever `handle` returns, and a null return means "notification, no response").
+ * @param opts.tools       [{ name, description, inputSchema, call }] (see defaultTools).
+ * @param opts.serverInfo  { name, version } advertised on initialize.
+ * @returns {{ handle: async (msg) => response|null, tools }}
+ */
+function createMcpServer( opts ) {
+	opts = opts || {};
+	var tools = opts.tools || [];
+	var serverInfo = opts.serverInfo || { name: 'skynet-graph', version: '0.0.0' };
+	var byName = {};
+	tools.forEach(function ( t ) { byName[t.name] = t; });
+
+	var reply = function ( id, result ) { return { jsonrpc: '2.0', id: id, result: result }; };
+	var rpcError = function ( id, code, message ) { return { jsonrpc: '2.0', id: id, error: { code: code, message: message } }; };
+
+	return {
+		tools: tools,
+		handle: async function ( msg ) {
+			if ( !msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' ) return rpcError(msg && msg.id != null ? msg.id : null, -32600, 'invalid JSON-RPC 2.0 message');
+			var id = msg.id, method = msg.method, params = msg.params || {};
+			var notification = (id === undefined);
+
+			switch ( method ) {
+				case 'initialize':
+					return reply(id, {
+						protocolVersion: params.protocolVersion || PROTOCOL_VERSION,
+						capabilities: { tools: {} },
+						serverInfo: serverInfo
+					});
+				case 'notifications/initialized':
+				case 'notifications/cancelled':
+					return null;   // notifications get no response
+				case 'ping':
+					return reply(id, {});
+				case 'tools/list':
+					return reply(id, { tools: tools.map(function ( t ) { return { name: t.name, description: t.description, inputSchema: t.inputSchema }; }) });
+				case 'tools/call': {
+					var tool = byName[params.name];
+					if ( !tool ) return rpcError(id, -32602, 'unknown tool: ' + params.name);
+					try {
+						var result = await tool.call(params.arguments || {});
+						// STRUCTURED first (a typed refusal is data): text mirror for hosts without structuredContent.
+						return reply(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result, isError: false });
+					}
+					catch ( e ) {
+						// a TOOL failure is a tool-level error (isError), not a protocol error — the host shows it.
+						return reply(id, { content: [{ type: 'text', text: String(e && e.message || e) }], isError: true });
+					}
+				}
+				default:
+					return notification ? null : rpcError(id, -32601, 'method not found: ' + method);
+			}
+		}
+	};
+}
+
+/**
+ * The zero-dep stdio transport: one JSON-RPC message per line (the MCP stdio framing). Injectable streams for
+ * tests; a parse failure answers a JSON-RPC -32700 instead of crashing the server.
+ * @param o.server  a createMcpServer instance.
+ * @param o.input   readable (default process.stdin);  o.output writable (default process.stdout).
+ * @returns {{ close }}
+ */
+function startMcpStdio( o ) {
+	o = o || {};
+	if ( !o.server || typeof o.server.handle !== 'function' ) throw new Error('startMcpStdio needs o.server (a createMcpServer instance)');
+	var input = o.input || process.stdin, output = o.output || process.stdout;
+	var buf = '';
+	var write = function ( res ) { if ( res ) output.write(JSON.stringify(res) + '\n'); };
+	// responses go out in ARRIVAL order (a promise chain) — a sync parse error must not overtake the async
+	// handling of an earlier message.
+	var chain = Promise.resolve();
+	var enqueue = function ( job ) { chain = chain.then(job, job); };
+	// the parameter CAPTURES the message per line — several lines can coalesce into one data chunk, and a
+	// loop-scoped `var` would leave every queued job handling the LAST parsed message.
+	var handleLine = function ( msg ) {
+		enqueue(function () {
+			return Promise.resolve(o.server.handle(msg)).then(write, function ( e ) {
+				write({ jsonrpc: '2.0', id: msg && msg.id != null ? msg.id : null, error: { code: -32603, message: String(e && e.message || e) } });
+			});
+		});
+	};
+	var onData = function ( d ) {
+		buf += d;
+		var nl;
+		while ( (nl = buf.indexOf('\n')) !== -1 ) {
+			var line = buf.slice(0, nl).trim();
+			buf = buf.slice(nl + 1);
+			if ( !line ) continue;
+			var msg;
+			try { msg = JSON.parse(line); }
+			catch ( e ) { enqueue(function () { write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } }); }); continue; }
+			handleLine(msg);
+		}
+	};
+	input.setEncoding && input.setEncoding('utf8');
+	input.on('data', onData);
+	return { close: function () { input.removeListener('data', onData); } };
+}
+
+/**
+ * stockWiring — a `.sgc kind:'methods'` bundle (or bare {methods}) → the ASSISTANT wirings (hints + gate) over
+ * its certified vocabulary (the per-method class key `structure.taskKind`). The cli.js `--stock` bridge: `hint`
+ * serves the certified menu, `propose` gates a {shape} proposal against the frozen referential and enumerates
+ * the admissible options. Fail-fast on an empty bundle (a silent empty referential would refuse everything).
+ */
+function stockWiring( bundle ) {
+	var methods = (bundle && (bundle.methods || (bundle.format === 'sgc' && bundle.kind === 'methods' && bundle.methods))) || null;
+	var seen = Object.create(null);
+	(methods || []).forEach(function ( m ) { var k = m && m.structure && m.structure.taskKind; if ( k ) seen[k] = true; });
+	var shapes = Object.keys(seen).sort();
+	if ( !shapes.length ) throw new Error('stockWiring: no certified shapes in the stock bundle (need .sgc kind:methods with structure.taskKind per method)');
+	return {
+		hints: { certifiedShapes: shapes },
+		gate: {
+			check: function ( p ) { return shapes.indexOf(p && p.shape) >= 0 ? { ok: true } : { ok: false, blame: 'shape "' + (p && p.shape) + '" ∉ certified referential (' + shapes.length + ' shapes)' }; },
+			optionsOf: function () { return shapes.map(function ( shape ) { return { shape: shape }; }); }
+		}
+	};
+}
+
+module.exports = { createMcpServer: createMcpServer, defaultTools: defaultTools, startMcpStdio: startMcpStdio, stockWiring: stockWiring };