skynet-graph 1.2.0

package/lib/authoring/adapt.js

@@ -0,0 +1,393 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * adapt — the adapt-or-forge CONTROLLER: the creative loop's drive (host-side, ZERO-CORE; study
+ * doc/WIP/studies/2026-06-30-creative-loop-two-level-grammar.md, brick C).
+ *
+ * The structuring grammar names a target mechanism; this drives retrieve-or-forge over the concept-DLL library:
+ *   RETRIEVE  dispatch (library.js) → a candidate with a template for THIS signature (K1-sound by construction) → HIT, 0 model calls.
+ *   FORGE     no hit → the model builds the method, REUSING the dispatched neighbours where it can (adapt = structural
+ *             reuse + content forge; forge = fresh — the host's forge labels which) → VERIFIER GATE (it must carry a
+ *             sound contract — the refuse-no-contract gate is HERE, not in crystallizeStructural, which admits a
+ *             contractless method) → index back so the next encounter HITS
+ *             (amortise). The measured master-loop retrieve-or-forge; the verifier is the born-defeasible contract.
+ *
+ * The contract's POST is an OUTPUT invariant (true after the method runs) — so it is NOT a pre-dispatch gate (that is
+ * the app-conditions, refined in dispatch). The gate here is "the forged method comes with a sound post" + an optional
+ * host `verify` hook (run it + `assertPost`); a drift that breaks the post is caught by the runtime monitor (the moat).
+ */
+const { dispatch, indexMethod, dispatchInterface, appConditionsHold, frontierOf } = require('./library.js');
+const { generalizeContent, fillContentHoles, blendAtSegment, combineAtFork, BASE } = require('./abstract.js');
+const { digest } = require('../providers/canonicalize.js');
+const { checkCompose } = require('./contract.js');
+
+const idOf = ( o ) => o && (o.$$_id != null ? o.$$_id : (o.$_id != null ? o.$_id : o._id));
+// the child-segment SLOTS of a parameterized method (base-derived segments — the graftable positions, never the
+// outer `_parent`/frontier). The blend's snapped-separator candidates.
+function segmentSlots( tpl ) {
+	return (Array.isArray(tpl) ? tpl : [tpl]).filter(( o ) => o && o.originNode != null && o.targetNode != null && typeof idOf(o) === 'string' && idOf(o).indexOf(BASE + '_') === 0).map(idOf);
+}
+
+const projectFacts = ( facts, keys ) => { const o = {}; for ( const k of (keys || []) ) if ( facts && k in facts ) o[k] = facts[k]; return o; };
+
+/* ── the antiUnify CONTENT-FORGE adapt operator (study §"conceptual blending"; brick C, the richer adapt). ──
+ * The crude adapt re-forged the whole method (or hard-coded "swap field X"). This DISCOVERS the content holes by
+ * generalizing the neighbour's own templates (Plotkin LGG over its `templatesBySig`), forges ONLY those holes for
+ * the new signature, and reuses the skeleton + structural holes verbatim. Domain-agnostic: the host supplies a
+ * `contentFor(contentVars, scopeFacts) -> { <holePath>: value }` (the model filling exactly the discovered holes),
+ * never the template surgery. */
+
+/** The content holes of a learned method (its `templatesBySig`): { stable, skeleton, contentVars:[{path}] }. */
+function methodContentHoles( neighbour ) {
+	return generalizeContent(Object.values((neighbour && neighbour.templatesBySig) || {}));
+}
+
+/** Build an adapted candidate = the neighbour + a NEW signature template (its skeleton with the forged content
+ *  filled). Pure + sync (the async model call is the caller's, before this). Returns null if a hole went unforged. */
+function buildAdaptedCandidate( neighbour, scopeFacts, skeleton, valuesByPath, signatureKeys ) {
+	const filled = fillContentHoles(skeleton, valuesByPath);
+	if ( !filled ) return null;                                       // a content hole was not forged → refuse (no undefined leaf)
+	const keys = signatureKeys || neighbour.signatureKeys || [];
+	const sig = digest(projectFacts(scopeFacts, keys));
+	const templatesBySig = Object.assign({}, neighbour.templatesBySig, { [sig]: filled });
+	return { candidate: Object.assign({}, neighbour, { templatesBySig }), template: filled, sig };
+}
+
+/** The controller's adapt operator: discover the neighbour's content holes → `contentFor` fills them (the model)
+ *  → build the adapted candidate. Returns null if the holes can't be auto-discovered (need ≥2 differing templates)
+ *  or a hole went unforged → the caller falls back to a fresh forge. `contentFor` is sync here (the controller is
+ *  sync); an async (live) host pre-forges and calls `buildAdaptedCandidate` directly. */
+function antiUnifyAdapt( opts ) {
+	const gen = methodContentHoles(opts.neighbour);
+	if ( !gen.stable || !gen.contentVars.length ) return null;        // no auto-discoverable content holes
+	const vals = opts.contentFor(gen.contentVars, opts.scopeFacts);
+	const built = buildAdaptedCandidate(opts.neighbour, opts.scopeFacts, gen.skeleton, vals, opts.signatureKeys);
+	return built && Object.assign(built, { outcome: 'adapt', contentVars: gen.contentVars });
+}
+
+/* ── CONCEPTUAL BLENDING at the candidate level (Boden COMBINATIONAL creativity; study §"conceptual blending"). ──
+ * Graft a DONOR method's body into a HOST method's segment SLOT → a NEW method candidate that is neither (e.g. a
+ * 1-level decompose host + a decompose donor → a 2-level decompose). The blend's OUTER interface (frontier +
+ * signature) is the HOST's, unchanged — so the blended method dispatches + mounts exactly like the host, but with a
+ * deeper, recombined body. v0 INHERITS the host contract (the donor's writes are a superset; the runtime monitor
+ * `assertPost` catches drift — a COMPOSED contract over both write-sets is the follow-up). Returns null if the slot
+ * is absent / does not blend in every signature class. */
+function blendMethods( hostCand, donorCand, opts ) {
+	opts = opts || {};
+	const donorTpl = Object.values((donorCand && donorCand.templatesBySig) || {})[0];
+	const entries = Object.entries((hostCand && hostCand.templatesBySig) || {});
+	if ( !donorTpl || !entries.length ) return null;
+	const slot = opts.atSegment || segmentSlots(entries[0][1])[0];    // default = the host's first child-segment slot
+	if ( !slot ) return null;                                         // no graftable segment slot
+	const templatesBySig = {};
+	for ( const [sig, tpl] of entries ) { const b = blendAtSegment(tpl, slot, donorTpl); if ( !b ) return null; templatesBySig[sig] = b; }
+	const hid = hostCand.schema && hostCand.schema._id, did = donorCand.schema && donorCand.schema._id;
+	// The graft is CONTRACT-CHECKED at the interface (H2 — `checkCompose` was dead-wired; the compose path used to
+	// blindly union an UNVERIFIED contract that `hasSoundContract` then accepted). checkCompose(host, donor) discharges
+	// the donor's PRE against the host's POST on the shared write→read keys. DEFEASIBLE — "a formal system is a GROUND,
+	// not a ceiling": a provably-`unsound` graft (the donor requires what the host contradicts) is REFUSED; an
+	// under-determined (`escalate`) one is ADMITTED and FLAGGED (`composeVerdict`) so the runtime `assertPost` monitor —
+	// the moat — checks it at mount rather than the synthesis over-refusing what it cannot statically decide.
+	const verdict = checkCompose(hostCand.schema, donorCand.schema).verdict;
+	if ( verdict === 'unsound' ) return null;                         // donor.pre provably contradicts host.post → refuse the graft
+	// the blend's contract is DERIVED (composed) from both parents, not merely inherited — the donor's body adds
+	// writes/posts the host omits (closes the v0 "inherited contract" hole). Conservative union; the interface is now
+	// discharged above (the composed post is still runtime-monitored by `assertPost` for the `escalate` residue).
+	const composed = composeContract(hostCand.schema && hostCand.schema.contract, donorCand.schema && donorCand.schema.contract);
+	const schema = Object.assign({}, hostCand.schema, composed ? { contract: composed } : {});
+	return Object.assign({}, hostCand, { schema, templatesBySig, blendedFrom: [hid, did], blendSlot: slot, contractDerived: !!composed, composeVerdict: verdict });
+}
+
+/* ── BINARY COMBINATION — the SECOND composition operator (sibling to blendMethods). Where a blend NESTS a donor
+ * into a host slot (series → a deeper single query, with an interface obligation the donor.pre ⊨ host.post check
+ * discharges), a combine runs TWO complete methods in PARALLEL from the same origin and joins their results with a
+ * SET OPERATION (∩/∪/−) → a NEW method whose result = op(left,right). This is a SQL set-op query (`A INTERSECT B`):
+ * two INDEPENDENT sub-queries over the same source. Because the branches are independent (no data flows left→right),
+ * there is NO interface to discharge — so no checkCompose (unlike blend); the combined contract is just the derived
+ * UNION of both. Provenance in `combinedFrom`. The combined method's BODY is the LEFT's frontier (origin→target),
+ * but it COVERS the set-op class, not LEFT's operand class — so `opts.outerClass` RE-KEYS it (frontier /
+ * signatureKeys / libraryKey from the class the combine is invoked for) so it dispatches on the set-op signature and
+ * never false-hits a plain operand task (which stays in its own bucket). Without `outerClass` it inherits LEFT's key
+ * (back-compat: the direct-mount path in combine-methods-setop.test.js keys it by hand and never dispatches).
+ * Returns null if either method is empty. 0 model calls (pure structural recombination of two distilled grammars). */
+function combineMethods( leftCand, rightCand, op, outerClass ) {
+	const rEntries = Object.values((rightCand && rightCand.templatesBySig) || {});
+	const lEntries = Object.entries((leftCand && leftCand.templatesBySig) || {});
+	if ( !rEntries.length || !lEntries.length ) return null;
+	const rightTpl = rEntries[0];
+	const templatesBySig = {};
+	for ( const [sig, ltpl] of lEntries ) { const c = combineAtFork(ltpl, rightTpl, op); if ( !c ) return null; templatesBySig[sig] = c; }
+	const lid = leftCand.schema && leftCand.schema._id, rid = rightCand.schema && rightCand.schema._id;
+	const composed = composeContract(leftCand.schema && leftCand.schema.contract, rightCand.schema && rightCand.schema.contract);
+	const schema = Object.assign({}, leftCand.schema, composed ? { contract: composed } : {});
+	const combined = Object.assign({}, leftCand, { schema, templatesBySig, combinedFrom: [lid, rid], setop: op, contractDerived: !!composed });
+	// RE-KEY to the OUTER set-op class (opt-in) — so indexMethod/dispatch bucket the combined method by the set-op
+	// signature, not LEFT's operand class. The stale inherited libraryKey is dropped so keyOf recomputes from the
+	// new frontier+signatureKeys (unless outerClass carries an explicit libraryKey).
+	if ( outerClass ) {
+		if ( outerClass.frontier ) { combined.frontier = outerClass.frontier; schema.frontier = outerClass.frontier; }
+		if ( outerClass.signatureKeys ) combined.signatureKeys = outerClass.signatureKeys.slice();
+		if ( outerClass.libraryKey ) { combined.libraryKey = outerClass.libraryKey; schema.libraryKey = outerClass.libraryKey; }
+		else { delete combined.libraryKey; delete schema.libraryKey; }
+	}
+	return combined;
+}
+
+/** The CANONICAL atom key — `$x==1` ≡ `x==1` ≡ `x == 1` (the Laurie-G3 atom-form fix: synthesizeContract emits
+ *  bare atoms, reviseOnBlame/widenOnVerified emit `$`-prefixed ones; provenance matching must not care). Kept a
+ *  READABLE atom string: leading ref-prefix stripped + whitespace removed — the same surface both the contract
+ *  emitters produce, so a postFrom key stays greppable/debuggable (never an opaque serialization). */
+const canonAtom = ( s ) => String(s).replace(/^\$\$?/, '').replace(/\s+/g, '');
+
+/** Compose two born-defeasible contracts (crystallize.js#synthesizeContract shape) into the blend's contract:
+ *  read/write/pre/post = the de-duplicated UNION; effect = pure iff BOTH pure. Conservative (over-approximates the
+ *  write footprint, conjoins both posts). Returns null only if BOTH are absent.
+ *  H3: the composed contract carries `postFrom` — which PARENT's post contributed each (canonical) post atom
+ *  ('host' | 'donor' | 'both') — the graft-provenance the blame rule needs to avoid corrupting the standalone
+ *  library (a=host, b=donor, matching the blendMethods call). */
+function composeContract( a, b ) {
+	if ( !a && !b ) return null;
+	const postFrom = {};
+	for ( const p of ((a && a.post) || []) ) postFrom[canonAtom(p)] = 'host';
+	for ( const p of ((b && b.post) || []) ) { const k = canonAtom(p); postFrom[k] = postFrom[k] === 'host' ? 'both' : 'donor'; }
+	if ( !a || !b ) return Object.assign({}, a || b, { postFrom });
+	const uniq = ( xs ) => [...new Set(xs)];
+	return {
+		read: uniq([...(a.read || []), ...(b.read || [])]),
+		write: uniq([...(a.write || []), ...(b.write || [])]),
+		pre: uniq([...(a.pre || []), ...(b.pre || [])]),
+		post: uniq([...(a.post || []), ...(b.post || [])]),
+		effect: (a.effect === 'pure' && b.effect === 'pure') ? 'pure' : (a.effect || b.effect || 'pure'),
+		postFrom,
+	};
+}
+
+/** H3 — graft-provenance BLAME (the Laurie-G rule; the naive "carry blendedFrom into reviseOnBlame and blame
+ *  the donor" OVER-PENALIZES a good donor for a bad composition and corrupts the standalone library). Given the
+ *  post atoms `assertPost` reported violated on a mounted COMPOSITE, attribute each to an axis:
+ *    'donor'  the atom is donor-only provenance on a `sound` graft → the donor's OWN post failed where used →
+ *             the fix is revising the DONOR's pre (reviseOnBlame on the donor);
+ *    'host'   symmetric;
+ *    'graft'  provenance 'both' / unknown atom / `composeVerdict === 'escalate'` (the statically-undischarged
+ *             interface — the prime suspect is the graft itself) → revise/retract the COMPOSITE only, parents
+ *             stay intact.
+ *  Overall axis = 'donor' (resp. 'host') iff EVERY failed atom reads donor (resp. host); anything mixed or
+ *  uncertain → 'graft' (conservative: when in doubt, narrow the composite, never a parent).
+ *  @returns { perAtom:[{atom,axis}], axis, host, donor, slot } — host/donor/slot from blendedFrom/blendSlot. */
+function attributeCompositeBlame( opts ) {
+	const composite = (opts && opts.composite) || {};
+	const contract = (composite.schema && composite.schema.contract) || composite.contract || {};
+	const postFrom = contract.postFrom || {};
+	const escalate = composite.composeVerdict === 'escalate';
+	const perAtom = ((opts && opts.failedAtoms) || []).map(( atom ) => {
+		const prov = postFrom[canonAtom(atom)];
+		const axis = escalate ? 'graft' : (prov === 'donor' ? 'donor' : (prov === 'host' ? 'host' : 'graft'));
+		return { atom, axis };
+	});
+	const axes = new Set(perAtom.map(( x ) => x.axis));
+	const axis = (axes.size === 1 && !axes.has('graft')) ? [...axes][0] : 'graft';
+	const bf = composite.blendedFrom || [];
+	return { perAtom, axis, host: bf[0], donor: bf[1], slot: composite.blendSlot };
+}
+
+/** the signature digest a candidate would key its replay on at this site (null if it has no template for it = a miss). */
+function hitTemplate( cand, scopeFacts ) {
+	const sig = digest(projectFacts(scopeFacts, cand.signatureKeys || []));
+	return (cand.templatesBySig || {})[sig] ? sig : null;
+}
+
+const hasSoundContract = ( cand ) => !!(cand && cand.schema && cand.schema.contract);
+
+/**
+ * Drive retrieve-or-forge for a target mechanism at a site.
+ * @param opts.lib/target/scopeFacts  the library + the abstract target FrontierSignature + the call-site facts.
+ * @param opts.forge   (scopeFacts, neighbours) → { candidate, outcome?:'adapt'|'forge', calls?:number } | null
+ *                     the model: builds a new method (may REUSE the dispatched `neighbours` = adapt). Returns null = give up.
+ * @param opts.verify  optional (candidate, scopeFacts) → boolean   a stronger gate than "has a contract" (e.g. run + assertPost).
+ * @param opts.onForge optional (candidate) → void   index the forged method (default: indexMethod into opts.lib).
+ * @param opts.requireContract  default true — refuse a forged method with no sound post (the verifier gate).
+ * @returns { outcome:'hit'|'adapt'|'forge'|'reject', candidate?, sig?, calls, neighbours, reason? }
+ */
+function adaptOrForge( opts ) {
+	const pre = _retrieveOrPrepare(opts);
+	if ( pre.done ) return pre.done;
+	const { neighbours, donors } = pre;
+
+	// ADAPT (antiUnify content-forge — the principled path, built INTO the controller): if a content-forger is given
+	// and the top neighbour has auto-discoverable content holes, forge ONLY those holes + reuse the skeleton + the
+	// structural holes verbatim (the neighbour's contract is inherited). Falls back to `opts.forge` (fresh) otherwise.
+	let f = null;
+	if ( opts.adaptContent && neighbours.length ) {
+		const a = antiUnifyAdapt({ neighbour: neighbours[0], scopeFacts: opts.scopeFacts, signatureKeys: neighbours[0].signatureKeys, contentFor: opts.adaptContent });
+		if ( a && a.candidate ) f = { candidate: a.candidate, outcome: 'adapt', calls: 1 };   // one content-forge model call
+	}
+	// BLEND (B.4 — compositional reuse, Boden combinational; opt-in `opts.blend`): before paying for a fresh
+	// FORGE, GRAFT a donor method into the host neighbour's segment slot — a STRUCTURAL recombination of two
+	// existing methods (0 model calls, contract-checked in blendMethods). If it does not graft (no slot /
+	// provably unsound) it falls through to forge; the blended candidate is then verifier-gated like any forge.
+	if ( !f && opts.blend && neighbours.length ) {
+		const donor = donors[0] || opts.donor;
+		const b = donor && blendMethods(neighbours[0], donor, typeof opts.blend === 'object' ? opts.blend : {});
+		if ( b ) f = { candidate: b, outcome: 'blend', calls: 0 };
+	}
+	// COMBINE (the 2nd composition operator — set-op; opt-in `opts.combine`, sibling to blend): before a fresh FORGE,
+	// if the host resolves this task as a set-op over two library methods, run them in PARALLEL and join with the op
+	// → a NEW method at 0 model calls (combineMethods). The host callback OWNS the decomposition (which two operands +
+	// which op), like target/dispatchFacts; the controller supplies the dispatched lib + facts and re-keys the result
+	// to the set-op class (spec.outerClass, default opts.target) so it never false-hits a plain operand task.
+	if ( !f && opts.combine ) {
+		const spec = opts.combine(opts.scopeFacts, opts.lib, neighbours, donors);
+		const c = spec && spec.left && spec.right && spec.op && combineMethods(spec.left, spec.right, spec.op, spec.outerClass || opts.target);
+		if ( c ) f = { candidate: c, outcome: 'combine', calls: 0 };
+	}
+	// FORGE / ADAPT — the model builds it, reusing the neighbours (+ §6.2 donor skeletons) where it can. Verifier-gated, indexed.
+	if ( !f ) f = opts.forge ? opts.forge(opts.scopeFacts, neighbours, donors) : null;
+	const rej = _rejectForged(opts, f, neighbours);
+	if ( rej ) return rej;
+	if ( opts.verify && !opts.verify(f.candidate, opts.scopeFacts) )
+		return { outcome: 'reject', reason: 'forged method failed the host verifier', calls: f.calls == null ? 1 : f.calls, neighbours };
+	return _acceptForged(opts, f, neighbours);
+}
+
+/**
+ * The ASYNC twin of `adaptOrForge` — the SAME retrieve/adapt/forge ladder and the SAME gates (shared
+ * helpers below, single source), for a LIVE host whose `forge` / `adaptContent` / `verify` are model
+ * calls (async). This is the brick a thin assembly (lib/combos/learning-library.js P3) wires as the
+ * master-loop's FORGE arm — without it, an async forge's Promise would fail `f.candidate` and every
+ * forge would silently `reject` (the sync controller cannot await).
+ * Same params as `adaptOrForge`; `forge`/`adaptContent`/`verify` may return promises.
+ * @returns Promise<{ outcome:'hit'|'adapt'|'forge'|'reject', candidate?, sig?, calls, neighbours, reason? }>
+ */
+async function adaptOrForgeAsync( opts ) {
+	const pre = _retrieveOrPrepare(opts);
+	if ( pre.done ) return pre.done;
+	const { neighbours, donors } = pre;
+
+	// ADAPT — the awaited variant of `antiUnifyAdapt` (its docstring's "an async host pre-forges" path,
+	// packaged): discover the holes, AWAIT the content-forge, rebuild via the same pure builder.
+	let f = null;
+	if ( opts.adaptContent && neighbours.length ) {
+		const gen = methodContentHoles(neighbours[0]);
+		if ( gen.stable && gen.contentVars.length ) {
+			const vals = await opts.adaptContent(gen.contentVars, opts.scopeFacts);
+			const built = vals && buildAdaptedCandidate(neighbours[0], opts.scopeFacts, gen.skeleton, vals, neighbours[0].signatureKeys);
+			if ( built && built.candidate ) f = { candidate: built.candidate, outcome: 'adapt', calls: 1 };
+		}
+	}
+	// BLEND (B.4) — the async twin's compositional-reuse rung (opt-in `opts.blend`): graft a donor into the host
+	// neighbour before a fresh FORGE (0 model calls, contract-checked); the async verifier below gates it.
+	if ( !f && opts.blend && neighbours.length ) {
+		const donor = donors[0] || opts.donor;
+		const b = donor && blendMethods(neighbours[0], donor, typeof opts.blend === 'object' ? opts.blend : {});
+		if ( b ) f = { candidate: b, outcome: 'blend', calls: 0 };
+	}
+	// COMBINE (opt-in `opts.combine`) — the async twin's set-op composition rung (may resolve operands async).
+	if ( !f && opts.combine ) {
+		const spec = await opts.combine(opts.scopeFacts, opts.lib, neighbours, donors);
+		const c = spec && spec.left && spec.right && spec.op && combineMethods(spec.left, spec.right, spec.op, spec.outerClass || opts.target);
+		if ( c ) f = { candidate: c, outcome: 'combine', calls: 0 };
+	}
+	if ( !f ) f = opts.forge ? await opts.forge(opts.scopeFacts, neighbours, donors) : null;
+	const rej = _rejectForged(opts, f, neighbours);
+	if ( rej ) return rej;
+	if ( opts.verify && !(await opts.verify(f.candidate, opts.scopeFacts)) )
+		return { outcome: 'reject', reason: 'forged method failed the host verifier', calls: f.calls == null ? 1 : f.calls, neighbours };
+	return _acceptForged(opts, f, neighbours);
+}
+
+/** RETRIEVE phase, shared by both controllers: dispatch → a template hit is K1-sound by construction
+ *  (0 model calls, `done`); else the neighbours + the §6.2 interface-recall DONOR skeletons (the
+ *  NAC-failing in-bucket methods exact dispatch dropped — skeleton sources ONLY, never replayed:
+ *  `_rejectForged` re-asserts the FORGED method's OWN appConditions; Laurie confront). */
+function _retrieveOrPrepare( opts ) {
+	const r = dispatch(opts.lib, opts.target, opts.scopeFacts);
+	const neighbours = r.candidates.map(( e ) => e.candidate );
+	for ( const cand of neighbours ) {
+		const sig = hitTemplate(cand, opts.scopeFacts);
+		if ( sig ) return { done: { outcome: 'hit', candidate: cand, sig, calls: 0, neighbours } };
+	}
+	const donors = opts.interfaceRecall
+		? dispatchInterface(opts.lib, opts.target, opts.scopeFacts, { k: opts.recallK || 3 }).proposals.map(( p ) => p.candidate)
+		: [];
+	return { neighbours, donors };
+}
+
+/** The forged-method REJECT gates, shared by both controllers (single source — the two paths must never
+ *  disagree): no candidate → reject; no sound contract (unless `requireContract:false`) → reject; under
+ *  interface-recall, the forged method's OWN appConditions must HOLD at the site — a donor replayed
+ *  verbatim (its dropped NAC still failing here) is REJECTED, never mounted (the #29 false-hit;
+ *  `appConditionsHold` = PRESENCE for require, never `satisfies` truthiness). Returns null = pass. */
+function _rejectForged( opts, f, neighbours ) {
+	if ( !f || !f.candidate ) return { outcome: 'reject', reason: 'no forge / forge failed', calls: f && f.calls || 0, neighbours };
+	if ( opts.requireContract !== false && !hasSoundContract(f.candidate) )
+		return { outcome: 'reject', reason: 'forged method has no sound contract (verifier gate)', calls: f.calls == null ? 1 : f.calls, neighbours };
+	if ( opts.interfaceRecall && !appConditionsHold(frontierOf(f.candidate), opts.scopeFacts || {}) )
+		return { outcome: 'reject', reason: 'forged method appConditions fail at the site (donor not replayed)', calls: f.calls == null ? 1 : f.calls, neighbours };
+	return null;
+}
+
+/** Accept a gated forged/adapted method: index it (default into `opts.lib`) + the outcome record. */
+function _acceptForged( opts, f, neighbours ) {
+	(opts.onForge || (( c ) => indexMethod(opts.lib, c)))(f.candidate);
+	const outcome = f.outcome === 'adapt' ? 'adapt' : f.outcome === 'blend' ? 'blend' : f.outcome === 'combine' ? 'combine' : 'forge';
+	return { outcome, candidate: f.candidate, calls: f.calls == null ? 1 : f.calls, neighbours, blendedFrom: f.candidate && f.candidate.blendedFrom, combinedFrom: f.candidate && f.candidate.combinedFrom };
+}
+
+/** The structural DEPTH of a method = the deepest nesting of its created mid nodes (`⟦@base⟧_m0` = 1,
+ *  `⟦@base⟧_a0_m0` = 2, …). The μ-measure the blend search descends on. */
+function methodDepth( cand ) {
+	let max = 0;
+	for ( const tpl of Object.values((cand && cand.templatesBySig) || {}) ) {
+		for ( const o of (Array.isArray(tpl) ? tpl : [tpl]) ) {
+			const id = o && (o.$$_id != null ? o.$$_id : (o.$_id != null ? o.$_id : o._id));
+			if ( typeof id === 'string' && id.indexOf(BASE + '_') === 0 && /_m0$/.test(id) ) {
+				const d = (id.slice(BASE.length).match(/_/g) || []).length;   // underscores in the suffix = nesting level
+				if ( d > max ) max = d;
+			}
+		}
+	}
+	return max;
+}
+
+/* ── the BLEND STRATEGY (the creativity AUTOMATION; study §"well-foundedness"): when no single dispatched method
+ * SATISFIES the goal, BLEND neighbours to DEEPEN — bounded compositional search with a TERMINATION guarantee.
+ * Greedy + μ-descent: host = top neighbour, donor = `opts.donor` (default the top neighbour, i.e. self-deepen);
+ * each blend strictly INCREASES `methodDepth` (the μ-measure), so the loop terminates at `maxDepth` (no `divergent`
+ * runaway — the AO* admissible-heuristic discipline the study demanded). 0 model calls: the deeper method is
+ * SYNTHESIZED from library parts, not forged. A cache cannot (it replays); crystallize cannot without ≥2 traces.
+ * @param opts.lib/target/scopeFacts  as adaptOrForge (the dispatch inputs).
+ * @param opts.satisfies  (candidate, scopeFacts) → bool   the goal test (host runs/mounts, or a template predicate).
+ * @param opts.donor      optional candidate to graft (default = the top dispatched neighbour).
+ * @param opts.maxDepth   the blend-depth cap (default 3) — the well-foundedness bound.
+ * @returns { outcome:'retrieve'|'blend'|'reject', candidate, depth, calls, reason? }
+ */
+function synthesizeByBlend( opts ) {
+	const r = dispatch(opts.lib, opts.target, opts.scopeFacts);
+	const neighbours = r.candidates.map(( e ) => e.candidate );
+	if ( !neighbours.length ) return { outcome: 'reject', reason: 'no neighbour to compose', candidate: null, calls: 0 };
+	let cand = neighbours[0];
+	if ( opts.satisfies(cand, opts.scopeFacts) ) return { outcome: 'retrieve', candidate: cand, depth: methodDepth(cand), calls: 0 };
+	const donor = opts.donor || neighbours[0];
+	const maxDepth = opts.maxDepth || 3;
+	const underscores = ( s ) => (s.match(/_/g) || []).length;
+	let last = methodDepth(cand);
+	for ( let i = 0; i < maxDepth; i++ ) {
+		// graft at the DEEPEST current slot so iterated blends DESCEND (each step deepens that branch by one level).
+		const deepest = segmentSlots(Object.values(cand.templatesBySig)[0]).sort(( a, b ) => underscores(b) - underscores(a))[0];
+		if ( !deepest ) break;
+		const blended = blendMethods(cand, donor, { atSegment: deepest });
+		if ( !blended ) break;                                          // no graftable slot → cannot deepen further
+		const d = methodDepth(blended);
+		if ( d <= last ) break;                                         // μ-descent guard: no strict progress → stop (no spin)
+		last = d; cand = blended;
+		if ( opts.satisfies(cand, opts.scopeFacts) ) return { outcome: 'blend', candidate: cand, depth: d, calls: 0 };
+	}
+	return { outcome: 'reject', reason: 'bounded blend (maxDepth/μ-descent) did not satisfy the goal', candidate: null, depth: last, calls: 0 };
+}
+
+module.exports = { adaptOrForge, adaptOrForgeAsync, hitTemplate, hasSoundContract, antiUnifyAdapt, methodContentHoles, buildAdaptedCandidate, blendMethods, combineMethods, segmentSlots, composeContract, attributeCompositeBlame, synthesizeByBlend, methodDepth, canonAtom };

