skynet-graph 1.2.0

package/lib/sg/proxy-run.js

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * `sg proxy` session orchestration — the local-first proxy cache run loop, EXTRACTED from cli.js so it is
+ * testable with an injected stub proxy (the model resolution stays GPU-bound in cli.js; this pure loop is
+ * where the single-shot / batch / metrics logic lives). Answers a list of queries against a `createProxyCache`
+ * instance, tracks per-answer provenance, and reports the ECONOMY (frontier calls saved vs a no-cache baseline).
+ */
+
+/**
+ * Run a proxy over a list of queries, in order (so repeats/paraphrases hit the warmed stock).
+ * @param opts.proxy     a createProxyCache instance ({ answer, metrics }).
+ * @param opts.queries   string[] — the session's queries (one entry = one ask).
+ * @param opts.onAnswer  optional (result, index, query) => void — a per-answer hook (CLI streams here).
+ * @returns { results:[{ query, answer, source, cached, cost }], metrics, saved }  — `saved` = frontier calls
+ *          avoided vs answering every query at the frontier (= local hits).
+ */
+async function runProxySession( opts ) {
+	opts = opts || {};
+	var proxy = opts.proxy;
+	var queries = opts.queries || [];
+	if ( !proxy || typeof proxy.answer !== 'function' ) throw new Error('runProxySession needs opts.proxy (a createProxyCache instance)');
+	var results = [];
+	for ( var i = 0; i < queries.length; i++ ) {
+		var q = queries[i];
+		var r = await proxy.answer(q);
+		var row = { query: q, answer: r.answer, source: r.source, cached: !!r.cached, cost: r.cost };
+		results.push(row);
+		if ( typeof opts.onAnswer === 'function' ) opts.onAnswer(row, i, q);
+	}
+	var metrics = (typeof proxy.metrics === 'function') ? proxy.metrics() : null;
+	var saved = metrics ? metrics.local : results.filter(function ( r ) { return r.source === 'local'; }).length;
+	return { results: results, metrics: metrics, saved: saved };
+}
+
+/**
+ * A one-block human report of a proxy session's economy (→ stderr; the answers go to stdout).
+ * @param metrics  the proxy.metrics() readout.
+ * @param saved    frontier calls avoided (= local hits).
+ */
+function formatProxyReport( metrics, saved ) {
+	if ( !metrics ) return 'proxy: (no metrics)';
+	var pct = Math.round((metrics.coverage || 0) * 100);
+	var lines = [
+		'── proxy economy ──────────────────────────',
+		'  served        : ' + metrics.served + ' queries',
+		'  local (cache) : ' + metrics.local + '   frontier: ' + metrics.frontier,
+		'  coverage      : ' + pct + '%  (frontier calls saved: ' + saved + ')'
+	];
+	if ( metrics.stock && metrics.stock.size != null ) {
+		var s = metrics.stock;
+		var stockLine = '  stock         : ' + s.size + ' entries';
+		if ( s.reuseRate != null ) stockLine += '   reuse: ' + Math.round(s.reuseRate * 100) + '%   deadWeight: ' + (s.deadWeight != null ? s.deadWeight : '?');
+		if ( s.evicted != null && s.evicted.count ) stockLine += '   evicted: ' + s.evicted.count;
+		lines.push(stockLine);
+	}
+	lines.push('────────────────────────────────────────────');
+	return lines.join('\n');
+}
+
+module.exports = { runProxySession: runProxySession, formatProxyReport: formatProxyReport };

package/lib/sg/serve-demo.js

