skynet-graph 1.2.0

package/lib/providers/solver-fork.js

@@ -0,0 +1,163 @@
+/*
+ * 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';
+/**
+ * C-regime solver-fork — search-where-D-propagates, with a snapped frontier (the
+ * Mixture-of-Reasoners "C regime"; doc/WIP/HANDOFF.md §7 Tier 1; SOTA subgraph-grammars
+ * brick ii; experiment E8). Zero core change.
+ *
+ * The deterministic D socle PROPAGATES to a fixpoint; it cannot SEARCH. A regime-C
+ * sub-graph delegates a constraint problem to a backtracking solver (Logic-LM style,
+ * Pan 2023) and EXPORTS ONLY the snapped model across the merge frontier — the colour/
+ * assignment enums + a `sat` bool — never the search internals (step counts, the search
+ * tree, continuous scores). So the parent stays deterministic and auditable, the barrier
+ * holds, and UNSAT is a discrete outcome the D grammar can gate on.
+ *
+ *   const { createSolver, snappedFrontier, solverConceptTree } = require('./solver-fork');
+ *   register(Graph, [ createSolver({ solve: myZ3Backend }) ]);    // wires Solve::run
+ *   const child = parent.fork(spec, { conceptMap: { common: solverConceptTree() } });
+ *   await nextStable(child);
+ *   parent.merge(child, 'prob', snappedFrontier({ targetId: 'prob' }));  // only sat+model cross
+ *
+ * The solver backend is INJECTED (backend-agnostic, like createLLMProvider's `ask`): a
+ * `solve(spec) -> { sat, model, ...internals }` function. The packaged default is a
+ * dependency-free backtracking finite-domain CSP (`backtrackColoring`) so the regime is
+ * runnable out of the box; the architectural point — search, snapped frontier, auditable
+ * D parent — is independent of hand-rolled-vs-Z3.
+ */
+
+// ---- reference C-regime backend: a dependency-free backtracking CSP (graph k-colouring) ----
+// spec = { nodes:[...], edges:[[u,v],...], colors?:[...] } -> { sat, model, steps }.
+// model = a node->colour assignment (the snapped enum the frontier carries); steps is a
+// search-internal cost (stays in the fork — it must NOT cross the frontier).
+function backtrackColoring( spec ) {
+	spec = spec || {};
+	var nodes = spec.nodes || [];
+	var edges = spec.edges || [];
+	var colors = spec.colors || ['R', 'G', 'B'];
+	var assign = {}, adj = {};
+	nodes.forEach(function ( n ) { adj[n] = []; });
+	edges.forEach(function ( e ) { adj[e[0]].push(e[1]); adj[e[1]].push(e[0]); });
+	var steps = 0;
+	function bt( i ) {
+		if ( i === nodes.length ) return true;
+		var n = nodes[i];
+		for ( var ci = 0; ci < colors.length; ci++ ) {
+			var c = colors[ci];
+			steps++;
+			if ( adj[n].every(function ( m ) { return assign[m] !== c; }) ) {
+				assign[n] = c;
+				if ( bt(i + 1) ) return true;
+				delete assign[n];
+			}
+		}
+		return false;
+	}
+	var sat = bt(0);
+	return { sat: sat, model: sat ? Object.assign({}, assign) : null, steps: steps };
+}
+
+/**
+ * Build the C-regime solver-fork provider fragment (host opt-in, like createVerifier).
+ * @param opts.solve   injected backend `(spec) -> { sat, model, ...internals }`
+ *                     (default: backtrackColoring).
+ * @returns { Solve: { run } }
+ *
+ * Concept wiring (in the C-fork grammar — see solverConceptTree):
+ *   { require:['toSolve'], provider:['Solve::run'], solve:{ specKey:'spec', as:'' } }
+ * `specKey` names the scope fact holding the problem spec (omit -> the whole scope fact
+ * bag is the spec). Emits the self-flag + <as>sat (bool) + <as>model (the snapped
+ * assignment, null when UNSAT) + any solver internals the backend returns (e.g. `steps`)
+ * — internals are kept on the CHILD and dropped by snappedFrontier at the merge.
+ */
+function createSolver( opts ) {
+	opts = opts || {};
+	var solve = opts.solve || backtrackColoring;
+	return {
+		Solve: {
+			run: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({ as: '' }, concept._schema && concept._schema.solve, argz && argz[0]),
+				    spec = cfg.specKey ? graph.getRef(cfg.specKey, scope) : scope._,
+				    r = solve(spec) || {},
+				    as = cfg.as || '',
+				    facts = { $_id: '_parent' };
+				facts[concept._name] = true;
+				facts[as + 'sat'] = !!r.sat;
+				facts[as + 'model'] = r.sat ? (r.model != null ? r.model : null) : null;
+				// solver internals (steps, the search tree, …) are emitted on the child only;
+				// they document the search but must NOT cross the frontier (see snappedFrontier).
+				for ( var k in r ) if ( k !== 'sat' && k !== 'model' ) facts[as + k] = r[k];
+				cb(null, facts);
+			}
+		}
+	};
+}
+
+/**
+ * A merge-projection that crosses ONLY the snapped model across the frontier — the C-regime
+ * barrier: the colour/assignment enums + the `sat` bool cross; search internals (step counts,
+ * the search tree, continuous scores) stay in the fork. Pass the returned function as the
+ * 3rd arg to `parent.merge(child, targetId, project)`.
+ * @param opts.targetId  the parent object id to write onto (required)
+ * @param opts.sourceId  the child object holding the solved facts (default = targetId)
+ * @param opts.frontier  keys allowed to cross (default ['sat','model'])
+ * @param opts.as        the child's output prefix (default '')
+ */
+function snappedFrontier( opts ) {
+	opts = opts || {};
+	var targetId = opts.targetId,
+	    sourceId = opts.sourceId || targetId,
+	    frontier = opts.frontier || ['sat', 'model'],
+	    as = opts.as || '';
+	return function ( child ) {
+		var f = child.getEtty(sourceId)._,
+		    tpl = { $$_id: targetId };
+		frontier.forEach(function ( k ) { tpl[k] = f[as + k]; });  // ONLY these keys cross
+		return tpl;
+	};
+}
+
+/**
+ * The C-fork grammar fragment: a `Solve` concept whose provider SEARCHES. Use it as the
+ * forked sub-graph's conceptMap so the fork runs the C regime.
+ * @param opts.require  the trigger fact that marks an object as "to solve" (default 'toSolve')
+ * @param opts.specKey  scope fact holding the spec (passed through to the provider)
+ * @param opts.as       output-fact prefix (default '')
+ */
+function solverConceptTree( opts ) {
+	opts = opts || {};
+	var solve = { as: opts.as || '' };
+	if ( opts.specKey ) solve.specKey = opts.specKey;
+	return {
+		childConcepts: {
+			Solve: {
+				_id: 'Solve', _name: 'Solve',
+				require: [opts.require || 'toSolve'],
+				provider: ['Solve::run'],
+				solve: solve
+			}
+		}
+	};
+}
+
+module.exports = {
+	backtrackColoring: backtrackColoring,
+	createSolver: createSolver,
+	snappedFrontier: snappedFrontier,
+	solverConceptTree: solverConceptTree
+};

