skynet-graph 1.2.0

package/lib/authoring/negotiate.js

@@ -0,0 +1,100 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * negotiate — THE BOUNDED LLM↔GRAPH DIALOGUE (owner 2026-07-09; ZERO-CORE, host-side). "A thinking mode for a model
+ * that doesn't think": instead of the model reasoning internally (CoT), the GRAPH supplies the reasoning as a
+ * structured pushback. The model PROPOSES a typed answer; the graph GATES it (`assertPost`); on a mismatch the graph
+ * returns the BLAME (why it fails) + the ADMISSIBLE OPTIONS (the domain values that PASS its own gate — enumerated by
+ * testing, not guessed) → serialized into a revision prompt (the §5b LEVER) → the model REVISES → repeat, BOUNDED.
+ *
+ * This turns the one-shot forge (`forge-fallback.js`: propose→gate→refuse) into a NEGOTIATION. It is CEGIS with the
+ * graph as the verifier and the model as the synthesizer, made CONSTRUCTIVE (the verifier enumerates admissible
+ * options) + defeasible + deterministic. Three invariants, all load-bearing:
+ *   • 0-FALSE — a non-gated answer is NEVER returned (`ok` ⇒ the gate passed); converge on a gated one or REFUSE.
+ *   • HONEST REFUSAL — no admissible option ⇒ a typed refusal (`no-admissible-option`); the graph NEVER forces a
+ *     match (forcing would be the graph hallucinating). This is the "…t'es sûr c'est pas une halu?" with no fit.
+ *   • TERMINATION — `maxRounds` bounds the loop (no oscillation), the dialogue-level analog of the apply-cap / G3.
+ *
+ *   const solve = makeNegotiate({ propose, gate: gateFromContract(contract), optionsOf, maxRounds: 4 });
+ *   const { ok, answer, refusal, rounds, trace } = await solve(input, ctx);
+ */
+const { assertPost } = require('./contract.js');
+
+/**
+ * gateFromContract(contract, opts) → gate(candidate) → { ok, blame, violations }
+ * The default graph gate: `assertPost` (P4) against a typed contract. candidate = { summary, footprint }.
+ * @param opts.oracle  a G2 ground-truth probe for an effecting post.
+ */
+function gateFromContract( contract, opts ) {
+	opts = opts || {};
+	return function gate( cand ) {
+		const summary = (cand && cand.summary) || {};
+		const post = assertPost(contract, summary, (cand && cand.footprint) || Object.keys(summary), { oracle: opts.oracle });
+		return { ok: post.ok, blame: post.blame, violations: post.violations };
+	};
+}
+
+/**
+ * admissibleOptions(gate, key, domain) → (candidate) => [values]
+ * THE CONSTRUCTIVE part: the graph enumerates "the other options that would match" by TESTING each domain value for
+ * `key` through its OWN gate — grounded (the gate decides), never a guess. Returns the domain values the gate admits.
+ */
+function admissibleOptions( gate, key, domain ) {
+	return function ( cand ) {
+		const base = (cand && cand.summary) || {};
+		return (domain || []).filter(function ( val ) {
+			const probe = Object.assign({}, cand, { summary: Object.assign({}, base, { [key]: val }) });
+			return gate(probe).ok;
+		});
+	};
+}
+
+/** defaultSerialize — the LEVER: turn the graph's refusal (blame + admissible options) into a revision prompt. */
+function defaultSerialize( blame, options, cand ) {
+	return 'REFUSED (' + ((blame && blame.kind) || 'mismatch') + '): your answer ' + JSON.stringify((cand && cand.summary) || {})
+		+ ' does not match what is established. The ONLY admissible options are: [' + (options || []).join(', ')
+		+ ']. Pick the one that fits; if none genuinely fits, say so rather than guessing.';
+}
+
+/**
+ * makeNegotiate(spec) → async solve(input, ctx) => { ok, answer?, refusal?, rounds, trace, blame? }
+ * @param spec.propose    async (input, { round, feedback, options, prior, ctx }) => candidate|null   the MODEL.
+ *                        round 0 = the initial proposal; round>0 = a revision seeing `feedback` (+ structured `options`).
+ * @param spec.gate       (candidate, ctx) => { ok, blame }   the GRAPH check (default idiom: gateFromContract).
+ * @param spec.optionsOf  (gateResult, candidate, ctx) => [options]   the admissible options (default idiom: admissibleOptions).
+ * @param spec.serializeFeedback (blame, options, candidate) => string   the LEVER (default: defaultSerialize).
+ * @param spec.maxRounds  the dialogue bound (default 4).
+ */
+function makeNegotiate( spec ) {
+	spec = spec || {};
+	if ( typeof spec.propose !== 'function' ) throw new Error('makeNegotiate needs spec.propose(input, ctx) -> candidate');
+	if ( typeof spec.gate !== 'function' ) throw new Error('makeNegotiate needs spec.gate(candidate) -> { ok, blame }');
+	const optionsOf = spec.optionsOf;
+	const serialize = spec.serializeFeedback || defaultSerialize;
+	const maxRounds = spec.maxRounds || 4;
+
+	return async function solve( input, ctx ) {
+		let feedback = null, options = null, prior = null;
+		const trace = [];
+		for ( let round = 0; round < maxRounds; round++ ) {
+			const cand = await spec.propose(input, { round: round, feedback: feedback, options: options, prior: prior, ctx: ctx });
+			if ( cand == null ) { trace.push({ round: round, event: 'no-candidate' }); return { ok: false, refusal: 'no-candidate', rounds: round + 1, trace: trace }; }
+			const g = spec.gate(cand, ctx);
+			trace.push({ round: round, summary: cand.summary, ok: g.ok, blame: g.blame && g.blame.kind });
+			if ( g.ok ) return { ok: true, answer: cand, rounds: round + 1, trace: trace };   // 0-false: only a GATED answer returns ok
+			options = optionsOf ? (optionsOf(g, cand, ctx) || []) : [];
+			if ( !options.length )                                                            // the graph has no match → HONEST refusal (never force one)
+				return { ok: false, refusal: 'no-admissible-option', rounds: round + 1, trace: trace, blame: g.blame };
+			feedback = serialize(g.blame, options, cand);                                     // the graph pushes back (blame + options)
+			prior = cand;
+		}
+		return { ok: false, refusal: 'max-rounds', rounds: maxRounds, trace: trace };          // bounded → terminates
+	};
+}
+
+module.exports = { makeNegotiate, gateFromContract, admissibleOptions, defaultSerialize };

