skynet-graph 1.2.0

package/lib/authoring/concept-net.js

@@ -0,0 +1,254 @@
+/*
+ * 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';
+/**
+ * concept-net — a differentiable POPULATION of concept-units, trained end-to-end across the
+ * composite (fixpoint) topology by implicit diff (equilibrium.js). Host-side, ZERO-CORE. Study
+ * 2026-06-26 dynamic-concepts; the user's target shape: each concept-unit = a NN that DECIDES
+ * whether to cast (the gate) × a NN that GENERATES the value it writes (the update):
+ *
+ *   contribution of unit i to its target fact = gate_i(ctx_i) · update_i(ctx_i)
+ *   gate_i  = σ(W^g_i·ctx + b^g_i)   (cast decision; hard = step at inference, STE backward)
+ *   update_i= σ(W^u_i·ctx + b^u_i)   (the value written when cast)
+ *   ctx_i   = z[ unit_i.inputs ]     (the facts the unit reads — the WIRING / structure)
+ *
+ * One synchronous sweep F updates every computed fact from the current state; the population is
+ * run to a fixpoint z*=F(z*) (a learned, gated equilibrium GNN). The structure (which fact each
+ * unit reads, how many units) is the FORM that can evolve — add/remove units = structure search.
+ * Input facts are clamped (constants), so the DEQ adjoint operates only on the COMPUTED subspace
+ * (a clamped fact would be an identity row in J_z → I−J_z singular).
+ *
+ * This is the differentiable MIRROR of a population of engine concepts; a trained unit is baked
+ * back into the real engine via ste.js (STE at the cast boundary) — that bridge is the next rung.
+ */
+const { solveFixpoint, implicitGrad, spectralRadius, numJac } = require('./equilibrium.js');
+
+const sigmoid = (x) => 1 / (1 + Math.exp(-x));
+
+/**
+ * Build a population from a STRUCTURE spec (no params — those live in the θ vector trained on top).
+ * @param spec.nFacts  total facts z[0..nFacts-1]
+ * @param spec.inputs  indices of CLAMPED input facts (held constant across sweeps)
+ * @param spec.units   [{ target, inputs:[...] }] — one unit per computed fact; inputs = the wiring
+ * @param spec.out     the readout fact (full-z index) the loss is taken on
+ */
+function makePopulation( spec ) {
+	const nFacts = spec.nFacts, inputs = (spec.inputs || []).slice();
+	const zeroSet = new Set(spec.zero || []);                       // clamped facts pinned to 0 (e.g. an unroll's stage-0 init)
+	let off = 0;
+	const units = spec.units.map((u) => {
+		const L = u.inputs.length;                                   // ctx size
+		const m = { target: u.target, inputs: u.inputs.slice(), L, oG: off, oGb: off + L, oU: off + L + 1, oUb: off + 2 * L + 1 };
+		off += 2 * (L + 1);                                          // gate (L w + bias) + update (L w + bias)
+		return m;
+	});
+	const nParams = off;
+	const computed = [...new Set(units.map((u) => u.target))];       // the differentiable state coords (unique facts)
+	const out = spec.out == null ? computed[computed.length - 1] : spec.out;
+	const outC = computed.indexOf(out);
+
+	// one synchronous sweep over the FULL z (input facts preserved); hard ⇒ gate is a step (cast).
+	// Multiple units may target the same fact — their gate·update contributions SUM (a wide
+	// population / mixture); one-unit-per-fact (a ring/chain) is the special case (sum of one).
+	function F( z, th, opts ) {
+		const hard = opts && opts.hard, zn = z.slice();
+		for ( const u of units ) zn[u.target] = 0;                  // reset computed facts before accumulating
+		for ( const u of units ) {
+			let ag = th[u.oGb], au = th[u.oUb];
+			for ( let k = 0; k < u.L; k++ ) { const c = z[u.inputs[k]]; ag += th[u.oG + k] * c; au += th[u.oU + k] * c; }
+			const gate = hard ? (ag >= 0 ? 1 : 0) : sigmoid(ag);
+			zn[u.target] += gate * sigmoid(au);
+		}
+		return zn;
+	}
+
+	// scatter a computed-subvector zc into a full z with inputs clamped to `xv`; gather the reverse
+	const scatter = (zc, xv) => { const z = new Array(nFacts).fill(0); for ( const i of inputs ) z[i] = zeroSet.has(i) ? 0 : xv; computed.forEach((j, c) => { z[j] = zc[c]; }); return z; };
+	const gather = (z) => computed.map((j) => z[j]);
+	// reduced sweep on the computed subspace (what the DEQ differentiates)
+	const stepC = (zc, th, xv, opts) => gather(F(scatter(zc, xv), th, opts));
+
+	return {
+		nFacts, inputs, units, nParams, computed, out, outC, F, scatter, gather, stepC,
+		randomParams( rng, scale ) { rng = rng || Math.random; scale = scale == null ? 1 : scale; const t = new Array(nParams); for ( let i = 0; i < nParams; i++ ) t[i] = (rng() * 2 - 1) * scale; return t; },
+		/** Run the population to its fixpoint for input value xv. hard ⇒ cast decisions are STEP. */
+		settle( th, xv, opts ) { return solveFixpoint((zc) => stepC(zc, th, xv, opts), new Array(this.computed.length).fill(0), { maxIter: (opts && opts.maxIter) || 2000, tol: (opts && opts.tol) || 1e-12 }); },
+	};
+}
+
+/** A ring of K concept-units (a genuine cycle: fact0=input → u1 → u2 → … → uK → back to u1). */
+function ringPopulation( K, opts ) {
+	opts = opts || {};
+	const units = [];
+	for ( let i = 1; i <= K; i++ ) units.push({ target: i, inputs: i === 1 ? [0, K] : [i - 1] });
+	return makePopulation({ nFacts: K + 1, inputs: [0], units, out: opts.out == null ? K : opts.out });
+}
+
+/** An ACYCLIC chain of K concept-units (a DAG: fact0=input → u1 → u2 → … → uK). The engine bridge
+ *  starts here — a DAG cascades in topological order, no value-change re-derivation / re-cast loop. */
+function chainPopulation( K, opts ) {
+	opts = opts || {};
+	const units = [];
+	for ( let i = 1; i <= K; i++ ) units.push({ target: i, inputs: [i - 1] });
+	return makePopulation({ nFacts: K + 1, inputs: [0], units, out: opts.out == null ? K : opts.out });
+}
+
+/** A WIDE population: K parallel units all reading the input fact and SUMMING into one readout
+ *  fact (a mixture / one-hidden-layer of gate×update bumps). Unlike a chain (which collapses under
+ *  [0,1]-squashing), capacity grows with K — the topology where the FORM genuinely needs to evolve. */
+function widePopulation( K ) {
+	const units = [];
+	for ( let i = 0; i < K; i++ ) units.push({ target: 1, inputs: [0] });
+	return makePopulation({ nFacts: 2, inputs: [0], units, out: 1 });
+}
+
+/**
+ * Unroll a CYCLIC population to depth N — turn the recurrent fixpoint z*=F(z*) into an ACYCLIC DAG
+ * of N stages (the Picard iteration, unrolled), so it can be served on the engine. Why unroll: a
+ * directly-baked cycle DEADLOCKS (the `require` graph is a producer cycle with no entry point), and
+ * even past that the engine does not natively iterate a value-feedback loop (findings #22/#15). So
+ * we break the cycle into stages: stage t reads stage t-1; stage 0 reads a clamped ZERO init (= the
+ * mirror's z0=0). Weights are TIED across stages (the same recurrence) — `tieTheta(theta)` lays the
+ * original params out for the unrolled population. The depth-N readout → the true fixpoint as N grows
+ * (error ~ρ^N). Bake the result with bakePopulation as usual (it's now an ordinary acyclic population).
+ * @returns { pop, tieTheta, readout }
+ */
+function unrollPopulation( pop, N ) {
+	const C = pop.computed.length, INPUT = 0, ZERO = 1;
+	const idx = (t, f) => 2 + t * C + pop.computed.indexOf(f);      // unrolled fact index for (stage t, computed fact f)
+	const inputSet = new Set(pop.inputs);
+	const units = [];
+	for ( let t = 0; t < N; t++ ) for ( const u of pop.units ) {
+		const inputs = u.inputs.map((i) => inputSet.has(i) ? INPUT : (t === 0 ? ZERO : idx(t - 1, i)));
+		units.push({ target: idx(t, u.target), inputs });
+	}
+	const readout = idx(N - 1, pop.out);
+	const up = makePopulation({ nFacts: 2 + N * C, inputs: [INPUT, ZERO], zero: [ZERO], units, out: readout });
+	function tieTheta( theta ) {
+		const out = [];
+		for ( let t = 0; t < N; t++ ) for ( const u of pop.units )
+			for ( let k = u.oG; k < u.oG + 2 * (u.L + 1); k++ ) out.push(theta[k]);   // each stage reuses u's frozen weights
+		return out;
+	}
+	return { pop: up, tieTheta, readout };
+}
+
+/**
+ * BAKE a trained population into REAL engine concepts + providers (the mirror↔engine bridge,
+ * the analogue of ste.js#createNet for a multi-unit population). Each unit → a concept whose
+ * provider reads its input facts `f<i>`, does the HARD gate × update with the frozen weights, and
+ * writes its target fact `f<target>` + its self-flag `U<target>` (finding #1). `require` keys on
+ * the PRODUCER unit's self-flag (or 'input' for a clamped input fact) — so an acyclic population
+ * cascades in topological order to a terminal state. Bake only an ACYCLIC population (a DAG); a
+ * cyclic one needs the value-change re-derivation work (#22) first.
+ * @returns { conceptTree: { childConcepts }, providers: { Pop } }
+ */
+function bakePopulation( pop, theta ) {
+	const inputSet = new Set(pop.inputs);
+	const producer = {};
+	for ( const u of pop.units ) producer[u.target] = 'U' + u.target;
+	const childConcepts = {}, provFns = {};
+	for ( const u of pop.units ) {
+		const name = 'U' + u.target;
+		const require = [...new Set(u.inputs.map((i) => (inputSet.has(i) ? 'input' : producer[i])))];
+		childConcepts[name] = { _id: name, _name: name, require, provider: ['Pop::' + name] };
+		provFns[name] = (function ( unit, nm ) {
+			return function ( graph, concept, scope, argz, cb ) {
+				let ag = theta[unit.oGb], au = theta[unit.oUb];
+				for ( let k = 0; k < unit.L; k++ ) { const c = Number(scope._['f' + unit.inputs[k]]); ag += theta[unit.oG + k] * c; au += theta[unit.oU + k] * c; }
+				const gate = ag >= 0 ? 1 : 0, upd = sigmoid(au), facts = { $_id: '_parent' };
+				facts[nm] = true; facts['f' + unit.target] = gate * upd;
+				cb(null, facts);
+			};
+		})(u, name);
+	}
+	return { conceptTree: { childConcepts }, providers: { Pop: provFns } };
+}
+
+/** Mean-squared fixpoint-output loss over a dataset (X = input values, T = targets on the readout). */
+function loss( pop, th, X, T, opts ) {
+	let s = 0;
+	for ( let i = 0; i < X.length; i++ ) s += (pop.settle(th, X[i], opts).z[pop.outC] - T[i]) ** 2;
+	return s / X.length;
+}
+
+/**
+ * Implicit-diff gradient dL/dθ over the whole population. Forward fixpoint uses the requested
+ * regime (hard ⇒ STE); the backward Jacobians J_z, J_θ are taken from the SOFT sweep at z*
+ * (the straight-through surrogate). Returns { grad, rho } (rho = mean spectral radius, instrument).
+ */
+function grad( pop, th, X, T, opts ) {
+	const g = new Array(pop.nParams).fill(0); let rhoSum = 0;
+	for ( let i = 0; i < X.length; i++ ) {
+		const zc = pop.settle(th, X[i], opts).z;
+		const gl = new Array(pop.computed.length).fill(0);
+		gl[pop.outC] = 2 * (zc[pop.outC] - T[i]) / X.length;
+		const Jz = numJac((z) => pop.stepC(z, th, X[i], { hard: false }), zc);          // soft surrogate
+		const Jt = numJac((t) => pop.stepC(zc, t, X[i], { hard: false }), th);
+		const r = implicitGrad(Jz, Jt, gl, opts && opts.mode ? { mode: opts.mode } : { mode: 'direct' });
+		for ( let k = 0; k < pop.nParams; k++ ) g[k] += r.grad[k];
+		rhoSum += spectralRadius(Jz, { iters: 60 });
+	}
+	return { grad: g, rho: rhoSum / X.length };
+}
+
+/**
+ * Train a population to a teacher map via implicit diff + Adam. @returns { theta, loss0, loss, rho }.
+ */
+function train( pop, conf ) {
+	const X = conf.X, T = conf.T, steps = conf.steps || 1500, lr = conf.lr || 0.05, hard = !!conf.hard;
+	let th = (conf.theta0 || pop.randomParams(conf.rng, conf.initScale)).slice();
+	const loss0 = loss(pop, th, X, T, { hard });
+	const mm = th.map(() => 0), vv = th.map(() => 0), b1 = 0.9, b2 = 0.999;
+	let rho = 0;
+	for ( let s = 1; s <= steps; s++ ) {
+		const r = grad(pop, th, X, T, { hard }); rho = r.rho;
+		for ( let k = 0; k < th.length; k++ ) { mm[k] = b1 * mm[k] + (1 - b1) * r.grad[k]; vv[k] = b2 * vv[k] + (1 - b2) * r.grad[k] * r.grad[k]; th[k] -= lr * (mm[k] / (1 - b1 ** s)) / (Math.sqrt(vv[k] / (1 - b2 ** s)) + 1e-8); }
+	}
+	return { theta: th, loss0, loss: loss(pop, th, X, T, { hard }), rho };
+}
+
+/**
+ * Evolve the population FORM by success: grow the structure one unit at a time, training each
+ * candidate, and KEEP a larger form only while the added unit earns its keep — loss must improve by
+ * more than `margin` (a utility / MDL gate, the continuous cousin of abstraction.js). Growth stops
+ * at the parsimonious size that fits the task: too few units underfit, the right size fits, more
+ * don't pay for themselves. "Their form may need to evolve" + favor-by-success, made mechanical.
+ * @param conf.makePop (K)->population   build a population of K units (e.g. K => chainPopulation(K))
+ * @param conf.X/T      the task (inputs, targets on the readout)
+ * @param conf.K0/maxK  size bounds (default 1 .. 6)
+ * @param conf.margin   min loss improvement to justify one more unit (default 1e-3)
+ * @param conf.rngFor   (K)->rng   per-size seeded RNG (default Math.random)
+ * @returns { K, pop, theta, loss, history:[{K,loss,params}] }
+ */
+function evolve( conf ) {
+	const makePop = conf.makePop, X = conf.X, T = conf.T, maxK = conf.maxK || 6;
+	const margin = conf.margin == null ? 1e-3 : conf.margin, steps = conf.steps || 1200, lr = conf.lr || 0.05;
+	const scale = conf.initScale == null ? 0.5 : conf.initScale, rngFor = conf.rngFor || (() => Math.random), hard = !!conf.hard;
+	const history = []; let best = null, prev = Infinity;
+	for ( let K = conf.K0 || 1; K <= maxK; K++ ) {
+		const pop = makePop(K);
+		const r = train(pop, { X, T, steps, lr, hard, theta0: pop.randomParams(rngFor(K), scale) });
+		history.push({ K, loss: r.loss, params: pop.nParams });
+		if ( prev - r.loss > margin ) { best = { K, pop, theta: r.theta, loss: r.loss }; prev = r.loss; }
+		else break;                                            // utility gate: the new unit didn't pay for itself
+	}
+	return { K: best.K, pop: best.pop, theta: best.theta, loss: best.loss, history };
+}
+
+module.exports = { makePopulation, ringPopulation, chainPopulation, widePopulation, unrollPopulation, bakePopulation, loss, grad, train, evolve };

