skynet-graph 1.2.0

package/lib/providers/llm.js

@@ -0,0 +1,236 @@
+/*
+ * 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';
+/**
+ * LLM provider — backend-agnostic.
+ *
+ * `createLLMProvider({ ask })` returns a provider-map fragment `{ LLM: { complete } }`
+ * where `complete` is a generic concept<->prompt runner: it builds a prompt from the
+ * concept's `_schema.prompt` (or argz[0]), calls the injected `ask`, optionally salvages
+ * JSON, and writes the result back as typed facts. A host plugs ANY backend by passing
+ * its own `ask` — the bundled Anthropic-style `ask` is only the default.
+ *
+ * Concept wiring:
+ *   { "provider": ["LLM::complete"],
+ *     "prompt": { "system": "...", "user": "Step: ${label}", "maxTokens": 500,
+ *                 "json": true, "as": "Classification" } }
+ *   - `user`/`system` strings interpolate `${ref}` tokens, resolved against the scope
+ *     via graph.getRef (objects are JSON-stringified).
+ *   - `json:true` -> parse the reply; if it's a plain object (and no `as`), merge its
+ *     keys as facts; with `as`, store the parsed/raw reply under that key.
+ *   - `facts:{<key>:<spec>}` -> the CANONICALIZATION BARRIER (doc/MODELISATION.md §4.2):
+ *     write ONLY those discrete keys (enum-snapped / grain-rounded / typed) as *tracked*
+ *     facts, the free reply text under an *untracked* `prose` key, and a stable
+ *     `<name>FactsDigest` memo key. This is what keeps downstream `require`/`ensure`
+ *     edges keyed on stable discrete facts instead of fragmenting on prose (K1).
+ *   - on backend error the concept is still flagged + `llmError` recorded, so the graph
+ *     can settle instead of hanging.
+ */
+
+var canonicalize = require('./canonicalize');
+
+// ---- backend clients (Node global fetch). Configurable via env / opts. `makeAsk` dispatches on
+// the API flavour (opts.api / env LLM_API): 'anthropic' (default, /v1/messages) or 'openai'
+// (/v1/chat/completions). A host can always inject its own `ask` instead. ----
+function makeAnthropicAsk( opts ) {
+	opts = opts || {};
+	var BASE  = opts.base  || process.env.LLM_BASE  || 'http://localhost:3000';
+	var MODEL = opts.model || process.env.LLM_MODEL || 'claude-3-5-sonnet-20241022';
+	var KEY   = opts.key   || process.env.LLM_KEY   || 'sk-local';
+	return async function ask( { system, user, maxTokens = 1024, temperature } ) {
+		// `temperature` (undefined unless a host drives it, e.g. from the plasticity ledger) is dropped
+		// by JSON.stringify when undefined, so the request body is unchanged for callers that don't set it.
+		var res = await fetch(BASE.replace(/\/$/, '') + '/v1/messages', {
+			method : 'POST',
+			headers: {
+				'content-type'     : 'application/json',
+				'x-api-key'        : KEY,
+				'authorization'    : 'Bearer ' + KEY,
+				'anthropic-version': '2023-06-01'
+			},
+			body: JSON.stringify({ model: MODEL, max_tokens: maxTokens, system: system, temperature: temperature, messages: [{ role: 'user', content: user }] })
+		});
+		if ( !res.ok ) throw new Error('LLM HTTP ' + res.status + ': ' + (await res.text()).slice(0, 200));
+		var j = await res.json();
+		if ( j.error ) throw new Error('LLM error: ' + (j.error.message || JSON.stringify(j.error)).slice(0, 200));
+		return (j.content || []).map(function ( b ) { return b.text || ''; }).join('');
+	};
+}
+
+// OpenAI-compatible chat-completions client (vLLM / llama.cpp / LM Studio / a local OpenAI shim).
+// Reads `choices[0].message.content`; for REASONING models that spend the token budget on a separate
+// `reasoning_content` and return empty `content`, it falls back to that text (cleaner than the
+// Anthropic shim, which mixes the thinking into the text and relies on JSON salvage).
+function makeOpenAIAsk( opts ) {
+	opts = opts || {};
+	var BASE  = opts.base  || process.env.LLM_BASE  || 'http://localhost:5000';
+	var MODEL = opts.model || process.env.LLM_MODEL || 'default';
+	var KEY   = opts.key   || process.env.LLM_KEY   || 'sk-local';
+	// extra request-body fields merged into every call — e.g. disable a reasoning model's "thinking":
+	//   extraBody: { chat_template_kwargs: { enable_thinking: false } }   (Qwen3 on vLLM/SGLang)
+	var EXTRA = opts.extraBody || (process.env.LLM_NO_THINK ? { chat_template_kwargs: { enable_thinking: false } } : null);
+	// ASSISTANT PREFILL (no-think for reasoning models that IGNORE chat_template_kwargs — e.g. Qwen3.x in LM
+	// Studio): seed a trailing assistant turn with CLOSED think tags so the model skips reasoning and emits the
+	// answer directly (the server returns only the continuation, not the prefill). Verified the kwargs path is a
+	// no-op there while this yields a clean one-word reply. Opt-in: opts.assistantPrefill, or LLM_NO_THINK env
+	// (which also sends the kwargs above — harmless if ignored). Set opts.assistantPrefill='' to disable.
+	var PREFILL = opts.assistantPrefill != null ? opts.assistantPrefill
+		: (process.env.LLM_NO_THINK ? '<think>\n\n</think>\n\n' : null);
+	return async function ask( { system, user, maxTokens = 1024, temperature } ) {
+		var messages = [];
+		if ( system ) messages.push({ role: 'system', content: system });
+		messages.push({ role: 'user', content: user });
+		if ( PREFILL ) messages.push({ role: 'assistant', content: PREFILL });   // continuation seed → skips thinking
+		var res = await fetch(BASE.replace(/\/$/, '') + '/v1/chat/completions', {
+			method : 'POST',
+			headers: { 'content-type': 'application/json', 'authorization': 'Bearer ' + KEY },
+			body   : JSON.stringify(Object.assign({ model: MODEL, max_tokens: maxTokens, temperature: temperature, messages: messages }, EXTRA))
+		});
+		if ( !res.ok ) throw new Error('LLM HTTP ' + res.status + ': ' + (await res.text()).slice(0, 200));
+		var j = await res.json();
+		if ( j.error ) throw new Error('LLM error: ' + (j.error.message || JSON.stringify(j.error)).slice(0, 200));
+		var m = (j.choices && j.choices[0] && j.choices[0].message) || {};
+		var content = m.content || '';
+		if ( !String(content).trim() && m.reasoning_content ) content = m.reasoning_content;
+		return content;
+	};
+}
+
+function makeAsk( opts ) {
+	opts = opts || {};
+	var api = opts.api || process.env.LLM_API;
+	return api === 'openai' ? makeOpenAIAsk(opts) : makeAnthropicAsk(opts);
+}
+
+// ---- Robust against "thinking" models: returns the LAST balanced {...}/[...] that JSON.parses. ----
+function parseJSON( text ) {
+	// strict first: if the WHOLE reply is valid JSON, use it verbatim — this preserves a nested
+	// wrapper like `{"steps":[{…}]}` that the salvage heuristic below would mis-grab (it returns the
+	// LAST balanced object = an inner element, dropping the wrapper key). Common with no-think replies.
+	try { return JSON.parse(String(text).trim()); } catch ( _e ) { /* fall through to salvage */ }
+	var fence = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+	if ( fence ) { try { return JSON.parse(fence[1]); } catch ( e ) { /* fall through */ } }
+	var candidates = [];
+	for ( var i = 0; i < text.length; i++ ) {
+		var open = text[i];
+		if ( open !== '{' && open !== '[' ) continue;
+		var close = open === '{' ? '}' : ']';
+		var depth = 0, inStr = false, esc = false;
+		for ( var j = i; j < text.length; j++ ) {
+			var ch = text[j];
+			if ( inStr ) { if ( esc ) esc = false; else if ( ch === '\\' ) esc = true; else if ( ch === '"' ) inStr = false; continue; }
+			if ( ch === '"' ) inStr = true;
+			else if ( ch === open ) depth++;
+			else if ( ch === close ) { depth--; if ( depth === 0 ) { candidates.push(text.slice(i, j + 1)); break; } }
+		}
+	}
+	for ( var k = candidates.length - 1; k >= 0; k-- ) {
+		try { return JSON.parse(candidates[k]); } catch ( e ) { /* try previous */ }
+	}
+	throw new Error('no parseable JSON in: ' + text.slice(0, 120));
+}
+
+function interpolate( str, graph, scope ) {
+	if ( typeof str !== 'string' ) return str;
+	return str.replace(/\$\{\s*([^}]+?)\s*\}/g, function ( _, ref ) {
+		var v = graph.getRef(ref, scope);
+		return v == null ? '' : (typeof v === 'object' ? JSON.stringify(v) : String(v));
+	});
+}
+
+/**
+ * Build the LLM provider-map fragment.
+ * @param opts.ask        async ({system,user,maxTokens}) -> string. Defaults to the bundled client.
+ * @param opts.parseJSON  JSON-salvage fn. Defaults to the bundled one.
+ * @param opts.namespace  provider namespace key. Default 'LLM'.
+ * @param opts.plasticity (conceptName)->p∈[0,1]  the UNIFIED plasticity knob (e.g. a
+ *        `lifecycle.plasticity` accessor). When wired, it drives the call temperature:
+ *        p=1 plastic → full temperature (explore/learn), p=0 frozen → temperature 0
+ *        (deterministic, memo-perfect). DISCIPLINE: this only modulates the call — it
+ *        never gates applicability (K1). Unwired → temperature is left unset (no API change).
+ * @param opts.temperature (p)->number  optional mapping from plasticity to temperature
+ *        (default identity, since p and the common temperature range are both [0,1]).
+ * @param opts.base/model/key  config for the default client (ignored if `ask` is given).
+ */
+function createLLMProvider( opts ) {
+	opts          = opts || {};
+	var ask        = opts.ask || makeAsk(opts),
+	    _parseJSON = opts.parseJSON || parseJSON,
+	    namespace  = opts.namespace || 'LLM',
+	    plasticity = opts.plasticity,
+	    tempFn     = typeof opts.temperature === 'function' ? opts.temperature : null;
+
+	var ns = {};
+	ns[namespace] = {
+		complete: function ( graph, concept, scope, argz, cb ) {
+			var cfg  = Object.assign({}, concept._schema && concept._schema.prompt, argz && argz[0]),
+			    name = concept._name,
+			    sys  = interpolate(cfg.system, graph, scope),
+			    usr  = interpolate(cfg.user, graph, scope),
+			    // plasticity (if wired) drives the temperature; else a static cfg.temperature; else unset
+			    temp = plasticity ? (tempFn ? tempFn(plasticity(name)) : plasticity(name)) : cfg.temperature,
+			    askArgs = { system: sys, user: usr, maxTokens: cfg.maxTokens };
+			if ( temp != null ) askArgs.temperature = temp;
+			Promise.resolve()
+				.then(function () {
+					return ask(askArgs);
+				})
+				.then(function ( txt ) {
+					// report prompt+reply to the trace (no-op if no sink configured)
+					graph.traceProvider && graph.traceProvider(concept, scope, { prompt: { system: sys, user: usr }, temperature: temp, reply: txt });
+					var facts = { $_id: '_parent' };
+					facts[name] = true;
+
+					// --- canonicalization barrier: discrete facts tracked, prose untracked ---
+					if ( cfg.facts ) {
+						var raw  = _parseJSON(txt),                       // strict structured extraction
+						    cf   = canonicalize.canonFacts(raw, cfg.facts);
+						Object.assign(facts, cf.facts);                   // ONLY declared discrete keys, snapped -> TRACKED
+						if ( cf.misses.length ) facts[name + 'CanonMiss'] = cf.misses;  // visible, fail-closed (untracked)
+						var proseKey = cfg.prose || (name + 'Prose'),     // the terminal, UNTRACKED free text
+						    proseVal = cfg.proseFrom != null ? raw[cfg.proseFrom]
+						             : (raw && raw.prose != null ? raw.prose : txt);
+						facts[proseKey] = proseVal;
+						if ( cfg.digest !== false ) facts[name + 'FactsDigest'] = canonicalize.digest(cf.facts);
+						return cb(null, facts);
+					}
+
+					// --- legacy path (no facts schema): merge object / `as` / `<name>Result` ---
+					var result = cfg.json ? _parseJSON(txt) : txt;
+					if ( cfg.as ) facts[cfg.as] = result;
+					else if ( cfg.json && result && typeof result === 'object' && !Array.isArray(result) ) Object.assign(facts, result);
+					else facts[name + 'Result'] = result;
+					cb(null, facts);
+				})
+				.catch(function ( e ) {
+					var facts = { $_id: '_parent', llmError: e.message };
+					facts[name] = true;
+					cb(null, facts);// flag + record error so the graph can still settle
+				});
+		}
+	};
+	return ns;
+}
+
+module.exports = {
+	createLLMProvider: createLLMProvider, makeAsk: makeAsk, parseJSON: parseJSON,
+	makeOpenAIAsk: makeOpenAIAsk, makeAnthropicAsk: makeAnthropicAsk,
+	// exported so the Intake front-door (providers/intake.js) reuses the SAME `${ref}` resolver
+	// instead of re-implementing it (one interpolation semantics across the prose-typed boundary).
+	interpolate: interpolate
+};

