skynet-graph 1.2.0

package/lib/authoring/author.js

@@ -0,0 +1,147 @@
+/*
+ * 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';
+/**
+ * Declarative AI-authoring as a CEGIS loop (counterexample-guided inductive
+ * synthesis — Solar-Lezama 2006), the host-side capstone of roadmap #10
+ * (doc/MODELISATION.md §6.5). Zero core change: it composes the engine's
+ * `addConcept`/`patchConcept` with the author-time validator.
+ *
+ * The concept schema IS a typed grammar; the AI authors TERMS of it, the host owns
+ * the PRIMITIVES (the provider palette + the ref alphabet). Two oracles bound the
+ * search:
+ *   - author-time oracle = `validateConceptTree` — a malformed candidate (prose
+ *     dependency / bad expr / unknown ref / off-palette provider) is rejected
+ *     BEFORE it touches the graph; the rejection is a counterexample;
+ *   - behavioral oracle = the live graph — install, stabilize, test the goal
+ *     predicate; an unmet goal is a counterexample.
+ * Each counterexample is appended to `history` and handed to the next proposal, so
+ * the candidate space strictly shrinks (CEGIS convergence / monotonicity).
+ *
+ *   const { authorConcept } = require('./author');
+ *   const res = await authorConcept(graph, {
+ *     goal:    (g) => ({ met: <bool>, counterexample: <string|null> }),
+ *     propose: async ({ goal, history, round }) => ({ op:'add'|'patch', ... }),
+ *     validate:{ palette, knownFacts, collectionKeys, strict },
+ *     maxRounds: 5,
+ *   });
+ *   // res = { ok, concept?, rounds:[{proposal, outcome, counterexample?}], reason? }
+ *
+ * A `proposal` is one of:
+ *   { op:'add',   parent:<nameOrId|null>, schema:<conceptSchema> }
+ *   { op:'patch', nameOrId:<concept>,     updates:<partialSchema> }
+ *
+ * The proposer is INJECTED (an LLM::complete call in production; a deterministic
+ * stub in tests) — same backend-agnostic discipline as the providers.
+ */
+const dmerge = require('deepmerge');
+const { validateConceptTree } = require('./validate');
+
+const replaceArrays = { arrayMerge: function ( _dest, src ) { return src; } };
+
+// Wrap a single concept schema as a tree the validator can walk.
+function asTree( schema ) {
+	return { childConcepts: { [schema._id]: schema } };
+}
+
+// Await one stabilize after a structural op; surface a synchronous engine throw
+// (e.g. duplicate _id, unknown parent) as a rejected promise.
+//
+// Engine gotcha (verified): `stabilize(cb)` only fires `cb` once something settles —
+// i.e. only if the op destabilized at least one object. A NO-OP op (a patch that
+// changes no cast-state, or an add that matches nothing) destabilizes nothing, so the
+// "stabilize" event never comes and the callback would hang. But a no-op means the
+// graph is ALREADY quiescent, so honour the callback on the next tick. A real op
+// leaves `_unstable`/`_triggeredCastCount` non-empty and resolves via the event.
+function applyOp( graph, proposal ) {
+	return new Promise(function ( resolve, reject ) {
+		var done = false;
+		var finish = function () { if ( !done ) { done = true; resolve(); } };
+		try {
+			if ( proposal.op === 'patch' )
+				graph.patchConcept(proposal.nameOrId, proposal.updates, finish);
+			else
+				graph.addConcept(proposal.parent == null ? null : proposal.parent, proposal.schema, finish);
+		} catch ( e ) { return reject(e); }
+		if ( !graph._unstable.length && !graph._triggeredCastCount ) setTimeout(finish);
+	});
+}
+
+async function authorConcept( graph, spec ) {
+	const goal       = spec.goal;
+	const propose    = spec.propose;
+	const validate   = spec.validate || {};
+	const maxRounds  = spec.maxRounds || 5;
+	const history    = [];
+
+	for ( let round = 0; round < maxRounds; round++ ) {
+		const proposal = await propose({ goal: spec.goalDescription, history, round });
+		if ( !proposal ) break;                       // proposer gave up
+		const op = proposal.op || 'add';
+
+		// 1. AUTHOR-TIME ORACLE — validate the candidate (for a patch, validate the
+		//    schema it would PRODUCE, so a patch that introduces a bad expr/ref is caught too).
+		let tree;
+		if ( op === 'patch' ) {
+			const c = graph.getConceptByName(proposal.nameOrId);
+			const merged = c ? dmerge(c._schema, proposal.updates || {}, replaceArrays)
+			                 : Object.assign({ _id: proposal.nameOrId, _name: proposal.nameOrId }, proposal.updates);
+			tree = asTree(merged);
+		} else {
+			tree = asTree(proposal.schema);
+		}
+		const errs = validateConceptTree(tree, validate).errors;
+		if ( errs.length ) {
+			history.push({ proposal, outcome: 'rejected', counterexample: `validation-failed: ${errs[0].kind} — ${errs[0].message}` });
+			continue;
+		}
+
+		// 1.5 ADMISSION GATE (optional) — a semantic gate beyond well-formedness, e.g. the
+		//     MDL/utility gate for an abstraction (lib/authoring/abstraction.js): admit only a
+		//     candidate that is fixpoint-equivalent + net-cheaper. A non-admission is a
+		//     counterexample (the candidate is NOT installed). The gate may be async and gets
+		//     (graph, proposal, {history, round}); returning {admit:false, reason} rejects.
+		if ( spec.gate ) {
+			const g = await spec.gate(graph, proposal, { history, round });
+			if ( g && g.admit === false ) {
+				history.push({ proposal, outcome: 'rejected', counterexample: `gate-rejected: ${g.reason || 'not admitted'}` });
+				continue;
+			}
+		}
+
+		// 2. INSTALL — engine-level guards (dup _id, unknown parent) are counterexamples too.
+		try {
+			await applyOp(graph, proposal);
+		} catch ( e ) {
+			history.push({ proposal, outcome: 'rejected', counterexample: `install-failed: ${e.message}` });
+			continue;
+		}
+
+		// 3. BEHAVIORAL ORACLE — does the live graph now satisfy the goal?
+		const verdict = goal(graph) || {};
+		if ( verdict.met ) {
+			history.push({ proposal, outcome: 'met' });
+			return { ok: true, concept: op === 'patch' ? proposal.nameOrId : proposal.schema._id, rounds: history };
+		}
+		history.push({ proposal, outcome: 'unmet', counterexample: verdict.counterexample || 'goal not met' });
+	}
+
+	return { ok: false, rounds: history, reason: 'maxRounds exhausted without meeting goal' };
+}
+
+module.exports = { authorConcept };

