skynet-graph 1.2.0

package/lib/authoring/loop.js

@@ -0,0 +1,193 @@
+/*
+ * 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 "answer a (huge) prompt" loop, as a reusable concept set + helpers.
+ *
+ *   DECOMPOSE (reactive concepts):  a root segment (start->goal) carrying the prompt
+ *     Task            require Segment                 every segment is a Task
+ *       EvalComplexity require Task        -> Atomic | NeedsSplit  (depth floor forces Atomic)
+ *       Expand         require NeedsSplit  -> child sub-step segments + expandedInto
+ *       Answer         require Atomic      -> a leaf answer
+ *
+ *   SYNTHESIZE — two regimes, same bounded rollup:
+ *
+ *   (a) DETERMINISTIC post-pass (`synthesize`, the one-shot default): a post-order
+ *     walk leaf->root. Race-free, simple, O(V+E); reactivity buys nothing when
+ *     everything is cold. Use with `loopConceptTree`.
+ *
+ *   (b) REACTIVE concepts (`reactiveLoopConceptTree`, the live/standing regime): each
+ *     answered segment appends its id to its parent's grow-only `answeredBy` array via
+ *     the race-free `{__push}` primitive; a `Rollup` concept gated on
+ *     `ensure:["$answeredBy.length == $expandedInto.length"]` (a monotone G-Set
+ *     cardinality predicate — §5.2) fires EXACTLY ONCE when the last child reports,
+ *     reads the children's bounded answers (ordered by `expandedInto`) and writes the
+ *     parent's answer. Synthesis happens IN stabilization, bottom-up, with ZERO core
+ *     change (the earlier `+=1` counter would have raced — Entity arrays REPLACE on
+ *     update; `{__push}` appends at serialized apply-time). The completion gate keys on
+ *     a discrete `.length`, never prose (the #1 typed-fact spine in action).
+ *     KNOWN LIMIT: this is reactive on COMPLETION; re-rolling on a live leaf-answer
+ *     CONTENT change needs per-child answer-following (the aggregation gap — roadmap #5).
+ *
+ * Content (eval/expand/answer/rollup) is INJECTED so the same loop runs with
+ * deterministic functions (tests) or an LLM (run-prompt.js).
+ */
+
+// ---- the concept set (the "library of concept<->prompt pairs", content-agnostic) ----
+const loopConceptTree = {
+	childConcepts: {
+		Task: {
+			_id: 'Task', _name: 'Task', require: 'Segment',
+			childConcepts: {
+				EvalComplexity: { _id: 'EvalComplexity', _name: 'EvalComplexity', require: ['Task'], provider: ['AI::evalComplexity'] },
+				Expand        : { _id: 'Expand', _name: 'Expand', require: ['Task', 'NeedsSplit'], provider: ['AI::expand'] },
+				Answer        : { _id: 'Answer', _name: 'Answer', require: ['Task', 'Atomic'], provider: ['AI::answer'] }
+			}
+		}
+	}
+};
+
+// The reactive variant: the same decompose concepts PLUS the two reactive-synthesis
+// concepts. `ReportUp` (every answered non-root segment) appends its id to its parent's
+// `answeredBy`; `Rollup` (every expanded segment) fires once its children all reported.
+var reactiveLoopConceptTree = (function () {
+	var t = JSON.parse(JSON.stringify(loopConceptTree));
+	Object.assign(t.childConcepts.Task.childConcepts, {
+		ReportUp: { _id: 'ReportUp', _name: 'ReportUp', require: ['Task', 'Answered', 'parentSeg'], provider: ['AI::reportUp'] },
+		Rollup  : { _id: 'Rollup', _name: 'Rollup', require: ['Task', 'expandedInto'], ensure: ['$answeredBy.length == $expandedInto.length'], provider: ['AI::rollup'] }
+	});
+	return t;
+})();
+
+/**
+ * The decomposition providers. Inject content functions:
+ *   evalFn(scope)   -> { atomic: bool }                  (depth floor still applies)
+ *   expandFn(scope) -> [{ name, description? }, ...]      ordered sub-steps
+ *   answerFn(scope) -> string                             a leaf answer
+ *   rollupFn(seg, childAnswers[]) -> string               bounded parent answer (reactive regime)
+ * Options: maxDepth (depth floor), maxBranch (cap sub-steps).
+ */
+function makeDecomposeProviders( opts ) {
+	opts          = opts || {};
+	var maxDepth  = opts.maxDepth == null ? 2 : opts.maxDepth,
+	    maxBranch = opts.maxBranch || 4,
+	    evalFn    = opts.evalFn || function () { return { atomic: true }; },
+	    expandFn  = opts.expandFn || function () { return []; },
+	    answerFn  = opts.answerFn || function () { return ''; },
+	    rollupFn  = opts.rollupFn || function ( seg, kids ) { return kids.join(''); };
+
+	// content fns may be sync OR async (LLM) — Promise.resolve handles both
+	return {
+		AI: {
+			evalComplexity: function ( graph, concept, scope, argz, cb ) {
+				var depth = scope._.depth || 0;
+				if ( depth >= maxDepth ) return cb(null, { $_id: '_parent', EvalComplexity: true, Atomic: true });// depth floor
+				Promise.resolve(evalFn(scope)).then(function ( r ) {
+					var facts = { $_id: '_parent', EvalComplexity: true };
+					facts[(r && r.atomic) ? 'Atomic' : 'NeedsSplit'] = true;
+					cb(null, facts);
+				}).catch(function ( e ) { cb(null, { $_id: '_parent', EvalComplexity: true, Atomic: true, llmError: e.message }); });
+			},
+			expand: function ( graph, concept, scope, argz, cb ) {
+				Promise.resolve(expandFn(scope)).then(function ( raw ) {
+					var steps = (raw || []).slice(0, maxBranch);
+					if ( !steps.length ) return cb(null, { $_id: '_parent', Expand: true, Atomic: true });// nothing to split -> leaf
+					var base    = scope._._id,
+					    origin  = scope._.originNode,
+					    target  = scope._.targetNode,
+					    depth   = (scope._.depth || 0) + 1,
+					    childIds = steps.map(function ( _, i ) { return base + '_s' + i; }),
+					    tpl      = [{ $_id: '_parent', Expand: true, expandedInto: childIds }],
+					    prev     = origin;
+					steps.forEach(function ( st, i ) {
+						var last  = i === steps.length - 1,
+						    tnode = last ? target : base + '_m' + i;
+						if ( !last ) tpl.push({ _id: tnode, Node: true, label: st.name });
+						tpl.push({
+							_id: childIds[i], Segment: true, originNode: prev, targetNode: tnode,
+							depth: depth, parentSeg: base, label: st.name, description: st.description
+						});
+						prev = tnode;
+					});
+					cb(null, tpl);
+				}).catch(function ( e ) { cb(null, { $_id: '_parent', Expand: true, Atomic: true, llmError: e.message }); });
+			},
+			answer: function ( graph, concept, scope, argz, cb ) {
+				// MUST set its own name (Answer:true) as the self-flag, else the engine
+				// keeps seeing the concept as applicable and re-fires it forever.
+				Promise.resolve(answerFn(scope)).then(function ( a ) {
+					cb(null, { $_id: '_parent', Answer: true, Answered: true, answer: a });
+				}).catch(function ( e ) { cb(null, { $_id: '_parent', Answer: true, answer: '(error)', llmError: e.message }); });
+			},
+			// reactive synthesis: an answered child appends its OWN id to the parent's
+			// grow-only `answeredBy` (race-free `{__push}` — distinct ids, no lost update).
+			reportUp: function ( graph, concept, scope, argz, cb ) {
+				var selfId = scope._._id, parentId = scope._.parentSeg;
+				cb(null, [
+					{ $$_id: parentId, answeredBy: { __push: selfId } },
+					{ $_id: '_parent', ReportUp: true }
+				]);
+			},
+			// fires once the completion gate holds; reads children's answers in
+			// `expandedInto` order (deterministic) and writes the BOUNDED parent answer.
+			rollup: function ( graph, concept, scope, argz, cb ) {
+				var kids = (scope._.expandedInto || []).map(function ( id ) {
+					var e = graph.getEtty(id);
+					return e && e._.answer;
+				});
+				Promise.resolve(rollupFn(scope._, kids)).then(function ( ans ) {
+					cb(null, { $_id: '_parent', Rollup: true, Answered: true, answer: ans });
+				}).catch(function ( e ) { cb(null, { $_id: '_parent', Rollup: true, Answered: true, answer: '(error)', llmError: e.message }); });
+			}
+		}
+	};
+}
+
+/**
+ * Bottom-up synthesis: post-order walk from rootId; each non-leaf segment's answer
+ * is rollupFn(segmentFacts, childAnswers) (which MUST be bounded — a summary, not a
+ * concatenation, in real use). Writes the answer back onto each segment (so it's in
+ * the graph + traced) and returns the root answer. Race-free (deterministic walk).
+ *
+ * @param graph
+ * @param rootId   the root segment id
+ * @param rollupFn (segFacts, childAnswers[]) -> answer string
+ */
+function synthesize( graph, rootId, rollupFn ) {
+	// async: rollupFn may be an LLM call. Post-order, sequential (leaves first).
+	async function answerOf( segId ) {
+		var o = graph.getEtty(segId);
+		if ( !o ) return undefined;
+		var e    = o._,
+		    kids = e.expandedInto || [];
+		if ( !kids.length ) return e.answer;// leaf: already answered by the Answer concept
+		var childAnswers = [];
+		for ( var i = 0; i < kids.length; i++ ) childAnswers.push(await answerOf(kids[i]));
+		var ans = await rollupFn(e, childAnswers);
+		graph.pushMutation({ $$_id: segId, answer: ans, Synthesized: true }, segId);
+		return ans;
+	}
+	return answerOf(rootId);
+}
+
+module.exports = {
+	loopConceptTree        : loopConceptTree,
+	reactiveLoopConceptTree: reactiveLoopConceptTree,
+	makeDecomposeProviders : makeDecomposeProviders,
+	synthesize             : synthesize
+};

