skynet-graph 1.2.0

package/lib/providers/nogood.js

@@ -0,0 +1,149 @@
+/*
+ * 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';
+/**
+ * L3 learned-NEGATIVE policy — a nogood / sound-skip ("this trial is a dead end for this
+ * context") expressed entirely with EXISTING engine machinery (doc/WIP/HANDOFF.md §7 Tier 2;
+ * experiment B). Zero core change, and provably fixpoint-preserving: it removes only the
+ * useless cast of a provably-dead trial and never changes a surviving useful conclusion
+ * (B verified the surviving set bit-for-bit identical with and without the policy).
+ *
+ * It generalizes the engine's own "`divergent` fact = non-cast condition" from per-(object,
+ * concept) to a LEARNED per-(contextKey, trial) policy:
+ *   - on a dead-end trial result, the trial's provider {__push}es a `{ctxKey, trial}` nogood
+ *     into a shared append-only store node (the same race-free primitive `_markDivergent`
+ *     uses) — `recordNogood(...)` builds that mutation fragment;
+ *   - a cheap upstream `Nogood::guard` concept reads the store and, for each nogood matching
+ *     this object's context, sets a DISCRETE typed `skip_<trial>:true` flag (barrier-clean —
+ *     the hot gate keys on a typed boolean, never on the store);
+ *   - the expensive trial gains `require:['NogoodGuard']` (DEFER the cast until the cheap
+ *     guard has run) + `ensure:['!$skip_<trial>']` (sound-skip) — `guardTrial(...)` adds both.
+ *
+ * Two ordering disciplines are load-bearing (B, critique-driven) and baked in here:
+ *   (1) the trial's `require` lists the guard, so an unresolved require DEFERS the expensive
+ *       cast until the cheap guard's self-flag appears (the frontier order is not host-
+ *       controllable per concept — the require-deferral is the existing-system route);
+ *   (2) the guard writes the `skip_*` flags FIRST and its OWN self-flag LAST, so when the
+ *       trial's require-watcher re-tests (the moment the self-flag lands) every skip flag is
+ *       already set — otherwise an intra-mutation key-order race lets a trial fire first.
+ *
+ * A purely ADVISORY hint (a fact nothing gates on) saved ZERO work in B — soft preference
+ * needs a core `cfg.frontierComparator` (P1, not built); the sound-skip here is the safe,
+ * fixpoint-preserving existing-system answer. Per-episode reset by default (clear the store
+ * between episodes; GitOfThoughts-style) — keep it only as long as the context holds.
+ *
+ *   const { createNogood, recordNogood, guardTrial, nogoodGuardConcept } = require('./nogood');
+ *   register(Graph, [ createNogood() ]);   // wires Nogood::guard
+ */
+
+/**
+ * Build the nogood-store push fragment a trial's provider emits on a dead end (score 0).
+ * Spread it into the provider's mutation array alongside the trial's own self-flag write.
+ * @param opts.memId    the shared store node id (default 'mem')
+ * @param opts.storeKey the array fact on it (default 'nogoods')
+ * @param opts.ctxKey   the canonical context key this dead end is keyed on (e.g. the segment kind)
+ * @param opts.trial    the trial concept name that is dead for this context
+ * @returns a `{ $$_id, <storeKey>: { __push: {ctxKey,trial} } }` mutation template
+ */
+function recordNogood( opts ) {
+	opts = opts || {};
+	var tpl = { $$_id: opts.memId || 'mem' };
+	tpl[opts.storeKey || 'nogoods'] = { __push: { ctxKey: opts.ctxKey, trial: opts.trial } };
+	return tpl;
+}
+
+/**
+ * Build the nogood guard provider fragment (host opt-in, like createVerifier).
+ * @returns { Nogood: { guard } }
+ *
+ * Concept wiring (the cheap upstream guard):
+ *   { require:['Trial','kind'], provider:['Nogood::guard'],
+ *     nogood:{ memId:'mem', storeKey:'nogoods', ctxKeyField:'kind' } }
+ * Reads the shared store, and for each nogood whose ctxKey matches this object's
+ * `<ctxKeyField>` writes `skip_<trial>:true`, then its OWN self-flag LAST.
+ */
+function createNogood( opts ) {
+	opts = opts || {};
+	return {
+		Nogood: {
+			guard: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({ memId: 'mem', storeKey: 'nogoods', ctxKeyField: 'kind' },
+					concept._schema && concept._schema.nogood, argz && argz[0]),
+				    memEtty = graph.getEtty(cfg.memId),
+				    store = (memEtty && memEtty._ && memEtty._[cfg.storeKey]) || [],
+				    ctx = scope._[cfg.ctxKeyField],
+				    out = { $_id: '_parent' };
+				// skip_* flags FIRST …
+				for ( var i = 0; i < store.length; i++ ) {
+					var ng = store[i];
+					if ( ng && ng.ctxKey === ctx ) out['skip_' + ng.trial] = true;
+				}
+				// … the guard's OWN self-flag LAST (so the trial's require-watcher re-tests with
+				// every skip flag already set — discipline (2) above).
+				out[concept._name] = true;
+				cb(null, out);
+			}
+		}
+	};
+}
+
+/**
+ * Add the sound-skip discipline to a trial concept schema: defer on the guard's self-flag
+ * (require) and skip when the learned nogood says so (ensure). Returns a NEW schema.
+ * @param schema       the trial concept schema
+ * @param opts.trial   the skip-flag basis (default schema._name)
+ * @param opts.guard   the guard concept self-flag name to require (default 'NogoodGuard')
+ */
+function guardTrial( schema, opts ) {
+	opts = opts || {};
+	var name = opts.trial || schema._name,
+	    guard = opts.guard || 'NogoodGuard',
+	    asArr = function ( v ) { return v == null ? [] : Array.isArray(v) ? v.slice() : [v]; },
+	    out = Object.assign({}, schema);
+	out.require = asArr(schema.require).concat([guard]);
+	out.ensure = asArr(schema.ensure).concat(['!$skip_' + name]);
+	return out;
+}
+
+/**
+ * The cheap upstream guard concept (provider-less wrapper) for a host that wants it ready-made.
+ * @param opts.require       what marks an object as guardable (default ['Trial','kind'])
+ * @param opts.memId/storeKey/ctxKeyField  passed through to the provider config
+ * @param opts.name          the guard self-flag name (default 'NogoodGuard')
+ */
+function nogoodGuardConcept( opts ) {
+	opts = opts || {};
+	var name = opts.name || 'NogoodGuard';
+	return {
+		_id: opts.id || name, _name: name,
+		require: opts.require || ['Trial', opts.ctxKeyField || 'kind'],
+		provider: ['Nogood::guard'],
+		nogood: {
+			memId: opts.memId || 'mem',
+			storeKey: opts.storeKey || 'nogoods',
+			ctxKeyField: opts.ctxKeyField || 'kind'
+		}
+	};
+}
+
+module.exports = {
+	recordNogood: recordNogood,
+	createNogood: createNogood,
+	guardTrial: guardTrial,
+	nogoodGuardConcept: nogoodGuardConcept
+};