package/lib/authoring/parametric.js

@@ -0,0 +1,139 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * parametric — role-typed SLOTS over an LGG method skeleton: bind, mount fail-closed, and blame per slot.
+ *
+ * The Probe-#1 mechanics promoted to a brick (2026-07-03; three experiment reuses: selftest, live-probe,
+ * live-discover-2). A method crystallized from param-DISJOINT episodes LGGs into a skeleton whose antiUnify
+ * HOLES are exactly the param positions — « sous-qualifié = abstrait = un slot ». This module:
+ *
+ *   - `slotBindings`        reads each content hole's OWNING template object and types it: role =
+ *                           `<stepKind>#<stepIndex>` (the frame's positional role id);
+ *   - `mountParametric`     fills the holes from typed params and mounts in ONE create-mode mutation (the
+ *                           ZERO-FIRE discipline — never re-decompose). Fail-closed at EVERY hole: a missing
+ *                           param → `{ status:'impracticable', hint:[{role,key,stepKind}] }` — the typed hint
+ *                           (« need sort X in role Y »), never a partial mount, never a provider re-fire;
+ *   - `slotPostFrom`        mint per-SLOT post provenance where the atoms are DECLARED (the H3 rule: build
+ *                           provenance where the knowledge exists, never reverse-engineer it at blame time);
+ *   - `attributeSlotBlame`  the blame-gate PRIMARY of restriction learning (Laurie Q2: incompetence noise is
+ *                           one-sided and self-sealing → classic candidate-elimination is UNSOUND; admitting
+ *                           ONLY blame-localized negatives restores the clean rates): a failed post atom maps
+ *                           to a slot iff its provenance names exactly ONE role; anything shared/unknown/mixed
+ *                           → `unlocalized` and the whole failure is INADMISSIBLE as negative evidence — the
+ *                           lab's C-arm (all-failures-negative) measured the price of skipping this gate
+ *                           (monotone self-sealing on rare sorts, never recovered).
+ *
+ * The provenance carrier (`postSlots`) mirrors adapt.js#composeContract's `postFrom` (atom→'host'|'donor'|
+ * 'both') at slot grain (atom→role|'shared'), with the same canonical atom key (adapt.js#canonAtom) so both
+ * provenances survive the `$x==1` ≡ `x == 1` surface variance.
+ */
+
+const { fillContentHoles } = require('./abstract.js');
+const { mountTemplate } = require('./typed-loop.js');
+const { canonAtom } = require('./adapt.js');
+
+/** Locate each content hole's OWNING template object and read its typed role: { path, key, stepKind,
+ *  stepIndex, role } — role = `<stepKind>#<stepIndex>`. `gen` = adapt.js#methodContentHoles output. */
+function slotBindings( gen ) {
+	const slots = [];
+	const walk = ( x, path, owner ) => {
+		if ( Array.isArray(x) ) { x.forEach(( v, i ) => walk(v, path + '[' + i + ']', owner)); return; }
+		if ( x && typeof x === 'object' ) {
+			if ( '§var' in x && Object.keys(x).length === 1 ) {
+				const key = path.split('.').pop().replace(/\[\d+\]/g, '');
+				slots.push({ path: x['§var'], key,
+					stepKind: owner && owner.stepKind, stepIndex: owner && owner.stepIndex,
+					role: (owner && owner.stepKind || '?') + '#' + (owner && owner.stepIndex != null ? owner.stepIndex : '?') });
+				return;
+			}
+			const own = (x.Segment || x.$_id === '_parent') ? x : owner;
+			for ( const k in x ) walk(x[k], path ? path + '.' + k : k, own);
+		}
+	};
+	walk(gen.skeleton, '', null);
+	return slots;
+}
+
+/**
+ * The parametric mount. `paramsByRole` keys: `<role>.<key>` (a slot's hole), or bare `<role>` when the role
+ * carries a single hole. Fail-closed at EVERY hole: missing → `{ status:'impracticable', hint }`, NOTHING
+ * mounted; complete → `{ status:'complete', mutation, filled, values }` for `graph.pushMutation`
+ * (create-mode: task + structure in ONE atomic mutation — the ZERO-FIRE discipline). `values` (path → value)
+ * is the fill-time provenance a per-slot contract minter reads.
+ */
+function mountParametric( gen, slots, site, paramsByRole ) {
+	const values = {}, hint = [];
+	for ( const s of slots ) {
+		const v = paramsByRole && (s.role + '.' + s.key in paramsByRole ? paramsByRole[s.role + '.' + s.key] : paramsByRole[s.role]);
+		if ( v != null && v !== '' ) values[s.path] = v;
+		else hint.push({ role: s.role, key: s.key, stepKind: s.stepKind });
+	}
+	if ( hint.length ) return { status: 'impracticable', hint };
+	const filled = fillContentHoles(gen.skeleton, values);
+	if ( !filled ) return { status: 'impracticable', hint: slots.map(( s ) => ({ role: s.role, key: s.key, stepKind: s.stepKind })) };
+	const mutation = mountTemplate(filled, site);
+	if ( !mutation ) return { status: 'impracticable', hint: [{ role: 'frontier', key: '_id' }] };
+	return { status: 'complete', mutation, filled, values };
+}
+
+/** Mint per-slot post provenance from atoms DECLARED per role: `{ role: [atoms] }` →
+ *  `{ post, postSlots }` — postSlots maps each canonical atom to its role, or 'shared' when two roles claim
+ *  the same atom (the 'both' of postFrom: a shared atom can never localize a failure). */
+function slotPostFrom( atomsByRole ) {
+	const post = [], postSlots = {};
+	for ( const role in (atomsByRole || {}) )
+		for ( const atom of atomsByRole[role] || [] ) {
+			const k = canonAtom(atom);
+			if ( !(k in postSlots) ) { post.push(atom); postSlots[k] = role; }
+			else if ( postSlots[k] !== role ) postSlots[k] = 'shared';
+		}
+	return { post, postSlots };
+}
+
+/** The per-SLOT blame rule (the H3 doctrine at slot grain). Given the post atoms `assertPost` reported
+ *  violated on a parametric mount, attribute each to its provenance role. A failure is ADMISSIBLE as negative
+ *  evidence for a slot iff EVERY failed atom localizes to the SAME single role — anything shared, unknown, or
+ *  spanning roles → `{ admissible:false, role:null }` and the caller DISCARDS it (the blame-gate: an
+ *  unlocalized failure is indistinguishable from model incompetence — Laurie Q2/8a). The same discipline
+ *  extends to causes OUTSIDE the provenance map: when the failing episode carries a co-present UNKNOWN
+ *  cause (e.g. an unresolved OOV token in the resolution path), the caller must treat the failure as
+ *  unlocalized even if the failed atoms map to one role — field-proven by the G4 alias-ring probe, where
+ *  skipping this wrong-blamed (and retracted) a CORRECT learned alias on episodes whose failure was owed
+ *  to vocabulary attrition elsewhere.
+ *  @param opts { contract | postSlots, failedAtoms }
+ *  @returns { perAtom:[{atom, role}], role, admissible } — perAtom role 'unlocalized' when unmapped/shared. */
+function attributeSlotBlame( opts ) {
+	const postSlots = (opts && (opts.postSlots || (opts.contract && opts.contract.postSlots))) || {};
+	const perAtom = ((opts && opts.failedAtoms) || []).map(( atom ) => {
+		const role = postSlots[canonAtom(atom)];
+		return { atom, role: role && role !== 'shared' ? role : 'unlocalized' };
+	});
+	const roles = new Set(perAtom.map(( x ) => x.role ));
+	const admissible = perAtom.length > 0 && roles.size === 1 && !roles.has('unlocalized');
+	return { perAtom, role: admissible ? [...roles][0] : null, admissible };
+}
+
+/** The per-SLOT credit rule — the blame's dual (Laurie 8d: POSITIVE credit to a composite must localize
+ *  like blame or it OVER-GENERALIZES — a success only verifies the slots it actually EXERCISED; crediting an
+ *  unexercised slot lifts its LGG on zero evidence). Asymmetry with blame, deliberate: a verified atom is
+ *  DIRECT evidence for its own role (each localized atom credits its role independently — several roles may
+ *  be credited by one success), whereas a failed atom set is a DISJUNCTION of causes (blame needs unanimity).
+ *  Shared/unknown atoms credit NOTHING (fail-closed).
+ *  @param opts { contract | postSlots, verifiedAtoms }
+ *  @returns { perAtom:[{atom, role}], roles } — roles = the creditable slots, sorted, deduplicated. */
+function attributeSlotCredit( opts ) {
+	const postSlots = (opts && (opts.postSlots || (opts.contract && opts.contract.postSlots))) || {};
+	const perAtom = ((opts && opts.verifiedAtoms) || []).map(( atom ) => {
+		const role = postSlots[canonAtom(atom)];
+		return { atom, role: role && role !== 'shared' ? role : 'unlocalized' };
+	});
+	const roles = [...new Set(perAtom.map(( x ) => x.role ).filter(( r ) => r !== 'unlocalized' ))].sort();
+	return { perAtom, roles };
+}
+
+module.exports = { slotBindings, mountParametric, slotPostFrom, attributeSlotBlame, attributeSlotCredit };

package/lib/authoring/reaggregate.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * reaggregate — DEFEASIBLE RE-AGGREGATION (host-side, ZERO-CORE). U3 / the study's A6-A7 point; closes
+ * finding #31 (the E4 defeasance wedge worked at the BELIEF level — a retracted premise dropped its concept
+ * — but the `{__push}`-aggregated SUMMARY did NOT auto-update, because push is monotonic and a cast rollup
+ * does not re-fire on a value change, #22). So a derived summary stayed STALE after a part retracted.
+ *
+ * THE MECHANISM (proven on the real engine). A part contributes via `{__push}` (race-free fan-in, the
+ * accumulation discipline). On RETRACT, the part's `cleaner` runs a SEQUENCED mutation that (a) filters its
+ * own contribution out of the anchor's list AND (b) re-folds the summary from what remains — in ONE
+ * mutation, so the summary is always consistent with the LIVE cast set without fighting #22. The summary
+ * concept folds on cast (after the parts push, fold-after-quiescence). Net: belief AND summary are both
+ * defeasible → the E4 wedge is end-to-end.
+ *
+ *   const agg = defeasibleAggregate({ anchor: s => s._.partOf, valueKey: 'val', fold: xs => xs.reduce((a,x)=>a+x.val,0) });
+ *   Graph._providers = { A: { part: agg.contribute, unpart: agg.uncontribute, summary: agg.summarize } };
+ *   // Part concept:    { require:[…], ensure:['$srcOk'], provider:['A::part'], cleaner:['A::unpart'] }
+ *   // Summary concept: { require:['Anchor','contributions'], provider:['A::summary'] }
+ */
+
+/**
+ * @param spec.anchor        (scope) => anchorId           where the aggregate lives (required)
+ * @param spec.fold          (contributions[]) => value    the aggregate (required)
+ * @param spec.contribution  (scope) => contributionObj    default { id: scope._._id, val: scope._[valueKey] }
+ * @param spec.same          (contrib, scope) => bool       identify THIS part's contribution; default by `id`
+ * @param spec.valueKey      fact key for the default contribution value (default 'val')
+ * @param spec.contribKey    the anchor list fact (default 'contributions')
+ * @param spec.summaryKey    the anchor summary fact (default 'summary')
+ */
+function defeasibleAggregate( spec ) {
+	spec = spec || {};
+	const anchorOf = spec.anchor || (( s ) => s._.partOf);
+	const fold = spec.fold || (( xs ) => (xs || []).length);
+	const valueKey = spec.valueKey || 'val';
+	const contribKey = spec.contribKey || 'contributions';
+	const summaryKey = spec.summaryKey || 'summary';
+	const contribution = spec.contribution || (( s ) => ({ id: s._._id, val: s._[valueKey] }));
+	const same = spec.same || (( x, s ) => x && x.id === s._._id);
+
+	return {
+		// PART cast: mark cast + push this part's contribution to the anchor (race-free fan-in via {__push}).
+		// If the summary was ALREADY folded once (a later re-add after a drift-recovery — a sequenced,
+		// single-part event, not the initial concurrent fan-in), re-fold inline too, since a cast Summary
+		// concept won't re-fire on the value change (#22). Initial concurrent fan-in (no summary yet) just
+		// pushes; the Summary concept folds the authoritative value after quiescence.
+		contribute: function ( graph, concept, scope, argz, cb ) {
+			const anchorId = anchorOf(scope), anc = graph.getEtty(anchorId);
+			const cur = (anc && anc._[contribKey]) || [];
+			const mine = contribution(scope);
+			const upd = { $$_id: anchorId, [contribKey]: { __push: mine } };
+			if ( anc && anc._[summaryKey] !== undefined ) upd[summaryKey] = fold(cur.concat([mine]));   // re-add → re-fold inline
+			cb(null, [{ $_id: '_parent', [concept._name]: true }, upd]);
+		},
+		// PART cleaner (runs on RETRACT): filter this part's contribution out AND re-fold — one sequenced
+		// mutation, so the summary tracks the live cast set (the defeasible re-aggregation).
+		uncontribute: function ( graph, concept, scope, argz, cb ) {
+			const anchorId = anchorOf(scope);
+			const anc = graph.getEtty(anchorId);
+			const kept = ((anc && anc._[contribKey]) || []).filter(( x ) => !same(x, scope));
+			cb(null, { $$_id: anchorId, [contribKey]: kept, [summaryKey]: fold(kept) });
+		},
+		// SUMMARY cast: fold the live contributions (after the parts have pushed — fold-after-quiescence).
+		summarize: function ( graph, concept, scope, argz, cb ) {
+			cb(null, { $_id: '_parent', [concept._name]: true, [summaryKey]: fold(scope._[contribKey] || []) });
+		}
+	};
+}
+
+module.exports = { defeasibleAggregate };

package/lib/authoring/rebalance.js

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * rebalance — the DEFEASIBLE REBALANCING FIXPOINT (ZERO-CORE, host-side). The R1 "réorganise les feuilles
+ * jusqu'à ce que l'ensemble soit équilibré" operator: a degenerate plan (redundant / over-budget / disordered
+ * leaves) is driven to a BALANCED fixpoint by four rules under a LEXICOGRAPHIC termination measure. Kill-gated
+ * GO on the real bricks (`WIP/experiments/2026-07-07-kg-r1b-fixpoint` — 4 degeneracies recover, measure
+ * monotone, negative-control severed refuses, checkCompose/footprintCycles with teeth).
+ *
+ * THE FOUR RULES (applied E2→E1→E3→E4 each round — see FINDING below):
+ *   E2 scission   — split any over-budget node into within-budget atoms (the typed-loop's job downstream)
+ *   E1 fusion     — collapse leaves with an IDENTICAL fusion key (redundant); distinct keys stay PARALLEL
+ *   E3 reorder    — topo by data-flow (a consumer reads its producers' writes → consumer last);
+ *                   `footprintCycles` rejects an illegal RETRACTABLE cycle → typed refusal, never oscillation
+ *   E4 rewrite    — re-fold a consumer from its LIVE producers (defeasibleAggregate semantics)
+ *
+ * FINDING (kill-gate KG-R1b): apply **E2 BEFORE E1**. E1-before-E2 is UNSOUND — when a bundle splits into
+ * atoms that duplicate existing leaves, E2 re-creates the redundancy E1 just removed, so the lexicographic
+ * measure GROWS mid-round (measured `[1]→[2,0,0,0]→[0]`). Split-then-dedupe restores monotonicity: E1 dedupes
+ * ALL atoms after scission, and fusing identical leaves never creates over-budget. ZERO-CORE (rule ordering).
+ *
+ * TERMINATION: measure = (redundancy, overBudget, inversions, staleness), lexicographic. Each round the tuple
+ * is monotone NON-INCREASING; a `cap` of rounds bounds it and non-convergence → a TYPED refusal (never a
+ * silent wedge). def-of-done: done is decided on the LEDGER (the measure), not a cast (#27/#44); the fusion
+ * key is a recursive stableStringify (#35); a severed/uncovered node is REFUSED, never silently folded.
+ *
+ * The brick is domain-agnostic: the caller supplies a `spec` adapting its plan nodes. `plan-loop.js` wires the
+ * spec to a decomposed report (typed requests, boundedProject digests, the C6 leaf ladder, checkCompose
+ * reassembly). Usable à nu with any plan whose nodes carry a fusion key, an over-budget test, a split, and a
+ * producer/consumer footprint.
+ *
+ *   const { rebalancePlan } = require('skynet-graph/lib/authoring/rebalance');
+ *   const out = rebalancePlan({ order: nodes }, spec);   // → { plan, rounds, converged, monotone, refusal, trace }
+ */
+const { checkCompose, footprintCycles } = require('./contract.js');
+const { stableStringify } = require('../providers/cache.js');
+
+// ── the spec the caller adapts (all optional bar isLeaf/fusionKey/overBudget/split/writes/reads/refold) ──
+// spec.isLeaf(n)      → is this node a produced leaf (vs a consumer/root)?
+// spec.fusionKey(n)   → stable identity for E1 (default: recursive stableStringify of n.request ?? n.contract)
+// spec.overBudget(n)  → does this node exceed the node budget (an E2 target: a bundle or an oversized digest)?
+// spec.split(n)       → [subnode…] within budget (E2). Must return ≥2 atoms with DISTINCT ids.
+// spec.writes(n)      → [key…] this node writes (its figure ids / results)
+// spec.reads(n)       → [key…] this node reads (a consumer reads its producers' writes)
+// spec.refold(root, leaves) → the fresh consumer value from the live producers (E4). MUST be pure (no side
+//                             effects) — the staleness check calls it too. E4 stores the result on `root.value`.
+// spec.contractOf(n)  → { name, contract:{read,write,pre,post,effect} } for checkCompose/footprintCycles
+const CAP_DEFAULT = 8;
+
+function defaultFusionKey( n ) { return stableStringify(n.request !== undefined ? n.request : (n.contract || n.id)); }
+
+// E2 scission — split over-budget nodes into within-budget atoms (before E1, per the finding).
+function E2( plan, spec ) {
+	let fired = false; const out = [];
+	for ( const n of plan.order ) {
+		if ( spec.isLeaf(n) && spec.overBudget(n) ) { const parts = spec.split(n); if ( parts && parts.length ) { fired = true; out.push(...parts); continue; } }
+		out.push(n);
+	}
+	plan.order = out; return fired;
+}
+// E1 fusion — collapse IDENTICAL leaves (redundant). checkCompose guard: identical key ⇒ unifiable; a distinct
+// key is a DIFFERENT method → kept PARALLEL (never over-merged). Severed/refused leaves are never fused.
+function E1( plan, spec ) {
+	const seen = new Set(); let fired = false; const kept = [];
+	for ( const n of plan.order ) {
+		if ( !spec.isLeaf(n) || n.severed || n.refused || spec.overBudget(n) ) { kept.push(n); continue; }
+		const k = spec.fusionKey(n);
+		if ( seen.has(k) ) { fired = true; continue; }
+		seen.add(k); kept.push(n);
+	}
+	plan.order = kept; return fired;
+}
+// E3 reorder — data-flow topo: a consumer reads its producers' writes, so it comes AFTER them. footprintCycles
+// rejects an illegal retractable back-edge (a producer reading a consumer's write) BEFORE reordering.
+function E3( plan, spec ) {
+	if ( spec.contractOf ) {
+		const cyc = footprintCycles(plan.order.map(spec.contractOf).filter(Boolean));
+		if ( cyc.length ) { plan._cycleRejected = cyc; return false; }
+	}
+	const producers = plan.order.filter(( n ) => spec.isLeaf(n) );
+	const consumers = plan.order.filter(( n ) => !spec.isLeaf(n) );
+	const want = producers.concat(consumers);                         // producers before consumers
+	const fired = plan.order.some(( n, i ) => n !== want[i] );
+	plan.order = want; return fired;
+}
+// E4 rewrite — re-fold each consumer from the LIVE producers (defeasibleAggregate semantics). Fires if stale.
+function E4( plan, spec ) {
+	let fired = false;
+	const leaves = plan.order.filter(( n ) => spec.isLeaf(n) );
+	for ( const c of plan.order ) if ( !spec.isLeaf(c) ) {
+		const fresh = spec.refold(c, leaves);
+		if ( c.value !== fresh ) { c.value = fresh; fired = true; }   // c.value is the ledger (NOT spec.valueOf — that inherits Object.prototype.valueOf)
+	}
+	return fired;
+}
+
+// ── the lexicographic termination measure (redundancy, overBudget, inversions, staleness) ──
+function measure( plan, spec ) {
+	const singles = plan.order.filter(( n ) => spec.isLeaf(n) && !n.severed && !n.refused && !spec.overBudget(n) );
+	const keys = singles.map(spec.fusionKey);
+	const redundancy = keys.length - new Set(keys).size;
+	const over = plan.order.filter(( n ) => spec.isLeaf(n) && spec.overBudget(n) ).length;
+	const cIdx = plan.order.findIndex(( n ) => !spec.isLeaf(n) );
+	const inversions = cIdx === -1 ? 0 : plan.order.slice(cIdx + 1).filter(( n ) => spec.isLeaf(n) ).length;
+	let staleness = 0;
+	if ( cIdx !== -1 ) {
+		const leaves = plan.order.filter(( n ) => spec.isLeaf(n) );
+		for ( const c of plan.order ) if ( !spec.isLeaf(c) ) {
+			if ( c.value !== spec.refold(c, leaves) ) { staleness = 1; break; }
+		}
+	}
+	return [redundancy, over, inversions, staleness];
+}
+const lexLE = ( a, b ) => { for ( let i = 0; i < a.length; i++ ) { if ( a[i] < b[i] ) return true; if ( a[i] > b[i] ) return false; } return true; };
+
+/**
+ * rebalancePlan(plan, spec, opts) — drive `plan` to a balanced fixpoint. Returns:
+ *   { plan, rounds, converged, monotone, refusal:null|'CYCLE'|'NONCONVERGENCE', trace:[measure…] }
+ * `refusal` is a TYPED non-null outcome the caller surfaces (never a silent wedge). `monotone:false` flags a
+ * termination-measure violation (a rule grew an earlier measure — a bug to fix, not to accept).
+ */
+function rebalancePlan( plan, spec, opts ) {
+	opts = opts || {};
+	spec = Object.assign({ fusionKey: defaultFusionKey }, spec);
+	const cap = opts.cap || CAP_DEFAULT;
+	const trace = [measure(plan, spec)];
+	let round = 0, monotone = true;
+	for ( ; round < cap; round++ ) {
+		const f2 = E2(plan, spec), f1 = E1(plan, spec), f3 = E3(plan, spec), f4 = E4(plan, spec);
+		if ( plan._cycleRejected ) { round++; break; }               // illegal structure → typed refusal
+		const m = measure(plan, spec), prev = trace[trace.length - 1];
+		if ( !lexLE(m, prev) ) monotone = false;
+		trace.push(m);
+		if ( !f1 && !f2 && !f3 && !f4 ) { round++; break; }          // FIXPOINT
+	}
+	const balanced = !plan._cycleRejected && measure(plan, spec).every(( x ) => x === 0 );
+	const converged = balanced && round <= cap;
+	return { plan, rounds: round, converged, monotone,
+		refusal: plan._cycleRejected ? 'CYCLE' : (!converged ? 'NONCONVERGENCE' : null), trace };
+}
+
+// checkReassembly(consumer, producers, opts) — is folding the producers into the consumer SOUND, and does the
+// consumer read anything NO producer writes (an uncovered claim-of-absence)? Uses the real checkCompose. ──
+function checkReassembly( consumer, producers, spec ) {
+	const cc = producers.map(( p ) => checkCompose(spec.contractOf(p), spec.contractOf(consumer)) );
+	const anyUnsound = cc.some(( r ) => r.verdict === 'unsound' );
+	const written = new Set(producers.flatMap(spec.writes));
+	const uncovered = spec.reads(consumer).filter(( k ) => !written.has(k) );
+	return { sound: !anyUnsound && uncovered.length === 0, anyUnsound, uncovered, perProducer: cc };
+}
+
+module.exports = { rebalancePlan, checkReassembly, measure, E1, E2, E3, E4, defaultFusionKey };

package/lib/authoring/recall.js

@@ -0,0 +1,135 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * recall — FUZZY-RECALL → TYPED-VERIFY retrieval (host-side, ZERO-CORE). U5 / the master-graph study §2.4.
+ *
+ * The derivation cache is an EXACT content-address (a hash hit on the K1 digest): a miss is total, so a
+ * related-but-different problem pays full price even when a verifiable NEAR method exists. U5 adds the
+ * missing arm — a RECALL front-end that PROPOSES close methods, gated by an exact TYPED VERIFY that ADMITS.
+ *
+ * THE CONTRACT (the load-bearing soundness line):
+ *   - RECALL is FUZZY (embedding / similarity over the whole method signature). It may be lossy and may
+ *     surface false neighbours. It only ORDERS + BUDGETS candidates — it NEVER admits.
+ *   - VERIFY is EXACT + TYPED. It gates on the STRUCTURE (the K1-canonical fields that DEFINE the method),
+ *     never on the similarity score. Three verdicts:
+ *       · full    — structure matches AND content matches  → replay at 0 model calls (= the cache hit).
+ *       · partial — structure matches, content differs      → mount the shared skeleton (U1 instantiate),
+ *                                                              RE-FORGE only the differing content holes.
+ *       · reject  — structure mismatch                      → forge fresh. NO false replay, whatever the score.
+ *
+ * So a candidate that is similar by embedding (overlapping CONTENT tokens) but has a DIFFERENT typed
+ * STRUCTURE is high-similarity yet REJECTED — recall's fuzziness can never write an unsound derivation
+ * (the canonicalize.js line; worst case of bad recall = a wasted lookup + a fresh call). The win compounds
+ * with concept-as-graph reuse: more crystallized structural methods → more partial hits → fewer model calls.
+ *
+ *   const idx = createRecallIndex();
+ *   idx.add({ structure:{oKind:'A',tKind:'B'}, content:{mid:'m1'} }, methodA);
+ *   const cands = idx.recall({ structure:{oKind:'A',tKind:'B'}, content:{mid:'m9'} }, 3);  // fuzzy, ranked
+ *   const v = verify(querySig, cands[0].sig);   // { mode:'partial', reForge:['mid'], reuse:['oKind','tKind'] }
+ */
+
+// ---- default embedding: a token multiset over the signature's typed values (deterministic, dep-free) ----
+function defaultEmbed( sig ) {
+	const toks = new Map();
+	const add = ( t ) => toks.set(t, (toks.get(t) || 0) + 1);
+	const walk = ( o ) => {
+		if ( o == null ) return;
+		if ( typeof o !== 'object' ) { add(String(o)); return; }
+		for ( const k of Object.keys(o) ) { add('k:' + k); walk(o[k]); }
+	};
+	walk(sig);
+	return toks;
+}
+
+// cosine over token multisets (the default similarity — pluggable via opts.sim / a real embedder via opts.embed).
+function cosine( a, b ) {
+	let dot = 0, na = 0, nb = 0;
+	for ( const [, v] of a ) na += v * v;
+	for ( const [, v] of b ) nb += v * v;
+	for ( const [t, v] of a ) if ( b.has(t) ) dot += v * b.get(t);
+	return (na && nb) ? dot / Math.sqrt(na * nb) : 0;
+}
+
+function createRecallIndex( opts ) {
+	opts = opts || {};
+	const embed = opts.embed || defaultEmbed;
+	const sim = opts.sim || cosine;
+	const entries = [];
+	return {
+		/** index a method under its typed signature { structure, content }. */
+		add( sig, method ) { entries.push({ sig: sig, method: method, vec: embed(sig) }); return this; },
+		/** FUZZY recall: top-k candidates by similarity over the WHOLE signature. ORDERS only — never admits. */
+		recall( sig, k ) {
+			const v = embed(sig);
+			return entries
+				.map(( e ) => ({ method: e.method, sig: e.sig, score: sim(v, e.vec) }))
+				.sort(( a, b ) => b.score - a.score)
+				.slice(0, k || 3);
+		},
+		/** remove every entry whose signature canonicalizes to `sig` — used on DRIFT (a stale method must not
+		 *  be recalled; a drifted premise means RE-DERIVE, never replay the invalidated method). */
+		remove( sig ) {
+			const c = canon(sig);
+			let n = 0;
+			for ( let i = entries.length - 1; i >= 0; i-- ) if ( canon(entries[i].sig) === c ) { entries.splice(i, 1); n++; }
+			return n;
+		},
+		entries,
+		size() { return entries.length; }
+	};
+}
+
+// stable, key-sorted stringify (digest-safe; used by the exact typed VERIFY).
+function canon( x ) {
+	if ( x === undefined ) return 'null';
+	if ( x === null || typeof x !== 'object' ) return JSON.stringify(x);
+	if ( Array.isArray(x) ) return '[' + x.map(canon).join(',') + ']';
+	return '{' + Object.keys(x).sort().map(( k ) => JSON.stringify(k) + ':' + canon(x[k])).join(',') + '}';
+}
+
+/**
+ * The EXACT TYPED VERIFY gate. Decides reuse on the STRUCTURE (the K1 fields that DEFINE the method),
+ * independent of the recall similarity score.
+ * @param query      { structure, content }   the new problem's typed signature
+ * @param candidate  { structure, content }   a recalled method's signature
+ * @returns { mode:'full'|'partial'|'reject', reuse:[fields], reForge:[fields] }
+ *   - 'reject'  : structure mismatch (or empty shared structure) — forge fresh; no false replay.
+ *   - 'full'    : structure AND content match — replay at 0 calls.
+ *   - 'partial' : structure matches, content differs — mount the skeleton (reuse), re-forge the diff (reForge).
+ */
+function verify( query, candidate ) {
+	const qs = (query && query.structure) || {}, cs = (candidate && candidate.structure) || {};
+	const qStructKeys = Object.keys(qs).sort();
+	// STRUCTURE must match exactly (same typed shape) — the K1 barrier. Any structural difference ⇒ reject.
+	if ( !qStructKeys.length || canon(qs) !== canon(cs) ) return { mode: 'reject', reuse: [], reForge: [] };
+	const qc = (query && query.content) || {}, cc = (candidate && candidate.content) || {};
+	const reForge = [];
+	for ( const k of new Set([...Object.keys(qc), ...Object.keys(cc)]) )
+		if ( canon(qc[k]) !== canon(cc[k]) ) reForge.push(k);
+	return reForge.length
+		? { mode: 'partial', reuse: qStructKeys, reForge: reForge.sort() }   // shared skeleton + re-forge the diff
+		: { mode: 'full', reuse: qStructKeys.concat(Object.keys(qc).sort()), reForge: [] };
+}
+
+/**
+ * Drive recall→verify for a query: recall top-k (fuzzy), then return the FIRST candidate the typed verify
+ * admits (full or partial), preferring 'full'. Returns null (→ forge fresh) if none verifies. The chosen
+ * candidate is NOT necessarily the highest-similarity one — verify, not the score, decides.
+ */
+function recallAndVerify( index, query, k ) {
+	const cands = index.recall(query, k || 3);
+	let partial = null;
+	for ( const c of cands ) {
+		const v = verify(query, c.sig);
+		if ( v.mode === 'full' ) return { method: c.method, sig: c.sig, score: c.score, verdict: v };
+		if ( v.mode === 'partial' && !partial ) partial = { method: c.method, sig: c.sig, score: c.score, verdict: v };
+	}
+	return partial;   // null if every recalled candidate was rejected by the typed verify
+}
+
+module.exports = { createRecallIndex, verify, recallAndVerify, defaultEmbed, cosine };