package/lib/authoring/master-loop.js

@@ -0,0 +1,132 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * master-loop — the ALWAYS-ON MASTER LOOP (host-side controller, ZERO-CORE). M1 of the productization
+ * campaign; the standing controller that wires the master-graph supervisor ARMS into ONE cost-ordered loop
+ * (master-graph study §2.2 — the value-of-computation ladder). Per incoming problem it climbs the ladder
+ * and takes the FIRST arm that resolves at acceptable cost:
+ *
+ *   MATCH    — exact cache hit on the K1 signature                       → 0 model calls (the warm library).
+ *   RETRIEVE — fuzzy recall (U5) → typed VERIFY: full → replay (0);       → 0 (full) or partial cost
+ *              partial → mount the shared skeleton + RE-FORGE only the diff.
+ *   FORGE    — the expensive path (fork + LLM + crystallize into the      → full cost; warms the library.
+ *              library); the mount policy (U2) picks the regime.
+ *   ESCALATE — a method pinned to the K1 floor (deopted K times) always   → full cost, never cached.
+ *              re-forges / stays in the LLM.
+ *
+ * DRIFT: when a premise changes, `drift(problem)` invalidates the method's cache entry and records a deopt
+ * (U2 mount-rank descends toward the ESCALATE floor → the adapt loop terminates). Re-aggregation of a
+ * derived summary is the caller's `reaggregate` arm (U3). The controller is DOMAIN-AGNOSTIC: the caller
+ * injects `signature`, `forge`, and (optionally) `reForge`; everything else is the built library machinery.
+ *
+ *   const loop = createMasterLoop({ signature, forge, reForge, mount: createMountController() });
+ *   const r = await loop.solve(problem);   // { result, arm, regime, cost }
+ *   loop.drift(problem);                    // a premise changed → invalidate + deopt
+ */
+const { digest } = require('../providers/canonicalize.js');
+const { createRecallIndex, recallAndVerify } = require('./recall.js');
+const { createMountController } = require('./mount.js');
+
+function canon( x ) {
+	if ( x === undefined ) return 'null';
+	if ( x === null || typeof x !== 'object' ) return JSON.stringify(x);
+	if ( Array.isArray(x) ) return '[' + x.map(canon).join(',') + ']';
+	return '{' + Object.keys(x).sort().map(( k ) => JSON.stringify(k) + ':' + canon(x[k])).join(',') + '}';
+}
+
+/**
+ * @param opts.signature  (problem) => { structure, content }   the typed K1 signature (required).
+ *                        STRUCTURE defines the method class (mount/deopt key); CONTENT is what's derived.
+ * @param opts.forge      async (problem, ctx) => { result, cost, signals? }   the expensive path (required).
+ * @param opts.reForge    async (problem, candidate, reForgeKeys, ctx) => { result, cost }   partial re-forge
+ *                        of only the differing content on a recalled skeleton (default: falls back to forge).
+ * @param opts.cache      a Map-like { has,get,set,delete } (default: in-memory Map). Pass a disk-backed
+ *                        store (M2) to make the library survive restarts.
+ * @param opts.index      a recall index (default: createRecallIndex()).
+ * @param opts.mount      a mount controller (default: createMountController()).
+ * @param opts.recallK    how many candidates recall proposes (default 3).
+ * @param opts.signals    (problem, methodId) => mount signals (reliability/hitRate/depth/readOnlyFrontier).
+ */
+function createMasterLoop( opts ) {
+	opts = opts || {};
+	const signature = opts.signature || (( p ) => ({ structure: p, content: {} }));
+	const forge = opts.forge;
+	const reForge = opts.reForge || ((( p, c, ks, ctx ) => forge(p, ctx)));   // no partial path → forge fully
+	const cache = opts.cache || new Map();
+	const index = opts.index || createRecallIndex();
+	const mount = opts.mount || createMountController();
+	const recallK = opts.recallK || 3;
+	const signalsOf = opts.signals || (() => ({}));
+	if ( typeof forge !== 'function' ) throw new Error('master-loop: opts.forge is required');
+
+	const stats = { match: 0, recallFull: 0, recallPartial: 0, forge: 0, escalate: 0, cost: 0, calls: 0 };
+	const keyOf = ( sig ) => digest({ s: canon(sig.structure), c: canon(sig.content) });
+	const idOf = ( sig ) => digest({ s: canon(sig.structure) });   // method CLASS id (mount/deopt key)
+	const hits = {};   // idOf -> {hit, total}  (a cheap hit-rate signal for the mount policy)
+
+	function bump( id, hit ) { const h = hits[id] || (hits[id] = { hit: 0, total: 0 }); h.total++; if ( hit ) h.hit++; }
+	function sig2signals( problem, id ) { const h = hits[id] || { hit: 0, total: 0 }; return Object.assign({ hitRate: h.total ? h.hit / h.total : 0 }, signalsOf(problem, id)); }
+
+	async function solve( problem ) {
+		stats.calls++;
+		const sig = signature(problem), key = keyOf(sig), id = idOf(sig);
+
+		// ── ESCALATE floor: a method deopted to the floor never replays — always re-forge / stay in the LLM.
+		if ( mount.regimeOf(id) === 'escalate' ) {
+			stats.escalate++; bump(id, false);
+			const r = await forge(problem, { id, sig, regime: 'escalate' });
+			stats.cost += (r.cost || 0);
+			return { result: r.result, arm: 'escalate', regime: 'escalate', cost: r.cost || 0 };
+		}
+
+		// ── MATCH: exact cache hit on the K1 signature → 0 model calls.
+		if ( cache.has(key) ) {
+			stats.match++; bump(id, true);
+			const regime = mount.decide(id, sig2signals(problem, id)).regime;
+			return { result: cache.get(key), arm: 'match', regime, cost: 0 };
+		}
+
+		// ── RETRIEVE: fuzzy recall → typed verify.
+		const cand = recallAndVerify(index, sig, recallK);
+		if ( cand && cand.verdict.mode === 'full' ) {
+			stats.recallFull++; bump(id, true); cache.set(key, cand.method);
+			const regime = mount.decide(id, sig2signals(problem, id)).regime;
+			return { result: cand.method, arm: 'recall-full', regime, cost: 0 };
+		}
+		if ( cand && cand.verdict.mode === 'partial' ) {
+			stats.recallPartial++; bump(id, false);
+			const r = await reForge(problem, cand, cand.verdict.reForge, { id, sig });
+			stats.cost += (r.cost || 0);
+			cache.set(key, r.result); index.add(sig, r.result);
+			const regime = mount.decide(id, sig2signals(problem, id)).regime;
+			return { result: r.result, arm: 'recall-partial', regime, cost: r.cost || 0, reForged: cand.verdict.reForge };
+		}
+
+		// ── FORGE: the expensive path; warms the library + the recall index.
+		stats.forge++; bump(id, false);
+		const r = await forge(problem, { id, sig, regime: 'instance' });
+		stats.cost += (r.cost || 0);
+		cache.set(key, r.result); index.add(sig, r.result);
+		const regime = mount.decide(id, Object.assign(sig2signals(problem, id), r.signals)).regime;
+		return { result: r.result, arm: 'forge', regime, cost: r.cost || 0 };
+	}
+
+	/** a premise drifted → invalidate this method (cache AND recall index) + record a deopt (U2 mount-rank
+	 *  descends toward the floor). The next solve RE-DERIVES — it must never recall the stale method. */
+	function drift( problem ) {
+		const sig = signature(problem), key = keyOf(sig), id = idOf(sig);
+		cache.delete(key);
+		if ( index.remove ) index.remove(sig);   // a drifted premise → re-derive, never replay the invalidated method
+		const deopts = mount.recordDeopt(id);
+		return { id, deopts, regime: mount.regimeOf(id) };
+	}
+
+	return { solve, drift, stats, cache, index, mount, keyOf, idOf };
+}
+
+module.exports = { createMasterLoop };

