skynet-graph 1.2.0

package/lib/authoring/segment-proxy.js

@@ -0,0 +1,114 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * segment-proxy — THE SEGMENT-PROXY RÉACTIF (roadmap 2026-07-09 P2; ZERO-CORE, host-side). A concept-method mounted
+ * as a reactive PROXY: it casts on its contract's cast-conditions, and AT CAST delegates its body to another instance
+ * via the P1 bounded invoke (instead of expanding inline), ADMITS the bounded result through the P4 gate
+ * (`assertPost`), and posts the summaryFacts as its own cast → JTMS-visible. The good C.8: an INTERFACE, not an
+ * in-core COW object (KG-PROXY C proved the posted facts are re-evaluable, not a severing read-gate).
+ *
+ * The cast is the COST GRADIENT (contract.js §0.1): (1) delegate to the library method (the invoke), (2) gate the
+ * result (assertPost), (3) LAST-RESORT LEARNING FALLBACK — on a hole / a gate refusal, an `forge` hook receives the
+ * problem STACK reconstituted UP the parent chain (`reconstructStack`, BOUNDED to each level's typed interface — not
+ * the prose) and may forge a method / adjust the slot qualification via the lattice. The forged method RE-ENTERS the
+ * gate (propose→assertPost disposes→index back) — it is typed sub-graph, so determinism holds. The full `adapt`/
+ * `crystallize` wiring of the fallback is the §5 plasticity layer; P2 provides the HOOK + the gate + the stack.
+ *
+ * Within one synchronous cast there is no extract→merge window, so the P4 assumption-recheck is not needed here (it
+ * guards the async host-side flow); P2 reuses P4's assertPost GATE and returns the cast template via `cb` (the engine
+ * applies it sequenced). GOTCHA respected: the template sets the proxy's own `<name>:true` cast marker.
+ */
+const { assertPost } = require('./contract.js');
+
+/**
+ * reconstructStack(graph, scope, opts) — reconstitute the bounded problem STACK by walking UP the `parentSeg` chain
+ * (the projection sets `parentSeg` on every seeded segment). Collects each level's TYPED interface only (statement +
+ * produces/needs), bounded by `maxDepth` — the reconstituted abstract context for a forge, WITHOUT the O(N) prose
+ * blow-up (garde-fou 1: the separator-typed interface travels, not the raw context).
+ * @returns [{ id, statement, produces, needs }]  (self first, root last)
+ */
+function reconstructStack( graph, scope, opts ) {
+	opts = opts || {};
+	const max = opts.maxDepth || 8;
+	const stack = [], seen = new Set();
+	let cur = scope && scope._, depth = 0;
+	while ( cur && depth <= max ) {
+		if ( cur._id == null || seen.has(cur._id) ) break;
+		seen.add(cur._id);
+		stack.push({ id: cur._id, statement: cur.statement, produces: cur.produces, needs: cur.needs });
+		const pid = cur.parentSeg;
+		if ( pid == null ) break;
+		const pe = graph.getEtty ? graph.getEtty(pid) : null;
+		cur = pe && pe._; depth++;
+	}
+	return stack;
+}
+
+/**
+ * makeSegmentProxy(spec) — build a reactive proxy concept + its provider.
+ * @param spec.name        the proxy concept name (its cast marker).
+ * @param spec.ns          provider namespace (default 'Proxy').
+ * @param spec.castWhen    extra require facts (besides Segment) that gate the cast (the contract's cast-conditions).
+ * @param spec.contract    { read, write, pre, post, effect } — the method's typed contract (the P4 gate).
+ * @param spec.methodMap   the concept map of the DELEGATE (the shared instance runs it).
+ * @param spec.buildSeed   (scope, graph) => seed   build the invoke seed from the cast segment (the slot bindings).
+ * @param spec.boundedFrom the delegate object id whose facts are the summary.
+ * @param spec.boundedKeys Σ_sep — the frontier alphabet to cross (default = contract.write).
+ * @param spec.invoke      (opts) => Promise<{summary,writeFootprint}>   the P1 invoke (default Graph.invokeGraph).
+ * @param spec.oracle      G2 ground-truth probe for an effecting post.
+ * @param spec.forge       ({scope, graph, contract, stack, reason, blame?}) => Promise<template>|template   the
+ *                         last-resort learning fallback (§5). Receives the reconstituted parent stack.
+ * @returns { conceptFragment, provider, name }
+ */
+function makeSegmentProxy( spec ) {
+	spec = spec || {};
+	const name = spec.name || 'Proxy';
+	const ns = spec.ns || 'Proxy';
+	const contract = spec.contract || {};
+	const boundedKeys = spec.boundedKeys || contract.write || [];
+	// invoke = the P1 wire. With a P3 pool, key it by libraryKey → N casts reuse ONE warm instance; else one-shot invokeGraph.
+	const libraryKey = spec.libraryKey || name;
+	const invoke = spec.invoke || (spec.pool ? ( iopts ) => spec.pool.invoke(libraryKey, iopts) : require('../index.js').invokeGraph);
+
+	const conceptFragment = { [name]: { _id: name, _name: name,
+		require: ['Segment'].concat(spec.castWhen || []), provider: [ ns + '::delegate' ] } };
+
+	function delegate( graph, concept, scope, argz, cb ) {
+		(async () => {
+			// the fallback: reconstitute the stack from the parents, forge under the gate; else a typed refusal.
+			const fallback = async ( reason, blame ) => {
+				if ( typeof spec.forge === 'function' ) {
+					const stack = reconstructStack(graph, scope, spec);
+					const t = await spec.forge({ scope, graph, contract, stack, reason, blame });
+					return t;                                                        // the forge returns a cast template (typed sub-graph)
+				}
+				return [ { $_id: '_parent', [name]: true, proxyRefused: (blame && blame.kind) || reason } ];
+			};
+
+			let seed;
+			try { seed = spec.buildSeed(scope, graph); }
+			catch ( e ) { return cb(null, await fallback('build-failed', { kind: e.message })); }
+
+			// (1) DELEGATE via the P1 bounded invoke to another instance (not expand inline).
+			let result;
+			try { result = await invoke({ conceptMap: spec.methodMap, seed, boundedFrom: spec.boundedFrom, boundedKeys, settleTimeout: spec.settleTimeout }); }
+			catch ( e ) { return cb(null, await fallback('invoke-failed', { kind: e.message })); }
+
+			// (2) GATE the bounded result (P4 assertPost: G1 frame via the write-footprint · post-holds · G2 oracle).
+			const post = assertPost(contract, result.summary || {}, result.writeFootprint || [], { oracle: spec.oracle });
+			if ( !post.ok ) return cb(null, await fallback('gate-refused', post.blame));   // (3) last-resort learning fallback
+
+			// admit — post the summaryFacts as this proxy's cast (JTMS-visible) + the cast marker.
+			cb(null, [ Object.assign({ $_id: '_parent', [name]: true }, result.summary || {}) ]);
+		})().catch(( e ) => cb(e));
+	}
+
+	return { conceptFragment, provider: { [ns]: { delegate } }, name };
+}
+
+module.exports = { makeSegmentProxy, reconstructStack };

