skynet-graph 1.2.0

package/lib/combos/learning-library.js

@@ -0,0 +1,253 @@
+/*
+ * 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';
+/**
+ * C3 — the LEARNING METHOD LIBRARY (roadmap P2 SKELETON → P3 complete). A thin assembly over the
+ * always-on master loop (the cost-ladder MATCH→RETRIEVE→FORGE→ESCALATE), a persistent method store,
+ * and the O(1) dispatch catalog — so a recurrent typed workload:
+ *   • AMORTIZES — a repeat problem elides the forge (MATCH → 0 model calls) once the library warms;
+ *   • SURVIVES a restart — the library is disk-backed (a fresh process replays at 0 calls);
+ *   • SHIPS — `pack()` → a portable `.sgc` a different deployment `load()`s and replays (version-gated);
+ *     `packAll()`/`loadAll()` ship the EXERCISED library = methods AND the grown typed lattice (the
+ *     registry: isa vocab + admitted synonym rings), each a version-gated single-kind `.sgc` bundle;
+ *   • RE-DERIVES on drift — `drift(problem)` invalidates the method (cache + recall) and deopts its
+ *     mount rank toward the ESCALATE floor, so the next solve re-forges only the violated entry.
+ *
+ * P2 laid the SKELETON: master-loop + store + dispatch catalog + `.sgc` portability, the §4 posture
+ * (durable store ON, validator/audit available; effectful forge opt-in). P3 COMPLETES it (all additive,
+ * `learning:false` default = the skeleton unchanged):
+ *   • `crystallizeFrom(records, ctx)` — distill methods from captured trace records
+ *     (crystallizeFromRecords pass-through; admitted candidates are indexed into the catalog);
+ *   • `learning:true` — the FORGE arm becomes the creative loop (adaptOrForgeAsync:
+ *     dispatch→hit(0 call)→antiUnify-adapt(1 call)→forge, verifier-gated, auto-indexed); the host
+ *     supplies the projections `target(problem)`/`dispatchFacts(problem)` and a forge that returns
+ *     `{candidate, calls}` (the method IS the amortized result). A `reject` THROWS a typed error
+ *     (fail-closed — a rejection must never be cached as a 0-call result). `drift()` then ALSO
+ *     invalidates the catalog-side template (library.invalidateTemplate) so the stale method cannot
+ *     re-`hit` at 0 calls right after the exact cache was evicted (correct-on-drift, both layers);
+ *   • `dispatch`/`blame`/`credit` — pure pass-throughs (library.dispatch, attributeSlot{Blame,Credit})
+ *     exposing the O(1) catalog lookup and the LOCALIZED blame/credit rules on mounted frames. The
+ *     AUTONOMOUS blame→revise loop is C5 (`relearn.js`), deliberately NOT here.
+ * The bricks stay usable "à nu" — this is an optional convenience over `Graph.authoring.*`.
+ *
+ * @param opts.signature (problem) => {structure, content}   the K1 signature; STRUCTURE = method class
+ *                       (mount/deopt key), CONTENT = what's derived. Default: identity on the problem.
+ * @param opts.forge     async (problem, ctx) => {result, cost, signals?}   the expensive path (REQUIRED).
+ *                       With `learning:true`: async (problem, ctx) => {candidate, calls} — ctx carries
+ *                       {scopeFacts, neighbours, donors} from the dispatch (reuse them = adapt).
+ * @param opts.reForge   optional partial re-forge of the differing content on a recalled skeleton.
+ * @param opts.store     a file PATH (→ disk-backed, cross-restart) or a Map-like store; default in-memory.
+ *                       NOTE with `learning:true` the exact cache holds METHOD candidates (they carry a
+ *                       provider fn) — use `pack()`/`load()` for cross-restart method portability; a
+ *                       JSON file store is for opaque (JSON-safe) results.
+ * @param opts.mount     a mount controller (default createMountController; opts.maxDeopt → its threshold).
+ * @param opts.recallK   fuzzy-recall breadth (default 3).
+ * @param opts.learning  OPT-IN (§4 default OFF). true → REQUIRES opts.target(problem) => {frontier,
+ *                       signatureKeys} and opts.dispatchFacts(problem) => scopeFacts (host projections;
+ *                       the combo never computes a signature/target — watch-point §11.1). Optional:
+ *                       opts.adaptContent(contentVars, scopeFacts) => {path:value} (the content-forger,
+ *                       may be async), opts.verify(candidate, scopeFacts) => bool (may be async),
+ *                       opts.interfaceRecall (§6.2 donor skeletons).
+ * @param opts.registry  optional grown typed lattice (a registry: isa vocab + synonym rings) the combo HOLDS
+ *                       so pack/load ship it with the methods. Host-supplied + host-grown (the combo never
+ *                       derives/grows it — loadLattice grows it through the registry's own admission gate).
+ * @param opts.*         the §4 knobs via resolveComboDefaults.
+ * @returns {{ solve, drift, stats, pack, load, packLattice, loadLattice, packAll, loadAll, registry,
+ *             library, loop, store, crystallizeFrom, dispatch, blame, credit }}
+ */
+
+var defaults = require('./defaults.js');
+var master = require('../authoring/master-loop.js');
+var mountMod = require('../authoring/mount.js');
+var libMod = require('../authoring/library.js');
+var storeMod = require('../authoring/store.js');
+var packMod = require('../authoring/method-pack.js');
+var latticeMod = require('../authoring/lattice-pack.js');
+var adaptMod = require('../authoring/adapt.js');
+var crystalMod = require('../authoring/crystallize.js');
+var parametric = require('../authoring/parametric.js');
+
+function createLearningLibrary( opts ) {
+	opts = opts || {};
+	var d = defaults.resolveComboDefaults(opts);
+	if ( typeof opts.forge !== 'function' ) throw new Error('createLearningLibrary needs opts.forge (async (problem, ctx) -> {result, cost})');
+	if ( d.learning && (typeof opts.target !== 'function' || typeof opts.dispatchFacts !== 'function') )
+		throw new Error('createLearningLibrary learning:true needs opts.target(problem) -> {frontier, signatureKeys} and opts.dispatchFacts(problem) -> scopeFacts');
+
+	// ── the persistent method store (the "library"): a file path → disk-backed (survives restart),
+	//    a Map-like → used as-is, else in-memory. This is the master-loop's exact-match cache. ────────
+	var store = (typeof opts.store === 'string') ? storeMod.createFileStore(opts.store)
+	          : (opts.store || new Map());
+
+	// ── the O(1) dispatch catalog (for the P3 adapt-or-forge creative loop; exposed now for wiring) ──
+	var library = opts.library || libMod.makeLibrary();
+
+	// ── the grown typed LATTICE (the registry: isa vocab + synonym rings). HOST-supplied + host-grown
+	//    (like target/dispatchFacts — the combo never derives/grows it; it only HOLDS the ref so pack/load
+	//    can ship it alongside the methods). null until a host passes one or loadLattice adopts one. ──────
+	var registry = opts.registry || null;
+
+	// ── the mount controller (regime + deopt-to-ESCALATE ladder) ────────────────────────────────────
+	var mount = opts.mount || mountMod.createMountController(opts.maxDeopt != null ? { thresholds: { maxDeopt: opts.maxDeopt } } : undefined);
+
+	// ── the FORGE arm. Default: the host's forge, raw (the skeleton). With `learning:true`: the
+	//    creative loop — adaptOrForgeAsync CHAINS dispatch(0-call hit)→antiUnify-adapt(1 call)→host
+	//    forge, gated + auto-indexed by the brick; the combo only CALLS the host projections and
+	//    renames candidate→result (the method IS the amortized unit). No invented signals (a policy
+	//    verdict would be combo logic — mount already gets hitRate from the loop's own bookkeeping);
+	//    the host keeps the opts.signals seam. A `reject` THROWS (fail-closed): the master loop would
+	//    otherwise cache it as a permanent 0-call result. ─────────────────────────────────────────────
+	var masterForge = opts.forge;
+	if ( d.learning ) masterForge = async function ( problem, ctx ) {
+		var r = await adaptMod.adaptOrForgeAsync({
+			lib            : library,
+			target         : opts.target(problem),
+			scopeFacts     : opts.dispatchFacts(problem),
+			adaptContent   : opts.adaptContent,
+			verify         : opts.verify,
+			interfaceRecall: opts.interfaceRecall,
+			recallK        : opts.recallK,
+			requireContract: d.failClosed,
+			blend          : opts.blend,   // B.4 — opt-in compositional-reuse rung (graft a donor before a fresh forge)
+			donor          : opts.donor,
+			combine        : opts.combine, // the 2nd composition operator (set-op) — opt-in, sibling to blend; the host
+			                               // resolves {left, right, op, outerClass?} for a set-op task (0 calls). The
+			                               // rung's outerClass defaults to the `target` above (re-keys the combined method).
+			forge          : function ( sf, neighbours, donors ) {
+				return opts.forge(problem, Object.assign({}, ctx, { scopeFacts: sf, neighbours: neighbours, donors: donors }));
+			}
+		});
+		if ( r.outcome === 'reject' ) {
+			var err = new Error('learning forge rejected: ' + r.reason);
+			err.outcome = 'reject'; err.reason = r.reason; err.calls = r.calls;
+			throw err;
+		}
+		return { result: r.candidate, cost: r.calls, outcome: r.outcome };
+	};
+
+	// ── the always-on master loop: MATCH→RETRIEVE→FORGE→ESCALATE ────────────────────────────────────
+	var loop = master.createMasterLoop({
+		signature: opts.signature,
+		forge    : masterForge,
+		reForge  : opts.reForge,
+		cache    : store,
+		mount    : mount,
+		recallK  : opts.recallK,
+		signals  : opts.signals
+	});
+
+	return {
+		loop   : loop,
+		store  : store,
+		library: library,
+
+		/** solve a problem through the cost ladder → {result, arm, regime, cost}. */
+		solve: function ( problem ) { return loop.solve(problem); },
+
+		/** a premise drifted → invalidate the method (cache + recall) + deopt its mount rank. With
+		 *  `learning:true` ALSO drop the catalog-side template for this site (invalidateTemplate) —
+		 *  else the next FORGE would re-`hit` the stale method at 0 calls (correct-on-drift). */
+		drift: function ( problem ) {
+			var r = loop.drift(problem);
+			if ( d.learning ) r.invalidated = libMod.invalidateTemplate(library, opts.target(problem), opts.dispatchFacts(problem)).invalidated;
+			return r;
+		},
+
+		/** P3 — distill methods from captured trace records (`methodTrace().records` off a live run):
+		 *  a PURE pass-through to crystallizeFromRecords (`ctx` carries {episodeTree, schemaGraph,
+		 *  declaredFrontier, equivKeys, proseKeys, minCount, all, idFor} — the combo is NOT tree-bound;
+		 *  traces from different trees may feed the same library). Every ADMITTED candidate is indexed
+		 *  into the dispatch catalog (in `all` mode, from res.candidates — indexMethod does not dedup). */
+		crystallizeFrom: function ( records, ctx ) {
+			var res = crystalMod.crystallizeFromRecords(Object.assign({ records: records }, ctx || {}));
+			var all = res.candidates || [res];
+			for ( var i = 0; i < all.length; i++ )
+				if ( all[i].admitted && all[i].candidate ) libMod.indexMethod(library, all[i].candidate);
+			return res;
+		},
+
+		/** P3 — the O(1) catalog lookup, exposed: → {key, candidates, scanned, total}. */
+		dispatch: function ( target, scopeFacts ) { return libMod.dispatch(library, target, scopeFacts); },
+
+		/** P3 — the LOCALIZED blame rule (per-slot): → {perAtom, role, admissible}. Admissible iff
+		 *  every failed atom maps to ONE role (else discard — the blame-gate). Pass-through. */
+		blame: function ( o ) { return parametric.attributeSlotBlame(o); },
+
+		/** P3 — the localized credit rule (blame's dual): → {perAtom, roles}. Pass-through. */
+		credit: function ( o ) { return parametric.attributeSlotCredit(o); },
+
+		/** the ladder counters {match, recallFull, recallPartial, forge, escalate, cost, calls}. */
+		stats: function () { return loop.stats; },
+
+		/** pack the warm library as a portable, version-stamped `.sgc` bundle (ship it). */
+		pack: function ( packOpts ) { return packMod.packMethods(loop, packOpts || {}); },
+
+		/** load a `.sgc` bundle into this library (version-gated — a stale package never silently
+		 *  replays). With `learning:true` (and the version gate passed) every loaded method that IS a
+		 *  candidate (schema + templatesBySig — the catalog's own unit, a shape read) is ALSO re-indexed
+		 *  into the dispatch catalog, so a fresh deployment 0-call `hit`s on dispatch (G-P3-5). The pack
+		 *  ships the EXERCISED library (recall-index entries); a crystallized-but-never-solved method
+		 *  re-crystallizes from its records (the durable source) — the honest portability boundary. */
+		load: function ( bundle, loadOpts ) {
+			var r = packMod.loadMethods(bundle, loop, loadOpts || {});
+			if ( d.learning && r.exactReplaySafe ) {
+				var ms = packMod.unpackMethods(bundle).methods, n = 0;
+				for ( var i = 0; i < ms.length; i++ )
+					if ( ms[i].method && ms[i].method.schema && ms[i].method.templatesBySig ) { libMod.indexMethod(library, ms[i].method); n++; }
+				r.catalogued = n;
+			}
+			return r;
+		},
+
+		/** the current grown typed lattice (the registry: isa vocab + synonym rings), or null. */
+		registry: function () { return registry; },
+
+		/** pack the grown typed LATTICE as a portable, version-stamped `.sgc kind:'lattice'` bundle — the
+		 *  runtime-grown canon (isa vocab + admitted synonym rings) ships alongside the methods. Packs the
+		 *  held registry (empty if the host never supplied one). Pass-through to lattice-pack. */
+		packLattice: function ( packOpts ) { return latticeMod.packLattice(registry, packOpts || {}); },
+
+		/** load a `.sgc kind:'lattice'` bundle into the held canon (version-gated). With a held registry it
+		 *  GROWS it through the SAME admission gate (mergeRingProposals — confluence-checked, conflicting
+		 *  aliases rejected); with none it ADOPTS the packaged canon. The grown registry becomes the held
+		 *  one (so a later packLattice ships it). Pass-through to lattice-pack. */
+		loadLattice: function ( bundle, loadOpts ) {
+			var r = latticeMod.loadLattice(bundle, registry, loadOpts || {});
+			if ( r.loadSafe && r.registry ) registry = r.registry;
+			return r;
+		},
+
+		/** SHIP BOTH in one call: the exercised library = the methods AND the grown lattice. Returns a plain
+		 *  `{ methods, lattice }` envelope of two single-kind `.sgc` bundles (NOT a new `.sgc` kind — each
+		 *  part stays a valid corpus/method/lattice bundle). `lattice` is null when no registry is held. */
+		packAll: function ( packOpts ) {
+			return { methods: packMod.packMethods(loop, packOpts || {}), lattice: registry ? latticeMod.packLattice(registry, packOpts || {}) : null };
+		},
+
+		/** load a `{ methods, lattice }` envelope (the packAll output) — methods then lattice, each
+		 *  version-gated by its own pack. Returns `{ methods, lattice }` load results (lattice null if absent). */
+		loadAll: function ( bundle, loadOpts ) {
+			bundle = bundle || {};
+			var m = bundle.methods ? this.load(bundle.methods, loadOpts) : null;
+			var l = bundle.lattice ? this.loadLattice(bundle.lattice, loadOpts) : null;
+			return { methods: m, lattice: l };
+		}
+	};
+}
+
+module.exports = { createLearningLibrary: createLearningLibrary };