package/lib/authoring/mdl.js

@@ -0,0 +1,209 @@
+/*
+ * 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';
+/**
+ * mdl — a STATIC, corpus-level, bits-based MDL admission objective for grammar induction
+ * (#12, the §4.2-A front-end). The cheap pre-filter/ranker IN FRONT OF the empirical gate
+ * (`abstraction.evaluate`), NEVER a replacement.
+ *
+ * Where `evaluate` BOOTS the engine twice per candidate on ONE seed (grounded but expensive,
+ * single-episode, can over-fit a seed), `mdl` is O(corpus) arithmetic with NO boot: it
+ * aggregates the co-firing `count` mined across EVERY episode, so it ranks GENERALITY and
+ * prunes the many `mineChains` candidates BEFORE any boot. The one-criterion unification
+ * (Minton speedup ≡ SEQUITUR rule-utility ≡ smallest-grammar MDL ≡ Lari-Young weights).
+ *
+ * Two-part code length  L = L(library) + L(corpus | library):
+ *   - L(library)        = Σ_c schemaBits(c)               — bits to DESCRIBE the grammar
+ *   - L(corpus|library) = R · log2(N)                     — bits to PARSE the corpus (R records,
+ *                                                           each names one of N concepts)
+ * Promote a chain A→…→B (length ℓ, co-firing `count`) iff it shrinks total L:
+ *   savedBits = count·(ℓ−1)·log2(N)   each co-firing now names 1 abstract, not ℓ constituents
+ *   encodeBits = schemaBits(M)        the new production added to the library
+ *   taxBits = R·(log2(N+1) − log2(N)) the Minton/Lari-Young MATCH-COST tax: +1 symbol raises
+ *                                     EVERY record's parse cost
+ *   ΔL = encodeBits + taxBits − savedBits ;  admit iff ΔL < 0     (SEQUITUR "used ≥2×" in bits)
+ *
+ * SOUNDNESS DISCIPLINE: MDL only RANKS / PRE-PRUNES. It cannot verify fixpoint-equivalence or
+ * real model-cost, so it must never be the sole admit authority (false-admit risk). Compose it
+ * with `abstraction.makeAbstractionGate` as the authority via `composeGates` (MDL rejects
+ * cheaply; survivors boot once through the empirical gate).
+ *
+ *   const { rankCandidates, mdlGain, makeMdlGate, composeGates } = require('./mdl');
+ *   const ranked = rankCandidates(mineChains(records, tree), { tree, records, alphabet });
+ *   const gate = composeGates(makeMdlGate(ctx), makeAbstractionGate(ctx));   // cheap → authority
+ */
+const { eachConcept, refsOf, refKeyOf, templateKeys } = require('./validate.js');
+
+var LOG2 = Math.log(2);
+function log2( x ) { return Math.log(x) / LOG2; }
+
+// The discrete SYMBOLS a concept's schema spends (the same auditable spine the validator reads:
+// require refs + ensure/assert atoms + applyMutations template keys + the provider name).
+function symbolsOf( schema ) {
+	schema = (schema && schema._schema) || schema || {};
+	var reqs = refsOf(schema.require, false).map(function ( r ) { return refKeyOf(r).key; });
+	var ens  = refsOf(schema.ensure, true).concat(refsOf(schema.assert, true));
+	var tpl  = templateKeys(schema.applyMutations);
+	var prov = schema.provider ? [Array.isArray(schema.provider) ? schema.provider[0] : schema.provider] : [];
+	return reqs.length + ens.length + tpl.length + prov.length;
+}
+
+// |Σ| from a number, or a {knownFacts, conceptNames, palette} alphabet (deduped union).
+function alphabetSize( alphabet ) {
+	if ( typeof alphabet === 'number' ) return Math.max(2, alphabet);
+	var s = new Set();
+	(alphabet && alphabet.knownFacts   || []).forEach(function ( x ) { s.add(x); });
+	(alphabet && alphabet.conceptNames || []).forEach(function ( x ) { s.add(x); });
+	(alphabet && alphabet.palette      || []).forEach(function ( x ) { s.add(x); });
+	return Math.max(2, s.size);
+}
+
+/**
+ * Description length (bits) of ONE concept's schema: its symbol count encoded in the alphabet
+ * + a small ordinal structural constant (the fixed _id/_name/wrapper overhead). Per the plan,
+ * keep `structConst` ORDINAL — it places the rarity boundary, not an absolute fitted threshold.
+ */
+function schemaBits( concept, alphabet, opts ) {
+	opts = opts || {};
+	var structConst = opts.structConst != null ? opts.structConst : 4;
+	return symbolsOf(concept) * log2(alphabetSize(alphabet)) + structConst;
+}
+
+// L(corpus | library) = R · log2(N): R records each costing log2(N) bits to name a concept.
+function corpusBits( records, conceptCount ) {
+	var R = (records && records.length) || 0;
+	var N = Math.max(2, conceptCount || 0);
+	return R * log2(N);
+}
+
+function conceptCountOf( tree ) {
+	var n = 0;
+	eachConcept(tree, function ( c ) { if ( c && c._name ) n++; });
+	return n;
+}
+
+function conceptByName( tree, name ) {
+	var found = null;
+	eachConcept(tree, function ( c ) { if ( c && c._name === name ) found = c; });
+	return found;
+}
+
+/**
+ * The MDL gain of promoting one mined chain to an abstract production.
+ * @param opts.chain     a mineChains edge { from, to, via, count } (+ optional `length` ℓ, default 2)
+ * @param opts.tree      the concept tree (for N and the constituents' schema symbols)
+ * @param opts.records   the trace corpus (for R, the parse-tax base)
+ * @param opts.alphabet  Σ — a number, or { knownFacts, conceptNames, palette }
+ * @param opts.abstractSchema  (optional) the composed method's schema; else estimated from the
+ *                       constituents (sum of from+to symbols — the inlined chain's spine)
+ * @returns { deltaL, encodeBits, savedBits, taxBits, admit, count, ell, N, R }
+ */
+function mdlGain( opts ) {
+	opts = opts || {};
+	var chain = opts.chain || {};
+	var tree  = opts.tree;
+	var count = chain.count || 0;
+	var ell   = chain.length || 2;
+	var N     = conceptCountOf(tree);
+	var R     = (opts.records && opts.records.length) || 0;
+	// conceptNames default into the alphabet when not given explicitly.
+	var alphabet = opts.alphabet;
+	if ( alphabet && typeof alphabet === 'object' && !alphabet.conceptNames ) {
+		var names = [];
+		eachConcept(tree, function ( c ) { if ( c && c._name ) names.push(c._name); });
+		alphabet = Object.assign({}, alphabet, { conceptNames: names });
+	}
+
+	var encodeBits;
+	if ( opts.abstractSchema ) {
+		encodeBits = schemaBits(opts.abstractSchema, alphabet, opts);
+	} else {
+		// estimate the abstract method's description from its constituents (inlined spine).
+		var fromC = conceptByName(tree, chain.from), toC = conceptByName(tree, chain.to);
+		var syms  = symbolsOf(fromC) + symbolsOf(toC);
+		var structConst = opts.structConst != null ? opts.structConst : 4;
+		encodeBits = syms * log2(alphabetSize(alphabet)) + structConst;
+	}
+
+	var savedBits = count * (ell - 1) * log2(Math.max(2, N));
+	var taxBits   = R * (log2(N + 1) - log2(Math.max(2, N)));
+	var deltaL    = encodeBits + taxBits - savedBits;
+
+	return {
+		deltaL: deltaL, encodeBits: encodeBits, savedBits: savedBits, taxBits: taxBits,
+		admit: deltaL < 0, count: count, ell: ell, N: N, R: R,
+	};
+}
+
+/**
+ * Rank mined candidates by MDL gain (most-negative ΔL = best refactor first). Each is annotated
+ * with its `mdl` record. A cheap O(corpus) ordering to apply BEFORE any expensive boot.
+ * @returns the chains sorted ascending by ΔL, each `{ ...chain, mdl }`.
+ */
+function rankCandidates( chains, ctx ) {
+	ctx = ctx || {};
+	return (chains || [])
+		.map(function ( chain ) {
+			return Object.assign({}, chain, { mdl: mdlGain(Object.assign({}, ctx, { chain: chain })) });
+		})
+		.sort(function ( a, b ) { return a.mdl.deltaL - b.mdl.deltaL; });
+}
+
+/**
+ * The MDL gate in the shape `authorConcept`'s `spec.gate` expects. A cheap PRE-FILTER: it only
+ * judges 'add' proposals that carry their mined `chain` (so the corpus stats exist); without
+ * one it ABSTAINS (admit:true → defer to the authority gate). Reject = ΔL ≥ 0.
+ * @param ctx { tree, records, alphabet, structConst }  the corpus context (as for mdlGain)
+ * @param ctx.chainOf  (proposal)->chain   how to read the mined chain off a proposal
+ *                     (default: `proposal.chain`)
+ */
+function makeMdlGate( ctx ) {
+	ctx = ctx || {};
+	var chainOf = ctx.chainOf || function ( proposal ) { return proposal && proposal.chain; };
+	return function gate( graph, proposal ) {
+		if ( (proposal.op || 'add') !== 'add' ) return { admit: true };
+		var chain = chainOf(proposal);
+		if ( !chain ) return { admit: true, reason: 'mdl-abstain (no mined chain on proposal)' };
+		var schema = proposal.schema;
+		var g = mdlGain(Object.assign({}, ctx, { chain: chain, abstractSchema: schema }));
+		return { admit: g.admit, reason: g.admit ? null : 'mdl-reject (ΔL=' + g.deltaL.toFixed(2) + ' ≥ 0)', mdl: g };
+	};
+}
+
+/**
+ * Compose gates as a short-circuiting AND: run them in order, the FIRST reject wins (cheap
+ * gates first prune before the expensive authority boots). All-admit → the last gate's verdict
+ * (so the authority's `eval` rides through). Each gate is sync or async; the composite awaits.
+ */
+function composeGates() {
+	var gates = Array.prototype.slice.call(arguments);
+	return async function gate( graph, proposal ) {
+		var last = { admit: true };
+		for ( var i = 0; i < gates.length; i++ ) {
+			last = await gates[i](graph, proposal);
+			if ( !last || !last.admit ) return last;     // short-circuit on the first reject
+		}
+		return last;
+	};
+}
+
+module.exports = {
+	symbolsOf: symbolsOf, alphabetSize: alphabetSize, schemaBits: schemaBits, corpusBits: corpusBits,
+	conceptCountOf: conceptCountOf, mdlGain: mdlGain, rankCandidates: rankCandidates,
+	makeMdlGate: makeMdlGate, composeGates: composeGates,
+};

