skynet-graph 1.2.0

package/lib/authoring/ground.js

@@ -0,0 +1,148 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * ground.js — GOLD-MINED GROUNDING RINGS (the promoted core of the 2026-07-06 ring-grounding cells).
+ *
+ * The grounding problem: which declared vocab unit does a surface form (a question token, a model's raw
+ * extraction) refer to? Lexical matching cannot learn it (paraphrases/synonyms miss) and a model's holistic
+ * judgment errs — measured on two domains (entity→table: every deterministic variant ≤ the model's 0.764;
+ * attribute vocab: a loose-prompt extractor grounds 0/18 hard paraphrases). The lattice's answer is the
+ * defeasible SYNONYM RING grown from ORACLE-LABELED traffic behind the one admission gate — this module is
+ * that miner, promoted after two cells exercised the identical shape (tables: joins 0.764→0.800, the first
+ * lever to beat the model; attributes: 0→11/18 at 0 served-wrong, traps refused).
+ *
+ * Episodes → per-(alias, member) evidence → `registry.js#decideRingAdmission` (the per-unit counterfactual
+ * gate) → `registry.js#mergeRingProposals` (confluence + provenance, retractable). THE GRAINS THAT MATTER
+ * (each measured against its own failed variant):
+ *   • support ≥ minSupport (default 3) — the df-2 fluke door under a noisy oracle (Rule-of-Three);
+ *   • 0 counters, with an optional per-episode `verdict` able to return 'neutral' — the middle bucket
+ *     (member ∈ gold but the grounded set over-shoots) must stay NEUTRAL: counting it against kills true
+ *     aliases through lexical-base noise (0.800→0.733 measured);
+ *   • vacuity BOTH by base (the episode's `base` set already grounds the member without rings) AND by prior
+ *     (baseRate > maxBaseRate: a member the oracle nearly always contains is grounded by the prior alone —
+ *     and a degenerate/constant oracle makes EVERYTHING vacuous → 0 admissions);
+ *   • the DOCTRINE (the registry's own): zero-under-noise is NOT the claim at finite support — the claim is
+ *     a BOUNDED admission rate under a structureless oracle plus RECOVERABILITY (provenance `via`, one
+ *     retractRingAlias per bad alias, 10/10 localized flips measured). Alias grain: prefer STABLE surface
+ *     tokens over model raw extractions (24 vs 9 aliases, serve 11 vs 2 — the same-pattern raw varies).
+ *
+ * @param episodes  [{ aliases:[string…], gold:Set|Array|string|null, base?:Set|Array }] — one oracle-labeled
+ *                  occurrence: the surface forms seen, the oracle's member(s) (null = out-of-vocabulary), and
+ *                  optionally the members already grounded WITHOUT rings (the lexical/enum base).
+ * @param opts.registry   a registry to grow ({keys:{[key]:{enum,…}}}), or use opts.key+opts.enum to build one.
+ * @param opts.key        the registry key the rings live under (default 'unit').
+ * @param opts.enum       the closed member vocabulary (required unless opts.registry carries it).
+ * @param opts.minSupport gate threshold (default 3).
+ * @param opts.maxBaseRate vacuity-by-prior threshold (default 0.8).
+ * @param opts.verdict    optional (episode, member) => 'support'|'counter'|'neutral' — defaults to
+ *                        member∈gold → 'support' else 'counter'. (The subset/overshoot rule of the table cell
+ *                        is a custom verdict; 'neutral' is the load-bearing middle bucket.)
+ * @param opts.via        provenance tag (default 'gold-mined').
+ * @returns { registry, admitted, rejected, stats:{ candidates, admitted, vacuous, countered, confluenceRejected } }
+ */
+
+var reg = require('./registry.js');
+
+function toSet( v ) {
+	if ( v == null ) return new Set();
+	if ( v instanceof Set ) return v;
+	if ( Array.isArray(v) ) return new Set(v);
+	return new Set([v]);
+}
+
+function mineGroundingRings( episodes, opts ) {
+	opts = opts || {};
+	var registry = opts.registry;
+	if ( !registry ) {
+		if ( !Array.isArray(opts.enum) ) throw new Error('mineGroundingRings needs opts.registry or opts.enum (the closed member vocabulary)');
+		registry = { keys: {}, version: 'v1' };
+		registry.keys[opts.key || 'unit'] = { enum: opts.enum.slice() };
+	}
+	var key = opts.key || Object.keys(registry.keys)[0] || 'unit';
+	var entry = registry.keys[key];
+	if ( !entry || !Array.isArray(entry.enum) ) throw new Error('mineGroundingRings: registry key "' + key + '" has no enum');
+	var members = entry.enum;
+	var minSupport = opts.minSupport == null ? 3 : opts.minSupport;
+	var maxBaseRate = opts.maxBaseRate == null ? 0.8 : opts.maxBaseRate;
+	var verdict = opts.verdict || function ( ep, member ) { return toSet(ep.gold).has(member) ? 'support' : 'counter'; };
+
+	// vacuity-by-prior: a member the oracle nearly always names is grounded by the prior alone.
+	var eps = (episodes || []).map(function ( ep ) { return { aliases: [...new Set(ep.aliases || [])], gold: toSet(ep.gold), base: toSet(ep.base) }; });
+	var baseRate = {};
+	for ( var mi = 0; mi < members.length; mi++ ) {
+		var m = members[mi];
+		var n = 0;
+		for ( var e = 0; e < eps.length; e++ ) if ( eps[e].gold.has(m) ) n++;
+		baseRate[m] = eps.length ? n / eps.length : 0;
+	}
+
+	// per-(alias, member) evidence over the episodes.
+	var stats = {};
+	for ( var i = 0; i < eps.length; i++ ) {
+		var ep = eps[i];
+		for ( var a = 0; a < ep.aliases.length; a++ ) {
+			var alias = String(ep.aliases[a]);
+			if ( !alias ) continue;
+			for ( var j = 0; j < members.length; j++ ) {
+				var member = members[j];
+				var v = verdict(ep, member);
+				if ( v !== 'support' && v !== 'counter' ) continue;                    // 'neutral' — the middle bucket
+				var k = alias.toLowerCase() + '::' + member;
+				var s = stats[k] || (stats[k] = { alias: alias, member: member, support: 0, counter: 0, nonVacuous: 0 });
+				if ( v === 'support' ) { s.support++; if ( !ep.base.has(member) ) s.nonVacuous++; }
+				else s.counter++;
+			}
+		}
+	}
+
+	// the gate, per candidate — then the confluence-checked merge (provenance, retractable).
+	var proposals = [];
+	var vacuous = 0, countered = 0, candidates = 0;
+	for ( var sk in stats ) {
+		var c = stats[sk];
+		if ( c.support + c.counter < Math.min(2, minSupport) ) continue;               // below any evidence bar — not a candidate
+		candidates++;
+		var d = reg.decideRingAdmission({
+			member      : c.member,
+			withAlias   : c.support >= minSupport && c.counter === 0,
+			withoutAlias: c.nonVacuous === 0 || baseRate[c.member] > maxBaseRate
+		});
+		if ( d.reason === 'vacuous' ) { vacuous++; continue; }
+		if ( !d.admit ) { countered++; continue; }
+		proposals.push({ key: key, alias: c.alias, member: c.member, via: opts.via || 'gold-mined' });
+	}
+	var merged = reg.mergeRingProposals(registry, proposals);
+	return {
+		registry: merged.registry,
+		admitted: merged.admitted,
+		rejected: merged.rejected,
+		stats: { candidates: candidates, admitted: merged.admitted.length, vacuous: vacuous, countered: countered, confluenceRejected: merged.rejected.length }
+	};
+}
+
+/**
+ * ringTouch — the serve-side half: which members do these surface forms ground to, through the grown ring?
+ * (Both cells' serve loop.) Ambiguity is the CALLER's policy — the sound default is "unique member or refuse"
+ * (the hybrid rescue of the attribute cell served 11/18 at 0 wrong with exactly that rule).
+ * @returns Set<member>
+ */
+function ringTouch( aliases, registry, key ) {
+	var entry = registry && registry.keys && registry.keys[key || Object.keys(registry.keys)[0]];
+	var syn = (entry && entry.synonyms) || {};
+	var norm = {};
+	for ( var i = 0; i < (aliases || []).length; i++ ) norm[String(aliases[i]).toLowerCase().trim()] = true;
+	var touched = new Set();
+	for ( var m in syn ) {
+		var ring = syn[m] || [];
+		for ( var a = 0; a < ring.length; a++ )
+			if ( norm[String(ring[a]).toLowerCase().trim()] ) { touched.add(m); break; }
+	}
+	return touched;
+}
+
+module.exports = { mineGroundingRings: mineGroundingRings, ringTouch: ringTouch };

package/lib/authoring/higher-order.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * higher-order — THE METHOD-SLOT / higher-order `need` (roadmap 2026-07-09 §5(a); ZERO-CORE). Until now a part
+ * declares only DATA-needs (it needs a VALUE). §5(a) adds the BEHAVIOURAL hole: a "loop" method declares
+ * *"I need a SUB-METHOD in this slot"* (the loop body, the stop predicate) = a **method-slot** (`kind:'subgraph'`),
+ * filled by DISPATCH (P2/serveLeaf) — a slot filled by a dispatched method, not hardcoded. Swapping the dispatched
+ * body changes the loop's behaviour: that IS the loop-in-loop. Soundness across the extra hop is KG-PROXY-2 (GO).
+ *
+ * `makeHigherOrderServe({ loops, bodies, pool })` → a projection `serve(leaf)`:
+ *   • DISPATCH the body sub-method for the leaf's method-slot (`loop.bodyKeyOf(leaf)` → a libraryKey);
+ *   • APPLY it (map/all/any/fold) over the leaf's items — each application is a MOUNTED, gated invoke (P1/P3/P4)
+ *     of the dispatched body → the loop's behavioural hole is filled at runtime by a dispatched method.
+ * The body sub-methods reuse `makeMethodServe` (P6), so each body application is itself dispatch + mount + gate.
+ *
+ * NESTING (map-of-maps): when a body key names ANOTHER loop (not a plain method), the application RECURSES — the
+ * inner loop's items are the current item. Bounded by construction (finite items × finite inner items = a finite
+ * tree) + a CYCLE guard (a loop that transitively names itself REFUSES, the control-structure analog of G3). The
+ * soundness of the stack of nested hops = KG-PROXY-2 (each hop bounded + gated).
+ */
+const { makeMethodServe } = require('./serve-leaf.js');
+
+/**
+ * @param spec.bodies  { <libraryKey>: <makeMethodServe method spec> }  the candidate SLOT FILLERS (dispatched bodies).
+ *                     each body's buildSeed receives a leaf carrying `.item` (the current element).
+ * @param spec.loops   { <libraryKey>: { bodyKeyOf(leaf)->libraryKey, items(leaf)->[..], combinator?, fold?, init? } }
+ *                     the higher-order "loop" methods. combinator: 'map'(default) | 'all' | 'any' | 'fold'.
+ * @param spec.keyOf   (leaf) => loop libraryKey (default: leaf.produces || leaf.id).
+ * @param spec.pool    a shared P3 invoke-pool (default: own).
+ * @returns serve      async (leaf, ctx) => value  (+ serve.pool, serve.close()).
+ */
+function makeHigherOrderServe( spec ) {
+	spec = spec || {};
+	const pool = spec.pool || require('../index.js').createInvokePool();
+	const loops = spec.loops || {};
+	const keyOf = spec.keyOf || (( leaf ) => leaf.produces || leaf.id);
+	// the SLOT FILLERS are served exactly like any leaf method (P6) — dispatch + mount + gate — keyed by the body key.
+	const bodyServe = makeMethodServe({ methods: spec.bodies || {}, keyOf: ( bl ) => bl.__key, pool });
+
+	// apply the body over ONE item: a body key that names a nested LOOP → RECURSE (the inner loop's items = this item);
+	// else dispatch+mount+gate a PLAIN method (P6). `chain` carries the loop-key path for the cycle guard.
+	async function applyBody( bodyKey, item, id, ctx, chain ) {
+		if ( loops[bodyKey] )                                            // NESTED loop → recurse (map-of-maps)
+			return runLoop(bodyKey, { id: id, produces: bodyKey, item: item, inputs: {} }, ctx, chain);
+		return bodyServe({ __key: bodyKey, id: id, produces: bodyKey, needs: [], inputs: {}, item: item }, ctx);
+	}
+
+	async function runLoop( loopKey, leaf, ctx, chain ) {
+		chain = chain || [];
+		if ( chain.indexOf(loopKey) !== -1 )                            // CYCLE guard: a loop that transitively names itself → REFUSE (control-structure G3)
+			throw new Error('higher-order serve: cyclic nested loop "' + loopKey + '" (chain ' + chain.concat(loopKey).join('→') + ')');
+		const next = chain.concat(loopKey);
+		const loop = loops[loopKey];
+		const bodyKey = loop.bodyKeyOf(leaf);                            // DISPATCH the body into the method-slot
+		const items = loop.items(leaf);                                  // items = the RESOLVED collection (never coerce undefined→[])
+		if ( !Array.isArray(items) )                                     // fail-closed: an UNRESOLVED slot is a refusal, NOT a vacuous empty loop (all([])===true)
+			throw new Error('higher-order serve: items(leaf) for "' + loopKey + '" is not an array (unresolved slot?) — leaf ' + leaf.id);
+		const results = [];
+		for ( let i = 0; i < items.length; i++ )                        // APPLY the body (plain OR nested loop) over the items
+			results.push(await applyBody(bodyKey, items[i], leaf.id + ':body' + i, ctx, next));
+
+		switch ( loop.combinator || 'map' ) {
+			case 'all':  return results.every(Boolean);
+			case 'any':  return results.some(Boolean);
+			case 'fold': return results.reduce(loop.fold, loop.init);
+			default:     return results;                                // 'map'
+		}
+	}
+
+	async function serve( leaf, ctx ) {
+		const key = keyOf(leaf);
+		if ( !loops[key] ) throw new Error('higher-order serve: no loop method for libraryKey "' + key + '" (leaf ' + leaf.id + ')');
+		return runLoop(key, leaf, ctx, []);
+	}
+	serve.pool = pool;
+	serve.close = () => spec.pool ? Promise.resolve() : pool.close();
+	return serve;
+}
+
+module.exports = { makeHigherOrderServe };

package/lib/authoring/hotspot.js

@@ -0,0 +1,132 @@
+/*
+ * 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';
+/**
+ * hotspot — the distill go/no-go DETECTOR (the §4.2-B / Proxy-KD plan-B pre-test). The cheap,
+ * standing question that GATES the entire distilled-NN-concept build (which otherwise stays filed).
+ *
+ * Why a pre-test at all: the fidelity-gated cache (`cache.js`) ALREADY serves an exact-key hot
+ * slice at 0 calls. So a parametric net buys NOTHING on an exactly-recurrent slice — it only
+ * earns its place where the exact-key memo keeps MISSING yet the mapping is learnable. That is a
+ * THREE-WAY condition, and proving/refuting it cheaply IS the deliverable:
+ *   (1) FREQUENT          — enough volume to be worth distilling          (calls ≥ minCalls)
+ *   (2) CACHE-MISSING     — many distinct-but-related keys the exact-key  (hitRate ≤ maxHitRate
+ *                           memo can't cover (high cardinality)            ⇔ high key cardinality)
+ *   (3) K1-SUFFICIENT     — the typed surface predicts the verdict; if    (fidMean ≥ minFidelity)
+ *                           even the repeated keys don't reproduce, the
+ *                           LLM reads something off-surface → unlearnable
+ * Only all-three ⇒ `distill-candidate` (a Phase-1 generalization measurement then confirms it).
+ * The honest, expected outcome on today's workloads is NO qualifying slice ⇒ the net stays filed —
+ * proven cheaply rather than on faith.
+ *
+ *   const t = trackCache();
+ *   const cache = createProviderCache({ ..., onHit: t.onHit, onMiss: t.onMiss, fidelity: {...} });
+ *   // ...run the workload through the cache...
+ *   const report = hotspots(t, cache.fid, { minCalls: 20, maxHitRate: 0.5, minFidelity: 0.8 });
+ */
+
+/**
+ * A per-concept tally you wire into a provider cache's `onHit`/`onMiss`. `onHit` = a served
+ * cache hit (0 model calls); `onMiss` = a cold (uncached) derivation (a model call). Each
+ * distinct key cold-misses exactly once (its first sight, before it is stored), so the cold-miss
+ * key set is the cardinality estimate; the served hits are the amortization.
+ */
+function trackCache() {
+	const perConcept = {};   // name -> { hits, misses, hitKeys:Set, missKeys:Set }
+	function slot( concept ) {
+		const n = (concept && concept._name) || String(concept);
+		return perConcept[n] || (perConcept[n] = { hits: 0, misses: 0, hitKeys: new Set(), missKeys: new Set() });
+	}
+	return {
+		perConcept,
+		onHit:  function ( key, concept ) { const s = slot(concept); s.hits++;   if ( key != null ) s.hitKeys.add(key); },
+		onMiss: function ( key, concept ) { const s = slot(concept); s.misses++; if ( key != null ) s.missKeys.add(key); },
+		reset:  function () { for ( const k of Object.keys(perConcept) ) delete perConcept[k]; },
+	};
+}
+
+// the mean exact-key reproduce rate over a concept's fidStore entries (the keys it actually
+// touched). null when no key has fidelity data yet (e.g. a pure-singleton high-cardinality
+// slice — repeats are what populate `fid`, so K1-sufficiency is then UNCONFIRMED, not refuted).
+function fidelityFor( keys, fidStore ) {
+	if ( !fidStore || !keys || !keys.size ) return { mean: null, n: 0 };
+	let sum = 0, n = 0;
+	for ( const k of keys ) {
+		const fs = fidStore.get(k);
+		if ( fs && fs.total > 0 ) { sum += fs.ok / fs.total; n++; }
+	}
+	return { mean: n ? sum / n : null, n: n };
+}
+
+/**
+ * Classify every tracked concept into the four buckets. Pure (no boot, no model calls).
+ * @param tracker   a `trackCache()` collector (or `{ perConcept }`)
+ * @param fidStore  the cache's `fid` Map (key -> { ok, total }); omit → fidelity unconfirmed
+ * @param opts.minCalls     volume floor (default 20)
+ * @param opts.maxHitRate   above this the exact-key cache already wins (default 0.5)
+ * @param opts.minFidelity  K1-sufficiency threshold on the reproduce rate (default 0.8)
+ * @returns [{ concept, calls, hits, misses, distinctKeys, hitRate, keyCardinality, fidMean, fidN, verdict, reason }]
+ *          sorted distill-candidates first, then by volume. verdict ∈
+ *          { 'distill-candidate', 'cache-already-wins', 'unlearnable', 'too-rare' }.
+ */
+function hotspots( tracker, fidStore, opts ) {
+	opts = opts || {};
+	const minCalls    = opts.minCalls    != null ? opts.minCalls    : 20;
+	const maxHitRate  = opts.maxHitRate  != null ? opts.maxHitRate  : 0.5;
+	const minFidelity = opts.minFidelity != null ? opts.minFidelity : 0.8;
+	const per = (tracker && tracker.perConcept) || tracker || {};
+
+	const rows = Object.keys(per).map(function ( name ) {
+		const s = per[name];
+		const hits = s.hits || 0, misses = s.misses || 0;
+		const calls = hits + misses;                                  // served + cold (verify/escalate uncounted — a floor)
+		const keys = new Set([...(s.missKeys || []), ...(s.hitKeys || [])]);
+		const distinctKeys = keys.size;
+		const hitRate = calls ? hits / calls : 0;
+		const keyCardinality = calls ? distinctKeys / calls : 0;       // ~1 = every call a new key (cache can't cover)
+		const fid = fidelityFor(keys, fidStore);
+
+		let verdict, reason;
+		if ( calls < minCalls ) {
+			verdict = 'too-rare'; reason = 'calls ' + calls + ' < minCalls ' + minCalls;
+		} else if ( hitRate > maxHitRate ) {
+			verdict = 'cache-already-wins'; reason = 'hitRate ' + hitRate.toFixed(2) + ' > ' + maxHitRate + ' — the exact-key memo already serves it';
+		} else if ( fid.mean != null && fid.mean < minFidelity ) {
+			verdict = 'unlearnable'; reason = 'fidMean ' + fid.mean.toFixed(2) + ' < ' + minFidelity + ' — the verdict is not a function of the typed key';
+		} else {
+			verdict = 'distill-candidate';
+			reason = fid.mean != null
+				? 'frequent ∧ cache-missing ∧ K1-sufficient (fidMean ' + fid.mean.toFixed(2) + ') — Phase-1 generalization check next'
+				: 'frequent ∧ cache-missing; fidelity UNCONFIRMED (no repeats yet) — Phase-1 must confirm K1-sufficiency';
+		}
+		return {
+			concept: name, calls: calls, hits: hits, misses: misses, distinctKeys: distinctKeys,
+			hitRate: hitRate, keyCardinality: keyCardinality, fidMean: fid.mean, fidN: fid.n,
+			verdict: verdict, reason: reason,
+		};
+	});
+
+	const rank = { 'distill-candidate': 0, 'unlearnable': 1, 'cache-already-wins': 2, 'too-rare': 3 };
+	rows.sort(function ( a, b ) { return (rank[a.verdict] - rank[b.verdict]) || (b.calls - a.calls); });
+	return rows;
+}
+
+// convenience: are there any distill-candidates? (the go/no-go boolean).
+function anyCandidate( rows ) { return (rows || []).some(function ( r ) { return r.verdict === 'distill-candidate'; }); }
+
+module.exports = { trackCache: trackCache, hotspots: hotspots, fidelityFor: fidelityFor, anyCandidate: anyCandidate };

package/lib/authoring/hysteresis.js

@@ -0,0 +1,85 @@
+/*
+ * 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';
+/**
+ * Hysteresis dead-band for the grain split/merge loop (doc/WIP/HANDOFF.md §7 Tier 3 P3;
+ * experiment C). Zero core change — a host-side decision helper for a supervisor's injected
+ * `evaluate` hook (lib/authoring/supervise.js).
+ *
+ * The problem (C probe): adopting a finer grain when a hold-out score improves, and reverting
+ * when it regresses, OSCILLATES across episodes if the keep/revert decision uses a SINGLE
+ * fixed margin and the re-evaluation variance exceeds it (the probe flipped 31/60 with a fixed
+ * margin < noise). What terminates is a HYSTERESIS dead-band: a high bar to ADOPT the finer
+ * grain (`keepThreshold`) and a separate bar to REVERT it (`mergeThreshold`), with the band
+ * between them sized to ≥ ~3σ of the re-eval variance — plus an idempotent "grain in force"
+ * marker so a settled grain stops re-triggering. Then steady-state flips → 0.
+ *
+ * HONEST: this is a statistical contraction, NOT a formal termination proof (an adversarial
+ * hold-out with unbounded between-episode variance can still cross any finite band). It is the
+ * available zero-core mitigation; a formal cross-episode guarantee is open R&D.
+ *
+ *   const { makeHysteresis, bandFromSigma } = require('./hysteresis');
+ *   const h = makeHysteresis({ keepThreshold: bandFromSigma(reEvalSigma), betterIsLower: true });
+ *   const action = h.decide(candidateScore, baselineScore, currentRegime);  // 'adopt' | 'revert' | 'hold'
+ */
+
+/** A ≥k·σ dead-band from an estimate of the re-evaluation std-dev (k defaults to 3, per C). */
+function bandFromSigma( sigma, k ) {
+	return (k == null ? 3 : k) * (sigma || 0);
+}
+
+/**
+ * Build a hysteresis decision function.
+ * @param opts.keepThreshold    the minimum GAIN to ADOPT the finer grain from 'coarse' (default 1).
+ * @param opts.mergeThreshold   the minimum REGRESSION to REVERT from 'fine' (default = keepThreshold;
+ *                              keeping it ≥ keepThreshold makes the dead-band ≥ keepThreshold wide).
+ * @param opts.betterIsLower    true (default) when a LOWER score is better (deviance/MSE/loss);
+ *                              false for higher-is-better (accuracy/reward).
+ * @returns { decide(candidate, baseline, regime), gain(candidate, baseline), keepThreshold, mergeThreshold }
+ */
+function makeHysteresis( opts ) {
+	opts = opts || {};
+	var keep = opts.keepThreshold == null ? 1 : opts.keepThreshold;
+	var merge = opts.mergeThreshold == null ? keep : opts.mergeThreshold;
+	var lower = opts.betterIsLower !== false;
+
+	// how much BETTER candidate is than baseline (positive = better), in either polarity
+	function gain( candidate, baseline ) {
+		return lower ? (baseline - candidate) : (candidate - baseline);
+	}
+
+	return {
+		keepThreshold: keep,
+		mergeThreshold: merge,
+		gain: gain,
+		/**
+		 * Decide from the CURRENT regime:
+		 *   'coarse' — considering adopting the finer grain: 'adopt' iff gain ≥ keepThreshold, else 'hold'.
+		 *   'fine'   — considering reverting: 'revert' iff the finer grain REGRESSED by ≥ mergeThreshold
+		 *              (gain ≤ −mergeThreshold), else 'hold'.
+		 * The gap (−mergeThreshold, keepThreshold) is the dead-band where nothing changes.
+		 */
+		decide: function ( candidate, baseline, regime ) {
+			var g = gain(candidate, baseline);
+			if ( regime === 'fine' ) return g <= -merge ? 'revert' : 'hold';
+			return g >= keep ? 'adopt' : 'hold';
+		}
+	};
+}
+
+module.exports = { makeHysteresis: makeHysteresis, bandFromSigma: bandFromSigma };

package/lib/authoring/index.js

@@ -0,0 +1,106 @@
+/*
+ * 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';
+/**
+ * Authoring & R&D toolkit — packaged so the substrate tools are usable "à nu"
+ * without deep-path requires.
+ *
+ *   const Graph = require('skynet-graph');
+ *   const { contract, method, abstract } = Graph.authoring;   // exposed as a static, like Graph.providers
+ *   contract.checkCompose(m1, m2);
+ *
+ * Unlike the providers barrel (which flattens function names), this barrel is
+ * NAMESPACED — one key per module — because authoring modules legitimately share
+ * export names (e.g. `validate` in both validate.js and bounded-merge.js,
+ * `verify` in recall.js, `evaluate` in abstraction.js). Each module also stays
+ * importable on its own (`require('skynet-graph/lib/authoring/contract')`) — the
+ * barrel is a convenience, not a gate.
+ */
+
+module.exports = {
+	// ── Concept authoring & validation ───────────────────────────────────────
+	concepts     : require('./concepts'),       // buildConceptTree(dir) — JSONC concept tree
+	validate     : require('./validate'),       // validateConceptTree — author-time structural validator (K1 barrier)
+	author       : require('./author'),         // authorConcept — declarative AI-authoring + CEGIS loop
+	contract     : require('./contract'),       // the defeasible separation-triple checker (checkCompose/assertPost/satisfies/reviseOnBlame)
+	grammarGraph : require('./grammar-graph'),  // conceptFactGraph — the concept↔fact grammar graph
+
+	// ── Concept-as-graph methods (build / select / mount / abstract) ──────────
+	method       : require('./method'),         // applySubgraphArg/mapSubgraph/lintMethod/selectCluster
+	mount        : require('./mount'),           // tiered mount controller (instance/inline/frozen)
+	abstract     : require('./abstract'),       // F6 relativize/instantiate/antiUnify/methodTransform (structural transfer) + generalizeContent/fillContentHoles (LGG content-hole discovery for the adapt operator)
+	abstraction  : require('./abstraction'),    // the abstraction-gate currency (applies→LLM-cost)
+	mdl          : require('./mdl'),             // static bits-based MDL ranker/pre-filter in front of abstraction.evaluate (#12)
+	decompose    : require('./decompose'),      // plan decomposition / forkPlan auto-tiling
+	registry     : require('./registry'),       // G-1 the interface-alphabet REGISTRY (Σ_sep): curated+versioned vocab CATALOG — deriveRegistry/freezeRegistry/specForKey (rings live here)/mergeRingProposals (borderline proposals, confluence re-checked)/checkTreeAgainstRegistry (enforce the frozen canon)
+	extract      : require('./extract'),        // bounded subgraph EXTRACTION for fork / multi-process ship (program slicing: segment-closed 1-hop ball + frozen frontier; mergeSlice = single-writer + assumption-recheck; the fork/ship lever, ZERO-CORE)
+	boundedMerge : require('./bounded-merge'),  // bounded N→1 projection (assume-guarantee merge interface)
+	reaggregate  : require('./reaggregate'),    // defeasibleAggregate (fold-back / merge)
+	memoStability: require('./memo-stability'), // memoSnapshot/memoDiff — the canonicalization-stability discipline (F4 adjudicator)
+	support      : require('./support'),        // support grammar (problem-solving scaffold)
+
+	// ── Library learning / crystallization / packaging ───────────────────────
+	crystallize  : require('./crystallize'),    // distil recurrent methods from traces — provider-fusion + crystallizeStructural (re-mountable defeasible method, DECLARED frontier + reified FrontierSignature + libraryKey dispatch + lintFrontier) + synthesizeContract (CLS capstone)
+	mine         : require('./mine'),           // traceMiner/methodTrace — mine producer→consumer chains + recurrent STRUCTURAL methods (mineMethods: antiUnify + K1-ceiling guard; declaredCtx = DECLARED frontier; emitEquivalence)
+	compress     : require('./compress'),       // the DIGRAM-grain affinity miner (2026-07-03 GO kill-gate): adjacent-pair support + dispatchable sub-expansion index (K1 rule, kind|ctx grains) + mdl.js-ΔL fold + typed-loop-parity subpath patches + the method-FOREST skeleton
+	library      : require('./library'),        // the method-library index + dispatch (the structuring↔concept-DLL juncture): O(1) libraryKey bucket → refine by app-conditions → ranked candidates
+	combinator   : require('./combinator'),     // the dispatch→MOUNT bridge (P2.5): a higher-order concept fills its behavioral hole with a DISPATCHED library fragment (recombination at 0 calls; durable guard, not the self-flag)
+	adapt        : require('./adapt'),          // the adapt-or-forge CONTROLLER (the creative loop's drive): retrieve(hit,0-call) → forge/adapt via the model (reuse neighbours) → verifier-gate (contract) → index back (amortise). antiUnifyAdapt = the principled CONTENT-FORGE adapt (LGG auto-discovers content holes, forge only those, reuse skeleton; opts.adaptContent)
+	hotspot      : require('./hotspot'),         // distill go/no-go detector (frequent ∧ cache-missing ∧ K1-sufficient slice) (#§4.2-B)
+	composeHotspot: require('./compose-hotspot'),// compress.js kill-gate, STRUCTURAL half: does a data-flow composite RECUR cross-distinct-task? (interleave-robust provenance chains + RE-PAIR; G-a poly ceiling)
+	costProbe    : require('./cost-probe'),      // compress.js kill-gate, COST half: does a composite-memo elide FORGE calls the leaf floor can't? (the thin canonicalization-in-context band — the axis that actually decides the build)
+	recall       : require('./recall'),         // recallAndVerify index (retrieve-or-forge)
+	methodPack   : require('./method-pack'),    // portable LEARNED-method package (.sgc sibling)
+	corpusPack   : require('./corpus-pack'),    // .sgc corpus exchange + derived manifest
+	latticePack  : require('./lattice-pack'),   // portable TYPED-LATTICE package (.sgc sibling — registry: isa vocab + grown rings)
+	methodExplorer: require('./method-explorer'), // list+judge a concept-method population (title/category/description + coverage/openness)
+	retention    : require('./retention'),      // usage-tracked + self-evicting store (the reuse/keep-or-evict axis; sibling of lifecycle's plasticity axis)
+	store        : require('./store'),          // createFileStore (durable cross-restart library)
+	stock        : require('./stock'),          // gold-gated concept-method STOCK building (goldGate + consistencyVote + packStock) — the reusable core of the dataset-stock pilot
+	ground       : require('./ground'),         // gold-mined GROUNDING RINGS (mineGroundingRings + ringTouch) — surface form → vocab unit through the ring gate (the 2026-07-06 cells' core)
+	glossary     : require('./glossary'),       // P2 the cross-round terminology REFERENCE: createGlossary = a persistent lattice-backed store of canonical GROUNDED notions (harvest = witness-overlap SELECTS the member + mergeRingProposals ADMITS the alias under confluence, audited/versioned/retractable; reconcile = JTMS entry-retract with cascade; inject = citable-vocabulary block). The managed reference the re-split needs — ZERO-CORE (assembles registry.js + canonicalize.js)
+	granularity  : require('./granularity'),    // P2 the STRUCTURAL granularity ARBITER (the sonde's grounded dimensions): clusterByGrounding = connected components on the witness co-citation graph; arbitrate = the lazy 2-régime verdict (coherent | MIXED = the re-plan `frame: TOO-NARROW` grounded signal | unstructured = escalate to Q2). No prose parsing — dimensions come from grounding, never fabricated. ZERO-CORE
+	datasetAdapter: require('./dataset-adapter'), // labelled query dataset → {query,context,klass,goldShape} (WikiSQL built-in; register more) — "plusieurs datasets" one registry away
+
+	// ── Supervision / lifecycle / runtime regime ─────────────────────────────
+	supervise    : require('./supervise'),      // reactive supervisor (Stuck→hypothesize→evaluate→revert)
+	relearn      : require('./relearn'),         // standing autonomous un-learn loop (blame→revise→patch as reactive concepts)
+	loop         : require('./loop'),           // autonomous episode loop
+	typedLoop    : require('./typed-loop'),     // the fused RECURSIVE TYPED decompose operator (loop.js emergent depth × canon-snapped stepKind children, prose untracked → the decompose trace is K1-crystallizable)
+	rebalance    : require('./rebalance'),       // R1 the DEFEASIBLE REBALANCING FIXPOINT (E2∘E1∘E3∘E4 under a lexicographic measure; kill-gated KG-R1b) — drives a degenerate plan to a balanced fixpoint; usable à nu
+	dagDecompose : require('./dag-decompose'),   // model-driven TYPED DAG DECOMPOSE (study 2026-07-08 §6.1): decompose PROMPT + grammar-constrained decoding → a needs/produces DAG (stepKind on a closed enum = the K1 barrier); makeDagDecompose = plan-loop's decompose seam feeding the projection
+	contextProject: require('./context-project'),// R1 §2 GRAPH-NATIVE CONTEXT PROJECTION (pool ref-parent + counter gate + recursive down-projection/remontée) — each node completes its BOUNDED context from structure; guardPlan (recursive deadlock guard) + createContextProjection; the real projection wired into plan-loop
+	soundInvoke  : require('./sound-invoke'),    // P4 the CONSTAT operationalized: soundInvokeMerge = assertPost (G1 frame via the P1 write-footprint + post-holds + G2 oracle) → mergeSlice (assumption-recheck + single-writer) → sequenced commit; a violation REFUSES (blame for reviseOnBlame) so composé-cross-instance ≡ plat, *sainement*
+	segmentProxy : require('./segment-proxy'),   // P2 the reactive SEGMENT-PROXY: makeSegmentProxy = a concept-method that casts on its contract's conditions → delegates via the P1 invoke → gates via P4 assertPost → posts summaryFacts JTMS-visible (the good C.8: an interface). Cast = the cost gradient: delegate → gate → LAST-RESORT forge fallback (reconstructStack up the parentSeg chain, bounded; forge re-enters the gate) — the §5 plasticity hook
+	serveLeaf    : require('./serve-leaf'),      // P6 the UNIFICATION: makeMethodServe = a projection serve(leaf) that DISPATCHES (libraryKey) + MOUNTS a concept-method (invoked on a P3 shared instance, gated by P4) — a leaf IS a mounted method, not an opaque value; folds projection + runtime + library + method into one structure
+	higherOrder  : require('./higher-order'),    // §5(a) the METHOD-SLOT / higher-order need: makeHigherOrderServe = a "loop" method whose behavioural hole (the body / stop predicate) is filled by a DISPATCHED sub-method (P2), applied (map/all/any/fold) over items — swap the dispatched body → different behaviour = the loop-in-loop (soundness across the hop = KG-PROXY-2 GO)
+	forgeFallback: require('./forge-fallback'),  // §5(b) the last-resort LEARNING fallback wired for P2's forge hook: reconstructStack → stackToPrompt (the LEVER) → forge (the model) → RE-ENTER the gate (assertPost DISPOSES a bad forge) → INDEX-BACK (amortise; next matching case = a dispatch hit). `maxRounds>1` = the BOUNDED BLAME-DRIVEN RETRY (residue USE-2(d), the OPEN-regime DUAL of negotiate): on a refusal, fold the violated atoms + rejected-history into the next prompt and revise, bounded → typed refusal. LIVE-PROVEN 17/24→24/24 at 0-false. Default maxRounds 1 = one-shot, byte-identical
+	forest       : require('./forest'),          // §5(c) the MULTI-PATH generalization: makeForestServe = a concept-method as a LIBRARY of alternative sub-paths; the FIRST candidate that dispatches+mounts+GATES sound is SELECTED (one stays active — the confluence guarantee that dodges G3: SELECT one path, never COMPOSE coupled retractable methods → no oscillation). Forest exhausted → the §5(b) forge
+	splitServe   : require('./split-serve'),     // the RECURSIVE composite path (KG-SPLIT GO 2026-07-10): kind-route → NL SPLIT into standalone sub-questions → plain-decompose each → assemble operand|op. Single-shot composed emission refuted (0-14%); the split reaches 55% strict / 64% relaxed / 0% plain-FP live — makes the COMPOSED certified vocabulary dispatchable (the trusted-tier growth lever). Fail-closed: malformed/conflicting/throwing split → plain fallback on the original query
+	negotiate    : require('./negotiate'),        // the bounded LLM↔GRAPH dialogue (CLOSED-domain): model PROPOSES a typed candidate → graph GATES (assertPost) → on mismatch, blame + ENUMERATED admissible options (tested through the gate, not guessed) → revision prompt → revise, bounded K. 0-false · honest refusal (empty options, never forced) · termination. The closed-domain sibling of forge-fallback's open-regime blame-retry
+	masterLoop   : require('./master-loop'),    // always-on master-loop (retrieve-or-forge→switch→bounded-context)
+	lifecycle    : require('./lifecycle'),      // onCast/teardown lifecycle helpers
+	clock        : require('./clock'),          // makeReaper / TTL clock (live regime)
+	hysteresis   : require('./hysteresis'),     // makeHysteresis — band stabilization
+
+	// ── Experimental / shelved (probabilistic concept-nets — see studies) ─────
+	conceptNet   : require('./concept-net'),    // (shelved) concept-net populations at the fixpoint
+	graphNet     : require('./graph-net'),      // (shelved) graph-net variant
+	equilibrium  : require('./equilibrium'),    // (shelved) implicit-equilibrium solver
+	ste          : require('./ste')             // (shelved) straight-through soft-train/hard-infer
+};

package/lib/authoring/lattice-morphism.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * lattice-morphism — STRUCTURAL reconciliation between two CARVINGS of a shared grounded domain (owner 2026-07-09;
+ * ZERO-CORE). The LEXICAL case (same classes, different labels: `high` vs `elevated`) is handled by the synonym ring
+ * (`canonicalize.js`). The STRUCTURAL case — two DIFFERENT partitions of the same ordered base ({low,mid,high} vs
+ * {cold,cool,warm,hot}) — is NOT a synonym: it is a MORPHISM derived from INTERVAL OVERLAP on the shared base. It is
+ *   • GROUNDED — computed from the intervals, not guessed;
+ *   • DETERMINISTIC on a known VALUE (both carvings classify the same v);
+ *   • SET-VALUED on a coarse MEMBER (a member that spans several target members = the coarsening loss);
+ *   • DEFEASIBLE at boundaries (a value within `eps` of a disputed cut is flagged `ambiguous` → escalate, never a
+ *     forced map) and FAIL-CLOSED off the base (a value outside every interval → null, never a forced nearest).
+ *
+ * REGIME (the honest ceiling): this works when both carvings anchor to a SHARED, GROUNDED base (a numeric grain, a
+ * measurable). Two UNGROUNDED carvings (no shared measurable) have no base to factor through → the morphism must be
+ * LEARNED from co-assignment on shared instances (paired data) — the harder residual, out of scope here.
+ *
+ *   const m = memberMorphism(A, B);   m.reconcile('high')      // -> ['warm','hot']  (A-high is coarser)
+ *   classifyValue(B, 70)              // -> { member:'warm' }   (a known value reconciles exactly)
+ *
+ * A carving = [{ member, lo, hi }] over a shared numeric base; intervals are [lo, hi) with the TOP interval closed.
+ */
+
+// do two intervals overlap on the shared base?
+function overlaps( a, b ) { return a.lo < b.hi && b.lo < a.hi; }
+
+/**
+ * classifyValue(carving, v, opts) → { member, ambiguous }
+ * The member whose interval contains v (deterministic). `ambiguous:true` when v is within `opts.eps` of an INTERNAL
+ * boundary (a disputed cut) — the defeasible signal. `member:null` when v is outside every interval (fail-closed).
+ */
+function classifyValue( carving, v, opts ) {
+	opts = opts || {};
+	const eps = opts.eps || 0;
+	const his = carving.map(( c ) => c.hi ), los = carving.map(( c ) => c.lo );
+	const maxHi = Math.max.apply(null, his), minLo = Math.min.apply(null, los);
+	let member = null;
+	for ( const c of carving ) if ( v >= c.lo && (v < c.hi || (c.hi === maxHi && v <= c.hi)) ) { member = c.member; break; }
+	let ambiguous = false;
+	for ( const c of carving ) if ( c.lo !== minLo && Math.abs(v - c.lo) <= eps ) ambiguous = true;   // near an internal cut
+	return { member: member, ambiguous: ambiguous };
+}
+
+/**
+ * memberMorphism(from, to) → { map, reconcile(member) }
+ * The member→member morphism by interval overlap. `map[m]` / `reconcile(m)` = the target members `m` overlaps: a
+ * SINGLETON = clean (from ⊆ to at that region), MULTI = `m` is COARSER (coarsening loss), EMPTY = disjoint (no
+ * fabricated overlap). Symmetric — call both directions for the full picture.
+ */
+function memberMorphism( from, to ) {
+	const map = Object.create(null);
+	for ( const f of (from || []) ) map[f.member] = (to || []).filter(( t ) => overlaps(f, t) ).map(( t ) => t.member );
+	return { map: map, reconcile: ( m ) => map[m] || [] };
+}
+
+module.exports = { classifyValue, memberMorphism, overlaps };