skynet-graph 1.2.0

package/lib/combos/proxy-cache.js

@@ -0,0 +1,272 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * C6 — the LOCAL-FIRST PROXY CACHE / DISTILLER (the owner's main use case, 2026-07-05). A cache-distiller in
+ * front of a FRONTIER model: a query is served from a minimal LOCAL operational stock when it is COVERED, and
+ * escalated to the frontier when it is not — enriching the stock in passing. Anti-drift + hallucination-null:
+ *   • the local side NEVER fabricates an answer from its own weights — it serves only VERIFIED stock (distilled
+ *     from the frontier = trusted) or ESCALATES → 0 hallucination;
+ *   • a miss escalates to the frontier (no false negative — the user always gets an answer);
+ *   • an optional local COVERAGE-CONFIRM (opts.coverageCheck) lets the local model reject a WRONG hit before
+ *     it is served (a stale/ill-fitting cache entry → invalidate + escalate, never serve a wrong answer);
+ *   • anti-drift: `drift(query)` invalidates the stock entry so the next ask re-escalates;
+ *   • `.sgc` ON DEMAND: `pack()`/`load()` ship the minimal operational stock; the store is a bounded local file.
+ *
+ * THIN assembly over `createLearningLibrary` (the doctrine — no new logic): the always-on cost ladder already
+ * IS "MATCH/RETRIEVE (local, 0 cost) → FORGE/ESCALATE (the expensive path)". Here the expensive path is the
+ * FRONTIER model, and the cached result is the distilled answer — so `solve` = local-first-then-escalate.
+ *
+ * @param opts.frontierAsk  REQUIRED async (query, ctx) => answer (string | {answer,…}) — the ground-truth escalation.
+ * @param opts.keyOf        (query) => string cache key (default: the string query, or `digest` of an object).
+ * @param opts.signature    (query) => {structure,content} — the coverage class (default: EXACT-key = a sound
+ *                          cache). A TYPED signature makes one frontier answer cover a CLASS (opt-in distillation).
+ * @param opts.coverageCheck optional async (query, cachedAnswer) => bool — the local model confirms a hit fits;
+ *                          a `false` invalidates the entry and escalates (the "does my stock answer this?" gate).
+ * @param opts.verify       optional async (query, frontierAnswer) => bool — gate the DISTILLATION: a `false`
+ *                          returns the frontier answer to the user but does NOT pollute the stock (no false neg).
+ * @param opts.store        a file PATH (durable, cross-restart) or a Map-like (default in-memory, minimal/local).
+ * @param opts.*            the §4 product knobs via resolveComboDefaults (fail-closed, durable memo, …).
+ * @returns {{ answer, drift, pack, load, stats, library }}
+ */
+
+var learning = require('./learning-library.js');
+var canon = require('../providers/canonicalize.js');
+var llm = require('../providers/llm.js');
+var storeMod = require('../authoring/store.js');
+var retention = require('../authoring/retention.js');
+
+function createProxyCache( opts ) {
+	opts = opts || {};
+	if ( typeof opts.frontierAsk !== 'function' ) throw new Error('createProxyCache needs opts.frontierAsk (async (query) -> answer) — the ground-truth escalation');
+	var keyOf = opts.keyOf || function ( q ) { return typeof q === 'string' ? q : canon.digest(q); };
+	var normAnswer = function ( r ) { return (r && typeof r === 'object' && r.answer !== undefined) ? r.answer : r; };
+
+	// SEMANTIC COVERAGE (opt-in): the local model maps a query → a stable canonical KEY, so PARAPHRASES snap to
+	// the same key and HIT the stock (a coverage far above exact-repeat). `signature` is sync (the master loop
+	// calls it inline), so the async key is computed in answer() and carried on a wrapped problem {__q,__k}.
+	var semanticKey = (typeof opts.semanticKey === 'function') ? opts.semanticKey : null;
+	var wrapped = function ( p ) { return !!(p && typeof p === 'object' && p.__proxy === true); };
+	var qOf = function ( p ) { return wrapped(p) ? p.__q : p; };                                   // the original query (→ the frontier)
+	var kOf = function ( p ) { return wrapped(p) ? p.__k : keyOf(p); };                            // the dispatch key (exact or semantic)
+	var signature = opts.signature || function ( p ) { return { structure: { q: kOf(p) }, content: {} }; };   // exact/semantic-key = a sound cache
+
+	// the FRONTIER forge — the ONLY generator (the local model never fabricates an answer). On a verify reject
+	// it THROWS carrying the frontier answer, so answer() returns it to the user UNCACHED (no false neg, no
+	// polluted stock) — the master loop would otherwise cache a forge result unconditionally.
+	var forge = async function ( problem, ctx ) {
+		var ans = await opts.frontierAsk(qOf(problem), ctx);
+		if ( opts.verify ) {
+			var ok = await opts.verify(qOf(problem), normAnswer(ans));
+			if ( !ok ) { var e = new Error('distillation rejected by verify'); e.outcome = 'reject'; e.frontierAnswer = normAnswer(ans); throw e; }
+		}
+		return { result: (ans && typeof ans === 'object' && ans.answer !== undefined) ? ans : { answer: ans }, cost: 1 };
+	};
+
+	// the local operational stock — optionally a self-managing RETENTION store (usage-tracked + auto-evicting):
+	// the owner's compass "supprime ce qui n'est jamais utilisé" + a MINIMAL bounded stock. Opt-in via
+	// maxStock/evictGrace; absent ⇒ a plain store (measures nothing, evicts nothing).
+	var inner = (typeof opts.store === 'string') ? storeMod.createFileStore(opts.store) : (opts.store || new Map());
+	var retentionOn = opts.maxStock != null || opts.evictGrace != null || opts.retention === true;
+	var stock = retentionOn ? retention.createRetentionStore(inner, { maxStock: opts.maxStock, evictGrace: opts.evictGrace }) : inner;
+
+	var lib = learning.createLearningLibrary(Object.assign({}, opts, { forge: forge, signature: signature, store: stock }));
+	var isLocal = function ( arm ) { return arm === 'match' || arm === 'recall-full' || arm === 'recall-partial'; };
+
+	return {
+		library: lib,
+
+		/** answer a query — served LOCAL when covered (0 frontier call), else ESCALATED to the frontier and the
+		 *  stock enriched in passing. Never fabricates locally (0 hallucination); a miss escalates (no false neg). */
+		answer: async function ( query ) {
+			// SEMANTIC key: the local model canonicalizes the query → paraphrases snap to one key (a cheap local
+			// call to save an expensive frontier call). Carried on a wrapped problem so the frontier still sees
+			// the ORIGINAL query. A key failure degrades safely to exact-key (never blocks the answer).
+			var problem = query;
+			if ( semanticKey ) {
+				try { var k = await semanticKey(query); if ( k != null && String(k).length ) problem = { __proxy: true, __q: query, __k: String(k) }; }
+				catch ( e ) { problem = query; }
+			}
+			var r;
+			try { r = await lib.solve(problem); }
+			catch ( e ) {
+				if ( e && e.outcome === 'reject' ) return { answer: e.frontierAnswer, source: 'frontier', enriched: false, cached: false, arm: 'escalate', cost: e.calls != null ? e.calls : 1 };
+				throw e;
+			}
+			// optional local coverage-confirm: a wrong/stale hit is invalidated + escalated (never served wrong).
+			if ( isLocal(r.arm) && typeof opts.coverageCheck === 'function' ) {
+				var fits = await opts.coverageCheck(qOf(problem), normAnswer(r.result));
+				if ( !fits ) {
+					lib.drift(problem);
+					try { r = await lib.solve(problem); }
+					catch ( e ) { if ( e && e.outcome === 'reject' ) return { answer: e.frontierAnswer, source: 'frontier', enriched: false, cached: false, arm: 'escalate', cost: 1 }; throw e; }
+				}
+			}
+			var local = isLocal(r.arm);
+			return { answer: normAnswer(r.result), source: local ? 'local' : 'frontier', enriched: !local, cached: local, arm: r.arm, cost: r.cost };
+		},
+
+		/** a fact drifted → invalidate the stock entry (anti-drift): the next ask re-escalates. Async because a
+		 *  semantic key must be recomputed to hit the same entry. */
+		drift: async function ( query ) {
+			if ( semanticKey ) { try { var k = await semanticKey(query); if ( k != null && String(k).length ) return lib.drift({ __proxy: true, __q: query, __k: String(k) }); } catch ( e ) {} }
+			return lib.drift(query);
+		},
+
+		/** ship / reload the minimal operational stock as a portable `.sgc` (on demand). */
+		pack: function ( o ) { return lib.pack(o); },
+		load: function ( b, o ) { return lib.load(b, o); },
+
+		/** the ladder counters {match, recallFull, recallPartial, forge, escalate, cost, calls}. */
+		stats: function () { return lib.stats(); },
+
+		/** THE COMPASS — convergence + lifecycle readout. Ladder coverage (queries served local vs escalated)
+		 *  + the RETENTION stock (size, reuse rate, dead weight, eviction tally). Drives "does it stabilize, at
+		 *  what level, and does it drop what's never used". */
+		metrics: function () {
+			var s = lib.stats() || {};
+			var local = (s.match || 0) + (s.recallFull || 0) + (s.recallPartial || 0);
+			var frontier = (s.forge || 0) + (s.escalate || 0);
+			var served = local + frontier;
+			var u = (stock && typeof stock.usage === 'function') ? stock.usage() : null;
+			return {
+				served: served, local: local, frontier: frontier,
+				coverage: served ? local / served : 0,             // cache coverage = queries served locally
+				stock: u ? { size: u.size, reused: u.reused, deadWeight: u.deadWeight, reuseRate: u.reuseRate, evicted: u.evicted } : { size: (stock && stock.size) || null }
+			};
+		},
+
+		/** run stock eviction on demand → { evicted:[keys] } (no-op without a retention store). */
+		evict: function () { return (stock && typeof stock.evict === 'function') ? stock.evict() : { evicted: [] }; },
+		/** the retention usage readout, or null (no retention store). */
+		usage: function () { return (stock && typeof stock.usage === 'function') ? stock.usage() : null; }
+	};
+}
+
+/**
+ * The FRONTIER adapter (à nu). `createProxyCache` wants `frontierAsk(query, ctx) -> answer`; a chat backend
+ * (`makeLocalAsk`, an HTTP endpoint, an API SDK) speaks `({system,user,maxTokens,temperature}) -> text`. This
+ * turns the latter into the former with a neutral answer-directly system prompt — symmetric to
+ * `makeLocalCoverage`, so a host wires real models with two one-liners:
+ *   const frontierAsk = makeFrontierAsk(makeLocalAsk({ modelPath: BIG_GGUF, reasoningBudget: 0 }));
+ *   const { semanticKey, coverageCheck } = makeLocalCoverage({ localAsk: makeLocalAsk({ modelPath: SMALL_GGUF }) });
+ *   const px = createProxyCache({ frontierAsk, semanticKey, coverageCheck, store: './.sg-proxy.json' });
+ * @param ask         async ({system,user,maxTokens,temperature}) => text — the chat backend (the ground truth).
+ * @param opts.system override the answer-directly system prompt (a domain host tightens it).
+ * @param opts.maxTokens  answer budget (default 512).
+ */
+function makeFrontierAsk( ask, opts ) {
+	opts = opts || {};
+	if ( typeof ask !== 'function' ) throw new Error('makeFrontierAsk needs a chat ask (async ({system,user}) -> text)');
+	var system = opts.system || 'You are a precise, factual assistant. Answer the question directly and correctly. If you are not sure, say so.';
+	var maxTokens = opts.maxTokens || 512;
+	return async function frontierAsk( query /*, ctx */ ) {
+		return await ask({ system: system, user: String(query), maxTokens: maxTokens, temperature: opts.temperature || 0 });
+	};
+}
+
+/**
+ * A ready-made SEMANTIC coverage pair from a local model: `semanticKey` (canonicalize a query → a short stable
+ * normal form so paraphrases collide onto ONE cache key) + `coverageCheck` (confirm a stocked answer fits the
+ * query). Both are CHEAP local calls that save an expensive frontier call — the local model's "do I cover
+ * this?" judge. Pass the pair into createProxyCache.
+ *
+ * The default `semanticKey` prompt is the KEYWORD-SLOT form (subject + attribute, question-words dropped) — a
+ * LIVE probe (2026-07-05, Qwen3-8B-Q4) measured it at 4/6 paraphrase collisions vs 0/6 for a loose
+ * "canonical normal form" prompt: a small model keeps a variable amount of the question stem, so the strict
+ * slot form is what forces string-identity. The residual misses are SYNONYMS (point↔temperature, ww2↔WWII) —
+ * a lattice/synonym-ring concern, not canonicalization. A domain host tightens further via `opts.keyPrompt`.
+ * @param opts.localAsk   async ({system,user,maxTokens}) => text — the small local model.
+ * @param opts.keyPrompt  override the canonicalization system prompt (default: the keyword-slot form).
+ * @param opts.fitPrompt  override the coverage-confirm system prompt (default: a strict yes/no fit check).
+ */
+function makeLocalCoverage( opts ) {
+	opts = opts || {};
+	var ask = opts.localAsk;
+	if ( typeof ask !== 'function' ) throw new Error('makeLocalCoverage needs opts.localAsk (async ({system,user}) -> text)');
+	var norm = function ( s ) { return String(s).trim().toLowerCase().replace(/[^a-z0-9 ]+/g, '').replace(/\s+/g, ' ').trim(); };
+	var keyPrompt = opts.keyPrompt || 'Reduce the question to its ESSENTIAL keywords ONLY: the main subject then the attribute asked about, as 2 to 4 lowercase words. DROP all question words (what/who/when/how/which/is/are/does) and articles. Examples: "What is the capital of France?" -> "france capital". "Who wrote Hamlet?" -> "hamlet author". "How tall is K2?" -> "k2 height". Reply ONLY the keywords.';
+	var fitPrompt = opts.fitPrompt || 'Does the ANSWER correctly and fully answer the QUESTION? Reply ONLY "yes" or "no".';
+	return {
+		semanticKey: async function ( query ) {
+			var t = await ask({ system: keyPrompt, user: String(query), maxTokens: 24 });
+			return norm(t) || norm(query);
+		},
+		coverageCheck: async function ( query, cachedAnswer ) {
+			var t = await ask({ system: fitPrompt, user: 'QUESTION: ' + String(query) + '\nANSWER: ' + String(cachedAnswer), maxTokens: 4 });
+			return /\byes\b/i.test(String(t));
+		}
+	};
+}
+
+/**
+ * A TYPED-INTAKE semantic key (the à-nu Intake front door, C0, run STANDALONE for the proxy). Where
+ * `makeLocalCoverage`'s key is a keyword STRING (loose string-identity — synonyms miss, no soundness gate), this
+ * snaps a prose query to a DECLARED VOCABULARY (`facts` = enum/typed schema) via the SAME canonicalization barrier
+ * as the Intake concept (`canonicalize.canonFacts` + `digest`), so a query COVERS a typed CLASS: two paraphrases
+ * with the same declared facts collapse to ONE key (a coverage far above keyword strings), and one frontier answer
+ * amortizes over the whole class — the "distillation par-classe sur un domaine déclaré" of the roadmap.
+ *
+ * THE SOUNDNESS BOUNDARY (Intake Invariant 2, carried into the proxy): a REUSABLE key is minted ONLY for a faithful
+ * (`typed`) projection. A query whose REQUIRED facts came back OUT-OF-VOCABULARY is `untyped` → the key is `null`,
+ * and `createProxyCache` degrades that to EXACT-key (never collapses an OOV query onto a wrong class → it escalates
+ * to the frontier). A `partial` (optional-only miss) likewise mints no reusable key. So the typed class NEVER
+ * false-admits a prose value as typed — the same non-negotiable as the Intake concept.
+ *
+ * THE CAVEAT (make it explicit): the typed class is only as sound as the `facts` schema is ANSWER-COMPLETE. A schema
+ * that omits an answer-determining dimension collapses two different-answer queries onto one key → a wrong cached
+ * hit. PAIR this with `makeLocalCoverage().coverageCheck` (the proxy's `opts.coverageCheck`) — the local model
+ * confirms a hit fits before it is served, invalidating + escalating a coarse-schema collision. The schema
+ * granularity IS the coverage/soundness knob; coverageCheck is its backstop.
+ *
+ * @param opts.localAsk  async ({system,user,maxTokens}) => text — the small local model (the à-nu intake ask).
+ * @param opts.facts     the DECLARED facts schema { <key>: {enum:[...]} | {type|grain|...} } (canonicalize spec).
+ * @param opts.required  the decision-bearing subset (default: ALL fact keys) — a miss here → `untyped` → null key.
+ * @param opts.keyPrompt override the extraction system prompt (default: emit the declared facts as JSON).
+ * @param opts.maxTokens extraction budget (default 64).
+ * @param opts.classOf   optional (typedFacts) => string|null — mint the CLASS key from the canonical facts instead
+ *                       of the opaque digest (e.g. `f => f.agg + '|' + f.conds` = a dataset-adapter class name), so
+ *                       the proxy's coverage classes ALIGN with a distilled `.sgc` grammar's class space and a
+ *                       loaded class METHOD is hit by prose queries (distillation par-classe, not just the key).
+ *                       Only consulted on a `typed` projection (the Invariant-2 gate runs first); a falsy return
+ *                       degrades to no key (exact-key → escalate), never a wrong class.
+ * @returns { semanticKey, project } — `semanticKey(query)` → the typed digest | null; `project(query)` → the full
+ *          { status, facts, misses, key } (for a host that wants the status/refusal, not just the key).
+ */
+function makeTypedIntakeKey( opts ) {
+	opts = opts || {};
+	var ask = opts.localAsk;
+	if ( typeof ask !== 'function' ) throw new Error('makeTypedIntakeKey needs opts.localAsk (async ({system,user}) -> text)');
+	if ( !opts.facts || typeof opts.facts !== 'object' ) throw new Error('makeTypedIntakeKey needs opts.facts (a declared facts schema)');
+	var facts = opts.facts, keys = Object.keys(facts);
+	var required = opts.required || keys;
+	var parseJSON = opts.parseJSON || llm.parseJSON;
+	var maxTokens = opts.maxTokens || 64;
+	var keyPrompt = opts.keyPrompt || ('Extract these fields from the question as a JSON object with EXACTLY these keys: '
+		+ keys.join(', ') + '. Use the question\'s own words for each value; if a field is not present, omit it. Reply ONLY the JSON.');
+
+	// the à-nu intake projection: prose → the declared typed facts → status → a reusable digest ONLY when typed.
+	var project = async function ( query ) {
+		var raw;
+		try { raw = parseJSON(await ask({ system: keyPrompt, user: String(query), maxTokens: maxTokens })); }
+		catch ( e ) { raw = {}; }
+		var cf = canon.canonFacts(raw || {}, facts);
+		var reqMiss = required.filter(function ( k ) { return cf.misses.indexOf(k) !== -1; });
+		var status = (reqMiss.length ? 'untyped' : (cf.misses.length ? 'partial' : 'typed'));
+		var key = null;
+		if ( status === 'typed' ) key = opts.classOf ? (opts.classOf(cf.facts) || null) : canon.digest(cf.facts);
+		return { status: status, facts: cf.facts, misses: cf.misses, missing: reqMiss, key: key };
+	};
+	return {
+		project: project,
+		// the semanticKey seam of createProxyCache: a typed digest collapses the class; null → exact-key (the OOV
+		// boundary — an untyped query never collapses onto a wrong class, it escalates).
+		semanticKey: async function ( query ) { return (await project(query)).key; }
+	};
+}
+
+module.exports = { createProxyCache: createProxyCache, makeLocalCoverage: makeLocalCoverage, makeFrontierAsk: makeFrontierAsk, makeTypedIntakeKey: makeTypedIntakeKey };

package/lib/combos/self-mod.js

@@ -0,0 +1,94 @@
+/*
+ * 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';
+/**
+ * C5 — SUPERVISED SELF-MODIFICATION (roadmap P3-bis). OPT-IN and GUARDED. A thin, prudent packaging of
+ * the engine's live-rule-editing bricks: `authorConcept` (CEGIS — propose→validate→install→test→refine),
+ * the reactive supervisor (`supervise`: Stuck→hypothesis→eval→revert), `patchConcept`/`addConcept`
+ * (hot-patch a live expert + re-evaluate), and `relearn` (the autonomous un-learn loop: blame→revise→
+ * patch, as reactive concepts).
+ *
+ * It edits the LIVE rules, so it is exposed with PRUDENCE:
+ *   • `author()` REQUIRES an explicit proposer (the "judge" — an `LLM::complete` in production, a
+ *     deterministic stub in tests). You cannot author without declaring how proposals are made/judged.
+ *   • REVERSIBILITY is THE guarantee: every structural op is a captured revision, and `rollbackTo(rev)`
+ *     ("git for reasoning") restores any prior coherent state. Two author-time + behavioral oracles
+ *     bound the CEGIS search (the validator rejects a malformed candidate before it touches the graph;
+ *     the live graph rejects an unmet goal).
+ *
+ * NOT activated by default anywhere — a host builds this combo explicitly. The bricks stay usable "à nu"
+ * (`Graph.authoring.author/supervise/relearn` + the engine MOE API `patchConcept/addConcept/rollbackTo`).
+ *
+ * @param opts.graph    the live graph to modify (REQUIRED).
+ * @param opts.propose  async ({goal, history, round}) => proposal   the AI author/judge (required for author()).
+ * @param opts.validate author-time validator config (palette/knownFacts/collectionKeys/strict) for the CEGIS oracle.
+ * @returns {{ graph, author, supervise, patch, addConcept, rollbackTo, revisions, relearn }}
+ */
+
+var author = require('../authoring/author.js');
+var supervise = require('../authoring/supervise.js');
+var relearn = require('../authoring/relearn.js');
+
+function createSelfMod( opts ) {
+	opts = opts || {};
+	var graph = opts.graph;
+	if ( !graph || typeof graph.patchConcept !== 'function' )
+		throw new Error('createSelfMod needs opts.graph (a live Graph with the MOE API)');
+
+	// a structural op → a promise. Mirrors author.js#applyOp: a NO-OP op destabilizes nothing, so the
+	// "stabilize" callback never fires — but the graph is already quiescent, so resolve on the next tick.
+	function structuralOp( invoke ) {
+		return new Promise(function ( resolve, reject ) {
+			var done = false, finish = function () { if ( !done ) { done = true; resolve(); } };
+			try { invoke(finish); } catch ( e ) { return reject(e); }
+			if ( !graph._unstable.length && !graph._triggeredCastCount ) setTimeout(finish);
+		});
+	}
+
+	return {
+		graph: graph,
+
+		/** CEGIS-author a concept toward `spec.goal` (propose→validate→install→test→refine). Requires a
+		 *  proposer (opts.propose or spec.propose — the guard). → { ok, concept?, rounds, reason? }. */
+		author: function ( spec ) {
+			spec = spec || {};
+			var propose = spec.propose || opts.propose;
+			if ( typeof propose !== 'function' )
+				throw new Error('self-mod author() needs a proposer: opts.propose or spec.propose (the AI author/judge)');
+			return author.authorConcept(graph, Object.assign({ validate: opts.validate }, spec, { propose: propose }));
+		},
+
+		/** run the reactive supervisor (Stuck→hypothesis→eval→revert) toward `spec`. */
+		supervise: function ( spec ) { return supervise.supervise(graph, spec || {}); },
+
+		/** hot-patch a live expert + re-evaluate (the change is a captured revision). */
+		patch: function ( nameOrId, updates ) { return structuralOp(function ( cb ) { graph.patchConcept(nameOrId, updates, cb); }); },
+		/** add a live concept under `parent` (null = root) + stabilize (a revision). */
+		addConcept: function ( parent, schema ) { return structuralOp(function ( cb ) { graph.addConcept(parent == null ? null : parent, schema, cb); }); },
+
+		/** THE reversibility guarantee: restore a prior coherent revision (git-for-reasoning). */
+		rollbackTo: function ( rev ) { return graph.rollbackTo(rev); },
+		/** the revisions available to rollbackTo (ascending). */
+		revisions: function () { return graph.getRevisions(); },
+
+		/** the autonomous un-learn loop as reactive concepts (blame→revise→patch) — host wires tree+providers. */
+		relearn: { tree: relearn.relearnTree, providers: relearn.makeRelearnProviders }
+	};
+}
+
+module.exports = { createSelfMod: createSelfMod };

package/lib/durable/audit.js

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * audit — C-audit: the durable executor's INSPECTION surface (design doc §8, "a headline win with no owner").
+ * The conception sells AUDITABILITY (typed/defeasible/auditable/versioned belief — the moat over opaque CBR/RAG);
+ * this makes it concrete. Pure + READ-ONLY over the `CheckpointStore` marking — no belief, no mutation.
+ *
+ * The marking already records everything needed: each token's `id`, `recordId`, `placeId`, `status`, `parentId`
+ * (the fan-out/fan-in lineage), `reason` (the blame), `payload` (the result). `auditRun` reconstructs:
+ *   - the DERIVATION FOREST per record: the parentId tree (root case → map children → fold collector);
+ *   - a per-record VERDICT: done / failed / pending, the terminal place, the result payload, and — on failure —
+ *     the BLAME reason (e.g. `contract:post-violated:…`, `group-failed`, `task-error:…`);
+ *   - whether the record FANNED OUT (a map) and was FOLDED back (a collector reached a sink);
+ *   - run TOTALS by status + the blame list.
+ *
+ * This is the audit trail no surface-similarity store can give: WHY a derivation holds or was retracted, traceable
+ * to the typed premise and the exact step that failed.
+ */
+
+const TERMINAL = { done: 1, failed: 1 };
+
+/**
+ * Build the audit trace for a run. Read-only.
+ * @param store  a CheckpointStore
+ * @param runId
+ * @param opts.sinks  the net's sink places (default ['done']) — to label a terminal token done-vs-elsewhere
+ * @returns { records: { <recordId>: {status, terminal, result, blame, fannedOut, folded, lineage:[…]} }, totals }
+ */
+function auditRun( store, runId, opts ) {
+	opts = opts || {};
+	const sinks = new Set(opts.sinks || ['done']);
+	const marking = store.marking(runId) || {};
+	const toks = [];
+	for ( const place of Object.keys(marking) ) for ( const t of marking[place] ) toks.push(t);
+
+	const byRecord = {};
+	for ( const t of toks ) (byRecord[t.recordId] = byRecord[t.recordId] || []).push(t);
+
+	const records = {};
+	const totals = { records: 0, done: 0, failed: 0, pending: 0, tokens: toks.length, blames: [] };
+
+	for ( const rid of Object.keys(byRecord) ) {
+		const ts = byRecord[rid].slice().sort(( a, b ) => idNum(a.id) - idNum(b.id));
+		const failed = ts.filter(( t ) => t.status === 'failed' );
+		const doneToks = ts.filter(( t ) => t.status === 'done' );
+		const fannedOut = ts.some(( t ) => t.status === 'consumed' );      // a fan-out consumes its source
+		const folded = ts.some(( t ) => t.parentId != null && t.status === 'done' && hasJoinedSiblings(ts, t.parentId) );
+
+		// verdict: a SURVIVORS fold wins FIRST — a collector reached a sink carrying `_partial` despite some FAILED
+		// (dropped) shards: that is done(partial), NOT a record failure (the drops are expected, surfaced not fatal).
+		// Else failed wins (any failure quarantines the record — fail-fast); else done iff a token reached a sink;
+		// else still pending (claimable/leased/parked).
+		const partialDone = doneToks.find(( t ) => t.payload && t.payload._partial === true );
+		let status, terminal = null, result, blame = null, partial = false, dropped = 0;
+		if ( partialDone ) {
+			status = 'done'; partial = true;
+			terminal = partialDone.placeId; result = partialDone.payload;
+			dropped = partialDone.payload._dropped != null ? partialDone.payload._dropped : failed.length;
+		} else if ( failed.length ) {
+			status = 'failed';
+			blame = failed.map(( t ) => t.reason ).find(( r ) => r && !/^sibling-failed$|^group-failed$/.test(r) ) || failed[0].reason;
+			terminal = failed[0].placeId;
+		} else if ( doneToks.length ) {
+			status = 'done';
+			const last = doneToks[doneToks.length - 1];                    // the fold collector, if any, is the last-created done
+			terminal = last.placeId; result = last.payload;
+		} else {
+			status = 'pending';
+		}
+
+		records[rid] = {
+			status, partial, dropped, terminal, result, blame, fannedOut, folded,
+			tokens: ts.length,
+			lineage: ts.map(( t ) => ({ id: t.id, place: t.placeId, status: t.status, parentId: t.parentId == null ? null : t.parentId,
+				reason: t.reason == null ? undefined : t.reason })),
+		};
+		totals.records++; totals[status]++;
+		if ( blame ) totals.blames.push({ recordId: rid, reason: blame });
+	}
+	return { records, totals };
+}
+
+function idNum( id ) { const n = parseInt(String(id).replace(/^t/, ''), 10); return isNaN(n) ? 0 : n; }
+function hasJoinedSiblings( ts, parentId ) { return ts.some(( t ) => t.parentId === parentId && t.status === 'joined' ); }
+
+/** A compact one-line-per-record summary (for a CLI / log). */
+function auditSummary( audit ) {
+	const lines = [];
+	for ( const rid of Object.keys(audit.records) ) {
+		const r = audit.records[rid];
+		lines.push(`${rid}: ${r.status}${r.partial ? ' (partial, ' + r.dropped + ' dropped)' : ''}${r.fannedOut ? ' (map' + (r.folded ? '→fold' : '') + ')' : ''}` +
+			`${r.blame ? ' — ' + r.blame : ''} @${r.terminal || '?'}`);
+	}
+	return lines.join('\n');
+}
+
+module.exports = { auditRun, auditSummary };