package/lib/providers/stats.js

@@ -0,0 +1,228 @@
+/*
+ * 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';
+/**
+ * L1 graded-evidence statistics — hierarchical Beta-Binomial shrinkage along the IS-A
+ * backbone (the bounded probabilistic layer; doc/WIP/HANDOFF.md §7 Tier 2; experiment A).
+ * Zero core change, and ADDITIVE: the deterministic socle is untouched — this only writes
+ * SNAPPED reliability facts that a downstream `ensure` gates on (graded evidence as a
+ * discrete fact + a threshold, the L1 frame, never a raw float on a defeasant gate).
+ *
+ * The statistical point (A3): at small n a per-leaf success rate is high-variance; shrinking
+ * it toward the parent "grand mean" prior (θ̂ = (n·x̄ + κ·prior)/(n+κ)) cuts MSE ≈7× at n=2,
+ * with the advantage decaying as n grows. The barrier point (A2): the leaf consumes the prior
+ * SNAPPED to its own grain (the bucket midpoint), and the downstream gate keys on the snapped
+ * reliability RANK — so sub-bucket noise doesn't churn the memo (snapping costs only ~1–4% MSE).
+ *
+ *   const { createStats, shrinkageConceptTree } = require('./stats');
+ *   register(Graph, [ createStats() ]);     // wires Stats::report / Stats::grandMean / Stats::shrink
+ *   // pool the children's grand mean, then (a host wave later, once the prior exists)
+ *   // shrink each leaf toward the SNAPPED prior and gate Trusted on the snapped rank.
+ *
+ * Hierarchical ordering: the grand-mean prior must exist before a leaf can shrink toward it.
+ * That is the "offline between revisions" pattern — pool first (its own settle), then add the
+ * shrink wave — not a live two-level reactive pool (which would need cross-object aggregation,
+ * roadmap #8). The pool reduces a race-free {__push} obs array gated on its cardinality.
+ */
+
+// ---- reliability bands: snap a probability to a discrete rank + the band MIDPOINT (the
+// snapped prior the synthesis mandates). 4 bands, edges 0.5/0.75/0.9. Override via opts.bands. ----
+var RELIABILITY_BANDS = [
+	{ max: 0.5, label: 'low', rank: 0, mid: 0.25 },
+	{ max: 0.75, label: 'med', rank: 1, mid: 0.625 },
+	{ max: 0.9, label: 'high', rank: 2, mid: 0.825 },
+	{ label: 'certain', rank: 3, mid: 0.95 }
+];
+
+function bandOf( p, bands ) {
+	bands = bands || RELIABILITY_BANDS;
+	for ( var i = 0; i < bands.length; i++ )
+		if ( bands[i].max == null || p < bands[i].max ) return { rank: bands[i].rank, label: bands[i].label, mid: bands[i].mid };
+	var last = bands[bands.length - 1];
+	return { rank: last.rank, label: last.label, mid: last.mid };
+}
+
+/**
+ * Beta-Binomial shrinkage of a leaf rate toward a prior.
+ *   θ̂ = (n·x̄ + κ·prior) / (n + κ)
+ * @param o.succ   leaf successes
+ * @param o.tot    leaf trials (n)
+ * @param o.prior  the (snapped) parent prior in [0,1]
+ * @param o.kappa  shrinkage strength (pseudo-count); larger -> more pooling
+ * @returns { theta, raw, n }  raw = the un-shrunk x̄ (0.5 when n=0)
+ */
+function shrink( o ) {
+	o = o || {};
+	var n = Number(o.tot) || 0,
+	    succ = Number(o.succ) || 0,
+	    prior = o.prior == null ? 0.5 : Number(o.prior),
+	    kappa = o.kappa == null ? 8 : Number(o.kappa),
+	    raw = n ? succ / n : 0.5,
+	    theta = (n * raw + kappa * prior) / (n + kappa);
+	return { theta: theta, raw: raw, n: n };
+}
+
+/**
+ * Empirical-Bayes shrinkage strength κ from a set of per-leaf raw rates at trial size n:
+ * κ ≈ n · (within-leaf sampling variance) / (between-leaf signal variance). Large when the
+ * leaves barely differ beyond sampling noise (pool hard); small when they genuinely spread.
+ * @param rawRates array of per-leaf x̄ in [0,1]
+ * @param n        trials per leaf
+ */
+function empiricalBayesKappa( rawRates, n ) {
+	var M = (rawRates || []).length;
+	if ( !M || !n ) return 0;
+	var gm = rawRates.reduce(function ( a, b ) { return a + b; }, 0) / M,
+	    varRaw = rawRates.reduce(function ( a, b ) { return a + (b - gm) * (b - gm); }, 0) / M,
+	    sampVar = gm * (1 - gm) / Math.max(1, n),
+	    betweenVar = Math.max(1e-4, varRaw - sampVar);
+	return sampVar / betweenVar * n;
+}
+
+/**
+ * Build the L1 statistics provider fragment (host opt-in, like createVerifier).
+ * @param opts.bands  default reliability bands (per-concept override via the concept's `stats.bands`)
+ * @param opts.kappa  default shrinkage strength (default 8)
+ * @returns { Stats: { report, grandMean, shrink } }
+ *
+ * Concept wiring:
+ *   Stats::report     { require:['Cat'], provider:['Stats::report'], stats:{ poolId:'pool', succKey:'succ', totKey:'tot' } }
+ *   Stats::grandMean  { require:['PoolRoot'], ensure:['$obs.length==$expected'], provider:['Stats::grandMean'] }
+ *   Stats::shrink     { require:['Cat','Report'], provider:['Stats::shrink'], stats:{ poolId:'pool', priorKey:'pHat0Bucket', kappa:8 } }
+ * shrink emits <as>thetaHat / <as>rawHat / <as>relRank / <as>relBucket / <as>priorMid (gate on relRank).
+ */
+function createStats( opts ) {
+	opts = opts || {};
+	var defaultBands = opts.bands,
+	    defaultKappa = opts.kappa == null ? 8 : opts.kappa;
+
+	return {
+		Stats: {
+			// each leaf appends its (succ,tot) into the pool's obs array (race-free {__push}).
+			report: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({ poolId: 'pool', succKey: 'succ', totKey: 'tot' }, concept._schema && concept._schema.stats, argz && argz[0]),
+				    push = { __push: { succ: scope._[cfg.succKey], tot: scope._[cfg.totKey] } },
+				    poolWrite = { $$_id: cfg.poolId },
+				    self = { $_id: '_parent' };
+				self[concept._name] = true;
+				poolWrite[cfg.obsKey || 'obs'] = push;
+				cb(null, [self, poolWrite]);
+			},
+
+			// reduce the pooled obs -> the grand mean, SNAPPED to its band (the prior the leaves consume).
+			grandMean: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({ as: '' }, concept._schema && concept._schema.stats, argz && argz[0]),
+				    obs = scope._[cfg.obsKey || 'obs'] || [],
+				    s = 0, t = 0;
+				for ( var i = 0; i < obs.length; i++ ) { s += obs[i].succ; t += obs[i].tot; }
+				var pHat0 = t ? s / t : 0.5,
+				    b = bandOf(pHat0, cfg.bands || defaultBands),
+				    as = cfg.as || '',
+				    facts = { $_id: '_parent' };
+				facts[concept._name] = true;
+				facts[as + 'pHat0'] = pHat0;
+				facts[as + 'pHat0Rank'] = b.rank;
+				facts[as + 'pHat0Bucket'] = b.label;
+				facts[as + 'pHat0Mid'] = b.mid;          // the snapped prior midpoint
+				facts[as + 'pooledSucc'] = s;
+				facts[as + 'pooledTot'] = t;
+				cb(null, facts);
+			},
+
+			// shrink the leaf toward the parent's SNAPPED prior; snap θ̂ to a reliability rank.
+			shrink: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({ poolId: 'pool', priorKey: 'pHat0Bucket', succKey: 'succ', totKey: 'tot', as: '' },
+					concept._schema && concept._schema.stats, argz && argz[0]),
+				    bands = cfg.bands || defaultBands,
+				    pool = graph.getEtty(cfg.poolId)._,
+				    priorMid, r;
+				// consume the SNAPPED prior (the band midpoint) — barrier-clean, no continuous leak.
+				// Prefer an explicit midpoint fact (grandMean writes pHat0Mid); else resolve it from
+				// the pool's snapped band label.
+				if ( cfg.priorMidKey ) {
+					priorMid = pool[cfg.priorMidKey];
+				} else {
+					var label = pool[cfg.priorKey],
+					    band = (bands || RELIABILITY_BANDS).filter(function ( x ) { return x.label === label; })[0];
+					priorMid = band ? band.mid : 0.5;
+				}
+				r = shrink({ succ: scope._[cfg.succKey], tot: scope._[cfg.totKey], prior: priorMid, kappa: cfg.kappa == null ? defaultKappa : cfg.kappa });
+				var b = bandOf(r.theta, bands),
+				    as = cfg.as || '',
+				    facts = { $_id: '_parent' };
+				facts[concept._name] = true;
+				facts[as + 'thetaHat'] = r.theta;
+				facts[as + 'rawHat'] = r.raw;
+				facts[as + 'relRank'] = b.rank;
+				facts[as + 'relBucket'] = b.label;
+				facts[as + 'priorMid'] = priorMid;
+				cb(null, facts);
+			}
+		}
+	};
+}
+
+/**
+ * A ready-made hierarchical-shrinkage fragment. Returns the two waves separately because the
+ * prior must exist before the leaves shrink (the offline-between-revisions ordering):
+ *   .pool   — the PoolRoot/Pool (grandMean) + Cat/Report concepts (wave 1, boot it);
+ *   .shrink — the Reliability (shrink) + Trusted gate concept (wave 2, addConcept once pooled).
+ * @param opts.kappa        shrinkage strength
+ * @param opts.trustedRank  the Trusted gate threshold on the snapped rank (default 2 = high)
+ * @param opts.poolId       the pool object id (default 'pool')
+ */
+function shrinkageConceptTree( opts ) {
+	opts = opts || {};
+	var poolId = opts.poolId || 'pool',
+	    trustedRank = opts.trustedRank == null ? 2 : opts.trustedRank,
+	    stats = { poolId: poolId };
+	if ( opts.kappa != null ) stats.kappa = opts.kappa;
+	return {
+		pool: {
+			childConcepts: {
+				PoolRoot: {
+					_id: 'PoolRoot', _name: 'PoolRoot', require: ['PoolRoot'],
+					childConcepts: {
+						Pool: { _id: 'Pool', _name: 'Pool', require: ['PoolRoot'], ensure: ['$obs.length==$expected'], provider: ['Stats::grandMean'] }
+					}
+				},
+				Cat: {
+					_id: 'Cat', _name: 'Cat', require: ['Cat'],
+					childConcepts: {
+						Report: { _id: 'Report', _name: 'Report', require: ['Cat'], provider: ['Stats::report'], stats: { poolId: poolId } }
+					}
+				}
+			}
+		},
+		shrink: {
+			_id: 'Reliability', _name: 'Reliability', require: ['Cat', 'Report'], provider: ['Stats::shrink'], stats: stats,
+			childConcepts: {
+				Trusted: { _id: 'Trusted', _name: 'Trusted', require: ['Reliability'], ensure: ['$relRank>=' + trustedRank] }
+			}
+		}
+	};
+}
+
+module.exports = {
+	RELIABILITY_BANDS: RELIABILITY_BANDS,
+	bandOf: bandOf,
+	shrink: shrink,
+	empiricalBayesKappa: empiricalBayesKappa,
+	createStats: createStats,
+	shrinkageConceptTree: shrinkageConceptTree
+};

