skynet-graph 1.2.0

package/lib/authoring/decompose.js

@@ -0,0 +1,343 @@
+/*
+ * 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';
+/**
+ * Tree-decomposition pass on the concept-dependency graph (host-side authoring tool,
+ * zero core change) — the Mixture-of-Reasoners "tiling" brick (doc/WIP/HANDOFF.md §7
+ * Tier 1; SOTA subgraph-grammars brick iii; experiment E7).
+ *
+ * From a concept tree it DERIVES — does not guess — (a) the interface alphabet (the
+ * SEPARATOR facts a fork frontier should cross) and (b) the hierarchical tiling (the
+ * candidate forks), and reports the TREEWIDTH as the inference cost bound: a low
+ * treewidth with thin separators means partitioning pays (cheap merge traffic, the
+ * #P-avoidance made operational); a dense corpus with high treewidth and no thin cut
+ * means it does not. It feeds fork creation (`Graph.fork`/`merge` with a snapped
+ * frontier — see lib/providers/merge-consistency.js for the C1 cross-boundary contract).
+ *
+ *   const { treeDecomposition } = require('./decompose');
+ *   const { treewidth, separators, tiles, partitionPays } = treeDecomposition(tree);
+ *
+ * Model (static analysis — no engine runtime):
+ *   - PRIMAL graph: facts = vertices; each concept's referenced fact-set is a clique
+ *     (a factor over those facts). `conceptCliques(tree)` extracts the fact-sets.
+ *   - MIN-FILL elimination -> treewidth (exact treewidth is NP-hard, Bodlaender 1996,
+ *     so this is the standard min-fill heuristic — an upper bound).
+ *   - ARTICULATION points (Tarjan) -> candidate separator facts = the interface alphabet.
+ *   - COMPONENTS after removing the separators -> the tiles (forks).
+ *
+ * Fact extraction note: this keys a cross-object walk ref (`a:b`) on its WALK BASE
+ * (the fact named first), which is the vertex the dependency hangs off in the primal
+ * graph — deliberately the same heuristic that recovered the planted structure in E7
+ * (synthetic -> {cost,risk}; real `common` -> [Distance,Stay]). validate.js keys the
+ * walk TARGET instead (it judges the resolved fact, a different question); the two are
+ * intentionally not unified.
+ */
+
+// ---- fact extraction: the cliques (one fact-set per concept) ----
+
+const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+// $ref / $$ref token in an assert/ensure expression (no ':' in the class -> a cross-walk
+// ref is captured at its base, e.g. `$$clock:tick` -> `clock`).
+const EXPR_REF_RE = /\$\$?[A-Za-z_][\w.]*/g;
+
+// The fact keys one concept node references — its self-flag, its require LHS facts, the
+// refs inside its assert/ensure, and the keys its applyMutations template writes.
+function conceptFacts( node ) {
+	const schema = (node && node._schema) || node || {};
+	const f = new Set();
+	if ( node && node._name ) f.add(node._name);
+	for ( const r of asArray(schema.require) )
+		if ( typeof r === 'string' ) f.add(r.split(':').pop());           // walk base of a require LHS
+	for ( const e of asArray(schema.assert).concat(asArray(schema.ensure)) ) {
+		if ( typeof e !== 'string' ) continue;
+		for ( const t of (e.match(EXPR_REF_RE) || []) )
+			f.add(t.replace(/^\$+/, '').split('.')[0].split(':').pop());   // strip $, drop .member, walk base
+	}
+	for ( const mu of asArray(schema.applyMutations) )
+		if ( mu && typeof mu === 'object' )
+			for ( const k of Object.keys(mu) ) if ( !k.startsWith('$') && k !== '_id' ) f.add(k);
+	return [...f];
+}
+
+// Walk the concept tree (same node semantics as validate.js#eachConcept: a node is a
+// concept iff it is a child entry or carries a `_name`; the synthetic root container is
+// not) and collect one non-empty clique per concept.
+function conceptCliques( tree ) {
+	const cliques = [];
+	const walk = ( node, isChild ) => {
+		if ( !node || typeof node !== 'object' ) return;
+		if ( isChild || node._name ) {
+			const c = conceptFacts(node);
+			if ( c.length ) cliques.push(c);
+		}
+		const kids = node.childConcepts;
+		if ( kids ) for ( const k of Object.keys(kids) ) walk(kids[k], true);
+	};
+	walk(tree, false);
+	return cliques;
+}
+
+// ---- graph algorithms ----
+
+function primalAdj( cliques ) {
+	const adj = new Map();
+	const add = (a, b) => { if ( !adj.has(a) ) adj.set(a, new Set()); if ( a !== b ) adj.get(a).add(b); };
+	for ( const cl of cliques ) for ( const a of cl ) { add(a, a); for ( const b of cl ) add(a, b); }
+	return adj;
+}
+
+// Min-fill elimination ordering -> a tree decomposition; bag sizes give the treewidth
+// (max bag - 1). Heuristic: pick the vertex whose elimination adds the fewest fill edges.
+// ALSO returns the bag-intersection SEPARATORS: when vertex v is eliminated, its higher-neighbour set
+// nb(v) is exactly B_v ∩ parent(B_v) in the resulting tree decomposition (Robertson-Seymour 1986) — the
+// REAL Σ_sep family (k-aware minimal separators of the chordal completion, monotone under edge addition,
+// Dirac 1961), NOT the size-1 articulation cuts. `treewidth` is a SCALAR PROJECTION that loses this.
+function minFillTreewidth( adj ) {
+	const G = new Map([...adj].map(([k, s]) => [k, new Set(s)]));
+	const remaining = new Set(G.keys());
+	const bags = [], separators = [];
+	while ( remaining.size ) {
+		let best = null, bestFill = Infinity;
+		for ( const v of remaining ) {
+			const nb = [...G.get(v)].filter((x) => remaining.has(x));
+			let fill = 0;
+			for ( let i = 0; i < nb.length; i++ )
+				for ( let j = i + 1; j < nb.length; j++ )
+					if ( !G.get(nb[i]).has(nb[j]) ) fill++;
+			if ( fill < bestFill ) { bestFill = fill; best = v; }
+		}
+		const nb = [...G.get(best)].filter((x) => remaining.has(x));
+		bags.push(new Set([best, ...nb]));
+		if ( nb.length ) separators.push(new Set(nb));   // B_best ∩ parent = the bag-intersection separator
+		for ( let i = 0; i < nb.length; i++ )            // make the neighbourhood a clique (fill in)
+			for ( let j = i + 1; j < nb.length; j++ ) { G.get(nb[i]).add(nb[j]); G.get(nb[j]).add(nb[i]); }
+		remaining.delete(best);
+	}
+	return { bags, treewidth: Math.max(0, ...bags.map((b) => b.size)) - 1, separators };
+}
+
+// A bag-intersection separator `s` SPLITS the corpus iff removing it leaves ≥2 components. It is MINIMAL
+// iff no single-element-smaller subset also splits (a sufficient, conservative minimality test — Robertson-
+// Seymour minimal separators). The MINIMAL splitting separators are the thin cross-tile interfaces (the
+// articulation points are exactly their size-1 case); their union is the cross-tile separator alphabet Σ_sep.
+function isMinimalSplit( adj, s ) {
+	if ( componentsWithout(adj, s).length < 2 ) return false;
+	for ( const v of s ) {
+		const sub = new Set([...s].filter(( x ) => x !== v));
+		if ( sub.size && componentsWithout(adj, sub).length >= 2 ) return false;   // a proper subset already splits → not minimal
+	}
+	return true;
+}
+
+/**
+ * The bounded-context HORIZON of a primal graph (E7/Σ_sep) — the OBJECT the scalar treewidth + the size-1
+ * articulation `separators` both PROJECT AWAY. Reconstructs the bag-intersection separators from the min-fill
+ * elimination and reports:
+ *   - `sigmaSep`          the cross-tile separator alphabet = ∪ of the MINIMAL splitting separators (the thin
+ *                         interface facts; generalises articulation points to size-k cuts);
+ *   - `minimalInterface`  the THINNEST splitting separator `{ size, sep }` — the horizon WIDTH. A grammar refactor
+ *                         that grows it (a size-1 cut → a size-2 cut) regressed the bound even when the scalar
+ *                         treewidth is unchanged AND no new articulation key appeared (the killer case).
+ *   - `indivisible`       true if NO bag-separator splits (one blob); then the "width" is the whole bag (treewidth+1).
+ *   - `treewidth`         kept as a DIAGNOSTIC only (min-fill is an uncoupled upper bound → unsound as a scalar gate).
+ */
+function bagInterface( cliques ) {
+	const adj = primalAdj(cliques);
+	const { treewidth, separators } = minFillTreewidth(adj);
+	const sigma = new Set();
+	let min = null;
+	for ( const s of separators ) {
+		if ( !isMinimalSplit(adj, s) ) continue;
+		for ( const f of s ) sigma.add(f);
+		if ( !min || s.size < min.size ) min = { size: s.size, sep: [...s].sort() };
+	}
+	return {
+		treewidth,
+		bagSeparators: separators.map(( s ) => [...s].sort()),
+		sigmaSep: [...sigma].sort(),
+		minimalInterface: min || { size: Math.max(1, treewidth + 1), sep: [...adj.keys()].sort() },
+		indivisible: !min,
+	};
+}
+
+// Tarjan articulation points — the cut vertices whose removal disconnects the primal
+// graph = the candidate separator facts (the interface alphabet between tiles).
+function articulationPoints( adj ) {
+	const disc = new Map(), low = new Map(), ap = new Set();
+	let timer = 0;
+	const dfs = (u, parent) => {
+		disc.set(u, ++timer); low.set(u, timer);
+		let children = 0;
+		for ( const v of adj.get(u) ) {
+			if ( !disc.has(v) ) {
+				children++; dfs(v, u);
+				low.set(u, Math.min(low.get(u), low.get(v)));
+				if ( parent !== null && low.get(v) >= disc.get(u) ) ap.add(u);
+			} else if ( v !== parent ) {
+				low.set(u, Math.min(low.get(u), disc.get(v)));
+			}
+		}
+		if ( parent === null && children > 1 ) ap.add(u);
+	};
+	for ( const v of adj.keys() ) if ( !disc.has(v) ) dfs(v, null);
+	return ap;
+}
+
+// Connected components of the primal graph with the `removed` vertices (separators) cut out.
+function componentsWithout( adj, removed ) {
+	const seen = new Set(), comps = [];
+	for ( const s of adj.keys() ) {
+		if ( seen.has(s) || removed.has(s) ) continue;
+		const comp = [], stack = [s]; seen.add(s);
+		while ( stack.length ) {
+			const u = stack.pop(); comp.push(u);
+			for ( const v of adj.get(u) ) if ( !seen.has(v) && !removed.has(v) ) { seen.add(v); stack.push(v); }
+		}
+		comps.push(comp);
+	}
+	return comps;
+}
+
+/**
+ * Decompose a primal graph given directly as cliques (fact-name arrays). Use this when
+ * you already have the fact-sets; `treeDecomposition` extracts them from a concept tree.
+ * @returns { nFacts, nConcepts, treewidth, separators, tiles, nTiles, bags, partitionPays }
+ */
+function decomposeCliques( cliques ) {
+	const adj = primalAdj(cliques);
+	const { bags, treewidth } = minFillTreewidth(adj);
+	const sepSet = articulationPoints(adj);
+	const separators = [...sepSet].sort();
+	const tiles = componentsWithout(adj, sepSet)
+		.filter((c) => c.length)
+		.map((c) => c.sort())
+		.sort((a, b) => b.length - a.length);
+	return {
+		nFacts: adj.size,
+		nConcepts: cliques.length,
+		treewidth,
+		separators,
+		tiles,
+		nTiles: tiles.length,
+		bags: bags.map((b) => [...b].sort()),
+		// partition pays when there is a thin cut AND it actually splits the corpus
+		partitionPays: separators.length > 0 && tiles.length > 1
+	};
+}
+
+/**
+ * Run the tree-decomposition pass over a concept tree.
+ * @param tree the nested concept tree (root container or a concept node)
+ * @returns the `decomposeCliques` result for the derived cliques.
+ */
+function treeDecomposition( tree ) {
+	return decomposeCliques(conceptCliques(tree));
+}
+
+// Walk the tree collecting { name, facts:Set } per concept (the named form of conceptCliques).
+function conceptsWithFacts( tree ) {
+	const out = [];
+	const walk = ( node, isChild ) => {
+		if ( !node || typeof node !== 'object' ) return;
+		if ( isChild || node._name ) {
+			const f = conceptFacts(node);
+			if ( f.length && node._name ) out.push({ name: node._name, facts: new Set(f) });
+		}
+		const kids = node.childConcepts;
+		if ( kids ) for ( const k of Object.keys(kids) ) walk(kids[k], true);
+	};
+	walk(tree, false);
+	return out;
+}
+
+/**
+ * Derive a FORK PLAN from the tree-decomposition — the "interface derivation" the SOTA synthesis
+ * flagged as the killer deliverable: assign each concept to a tile/fork (by where its non-separator
+ * facts fall) and derive each fork's FRONTIER ALPHABET (the separator facts its concepts touch =
+ * what crosses that fork boundary). Feeds `Graph.fork`/`merge` AND the `validateMergeProjection`
+ * frontier alphabet. Hub concepts (only separator facts) are reported as `interface` glue, not tiled.
+ * @returns { treewidth, separators, partitionPays, forks:[{ facts, concepts, frontier }], interface:[names] }
+ */
+function forkPlan( tree ) {
+	const concepts = conceptsWithFacts(tree);
+	const decomp = decomposeCliques(concepts.map((c) => [...c.facts]));
+	const sepSet = new Set(decomp.separators);
+
+	// fact -> tile index (non-separator facts only; tiles are the post-cut components)
+	const tileOf = new Map();
+	decomp.tiles.forEach((t, i) => t.forEach((f) => tileOf.set(f, i)));
+
+	const forks = decomp.tiles.map((tile) => ({ facts: tile, concepts: [], frontier: new Set() }));
+	const iface = [];
+	for ( const c of concepts ) {
+		const votes = {};
+		const seps = [];
+		for ( const f of c.facts ) {
+			if ( sepSet.has(f) ) seps.push(f);
+			else if ( tileOf.has(f) ) votes[tileOf.get(f)] = (votes[tileOf.get(f)] || 0) + 1;
+		}
+		const best = Object.keys(votes).sort((a, b) => votes[b] - votes[a])[0];
+		if ( best == null ) { iface.push(c.name); continue; }       // only separator facts -> interface glue
+		forks[best].concepts.push(c.name);
+		seps.forEach((s) => forks[best].frontier.add(s));
+	}
+
+	return {
+		treewidth: decomp.treewidth,
+		separators: decomp.separators,
+		partitionPays: decomp.partitionPays,
+		forks: forks.map((p) => ({ facts: p.facts, concepts: p.concepts.sort(), frontier: [...p.frontier].sort() })),
+		interface: iface.sort()
+	};
+}
+
+/**
+ * §6.3 separatorGate — the SEPARATOR HORIZON check (the §3.3 obligation `params ∪ appConditions ∪ requiredFacts
+ * ⊆ Σ_sep`). A proposed ancestry projection (the facts the ancestry oracle would promote to runtime params / fold
+ * into the memo digest KEY) is sound iff every projected fact is a CROSS-TILE SEPARATOR fact (on the horizon) —
+ * never a fact above the separator (in another tile's interior), which a runtime read would reach past the horizon.
+ *   • Σ_sep = the bag-intersection minimal splitting separators (NOT the global articulation points: those are the
+ *     size-1 cut family only, and a global cut-vertex elsewhere is NOT on THIS projection's horizon — `bagInterface`).
+ *   • a projected fact ∉ Σ_sep is "above-separator" → REFUSED (the spec compiles it to a baked constant / forged hole).
+ * Pairs with the memo-key MONOTONICITY (a finer key never false-hits): key-enlargement is safe for memo correctness,
+ * but ONLY this gate makes it bound-safe (the digest read at dispatch is itself a `requiredFact`).
+ * @returns { ok, above:[facts ∉ Σ_sep], sigmaSep }
+ */
+function separatorGate( tree, projectionFacts ) {
+	const iface = bagInterface(conceptCliques(tree));
+	const sigma = new Set(iface.sigmaSep);
+	const above = (projectionFacts || []).filter(( f ) => !sigma.has(f));
+	return { ok: above.length === 0, above, sigmaSep: iface.sigmaSep };
+}
+
+module.exports = {
+	treeDecomposition,
+	forkPlan,
+	decomposeCliques,
+	conceptCliques,
+	conceptFacts,
+	// §6.3 — the bag-intersection separator horizon (the real Σ_sep) + the gate
+	bagInterface,
+	separatorGate,
+	isMinimalSplit,
+	// lower-level graph primitives (exported for reuse / testing)
+	primalAdj,
+	minFillTreewidth,
+	articulationPoints,
+	componentsWithout
+};

