skynet-graph 1.2.0

package/lib/combos/defaults.js

@@ -0,0 +1,86 @@
+/*
+ * 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';
+/**
+ * Combos — the SHARED product-default module (roadmap P1 / design doc §2).
+ *
+ * The ONE place the default posture (§4 of studies/2026-07-04-inventaire-outils-combos.md) is
+ * decided, so every `lib/combos/*` component wires the SAME knobs instead of each re-deciding them.
+ * CONFIG ONLY — each field is a flag or a brick option passed straight through; NO behavior lives
+ * here (behavior would make this a brick-in-disguise, violating the thin-assembly rule). The
+ * default posture, from the convergent findings:
+ *   fail-closed ON · admission gate ON · IntakeStatus required downstream · durable memo ON ·
+ *   author-time validator ON · logs `warn` + audit · constrained grammar OFF (STAGE-1 finding) ·
+ *   effectful providers / embedded LLM / durable / learning = OPT-IN by argument (never by env).
+ */
+
+/**
+ * resolveComboDefaults(opts) → the resolved §4 knob-set, host overrides merged in.
+ * @returns {{
+ *   failClosed:boolean, gate:'gated'|'ungated', requireTyped:boolean, memo:boolean,
+ *   validate:boolean, logLevel:string, audit:boolean, grammar:boolean,
+ *   ask:(function|{localModel:string}|null), durable:(object|string|null), learning:boolean
+ * }}
+ */
+function resolveComboDefaults( opts ) {
+	opts = opts || {};
+	return {
+		failClosed  : opts.failClosed   !== false,   // ON  — canon/snap/mount fail-closed
+		gate        : opts.gate          || 'gated', // ON  — admission gate (parametric/registry, gated)
+		requireTyped: opts.requireTyped  !== false,  // ON  — downstream ensure IntakeStatus=='typed'
+		memo        : opts.memo          !== false,  // ON  — content-addressed cache, un-cacheable on CanonMiss
+		validate    : opts.validate      !== false,  // ON  — validateOrThrow before the tree reaches the engine
+		logLevel    : opts.logLevel      || 'warn',
+		audit       : opts.audit         !== false,  // ON  — apply-correlated trace / durable audit available
+		grammar     : opts.grammar       === true,   // OFF — STAGE-1 finding; opt-in, per-call on the borderline gate
+		ask         : opts.ask           || null,    // opt-in — NO default LLM backend
+		durable     : opts.durable       || null,    // opt-in — off = in-memory / none
+		learning    : opts.learning      === true    // opt-in — creative loop off by default
+	};
+}
+
+/**
+ * buildAsk(d) → resolve `d.ask` to an async `({system,user,maxTokens}) -> string`.
+ *   - a function            → returned as-is (host-supplied backend)
+ *   - { localModel:'<gguf>' } → the embedded node-llama-cpp `ask` via the shared host, with the §4
+ *                             default `reasoningBudget:0` applied HERE (one place, not re-decided per combo)
+ *   - null / absent         → throws (the combo needs a backend)
+ *
+ * Grammar is deliberately NOT wired here (finding R3): `makeLocalAsk` reads `jsonSchema`/`gbnf`, never
+ * a boolean `grammar`; constrained decoding is a per-call seam on the borderline gate, opt-in. So
+ * `buildAsk` never touches grammar — the STAGE-1 default (OFF) is simply "pass no schema".
+ * The `llm-local`/`local-host` requires are LAZY (only when `{localModel}` is used), so a host that
+ * injects its own `ask` never loads the native dependency.
+ */
+function buildAsk( d ) {
+	var a = d && d.ask;
+	if ( typeof a === 'function' ) return a;
+	if ( a && a.localModel ) {
+		var sharedLocalModelHost = require('../providers/local-host.js').sharedLocalModelHost;
+		var makeLocalAsk = require('../providers/llm-local.js').makeLocalAsk;
+		return makeLocalAsk({
+			modelPath      : a.localModel,
+			reasoningBudget: a.reasoningBudget != null ? a.reasoningBudget : 0,
+			seed           : a.seed,
+			host           : sharedLocalModelHost()
+		});
+	}
+	throw new Error('combo needs a backend: pass opts.ask (a function, or { localModel: "<path.gguf>" })');
+}
+
+module.exports = { resolveComboDefaults: resolveComboDefaults, buildAsk: buildAsk };

package/lib/combos/durable-runner.js