package/lib/combos/mixture-serve.js

@@ -0,0 +1,193 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * C8 — the MIXTURE-RUNTIME server (owner "cerveau gauche × LLM intuitif", 2026-07-09). A cheap local model,
+ * ORIENTED by a forged certified-method stock, serves what a trust-gate can vouch for at 0 big-model cost, and
+ * ESCALATES the rest to a bigger/frontier tier (the tiered corrector, proven 10/16). A thin assembly over the
+ * proven arc — orientation (exact 5→8/36 gold-free, `WIP/experiments/2026-07-09-orientation` + `…-mixture-runtime`)
+ * + tiered correction (`…-tiered-correction`) — adding only the runtime trust-gate.
+ *
+ * ⟐ THE HONEST GUARANTEE (kill-gated live on Spider, Ministral-8B; the confront de-leaked the numbers):
+ *   1. 0-FALSE lives on the LEARNED CERTIFIED LAYER, never on the decomposition PICK. The stock's shapes are
+ *      gold-certified at forge time (`stock.js#goldGate`); at runtime a shape is only ever SERVED-AS-CERTIFIED if
+ *      it is in that vocabulary. We NEVER claim the small's chosen shape is correct — that is "pas gagné" (owner).
+ *   2. ORIENTATION improves the SCORE, not the soundness: the certified menu lifts the small's exact-match
+ *      (+3/36 gold-free, measured) — a quality lever, cost-free, no guarantee attached.
+ *   3. The TRUST-GATE is a CONFIDENCE gate, not a truth oracle. The only gate that reached 0-false live is
+ *      CROSS-AGREEMENT — the small's oriented shape EQUALS an INDEPENDENT predictor's shape (surface k-NN). Two
+ *      independent signals concurring = trustable (100% precision live, ~38% recall). Self-consistency and a
+ *      self-fit check did NOT separate correct from a confidently-wrong misread (a systematic misread is stable).
+ *      ⚠ SCALE ERRATUM (2026-07-10, `WIP/experiments/2026-07-10-mixture-scale`, N=201 stratified over the FULL
+ *      Spider dev distribution, 12% in-stock coverage): the "100%" was the n≤8 small-sample bound coming home —
+ *      at scale surface cross-agreement admits 6/8 WRONG (25% precision): on an out-of-stock query surface-CLOSE
+ *      to a certified class, the menu-steered small and the surface k-NN agree on the same wrong certified shape
+ *      (independence of signals does not make the QUERY separable). CONFIRMED AT HIGH COVERAGE TOO (FinQA N=120,
+ *      85% traffic-covered stock: precision 42% — `2026-07-10-finqa-mixture-scale`): the failure is not the
+ *      uncovered mass, surface agreement is simply not a truth signal. DO NOT ship cross-agreement as a 0-false
+ *      trust tier; the fail-closed default (nothing auto-trusted) stays the safe wiring, and forge-time admission
+ *      (oracle-gated) is a DIFFERENT, untouched layer. A trustable runtime tier needs a typed/grounded signal
+ *      (per-query executable verification, deterministic slot-checker) — open work, tracked in the ledger.
+ *      ⚠ INDEPENDENCE IS LOAD-BEARING (live finding): the cross-agreement precision COLLAPSES (100%→60% live) if
+ *      `proposeMenu` and `predict` share the SAME surface signal — the menu then STEERS the small toward the very
+ *      shape the predictor will name, so "agreement" is circular. Wire the FLAT certified menu (default) for
+ *      orientation and keep `predict` as the independent signal; do NOT surface-narrow the menu AND predict from
+ *      the same k-NN (narrowing is a large-stock optimization, but then use a DIFFERENT independent predictor).
+ *   4. ESCALATION carries the residual: whatever the trust-gate does not vouch for goes to the big tier (no false
+ *      negative — the caller always gets an answer). The big model, not the gate, is what corrects a misread.
+ *   5. PRE-ROUTING is where the amortization actually lives (Fable-review correction, verified on the memoized
+ *      traces `WIP/experiments/2026-07-09-amortization-e2e/prerouting.js`): gate-AFTER-small makes every query pay
+ *      the small pass, so a high escalation rate costs MORE than big-alone (+28% live). A TEXT-ONLY router that
+ *      sends predicted-uncovered queries STRAIGHT to the big tier (skipping the wasted small pass) turns the same
+ *      k-NN predictor into +2%, and a perfect covered/uncovered router into −18%. `preRoute` wires that router
+ *      BEFORE the small call; it never touches the trust decision (a pre-routed serve is a plain escalation).
+ * So: closed-vocabulary soundness + a small MEASURED 0-false trusted tier + a raw-score lift + escalation of the
+ * rest. The amortization is `1 − escalation-rate`; grow it by growing the stock / a tighter independent predictor,
+ * and CAPTURE it by pre-routing (route-then-gate, never pay-small-first).
+ *
+ * Bricks stay usable "à nu": `small`/`big`/`proposeMenu`/`predict` are all INJECTED (the combo owns no model and
+ * no corpus). `makeSurfaceDispatch` is an optional helper that builds `proposeMenu`+`predict` from a labelled
+ * anchor corpus (TF-IDF k-NN) — the surface signal is real (+20 pts over permuted-labels) but modest over the
+ * frequency prior, so it is an OPTIMIZATION (narrow a large stock + feed the cross-agreement gate), never load-bearing.
+ *
+ *   const sd = makeSurfaceDispatch({ anchors: [{text, shape}, …], k: 5 });
+ *   const mx = createMixtureServe({ certifiedShapes, small, big, proposeMenu: sd.proposeMenu, predict: sd.predict });
+ *   const r = await mx.serve(query);   // { shape, tier:'local-trusted'|'escalated'|'local-untrusted', certified, … }
+ *
+ * @param opts.certifiedShapes  REQUIRED array<string> — the learned 0-false vocabulary (from the forged `.sgc` stock).
+ * @param opts.small     REQUIRED async (query, menu) => shape — the cheap tier-1 model, oriented by `menu`.
+ * @param opts.big       optional async (query, menu) => shape — the tier-2 escalation (frontier corrector). Absent
+ *                       → an untrusted result is returned tagged `local-untrusted` (the host decides), never forced.
+ * @param opts.proposeMenu optional (query) => array<string> — the oriented menu (surface-narrowed); default = the
+ *                       flat certified vocabulary (already gold-free; narrowing is the optional optimization).
+ * @param opts.predict   optional (query) => shape — an INDEPENDENT shape predictor (surface k-NN). Enables the
+ *                       default CROSS-AGREEMENT trust-gate. Without it (and without `trust`) nothing is auto-trusted
+ *                       (fail-closed: everything escalates) — we never auto-trust a bare certified shape (47% live).
+ * @param opts.trust     optional (query, shape, ctx{menu,predicted}) => bool — override the trust predicate.
+ * @param opts.preRoute  optional true | (query, ctx{predicted,menu}) => bool — route-then-gate (the amortization
+ *                       capture): decided BEFORE the small call; `true` routes a query whose predicted shape is
+ *                       OUTSIDE the certified vocabulary straight to `big` (needs `predict`); a function is a
+ *                       custom router (return true = go direct). Inert without a `big` tier (fail-safe: the small
+ *                       path still serves). A pre-routed record is `tier:'escalated', preRouted:true`.
+ * @param opts.onServe   optional (record) => void — a per-serve hook (telemetry).
+ * @returns {{ serve, stats, certifiedShapes }}
+ */
+function createMixtureServe( opts ) {
+	opts = opts || {};
+	var shapes = opts.certifiedShapes;
+	if ( !Array.isArray(shapes) || !shapes.length ) throw new Error('createMixtureServe needs opts.certifiedShapes (the learned certified vocabulary from the forged stock)');
+	if ( typeof opts.small !== 'function' ) throw new Error('createMixtureServe needs opts.small (async (query, menu) -> shape) — the cheap tier-1 model');
+	var certified = Object.create(null); shapes.forEach(function ( s ) { certified[s] = true; });
+	var big = (typeof opts.big === 'function') ? opts.big : null;
+	var proposeMenu = (typeof opts.proposeMenu === 'function') ? opts.proposeMenu : function () { return shapes; };
+	var predict = (typeof opts.predict === 'function') ? opts.predict : null;
+	// default trust = CROSS-AGREEMENT when an independent predictor is given; else fail-closed (never auto-trust).
+	var trust = (typeof opts.trust === 'function') ? opts.trust
+		: (predict ? function ( q, shape, ctx ) { return shape === ctx.predicted; } : function () { return false; });
+	var onServe = (typeof opts.onServe === 'function') ? opts.onServe : null;
+	// pre-router (route-then-gate): default = predicted shape outside the certified vocabulary → go direct to big.
+	var router = (typeof opts.preRoute === 'function') ? opts.preRoute
+		: (opts.preRoute ? function ( q, ctx ) { return !certified[ctx.predicted]; } : null);
+	if ( router && !predict && typeof opts.preRoute !== 'function' ) throw new Error('createMixtureServe preRoute:true needs opts.predict (the text-only covered/uncovered signal) — or pass a custom router function');
+	var stats = { served: 0, localTrusted: 0, escalated: 0, localUntrusted: 0, preRouted: 0 };
+
+	async function serve( query ) {
+		stats.served++;
+		var menu = proposeMenu(query) || shapes;
+		var predicted = predict ? predict(query) : undefined;   // ONE predict call: shared by the router and the gate
+		if ( router && big && router(query, { predicted: predicted, menu: menu }) ) {
+			var dshape = await big(query, menu);
+			stats.preRouted++; stats.escalated++;
+			var drec = { shape: dshape, tier: 'escalated', certified: !!certified[dshape], trusted: false, preRouted: true, predicted: predicted };
+			if ( onServe ) onServe(Object.assign({ query: query }, drec));
+			return drec;
+		}
+		var shape = await opts.small(query, menu);
+		var isCert = !!certified[shape];
+		var trusted = isCert && !!trust(query, shape, { menu: menu, predicted: predicted });
+		var rec;
+		if ( trusted ) {
+			stats.localTrusted++;
+			rec = { shape: shape, tier: 'local-trusted', certified: true, trusted: true, predicted: predicted };
+		} else if ( big ) {
+			var bshape = await big(query, menu);
+			stats.escalated++;
+			rec = { shape: bshape, tier: 'escalated', certified: !!certified[bshape], trusted: false, local: shape, predicted: predicted };
+		} else {
+			stats.localUntrusted++;
+			rec = { shape: shape, tier: 'local-untrusted', certified: isCert, trusted: false, predicted: predicted };
+		}
+		if ( onServe ) onServe(Object.assign({ query: query }, rec));
+		return rec;
+	}
+
+	return { serve: serve, stats: stats, certifiedShapes: shapes.slice() };
+}
+
+// --- makeSurfaceDispatch: the KG-1 surface signal promoted to a reusable brick (TF-IDF k-NN over labelled anchors).
+
+var STOP = { 'the': 1, 'a': 1, 'an': 1, 'of': 1, 'to': 1, 'in': 1, 'on': 1, 'for': 1, 'and': 1, 'or': 1, 'is': 1, 'are': 1, 'was': 1, 'were': 1, 'be': 1, 'with': 1, 'by': 1, 'at': 1, 'as': 1, 'from': 1, 'that': 1, 'this': 1, 'these': 1, 'those': 1, 'what': 1, 'which': 1, 'who': 1, 'how': 1, 'many': 1, 'much': 1, 'list': 1, 'show': 1, 'give': 1, 'find': 1, 'name': 1, 'number': 1, 'count': 1, 'all': 1, 'each': 1, 'every': 1, 'their': 1, 'its': 1, 'there': 1 };
+function tokenize( s ) { return String(s || '').toLowerCase().split(/[^a-z0-9]+/).filter(function ( w ) { return w && w.length > 1 && !STOP[w]; }); }
+function vectorize( toks, idf ) {
+	var tf = {}, i; for ( i = 0; i < toks.length; i++ ) tf[toks[i]] = (tf[toks[i]] || 0) + 1;
+	var v = {}, n = 0, w; for ( w in tf ) { var x = tf[w] * (idf[w] || 0); v[w] = x; n += x * x; }
+	n = Math.sqrt(n) || 1; for ( w in v ) v[w] /= n; return v;
+}
+function cosine( a, b ) { var s = 0, x = a, y = b, w; if ( Object.keys(a).length > Object.keys(b).length ) { x = b; y = a; } for ( w in x ) if ( y[w] ) s += x[w] * y[w]; return s; }
+
+/**
+ * Build the surface-dispatch pair (`proposeMenu` + `predict`) from a labelled anchor corpus — the same signal the
+ * KG-1 kill-gate measured (real geometry, +20 pts over permuted-labels; modest over the frequency prior, so an
+ * optimization). Deterministic (pure TF-IDF, index-stable tie-breaks). The anchors are TRAINING queries of the
+ * certified classes (their `shape` is the training label) — no runtime gold.
+ * @param opts.anchors  REQUIRED array<{ text, shape }> — labelled training queries.
+ * @param opts.k        proposal menu size (default 5).
+ * @returns {{ proposeMenu, predict }} — proposeMenu(query) => top-k distinct shapes (cosine-vote); predict(query)
+ *          => the single top-1 shape (for the cross-agreement trust-gate).
+ */
+function makeSurfaceDispatch( opts ) {
+	opts = opts || {};
+	var anchors = opts.anchors;
+	if ( !Array.isArray(anchors) || !anchors.length ) throw new Error('makeSurfaceDispatch needs opts.anchors ([{text, shape}])');
+	var K = opts.k == null ? 5 : opts.k;
+	var toks = anchors.map(function ( a ) { return tokenize(a.text); });
+	var df = {}; toks.forEach(function ( t ) { var seen = {}, i; for ( i = 0; i < t.length; i++ ) if ( !seen[t[i]] ) { seen[t[i]] = 1; df[t[i]] = (df[t[i]] || 0) + 1; } });
+	var idf = {}, w; for ( w in df ) idf[w] = Math.log((anchors.length + 1) / (df[w] + 1)) + 1;
+	var vecs = toks.map(function ( t ) { return vectorize(t, idf); });
+
+	// ranked (shape -> summed cosine) over ALL anchors, ties broken by lexical shape then first-seen index.
+	function rankShapes( query ) {
+		var qv = vectorize(tokenize(query), idf), byShape = {}, i;
+		for ( i = 0; i < anchors.length; i++ ) { var sh = anchors[i].shape, s = cosine(qv, vecs[i]); byShape[sh] = (byShape[sh] || 0) + s; }
+		return Object.keys(byShape).sort(function ( a, b ) { return (byShape[b] - byShape[a]) || (a < b ? -1 : 1); });
+	}
+	return {
+		proposeMenu: function ( query ) { return rankShapes(query).slice(0, K); },
+		predict: function ( query ) { return rankShapes(query)[0] || null; }
+	};
+}
+
+/**
+ * qualifyMenu — present the certified shapes with their SLOT QUALIFICATIONS so the small conforms to the reference
+ * vocabulary instead of deviating off-menu (the owner's "meilleure qualification des slots"). Kill-gated live: a
+ * slot-glossed menu lifted in-stock exact-match +3/18 (8→11) over the opaque shape strings, because the loss is
+ * CONFORMANCE (the small emits an off-reference shape), not selection-among-options (KG-3). Pure/deterministic; the
+ * host supplies the domain gloss (a step→meaning map — the "role" the lattice types each slot with).
+ * @param shapes    array<string> — the certified shapes (e.g. "join>filter>select").
+ * @param glossMap  { <stepKind>: "human meaning" } — the per-slot role. Missing kinds echo the kind.
+ * @param sep       the step separator inside a shape (default '>').
+ * @returns array<string> — each shape annotated "shape (kind=meaning, …)" for the orientation prompt.
+ */
+function qualifyMenu( shapes, glossMap, sep ) {
+	var s = sep || '>', g = glossMap || {};
+	return (shapes || []).map(function ( shape ) {
+		var parts = String(shape).split(s).map(function ( k ) { return k + '=' + (g[k] || k); });
+		return shape + ' (' + parts.join(', ') + ')';
+	});
+}
+
+module.exports = { createMixtureServe: createMixtureServe, makeSurfaceDispatch: makeSurfaceDispatch, qualifyMenu: qualifyMenu };

