skynet-graph 1.2.0

package/lib/authoring/equilibrium.js

@@ -0,0 +1,160 @@
+/*
+ * 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';
+/**
+ * equilibrium — implicit differentiation through a forward-chaining FIXPOINT (the DEQ method),
+ * for learning across the COMPOSITE concept topology. Host-side, ZERO-CORE. Study
+ * doc/WIP/studies/2026-06-26-concepts-dynamiques-grammaire-induction.md; theory brief = Laurie.
+ *
+ * The engine's stabilization is a Picard iteration z_{t+1}=F(z_t,θ) driven to a fixpoint
+ * z*=F(z*,θ). To train params θ that live inside concept-nets, we want dL(z*)/dθ WITHOUT
+ * differentiating through the iteration. Differentiate the fixpoint condition instead
+ * (Almeida/Pineda 1987; DEQ, Bai-Kolter-Koltun 2019):
+ *
+ *   J_z := ∂F/∂z |_{z*}   (n×n)        J_θ := ∂F/∂θ |_{z*}   (n×p)   — ONE sweep, at z*
+ *   dz* / dθ = (I − J_z)^{-1} J_θ
+ *   dL/dθ  = (∇_z L) (I − J_z)^{-1} J_θ
+ *
+ * Reverse mode (never form the inverse): solve the adjoint (I − J_z)^T u = ∇_z L once, then
+ * dL/dθ = J_θ^T u. Well-posed iff ρ(J_z) < 1 (the contraction that also makes the forward
+ * fixpoint exist & be unique). Neumann: (I − J_z)^{-1} = Σ_k J_z^k, so u_K = Σ_{k≤K}(J_z^T)^k g
+ * — the truncation depth K is the exact analogue of the engine's apply-cap, and its bias ~ρ^K
+ * binds precisely as ρ→1. This module is the differentiable MIRROR of the composite topology;
+ * the real engine stays discrete (a trained net is baked back via ste.js, STE at the boundary).
+ *
+ *   const fp = solveFixpoint((z) => F(z, θ, x), z0, { maxIter, tol });
+ *   const { grad } = implicitGrad(jacZ(fp.z), jacTheta(fp.z), gradL, { mode: 'direct' });
+ */
+
+// ---- small dense linear algebra (POC scale, n ≲ tens — a direct solve is free) ----
+
+// Solve A u = b by Gaussian elimination with partial pivoting. A is n×n (row-major), b is n.
+function solveLinear( A, b ) {
+	const n = b.length, M = A.map((row, i) => row.slice().concat(b[i]));   // augmented
+	for ( let col = 0; col < n; col++ ) {
+		let piv = col;
+		for ( let r = col + 1; r < n; r++ ) if ( Math.abs(M[r][col]) > Math.abs(M[piv][col]) ) piv = r;
+		if ( Math.abs(M[piv][col]) < 1e-300 ) throw new Error('equilibrium: singular system (I − J_z not invertible; ρ ≥ 1?)');
+		if ( piv !== col ) { const tmp = M[piv]; M[piv] = M[col]; M[col] = tmp; }
+		for ( let r = 0; r < n; r++ ) {
+			if ( r === col ) continue;
+			const f = M[r][col] / M[col][col];
+			for ( let c = col; c <= n; c++ ) M[r][c] -= f * M[col][c];
+		}
+	}
+	return M.map((row, i) => row[n] / row[i]);
+}
+
+// (J^T v)[i] = Σ_j J[j][i] v[j]   — transpose-times-vector (J is r×c, v is r → c-vector)
+function matTvec( J, v ) {
+	const r = J.length, c = r ? J[0].length : 0, out = new Array(c).fill(0);
+	for ( let i = 0; i < r; i++ ) for ( let j = 0; j < c; j++ ) out[j] += J[i][j] * v[i];
+	return out;
+}
+
+/**
+ * Picard iteration to a fixpoint z* = F(z*). Faithful to the engine's stabilization sweep.
+ * @returns { z, iters, residual, converged }  residual = max|z_{t+1} − z_t|.
+ */
+function solveFixpoint( F, z0, opts ) {
+	opts = opts || {};
+	const maxIter = opts.maxIter || 1000, tol = opts.tol == null ? 1e-12 : opts.tol;
+	let z = z0.slice(), iters = 0, residual = Infinity;
+	for ( ; iters < maxIter; ) {
+		const zn = F(z);
+		residual = 0;
+		for ( let i = 0; i < zn.length; i++ ) residual = Math.max(residual, Math.abs(zn[i] - z[i]));
+		z = zn; iters++;
+		if ( residual < tol ) break;
+	}
+	return { z: z, iters: iters, residual: residual, converged: residual < tol };
+}
+
+/**
+ * Implicit (DEQ) gradient dL/dθ = J_θ^T u where (I − J_z)^T u = gradL.
+ * @param Jz     ∂F/∂z at z*  (n×n)
+ * @param Jtheta ∂F/∂θ at z*  (n×p)
+ * @param gradL  ∇_z L at z*  (n)
+ * @param opts.mode  'direct' (dense solve, the gold value) | { neumann: K } (truncated series)
+ * @returns { grad (p), u (n) }
+ */
+function implicitGrad( Jz, Jtheta, gradL, opts ) {
+	opts = opts || {};
+	const n = gradL.length;
+	let u;
+	if ( opts.mode && opts.mode.neumann != null ) {
+		// u = Σ_{k=0..K} (Jz^T)^k gradL  — each step is one VJP v ↦ Jz^T v (Jacobian-free)
+		const K = opts.mode.neumann;
+		u = gradL.slice();
+		let term = gradL.slice();
+		for ( let k = 0; k < K; k++ ) {
+			term = matTvec(Jz, term);                       // Jz^T · term
+			for ( let i = 0; i < n; i++ ) u[i] += term[i];
+		}
+	} else {
+		// direct: A = (I − Jz)^T,  A[i][j] = δ_ij − Jz[j][i]
+		const A = [];
+		for ( let i = 0; i < n; i++ ) { const row = new Array(n); for ( let j = 0; j < n; j++ ) row[j] = (i === j ? 1 : 0) - Jz[j][i]; A.push(row); }
+		u = solveLinear(A, gradL);
+	}
+	return { grad: matTvec(Jtheta, u), u: u };
+}
+
+/**
+ * Central finite-difference Jacobian of fn: R^d → R^n, returned as n×d. The general way to get
+ * J_z / J_θ of one composite sweep F without hand-deriving per-unit VJPs — at POC scale (n,d ≲
+ * tens) it's cheap and exact-to-O(ε²). For an STE (hard-gate) population, feed it the SOFT sweep
+ * (sigmoid gates) at z* — that IS the straight-through surrogate Jacobian for the backward.
+ */
+function numJac( fn, point, eps ) {
+	eps = eps || 1e-6;
+	const d = point.length, f0 = fn(point), n = f0.length;
+	const J = Array.from({ length: n }, () => new Array(d));
+	for ( let k = 0; k < d; k++ ) {
+		const a = point.slice(), b = point.slice(); a[k] += eps; b[k] -= eps;
+		const fa = fn(a), fb = fn(b);
+		for ( let i = 0; i < n; i++ ) J[i][k] = (fa[i] - fb[i]) / (2 * eps);
+	}
+	return J;
+}
+
+/**
+ * Spectral radius of J_z — the regime instrument (ρ→1 ⇒ slow forward, deep Neumann, large
+ * gradient). Estimated as the geometric-mean growth rate ρ = lim ‖J_z^k v‖^{1/k} (a normalized
+ * power iteration averaging the per-step log-growth). Unlike a last-step power-iteration estimate
+ * this is correct when the dominant eigenvalues are TIED in magnitude or complex — e.g. the cycle
+ * J_z=[[0,b],[c,0]] has eigenvalues ±√(b·c) (equal magnitude), where the per-step factors form a
+ * 2-cycle whose geometric mean is exactly √(b·c).
+ */
+function spectralRadius( Jz, opts ) {
+	opts = opts || {};
+	const iters = opts.iters || 100, burn = opts.burn == null ? Math.floor((opts.iters || 100) / 2) : opts.burn, n = Jz.length;
+	const matVec = (M, v) => M.map((row) => row.reduce((s, m, j) => s + m * v[j], 0));
+	let v = new Array(n).fill(0).map((_, i) => 1 / Math.sqrt(n) + 1e-3 * (i % 2 ? -1 : 1));  // off-axis seed
+	let sumLog = 0, count = 0;
+	for ( let k = 0; k < iters; k++ ) {
+		const w = matVec(Jz, v);
+		const norm = Math.sqrt(w.reduce((s, x) => s + x * x, 0));
+		if ( norm < 1e-300 ) return 0;
+		if ( k >= burn ) { sumLog += Math.log(norm); count++; }
+		v = w.map((x) => x / norm);
+	}
+	return count ? Math.exp(sumLog / count) : 0;
+}
+
+module.exports = { solveFixpoint, implicitGrad, spectralRadius, solveLinear, matTvec, numJac };