@@ -0,0 +1,115 @@
+/*
+ * 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';
+/**
+ * C2 — the DURABLE WORKFLOW RUNNER (roadmap P4). A thin assembly over the durable executor bricks
+ * (`lib/durable/*`): the CheckpointStore (durable marking + content-memo + lease queue, memory or
+ * SQLite), the C-xlate (`compileMethod`: a compact select+task+map+reduce spec → a workflow net), the
+ * interpreter (`runFlow`: routes typed records, memoizes task calls, fans out maps, folds joins,
+ * asserts a per-step contract), and the audit forest (`auditRun`). The properties are already MEASURED
+ * (the §11 gate: STRUCT 6 calls vs RAG 24, 0/12 drift-stale; crash-safety via fencing token +
+ * rollbackInflight): this combo just names them behind one governed entry point.
+ *
+ *   const runner = createDurableRunner({ store: 'flow.db', runTask });
+ *   await runner.run('run-1', spec, records);   // compile-if-spec → ensureRun → inject → runFlow
+ *   await runner.resume('run-1', spec);          // crash-recovery: reclaim orphaned tokens → finish
+ *   const { summary } = runner.audit('run-1');   // the derivation forest + verdict + blame
+ *
+ * The content-memo is SOUND by its key: `keyOf(taskRef, token)` must project to a SUPERSET of the
+ * facts each task reads (so it never under-keys → never a false hit) yet ignore incidental fields (so a
+ * recurrent class amortizes). The default keys on `{task, payload}` (sound but coarse — incidental
+ * fields re-key); pass `opts.keyOf` for tighter amortization (see examples/poc/durable-flow.js).
+ * The bricks stay usable "à nu" (`Graph.durable.*`); this is an optional convenience.
+ *
+ * @param opts.store    a file PATH (→ SQLite, crash-safe, cross-restart) or a store; default in-memory.
+ * @param opts.runTask  (task, token) => {payload?, created?} | Promise<…>   the micro-task runner (REQUIRED).
+ * @param opts.contract optional per-step contract (assertPost G1/G2) passed to runFlow.
+ * @param opts.keyOf    optional content-memo key `(taskRef, token) => key`. Default: digest({task,payload}).
+ * @param opts.lease/batch/maxSteps  optional runFlow bounds.
+ * @param opts.*        the §4 knobs via resolveComboDefaults.
+ * @returns {{ compile, run, resume, audit, stats, marking, store, close }}
+ */
+
+var defaults = require('./defaults.js');
+var xlate = require('../durable/xlate.js');
+var interp = require('../durable/interpreter.js');
+var audit = require('../durable/audit.js');
+var cp = require('../durable/checkpoint-store.js');
+var digest = require('../providers/canonicalize.js').digest;
+
+function looksLikeSpec( x ) { return !!(x && (x.select || x.methods || x.steps || x.map)); }
+
+function createDurableRunner( opts ) {
+	opts = opts || {};
+	var d = defaults.resolveComboDefaults(opts);
+	if ( typeof opts.runTask !== 'function' )
+		throw new Error('createDurableRunner needs opts.runTask ((task, token) => {payload?, created?})');
+
+	// the durable store: a file path → SQLite (crash-safe + cross-restart), a store object → as-is, else in-memory.
+	var store = (typeof opts.store === 'string') ? cp.createSqliteCheckpointStore({ file: opts.store })
+	          : (opts.store || cp.createMemoryCheckpointStore());
+
+	// SOUND-by-default content-memo key (coarse: incidental fields re-key). Host overrides for tighter amortization.
+	var keyOf = opts.keyOf || function ( taskRef, token ) { return digest({ task: taskRef.task, payload: token.payload || {} }); };
+
+	function runFlowOpts( extra ) {
+		return Object.assign({ runTask: opts.runTask, keyOf: keyOf, contract: opts.contract,
+		                       lease: opts.lease, batch: opts.batch, maxSteps: opts.maxSteps }, extra);
+	}
+	function netOf( netOrSpec ) {
+		if ( !looksLikeSpec(netOrSpec) ) return netOrSpec;   // already a compiled net
+		var net = xlate.compileMethod(netOrSpec);
+		if ( d.validate ) xlate.validateNet(net);            // author-time net validation (default ON)
+		return net;
+	}
+
+	return {
+		store: store,
+
+		/** compile a compact select+task+map+reduce spec → a workflow net (+ validate). */
+		compile: function ( spec ) { var net = xlate.compileMethod(spec); if ( d.validate ) xlate.validateNet(net); return net; },
+
+		/** run a workflow: compile-if-spec → ensureRun → inject records → drain to completion. */
+		run: function ( runId, netOrSpec, records, extra ) {
+			var net = netOf(netOrSpec);
+			store.ensureRun(runId, net);
+			if ( records && records.length ) store.inject(runId, records);
+			return interp.runFlow(store, runId, net, runFlowOpts(extra));
+		},
+
+		/** crash-recovery: reclaim orphaned in-flight tokens (rollbackInflight), then drain to completion —
+		 *  no effect lost or duplicated (the memo + fencing token make replay exactly-once). */
+		resume: function ( runId, netOrSpec, extra ) {
+			var net = netOf(netOrSpec);
+			if ( store.rollbackInflight ) store.rollbackInflight(runId);
+			return interp.runFlow(store, runId, net, runFlowOpts(extra));
+		},
+
+		/** the derivation forest + verdict + blame for a run. */
+		audit: function ( runId ) { var a = audit.auditRun(store, runId); return { audit: a, summary: audit.auditSummary(a) }; },
+
+		/** the run's token status counts { ready, leased, done, failed, … }. */
+		stats: function ( runId ) { return store.stats(runId); },
+		/** the run's place marking. */
+		marking: function ( runId ) { return store.marking ? store.marking(runId) : null; },
+
+		close: function () { if ( store.close ) store.close(); }
+	};
+}
+
+module.exports = { createDurableRunner: createDurableRunner };