package/lib/providers/verify.js

@@ -0,0 +1,120 @@
+/*
+ * 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';
+/**
+ * Verification providers (roadmap #3) — the structural answer to K3 (coherence ≠ truth).
+ * The engine maintains COHERENCE, never TRUTH; verification makes unreliability *visible
+ * and non-propagating* by emitting discrete VERDICT facts that downstream concepts gate
+ * on via `ensure` (a refuted fact auto-retracts its dependents — refutation IS defeasance,
+ * no new engine path). Verdicts are discrete facts (the #1 typed-fact spine), never prose,
+ * and NEVER overwrite the checked fact (the graph is additive; experts don't fight).
+ *
+ * Three reliable patterns (all verified against the engine):
+ *   1. DETERMINISTIC verifier = a concept whose `ensure` IS the invariant (full `expr.js`
+ *      grammar — uncapped). Its self-flag is the verdict; a target change re-tests it and
+ *      auto-retracts. Consumers either nest under it (structural cascade) or `ensure` a
+ *      verdict fact it writes. Prefer this — deterministic checkers >> LLM-refuters.
+ *   2. INDEPENDENT verdict provider (`Verify::check`) — for a check that must run as an
+ *      effect (an external lookup, or an LLM-refuter): reads the target, runs a checker,
+ *      writes a DISTINCT verdict fact + `VerifiedAgainst` provenance. Downstream gates via
+ *      `ensure:["$xVerified == true"]`.
+ *   3. k-of-n VOTING (`Vote::tally`) — self-consistency: n strategies `{__push}` a vote
+ *      into a grow-only array; a `Vote` concept gated `ensure:["$votes.length == $n"]`
+ *      (the proven completion-gate) emits majority `consensus` + `confidence = agree/n`.
+ *      Downstream gates `ensure:["$confidence >= threshold"]`.
+ *
+ * Independence discipline: a refuter must not be the same call that produced the fact
+ * (don't ask the hallucination to grade itself) — a deterministic checker, a different
+ * provider, or an adversarially-framed LLM. k-of-n over a biased model votes confidently
+ * wrong; treat `confidence` as a heuristic, never a proof.
+ */
+
+// ---- deterministic checker library: (value, params) -> { pass, reason } ----
+// Pure, side-effect-free, total (never throws). Add domain checks here as needed.
+var checks = {
+	range  : function ( v, p ) { var n = Number(v); return { pass: isFinite(n) && n >= p.min && n <= p.max, reason: 'range[' + p.min + ',' + p.max + ']' }; },
+	oneOf  : function ( v, p ) { return { pass: (p.values || []).indexOf(v) !== -1, reason: 'oneOf' }; },
+	equals : function ( v, p ) { return { pass: v === p.to, reason: 'equals' }; },
+	approx : function ( v, p ) { var n = Number(v); return { pass: isFinite(n) && Math.abs(n - Number(p.to)) <= (p.tol || 0), reason: 'approx±' + (p.tol || 0) }; },
+	nonEmpty: function ( v ) { return { pass: v != null && (typeof v === 'string' || Array.isArray(v) ? v.length > 0 : true), reason: 'nonEmpty' }; }
+};
+
+// ---- majority vote over an array of discrete votes ----
+function majority( votes ) {
+	var counts = {}, best = null, bestN = 0;
+	for ( var i = 0; i < votes.length; i++ ) {
+		var k = JSON.stringify(votes[i]);
+		counts[k] = (counts[k] || 0) + 1;
+		if ( counts[k] > bestN ) { bestN = counts[k]; best = votes[i]; }
+	}
+	return { value: best, agree: bestN, total: votes.length, confidence: votes.length ? bestN / votes.length : 0 };
+}
+
+/**
+ * Build the verification provider-map fragment.
+ * @param opts.checks  extra deterministic checkers merged over the defaults.
+ * @returns { Verify: { check }, Vote: { tally } }
+ */
+function createVerifier( opts ) {
+	opts = opts || {};
+	var lib = Object.assign({}, checks, opts.checks);
+
+	return {
+		// Verify::check — independent verdict provider. Concept wiring:
+		//   { provider:['Verify::check'],
+		//     verify: { target:'$x', check:'range', params:{min:0,max:100}, as:'x' } }
+		// Emits <as>Verdict / <as>Verified / <as>Reason / <as>VerifiedAgainst — never $x itself.
+		Verify: {
+			check: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({}, concept._schema && concept._schema.verify, argz && argz[0]),
+				    prefix = cfg.as || concept._name,
+				    checker = lib[cfg.check],
+				    value = graph.getRef(cfg.target, scope),
+				    res = checker ? checker(value, cfg.params || {}) : { pass: false, reason: 'unknown-check:' + cfg.check },
+				    facts = { $_id: '_parent' };
+				facts[concept._name] = true;
+				facts[prefix + 'Verdict'] = res.pass ? 'pass' : 'fail';
+				facts[prefix + 'Verified'] = res.pass;
+				facts[prefix + 'Reason'] = res.reason;
+				facts[prefix + 'VerifiedAgainst'] = cfg.check;
+				cb(null, facts);
+			}
+		},
+		// Vote::tally — k-of-n consensus. Concept wiring:
+		//   { require:['votes'], ensure:['$votes.length == $expected'], provider:['Vote::tally'],
+		//     vote: { votesKey:'votes', as:'' } }
+		// Emits <as>consensus / <as>confidence / <as>agree / <as>total (flat by default).
+		Vote: {
+			tally: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({}, concept._schema && concept._schema.vote, argz && argz[0]),
+				    prefix = cfg.as || '',
+				    votes = graph.getRef(cfg.votesKey || 'votes', scope) || [],
+				    m = majority(votes),
+				    facts = { $_id: '_parent' };
+				facts[concept._name] = true;
+				facts[prefix + 'consensus'] = m.value;
+				facts[prefix + 'confidence'] = m.confidence;
+				facts[prefix + 'agree'] = m.agree;
+				facts[prefix + 'total'] = m.total;
+				cb(null, facts);
+			}
+		}
+	};
+}
+
+module.exports = { createVerifier: createVerifier, checks: checks, majority: majority };