package/lib/authoring/memo-stability.js

@@ -0,0 +1,122 @@
+/*
+ * 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';
+/**
+ * memo-stability — the safety instrument for structure-learning (host-side, ZERO-CORE;
+ * study doc/WIP/studies/2026-06-26-…, promotes experiment F4).
+ *
+ * WHY. The engine's incrementality rides on the canonicalization memo: identical typed
+ * inputs to a concept ⇒ identical `<name>FactsDigest` ⇒ memo hit, no re-derivation. A
+ * structural change (addConcept/patchConcept, or a mined abstraction) is SAFE iff it is
+ * **memo-surface-preserving** — it must not alter the canonical facts that incumbent
+ * concepts' `require`/`ensure`/`assert` read. Violating this collapses the memo silently
+ * (the only "quiet failure" the adversarial lens identified). This module makes the F4
+ * boundary a reusable, gateable check.
+ *
+ *   const { memoSnapshot, memoDiff } = require('./memo-stability');
+ *   const before = memoSnapshot(graph, ['Consume']);   // incumbents to protect
+ *   graph.addConcept(null, candidateSchema, () => {
+ *     const { stable, changed } = memoDiff(before, memoSnapshot(graph, ['Consume']));
+ *     // stable === false ⇒ the candidate perturbed an incumbent's memo key ⇒ reject/rollback
+ *   });
+ *
+ * A concept's MEMO SURFACE = the fact keys its require/ensure/assert depend on (the same
+ * ref extraction `validate.js` uses, single source of truth). A snapshot digests, per
+ * (object × concept), the projection of the object's facts onto that surface — so a drift
+ * in any depended-on key shows up as a changed digest, while an isolated new fact does not.
+ */
+const canon = require('../providers/canonicalize.js');
+const { refsOf, refKeyOf } = require('./validate.js');
+
+const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+
+/** The fact keys a concept's require/ensure/assert read — its incremental memo surface. */
+function memoSurfaceKeys( graph, conceptName ) {
+	const c = graph.getConceptByName ? graph.getConceptByName(conceptName) : null;
+	const schema = (c && (c._schema || c)) || {};
+	const keys = new Set();
+	for ( const r of refsOf(schema.require, false) ) keys.add(refKeyOf(r).key);
+	for ( const fld of ['ensure', 'assert'] )
+		for ( const e of asArray(schema[fld]) )
+			if ( typeof e === 'string' ) for ( const r of refsOf(e, true) ) keys.add(refKeyOf(r).key);
+	return [...keys];
+}
+
+/**
+ * Capture the memo keys of the named incumbents across the live graph.
+ * @param graph         a live Graph
+ * @param conceptNames  incumbents to protect (default: every concept in the lib)
+ * @returns {{[key:string]: string}}  "<objId>|<conceptName>" -> digest of the depended-on facts
+ */
+function memoSnapshot( graph, conceptNames ) {
+	const out = {};
+	const names = conceptNames || Object.keys(graph._conceptLib || {});
+	const objs = graph._objById || {};
+	for ( const name of names ) {
+		const keys = memoSurfaceKeys(graph, name);
+		if ( !keys.length ) continue;
+		for ( const id of Object.keys(objs) ) {
+			const etty = objs[id] && objs[id]._etty;
+			const facts = etty && etty._;
+			if ( !facts ) continue;
+			const proj = {};
+			let has = false;
+			for ( const k of keys ) if ( k in facts ) { proj[k] = facts[k]; has = true; }
+			if ( has ) out[id + '|' + name] = canon.digest(proj);
+		}
+	}
+	return out;
+}
+
+/**
+ * Compare two snapshots. `stable` iff no depended-on memo key changed or disappeared.
+ * @returns {{ stable:boolean, changed:Array<{key,before,after}>, removed:string[], added:string[] }}
+ */
+function memoDiff( before, after ) {
+	const changed = [], removed = [];
+	for ( const k of Object.keys(before) ) {
+		if ( !(k in after) ) removed.push(k);
+		else if ( after[k] !== before[k] ) changed.push({ key: k, before: before[k], after: after[k] });
+	}
+	const added = Object.keys(after).filter((k) => !(k in before));
+	return { stable: changed.length === 0 && removed.length === 0, changed, removed, added };
+}
+
+/**
+ * Fail-closed CI gate around a structural change: snapshot the incumbents' memo keys, run
+ * `applyFn` (e.g. an addConcept/patchConcept install or a mined-abstraction adoption), and
+ * THROW if the change perturbed any of them. Wrap any structure-learning mutation in this so
+ * a memo-surface regression fails the build instead of silently collapsing the incremental memo.
+ * @returns the memoDiff on success (stable); throws an Error (with `.diff`) on instability.
+ */
+async function assertMemoStable( graph, incumbents, applyFn ) {
+	const before = memoSnapshot(graph, incumbents);
+	await applyFn();
+	const after = memoSnapshot(graph, incumbents);
+	const d = memoDiff(before, after);
+	if ( !d.stable ) {
+		const names = d.changed.map((c) => c.key).concat(d.removed).join(', ');
+		const e = new Error('memo-stability violation: ' + (names || 'incumbent memo keys changed') +
+			' — a structural change must be memo-surface-preserving (snapped, incumbents\' digests unchanged)');
+		e.diff = d;
+		throw e;
+	}
+	return d;
+}
+
+module.exports = { memoSnapshot, memoDiff, memoSurfaceKeys, assertMemoStable };