package/lib/authoring/serve-leaf.js

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * serve-leaf — THE UNIFICATION (roadmap 2026-07-09 P6; ZERO-CORE). `context-project`'s projection serves each leaf
+ * with an injected `serve(leaf)` — until now an opaque stub. P6 makes **`serveLeaf` = DISPATCH (libraryKey) + MOUNT
+ * (a concept-method invoked on a shared instance)**: a leaf is no longer an opaque value, it IS a mounted method. This
+ * folds projection + runtime (P1 invoke) + library (dispatch) + method (the contract gate) into ONE structure — "le
+ * reste s'adapte à la structure centrale", by the constat.
+ *
+ *   const serve = makeMethodServe({ methods, pool });          // pool = a P3 invoke-pool (N cases → 1 instance)
+ *   const proj  = createContextProjection({ serve });          // a leaf IS a dispatched, mounted, gated method
+ *   const { order, results } = await proj.run(roadmap, ctx);
+ *
+ * Per leaf: (1) DISPATCH — `keyOf(leaf)` → a libraryKey (default: leaf.produces; library.js#byKey in production);
+ * (2) MOUNT + INVOKE — the method runs on its shared warm instance (P3) with the leaf's bounded inputs as the seed
+ * (the slot bindings); (3) GATE — assertPost (P4) admits the bounded summary or refuses (blame → the §5 forge fallback);
+ * the leaf's VALUE is the method's bounded output, which flows to downstream leaves through the projection's pool.
+ */
+const { assertPost } = require('./contract.js');
+
+/**
+ * makeMethodServe(spec) — a projection `serve(leaf, ctx)` that dispatches+mounts a concept-method per leaf.
+ * @param spec.methods  { <libraryKey>: { conceptMap, providers?, contract, boundedFrom, boundedKeys?, buildSeed(leaf,ctx), value?(summary), oracle? } }
+ * @param spec.keyOf    (leaf) => libraryKey        the dispatch (default: leaf.produces || leaf.id).
+ * @param spec.pool     a P3 invoke-pool (default: a fresh own pool — close via serve.close()).
+ * @param spec.fallback (leaf, ctx, info) => value  the §5 last-resort on a dispatch miss / a gate refusal.
+ * @returns serve       async (leaf, ctx) => value  (+ serve.pool, serve.close()).
+ */
+function makeMethodServe( spec ) {
+	spec = spec || {};
+	const methods = spec.methods || {};
+	const keyOf = spec.keyOf || (( leaf ) => leaf.produces || leaf.id);
+	const pool = spec.pool || require('../index.js').createInvokePool();
+	const ownPool = !spec.pool;
+
+	async function serve( leaf, ctx ) {
+		const key = keyOf(leaf);                                          // (1) DISPATCH
+		const m = methods[key];
+		if ( !m ) {
+			if ( spec.fallback ) return spec.fallback(leaf, ctx, { reason: 'no-method', key });
+			throw new Error('serveLeaf: no method for libraryKey "' + key + '" (leaf ' + leaf.id + ')');
+		}
+		const boundedKeys = m.boundedKeys || (m.contract && m.contract.write) || [];
+		const seed = m.buildSeed(leaf, ctx);                             // the leaf's bounded inputs = the slot bindings
+		const result = await pool.invoke(key, { conceptMap: m.conceptMap, providers: m.providers,   // (2) MOUNT + INVOKE (P1/P3)
+			seed, boundedFrom: m.boundedFrom, boundedKeys, settleTimeout: m.settleTimeout });
+		const post = assertPost(m.contract || {}, result.summary || {}, result.writeFootprint || [], { oracle: m.oracle });   // (3) GATE (P4)
+		if ( !post.ok ) {
+			if ( spec.fallback ) return spec.fallback(leaf, ctx, { reason: 'gate-refused', blame: post.blame });
+			throw new Error('serveLeaf: gate refused for "' + key + '": ' + post.violations.map(( v ) => v.kind).join(','));
+		}
+		return m.value ? m.value(result.summary, leaf) : result.summary;   // the leaf's VALUE = the mounted method's bounded output
+	}
+	serve.pool = pool;
+	serve.close = () => ownPool ? pool.close() : Promise.resolve();
+	return serve;
+}
+
+module.exports = { makeMethodServe };

package/lib/authoring/slot-aware-serve.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * slot-aware-serve — THE ROUTER between a plain leaf and a higher-order (method-slot) leaf (roadmap §5(a), the
+ * GENERATION seam; ZERO-CORE). `dag-decompose` now EMITS a typed `slot:{over,body,combinator}` on a part; this serve
+ * inspects it and forks:
+ *   • NO slot        → `makeMethodServe` (P6): dispatch → mount → gate a concept-method (a leaf IS a mounted method).
+ *   • a typed slot   → `makeHigherOrderServe` (§5a): the slot's `body` is DISPATCHED over the items resolved under
+ *                      `over`, reduced by `combinator` (map|all|any) — a leaf IS a mounted loop-of-methods.
+ * Both forks SHARE one P3 invoke-pool (N cases → 1 instance). The items come from the projection's RESOLVED bounded
+ * context (`leaf.inputs[over]`, because `over` was auto-added as a need) — so the loop is never vacuous: an UNRESOLVED
+ * `over` (or a non-array value) is a typed refusal (→ fallback), NEVER `[].every(Boolean)===true` (the confront break).
+ *
+ *   const serve = makeSlotAwareServe({ methods, bodies });        // methods = plain library, bodies = slot fillers
+ *   const proj  = createContextProjection({ serve });             // plain + higher-order leaves, one projection
+ *   const { results } = await proj.run(leavesToRoadmap(await decompose(task)), ctx);
+ */
+const { makeMethodServe } = require('./serve-leaf.js');
+const { makeHigherOrderServe } = require('./higher-order.js');
+
+// read the method-slot off a leaf, from either channel: the projection-reconstructed leaf (`leaf.slot`) or the
+// plan-loop-carried leaf (`leaf.request.slot`).
+function slotOf( leaf ) { return (leaf && (leaf.slot || (leaf.request && leaf.request.slot))) || null; }
+
+/**
+ * makeSlotAwareServe(spec) — a projection `serve(leaf, ctx)` that routes plain vs higher-order leaves.
+ * @param spec.methods   { <libraryKey>: <makeMethodServe method spec> }  the PLAIN library (dispatched per leaf).
+ * @param spec.bodies    { <bodyKey>:    <makeMethodServe method spec> }  the SLOT FILLERS (dispatched per item).
+ * @param spec.keyOf     (leaf) => libraryKey   the plain dispatch (default: leaf.produces || leaf.id).
+ * @param spec.pool      a shared P3 invoke-pool (default: a fresh own pool — close via serve.close()).
+ * @param spec.fallback  (leaf, ctx, info) => value  the §5 last-resort on a dispatch miss / an unresolved slot.
+ * @returns serve        async (leaf, ctx) => value  (+ serve.pool, serve.close()).
+ */
+function makeSlotAwareServe( spec ) {
+	spec = spec || {};
+	const bodies = spec.bodies || {};
+	const pool = spec.pool || require('../index.js').createInvokePool();
+	const ownPool = !spec.pool;
+	// dispatch key, ROBUST to both leaf shapes: the plan-loop leaf keys on `request.id` (its id is prefixed `n_<key>`),
+	// the à-nu projection leaf keys on `produces`. Without this a plan-loop leaf mis-dispatches → provider error →
+	// the Step concept re-fires to the apply-cap (1000) → DIVERGENT (the cast-marker GOTCHA). Default covers both.
+	const keyOf = spec.keyOf || (( l ) => (l.request && l.request.id) || l.produces || l.id);
+	const plain = makeMethodServe({ methods: spec.methods || {}, keyOf: keyOf, pool: pool, fallback: spec.fallback });
+	// three generic combinator-keyed loops → the emitted slot maps 1:1 onto `makeHigherOrderServe` (ZERO consumer delta):
+	// bodyKeyOf/items are DATA-DRIVEN off the slot, so the same three loops serve every emitted higher-order leaf.
+	const mkLoop = ( combinator ) => ({ combinator: combinator,
+		bodyKeyOf: ( l ) => slotOf(l).body, items: ( l ) => (l.inputs || {})[slotOf(l).over] });
+	// the 3 generic combinator loops + any NAMED nested loops (spec.loops) → a slot whose `body` names a nested loop
+	// (map-of-maps) recurses inside makeHigherOrderServe.
+	const nested = spec.loops || {};
+	const loops = Object.assign({ __slot_map: mkLoop('map'), __slot_all: mkLoop('all'), __slot_any: mkLoop('any') }, nested);
+	const ho = makeHigherOrderServe({ bodies: bodies, pool: pool, loops: loops, keyOf: ( l ) => '__slot_' + slotOf(l).combinator });
+
+	function refuse( leaf, ctx, info ) {
+		if ( spec.fallback ) return spec.fallback(leaf, ctx, info);
+		throw new Error('slot-aware serve: ' + info.reason + ' for slot on leaf ' + (leaf && leaf.id) + (info.over ? ' (over="' + info.over + '")' : ''));
+	}
+
+	async function serve( leaf, ctx ) {
+		const slot = slotOf(leaf);
+		if ( !slot ) return plain(leaf, ctx);                                   // PLAIN → dispatch+mount+gate a method
+		if ( !bodies[slot.body] && !nested[slot.body] ) return refuse(leaf, ctx, { reason: 'no-body', body: slot.body });   // dispatch miss (a plain body OR a nested loop)
+		const items = (leaf.inputs || {})[slot.over];                           // the items = the RESOLVED bounded input
+		if ( !Array.isArray(items) ) return refuse(leaf, ctx, { reason: 'slot-unresolved', over: slot.over });   // never iterate undefined/a string
+		return ho(leaf, ctx);                                                   // HIGHER-ORDER → dispatched loop over items
+	}
+	serve.pool = pool;
+	serve.close = () => ownPool ? pool.close() : Promise.resolve();
+	return serve;
+}
+
+module.exports = { makeSlotAwareServe, slotOf };

package/lib/authoring/sound-invoke.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * sound-invoke — THE CONSTAT OPERATIONALIZED (roadmap 2026-07-09 P4; ZERO-CORE, host-side). KG-PROXY proved that a
+ * bounded cross-instance invoke ≡ the flat run — same result + same JTMS at drift. P1 gave the bounded WIRE
+ * (`invoke` → `{ summary, writeFootprint }`, only Σ_sep crosses). P4 makes the ADMISSION of that result SOUND, so the
+ * equivalence is not just observed on a happy path but ENFORCED — "composé-cross-instance ≡ plat, *sainement*".
+ *
+ * `soundInvokeMerge(parent, invokeResult, extraction, { contract, targetId, oracle? })` gates the commit on the two
+ * things the constat needs across the frontier, then applies through the sequenced taskflow:
+ *
+ *   1. assertPost(contract, summary, writeFootprint)  — the induced post asserted at ADMISSION (contract.js):
+ *        · G1 FRAME-COMPLETENESS — the keys the body actually wrote (the P1 write-footprint = the delta) ⊆ declared
+ *          write. An under-declared frame is the silent unsoundness; the write-footprint from P1 is exactly its witness.
+ *        · the POST holds on the returned summaryFacts (the induced hypothesis — sound on observed, asserted here).
+ *        · G2 EFFECT-TAG — an external/irreversible method's post needs a ground-truth ORACLE, never the internal fact.
+ *      A violation → REFUSE (the caller never commits a lying result) + `blame` (feed `reviseOnBlame`, CEGIS).
+ *   2. mergeSlice (extract.js) — the ASSUMPTION-RECHECK (the frozen frontier still holds in the parent since extraction
+ *      — the ATMS defeasance) + SINGLE-WRITER (never writes a frontier id) + `pushMutation` (sequenced). A frontier
+ *      drift → REFUSE (the dead-premise result is not committed — the sound analog of the flat JTMS retract).
+ *
+ * On success the summaryFacts are posted as FIRST-CLASS re-evaluable facts (KG-PROXY C): the caller's JTMS carries the
+ * ongoing soundness — a LATER premise drift retracts them like any flat fact. ⇒ composé-cross-instance ≡ plat, sainement.
+ */
+const { assertPost } = require('./contract.js');
+const { mergeSlice } = require('./extract.js');
+
+/**
+ * @param parent        the caller graph.
+ * @param invokeResult  { summary:{<Σ_sep facts>}, writeFootprint:[keys] } — from Graph.invokeGraph / worker `invoke`.
+ * @param extraction    the extractSubgraph record (carries the frozen frontier for the assumption-recheck).
+ * @param opts.contract { read, write, pre, post, effect } — the method's typed contract.
+ * @param opts.targetId the caller object the bounded summary posts onto (an interior id — never a frozen frontier id).
+ * @param opts.oracle   (contract, factsAfter) => bool — ground-truth probe for an effecting post (G2).
+ * @returns { merged:true, template } | { merged:false, reason, blame? }
+ */
+function soundInvokeMerge( parent, invokeResult, extraction, opts ) {
+	opts = opts || {};
+	const summary = (invokeResult && invokeResult.summary) || {};
+	const footprint = (invokeResult && invokeResult.writeFootprint) || [];
+	const contract = opts.contract || {};
+
+	// (1) post-assert + blame — G1 frame / post-holds / G2 oracle, at admission.
+	const post = assertPost(contract, summary, footprint, { oracle: opts.oracle });
+	if ( !post.ok )
+		return { merged: false, reason: 'post-violation: ' + post.violations.map(( v ) => v.kind + (v.detail != null ? '(' + v.detail + ')' : '')).join(','), blame: post.blame };
+
+	// (2) assumption-recheck (frontier) + single-writer + sequenced apply. The write template IS the bounded summary
+	// (already Σ_sep — no child to project from), posted onto the interior target.
+	const project = () => [ Object.assign({ $$_id: opts.targetId }, summary) ];
+	return mergeSlice(parent, null, extraction, { project });
+}
+
+module.exports = { soundInvokeMerge };

package/lib/authoring/split-serve.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * makeSplitServe — the RECURSIVE composite path (KG-SPLIT GO, 2026-07-10). Single-shot emission of a COMPOSED
+ * shape was REFUTED live (Q6 oriented: 0% strict / 14% relaxed — `2026-07-09-reachability-composed`); what works
+ * is the recursive chain, proven live on the same corpus (55% strict / 64% relaxed / 86% kind / 0% plain
+ * false-positives — `2026-07-10-recursive-split`):
+ *
+ *   kind-route (SET-OP / NESTED / PLAIN) → SPLIT the NL question into STANDALONE sub-questions →
+ *   plain-decompose EACH sub-question with the proven oriented emission → assemble `operand|op`.
+ *
+ * The split is where the lift lives: a standalone sub-question decomposes at the plain rate (~78%) because the
+ * sub-query no longer LEAKS into the outer reading and the certified-atom menu no longer has to steer a composite
+ * question. This is what makes the COMPOSED certified vocabulary (blend/combine classes, KG-6) DISPATCHABLE — the
+ * named lever for growing the trusted tier.
+ *
+ * The brick owns NO model (à-nu doctrine): `split` and `plain` are injected. FAIL-CLOSED routing: a malformed,
+ * conflicting, or throwing split falls back to the plain path on the ORIGINAL query (tagged `fallback:true`) —
+ * the router never invents a composition and never blocks a query. Honest residual (do NOT claim it): the NESTED
+ * outer-with-VALUE-placeholder decomposes at ~2/6 live; set-ops are the proven half (intersect 6/6 strict).
+ *
+ *   const sv = makeSplitServe({ split, plain });
+ *   const r = await sv.serve(query);   // { shape, kind:'plain'|'setop'|'nested', parts?, sameOperand?, fallback? }
+ *
+ * @param opts.split  REQUIRED async (query) => { setop:'none'|'intersect'|'except'|'union', nested:bool, q1, q2 }
+ *                    — the NL splitter (an LLM call; see the kill-gate's SYS_SPLIT prompt + grammar).
+ * @param opts.plain  REQUIRED async (question) => shape — the PROVEN oriented plain decomposer (menu-glossed,
+ *                    canonical-order prompt; the grammar is format-insurance only — signature-stability finding).
+ * @param opts.ops    optional array — accepted set-ops (default ['intersect','except','union']).
+ * @returns {{ serve, stats }}
+ */
+function makeSplitServe( opts ) {
+	opts = opts || {};
+	if ( typeof opts.split !== 'function' ) throw new Error('makeSplitServe needs opts.split (async query -> {setop, nested, q1, q2})');
+	if ( typeof opts.plain !== 'function' ) throw new Error('makeSplitServe needs opts.plain (async question -> shape) — the proven plain decomposer');
+	var OPS = Array.isArray(opts.ops) && opts.ops.length ? opts.ops : ['intersect', 'except', 'union'];
+	var stats = { served: 0, plain: 0, setop: 0, nested: 0, fallback: 0 };
+
+	async function plainFallback( query ) {
+		stats.plain++; stats.fallback++;
+		return { shape: await opts.plain(query), kind: 'plain', fallback: true };
+	}
+
+	async function serve( query ) {
+		stats.served++;
+		var k;
+		try { k = await opts.split(query) || {}; } catch ( _e ) { return plainFallback(query); }
+		var isSet = OPS.indexOf(k.setop) >= 0;
+		// fail-closed routing: conflicting (setop AND nested) or malformed (set-op without both sides) → plain.
+		if ( (isSet && k.nested) || (isSet && !(k.q1 && k.q2)) || (k.nested && !k.q1) ) return plainFallback(query);
+		if ( isSet ) {
+			var s1 = await opts.plain(String(k.q1));
+			var s2 = await opts.plain(String(k.q2));
+			stats.setop++;
+			return { shape: s1 + '|' + k.setop, kind: 'setop', sameOperand: s1 === s2, parts: { q1: k.q1, q2: k.q2, s1: s1, s2: s2 } };
+		}
+		if ( k.nested ) {
+			var outer = await opts.plain(String(k.q1));
+			stats.nested++;
+			return { shape: outer + '|n', kind: 'nested', parts: { q1: k.q1, inner: k.q2 || '', s1: outer } };
+		}
+		stats.plain++;
+		return { shape: await opts.plain(query), kind: 'plain' };   // plain: the ORIGINAL query, not q1 (no drift)
+	}
+
+	return { serve: serve, stats: stats };
+}
+
+module.exports = { makeSplitServe: makeSplitServe };

package/lib/authoring/ste.js

@@ -0,0 +1,239 @@
+/*
+ * 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';
+/**
+ * Straight-Through Estimator (STE) training for concept-networks (doc/WIP/HANDOFF.md §7 Tier 4;
+ * experiment E5). Zero core change — an OFFLINE trainer (run between revisions, not in the cast
+ * loop) plus a provider that bakes the learned weights into a concept doing HARD forward
+ * inference. Train SOFT (sigmoid + SGD), infer HARD (step/threshold cast) with the same weights:
+ * the straight-through estimator, consistent with the canonicalization barrier (a hard discrete
+ * cast at inference, continuous only during offline training).
+ *
+ * The thesis it makes operational (E5, the user's founding intuition): the TOPOLOGY decides what
+ * is learnable. A single log-linear unit learns AND but never XOR; adding a hidden layer (depth
+ * in the concept topology) turns the unlearnable into the learnable — measured, not asserted.
+ *
+ *   const { trainNet, predictHard, createNet, netConceptTree } = require('./ste');
+ *   const fit = trainNet(X, Y, { layers: [2, 3, 1], restarts: 8 });   // offline
+ *   register(Graph, [ createNet(fit.net, { inputKeys: ['x0', 'x1'] }) ]); // bake -> Net::infer (hard)
+ *
+ * NOT a substitute for the deterministic socle: this trains a bounded feed-forward concept-net
+ * offline. Cross-strata credit assignment for continuous weights across the full graph is open R&D.
+ */
+
+function sigmoid( x ) { return 1 / (1 + Math.exp(-x)); }
+function dSigmoidFromOutput( y ) { return y * (1 - y); }   // σ'(z) in terms of a = σ(z)
+
+// Initialise an MLP for the given layer sizes [n_in, ..., n_out]; weights/biases in [-1,1].
+function initNet( layers, rng ) {
+	rng = rng || Math.random;
+	var W = [], b = [];
+	for ( var l = 1; l < layers.length; l++ ) {
+		var rows = layers[l], cols = layers[l - 1], Wl = [], bl = [];
+		for ( var i = 0; i < rows; i++ ) {
+			var row = [];
+			for ( var j = 0; j < cols; j++ ) row.push(rng() * 2 - 1);
+			Wl.push(row);
+			bl.push(rng() * 2 - 1);
+		}
+		W.push(Wl); b.push(bl);
+	}
+	return { layers: layers.slice(), W: W, b: b };
+}
+
+// Soft forward pass; returns the activation vector of every layer (acts[0] = input).
+function forward( net, x ) {
+	var acts = [x.slice()];
+	for ( var l = 0; l < net.W.length; l++ ) {
+		var Wl = net.W[l], bl = net.b[l], a = acts[acts.length - 1], out = [];
+		for ( var i = 0; i < Wl.length; i++ ) {
+			var z = bl[i];
+			for ( var j = 0; j < Wl[i].length; j++ ) z += Wl[i][j] * a[j];
+			out.push(sigmoid(z));
+		}
+		acts.push(out);
+	}
+	return acts;
+}
+
+// One SGD step (MSE loss) on a single example.
+function trainStep( net, x, y, lr ) {
+	var acts = forward(net, x), L = net.W.length, deltas = new Array(L);
+	var outA = acts[L], dL = [];
+	for ( var i = 0; i < outA.length; i++ ) dL.push((outA[i] - y[i]) * dSigmoidFromOutput(outA[i]));
+	deltas[L - 1] = dL;
+	for ( var l = L - 2; l >= 0; l-- ) {
+		var Wnext = net.W[l + 1], dNext = deltas[l + 1], a = acts[l + 1], d = [];
+		for ( var iH = 0; iH < a.length; iH++ ) {
+			var s = 0;
+			for ( var k = 0; k < Wnext.length; k++ ) s += Wnext[k][iH] * dNext[k];
+			d.push(s * dSigmoidFromOutput(a[iH]));
+		}
+		deltas[l] = d;
+	}
+	for ( var ll = 0; ll < L; ll++ ) {
+		var aPrev = acts[ll], Wl = net.W[ll], bl = net.b[ll], dd = deltas[ll];
+		for ( var r = 0; r < Wl.length; r++ ) {
+			for ( var c = 0; c < Wl[r].length; c++ ) Wl[r][c] -= lr * dd[r] * aPrev[c];
+			bl[r] -= lr * dd[r];
+		}
+	}
+}
+
+// Mean squared error over a dataset.
+function mseLoss( net, X, Y ) {
+	var s = 0;
+	for ( var i = 0; i < X.length; i++ ) {
+		var o = forward(net, X[i]).pop();
+		for ( var j = 0; j < o.length; j++ ) s += (o[j] - Y[i][j]) * (o[j] - Y[i][j]);
+	}
+	return s / X.length;
+}
+
+/**
+ * Train an MLP offline (SOFT — sigmoid + SGD), with random restarts to escape bad inits.
+ * @param X        inputs (array of number vectors)
+ * @param Y        targets (array of number vectors)
+ * @param opts.layers    layer sizes (default [n_in, 2, n_out]); the TOPOLOGY that gates learnability
+ * @param opts.epochs    passes over the data (default 3000)
+ * @param opts.lr        learning rate (default 0.5)
+ * @param opts.restarts  random restarts; keep the best (default 6)
+ * @param opts.rng       seedable RNG for reproducibility (default Math.random)
+ * @returns { net, loss }  the lowest-loss net
+ */
+function trainNet( X, Y, opts ) {
+	opts = opts || {};
+	var layers = opts.layers || [X[0].length, 2, Y[0].length],
+	    epochs = opts.epochs || 3000, lr = opts.lr || 0.5, restarts = opts.restarts || 6, rng = opts.rng || Math.random,
+	    best = null;
+	for ( var r = 0; r < restarts; r++ ) {
+		var net = initNet(layers, rng);
+		for ( var e = 0; e < epochs; e++ )
+			for ( var i = 0; i < X.length; i++ ) trainStep(net, X[i], Y[i], lr);
+		var loss = mseLoss(net, X, Y);
+		if ( !best || loss < best.loss ) best = { net: net, loss: loss };
+	}
+	return best;
+}
+
+/**
+ * Straight-through HARD inference: the SAME learned weights, but every unit is a STEP (z≥0 → 1)
+ * instead of a sigmoid — i.e. each layer's activation is snapped (round(σ(z))). This is the cast
+ * the engine performs; it equals the rounded soft prediction on a well-separated trained net (E5).
+ */
+function predictHard( net, x ) {
+	var a = x.slice();
+	for ( var l = 0; l < net.W.length; l++ ) {
+		var Wl = net.W[l], bl = net.b[l], out = [];
+		for ( var i = 0; i < Wl.length; i++ ) {
+			var z = bl[i];
+			for ( var j = 0; j < Wl[i].length; j++ ) z += Wl[i][j] * a[j];
+			out.push(z >= 0 ? 1 : 0);
+		}
+		a = out;
+	}
+	return a;
+}
+
+/**
+ * Like predictHard, but injects exploration noise into each unit's pre-activation z before the
+ * step threshold — the inference-time face of PLASTICITY for an NN concept. `noise` scales the
+ * uniform perturbation (±noise); `noise = 0` is exactly predictHard (the frozen path). A plastic
+ * net thus occasionally explores a different cast on a well-separated unit; a frozen one is
+ * deterministic. Offline training uses lr; live inference uses this noise — the same continuous p.
+ */
+function predictNoisy( net, x, opts ) {
+	opts = opts || {};
+	var noise = opts.noise || 0, rng = opts.rng || Math.random;
+	var a = x.slice();
+	for ( var l = 0; l < net.W.length; l++ ) {
+		var Wl = net.W[l], bl = net.b[l], out = [];
+		for ( var i = 0; i < Wl.length; i++ ) {
+			var z = bl[i];
+			for ( var j = 0; j < Wl[i].length; j++ ) z += Wl[i][j] * a[j];
+			if ( noise ) z += (rng() * 2 - 1) * noise;
+			out.push(z >= 0 ? 1 : 0);
+		}
+		a = out;
+	}
+	return a;
+}
+
+/**
+ * Bake a trained net into a provider fragment (host opt-in). The provider reads the input facts
+ * and writes the HARD prediction — offline-trained weights, hard inference in the engine.
+ * @param net            a trained net (from trainNet().net)
+ * @param opts.inputKeys default input fact keys (per-concept override via the concept's `net`)
+ * @param opts.plasticity (conceptName)->p∈[0,1]  the UNIFIED plasticity knob (e.g. a
+ *        `lifecycle.plasticity` accessor). p=0 (frozen) → deterministic predictHard; p>0
+ *        (plastic) → predictNoisy with noise = noiseScale·p (explore). Unwired → frozen.
+ *        DISCIPLINE: plasticity modulates the cast value, it never gates applicability (K1).
+ * @param opts.noiseScale max exploration noise at p=1 (default 4 — enough to flip a separated unit)
+ * @param opts.rng       seedable RNG for reproducible exploration (default Math.random)
+ * @returns { Net: { infer } }
+ *
+ * Concept wiring: { require:['input'], provider:['Net::infer'], net:{ inputKeys:['x0','x1'], as:'' } }
+ * Emits the self-flag + <as>pred (a scalar for a single output, else the vector).
+ */
+function createNet( net, opts ) {
+	opts = opts || {};
+	var plasticity = opts.plasticity,
+	    noiseScale = opts.noiseScale == null ? 4 : opts.noiseScale,
+	    rng        = opts.rng || Math.random;
+	return {
+		Net: {
+			infer: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({ inputKeys: opts.inputKeys || [], as: '' },
+					concept._schema && concept._schema.net, argz && argz[0]),
+				    x = cfg.inputKeys.map(function ( k ) { return Number(scope._[k]); }),
+				    p = plasticity ? plasticity(concept._name) : 0,
+				    noise = noiseScale * p,
+				    y = noise > 0 ? predictNoisy(net, x, { noise: noise, rng: rng }) : predictHard(net, x),
+				    facts = { $_id: '_parent' };
+				facts[concept._name] = true;
+				facts[cfg.as + 'pred'] = y.length === 1 ? y[0] : y;
+				cb(null, facts);
+			}
+		}
+	};
+}
+
+/** A ready-made inference concept fragment for a baked net. */
+function netConceptTree( opts ) {
+	opts = opts || {};
+	return {
+		childConcepts: {
+			Net: {
+				_id: 'Net', _name: 'Net',
+				require: [opts.require || 'input'],
+				provider: ['Net::infer'],
+				net: { inputKeys: opts.inputKeys || [], as: opts.as || '' }
+			}
+		}
+	};
+}
+
+module.exports = {
+	trainNet: trainNet,
+	predictHard: predictHard,
+	predictNoisy: predictNoisy,
+	forward: forward,
+	mseLoss: mseLoss,
+	createNet: createNet,
+	netConceptTree: netConceptTree
+};