@@ -0,0 +1,185 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * `sg serve` — a MINIMAL OpenAI-compatible proxy DEMO over any chat backend. Point an OpenAI client's
+ * `baseURL` at it (official SDKs, LangChain, Open WebUI, curl — zero integration code): a repeated query
+ * is answered from an exact-match SESSION cache at 0 backend calls, and every response says where it came
+ * from (`x-sg-served-from: cache|backend`, `x-sg-saved`).
+ *
+ * WHAT IT IS / IS NOT: this is the demo of the GESTURE — an in-memory, per-process cache keyed on the
+ * exact query text, gone on restart. It is NOT a knowledge store: no verification, no typed coverage, no
+ * persistence, no freshness. The professional appliance replaces the session cache with maintained,
+ * verified knowledge served under the same wire contract.
+ *
+ * THE v1 WIRE CONTRACT (same shape as the appliance):
+ *   • POST /v1/chat/completions — the QUERY is the LAST `user` turn (string content or text parts).
+ *   • `stream:true` is SIMULATED: the answer is computed in one block, then emitted as standard SSE
+ *     chunks (role delta → content delta → finish → [DONE]) so streaming clients work unchanged.
+ *   • GET /v1/models — one model row, so SDK bootstraps and model pickers work.
+ *   • Token counts are NOT estimated: 0 means "not counted", never a made-up number.
+ *
+ * THIN split (doctrine): `createServeDemoHandler` is a PURE request handler (stub-testable, no socket),
+ * `startServeDemoServer` is the zero-dep node:http wrapper; backend resolution stays in cli.js.
+ */
+
+/** The text of an OpenAI message `content` (a string, or an array of {type:'text',text} parts). */
+function textOf( content ) {
+	if ( typeof content === 'string' ) return content;
+	if ( Array.isArray(content) )
+		return content.filter(function ( p ) { return p && (p.type === 'text' || typeof p.text === 'string'); })
+		              .map(function ( p ) { return p.text; }).join('\n');
+	return '';
+}
+
+/** The demo QUERY of an OpenAI `messages` array = the LAST user turn's text, or null (no user turn). */
+function queryOfMessages( messages ) {
+	if ( !Array.isArray(messages) ) return null;
+	for ( var i = messages.length - 1; i >= 0; i-- ) {
+		if ( messages[i] && messages[i].role === 'user' ) {
+			var t = textOf(messages[i].content).trim();
+			return t.length ? t : null;
+		}
+	}
+	return null;
+}
+
+/**
+ * The PURE request handler (no socket): `(req) -> res` over a chat backend.
+ * @param opts.ask    REQUIRED async ({system,user}) -> text — the backend (a gguf, an endpoint, a stub).
+ * @param opts.model  the model id advertised on /v1/models and echoed when the client sends none
+ *                    (default 'skynet-graph-serve-demo').
+ * @param opts.onAnswer optional ({query, answer, source}) => void — a per-answer hook (the CLI logs here).
+ * @returns async ({ method, url, body }) => { status, headers, body } — or { status, headers, sse:[frames] }
+ *          for a simulated stream (the http wrapper writes each frame as an SSE event).
+ */
+function createServeDemoHandler( opts ) {
+	opts = opts || {};
+	var ask = opts.ask;
+	if ( typeof ask !== 'function' ) throw new Error('createServeDemoHandler needs opts.ask (async ({system,user}) -> text)');
+	var modelId = opts.model || 'skynet-graph-serve-demo';
+	var cache = new Map();   // exact query text -> the backend's verbatim answer (session-lifetime)
+	var saved = 0;           // backend calls avoided so far
+	var nextId = 0;
+
+	var JSON_H = { 'content-type': 'application/json' };
+	var oaiError = function ( status, message, type ) {
+		return { status: status, headers: JSON_H, body: { error: { message: message, type: type || 'invalid_request_error' } } };
+	};
+
+	return async function handle( req ) {
+		req = req || {};
+		var method = String(req.method || 'GET').toUpperCase();
+		var url = String(req.url || '/').split('?')[0];
+
+		if ( url === '/v1/models' ) {
+			if ( method !== 'GET' ) return oaiError(405, 'method ' + method + ' not allowed on /v1/models');
+			return {
+				status: 200, headers: JSON_H,
+				body: { object: 'list', data: [{ id: modelId, object: 'model', created: Math.floor(Date.now() / 1000), owned_by: 'skynet-graph' }] }
+			};
+		}
+
+		if ( url === '/v1/chat/completions' ) {
+			if ( method !== 'POST' ) return oaiError(405, 'method ' + method + ' not allowed on /v1/chat/completions');
+			var b = req.body;
+			if ( !b || typeof b !== 'object' ) return oaiError(400, 'request body must be a JSON object');
+			var q = queryOfMessages(b.messages);
+			if ( q == null ) return oaiError(400, 'messages must contain at least one non-empty user turn');
+
+			var source, answer;
+			if ( cache.has(q) ) { source = 'cache'; answer = cache.get(q); saved++; }
+			else {
+				try { answer = String(await ask({ user: q })); }
+				catch ( e ) { return oaiError(500, String(e && e.message || e), 'server_error'); }
+				cache.set(q, answer);
+				source = 'backend';
+			}
+			if ( typeof opts.onAnswer === 'function' ) opts.onAnswer({ query: q, answer: answer, source: source });
+
+			// PROVENANCE — on the wire for every completion (headers + usage.sg_* mirror).
+			var prov = { 'x-sg-served-from': source, 'x-sg-saved': String(saved) };
+			var usage = {
+				prompt_tokens: 0, completion_tokens: 0, total_tokens: 0,   // 0 = not counted (never estimated)
+				sg_served_from: source, sg_saved: saved
+			};
+			var id = 'chatcmpl-sgdemo' + (++nextId) + '-' + Date.now().toString(36);
+			var created = Math.floor(Date.now() / 1000);
+			var modelOut = (typeof b.model === 'string' && b.model) ? b.model : modelId;
+
+			if ( b.stream === true ) {
+				var chunk = function ( delta, finish ) {
+					return 'data: ' + JSON.stringify({
+						id: id, object: 'chat.completion.chunk', created: created, model: modelOut,
+						choices: [{ index: 0, delta: delta, finish_reason: finish || null }]
+					});
+				};
+				return {
+					status: 200,
+					headers: Object.assign({ 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' }, prov),
+					sse: [chunk({ role: 'assistant', content: '' }), chunk({ content: answer }), chunk({}, 'stop'), 'data: [DONE]']
+				};
+			}
+			return {
+				status: 200, headers: Object.assign({}, JSON_H, prov),
+				body: {
+					id: id, object: 'chat.completion', created: created, model: modelOut,
+					choices: [{ index: 0, message: { role: 'assistant', content: answer }, finish_reason: 'stop' }],
+					usage: usage
+				}
+			};
+		}
+
+		return oaiError(404, 'unknown route ' + method + ' ' + url);
+	};
+}
+
+/**
+ * The zero-dep node:http wrapper around a handler (JSON body in, JSON or SSE out).
+ * @param o.handler  the createServeDemoHandler function.
+ * @param o.port     default 4747;  o.host default 127.0.0.1 (LOCAL by default, on purpose);
+ * @param o.maxBody  request-body cap (default 1 MiB).  o.onReady  optional () => void once listening.
+ * @returns the http.Server (close it to stop).
+ */
+function startServeDemoServer( o ) {
+	o = o || {};
+	if ( typeof o.handler !== 'function' ) throw new Error('startServeDemoServer needs o.handler (a createServeDemoHandler function)');
+	var http = require('http');
+	var LIM = o.maxBody || (1 << 20);
+	var srv = http.createServer(function ( req, res ) {
+		var chunks = [], size = 0, over = false;
+		req.on('data', function ( d ) {
+			size += d.length;
+			if ( size > LIM ) { over = true; req.destroy(); return; }
+			chunks.push(d);
+		});
+		req.on('error', function () { /* destroyed over-limit request */ });
+		req.on('end', function () {
+			if ( over ) { try { res.writeHead(413, { 'content-type': 'application/json' }); res.end(JSON.stringify({ error: { message: 'request body over ' + LIM + ' bytes', type: 'invalid_request_error' } })); } catch ( e ) {} return; }
+			var body = null, raw = Buffer.concat(chunks).toString('utf8');
+			if ( raw.length ) { try { body = JSON.parse(raw); } catch ( e ) { body = undefined; } }   // undefined = present but invalid JSON → 400 in the handler
+			Promise.resolve(o.handler({ method: req.method, url: req.url, headers: req.headers, body: body }))
+				.catch(function ( e ) { return { status: 500, headers: { 'content-type': 'application/json' }, body: { error: { message: String(e && e.message || e), type: 'server_error' } } }; })
+				.then(function ( out ) {
+					out = out || { status: 500, headers: {}, body: { error: { message: 'empty handler result', type: 'server_error' } } };
+					if ( out.sse ) {
+						res.writeHead(out.status || 200, out.headers || {});
+						(out.sse || []).forEach(function ( f ) { res.write(f + '\n\n'); });
+						res.end();
+						return;
+					}
+					var txt = JSON.stringify(out.body != null ? out.body : {});
+					res.writeHead(out.status || 200, Object.assign({ 'content-length': Buffer.byteLength(txt) }, out.headers || {}));
+					res.end(txt);
+				});
+		});
+	});
+	srv.listen(o.port != null ? o.port : 4747, o.host || '127.0.0.1', o.onReady);
+	return srv;
+}
+
+module.exports = { createServeDemoHandler: createServeDemoHandler, startServeDemoServer: startServeDemoServer, queryOfMessages: queryOfMessages };

package/lib/sg/serve.js

@@ -0,0 +1,205 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * `sg serve` — the OpenAI-COMPATIBLE endpoint over the C6 proxy cache (roadmap FINIR, F1). Any client of the
+ * OpenAI ecosystem (official SDKs, LangChain, Open WebUI, curl) integrates by pointing `baseURL` at this
+ * server — zero integration code. Every completion is `createProxyCache.answer` underneath: a COVERED query is
+ * served from the verified local stock at 0 frontier calls, a miss escalates to the frontier and enriches the
+ * stock in passing (0 hallucination — verified stock or escalate; a miss always answers, no false neg).
+ *
+ * THIN assembly (doctrine): `createServeHandler` is a PURE request handler (stub-testable, no socket — the same
+ * split as proxy-run.js), `startServeServer` is the zero-dep node:http wrapper, and the GPU-bound model
+ * resolution stays in cli.js.
+ *
+ * THE v1 WIRE CONTRACT:
+ *   • POST /v1/chat/completions — the QUERY is the LAST `user` turn (string content or text parts). Multi-turn
+ *     history and client system prompts are NOT part of the cache identity: this is a QA proxy-cache, not a
+ *     dialog engine (the honest v1 boundary — a context-dependent flow belongs on the frontier directly, and
+ *     `coverageCheck` is the backstop that rejects an ill-fitting hit before it is served).
+ *   • `stream:true` is SIMULATED (arbitrage F0-3): the answer is computed in one block, then emitted as
+ *     standard SSE chunks (role delta → content delta → finish → [DONE]) so streaming clients work unchanged.
+ *     A true frontier passthrough stream is a later opt-in — the local stock answers in one block anyway.
+ *   • PROVENANCE on every completion (the debug contract): headers `x-sg-served-from: local|frontier`,
+ *     `x-sg-arm`, `x-sg-cost`, `x-sg-coverage`, `x-sg-saved` — plus `x-sg-sgc-version` (the loaded `.sgc`
+ *     catalog state, host-supplied via `opts.sgcVersion`, read per request so a refresh shows live) —
+ *     mirrored as `usage.sg_*` extension fields (an OpenAI `usage` object tolerates extra keys). Token
+ *     counts are NOT estimated: 0 means "not counted", never a made-up number.
+ *   • GET /v1/models — one model row (the proxy), so SDK bootstraps and model pickers work.
+ */
+
+/** The text of an OpenAI message `content` (a string, or an array of {type:'text',text} parts). */
+function textOf( content ) {
+	if ( typeof content === 'string' ) return content;
+	if ( Array.isArray(content) )
+		return content.filter(function ( p ) { return p && (p.type === 'text' || typeof p.text === 'string'); })
+		              .map(function ( p ) { return p.text; }).join('\n');
+	return '';
+}
+
+/** The proxy QUERY of an OpenAI `messages` array = the LAST user turn's text, or null (no user turn). */
+function queryOfMessages( messages ) {
+	if ( !Array.isArray(messages) ) return null;
+	for ( var i = messages.length - 1; i >= 0; i-- ) {
+		if ( messages[i] && messages[i].role === 'user' ) {
+			var t = textOf(messages[i].content).trim();
+			return t.length ? t : null;
+		}
+	}
+	return null;
+}
+
+/**
+ * The PURE request handler (no socket): `(req) -> res` over a `createProxyCache` instance.
+ * @param opts.proxy  REQUIRED — a createProxyCache instance ({ answer, metrics }).
+ * @param opts.model  the model id advertised on /v1/models and echoed when the client sends none
+ *                    (default 'skynet-graph-proxy').
+ * @param opts.onAnswer optional (row) => void — a per-answer hook ({query, answer, source, cached, cost};
+ *                    the CLI logs/streams here, same seam as runProxySession).
+ * @param opts.sgcVersion optional string or () => string — the loaded `.sgc` catalog state (e.g.
+ *                    'units@1.0.0,laws@2.1.0'). When non-empty it rides every completion as the
+ *                    `x-sg-sgc-version` header + `usage.sg_sgc_version` (stock-freshness provenance).
+ *                    The function form is read PER REQUEST so a catalog refresh shows up live. The lib
+ *                    has no catalog notion of its own — the host (an appliance) owns the value.
+ * @returns async ({ method, url, body }) => { status, headers, body } — or { status, headers, sse:[frames] }
+ *          for a simulated stream (the http wrapper writes each frame as an SSE event).
+ */
+function createServeHandler( opts ) {
+	opts = opts || {};
+	var proxy = opts.proxy;
+	if ( !proxy || typeof proxy.answer !== 'function' ) throw new Error('createServeHandler needs opts.proxy (a createProxyCache instance)');
+	var modelId = opts.model || 'skynet-graph-proxy';
+	var nextId = 0;
+
+	var JSON_H = { 'content-type': 'application/json' };
+	var oaiError = function ( status, message, type ) {
+		return { status: status, headers: JSON_H, body: { error: { message: message, type: type || 'invalid_request_error' } } };
+	};
+
+	return async function handle( req ) {
+		req = req || {};
+		var method = String(req.method || 'GET').toUpperCase();
+		var url = String(req.url || '/').split('?')[0];
+
+		if ( url === '/v1/models' ) {
+			if ( method !== 'GET' ) return oaiError(405, 'method ' + method + ' not allowed on /v1/models');
+			return {
+				status: 200, headers: JSON_H,
+				body: { object: 'list', data: [{ id: modelId, object: 'model', created: Math.floor(Date.now() / 1000), owned_by: 'skynet-graph' }] }
+			};
+		}
+
+		if ( url === '/v1/chat/completions' ) {
+			if ( method !== 'POST' ) return oaiError(405, 'method ' + method + ' not allowed on /v1/chat/completions');
+			var b = req.body;
+			if ( !b || typeof b !== 'object' ) return oaiError(400, 'request body must be a JSON object');
+			var q = queryOfMessages(b.messages);
+			if ( q == null ) return oaiError(400, 'messages must contain at least one non-empty user turn');
+
+			var r;
+			try { r = await proxy.answer(q); }
+			catch ( e ) { return oaiError(500, String(e && e.message || e), 'server_error'); }
+			var m = (typeof proxy.metrics === 'function') ? proxy.metrics() : null;
+			if ( typeof opts.onAnswer === 'function' )
+				opts.onAnswer({ query: q, answer: r.answer, source: r.source, cached: !!r.cached, cost: r.cost });
+
+			// PROVENANCE — on the wire for every completion (headers + usage.sg_* mirror).
+			var sgcv = (typeof opts.sgcVersion === 'function') ? opts.sgcVersion() : opts.sgcVersion;
+			var prov = {
+				'x-sg-served-from': String(r.source || ''),
+				'x-sg-arm'        : String(r.arm || ''),
+				'x-sg-cost'       : String(r.cost != null ? r.cost : '')
+			};
+			if ( m ) {
+				prov['x-sg-coverage'] = String(Math.round((m.coverage || 0) * 100) / 100);
+				prov['x-sg-saved']    = String(m.local);   // frontier calls avoided so far = local hits
+			}
+			if ( sgcv ) prov['x-sg-sgc-version'] = String(sgcv);
+			var usage = {
+				prompt_tokens: 0, completion_tokens: 0, total_tokens: 0,   // 0 = not counted (never estimated)
+				sg_served_from: r.source, sg_cached: !!r.cached,
+				sg_saved: m ? m.local : undefined, sg_frontier_calls: m ? m.frontier : undefined,
+				sg_coverage: m ? m.coverage : undefined,
+				sg_sgc_version: sgcv ? String(sgcv) : undefined
+			};
+			var id = 'chatcmpl-sg' + (++nextId) + '-' + Date.now().toString(36);
+			var created = Math.floor(Date.now() / 1000);
+			var modelOut = (typeof b.model === 'string' && b.model) ? b.model : modelId;
+
+			if ( b.stream === true ) {
+				// SIMULATED stream: the standard SSE chunk sequence over the already-computed answer.
+				var chunk = function ( delta, finish ) {
+					return 'data: ' + JSON.stringify({
+						id: id, object: 'chat.completion.chunk', created: created, model: modelOut,
+						choices: [{ index: 0, delta: delta, finish_reason: finish || null }]
+					});
+				};
+				return {
+					status: 200,
+					headers: Object.assign({ 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' }, prov),
+					sse: [chunk({ role: 'assistant', content: '' }), chunk({ content: String(r.answer) }), chunk({}, 'stop'), 'data: [DONE]']
+				};
+			}
+			return {
+				status: 200, headers: Object.assign({}, JSON_H, prov),
+				body: {
+					id: id, object: 'chat.completion', created: created, model: modelOut,
+					choices: [{ index: 0, message: { role: 'assistant', content: String(r.answer) }, finish_reason: 'stop' }],
+					usage: usage
+				}
+			};
+		}
+
+		return oaiError(404, 'unknown route ' + method + ' ' + url);
+	};
+}
+
+/**
+ * The zero-dep node:http wrapper around a handler (JSON body in, JSON or SSE out).
+ * @param o.handler  the createServeHandler function.
+ * @param o.port     default 4747;  o.host default 127.0.0.1;  o.maxBody request-body cap (default 1 MiB).
+ * @param o.onReady  optional () => void once listening.
+ * @returns the http.Server (close it to stop).
+ */
+function startServeServer( o ) {
+	o = o || {};
+	if ( typeof o.handler !== 'function' ) throw new Error('startServeServer needs o.handler (a createServeHandler function)');
+	var http = require('http');
+	var LIM = o.maxBody || (1 << 20);
+	var srv = http.createServer(function ( req, res ) {
+		var chunks = [], size = 0, over = false;
+		req.on('data', function ( d ) {
+			size += d.length;
+			if ( size > LIM ) { over = true; req.destroy(); return; }
+			chunks.push(d);
+		});
+		req.on('error', function () { /* destroyed over-limit request — response below or dropped */ });
+		req.on('end', function () {
+			if ( over ) { try { res.writeHead(413, { 'content-type': 'application/json' }); res.end(JSON.stringify({ error: { message: 'request body over ' + LIM + ' bytes', type: 'invalid_request_error' } })); } catch ( e ) {} return; }
+			var body = null, raw = Buffer.concat(chunks).toString('utf8');
+			if ( raw.length ) { try { body = JSON.parse(raw); } catch ( e ) { body = undefined; } }   // undefined = present but invalid JSON → 400 in the handler
+			Promise.resolve(o.handler({ method: req.method, url: req.url, headers: req.headers, body: body }))
+				.catch(function ( e ) { return { status: 500, headers: { 'content-type': 'application/json' }, body: { error: { message: String(e && e.message || e), type: 'server_error' } } }; })
+				.then(function ( out ) {
+					out = out || { status: 500, headers: {}, body: { error: { message: 'empty handler result', type: 'server_error' } } };
+					if ( out.sse ) {
+						res.writeHead(out.status || 200, out.headers || {});
+						(out.sse || []).forEach(function ( f ) { res.write(f + '\n\n'); });
+						res.end();
+						return;
+					}
+					var txt = JSON.stringify(out.body != null ? out.body : {});
+					res.writeHead(out.status || 200, Object.assign({ 'content-length': Buffer.byteLength(txt) }, out.headers || {}));
+					res.end(txt);
+				});
+		});
+	});
+	srv.listen(o.port != null ? o.port : 4747, o.host || '127.0.0.1', o.onReady);
+	return srv;
+}
+
+module.exports = { createServeHandler: createServeHandler, startServeServer: startServeServer, queryOfMessages: queryOfMessages };

package/lib/sg/trace.js

@@ -0,0 +1,118 @@
+/*
+ * 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';
+/**
+ * Concept-apply trace collector + render helpers — the engine behind the `sg`
+ * inspector CLI. Host-side (not part of the engine): wire `cfg.onConceptApply =
+ * trace.onConceptApply`, run the graph, then write/inspect the artifact.
+ *
+ *   const trace = createTrace();
+ *   new Graph(seed, { ..., onConceptApply: trace.onConceptApply }, conceptMap);
+ *   // on stabilize:
+ *   trace.write('run.json', graph, { objective });
+ */
+const fs = require('fs');
+
+function createTrace() {
+	const records = [];
+	const api = {
+		records,
+		onConceptApply( rec ) { records.push(rec); },
+		// bundle records + a final graph snapshot (serialize()) for post-hoc inspection
+		toArtifact( graph, meta ) {
+			return { meta: meta || {}, snapshot: graph ? graph.serialize() : null, records };
+		},
+		write( path, graph, meta ) {
+			fs.writeFileSync(path, JSON.stringify(api.toArtifact(graph, meta), null, 2));
+			return path;
+		}
+	};
+	return api;
+}
+
+// compact one-line summary of a patch (the applied mutation template)
+function patchSummary( patch ) {
+	if ( !patch ) return '';
+	const arr = Array.isArray(patch) ? patch : [patch];
+	const segs = arr.filter(o => o && o.Segment).length;
+	const parts = [];
+	if ( segs ) parts.push('+' + segs + ' seg' + (segs > 1 ? 's' : ''));
+	for ( const o of arr ) {
+		for ( const k of Object.keys(o || {}) ) {
+			if ( k === '_id' || k === '$$_id' || k === '$_id' || k === '_rev' || k === 'Segment' || k === 'Node' ) continue;
+			let v = o[k];
+			v = (v && typeof v === 'object') ? (Array.isArray(v) ? '[' + v.length + ']' : JSON.stringify(v)) : String(v);
+			if ( v.length > 24 ) v = v.slice(0, 23) + '…';
+			parts.push(k + ':' + v);
+		}
+	}
+	const s = parts.join(' ');
+	return s.length > 48 ? s.slice(0, 47) + '…' : s;
+}
+
+// one summary row per record (for `sg trace`)
+function summarizeTrace( records ) {
+	return records.map(( r, i ) => ({
+		n      : i,
+		rev    : r.rev,
+		concept: r.conceptName,
+		target : r.targetId,
+		kind   : r.kind,
+		patch  : patchSummary(r.patch),
+		ms     : Math.round(r.ms || 0)
+	}));
+}
+
+// per-concept rollup (count + total ms), heaviest first (for finding expensive branches)
+function perConcept( records ) {
+	const by = {};
+	for ( const r of records ) {
+		const c = by[r.conceptName] = by[r.conceptName] || { concept: r.conceptName, count: 0, totalMs: 0 };
+		c.count++;
+		c.totalMs += Math.round(r.ms || 0);
+	}
+	return Object.keys(by).map(k => by[k]).sort(( a, b ) => b.totalMs - a.totalMs);
+}
+
+// records whose patch flagged an llmError (for `sg errors`)
+function errorRecords( records ) {
+	return records.filter(r => JSON.stringify(r.patch || '').includes('llmError'));
+}
+
+// full detail of one record (for `sg show <n>`)
+function formatRecord( rec ) {
+	if ( !rec ) return '(no such record)';
+	const lines = [];
+	lines.push(`#${rec.rev}  ${rec.conceptName}  ->  ${rec.targetId}   [${rec.kind}, ${Math.round(rec.ms || 0)}ms]`);
+	if ( rec.why && rec.why.length ) {
+		lines.push('  why fired:');
+		for ( const w of rec.why ) {
+			let v = (w.value && typeof w.value === 'object') ? JSON.stringify(w.value) : String(w.value);
+			lines.push(`    ${w.require} = ${v}` + (w.producedAtRev != null ? `  @rev ${w.producedAtRev}` : ''));
+		}
+	}
+	if ( rec.prompt ) {
+		if ( rec.prompt.system ) lines.push('  prompt.system: ' + rec.prompt.system);
+		if ( rec.prompt.user ) lines.push('  prompt.user:   ' + rec.prompt.user);
+	}
+	if ( rec.reply != null ) lines.push('  reply: ' + (typeof rec.reply === 'string' ? rec.reply : JSON.stringify(rec.reply)));
+	lines.push('  patch: ' + JSON.stringify(rec.patch));
+	return lines.join('\n');
+}
+
+module.exports = { createTrace, summarizeTrace, perConcept, errorRecords, formatRecord, patchSummary };

package/lib/studio/protocol.js

@@ -0,0 +1,45 @@
+/*
+ * 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';
+/**
+ * The studio wire contract (shared by server.js and the frontend ws client).
+ *
+ * Client -> server : { id, sessionId?, op, args }   (op in OPS)
+ * Server -> client : { id, ok, result | error }     (op responses)
+ *                  | { type, sessionId, payload }    (unsolicited events, type in EVENTS)
+ */
+
+// operations a client may invoke (one Session/Studio method each)
+const OPS = Object.freeze([
+	'listCorpora', 'loadCorpus', 'reset',
+	'mutate', 'run', 'state',
+	'conceptTree', 'getConcept', 'validateConcept', 'patchConcept', 'addConcept', 'forkPlan',
+	'grammarGraph', 'corpusManifest', 'exportCorpus', 'importCorpus', 'providerTrace', 'mergePreview',
+	'revisions', 'snapshot', 'rollback', 'diff',
+	'fork', 'merge', 'selectSession',
+	'registry', 'declareKey', 'proposeAlias', 'retractAlias', 'creditAlias', 'exportLattice', 'importLattice',
+	'prompt'
+]);
+
+// events the server pushes to subscribers
+const EVENTS = Object.freeze([
+	'conceptApply', 'stabilize', 'mutation', 'rollback', 'state', 'retract',
+	'forks', 'promptProgress', 'promptAnswer', 'error'
+]);
+
+module.exports = { OPS, EVENTS };