skynet-graph 1.2.0

package/lib/authoring/registry.js

@@ -0,0 +1,350 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * registry — the interface-alphabet REGISTRY (Σ_sep), G-1 rung 3b: the STAGE-1 keystone as a FIRST-CLASS,
+ * CURATED, VERSIONED object (the owner's library CATALOG). It promotes the DERIVED separator alphabet
+ * (`decompose.js#bagInterface.sigmaSep`) + the typed value vocabulary (enum members / curated synonym RINGS /
+ * grain / sort, from `prompt.facts`) from scattered-per-concept to ONE object where the vocabulary LIVES,
+ * versioned and enforceable. It is the home of three things this session built separately:
+ *   • the curated SYNONYM RINGS (rung 1) — now sourced FROM the registry (`specForKey`), not re-inlined per concept;
+ *   • the cross-method COHERENCE (rung 3) — now checkable against the FROZEN canon, not just within one tree;
+ *   • the borderline PROPOSALS (rung 2) — admitted via `mergeRingProposals` (confluence re-checked), converging the ring.
+ *
+ * TIERS (the soundness/flexibility split — §9 vocab topology): a key ∈ `sigmaSep` (a cross-tile SEPARATOR) is
+ * **Tier-1** (the closed, frozen, producer↔consumer interface); everything else is **Tier-2** (open interior). Freezing
+ * is on Tier-1 only — a new Tier-1 value must go through a validated proposal (version bump); Tier-2 stays open.
+ *
+ *   const reg = freezeRegistry(deriveRegistry(tree), 'v1');   // derive + stamp the canon
+ *   const spec = specForKey(reg, 'severity');                 // { enum, synonyms } for canonValue — the ring lives here
+ *   const reg2 = mergeRingProposals(reg, borderlineProposals);// admit validated aliases → the ring converges (v2)
+ *   const { errors } = checkTreeAgainstRegistry(otherTree, reg);// enforce: no off-canon Tier-1 value / un-registered key
+ */
+const { eachConcept, refsOf, refKeyOf } = require('./validate.js');
+const { conceptCliques, bagInterface } = require('./decompose.js');
+const { compileEnumMap, normToken } = require('../providers/canonicalize.js');
+
+// the literal STRING values an applyMutations template WRITES per key (a closed-vocab value written by a template —
+// part of the reachable vocabulary). Same discipline as validate.js#templateStringValues (kept local for independence).
+function templateValues( tpl, out ) {
+	out = out || {};
+	(function walk( n ) {
+		if ( Array.isArray(n) ) return n.forEach(walk);
+		if ( n && typeof n === 'object' ) for ( const k in n ) {
+			const v = n[k];
+			if ( typeof v === 'string' && k[0] !== '$' && k !== '_id' && v[0] !== '$' ) (out[k] = out[k] || new Set()).add(v);
+			else if ( v && typeof v === 'object' ) walk(v);
+		}
+	})(tpl);
+	return out;
+}
+
+const uniq = ( xs ) => [...new Set(xs)];
+
+/**
+ * Derive the registry from a concept tree (does not FREEZE it — that is `freezeRegistry`). Total: any confluence
+ * conflict in the merged rings is RECORDED (`reg.conflicts`), never thrown (a tree can be inconsistent; the caller gates).
+ * @returns { version:null, frozen:false, keys:{ <key>: entry }, conflicts:[{key,error}] }
+ *   entry = { tier:1|2, enum?:[..], synonyms?:{member:[alias]}, grain?, sort?, producers:[name], consumers:[name], values:[..] }
+ */
+function deriveRegistry( tree ) {
+	const sep = new Set(bagInterface(conceptCliques(tree)).sigmaSep);   // the cross-tile separator alphabet (a Tier-1 signal)
+	const keys = Object.create(null);
+	const ent = ( k ) => (keys[k] = keys[k] || { producers: new Set(), consumers: new Set(), values: new Set() });
+
+	eachConcept(tree, ( c ) => {
+		if ( !c._name ) return;
+		const schema = c._schema || c;
+		ent(c._name).producers.add(c._name);                            // the self-flag is produced by the concept
+		const facts = schema.prompt && schema.prompt.facts;
+		if ( facts ) for ( const key of Object.keys(facts) ) {
+			const spec = facts[key], e = ent(key);
+			e.producers.add(c._name);
+			if ( spec && spec.enum ) {
+				e.enum = uniq([...(e.enum || []), ...spec.enum]);
+				for ( const m of spec.enum ) e.values.add(m);
+				if ( spec.synonyms ) { e.synonyms = e.synonyms || {};
+					for ( const member of Object.keys(spec.synonyms) )
+						e.synonyms[member] = uniq([...(e.synonyms[member] || []), ...(spec.synonyms[member] || [])]); }
+			}
+			if ( spec && spec.grain != null ) e.grain = spec.grain;
+			if ( spec && spec.sort != null ) e.sort = spec.sort;
+		}
+		const tv = templateValues(schema.applyMutations);               // template writes → producer + reachable values
+		for ( const key of Object.keys(tv) ) { const e = ent(key); e.producers.add(c._name); for ( const v of tv[key] ) e.values.add(v); }
+		for ( const r of refsOf(schema.require, false).concat(refsOf(schema.ensure, true), refsOf(schema.assert, true)) )
+			ent(refKeyOf(r).key).consumers.add(c._name);                // a gate → consumer of the key
+	});
+
+	const conflicts = [];
+	const out = { version: null, frozen: false, keys: {}, conflicts };
+	for ( const k of Object.keys(keys) ) {
+		const e = keys[k];
+		// Tier-1 = a cross-tile SEPARATOR (sigmaSep) OR a typed enum interface that is BOTH produced and consumed (an
+		// actual interface vocabulary — the sigmaSep structural cut can miss it on small trees). Else Tier-2 (interior).
+		const tier = (sep.has(k) || (e.enum && e.producers.size && e.consumers.size)) ? 1 : 2;
+		const entry = { tier, producers: [...e.producers].sort(), consumers: [...e.consumers].sort(), values: [...e.values].sort() };
+		if ( e.enum ) entry.enum = e.enum;
+		if ( e.synonyms ) entry.synonyms = e.synonyms;
+		if ( e.grain != null ) entry.grain = e.grain;
+		if ( e.sort != null ) entry.sort = e.sort;
+		if ( entry.enum ) { try { compileEnumMap(specForEntry(entry)); } catch ( err ) { conflicts.push({ key: k, error: err.message }); } }
+		out.keys[k] = entry;
+	}
+	return out;
+}
+
+// a canonValue spec ({enum, synonyms, grain}) for a registry ENTRY — the source of truth for the barrier (the ring LIVES here).
+function specForEntry( entry ) {
+	const spec = {};
+	if ( entry.enum ) spec.enum = entry.enum;
+	if ( entry.synonyms ) spec.synonyms = entry.synonyms;
+	if ( entry.grain != null ) spec.grain = entry.grain;
+	return spec;
+}
+/** The canonValue spec for a registry KEY, or null if the key carries no typed vocabulary. */
+function specForKey( reg, key ) {
+	const entry = reg && reg.keys && reg.keys[key];
+	if ( !entry || (!entry.enum && entry.grain == null) ) return null;
+	return specForEntry(entry);
+}
+
+/**
+ * Resolve a `prompt.facts` schema against the registry: a spec `{ ref: '<key>' }` is REPLACED by the registry's canonical
+ * spec for that key (enum + ring + grain) — so a concept REFERENCES the registry vocabulary instead of re-inlining the
+ * ring (one source of truth; the ring lives in the registry). A local `from` (the raw reply key) is preserved. A spec
+ * without `ref` passes through unchanged. An unknown/non-typed ref is left AS-IS and reported in `unresolved` (the caller
+ * decides: an author-time ERROR, or a runtime untyped/CanonMiss).
+ * @returns { facts, unresolved:[{key,ref}] }
+ */
+function resolveFactsSchema( factsSchema, registry ) {
+	const facts = {}, unresolved = [];
+	for ( const key of Object.keys(factsSchema || {}) ) {
+		const spec = factsSchema[key] || {};
+		if ( spec.ref ) {
+			const rspec = specForKey(registry, spec.ref);
+			if ( rspec ) facts[key] = Object.assign(rspec, spec.from != null ? { from: spec.from } : {});
+			else { facts[key] = spec; unresolved.push({ key, ref: spec.ref }); }
+		} else facts[key] = spec;
+	}
+	return { facts, unresolved };
+}
+
+/** Stamp a version + FREEZE the registry (Tier-1 becomes the closed canon; Tier-2 stays open). Returns a new object. */
+function freezeRegistry( reg, version ) {
+	return Object.assign({}, reg, { frozen: true, version: version == null ? (reg.version || 'v1') : version });
+}
+
+/**
+ * Admit borderline / LILO ring PROPOSALS into the registry (propose-only → validated). Each `{key, alias, member}` is
+ * added to key's ring iff (a) member is a registered enum member of key, and (b) the resulting ring stays CONFLUENT
+ * (the critical-pair check — `compileEnumMap` does not throw). Rejected proposals are returned; on any admit the version
+ * bumps. Never mutates the input registry.
+ * @returns { registry, admitted:[{key,alias,member}], rejected:[{key,alias,member,reason}] }
+ */
+function mergeRingProposals( reg, proposals ) {
+	const keys = JSON.parse(JSON.stringify(reg.keys || {}));
+	const provenance = Object.assign({}, reg.ringProvenance || {});   // parallel { <provKey> -> {member,via} } — audit + retraction handle
+	const admitted = [], rejected = [];
+	for ( const p of (proposals || []) ) {
+		const entry = keys[p.key];
+		if ( !entry || !entry.enum ) { rejected.push(Object.assign({ reason: 'no such enum key' }, p)); continue; }
+		if ( entry.enum.indexOf(p.member) < 0 ) { rejected.push(Object.assign({ reason: 'member not in the enum' }, p)); continue; }
+		const trial = { enum: entry.enum, synonyms: Object.assign({}, entry.synonyms) };
+		trial.synonyms[p.member] = uniq([...(trial.synonyms[p.member] || []), p.alias]);
+		try { compileEnumMap(trial); }
+		catch ( err ) { rejected.push(Object.assign({ reason: 'breaks confluence: ' + err.message }, p)); continue; }
+		entry.synonyms = trial.synonyms; admitted.push(p);
+		// PROVENANCE (Laurie confront): tag every admitted alias with its source. Model-independent value — it makes an
+		// admission AUDITABLE and RETRACTABLE (the outcome-blame loop / a curator can find + retractRingAlias a model-
+		// sourced entry). Keyed post-normToken so it lines up with canonValue's lookup + retractRingAlias.
+		provenance[provKey(p.key, p.alias)] = { member: p.member, via: p.via || 'proposal' };
+	}
+	const version = admitted.length ? bumpVersion(reg.version) : reg.version;
+	return { registry: Object.assign({}, reg, { keys, version, ringProvenance: provenance }), admitted, rejected };
+}
+const provKey = ( key, alias ) => key + '::' + normToken(alias);
+
+/**
+ * RETRACT a synonym-ring ALIAS — the un-learn verb for the ring, and the actual DEFUSER of a bad autonomous admission
+ * (Laurie confront: "8/8 does not certify an oracle" — Rule-of-Three 95% upper bound ≈ 37% on 8 samples; so soundness
+ * rests on RECOVERABILITY, not oracle reliability. A strong model lowers the RATE of a wrong admit; retraction bounds the
+ * DAMAGE). It is the vocabulary-level sibling of relearn.js's blame→un-learn, and the "teeth" that make the registry's
+ * "audited + retractable" envelope actually TRUE (there was no retraction path — the ring only ever ADDED).
+ *
+ * Removes `alias` (by normToken) from every member's ring under `key`, which DE-LOCKS it: because mergeRingProposals is
+ * first-writer-wins-under-confluence, a wrong `catastrophic→low` blocks the correct `catastrophic→high` ("breaks
+ * confluence"); after retraction the corrected proposal is admissible (removal can never break confluence). The version
+ * bumps iff something changed — and the bump IS the invalidation signal (B8 version-gates the replay paths, so a digest/
+ * cache entry typed via the retracted alias is gated, not silently served stale). Never mutates the input registry.
+ * @returns { registry, retracted:bool, member:(the member the alias mapped to, or null) }
+ */
+function retractRingAlias( reg, key, alias ) {
+	const keys = JSON.parse(JSON.stringify(reg.keys || {}));
+	const entry = keys[key];
+	const na = normToken(alias);
+	let member = null, changed = false;
+	if ( entry && entry.synonyms ) {
+		for ( const m of Object.keys(entry.synonyms) ) {
+			const before = entry.synonyms[m] || [];
+			const after = before.filter(( a ) => normToken(a) !== na);
+			if ( after.length !== before.length ) { member = m; changed = true; }
+			if ( after.length ) entry.synonyms[m] = after; else delete entry.synonyms[m];
+		}
+		if ( Object.keys(entry.synonyms).length === 0 ) delete entry.synonyms;
+	}
+	const provenance = Object.assign({}, reg.ringProvenance || {});
+	if ( provenance[provKey(key, alias)] ) { delete provenance[provKey(key, alias)]; changed = true; }
+	const version = changed ? bumpVersion(reg.version) : reg.version;
+	return { registry: Object.assign({}, reg, { keys, version, ringProvenance: provenance }), retracted: changed, member };
+}
+function bumpVersion( v ) {
+	const m = /^v(\d+)$/.exec(String(v || 'v1'));
+	return m ? 'v' + (Number(m[1]) + 1) : String(v || 'v1') + '+1';
+}
+
+/**
+ * The vocabulary-grain ADMISSION rule (G4) — the ratchet's teeth applied to a surface ALIAS. Pure decision:
+ * given the episode verdicts under the TWO counterfactuals (with the proposed alias→member mapping applied,
+ * and without any mapping), admit iff the alias is LOAD-BEARING for the success — the verdict passes WITH it
+ * and fails WITHOUT it (the vacuity guard: a benign word whose episode succeeds anyway must never enter the
+ * ring). LOCALIZATION (a single pending alias exercised per episode — the 8d credit discipline, see
+ * parametric.js#attributeSlotCredit) is the CALLER's tooth: this rule assumes the two verdicts are
+ * attributable to THIS alias. Member-UNIQUENESS over the whole enum is deliberately NOT required — on one
+ * episode members are verdict-equivalent by category class (requiring uniqueness would self-seal a correct
+ * alias forever, the lab's C-arm defect at vocab grain); intra-class discrimination = the semantic prior
+ * (the model's proposal picks the member) + the defeasible envelope (support via `creditRingAlias`, damage
+ * bounded by `retractRingAlias`). Report `equivalents` (how many members would also pass) as a DIAGNOSTIC,
+ * never a gate.
+ * @param opts { member, withAlias:bool, withoutAlias:bool }
+ * @returns { admit, reason } — reason ∈ admit|no-proposal|vacuous|failed-verify
+ */
+function decideRingAdmission( opts ) {
+	if ( !opts || !opts.member || opts.member === 'none' ) return { admit: false, reason: 'no-proposal' };
+	if ( opts.withoutAlias ) return { admit: false, reason: 'vacuous' };
+	if ( !opts.withAlias ) return { admit: false, reason: 'failed-verify' };
+	return { admit: true, reason: 'admit' };
+}
+
+/**
+ * CREDIT a ring alias on a VERIFIED reuse — the `confiance` half of the defeasible ring's {source, confiance}
+ * envelope (`via` = the source, `support` = verified-use count; the reading a curator or a selection pressure
+ * consumes). Rule-of-Three stays the doctrine: support bounds what verified use can certify — soundness rests
+ * on RECOVERABILITY (retractRingAlias), never on the count. An AUTHORED alias (in a ring with no provenance
+ * entry) gets `{via:'authored'}` on first credit, so confidence reads uniformly across sources. Does NOT bump
+ * the version: support changes no resolution semantics, so version-gated replay/caches must not invalidate on
+ * credit. Never mutates the input registry.
+ * @returns { registry, member, support } — support = the new count, or null when the alias resolves nowhere under key.
+ */
+function creditRingAlias( reg, key, alias ) {
+	const entry = reg && reg.keys && reg.keys[key];
+	const na = normToken(alias);
+	let member = null;
+	if ( entry && entry.synonyms )
+		for ( const m of Object.keys(entry.synonyms) )
+			if ( (entry.synonyms[m] || []).some(( a ) => normToken(a) === na) ) { member = m; break; }
+	if ( member == null ) return { registry: reg, member: null, support: null };   // exact enum words are not ring entries
+	const provenance = Object.assign({}, reg.ringProvenance || {});
+	const pk = provKey(key, alias);
+	const prev = provenance[pk] || { member, via: 'authored' };
+	provenance[pk] = Object.assign({}, prev, { support: (prev.support || 0) + 1 });
+	return { registry: Object.assign({}, reg, { ringProvenance: provenance }), member, support: provenance[pk].support };
+}
+
+/**
+ * Enforce a concept tree against a registry — "crystallize/dispatch consult the registry". Two findings, kept sound:
+ *   • off-canon VALUE (ERROR when frozen) — a concept types a key with an enum value the registry's enum for that key
+ *     does NOT list. A registered enum IS the closed vocabulary for that key (any tier), so this is a clear canon
+ *     divergence → hard error on a frozen canon (a warning otherwise). SOUND: no false errors — subset trees are clean.
+ *   • un-registered enum KEY (WARN) — the tree types an enum key the registry does not know. This is ADVISORY, never a
+ *     hard error: it may be a legit Tier-2 (interior) extension OR a Tier-1 omission — the curator decides. (Freezing
+ *     cannot soundly hard-refuse an unknown key without knowing it MUST be Tier-1.)
+ * @returns { errors, warnings }  each `{ concept, kind, message }`.
+ */
+function checkTreeAgainstRegistry( tree, reg ) {
+	const errors = [], warnings = [];
+	const frozen = !!(reg && reg.frozen);
+	const known = (reg && reg.keys) || {};
+	eachConcept(tree, ( c ) => {
+		if ( !c._name ) return;
+		const facts = (c._schema || c).prompt && (c._schema || c).prompt.facts;
+		if ( !facts ) return;
+		for ( const key of Object.keys(facts) ) {
+			const spec = facts[key];
+			if ( !spec || !spec.enum ) continue;
+			const entry = known[key];
+			if ( !entry || !entry.enum ) {                              // an enum key the canon does not know → advisory only
+				warnings.push({ concept: c._name, kind: 'unregistered-interface-key', message: `typed interface key "${key}" is not in the registry — register it (Tier-1) or confirm it is a Tier-2 interior extension` });
+				continue;
+			}
+			for ( const v of spec.enum ) if ( entry.enum.indexOf(v) < 0 )   // a value outside the registered closed vocabulary
+				(frozen ? errors : warnings).push({ concept: c._name, kind: 'off-canon-value', tier: entry.tier,
+					message: `key "${key}" value "${v}" is not in the registry enum {${entry.enum.join(', ')}} — the tree diverged from the canon; add it via a validated proposal` });
+		}
+	});
+	return { errors, warnings };
+}
+
+// "validate consults the registry" — compose the author-time structural validator with the registry enforcement (kept
+// here, not in validate.js, to avoid a require cycle: registry already depends on validate). Merges both finding sets.
+function validateWithRegistry( tree, reg, opts ) {
+	const base = require('./validate.js').validateConceptTree(tree, opts);
+	const ren = checkTreeAgainstRegistry(tree, reg);
+	return { errors: base.errors.concat(ren.errors), warnings: base.warnings.concat(ren.warnings) };
+}
+
+// ─────────────────────────── the AUTONOMOUS convergence loop (the living catalog — sibling of relearn.js) ──────────────
+//
+// The engine drives borderline PROPOSAL → validated ring GROWTH as REACTIVE concepts at the stabilize fixpoint, with NO
+// host glue (mirrors `relearn.js`'s blame→revise loop). A proposer (the rung-2 borderline gate, or any) deposits a
+// proposal on a FRESH proxy node (`proposalTemplate`, #22-safe: one node → one fire); a `RegistryMerge` meta-concept
+// (`require:['proposalMember'], ensure:['!$merged']`) fires; `Reg::merge` admits it via `mergeRingProposals` (member∈enum
+// ∧ CONFLUENCE re-checked) into a MUTABLE registry container so every closure (the `resolveFacts` seam) sees the grown
+// ring — the exogenous vocabulary CONVERGES autonomously. An invalid proposal is REJECTED (registry unchanged) but still
+// marks `merged` (no re-fire / no `divergent`, the #33 GOTCHA). Curation stays a gate: `mergeRingProposals` is the gate.
+
+/** The reactive convergence flow as a concept tree. @param opts.name  meta-concept id (default 'RegistryMerge'). */
+function registryLoopTree( opts ) {
+	opts = opts || {};
+	const name = (opts && opts.name) || 'RegistryMerge';
+	const tree = { childConcepts: {} };
+	tree.childConcepts[name] = { _id: name, _name: name, require: ['proposalMember'], ensure: ['!$merged'], provider: ['Reg::merge'] };
+	return tree;
+}
+
+/** Build a proposal-deposit template (a FRESH proxy node per proposal → RegistryMerge fires exactly once). `via` carries
+ *  the source (e.g. 'llm-borderline') into the admit provenance. */
+function proposalTemplate( proposal, id ) {
+	return { $$_id: id, proposalKey: proposal.key, proposalAlias: proposal.alias, proposalMember: proposal.member, proposalVia: proposal.via };
+}
+
+/**
+ * The reactive merge provider (host opt-in, like `makeRelearnProviders`). `Reg::merge` admits the pending proposal into a
+ * MUTABLE registry container (so the grown ring is visible to every closure — the living catalog).
+ * @param opts.regBox  { registry } — the mutable container (merge swaps in the grown registry). Or pass opts.registry.
+ * @param opts.onMerge optional (mergeResult, regBox) => void — a hook (audit / persist the versioned registry).
+ * @returns { Reg: { merge } }
+ */
+function makeRegistryLoopProviders( opts ) {
+	opts = opts || {};
+	const regBox = opts.regBox || { registry: opts.registry };
+	return { Reg: {
+		merge: function ( graph, concept, scope, argz, cb ) {
+			const e = (scope && scope._) || {};
+			const p = { key: e.proposalKey, alias: e.proposalAlias, member: e.proposalMember, via: e.proposalVia };
+			const r = mergeRingProposals(regBox.registry, [p]);
+			regBox.registry = r.registry;                            // swap in the grown registry (closures re-read it)
+			if ( opts.onMerge ) { try { opts.onMerge(r, regBox); } catch ( _e ) {} }
+			cb(null, { $_id: '_parent', RegistryMerge: true, merged: true,   // self-flag + re-fire guard (#33)
+				registryVersion: regBox.registry.version, admitted: r.admitted.length > 0,
+				rejectedReason: r.rejected.length ? r.rejected[0].reason : null });
+		}
+	} };
+}
+
+module.exports = { deriveRegistry, freezeRegistry, specForKey, resolveFactsSchema, mergeRingProposals, retractRingAlias, decideRingAdmission, creditRingAlias, checkTreeAgainstRegistry, validateWithRegistry,
+	registryLoopTree, proposalTemplate, makeRegistryLoopProviders };

package/lib/authoring/relearn.js

@@ -0,0 +1,147 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * The STANDING / autonomous C-contract un-learn loop (§3.1) — the engine drives
+ * blame → revise → patch as REACTIVE concepts at the stabilize fixpoint, with NO host
+ * glue. The defeasance moat no RAG / CBR / skill-library has: when a learned method's
+ * typed premise falls, the JTMS retracts the belief (handled by the engine) AND the
+ * library autonomously, surgically NARROWS the method's applicability (this module) —
+ * versioned/undoable (N6/B8).
+ *
+ * This is the reactive sibling of the host-orchestrated `examples/poc/contract-unlearn.js`
+ * (whose steps 3-4 — reviseOnBlame + the gate narrowing — were plain host JS). It mirrors
+ * the shape of `supervise.js#reactiveSupervisorTree` / `makeSupervisorProviders`:
+ *   - a `cleaner` (`Lib::blame`) deposits, on retraction, BOTH the typed constat AND a
+ *     discrete `blamed` fact on the method's library node — a clean `require` trigger;
+ *   - a `Revise` meta-concept (`require:['blamed']`, `ensure:["!$revised"]`) fires on the
+ *     blame's appearance (#22-safe: keyed on a fact APPEARING, not a value change);
+ *   - the `Lib::revise` provider revises the library contract (reviseOnBlame / CEGIS) AND
+ *     `patchConcept`es the engine gate to match (queued mid-stabilize, #11.a) — then sets
+ *     its own cast marker + the `revised` re-fire guard (the #33 GOTCHA).
+ *
+ * Wiring (see `examples/poc/contract-relearn.js`):
+ *   const { makeRelearnProviders, relearnTree } = require('./relearn');
+ *   Graph._providers = Object.assign({ App:{approve} }, createConstat(), makeRelearnProviders({ registry }));
+ *   // tree: the defeasant method gets `cleaner:['Lib::blame'], discriminator:'region', constat:{...}`
+ *   //       + the relearnTree() Revise concept; seed a `lib:<Method>` node.
+ */
+
+const { recordConstat } = require('../providers/constat.js');
+const { reviseOnBlame } = require('./contract.js');
+
+// The exclusion atom a point-exclusion revision adds, in the engine/expr.js form
+// (`$key!='val'` for strings, `$key!=val` for numbers — VERIFIED to parse on the real
+// expr.js, single quotes included). Kept identical to reviseOnBlame's pre atom so the
+// library contract and the engine `ensure` gate stay in lockstep.
+function exclusionAtom( ce ) {
+	if ( ce == null || ce.key == null || ce.value === undefined ) return null;
+	return '$' + ce.key + '!=' + (typeof ce.value === 'string' ? "'" + ce.value + "'" : ce.value);
+}
+
+// The default revision STRATEGY (open R&D / pluggable, §7): point-exclude the failing
+// discriminator (CEGIS specialize-pre, NOT method removal — which oscillates). Returns the
+// new contract + the matching engine-gate atom so the gate sync is derived from the strategy
+// (a different strategy — tighten-bound, etc. — returns its own atom).
+function defaultStrategy( contract, ce ) {
+	return { contract: reviseOnBlame(contract, ce), ensureAtom: exclusionAtom(ce) };
+}
+
+/**
+ * The reactive un-learn flow as a concept tree (vs the host-orchestrated loop in
+ * contract-unlearn.js). One meta-concept:
+ *   <Method> ──retract──▶ (cleaner Lib::blame deposits `blamed` on lib:<Method>)
+ *   blamed ──require──▶ Revise  (ensure !revised)  ──▶ Lib::revise narrows the library + the gate
+ * @param opts.name  the meta-concept id/_name (default 'Revise')
+ */
+function relearnTree( opts ) {
+	opts = opts || {};
+	var name = opts.name || 'Revise';
+	var def  = { _id: name, _name: name, require: ['blamed'], ensure: ['!$revised'], provider: ['Lib::revise'] };
+	var tree = { childConcepts: {} };
+	tree.childConcepts[name] = def;
+	return tree;
+}
+
+/**
+ * The Lib provider pair (host opt-in, like createConstat / makeSupervisorProviders).
+ * @param opts.registry  { <Method>: contract } — the library's typed contracts; revise
+ *                       mutates the entry to the new (versioned) contract. Pass copies for B8.
+ * @param opts.strategy  (contract, ce) => { contract, ensureAtom }  — the revision policy
+ *                       (default = point-exclusion via reviseOnBlame). Injectable (§7).
+ * @returns { Lib: { blame, revise } }
+ */
+function makeRelearnProviders( opts ) {
+	opts = opts || {};
+	var registry = opts.registry || {};
+	var strategy = opts.strategy || defaultStrategy;
+
+	return { Lib: {
+		// cleaner: on a method's retraction, deposit (a) the typed constat on `mem` AND
+		// (b) a discrete `blamed` fact on the method's library node lib:<Method> (a clean
+		// `require` trigger for Revise). Multi-target template (pushMutation accepts arrays).
+		blame: function ( graph, concept, scope, argz, cb ) {
+			var cfg   = Object.assign({ memId: 'mem', storeKey: 'lessons' },
+				concept._schema && concept._schema.constat, argz && argz[0]);
+			var disc  = concept._schema && concept._schema.discriminator;   // e.g. 'region'
+			var e     = (scope && scope._) || {};
+			var libId = (concept._schema && concept._schema.libNode) || ('lib:' + concept._name);
+			var blameTpl = {
+				$$_id      : libId,
+				blamed     : true,
+				method     : concept._name,
+				claim      : cfg.claimKey != null && e[cfg.claimKey] != null ? e[cfg.claimKey] : null,
+				because    : cfg.because != null ? cfg.because : null,
+				failingCase: e._id,
+				discKey    : disc != null ? disc : null,
+				discVal    : disc != null ? e[disc] : null,
+				atRev      : graph.getCurrentRevision()
+			};
+			cb(null, [recordConstat(graph, concept, scope, cfg), blameTpl]);
+		},
+
+		// the standing revise: read the blame → revise the library contract + narrow the
+		// engine gate, autonomously. ZERO host orchestration (vs contract-unlearn.js:85-93).
+		revise: function ( graph, concept, scope, argz, cb ) {
+			var e  = (scope && scope._) || {};
+			var M  = e.method;
+			var ce = { key: e.discKey, value: e.discVal };
+
+			// 1 — revise the library contract (B8: a NEW contract; we version the registry entry).
+			var out = strategy(registry[M], ce);
+			if ( registry[M] != null ) registry[M] = out.contract;
+
+			// 2 — narrow the engine gate to match. Concept.patch REPLACES arrays → pass the FULL
+			//     ensure. The patch is issued mid-stabilize → QUEUED to the quiescent boundary (#11.a).
+			var target    = graph.getConceptByName(M);
+			var newEnsure = (target && target._schema.ensure || []).slice();
+			if ( out.ensureAtom && newEnsure.indexOf(out.ensureAtom) < 0 ) {
+				newEnsure.push(out.ensureAtom);
+				graph.patchConcept(M, { ensure: newEnsure });
+			}
+
+			// 3 — own cast marker (#33) + `revised` re-fire guard; B8: the live narrowed pre is
+			//     stored as a graph fact on lib:<Method> (typed DSL atoms, not prose) so rollbackTo
+			//     restores both the concept (N6) and the recorded pre coherently.
+			cb(null, { $_id: '_parent', Revise: true, revised: true,
+				narrowedPre: out.contract && out.contract.pre, narrowedEnsure: newEnsure });
+		}
+	} };
+}
+
+module.exports = { makeRelearnProviders, relearnTree, defaultStrategy, exclusionAtom };

package/lib/authoring/retention.js

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * retention — a USAGE-TRACKING, self-EVICTING store wrapper (host-side, ZERO-CORE, fs-free). The RETENTION
+ * axis of a concept's life-cycle, sibling of `lifecycle.js` (the PLASTICITY/consolidation axis): lifecycle
+ * answers "is it reliable?" (proven → freeze); retention answers "is it USED?" (reused → keep, never used →
+ * evict). The owner's compass (2026-07-05): a stock must EARN its keep — track per-entry reuse and REMOVE the
+ * dead weight, so the local operational stock stays MINIMAL and converges. Wraps any Map-like store the
+ * master-loop cache uses (`has`/`get`/`set`/`delete`); a served `get` on a present key counts a reuse.
+ *
+ * Two eviction rules (opt-in — with neither, the wrapper only MEASURES, never drops):
+ *   • DEAD WEIGHT — an entry set but never re-served (`uses == 0`) past `evictGrace` operations is removed
+ *     ("supprime ce qui n'est jamais utilisé"); a re-used entry (`uses > 0`) is NEVER dropped by this rule.
+ *   • BOUNDED — beyond `maxStock` entries, evict the LEAST-RECENTLY-served (LRU) until back under the cap.
+ *
+ * The clock is a LOGICAL operation counter (deterministic, no wall-clock) → eviction + `usage()` replay
+ * identically in a test. `usage()` is the compass readout: size, reused/dead split, per-entry reuse, the
+ * running reuse rate, and the eviction tally (dead-weight vs LRU).
+ *
+ *   const store = createRetentionStore(new Map(), { maxStock: 500, evictGrace: 50 });
+ *   const px = createProxyCache({ frontierAsk, store });   // the proxy's stock now self-manages
+ *   store.usage();   // { size, reused, deadWeight, reuseRate, evicted:{deadWeight,lru}, byKey:[…] }
+ *
+ * @param inner  a Map-like store ({ has, get, set, delete }); default a fresh Map.
+ * @param opts   { maxStock, evictGrace, autoEvict } — autoEvict (default true iff a rule is set) runs evict on set.
+ */
+function createRetentionStore( inner, opts ) {
+	opts = opts || {};
+	inner = inner || new Map();
+	const meta = new Map();                  // key → { uses, addedAt, lastUsed }
+	let clock = 0;
+	const evicted = { count: 0, deadWeight: 0, lru: 0 };
+	const hasRule = opts.maxStock != null || (opts.evictGrace != null && isFinite(opts.evictGrace));
+	const autoEvict = opts.autoEvict != null ? opts.autoEvict : hasRule;
+
+	function drop( k ) { meta.delete(k); return inner.delete(k); }
+
+	function evict() {
+		const out = [];
+		if ( opts.evictGrace != null && isFinite(opts.evictGrace) ) {           // (a) dead weight — never re-served past the grace window
+			for ( const [k, m] of meta ) if ( m.uses === 0 && (clock - m.addedAt) > opts.evictGrace ) { drop(k); out.push(k); evicted.deadWeight++; }
+		}
+		if ( opts.maxStock != null ) {                                          // (b) bounded — evict the LEAST VALUABLE
+			while ( meta.size > opts.maxStock ) {                               // least-frequently-used first, then least-recently (keep what's reused)
+				let victimK = null, vUses = Infinity, vLast = Infinity;
+				for ( const [k, m] of meta ) if ( m.uses < vUses || (m.uses === vUses && m.lastUsed < vLast) ) { vUses = m.uses; vLast = m.lastUsed; victimK = k; }
+				if ( victimK == null ) break;
+				drop(victimK); out.push(victimK); evicted.lru++;
+			}
+		}
+		evicted.count += out.length;
+		return { evicted: out };
+	}
+
+	const store = {
+		has( k ) { return inner.has(k); },                                     // a probe — NOT a reuse
+		get( k ) { if ( inner.has(k) ) { const m = meta.get(k); if ( m ) { m.uses++; m.lastUsed = clock++; } } return inner.get(k); },   // a served get = a reuse
+		set( k, v ) {
+			if ( !meta.has(k) ) meta.set(k, { uses: 0, addedAt: clock, lastUsed: clock });
+			clock++;
+			inner.set(k, v);
+			if ( autoEvict ) evict();
+			return store;
+		},
+		delete( k ) { meta.delete(k); return inner.delete(k); },
+		get size() { return meta.size; },
+
+		/** run eviction on demand → { evicted:[keys] }. */
+		evict,
+		/** the compass readout — size, reuse split, running reuse rate, eviction tally, per-entry usage. */
+		usage() {
+			let reused = 0, dead = 0;
+			const byKey = [];
+			for ( const [k, m] of meta ) { if ( m.uses > 0 ) reused++; else dead++; byKey.push({ key: k, uses: m.uses, idle: clock - m.lastUsed, age: clock - m.addedAt }); }
+			byKey.sort(( a, b ) => b.uses - a.uses );
+			return { size: meta.size, reused, deadWeight: dead, reuseRate: meta.size ? reused / meta.size : 0, evicted: Object.assign({}, evicted), byKey };
+		},
+		/** the underlying meta (advanced hosts / debugging). */
+		meta
+	};
+	return store;
+}
+
+module.exports = { createRetentionStore };