package/lib/authoring/bounded-merge.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * bounded-merge — the BOUNDED `project` at a fork/merge JOIN (host-side, ZERO-CORE). The enforcement gate
+ * Lens 3 flagged: `Graph#merge(child, targetId)` with NO project DEFAULTS to crossing the WHOLE serialized
+ * child (`{ forkResult: child.serialize() }`) — which re-creates the O(N) context blowup the architecture
+ * exists to avoid (a child's entire sub-graph leaks across the AND-join). The bounded-context contract
+ * (master-graph study §2.3, rule A1/A6) requires every join to cross only a separator-sized FRONTIER.
+ *
+ * `boundedProject` builds a `project` fn that crosses ONLY the declared frontier facts (the separator
+ * alphabet Σ_sep), snapped off one result object in the child — so the merge traffic is O(|frontier|),
+ * independent of the child's size. Pair it with `validate` (the author-time `validateMergeProjection`
+ * frontier-leak check) to assert no key escapes the alphabet.
+ *
+ *   const project = boundedProject({ targetId: 'root', from: 'result', keys: ['answer', 'cost'] });
+ *   parent.merge(child, 'root', project);     // crosses {answer,cost} only — NOT the whole child
+ */
+const { validateMergeProjection } = require('./validate.js');
+
+/**
+ * @param spec.targetId  the parent object the projection updates ($$_id)
+ * @param spec.from      the child object id whose facts are the result (default: spec.targetId)
+ * @param spec.keys      the frontier fact keys allowed to cross (the separator alphabet)
+ * @returns (child) => mutationTemplate   a `project` fn for Graph#merge that crosses only `keys`
+ */
+function boundedProject( spec ) {
+	spec = spec || {};
+	const targetId = spec.targetId, from = spec.from || spec.targetId, keys = spec.keys || [];
+	return function ( child ) {
+		const e = child.getEtty ? child.getEtty(from) : null;
+		const f = (e && e._) || {};
+		const out = { $$_id: targetId };
+		for ( const k of keys ) if ( f[k] !== undefined ) out[k] = f[k];   // ONLY the frontier crosses
+		return out;
+	};
+}
+
+/**
+ * Author-time check that a produced merge template crosses only the declared frontier alphabet (no leak).
+ * Thin wrapper over `validate.js#validateMergeProjection` so a host can gate a merge before applying it.
+ * A frontier leak (a key crossing that isn't in the alphabet) is a `frontier-leak` warning (an error under
+ * `strict`); `ok` is false if anything leaked.
+ * @returns { errors:[…], warnings:[…], leaks:[…], ok:bool }
+ */
+function validate( template, frontierKeys, opts ) {
+	const r = validateMergeProjection(template, Object.assign({ frontierAlphabet: frontierKeys || [] }, opts || {})) || {};
+	const errors = r.errors || [], warnings = r.warnings || [];
+	const leaks = warnings.filter(( w ) => w && w.kind === 'frontier-leak').concat(errors.filter(( e ) => e && e.kind === 'frontier-leak'));
+	return { errors, warnings, leaks, ok: errors.length === 0 && leaks.length === 0 };
+}
+
+module.exports = { boundedProject, validate };