package/lib/providers/local-host.js

@@ -0,0 +1,197 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * local-host — a CENTRALIZED in-process host for embedded inference (node-llama-cpp): ONE place that owns
+ * the GPU-resident model(s) + an in-memory prompt cache, so many `makeLocalAsk` handles / per-concept
+ * namespaces SHARE a single VRAM load and identical (deterministic) prompts don't re-run.
+ *
+ * WHY (the design gap the naive per-instance makeLocalAsk had): each `makeLocalAsk({...})` loaded its OWN
+ * model → N arms / N namespaces of the SAME gguf = N copies in VRAM (the 2026-07-01 signature-stability run
+ * loaded a 3.2GB model 4× per experiment), and nothing cached identical prompts. This host fixes both and
+ * manages VRAM under a budget (LRU eviction) — the in-process analogue of a grant-based GPU orchestrator.
+ *
+ * Reference: rocinante `GPUMaster.js` (a grant-based multi-GPU VRAM orchestrator). We LIFT its ideas — a
+ * load-once registry, a VRAM ledger + real-VRAM guard (here `llama.getVramState()` not nvidia-smi), LRU
+ * eviction — and DROP the machinery an in-process single-process node-llama-cpp host does not need (HTTP
+ * load/unload endpoints, the multi-GPU grant queue, the task DB, exclusive/shared cross-card placement).
+ *
+ * Grammar is applied PER CALL (cached by schema on the handle), NOT baked per model → several constrained
+ * grammars share ONE model load. Only temperature-0 (deterministic) completions are cached.
+ *
+ * ZERO-CORE, provider layer. The model loader is INJECTABLE (`opts.loadModel`) so the registry / cache /
+ * eviction logic is unit-testable without a GPU; the default loader is node-llama-cpp.
+ *
+ * A loader returns a HANDLE:  { vramBytes?, async complete({system,user,maxTokens,temperature,seed,grammar,reasoningBudget})
+ *                               -> string,  dispose() }  — `grammar` is a spec {jsonSchema}|{gbnf}|null;
+ *                               `reasoningBudget` is the native thinking budget in tokens (0 = thinking OFF, undefined = default).
+ */
+
+function modelKey( spec ) {
+	return [spec.modelPath, 'ctx=' + (spec.contextSize || 4096), 'gpu=' + (spec.gpu === undefined ? 'auto' : spec.gpu),
+		'lora=' + (spec.lora ? JSON.stringify(spec.lora) : '')].join('|');
+}
+function grammarKey( g ) { return g ? (g.jsonSchema ? 'js:' + stable(g.jsonSchema) : g.gbnf ? 'gb:' + g.gbnf : '') : ''; }
+// Finalize a completion under an optional COMPILED grammar. A JSON-SCHEMA grammar exposes `.parse()` (re-emit canonical
+// JSON); a raw GBNF grammar does NOT — its constrained output is already the bare text (e.g. an enum member). Guarding on
+// `typeof gr.parse === 'function'` (not merely `gr`) is the fix for the raw-GBNF path (`gr.parse is not a function`).
+function finalizeGrammarOutput( gr, out ) {
+	// A JSON-schema grammar guarantees a valid PREFIX, but a completion truncated at maxTokens can end mid-string, and
+	// `gr.parse()` (which JSON.parses) then THROWS on the unterminated JSON — crashing the whole run on one long, noisy
+	// generation (seen on Gemma-4-31B-Q2 under the intake schema). Degrade to the raw constrained text (fail-closed):
+	// the caller's own parse/guard salvages or nulls it, so a verbose model costs a fail-closed episode, not a crash.
+	if ( gr && typeof gr.parse === 'function' ) {
+		try { return JSON.stringify(gr.parse(out)); } catch ( _e ) { return out; }
+	}
+	return out;
+}
+function stable( o ) { return JSON.stringify(o, Object.keys(o || {}).sort()); }   // shallow-stable (schemas are small)
+function cacheKey( mk, gk, r ) {
+	var US = '\u001f';                                           // unit separator — collision-safe, NOT a NUL byte (the source-NUL gotcha)
+	return [mk, gk, r.maxTokens || '', r.temperature || 0, r.seed == null ? 0 : r.seed,
+		r.reasoningBudget == null ? '' : 'rb' + r.reasoningBudget, r.system || '', r.user || ''].join(US);
+}
+
+/**
+ * @param opts.loadModel     async (spec) -> handle. Default: node-llama-cpp.
+ * @param opts.vramBudgetGB  soft VRAM budget; when the ledger (Σ handle.vramBytes) would exceed it, LRU-evict.
+ * @param opts.maxModels     hard cap on resident models (LRU-evict beyond it). Default: unbounded.
+ * @param opts.cacheSize     bounded prompt-cache entries (LRU). Default 512; 0 disables.
+ */
+function createLocalModelHost( opts ) {
+	opts = opts || {};
+	const loadModel  = opts.loadModel || defaultLoader(opts);
+	const vramBudget = opts.vramBudgetGB != null ? opts.vramBudgetGB * 1e9 : null;
+	const maxModels  = opts.maxModels || null;
+	const cacheMax   = opts.cacheSize == null ? 512 : opts.cacheSize;
+
+	const models = new Map();          // key -> { spec, handle, loading, vramBytes, lastUsed, chain }
+	const cache  = new Map();          // LRU (insertion-ordered) prompt cache
+	const stats  = { loads: 0, evictions: 0, cacheHits: 0, cacheMisses: 0, infer: 0 };
+	let tick = 0;
+
+	function totalVram() { let s = 0; for ( const e of models.values() ) s += e.vramBytes || 0; return s; }
+
+	async function evictIfNeeded( keepKey ) {
+		// evict LRU residents (never the one just requested) while over the count cap or the vram budget.
+		function over() { return (maxModels && models.size > maxModels) || (vramBudget && totalVram() > vramBudget); }
+		while ( over() ) {
+			let victim = null, oldest = Infinity;
+			for ( const [k, e] of models ) if ( k !== keepKey && !e.loading && e.lastUsed < oldest ) { oldest = e.lastUsed; victim = k; }
+			if ( !victim ) break;
+			const e = models.get(victim);
+			models.delete(victim);
+			stats.evictions++;
+			try { e.handle && e.handle.dispose && e.handle.dispose(); } catch ( _e ) { /* best-effort */ }
+		}
+	}
+
+	async function getModel( spec ) {
+		const key = modelKey(spec);
+		let e = models.get(key);
+		if ( e ) { e.lastUsed = ++tick; return e.loading ? e.loading : e.handle; }
+		e = { spec, handle: null, loading: null, vramBytes: 0, lastUsed: ++tick, chain: Promise.resolve() };
+		e.loading = Promise.resolve()
+			.then(() => loadModel(spec))
+			.then(( h ) => { e.handle = h; e.vramBytes = h && h.vramBytes || 0; e.loading = null; stats.loads++; return h; });
+		models.set(key, e);
+		const h = await e.loading;
+		await evictIfNeeded(key);          // make room AFTER we know this one's footprint (never evict `key`)
+		return h;
+	}
+
+	/** The one entry point: resolve/share the model, check the prompt cache, serialize the GPU call. */
+	async function ask( req ) {
+		const spec = { modelPath: req.modelPath, contextSize: req.contextSize, gpu: req.gpu, lora: req.lora };
+		const mk = modelKey(spec), gk = grammarKey(req.grammar);
+		const ck = cacheKey(mk, gk, req);
+		if ( cacheMax && cache.has(ck) ) { stats.cacheHits++; const v = cache.get(ck); cache.delete(ck); cache.set(ck, v); return v; }
+		stats.cacheMisses++;
+		await getModel(spec);
+		const e = models.get(mk);
+		// per-model serialization: chain calls so concurrent asks queue (don't exhaust sequences).
+		const run = e.chain.then(() => e.handle.complete({
+			system: req.system, user: req.user, maxTokens: req.maxTokens, temperature: req.temperature,
+			seed: req.seed, grammar: req.grammar, reasoningBudget: req.reasoningBudget
+		}));
+		e.chain = run.catch(() => {});    // keep the chain alive past a failure
+		const out = await run;
+		stats.infer++;
+		if ( cacheMax && (req.temperature || 0) === 0 ) {   // cache ONLY deterministic results
+			cache.set(ck, out);
+			if ( cache.size > cacheMax ) cache.delete(cache.keys().next().value);   // evict oldest
+		}
+		return out;
+	}
+
+	function dispose() {
+		for ( const e of models.values() ) { try { e.handle && e.handle.dispose && e.handle.dispose(); } catch ( _e ) {} }
+		models.clear(); cache.clear();
+	}
+
+	return { ask, getModel, dispose, stats, _models: models, _cache: cache };
+}
+
+// ── default node-llama-cpp loader (lazy; only required when the default host actually loads a model) ──
+function defaultLoader( hostOpts ) {
+	return async function load( spec ) {
+		let nlc;
+		try { nlc = await import('node-llama-cpp'); }
+		catch ( e ) { throw new Error('node-llama-cpp is not installed. Run `npm run local-inference:setup`. Cause: ' + e.message); }
+		const { getLlama, LlamaChatSession } = nlc;
+		const llama   = await getLlama(spec.gpu === undefined ? undefined : { gpu: spec.gpu });
+		const before  = tryVram(llama);
+		const model   = await llama.loadModel({ modelPath: spec.modelPath });
+		const context = await model.createContext(Object.assign({ contextSize: spec.contextSize || 4096 }, spec.lora ? { lora: spec.lora } : {}));
+		const after   = tryVram(llama);
+		const vramBytes = (before != null && after != null) ? Math.max(0, after - before) : 0;
+		const grammars = new Map();                                   // schema -> compiled grammar (per model)
+		async function grammarFor( g ) {
+			if ( !g ) return null;
+			const k = grammarKey(g);
+			if ( grammars.has(k) ) return grammars.get(k);
+			const compiled = g.jsonSchema ? await llama.createGrammarForJsonSchema(g.jsonSchema) : await llama.createGrammar({ grammar: g.gbnf });
+			grammars.set(k, compiled);
+			return compiled;
+		}
+		// ONE persistent sequence per model, REUSED across calls (`clearHistory` resets the KV for a clean single-turn).
+		// A VRAM-tight context allocates only 1 sequence; getSequence()/dispose() per call then throws "No sequences left"
+		// on the 2nd call (dispose does not return a slot to a 1-sequence pool). Reuse is also the right shape given the
+		// host serializes calls per model. (Live-verified on Qwen3.6-27B-Q2, which loads a 1-sequence context.)
+		const seq = context.getSequence();
+		return {
+			vramBytes,
+			async complete( { system, user, maxTokens = 1024, temperature = 0, seed, grammar, reasoningBudget } ) {
+				const gr = await grammarFor(grammar);
+				try { await seq.clearHistory(); } catch ( _e ) {}     // reset the reused sequence's KV for a fresh single-turn
+				const session = new LlamaChatSession({ contextSequence: seq, systemPrompt: system || undefined, autoDisposeSequence: false });
+				try {
+					const popts = Object.assign({ maxTokens, temperature, seed: seed == null ? 0 : seed }, gr ? { grammar: gr } : {});
+					// native thinking control (node-llama-cpp `budgets.thoughtTokens`; == CLI --reasoningBudget). 0 = thinking OFF —
+					// the adapted lever for a reasoning model at a one-token TYPED touchpoint (CoT there just truncates the answer).
+					if ( reasoningBudget != null ) popts.budgets = { thoughtTokens: reasoningBudget };
+					const out = await session.prompt(user, popts);
+					return finalizeGrammarOutput(gr, out);
+				} finally { try { session.dispose({ disposeSequence: false }); } catch ( _e ) {} }   // keep the sequence for the next call
+			},
+			dispose() { try { model.dispose(); } catch ( _e ) {} }
+		};
+	};
+	function tryVram( llama ) { try { const s = llama.getVramState && llama.getVramState(); return s ? s.used : null; } catch ( _e ) { return null; } }
+}
+
+// a process-wide shared host (so independent makeLocalAsk handles share loads + the prompt cache).
+let _shared = null;
+function sharedLocalModelHost() {
+	if ( !_shared ) _shared = createLocalModelHost({
+		vramBudgetGB: process.env.SG_LOCAL_VRAM_BUDGET_GB ? Number(process.env.SG_LOCAL_VRAM_BUDGET_GB) : undefined,
+		maxModels   : process.env.SG_LOCAL_MAX_MODELS ? Number(process.env.SG_LOCAL_MAX_MODELS) : undefined,
+	});
+	return _shared;
+}
+
+module.exports = { createLocalModelHost, sharedLocalModelHost, modelKey, grammarKey, finalizeGrammarOutput };