package/lib/combos/forge.js

@@ -0,0 +1,209 @@
+/*
+ * Copyright 2026 Nathanael Braun — AGPL-3.0-or-later.
+ */
+'use strict';
+/**
+ * forge (M3) — the one-call STOCK FABRICATION pipeline, promoted from the WikiSQL pilot (2026-07-05) into
+ * a reusable brick. Given a class-grouped adapted corpus (each record carries its gold typed-step shape),
+ * it runs, per class: a model FORGE decomposition → an engine TRACE (a typed-step Plan chain) → CRYSTALLIZE
+ * (distil a per-class structural method) → the GOLD-GATE (admit iff consistent ∧ shape==gold ∧ crystallized)
+ * → packStock into a portable `.sgc`. It also emits a VALIDATION DOSSIER — the certification asset: which
+ * dataset, which forge model, the per-class verdicts, the aggregate (0 false admitted, by construction of
+ * the gate), the soundness gates (neg-control + round-trip), and the sha256 the dossier binds.
+ *
+ * SOUNDNESS is carried by the GATE + the dataset oracle, never the model: whatever a small model renders,
+ * only a gold-matching, consistent, crystallized shape enters the stock. YIELD (how many classes admit) is
+ * bounded by model consistency — the soundness-preserving lever is `consistencyVote` (sample N, take the
+ * majority shape; still gold-gated).
+ *
+ *   const r = await forgeStock({ classes, stepEnum, ask, name, version, dataset, negControl:true });
+ *   // r.bundle = the .sgc methods stock ; r.dossier = the validation record ; r.verdict = the pass summary
+ *
+ * The trace-producing engine run lives here (the Plan provider + the typed-step chain are dataset-agnostic);
+ * a dataset supplies only the adapted `classes` (+ optionally a tighter `decompose` for yield).
+ */
+const path = require('path');
+const crypto = require('crypto');
+const Graph = require('../graph');
+const { nextStable } = require('../authoring/supervise.js');
+const { methodTrace } = require('../authoring/mine.js');
+const { createLearningLibrary } = require('./learning-library.js');
+const stockMod = require('../authoring/stock.js');   // goldGate + packStock + consistencyVote + shapeOf
+const packMod = require('../authoring/method-pack.js');
+
+// the dataset-agnostic engine scaffold: a Plan concept that decomposes a task segment into a typed-step chain.
+const TREE = { childConcepts: { Plan: { _id: 'Plan', _name: 'Plan', require: ['Segment', 'taskKind'], ensure: ['!$Planned'], provider: ['Plan::plan'] } } };
+const DECL = { origin: { field: 'originNode' }, target: { field: 'targetNode' } };
+const CFG = { label: 'forge', isMaster: true, autoMount: true, conceptSets: ['common'], bagRefManagers: {}, logLevel: 'error' };
+
+/** the default typed-step forge: deterministic gold-forge when no model (ask=null), else a generic prompt. */
+function makeDefaultDecompose( stepEnum ) {
+	const snap = ( s ) => (stepEnum || []).find(( e ) => String(s || '').toLowerCase().includes(e)) || String(s || '').toLowerCase();
+	return async function ( ask, rec, o ) {
+		o = o || {};
+		if ( !ask ) return o.corrupt ? rec.goldSteps.slice(0, Math.max(1, rec.goldSteps.length - 1)) : rec.goldSteps.slice();
+		const txt = await ask({
+			system: 'Break the query into an ORDERED list of typed steps. Use ONLY these kinds: ' + (stepEnum || []).join(', ')
+				+ '. Reply ONLY JSON: {"steps":["..."]}.',
+			user: String(rec.problem || ''), maxTokens: 80, temperature: o.temperature || 0
+		});
+		try { const m = String(txt).match(/\{[\s\S]*\}/); return (JSON.parse(m ? m[0] : txt).steps || []).map(snap); }
+		catch ( e ) { return []; }
+	};
+}
+
+async function decomposeVoted( voters, rec, decompose ) {
+	const samples = [];
+	for ( const ask of voters ) { const s = await decompose(ask, rec, { temperature: 0.7 }); if ( s.length ) samples.push(s); }
+	return stockMod.consistencyVote(samples).steps;
+}
+
+function makePlanProvider( decompose, ask, meter, plans, voters ) {
+	return { plan: async function ( g, c, scope, argz, cb ) {
+		const base = scope._._id, o = scope._.originNode, t = scope._.targetNode;
+		const rec = plans[scope._.recId];
+		let steps;
+		if ( voters ) { meter.calls += voters.length; steps = await decomposeVoted(voters, rec, decompose); }
+		else if ( ask ) { meter.calls++; steps = await decompose(ask, rec, {}); }
+		else steps = await decompose(null, rec, { corrupt: rec._corrupt });
+		if ( !steps.length ) return cb(null, { $_id: '_parent', Plan: true, Planned: true, planFailed: true });
+		const tpl = [{ $_id: '_parent', Plan: true, Planned: true, nSteps: steps.length }];
+		let prev = o;
+		steps.forEach(function ( kind, i ) {
+			const last = i === steps.length - 1, tnode = last ? t : base + '_m' + i;
+			if ( !last ) tpl.push({ _id: tnode, Node: true, state: kind });
+			tpl.push({ _id: base + '_s' + i, Segment: true, originNode: prev, targetNode: tnode, parentSeg: base, state: kind });
+			prev = tnode;
+		});
+		rec._modelSteps = steps;
+		cb(null, tpl);
+	} };
+}
+
+// run every instance of ONE class through a live graph, capture the trace, crystallize, gold-gate → verdict.
+async function buildClassMethod( sig, recs, ask, meter, voters, decompose ) {
+	const plans = {};
+	recs.forEach(( r, i ) => { r.recId = sig + '#' + i; r.sig = sig; plans[r.recId] = r; });
+	const saved = Graph._providers;
+	Graph._providers = Object.assign({}, Graph._providers, { Plan: makePlanProvider(decompose, ask, meter, plans, voters) });
+	try {
+		const nodes = [], segments = [];
+		recs.forEach(( r, i ) => {
+			nodes.push({ _id: 'S' + i }, { _id: 'G' + i });
+			segments.push({ _id: 'E' + i, originNode: 'S' + i, targetNode: 'G' + i, taskKind: sig, recId: r.recId });
+		});
+		const mt = methodTrace();
+		const g = new Graph({ lastRev: 0, nodes, segments }, CFG, { common: TREE });
+		mt.listen(g);
+		await nextStable(g);
+
+		const lib = createLearningLibrary({ learning: true, signature: ( p ) => ({ structure: { taskKind: p.taskKind }, content: {} }),
+			target: () => null, dispatchFacts: ( p ) => ({ Segment: true, taskKind: p.taskKind }), forge: async () => null });
+		const res = lib.crystallizeFrom(mt.records, { episodeTree: TREE, schemaGraph: g, declaredFrontier: DECL, equivKeys: ['Planned'], idFor: () => 'Crystal_' + sig.replace(/[^A-Za-z0-9]/g, '_') });
+
+		const gate = stockMod.goldGate({ modelShapes: recs.map(( r ) => r._modelSteps || []), goldSteps: recs[0].goldSteps, crystallized: !!res.admitted });
+		return { sig, n: recs.length, modelConsistent: gate.consistent, goldShape: gate.goldShape, modelShape: gate.modelShape || '(none)',
+			crystallized: !!res.admitted, crystalReason: res.reason, goldMatch: gate.goldMatch, admitted: gate.admitted,
+			reason: gate.reason, candidate: gate.admitted ? res.candidate : null };
+	} finally { Graph._providers = saved; }
+}
+
+/**
+ * Fabricate a gold-verified stock + its validation dossier.
+ * @param opts.classes    { sig: [ {problem, goldSteps:[kind]} ] }  — the adapted, class-grouped corpus.
+ * @param opts.stepEnum   the typed-step vocabulary (for the default forge prompt).
+ * @param opts.decompose  optional async (ask, rec, {corrupt,temperature}) -> steps[] (override the default).
+ * @param opts.ask        the model forge (a chat ask). Omit for the deterministic gold-forge (tests).
+ * @param opts.voters     optional array of asks → consistencyVote (the yield lever).
+ * @param opts.name/version/description/dataset  bundle + dossier metadata.
+ * @param opts.negControl add a corrupted-shape neg-control (proves the gate is non-vacuous). Default true.
+ * @returns { results, bundle, dossier, verdict }
+ */
+async function forgeStock( opts ) {
+	opts = opts || {};
+	const classes = opts.classes || {};
+	const decompose = opts.decompose || makeDefaultDecompose(opts.stepEnum);
+	const ask = opts.ask || null;
+	const voters = opts.voters || null;
+	const meter = { calls: 0 };
+	const negControl = opts.negControl !== false;
+
+	const results = [];
+	for ( const sig of Object.keys(classes) ) {
+		const recs = (classes[sig] || []).slice();
+		if ( recs.length < 2 ) continue;   // need ≥2 instances to judge consistency
+		results.push(await buildClassMethod(sig, recs, ask, meter, voters, decompose));
+	}
+
+	const admittedList = results.filter(( v ) => v.admitted && v.candidate ).map(( v ) => ({ sig: v.sig, candidate: v.candidate }));
+	const bundle = stockMod.packStock(admittedList, { name: opts.name || 'stock', version: opts.version || '0.0.0', description: opts.description || '' });
+	const packed = (packMod.unpackMethods(bundle).methods || []).length;
+	// round-trip: a fresh library reloads the .sgc → the methods hydrate (cross-deployment ship-ability).
+	const fresh = createLearningLibrary({ learning: true, signature: ( p ) => ({ structure: { taskKind: p.taskKind }, content: {} }),
+		target: () => null, dispatchFacts: ( p ) => ({ Segment: true, taskKind: p.taskKind }), forge: async () => null });
+	const ld = fresh.load(bundle, { version: opts.version || '0.0.0' });
+	const reloaded = ld.added != null ? ld.added : 0;
+
+	// neg-control: a deliberately-corrupted shape on one class MUST be rejected by the gate (non-vacuity).
+	let neg = { ran: false, rejected: null };
+	if ( negControl ) {
+		// need a MULTI-step gold shape — corrupting a 1-step shape yields the same shape (not a real negative).
+		const sig = Object.keys(classes).find(( s ) => (classes[s] || []).length >= 2 && ((classes[s][0] || {}).goldSteps || []).length >= 2 );
+		if ( sig ) {
+			// the neg-control is a DETERMINISTIC soundness check (corrupt the gold shape) — it uses the
+			// default gold-forge, never the caller's model decompose (which need only handle a real ask).
+			const recs = classes[sig].slice(0, Math.max(2, 3)).map(( r ) => Object.assign({}, r, { _corrupt: true }));
+			const v = await buildClassMethod(sig + '~neg', recs, null, meter, null, makeDefaultDecompose(opts.stepEnum));
+			neg = { ran: true, rejected: v.admitted === false, sig };
+		}
+	}
+
+	const attempted = results.length;
+	const admitted = admittedList.length;
+	const falseAdmitted = results.filter(( v ) => v.admitted && !v.goldMatch ).length;   // 0 by construction of the gate
+	const gates = [
+		{ name: 'gold-gate: 0 false admitted (shape != gold never enters)', pass: falseAdmitted === 0 },
+		{ name: 'stock packs to .sgc and reloads cross-deployment', pass: packed === admitted && reloaded === admitted },
+		negControl ? { name: 'neg-control: a corrupted shape is rejected', pass: neg.rejected === true }
+			: { name: 'at least one class admitted', pass: admitted >= 1 }
+	];
+	const pass = gates.every(( g ) => g.pass );
+
+	const dossier = {
+		forge: 'skynet-sg-forge', generated: opts.now || null,
+		dataset: { name: opts.dataset || opts.name || 'corpus', classesAttempted: attempted },
+		model: { forge: (ask || (voters && voters.length)) ? (opts.modelName || 'embedded model') : 'gold-forge (deterministic)', reasoningBudget: 0, voters: voters ? voters.length : 0, calls: meter.calls },
+		classes: results.map(( v ) => ({ sig: v.sig, n: v.n, modelConsistent: v.modelConsistent, modelShape: v.modelShape,
+			goldShape: v.goldShape, crystallized: v.crystallized, crystalReason: v.crystalReason, goldMatch: v.goldMatch, admitted: v.admitted, reason: v.reason })),
+		summary: { attempted, admitted, falseAdmitted, modelCalls: meter.calls },
+		soundness: { negControl: neg, gates },
+		gates,
+		bundle: { name: bundle.manifest ? bundle.manifest.name : (opts.name || 'stock'), version: opts.version || '0.0.0',
+			methods: packed, sha256: crypto.createHash('sha256').update(JSON.stringify(bundle)).digest('hex') },
+		verdict: { pass }
+	};
+
+	return { results, bundle, dossier, verdict: { attempted, admitted, falseAdmitted, packed, reloaded, pass } };
+}
+
+/** Render the validation dossier as a human-readable markdown certificate (the deliverable a buyer reads). */
+function dossierMarkdown( d ) {
+	const rows = d.classes.map(( c ) => '| `' + c.sig + '` | ' + c.n + ' | `' + c.modelShape + '` | `' + c.goldShape + '` | '
+		+ (c.crystallized ? 'yes' : 'no') + ' | ' + (c.admitted ? '✅ admitted' : '⛔ ' + c.reason) + ' |').join('\n');
+	return [
+		'# Validation dossier — ' + d.bundle.name + '@' + d.bundle.version,
+		'', 'Dataset: **' + d.dataset.name + '**  ·  forge: **' + d.model.forge + '**  ·  model calls: ' + d.model.calls,
+		'Bundle sha256: `' + d.bundle.sha256 + '`', '',
+		'| class | n | model shape | gold shape | crystallized | gold-gate |',
+		'|---|---|---|---|---|---|', rows, '',
+		'## Summary',
+		'- classes attempted: **' + d.summary.attempted + '**',
+		'- admitted (gold-verified): **' + d.summary.admitted + '**',
+		'- FALSE admitted (shape ≠ gold): **' + d.summary.falseAdmitted + '** ' + (d.summary.falseAdmitted === 0 ? '(the gate keeps the stock clean)' : '(!!)'),
+		'', '## Soundness gates',
+		d.gates.map(( g ) => '- ' + (g.pass ? '✅' : '❌') + ' ' + g.name).join('\n'), '',
+		'**Verdict: ' + (d.verdict.pass ? '✅ PASS' : '❌ FAIL') + '** — a gold-verified `.sgc` stock certified from the dataset oracle.'
+	].join('\n');
+}
+
+module.exports = { forgeStock, dossierMarkdown, makeDefaultDecompose, buildClassMethod };