package/lib/combos/plan-loop.js

@@ -0,0 +1,192 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * plan-loop — C7, the HIERARCHICAL PLAN LOOP (design `WIP/2026-07-07-design-r1-plan-loop.md`; kill-gated R1:
+ * KG-R1a the channel + KG-R1b the fixpoint). A task LONGER THAN THE CONTEXT is decomposed into typed leaves,
+ * each leaf sees only a PROJECTED digest (never the whole task), leaves are served by the cost ladder, the plan
+ * is driven to a BALANCED fixpoint (rebalance brick), and reassembly is VERIFIED — a leaf whose required facts
+ * are missing is REFUSED (never a silent wrong), and reassembly reads nothing uncovered (never a claim-of-absence).
+ *
+ * THIN assembly (the combo doctrine — no new logic; a missing piece goes into a brick):
+ *   decompose (injected: typed-loop)  →  project + leaf pre-contract  →  serveLeaf (injected: the C6 ladder,
+ *   match→retrieve→forge→ESCALADE frontier — kill-gate finding: escalation is LOAD-BEARING on hard/novel leaves,
+ *   C-local alone is model-capability-bound)  →  rebalancePlan (E2∘E1∘E3∘E4)  →  checkReassembly (checkCompose).
+ *
+ * Both heavy stages are INJECTED so the combo stays usable "à nu" and testable without a model: production wires
+ *   decompose = typed-loop's recursive typed decompose,   serveLeaf = createProxyCache(...).solve  (the C6 ladder).
+ *
+ *   const { createPlanLoop } = require('skynet-graph').combos;   // or Graph.combos.createPlanLoop
+ *   const loop = createPlanLoop({ decompose, serveLeaf });
+ *   const { answer, converged, refused, reassembly } = await loop.run(task, ctx);
+ *   // ctx.givens = { key: value } (givens.js#seedOf): the task's BASE FACTS, seeded into the projection pool as
+ *   // val_<key> — a leaf citing a given key in readsExtra gets the value injected into its bounded inputs (gap i).
+ */
+const { rebalancePlan, checkReassembly } = require('../authoring/rebalance.js');
+const { createContextProjection } = require('../authoring/context-project.js');
+const { stableStringify } = require('../providers/cache.js');
+
+const tok = ( s ) => Math.ceil(String(s == null ? '' : s).length / 4);
+
+// leaf pre-contract (default): a typed request is COMPLETE iff no required field is null/'' (a severed digest
+// amputates one → refused AT PROJECTION, before any serve). Shallow + one level into a `filters` array. ──
+function defaultComplete( request ) {
+	if ( !request || typeof request !== 'object' ) return false;
+	for ( const k of Object.keys(request) ) {
+		const v = request[k];
+		if ( v === null || v === '' ) return false;
+		if ( Array.isArray(v) ) for ( const f of v ) if ( f && typeof f === 'object' )
+			for ( const kk of Object.keys(f) ) if ( f[kk] === null || f[kk] === '' ) return false;
+	}
+	return true;
+}
+
+// default answer fold — canonical {id: value | REFUSED}, sorted (deterministic; E4/refold semantics). ──
+function defaultFold( leaves ) {
+	const parts = [];
+	for ( const lf of leaves ) for ( const id of leafWrites(lf) )
+		parts.push([id, lf.refused ? 'REFUSED' : (lf.severed ? 'REFUSED' : String(lf.value == null ? '' : lf.value))]);
+	parts.sort(( a, b ) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+	return parts.map(( [id, v] ) => id + '=' + v ).join(';');
+}
+const leafWrites = ( n ) => n.bundle ? n.bundle.map(( r ) => r.id ) : [n.request && n.request.id];
+
+// sink fold — the answer is the LAST SINK's value (a leaf nobody reads; "the LAST part yields the final answer"
+// plans). Promoted from the KG-ZOOM harness (P1/P1.5, measured on 560 tasks). Wire as opts.fold: sinkFold. ──
+function sinkFold( leaves ) {
+	const needed = new Set(leaves.flatMap(( l ) => l.readsExtra || [] ));
+	const sinks = leaves.filter(( l ) => l.request && !needed.has(l.request.id) && !l.refused );
+	const last = sinks.length ? sinks[sinks.length - 1] : leaves[leaves.length - 1];
+	return last ? String(last.value == null ? '' : last.value) : '';
+}
+
+// degenerate decompose — the split FAILED (no leaves, or a single untyped task-echo leaf). With opts.fallback
+// the product answer is "don't split then": serve the WHOLE task, FLAGGED (never a silent wrong/undefined). ──
+function defaultIsDegenerate( leaves ) {
+	return leaves.length === 0 || (leaves.length === 1 && !(leaves[0] && leaves[0].request && leaves[0].request.kind));
+}
+
+/**
+ * createPlanLoop(opts)
+ * @param opts.decompose  REQUIRED async (task, ctx) => [{ id, request, nl }]  — the typed leaves (typed-loop in
+ *        production). May be DEGENERATE (redundant / disordered / an over-budget `{ bundle:[request,…] }`) — the
+ *        fixpoint repairs it. `request` is the leaf's typed request (the fusion key + contract are derived from it).
+ * @param opts.serveLeaf  REQUIRED async (leaf, ctx) => value  — the cost ladder (createProxyCache(...).solve).
+ * @param opts.isComplete (request) => bool   — the leaf pre-contract (default: no null/'' required field).
+ * @param opts.complete   (leaf) => promptString — the projection's prompt renderer, passed through to
+ *        createContextProjection (e.g. context-project's `stratComplete`). Caveat: the projected roadmap keys
+ *        are internal step ids (L0, L1…) — a host wanting figure-keyed prompts renders in serveLeaf instead.
+ * @param opts.fold       (servedLeaves) => answer   — the report fold (default: canonical {id:value|REFUSED};
+ *        `sinkFold` exported for "the LAST part yields the answer" plans).
+ * @param opts.fallback   async (task, ctx) => value — OPT-IN whole-task fallback when the decompose is DEGENERATE
+ *        (opts.isDegenerate, default: no leaves / single untyped echo): a failed split means "don't split", the
+ *        answer is served whole and FLAGGED `fallback:true` in the result (report it apart from pure-decomposed).
+ * @param opts.budget     node token budget (default 512) — a served digest over budget is an E2 scission target.
+ * @param opts.cap        fixpoint round cap (default from the brick).
+ * ctx.givens = base facts seeded as val_<key> (givens.js#seedOf) · ctx.labels = provenance labels
+ * (givens.js#labelsOf, the cells rule) — both ride into the context projection.
+ */
+function createPlanLoop( opts ) {
+	opts = opts || {};
+	if ( typeof opts.decompose !== 'function' ) throw new Error('createPlanLoop needs opts.decompose(task,ctx) -> [{id,request,nl}]');
+	if ( typeof opts.serveLeaf !== 'function' ) throw new Error('createPlanLoop needs opts.serveLeaf(leaf,ctx) -> value');
+	const budget = opts.budget || 512;
+	const isComplete = opts.isComplete || defaultComplete;
+	const fold = opts.fold || defaultFold;
+	const isDegenerate = opts.isDegenerate || defaultIsDegenerate;
+
+	// the rebalance spec — derived entirely from the leaves' TYPED requests (no new logic) ──
+	const spec = {
+		isLeaf: ( n ) => n.kind === 'leaf',
+		fusionKey: ( n ) => stableStringify(n.bundle ? n.bundle : n.request),
+		overBudget: ( n ) => n.kind === 'leaf' && (!!n.bundle || tok(n.digest) > budget),
+		split: ( n ) => (n.bundle || []).map(( r, i ) => ({ id: n.id + '_' + i, kind: 'leaf', request: r, nl: r.nl, refused: !isComplete(r), value: n.served && n.served[i] }) ),
+		writes: leafWrites,
+		reads: ( n ) => n.kind === 'root' ? (n.reads || []) : (n.readsExtra || []),
+		refold: ( root, leaves ) => fold(leaves),
+		contractOf: ( n ) => n.kind === 'root'
+			? { name: n.id, contract: { read: (n.reads || []), write: ['__answer'], effect: 'pure' } }
+			: { name: n.id, contract: { read: (n.readsExtra || []), write: leafWrites(n), effect: n.retract ? 'effect' : 'pure' } },
+	};
+
+	// serve the atomic leaves THROUGH the graph-native projection: build a roadmap from the leaves' footprint
+	// (a leaf's produces = a unique per-leaf key; its needs = the readsExtra it shares with a producing sibling),
+	// serve each leaf WITH its completed bounded context (upstream values relabelled to the figure key), in the
+	// emergent dependency order. A cyclic footprint → the projection's `guardPlan` returns a TYPED refusal (the
+	// intra-plan cycle detector) which run() surfaces — never a silent wedge, never a serve-despite-impossible-deps.
+	// Mutates lf.value / lf.projectedPrompt in place; returns the refusal string or null. ──
+	async function projectServe( atomic, producedKeys, task, ctx ) {
+		const givens = (ctx && ctx.givens) || {};                        // the task's base facts (givens.js) — ride as pre-satisfied needs
+		const writeKeyOf = ( l ) => leafWrites(l)[0];
+		const firstIdxOf = {}; atomic.forEach(( l, i ) => { const k = writeKeyOf(l); if ( k != null && !(k in firstIdxOf) ) firstIdxOf[k] = i; });
+		const stepId = ( i ) => 'L' + i, byStep = {}, writeKeyByStep = {};
+		atomic.forEach(( l, i ) => { byStep[stepId(i)] = l; writeKeyByStep[stepId(i)] = writeKeyOf(l); });
+		const roadmap = atomic.map(( l, i ) => ({ id: stepId(i), produces: stepId(i),
+			needs: (l.readsExtra || []).filter(( k ) => producedKeys.has(k) && firstIdxOf[k] !== i ).map(( k ) => stepId(firstIdxOf[k]) )
+				.concat((l.readsExtra || []).filter(( k ) => !producedKeys.has(k) && k in givens )) }) );
+		const serve = async ( s, c ) => {
+			const inputs = {}; for ( const k of Object.keys(s.inputs) ) inputs[writeKeyByStep[k] || k] = s.inputs[k];   // relabel producer-step id → figure key
+			// the projected prompt + provenance labels ride along (a host serveLeaf may use leaf.prompt as-is, or
+			// render its own from inputs + labels — the cells rule, givens.js#labelsOf).
+			return await opts.serveLeaf(Object.assign({}, byStep[s.id], { inputs: inputs, prompt: s.prompt, labels: s.labels }), c);
+		};
+		const statement = typeof task === 'string' ? task : (( ctx && ctx.statement ) || JSON.stringify(task));
+		const pr = await createContextProjection({ serve: serve, complete: opts.complete }).run(roadmap, Object.assign({ statement: statement }, ctx));
+		if ( pr.refusal ) return pr.refusal;                              // unresolvable structure (cycle) → surfaced, leaves unserved
+		for ( const s of roadmap ) { const l = byStep[s.id]; l.value = pr.results[s.id].value; l.projectedPrompt = pr.results[s.id].prompt; }
+		return null;
+	}
+
+	async function run( task, ctx ) {
+		// 1. DECOMPOSE (typed) → leaves (possibly degenerate)
+		const raw = await opts.decompose(task, ctx) || [];
+		// 1b. DEGENERATE + opts.fallback → the whole-task answer, FLAGGED (a failed split is "don't split",
+		//     never a silent String(undefined) nor an unexplained refusal when the host opted into the fallback).
+		if ( opts.fallback && isDegenerate(raw) ) {
+			const v = await opts.fallback(task, ctx);
+			return { answer: v, fallback: true, converged: true, refusal: null, refused: [],
+				reassembly: null, rounds: 0, monotone: true, trace: [], leaves: raw.length, projected: false };
+		}
+		// 2. PROJECT + leaf PRE-CONTRACT (a severed/incomplete request → refused AT PROJECTION, never served-then-guessed)
+		const leaves = raw.map(( n ) => Object.assign({ kind: 'leaf' }, n, { refused: !!n.bundle ? false : !isComplete(n.request) }) );
+		// 3. SERVE. Bundles are pre-served per atom (a scission concern). Admissible ATOMIC leaves are served through
+		//    the REAL context projection (lib/authoring/context-project): a leaf that reads another leaf's write is
+		//    served AFTER it, with the upstream value completed into its bounded context (the R1 §2 "contexte par
+		//    nœud" — no leaf sees the whole task). A decompose with NO intra-plan dependency degenerates to the
+		//    direct serve (all leaves are independent roots) — that IS the no-dependency case of the same projection,
+		//    kept as a fast path (redundant serves are cheap — the C6 cache dedupes).
+		for ( const lf of leaves ) if ( lf.bundle ) {
+			lf.served = []; for ( const r of lf.bundle ) lf.served.push(await opts.serveLeaf({ kind: 'leaf', request: r, nl: r.nl }, ctx));
+		}
+		const atomic = leaves.filter(( l ) => !l.bundle && !l.refused );
+		const producedKeys = new Set(atomic.map(( l ) => leafWrites(l)[0] ).filter(( k ) => k != null ));
+		const givens = (ctx && ctx.givens) || {};
+		const projected = atomic.some(( l ) => (l.readsExtra || []).some(( k ) => producedKeys.has(k) || k in givens ) );
+		let projRefusal = null;
+		if ( !projected ) { for ( const lf of atomic ) lf.value = await opts.serveLeaf(lf, ctx); }
+		else projRefusal = await projectServe(atomic, producedKeys, task, ctx);
+		// 4. BUILD the plan + REBALANCE to the fixpoint (E2 split → E1 dedupe → E3 reorder → E4 refold)
+		const producedIds = leaves.filter(( l ) => !l.refused ).flatMap(spec.writes).filter(Boolean);
+		const root = { id: '__root', kind: 'root', reads: producedIds, value: null };
+		const plan = { order: leaves.concat([root]) };
+		const rb = rebalancePlan(plan, spec, { cap: opts.cap });
+		// 5. VERIFIED REASSEMBLY (checkCompose sound + nothing uncovered)
+		const producers = rb.plan.order.filter(spec.isLeaf);
+		const reassembly = checkReassembly(root, producers, spec);
+		return {
+			answer: root.value, converged: rb.converged, refusal: projRefusal || rb.refusal,
+			refused: producers.filter(( p ) => p.refused ).flatMap(spec.writes).filter(Boolean),
+			reassembly, rounds: rb.rounds, monotone: rb.monotone, trace: rb.trace,
+			leaves: producers.length, projected: projected,
+		};
+	}
+
+	return { run: run, rebalance: rebalancePlan, spec: spec };
+}
+
+module.exports = { createPlanLoop: createPlanLoop, defaultComplete: defaultComplete, defaultFold: defaultFold,
+	sinkFold: sinkFold, defaultIsDegenerate: defaultIsDegenerate };