package/lib/authoring/emittability.js

@@ -0,0 +1,236 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * emittability — the SIGNATURE-STABILITY / paraphrase-consistency profiler (roadmap STAGE-0 Grammar-P1
+ * instrument, 2026-07-01). Read-only measurement: given the intake `FactsDigest` a small model produces
+ * for many PARAPHRASES of the same latent task, does the typed signature stay STABLE? Everything
+ * downstream (dispatch, cache, call-elision, method reuse) keys on that digest; if paraphrases fragment
+ * the key, the memo never hits (K1 fragmentation) — so this is the component SCREEN feeding the
+ * end-to-end call-count gate (paper-dll arms). It is NOT itself the make-or-break gate (Laurie confront).
+ *
+ * TWO failure modes, not one (Laurie confront — the load-bearing correction):
+ *   • FRAGMENTATION (cheap): paraphrases of ONE task scatter into several digests → wasted calls.
+ *     Measured by within-task agreement (`collisionProb`, the unbiased Simpson estimator).
+ *   • COLLISION (correctness-fatal): TWO DIFFERENT tasks land on the SAME digest → the memo returns the
+ *     WRONG method. Measured by cross-task HOMOGENEITY of the pooled partition (V-measure).
+ * A scheme that maps EVERYTHING to one tuple scores perfect within-task agreement and is catastrophic;
+ * only the pooled two-partition view (reference=task vs induced=digest) catches that. So we report BOTH,
+ * with a HIGHER bar on homogeneity than on completeness.
+ *
+ * Chance correction (the vacuousness alarm): raw agreement can't tell "stable" from "always emits the same
+ * enum". Fleiss' κ (1971) subtracts the pooled-marginal chance agreement → κ→0 under mode collapse even as
+ * raw agreement→1 (the κ paradox under skew is here a FEATURE). NOTE for the memo, chance agreement is REAL
+ * value (a hit is a hit), so `collisionProb` is the OPERATIONAL number and κ is the VALIDITY/discrimination
+ * number — reported side by side, never conflated.
+ *
+ * The "by construction" split (the crux): grammar-constrained decoding guarantees FORMAT VALIDITY + VOCAB
+ * CLOSURE (digest drawn from a finite known set → H(D|T) bounded). It does NOT guarantee SEMANTIC
+ * consistency (which enum member → H(D|T)≈0, nuisance-invariance in the Information-Bottleneck sense) — and
+ * can DISTORT it (Park et al. 2024, Grammar-Aligned Decoding). So to measure the semantic half you must NET
+ * OUT format: compare arms only on inputs where BOTH emitted an in-vocab label (`crossArmAgreement`).
+ *
+ * `untyped` is NOT dropped (survivorship bias) — it is its own digest class ⊥; `typedRate` is reported
+ * separately from the digest agreement. Refs: Simpson 1949; Fleiss 1971; Rosenberg & Hirschberg 2007
+ * (V-measure); Hubert & Arabie 1985 (ARI); Errica et al. 2025 (sensitivity/consistency of LM labels).
+ *
+ * Pure + synchronous (unit-tested). No engine coupling — it consumes plain intake-result records.
+ */
+
+var UNTYPED = '⊥';   // ⊥ — the digest class for a non-typed (out-of-vocab / errored) intake.
+
+// the digest CLASS of one intake result: its FactsDigest when typed, else ⊥.
+function signatureClass( r ) {
+	return (r && r.status === 'typed' && r.digest != null) ? String(r.digest) : UNTYPED;
+}
+
+function countBy( items, keyOf ) {
+	var m = new Map();
+	items.forEach(function ( x ) { var k = keyOf(x); m.set(k, (m.get(k) || 0) + 1); });
+	return m;
+}
+
+function log2( x ) { return Math.log(x) / Math.LN2; }
+
+// Shannon entropy (bits) of a count map over N items.
+function entropyOf( counts, N ) {
+	if ( !N ) return 0;
+	var h = 0;
+	counts.forEach(function ( n ) { if ( n > 0 ) { var p = n / N; h -= p * log2(p); } });
+	return h;
+}
+
+/**
+ * Within-task statistics for ONE task's paraphrase results.
+ * @param results [{status, digest}]  the K paraphrase intake results for one latent task.
+ * @param classOf (optional) override the class projection (for per-field marginals).
+ * @returns { K, typedRate, collisionProb, modalCoverage, effectiveSignatures, numClasses, counts }
+ *   collisionProb   — UNBIASED Simpson estimator Σ n_i(n_i-1)/[K(K-1)] = P(two paraphrases collide on the
+ *                     same digest) = the memo-hit event. null when K<2. PRIMARY.
+ *   modalCoverage   — max n_i / K. SECONDARY (upward-biased at small K — flag, don't lead with it).
+ *   effectiveSignatures — 1/Σ p_i^2 (plug-in Hill-2): how many memo keys one task splinters into.
+ */
+function perTaskStats( results, classOf ) {
+	classOf = classOf || signatureClass;
+	var K = results.length;
+	var typed = results.filter(function ( r ) { return r && r.status === 'typed'; }).length;
+	var counts = countBy(results, classOf);
+	var sumNiNi1 = 0, sumP2 = 0, modal = 0;
+	counts.forEach(function ( n ) { sumNiNi1 += n * (n - 1); sumP2 += (n / K) * (n / K); if ( n > modal ) modal = n; });
+	return {
+		K: K,
+		typedRate: K ? typed / K : 0,
+		collisionProb: K > 1 ? sumNiNi1 / (K * (K - 1)) : null,
+		modalCoverage: K ? modal / K : 0,
+		effectiveSignatures: sumP2 > 0 ? 1 / sumP2 : 0,
+		numClasses: counts.size,
+		counts: counts,
+	};
+}
+
+/**
+ * Pooled two-partition agreement over ALL tasks (reference partition = taskId, induced = digest class).
+ * @param groups [{ taskId, results:[{status,digest}] }]
+ * @returns { N, homogeneity, completeness, vMeasure, ari, miBits, hClass, hCluster }
+ *   homogeneity  — 1 - H(task|digest)/H(task): each digest holds ONE task = COLLISION-FREE (the safety
+ *                  direction; bar it HIGH).
+ *   completeness — 1 - H(digest|task)/H(digest): each task's paraphrases share ONE digest = consistency.
+ *   vMeasure     — harmonic mean (the rate-distortion pair collapsed to one number; report H & C too).
+ *   ari          — Adjusted Rand Index (chance-corrected pooled agreement, Hubert & Arabie 1985).
+ */
+function poolAgreement( groups, classOf ) {
+	classOf = classOf || signatureClass;
+	var points = [];
+	groups.forEach(function ( g ) { g.results.forEach(function ( r ) { points.push({ cls: g.taskId, clu: classOf(r) }); }); });
+	var N = points.length;
+	if ( !N ) return { N: 0, homogeneity: 1, completeness: 1, vMeasure: 1, ari: 1, miBits: 0, hClass: 0, hCluster: 0 };
+
+	var classCounts = countBy(points, function ( p ) { return p.cls; });
+	var cluCounts   = countBy(points, function ( p ) { return p.clu; });
+	// joint contingency table keyed "cls
clu"
+	var joint = countBy(points, function ( p ) { return p.cls + '
' + p.clu; });
+
+	var hClass = entropyOf(classCounts, N), hCluster = entropyOf(cluCounts, N);
+	// H(class|cluster) = Σ_k (|k|/N) H(class within k) = H(class,cluster) - H(cluster)
+	var hJoint = entropyOf(joint, N);
+	var hClassGivenClu = hJoint - hCluster;         // ≥0 (numerical clamp below)
+	var hCluGivenClass = hJoint - hClass;
+	if ( hClassGivenClu < 0 ) hClassGivenClu = 0;
+	if ( hCluGivenClass < 0 ) hCluGivenClass = 0;
+
+	var homogeneity  = hClass  === 0 ? 1 : 1 - hClassGivenClu / hClass;
+	var completeness = hCluster === 0 ? 1 : 1 - hCluGivenClass / hCluster;
+	var vMeasure = (homogeneity + completeness) === 0 ? 0 : 2 * homogeneity * completeness / (homogeneity + completeness);
+	var miBits = hCluster - hCluGivenClass;         // I(class;cluster)
+
+	// ── Adjusted Rand Index (Hubert & Arabie 1985) ──
+	var choose2 = function ( n ) { return n * (n - 1) / 2; };
+	var sumJoint = 0; joint.forEach(function ( n ) { sumJoint += choose2(n); });
+	var sumA = 0; classCounts.forEach(function ( n ) { sumA += choose2(n); });
+	var sumB = 0; cluCounts.forEach(function ( n ) { sumB += choose2(n); });
+	var totPairs = choose2(N);
+	var expected = totPairs ? (sumA * sumB) / totPairs : 0;
+	var maxIndex = (sumA + sumB) / 2;
+	var ari = (maxIndex - expected) === 0 ? 1 : (sumJoint - expected) / (maxIndex - expected);
+
+	return { N: N, homogeneity: homogeneity, completeness: completeness, vMeasure: vMeasure, ari: ari, miBits: miBits, hClass: hClass, hCluster: hCluster };
+}
+
+/**
+ * Fleiss' κ (1971) over tasks: items = tasks, ratings = the K paraphrase digest-classes, categories = the
+ * union of digest classes seen. The vacuousness alarm: mode collapse → Pe→1 → κ→0 (or vacuous). Handles
+ * per-item K_i (generalized). @returns { kappa, Pbar, Pe, vacuous }
+ */
+function fleissKappa( groups, classOf ) {
+	classOf = classOf || signatureClass;
+	var perItem = groups.map(function ( g ) {
+		var K = g.results.length;
+		var counts = countBy(g.results, classOf);
+		var sumSq = 0; counts.forEach(function ( n ) { sumSq += n * n; });
+		var Pi = K > 1 ? (sumSq - K) / (K * (K - 1)) : null;   // = the unbiased Simpson for this item
+		return { counts: counts, K: K, Pi: Pi };
+	}).filter(function ( it ) { return it.Pi != null; });
+	if ( !perItem.length ) return { kappa: null, Pbar: null, Pe: null, vacuous: true };
+
+	var Pbar = perItem.reduce(function ( s, it ) { return s + it.Pi; }, 0) / perItem.length;
+	var totalRatings = perItem.reduce(function ( s, it ) { return s + it.K; }, 0);
+	var catTotals = new Map();
+	perItem.forEach(function ( it ) { it.counts.forEach(function ( n, cat ) { catTotals.set(cat, (catTotals.get(cat) || 0) + n); }); });
+	var Pe = 0; catTotals.forEach(function ( n ) { var p = n / totalRatings; Pe += p * p; });
+	var vacuous = (1 - Pe) < 1e-12;
+	return { kappa: vacuous ? null : (Pbar - Pe) / (1 - Pe), Pbar: Pbar, Pe: Pe, vacuous: vacuous };
+}
+
+/**
+ * Cross-arm SEMANTIC agreement, format NETTED OUT (the (a)/(b)-isolating comparison — Laurie + SOTA).
+ * Given two arms' results ALIGNED by input index, restrict to inputs where BOTH are `typed`
+ * (both in-vocab) and report the fraction whose digest AGREES. This is what tells whether the grammar
+ * constraint changes the SEMANTIC choice vs a format-guaranteed control — could be ≤0 (Park et al. 2024).
+ * @param a,b  aligned arrays [{status,digest}] (same inputs, same order).
+ * @returns { nBothTyped, agree, agreeFraction, aTypedRate, bTypedRate }
+ */
+function crossArmAgreement( a, b ) {
+	var n = Math.min(a.length, b.length), both = 0, agree = 0, at = 0, bt = 0;
+	for ( var i = 0; i < n; i++ ) {
+		var ta = a[i] && a[i].status === 'typed', tb = b[i] && b[i].status === 'typed';
+		if ( ta ) at++; if ( tb ) bt++;
+		if ( ta && tb ) { both++; if ( String(a[i].digest) === String(b[i].digest) ) agree++; }
+	}
+	return { nBothTyped: both, agree: agree, agreeFraction: both ? agree / both : null, aTypedRate: n ? at / n : 0, bTypedRate: n ? bt / n : 0 };
+}
+
+/**
+ * Aggregate profile for one arm over many paraphrase-task groups.
+ * @param groups [{ taskId, results:[{status,digest,facts?}] }]
+ * @param opts.fields  optional [fieldName...] → also report per-field MARGINAL stability (a low marginal
+ *                     localizes the instability + flags a field that should be DEMOTED off the tracked digest).
+ * @returns aggregate (per-task array, means with the replication unit = TASK, pooled agreement, κ, marginals)
+ */
+function profile( groups, opts ) {
+	opts = opts || {};
+	var perTask = groups.map(function ( g ) {
+		var s = perTaskStats(g.results);
+		return { taskId: g.taskId, K: s.K, typedRate: s.typedRate, collisionProb: s.collisionProb, modalCoverage: s.modalCoverage, effectiveSignatures: s.effectiveSignatures, numClasses: s.numClasses };
+	});
+	var withCollision = perTask.filter(function ( t ) { return t.collisionProb != null; });
+	var mean = function ( arr, f ) { return arr.length ? arr.reduce(function ( s, x ) { return s + f(x); }, 0) / arr.length : null; };
+
+	var out = {
+		nTasks: groups.length,                                          // the replication unit for population claims
+		perTask: perTask,
+		meanCollisionProb: mean(withCollision, function ( t ) { return t.collisionProb; }),
+		meanModalCoverage: mean(perTask, function ( t ) { return t.modalCoverage; }),
+		meanTypedRate: mean(perTask, function ( t ) { return t.typedRate; }),
+		minCollisionProb: withCollision.length ? Math.min.apply(null, withCollision.map(function ( t ) { return t.collisionProb; })) : null,
+		pool: poolAgreement(groups),
+		fleiss: fleissKappa(groups),
+	};
+	if ( opts.fields ) {
+		out.marginals = {};
+		opts.fields.forEach(function ( field ) {
+			var proj = function ( r ) {
+				if ( !r || r.status !== 'typed' || !r.facts || r.facts[field] == null ) return UNTYPED;
+				return field + '=' + String(r.facts[field]);
+			};
+			var pt = groups.map(function ( g ) { var s = perTaskStats(g.results, proj); return { taskId: g.taskId, collisionProb: s.collisionProb, modalCoverage: s.modalCoverage }; });
+			var wc = pt.filter(function ( t ) { return t.collisionProb != null; });
+			out.marginals[field] = { perTask: pt, meanCollisionProb: mean(wc, function ( t ) { return t.collisionProb; }), pool: poolAgreement(groups, proj) };
+		});
+	}
+	return out;
+}
+
+module.exports = {
+	UNTYPED: UNTYPED,
+	signatureClass: signatureClass,
+	perTaskStats: perTaskStats,
+	poolAgreement: poolAgreement,
+	fleissKappa: fleissKappa,
+	crossArmAgreement: crossArmAgreement,
+	profile: profile,
+	_entropyOf: entropyOf,   // exported for the unit test
+};