skynet-graph 1.2.0

package/lib/authoring/abstract.js

@@ -0,0 +1,401 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * abstract — ABSTRACTIVATION of a STRUCTURAL method (host-side, ZERO-CORE). The F6 slice the
+ * decisive-experiment gate green-lit (study `doc/WIP/studies/2026-06-27-concept-as-graph-adaptive-
+ * mount-abstraction.md` §8 / U1; finding #30).
+ *
+ * THE PROBLEM (#30). The derivation cache (`providers/cache.js`) replays a stored mutation TEMPLATE
+ * verbatim. A LEAF template is id-RELATIVE (`$_id:'_parent'`) so a different RECORD of the same canonical
+ * class replays soundly (method-instance.js: cost→0). But a STRUCTURAL template — one that CREATES a
+ * sub-graph (an intermediate node + child segments) — bakes ABSOLUTE object ids at derivation time
+ * (`base+'_m0'`, `originNode:'S'`, where `base = seg._id`). Replaying THAT verbatim in a DIFFERENT problem
+ * injects the wrong id-space → unsound / a crash in `Segment._onOriginChange`. So flat caching transfers
+ * structural decisions only across EXACT-structure repeats (same id-space), never related-but-different
+ * problems. Cross-problem STRUCTURAL transfer needs PARAMETERIZED / relative templates.
+ *
+ * THE FIX (anti-unification + splice-time binding). A structural template is the LEAST GENERAL
+ * GENERALIZATION (Plotkin 1970 LGG) of its ground instances: the differing parts are HOLES, the shared
+ * skeleton is kept. Two kinds of hole:
+ *   - STRUCTURAL holes — created ids derived from the cast object's id (`base+suffix`) and the FRONTIER
+ *     refs the template consumes (the call-site endpoints, e.g. `originNode`/`targetNode`). These are
+ *     bound DETERMINISTICALLY from the new call site at replay → free, sound, no model call.
+ *   - CONTENT holes — the typed payload the model derived (the intermediate state/kind/role). These are
+ *     the CACHED PAYLOAD, replayed verbatim. They are sound to replay IFF the cache KEY is the K1-canonical
+ *     TYPED signature that determines them (the canonicalization barrier) — never raw prose.
+ *
+ * So: `relativize(tpl, ctx)` rewrites a ground structural template into a PARAMETERIZED one (store time);
+ * `instantiate(paramTpl, ctx')` binds the holes to a NEW call site (replay time); `antiUnify(A, B)` checks
+ * that two ground derivations of the same signature generalize to the SAME skeleton (the soundness /
+ * crystallization check — the study's "≥2 ground derivations → one schema"). `methodTransform(spec)`
+ * packages these as the generic `{onStore,onReplay}` hooks that `providers/cache.js#wrap` accepts, so a
+ * STRUCTURAL provider gets cross-problem transfer with no change to the cache or the grammar.
+ *
+ *   const { methodTransform } = require('./abstract');
+ *   const T = methodTransform({ frontier: { origin: 'originNode', target: 'targetNode' } });
+ *   Graph._providers = cache.wrapFragment({ P: { plan } }, { 'P::plan': planSigKey }, { 'P::plan': T });
+ *   //                                      key on the TYPED signature ^^^^^^^^^^     transform ^^^
+ */
+
+// sentinels for the two hole kinds, embedded INSIDE id-valued strings. The ⟦ ⟧ brackets are OUT of the id
+// alphabet ([A-Za-z0-9_-]: shortid + authored ids), so a sentinel can never collide with a real id token —
+// and they are HUMAN-READABLE: these holes appear in mutation templates, so prefer legible over opaque (an
+// opaque/byte sentinel would only be justified for a numeric payload — weights/float vectors — not here).
+const BASE = '⟦@base⟧';                                      // created-id prefix: BASE + suffix  (suffix '' = the base id itself)
+const REF  = ( name ) => '⟦@ref:' + name + '⟧';              // a frontier ref hole, bound to a call-site id
+const REF_RE = /^⟦@ref:(.+)⟧$/;
+
+function isStr( x ) { return typeof x === 'string'; }
+
+/**
+ * Rewrite ONE id-valued string into its parameterized form, given the call-site `ctx`.
+ *   ctx.base        the cast object's id (= scope._._id); created ids are `base` or `base+suffix`.
+ *   ctx.refs        { name: idValue } the frontier ids the template consumes (endpoints, parent, …).
+ * A value that is neither base-derived nor a known frontier ref is left LITERAL (it is content payload).
+ * NB: refs are matched FIRST (exact) so a frontier id is never mistaken for a base-derived id; a frontier
+ * ref never equals `base` (the cast object is not its own endpoint), so the order is unambiguous.
+ */
+function relativizeVal( v, ctx ) {
+	if ( !isStr(v) ) return v;
+	for ( const name in ctx.refs ) if ( ctx.refs[name] === v ) return REF(name);
+	if ( v === ctx.base ) return BASE;
+	if ( ctx.base && v.indexOf(ctx.base + '_') === 0 ) return BASE + v.slice(ctx.base.length);
+	return v;
+}
+
+// the inverse: bind a parameterized id-valued string to a NEW call site `ctx`. Returns `undefined` if a
+// required frontier ref is unbound in the new ctx (caller treats that as a BYPASS — never a wrong replay).
+function instantiateVal( v, ctx, miss ) {
+	if ( !isStr(v) ) return v;
+	const m = REF_RE.exec(v);
+	if ( m ) { const name = m[1]; if ( !(name in ctx.refs) || ctx.refs[name] == null ) { miss.bad = true; return v; } return ctx.refs[name]; }
+	if ( v.indexOf(BASE) === 0 ) return ctx.base + v.slice(BASE.length);
+	return v;
+}
+
+// walk a template (array | object | scalar) applying a per-string-value transform. Object KEYS are
+// structural (`_id`, `$_id`, `originNode`, …), never data ids, so only VALUES are transformed. `'_parent'`
+// (the cast-target alias) is already relative and matches nothing → passes through untouched.
+function mapValues( tpl, fn ) {
+	if ( Array.isArray(tpl) ) return tpl.map(( x ) => mapValues(x, fn));
+	if ( tpl && typeof tpl === 'object' ) {
+		const out = {};
+		for ( const k in tpl ) out[k] = mapValues(tpl[k], fn);
+		return out;
+	}
+	return fn(tpl);
+}
+
+/** Ground structural template + call-site ctx → PARAMETERIZED template (holes for ids/refs). */
+function relativize( tpl, ctx ) {
+	ctx = ctx || {}; ctx.refs = ctx.refs || {};
+	return mapValues(tpl, ( v ) => relativizeVal(v, ctx));
+}
+
+/**
+ * PARAMETERIZED template + a NEW call-site ctx → GROUND template (ids rebased, frontier refs rebound).
+ * Returns `null` if any frontier ref hole is unbound in the new ctx (the caller bypasses to a fresh call).
+ */
+function instantiate( paramTpl, ctx ) {
+	ctx = ctx || {}; ctx.refs = ctx.refs || {};
+	const miss = { bad: false };
+	const out = mapValues(paramTpl, ( v ) => instantiateVal(v, ctx, miss));
+	return miss.bad ? null : out;
+}
+
+/** True iff a template still carries hole sentinels (i.e. it is a parameterized, not-yet-bound form). */
+function hasHoles( tpl ) {
+	let found = false;
+	mapValues(tpl, ( v ) => { if ( isStr(v) && (v.indexOf(BASE) === 0 || REF_RE.test(v)) ) found = true; return v; });
+	return found;
+}
+
+/** Deterministic, key-sorted, recursive stringify (for skeleton equality). */
+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(',') + '}';
+}
+
+/**
+ * Plotkin LGG (1970) over the engine's typed templates — the study's "≥2 ground derivations → one schema"
+ * SOUNDNESS / crystallization check. Relativize TWO ground derivations (each with its own call-site ctx —
+ * so ids/refs already align as STRUCTURAL holes), then compute their least general generalization: where
+ * the two agree, keep the literal; where they DIFFER at a leaf, introduce a CONTENT variable; where the
+ * TREE SHAPE differs (different keys / array length / object-vs-scalar), they do not generalize.
+ *
+ * `stable` = the two are SHAPE-COMPATIBLE (one structural skeleton; all differences are content leaves).
+ * That justifies treating them as ONE parameterized method: the structural holes bind from the call site
+ * (`instantiate`), the content variables are what the cache KEY must determine (the K1 signature — a
+ * content var that is NOT a function of the typed key is a false-hit risk, the canonicalize.js line).
+ * A shape mismatch ⇒ NOT one abstraction (don't crystallize them together).
+ *
+ * @returns { stable, skeleton, contentVars, shapeDiffs }
+ *   skeleton    the LGG: structural holes + `{ '§var': path }` at each content leaf (documentation / gate input)
+ *   contentVars [{ path, a, b }]  the per-instance-varying leaves (cache-key obligations)
+ *   shapeDiffs  [path]            positions where the tree shape itself differs (empty ⇔ stable)
+ */
+function antiUnify( groundA, ctxA, groundB, ctxB ) {
+	const sa = relativize(groundA, ctxA), sb = relativize(groundB, ctxB);
+	const acc = { contentVars: [], shapeDiffs: [] };
+	const skeleton = lgg(sa, sb, '', acc);
+	return { stable: acc.shapeDiffs.length === 0, skeleton: acc.shapeDiffs.length === 0 ? skeleton : null,
+		contentVars: acc.contentVars, shapeDiffs: acc.shapeDiffs };
+}
+
+// least general generalization of two (already structurally-relativized) values.
+function lgg( a, b, path, acc ) {
+	if ( canon(a) === canon(b) ) return a;                          // agree → keep the literal/skeleton
+	const oa = a && typeof a === 'object', ob = b && typeof b === 'object';
+	if ( !oa || !ob || Array.isArray(a) !== Array.isArray(b) ) {    // leaf disagreement OR object-vs-scalar
+		if ( oa || ob ) { acc.shapeDiffs.push(path); return null; } //   shape mismatch (one side has structure)
+		acc.contentVars.push({ path, a, b }); return { '§var': path };  // both scalars, differ → content variable
+	}
+	if ( Array.isArray(a) ) {
+		if ( a.length !== b.length ) { acc.shapeDiffs.push(path); return null; }
+		return a.map(( x, i ) => lgg(x, b[i], path + '[' + i + ']', acc));
+	}
+	const ka = Object.keys(a).sort(), kb = Object.keys(b).sort();
+	if ( canon(ka) !== canon(kb) ) { acc.shapeDiffs.push(path); return null; }   // different field sets → shape mismatch
+	const out = {};
+	for ( const k of ka ) out[k] = lgg(a[k], b[k], path ? path + '.' + k : k, acc);
+	return out;
+}
+
+/**
+ * Read the call-site ctx (base + frontier refs) off a provider `scope`, per a declarative `spec`.
+ *   spec.frontier   { name: factKey | "ref:path" }  — where each frontier id lives on the cast object.
+ *                   A bare factKey reads `scope._[factKey]`; a "a:b" path resolves via `scope.getRef`.
+ *   spec.base       optional fact key for the base id (default the cast object's own `_id`).
+ * Returns null if the base id is unknown (→ the transform bypasses, never an unsound store/replay).
+ */
+function ctxFromScope( scope, spec ) {
+	spec = spec || {};
+	const f = (scope && scope._) || {};
+	const base = spec.base ? f[spec.base] : f._id;
+	if ( base == null ) return null;
+	const refs = {};
+	const frontier = spec.frontier || {};
+	for ( const name in frontier ) {
+		const where = frontier[name];
+		let v;
+		if ( isStr(where) && where.indexOf(':') >= 0 ) {            // a cross-object ref path
+			try { const r = scope.getRef ? scope.getRef(where) : undefined; v = (r && r._ && r._._id !== undefined) ? r._._id : (r && r._id !== undefined ? r._id : r); } catch ( e ) { v = undefined; }
+		} else {
+			v = f[where];
+		}
+		refs[name] = v;
+	}
+	return { base, refs };
+}
+
+/**
+ * Package relativize/instantiate as the generic `{onStore,onReplay}` transform that
+ * `providers/cache.js#wrap(fn, keyFn, transform)` accepts:
+ *   - onStore(groundTpl, {scope})  → PARAMETERIZED form to store (or null = don't store: not transfer-safe).
+ *   - onReplay(paramTpl, {scope})  → GROUND form bound to the new call site (or null = bypass to a fresh call).
+ * The cold call still returns its own ground template unchanged; only the STORED form is parameterized,
+ * and only a HIT is re-bound — so the cold derivation is never perturbed.
+ */
+function methodTransform( spec ) {
+	spec = spec || {};
+	return {
+		onStore: function ( tpl, info ) {
+			const ctx = ctxFromScope(info && info.scope, spec);
+			if ( !ctx ) return null;                                // unknown call site → don't store (no unsound future replay)
+			const param = relativize(tpl, ctx);
+			// only worth storing parameterized if it actually generalized (else it's a flat template under a
+			// shared signature key → would leak on replay). Require at least one hole.
+			return hasHoles(param) ? param : null;
+		},
+		onReplay: function ( paramTpl, info ) {
+			const ctx = ctxFromScope(info && info.scope, spec);
+			if ( !ctx ) return null;                                // unknown call site → bypass (fresh call)
+			return instantiate(paramTpl, ctx);                      // null if a frontier ref is unbound → bypass
+		}
+	};
+}
+
+/**
+ * EMIT-METHOD-AS-SUBGRAPH (study §8 / U1a), built on the ENGINE-NATIVE serializer `Graph#getMutationFromPath`.
+ *
+ * `relativize`/`instantiate` are the domain-agnostic GENERALIZATION of a pattern the engine already proved
+ * in production (the epikeo/aetheris travel-path mounting: `MapPaths` normalizes a discovered sub-graph's
+ * endpoints to the FORMAL ids 'start'/'target' and serializes it into `OpenPaths`; `pushPath`/`MountPaths`
+ * re-mount it, BINDING the formal frontier back to the call site — `tpl[0].originNode = scope._.originNode`,
+ * `relatedTpl.map(m => ({...m, $_id:'$'+m._id}))`). `getMutationFromPath` is the serializer that turns a
+ * graph fragment into a mutation TEMPLATE (bagRef→`$$` refs, strips `_rev`).
+ *
+ * This helper closes the loop: take a DERIVED method's sub-graph (the objects a structural cast created),
+ * serialize it through the engine primitive, and relativize it into a re-mountable PARAMETERIZED method —
+ * so a method is a re-mountable graph (the study's U1a), not only a cached opaque provider output. Bind it
+ * at a new call site with `instantiate(...)` and apply via `graph.pushMutation(bound, targetId, …)`.
+ *
+ * @param graph    the graph holding the derived sub-graph
+ * @param subIds   the ids of the method's emitted objects (the created intermediate nodes + child segments)
+ * @param ctx      { base, refs:{name:idValue} } — the derivation call site (as for `relativize`)
+ * @returns the PARAMETERIZED method template (holes for ids/frontier refs), or null if a sub-id is missing.
+ */
+function emitMethodAsSubgraph( graph, subIds, ctx ) {
+	const path = [];
+	for ( const id of subIds || [] ) {
+		const e = graph.getEtty ? graph.getEtty(id) : (graph._objById && graph._objById[id] && graph._objById[id]._etty);
+		if ( !e || !e._ ) return null;
+		path.push(Object.assign({}, e._));
+	}
+	if ( !path.length ) return null;
+	const tpl = graph.getMutationFromPath ? graph.getMutationFromPath(path, [], null) : path;   // engine-native serialize
+	return relativize(tpl, ctx);
+}
+
+/**
+ * CONTENT-HOLE GENERALIZATION (the adapt operator — "conceptual blending" / Fauconnier-Turner via Plotkin LGG).
+ * Given ≥2 parameterized templates of ONE method (its `templatesBySig` values — same structural skeleton, content
+ * differing per signature class), discover WHICH leaves are CONTENT (vary across the instances) vs the SKELETON
+ * (shared, kept verbatim — both the structural `⟦@…⟧` holes and the agreeing literals). It is `antiUnify` folded
+ * over the set: the union of every pairwise content-var path. The result is a skeleton with a `{'§var': path}`
+ * CONTENT HOLE at each varying leaf — so a controller can forge ONLY those holes for a new signature and reuse the
+ * skeleton, instead of re-forging the whole method (the v0 demo's hard-coded "swap the `state` field" → principled).
+ *
+ * @param templates  array of ≥2 parameterized templates (already relativized — structural holes are literal here).
+ * @returns { stable, skeleton, contentVars:[{path}] }  stable=false if a template's SHAPE differs from the first
+ *          (then it is excluded from the union) or there are <2 templates; contentVars empty ⇒ nothing to forge.
+ */
+function generalizeContent( templates ) {
+	const ts = (templates || []).filter(Boolean);
+	if ( ts.length < 2 ) return { stable: false, skeleton: ts[0] || null, contentVars: [] };
+	const paths = new Set();
+	let stable = true;
+	for ( let i = 1; i < ts.length; i++ ) {
+		const au = antiUnify(ts[0], {}, ts[i], {});   // ctx={} → no further relativization; compare the parameterized forms
+		if ( !au.stable ) { stable = false; continue; }   // a shape-incompatible template can't share this skeleton
+		for ( const cv of au.contentVars ) paths.add(cv.path);
+	}
+	return { stable, skeleton: holePaths(ts[0], paths, ''), contentVars: [...paths].map(( p ) => ({ path: p })) };
+}
+
+// rewrite the leaves at `paths` into `{'§var': path}` content holes; path format MIRRORS lgg's (array `[i]`,
+// object `k` / `parent.k`) so the holes line up with `generalizeContent`'s contentVars.
+function holePaths( tpl, paths, path ) {
+	if ( paths.has(path) ) return { '§var': path };
+	if ( Array.isArray(tpl) ) return tpl.map(( x, i ) => holePaths(x, paths, path + '[' + i + ']'));
+	if ( tpl && typeof tpl === 'object' ) { const o = {}; for ( const k in tpl ) o[k] = holePaths(tpl[k], paths, path ? path + '.' + k : k); return o; }
+	return tpl;
+}
+
+/** Fill a content-hole skeleton (from `generalizeContent`) with forged values keyed by hole path → a parameterized
+ *  template (structural holes still present, to be `instantiate`d at the call site). Returns null if any content
+ *  hole was NOT forged (a partial forge must never silently bake an `undefined` leaf). */
+function fillContentHoles( skel, valuesByPath ) {
+	let missing = false;
+	const walk = ( x ) => {
+		if ( Array.isArray(x) ) return x.map(walk);
+		if ( x && typeof x === 'object' ) {
+			if ( '§var' in x && Object.keys(x).length === 1 ) { const p = x['§var']; if ( !valuesByPath || !(p in valuesByPath) ) { missing = true; return x; } return valuesByPath[p]; }
+			const o = {}; for ( const k in x ) o[k] = walk(x[k]); return o;
+		}
+		return x;
+	};
+	const out = walk(skel);
+	return missing ? null : out;
+}
+
+/**
+ * CONCEPTUAL BLENDING (Boden's COMBINATIONAL creativity / Fauconnier-Turner): graft a DONOR method's body into a
+ * structural SLOT of a HOST method — producing a NEW method that is neither, made by recombining their parts. The
+ * slot is a host SEGMENT hole (the canonical decompose shape origin→mid→target has child-segment slots); the donor
+ * decomposes THAT segment, so the host's edge is replaced by the donor's sub-graph (a deeper, blended method).
+ *
+ * SOUNDNESS (the snapped-separator interface = the study's open frontier, made concrete):
+ *  - INTERFACE: the donor's frontier (its `⟦@ref:…⟧` endpoints) binds to the host slot's endpoints (the segment's
+ *    `originNode`/`targetNode`). v0: a segment slot ↔ a donor whose frontier is {origin,target} (a 2-endpoint method).
+ *  - NO ID COLLISION: the donor is RE-BASED under the host slot's id (`⟦@base⟧_a0` → the donor's `⟦@base⟧`), so its
+ *    created ids nest as `⟦@base⟧_a0_m0` etc. — disjoint from the host's `⟦@base⟧_*` and any sibling slot. The donor's
+ *    own parent element MERGES its decomposition markers onto the host segment (which becomes a decomposed parent).
+ * The result is a parameterized template (the OUTER frontier unchanged) → `instantiate` mounts it at a fresh site.
+ *
+ * @param hostTpl    a parameterized method template (array of mutation objects with `⟦@…⟧` holes).
+ * @param hostSegId  the `$$_id`/`$_id` hole of the host SEGMENT slot to graft into (e.g. `⟦@base⟧_a0`).
+ * @param donorTpl   a parameterized method template whose frontier is {origin,target} (it decomposes a segment).
+ * @returns the blended parameterized template, or null (slot not found / not a segment / nothing to graft).
+ */
+function blendAtSegment( hostTpl, hostSegId, donorTpl ) {
+	const idOf = ( o ) => o && (o.$$_id != null ? o.$$_id : (o.$_id != null ? o.$_id : o._id));
+	const host = (Array.isArray(hostTpl) ? hostTpl : [hostTpl]).slice();
+	const si = host.findIndex(( o ) => idOf(o) === hostSegId );
+	if ( si < 0 ) return null;                                        // no such slot
+	const seg = host[si];
+	if ( seg.originNode == null || seg.targetNode == null ) return null;   // the slot must be a SEGMENT (2-endpoint interface)
+	const refMap = { origin: seg.originNode, target: seg.targetNode };     // donor frontier ← host slot endpoints (the snapped separator)
+	const donor = rebaseDonor(Array.isArray(donorTpl) ? donorTpl : [donorTpl], hostSegId, refMap);
+	const dParent = donor.find(( o ) => idOf(o) === hostSegId ) || {};     // donor's parent re-based onto the slot
+	const dRest   = donor.filter(( o ) => idOf(o) !== hostSegId );         // the donor's body (mid + children), nested under the slot
+	const merged  = Object.assign({}, seg, dParent);                       // the slot keeps its endpoints + gains donor's decomposition markers
+	const out = host.slice(); out[si] = merged;
+	return out.concat(dRest);
+}
+
+/**
+ * BINARY COMBINATION at a FORK — the SECOND composition operator (sibling to blendAtSegment's NESTING). Where a
+ * blend grafts a donor INTO a host slot (series → a deeper single query), a combine runs TWO complete methods in
+ * PARALLEL from the same origin and joins their results at a `combine` node with a set operation (∩/∪/−) → a NEW
+ * method whose result = op(left, right). This is the shape of a SQL set-op query (`A INTERSECT B`): two independent
+ * sub-queries over the same source, combined. Both branches are 2-endpoint methods (origin→target frontier).
+ *
+ * STRUCTURE (a diamond, all under ONE outer parent — no fabricated sub-parents):
+ *   origin →[left body, re-based ⟦@base⟧_L_*]→ ⟦@base⟧_c ←[right body, re-based ⟦@base⟧_R_*]← origin
+ *   ⟦@base⟧_c →[set-op segment ⟦@base⟧_out]→ target
+ * NO ID COLLISION: each branch re-based under a distinct namespace (⟦@base⟧_L / ⟦@base⟧_R); its frontier binds
+ * origin→the outer origin, target→the shared combine node; its parent object is DROPPED and its segments re-parent
+ * to the outer base. The combine node legitimately has two incoming edges (a node may be many segments' target).
+ * @param leftTpl/rightTpl  parameterized 2-endpoint method templates.
+ * @param op                the set operation tag ('intersect' | 'union' | 'except').
+ * @returns the combined parameterized template (OUTER frontier origin→target), or null if a branch is empty.
+ */
+function combineAtFork( leftTpl, rightTpl, op ) {
+	const idOf = ( o ) => o && (o.$$_id != null ? o.$$_id : (o.$_id != null ? o.$_id : o._id));
+	const L = Array.isArray(leftTpl) ? leftTpl : [leftTpl], R = Array.isArray(rightTpl) ? rightTpl : [rightTpl];
+	if ( !L.length || !R.length ) return null;
+	const combineId = BASE + '_c';
+	const refMap = { origin: REF('origin'), target: combineId };            // branch frontier: origin→outer origin, target→combine node
+	// re-base a branch, DROP its parent object, re-parent its segments to the OUTER base.
+	const branch = ( tpl, ns ) => rebaseDonor(tpl, BASE + ns, refMap).filter(( o ) => idOf(o) !== BASE + ns )
+		.map(( o ) => ('parentSeg' in o) ? Object.assign({}, o, { parentSeg: BASE }) : o);
+	const parent = { $$_id: BASE, Combine: true, Combined: true, setop: op };
+	const combineNode = { $$_id: combineId, Node: true, state: 'combine' };
+	const setopSeg = { $$_id: BASE + '_out', Segment: true, originNode: combineId, targetNode: REF('target'), parentSeg: BASE, state: 'setop', setop: op };
+	return [parent].concat(branch(L, '_L'), branch(R, '_R'), [combineNode, setopSeg]);
+}
+
+// re-base a donor template: its `⟦@base⟧` (+ `⟦@base⟧_suffix`) holes nest under `newBase`; its frontier refs are
+// re-bound via `refMap` (donorRefName → the host slot's endpoint value). REF matched FIRST (as in relativizeVal).
+function rebaseDonor( donorTpl, newBase, refMap ) {
+	return mapValues(donorTpl, ( v ) => {
+		if ( !isStr(v) ) return v;
+		const m = REF_RE.exec(v);
+		if ( m ) return (m[1] in refMap) ? refMap[m[1]] : v;          // a frontier hole → the host slot's endpoint
+		if ( v === BASE ) return newBase;                            // the donor base → the slot id
+		if ( v.indexOf(BASE + '_') === 0 ) return newBase + v.slice(BASE.length);   // ⟦@base⟧_m0 → newBase_m0 (nested)
+		return v;
+	});
+}
+
+/** Collect the frontier-ref hole NAMES a parameterized template uses (reuses THIS module's REF_RE, so the
+ *  sentinel format stays in ONE place — callers never re-derive it). Returns a Set of names. */
+function refHolesOf( tpl, out ) {
+	out = out || new Set();
+	mapValues(tpl, function ( v ) { var m = isStr(v) && REF_RE.exec(v); if ( m ) out.add(m[1]); return v; });
+	return out;
+}
+
+module.exports = {
+	relativize, instantiate, antiUnify, hasHoles, methodTransform, ctxFromScope,
+	emitMethodAsSubgraph, refHolesOf, BASE, REF, canon,
+	generalizeContent, fillContentHoles, blendAtSegment, combineAtFork
+};

package/lib/authoring/abstraction.js

@@ -0,0 +1,190 @@
+/*
+ * 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';
+/**
+ * abstraction — the MDL/utility admission gate for "abstract methods" (host-side, ZERO-CORE;
+ * study doc/WIP/studies/2026-06-26-…, promotes experiment F2).
+ *
+ * Hybridizing concepts into a reusable abstract method = inventing a nonterminal for a
+ * recurring sub-derivation. Grammar theory gives ONE admission criterion (Minton speedup-
+ * utility ≡ SEQUITUR rule-utility ≡ smallest-grammar MDL ≡ Lari-Young nonterminal control):
+ * **admit a learned production iff its net utility is positive**. Here, "utility" is measured
+ * empirically on the real engine — an abstract grammar is admitted iff it is
+ *   (a) VALID (passes the author-time validator),
+ *   (b) fixpoint-EQUIVALENT to the chain it replaces (same external facts), and
+ *   (c) net-CHEAPER (fewer cumulative applies — the refactor win).
+ * Keeping the macro *alongside* its constituents (no refactor) costs more applies for the
+ * same result -> a net tax (Minton 1990) -> rejected. This is the offline, author-time form
+ * the adversarial lens endorsed ("library curation with a gate"); it never mints mid-stabilize.
+ *
+ *   const { evaluate } = require('./abstraction');
+ *   const r = await evaluate({ seed, providers, chainTree, abstractTree, equivKeys: ['amplified'] });
+ *   if (r.admit) // adopt abstractTree as the grammar
+ */
+const Graph = require('../graph/index.js');
+const { nextStable } = require('./supervise.js');
+const { validateConceptTree } = require('./validate.js');
+const { forkPlan, bagInterface, conceptCliques } = require('./decompose.js');
+
+const clone = (x) => JSON.parse(JSON.stringify(x));
+
+// Collect the names of concepts that INVOKE a provider — the casts that cost an (LLM-ish) model call.
+// The U4 currency fix: the utility gate must score MODEL CALLS, not all `applies` (a provider-less
+// applyMutations cast is ~free; fusing it away saves nothing — Minton 1990, the utility problem).
+function providerNames( tree, out ) {
+	out = out || new Set();
+	const walk = ( node, isChild ) => {
+		if ( !node || typeof node !== 'object' ) return;
+		const schema = node._schema || node;
+		if ( (isChild || node._name) && node._name && schema.provider ) out.add(node._name);
+		if ( node.childConcepts ) for ( const k of Object.keys(node.childConcepts) ) walk(node.childConcepts[k], true);
+	};
+	walk(tree, false);
+	return out;
+}
+
+// Boot a tree on the seed, count cumulative applies AND estimated model-cost, and collect the values of
+// `equivKeys` per object — the external contract by which two grammars are compared for equivalence.
+async function bootMeasure( tree, seed, providers, opts ) {
+	Graph._providers = Object.assign({}, Graph._providers || {}, providers || {});
+	const provSet = providerNames(tree);
+	// cost currency (U4): opts.cost(name)->estimate, else 1 per provider-bearing cast, 0 for provider-less.
+	const costOf = opts.cost || (( name ) => (provSet.has(name) ? 1 : 0));
+	let applies = 0, cost = 0;
+	const cfg = {
+		label: opts.label || 'abstraction', isMaster: true, autoMount: true,
+		conceptSets: opts.conceptSets || ['common'], bagRefManagers: {}, logLevel: 'error',
+		onConceptApply: function ( rec ) { applies++; cost += (costOf(rec && rec.conceptName) || 0); },
+	};
+	const g = new Graph(clone(seed || { lastRev: 0, nodes: [], segments: [] }), cfg, { common: clone(tree) });
+	await nextStable(g);
+	const keys = opts.equivKeys || [];
+	const facts = {};
+	for ( const id of Object.keys(g._objById || {}) ) {
+		const etty = g._objById[id] && g._objById[id]._etty;
+		const f = etty && etty._;
+		if ( !f ) continue;
+		const proj = {};
+		let has = false;
+		for ( const k of keys ) if ( k in f ) { proj[k] = f[k]; has = true; }
+		if ( has ) facts[id] = proj;
+	}
+	return { applies, cost, facts };
+}
+
+// Σ_sep NON-REGRESSION (the E7 rule, refined by the 2026-06-30 Laurie confront): a created/merged method must not
+// WIDEN the bounded-context HORIZON. The sound object is the bag-intersection MINIMAL-INTERFACE width (`bagInterface`,
+// Robertson-Seymour 1986) — NOT the scalar min-fill treewidth (an uncoupled upper bound → false-admits a real
+// regression) NOR the size-1 articulation `widened` alone (blind to a size-1→size-2 cut). Both are kept as DIAGNOSTICS.
+// FIX (finding): the prior code fed `forkPlan({common: tree})`, which `conceptCliques` does NOT unwrap → 0 cliques →
+// the gate was VACUOUS (`widened` always []). The trees are the bare childConcepts form; feed them DIRECTLY.
+function interfaceRegression( chainTree, abstractTree ) {
+	let before, after;
+	try { before = forkPlan(chainTree); } catch ( e ) { before = null; }
+	try { after = forkPlan(abstractTree); } catch ( e ) { after = null; }
+	const sepB = new Set((before && before.separators) || []);
+	const sepA = (after && after.separators) || [];
+	const widened = sepA.filter(( s ) => !sepB.has(s));     // (diagnostic) size-1 articulation keys the abstraction ADDED
+	const bagB = bagInterface(conceptCliques(chainTree)), bagA = bagInterface(conceptCliques(abstractTree));
+	const mB = bagB.minimalInterface.size, mA = bagA.minimalInterface.size;
+	// the SOUND gate fires only on a genuine CROSS-TILE widening — BOTH sides divisible (a real thin interface exists
+	// on each) and the after's thinnest cut is wider. A fusion that COLLAPSES a chain to a single concept makes the
+	// after INDIVISIBLE (a black box); its internal clique is the UTILITY gate's concern, NOT a bounded-context
+	// regression (the original `interfaceRegression` comment, vindicated). So indivisible-after is never an interface regress.
+	const interfaceRegressed = !bagA.indivisible && !bagB.indivisible && mA > mB;
+	return {
+		separatorsBefore: [...sepB].sort(), separatorsAfter: sepA.slice().sort(), widened,
+		treewidthBefore: bagB.treewidth, treewidthAfter: bagA.treewidth,                 // diagnostic (NOT gated — see confront)
+		minimalInterfaceBefore: bagB.minimalInterface, minimalInterfaceAfter: bagA.minimalInterface,
+		indivisibleBefore: bagB.indivisible, indivisibleAfter: bagA.indivisible,
+		interfaceRegressed,                                                              // the SOUND gate: the cross-tile horizon widened
+		sigmaSepBefore: bagB.sigmaSep, sigmaSepAfter: bagA.sigmaSep
+	};
+}
+
+// Same set of objects, same value for every compared key on each.
+function factsEqual( a, b ) {
+	const ka = Object.keys(a), kb = Object.keys(b);
+	if ( ka.length !== kb.length ) return false;
+	for ( const id of ka ) {
+		if ( !(id in b) ) return false;
+		if ( JSON.stringify(a[id]) !== JSON.stringify(b[id]) ) return false;
+	}
+	return true;
+}
+
+/**
+ * Evaluate whether `abstractTree` should be admitted over `chainTree`.
+ * @param opts.seed/providers      the representative episode to measure on
+ * @param opts.chainTree           the incumbent grammar (the constituents)
+ * @param opts.abstractTree        the candidate grammar (with the abstract method)
+ * @param opts.equivKeys           the external output facts that define equivalence
+ * @param opts.validate            opts forwarded to validateConceptTree (palette, etc.)
+ * @returns {{ valid, errors, equivalent, chainApplies, abstractApplies, gain, admit }}
+ */
+async function evaluate( opts ) {
+	opts = opts || {};
+	const { errors } = validateConceptTree(opts.abstractTree, opts.validate || {});
+	const valid = errors.length === 0;
+	const chain = await bootMeasure(opts.chainTree, opts.seed, opts.providers, Object.assign({ label: 'chain' }, opts));
+	const abstract = await bootMeasure(opts.abstractTree, opts.seed, opts.providers, Object.assign({ label: 'abstract' }, opts));
+	const equivalent = factsEqual(chain.facts, abstract.facts);
+	const gain = chain.applies - abstract.applies;
+	const costGain = chain.cost - abstract.cost;                 // U4: the LLM-cost currency (model calls saved)
+	const iface = interfaceRegression(opts.chainTree, opts.abstractTree);
+	// E7 (refined): the SOUND gate is the bag-intersection minimal-interface non-regression (`interfaceRegressed`);
+	// the size-1 articulation `widened` is kept as an additional necessary check (a new size-1 cut key is a regression
+	// the interface-width can miss when the cut count, not its width, grows). The scalar treewidth is NOT gated.
+	const interfaceOk = !iface.interfaceRegressed && iface.widened.length === 0;
+	// admit on the CORRECT currency (model-cost), equivalence, validity, and no interface regression. `gain`
+	// (applies) stays reported for continuity; a degenerate corpus with no providers falls back to applies.
+	const utility = (chain.cost > 0 || abstract.cost > 0) ? costGain : gain;
+	return {
+		valid, errors,
+		equivalent,
+		chainApplies: chain.applies, abstractApplies: abstract.applies, gain,
+		chainCost: chain.cost, abstractCost: abstract.cost, costGain,
+		interface: iface, interfaceOk,
+		admit: valid && equivalent && utility > 0 && interfaceOk,
+	};
+}
+
+/**
+ * Adapt the MDL/utility gate to the shape `authorConcept`'s `spec.gate` expects, so the
+ * CEGIS loop self-admits abstractions: only an 'add' proposal that `evaluate` admits (valid
+ * + fixpoint-equivalent + net-cheaper vs the reference `chainTree`) is installed.
+ * @param opts.chainTree/seed/providers/equivKeys  the reference episode (as for evaluate)
+ * @param opts.asAbstractTree  (proposal)->tree   how to read the candidate grammar from a
+ *                             proposal (default: the single proposed schema as a tree)
+ * @returns async (graph, proposal) => { admit, reason, eval }
+ */
+function makeAbstractionGate( opts ) {
+	opts = opts || {};
+	const asAbstractTree = opts.asAbstractTree
+		|| ((proposal) => ({ childConcepts: { [proposal.schema._id]: proposal.schema } }));
+	return async function gate( graph, proposal ) {
+		if ( (proposal.op || 'add') !== 'add' ) return { admit: true };   // gate only ADDs
+		const r = await evaluate({
+			seed: opts.seed, providers: opts.providers, chainTree: opts.chainTree,
+			abstractTree: asAbstractTree(proposal), equivKeys: opts.equivKeys, validate: opts.validate,
+		});
+		return { admit: r.admit, reason: r.admit ? null : `not admitted (equivalent=${r.equivalent}, gain=${r.gain})`, eval: r };
+	};
+}
+
+module.exports = { evaluate, bootMeasure, factsEqual, makeAbstractionGate, interfaceRegression, providerNames };