package/lib/authoring/canon.js

@@ -0,0 +1,158 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * canon — the CANONICALIZATION BARRIER as a standalone brick (values AND structure).
+ *
+ * Two field-proven moves, promoted from experiment code where each served twice (2026-07-03):
+ *
+ *   1. VALUE snap (`snapToVocab`) — the intake barrier: a model-extracted SURFACE value is snapped onto the
+ *      vocabulary of the system's OWN data (exact ci-match keeps the surface form; containment either way
+ *      snaps to the canonical form; anything else survives RAW and is counted OOV — the honest path: a
+ *      genuine out-of-vocabulary value must fail downstream verify, never be silently coerced).
+ *
+ *   2. STRUCTURAL canon (`makeStructuralCanon`) — the same barrier applied to a typed step-list: a model
+ *      emits ONE plan at SEVERAL granularities (e.g. `[filter(f,v), aggregate]` vs `[aggregate(f,v)]`),
+ *      related exactly by recurring digrams — the equivalence the system itself mines (`compress.js
+ *      mineDigrams`, GO-gated 2026-07-03). The canon folds those digrams and whitelists per-step facts
+ *      fail-closed, so emission STABILITY (and every downstream memo/LGG key) is claimed MODULO a learned
+ *      equivalence, never modulo an ad-hoc regex.
+ *
+ * Both are K1 instruments: they keep dependency edges on DISCRETE, canonical keys (doc/API.md facts/prose
+ * contract). Fail-closed throughout — a fact that cannot be certified is DROPPED, never guessed:
+ *   - facts live only on declared `factKinds` steps;
+ *   - if the gating fact (default `value`) is absent or out of the data vocabulary, ALL facts drop for
+ *     that step (an operation word leaked into `value` must not survive as a param);
+ *   - a fold merges facts per-key: one side present → carried; both present and ci-equal → kept; a
+ *     CONFLICT → the key is dropped (parallel-over-collapse, the §9 rule at fact grain).
+ */
+
+const low = ( v ) => String(v).toLowerCase();
+
+/**
+ * Snap a surface value onto a canonical vocabulary.
+ * @param value   the extracted surface form
+ * @param vocab   array of canonical strings (the system's own data values — never test golds)
+ * @param stats   optional { kept, snapped, oov } counters, incremented in place
+ * @returns { value, verdict } — verdict ∈ exact|snapped|oov
+ */
+function snapToVocab( value, vocab, stats ) {
+	stats = stats || {};
+	const v = low(value == null ? '' : value);
+	if ( vocab.some(( c ) => low(c) === v) ) {
+		stats.kept = (stats.kept || 0) + 1;
+		return { value: value, verdict: 'exact' };
+	}
+	// containment must be UNIQUE to snap: a hypernym surface ('plug' ⊂ europlug|usplug|ukplug) matches
+	// several vocab words — snapping to the first is an arbitrary wrong pick that then OVERRIDES a correct
+	// explicit fact downstream (measured: the G3 plugs domain). Ambiguous containment → OOV, fail-closed.
+	const hits = v ? vocab.filter(( c ) => v.includes(low(c)) || low(c).includes(v) ) : [];
+	if ( hits.length === 1 ) {
+		stats.snapped = (stats.snapped || 0) + 1;
+		return { value: hits[0], verdict: 'snapped' };
+	}
+	stats.oov = (stats.oov || 0) + 1;
+	if ( hits.length > 1 ) { stats.ambiguous = (stats.ambiguous || 0) + 1; return { value: value, verdict: 'oov', ambiguous: hits }; }
+	return { value: value, verdict: 'oov' };
+}
+
+/** Fold specs from a `compress.js#mineDigrams` result: each mined adjacent pair (a,b) above minSupport
+ *  becomes a fold `[a, b] → b` (facts carried per the merge rule). The folds are thereby LEARNED from the
+ *  system's own traces — the only legitimacy a structural rewrite gets. */
+function foldsFromDigrams( digrams, opts ) {
+	opts = opts || {};
+	const min = opts.minSupport != null ? opts.minSupport : 2;
+	return (digrams || []).filter(( d ) => d && d.a && d.b && (d.support == null || d.support >= min) )
+		.map(( d ) => ({ a: d.a, b: d.b, into: opts.into || d.b }));
+}
+
+/**
+ * Build a structural canonicalizer over typed step-lists.
+ * @param opts {
+ *   kindKey   = 'stepKind'          — the step's kind fact
+ *   factKeys  = []                  — per-step content facts under whitelist discipline (e.g. ['field','value'])
+ *   factKinds = null                — kinds allowed to carry facts (null = all kinds)
+ *   gateKey   = 'value'             — the fact whose vocabulary membership gates ALL facts of the step
+ *   vocab     = null                — array/Set of data values (ci); null = no vocabulary gate
+ *   folds     = []                  — [{a, b, into}] adjacent-digram folds (see foldsFromDigrams)
+ * }
+ * @returns ( steps ) => canonical steps (null in → null out; input never mutated)
+ */
+function makeStructuralCanon( opts ) {
+	opts = opts || {};
+	const kindKey = opts.kindKey || 'stepKind';
+	const factKeys = opts.factKeys || [];
+	const factKinds = opts.factKinds ? new Set(opts.factKinds) : null;
+	const gateKey = opts.gateKey || 'value';
+	const vocab = opts.vocab ? new Set([...opts.vocab].map(low)) : null;
+	const folds = opts.folds || [];
+
+	const clean = ( s ) => {
+		const kind = s[kindKey];
+		let keep = !factKinds || factKinds.has(kind);
+		if ( keep && vocab && factKeys.includes(gateKey) )
+			keep = s[gateKey] != null && vocab.has(low(s[gateKey]));
+		const out = Object.assign({}, s);
+		for ( const k of factKeys ) if ( !keep || out[k] == null ) delete out[k];
+		return out;
+	};
+
+	// per-key fact merge: one side → carried · ci-equal → kept · conflict → DROPPED (fail-closed)
+	const mergeFacts = ( a, b ) => {
+		const m = {};
+		for ( const k of factKeys ) {
+			if ( a[k] != null && b[k] != null ) { if ( low(a[k]) === low(b[k]) ) m[k] = a[k]; }
+			else if ( a[k] != null ) m[k] = a[k];
+			else if ( b[k] != null ) m[k] = b[k];
+		}
+		return m;
+	};
+
+	return function canon( steps ) {
+		if ( !Array.isArray(steps) ) return null;
+		let cur = steps.map(clean);
+		for ( let pass = 0; pass < steps.length; pass++ ) {                     // to fixpoint, bounded
+			const out = [];
+			let folded = false;
+			for ( let i = 0; i < cur.length; i++ ) {
+				const nxt = cur[i + 1];
+				const f = nxt && folds.find(( f ) => cur[i][kindKey] === f.a && nxt[kindKey] === f.b );
+				if ( f ) {
+					const facts = mergeFacts(cur[i], nxt);
+					const base = Object.assign({}, nxt);
+					for ( const k of factKeys ) delete base[k];
+					Object.assign(base, facts);
+					base[kindKey] = f.into || f.b;
+					out.push(base);
+					i++; folded = true;
+				}
+				else out.push(cur[i]);
+			}
+			cur = out;
+			if ( !folded ) break;
+		}
+		return cur;
+	};
+}
+
+/** The kinds-only key of a step-list — the SHAPE face of stability (G1's post-canon comparison). */
+const shapeKey = ( steps, opts ) => steps == null ? null
+	: JSON.stringify(steps.map(( s ) => s[(opts && opts.kindKey) || 'stepKind'] ));
+
+/** The shape+facts key (ci values) — the full canonical digest both experiments compared on. */
+function canonKey( steps, opts ) {
+	if ( steps == null ) return null;
+	const kindKey = (opts && opts.kindKey) || 'stepKind';
+	const factKeys = (opts && opts.factKeys) || [];
+	return JSON.stringify(steps.map(( s ) => {
+		const o = { k: s[kindKey] };
+		for ( const f of factKeys ) o[f] = s[f] != null ? low(s[f]) : '';
+		return o;
+	}));
+}
+
+module.exports = { snapToVocab, foldsFromDigrams, makeStructuralCanon, shapeKey, canonKey };