package/lib/authoring/concepts.js

@@ -0,0 +1,66 @@
+/*
+ * 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/>.
+ */
+// Builds the nested concept tree the engine expects from concepts/<set>/.
+// Engine invariants honored:
+//   - a child's key in parent.childConcepts MUST equal that child's _id
+//   - _id must be globally unique (it keys graph._conceptLib)
+//   - _name is the flag written on entities (defaults to the concept name)
+const fs = require('fs');
+const path = require('path');
+const JSON5 = require('json5');
+
+function buildConceptTree(setDir, { exclude = [] } = {}) {
+  const seenIds = new Set();
+  const reserve = (name) => {
+    if (seenIds.has(name)) throw new Error(`concept id collision: ${name}`);
+    seenIds.add(name);
+    return name;
+  };
+
+  // Build one concept from its .json file + optional sibling directory of children.
+  function build(name, filePath, childDir) {
+    const rec = JSON5.parse(fs.readFileSync(filePath, 'utf8'));
+    rec._id = reserve(name);
+    rec._name = name;
+    if (fs.existsSync(childDir) && fs.statSync(childDir).isDirectory()) {
+      const kids = {};
+      for (const f of fs.readdirSync(childDir).sort()) {
+        if (!f.endsWith('.json')) continue;
+        const cname = f.slice(0, -5);
+        if (exclude.includes(cname)) continue;
+        kids[cname] = build(cname, path.join(childDir, f), path.join(childDir, cname));
+      }
+      if (Object.keys(kids).length) rec.childConcepts = kids;
+    }
+    return rec;
+  }
+
+  // Root = a container whose children are the top-level *.json files of the set.
+  const root = {};
+  const kids = {};
+  for (const f of fs.readdirSync(setDir).sort()) {
+    if (!f.endsWith('.json')) continue;
+    const cname = f.slice(0, -5);
+    if (exclude.includes(cname)) continue;
+    kids[cname] = build(cname, path.join(setDir, f), path.join(setDir, cname));
+  }
+  root.childConcepts = kids;
+  return root;
+}
+
+module.exports = { buildConceptTree };

