skynet-graph 1.2.0

package/lib/authoring/dag-decompose.js

@@ -0,0 +1,256 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * dag-decompose — the model-driven TYPED DAG DECOMPOSE (ZERO-CORE, host-side). The upstream half of the context
+ * projection: it turns a task into the `needs`/`produces` DAG that `context-project.js` + `plan-loop.js` execute.
+ * Realizes the study `WIP/2026-07-08-etude-decoupage-de-tache.md` §6.1: the decompose PROMPT + GRAMMAR-CONSTRAINED
+ * decoding force a well-formed typed dataflow graph, and the engine's offline guards (guardPlan cycle/coverage,
+ * rebalance) validate the CONTENT — "propose freely, validate hard, refuse cleanly".
+ *
+ * Where the sibling reactive `typed-loop` chains its steps SEQUENTIALLY (originNode = the previous step's target),
+ * this emits an explicit producer→consumer DAG: each part declares WHAT IT PRODUCES (a typed key) and WHAT IT NEEDS
+ * (other parts' produced keys). That is the class matching our projection (LLMCompiler `$1,$2` / ReWOO `#E` /
+ * HuggingGPT `<resource-N>`), plus bounded per-node context.
+ *
+ * THE GRAMMAR IS THE K1 BARRIER (the crown jewel, per typed-loop): the output is decoded under a JSON Schema, so a
+ * small model CANNOT emit a malformed part — `stepKind` snaps onto a CLOSED enum (fail-closed via `canonValue`), the
+ * shape is guaranteed. The grammar guarantees FORMAT, not correct dependency CONTENT — guardPlan/rebalance do that.
+ *
+ *   const { makeDagDecompose } = require('skynet-graph/lib/authoring/dag-decompose');
+ *   const decompose = makeDagDecompose({ ask: makeLocalAsk({ modelPath }), stepKinds: ['retrieve','compute','compare','summarize'] });
+ *   const loop = createPlanLoop({ decompose, serveLeaf });   // the projection consumes it directly
+ *   // à nu:  const leaves = await decompose(task);  const roadmap = leavesToRoadmap(leaves);
+ *
+ * @param opts.ask       async ({ system, user, maxTokens, temperature, grammar }) => string  — a grammar-capable
+ *                       chat backend (makeLocalAsk supports `grammar:{jsonSchema}`). REQUIRED.
+ * @param opts.stepKinds closed enum of step TYPES (the K1-discriminating class) — canon-snapped, fail-closed.
+ * @param opts.maxSteps  cap on the number of parts (default 8).
+ * @param opts.minSteps  granularity floor: a split below it triggers ONE bounded re-ask with a coarseness blame
+ *                       (gap iii — anti 1-step collapse); still under → the larger split is kept (honest degrade).
+ * @param opts.givenKeys the task's given keys (givens.js): arms the cited-never-produced validation — a "needs"
+ *                       key that no part produces and that is not a given joins the same bounded re-ask blame.
+ * @param opts.onReask   observer ({task,firstCount,minSteps,uncovered}) fired when the validation re-ask triggers.
+ * @param opts.system    override the decompose system prompt.
+ * @param opts.hint      an optional one-line orientation appended to the system prompt (the §6.2 per-archetype steer,
+ *                       e.g. "The parts are INDEPENDENT — emit no needs." for a fan-out / extraction prompt).
+ */
+const { canonValue } = require('../providers/canonicalize.js');
+
+// the study §6.1 contract, as the system prompt (imperative, the 5 hard rules that encode invariants 1-3,5,8).
+const DECOMPOSE_SYSTEM =
+	'You are a TASK DECOMPOSER for a bounded-context execution engine. Split the task into parts and output ONLY a ' +
+	'JSON array. Each part = {"produces": a short snake_case typed key naming the ARTIFACT this part outputs, ' +
+	'"stepKind": the step TYPE, "instruction": one imperative sentence, "needs": the list of OTHER parts\' "produces" ' +
+	'keys whose output this part consumes}. HARD RULES (the engine rejects a split that breaks them): ' +
+	'(1) ACYCLIC — no part may need a part that (transitively) needs it. ' +
+	'(2) COVERED — every key in "needs" must be some other part\'s "produces", or a GIVEN key listed in the task. ' +
+	'(3) THIN — need as FEW parts as possible; produce exactly ONE key. ' +
+	'(4) INDEPENDENT — if two parts do not depend on each other, do NOT invent a dependency (they run in parallel). ' +
+	'(5) TYPED — "produces"/"needs" are keys, never sentences. Decompose only as far as needed; a directly-answerable part is a leaf. ' +
+	'(6) GIVENS — when the task lists GIVENS (typed keys, e.g. g1_price=5), a part that uses a base fact MUST cite its ' +
+	'given key in "needs" and MUST NOT restate that number in the instruction (the engine injects the value). ' +
+	'(7) SELF-CONTAINED — a base fact NOT listed in GIVENS (a quantity spelled in words, a fraction, common knowledge ' +
+	'like 52 weeks per year) MUST be written explicitly AS A NUMBER in the instruction of every part that uses it; ' +
+	'never reference it as a key and never assume the executor saw the original task.';
+
+// the METHOD-SLOT / higher-order need (roadmap §5(a)): a part may declare it is a LOOP whose behavioural hole (the
+// body) is filled by a DISPATCHED sub-method applied over items. The combinator vocabulary is CLOSED to the three the
+// LLM can legitimately emit; `fold` is EXCLUDED on purpose — a reducer/init is arbitrary host code, never LLM-emittable
+// (roadmap §5(a) confront: a `combinator:'fold'` from the grammar would crash `results.reduce(undefined,undefined)`).
+const SLOT_COMBINATORS = ['map', 'all', 'any'];
+
+// the JSON-Schema grammar: a bounded array of typed parts; `stepKind` on the CLOSED enum (the decode-level K1 barrier).
+// A part may OPTIONALLY carry a `slot` (the method-slot): `over` = a produced-key whose value yields the items, `body`
+// = the dispatched slot-filler on the CLOSED `bodyKinds` enum (same K1 barrier as stepKind), `combinator` closed.
+function decomposeSchema( stepKinds, maxSteps, bodyKinds ) {
+	const kind = (stepKinds && stepKinds.length) ? { type: 'string', enum: stepKinds } : { type: 'string' };
+	const body = (bodyKinds && bodyKinds.length) ? { type: 'string', enum: bodyKinds } : { type: 'string' };
+	return {
+		type: 'array', minItems: 1, maxItems: maxSteps,
+		items: {
+			type: 'object',
+			properties: {
+				produces:    { type: 'string' },
+				stepKind:    kind,
+				instruction: { type: 'string' },
+				needs:       { type: 'array', items: { type: 'string' } },
+				slot:        { type: 'object', properties: {                    // OPTIONAL — present ⇒ this part is a loop
+					over:       { type: 'string' },
+					body:       body,
+					combinator: { type: 'string', enum: SLOT_COMBINATORS }
+				}, required: ['over', 'body'] }
+			},
+			required: ['produces', 'stepKind', 'instruction', 'needs']          // slot NOT required → plain parts unchanged
+		}
+	};
+}
+
+// parse a raw `slot` fail-closed: `over` cleaned to a key; `body` snapped onto bodyKinds (a MISS drops the whole slot —
+// never mount an unconstrained hole); `combinator` snapped onto SLOT_COMBINATORS (a MISS → the safe default `map`).
+// Returns null (⇒ degrade to a PLAIN leaf) when the slot is malformed / the body is out-of-vocab.
+function parseSlot( raw, bodyKinds ) {
+	if ( !raw || typeof raw !== 'object' ) return null;
+	const over = keyOf(raw.over);
+	if ( !over ) return null;                                                   // a loop with no items source is malformed
+	const bsnap = (bodyKinds && bodyKinds.length) ? canonValue(raw.body, { enum: bodyKinds }) : { value: raw.body };
+	if ( bsnap.miss || raw.body == null || raw.body === '' ) return null;       // body∉vocab → fail-closed DROP (plain leaf)
+	const csnap = canonValue(raw.combinator, { enum: SLOT_COMBINATORS, default: 'map' });
+	const slot = { over: over, body: bsnap.value, combinator: csnap.miss ? 'map' : csnap.value };
+	if ( csnap.miss && raw.combinator != null && raw.combinator !== '' ) { slot.combinatorMiss = true; slot.combinatorRaw = String(raw.combinator); }
+	return slot;
+}
+
+// clean a produced key to a stable typed id (snake_case-ish, the projection's fusion/write key).
+function keyOf( raw ) { return String(raw == null ? '' : raw).trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'part'; }
+
+function parseSteps( out ) {
+	if ( Array.isArray(out) ) return out;
+	try { const v = JSON.parse(out); return Array.isArray(v) ? v : (v && Array.isArray(v.parts) ? v.parts : []); }
+	catch ( _e ) {                                                    // defensive (grammar-constrained output IS valid JSON; this covers a raw/ungrammared backend)
+		const m = String(out).match(/\[[\s\S]*\]/); if ( m ) { try { return JSON.parse(m[0]); } catch ( _e2 ) { /* fall through */ } }
+		return [];
+	}
+}
+
+/**
+ * makeDagDecompose(opts) → async decompose(task, ctx) -> [{ id, request:{id,kind}, nl, readsExtra:[keys] }]
+ * The returned leaf list is the plan-loop DECOMPOSE contract: `request.id` is the produced key (leafWrites), and
+ * `readsExtra` are the produced keys it consumes (the projection derives needs = readsExtra ∩ produced). Fail-closed:
+ * an out-of-vocab `stepKind` rides `kindMiss:true` + the raw surface; a `needs` self-reference is dropped.
+ */
+function makeDagDecompose( opts ) {
+	opts = opts || {};
+	if ( typeof opts.ask !== 'function' ) throw new Error('makeDagDecompose needs opts.ask({system,user,grammar}) -> string');
+	const stepKinds = opts.stepKinds || [];
+	const bodyKinds = opts.bodyKinds || [];
+	const maxSteps  = opts.maxSteps || 8;
+	const minSteps  = opts.minSteps || 0;
+	const system    = (opts.system || DECOMPOSE_SYSTEM) + (opts.hint ? ' ' + opts.hint : '');
+	const schema    = decomposeSchema(stepKinds, maxSteps, bodyKinds);
+
+	const givenKeys = (opts.givenKeys || []).map(keyOf);
+
+	// the OFFLINE plan validation (gap iii + the P0-critique symmetric): granularity floor + cited-never-produced
+	// keys (a need that is neither some part's produces nor a given = a phantom the projection would drop → the
+	// consuming leaf computes blind). Both feed ONE bounded re-ask with an explicit blame.
+	function problemsOf( raw ) {
+		const produced = new Set(raw.map(( s ) => keyOf(s.produces) ));
+		const uncovered = [];
+		for ( const s of raw ) for ( const n of (Array.isArray(s.needs) ? s.needs : []).map(keyOf) )
+			if ( n && !produced.has(n) && givenKeys.indexOf(n) < 0 && n !== keyOf(s.produces) ) uncovered.push(n);
+		return { tooCoarse: !!(minSteps && raw.length < minSteps), uncovered: Array.from(new Set(uncovered)) };
+	}
+
+	return async function decompose( task, ctx ) {
+		const user = typeof task === 'string' ? task : ((ctx && ctx.statement) || JSON.stringify(task));
+		const askOnce = ( sys ) => opts.ask({ system: sys, user: user, grammar: { jsonSchema: schema }, maxTokens: opts.maxTokens || 700, temperature: 0 });
+		let raw = parseSteps(await askOnce(system)).slice(0, maxSteps);
+		let probs = problemsOf(raw);
+		// ONE bounded re-ask on a validation miss; keep the attempt with fewer uncovered keys (then finer). The check
+		// only has teeth when the host declares its vocabulary: no givenKeys ⇒ only the granularity floor fires.
+		if ( probs.tooCoarse || (givenKeys.length && probs.uncovered.length) ) {
+			if ( opts.onReask ) opts.onReask({ task: user, firstCount: raw.length, minSteps: minSteps, uncovered: probs.uncovered });
+			const blame = ' PREVIOUS ATTEMPT REJECTED:'
+				+ (probs.tooCoarse ? ' only ' + raw.length + ' part(s) — TOO COARSE, emit AT LEAST ' + minSteps + ' parts, each ONE small operation, chained via "needs".' : '')
+				+ (givenKeys.length && probs.uncovered.length ? ' these "needs" keys are produced by NO part and are NOT givens: ['
+					+ probs.uncovered.join(', ') + '] — either add a part that produces each, cite a listed given key, or restate the fact as a number in the instruction (rule 7).' : '');
+			const raw2 = parseSteps(await askOnce(system + blame)).slice(0, maxSteps);
+			const probs2 = problemsOf(raw2);
+			const better = probs2.uncovered.length < probs.uncovered.length
+				|| (probs2.uncovered.length === probs.uncovered.length && (probs.tooCoarse && !probs2.tooCoarse))
+				|| (probs2.uncovered.length === probs.uncovered.length && probs2.tooCoarse === probs.tooCoarse && raw2.length > raw.length);
+			if ( better ) { raw = raw2; probs = probs2; }
+		}
+		const seen = Object.create(null);
+		const leaves = [];
+		for ( const s of raw ) {
+			let key = keyOf(s.produces);
+			while ( seen[key] ) key = key + '_2';                    // uniquify a duplicated produced key (rebalance would dedupe identical, but a distinct write key keeps needs unambiguous)
+			seen[key] = true;
+			const snap = stepKinds.length ? canonValue(s.stepKind, { enum: stepKinds }) : { value: s.stepKind };
+			const request = { id: key, kind: snap.miss ? null : snap.value };
+			if ( snap.miss ) { request.kindMiss = true; request.kindRaw = String(s.stepKind); }
+			const slot = parseSlot(s.slot, bodyKinds);                   // the method-slot (higher-order need), fail-closed
+			if ( slot ) request.slot = slot;
+			const needs = (Array.isArray(s.needs) ? s.needs : []).map(keyOf).filter(( n ) => n !== key );
+			if ( slot && slot.over !== key && !needs.includes(slot.over) ) needs.push(slot.over);   // `over` rides the needs channel (resolution+gate+coverage)
+			leaves.push({ id: 'n_' + key, request: request, nl: String(s.instruction == null ? '' : s.instruction), readsExtra: needs });
+		}
+		if ( !leaves.length )                                        // never crash the loop: degrade to a single atomic leaf (the whole task)
+			leaves.push({ id: 'n_task', request: { id: 'task', kind: null }, nl: user, readsExtra: [] });
+		return leaves;
+	};
+}
+
+// leaves → a context-project roadmap (à-nu use of the projection directly, without plan-loop). produces = the write
+// key; needs = readsExtra restricted to keys some leaf produces OR a given key (givens = { key: value } — the
+// projection pre-satisfies those; any other external readsExtra is context, not a gate). ──
+function leavesToRoadmap( leaves, givens ) {
+	givens = givens || {};
+	const produced = new Set(leaves.map(( l ) => l.request && l.request.id ).filter(Boolean));
+	return leaves.map(( l ) => {
+		const step = { id: l.request.id, produces: l.request.id, nl: l.nl,
+			needs: (l.readsExtra || []).filter(( n ) => produced.has(n) || n in givens ) };
+		if ( l.request.slot ) step.slot = l.request.slot;                // carry the method-slot through to the projection
+		return step;
+	});
+}
+
+// ── the ARCHETYPE ROUTER (study §6.2/§6.3): type-of-prompt → best decomposition organization. A prompt is first
+// classified into a decomposition ARCHETYPE (grammar-constrained, closed enum, fail-closed), then the matching
+// per-archetype ORIENTATION (`hint`) steers `makeDagDecompose` toward the structure that archetype justifies
+// (chain / fan-out / layered DAG / fan-out+merge / general DAG). The type→scheme map is a well-motivated PRIOR
+// (the study's caveat: not a proven law — same-model inflation, thin cross-model evidence); this wires the DECISION
+// mechanism, not a claim of optimality. ──
+const ARCHETYPES = ['sequential', 'extraction', 'multihop', 'aggregate', 'planning'];
+const ARCHETYPE_HINTS = {
+	sequential: 'This is SEQUENTIAL reasoning (each step feeds the next): emit a CHAIN — each part needs AT MOST the single previous part.',
+	extraction: 'This is INDEPENDENT extraction/transformation of many items: emit parts with EMPTY "needs" (a pure fan-out); add one final aggregating part only if a single combined output is required.',
+	multihop:   'This is MULTI-HOP gathering: emit the independent gather parts in ONE parallel layer (no "needs" among them), then a SINGLE combine part that needs them.',
+	aggregate:  'This is DECOMPOSE-then-AGGREGATE: emit the independent producer parts (empty "needs"), then EXACTLY ONE final part whose "needs" lists ALL of them and merges them.',
+	planning:   'Emit the dependency DAG directly: each part references by key the outputs it consumes; keep independent parts free of needs so they run in parallel.',
+};
+function detectSystem( archetypes ) {
+	return 'Classify the task into EXACTLY ONE decomposition archetype and reply with ONLY the label. Labels: ' +
+		archetypes.join(' | ') + '. Guidance — sequential: each step strictly feeds the next; extraction: many ' +
+		'independent items of the same type; multihop: gather from several sources then combine; aggregate: produce ' +
+		'independent pieces then merge into one; planning: a general step/tool plan with mixed dependencies.';
+}
+
+/**
+ * makeArchetypeRouter(opts) → { detect(task), route(task) -> {archetype,hint,leaves}, decompose(task) -> leaves }
+ * `decompose` is the plan-loop seam (detect → steer → emit the DAG). `route` also surfaces the detected archetype.
+ * @param opts.ask       grammar-capable ask (REQUIRED). @param opts.stepKinds closed step-kind enum (passed through).
+ * @param opts.archetypes / opts.hints  override the archetype vocabulary / their orientation lines (usable à nu).
+ * @param opts.fallback  archetype used when detection misses (default 'planning' — the general DAG, always safe).
+ */
+function makeArchetypeRouter( opts ) {
+	opts = opts || {};
+	if ( typeof opts.ask !== 'function' ) throw new Error('makeArchetypeRouter needs opts.ask({system,user,grammar}) -> string');
+	const archetypes = opts.archetypes || ARCHETYPES;
+	const hints      = opts.hints || ARCHETYPE_HINTS;
+	const fallback   = opts.fallback || (archetypes.indexOf('planning') !== -1 ? 'planning' : archetypes[0]);
+
+	async function detect( task, ctx ) {
+		const user = typeof task === 'string' ? task : ((ctx && ctx.statement) || JSON.stringify(task));
+		const out = await opts.ask({ system: detectSystem(archetypes), user: user, grammar: { jsonSchema: { type: 'string', enum: archetypes } }, maxTokens: 8, temperature: 0 });
+		let raw; try { raw = JSON.parse(out); } catch ( _e ) { raw = String(out).trim().replace(/^["']|["']$/g, ''); }
+		const snap = canonValue(raw, { enum: archetypes, default: fallback });   // fail-closed to the safe default
+		return snap.miss ? fallback : snap.value;
+	}
+	async function route( task, ctx ) {
+		const archetype = await detect(task, ctx);
+		const hint = hints[archetype] || '';
+		const leaves = await makeDagDecompose({ ask: opts.ask, stepKinds: opts.stepKinds, maxSteps: opts.maxSteps, hint: hint })(task, ctx);
+		return { archetype: archetype, hint: hint, leaves: leaves };
+	}
+	async function decompose( task, ctx ) { return (await route(task, ctx)).leaves; }
+	return { detect: detect, route: route, decompose: decompose, archetypes: archetypes, hints: hints };
+}
+
+module.exports = { makeDagDecompose, makeArchetypeRouter, leavesToRoadmap, decomposeSchema, parseSlot, SLOT_COMBINATORS, DECOMPOSE_SYSTEM, ARCHETYPES, ARCHETYPE_HINTS, keyOf };

package/lib/authoring/dataset-adapter.js

@@ -0,0 +1,253 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * dataset-adapter — the PROMOTED dataset-adapter brick (roadmap-use-cases: "promouvoir la brique dataset-adapter
+ * en lib"). Turns a LABELLED query dataset (WikiSQL, a semantic-parsing set, a client corpus) into the neutral
+ * shape the typed-grammar STOCK pipeline consumes, so "plusieurs datasets" is one registry away and their
+ * distilled `.sgc` grammars are COMPARABLE (same explorer metrics on each).
+ *
+ * PURE + engine-free (an optional `fs` read for jsonl; no Graph, no model). An adapter maps one record →
+ *   {
+ *     query:     string        — the NL query (→ the model extractor / the frontier answer)
+ *     context:   object|null   — typed context for the extractor prompt (e.g. {columns:[...]}), or null
+ *     klass:     string        — the COVERAGE CLASS key = signature.structure (ONE method distilled per class)
+ *     goldShape: string[]      — the gold typed decomposition = the ORACLE (goldGate admits iff model==gold)
+ *   }
+ * The class is the typed signature the proxy dispatches on (one frontier answer covers the class); the goldShape
+ * is the gold-gate oracle (0-false stock). Same two fields ⇒ any dataset flows the SAME pipeline + SAME metrics.
+ *
+ *   const { getAdapter, loadDataset } = require('skynet-graph/lib/authoring/dataset-adapter');
+ *   const byClass = loadDataset(getAdapter('wikisql'), { file, aux:{tablesFile}, perClass:4 });
+ *
+ * An adapter: { name, stepEnum:[kinds], adapt(record, aux) -> mapped|null }. Register more with registerAdapter.
+ */
+
+var _adapters = {};
+
+/** register a dataset adapter (name → {name, stepEnum, adapt}). Later registration overrides. */
+function registerAdapter( adapter ) {
+	if ( !adapter || !adapter.name || typeof adapter.adapt !== 'function' ) throw new Error('registerAdapter needs { name, adapt(record, aux) }');
+	_adapters[adapter.name] = adapter;
+	return adapter;
+}
+/** fetch a registered adapter by name (throws if unknown). */
+function getAdapter( name ) {
+	if ( !_adapters[name] ) throw new Error('no dataset adapter "' + name + '" (registered: ' + Object.keys(_adapters).join(', ') + ')');
+	return _adapters[name];
+}
+/** list registered adapter names. */
+function listAdapters() { return Object.keys(_adapters); }
+
+/**
+ * Group a dataset's records by their coverage CLASS (the typed signature). Reads a jsonl file (or takes an
+ * in-memory `records` array), maps each with the adapter, drops nulls, and buckets by `klass`.
+ * @param adapter        a registered/inline adapter { adapt(record, aux) }.
+ * @param opts.file      jsonl path (one JSON record per line) — OR opts.records (an array, no fs).
+ * @param opts.aux       adapter-specific side data (e.g. {tables} / {tablesFile}); passed to adapt(record, aux).
+ * @param opts.classes   optional string[] whitelist of class keys to keep (else all).
+ * @param opts.perClass  optional cap on kept instances PER class (the extra are dropped; the caller slices held-out).
+ * @returns { [klass]: [ {query,context,klass,goldShape}, … ] }
+ */
+function loadDataset( adapter, opts ) {
+	opts = opts || {};
+	var aux = resolveAux(adapter, opts.aux);
+	var records = opts.records || readJsonl(opts.file);
+	var byClass = {};
+	for ( var i = 0; i < records.length; i++ ) {
+		var m = adapter.adapt(records[i], aux);
+		if ( !m || !m.klass || !Array.isArray(m.goldShape) ) continue;
+		if ( opts.classes && opts.classes.indexOf(m.klass) < 0 ) continue;
+		var b = (byClass[m.klass] = byClass[m.klass] || []);
+		if ( opts.perClass != null && b.length >= opts.perClass ) continue;
+		b.push(m);
+	}
+	return byClass;
+}
+
+// an adapter may declare aux it needs loaded from a file (e.g. WikiSQL's tables). Resolve a *File → parsed.
+function resolveAux( adapter, aux ) {
+	aux = aux || {};
+	if ( typeof adapter.resolveAux === 'function' ) return adapter.resolveAux(aux);
+	return aux;
+}
+
+function readJsonl( file ) {
+	if ( !file ) return [];
+	var fs = require('fs');
+	var out = [], lines = fs.readFileSync(file, 'utf8').trim().split('\n');
+	for ( var i = 0; i < lines.length; i++ ) { var l = lines[i].trim(); if ( l ) try { out.push(JSON.parse(l)); } catch ( e ) {} }
+	return out;
+}
+
+// ── built-in: WikiSQL (github salesforce/WikiSQL). Its `sql:{sel,agg,conds}` is a PRE-TYPED decomposition →
+//    the gold oracle with NO SQL parsing. class = {agg}|{nConds}; method shape = nConds×filter [+aggregate] +select.
+var WIKISQL_AGG = ['none', 'max', 'min', 'count', 'sum', 'avg'];
+function wikisqlGoldShape( sql ) {
+	var steps = [];
+	for ( var i = 0; i < (sql.conds || []).length; i++ ) steps.push('filter');
+	if ( sql.agg !== 0 ) steps.push('aggregate');
+	steps.push('select');
+	return steps;
+}
+registerAdapter({
+	name: 'wikisql',
+	stepEnum: ['filter', 'aggregate', 'select'],
+	// aux: { tables } (id→table) OR { tablesFile } (a jsonl of {id,header}); resolveAux loads the file once.
+	resolveAux: function ( aux ) {
+		if ( aux.tables ) return aux;
+		if ( aux.tablesFile ) { var t = {}; readJsonl(aux.tablesFile).forEach(function ( x ) { t[x.id] = x; }); return { tables: t }; }
+		return { tables: {} };
+	},
+	adapt: function ( r, aux ) {
+		if ( !r || !r.sql || !Array.isArray(r.sql.conds) ) return null;
+		var agg = WIKISQL_AGG[r.sql.agg] || 'none';
+		return {
+			query: r.question,
+			context: { columns: ((aux.tables[r.table_id] || {}).header) || [] },
+			klass: agg + '|' + r.sql.conds.length,          // the coverage class = {agg, nConds}
+			goldShape: wikisqlGoldShape(r.sql)
+		};
+	}
+});
+
+// ── built-in: Spider (Yale text-to-SQL). Unlike WikiSQL, the HF release ships only the raw gold SQL string
+//    (no pre-parsed AST), so this adapter is a SMALL structural SQL analyzer over the gold `query` — the typed
+//    decomposition is a deterministic function of the gold SQL (parsing the gold IS reading the oracle, the same
+//    way Spider's own evaluation parses gold). Its POINT vs WikiSQL: Spider is RECURSIVE — a WHERE operand can be
+//    a nested `(SELECT …)` subquery, and two full queries combine via INTERSECT/UNION/EXCEPT. The subquery case is
+//    exactly a graft-into-slot (blendMethods) — a nested query's method = a BLEND of the outer skeleton + the
+//    subquery grammar (the "concepts combine" payoff). Set-ops are a SECOND, binary top-level composition (noted,
+//    but out of blendMethods' scope). stepEnum = the typed step kinds; nesting is depth (not a step token).
+var SPIDER_STEPS = ['join', 'filter', 'group', 'having', 'aggregate', 'order', 'select'];
+
+// scan a lowercased SQL string tracking paren depth + single-quoted strings; call `at(i, ch, depth)` per char.
+function scanSQL( s, at ) {
+	var depth = 0, q = false;
+	for ( var i = 0; i < s.length; i++ ) {
+		var ch = s[i];
+		if ( ch === "'" ) { q = !q; continue; }
+		if ( q ) continue;
+		if ( ch === '(' ) { at(i, ch, depth); depth++; continue; }
+		if ( ch === ')' ) { depth--; at(i, ch, depth); continue; }
+		at(i, ch, depth);
+	}
+}
+// first index of any needle at paren-depth 0 (outside quotes); returns { index, token } or null.
+function findTop( s, needles ) {
+	var hit = null;
+	scanSQL(s, function ( i, ch, depth ) {
+		if ( hit || depth !== 0 ) return;
+		for ( var k = 0; k < needles.length; k++ ) if ( s.startsWith(needles[k], i) ) { hit = { index: i, token: needles[k].trim() }; return; }
+	});
+	return hit;
+}
+// count occurrences of a needle at paren-depth 0.
+function countTop( s, needle ) {
+	var n = 0;
+	scanSQL(s, function ( i, ch, depth ) { if ( depth === 0 && s.startsWith(needle, i) ) n++; });
+	return n;
+}
+// the balanced-paren substring of the FIRST `(select …)` (original case), or null. Used to pull the subquery
+// for the blend cell (the donor grammar). Scans the lowercased copy for the marker, cuts from the original.
+function firstSubquery( orig, s ) {
+	var start = -1;
+	scanSQL(s, function ( i, ch, depth ) {
+		if ( start >= 0 || ch !== '(' ) return;
+		if ( /^\(\s*select\b/.test(s.slice(i, i + 12)) ) start = i;
+	});
+	if ( start < 0 ) return null;
+	var d = 0, end = -1;
+	for ( var i = start; i < orig.length; i++ ) { if ( orig[i] === '(' ) d++; else if ( orig[i] === ')' ) { d--; if ( d === 0 ) { end = i; break; } } }
+	return end > start ? orig.slice(start + 1, end).trim() : null;
+}
+// MASK each balanced `(select …)` subquery to `(?)` so the OUTER structure is analyzed with the subquery as an
+// opaque operand (else the subquery's own agg/join/group would pollute the outer skeleton — the blend host must be
+// the clean outer shape, the subquery its own donor grammar). Operates on a lowercased string.
+function maskSubqueries( s ) {
+	var out = '', i = 0;
+	while ( i < s.length ) {
+		if ( s[i] === '(' && /^\(\s*select\b/.test(s.slice(i, i + 12)) ) {
+			var d = 0, j = i;
+			for ( ; j < s.length; j++ ) { if ( s[j] === '(' ) d++; else if ( s[j] === ')' ) { d--; if ( d === 0 ) { j++; break; } } }
+			out += '(?)'; i = j;
+		} else { out += s[i]; i++; }
+	}
+	return out;
+}
+
+// analyze ONE select block (no top-level set-op): counts + flags of the OUTER query (subqueries masked out).
+function analyzeSelect( orig ) {
+	var raw = orig.toLowerCase();
+	var s = maskSubqueries(raw);                         // outer structure sees the subquery as an opaque operand
+	var joins = countTop(s, ' join ');
+	var whereAt = findTop(s, [' where ']);
+	var filters = 0, nested = false;
+	if ( whereAt ) {
+		// the WHERE clause runs to the first top-level group by / order by / having / end.
+		var rest = s.slice(whereAt.index + 7);
+		var endAt = findTop(rest, [' group by ', ' order by ', ' having ']);
+		var where = endAt ? rest.slice(0, endAt.index) : rest;
+		// conditions = top-level ` and `/` or `-separated fragments (a subquery is masked → its ANDs don't count).
+		var conds = 1;
+		scanSQL(where, function ( i, ch, depth ) { if ( depth === 0 && (where.startsWith(' and ', i) || where.startsWith(' or ', i)) ) conds++; });
+		filters = conds;
+		nested = where.indexOf('(?)') >= 0;              // a subquery operand appeared in a WHERE condition
+	}
+	return {
+		joins: joins, filters: filters,
+		group: findTop(s, [' group by ']) != null,
+		having: findTop(s, [' having ']) != null,
+		agg: /\b(count|sum|avg|min|max)\s*\(/.test(s),   // masked → outer aggregates only
+		order: findTop(s, [' order by ']) != null,
+		nested: nested, subquery: nested ? firstSubquery(orig, raw) : null
+	};
+}
+
+// the ordered typed decomposition of the OUTER query (subquery stays inside its filter operand → depth, not a step).
+function spiderGoldShape( a ) {
+	var steps = [];
+	for ( var i = 0; i < a.joins; i++ ) steps.push('join');
+	for ( var j = 0; j < a.filters; j++ ) steps.push('filter');
+	if ( a.group ) steps.push('group');
+	if ( a.having ) steps.push('having');
+	if ( a.agg ) steps.push('aggregate');
+	if ( a.order ) steps.push('order');
+	steps.push('select');
+	return steps;
+}
+
+// analyze a full gold SQL: detect a top-level set-op, else the single select. Returns { …counts, setop, subquery }.
+function analyzeSpiderSQL( query ) {
+	var orig = String(query || '').replace(/\s+/g, ' ').trim();
+	var s = orig.toLowerCase();
+	var so = findTop(s, [' intersect ', ' union ', ' except ']);
+	if ( so ) { var left = analyzeSelect(orig.slice(0, so.index)); left.setop = so.token; return left; }
+	var a = analyzeSelect(orig); a.setop = null; return a;
+}
+
+registerAdapter({
+	name: 'spider',
+	stepEnum: SPIDER_STEPS,
+	analyze: analyzeSpiderSQL,                            // exposed for the blend cell (outer skeleton + subquery)
+	goldShapeOf: spiderGoldShape,
+	adapt: function ( r ) {
+		if ( !r || !r.query ) return null;
+		var a = analyzeSpiderSQL(r.query);
+		var shape = spiderGoldShape(a);
+		// the coverage class = the outer shape + a nesting flag + a set-op tag (both make a distinct, VISIBLE class).
+		var klass = shape.join('>') + (a.nested ? '|n' : '') + (a.setop ? '|' + a.setop : '');
+		return {
+			query: r.question, context: { db_id: r.db_id },
+			klass: klass, goldShape: shape,
+			sql: r.query, nested: a.nested, subquery: a.subquery, setop: a.setop   // extras for the blend cell (kept by loadDataset)
+		};
+	}
+});
+
+module.exports = { registerAdapter: registerAdapter, getAdapter: getAdapter, listAdapters: listAdapters, loadDataset: loadDataset,
+	analyzeSpiderSQL: analyzeSpiderSQL, spiderGoldShape: spiderGoldShape };

package/lib/authoring/debug-provider.js

@@ -0,0 +1,92 @@
+/*
+ * 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';
+/**
+ * debug-provider.js — a STRUCTURAL debugging provider for the distillation kill-gate (B-thin;
+ * `doc/WIP/specs/2026-06-30-distill-killgate-construct-method-design.md`).
+ *
+ * It snaps a bug to typed facts (the canonicalization barrier, `canonicalize.canonFacts`) and emits a
+ * MULTI-OBJECT decomposition sub-graph `Bug → Hypothesis → Localize → Fix(target)` whose typed content
+ * (`fixKind`, the intermediate `role`s) is a FUNCTION of the typed `bugClass` — so the cast is
+ * signature-determined and therefore crystallizable into a re-mountable `Method` (`crystallizeStructural`).
+ * The free text rides an UNTRACKED `debugProse` key (it stays in the model, off the dependency edges).
+ *
+ * Two non-negotiables it obeys (CLAUDE.md):
+ *   • a flat length-1 fact patch is SKIPPED by the structural miner (`mine.js`), so the cast emits a
+ *     multi-object sub-graph (intermediate nodes + child segments);
+ *   • a wired provider does NOT auto-flag its cast, so the head template sets BOTH the cast marker
+ *     `{ DebugStep:true }` and a DISTINCT durable re-fire guard `{ Decomposed:true }` (the gotcha).
+ *
+ * `ask` is INJECTABLE: a deterministic stub in tests, the real model in the live harness — so the
+ * deterministic backbone and the live measurement share ONE code path. `classify(rawJSON)` decides the
+ * typed class (a deterministic table in the stub; the canon barrier on the model's JSON, live).
+ *
+ * @param opts.ask         async ({system,user,maxTokens}) -> string (the model, or a stub).
+ * @param opts.parseJSON   JSON-salvage fn. Default JSON.parse.
+ * @param opts.classify    (rawJSON) -> { bugClass, fixKind }. The typed-class decision.
+ * @param opts.factsSchema optional override of the closed enum vocab for { bugClass, fixKind }.
+ * @returns { AI: { debugStep } }  a provider-map fragment (concept provider ref `AI::debugStep`).
+ */
+var canonicalize = require('../providers/canonicalize.js');
+
+var DEFAULT_FACTS = {
+	bugClass: { enum: ['off-by-one', 'null-deref', 'wrong-branch', 'type-mismatch', 'resource-leak'] },
+	fixKind:  { enum: ['adjust-bound', 'guard-null', 'fix-cond', 'cast', 'release'] },
+};
+
+function makeDebugProvider( opts ) {
+	opts = opts || {};
+	var ask         = opts.ask;
+	var parseJSON   = opts.parseJSON || JSON.parse;
+	var classify    = opts.classify;
+	var factsSchema = opts.factsSchema || DEFAULT_FACTS;
+
+	return { AI: {
+		debugStep: function ( graph, concept, scope, argz, cb ) {
+			var base = scope._._id, origin = scope._.originNode, target = scope._.targetNode;
+			var sys = 'You debug code. Decompose the bug into hypothesis / localize / fix. ' +
+			          'Respond ONLY JSON: {"bugClass":"...","hypothesis":"...","fix":"..."}';
+			var usr = 'Failing test: ' + (scope._.failingTest || '?') + '\n' +
+			          'Bug: ' + (scope._.bugText || scope._.label || base);
+			Promise.resolve(ask({ system: sys, user: usr, maxTokens: 600 }))
+				.then(function ( txt ) {
+					graph.traceProvider && graph.traceProvider(concept, scope, { prompt: { system: sys, user: usr }, reply: txt });
+					var raw = parseJSON(txt);
+					var cls = classify(raw);                              // host/stub picks the typed class
+					var cf  = canonicalize.canonFacts({ bugClass: cls.bugClass, fixKind: cls.fixKind }, factsSchema);
+					var fixKind = cf.facts.fixKind;
+					var h = base + '_h', l = base + '_l';
+					var head = { $_id: '_parent', DebugStep: true, Decomposed: true,
+					             debugProse: (raw && ((raw.hypothesis || '') + ' | ' + (raw.fix || ''))) };
+					if ( cf.misses.length ) head.DebugStepCanonMiss = cf.misses;   // visible + fail-closed (un-cacheable)
+					Object.assign(head, cf.facts);                        // ONLY declared, snapped keys -> TRACKED
+					cb(null, [
+						head,
+						{ _id: h, Node: true, role: 'hypothesis', fixKind: fixKind },
+						{ _id: l, Node: true, role: 'localize' },
+						{ _id: base + '_a0', Segment: true, originNode: origin, targetNode: h, parentSeg: base },
+						{ _id: base + '_a1', Segment: true, originNode: h, targetNode: l, parentSeg: base },
+						{ _id: base + '_a2', Segment: true, originNode: l, targetNode: target, parentSeg: base },
+					]);
+				})
+				.catch(function ( e ) { cb(null, { $_id: '_parent', DebugStep: true, Decomposed: true, llmError: e.message }); });
+		},
+	} };
+}
+
+module.exports = { makeDebugProvider: makeDebugProvider };