package/lib/authoring/clock.js

@@ -0,0 +1,123 @@
+/*
+ * 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';
+/**
+ * Host-side clock for freshness / TTL / epochs as facts (roadmap N1).
+ *
+ * Time enters the graph as an ordinary fact on a `clock` free-node — the engine has no
+ * internal wall-clock (and shouldn't: that keeps replay hermetic). A time-bound concept
+ * gates freshness in an `ensure`, e.g. `ensure:["$$clock:tick - $sensedAt < $ttl"]`.
+ *
+ * IMPORTANT: reference the global clock with a DOUBLE-`$` — `$$clock:tick`. A single
+ * `$clock` is a key on the *current* scope (almost always undefined); the ref regex
+ * consumes one `$`, so the global free-node ref needs two (HANDOFF §3). A provider reads
+ * it via `clockNow(graph)`.
+ *
+ * Advancing the clock (a one-line mutation) re-tests EXACTLY the concepts whose `ensure`
+ * follows `$$clock:tick` — the existing ensure/defeasance re-fire path. A fact that has
+ * gone stale (and its dependents) retracts in cascade; this is the cache-poisoning fix
+ * (a graven LLM/API fact otherwise lives forever). Near-zero new evaluation code.
+ *
+ * BOUNDARY (honest): invalidation is automatic + reliable. Automatic RE-FETCH is not —
+ * a provider is cast-once, so a stale provider-fact re-derives only on uncast→recast.
+ * Re-trigger it from the host (`refetch` below = uncast/recast, which re-runs the
+ * provider with the now-current clock) or bump its input. A fully-autonomous reaper that
+ * destabilizes+recasts stale nodes itself is an optional core primitive (see HANDOFF §5).
+ */
+
+const CLOCK_ID = 'clock';
+
+// A clock seed entry — spread into `seed.freeNodes`.
+function clockSeed( tick ) { return { _id: CLOCK_ID, tick: tick || 0 }; }
+
+// The current tick (for a provider to stamp `<x>At: clockNow(graph)`).
+function clockNow( graph ) {
+	var c = graph._objById[CLOCK_ID];
+	return c ? c._etty._.tick : undefined;
+}
+
+// Advance the clock by `delta` (default 1). Returns the new tick. Re-tests every
+// `$$clock:tick`-following concept → stale facts (and dependents) retract.
+function advanceClock( graph, delta ) {
+	var tick = (clockNow(graph) || 0) + (delta == null ? 1 : delta);
+	graph.pushMutation({ $$_id: CLOCK_ID, tick: tick }, CLOCK_ID);
+	return tick;
+}
+
+// Host-triggered refetch of a cast-once provider concept: re-run it against the current
+// clock. If still cast (forced early refresh) uncast first; if already stale-retracted,
+// a direct re-cast re-runs the provider. The reliable refresh path (zero-core).
+function refetch( graph, objId, conceptId, cb ) {
+	var etty = graph._objById[objId] && graph._objById[objId]._etty,
+	    isCast = etty && etty._mappedConcepts && etty._mappedConcepts[conceptId];
+	if ( isCast ) graph.unCastConcept(objId, conceptId, function () { graph.castConcept(objId, conceptId, cb); });
+	else graph.castConcept(objId, conceptId, cb);
+}
+
+/**
+ * Freshness reaper (N1 follow-on) — a zero-core HOST helper over `refetch`: the host registers
+ * freshness contracts and calls `reap()` (e.g. right after `advanceClock`, or on a wall-clock
+ * timer) to re-run the cast-once provider for every node whose stamp has aged past its TTL.
+ * Invalidation is already automatic (a `$$clock`-gated `ensure` retracts a stale fact); this
+ * automates the RE-FETCH that a cast-once provider otherwise needs the host to trigger per node.
+ *
+ * (The fully-autonomous version — the ENGINE reaping itself by piggybacking the settle loop —
+ * is an optional CORE primitive, see HANDOFF §5; this is the host-loop form on existing parts.)
+ *
+ *   const reaper = makeReaper(graph);
+ *   reaper.watch('sensorNode', 'Sensor', { stampKey: 'sensedAt', ttl: 100 });
+ *   advanceClock(graph, 200);
+ *   reaper.reap((n) => { ... n stale provider-facts re-fetched ... });
+ *
+ * A provider under a reaped contract MUST re-stamp its `stampKey` with `clockNow(graph)` when it
+ * runs, or it stays stale and re-fetches every sweep.
+ */
+function makeReaper( graph ) {
+	var contracts = [];
+	return {
+		// Register a freshness contract. ttl is in clock-tick units; stampKey is the fact the
+		// provider stamps with `clockNow(graph)`.
+		watch: function ( objId, conceptId, opts ) {
+			opts = opts || {};
+			contracts.push({ objId: objId, conceptId: conceptId, stampKey: opts.stampKey || 'sensedAt', ttl: opts.ttl });
+			return this;
+		},
+		// The contracts whose stamp is missing or older than ttl vs the current clock.
+		stale: function () {
+			var now = clockNow(graph) || 0, out = [];
+			contracts.forEach(function ( c ) {
+				var o = graph._objById[c.objId], etty = o && o._etty;
+				if ( !etty ) return;                                    // node gone — nothing to reap
+				var stamp = etty._[c.stampKey];
+				if ( stamp == null || (now - stamp) >= c.ttl ) out.push(c);
+			});
+			return out;
+		},
+		// Re-fetch every stale contract; cb(count) fires once all re-fetches have settled.
+		reap: function ( cb ) {
+			var due = this.stale(), n = due.length, done = 0;
+			if ( !n ) { cb && cb(0); return 0; }
+			due.forEach(function ( c ) {
+				refetch(graph, c.objId, c.conceptId, function () { if ( ++done === n && cb ) cb(n); });
+			});
+			return n;
+		}
+	};
+}
+
+module.exports = { CLOCK_ID: CLOCK_ID, clockSeed: clockSeed, clockNow: clockNow, advanceClock: advanceClock, refetch: refetch, makeReaper: makeReaper };

