skynet-graph 1.2.0

package/lib/authoring/glossary.js

@@ -0,0 +1,177 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * glossary — the P2 cross-round terminology REFERENCE (the "glossaire de campagne"): a persistent,
+ * lattice-backed store of canonical GROUNDED notions (theses / arguments / tags) that follows the pool
+ * BETWEEN refinement rounds. It is the condition of a reliable re-split (the C9 re-plan / the generative
+ * loop's round 2): without a managed reference, duplicates go invisible, meaning drifts, and a re-split
+ * cites phantom keys. It is [ZERO-CORE] — it ASSEMBLES organs that already exist and are tested:
+ *
+ *   • RECONCILIATION composes TWO gates (they compose, they do not compete):
+ *       – witness-overlap ≥ θ = the GROUNDED semantic selector — which existing notion a new term duplicates
+ *         (it picks the ring MEMBER). Same denominator as the generative loop's merge check (critique.js).
+ *       – `registry.js#mergeRingProposals` = the SAFETY + AUDIT layer — it admits the alias under CONFLUENCE
+ *         (a surface phrasing can never denote TWO notions → no silent collision), tags provenance, and BUMPS
+ *         the version (the invalidation signal that version-gates stale caches/digests). A bad merge is
+ *         RETRACTABLE (`retractRingAlias`) — a plain Set (the harness) can do none of this.
+ *   • ENTRY-level JTMS retract (a notion whose witnesses left the pool) cascades via the uniform in-pool test
+ *     — the same structural reconcile the C9/boucle-generative harness proved, here over the PERSISTENT store.
+ *
+ * Modelled as a registry with ONE Tier-2 key `notion` whose `enum` GROWS as notions are harvested (the
+ * canonical ids) and whose `synonyms[id]` holds the surface phrasings; the ring primitives operate
+ * generically on `reg.keys[key]`, so a hand-built single-key registry is a legal registry.
+ *
+ *   const g = createGlossary();
+ *   g.harvest({ text: 'open-source maximizes adoption', witnesses: ['p1','p3'], side: 'PRO' });  // → {status:'added', id:'n1'}
+ *   g.harvest({ text: 'openness drives uptake',        witnesses: ['p1','p4'], side: 'PRO' });  // → {status:'merged', id:'n1'} (overlap 0.5, alias audited)
+ *   g.inject();                                                                                  // citable vocabulary block
+ *   g.reconcile(pool);                                                                           // JTMS entry-retract (witnesses gone → cascade)
+ *
+ * NOTE: a notion enters the ring only when GROUNDED (≥1 witness) — 0-fabrication: harvest never invents a
+ * witness, inject renders only the store. An ungrounded (open) point is not a canonical notion yet.
+ */
+const { digest, normToken } = require('../providers/canonicalize.js');
+const { mergeRingProposals, retractRingAlias, creditRingAlias } = require('./registry.js');
+const { clusterByGrounding, arbitrate } = require('./granularity.js');
+
+const overlapOf = ( a, b ) => {                                                 // |shared| / |candidate|, candidate = a
+	if ( !a.length ) return 0;
+	const set = new Set(b);
+	return a.filter(( x ) => set.has(x) ).length / a.length;
+};
+
+function createGlossary( opts ) {
+	opts = opts || {};
+	const KEY = opts.key || 'notion';
+	const THETA = opts.overlap != null ? opts.overlap : 0.5;
+	// a legal single-key registry (Tier-2, open interior); the ring primitives read `reg.keys[key]` generically.
+	let registry = { version: 'v1', frozen: false, conflicts: [], ringProvenance: {},
+		keys: { [KEY]: { tier: 2, enum: [], synonyms: {}, producers: [], consumers: [], values: [] } } };
+	const entries = new Map();                                                  // id -> { id, text, witnesses[], side, type, round, provenance, status, aliases[] }
+	let counter = 0;
+
+	const memberOfAlias = ( text ) => {                                        // the notion a surface phrasing already denotes (or null)
+		const na = normToken(text), syn = registry.keys[KEY].synonyms || {};
+		for ( const m of Object.keys(syn) ) if ( (syn[m] || []).some(( a ) => normToken(a) === na ) ) return m;
+		return null;
+	};
+	const propose = ( member, alias, via ) => {                                // admit an alias through the CONFLUENCE gate; swap in the grown (versioned) registry on admit
+		const r = mergeRingProposals(registry, [{ key: KEY, member, alias, via: via || 'harvest' }]);
+		if ( r.admitted.length ) { registry = r.registry; return { admitted: true }; }
+		return { admitted: false, reason: (r.rejected[0] && r.rejected[0].reason) || 'rejected' };
+	};
+
+	/**
+	 * Harvest one grounded element into the glossary. Returns the reconciliation outcome:
+	 *   { status:'added', id }          a NEW canonical notion
+	 *   { status:'merged', id, alias }  a duplicate of `id` (surface identity OR grounded overlap ≥ θ) — alias audited
+	 *   { status:'conflict', id, rejectedReason }  the surface would denote TWO notions — SURFACED, never silently merged
+	 *   { status:'ungrounded' }         no witness → not a canonical notion (0-fabrication)
+	 * @param entry { text, witnesses:[argId], side?, type?, round?, provenance? }
+	 */
+	function harvest( entry ) {
+		const text = String((entry && entry.text) || '').trim();
+		const witnesses = ((entry && entry.witnesses) || []).slice();
+		if ( !text ) return { status: 'ungrounded', reason: 'no text' };
+		if ( !witnesses.length ) return { status: 'ungrounded', reason: 'no witness (0-fabrication: a notion enters the ring only when grounded)' };
+		const side = entry.side != null ? String(entry.side).toUpperCase() : null;
+
+		// (1) SURFACE IDENTITY — the exact phrasing already names a notion → that notion, definitively.
+		const surf = memberOfAlias(text);
+		if ( surf ) { entries.get(surf).aliases.push({ text, witnesses, via: 'surface' }); return { status: 'merged', id: surf, alias: text }; }
+
+		// (2) GROUNDED OVERLAP — witness-overlap ≥ θ picks the member; the ring gate admits/audits the alias.
+		let best = null, bestOv = 0;
+		for ( const e of entries.values() ) {
+			if ( e.status !== 'active' || !e.witnesses.length ) continue;
+			if ( side && e.side && e.side !== side ) continue;                 // never merge across sides
+			const ov = overlapOf(witnesses, e.witnesses);
+			if ( ov > bestOv ) { bestOv = ov; best = e; }
+		}
+		if ( best && bestOv >= THETA ) {
+			const r = propose(best.id, text, entry.provenance);
+			if ( r.admitted ) { best.aliases.push({ text, witnesses, via: entry.provenance || 'harvest' }); return { status: 'merged', id: best.id, alias: text }; }
+			return { status: 'conflict', id: best.id, rejectedReason: r.reason };   // confluence refused — SURFACED, not silently collided
+		}
+
+		// (3) NEW GROUNDED NOTION — extend the enum, register its text as the first alias (version bumps).
+		const id = 'n' + (++counter);
+		registry.keys[KEY].enum = registry.keys[KEY].enum.concat([id]);
+		const r = propose(id, text, entry.provenance);
+		if ( !r.admitted ) {                                                    // the text already denotes another notion → a disguised merge into its owner
+			registry.keys[KEY].enum = registry.keys[KEY].enum.filter(( x ) => x !== id );
+			const owner = memberOfAlias(text);
+			if ( owner ) { entries.get(owner).aliases.push({ text, witnesses, via: 'surface-late' }); return { status: 'merged', id: owner, alias: text }; }
+			counter--; return { status: 'conflict', id: null, rejectedReason: r.reason };
+		}
+		entries.set(id, { id, text, witnesses: witnesses.slice(), side, type: entry.type || null,
+			round: entry.round != null ? entry.round : 0, provenance: entry.provenance || 'harvest', status: 'active', aliases: [] });
+		return { status: 'added', id };
+	}
+
+	/**
+	 * JTMS entry-retract over the PERSISTENT store — an active notion whose witnesses no longer ALL live in the
+	 * pool is retracted. The uniform in-pool test gives the CASCADE for free (a shared witness leaving drops
+	 * every notion citing it; a notion retracted for one bad witness never drags down notions sharing its
+	 * still-valid witnesses). Pure + structural; identical logic to critique.js#reconcile, over the store.
+	 * @returns retracted ids
+	 */
+	function reconcile( pool ) {
+		const inPool = new Set((pool || []).map(( a ) => typeof a === 'string' ? a : a.id ));
+		const retracted = [];
+		for ( const e of entries.values() )
+			if ( e.status === 'active' && e.witnesses.length && !e.witnesses.every(( w ) => inPool.has(w) ) ) { e.status = 'retracted'; retracted.push(e.id); }
+		return retracted;
+	}
+
+	/** Render the canonical notions as a deterministic, sorted CITABLE-VOCABULARY block (the re-découpe injection). */
+	function inject( o ) {
+		o = o || {};
+		const activeOnly = o.activeOnly !== false;
+		const list = [...entries.values()].filter(( e ) => (activeOnly ? e.status === 'active' : true) && (!o.side || e.side === o.side) );
+		if ( !list.length ) return '';
+		return list.map(( e ) => '- ' + e.id + ': ' + e.text + (e.side ? ' [' + e.side + ']' : '') ).join('\n');
+	}
+	/** The set of citable notion ids — a re-ask that cites a key OUTSIDE this set is a phantom (caught by validation). */
+	function citableKeys( o ) {
+		o = o || {};
+		const activeOnly = o.activeOnly !== false;
+		return new Set([...entries.values()].filter(( e ) => (activeOnly ? e.status === 'active' : true)).map(( e ) => e.id ));
+	}
+
+	/** Retract a bad merge (a wrong alias) — the un-learn verb; bumps the version (the invalidation signal). */
+	function retractAlias( id, alias ) {
+		const r = retractRingAlias(registry, KEY, alias); registry = r.registry;
+		const e = entries.get(id); if ( e ) e.aliases = e.aliases.filter(( a ) => normToken(a.text) !== normToken(alias) );
+		return { retracted: r.retracted, member: r.member, version: registry.version };
+	}
+	/** Credit a verified reuse of an alias — support++, NEVER bumps the version (resolution semantics unchanged). */
+	function credit( alias ) {
+		const r = creditRingAlias(registry, KEY, alias); registry = r.registry;
+		return { member: r.member, support: r.support, version: registry.version };
+	}
+
+	// P2 granularity ARBITER over the active notions — group them into grounded dimensions (co-citation of
+	// witnesses) and return the lazy-2-régime frame verdict (coherent | mixed=the re-plan TOO-NARROW signal |
+	// unstructured=escalate to Q2). Delegates to granularity.js; the glossary just supplies its active notions.
+	const activeItems = ( o ) => [...entries.values()].filter(( e ) => e.status === 'active' && e.witnesses.length )
+		.map(( e ) => ({ id: e.id, witnesses: e.witnesses, side: e.side }) );
+	return {
+		harvest, reconcile, inject, citableKeys, retractAlias, credit,
+		cluster: ( o ) => clusterByGrounding(activeItems(o), o),
+		arbitrate: ( o ) => arbitrate(activeItems(o), o),
+		notions: ( o ) => [...entries.values()].filter(( e ) => !(o && o.activeOnly) || e.status === 'active' ),
+		get: ( id ) => entries.get(id) || null,
+		version: () => registry.version,
+		snapshot: () => ({ version: registry.version, notions: [...entries.values()].map(( e ) => ({ ...e, aliases: e.aliases.slice() })),
+			rings: JSON.parse(JSON.stringify(registry.keys[KEY].synonyms || {})), provenance: Object.assign({}, registry.ringProvenance) }),
+		fingerprint: () => digest({ v: registry.version, n: [...entries.values()].map(( e ) => e.id + ':' + e.status + ':' + e.witnesses.join(',') ).sort() })
+	};
+}
+
+module.exports = { createGlossary, overlapOf };

package/lib/authoring/grammar-graph.js

@@ -0,0 +1,191 @@
+/*
+ * 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';
+/**
+ * Grammar graph (host-side authoring tool, zero core change) — the second, orthogonal view
+ * the Studio was missing: not the IS-A tree (`childConcepts`, already shown), but the
+ * concept↔fact FLUX graph, where the real interactions live.
+ *
+ * A grammar's concepts interact through FACTS: a concept WRITES facts (its self-flag + the
+ * keys its `applyMutations` template sets) and READS facts (its `require` LHS + the `$ref`s in
+ * its `assert`/`ensure`, with the dependency's POLARITY — a `!$f` / `$f==false` read is a
+ * defeasance edge). Crossing two concept sets, a fact written in one set and read in another is
+ * a CROSS-CORPUS link; a fact written in two sets is a silent COLLISION (the `leadTime` trap);
+ * a fact read but produced by nobody is an external ENTRY POINT (seed / engine input).
+ *
+ *   const { conceptFactGraph } = require('./grammar-graph');
+ *   const g = conceptFactGraph({ common: tree, clinical: tree2 });
+ *   // g.concepts, g.facts, g.edges, g.crossCorpus, g.collisions, g.entryPoints, g.tiling
+ *
+ * The ref / polarity / produced-fact extraction reuses validate.js (single source of truth);
+ * the tiling overlay (separators / forks / frontier alphabets) comes from decompose.js#forkPlan.
+ * Pure static analysis — no engine runtime.
+ */
+const { eachConcept, refsOf, refKeyOf, templateKeys, negatedRefKeys } = require('./validate');
+const { parseExpression } = require('../graph/expr');
+const { forkPlan } = require('./decompose');
+
+const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+const schemaOf = (c) => (c && c._schema) || c || {};
+
+function conceptKind( schema ) {
+	const p = schema.provider;
+	if ( !p ) return 'pure';
+	const name = Array.isArray(p) ? p[0] : p;
+	return (typeof name === 'string' && name.startsWith('LLM::')) ? 'llm' : 'provider';
+}
+
+// A `$$key` in a mutation template marks a bagRef (external data) — detect it for the flag badge.
+function hasBagRef( applyMutations ) {
+	for ( const obj of asArray(applyMutations) ) {
+		if ( !obj || typeof obj !== 'object' ) continue;
+		for ( const k of Object.keys(obj) ) if ( k.startsWith('$$') ) return true;
+	}
+	return false;
+}
+
+function conceptFlags( schema ) {
+	return {
+		onCast       : !!schema.onCast,        // standing-cluster subscribe hook
+		cleaner      : !!schema.cleaner,        // retraction / teardown hook
+		autoCastFalse: schema.autoCast === false,
+		enum         : schema.type === 'enum',
+		bagRef       : hasBagRef(schema.applyMutations)
+	};
+}
+
+// Is this a set-map ({ setName: tree }) or a single bare tree (has its own childConcepts)?
+function asSetMap( conceptMap ) {
+	if ( conceptMap && Object.prototype.hasOwnProperty.call(conceptMap, 'childConcepts') )
+		return { default: conceptMap };
+	return conceptMap || {};
+}
+
+// Shallow-merge the top-level childConcepts of every set into one tree (nested childConcepts are
+// preserved) for the tiling overlay. An approximation of the engine's deepmerge — enough for the
+// static decomposition; a same-named top-level concept in two sets is overwritten (last wins).
+function mergeTrees( trees ) {
+	const childConcepts = {};
+	for ( const t of trees ) Object.assign(childConcepts, (t && t.childConcepts) || {});
+	return { childConcepts };
+}
+
+/**
+ * Build the concept↔fact grammar graph from a concept map (or a single tree).
+ * @param conceptMap { setName: tree, … }  or a single concept tree
+ * @returns {{
+ *   concepts: Array<{id,name,set,kind,flags}>,
+ *   facts:    Array<{key,producedBy:string[],consumedBy:Array<{name,polarity,via}>,sets:string[]}>,
+ *   edges:    Array<{kind:'writes',concept,fact} | {kind:'reads',concept,fact,polarity,via}>,
+ *   crossCorpus: Array<{fact,fromSet,toSet}>,
+ *   collisions:  Array<{fact,sets:string[]}>,
+ *   entryPoints: string[],
+ *   tiling: object|null
+ * }}
+ */
+function conceptFactGraph( conceptMap ) {
+	const map = asSetMap(conceptMap);
+	const sets = Object.keys(map);
+
+	const concepts = [];
+	const setOfConcept = new Map();          // concept name -> set
+	const edges = [];
+	const producersByFact = new Map();        // fact -> Set(concept name)
+	const producerSetsByFact = new Map();     // fact -> Set(set)
+
+	for ( const set of sets ) {
+		eachConcept(map[set], ( c, key ) => {
+			const schema = schemaOf(c);
+			const name = c._name || key;
+			if ( !name ) return;               // unnamed node — validate.js flags it; skip here
+			concepts.push({ id: c._id || name, name, set, kind: conceptKind(schema), flags: conceptFlags(schema) });
+			setOfConcept.set(name, set);
+
+			// produced: self-flag + applyMutations keys
+			const produced = new Set([name, ...templateKeys(schema.applyMutations)]);
+			for ( const f of produced ) {
+				edges.push({ kind: 'writes', concept: name, fact: f });
+				if ( !producersByFact.has(f) ) producersByFact.set(f, new Set());
+				producersByFact.get(f).add(name);
+				if ( !producerSetsByFact.has(f) ) producerSetsByFact.set(f, new Set());
+				producerSetsByFact.get(f).add(set);
+			}
+
+			// consumed: require (positive); assert/ensure (polarity from the AST)
+			for ( const r of refsOf(schema.require, false) )
+				edges.push({ kind: 'reads', concept: name, fact: refKeyOf(r).key, polarity: '+', via: 'require' });
+			for ( const via of ['assert', 'ensure'] )
+				for ( const e of asArray(schema[via]) ) {
+					if ( typeof e !== 'string' ) continue;
+					let ast; try { ast = parseExpression(e); } catch ( _e ) { ast = null; }
+					const negs = negatedRefKeys(ast);
+					for ( const r of refsOf(e, true) ) {
+						const k = refKeyOf(r).key;
+						edges.push({ kind: 'reads', concept: name, fact: k, polarity: negs.has(k) ? '-' : '+', via });
+					}
+				}
+		});
+	}
+
+	// consumers per fact
+	const consumersByFact = new Map();        // fact -> [{name,polarity,via}]
+	const consumerSetsByFact = new Map();     // fact -> Set(set)
+	for ( const e of edges ) if ( e.kind === 'reads' ) {
+		if ( !consumersByFact.has(e.fact) ) consumersByFact.set(e.fact, []);
+		consumersByFact.get(e.fact).push({ name: e.concept, polarity: e.polarity, via: e.via });
+		const s = setOfConcept.get(e.concept);
+		if ( !consumerSetsByFact.has(e.fact) ) consumerSetsByFact.set(e.fact, new Set());
+		if ( s ) consumerSetsByFact.get(e.fact).add(s);
+	}
+
+	const allFacts = new Set([...producersByFact.keys(), ...consumersByFact.keys()]);
+	const facts = [...allFacts].sort().map(( key ) => ({
+		key,
+		producedBy: [...(producersByFact.get(key) || [])].sort(),
+		consumedBy: (consumersByFact.get(key) || []).slice()
+			.sort(( a, b ) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+		sets: [...new Set([...(producerSetsByFact.get(key) || []), ...(consumerSetsByFact.get(key) || [])])].sort()
+	}));
+
+	// collisions: a fact written by concepts in >= 2 sets
+	const collisions = [];
+	for ( const [fact, setSet] of producerSetsByFact )
+		if ( setSet.size >= 2 ) collisions.push({ fact, sets: [...setSet].sort() });
+	collisions.sort(( a, b ) => (a.fact < b.fact ? -1 : 1));
+
+	// cross-corpus links: produced in set X, consumed in set Y != X
+	const crossCorpus = [];
+	for ( const fact of allFacts ) {
+		const pSets = producerSetsByFact.get(fact) || new Set();
+		const cSets = consumerSetsByFact.get(fact) || new Set();
+		for ( const from of pSets ) for ( const to of cSets ) if ( from !== to )
+			crossCorpus.push({ fact, fromSet: from, toSet: to });
+	}
+	crossCorpus.sort(( a, b ) => (a.fact < b.fact ? -1 : a.fact > b.fact ? 1 : a.fromSet < b.fromSet ? -1 : 1));
+
+	// entry points: read by someone, produced by no one (external / seed / engine input)
+	const entryPoints = [...allFacts].filter(( f ) => !producersByFact.has(f) && consumersByFact.has(f)).sort();
+
+	// tiling overlay (best-effort; never throw the whole derivation on a degenerate corpus)
+	let tiling = null;
+	try { tiling = forkPlan(mergeTrees(sets.map(( s ) => map[s]))); } catch ( _e ) { tiling = null; }
+
+	return { concepts, facts, edges, crossCorpus, collisions, entryPoints, tiling };
+}
+
+module.exports = { conceptFactGraph };

package/lib/authoring/granularity.js

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * granularity — the STRUCTURAL granularity ARBITER (P2's 4th client, the sonde's grounded dimensions):
+ * cluster grounded notions / key-points into candidate DIMENSIONS by their GROUNDING overlap (co-citation
+ * of witnesses), with NO prose parsing. The sonde (WIP 2026-07-13) measured that the real dimensions of a
+ * question come from CLUSTERING the KPs on their grounding, not from asking Q2 to parse them (its "moral;
+ * legal" prior is a shallow cliché). Two items are in the same dimension iff their witness-sets share ≥
+ * `minShared` arguments — transitively, via connected components on the co-citation graph.
+ *
+ * The arbiter's job is to ARBITRATE the lazy 2-régime factorization (sonde): when the grounding is dense
+ * enough to form ≥2 grounded groups, it RESOLVES the dimensions for free ('mixed' = the re-plan's
+ * `frame: TOO-NARROW` signal, grounded — the moral⊥legal separation, structurally); when the grounding is
+ * a single connected block it is a 'coherent' frame (decide normally); when it is all singletons (sparse
+ * co-citation — measured ~6% multi-matched on ArgKP) there is no grounded dimension structure and it
+ * ESCALATES ('unstructured' → Q2 proposes dimensions, seeded by the groups). It never hallucinates a
+ * dimension (the discriminating negative control). Deterministic, grounded, ZERO-CORE.
+ *
+ *   const { arbitrate } = require('skynet-graph/lib/authoring/granularity');
+ *   arbitrate([{id:'n1',witnesses:['a','b']}, {id:'n2',witnesses:['b','c']}, {id:'n3',witnesses:['x','y']}]);
+ *   // → { frame:'mixed', dimensions:[['n1','n2'],['n3']-dropped], ... }  (n1~n2 share b; n3 disjoint)
+ */
+
+// Union-find over the item ids, edges = share ≥ minShared witnesses (optionally never across `side`).
+function clusterByGrounding( items, opts ) {
+	opts = opts || {};
+	const minShared = opts.minShared != null ? opts.minShared : 1;
+	const bySide = !!opts.bySide;
+	const parent = new Map();
+	const find = ( x ) => { while ( parent.get(x) !== x ) { parent.set(x, parent.get(parent.get(x))); x = parent.get(x); } return x; };
+	for ( const it of items ) parent.set(it.id, it.id);
+	let edges = 0;
+	for ( let i = 0; i < items.length; i++ ) for ( let j = i + 1; j < items.length; j++ ) {
+		const A = items[i], B = items[j];
+		if ( bySide && A.side && B.side && A.side !== B.side ) continue;
+		const wb = new Set(B.witnesses || []);
+		const shared = (A.witnesses || []).filter(( w ) => wb.has(w) ).length;
+		if ( shared >= minShared ) { const ra = find(A.id), rb = find(B.id); if ( ra !== rb ) { parent.set(ra, rb); edges++; } }
+	}
+	const groups = new Map();
+	for ( const it of items ) { const r = find(it.id); if ( !groups.has(r) ) groups.set(r, []); groups.get(r).push(it.id); }
+	const clusters = [...groups.values()].map(( g ) => g.slice().sort() ).sort(( a, b ) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0 );
+	return { clusters, separability: { components: clusters.length, singletons: clusters.filter(( c ) => c.length === 1 ).length,
+		sizes: clusters.map(( c ) => c.length ).sort(( a, b ) => b - a ), edges } };
+}
+
+/**
+ * Classify a set of grounded items into a FRAME verdict for the re-plan (the `frame: TOO-NARROW` signal):
+ *   'coherent'     — one connected grounded block → a single dimension → decide normally (no re-plan).
+ *   'mixed'        — ≥2 grounded groups (size ≥ minGroup) → the frame conflates dimensions → SEPARATE them
+ *                    (the moral⊥legal case, detected structurally, grounded — the re-plan's re-split seed).
+ *   'unstructured' — no grounded groups (all singletons; sparse co-citation) → ESCALATE to Q2 to propose
+ *                    dimensions (the lazy-régime GAP), seeded by the singletons; never fabricate a split.
+ * @param items [{ id, witnesses:[argId], side? }]
+ * @returns { frame, dimensions:[[id..]], singletons:[[id]..], separability, reason }
+ */
+function arbitrate( items, opts ) {
+	opts = opts || {};
+	const minGroup = opts.minGroup != null ? opts.minGroup : 2;
+	const { clusters, separability } = clusterByGrounding(items, opts);
+	const dimensions = clusters.filter(( c ) => c.length >= minGroup );
+	const singletons = clusters.filter(( c ) => c.length < minGroup );
+	let frame, reason;
+	if ( dimensions.length >= 2 ) { frame = 'mixed';
+		reason = dimensions.length + ' grounded groups share no witnesses across groups — the frame conflates ' + dimensions.length + ' dimensions'; }
+	else if ( dimensions.length === 1 && !singletons.length ) { frame = 'coherent';
+		reason = 'one connected grounded block — a single dimension'; }
+	else if ( dimensions.length === 1 ) { frame = 'coherent';
+		reason = 'one grounded group' + (singletons.length ? ' + ' + singletons.length + ' ungrounded singleton(s)' : ''); }
+	else { frame = 'unstructured';
+		reason = 'no grounded group (co-citation too sparse) — escalate to Q2 to propose dimensions'; }
+	return { frame, dimensions, singletons, separability, reason };
+}
+
+module.exports = { clusterByGrounding, arbitrate };

package/lib/authoring/graph-net.js

@@ -0,0 +1,108 @@
+/*
+ * 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';
+/**
+ * graph-net — a SHARED-WEIGHT message-passing population over an arbitrary graph: ONE node-update
+ * rule (a gate-NN × update-NN) applied at every node, reading a permutation-invariant aggregate of
+ * its neighbours, run to a FIXPOINT, trained by the same implicit-diff/DEQ machinery (equilibrium.js).
+ * A quantized equilibrium GNN — the substrate generalised from concept-net's fixed structures to an
+ * actual graph, so it (a) handles real graph problems where recurrence is essential and (b)
+ * GENERALISES to new graphs (one rule everywhere = the distillation payoff). Host-side, ZERO-CORE.
+ * Study 2026-06-26 (see doc/concept-learning.md); the rung after the population substrate.
+ *
+ * Unit: z'[i] = gate_i · cand_i, both σ over ctx_i = [ mean(neighbour states), own state ]; weights
+ * SHARED across nodes (θ = 6 numbers, any graph size). Seed-initialised: settle starts from z0.
+ *
+ * CLAMPED nodes (`opts.clamp`) are held fixed at their z0 value — the "grounded" anchors for a
+ * SEED-ANCHORED propagation problem (e.g. known types propagating across a dependency graph). This
+ * matters: an UNCLAMPED equilibrium GNN OVERSMOOTHS to the consensus fixpoint (washes out the seed →
+ * cannot do symmetry-breaking labelling, finding #26); a clamp breaks the symmetry so the fixpoint is
+ * seed-determined and learnable. The DEQ adjoint runs on the FREE (non-clamped) subspace (a clamped
+ * node is an identity J_z row → I−J_z singular).
+ *
+ *   const gp = graphPopulation(n, edges, { clamp: [0] });   // node 0 = the grounded source
+ *   const r  = trainGraph(gp, episodes, { steps, lr });      // episodes: [{ z0, target }]
+ *   const z  = gp.settle(r.theta, z0).z;                      // propagate a NEW graph, no oracle
+ */
+const { solveFixpoint, implicitGrad, numJac, spectralRadius } = require('./equilibrium.js');
+
+const sigmoid = (x) => 1 / (1 + Math.exp(-x));
+
+function graphPopulation( n, edges, opts ) {
+	opts = opts || {};
+	const clamp = new Set(opts.clamp || []);
+	const free = []; for ( let i = 0; i < n; i++ ) if ( !clamp.has(i) ) free.push(i);
+	const nb = Array.from({ length: n }, () => []);
+	for ( const [a, b] of (edges || []) ) { nb[a].push(b); nb[b].push(a); }
+	const nParams = 6;                       // [Wg_agg, Wg_self, bg, Wu_agg, Wu_self, bu] — SHARED
+	function F( z, th ) {
+		const zn = z.slice();
+		for ( const i of free ) {            // clamped nodes keep z[i]
+			const ne = nb[i]; let agg = 0;
+			for ( const j of ne ) agg += z[j];
+			agg = ne.length ? agg / ne.length : 0;
+			const self = z[i];
+			zn[i] = sigmoid(th[0] * agg + th[1] * self + th[2]) * sigmoid(th[3] * agg + th[4] * self + th[5]);
+		}
+		return zn;
+	}
+	const scatter = (zf, z0) => { const z = z0.slice(); free.forEach((j, c) => { z[j] = zf[c]; }); return z; };  // clamped from z0
+	const gather = (z) => free.map((j) => z[j]);
+	const freeStep = (zf, z0, th) => gather(F(scatter(zf, z0), th));   // the reduced sweep the DEQ differentiates
+	return {
+		n, nParams, F, neighbors: nb, clamp: [...clamp], free, scatter, gather, freeStep,
+		settle( th, z0, o ) { return solveFixpoint((z) => F(z, th), z0.slice(), { maxIter: (o && o.maxIter) || 3000, tol: (o && o.tol) || 1e-12 }); },
+		settleFree( th, z0, o ) { const r = solveFixpoint((zf) => freeStep(zf, z0, th), gather(z0), { maxIter: (o && o.maxIter) || 3000, tol: (o && o.tol) || 1e-12 }); return { zfree: r.z, z: scatter(r.z, z0), iters: r.iters, converged: r.converged }; },
+		randomParams( rng, scale ) { rng = rng || Math.random; scale = scale == null ? 1 : scale; const t = new Array(nParams); for ( let i = 0; i < nParams; i++ ) t[i] = (rng() * 2 - 1) * scale; return t; },
+	};
+}
+
+/** Mean-squared per-FREE-node loss over episodes [{ z0, target }]. */
+function graphLoss( gp, th, episodes ) {
+	let s = 0, cnt = 0;
+	for ( const ep of episodes ) { const z = gp.settle(th, ep.z0).z; for ( const i of gp.free ) { s += (z[i] - ep.target[i]) ** 2; cnt++; } }
+	return s / cnt;
+}
+
+/** Implicit-diff (DEQ) gradient of graphLoss wrt the shared θ (over the free subspace), summed. */
+function graphGrad( gp, th, episodes ) {
+	const g = new Array(gp.nParams).fill(0), N = episodes.length * gp.free.length;
+	for ( const ep of episodes ) {
+		const r = gp.settleFree(th, ep.z0), zf = r.zfree;
+		const gl = zf.map((v, c) => 2 * (v - ep.target[gp.free[c]]) / N);
+		const Jz = numJac((zz) => gp.freeStep(zz, ep.z0, th), zf), Jt = numJac((tt) => gp.freeStep(zf, ep.z0, tt), th);
+		const gr = implicitGrad(Jz, Jt, gl, { mode: 'direct' });
+		for ( let k = 0; k < gp.nParams; k++ ) g[k] += gr.grad[k];
+	}
+	return g;
+}
+
+/** Train the shared node-rule on episodes (Adam). @returns { theta, loss0, loss }. */
+function trainGraph( gp, episodes, conf ) {
+	conf = conf || {};
+	const steps = conf.steps || 1500, lr = conf.lr || 0.05;
+	let th = (conf.theta0 || gp.randomParams(conf.rng, conf.initScale)).slice();
+	const loss0 = graphLoss(gp, th, episodes), mm = th.map(() => 0), vv = th.map(() => 0), b1 = 0.9, b2 = 0.999;
+	for ( let s = 1; s <= steps; s++ ) {
+		const gr = graphGrad(gp, th, episodes);
+		for ( let k = 0; k < th.length; k++ ) { mm[k] = b1 * mm[k] + (1 - b1) * gr[k]; vv[k] = b2 * vv[k] + (1 - b2) * gr[k] * gr[k]; th[k] -= lr * (mm[k] / (1 - b1 ** s)) / (Math.sqrt(vv[k] / (1 - b2 ** s)) + 1e-8); }
+	}
+	return { theta: th, loss0, loss: graphLoss(gp, th, episodes) };
+}
+
+module.exports = { graphPopulation, graphLoss, graphGrad, trainGraph };