package/lib/authoring/ancestry.js

@@ -0,0 +1,216 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * ancestry — §6.3(b) the ANCESTRY ORACLE: content→param PROMOTION (host-side, ZERO-CORE; spec §3.2, refined by the
+ * 2026-06-30 Laurie confront). Relative LGG / bounded ij-determinacy (Plotkin 1971; GOLEM, Muggleton-Feng 1990).
+ *
+ * A crystallized method's VARYING content leaf is one of three bins (NEVER dropped — "ignorable" is unsound):
+ *   • BAKE  (baked+keyed) — constant across ALL instances AND digests (`signatureDetermined` is within-digest only;
+ *           `generalizeContent` folds across digests → a within-digest constant could bake a premise-dependent value
+ *           above the memo key). The mount stays gated on a digest hit.
+ *   • PROMOTE (rebound+verified) — the identity FD `value(f)=N(s).g` (or a deterministic field-projection `g.field`)
+ *           holds, g is BELOW the separator horizon (g ∈ Σ_sep), and it SURVIVES a held-out strict-=== check. The leaf
+ *           becomes a frontier ref bound from the ancestor at the call site, with an EXACT relational post `$leaf==$g`.
+ *   • FORGE (forged+verified) — everything else (the always-sound catch-all: the model re-derives, assertPost verifies).
+ *
+ * THE SOUNDNESS SPINE (Laurie confront — the SAME §6.4 hazard): the promote bin is BY CONSTRUCTION the varying-leaf
+ * case, so `crystallize.js#invariantAtom` would give it an over-approximating BAND → a spurious g whose wrong value
+ * lands in the band passes `assertPost` silently. PAC (Džeroski-Muggleton-Russell 1992) does NOT save it (workload
+ * firings are non-iid; the engine deploys under drift). The fix:
+ *   (1) minK floor ≥ 3 (the union-bound over |Σ_sep| is advisory — `opts.minK` raises it; k bounds the in-sample
+ *       false-discovery rate, NOT soundness);
+ *   (2) a MANDATORY held-out (≥1 withheld instance) verified by strict `===` — the negative-based reduction; the only
+ *       in-sample test that kills an in-distribution spurious g;
+ *   (3) the promoted post is the EXACT relation `$leaf==$g`, NOT the band → a future divergence is caught at mount.
+ * Ambiguity (≥2 survivors) → FORGE (the version-space join ⊤ = a fresh variable = forge IS the Plotkin/Mitchell answer).
+ */
+const { REF } = require('./abstract.js');
+
+function canon( x ) {
+	if ( x === undefined ) return 'u';
+	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(',') + '}';
+}
+const eq = ( a, b ) => canon(a) === canon(b);
+
+// the ancestor value a hypothesis reads: identity `N(s).g` or field-projection `N(s).g.field` (the ONLY two φ — a
+// lookup-table φ is a memo, affine/multi-arg fit a free parameter → spurious-rate explosion, deferred).
+function ancestorVal( ancestry, cand ) {
+	const g = (ancestry || {})[cand.g];
+	if ( cand.field == null ) return g;
+	return (g && typeof g === 'object') ? g[cand.field] : undefined;
+}
+
+/**
+ * Decide the bin for ONE content leaf from its per-instance observations `[{ value, ancestry:{factName:value}, digest? }]`.
+ * @param opts.sigmaSep      the separator horizon (decompose.js#separatorGate / bagInterface) — g must be ∈ this.
+ * @param opts.minK          the determinacy floor (≥3; the union-bound over |Σ_sep| is the host's to raise).
+ * @param opts.fieldProjection  allow the `g.field` φ (default false).
+ * @param opts.leafKey       the fact key the leaf writes (for the exact post `$<leafKey>==$<ref>`; default 'leaf').
+ * @returns { bin:'bake'|'promote'|'forge', promotion?, post?, value?, reason, fitCandidates, survivors }
+ */
+function decideLeaf( opts ) {
+	opts = opts || {};
+	const obs = (opts.observations || []).filter(Boolean);
+	const sigma = new Set(opts.sigmaSep || []);
+	const minFit = Math.max(3, opts.minK || 3);
+	const leafKey = opts.leafKey || 'leaf';
+
+	// need ≥ minFit instances to FIT + ≥1 HELD-OUT (the negative-based reduction). Else FORGE (the safe catch-all).
+	if ( obs.length < minFit + 1 ) return { bin: 'forge', reason: 'insufficient-instances (need minK+1; got ' + obs.length + ')', fitCandidates: [], survivors: [] };
+	const fit = obs.slice(0, obs.length - 1), held = obs[obs.length - 1];
+	const vals = fit.map(( o ) => o.value );
+
+	// (4) BAKE — constant across ALL observations (incl. held-out). Cross-digest constancy is the soundness condition.
+	if ( obs.every(( o ) => eq(o.value, obs[0].value)) ) {
+		const digests = new Set(obs.map(( o ) => o.digest).filter(( d ) => d != null));
+		return { bin: 'bake', reason: digests.size > 1 ? 'constant-cross-digest' : 'constant', value: obs[0].value, crossDigest: digests.size > 1, fitCandidates: [], survivors: [] };
+	}
+
+	// the hypothesis space H = { identity g } ∪ { field-projection g.field }, g ∈ Σ_sep (the horizon).
+	const anc0 = fit[0].ancestry || {};
+	const H = [];
+	for ( const g of Object.keys(anc0) ) {
+		if ( !sigma.has(g) ) continue;
+		H.push({ g });
+		if ( opts.fieldProjection && anc0[g] && typeof anc0[g] === 'object' )
+			for ( const field of Object.keys(anc0[g]) ) H.push({ g, field });
+	}
+
+	// fit candidates: the FD holds on EVERY fit instance.
+	const fitCandidates = H.filter(( c ) => fit.every(( o, k ) => o.ancestry && eq(vals[k], ancestorVal(o.ancestry, c))));
+	// survivors: ALSO predict the held-out leaf by strict === (eliminate an in-distribution spurious g).
+	const survivors = [];
+	const seen = new Set();
+	for ( const c of fitCandidates ) {
+		if ( !eq(held.value, ancestorVal(held.ancestry, c)) ) continue;
+		const k = c.g + '|' + (c.field || '');
+		if ( !seen.has(k) ) { seen.add(k); survivors.push(c); }
+	}
+
+	if ( survivors.length === 1 ) {
+		// a colon-free ref name (a colon is the cross-walk syntax → would mis-resolve in `expr.js`/`assertPost`).
+		const c = survivors[0], refName = 'anc_' + c.g + (c.field ? '_' + c.field : '');
+		return { bin: 'promote', promotion: { ref: REF(refName), refName, ancestorFact: c.g, field: c.field || null, leafKey },
+			post: '$' + leafKey + '==$' + refName, fitCandidates, survivors };
+	}
+	return { bin: 'forge', fitCandidates, survivors,
+		reason: survivors.length ? 'ambiguous-version-space-join (' + survivors.length + ' survivors)' : 'no-determinate-ancestor' };
+}
+
+// the leaf's fact key from a generalizeContent path (`[1].state` → `state`; `state` → `state`).
+function leafKeyOf( path ) { const parts = String(path).split('.'); return parts[parts.length - 1].replace(/\[\d+\]/g, '') || 'leaf'; }
+
+// rewrite a generalizeContent skeleton: a promoted `{'§var':p}` hole → its frontier REF; a baked hole → its literal;
+// a forged hole → left as the content hole (the model fills it).
+function rewriteSkeleton( skel, byPath ) {
+	if ( Array.isArray(skel) ) return skel.map(( x ) => rewriteSkeleton(x, byPath));
+	if ( skel && typeof skel === 'object' ) {
+		if ( '§var' in skel && Object.keys(skel).length === 1 ) { const p = skel['§var']; return (p in byPath) ? byPath[p] : skel; }
+		const o = {}; for ( const k in skel ) o[k] = rewriteSkeleton(skel[k], byPath); return o;
+	}
+	return skel;
+}
+
+/**
+ * Batch the promotion over a method's content vars + rewrite the skeleton.
+ * @param opts.skeleton  the `generalizeContent` skeleton (with `{'§var':path}` holes).
+ * @param opts.leaves    [{ path, observations:[{value,ancestry,digest?}] }] — one per content var.
+ * @returns { promoted:[{path,ancestorFact,field,refName}], baked:[path], forged:[path], posts:[atom], bins:{path:bin}, skeleton }
+ */
+function promoteContentVars( opts ) {
+	opts = opts || {};
+	const out = { promoted: [], baked: [], forged: [], posts: [], bins: {} };
+	const byPath = {};
+	for ( const leaf of (opts.leaves || []) ) {
+		const d = decideLeaf({ observations: leaf.observations, sigmaSep: opts.sigmaSep, minK: opts.minK, fieldProjection: opts.fieldProjection, leafKey: leafKeyOf(leaf.path) });
+		out.bins[leaf.path] = d.bin;
+		if ( d.bin === 'promote' ) { out.promoted.push(Object.assign({ path: leaf.path }, d.promotion)); out.posts.push(d.post); byPath[leaf.path] = d.promotion.ref; }
+		else if ( d.bin === 'bake' ) { out.baked.push(leaf.path); byPath[leaf.path] = d.value; }
+		else out.forged.push(leaf.path);
+	}
+	out.skeleton = rewriteSkeleton(opts.skeleton, byPath);
+	return out;
+}
+
+// parse a generalizeContent path (`[1].state`) into navigation tokens; set the value at it (immutably).
+function parsePath( path ) {
+	const toks = [], re = /\[(\d+)\]|\.?([A-Za-z_]\w*)/g; let m;
+	while ( (m = re.exec(path)) ) { if ( m[1] != null ) toks.push({ i: +m[1] }); else if ( m[2] != null ) toks.push({ k: m[2] }); }
+	return toks;
+}
+function setAtPath( tpl, path, value ) {
+	const toks = parsePath(path), clone = JSON.parse(JSON.stringify(tpl));
+	let cur = clone;
+	for ( let i = 0; i < toks.length - 1; i++ ) { const t = toks[i]; cur = t.i != null ? cur[t.i] : cur[t.k]; if ( cur == null ) return clone; }
+	const last = toks[toks.length - 1];
+	if ( last.i != null ) cur[last.i] = value; else cur[last.k] = value;
+	return clone;
+}
+const projectFacts = ( facts, keys ) => { const o = {}; for ( const k of (keys || []) ) if ( facts && k in facts ) o[k] = facts[k]; return o; };
+
+/**
+ * §6.3(b) WIRING — enhance a crystallized candidate with ancestry promotions. A content leaf the ancestry oracle
+ * promotes (`decideLeaf` → promote) becomes a frontier REF bound from the ancestor at the call site; the EXACT post
+ * `$leaf==$g` is added; and (opt-in `dropKeys`) the now-redundant signature key is DROPPED — so when promotion removes
+ * the SOLE differentiator the templates collapse to one and the method GENERALIZES to UNSEEN signature classes (it
+ * rebinds the leaf from the ancestor) instead of bypassing. Sound by the held-out FD + the exact post (the runtime monitor).
+ * @param candidate  a crystallizeStructural candidate `{ schema, providerName, signatureKeys, frontierFields, templatesBySig }`.
+ * @param opts.leaves         [{ path, observations }] — the content leaves + their per-instance (value, ancestry).
+ * @param opts.sigmaSep/minK/fieldProjection  forwarded to `decideLeaf` (the horizon + the determinacy discipline).
+ * @param opts.ancestorField  (g) => the scope field the ancestor fact lives on (default `g` — the cast object's own fact;
+ *                            pass e.g. (g)=>'originNode:'+g for a predecessor cross-walk, which `ctxFromScope` resolves).
+ * @param opts.dropKeys       drop a promoted ancestor from `signatureKeys` (+ collapse templates) when it leaves an
+ *                            empty reduced signature and all rewritten templates coincide (the generalization). Default false.
+ * @returns the ENHANCED candidate (templates rewritten, frontier params + posts added, provider rebuilt) + `promotions`.
+ */
+function enhanceCandidateWithAncestry( candidate, opts ) {
+	opts = opts || {};
+	const { buildStructuralProvider } = require('./crystallize.js');   // lazy (avoid any load-order coupling)
+	const ancestorField = opts.ancestorField || (( g ) => g);
+	const cand = JSON.parse(JSON.stringify({ schema: candidate.schema, signatureKeys: candidate.signatureKeys || [], frontierFields: candidate.frontierFields || {}, templatesBySig: candidate.templatesBySig || {} }));
+
+	const promotions = [];
+	for ( const leaf of (opts.leaves || []) ) {
+		const d = decideLeaf({ observations: leaf.observations, sigmaSep: opts.sigmaSep, minK: opts.minK, fieldProjection: opts.fieldProjection, leafKey: leafKeyOf(leaf.path) });
+		if ( d.bin === 'promote' ) promotions.push({ path: leaf.path, refName: d.promotion.refName, ancestorFact: d.promotion.ancestorFact, field: d.promotion.field, post: d.post });
+	}
+	if ( !promotions.length ) return Object.assign({}, candidate, { promotions: [] });
+
+	// rewrite every template: the promoted leaf → its frontier REF.
+	for ( const sig of Object.keys(cand.templatesBySig) )
+		for ( const pr of promotions ) cand.templatesBySig[sig] = setAtPath(cand.templatesBySig[sig], pr.path, REF(pr.refName));
+
+	// add the frontier params + frontierFields + the EXACT posts; (opt-in) drop the redundant signature key.
+	cand.schema.frontier = cand.schema.frontier || { params: [], appConditions: { require: [], assert: [] } };
+	cand.schema.contract = cand.schema.contract || { read: [], write: [], pre: [], post: [], effect: 'pure' };
+	for ( const pr of promotions ) {
+		const fieldPath = ancestorField(pr.ancestorFact) + (pr.field ? '.' + pr.field : '');
+		cand.schema.frontier.params.push({ name: pr.refName, sort: 'node-ref', role: 'endpoint', field: fieldPath, requiredFacts: [] });
+		cand.frontierFields[pr.refName] = fieldPath;
+		if ( cand.schema.contract.post.indexOf(pr.post) < 0 ) cand.schema.contract.post.push(pr.post);
+		if ( opts.dropKeys ) cand.signatureKeys = cand.signatureKeys.filter(( k ) => k !== pr.ancestorFact);
+	}
+
+	// COLLAPSE: if dropping left an empty reduced signature and all rewritten templates now coincide (the promoted
+	// leaf was the SOLE differentiator), re-key to ONE template under the reduced-signature digest → generalizes.
+	if ( opts.dropKeys && !cand.signatureKeys.length ) {
+		const tpls = Object.values(cand.templatesBySig);
+		const allSame = tpls.every(( t ) => canon(t) === canon(tpls[0]));
+		if ( allSame && tpls.length ) cand.templatesBySig = { [digestOf(projectFacts({}, cand.signatureKeys))]: tpls[0] };
+	}
+
+	const provider = buildStructuralProvider({ cryId: cand.schema._name, frontier: cand.schema.frontier, frontierFields: cand.frontierFields, templatesBySig: cand.templatesBySig, signatureKeys: cand.signatureKeys });
+	return { schema: cand.schema, providerName: candidate.providerName, provider, signatureKeys: cand.signatureKeys, frontierFields: cand.frontierFields, templatesBySig: cand.templatesBySig, promotions };
+}
+
+// the digest the structural provider keys on (must match buildStructuralProvider's `digest(projectFacts(...))`).
+const digestOf = require('../providers/canonicalize.js').digest;
+
+module.exports = { decideLeaf, promoteContentVars, rewriteSkeleton, leafKeyOf, enhanceCandidateWithAncestry, setAtPath };