package/lib/providers/reason-loop.js

@@ -0,0 +1,223 @@
+/*
+ * 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';
+/**
+ * Reason-loop — the packaged `AI::*` provider set that drives `concepts/_substrate` end-to-end.
+ * The LLM generalization of `examples/poc/trip-decompose.js#makeTripProviders` (which used canned
+ * content). Roadmap P1.a / GAP A of `doc/WIP/2026-07-05-combos-design.md §11`.
+ *
+ * WHY THIS EXISTS. `concepts/_substrate/Task/*` + `Claim/*` NAME `AI::evalComplexity/expand/answer/
+ * reportUp/rollup/confidence` but the library ships NO `AI::` provider — so the answer loop never
+ * runs: an unwired provider silently auto-flags its concept (Concept.js:239) without writing
+ * `complexityClass`, so `Atomic`/`Compound` never cast and no `Answer` is ever produced. This brick
+ * supplies the set, each fn emitting the EXACT marker its concept gates on (mirroring the proven
+ * trip markers — `tests/integration/poc-decompose.test.js`):
+ *
+ *   Task/EvalComplexity   -> { EvalComplexity, complexityClass:'atomic'|'compound' }  (enum, canon-snapped)
+ *   .../Compound/Expansion-> { Expansion, expandedInto } + child Node/Segment templates (the AND hyper-edge)
+ *   Task/Answer           -> { Answer, answer }         (concept's own applyMutations sets `Answered`)
+ *   Task/ReportUp         -> push self-id into parent.answeredBy (deterministic, race-free {__push})
+ *   Task/Rollup           -> { Rollup, answer }         (fires on the .length completion gate)
+ *   Claim/Confidence      -> { Confidence, confBand }   (a SNAPPED band, never a raw float — K1/A2)
+ *
+ * Plus the INTAKE→TASK BRIDGE (GAP B): `AI::seedTask` turns a typed Intake node into a root Task
+ * Segment carrying the question, so the answer loop has something to run on (without it the intake
+ * and the loop are two disconnected sub-graphs). A host wires the matching concept
+ * `concepts/_substrate/Intake/ToTask.json` (require Intake, ensure IntakeStatus=='typed').
+ *
+ * TERMINATION + TYPED REFUSAL (answer-side). A depth FLOOR forces `atomic` at `maxDepth`. A model
+ * reply that can't be snapped to a class (eval) or yields no steps (expand) emits `strategiesExhausted`
+ * WITHOUT a class/children — so the task neither answers nor expands and lands in `Frontier/Stuck`
+ * (`ensure:["$strategiesExhausted"]`, previously never written — GAP C), a readable answer-side refusal,
+ * instead of re-firing to the apply-cap. `strategiesExhausted` is placed only on eval/expand (whose
+ * concepts do NOT force `Answered`); the answer concept's own `applyMutations` sets `Answered`, so an
+ * answer-call failure is surfaced as an errored answer (`llmError`), not a stuck state.
+ *
+ * FAITHFUL to the substrate authoring: each provider USES the concept's declared `prompt` (interpolated
+ * `${label}` etc.) and, where the concept declares `prompt.facts`, the canonicalization barrier
+ * (`canonicalize.canonFacts`) to snap the enum — the same K1 discipline as `LLM::complete`/`Intake`.
+ * Provider-cast-marker GOTCHA honored: every returned template self-flags its concept `_name`.
+ *
+ * @param opts.ask       async ({system,user,maxTokens}) -> string. REQUIRED (throws otherwise).
+ * @param opts.parseJSON JSON-salvage fn. Default `llm.parseJSON`.
+ * @param opts.maxDepth  decomposition depth floor (forces atomic at/after it). Default 2.
+ * @param opts.maxBranch max sub-steps per expand. Default 5.
+ * @param opts.namespace provider namespace. Default 'AI'.
+ * @returns { AI: { seedTask, evalComplexity, expand, answer, reportUp, rollup, confidence } }
+ */
+
+var llm = require('./llm');
+var canonicalize = require('./canonicalize');
+
+function createReasonLoop( opts ) {
+	opts = opts || {};
+	var ask = opts.ask;
+	if ( typeof ask !== 'function' )
+		throw new Error('createReasonLoop needs opts.ask (an async ({system,user,maxTokens}) -> string)');
+	var parseJSON = opts.parseJSON || llm.parseJSON,
+	    maxDepth   = opts.maxDepth == null ? 2 : opts.maxDepth,
+	    maxBranch  = opts.maxBranch || 5,
+	    namespace  = opts.namespace || 'AI';
+
+	// the task's text: the segment label (the sub-problem) or the raw question on a seed node.
+	function taskText( scope ) { return scope._.rawText || scope._.label || ''; }
+
+	// the concept's authored prompt (interpolated), with a default when the concept ships none.
+	function promptOf( concept, scope, graph, dflt ) {
+		var p = (concept._schema && concept._schema.prompt) || {};
+		return {
+			system : llm.interpolate(p.system, graph, scope) || dflt.system,
+			user   : llm.interpolate(p.user, graph, scope) || dflt.user,
+			facts  : p.facts,
+			prose  : p.prose
+		};
+	}
+	function trace( graph, concept, scope, io ) { if ( graph.traceProvider ) graph.traceProvider(concept, scope, io); }
+
+	var ns = {};
+	ns[namespace] = {
+		// ── BRIDGE (GAP B): a typed intake seeds a root Task Segment carrying the question ──────────
+		seedTask: function ( graph, concept, scope, argz, cb ) {
+			var id = scope._._id,
+			    q  = scope._.rawText || scope._.intakeNarrative || scope._.label || '';
+			cb(null, [
+				{ $_id: '_parent', ToTask: true },                                         // self-flag (GOTCHA)
+				{ _id: id + '_start', Node: true, label: '(question)' },                   // fresh endpoints (NOT the intake node,
+				{ _id: id + '_goal', Node: true, label: '(answer)' },                      //  which is not a segment endpoint)
+				{ _id: id + '_task', Segment: true, originNode: id + '_start', targetNode: id + '_goal',
+				  depth: 0, label: q }                                                     // the root Task (label, NOT rawText:
+				                                                                           //  rawText re-triggers Intake → runaway)
+			]);
+		},
+
+		// ── EvalComplexity: atomic vs compound, canon-snapped to the concept's enum ────────────────
+		evalComplexity: function ( graph, concept, scope, argz, cb ) {
+			var depth = scope._.depth || 0;
+			if ( depth >= maxDepth )                                                       // depth floor → terminate
+				return cb(null, { $_id: '_parent', EvalComplexity: true, complexityClass: 'atomic' });
+			var pr     = promptOf(concept, scope, graph, {
+				    system: 'Classify whether the task is "atomic" (answerable directly in one step) or "compound" (needs breaking into sub-steps).',
+				    user  : 'Task: ' + taskText(scope) }),
+			    schema = pr.facts || { complexityClass: { enum: ['atomic', 'compound'] } };
+			Promise.resolve()
+				.then(function () { return ask({ system: pr.system + ' Reply ONLY JSON: {"complexityClass":"atomic"|"compound"}.', user: pr.user, maxTokens: 80 }); })
+				.then(function ( txt ) {
+					trace(graph, concept, scope, { reply: txt });
+					var cf = canonicalize.canonFacts(parseJSON(txt), schema);
+					if ( cf.misses.length || !cf.facts.complexityClass )                    // no snappable class → no strategy
+						return cb(null, { $_id: '_parent', EvalComplexity: true, strategiesExhausted: true });
+					cb(null, { $_id: '_parent', EvalComplexity: true, complexityClass: cf.facts.complexityClass });
+				})
+				.catch(function ( e ) { cb(null, { $_id: '_parent', EvalComplexity: true, strategiesExhausted: true, llmError: e.message }); });
+		},
+
+		// ── Expansion: the AND hyper-edge of child sub-segments ────────────────────────────────────
+		expand: function ( graph, concept, scope, argz, cb ) {
+			var pr = promptOf(concept, scope, graph, {
+				system: 'Break the task into 2-' + maxBranch + ' ordered sub-steps.',
+				user  : 'Task: ' + taskText(scope) });
+			Promise.resolve()
+				.then(function () { return ask({ system: pr.system + ' Reply ONLY JSON: {"steps":["...","..."]}.', user: pr.user, maxTokens: 400 }); })
+				.then(function ( txt ) {
+					trace(graph, concept, scope, { reply: txt });
+					var r = parseJSON(txt),
+					    steps = (r && Array.isArray(r.steps) ? r.steps : []).slice(0, maxBranch)
+						.map(function ( s ) { return typeof s === 'string' ? s : (s && (s.name || s.step || s.label)) || ''; })
+						.filter(Boolean);
+					if ( !steps.length )                                                    // couldn't decompose → stuck
+						return cb(null, { $_id: '_parent', Expansion: true, strategiesExhausted: true });
+					var base = scope._._id, origin = scope._.originNode, target = scope._.targetNode,
+					    depth = (scope._.depth || 0) + 1,
+					    childIds = steps.map(function ( _, i ) { return base + '_s' + i; }),
+					    tpl = [{ $_id: '_parent', Expansion: true, expandedInto: childIds }],
+					    prev = origin;
+					steps.forEach(function ( name, i ) {
+						var last = i === steps.length - 1, tnode = last ? target : base + '_m' + i;
+						if ( !last ) tpl.push({ _id: tnode, Node: true, label: name });
+						tpl.push({ _id: childIds[i], Segment: true, originNode: prev, targetNode: tnode,
+						           depth: depth, parentSeg: base, label: name });   // label only (no rawText → no re-intake)
+						prev = tnode;
+					});
+					cb(null, tpl);
+				})
+				.catch(function ( e ) { cb(null, { $_id: '_parent', Expansion: true, strategiesExhausted: true, llmError: e.message }); });
+		},
+
+		// ── Answer: terminal prose for an atomic leaf (concept applyMutations sets `Answered`) ──────
+		answer: function ( graph, concept, scope, argz, cb ) {
+			var pr = promptOf(concept, scope, graph, {
+				system: 'Answer the task directly and concisely (max ~4 sentences).',
+				user  : 'Task: ' + taskText(scope) });
+			Promise.resolve()
+				.then(function () { return ask({ system: pr.system, user: pr.user, maxTokens: 500 }); })
+				.then(function ( txt ) {
+					trace(graph, concept, scope, { reply: txt });
+					cb(null, { $_id: '_parent', Answer: true, answer: String(txt).trim() });
+				})
+				.catch(function ( e ) { cb(null, { $_id: '_parent', Answer: true, answer: '(answer unavailable)', llmError: e.message }); });
+		},
+
+		// ── ReportUp: race-free stigmergic fan-in (no LLM) ─────────────────────────────────────────
+		reportUp: function ( graph, concept, scope, argz, cb ) {
+			cb(null, [
+				{ $$_id: scope._.parentSeg, answeredBy: { __push: scope._._id } },
+				{ $_id: '_parent', ReportUp: true }
+			]);
+		},
+
+		// ── Rollup: bounded bottom-up synthesis, fires once on the .length gate ─────────────────────
+		rollup: function ( graph, concept, scope, argz, cb ) {
+			var kids = (scope._.expandedInto || [])
+				.map(function ( id ) { var e = graph.getEtty(id); return e && e._.answer; })
+				.filter(function ( a ) { return a != null; });
+			var pr = promptOf(concept, scope, graph, {
+				system: 'Synthesize the sub-answers into ONE coherent, BOUNDED answer (max ~6 sentences). Do not copy; summarize.',
+				user  : null });
+			Promise.resolve()
+				.then(function () {
+					return ask({ system: pr.system,
+						user: (pr.user ? pr.user + '\n\n' : 'Task: ' + taskText(scope) + '\n\n') +
+						      'Sub-answers:\n' + kids.map(function ( a, i ) { return (i + 1) + '. ' + a; }).join('\n'),
+						maxTokens: 700 });
+				})
+				.then(function ( txt ) {
+					trace(graph, concept, scope, { reply: txt });
+					cb(null, { $_id: '_parent', Rollup: true, answer: String(txt).trim() });
+				})
+				.catch(function () { cb(null, { $_id: '_parent', Rollup: true, answer: kids.join(' ') }); });   // fail-soft: concat
+		},
+
+		// ── Confidence: a SNAPPED band, canon-checked against the concept's enum ─────────────────────
+		confidence: function ( graph, concept, scope, argz, cb ) {
+			var pr     = promptOf(concept, scope, graph, {
+				    system: 'Rate confidence in the answer as one of: low, medium, high.',
+				    user  : 'Task: ' + taskText(scope) + '\nAnswer: ' + (scope._.answer || '') }),
+			    schema = pr.facts || { confBand: { enum: ['low', 'medium', 'high'] } };
+			Promise.resolve()
+				.then(function () { return ask({ system: pr.system + ' Reply ONLY JSON: {"confBand":"low"|"medium"|"high"}.', user: pr.user, maxTokens: 40 }); })
+				.then(function ( txt ) {
+					var cf = canonicalize.canonFacts(parseJSON(txt), schema);
+					cb(null, { $_id: '_parent', Confidence: true, confBand: cf.facts.confBand || 'low' });   // OOB → fail-closed low
+				})
+				.catch(function () { cb(null, { $_id: '_parent', Confidence: true, confBand: 'low' }); });
+		}
+	};
+	return ns;
+}
+
+module.exports = { createReasonLoop: createReasonLoop };