package/lib/combos/index.js

@@ -0,0 +1,86 @@
+/*
+ * 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';
+/**
+ * Combos — THIN, delivered assemblies over the shipped bricks (roadmap P1+, design doc
+ * doc/WIP/2026-07-05-combos-design.md). Each combo composes existing library bricks with the §4
+ * product posture (defaults.js) wired ON; it never adds new logic (a missing piece goes into the
+ * brick, not here) and the underlying bricks stay usable "à nu". Reached lazily via `Graph.combos`.
+ *
+ *   createAppliance         C1 — typed-QA appliance (intake→reason-loop→typed refusal→memo)   [P1]
+ *   createDurableRunner     C2 — durable workflow executor                                    [P4]
+ *   createLearningLibrary   C3 — learning method library                                      [P2-P3]
+ *   createSelfMod           C5 — supervised self-modification (opt-in, guarded)               [P3-bis]
+ *   createProxyCache        C6 — local-first proxy cache / distiller (cover→serve / miss→escalate+enrich)
+ */
+var defaults  = require('./defaults.js');
+var appliance = require('./appliance.js');
+var learning  = require('./learning-library.js');
+var durable   = require('./durable-runner.js');
+var selfmod   = require('./self-mod.js');
+var proxy     = require('./proxy-cache.js');
+var planLoop  = require('./plan-loop.js');
+var mixture   = require('./mixture-serve.js');
+var critique  = require('./critique.js');
+
+module.exports = {
+	resolveComboDefaults : defaults.resolveComboDefaults,
+	buildAsk             : defaults.buildAsk,
+	createAppliance      : appliance.createAppliance,       // C1 — typed-QA appliance
+	createLearningLibrary: learning.createLearningLibrary,  // C3 (P3 COMPLETE) — ladder + crystallizeFrom + learning forge (adaptOrForgeAsync) + blame/credit + .sgc
+	createDurableRunner  : durable.createDurableRunner,     // C2 — durable workflow runner (compile/run/resume/audit)
+
+	// C4 — the reactive KG (the engine's ORIGINAL Use-1: rule-KG + concepts + stabilization + travel/geo).
+	// A trivial preset over Graph.fromDirs (builtins ON = geo + default llm) — the core + fromDirs stay the
+	// real entry, usable "à nu"; this just names the historical capability. Lazy-required (avoids a load-time
+	// cycle: lib/index.js → the Graph.combos getter → here → lib/index.js).
+	reactiveKG: function ( opts ) { return require('../index.js').fromDirs(Object.assign({ builtins: true }, opts || {})); },
+
+	// C5 — supervised self-modification (OPT-IN, guarded: author() requires a proposer; rollbackTo is the
+	// reversibility guarantee). Edits the LIVE rules — a host builds it explicitly, never a default.
+	createSelfMod: selfmod.createSelfMod,
+
+	// C6 — local-first proxy cache / distiller: serve a query from the minimal local stock when COVERED,
+	// escalate to the frontier model on a miss and enrich the stock in passing. The local side never
+	// fabricates (0 hallucination); a miss escalates (no false neg); anti-drift + .sgc on demand. A thin
+	// preset over createLearningLibrary (forge = the frontier ask).
+	createProxyCache: proxy.createProxyCache,
+	makeFrontierAsk : proxy.makeFrontierAsk,   // wire a chat backend (embedded gguf / endpoint) as the frontier ground-truth
+	makeLocalCoverage: proxy.makeLocalCoverage, // wire a small local model as the semantic-key + coverage-check judge
+	makeTypedIntakeKey: proxy.makeTypedIntakeKey, // the à-nu typed Intake front door: prose → a DECLARED-vocab class key (distillation par-classe; untyped → exact-key, never a false class)
+
+	// C7 — the hierarchical PLAN LOOP: a task longer than the context is decomposed into typed leaves (each sees
+	// only a projected digest), served by the cost ladder (escalation LOAD-BEARING — kill-gate R1), driven to a
+	// BALANCED fixpoint (rebalance brick E2∘E1∘E3∘E4), and reassembled with checkCompose. decompose + serveLeaf
+	// are INJECTED (typed-loop + createProxyCache.solve in production) so the combo stays usable "à nu".
+	createPlanLoop: planLoop.createPlanLoop,
+
+	// C8 — the MIXTURE-RUNTIME server: a cheap local model ORIENTED by a forged certified stock, with
+	// escalation to a bigger tier. NOTE: the runtime CROSS-AGREEMENT trust tier is REFUTED at scale
+	// (precision 25-42 % at N=201 — keep fail-closed; see mixture-serve.js header erratum). What holds:
+	// orientation lifts the raw score; 0-false lives at ADMISSION (the forge), never as a runtime badge.
+	// small/big/proposeMenu/predict are INJECTED.
+	createMixtureServe: mixture.createMixtureServe,
+	makeSurfaceDispatch: mixture.makeSurfaceDispatch,  // build proposeMenu+predict from a labelled anchor corpus (surface k-NN)
+
+	// C9 — the external CRITICAL MIND: declared viewpoints established through a witness gate over a
+	// statement pool, anchored generation of the MISSING theses (0-fabrication), a typed LEDGER as the
+	// deliverable, and a certification-aware verdict (mechanical only at the measured margin bound;
+	// below → counts + honest UNDECIDED). ask is INJECTED; frame statuses FREE/MATERIAL/DECLARED announced.
+	createCriticalMind: critique.createCriticalMind
+};