package/lib/runtime/index.js

@@ -0,0 +1,135 @@
+/*
+ * 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';
+/**
+ * Parent-side sub-graph runtime — dispatch graph parts to a warm worker for horizontal scale. The worker
+ * rehydrates from a conceptMap (JSON) + provider dir path + a seed snapshot (JSON); the one effect that can't be
+ * shipped — a parent-bound model `ask` — is PROXIED back over the channel and the parent's real `ask` answers it.
+ *
+ *   const { createGraphWorker } = require('skynet-graph/lib/runtime');
+ *   const w = createGraphWorker({ conceptMap, geo: true });        // default: worker_threads (same machine)
+ *   const snapshot = await w.dispatch(seed);                       // -> graph.serialize()
+ *   w.terminate();
+ *
+ * TRANSPORT (P5). The {init, dispatch, ask, result, log} protocol is transport-agnostic (see protocol.js). Two
+ * transports slot in behind the SAME channel seam:
+ *   • worker_threads (default)              — same-machine parallelism, spawns worker-entry.js;
+ *   • socket (opts.address / transport)     — a CROSS-INSTANCE runtime: connect to a `serveGraphWorker` on another
+ *                                             process or machine. `createGraphWorker({ address:{path|port}, … })`.
+ * A host stands up the remote side with `serveGraphWorker({ path } | { port })`.
+ *
+ * @param {object}   [opts.conceptMap]  concept map (JSON) — or
+ * @param {string}   [opts.concepts]    a concept-set dir the worker can read
+ * @param {string}   [opts.providers]   provider dir/file the worker loads locally
+ * @param {boolean}  [opts.geo]         register the packaged Geo provider
+ * @param {boolean}  [opts.llm]         register the packaged LLM provider, wired to `opts.ask`
+ * @param {function} [opts.ask]         parent model backend — answers proxied calls (prompt,opts)=>Promise
+ * @param {object}   [opts.conf]        data-only Graph cfg for dispatched graphs
+ * @param {object}   [opts.logger]      parent logger — worker log records re-emit into it (tagged {worker:true})
+ * @param {string}   [opts.logLevel]    threshold for the worker's forwarding logger (default 'verbose')
+ * @param {object}   [opts.address]     socket transport: { path } (unix) | { port[, host] } (TCP). Omit = threads.
+ * @param {string}   [opts.transport]   'socket' | 'thread' (default). 'socket' requires opts.address.
+ * @returns {{ready, dispatch, terminate, worker?}}
+ */
+var path = require('path');
+var protocol = require('./protocol.js');
+
+function threadChannel() {
+	var Worker = require('worker_threads').Worker;
+	var worker = new Worker(path.join(__dirname, 'worker-entry.js'));
+	return {
+		worker: worker,
+		send: function ( m ) { worker.postMessage(m); },
+		onMessage: function ( fn ) { worker.on('message', fn); },
+		onError: function ( fn ) { worker.on('error', fn); },
+		close: function () { return worker.terminate(); }
+	};
+}
+
+function createGraphWorker( opts ) {
+	opts = opts || {};
+
+	// ── socket transport: connect to a remote serveGraphWorker; the API awaits the connection lazily ──────────
+	if ( opts.transport === 'socket' || opts.address ) {
+		if ( !opts.address ) throw new Error("createGraphWorker transport 'socket' needs opts.address ({ path } | { port })");
+		var connect = require('./transport-socket.js').connect;
+		var connected = connect(opts.address).then(function ( channel ) { return protocol.attachClient(channel, opts); });
+		return {
+			ready:     function () { return connected.then(function ( a ) { return a.ready(); }); },
+			dispatch:  function ( seed, dopts ) { return connected.then(function ( a ) { return a.dispatch(seed, dopts); }); },
+			invoke:    function ( iopts ) { return connected.then(function ( a ) { return a.invoke(iopts); }); },
+			terminate: function () { return connected.then(function ( a ) { return a.terminate(); }); }
+		};
+	}
+
+	// ── default: worker_threads (same-machine) ────────────────────────────────────────────────────────────────
+	var channel = threadChannel();
+	var api = protocol.attachClient(channel, opts);
+	api.worker = channel.worker;                          // back-compat: expose the raw Worker
+	return api;
+}
+
+/**
+ * One-shot convenience: spawn/connect a worker, dispatch a single seed, return the stabilized snapshot, tear down.
+ * @param {object} opts  createGraphWorker opts + { seed, settleTimeout }
+ * @returns {Promise<object>} snapshot (graph.serialize())
+ */
+function spawnGraph( opts ) {
+	opts = opts || {};
+	var w = createGraphWorker(opts);
+	return w.dispatch(opts.seed, opts).then(
+		function ( snap ) { return Promise.resolve(w.terminate()).then(function () { return snap; }); },
+		function ( err )  { return Promise.resolve(w.terminate()).then(function () { throw err; }); }
+	);
+}
+
+/**
+ * One-shot BOUNDED invoke (P1): spawn/connect a worker, invoke a single seed, return { summary, writeFootprint } —
+ * ONLY the declared frontier alphabet (Σ_sep) crosses back, not the whole snapshot — tear down.
+ * @param {object} opts  createGraphWorker opts + { seed, boundedFrom, boundedKeys, settleTimeout }
+ * @returns {Promise<{summary:object, writeFootprint:string[]}>}
+ */
+function invokeGraph( opts ) {
+	opts = opts || {};
+	var w = createGraphWorker(opts);
+	return w.invoke(opts).then(
+		function ( res ) { return Promise.resolve(w.terminate()).then(function () { return res; }); },
+		function ( err ) { return Promise.resolve(w.terminate()).then(function () { throw err; }); }
+	);
+}
+
+/**
+ * serveGraphWorker(opts) → Promise<{ server, address, close }>. Stand up a socket runtime that accepts sub-graph
+ * dispatches from remote `createGraphWorker({ address, … })` clients. opts.path (unix) or opts.port[/host] (TCP),
+ * or opts.address directly. `close()` stops accepting and resolves when the server is down.
+ */
+function serveGraphWorker( opts ) {
+	opts = opts || {};
+	var serve = require('./transport-socket.js').serve;
+	var listen = opts.address || (opts.path != null ? { path: opts.path } : { port: opts.port, host: opts.host });
+	return serve(listen).then(function ( server ) {
+		return {
+			server: server,
+			address: server.address(),
+			close: function () { return new Promise(function ( res ) { server.close(function () { res(); }); }); }
+		};
+	});
+}
+
+module.exports = { createGraphWorker: createGraphWorker, spawnGraph: spawnGraph, invokeGraph: invokeGraph, serveGraphWorker: serveGraphWorker };
+module.exports.createInvokePool = require('./invoke-pool.js').createInvokePool;   // P3: warm-worker pool keyed by contract (N cases → 1 instance)