package/lib/authoring/extract.js

@@ -0,0 +1,153 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * extract — BOUNDED SUBGRAPH EXTRACTION for fork / multi-process ship (host-side, ZERO-CORE; the 2026-07-01 fork-perf
+ * measure + Laurie confront, verdict SOUND-WITH-CORRECTION).
+ *
+ * WHY. `fork()` with no seed deep-copies the WHOLE working graph (`JSON.parse(serialize().graph)`) then re-mounts it.
+ * Measured (`doc/WIP/experiments/2026-07-01-fork-perf/`): the deep-copy is O(working-graph) and a bounded-seed fork is
+ * 27–245× cheaper (growing with N). The lever for the MULTI-PROCESS/worker case (`lib/runtime` ships a seed to a
+ * separate process — no shared memory) is shipping a bounded SLICE, not the whole graph. COW can't help cross-process.
+ *
+ * WHAT. This is PROGRAM SLICING (Weiser 1984) on the reference-dependence graph: `focus` is the slicing criterion; a
+ * ship-able slice is a CLOSED backward slice with its free variables FROZEN as inputs. A segment-closed **k-hop ball**
+ * (`opts.hops`, default 1): the interior grows by (hops-1) BFS rings from the focus + all their incident segments; the
+ * segments' non-interior endpoints are the FROZEN frontier (their current facts copied as constants). Sound iff the
+ * frozen frontier is FRAME-COMPLETE — `contract.js` G1 applied at the fork boundary: every
+ * cross-cut reference reads a frozen value, none is WRITTEN by the slice. Merge-back = SINGLE-WRITER (separation-logic
+ * `*`-disjointness; Reynolds 2002) + an ASSUMPTION-RECHECK (the frozen frontier still holds at merge time — the
+ * drift-defeasance moved to the fork frontier; de Kleer ATMS 1986: the frozen frontier is the assumption environment).
+ *
+ * The seed is a `serialize()`-shaped record (`{ lastRev, conceptMaps:[{...facts}], bagRefs }`) → `graph.fork(seed)`
+ * locally OR `spawnGraph({ seed })` to a worker. `lib/graph` is UNTOUCHED.
+ *
+ * DEFERRED / refused (Laurie): a cyclic cross-cut ref (contract G3 footprint-cycle — refuse), a bagRef spanning the cut
+ * (needs manager replication), a not-yet-materialized cross-cut producer (the frame-problem impossible case — refuse),
+ * multi-writer frontier (the ATMS multi-context, FILED §6.1); the horizon gate on the precise cross-cut-REF facts (v0
+ * gates all frontier facts).
+ */
+const factsOf = ( graph, id ) => { const o = graph._objById[id]; return o && o._etty && o._etty._; };
+const idOf = ( o ) => o && (o.$$_id != null ? o.$$_id : (o.$_id != null ? o.$_id : o._id));
+
+/**
+ * Extract a bounded, ship-able subgraph around `focus`.
+ * @param graph  the parent graph.
+ * @param focus  a node id / segment id / array of ids (the slicing criterion). A focus segment contributes its
+ *               endpoints as focus nodes.
+ * @param opts.tree   optional concept tree → run `separatorGate` on the frozen-frontier facts (horizon check).
+ * @param opts.refuseAboveHorizon  throw if a frozen frontier fact is above Σ_sep (default false → reported only).
+ * @returns { seed, interior, segments, frontier, frozen, focusNodes, horizonOk?, aboveHorizon? }
+ */
+function extractSubgraph( graph, focus, opts ) {
+	opts = opts || {};
+	const focusIds = Array.isArray(focus) ? focus.slice() : [focus];
+	const focusNodes = new Set(), focusSegs = new Set();
+	for ( const id of focusIds ) {
+		const f = factsOf(graph, id);
+		if ( !f ) throw new Error('extractSubgraph: unknown focus id "' + id + '"');
+		if ( f.Segment ) { focusSegs.add(id); if ( f.originNode ) focusNodes.add(f.originNode); if ( f.targetNode ) focusNodes.add(f.targetNode); }
+		else focusNodes.add(id);
+	}
+	// segment-closed k-hop ball. `hops` (default 1) = the INTERIOR radius: grow the interior by (hops-1) rings of nodes
+	// (BFS over incident segments), then include every segment incident to an interior node; a segment's endpoint NOT in
+	// the interior is a FROZEN frontier node (the boundary, pinned). hops=1 → interior={focus}, frontier=1-hop neighbours
+	// (byte-identical to v0); hops=2 → interior=focus+1-hop, frontier=2-hop; etc.
+	const hops = opts.hops == null ? 1 : Math.max(1, opts.hops | 0);
+	const incidentOf = ( n ) => { const node = graph._objById[n]; return [].concat((node && node._outgoing) || [], (node && node._incoming) || []); };
+	const interiorNodes = new Set(focusNodes);
+	let ring = new Set(focusNodes);
+	for ( let d = 0; d < hops - 1; d++ ) {                       // grow the interior by (hops-1) BFS rings
+		const next = new Set();
+		for ( const n of ring ) for ( const sid of incidentOf(n) ) {
+			const sf = factsOf(graph, sid) || {};
+			for ( const end of [sf.originNode, sf.targetNode] ) if ( end && !interiorNodes.has(end) ) { interiorNodes.add(end); next.add(end); }
+		}
+		ring = next;
+		if ( !ring.size ) break;                                // the component is fully inside the ball
+	}
+	// include every segment incident to an interior node; non-interior endpoints become the frozen frontier.
+	const segs = new Set(focusSegs), frontierNodes = new Set();
+	for ( const n of interiorNodes ) for ( const sid of incidentOf(n) ) {
+		segs.add(sid);
+		const sf = factsOf(graph, sid) || {};
+		for ( const end of [sf.originNode, sf.targetNode] ) if ( end && !interiorNodes.has(end) ) frontierNodes.add(end);
+	}
+	// freeze = copy the raw facts of every slice object (interior nodes + incident segments + frozen frontier nodes).
+	const sliceIds = [...interiorNodes, ...segs, ...frontierNodes];
+	const conceptMaps = sliceIds.map(( id ) => ({ ...factsOf(graph, id) }));
+	const frozen = {}; for ( const n of frontierNodes ) frozen[n] = { ...factsOf(graph, n) };
+
+	const extraction = {
+		seed: { lastRev: graph.getCurrentRevision ? graph.getCurrentRevision() : 0, conceptMaps, bagRefs: {} },
+		interior: [...interiorNodes], segments: [...segs], frontier: [...frontierNodes], frozen, focusNodes: [...focusNodes], focusSegs: [...focusSegs],
+	};
+	// horizon gate (optional): every frozen frontier FACT must be on the separator horizon (Σ_sep) or the bound regresses.
+	if ( opts.tree ) {
+		const { separatorGate } = require('./decompose.js');
+		const facts = {};
+		for ( const n of frontierNodes ) for ( const k of Object.keys(frozen[n]) ) if ( k !== '_id' && k !== '_rev' ) facts[k] = true;
+		const gate = separatorGate(opts.tree, Object.keys(facts));
+		extraction.horizonOk = gate.ok; extraction.aboveHorizon = gate.above;
+		if ( !gate.ok && opts.refuseAboveHorizon ) throw new Error('extractSubgraph: frozen frontier facts above Σ_sep: ' + gate.above.join(','));
+	}
+	return extraction;
+}
+
+/**
+ * The interior-only footprint of a merge template: the ids it writes. SOUND merge writes ONLY interior/focus ids —
+ * NEVER a frozen frontier id (that is a write across the cut → the ATMS multi-context contradiction). `$$_id` / `$_id`
+ * targets an existing object; a bare `_id` creates a new one (also fine — not a frontier write).
+ */
+function templateWrites( tpl ) {
+	return (Array.isArray(tpl) ? tpl : [tpl]).map(( o ) => o && (o.$$_id != null ? o.$$_id : (o.$_id != null ? o.$_id : null))).filter(( x ) => x != null);
+}
+
+/**
+ * Merge a bounded-slice worker/child result back into the parent — SOUNDLY.
+ *   1. ASSUMPTION-RECHECK: every frozen frontier fact must still equal the parent's current value (else the slice
+ *      stabilized on a dead premise → REJECT and re-run; the drift-defeasance at the fork frontier).
+ *   2. SINGLE-WRITER: the project template must write ONLY interior ids, never a frozen frontier id (separation-logic
+ *      disjointness) → else REJECT (the multi-writer/ATMS hazard).
+ *   3. apply via the sequenced taskflow (`pushMutation`) — never out-of-band.
+ * @param parent  the parent graph.
+ * @param child   the settled fork/worker child (or, cross-process, a plain object with `_objById`-like access via `factsGetter`).
+ * @param extraction  the object returned by `extractSubgraph`.
+ * @param opts.project  (child) -> mutationTemplate; default = write back the focus objects' produced facts onto their ids.
+ * @param opts.factsGetter  (child, id) -> facts; default reads `child._objById[id]._etty._` (override for a cross-process JSON child).
+ * @returns { merged:true, template } | { merged:false, reason }
+ */
+function mergeSlice( parent, child, extraction, opts ) {
+	opts = opts || {};
+	const getFacts = opts.factsGetter || (( c, id ) => factsOf(c, id));
+	// (1) assumption-recheck — frozen frontier unchanged in the parent.
+	for ( const n of extraction.frontier ) {
+		const now = factsOf(parent, n) || {}, was = extraction.frozen[n] || {};
+		for ( const k of Object.keys(was) ) {
+			if ( k === '_id' || k === '_rev' ) continue;
+			if ( JSON.stringify(now[k]) !== JSON.stringify(was[k]) ) return { merged: false, reason: 'frontier drift: ' + n + '.' + k + ' changed since extraction' };
+		}
+	}
+	// build the write-back template (default = focus objects' current child facts, minus volatile markers).
+	const project = opts.project || function ( c ) {
+		return extraction.focusNodes.concat(extraction.focusSegs).map(function ( id ) {
+			const f = getFacts(c, id) || {}; const o = { $$_id: id };
+			for ( const k of Object.keys(f) ) if ( k !== '_id' && k !== '_rev' && k !== '_origin' ) o[k] = f[k];
+			return o;
+		});
+	};
+	const tpl = project(child);
+	// (2) single-writer — the template must not write a frozen frontier id.
+	const frontierSet = new Set(extraction.frontier);
+	const badWrite = templateWrites(tpl).find(( id ) => frontierSet.has(id) );
+	if ( badWrite ) return { merged: false, reason: 'single-writer violation: template writes frontier object "' + badWrite + '"' };
+	// (3) apply through the sequenced taskflow.
+	parent.pushMutation(tpl);
+	return { merged: true, template: tpl };
+}
+
+module.exports = { extractSubgraph, mergeSlice, templateWrites };

