skynet-graph 1.2.0

package/lib/authoring/compose-hotspot.js

@@ -0,0 +1,314 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * compose-hotspot — the COMPOSITIONAL-recurrence go/no-go DETECTOR (roadmap STAGE-0 gate; the depth-≥2
+ * analog of `hotspot.js`). It answers the one shared front kill-gate of the composed roadmap: *does the
+ * workload COMPOSE?* — before building the (substantial, still-absent) `compress.js` operator.
+ *
+ * Why a pre-test (the honest off-ramp, mirroring hotspot): the flat LEAF/whole-task memo ALREADY elides a
+ * recurrent typed slice at 0 calls. So minting a persisted depth-≥2 "method-of-methods" buys NOTHING unless a
+ * SUB-composite recurs across DISTINCT whole-tasks — i.e. the shared sub-work that whole-task crystallization
+ * cannot cover (X=A∘B∘C and Y=A∘B∘D both contain A∘B, but X≠Y so neither's crystallized method serves the other).
+ * That is the precise "compress pays" condition; the detector separates it from "already-flat-covered".
+ *
+ * Signal = RE-PAIR (Larsson & Moffat 2000): repeatedly replace the most-frequent adjacent method-pair with a new
+ * symbol → recovers the composition TREE/hierarchy and the MDL saving cheaply. A recurring composite tree
+ * linearizes to a recurring subsequence, so a contiguous-pair tally has NO false negatives for the GATE (spurious
+ * pairs are filtered by the cross-task + utility gates downstream — the operator-grade SEQUITUR/Stitch/DreamCoder
+ * corpus-MDL is `compress.js`'s job, not the gate's).
+ *
+ * The four-way verdict per candidate composite S (analog of hotspot's four):
+ *   too-rare            — count(S) < minCount                             (not enough volume)
+ *   already-flat-covered— frequent BUT distinctTasks(S) < minDistinctTasks (only inside ONE repeated whole-task →
+ *                         whole-task memo already serves it; compression is redundant — THE off-ramp)
+ *   unstable            — frequent ∧ cross-task BUT the composite's result is NOT a function of its typed input
+ *                         (K1-insufficient at the composite level; only checked when result keys are provided)
+ *   compose-candidate   — FREQUENT ∧ CROSS-TASK (≥ minDistinctTasks) ∧ COMPRESSIBLE (savedCalls > 0)
+ * Utility is in CALLS (Minton): savedCalls(S) ≈ distinctTasks(S) − 1 forge-calls elided over the whole-task
+ * baseline, minus library bloat. `anyComposeCandidate(rows)` is the go/no-go boolean for `compress.js`.
+ *
+ * HONEST SCOPE: on a DESIGNED workload the planted composite is found by construction — a positive result
+ * validates the INSTRUMENT + QUANTIFIES the saving, it does NOT establish that real domains compose. Run the
+ * detector on a REAL dispatch trace to answer that (the instrument is the deliverable; cf. hotspot's "no
+ * candidate on today's workload"). Pure + synchronous.
+ *
+ * ─────────────────────────── PROVENANCE layer (confront-reshaped 2026-07-01, Laurie Q2/Q4 + babble/Stitch SOTA) ──
+ * The flat tally above keys on CONTIGUOUS method-id adjacency in a per-task EMISSION-order sequence. But the engine's
+ * stabilize loop is a fixpoint over `_unstable`, so the emission order of data-flow-INDEPENDENT firings is NOT
+ * deterministic: on a multi-subproblem task a real composite A→B→C surfaces INTERLEAVED as [A,D,B,E,C] and the
+ * contiguous tally MISSES it (a false NEGATIVE — the EXPENSIVE gate error: it would wrongly FILE compress.js when it
+ * would pay). The fix: tally producer→consumer PROVENANCE edges (interleave-robust) and extract the DATA-FLOW CHAINS,
+ * then RE-PAIR those clean chains — so a composite is recognised by its data-flow, regardless of interleaving.
+ * `provenanceEdges` is the tally, `provenanceChains` the extraction, `trackFromFirings` feeds `composeHotspots`.
+ *
+ * The poly / iso-free GUARDS (Laurie — dropping any one re-summons a named NP-hardness):
+ *   G-a  candidates are PATHS: an internal chain node has in-degree = out-degree = 1 WITHIN the task DAG. A fork/join
+ *        (fan-in/out > 1) is a chain BOUNDARY. Fork-join composites are OUT of scope for the poly gate (SUBDUE-beam
+ *        territory, not poly / not exact) — a DOCUMENTED CEILING, not a silent drop. [drop → frequent-subgraph mining,
+ *        subgraph-iso NP-complete: Yan-Han gSpan ICDM'02, Cook'71]
+ *   G-b  cross-task grouping is the RE-PAIR canonical-STRING recurrence over the path's concept sequence (a path's
+ *        topological order is unique) — never a pairwise graph-iso test. [drop → graph canonicalization / GI]
+ *   G-c  edges come from PROVENANCE (a producer WROTE a key the consumer READ, SAME target, earlier rev) via a
+ *        (target,key) last-writer hash-join — never value-matching (a shared value across many objects = a needless
+ *        m×n blowup + semantically spurious edges).
+ *   Q3   SAME-TARGET only (single relativization base). Cross-linked-target provenance (a producer on segment X
+ *        feeding a child segment Y) is MULTI-BASE (needs a third `⟦@internal⟧` hole kind) and belongs to compress.js.
+ * The gate stops at DETECTION (G-d): "does ANY sound cross-task PATH-composite recur?". The antiUnify CERTIFICATION
+ * (`mine.js#mineMethods` lifted to the composite) + the MDL non-overlap SELECTION (MWIS/B&B) are compress.js's front
+ * half (babble-generator + Stitch-selector, minus the e-graph), NOT the gate — a false GO is cheap (compress.js
+ * refuses the unstable composite via its own `signatureDetermined`/leak guards), a false NO-GO is expensive.
+ */
+
+var SEP = '\u001f';
+
+/**
+ * A tally you feed one entry per task: the ordered SEQUENCE of method ids it dispatched, its whole-task
+ * signature (so cross-task recurrence is distinguishable from a repeated whole-task), and optionally a
+ * per-occurrence result key (for the composite-level K1-stability gate).
+ */
+function trackCompositions() {
+	var tasks = [];   // [{ taskSig, seq:[methodId...], resultBySpan?:{ "i:j": resultKey } }]
+	return {
+		tasks: tasks,
+		/** @param e { taskSig, seq:[id...], resultKeyOf?(i,j)->key }  — resultKeyOf spans the composite seq[i..j] */
+		observe: function ( e ) {
+			tasks.push({ taskSig: e.taskSig != null ? String(e.taskSig) : (e.seq || []).join('>'),
+				seq: (e.seq || []).map(String), resultKeyOf: e.resultKeyOf || null });
+		},
+		reset: function () { tasks.length = 0; },
+	};
+}
+
+// count adjacent pairs across the corpus; return the most frequent (count ≥ 2) with its distinct-task set.
+function bestPair( corpus ) {
+	var count = new Map(), tasksOf = new Map();
+	for ( var t = 0; t < corpus.length; t++ ) {
+		var seq = corpus[t].seq, sig = corpus[t].taskSig;
+		for ( var i = 0; i < seq.length - 1; i++ ) {
+			var p = seq[i] + SEP + seq[i + 1];
+			count.set(p, (count.get(p) || 0) + 1);
+			var s = tasksOf.get(p); if ( !s ) { s = new Set(); tasksOf.set(p, s); } s.add(sig);
+		}
+	}
+	var best = null, bc = 1;
+	count.forEach(function ( c, p ) { if ( c > bc ) { bc = c; best = p; } });
+	return best ? { pair: best, count: bc, tasks: tasksOf.get(best) } : null;
+}
+
+// replace every non-overlapping occurrence of (a,b) with `sym` in each sequence (left-to-right, greedy).
+function replacePair( corpus, a, b, sym ) {
+	for ( var t = 0; t < corpus.length; t++ ) {
+		var seq = corpus[t].seq, out = [];
+		for ( var i = 0; i < seq.length; i++ ) {
+			if ( i < seq.length - 1 && seq[i] === a && seq[i + 1] === b ) { out.push(sym); i++; }
+			else out.push(seq[i]);
+		}
+		corpus[t].seq = out;
+	}
+}
+
+// expand a composite symbol back to its primitive-method leaf sequence (the flattened tree).
+function expand( sym, rules ) {
+	var r = rules[sym];
+	if ( !r ) return [sym];
+	return expand(r.expansion[0], rules).concat(expand(r.expansion[1], rules));
+}
+
+/**
+ * Detect compositional recurrence. Pure (no engine, no model).
+ * @param tracker  a trackCompositions() collector (or { tasks })
+ * @param opts.minCount          volume floor on a composite's occurrences (default 3)
+ * @param opts.minDistinctTasks  cross-task floor: # DISTINCT whole-tasks a composite must span (default 2)
+ * @returns [{ composite:[leafId...], size, count, distinctTasks, savedCalls, mdlSymbols, stable, verdict, reason }]
+ *          sorted compose-candidates first, then by savedCalls. verdict ∈
+ *          { 'compose-candidate', 'unstable', 'already-flat-covered', 'too-rare' }.
+ */
+function composeHotspots( tracker, opts ) {
+	opts = opts || {};
+	var minCount = opts.minCount != null ? opts.minCount : 3;
+	var minDist  = opts.minDistinctTasks != null ? opts.minDistinctTasks : 2;
+	var tasks = (tracker && tracker.tasks) || tracker || [];
+
+	// working copy (RE-PAIR mutates the sequences) + a parallel copy for the stability span lookup.
+	var corpus = tasks.map(function ( t ) { return { taskSig: t.taskSig, seq: t.seq.slice(), resultKeyOf: t.resultKeyOf }; });
+	var rules = {};            // sym -> { expansion:[a,b], count, tasks:Set }
+	var nextSym = 0;
+
+	// RE-PAIR: greedily fold the most-frequent adjacent pair into a fresh symbol, recording the rule.
+	while ( true ) {
+		var bp = bestPair(corpus);
+		if ( !bp || bp.count < 2 ) break;
+		var parts = bp.pair.split(SEP);
+		var sym = '§' + (nextSym++);
+		rules[sym] = { expansion: [parts[0], parts[1]], count: bp.count, tasks: bp.tasks };
+		replacePair(corpus, parts[0], parts[1], sym);
+	}
+
+	// stability (optional): a composite is K1-UNSTABLE if, for its occurrences sharing an input, results diverge.
+	// v0 proxy via caller-provided resultKeyOf over the composite's leaf span: two occurrences of the SAME leaf
+	// sequence whose result keys differ ⇒ the composite result is not a function of the (structural) input.
+	function stabilityOf( leafSeq ) {
+		var seen = null, saw = false;
+		for ( var t = 0; t < tasks.length; t++ ) {
+			var seq = tasks[t].seq, rk = tasks[t].resultKeyOf; if ( !rk ) continue;
+			for ( var i = 0; i + leafSeq.length <= seq.length; i++ ) {
+				var match = true;
+				for ( var j = 0; j < leafSeq.length; j++ ) if ( seq[i + j] !== leafSeq[j] ) { match = false; break; }
+				if ( !match ) continue;
+				var key = rk(i, i + leafSeq.length - 1); if ( key == null ) continue;
+				saw = true;
+				if ( seen == null ) seen = key; else if ( seen !== key ) return false;   // diverged → unstable
+			}
+		}
+		return saw ? true : null;   // null = unconfirmed (no result data)
+	}
+
+	var rows = Object.keys(rules).map(function ( sym ) {
+		var r = rules[sym];
+		var leaf = expand(sym, rules);
+		var distinctTasks = r.tasks.size;
+		var savedCalls = Math.max(0, distinctTasks - 1);           // forge-calls elided over the whole-task baseline
+		var mdlSymbols = (r.count - 1) * (leaf.length - 1) - 1;    // RE-PAIR description-length saving (symbols)
+		var stable = stabilityOf(leaf);
+		var verdict, reason;
+		if ( r.count < minCount ) {
+			verdict = 'too-rare'; reason = 'count ' + r.count + ' < minCount ' + minCount;
+		} else if ( distinctTasks < minDist ) {
+			verdict = 'already-flat-covered';
+			reason = 'distinctTasks ' + distinctTasks + ' < ' + minDist + ' — only inside one repeated whole-task; whole-task memo already serves it';
+		} else if ( stable === false ) {
+			verdict = 'unstable'; reason = 'the composite result is not a function of its typed input (K1-insufficient at the composite level)';
+		} else {
+			verdict = 'compose-candidate';
+			reason = 'frequent ∧ cross-task (' + distinctTasks + ' distinct tasks) ∧ compressible (saves ~' + savedCalls + ' forge-calls)'
+				+ (stable == null ? '; stability UNCONFIRMED (no result data)' : '');
+		}
+		return { composite: leaf, size: leaf.length, count: r.count, distinctTasks: distinctTasks,
+			savedCalls: savedCalls, mdlSymbols: mdlSymbols, stable: stable, verdict: verdict, reason: reason };
+	});
+
+	var rank = { 'compose-candidate': 0, 'unstable': 1, 'already-flat-covered': 2, 'too-rare': 3 };
+	rows.sort(function ( a, b ) { return (rank[a.verdict] - rank[b.verdict]) || (b.savedCalls - a.savedCalls) || (b.count - a.count); });
+	return rows;
+}
+
+// ─────────────────────────── PROVENANCE tally + DATA-FLOW chain extraction (the interleave-robust signal) ──────────
+//
+// A FIRING record (one per dispatched method / concept apply):
+//   { task, rev, concept, target, reads:[key…], writes:[key…] }
+// `task` = the whole-task signature (so cross-DISTINCT-task recurrence is distinguishable — the off-ramp); `rev` = the
+// engine's monotonic apply order (the total order, from the onConceptApply record); `concept` = the method-id SYMBOL
+// (two firings of one crystallized method share it — the gate keys on the method, not its content, per G-d liberal
+// gate); `reads`/`writes` = the require/premise keys consumed and the produced-fact keys (self-flag + template keys).
+
+/**
+ * The PROVENANCE tally (G-c): same-target producer→consumer edges via an (target,key) LAST-WRITER hash-join. A
+ * consumer C's read of key K binds to the most-recent EARLIER firing that wrote K on the SAME target — provenance,
+ * never value-matching. Pure, O(Σ reads). @returns [{ from, to, via, fromConcept, toConcept, task, target }] (from/to
+ * are the producer/consumer `rev`s).
+ */
+function provenanceEdges( firings ) {
+	var byTask = new Map();
+	for ( var i = 0; i < (firings || []).length; i++ ) {
+		var f = firings[i]; if ( !f || f.concept == null ) continue;
+		if ( !byTask.has(f.task) ) byTask.set(f.task, []);
+		byTask.get(f.task).push(f);
+	}
+	var edges = [];
+	byTask.forEach(function ( fs, task ) {
+		fs = fs.slice().sort(function ( a, b ) { return (a.rev || 0) - (b.rev || 0); });
+		var lastWriter = new Map();                                  // "target SEP key" -> the most-recent writer firing
+		for ( var j = 0; j < fs.length; j++ ) {
+			var f = fs[j];
+			for ( var r = 0; r < (f.reads || []).length; r++ ) {    // resolve reads against PRIOR writers (before recording this firing's writes)
+				var k = f.reads[r], w = lastWriter.get(f.target + SEP + k);
+				if ( w && w !== f ) edges.push({ from: w.rev, to: f.rev, via: k, fromConcept: w.concept, toConcept: f.concept, task: task, target: f.target });
+			}
+			for ( var wI = 0; wI < (f.writes || []).length; wI++ ) lastWriter.set(f.target + SEP + f.writes[wI], f);
+		}
+	});
+	return edges;
+}
+
+/**
+ * Extract per-task maximal DATA-FLOW CHAINS (G-a paths) from the provenance edges. An edge from→to is a CHAIN EDGE iff
+ * outDeg(from)==1 ∧ inDeg(to)==1 in the task DAG (both endpoints linearly connected); chain edges form vertex-disjoint
+ * simple paths (rev-monotone ⇒ acyclic). A fork/join breaks the chain (the fan node is a boundary — G-a ceiling). Each
+ * maximal chain of ≥2 firings is a candidate composite. @returns [{ task, seq:[concept…], firings:[rev…], vias:[[key…]…] }].
+ */
+function provenanceChains( firings, opts ) {
+	opts = opts || {};
+	var edges = provenanceEdges(firings);
+	var conceptByRev = new Map(), taskEdges = new Map();
+	for ( var i = 0; i < (firings || []).length; i++ ) { var f = firings[i]; if ( f && f.concept != null ) conceptByRev.set(f.task + SEP + f.rev, f.concept); }
+	for ( var e = 0; e < edges.length; e++ ) { var ed = edges[e]; if ( !taskEdges.has(ed.task) ) taskEdges.set(ed.task, []); taskEdges.get(ed.task).push(ed); }
+
+	var chains = [];
+	taskEdges.forEach(function ( es, task ) {
+		// collapse parallel multi-key edges between the SAME (from,to) into one (a diamond via two keys is still ONE edge).
+		var byPair = new Map();
+		for ( var i = 0; i < es.length; i++ ) { var ed = es[i], pk = ed.from + '>' + ed.to;
+			if ( !byPair.has(pk) ) byPair.set(pk, { from: ed.from, to: ed.to, vias: [] }); byPair.get(pk).vias.push(ed.via); }
+		var uedges = Array.from(byPair.values());
+		var outDeg = new Map(), inDeg = new Map();
+		uedges.forEach(function ( ed ) { outDeg.set(ed.from, (outDeg.get(ed.from) || 0) + 1); inDeg.set(ed.to, (inDeg.get(ed.to) || 0) + 1); });
+		var chainSucc = new Map(), isChainTo = new Set();
+		uedges.forEach(function ( ed ) { if ( outDeg.get(ed.from) === 1 && inDeg.get(ed.to) === 1 ) { chainSucc.set(ed.from, ed); isChainTo.add(ed.to); } });
+		chainSucc.forEach(function ( _e, from ) {
+			if ( isChainTo.has(from) ) return;                       // not a start (mid-chain node)
+			var revs = [from], vias = [], cur = from;
+			while ( chainSucc.has(cur) ) { var ce = chainSucc.get(cur); revs.push(ce.to); vias.push(ce.vias); cur = ce.to; }
+			if ( revs.length < 2 ) return;
+			chains.push({ task: task, seq: revs.map(function ( rv ) { return conceptByRev.get(task + SEP + rv); }), firings: revs, vias: vias });
+		});
+	});
+	return chains;
+}
+
+/**
+ * Feed an enriched FIRING trace through the provenance layer into a `trackCompositions()` collector, so `composeHotspots`
+ * runs the four-way verdict over the INTERLEAVE-ROBUST data-flow chains (not the raw emission order). This is the honest
+ * structural go/no-go. @param opts.stability  if a firing carries an `outKey` (a canonical digest of the composite's
+ * observed output), thread a `resultKeyOf` so the `unstable` verdict still fires (the cheap K1 PROXY — NOT the full
+ * antiUnify certification, which is compress.js's job).
+ */
+function trackFromFirings( firings, opts ) {
+	opts = opts || {};
+	var t = trackCompositions();
+	var chains = provenanceChains(firings, opts);
+	var byRev = new Map();
+	for ( var i = 0; i < (firings || []).length; i++ ) { var f = firings[i]; if ( f && f.concept != null ) byRev.set(f.task + SEP + f.rev, f); }
+	for ( var c = 0; c < chains.length; c++ ) {
+		var ch = chains[c], entry = { taskSig: ch.task, seq: ch.seq };
+		if ( opts.stability ) entry.resultKeyOf = (function ( chain ) {
+			return function ( _i, j ) { var f = byRev.get(chain.task + SEP + chain.firings[j]); return f && f.outKey != null ? String(f.outKey) : null; };
+		})(ch);
+		t.observe(entry);
+	}
+	return t;
+}
+
+// the go/no-go boolean: is there any compositional recurrence worth compressing?
+function anyComposeCandidate( rows ) { return (rows || []).some(function ( r ) { return r.verdict === 'compose-candidate'; }); }
+
+// total forge-calls a fully-built compress.js could elide (upper bound) across all candidates.
+function potentialSavedCalls( rows ) {
+	return (rows || []).reduce(function ( s, r ) { return s + (r.verdict === 'compose-candidate' ? r.savedCalls : 0); }, 0);
+}
+
+module.exports = {
+	trackCompositions: trackCompositions,
+	composeHotspots: composeHotspots,
+	anyComposeCandidate: anyComposeCandidate,
+	potentialSavedCalls: potentialSavedCalls,
+	expand: expand,
+	// the PROVENANCE layer (interleave-robust structural go/no-go)
+	provenanceEdges: provenanceEdges,
+	provenanceChains: provenanceChains,
+	trackFromFirings: trackFromFirings,
+};

package/lib/authoring/compress.js

@@ -0,0 +1,279 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * compress — the DIGRAM-grain AFFINITY MINER (the long-filed compress.js, finally built on evidence).
+ *
+ * WHY NOW. RUN 8 (e2e-fidelity) bounded whole-structure composition by whole-structure decode invariance:
+ * on external/cross-domain prose a task class holds 4-5 decompose shapes (mode 38%) → no whole composite ever
+ * forms → `synthesizeByBlend` has nothing to blend. The 2026-07-03 kill-gate (experiments/2026-07-03-digram-
+ * invariance) measured the SAME captured shapes at DIGRAM grain — recurring pairs of ADJACENT typed steps —
+ * and returned GO: top-digram support 1.0/0.875, coverage 0.98/0.92, net MDL gain 20/12% exactly where the
+ * whole-structure read 0. This module mines that grain: the owner's affinity mechanism « AB qualifié · BC
+ * adjacent ont une affinité → composer AC qualifié qui devient un slot » — a SEQUITUR/SUBDUE binary production
+ * (nonterminal invention), affinity = MDL gain on OBSERVED digrams (linear in the trace, never |lattice|²).
+ *
+ * WHAT IT MINES (input = decompose shape-trees: `[{k:<stepKind>, c:[…children]}]` per task — the typed-loop
+ * trace grain, also the RUN-8 diag-dump grain):
+ *   - `mineDigrams`        recurring adjacent sibling pairs (support = tasks, multiplicity-weighted);
+ *   - `subExpansionIndex`  the DISPATCHABLE form: (parentKind→kind | kind) → unique observed expansion body,
+ *                          under the online K1 rule (conflicting bodies → undetermined, never first-wins) —
+ *                          the ctx grain splits classes the kind grain conflates (the granularity lever at
+ *                          the LEVEL grain instead of the root);
+ *   - `foldSubpaths`       admission under the mdl.js ΔL objective (its step-alphabet face: savedBits −
+ *                          encodeBits − taxBits, same three terms — mdl.js states the concept-schema face);
+ *   - `toExpandPatch`      mint a typed-loop-PARITY expand patch from a mined body (the mount/guard
+ *                          conventions ride the template: stamped EvalComplexity + Atomic|NeedsSplit, the
+ *                          plan-state mid nodes, the `_s`/`_m` id scheme) — a mined subpath mounts EXACTLY
+ *                          like a live expand, so the #33 re-fire guard discipline is preserved;
+ *   - `mineForest`         the method-FOREST skeleton: per class, the observed variant multiset + the digrams
+ *                          shared across ≥2 variants (a concept-method is a LIBRARY of alternative subpaths
+ *                          for one abstract problem — the concept-method design (the lattice preprint); the variants are its body,
+ *                          the shared digrams its common sub-methods).
+ *
+ * Fail-closed: a node with no typed `k` mines as the literal kind `∅` — it supports nothing typed and a body
+ * containing it stays mintable-but-quarantined (the caller sees the ∅). Kinds are NEVER invented.
+ *
+ * NON-GOAL (measured, not assumed): whether dispatching mined sub-expansions nets out ELIDED calls against
+ * the on-demand `synthesizeByBlend`+`indexMethod` baseline is the replay experiment's question
+ * (experiments/2026-07-03-digram-miner-elision), per the cont.⁶/⁷ baseline discipline — MDL gain is a
+ * compression floor, not an elision.
+ */
+
+const NIL = '∅'; // fail-closed kind for a malformed (k-less) node
+const TOP = '⊤'; // the synthetic parent of a task root
+
+const kindOf = ( node ) => (node && typeof node.k === 'string') ? node.k : NIL;
+const childrenOf = ( node ) => (node && Array.isArray(node.c)) ? node.c : [];
+const isAtomic = ( node ) => childrenOf(node).length === 0;
+const digramKey = ( a, b ) => a + '→' + b;
+
+/** The canonical BODY of one expansion: the child step-list with atomicity flags — the exact per-level memo
+ *  canon of the fidelity harness (a dispatch must predict the kinds AND the split-vs-atomic verdicts). */
+const bodyOf = ( children ) => children.map(( ch ) => ({ k: kindOf(ch), a: isAtomic(ch) }));
+const bodyKey = ( body ) => JSON.stringify(body);
+
+/** Every horizontal sibling sequence of a tree (as kind arrays): the top-level array + each node's children. */
+function siblingSequences( topArr ) {
+	const seqs = [];
+	const stack = [topArr];
+	while ( stack.length ) {
+		const arr = stack.pop();
+		seqs.push(arr.map(kindOf));
+		for ( const node of arr ) { const kids = childrenOf(node); if ( kids.length ) stack.push(kids); }
+	}
+	return seqs;
+}
+
+/**
+ * Mine recurring adjacent digrams over a shape corpus.
+ * @param entries [{ cls, mult=1, tree }] — tree = the task root's expansion, `[{k,c}]`
+ * @returns { digrams:[{a,b,key,support,occurrences}], tasks, pairOccurrences } — support = # tasks
+ *          (multiplicity-weighted) containing the digram ≥ once; occurrences overlap (raw adjacency count).
+ */
+function mineDigrams( entries, opts ) {
+	opts = opts || {};
+	const support = new Map(), occurrences = new Map();
+	let tasks = 0, pairOccurrences = 0;
+	for ( const e of entries ) {
+		const mult = e.mult == null ? 1 : e.mult;
+		tasks += mult;
+		const present = new Set();
+		for ( const seq of siblingSequences(e.tree) )
+			for ( let i = 0; i + 1 < seq.length; i++ ) {
+				const k = digramKey(seq[i], seq[i + 1]);
+				present.add(k);
+				occurrences.set(k, (occurrences.get(k) || 0) + mult);
+				pairOccurrences += mult;
+			}
+		for ( const k of present ) support.set(k, (support.get(k) || 0) + mult);
+	}
+	const digrams = [...support.entries()]
+		.map(( [key, sup] ) => { const i = key.indexOf('→'); return { a: key.slice(0, i), b: key.slice(i + 1), key, support: sup, occurrences: occurrences.get(key) }; })
+		.sort(( x, y ) => (y.support - x.support) || (x.key < y.key ? -1 : 1));
+	return { digrams, tasks, pairOccurrences };
+}
+
+/**
+ * The DISPATCHABLE index of observed sub-expansions, at two key grains:
+ *   kind grain  — key = the expanding node's stepKind (≈ the fidelity harness's per-level memo);
+ *   ctx grain   — key = parentKind→stepKind (splits classes the kind grain conflates).
+ * Online K1 rule at dispatch: a key maps to a body ONLY if exactly one distinct body was ever observed for it
+ * (conflict → undetermined, refuse — never first-wins/majority) AND its support ≥ minSupport.
+ */
+function subExpansionIndex( opts ) {
+	opts = opts || {};
+	const minSupport = opts.minSupport == null ? 2 : opts.minSupport;
+	const byKind = new Map(), byCtx = new Map(); // key → Map(bodyKey → {body, support})
+	const bump = ( map, key, body, mult ) => {
+		let bodies = map.get(key);
+		if ( !bodies ) map.set(key, bodies = new Map());
+		const bk = bodyKey(body);
+		const cur = bodies.get(bk);
+		if ( cur ) cur.support += mult; else bodies.set(bk, { body, support: mult });
+	};
+	const walk = ( arr, parentKind, mult ) => {
+		for ( const node of arr ) {
+			const kids = childrenOf(node);
+			if ( !kids.length ) continue;
+			const body = bodyOf(kids), k = kindOf(node);
+			bump(byKind, k, body, mult);
+			bump(byCtx, digramKey(parentKind, k), body, mult);
+			walk(kids, k, mult);
+		}
+	};
+	return {
+		/** Observe ONE production (a single paid expand: parentKind→kind emitted `body`) — the STREAMING grain:
+		 *  a live/replay loop must accrue exactly what was derived, never a whole tree at once (future leak). */
+		observeProduction( parentKind, kind, body, mult ) {
+			mult = mult == null ? 1 : mult;
+			bump(byKind, kind, body, mult);
+			bump(byCtx, digramKey(parentKind == null ? TOP : parentKind, kind), body, mult);
+		},
+		/** Observe one task's shape. site = { rootKind, mult=1 } — the root's own expansion is indexed too
+		 *  (kind = rootKind, ctx = ⊤→rootKind). */
+		observe( tree, site ) {
+			site = site || {};
+			const mult = site.mult == null ? 1 : site.mult;
+			const rootKind = site.rootKind || TOP;
+			bump(byKind, rootKind, bodyOf(tree), mult);
+			bump(byCtx, digramKey(TOP, rootKind), bodyOf(tree), mult);
+			walk(tree, rootKind, mult);
+		},
+		/** parentKind null → kind grain; else ctx grain. → {body, support} | null (undetermined/unseen/under-support). */
+		dispatch( parentKind, kind ) {
+			const bodies = parentKind == null ? byKind.get(kind) : byCtx.get(digramKey(parentKind, kind));
+			if ( !bodies || bodies.size !== 1 ) return null;               // unseen, or K1-undetermined (≥2 bodies)
+			const only = bodies.values().next().value;
+			return only.support >= minSupport ? { body: only.body, support: only.support } : null;
+		},
+		/** The RUN-8 false-hit discipline: a dispatched body contradicted by ground truth INVALIDATES exactly
+		 *  the used key at the used grain (parentKind null = kind grain) — it goes undetermined, never re-fires. */
+		invalidate( parentKind, kind ) {
+			const map = parentKind == null ? byKind : byCtx;
+			const key = parentKind == null ? kind : digramKey(parentKind, kind);
+			const bodies = map.get(key);
+			if ( bodies ) bodies.set('⊥', { body: null, support: 0 });     // a 2nd distinct entry ⇒ K1-undetermined
+		},
+		stats() {
+			const summarize = ( map ) => { let determined = 0, undetermined = 0;
+				for ( const bodies of map.values() ) (bodies.size === 1 ? determined++ : undetermined++);
+				return { keys: map.size, determined, undetermined }; };
+			return { kind: summarize(byKind), ctx: summarize(byCtx), minSupport };
+		},
+	};
+}
+
+/**
+ * Fold admission under the mdl.js ΔL objective, step-alphabet face (same three terms as mdl.js — which states
+ * the concept-schema face; one objective, two alphabets):
+ *   savedBits  = folds·log2(N)          each non-overlapping fold names 1 nonterminal instead of 2 symbols
+ *   encodeBits = 2·log2(N)              the nonterminal's body, paid once (the dictionary)
+ *   taxBits    = R·(log2(N+1)−log2(N))  the match-cost tax: +1 alphabet symbol raises EVERY parse
+ *   ΔL = encodeBits + taxBits − savedBits ; admit iff ΔL < 0 ∧ support ≥ minSupport
+ * Folds are counted greedily (most-frequent-by-occurrence first, non-overlapping within a sibling sequence) —
+ * the SEQUITUR single pass; dlAfter = dlBefore + Σ_admitted ΔL (a ranking proxy, documented as such).
+ */
+function foldSubpaths( entries, opts ) {
+	opts = opts || {};
+	const minSupport = opts.minSupport == null ? 2 : opts.minSupport;
+	const { digrams } = mineDigrams(entries);
+
+	// alphabet + corpus size (weighted symbol count)
+	const alphabet = new Set();
+	let R = 0;
+	const work = []; // flat {kinds, mult, consumed} sequence instances for the greedy fold
+	for ( const e of entries ) {
+		const mult = e.mult == null ? 1 : e.mult;
+		for ( const seq of siblingSequences(e.tree) ) {
+			for ( const k of seq ) { alphabet.add(k); R += mult; }
+			if ( seq.length >= 2 ) work.push({ kinds: seq, mult, consumed: new Array(seq.length).fill(false) });
+		}
+	}
+	const N = Math.max(alphabet.size, 2);
+	const log2 = ( x ) => Math.log(x) / Math.LN2;
+	const dlBefore = R * log2(N);
+	const taxBits = R * (log2(N + 1) - log2(N));
+
+	const ranked = digrams.slice().sort(( x, y ) => (y.occurrences - x.occurrences) || (x.key < y.key ? -1 : 1));
+	const subpaths = [];
+	let dlAfter = dlBefore;
+	for ( const d of ranked ) {
+		let folds = 0;
+		for ( const w of work ) {
+			const K = w.kinds, C = w.consumed;
+			for ( let i = 0; i + 1 < K.length; i++ )
+				if ( !C[i] && !C[i + 1] && K[i] === d.a && K[i + 1] === d.b ) { C[i] = C[i + 1] = true; folds += w.mult; i++; }
+		}
+		const saved = folds * log2(N), encode = 2 * log2(N);
+		const delta = encode + taxBits - saved;
+		const admitted = delta < 0 && d.support >= minSupport;
+		if ( admitted ) dlAfter += delta;
+		subpaths.push(Object.assign({}, d, { folds, dl: { saved, encode, tax: taxBits, delta }, admitted }));
+	}
+	return { subpaths, dlBefore, dlAfter, alphabet: [...alphabet].sort() };
+}
+
+/**
+ * Mint the typed-loop-PARITY expand patch for a mined body — byte-for-byte what `makeTypedDecomposeProviders`'
+ * expand emits for the same steps at the same site (minus prose, which a mined subpath never carries): the
+ * `$_id:'_parent'` header with `Expand:true + expandedInto`, per-step Segment children carrying the STAMPED
+ * `EvalComplexity` + `Atomic|NeedsSplit` guards (#33 — a mounted subpath must never re-fire the providers),
+ * the typed `state:'plan-<kind>'` mid nodes, and the `_s`/`_m` id scheme `mountTemplate` grounds.
+ * @param steps [{kind, atomic=true}]   @param site {baseId, origin, target, depth=1}
+ */
+function toExpandPatch( steps, site ) {
+	const baseId = site.baseId, depth = site.depth == null ? 1 : site.depth;
+	const childIds = steps.map(( _, i ) => baseId + '_s' + i);
+	const tpl = [{ $_id: '_parent', Expand: true, expandedInto: childIds }];
+	let prev = site.origin;
+	steps.forEach(( st, i ) => {
+		const last = i === steps.length - 1;
+		const tnode = last ? site.target : baseId + '_m' + i;
+		const child = { _id: childIds[i], Segment: true, originNode: prev, targetNode: tnode,
+			depth, parentSeg: baseId, stepIndex: i, EvalComplexity: true };
+		if ( st.atomic !== false ) child.Atomic = true; else child.NeedsSplit = true;
+		child.stepKind = st.kind;
+		if ( !last ) tpl.push({ _id: tnode, Node: true, state: 'plan-' + st.kind });
+		tpl.push(child);
+		prev = tnode;
+	});
+	return tpl;
+}
+
+/**
+ * The method-FOREST skeleton per class: the observed variant multiset (the alternative subpaths that ARE the
+ * concept-method's body — the concept-method design (the lattice preprint)) + the digrams shared across ≥2 distinct variants (the
+ * common sub-methods the miner would fold).
+ * @returns { classes: { <cls>: { variants:[{tree,mult,canon}], shared:[digramKey] } } }
+ */
+function mineForest( entries ) {
+	const classes = {};
+	for ( const e of entries ) {
+		const mult = e.mult == null ? 1 : e.mult;
+		const cls = classes[e.cls] = classes[e.cls] || { variants: [], _byCanon: new Map() };
+		const canon = JSON.stringify(e.tree);
+		const cur = cls._byCanon.get(canon);
+		if ( cur ) cur.mult += mult;
+		else { const v = { tree: e.tree, mult, canon }; cls._byCanon.set(canon, v); cls.variants.push(v); }
+	}
+	for ( const cls of Object.values(classes) ) {
+		const inVariants = new Map(); // digramKey → # distinct variants containing it
+		for ( const v of cls.variants ) {
+			const present = new Set();
+			for ( const seq of siblingSequences(v.tree) )
+				for ( let i = 0; i + 1 < seq.length; i++ ) present.add(digramKey(seq[i], seq[i + 1]));
+			for ( const k of present ) inVariants.set(k, (inVariants.get(k) || 0) + 1);
+		}
+		cls.shared = [...inVariants.entries()].filter(( [, n] ) => n >= 2).map(( [k] ) => k).sort();
+		delete cls._byCanon;
+	}
+	return { classes };
+}
+
+module.exports = { mineDigrams, subExpansionIndex, foldSubpaths, toExpandPatch, mineForest,
+	NIL, TOP, bodyOf, siblingSequences };