skynet-graph 1.2.0

package/lib/runtime/invoke-pool.js

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * invoke-pool — THE SHARED INSTANCE KEYED BY CONTRACT (roadmap 2026-07-09 P3; the scale point). P2 delegates via the
+ * P1 invoke, but `invokeGraph` SPAWNS + TEARS DOWN a worker per cast (the proven fil). P3 keeps workers WARM in a pool
+ * keyed by `libraryKey`/contract, so **N cases → 1 instance** (never one sub-graph per concept-method instance) — the
+ * conceptMap + providers (+ a load-once model, via local-host, on the worker) are paid ONCE, reused across invokes.
+ *
+ * STATELESS-PER-INVOKE (the guardrail that keeps the constat): the warm worker is only warm in its CONFIG — each
+ * `invoke` builds a FRESH graph from its seed (`Graph.fromDirs({seed})` in protocol.js#invoke) and stabilizes it
+ * independently, so a reused worker carries NO cross-invoke graph state. Reuse buys the load cost, not shared mutable
+ * state; determinism per invoke is unchanged. The pool is ZERO-CORE host orchestration over `createGraphWorker`.
+ *
+ *   const pool = createInvokePool();
+ *   const r = await pool.invoke('methodKey', { conceptMap, providers, seed, boundedFrom, boundedKeys });
+ *   // ... N more invokes of 'methodKey' reuse the SAME warm worker (pool.size() === 1) ...
+ *   await pool.close();
+ */
+/**
+ * createInvokePool(opts) — a warm-worker pool keyed by contract.
+ * @param opts.workerDefaults  base createGraphWorker opts merged under every keyed worker (logger, conf, …).
+ * @param opts.max             optional soft cap on distinct warm instances (LRU-evict the least-recently-used).
+ * @returns { invoke(key, iopts), has(key), keys(), size(), stats(), evict(key), close() }
+ */
+function createInvokePool( opts ) {
+	opts = opts || {};
+	const workers = new Map();                                         // key -> { worker, uses, last }
+	let tick = 0;
+
+	// the method CONFIG the key's worker is built from (conceptMap/providers) — stored so P5 `refine` can swap the BODY
+	// behind the fixed key without the caller re-supplying it.
+	const configOf = ( iopts ) => ({ conceptMap: iopts.conceptMap, concepts: iopts.concepts, providers: iopts.providers,
+		geo: iopts.geo, llm: iopts.llm, ask: iopts.ask, conf: iopts.conf, logger: iopts.logger || opts.logger });
+
+	function keyWorker( key, iopts ) {
+		let e = workers.get(key);
+		if ( !e ) { e = { worker: null, uses: 0, config: configOf(iopts) }; workers.set(key, e); }   // first use registers the config
+		if ( !e.worker ) {                                                     // create (first use) or RE-create (post-refine, body swapped)
+			const createGraphWorker = require('./index.js').createGraphWorker; // lazy — avoids the load-order circular
+			e.worker = createGraphWorker(Object.assign({}, opts.workerDefaults, e.config));   // the STORED config (refine wins over iopts)
+			e.last = ++tick;                                                  // stamp BEFORE the cap check so a fresh worker isn't its own LRU victim
+			if ( opts.max && liveCount() > opts.max ) evictLRU(key);
+		}
+		e.uses++; e.last = ++tick;
+		return e.worker;
+	}
+	const liveCount = () => { let n = 0; for ( const e of workers.values() ) if ( e.worker ) n++; return n; };
+	function evictLRU( keep ) {                                              // evict the LRU among LIVE workers (never `keep`)
+		let lruKey = null, lruTick = Infinity;
+		for ( const [k, e] of workers ) if ( e.worker && k !== keep && e.last < lruTick ) { lruTick = e.last; lruKey = k; }
+		if ( lruKey != null ) evict(lruKey);
+	}
+	function evict( key ) {
+		const e = workers.get(key);
+		if ( !e ) return Promise.resolve(false);
+		workers.delete(key);
+		return e.worker ? Promise.resolve(e.worker.terminate()).then(() => true) : Promise.resolve(true);
+	}
+
+	return {
+		// invoke the method keyed by `key` on its WARM instance (created on first use, reused after). Stateless-per-invoke.
+		invoke: function ( key, iopts ) {
+			iopts = iopts || {};
+			const w = keyWorker(key, iopts);
+			return w.invoke({ seed: iopts.seed, boundedFrom: iopts.boundedFrom, boundedKeys: iopts.boundedKeys, settleTimeout: iopts.settleTimeout });
+		},
+		// P5 — AFFINER sans casser le contrat: swap the BODY behind the fixed key (new conceptMap/providers) and tear
+		// down the warm worker; the NEXT invoke re-creates from the refined config. The key/contract/Σ_sep — the
+		// interface the caller casts on — is untouched. "Le délégué évolue, l'interface reste."
+		refine: function ( key, newConfig ) {
+			let e = workers.get(key);
+			if ( !e ) { workers.set(key, { worker: null, uses: 0, config: Object.assign({}, newConfig) }); return Promise.resolve(true); }
+			const old = e.worker;
+			e.config = Object.assign({}, e.config, newConfig);   // the refined body
+			e.worker = null;                                     // force re-create on next invoke
+			return old ? Promise.resolve(old.terminate()).then(() => true) : Promise.resolve(true);
+		},
+		has:   ( key ) => workers.has(key),
+		keys:  () => [...workers.keys()],
+		size:  () => [...workers.values()].filter(( e ) => e.worker ).length,   // LIVE warm instances (a refined-but-not-yet-reinvoked key has no worker)
+		stats: () => ({ instances: [...workers.values()].filter(( e ) => e.worker ).length, keys: [...workers.keys()], uses: [...workers.values()].reduce(( a, e ) => a + e.uses, 0) }),
+		evict: evict,
+		close: function () { return Promise.all([...workers.values()].map(( e ) => Promise.resolve(e.worker.terminate()))).then(() => { workers.clear(); }); }
+	};
+}
+
+module.exports = { createInvokePool };

package/lib/runtime/protocol.js

@@ -0,0 +1,210 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * Runtime PROTOCOL — the transport-agnostic halves of the distributed sub-graph runtime (roadmap P5).
+ *
+ * The message shape {init, dispatch, ask, askReply, result, error, log, ready, terminate} was plain-JSON by
+ * design; this module lifts the worker- and client-side handling OFF worker_threads so the SAME logic runs over
+ * ANY duplex `channel` — a worker_threads port (transport-thread) OR a TCP/unix socket (transport-socket). A
+ * channel is the minimal duplex seam:
+ *     { send(msg), onMessage(fn), close(), onError?(fn) }
+ * `send`/`onMessage` carry already-parsed JSON objects (a socket transport frames them; a thread transport passes
+ * them through structured-clone). Behaviour is byte-for-byte the worker_threads original — only the seam changed.
+ */
+
+/**
+ * attachWorker(channel) — the WORKER/SERVER side. Loads a concept set + providers on `init` (wiring any LLM `ask`
+ * to a proxy that round-trips the model call back over the channel), builds+stabilizes a fresh sub-graph per
+ * `dispatch`, and ships the serialized snapshot back. One config per process (engine providers are process-global),
+ * exactly like the worker_thread model.
+ */
+function attachWorker( channel ) {
+	var Graph     = require('../index.js');
+	var providers = require('../providers');
+	var createLogger = require('../graph/log.js').createLogger;
+	var boundedProject = require('../authoring/bounded-merge.js').boundedProject;
+
+	var ctx = null, askCounter = 0;
+	var askPending = {};
+
+	// the proxied model backend: forward the prompt over the channel, await the peer's reply.
+	function proxiedAsk( prompt, opts ) {
+		return new Promise(function ( resolve, reject ) {
+			var callId = ++askCounter;
+			askPending[callId] = { resolve: resolve, reject: reject };
+			channel.send({ type: 'ask', callId: callId, prompt: prompt, opts: opts });
+		});
+	}
+
+	function init( msg ) {
+		var conceptMap = msg.conceptMap || (msg.concepts ? Graph.loadConceptMap(msg.concepts) : {});
+		if ( msg.providers ) providers.register(Graph, Graph.loadProviders(msg.providers, { ask: proxiedAsk, env: process.env }));
+		if ( msg.geo )       providers.register(Graph, [{ CommonGeo: providers.CommonGeo }]);
+		if ( msg.llm )       providers.register(Graph, [providers.createLLMProvider({ ask: proxiedAsk })]);
+		var logger = createLogger({ label: 'worker', level: msg.logLevel || 'verbose', console: false });
+		logger.addSink(function ( record ) { channel.send({ type: 'log', record: record }); });
+		ctx = { conceptMap: conceptMap, conf: msg.conf || {}, logger: logger };
+		channel.send({ type: 'ready' });
+	}
+
+	function dispatch( msg ) {
+		var dispatchId = msg.dispatchId, settled = false;
+		var finish = function ( graph ) {
+			if ( settled ) return; settled = true;
+			channel.send({ type: 'result', dispatchId: dispatchId, snapshot: graph.serialize() });
+		};
+		try {
+			var g = Graph.fromDirs({
+				conceptMap: ctx.conceptMap,
+				seed      : msg.seed,
+				conf      : Object.assign({}, ctx.conf, { autoMount: true, logger: ctx.logger, onStabilize: function ( graph ) { finish(graph); } })
+			});
+			var t = setTimeout(function () { finish(g); }, msg.settleTimeout || 10000);   // bound the empty-seed / no-write case
+			if ( t.unref ) t.unref();
+		} catch ( e ) {
+			channel.send({ type: 'error', dispatchId: dispatchId, message: e.message });
+		}
+	}
+
+	// invoke (roadmap P1) — the BOUNDED cross-instance invoke. Same settle as dispatch, but the worker crosses back
+	// ONLY the declared frontier alphabet (Σ_sep) off the `boundedFrom` object — `boundedProject(summaryFacts)` + the
+	// write-footprint (the keys the object carries) — NOT the whole serialized snapshot. This is the KG-PROXY fil
+	// promoted into the runtime: the constat holds while merge traffic is O(|frontier|), independent of the child size.
+	// facts of an object as seeded (across the seed's conceptMaps/nodes/segments shapes) — the "before" for the delta.
+	function seedFactsOf( seed, id ) {
+		var lists = [].concat((seed && seed.conceptMaps) || [], (seed && seed.nodes) || [], (seed && seed.segments) || []);
+		for ( var i = 0; i < lists.length; i++ ) if ( lists[i] && lists[i]._id === id ) return lists[i];
+		return {};
+	}
+	function invoke( msg ) {
+		var invokeId = msg.invokeId, settled = false;
+		var finish = function ( graph ) {
+			if ( settled ) return; settled = true;
+			var summary = boundedProject({ from: msg.boundedFrom, targetId: msg.boundedFrom, keys: msg.boundedKeys || [] })(graph);
+			delete summary.$$_id;                                                     // the wire summary is a plain facts object
+			var e = graph.getEtty ? graph.getEtty(msg.boundedFrom) : null, f = (e && e._) || {};
+			// write-footprint = the DELTA the body actually wrote (added/changed vs the seed) — what G1 (frame-completeness)
+			// diffs against the declared write; NOT the pre-existing structural facts (Segment/originNode/…).
+			var orig = seedFactsOf(msg.seed, msg.boundedFrom);
+			var footprint = Object.keys(f).filter(function ( k ) {
+				return k !== '_id' && k !== '_rev' && JSON.stringify(f[k]) !== JSON.stringify(orig[k]);
+			});
+			channel.send({ type: 'invokeResult', invokeId: invokeId, summary: summary, writeFootprint: footprint });
+		};
+		try {
+			var g = Graph.fromDirs({
+				conceptMap: ctx.conceptMap,
+				seed      : msg.seed,
+				conf      : Object.assign({}, ctx.conf, { autoMount: true, logger: ctx.logger, onStabilize: function ( graph ) { finish(graph); } })
+			});
+			var t = setTimeout(function () { finish(g); }, msg.settleTimeout || 10000);
+			if ( t.unref ) t.unref();
+		} catch ( e ) {
+			channel.send({ type: 'error', invokeId: invokeId, message: e.message });
+		}
+	}
+
+	channel.onMessage(function ( msg ) {
+		switch ( msg.type ) {
+			case 'init':     init(msg); break;
+			case 'dispatch': dispatch(msg); break;
+			case 'invoke':   invoke(msg); break;
+			case 'askReply': {
+				var p = askPending[msg.callId];
+				if ( p ) { delete askPending[msg.callId]; msg.error ? p.reject(new Error(msg.error)) : p.resolve(msg.result); }
+				break;
+			}
+			case 'terminate': channel.close(); break;
+		}
+	});
+}
+
+/**
+ * attachClient(channel, opts) — the PARENT/CLIENT side. Sends `init`, answers proxied `ask` calls with the
+ * parent-bound `opts.ask`, re-emits forwarded `log` records into `opts.logger` (tagged {worker:true}), and
+ * resolves each `dispatch` with the peer's stabilized snapshot. Returns { ready, dispatch, terminate }.
+ */
+function attachClient( channel, opts ) {
+	opts = opts || {};
+	var ask = opts.ask || function () { return Promise.reject(new Error('worker requested a model call but no `ask` backend was wired')); };
+	var dispatches = {}, dispatchCounter = 0, invokes = {}, invokeCounter = 0, readyResolve;
+	var ready = new Promise(function ( res ) { readyResolve = res; });
+
+	channel.onMessage(async function ( msg ) {
+		switch ( msg.type ) {
+			case 'ready': readyResolve(); break;
+			case 'ask': {
+				try { channel.send({ type: 'askReply', callId: msg.callId, result: await ask(msg.prompt, msg.opts) }); }
+				catch ( e ) { channel.send({ type: 'askReply', callId: msg.callId, error: e.message }); }
+				break;
+			}
+			case 'result': {
+				var dr = dispatches[msg.dispatchId];
+				if ( dr ) { delete dispatches[msg.dispatchId]; dr.resolve(msg.snapshot); }
+				break;
+			}
+			case 'invokeResult': {
+				var ir = invokes[msg.invokeId];
+				if ( ir ) { delete invokes[msg.invokeId]; ir.resolve({ summary: msg.summary, writeFootprint: msg.writeFootprint }); }
+				break;
+			}
+			case 'error': {
+				if ( msg.invokeId != null ) { var ie = invokes[msg.invokeId]; if ( ie ) { delete invokes[msg.invokeId]; ie.reject(new Error(msg.message)); } break; }
+				var de = dispatches[msg.dispatchId];
+				if ( de ) { delete dispatches[msg.dispatchId]; de.reject(new Error(msg.message)); }
+				break;
+			}
+			case 'log': {
+				var r = msg.record;
+				if ( opts.logger && r && typeof opts.logger[r.level] === 'function' ) {
+					var child = opts.logger.child(Object.assign({ worker: true }, r.ctx || {}));
+					child[r.level].apply(child, [r.msg].concat(r.args || []));
+				}
+				break;
+			}
+		}
+	});
+	if ( channel.onError ) channel.onError(function ( e ) {
+		Object.keys(dispatches).forEach(function ( id ) { dispatches[id].reject(e); delete dispatches[id]; });
+		Object.keys(invokes).forEach(function ( id ) { invokes[id].reject(e); delete invokes[id]; });
+	});
+
+	channel.send({
+		type: 'init', conceptMap: opts.conceptMap, concepts: opts.concepts, providers: opts.providers,
+		geo: opts.geo, llm: opts.llm, logLevel: opts.logLevel, conf: opts.conf
+	});
+
+	return {
+		ready: function () { return ready; },
+		dispatch: function ( seed, dopts ) {
+			dopts = dopts || {};
+			return ready.then(function () {
+				return new Promise(function ( resolve, reject ) {
+					var dispatchId = ++dispatchCounter;
+					dispatches[dispatchId] = { resolve: resolve, reject: reject };
+					channel.send({ type: 'dispatch', dispatchId: dispatchId, seed: seed, settleTimeout: dopts.settleTimeout });
+				});
+			});
+		},
+		// invoke (P1) — resolve with the BOUNDED summary only: { summary:{<Σ_sep facts>}, writeFootprint:[keys] }.
+		invoke: function ( iopts ) {
+			iopts = iopts || {};
+			return ready.then(function () {
+				return new Promise(function ( resolve, reject ) {
+					var invokeId = ++invokeCounter;
+					invokes[invokeId] = { resolve: resolve, reject: reject };
+					channel.send({ type: 'invoke', invokeId: invokeId, seed: iopts.seed,
+						boundedFrom: iopts.boundedFrom, boundedKeys: iopts.boundedKeys, settleTimeout: iopts.settleTimeout });
+				});
+			});
+		},
+		terminate: function () { return channel.close(); }
+	};
+}
+
+module.exports = { attachWorker: attachWorker, attachClient: attachClient };

package/lib/runtime/transport-socket.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * Socket transport (roadmap P5) — the cross-INSTANCE channel: the same {init, dispatch, ask, …} protocol as
+ * worker_threads, carried over a TCP or unix-domain socket, so a sub-graph can be dispatched to a graph runtime
+ * on ANOTHER process or machine. Framing = NDJSON (one `JSON.stringify(msg)` per line; JSON never emits a raw
+ * newline, so a line is a whole message). The parent-bound model `ask` round-trips back over the SAME socket,
+ * exactly as in-thread.
+ *
+ *   // server (the remote runtime instance):
+ *   const { serve } = require('skynet-graph/lib/runtime/transport-socket');
+ *   const server = await serve({ path: '/tmp/sg.sock' });      // each connection = one attachWorker
+ *   // client (elsewhere): createGraphWorker({ address: { path: '/tmp/sg.sock' }, conceptMap, geo:true })
+ */
+var net = require('net');
+
+/**
+ * socketChannel(socket) — wrap a connected duplex socket as a protocol channel { send, onMessage, close, onError }.
+ * NDJSON: buffer incoming bytes, split on '\n', JSON.parse each complete line → the message handler.
+ */
+function socketChannel( socket ) {
+	socket.setEncoding('utf8');
+	var buf = '';
+	var handlers = [];
+	socket.on('data', function ( chunk ) {
+		buf += chunk;
+		var i;
+		while ( (i = buf.indexOf('\n')) >= 0 ) {
+			var line = buf.slice(0, i);
+			buf = buf.slice(i + 1);
+			if ( !line ) continue;
+			var msg;
+			try { msg = JSON.parse(line); } catch ( e ) { continue; }   // skip a corrupt frame rather than crash the peer
+			for ( var h = 0; h < handlers.length; h++ ) handlers[h](msg);
+		}
+	});
+	return {
+		socket: socket,
+		send: function ( m ) { try { socket.write(JSON.stringify(m) + '\n'); } catch ( e ) { /* peer gone */ } },
+		onMessage: function ( fn ) { handlers.push(fn); },
+		onError: function ( fn ) { socket.on('error', fn); },
+		close: function () { try { socket.end(); } catch ( e ) {} }
+	};
+}
+
+/**
+ * connect(address) → Promise<channel>. address = { port[, host] } (TCP) | { path } (unix socket) — anything
+ * net.connect accepts. Resolves once the connection is open; rejects on a connect error.
+ */
+function connect( address ) {
+	return new Promise(function ( resolve, reject ) {
+		var socket = net.connect(address, function () { socket.removeListener('error', reject); resolve(socketChannel(socket)); });
+		socket.once('error', reject);
+	});
+}
+
+/**
+ * serve(listenOpts, workerOpts?) → Promise<server>. Listens (TCP { port } or unix { path }); for EACH connection,
+ * runs a worker-side protocol handler (attachWorker) over that connection's channel — the connecting client drives
+ * `init`/`dispatch` and answers the proxied `ask`. `server.close()` stops accepting. (One config per process, like
+ * the thread worker — engine providers are process-global.)
+ */
+function serve( listenOpts, workerOpts ) {
+	var attachWorker = require('./protocol.js').attachWorker;
+	var server = net.createServer(function ( conn ) { attachWorker(socketChannel(conn), workerOpts || {}); });
+	return new Promise(function ( resolve, reject ) {
+		server.once('error', reject);
+		server.listen(listenOpts, function () { server.removeListener('error', reject); resolve(server); });
+	});
+}
+
+module.exports = { socketChannel: socketChannel, connect: connect, serve: serve };

package/lib/runtime/worker-entry.js

@@ -0,0 +1,31 @@
+/*
+ * 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';
+/**
+ * Worker-thread entry — the worker_threads adaptor for the transport-agnostic worker protocol (protocol.js).
+ * It wraps `parentPort` as a channel and hands it to `attachWorker`; all the init/dispatch/ask logic lives in
+ * protocol.js so the socket transport (transport-socket.js) runs the identical handler over a socket.
+ */
+var parentPort = require('worker_threads').parentPort;
+var attachWorker = require('./protocol.js').attachWorker;
+
+attachWorker({
+	send: function ( m ) { parentPort.postMessage(m); },
+	onMessage: function ( fn ) { parentPort.on('message', fn); },
+	close: function () { process.exit(0); }
+});