package/lib/providers/semiring.js

@@ -0,0 +1,285 @@
+/*
+ * 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';
+/**
+ * Semiring-parameterized accumulation — D and P are ONE forward-chaining machine
+ * parameterized by the certainty semiring (doc/WIP/HANDOFF.md §7 Tier 2; SOTA
+ * subgraph-grammars: provenance semirings, Green-Tannen 2007; experiments E1/E4). Zero
+ * core change: it packages the coherence-theorem-validated commutative-monoid REDUCE
+ * (E1: fold `{__push}`ed contributions after quiescence; order-independence ⟺ the combine
+ * is a commutative monoid) as a reusable provider whose `⊕`/identity/readout you choose:
+ *
+ *   - `boolean` (the D socle):     ⊕ = OR,  readout = identity   -> "does ANY contribution hold"
+ *   - `logodds` (the P layer):     ⊕ = +,   readout = σ          -> certainty accumulation (E1/E4)
+ *   - `maxplus` (best-path):       ⊕ = max, readout = identity   -> Viterbi / longest-evidence
+ *   - `probor`  (noisy-OR):        ⊕ = a+b−ab on [0,1]           -> independent-evidence OR
+ *
+ * The same engine, the same fold-after-quiescence, a different algebra — adding a same-family
+ * regime is "declare a semiring", not a core change. Keep `⊕` a COMMUTATIVE monoid or the
+ * result depends on the (non-semantic) scheduler order (E1: monoid variance ≈0 vs a
+ * non-commutative combine ranging [−0.41, 1.06] on the SAME contributions).
+ *
+ *   const { createSemiring, semiringConceptTree } = require('./semiring');
+ *   register(Graph, [ createSemiring() ]);   // wires Semiring::reduce
+ *
+ * Contributions arrive via the race-free `{__push}` primitive into an array fact; a `Reduce`
+ * concept gated `ensure:["$contribs.length==$expected"]` (the proven completion gate) folds
+ * them after the stratum is quiescent — same shape as verify's Vote::tally and stats' grandMean.
+ */
+
+var mc = require('./merge-consistency');
+var sigmoid = mc.sigmoid, bandOf = mc.bandOf;
+
+// Built-in commutative semirings: { plus, zero, times, one, readout }. `plus`/`zero` drive the
+// REDUCE; `times`/`one` are the ⊗ for combining along a path (exposed for completeness).
+var SEMIRINGS = {
+	boolean: { plus: function ( a, b ) { return !!(a || b); }, zero: false, times: function ( a, b ) { return !!(a && b); }, one: true,  readout: function ( x ) { return x; } },
+	logodds: { plus: function ( a, b ) { return a + b; },      zero: 0,     times: function ( a, b ) { return a + b; },      one: 0,     readout: sigmoid },
+	maxplus: { plus: function ( a, b ) { return Math.max(a, b); }, zero: -Infinity, times: function ( a, b ) { return a + b; }, one: 0, readout: function ( x ) { return x; } },
+	probor:  { plus: function ( a, b ) { return a + b - a * b; }, zero: 0,  times: function ( a, b ) { return a * b; },      one: 1,     readout: function ( x ) { return x; } }
+};
+
+function resolveSemiring( sr ) {
+	if ( !sr ) return SEMIRINGS.logodds;
+	return typeof sr === 'string' ? (SEMIRINGS[sr] || SEMIRINGS.logodds) : sr;
+}
+
+/**
+ * Fold a list of contributions under a semiring's ⊕ (commutative -> order-independent), then
+ * apply the readout. The accumulation is the abstract value; the readout is the observable.
+ * @param values  the contributions (`{__push}`ed)
+ * @param sr      a built-in name or a `{ plus, zero, readout }` object (default 'logodds')
+ * @returns { acc, value, n }  acc = Σ⊕ contributions, value = readout(acc)
+ */
+function reduceSemiring( values, sr ) {
+	sr = resolveSemiring(sr);
+	var xs = values || [], acc = sr.zero;
+	for ( var i = 0; i < xs.length; i++ ) acc = sr.plus(acc, xs[i]);
+	return { acc: acc, value: sr.readout ? sr.readout(acc) : acc, n: xs.length };
+}
+
+// ---- Pareto / skyline selection (the multi-criteria SELECT operator for the support grammar's
+// Candidate/Selected cluster). Laurie's framing: skyline-of-union is an IDEMPOTENT COMMUTATIVE
+// MONOID, so it folds in reduceSemiring exactly like any semiring and inherits E1 order-
+// independence; criteria scored on DISCRETE BAND RANKS keep dominance deterministic & memoizable
+// (the float skyline is fragile — re-keys the K1 memo) and bound the front size. ----
+
+// Rank of a value under a criterion spec — HIGHER RANK = BETTER, always (polarity folded in here,
+// so dominance never silently selects the worst). A spec is either an ORDERED band list worst→best
+// (the order IS the preference direction) or { dir:'max'|'min' } for a numeric criterion. A
+// missing/unknown band ranks below all, so it never spuriously dominates.
+function rankOf( value, spec ) {
+	if ( Array.isArray(spec) ) { var i = spec.indexOf(value); return i < 0 ? -1 : i; }
+	if ( spec && spec.order ) { var j = spec.order.indexOf(value); return j < 0 ? -1 : j; }
+	var n = Number(value);
+	if ( !isFinite(n) ) return -Infinity;
+	return (spec && spec.dir === 'min') ? -n : n;     // min: lower is better -> negate
+}
+
+// Strict Pareto dominance: a ≥ b on EVERY criterion AND > on at least one. Strict (not weak), so
+// mutually-equal points do NOT dominate each other — ties are kept.
+function dominates( a, b, criteria ) {
+	var keys = Object.keys(criteria), strictly = false;
+	for ( var i = 0; i < keys.length; i++ ) {
+		var ra = rankOf(a[keys[i]], criteria[keys[i]]), rb = rankOf(b[keys[i]], criteria[keys[i]]);
+		if ( ra < rb ) return false;
+		if ( ra > rb ) strictly = true;
+	}
+	return strictly;
+}
+
+// The skyline: points not strictly dominated by any other. Stable (input order preserved); ties
+// all kept. O(n²·d) block-nested-loop — trivial at this scale (a handful of candidates); no index
+// or pre-sort is justified.
+function paretoFront( points, criteria ) {
+	var pts = points || [], out = [];
+	for ( var i = 0; i < pts.length; i++ ) {
+		var dominated = false;
+		for ( var j = 0; j < pts.length; j++ )
+			if ( i !== j && dominates(pts[j], pts[i], criteria) ) { dominated = true; break; }
+		if ( !dominated ) out.push(pts[i]);
+	}
+	return out;
+}
+
+// Étage-2 tie-break: lexicographic by DESCENDING rank along a criterion-priority list.
+function lexCompare( a, b, criteria, lex ) {
+	for ( var i = 0; i < lex.length; i++ ) {
+		var d = rankOf(b[lex[i]], criteria[lex[i]]) - rankOf(a[lex[i]], criteria[lex[i]]);   // desc = better first
+		if ( d ) return d;
+	}
+	return 0;
+}
+
+// Pareto SELECT = étage 1 (front, no weighting) + étage 2 (tie-break, default lexicographic on the
+// criteria order; a custom `opts.tieBreak(a,b)` overrides), with a FINAL deterministic id tie-break
+// so the pick is reproducible run-to-run (a hard tie must not depend on iteration order). idKey='id'.
+function paretoSelect( points, criteria, opts ) {
+	opts = opts || {};
+	var idKey = opts.idKey || 'id',
+	    lex   = opts.lex || Object.keys(criteria),
+	    cmp   = opts.tieBreak || function ( a, b ) { return lexCompare(a, b, criteria, lex); },
+	    front = paretoFront(points, criteria),
+	    ranked = front.slice().sort(function ( a, b ) {
+		    return cmp(a, b) || String(a[idKey]).localeCompare(String(b[idKey]));
+	    }),
+	    selected = ranked[0] || null;
+	return {
+		front     : front,
+		frontIds  : front.map(function ( p ) { return p[idKey]; }),
+		ranked    : ranked,
+		selected  : selected,
+		selectedId: selected ? selected[idKey] : null,
+		n         : (points || []).length
+	};
+}
+
+// Pareto AS A SEMIRING for reduceSemiring: plus = skyline(front ∪ {point}) RECOMPUTED (never an
+// incremental shortcut — that would break associativity → E1 order-independence), zero = ∅,
+// readout = the front. So `reduceSemiring(points, makePareto(crit)).value` is the order-invariant skyline.
+function makePareto( criteria ) {
+	return {
+		plus   : function ( front, point ) { return paretoFront(front.concat([point]), criteria); },
+		zero   : [],
+		readout: function ( front ) { return front; }
+	};
+}
+
+/**
+ * Build the semiring reducer provider fragment (host opt-in, like createVerifier).
+ * @param opts.semirings  extra named semirings merged over the built-ins.
+ * @returns { Semiring: { reduce } }
+ *
+ * Concept wiring:
+ *   { require:['Pool'], ensure:['$contribs.length==$expected'], provider:['Semiring::reduce'],
+ *     semiring:{ contribKey:'contribs', semiring:'logodds', as:'', bands:<optional> } }
+ * Emits the self-flag + <as>acc (the ⊕-fold) + <as>value (readout) + <as>n, and — when a
+ * `bands` table is given — a SNAPPED <as>band / <as>bandRank (barrier-clean enum to gate on).
+ */
+function createSemiring( opts ) {
+	opts = opts || {};
+	var registry = Object.assign({}, SEMIRINGS, opts.semirings);
+	return {
+		Semiring: {
+			reduce: function ( graph, concept, scope, argz, cb ) {
+				var cfg = Object.assign({ contribKey: 'contribs', semiring: 'logodds', as: '' },
+					concept._schema && concept._schema.semiring, argz && argz[0]),
+				    vals = graph.getRef(cfg.contribKey, scope) || [],
+				    as = cfg.as || '',
+				    facts = { $_id: '_parent' };
+				facts[concept._name] = true;
+
+				// pareto family: multi-criteria SELECT (front + tie-break). Emits a barrier-clean
+				// discrete selectedId + the front ids (NOT the candidate objects) for the cluster to gate on.
+				if ( cfg.semiring === 'pareto' ) {
+					var sel = paretoSelect(vals, cfg.criteria || {}, { idKey: cfg.idKey, lex: cfg.lex, tieBreak: cfg.tieBreak });
+					facts[as + 'selectedId'] = sel.selectedId;
+					facts[as + 'frontSize'] = sel.front.length;
+					facts[as + 'frontIds'] = sel.frontIds;
+					facts[as + 'n'] = sel.n;
+					return cb(null, facts);
+				}
+
+				var sr = typeof cfg.semiring === 'string' ? (registry[cfg.semiring] || SEMIRINGS.logodds) : cfg.semiring,
+				    r = reduceSemiring(vals, sr);
+				facts[as + 'acc'] = r.acc;
+				facts[as + 'value'] = r.value;
+				facts[as + 'n'] = r.n;
+				if ( cfg.bands ) {                       // optional snapped readout (barrier-clean enum)
+					var b = bandOf(r.value, cfg.bands);
+					facts[as + 'band'] = b.label;
+					facts[as + 'bandRank'] = b.rank;
+				}
+				cb(null, facts);
+			}
+		}
+	};
+}
+
+/**
+ * A ready-made reducer concept fragment: contributions `{__push}` into `contribKey`, and a
+ * `Reduce` concept folds them under the semiring once the cardinality gate is satisfied.
+ * @param opts.semiring   built-in name or a semiring object (default 'logodds')
+ * @param opts.contribKey the pushed-contributions array fact (default 'contribs')
+ * @param opts.require    Reduce's require (default ['Pool'])
+ * @param opts.as         output prefix
+ * @param opts.bands      optional snapped-band table
+ */
+function semiringConceptTree( opts ) {
+	opts = opts || {};
+	var contribKey = opts.contribKey || 'contribs',
+	    semiring = { contribKey: contribKey, semiring: opts.semiring || 'logodds', as: opts.as || '' };
+	if ( opts.bands ) semiring.bands = opts.bands;
+	return {
+		childConcepts: {
+			Reduce: {
+				_id: 'Reduce', _name: 'Reduce',
+				require: opts.require || ['Pool'],
+				ensure: ['$' + contribKey + '.length==$expected'],
+				provider: ['Semiring::reduce'],
+				semiring: semiring
+			}
+		}
+	};
+}
+
+/**
+ * A ready-made multi-criteria SELECT concept (the support grammar's Candidate→Selected step, J2):
+ * candidate vectors `{__push}` into `contribKey`, and a `Select` concept folds them with the `pareto`
+ * semiring once the cardinality gate holds — emitting the Pareto front + a deterministic lexicographic
+ * pick (`selectedId`). Same shape as semiringConceptTree, specialized to the pareto family.
+ * @param opts.criteria   {name: bandList|{dir}} the comparison criteria (REQUIRED to be useful)
+ * @param opts.lex        criterion-priority order for the tie-break (default: criteria key order)
+ * @param opts.idKey      candidate id key (default 'id')
+ * @param opts.contribKey pooled-candidates array fact (default 'candidates')
+ * @param opts.require    Select's require (default ['Pool'])
+ * @param opts.as         output prefix
+ */
+function selectConceptTree( opts ) {
+	opts = opts || {};
+	var contribKey = opts.contribKey || 'candidates',
+	    semiring = { contribKey: contribKey, semiring: 'pareto', criteria: opts.criteria || {}, as: opts.as || '' };
+	if ( opts.lex ) semiring.lex = opts.lex;
+	if ( opts.idKey ) semiring.idKey = opts.idKey;
+	return {
+		childConcepts: {
+			Select: {
+				_id: 'Select', _name: 'Select',
+				require: opts.require || ['Pool'],
+				ensure: ['$' + contribKey + '.length==$expected'],
+				provider: ['Semiring::reduce'],
+				semiring: semiring
+			}
+		}
+	};
+}
+
+module.exports = {
+	SEMIRINGS: SEMIRINGS,
+	reduceSemiring: reduceSemiring,
+	createSemiring: createSemiring,
+	semiringConceptTree: semiringConceptTree,
+	selectConceptTree: selectConceptTree,
+	// Pareto / skyline selection (the multi-criteria SELECT operator; a semiring that folds in reduceSemiring)
+	rankOf: rankOf,
+	dominates: dominates,
+	paretoFront: paretoFront,
+	lexCompare: lexCompare,
+	paretoSelect: paretoSelect,
+	makePareto: makePareto
+};