package/lib/authoring/context-project.js

@@ -0,0 +1,277 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * context-project — GRAPH-NATIVE CONTEXT PROJECTION (the R1 §2 "contexte par nœud", ZERO-CORE). A big roadmap
+ * does not fit one context window, so no node ever sees the whole task: each part reads its BOUNDED neighbourhood
+ * from the graph's STRUCTURE and completes its own prompt. Kill-gated on the real engine (the study
+ * `WIP/experiments/2026-07-08-graph-context-completion/` — reactive-pool.js the reference, recursive.js multi-level).
+ *
+ * THE MECHANISM (all by structure, no orchestrator):
+ *   • the roadmap is seeded as SEGMENTS + a POOL ref by the parent (versionable key-values): `available` (produced
+ *     resources), `wait_<res>` (who awaits <res>), `val_<res>` (the value). A part reads its inputs from the pool.
+ *   • a dependency is a COUNTER GATE `ensure:'$got.length == $expected'` — a producer posts its resource to the
+ *     pool and PUSHes its name into each waiter's `got`; the waiter casts when it has all of them. Arity-agnostic,
+ *     one gate. The ORDER EMERGES from the data-flow (a consumer casts strictly after its producers).
+ *   • RECURSIVE: a step with `sub` is a COMPOSITE — once its inputs are ready it seeds a SUB-pool + its sub-steps,
+ *     DOWN-PROJECTS its resolved inputs into the sub-pool (bounded context for the children), and wires the
+ *     sub-plan's TERMINAL leaf (the one that produces the composite's resource) to REPORT UP to the parent pool.
+ *   • NO RUNTIME DEADLOCK: propagation is MONOTONE + deterministic, so a stuck part is a DÉCOUPAGE BUG (a resource
+ *     awaited with no producer, or a cycle), caught OFFLINE by `guardPlan` (coverage + footprintCycles, recursive).
+ *     A mis-split never hangs (the engine goes quiescent) and never silently builds with a missing input (a leaf
+ *     gates on ALL its needs; only the down-projected ones are pre-satisfied) — it is REFUSED before seeding.
+ *   • STATELESS / VERSIONABLE → COLD-REBOOTABLE: serialize → new Graph → identical state, 0 re-fire (a completed
+ *     roadmap is a fixpoint). Follows the mutation-sequencing discipline (every change through the taskflow).
+ *
+ * USABLE À NU (domain-agnostic): the host supplies a `roadmap` of `{ id, needs, produces, sub? }` and a `serve`
+ * (the bounded work — a deterministic stub, or the C6 ladder / an LLM in production). `plan-loop.js` wires this as
+ * its REAL projection (each leaf served WITH its completed bounded context, in emergent order) in place of the
+ * abstract per-leaf map.
+ *
+ * DETERMINISM CAVEAT (measured, A3 monster harness): independent-ready leaves are served CONCURRENTLY, and the
+ * COMPLETION order of in-flight serves is a race. Values are immune (each leaf's inputs come from its own gated
+ * needs), but if a host's serve side-feeds OTHER leaves' prompts (e.g. a "DONE so far" summary channel), that
+ * prompt content becomes completion-order-dependent and replays diverge. Fix at the host: serialize the serves
+ * (`let q = Promise.resolve(); serve = (l) => (q = q.then(() => real(l)))`) — enqueue order is deterministic,
+ * and a single local model host is serial anyway, so the mutex costs nothing.
+ *
+ *   const { createContextProjection, guardPlan } = require('skynet-graph/lib/authoring/context-project');
+ *   const proj = createContextProjection({ serve: async (leaf) => callModel(leaf.prompt) });
+ *   const { order, results, refusal } = await proj.run(roadmap, ctx);
+ */
+const Graph = require('../graph/index.js');
+const { nextStable } = require('./supervise.js');
+const { footprintCycles } = require('./contract.js');
+
+// ── guardPlan — the OFFLINE deadlock guard (recursive). A level is coherent iff every `need` has a producer at
+// that level OR is inherited (down-projected from a composite's inputs), and the data-flow is acyclic. The ONLY
+// place a "deadlock" can live is a bad split; this converts a silent starve into a typed refusal BEFORE seeding. ──
+function guardPlan( roadmap, inherited ) {
+	inherited = inherited || [];
+	const producers = new Set(roadmap.map(( s ) => s.produces ).concat(inherited));
+	const uncovered = [], cycles = [];
+	const methodOf = ( s ) => ({ name: s.id, contract: { read: (s.needs || []).filter(( n ) => !inherited.includes(n) ), write: [s.produces], effect: 'effect' } });
+	cycles.push(...footprintCycles(roadmap.map(methodOf)));
+	for ( const s of roadmap ) {
+		for ( const n of (s.needs || []) ) if ( !producers.has(n) ) uncovered.push({ step: s.id, need: n });
+		if ( s.sub ) {
+			if ( !s.sub.some(( c ) => c.produces === s.produces ) ) uncovered.push({ step: s.id, need: '(no sub-terminal produces ' + s.produces + ')' });
+			const sub = guardPlan(s.sub, s.needs);                        // the composite's inputs are available DOWN in the sub-plan
+			uncovered.push(...sub.uncovered); cycles.push(...sub.cycles);
+		}
+	}
+	return { ok: uncovered.length === 0 && cycles.length === 0, uncovered, cycles };
+}
+
+// ── the concept map: a leaf STEP (counter gate → serve → post + notify [+ report up]) and a COMPOSITE DECOMPOSE
+// (counter gate on inputs → seed the sub-plan). One-shot casts guarded by the `_name` marker (re-fire guard). ──
+const CONCEPT_MAP = { common: { childConcepts: {
+	Task: { _id: 'Task', _name: 'Task', require: 'Segment', childConcepts: {
+		Step:      { _id: 'Step',      _name: 'Step',      require: ['Task', 'isStep'],      ensure: ['$got.length == $expected'], provider: ['CtxProj::step'] },
+		Decompose: { _id: 'Decompose', _name: 'Decompose', require: ['Task', 'isComposite'], ensure: ['$got.length == $expected'], provider: ['CtxProj::decompose'] },
+	} }
+} } };
+
+// default prompt completion — the bounded neighbourhood: the ancestor statement + the resolved inputs + the goal
+// to produce. An input whose key has a `ctx.labels` entry is rendered WITH its provenance label (the "cells" rule,
+// givens.js#labelsOf — structured provenance only; measured: fixes mis-localization, never label prose).
+function defaultComplete( leaf ) {
+	const lbl = leaf.labels || {};
+	const inputs = Object.keys(leaf.inputs).map(( k ) => k + '=' + leaf.inputs[k] + (lbl[k] ? ' (' + lbl[k] + ')' : '') );
+	return 'GOAL ' + leaf.statement + (inputs.length ? ' · USE ' + inputs.join(',') : ' · (root)')
+		+ (leaf.reportsUp ? ' · REPORT-UP ' + leaf.produces : '') + ' · PRODUCE ' + leaf.produces;
+}
+
+// deterministic prose title — the first sentence, truncated (never invented; A3 owner-spec roadmap).
+function proseTitle( s, cap ) {
+	const first = (String(s || '').match(/^[^.!?]*[.!?]/) || [String(s || '')])[0].trim();
+	return first.length > cap ? first.slice(0, cap).trim() + '…' : first;
+}
+
+// ── stratComplete — the STRATIFIED leaf rendering, promoted from the A3 monster harness (opt-in via
+// opts.complete; the default stays defaultComplete). Each LEVEL gets the regime measured best for it:
+//   • leaves inside a composite (and flat levels)  = CONTEXT (the parent statement) + DONE (already-served
+//     level siblings, `key = value (nl…)`) + TASK — the "chainsum" regime (A3: 58/80 vs base 50/80);
+//   • leaves of a level that CONTAINS composites   = CONTEXT + the ROADMAP view (every level step with its
+//     instruction and produced value `[done]`/`[todo]`, composites folded to their statement title, the
+//     current step marked `>>x<< [YOU ARE HERE]` + a scope guard) — the integrator USES it (A3 NEG:
+//     a lying roadmap breaks finals), calculation leaves ignore it, hence the stratification.
+// The wording below is the CANONICAL FORM p0 — measured form-ROBUST by the K-paraphrases harness
+// (`WIP/experiments/2026-07-12-k-paraphrases/`: 4 full re-wordings → sections mean 56.3/80 ± 1.5, min 55,
+// vs base 50; integration mean 4.7/20 vs base 3, never below). The INFORMATION carries the gain, not the
+// tokens — so the form is FROZEN (anti-butterfly: never re-phrase per task, never tune the wording).
+// DONE/ROADMAP read level state at serve time → they require SERIALIZED serves (see the determinism
+// caveat in the header) for replay-stable prompts.
+function stratComplete( leaf ) {
+	const lbl = leaf.labels || {};
+	const inputs = Object.keys(leaf.inputs || {}).map(( k ) => k + ' = ' + leaf.inputs[k] + (lbl[k] ? ' (' + lbl[k] + ')' : '') );
+	const parts = [];
+	if ( leaf.statement ) parts.push('CONTEXT: ' + leaf.statement);
+	const plan = leaf.plan || [];
+	if ( leaf.level === 'top' && plan.some(( p ) => p.composite ) ) {                     // integration level → ROADMAP view
+		const lines = ['PLAN:'];
+		for ( const p of plan ) {
+			const head = p.composite && p.statement ? p.key + ' ("' + proseTitle(p.statement, 72) + '")'
+				: (p.current ? '>>' + p.key + '<<' : p.key) + (p.nl ? ' (' + String(p.nl).slice(0, 90) + ')' : '');
+			lines.push('  ' + head + (p.value !== undefined ? ' = ' + p.value + ' [done]' : (p.current ? ' [YOU ARE HERE]' : ' [todo]')));
+		}
+		parts.push(lines.join('\n') + '\nYou are at the marked >>step<<. Solve ONLY that step; everything else is out of your scope.');
+	} else if ( (leaf.done || []).length )
+		parts.push('DONE: ' + leaf.done.map(( d ) => d.key + ' = ' + d.value + (d.nl ? ' (' + String(d.nl).split(/\s+/).slice(0, 8).join(' ') + ')' : '') ).join(' · '));
+	parts.push('TASK: ' + (leaf.nl || 'produce ' + leaf.produces) + (inputs.length ? ' Given: ' + inputs.join(' ; ') + '.' : ''));
+	return parts.join('\n');
+}
+
+// build the seed for the TOP level (a parent énoncé + a pool ref by it, pre-populated with the wait index).
+// `givens` ({ key: value }, optional) = the task's BASE FACTS (givens.js front-door): seeded as already-available
+// `val_<key>` pool entries, and every step's given-needs are PRE-SATISFIED (counted in `got` like a down-projected
+// input) — the same inherited semantics as a composite's down-projection, applied at the top level.
+function buildSeed( roadmap, statement, givens ) {
+	givens = givens || {};
+	// _seed = the pre-satisfied entries (to tell "already available" from "produced so far" — leaf.done) ·
+	// _plan = the level skeleton (id/key/nl/composite/statement — leaf.plan, the roadmap-view source). Inert data.
+	const pool = { _id: 'POOL', _isPool: true, available: Object.keys(givens), _seed: Object.keys(givens),
+		_plan: roadmap.map(( s ) => ({ id: s.id, key: s.produces, nl: s.nl || '', composite: !!s.sub, statement: s.statement || '' }) ) };
+	Object.keys(givens).forEach(( g ) => { pool['val_' + g] = givens[g]; });
+	roadmap.forEach(( s ) => { pool['wait_' + s.produces] = pool['wait_' + s.produces] || []; });
+	roadmap.forEach(( s ) => (s.needs || []).filter(( n ) => !(n in givens) ).forEach(( n ) => { (pool['wait_' + n] = pool['wait_' + n] || []).push(s.id); }) );
+	const nodes = [{ _id: 'nRoot', Node: true }, pool];
+	const segments = [{ _id: 'PARENT', Segment: true, originNode: 'nRoot', targetNode: 'nRoot', statement: statement, pool: 'POOL' }];
+	roadmap.forEach(( s ) => {
+		nodes.push({ _id: 'a_' + s.id, Node: true }, { _id: 'b_' + s.id, Node: true });
+		const seg = { _id: s.id, Segment: true, originNode: 'a_' + s.id, targetNode: 'b_' + s.id, parentSeg: 'PARENT',
+			pool: 'POOL', needs: s.needs || [], produces: s.produces, expected: (s.needs || []).length,
+			got: (s.needs || []).filter(( n ) => n in givens ) };
+		if ( s.slot ) seg.slot = s.slot;                             // carry the method-slot (higher-order need) to the leaf — inert data, like `sub`
+		if ( s.nl != null ) seg.nl = s.nl;                           // step instruction + level statement (strat rendering) — inert data too
+		if ( s.statement != null ) seg.statement = s.statement;
+		if ( s.sub ) { seg.isComposite = true; seg.sub = s.sub; } else seg.isStep = true;
+		segments.push(seg);
+	});
+	return { lastRev: 0, nodes, segments };
+}
+
+// enumerate every id in the roadmap tree (top + all sub levels) — for collecting results incl. runtime sub-steps.
+function allSteps( roadmap ) { return roadmap.flatMap(( s ) => [s].concat(s.sub ? allSteps(s.sub) : []) ); }
+
+function makeProviders( serve, complete, ctx, order ) {
+	return { CtxProj: {
+		// LEAF — read bounded inputs from own pool, SERVE (the injected bounded work), post to own pool + notify, report up if terminal.
+		step: function ( graph, concept, scope, argz, cb ) {
+			(async () => {
+				const self = scope._, pool = graph.getEtty(self.pool)._;
+				const inputs = {}; (self.needs || []).forEach(( n ) => { inputs[n] = pool['val_' + n]; });
+				// the LEVEL state read on the structure (strat rendering; additive — hosts ignoring them see no change):
+				// done = level entries produced so far (available beyond _seed, emergent order) · plan = the level
+				// skeleton with current values + the own-step marker · level = top vs inside-a-composite.
+				const seedSet = new Set(pool._seed || pool.available || []);
+				const nlOf = {}; (pool._plan || []).forEach(( p ) => { nlOf[p.key] = p.nl; });
+				const done = (pool.available || []).filter(( k ) => !seedSet.has(k) )
+					.map(( k ) => ({ key: k, value: pool['val_' + k], nl: nlOf[k] || '' }) );
+				const plan = (pool._plan || []).map(( p ) => Object.assign({}, p, { value: pool['val_' + p.key], current: p.id === self._id }) );
+				const leaf = { id: self._id, statement: graph.getEtty(self.parentSeg)._.statement, produces: self.produces,
+					needs: self.needs || [], inputs: inputs, reportsUp: !!self.up_res, slot: self.slot,
+					nl: self.nl, level: self.parentSeg === 'PARENT' ? 'top' : 'sub', done: done, plan: plan,
+					labels: (ctx && ctx.labels) || {} };
+				const prompt = complete(leaf);
+				let value;
+				try { value = await serve(Object.assign({ prompt: prompt }, leaf), ctx); }
+				catch ( e ) { return cb(e); }
+				order.push(self._id);
+				const tpl = [ { $_id: '_parent', Step: true, prompt: prompt, out: value } ];
+				tpl.push({ $$_id: self.pool, available: { __push: self.produces }, ['val_' + self.produces]: value });
+				(pool['wait_' + self.produces] || []).forEach(( wid ) => tpl.push({ $$_id: wid, got: { __push: self.produces } }) );
+				if ( self.up_res ) {                                                      // REMONTÉE — deliver to the parent pool + notify parent waiters
+					tpl.push({ $$_id: self.up_pool, available: { __push: self.up_res }, ['val_' + self.up_res]: value });
+					(self.up_wait || []).forEach(( wid ) => tpl.push({ $$_id: wid, got: { __push: self.up_res } }) );
+				}
+				cb(null, tpl);
+			})();
+		},
+		// COMPOSITE — inputs ready → seed a SUB-pool ref by me + my sub-steps, DOWN-project my inputs, wire the terminal UP.
+		decompose: function ( graph, concept, scope, argz, cb ) {
+			const self = scope._, pool = graph.getEtty(self.pool)._, sub = self.sub, SUB = 'SUBPOOL_' + self._id;
+			order.push(self._id + ':decompose');
+			const subProducers = new Set(sub.map(( c ) => c.produces ));
+			const downSet = new Set(self.needs || []);
+			const subPool = { _id: SUB, _isPool: true, available: (self.needs || []).slice(), _seed: (self.needs || []).slice(),
+				_plan: sub.map(( c ) => ({ id: c.id, key: c.produces, nl: c.nl || '', composite: !!c.sub, statement: c.statement || '' }) ) };
+			(self.needs || []).forEach(( n ) => { subPool['val_' + n] = pool['val_' + n]; });   // ← down-projection (bounded ctx for children)
+			sub.forEach(( c ) => { subPool['wait_' + c.produces] = subPool['wait_' + c.produces] || []; });
+			sub.forEach(( c ) => (c.needs || []).filter(( n ) => subProducers.has(n) ).forEach(( n ) => subPool['wait_' + n].push(c.id) ) );
+			const tpl = [ { $_id: '_parent', Decompose: true, prompt: complete({ id: self._id, statement: graph.getEtty(self.parentSeg)._.statement, produces: self.produces, needs: self.needs || [], inputs: {}, reportsUp: false }) }, subPool ];
+			sub.forEach(( c ) => {
+				// a runtime-created node needs Node:true (else it lands as a generic record with no _outgoing → relink throws).
+				tpl.push({ _id: 'a_' + c.id, Node: true }, { _id: 'b_' + c.id, Node: true });
+				// gate on ALL needs; pre-fill `got` with the down-projected (already-satisfied) inputs → an uncovered
+				// need stays in `expected` but never enters `got` (visible famine, not a silent build).
+				const preGot = (c.needs || []).filter(( n ) => downSet.has(n) );
+				const seg = { _id: c.id, Segment: true, originNode: 'a_' + c.id, targetNode: 'b_' + c.id, parentSeg: self._id,
+					pool: SUB, needs: c.needs || [], produces: c.produces, expected: (c.needs || []).length, got: preGot.slice() };
+				if ( c.slot ) seg.slot = c.slot;                                          // carry a nested method-slot down the recursion too
+				if ( c.nl != null ) seg.nl = c.nl;                                        // strat rendering metadata, inert
+				if ( c.statement != null ) seg.statement = c.statement;
+				if ( c.sub ) { seg.isComposite = true; seg.sub = c.sub; } else seg.isStep = true;   // deeper recursion supported
+				if ( c.produces === self.produces ) {                                     // the TERMINAL → report UP to the parent pool
+					seg.up_pool = self.pool; seg.up_res = self.produces; seg.up_wait = (pool['wait_' + self.produces] || []).slice();
+				}
+				tpl.push(seg);
+			});
+			cb(null, tpl);
+		},
+	} };
+}
+
+/**
+ * createContextProjection(opts) — build a reusable projection.
+ * @param opts.serve    async (leaf, ctx) => value  REQUIRED. leaf = { id, statement, produces, needs, inputs, prompt,
+ *        reportsUp, nl, level ('top'|'sub'), done ([{key,value,nl}] level results so far), plan (the level skeleton
+ *        with values + the own-step marker) } — the structural fields feed strat rendering, hosts may ignore them.
+ * @param opts.complete (leaf) => promptString      the bounded prompt (default: statement · USE inputs · PRODUCE;
+ *        `stratComplete` exported = the stratified CONTEXT/DONE/ROADMAP rendering measured on the A3 monster
+ *        harness + the K-paraphrases gate — opt-in, canonical form frozen).
+ * @param opts.label    graph label.
+ * Roadmap steps may carry `nl` (the step instruction) and — on composites — `statement` (the sub-level énoncé):
+ * inert metadata, read by the strat rendering (a sub leaf's `statement` = its composite's, top = ctx.statement).
+ * ctx.givens = { key: value } base facts (givens.js#seedOf) · ctx.labels = { key: label } provenance labels
+ * (givens.js#labelsOf — structured provenance only), rendered by defaultComplete next to each labelled input.
+ * @returns { run(roadmap, ctx), guardPlan, conceptMap, buildSeed }
+ */
+function createContextProjection( opts ) {
+	opts = opts || {};
+	if ( typeof opts.serve !== 'function' ) throw new Error('createContextProjection needs opts.serve(leaf,ctx) -> value');
+	const complete = opts.complete || defaultComplete;
+	const label = opts.label || 'context-projection';
+
+	async function run( roadmap, ctx ) {
+		const statement = (ctx && ctx.statement) || 'ROADMAP';
+		const givens = (ctx && ctx.givens) || {};                                        // the task's base facts (givens.js) — inherited at the top level
+		const guard = guardPlan(roadmap, Object.keys(givens));
+		if ( !guard.ok ) return { order: [], results: {}, refusal: guard.cycles.length ? 'CYCLE' : 'UNCOVERED', guard, graph: null };
+		const order = [];
+		const saved = Graph._providers;                                                  // forge idiom: set globally, restore in finally
+		Graph._providers = Object.assign({}, saved, makeProviders(opts.serve, complete, ctx, order));
+		let g;
+		try {
+			g = new Graph(buildSeed(roadmap, statement, givens), { label: label, isMaster: true, autoMount: true, conceptSets: ['common'], bagRefManagers: {} }, CONCEPT_MAP);
+			await nextStable(g);
+		} finally { Graph._providers = saved; }
+		// collect completed contexts (stable roadmap order — NOT the async cast order — so the result is deterministic)
+		const results = {};
+		for ( const s of allSteps(roadmap) ) {
+			const e = g.getEtty(s.id), f = e && e._;
+			if ( f && f.Step === true ) results[s.id] = { kind: 'leaf', value: f.out, prompt: f.prompt, needs: s.needs || [], produces: s.produces };
+			else if ( f && f.Decompose === true ) results[s.id] = { kind: 'composite', prompt: f.prompt, produces: s.produces };
+			else results[s.id] = { kind: 'starved', needs: s.needs || [], produces: s.produces };   // a mis-split part that never gated (guardPlan should have caught it)
+		}
+		return { order, results, refusal: null, guard, graph: g };
+	}
+
+	return { run: run, guardPlan: guardPlan, conceptMap: CONCEPT_MAP, buildSeed: buildSeed, complete: complete };
+}
+
+module.exports = { createContextProjection, guardPlan, defaultComplete, stratComplete, buildSeed, CONCEPT_MAP, makeProviders, allSteps };