package/lib/authoring/forest.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * forest — THE MULTI-PATH GENERALIZATION (roadmap 2026-07-09 §5(c); ZERO-CORE). The concept-method as a LIBRARY of
+ * alternative sub-paths (the derivation forest): "au moins un chemin complète, un seul reste actif". Re-opened now
+ * that the single-path P1-P6 + the transitivity (KG-PROXY-2) hold — the single-path is the degenerate forest.
+ *
+ * `makeForestServe({ forests, candidates, pool, forge? })` → a projection `serve(leaf)`: for a leaf, try its candidate
+ * sub-paths IN PREFERENCE ORDER; the FIRST that dispatches + mounts + GATES sound (P1/P3/P4) is SELECTED — the rest are
+ * never activated. That selection IS the confluence guarantee that dodges G3 (`footprintCycles`): we SELECT one path,
+ * we never COMPOSE mutually-retractable coupled methods, so there is no JTMS oscillation to the apply-cap. If every
+ * candidate fails, fall to the §5(b) forge (last-resort learning) or refuse.
+ */
+const { makeMethodServe } = require('./serve-leaf.js');
+
+/**
+ * @param spec.candidates { <candidateKey>: <makeMethodServe method spec> }  the alternative sub-paths (each a method).
+ * @param spec.forests    { <leafKey>: [candidateKey, ...] }  the forest per leaf, in PREFERENCE order.
+ * @param spec.keyOf      (leaf) => leafKey   (default: leaf.produces || leaf.id).
+ * @param spec.pool       a shared P3 invoke-pool (default: own).
+ * @param spec.forge      async (args) => value   the §5(b) fallback when the forest is EXHAUSTED (optional).
+ * @returns serve         async (leaf, ctx) => { value, selected, tried }  (+ serve.pool, serve.close()).
+ */
+function makeForestServe( spec ) {
+	spec = spec || {};
+	const pool = spec.pool || require('../index.js').createInvokePool();
+	const forests = spec.forests || {};
+	const keyOf = spec.keyOf || (( leaf ) => leaf.produces || leaf.id);
+	const serveOne = makeMethodServe({ methods: spec.candidates || {}, keyOf: ( l ) => l.__cand, pool });
+
+	async function serve( leaf, ctx ) {
+		const key = keyOf(leaf);
+		const candidates = forests[key] || [];
+		const tried = [];
+		for ( const c of candidates ) {
+			try {
+				const value = await serveOne(Object.assign({}, leaf, { __cand: c, id: leaf.id + ':' + c }), ctx);   // dispatch + mount + GATE
+				return { value, selected: c, tried: tried.concat(c) };                                             // FIRST sound → SELECTED (one stays active)
+			} catch ( e ) { tried.push(c); }                                                                       // this path didn't complete → try the next (no coupling → no G3)
+		}
+		if ( typeof spec.forge === 'function' )                                                                    // forest EXHAUSTED → §5(b) last-resort learning
+			return { value: await spec.forge({ leaf, stack: (ctx && ctx.stack) || [], contract: (ctx && ctx.contract) || {}, reason: 'forest-exhausted', tried }), selected: 'forged', tried };
+		return { value: undefined, selected: null, tried, refusal: 'forest-exhausted' };
+	}
+	serve.pool = pool;
+	serve.close = () => spec.pool ? Promise.resolve() : pool.close();
+	return serve;
+}
+
+module.exports = { makeForestServe };