package/lib/providers/merge-consistency.js

@@ -0,0 +1,162 @@
+/*
+ * 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';
+/**
+ * Merge-consistency operator — the consistency radius ε (the sheaf C1 gluing brick;
+ * doc/WIP/HANDOFF.md §7 Tier 1; SOTA subgraph-grammars C1; experiment E6). Zero core change.
+ *
+ * NRG already had the other two sheaf conditions at the sub-graph frontier: C2 (the
+ * commutative log-odds monoid = separation) and C3 (recombine-the-continuous-partials-
+ * THEN-snap, E4). The missing one was C1 (coherent restrictions). The reason it matters,
+ * shown decisively in E6: the monoid combine collapses two opposite epistemic states to
+ * the SAME certainty —
+ *   - two confident sources that DISAGREE   ℓ=(+2.5,−2.5) -> Σℓ=0 -> κ=0.5
+ *   - two genuinely NEUTRAL sources         ℓ=(+0.1,−0.1) -> Σℓ=0 -> κ=0.5
+ * identical κ=0.5, opposite meaning. The combine alone LOSES the disagreement. The
+ * consistency radius ε = the spread of the partials in log-odds (max−min; = |ℓ_A−ℓ_B|
+ * for two) is the missing dimension. Exposed as a SNAPPED typed fact `mergeConsistency`
+ * (barrier-clean enum, never a raw float on a gate), a pure-D `Reconcile` concept can
+ * fire/audit on the conflict band. C1 is, in clear, "a fact + a gate."
+ *
+ *   const { createConsistency, consistencyConceptTree } = require('./merge-consistency');
+ *   register(Graph, [ createConsistency() ]);                 // wires Merge::combine
+ *   // a ready-made audited contract (Combine crosses + snaps; Reconcile gates on conflict):
+ *   const tree = consistencyConceptTree({ partials: ['ellA', 'ellB'] });
+ *
+ * Combine the CONTINUOUS partials and compute ε BEFORE snapping (correction #6 / E4) — snap
+ * first and you lose evidence (two partials that each round down sum higher than their
+ * rounded sum). The crossing fact at the frontier is the continuous log-odds; only the
+ * snapped enum is consumed by a gate.
+ */
+
+function sigmoid( x ) { return 1 / (1 + Math.exp(-x)); }
+
+// Default consistency-radius bands on ε (log-odds disagreement): agree <1, borderline <3,
+// conflict ≥3. A band with no `max` is the catch-all (largest disagreement). Override via opts.bands.
+var DEFAULT_BANDS = [
+	{ max: 1, label: 'agree', rank: 0 },
+	{ max: 3, label: 'borderline', rank: 1 },
+	{ label: 'conflict', rank: 2 }
+];
+
+// Snap a disagreement ε to its band { rank, label }. The first band whose `max` ε is under
+// wins; a maxless band is the catch-all.
+function bandOf( eps, bands ) {
+	bands = bands || DEFAULT_BANDS;
+	for ( var i = 0; i < bands.length; i++ )
+		if ( bands[i].max == null || eps < bands[i].max ) return { rank: bands[i].rank, label: bands[i].label };
+	var last = bands[bands.length - 1];
+	return { rank: last.rank, label: last.label };
+}
+
+/**
+ * The C1 operator: combine N log-odds partials and expose the consistency radius ε.
+ * @param partials   array of log-odds numbers (non-finite entries ignored)
+ * @param opts.bands custom band table (default DEFAULT_BANDS)
+ * @returns { ell, kappa, eps, rank, label, n }
+ *   ell   = Σ partials (the commutative monoid combine)
+ *   kappa = σ(ell)     (the recombined certainty)
+ *   eps   = max−min    (the disagreement; 0 for a single partial)
+ *   rank/label = the snapped consistency band (the barrier-clean enum)
+ */
+function mergeConsistency( partials, opts ) {
+	opts = opts || {};
+	var xs = (partials || []).map(Number).filter(function ( x ) { return isFinite(x); });
+	var ell = xs.reduce(function ( s, w ) { return s + w; }, 0);
+	var eps = xs.length ? Math.max.apply(null, xs) - Math.min.apply(null, xs) : 0;
+	var b = bandOf(eps, opts.bands);
+	return { ell: ell, kappa: sigmoid(ell), eps: eps, rank: b.rank, label: b.label, n: xs.length };
+}
+
+/**
+ * Build the merge-consistency provider fragment (host opt-in, like createVerifier).
+ * @param opts.bands  default band table for every Merge::combine apply (per-concept override
+ *                    via the concept's `merge.bands`).
+ * @returns { Merge: { combine } }
+ *
+ * Concept wiring (the Combine concept at a merge frontier):
+ *   { require:['ellA','ellB'], provider:['Merge::combine'],
+ *     merge: { partials:['ellA','ellB'], as:'' } }
+ * Emits the self-flag + <as>ell / <as>kappa / <as>eps / <as>mergeConsistency (enum) /
+ * <as>mergeConsistencyRank. Reads each partial via getRef (a key on the merge target).
+ */
+function createConsistency( opts ) {
+	opts = opts || {};
+	var defaultBands = opts.bands;
+	return {
+		Merge: {
+			combine: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({}, concept._schema && concept._schema.merge, argz && argz[0]),
+				    prefix = cfg.as || '',
+				    keys = cfg.partials || [],
+				    xs = keys.map(function ( k ) { return Number(graph.getRef(k, scope)); }),
+				    r = mergeConsistency(xs, { bands: cfg.bands || defaultBands }),
+				    facts = { $_id: '_parent' };
+				facts[concept._name] = true;
+				facts[prefix + 'ell'] = r.ell;
+				facts[prefix + 'kappa'] = r.kappa;
+				facts[prefix + 'eps'] = r.eps;
+				facts[prefix + 'mergeConsistency'] = r.label;     // snapped enum — barrier-clean
+				facts[prefix + 'mergeConsistencyRank'] = r.rank;
+				cb(null, facts);
+			}
+		}
+	};
+}
+
+/**
+ * A ready-made audited merge-projection contract as a concept-tree fragment: a `Combine`
+ * concept that crosses the continuous partials and snaps ε, with a pure-D `Reconcile` gate
+ * nested under it that casts ONLY in the conflict band (so the D grammar can react/audit).
+ * @param opts.partials      partial-fact keys to combine (default ['ellA','ellB'])
+ * @param opts.require       Combine's require keys (default = the partials)
+ * @param opts.conflictRank  Reconcile's gate threshold on the snapped rank (default 2 = conflict)
+ * @param opts.as            output-fact prefix (default '')
+ */
+function consistencyConceptTree( opts ) {
+	opts = opts || {};
+	var partials = opts.partials || ['ellA', 'ellB'],
+	    as = opts.as || '',
+	    rank = opts.conflictRank == null ? 2 : opts.conflictRank;
+	return {
+		childConcepts: {
+			Combine: {
+				_id: 'Combine', _name: 'Combine',
+				require: opts.require || partials.slice(),
+				provider: ['Merge::combine'],
+				merge: { partials: partials, as: as },
+				childConcepts: {
+					Reconcile: {
+						_id: 'Reconcile', _name: 'Reconcile',
+						require: ['Combine'],
+						ensure: ['$' + as + 'mergeConsistencyRank>=' + rank]
+					}
+				}
+			}
+		}
+	};
+}
+
+module.exports = {
+	mergeConsistency: mergeConsistency,
+	bandOf: bandOf,
+	sigmoid: sigmoid,
+	DEFAULT_BANDS: DEFAULT_BANDS,
+	createConsistency: createConsistency,
+	consistencyConceptTree: consistencyConceptTree
+};