package/lib/authoring/combinator.js

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * combinator — the dispatch→MOUNT bridge (P2.5; host-side, ZERO-CORE; study
+ * doc/WIP/studies/2026-06-30-creative-loop-two-level-grammar.md, brick B).
+ *
+ * Brick A (`library.js`) SELECTS a learned method for an abstract mechanism (an O(1) `libraryKey` lookup refined by
+ * application-conditions = structure-mapping). Brick B MOUNTS it: a higher-order method = a CONCEPT whose `require`
+ * is its behavioral hole; when the hole's fragment co-occurs justified at a site, the concept casts and its provider
+ * binds the DISPATCHED fragment's template to the call site and splices it — at 0 model calls. The hole is filled by
+ * the library method whose FrontierSignature the structuring grammar's target dispatched to, so a concept can REUSE
+ * another concept's learned method purely because their abstract interfaces match (recombination = the creative step).
+ *
+ * Engine landmines respected (mirrors crystallize.js#buildStructuralProvider): the returned template MUST self-flag
+ * the cast (provider-cast-marker gotcha, else re-fire to the apply-cap), an unbound frontier ref BYPASSES (never a
+ * wrong replay), and the splice rides the SEQUENCED cb (determinism). The interface alphabet must align: the
+ * combinator's frontier param NAMES must equal the fragment's hole names (the snapped separator).
+ */
+const { dispatch } = require('./library.js');
+const { ctxFromScope, instantiate } = require('./abstract.js');
+const { digest } = require('../providers/canonicalize.js');
+
+// the call-site facts projected onto a fragment's replay signature (mirrors crystallize.js#projectFacts).
+const projectFacts = ( facts, keys ) => { const o = {}; for ( const k of (keys || []) ) if ( facts && k in facts ) o[k] = facts[k]; return o; };
+
+// the re-fire GUARD fact a combinator gates on — a DISTINCT durable mutation fact, NOT the concept's own `_name`
+// marker. Gating on the self-flag does not stop re-application (finding #27 "self-flag not durable" — verified: the
+// concept-name marker set by a provider does not gate the same concept's `ensure`; the crystallizer gates on the
+// fragment's `Refined`, not `!$CrystalRefine`). So we mint `<cryId>Done`.
+const guardKey = ( cryId ) => cryId + 'Done';
+
+// add the combinator's cast marker AND its durable re-fire guard to the mounted parent object (mirrors
+// crystallize.js#injectCastMarker, plus the separate guard so the concept de-applies after one mount).
+function injectMarker( ground, base, cryId ) {
+	return (Array.isArray(ground) ? ground : [ground]).map(( o ) => {
+		if ( !o || typeof o !== 'object' ) return o;
+		const idv = String(o.$$_id != null ? o.$$_id : (o.$_id != null ? o.$_id : o._id)).replace(/^\$+/, '');
+		return (o.$_id === '_parent' || idv === base) ? Object.assign({}, o, { [cryId]: true, [guardKey(cryId)]: true }) : o;
+	});
+}
+
+/**
+ * A provider that DISPATCHES a library fragment for the call site, then MOUNTS it bound to the site (0 model calls).
+ * @param spec.lib            the method library (`library.js`).
+ * @param spec.cryId          the combinator's cast-marker / concept name.
+ * @param spec.target         { frontier, signatureKeys } — the abstract mechanism this combinator wants (the target
+ *                            FrontierSignature the structuring grammar describes). May be a fn (scope)->target.
+ * @param spec.frontierFields { name: factKey|"ref:path" } — where each frontier endpoint lives on the cast object (its
+ *                            names MUST equal the dispatched fragment's hole names).
+ * @param spec.pick           optional (candidates, scope)->candidate (default = top by weight; the supervisor's choice).
+ */
+function buildDispatchProvider( spec ) {
+	return function ( graph, concept, scope, argz, cb ) {
+		const noop = { $_id: '_parent', [spec.cryId]: true, [guardKey(spec.cryId)]: true };   // bypass: marker + guard (no re-fire)
+		const target = typeof spec.target === 'function' ? spec.target(scope) : spec.target;
+		const r = dispatch(spec.lib, target, scope._ || {});
+		const top = spec.pick ? spec.pick(r.candidates, scope) : r.candidates[0];
+		if ( !top ) return cb(null, noop);                             // the structuring grammar must forge (no library hit)
+		const cand = top.candidate;
+		const ctx = ctxFromScope(scope, { frontier: spec.frontierFields });
+		if ( !ctx ) return cb(null, noop);                             // unknown base → bypass
+		const tpl = (cand.templatesBySig || {})[digest(projectFacts(scope._ || {}, cand.signatureKeys || []))];
+		if ( !tpl ) return cb(null, noop);                             // the dispatched method has no template for this signature class
+		const ground = instantiate(tpl, ctx);
+		if ( !ground ) return cb(null, noop);                          // an unbound frontier ref → bypass
+		return cb(null, injectMarker(ground, ctx.base, spec.cryId));   // mount the dispatched fragment, self-flagged
+	};
+}
+
+/**
+ * Build a higher-order combinator CONCEPT that mounts a dispatched library fragment via require-resolution. The
+ * concept casts when its `require` markers co-occur (the fragment is justified-present); its provider dispatches +
+ * mounts. Mirrors `method.js#selectCluster` / `relearn.js#relearnTree` (concept + provider, host-wired).
+ * @returns { schema, provider, providerName }  — register the provider and drop the schema into a concept tree.
+ */
+function dispatchConcept( opts ) {
+	const cryId = opts.name;
+	const provider = buildDispatchProvider({ lib: opts.lib, cryId, target: opts.target, frontierFields: opts.frontierFields, pick: opts.pick });
+	const providerName = 'Combinator::' + cryId;
+	// gate on the DURABLE guard fact `<cryId>Done` (set by the mount/bypass), NOT the self-flag `!$<cryId>` (which does
+	// not stop re-application — finding #27). require + this ensure = the higher-order require-resolution trigger.
+	const schema = { _id: cryId, _name: cryId, require: (opts.require || []).slice(), ensure: ['!$' + guardKey(cryId)], provider: [providerName] };
+	if ( opts.assert ) schema.assert = Array.isArray(opts.assert) ? opts.assert.slice() : [opts.assert];
+	return { schema, provider, providerName };
+}
+
+module.exports = { buildDispatchProvider, dispatchConcept, injectMarker, guardKey };

package/lib/authoring/compete.js

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * compete — §6.1 MULTI-PATH `Construct` → the dominance-gated competitive crystallizer (host-side, ZERO-CORE; spec
+ * §6.1, refined by the 2026-06-30 Laurie residency confront).
+ *
+ * A `Construct` is the abstract, multi-hypothesis stage of the Construct→Method gradient: an LLM response is a SET of
+ * candidate decompositions that expand. This provider runs that competition — propose N candidates, SELECT the survivor
+ * by the `pareto` semiring (`semiring.js#paretoSelect`, the realized multi-criteria outcome, not a static heuristic) —
+ * and EMITS the winner's decomposition as a bounded STRUCTURAL sub-graph so the existing trace→mine→crystallize pipeline
+ * (the kill-gate's) turns a recurrent winner into a re-mountable `Method`. The next same-class problem then DISPATCHES
+ * the winner at 0 model calls, eliding the WHOLE N-way rollout.
+ *
+ * RESIDENCY = isolated forks / per-instance competition (ZERO-CORE). True co-residency of contradictory branches = an
+ * ATMS multi-context (de Kleer 1986) over a single-context JTMS engine — FILED (its only justifying case, a non-local
+ * frontier, is what `contract.js` G1 already forbids). The candidate ELABORATION is the host's `propose` (a real
+ * `graph.fork` rollout live, like `examples/poc/problem-compete.js`; a deterministic scorer in tests).
+ *
+ * THE LOAD-BEARING SOUNDNESS GATE (Laurie pt2 — else the survivor is a SILENT MIS-DISPATCHER): crystallizing the
+ * survivor with `pre:[]` is candidate elimination (Mitchell 1982) with the NEGATIVES (the losing siblings) discarded.
+ * The fix reifies the SELECTION CRITERION, not the siblings:
+ *   • emit the winner's STRUCTURAL decomposition ONLY on a CLEAN DOMINANCE (`front.length===1`, one strict Pareto
+ *     dominator); a Pareto TIE (`front.length>1`, a trade-off / equally-good sibling) → a FLAT head marker only, which
+ *     the structural miner SKIPS (the existing flat-patch-skip IS the tie-gate — an arbitrary pick is unsound);
+ *   • a winner that FLIPS for the same typed premise → two winner templates for one signature → the crystalliser's
+ *     `signatureDetermined` (K1) REFUSES — winner-determinacy lifted from content-determinacy, no false crystallization.
+ *
+ * Engine landmines respected: a flat length-1 fact patch is skipped by the miner (so the WINNING cast emits a
+ * multi-object sub-graph); a wired provider does NOT auto-flag its cast, so the head sets BOTH the cast marker
+ * `{ Compete:true }` and a DISTINCT durable re-fire guard `{ Competed:true }`.
+ *
+ * @param opts.propose         (scope) -> [{ id, ...criteria, decomp }] | Promise<...>   the candidate decompositions;
+ *                             each carries its pareto-criteria values + a `decomp(base, originNode, targetNode) ->
+ *                             [obj,...]` builder for its structural sub-graph. Injectable: a fork rollout live, a stub in tests.
+ * @param opts.criteria        {name: bandList|{dir}} the pareto comparison criteria (REQUIRED to discriminate).
+ * @param opts.lex             criterion-priority order for the deterministic tie-break (default: criteria key order).
+ * @param opts.discriminantKey the typed premise fact that should determine the winner (default 'taskClass') — echoed
+ *                             onto the head only if NOT a require key (avoids the echoed-require crystallise hazard).
+ * @returns { Compete: { compete } }  a provider-map fragment (concept provider ref `Compete::compete`).
+ */
+const { paretoSelect } = require('../providers/semiring.js');
+
+function makeCompeteProvider( opts ) {
+	opts = opts || {};
+	const propose  = opts.propose;
+	const criteria = opts.criteria || {};
+	const discKey  = opts.discriminantKey || 'taskClass';
+
+	return { Compete: {
+		compete: function ( graph, concept, scope, argz, cb ) {
+			Promise.resolve(propose(scope)).then(function ( cands ) {
+				cands = cands || [];
+				const sel  = paretoSelect(cands, criteria, { idKey: 'id', lex: opts.lex });
+				const base = scope._._id, o = scope._.originNode, t = scope._.targetNode;
+				// the head: the cast marker + the DISTINCT durable re-fire guard + the dominance discriminant (frontSize).
+				const head = { $_id: '_parent', Compete: true, Competed: true, frontSize: sel.front.length };
+				graph.traceProvider && graph.traceProvider(concept, scope, { compete: { frontIds: sel.frontIds, selectedId: sel.selectedId } });
+				const winner = cands.filter(function ( c ) { return c.id === sel.selectedId; })[0];
+
+				// TIE-GATE: a Pareto trade-off (no single dominator) → emit ONLY the flat head marker → the structural
+				// miner skips it (an arbitrary pick among equally-good siblings is unsound to crystallise).
+				if ( sel.front.length !== 1 || !winner || typeof winner.decomp !== 'function' ) return cb(null, head);
+
+				// CLEAN DOMINANCE → emit the winner's structural decomposition (minable → crystallisable iff winner = f(premise)).
+				cb(null, [head].concat(winner.decomp(base, o, t)));
+			}).catch(function ( e ) { cb(null, { $_id: '_parent', Compete: true, Competed: true, llmError: e.message }); });
+		},
+	} };
+}
+
+module.exports = { makeCompeteProvider };