skynet-graph 1.2.0

package/lib/providers/borderline.js

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * borderline — the BORDERLINE-ONLY LLM gate (G-1 rung 2; the "ask the librarian" LAST resort). The library-science
+ * dispatch pattern (owner) + wiseways.me's production shape: the deterministic barrier (`canonicalize.js`, exact members
+ * + curated synonym ring) resolves ~everything; a small model is consulted ONLY for the thin residual band — a surface
+ * in NEITHER the enum members NOR the ring — and even then it may only PROPOSE, never author.
+ *
+ * SOUNDNESS (the load-bearing discipline — why this does not reopen the false-merge the barrier guards):
+ *   • OUTSIDE the barrier. `canonValue` stays a pure, deterministic, confluent lookup. This gate runs only AFTER it MISSES.
+ *   • RE-CANONICALIZED. The model's answer is snapped back through the SAME spec (`canonValue`) — a hallucinated or
+ *     free-text answer becomes a member or a miss; the model can NEVER put raw prose on a dependency edge (fuzzy recall,
+ *     EXACT truth). Constrained decoding (`enumGbnf`) makes the answer a valid member/`none` by construction.
+ *   • PROVISIONAL. A borderline resolution is a GUESS on out-of-vocabulary. It is returned `via:'llm-borderline',
+ *     provisional:true` — best-effort for THIS run's dispatch, but treated like a CanonMiss for MEMOIZATION (never mint a
+ *     reusable digest → never CACHE a borderline merge). So an un-validated guess can serve one dispatch but can never
+ *     become a cached false-merge.
+ *   • PROPOSE-ONLY (LILO/AutoDoc). It also returns a `proposal:{alias,member}` — a candidate SYNONYM-RING entry for
+ *     human/gate validation. Admitted proposals grow the ring, which is deterministic + confluent (validated by
+ *     `validate.js`'s critical-pair check), so the exogenous vocabulary CONVERGES and the model fires ever less.
+ *
+ *   const { makeLocalAsk } = require('skynet-graph/lib/providers/llm-local');
+ *   const snap = makeBorderlineSnap({ ask: makeLocalAsk({ modelPath, gbnf: null }) });  // a small local model suffices
+ *   const r = await snap('catastrophic', { enum: ['low','high'], synonyms: { high: ['severe'] } });
+ *   // r = { value:'high', via:'llm-borderline', provisional:true, proposal:{ alias:'catastrophic', member:'high' } }
+ */
+var canonicalize = require('./canonicalize');
+
+// A GBNF grammar restricting the model's reply to a bare enum member or "none" (constrained decoding = the answer is a
+// valid member by construction). Members are emitted as quoted GBNF string literals. Pass as `makeLocalAsk({ gbnf })`.
+function enumGbnf( spec ) {
+	var members = (spec && spec.enum) || [];
+	var alts = members.concat(['none']).map(function ( m ) { return JSON.stringify(String(m)); });
+	return 'root ::= ' + alts.join(' | ');
+}
+
+// Extract the chosen member from a model reply, THROUGH the barrier (so the ring + normalization apply). Tries the whole
+// reply first (a constrained/one-word answer), then a token scan (robust to a free-text answer). Returns the member or null.
+function pickMember( answer, spec ) {
+	var whole = canonicalize.canonValue(String(answer == null ? '' : answer).trim(), spec);
+	if ( !whole.miss ) return whole.value;
+	var toks = String(answer == null ? '' : answer).toLowerCase().split(/[^a-z0-9_-]+/);
+	for ( var i = 0; i < toks.length; i++ ) {
+		if ( !toks[i] ) continue;
+		var c = canonicalize.canonValue(toks[i], spec);
+		if ( !c.miss ) return c.value;
+	}
+	return null;                                                     // "none" / unresolvable → stays a miss
+}
+
+var DEFAULT_SYS = 'You map a term to the single closest label from a fixed list, or "none" if it fits none. Reply with only the label.';
+function defaultPrompt( raw, members ) {
+	return 'Labels: ' + members.join(', ') + ', none.\nWhich single label best matches the term "' + String(raw) + '"? Reply with only the label.';
+}
+
+/**
+ * Build a borderline snapper over an `ask` backend (e.g. `makeLocalAsk(...)` — a SMALL local model is enough).
+ * @param opts.ask     async ({system,user,maxTokens,temperature,grammar}) -> string (the model seam; the ONLY coupling).
+ * @param opts.system  optional system prompt override.
+ * @param opts.prompt  optional (raw, members) -> user-prompt override.
+ * @param opts.constrain  opt-in: request CONSTRAINED decoding — pass `grammar:{gbnf:enumGbnf(spec)}` per call so the reply
+ *                        is a valid member or "none" BY CONSTRUCTION (a backend that understands `grammar`, e.g.
+ *                        `makeLocalAsk`, applies it; others ignore it). DEFAULT off = free-text + `pickMember` re-canon:
+ *                        the signature-stability screen found constrained decoding a semantic-consistency HAZARD on a small
+ *                        model, so grammar is FORMAT-INSURANCE, not the default. (The Park/GAD distortion is muted here —
+ *                        a single-enum-token reply has no multi-token future to renormalize.)
+ * @returns async snap(raw, spec) -> { value, miss?, via?, provisional?, proposal? }
+ *          If the deterministic barrier already resolves `raw` (member or ring), returns THAT (the model is NOT called).
+ *          On a genuine miss, consults the model, re-canonicalizes, and returns a PROVISIONAL member (+ a ring proposal)
+ *          or the original miss (→ the host's existing CanonMiss escalation). Never mutates the spec/ring.
+ */
+function makeBorderlineSnap( opts ) {
+	opts = opts || {};
+	var ask = opts.ask;
+	if ( typeof ask !== 'function' ) throw new Error('makeBorderlineSnap: opts.ask (a model backend) is required');
+	var system = opts.system || DEFAULT_SYS;
+	var mkPrompt = opts.prompt || defaultPrompt;
+	var constrain = opts.constrain;                                  // opt-in: per-call constrained decoding (format-insurance)
+
+	return async function snap( raw, spec ) {
+		spec = spec || {};
+		var det = canonicalize.canonValue(raw, spec);
+		if ( !det.miss ) return det;                                 // the deterministic barrier resolved it → NEVER call the model
+		if ( !spec.enum || raw == null || String(raw).trim() === '' ) return det;   // nothing to disambiguate
+
+		var req = { system: system, user: mkPrompt(raw, spec.enum), maxTokens: 16, temperature: 0 };
+		if ( constrain ) req.grammar = { gbnf: enumGbnf(spec) };     // per-call grammar (tracks THIS spec; un-bakeable at construction)
+		var answer = await ask(req);
+		var member = pickMember(answer, spec);                      // re-canonicalized through the SAME spec (defense in depth)
+		if ( member == null ) return det;                           // model said none / unresolvable → stays a miss (escalate as today)
+
+		return {
+			value: member, via: 'llm-borderline', provisional: true,   // best-effort for THIS run; treat like CanonMiss for memo
+			proposal: { alias: String(raw), member: member },          // a candidate ring entry for human/gate validation (propose-only)
+		};
+	};
+}
+
+/**
+ * Batch helper: canonicalize a raw reply against a facts schema (the deterministic barrier), then run the borderline gate
+ * on the MISSES only. Returns the same shape as `canonFacts` plus `borderline` (the provisional snaps) and `proposals`
+ * (candidate ring entries). The still-unresolved keys remain in `misses` (→ the host's CanonMiss escalation). `provisional`
+ * keys carry a member value for dispatch but MUST be treated as un-cacheable (no reusable digest) by the caller.
+ * @param snap  a `makeBorderlineSnap(...)` snapper.
+ */
+async function borderlineFacts( raw, factsSchema, snap ) {
+	raw = raw || {};
+	var base = canonicalize.canonFacts(raw, factsSchema);
+	var facts = Object.assign({}, base.facts), misses = [], borderline = [], proposals = [];
+	for ( var i = 0; i < base.misses.length; i++ ) {
+		var key = base.misses[i], spec = (factsSchema || {})[key] || {};
+		var src = spec.from != null ? spec.from : key;
+		var r = await snap(raw[src], spec);
+		if ( r && r.provisional && !r.miss ) {
+			facts[key] = r.value; borderline.push({ key: key, raw: raw[src], member: r.value });
+			if ( r.proposal ) proposals.push(Object.assign({ key: key }, r.proposal));
+		} else {
+			misses.push(key);                                       // still out-of-vocab → the existing fail-closed escalation
+		}
+	}
+	return { facts: facts, misses: misses, synonyms: base.synonyms, borderline: borderline, proposals: proposals };
+}
+
+module.exports = { makeBorderlineSnap: makeBorderlineSnap, borderlineFacts: borderlineFacts, enumGbnf: enumGbnf, pickMember: pickMember };

package/lib/providers/cache.js

@@ -0,0 +1,226 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * DERIVATION CACHE — an ADDITIVE, opt-in way to use the engine that benefits from the rest (it changes
+ * NOTHING in the core or in any grammar). It is a content-addressed memo over a PROVIDER: a provider's
+ * mutation template is keyed on the CANONICAL JUSTIFICATION of the cast, so a retract→re-derive cycle
+ * (finding #22 re-RUNS the provider — a fresh, expensive LLM call) becomes a hash lookup, and the SAME
+ * typed sub-problem flowing through the SAME method (a second instance) replays instead of re-calling.
+ *
+ * Soundness (study `doc/WIP/studies/2026-06-27-method-instance-workflow-cache-control.md` §2): a cached
+ * template stored under `(C, d)` may be REPLAYED iff `digest(canonical-justification) = d`; the fixpoint is
+ * then identical on all TRACKED facts (prose is untracked, no gate reads it). The cache's trust surface ⊆
+ * the engine's EXISTING incrementality contract (the skip-on-already-cast of #22 already assumes tracked
+ * facts are a stable function of the justification), so it adds ZERO new unsoundness. It is the "good" dual
+ * of the nogood cache (`learn-nogood.js`), and the fast/episodic half of CLS whose slow half is
+ * `crystallize.js` — a hot key auto-nominates its chain for crystallization (wire `stats`/`onHot`).
+ *
+ * Discipline (the blocking points the study flags):
+ *  - the KEY must capture everything the provider READS. Only the provider knows that, so the key fn is
+ *    supplied per provider (default = the concept's memo-surface projection, sound when the provider reads
+ *    only its gate facts). A cross-object provider (reads endpoint states, etc.) supplies a key fn that
+ *    digests those reads — see `keyFromScope`.
+ *  - a key fn returning `null` (a `CanonMiss`, an unkeyable/exploratory cast) BYPASSES the cache (fail-open
+ *    to a fresh call — never a wrong replay).
+ *  - the key is namespaced by concept name + an optional method/lib VERSION token (B8): a method edit must
+ *    not serve a stale template to a new-version instance. Pass `version()` (e.g. a concept-lib digest).
+ */
+const { digest } = require('./canonicalize.js');
+
+function clone( x ) { return x == null ? x : JSON.parse(JSON.stringify(x)); }
+
+/**
+ * @param opts.store    a Map-like (has/get/set/delete/size) — default a bounded in-memory LRU-ish Map
+ * @param opts.max      max entries before oldest-eviction (default 5000)
+ * @param opts.version  () => string — a method/concept-lib version token folded into every key (B8)
+ * @param opts.onHit    (key, concept) => void   (e.g. bump a crystallization counter)
+ * @param opts.onMiss   (key, concept) => void   — a cold (uncached) derivation; symmetric to onHit (hot-spot tally)
+ * @param opts.canonMiss (tpl, concept) => bool  — treat a result as un-cacheable (default: a `<name>CanonMiss` flag)
+ */
+function createProviderCache( opts ) {
+	opts = opts || {};
+	const store = opts.store || new Map();
+	const max = opts.max || 5000;
+	const version = opts.version || (() => '');
+	const canonMiss = opts.canonMiss || defaultCanonMiss;
+	// FIDELITY-GATED REPLAY (opt-in; default = exact-key hit/miss, regression-clean). Per-key the cache learns how
+	// reliably the canonical key predicts the provider's verdict: a few WARMUP hits are VERIFIED (re-derive + compare
+	// to the cached template) to build a reproduce-rate; thereafter a high-rate key REPLAYS (0 calls) but a low-rate
+	// key — a LOSSY canonicalization that drops a decision-relevant fact — ESCALATES (always re-derives, never serves
+	// a stale entry). This is the continuous form of the K1 cliff (the "cost gradient, not cliff" / micro-task floor),
+	// borrowed from Proxy-KD's per-sample fidelity weight w(x,y) (arXiv:2401.07013 v2, principle 4 of the 2026-06-28 study).
+	//   opts.fidelity = { threshold=0.8, warmup=3, equals?(a,b) }   (omit → fidelity gating OFF)
+	const fidelity = opts.fidelity || null;
+	const fidThreshold = fidelity && fidelity.threshold != null ? fidelity.threshold : 0.8;
+	const fidWarmup = fidelity && fidelity.warmup != null ? fidelity.warmup : 3;
+	const tplEquals = ( fidelity && fidelity.equals ) || (( a, b ) => digest(a) === digest(b));
+	const fidStore = new Map();   // key -> { ok, total }
+	// SINGLE-FLIGHT (in-flight dedup) — default ON, opt-out via opts.singleflight === false. The engine casts
+	// unstable objects as a CONCURRENT pool (taskflow async pool in `lib/graph/tasks/`), so N same-key derivations
+	// can be in flight at once. The cache only `set`s AFTER a provider resolves, so without coalescing each of the
+	// N fires the provider (a race → redundant work, NO amortization; correctness is unaffected — same key, same
+	// answer). Coalescing concurrent same-key misses onto ONE provider run makes amortization robust to the
+	// engine's native concurrency, not just to a serialized/streaming execution model. (Transparent to SYNC
+	// providers: the first call resolves + stores before the second starts, so there is never an in-flight window.)
+	const singleflight = opts.singleflight !== false;
+	const inflight = new Map();    // key -> [ wake-thunk ]   (waiters re-run the lookup once the originator resolves)
+	const stats = { hits: 0, misses: 0, bypass: 0, stores: 0, calls: 0, verified: 0, escalated: 0, coalesced: 0 };
+
+	function fullKey( concept, sub ) { return concept._name + '
' + version() + '
' + sub; }
+
+	function evict() { if ( store.size > max ) { const k = store.keys().next().value; store.delete(k); } }
+
+	/**
+	 * Wrap a provider fn `(graph, concept, scope, argz, cb)` with content-addressed caching.
+	 * @param fn     the provider to memoize
+	 * @param keyFn  (graph, concept, scope, argz) => canonical-input (object|string) | null
+	 *               returns null to BYPASS (CanonMiss / exploratory / unkeyable). Default = memo-surface.
+	 * @param transform optional `{ onStore(tpl, info), onReplay(tpl, info) }` — a GENERIC store/replay
+	 *               rewrite (info = {graph,concept,scope,argz}). The cache itself stays grammar-agnostic;
+	 *               the F6 abstractivation (`authoring/abstract.js#methodTransform`) supplies these to
+	 *               PARAMETERIZE a structural template on store and BIND it to the new call site on replay,
+	 *               so a structural decision transfers across related-but-different problems (finding #30).
+	 *               onStore returning null = DON'T store (not transfer-safe); onReplay returning null =
+	 *               BYPASS to a fresh call (a frontier ref couldn't be re-bound) — never a wrong replay.
+	 */
+	function wrap( fn, keyFn, transform ) {
+		keyFn = keyFn || defaultKeyFn;
+		const onStore = transform && transform.onStore, onReplay = transform && transform.onReplay;
+		const wrapped = function ( graph, concept, scope, argz, cb ) {
+			stats.calls++;
+			// an explicitly-exploratory cast (wants a fresh draw) bypasses.
+			if ( scope && scope._ && scope._.explore ) { stats.bypass++; return fn(graph, concept, scope, argz, cb); }
+			let sub;
+			try { sub = keyFn(graph, concept, scope, argz); } catch ( e ) { sub = null; }
+			if ( sub == null ) { stats.bypass++; return fn(graph, concept, scope, argz, cb); }
+			const key = fullKey(concept, typeof sub === 'string' ? sub : digest(sub));
+			const info = { graph: graph, concept: concept, scope: scope, argz: argz };
+			if ( store.has(key) ) {
+				let hit = clone(store.get(key));
+				if ( onReplay ) { hit = onReplay(hit, info); if ( hit == null ) { stats.bypass++; return fn(graph, concept, scope, argz, cb); } }
+				if ( fidelity ) {
+					const fs = fidStore.get(key) || { ok: 0, total: 0 };
+					const established = fs.total >= fidWarmup;
+					const rate = fs.total ? fs.ok / fs.total : 1;
+					if ( established && rate < fidThreshold ) {                 // LOSSY key → escalate (never serve stale)
+						stats.escalated++; return fn(graph, concept, scope, argz, cb);
+					}
+					if ( !established ) {                                      // WARMUP/VERIFY → re-derive, compare, serve fresh
+						stats.verified++;
+						return fn(graph, concept, scope, argz, function ( err, tpl ) {
+							if ( !err && tpl != null ) { fs.total++; if ( tplEquals(tpl, store.get(key)) ) fs.ok++; fidStore.set(key, fs); }
+							cb(err, tpl);
+						});
+					}
+				}
+				stats.hits++; opts.onHit && opts.onHit(key, concept); return cb(null, hit);
+			}
+			// SINGLE-FLIGHT: coalesce concurrent same-key MISSES onto ONE provider run. A waiter re-runs the
+			// lookup once the originator resolves — a cacheable result → it then HITS the store/replay (with its
+			// OWN onReplay+fidelity, so a transform-wrap waiter still rebinds to its call site); an uncacheable
+			// CanonMiss (not stored) → it re-derives, exactly as without single-flight (no new unsoundness).
+			if ( singleflight ) {
+				if ( inflight.has(key) ) { stats.coalesced++; inflight.get(key).push(function () { wrapped(graph, concept, scope, argz, cb); }); return; }
+				inflight.set(key, []);
+			}
+			stats.misses++;
+			opts.onMiss && opts.onMiss(key, concept);   // symmetric to onHit: a cold (uncached) derivation — the per-concept hot-spot tally reads this + onHit + `fid`
+			fn(graph, concept, scope, argz, function ( err, tpl ) {
+				if ( !err && tpl != null && !canonMiss(tpl, concept) ) {
+					let toStore = tpl;
+					if ( onStore ) toStore = onStore(tpl, info);   // null = not transfer-safe → skip storing
+					if ( toStore != null ) { store.set(key, clone(toStore)); stats.stores++; evict(); }
+				}
+				cb(err, tpl);                                       // the COLD call returns its own ground template, unperturbed
+				if ( singleflight ) {
+					const waiters = inflight.get(key) || [];
+					inflight.delete(key);
+					for ( let i = 0 ; i < waiters.length ; i++ ) waiters[i]();   // wake waiters: each re-runs the lookup
+				}
+			});
+		};
+		return wrapped;
+	}
+
+	/**
+	 * Wrap a whole provider FRAGMENT `{Ns: {fn,...}}` — apply a per-fn key map (or the default to all).
+	 * @param fragment  { Ns: { fn: providerFn } }
+	 * @param keyMap    { "Ns::fn": keyFn }     (a fn absent from the map uses the default memo-surface key)
+	 * @param transformMap { "Ns::fn": {onStore,onReplay} }  (optional per-fn store/replay transform; see `wrap`)
+	 */
+	function wrapFragment( fragment, keyMap, transformMap ) {
+		keyMap = keyMap || {}; transformMap = transformMap || {};
+		const out = {};
+		for ( const ns in fragment ) {
+			out[ns] = {};
+			for ( const fn in fragment[ns] ) {
+				const k = keyMap[ns + '::' + fn];
+				out[ns][fn] = (k === false) ? fragment[ns][fn] : wrap(fragment[ns][fn], k || undefined, transformMap[ns + '::' + fn]);
+			}
+		}
+		return out;
+	}
+
+	// default key: the concept's MEMO SURFACE projected off the cast object (sound when the provider reads
+	// only its own gate facts). Falls back to bypass if the surface is empty/unknowable.
+	function defaultKeyFn( graph, concept, scope ) {
+		let keys = [];
+		try { keys = require('../authoring/memo-stability.js').memoSurfaceKeys(graph, concept._name) || []; } catch ( e ) { keys = []; }
+		const flat = keys.filter(( k ) => k.indexOf(':') < 0);   // skip cross-object walks (the provider may read further — bypass unless a custom key is given)
+		if ( !flat.length || flat.length !== keys.length ) return null;
+		const f = scope._, proj = {};
+		for ( const k of flat ) proj[k] = f[k];
+		return proj;
+	}
+
+	return { wrap, wrapFragment, stats, store, clear: () => store.clear(), size: () => store.size, key: fullKey, fid: fidStore };
+}
+
+// a result is un-cacheable if it carries a CanonMiss signal (the K1 fail-closed marker).
+function defaultCanonMiss( tpl, concept ) {
+	const arr = Array.isArray(tpl) ? tpl : [tpl];
+	return arr.some(( t ) => t && typeof t === 'object' && Object.keys(t).some(( k ) => /CanonMiss$/.test(k) && t[k]));
+}
+
+/**
+ * Build a key fn that digests a SCOPE projection (the facts the provider reads on the cast object),
+ * optionally following cross-object refs the provider consumes. Use this for a cross-object provider.
+ * @param spec.facts  string[] of fact keys read off the cast object (scope._)
+ * @param spec.refs   { name: "ref:path" } resolved via scope.getRef (e.g. endpoint states)
+ *                    — returns null (bypass) if any required ref is unresolved.
+ * @param spec.require optional: keys/refs that MUST be present (else bypass)
+ */
+function keyFromScope( spec ) {
+	spec = spec || {};
+	const facts = spec.facts || [], refs = spec.refs || {}, req = spec.require || [];
+	return function ( graph, concept, scope ) {
+		const f = scope._, key = {};
+		for ( const k of facts ) key[k] = f[k];
+		for ( const name in refs ) {
+			let v;
+			try { v = scope.getRef ? scope.getRef(refs[name]) : undefined; } catch ( e ) { v = undefined; }
+			key[name] = (v && v._ !== undefined) ? v._ : v;   // an entity-ref → its facts; a value-ref → the value
+		}
+		for ( const r of req ) if ( key[r] === undefined || key[r] === null ) return null;   // missing input → bypass
+		// Return a STABLE STRING (not the object): a ref can resolve to an OBJECT (entity facts or a whole
+		// bagRef record), and `digest` uses the TOP-LEVEL keys as a JSON.stringify allowlist — it would strip
+		// nested fields, collapsing every record to the same key (a false hit). stableStringify is recursive +
+		// key-sorted, so a different record snapshot yields a different key (C1/B2). wrap() uses a string sub as-is.
+		return stableStringify(key);
+	};
+}
+
+// deterministic, key-sorted, fully-recursive stringify (digest-safe for nested refs).
+function stableStringify( x ) {
+	if ( x === undefined ) return 'null';
+	if ( x === null || typeof x !== 'object' ) return JSON.stringify(x);
+	if ( Array.isArray(x) ) return '[' + x.map(stableStringify).join(',') + ']';
+	return '{' + Object.keys(x).sort().map(( k ) => JSON.stringify(k) + ':' + stableStringify(x[k])).join(',') + '}';
+}
+
+module.exports = { createProviderCache, keyFromScope, defaultCanonMiss, stableStringify };

package/lib/providers/canonicalize.js

@@ -0,0 +1,198 @@
+/*
+ * 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';
+/**
+ * Deterministic fact canonicalization — the implementation half of the typed-fact
+ * spine / canonicalization barrier (doc/MODELISATION.md §4.2, roadmap #1).
+ *
+ * WHY (the existential risk K1 — prose memo-fragmentation): a concept that depends
+ * on variable LLM *prose* re-keys every run (two semantically-equal replies differ
+ * textually) → the memo edge never hits → incrementality evaporates, *worse* than
+ * nil (you still pay the watcher bookkeeping). The fix is a MODELING rule, enforced
+ * here: an `LLM::complete` expert that feeds downstream experts emits a small set of
+ * DISCRETE, TYPED, low-cardinality facts (enums, ids, numbers, booleans, short
+ * canonical strings); only those are written as *tracked* keys; the free text is a
+ * terminal, *untracked* fact. This module snaps the raw LLM values onto that grid.
+ *
+ * HARD RULE — deterministic snapping ONLY, never embedding/similarity matching.
+ * A fuzzy false-hit (GPTCache-style ~33%) graves a WRONG fact that *propagates*
+ * through the cascade-invalidation graph (it triggers/inhibits other concepts).
+ * Strict structured extraction with a closed vocabulary fails closed instead.
+ *
+ * A fact spec is a small object:
+ *   { enum: [...], default? }   snap to a closed vocabulary: exact match, else a
+ *                               whitespace/case-normalized match; a miss -> `default`
+ *                               (or null) and is reported in `misses` (fail-closed,
+ *                               visible — never a silent wrong snap).
+ *   { grain: N }                round a numeric to the nearest multiple of N (the
+ *                               per-EDGE grain declaration: the downstream's needed
+ *                               granularity, not a global setting).
+ *   { type: 'int' | 'number' | 'bool' | 'id' | 'string' }   plain typed coercion.
+ *   { from: 'rawKey' }          read the raw value from a different reply key
+ *                               (combinable with any of the above).
+ *
+ * Everything here is pure and synchronous (independently unit-tested).
+ */
+
+// ---- closed-vocabulary normalization: trim, lowercase, collapse inner whitespace ----
+function normToken( v ) {
+	return String(v == null ? '' : v).trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+// number of decimal places a grain implies (so 0.1 rounds to 1 decimal, 25 -> 0) ----
+function grainDecimals( grain ) {
+	var s = String(grain);
+	var dot = s.indexOf('.');
+	return dot === -1 ? 0 : (s.length - dot - 1);
+}
+
+// ─────────────────────────── the enum normalization map (+ optional CURATED SYNONYM RING) ──────────────────────────
+//
+// A per-spec compiled, CONFLUENT normalization map `σ: Σ*/~normToken ⇀ E` extending the enum map with an optional
+// curated synonym ring (`spec.synonyms = { <member>: [<alias>...] }`). Members are the NORMAL FORMS; each alias is a
+// non-preferred term (ISO 25964-1 §10 USE/UF; SKOS altLabel→prefLabel). Keyed POST-`normToken`, so it is a partial
+// function on the normalization quotient → **confluent by construction** (Church-Rosser: normToken is idempotent, one
+// normal form per class), GIVEN the two critical-pair conditions checked here at COMPILE (a violation THROWS):
+//   • SINGLE-VALUED — no alias maps to two members;   • DISJOINT — no alias `normToken`-collides a member (or a
+//   different member's alias).  These are the ground-TRS critical pairs (Knuth-Bendix 1970).
+// This is a DETERMINISTIC, closed-domain, author-time LOOKUP — a bigger table, categorically NOT an embedding/similarity
+// oracle (which is non-deterministic, non-confluent, open-domain, runtime — the ~33% GPTCache false-hit). So it stays
+// INSIDE the barrier's HARD RULE ("no non-deterministic open-domain runtime similarity"), it does not weaken it.
+// REGIME (the honest ceiling — signature-stability screen): a strong closed-vocab PROMPT already makes the model emit
+// the MEMBER directly, so a ring is REDUNDANT for model-sourced facts. Ring the EXOGENOUS vocabulary you are forced to
+// ingest (human free-text, legacy CSV/DB, weak/non-LLM upstreams, cross-system status strings) — finite, domain-stable,
+// so the ring CONVERGES (not a treadmill). The residual (a surface in neither members nor ring) stays a fail-closed
+// CanonMiss → the host-owned escalation; NEVER an inline fuzzy/edit-distance match (that reimports the banned oracle).
+var _enumMaps = new WeakMap();
+function compileEnumMap( spec ) {
+	var cached = _enumMaps.get(spec);
+	if ( cached ) return cached;
+	var map = Object.create(null), origin = Object.create(null);   // normToken(term) -> member ; origin ∈ member|alias
+	var vocab = spec.enum || [];
+	for ( var i = 0; i < vocab.length; i++ ) {
+		var m = vocab[i], nk = normToken(m);
+		if ( nk in map && map[nk] !== m ) throw new Error('enum: two members normalize to "' + nk + '" (' + map[nk] + ' vs ' + m + ')');
+		map[nk] = m; origin[nk] = 'member';
+	}
+	var syn = spec.synonyms || null;
+	if ( syn ) {
+		for ( var member in syn ) {
+			if ( vocab.indexOf(member) < 0 ) throw new Error('synonyms: ring key "' + member + '" is not an enum member');   // malformed → fail-closed
+			var aliases = syn[member] || [];
+			for ( var a = 0; a < aliases.length; a++ ) {
+				var na = normToken(aliases[a]);
+				if ( na in map ) {
+					if ( map[na] !== member )                                   // critical pair: alias collides a member / another ring's member
+						throw new Error('synonyms: "' + aliases[a] + '" → "' + member + '" collides with "' + map[na] + '" (' + origin[na] + ') — not single-valued/disjoint');
+					// else a harmless duplicate (same member) → skip
+				} else { map[na] = member; origin[na] = 'alias'; }
+			}
+		}
+	}
+	var out = { map: map, origin: origin };
+	_enumMaps.set(spec, out);
+	return out;
+}
+
+/**
+ * Canonicalize one raw value against one spec.
+ * @returns {{ value: *, miss?: boolean, via?: 'synonym' }}  `miss:true` = out-of-vocabulary / un-coercible (falls back
+ *          to `default`/null). `via:'synonym'` = snapped through a curated ring alias (surfaced for audit/reversibility).
+ */
+function canonValue( raw, spec ) {
+	spec = spec || {};
+
+	// enum: snap to a closed vocabulary (deterministic, fail-closed) via the confluent normalization map ----------
+	if ( spec.enum ) {
+		var comp = compileEnumMap(spec);
+		var nk = normToken(raw);                                     // exact + case/whitespace + curated-ring, one probe
+		if ( nk in comp.map ) return comp.origin[nk] === 'alias' ? { value: comp.map[nk], via: 'synonym' } : { value: comp.map[nk] };
+		return { value: spec.default !== undefined ? spec.default : null, miss: true };
+	}
+
+	// grain: round a numeric to the nearest multiple of N -------------------------
+	if ( spec.grain != null ) {
+		var n = typeof raw === 'number' ? raw : parseFloat(raw);
+		if ( !isFinite(n) ) return { value: spec.default !== undefined ? spec.default : null, miss: true };
+		var snapped = Math.round(n / spec.grain) * spec.grain;
+		return { value: Number(snapped.toFixed(grainDecimals(spec.grain))) };
+	}
+
+	// plain typed coercion --------------------------------------------------------
+	switch ( spec.type ) {
+		case 'int': {
+			var iv = typeof raw === 'number' ? raw : parseFloat(raw);
+			return isFinite(iv) ? { value: Math.round(iv) } : { value: spec.default !== undefined ? spec.default : null, miss: true };
+		}
+		case 'number': {
+			var fv = typeof raw === 'number' ? raw : parseFloat(raw);
+			return isFinite(fv) ? { value: fv } : { value: spec.default !== undefined ? spec.default : null, miss: true };
+		}
+		case 'bool': {
+			if ( typeof raw === 'boolean' ) return { value: raw };
+			var t = normToken(raw);
+			if ( t === 'true' || t === '1' || t === 'yes' || t === 'y' ) return { value: true };
+			if ( t === 'false' || t === '0' || t === 'no' || t === 'n' || t === '' ) return { value: false };
+			return { value: spec.default !== undefined ? spec.default : null, miss: true };
+		}
+		case 'id':
+			return { value: raw == null ? (spec.default !== undefined ? spec.default : null) : String(raw).trim() };
+		case 'string':
+		default:
+			// a SHORT canonical string (whitespace-normalized). Note: a free-text
+			// field is prose, not a fact — keep it out of `facts`/off dependency edges.
+			return { value: raw == null ? (spec.default !== undefined ? spec.default : null) : normTokenPreserveCase(raw) };
+	}
+}
+
+// like normToken but preserves case (short canonical string, not a vocab key) ----
+function normTokenPreserveCase( v ) {
+	return String(v).trim().replace(/\s+/g, ' ');
+}
+
+/**
+ * Canonicalize a raw reply object against a facts schema.
+ * @param raw          the parsed LLM reply (a plain object)
+ * @param factsSchema  { <factKey>: <spec> }
+ * @returns {{ facts: {<factKey>: value}, misses: [<factKey>...] }}
+ *          `facts` holds ONLY the declared keys, canonicalized — the tracked spine.
+ */
+function canonFacts( raw, factsSchema ) {
+	raw = raw || {};
+	var facts = {}, misses = [], synonyms = [];
+	Object.keys(factsSchema || {}).forEach(function ( key ) {
+		var spec = factsSchema[key] || {};
+		var src = spec.from != null ? spec.from : key;
+		var out = canonValue(raw[src], spec);
+		facts[key] = out.value;
+		if ( out.miss ) misses.push(key);
+		if ( out.via === 'synonym' ) synonyms.push({ key: key, raw: raw[src], member: out.value });   // audit trail (reversibility)
+	});
+	return { facts: facts, misses: misses, synonyms: synonyms };
+}
+
+/**
+ * Stable content digest of a canonical fact set — usable as an explicit memo key
+ * so identical projections short-circuit *even across re-prose*. Keys sorted so the
+ * digest is order-independent.
+ */
+function digest( facts ) {
+	return JSON.stringify(facts || {}, Object.keys(facts || {}).sort());
+}
+
+module.exports = { canonValue: canonValue, canonFacts: canonFacts, digest: digest, normToken: normToken, compileEnumMap: compileEnumMap };

package/lib/providers/constat.js

@@ -0,0 +1,107 @@
+/*
+ * 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';
+/**
+ * Typed CONSTAT record (Q6) — promotes memory-on-retraction from an ad-hoc string blob into a
+ * STRUCTURED, queryable, bisectable learning surface, with EXISTING engine machinery (the
+ * `cleaner` hook + `{__push}` + a surviving anchor). Zero core change.
+ *
+ * A constat is what a defeasant concept deposits when it RETRACTS: WHAT fell (`kind`/`claim`),
+ * WHY (`retractedBecause` — the premise), with what SNAPPED certainty (`certaintyBand` — never a
+ * raw float, the barrier), and at which revision (`atRev` — bisectable). The lineage is free:
+ * `graph.getCurrentRevision()` + the concept's `_computeWhy` credit graph join it to the trace.
+ *
+ * Q6 verdict (doc/WIP/plans/2026-06-24-poc-roadmap-learning-tiling.md §4): the log-odds inc/dec
+ * channel already exists (semiring + {__push}+fold + snap-band) — do NOT add a core op; the ONE
+ * real gain is this typed constat record. The certainty is read from a SNAPPED key
+ * (`certaintyBand`/`confBand`), never a raw continuous value (K1).
+ *
+ *   const { createConstat, recordConstat } = require('./constat');
+ *   register(Graph, [ createConstat() ]);                       // wires Constat::record
+ *   // on a defeasant concept:  cleaner:['Constat::record'], constat:{ claimKey:'diagnosis', because:'labVerdict' }
+ */
+
+// The canonical constat shape (a `produces`-style declaration — for docs + author-time checks).
+var CONSTAT_FIELDS = {
+	kind            : { role: 'fact', type: 'id' },     // the concept/claim that retracted
+	claim           : { role: 'fact', type: 'id' },     // the value it had asserted
+	retractedBecause: { role: 'fact', type: 'id' },     // the premise that fell (the defeasance cause)
+	certaintyBand   : { role: 'fact', enum: ['low', 'medium', 'high', 'certain'] },  // SNAPPED, never raw (K1)
+	atRev           : { role: 'fact', type: 'int' },    // the revision — bisectable
+	note            : { role: 'prose' }                  // free text — UNTRACKED, terminal
+};
+
+/**
+ * Build a constat record from the retracting concept + its scope.
+ * @param cfg.claimKey  the fact key holding the asserted value (e.g. 'diagnosis')
+ * @param cfg.because   the premise that fell (e.g. 'labVerdict')
+ * @param cfg.extra     extra fields to merge in (e.g. evidenceRefs)
+ */
+function buildConstat( graph, concept, scope, cfg ) {
+	cfg = cfg || {};
+	var e = (scope && scope._) || {};
+	var rec = {
+		kind            : concept._name,
+		claim           : cfg.claimKey != null && e[cfg.claimKey] != null ? e[cfg.claimKey] : null,
+		retractedBecause: cfg.because != null ? cfg.because : null,
+		// certainty is read from a SNAPPED band key only (barrier); never a raw float
+		certaintyBand   : e.certaintyBand != null ? e.certaintyBand : (e.confBand != null ? e.confBand : null),
+		atRev           : graph.getCurrentRevision()
+	};
+	if ( cfg.extra ) for ( var k in cfg.extra ) rec[k] = cfg.extra[k];
+	return rec;
+}
+
+/**
+ * The `{__push}` mutation fragment a cleaner returns to deposit a constat on a surviving anchor
+ * (race-free append — a shared `lessons` array, not a distinct key).
+ * @param cfg.memId/storeKey  the anchor node + array fact (default 'mem'/'lessons')
+ */
+function recordConstat( graph, concept, scope, cfg ) {
+	cfg = cfg || {};
+	var tpl = { $$_id: cfg.memId || 'mem' };
+	tpl[cfg.storeKey || 'lessons'] = { __push: buildConstat(graph, concept, scope, cfg) };
+	return tpl;
+}
+
+/**
+ * Package the constat cleaner provider (host opt-in, like createNogood / createVerifier).
+ * @returns { Constat: { record } }
+ *
+ * Wiring on a defeasant concept:
+ *   { ..., cleaner:['Constat::record'], constat:{ claimKey:'diagnosis', because:'labVerdict' } }
+ * On uncast, reads the concept's `constat` config (+ any argz) and deposits the typed record.
+ */
+function createConstat() {
+	return {
+		Constat: {
+			record: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({ memId: 'mem', storeKey: 'lessons' },
+					concept._schema && concept._schema.constat, argz && argz[0]);
+				cb(null, recordConstat(graph, concept, scope, cfg));
+			}
+		}
+	};
+}
+
+module.exports = {
+	CONSTAT_FIELDS: CONSTAT_FIELDS,
+	buildConstat  : buildConstat,
+	recordConstat : recordConstat,
+	createConstat : createConstat
+};