package/lib/authoring/forge-fallback.js

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * forge-fallback — THE LAST-RESORT LEARNING FALLBACK, wired (roadmap 2026-07-09 §5(b); ZERO-CORE). P2's segment-proxy
+ * exposes a `forge` HOOK + `reconstructStack` (the bounded problem stack, walked UP the parentSeg chain). §5(b) wires
+ * the pipeline behind that hook:
+ *
+ *   reconstructStack → STACK-TO-PROMPT → forge (the model) → RE-ENTER the gate (assertPost) → INDEX-BACK (amortise)
+ *
+ * The LEVER (owner): the fallback's success is the SERIALIZATION of the stack into a prompt — if `stackToPrompt`
+ * reconstitutes "what we're doing", the model only has to answer simple-but-relevant. When it fails, you work the
+ * info-provisioning + the prompt, NOT the model. The forged method is PROPOSE-only: it must satisfy the contract
+ * (assertPost DISPOSES) before it casts — it is typed sub-graph, so determinism holds. A forged method is INDEXED so
+ * the next matching case is a dispatch HIT (0-call) — the amortisation. The `forge` model is injected (a real LLM in
+ * production; a deterministic stub in tests).
+ *
+ * BOUNDED BLAME-DRIVEN RETRY (2026-07-09, residue USE-2(d), RE-SCOPED by the 2-lens confront). `maxRounds > 1` turns
+ * the one-shot forge into a bounded loop: on a gate refusal, the graph's PUSHBACK (the violated post atoms + the
+ * rejected-history) is folded into the next prompt (`serializeBlame`, the §5b LEVER one level up) and the model
+ * revises, up to `maxRounds`, then a typed refusal. This is the OPEN-regime DUAL of `negotiate.js`: negotiate is the
+ * CLOSED-domain constructive dialogue (it ENUMERATES admissible options and refuses on empty-options); here the space
+ * is OPEN (a method/castTemplate, not an enum), so the pushback is the BLAME and refusal is on max-rounds — importing
+ * negotiate's `optionsOf` is inert here (no enumerable domain) / gold-leaks on a closed enum. The three invariants
+ * hold, re-earned for the open regime: 0-FALSE (the admit path is the UNCHANGED `assertPost` — a non-gated forge is
+ * never returned, any round), HONEST-but-OPERATIONAL REFUSAL (refuse when no gated answer was produced within the
+ * bound — an operational, not epistemic, refusal; the graph never fabricates one), TERMINATION (`maxRounds`).
+ * LIVE-PROVEN (Ministral-Q8, `WIP/experiments/2026-07-09-blame-retry-killgate/`): on an OPEN sum+mod3 target, one-shot
+ * 17/24 → retry 24/24 at 0-FALSE; the dominant lever is the bounded retry-with-memory (+6/7), the violated-atom
+ * CONTENT adds a thin-but-robust +1 (a stubborn case resampling can't reach). `maxRounds` DEFAULTS to 1 → the one-shot
+ * behavior is byte-identical (fully backward-compatible).
+ */
+const { assertPost } = require('./contract.js');
+
+/**
+ * defaultStackToPrompt — the tunable serialization. Reconstitutes each level's TYPED interface (statement + produces
+ * ⊢ / needs ⊨) + the required output (contract.write) — "what we're doing", bounded, no prose.
+ */
+function defaultStackToPrompt( stack, contract, args ) {
+	const levels = (stack || []).map(( s, i ) => 'L' + i + ' ' + (s.statement || s.id)
+		+ (s.produces ? ' ⊢' + s.produces : '') + (s.needs && s.needs.length ? ' ⊨' + s.needs.join(',') : '')).join(' | ');
+	const goal = 'PRODUCE ' + (((contract || {}).write) || []).join(',');
+	return 'STACK[' + levels + '] · ' + ((args && args.reason) || 'forge') + ' → ' + goal;
+}
+
+/**
+ * defaultSerializeBlame — the graph's PUSHBACK folded into the revision prompt (the §5b LEVER, one level up). The
+ * ONLY thing beyond a bare resample is the CONTENT: the violated post atoms + the rejected-history. Bounded, no prose.
+ * @param violations  the `assertPost` violations of the last-rejected candidate ({kind,detail}).
+ * @param rejected    the summaries rejected so far (so the model does NOT repeat them).
+ * @param round       the current (0-indexed) round about to be attempted.
+ */
+function defaultSerializeBlame( violations, rejected, round ) {
+	const atoms = (violations || []).filter(( v ) => v.kind === 'post-violated').map(( v ) => v.detail);
+	const undecl = (violations || []).filter(( v ) => v.kind === 'undeclared-write').map(( v ) => v.detail);
+	const why = [];
+	if ( atoms.length ) why.push('violated constraints: [' + atoms.join(', ') + ']');
+	if ( undecl.length ) why.push('undeclared writes: [' + undecl.join(', ') + ']');
+	return ' | REVISE (attempt #' + (round + 1) + '): the previous answer was REJECTED — ' + (why.join('; ') || 'the post did not hold')
+		+ '. Already-rejected (do NOT repeat): [' + (rejected || []).map(( r ) => JSON.stringify(r)).join(' ') + ']. Produce a NEW answer satisfying ALL.';
+}
+
+/**
+ * makeForgeFallback(spec) — build a `forge` fn wired for a segment-proxy's hook.
+ * @param spec.forge         (prompt, args) => { name, castTemplate, summary?, footprint?, method? } | null   REQUIRED — the model.
+ *                           castTemplate = the cast the proxy applies (a typed sub-graph); summary/footprint = what it
+ *                           produces (re-gated); method = a method spec to index-back.
+ * @param spec.stackToPrompt (stack, contract, args) => prompt   the LEVER (default: defaultStackToPrompt).
+ * @param spec.serializeBlame (violations, rejected, round) => promptSuffix   the retry pushback (default: defaultSerializeBlame).
+ * @param spec.maxRounds     the bounded-retry cap (default 1 = one-shot, byte-identical to the pre-retry behavior).
+ * @param spec.oracle        optional G2 ground-truth probe forwarded to `assertPost` (for an effecting post).
+ * @param spec.index         Map<libraryKey, method>   the library the forged method is indexed into (amortise; default: own).
+ * @returns fallback         async (args) => castTemplate   (args = the P2 hook: { scope, graph, contract, stack, reason, blame }).
+ *                           fallback.index exposes the growing library.
+ */
+function makeForgeFallback( spec ) {
+	spec = spec || {};
+	const stackToPrompt = spec.stackToPrompt || defaultStackToPrompt;
+	const serializeBlame = spec.serializeBlame || defaultSerializeBlame;
+	const maxRounds = spec.maxRounds || 1;
+	const forge = spec.forge;
+	const index = spec.index || new Map();
+	if ( typeof forge !== 'function' ) throw new Error('makeForgeFallback needs spec.forge(prompt, args)');
+
+	const fallback = async function ( args ) {
+		args = args || {};
+		const base = stackToPrompt(args.stack || [], args.contract || {}, args);      // the LEVER: stack → prompt
+		const rejected = [];
+		let lastViolations = null;
+		for ( let round = 0; round < maxRounds; round++ ) {
+			const prompt = round === 0 ? base : base + serializeBlame(lastViolations, rejected, round);   // fold the pushback in (round>0)
+			const cand = await forge(prompt, args);                                   // the model — PROPOSE
+			if ( !cand || !cand.castTemplate ) throw new Error('forge-fallback: the model produced no candidate');
+			// RE-ENTER the gate (DISPOSE): the forged output must satisfy the contract — a bad forge cannot corrupt the caller.
+			if ( cand.summary ) {
+				const post = assertPost(args.contract || {}, cand.summary, cand.footprint || Object.keys(cand.summary), { oracle: spec.oracle });
+				if ( !post.ok ) {
+					rejected.push(cand.summary); lastViolations = post.violations;
+					if ( round + 1 < maxRounds ) continue;                            // RETRY with the graph's pushback in the prompt
+					throw new Error('forge-fallback: the forged method is REFUSED by the gate (' + post.violations.map(( v ) => v.kind).join(',') + ')');
+				}
+			}
+			if ( cand.method ) index.set(cand.name || (args.stack && args.stack[0] && args.stack[0].id) || 'forged', cand.method);   // INDEX-BACK (amortise)
+			return cand.castTemplate;
+		}
+		throw new Error('forge-fallback: no gated candidate within ' + maxRounds + ' rounds');   // (unreachable when maxRounds>=1; a guard)
+	};
+	fallback.index = index;
+	return fallback;
+}
+
+module.exports = { makeForgeFallback, defaultStackToPrompt, defaultSerializeBlame };

package/lib/authoring/givens.js

@@ -0,0 +1,121 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * givens — the TYPED BASE-FACT FRONT-DOOR (ZERO-CORE, host-side). Closes the tiered-plan gap (i): a leaf served
+ * through the context projection saw its UPSTREAM values but never the task's own literals (the 6 and the 4 of
+ * "a 6×4 rectangle"), so the executor re-guessed them. This brick extracts the task's base facts DETERMINISTICALLY
+ * (no model), names each one with a stable typed key, and the projection seeds them into the top pool as
+ * `val_<given>` — a leaf that cites a given key in its `needs` gets the VALUE injected into its bounded context,
+ * exactly like a producer's output. Nothing here is domain reasoning: it is a DECLARED front-door — two extractors
+ * (numeric literals in prose; numeric cells of a table), both pure surface, both fail-closed (what is not a clean
+ * numeric literal is NOT a given).
+ *
+ *   const { numberGivens, givensBlock, seedOf } = require('skynet-graph/lib/authoring/givens');
+ *   const givens = numberGivens(task);                        // [{ key:'g1_wide', value:6, snippet:'is 6 wide' }]
+ *   const leaves = await decompose(task + '\n' + givensBlock(givens));   // parts cite given keys in `needs`
+ *   await createPlanLoop({ decompose, serveLeaf }).run(task, { givens: seedOf(givens) });
+ *
+ * The KEY is positional + a lexical slug (`g<i>_<word>`): stable, typed, never a sentence — the human-readable
+ * meaning rides the SNIPPET (presentation), never the key (dispatch), per the K1 discipline.
+ */
+
+// a numeric literal in prose: optional $, digits with thousand-commas, optional decimals, optional %.
+// NOTE (owner 07-10): the front-door stays DIGITS-ONLY on purpose — translating prose quantities ("ten",
+// "twice") into numbers host-side is the wrong layer; the DECOMPOSER is instructed to restate any non-given
+// base fact explicitly in the consuming part's instruction (DECOMPOSE_SYSTEM rule 6), which covers spelled
+// numbers, fractions in words, and world knowledge alike.
+const NUM_RE = /\$?\s?\d[\d,]*(?:\.\d+)?%?/g;
+const WORD_RE = /[a-z][a-z'-]*/i;
+
+// slug = the nearest content word AFTER the number (else BEFORE) — purely lexical, lowercased, bounded.
+const STOP = { the: 1, a: 1, an: 1, of: 1, to: 1, and: 1, or: 1, is: 1, are: 1, was: 1, were: 1, it: 1, its: 1, in: 1, on: 1, at: 1, for: 1, with: 1, then: 1, than: 1, by: 1, per: 1, each: 1, more: 1, less: 1, had: 1, has: 1, have: 1, them: 1, they: 1, those: 1, these: 1, this: 1, that: 1, his: 1, her: 1, their: 1, he: 1, she: 1, we: 1, as: 1, so: 1, but: 1, if: 1, how: 1, many: 1, much: 1, did: 1, does: 1, do: 1 };
+function slugNear( text, start, end ) {
+	const pick = ( s ) => {
+		let m;
+		const re = new RegExp(WORD_RE.source, 'gi');
+		while ( (m = re.exec(s)) ) if ( !STOP[m[0].toLowerCase()] ) return m[0].toLowerCase().replace(/[^a-z]/g, '').slice(0, 12);
+		return '';
+	};
+	return pick(text.slice(end, end + 24)) || pick(text.slice(Math.max(0, start - 24), start).split(/\s+/).reverse().join(' '));
+}
+
+/**
+ * numberGivens(text) → [{ key, value, snippet }] — every clean numeric literal of the prose, in reading order.
+ * Deterministic, fail-closed, DIGITS-ONLY (see the NOTE above — prose quantities are the decomposer's job,
+ * by prompt rule, not a host-side translation table). `value` is the bare Number ($/commas/% stripped).
+ */
+function numberGivens( text ) {
+	const s = String(text == null ? '' : text);
+	const out = [];
+	let m;
+	NUM_RE.lastIndex = 0;
+	while ( (m = NUM_RE.exec(s)) ) {
+		const raw = m[0];
+		const v = Number(raw.replace(/[$,%\s]/g, ''));
+		if ( !isFinite(v) ) continue;
+		const slug = slugNear(s, m.index, m.index + raw.length);
+		const key = 'g' + (out.length + 1) + (slug ? '_' + slug : '');
+		out.push({ key: key, value: v, snippet: s.slice(Math.max(0, m.index - 18), m.index + raw.length + 18).trim().replace(/\s+/g, ' ') });
+	}
+	return out;
+}
+
+/**
+ * cellGivens(table) → [{ key, value, snippet, cell:{r,c} }] — every numeric cell of a row-major table (the FinQA
+ * front-door; row 0 = headers by convention). Key = `c<r>_<c>_<slug-of-row-label>`; snippet = "rowLabel · colHeader".
+ */
+function cellGivens( table ) {
+	const rows = Array.isArray(table) ? table : [];
+	const headers = Array.isArray(rows[0]) ? rows[0] : [];
+	const out = [];
+	for ( let r = 1; r < rows.length; r++ ) {
+		const row = rows[r] || [];
+		const label = String(row[0] == null ? '' : row[0]);
+		for ( let c = 1; c < row.length; c++ ) {
+			let raw = String(row[c] == null ? '' : row[c]).trim();
+			if ( !raw ) continue;
+			const neg = /^\(.*\)$/.test(raw);                                 // (1,234) = accounting negative
+			if ( !neg ) raw = raw.replace(/\(\s*[^)]*\)\s*$/, '').trim();     // "-17.1 ( 17.1 )" = FinQA dup-in-parens → keep the head
+			const v = Number(raw.replace(/[$,%()\s]/g, '')) * (neg ? -1 : 1);
+			if ( !isFinite(v) || !/\d/.test(raw) ) continue;
+			const slug = (label.toLowerCase().match(WORD_RE) || [''])[0].replace(/[^a-z]/g, '').slice(0, 12);
+			out.push({ key: 'c' + r + '_' + c + (slug ? '_' + slug : ''), value: v, cell: { r: r, c: c },
+				snippet: (label + ' · ' + String(headers[c] == null ? '' : headers[c])).trim() });
+		}
+	}
+	return out;
+}
+
+/** givensBlock(givens) → the prompt block appended to the decompose USER message (keys citable in `needs`). */
+function givensBlock( givens ) {
+	if ( !givens || !givens.length ) return '';
+	return 'GIVENS (base facts already available — a part that uses one MUST cite its key in "needs"; do NOT restate the number): '
+		+ givens.map(( g ) => g.key + '=' + g.value + ' ("' + g.snippet + '")' ).join(' · ');
+}
+
+/** seedOf(givens) → { key: value } — the map the projection seeds as `val_<key>` (plan-loop's `ctx.givens`). */
+function seedOf( givens ) {
+	const map = {};
+	for ( const g of (givens || []) ) map[g.key] = g.value;
+	return map;
+}
+
+/**
+ * labelsOf(givens) → { key: snippet } — provenance labels for leaf prompts, STRUCTURED PROVENANCE ONLY (the
+ * "cells" rule, ablation-verified at N=40 and N=200): a table cell's MEANING (row · col header) is invisible in
+ * its bare value, so the label fixes leaf mis-localization (wrong cell/base-year/sign); a PROSE given is already
+ * restated self-contained by the decomposer (rule 7), so labelling it is pure prompt perturbation (net-negative),
+ * and upstream-producer labels help nowhere. Wire as `ctx.labels` (plan-loop → context-project).
+ */
+function labelsOf( givens ) {
+	const map = {};
+	for ( const g of (givens || []) ) if ( g && g.cell && g.snippet ) map[g.key] = String(g.snippet).slice(0, 70);
+	return map;
+}
+
+module.exports = { numberGivens, cellGivens, givensBlock, seedOf, labelsOf };