skynet-graph 1.2.0

package/lib/authoring/method-explorer.js

@@ -0,0 +1,138 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * method-explorer — LIST + JUDGE a concept-method population (host-side, ZERO-CORE, fs-free). The owner's
+ * "outil/explorer" ask (2026-07-05): give every crystallized method a TITLE / mini-DESCRIPTION / CATEGORY, and
+ * summarize the population so its QUALITY, its OPENNESS (diversity), and its COVERAGE (which declared task-
+ * classes have a method — and which are GAPS) are legible. Reads any library SOURCE method-pack normalizes
+ * (a master loop / recall index / { entries } / array / a `.sgc methods` bundle's `.methods`).
+ *
+ * A concept-method is a TYPED decomposition: a class SIGNATURE (the K1 `structure` discriminant keys) → a
+ * derivation over `content` holes → reusable templates (`templatesBySig`). So:
+ *   - CATEGORY  = the canonical structure signature (the class the method serves).
+ *   - TITLE     = the structure values, human-legible.
+ *   - COVERAGE  = per structure-key, which VALUES have a method; against a declared vocabulary (a registry enum
+ *                 or an explicit `expected`), the MISSING values = the population's gaps (the actionable metric).
+ *   - OPENNESS  = distinct classes, singleton fraction (one-off vs reused), templates/method (reuse depth),
+ *                 and the Shannon ENTROPY of the class distribution (spread vs concentration).
+ *
+ *   const { describeLibrary, formatLibrary } = require('skynet-graph/lib/authoring/method-explorer');
+ *   const report = describeLibrary(masterLoop, { registry });   // registry → coverage gaps vs the declared canon
+ *   console.log(formatLibrary(report));                          // a text listing + population summary
+ */
+
+const { toEntries } = require('./method-pack.js');
+
+function canon( x ) {
+	if ( x === undefined ) return 'null';
+	if ( x === null || typeof x !== 'object' ) return JSON.stringify(x);
+	if ( Array.isArray(x) ) return '[' + x.map(canon).join(',') + ']';
+	return '{' + Object.keys(x).sort().map(( k ) => JSON.stringify(k) + ':' + canon(x[k])).join(',') + '}';
+}
+function templateCountOf( method ) {
+	if ( !method || typeof method !== 'object' ) return 0;
+	if ( method.templatesBySig && typeof method.templatesBySig === 'object' ) return Object.keys(method.templatesBySig).length;
+	if ( Array.isArray(method.templates) ) return method.templates.length;
+	return method.template || method.derivation ? 1 : 0;
+}
+
+/**
+ * A single method's descriptor: id, title, category, mini-description + the typed keys and template count.
+ * @param entry a normalized `{ structure, content, method }`
+ */
+function describeMethod( entry ) {
+	const s = entry.structure || {}, c = entry.content || {};
+	const sKeys = Object.keys(s).sort(), cKeys = Object.keys(c).sort();
+	const category = sKeys.length ? sKeys.map(( k ) => k + '=' + s[k]).join(',') : '(untyped)';
+	const title = sKeys.length ? sKeys.map(( k ) => String(s[k])).join(' · ') : '(untyped)';
+	const templates = templateCountOf(entry.method);
+	const id = (entry.method && entry.method.id) || 'm:' + canon(s);
+	return {
+		id, title, category,
+		description: `keys on {${sKeys.join(', ') || '∅'}} → derives {${cKeys.join(', ') || '∅'}} · ${templates} template${templates === 1 ? '' : 's'}`,
+		structureKeys: sKeys, contentKeys: cKeys, templateCount: templates
+	};
+}
+
+function entropyBits( counts ) {
+	const total = counts.reduce(( a, b ) => a + b, 0);
+	if ( total <= 0 ) return 0;
+	let h = 0;
+	for ( const n of counts ) if ( n > 0 ) { const p = n / total; h -= p * Math.log2(p); }
+	return h;
+}
+
+/**
+ * Describe + judge a whole method population.
+ * @param source  any library source (see `toEntries`) — a master loop / recall index / { entries } / array /
+ *                a `.sgc methods` bundle's `.methods`.
+ * @param opts    { registry } to compute coverage GAPS against the declared enum vocab, or { expected:{ <key>:
+ *                [values] } } for an explicit declared value-space per structure key.
+ * @returns {{ methods, population:{ count, categories, coverage, openness } }}
+ */
+function describeLibrary( source, opts ) {
+	opts = opts || {};
+	const entries = toEntries(source);
+	const methods = entries.map(describeMethod);
+
+	// class distribution (the CATEGORY = the served signature)
+	const catCount = {};
+	for ( const m of methods ) catCount[m.category] = (catCount[m.category] || 0) + 1;
+	const categories = Object.keys(catCount).map(( category ) => ({ category, count: catCount[category] }))
+		.sort(( a, b ) => b.count - a.count || (a.category < b.category ? -1 : 1));
+
+	// COVERAGE — per structure-key present values, and the declared-vocab GAPS (missing values with no method)
+	const keyVals = {};
+	for ( const e of entries ) for ( const k of Object.keys(e.structure || {}) ) (keyVals[k] = keyVals[k] || new Set()).add(String(e.structure[k]));
+	const expectedFor = ( key ) => {
+		if ( opts.expected && opts.expected[key] ) return opts.expected[key];
+		const entry = opts.registry && opts.registry.keys && opts.registry.keys[key];
+		return entry && entry.enum ? entry.enum : null;
+	};
+	const coverage = Object.keys(keyVals).sort().map(( key ) => {
+		const present = [...keyVals[key]].sort();
+		const c = { key, present, covered: present.length };
+		const exp = expectedFor(key);
+		if ( exp ) { const has = keyVals[key]; c.expected = exp.length; c.missing = exp.filter(( v ) => !has.has(String(v))).sort(); c.fraction = exp.length ? present.filter(( v ) => exp.map(String).includes(v)).length / exp.length : 0; }
+		return c;
+	});
+
+	// OPENNESS — diversity of the population
+	const singleton = categories.filter(( c ) => c.count === 1 ).length;
+	const totalTemplates = methods.reduce(( s, m ) => s + m.templateCount, 0);
+	const openness = {
+		distinctClasses: categories.length,
+		singletonFraction: categories.length ? singleton / categories.length : 0,
+		avgTemplatesPerMethod: methods.length ? totalTemplates / methods.length : 0,
+		entropyBits: entropyBits(categories.map(( c ) => c.count )),
+		maxEntropyBits: categories.length > 1 ? Math.log2(categories.length) : 0
+	};
+
+	return { methods, population: { count: methods.length, categories, coverage, openness } };
+}
+
+/** Render a `describeLibrary` report as a compact text listing + a population summary (the CLI/explorer view). */
+function formatLibrary( report ) {
+	const L = [];
+	const p = report.population;
+	L.push(`CONCEPT-METHODS — ${p.count} method(s), ${p.openness.distinctClasses} distinct class(es)`);
+	L.push('');
+	for ( const m of report.methods ) L.push(`  • ${m.title.padEnd(24)}  [${m.category}]  ${m.description}`);
+	L.push('');
+	L.push(`POPULATION`);
+	L.push(`  classes (top): ${p.categories.slice(0, 8).map(( c ) => c.category + '×' + c.count).join(' · ')}`);
+	L.push(`  openness: ${p.openness.distinctClasses} classes · singletons ${(100 * p.openness.singletonFraction).toFixed(0)}% · templates/method ${p.openness.avgTemplatesPerMethod.toFixed(2)} · entropy ${p.openness.entropyBits.toFixed(2)}/${p.openness.maxEntropyBits.toFixed(2)} bits`);
+	L.push(`  coverage:`);
+	for ( const c of p.coverage ) {
+		if ( c.expected != null ) L.push(`    ${c.key}: ${c.covered}/${c.expected} (${(100 * c.fraction).toFixed(0)}%)${c.missing.length ? ' · GAPS: ' + c.missing.join(', ') : ' · complete'}`);
+		else L.push(`    ${c.key}: ${c.covered} value(s) present [${c.present.join(', ')}]`);
+	}
+	return L.join('\n');
+}
+
+module.exports = { describeMethod, describeLibrary, formatLibrary, templateCountOf };

package/lib/authoring/method-pack.js

@@ -0,0 +1,181 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * method-pack — the `.sgc` CRYSTALLIZED-METHOD PACKAGE (host-side, ZERO-CORE, fs-free). M3 of the
+ * productization campaign / master-graph study persistence rung. The SIBLING of `corpus-pack.js`: that one
+ * packages the AUTHORED grammar (a concept tree → a portable bundle with a derived manifest); THIS one
+ * packages the LEARNED method library (the forged + crystallized methods the master loop accumulates) so a
+ * warm library MOVES between deployments — not just survives a local restart (that is M2 / `store.js`).
+ *
+ * It reuses the SAME `.sgc` envelope (`format:'sgc'` + `sgcVersion` + `manifest`), discriminated by a
+ * `kind` field: `'corpus'` (the existing grammar bundle) vs `'methods'` (this one). One exchange format,
+ * two payload kinds; `corpus-pack.js` is untouched and a reader dispatches on `kind` (default `'corpus'`).
+ *
+ *   const bundle = packMethods(masterLoop, { name: 'travel', version: 'v3' });   // .sgc JSON
+ *   //   ... ship the bundle to another deployment, write it to disk via store.saveSgc ...
+ *   const r = loadMethods(bundle, freshLoop, { version: 'v3' });                 // re-hydrate the library
+ *   //   r.added entries recalled; r.exactReplayed entries warm the 0-call cache (iff versions match)
+ *
+ * THE PORTABLE UNIT is the recall-index entry `{ structure, content, method }` — signature-addressed, so a
+ * receiver can RECALL→VERIFY it (U5). The exact content-address cache is a DERIVED acceleration: its key is
+ * recomputable from each entry's signature via the host loop's own `keyOf`, so packing the index is enough.
+ *
+ * THE LOAD-BEARING SOUNDNESS LINE (B8 — method-version pinning, made portable):
+ *   A method is `(typed signature) → derivation`; that FUNCTION is defined by the grammar + the providers,
+ *   whose identity IS the version token. Replaying a packaged method verbatim is sound in a receiving host
+ *   IFF the host's version matches the package's — otherwise the same typed input may now map to a DIFFERENT
+ *   derivation, so NO verbatim replay (neither the exact 0-call cache NOR a recall→verify `'full'` hit, which
+ *   also replays the stored method at 0 cost) is trustworthy. So the version gate covers BOTH replay paths:
+ *     - versions AGREE → hydrate the recall index AND the exact cache (full 0-call replay, sound).
+ *     - versions DIFFER → hydrate NEITHER: the host re-forges (sound). The entries stay readable via
+ *       `unpackMethods` for a host that wants to re-forge FROM the skeletons (a future version-aware-recall
+ *       refinement could downgrade a cross-version `'full'` to a partial re-forge; not built — refuse beats
+ *       a stale replay: "fuzziness in recall, exactness in truth" — a cross-version method is not TRUTH here).
+ *   Versions are opt-in (like `cache.js` `version()`): the gate enforces iff BOTH sides declare a version
+ *   (absent ⇒ permissive — the host explicitly opted out of pinning). Independently, the typed VERIFY
+ *   (`recall.js#verify`) ALSO runs on the receiver, so even a same-version package never replays a method
+ *   whose typed STRUCTURE mismatches a local query (the canonicalize.js line holds across hosts).
+ *
+ * A typed SCHEMA is DERIVED from the entries (mirrors `corpus-pack.js#deriveManifest`): the method-CLASS
+ * discriminants (the K1 `structure` keys) and the derived `content` keys — self-describing, no hand-upkeep,
+ * so a receiving host knows what typed inputs key each method class without reading the bodies.
+ */
+
+// stable, key-sorted, recursive stringify (digest-safe; the same canon the recall index + master loop use).
+function canon( x ) {
+	if ( x === undefined ) return 'null';
+	if ( x === null || typeof x !== 'object' ) return JSON.stringify(x);
+	if ( Array.isArray(x) ) return '[' + x.map(canon).join(',') + ']';
+	return '{' + Object.keys(x).sort().map(( k ) => JSON.stringify(k) + ':' + canon(x[k])).join(',') + '}';
+}
+
+function clone( x ) { return x == null ? x : JSON.parse(JSON.stringify(x)); }
+
+/**
+ * Normalize any reasonable library SOURCE into a flat array of `{ structure, content, method }` entries:
+ *   - a master loop      (has `.index` recall index)  → its index entries
+ *   - a recall index     (has `.entries` + `.recall`) → its entries
+ *   - `{ entries:[...] }`                              → those entries
+ *   - a bare array                                     → itself
+ * Each raw entry may be `{ sig:{structure,content}, method }` (the index shape) or already
+ * `{ structure, content, method }`. Missing structure/content default to `{}`.
+ */
+function toEntries( source ) {
+	let raw;
+	if ( Array.isArray(source) ) raw = source;
+	else if ( source && source.index && Array.isArray(source.index.entries) ) raw = source.index.entries;
+	else if ( source && Array.isArray(source.entries) ) raw = source.entries;
+	else raw = [];
+	return raw.map(( e ) => {
+		const structure = (e.sig ? e.sig.structure : e.structure) || {};
+		const content   = (e.sig ? e.sig.content   : e.content)   || {};
+		return { structure: clone(structure), content: clone(content), method: clone(e.method) };
+	});
+}
+
+/**
+ * Derive the typed SCHEMA off the method entries — the self-describing contract a receiver needs.
+ * @returns {{ structureKeys, contentKeys, classes:[{structure,count}] }}
+ *   structureKeys  the union of K1 method-CLASS discriminant keys (what defines a method class).
+ *   contentKeys    the union of derived `content` keys (the per-instance holes).
+ *   classes        the distinct typed structures present, with how many entries each covers.
+ */
+function deriveMethodSchema( entries ) {
+	const sKeys = new Set(), cKeys = new Set(), classes = new Map();
+	for ( const e of entries ) {
+		for ( const k of Object.keys(e.structure || {}) ) sKeys.add(k);
+		for ( const k of Object.keys(e.content || {}) ) cKeys.add(k);
+		const key = canon(e.structure || {});
+		const c = classes.get(key) || { structure: clone(e.structure || {}), count: 0 };
+		c.count++; classes.set(key, c);
+	}
+	return {
+		structureKeys: [...sKeys].sort(),
+		contentKeys  : [...cKeys].sort(),
+		classes      : [...classes.values()].sort(( a, b ) => canon(a.structure) < canon(b.structure) ? -1 : 1)
+	};
+}
+
+/**
+ * Pack a learned method library into a portable `.sgc` methods bundle (plain JSON).
+ * @param source  a master loop / recall index / { entries } / array (see `toEntries`)
+ * @param opts    { name, version, description }
+ */
+function packMethods( source, opts ) {
+	opts = opts || {};
+	const entries = toEntries(source);
+	return {
+		format    : 'sgc',
+		sgcVersion: 1,
+		kind      : 'methods',
+		manifest  : {
+			name       : opts.name || 'methods',
+			version    : opts.version || '0.0.0',
+			description: opts.description || '',
+			methodCount: entries.length,
+			schema     : deriveMethodSchema(entries)
+		},
+		methods   : entries
+	};
+}
+
+/**
+ * Unpack a `.sgc` methods bundle. Pure read — returns the entries + manifest + derived schema and a
+ * version-gate verdict (does NOT mutate any host). Throws on a non-methods bundle.
+ * @param bundle  a packMethods() output
+ * @param opts    { hostVersion } — if given, compared against the package version for `exactReplaySafe`.
+ * @returns {{ methods, manifest, schema, versionPackage, exactReplaySafe }}
+ */
+function unpackMethods( bundle, opts ) {
+	opts = opts || {};
+	if ( !bundle || bundle.format !== 'sgc' ) throw new Error('not an .sgc bundle');
+	if ( bundle.kind !== 'methods' ) throw new Error('not a .sgc methods bundle (kind=' + bundle.kind + ')');
+	const methods = bundle.methods || [];
+	const manifest = bundle.manifest || {};
+	return {
+		methods, manifest, schema: manifest.schema || deriveMethodSchema(methods),
+		versionPackage : manifest.version,
+		exactReplaySafe: versionsAgree(opts.hostVersion, manifest.version)
+	};
+}
+
+// B8 gating: active iff BOTH sides declare a version (opt-in, like cache.js#version). Absent ⇒ permissive.
+function versionsAgree( vHost, vPkg ) {
+	if ( vHost == null || vPkg == null ) return true;   // no pinning requested → permissive
+	return vHost === vPkg;
+}
+
+/**
+ * Re-hydrate a `.sgc` methods bundle INTO a host library, gated by the version (B8). On a version MATCH it
+ * feeds BOTH replay paths — the recall index AND the exact 0-call cache; on a MISMATCH it hydrates NEITHER
+ * (the host re-forges; the stale bodies never write a derivation here). See the soundness line in the header.
+ *
+ * @param bundle  a packMethods() output
+ * @param host    { index, cache, keyOf } — e.g. a master loop (it exposes exactly these). `cache`/`keyOf`
+ *                optional: without them only the recall index is hydrated.
+ * @param opts    { version } — the host's method-lib version (B8). Omit to opt out of version pinning.
+ * @returns {{ added, exactReplayed, exactReplaySafe, skipped, versionHost, versionPackage }}
+ */
+function loadMethods( bundle, host, opts ) {
+	opts = opts || {};
+	const { methods, versionPackage } = unpackMethods(bundle, { hostVersion: opts.version });
+	const safe = versionsAgree(opts.version, versionPackage);
+	let added = 0, exactReplayed = 0;
+	if ( !safe )   // version mismatch → refuse to inject stale methods into the live replay paths (re-forge instead).
+		return { added: 0, exactReplayed: 0, exactReplaySafe: false, skipped: methods.length, versionHost: opts.version, versionPackage };
+	for ( const e of methods ) {
+		const sig = { structure: e.structure, content: e.content };
+		if ( host && host.index && host.index.add ) { host.index.add(sig, clone(e.method)); added++; }    // recall path
+		if ( host && host.cache && host.cache.set && typeof host.keyOf === 'function' ) {
+			host.cache.set(host.keyOf(sig), clone(e.method)); exactReplayed++;                            // exact 0-call path
+		}
+	}
+	return { added, exactReplayed, exactReplaySafe: true, skipped: 0, versionHost: opts.version, versionPackage };
+}
+
+module.exports = { packMethods, unpackMethods, deriveMethodSchema, loadMethods, toEntries };

package/lib/authoring/method.js

@@ -0,0 +1,202 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * method — HIGHER-ORDER methods-as-graphs: a method receives a SUB-GRAPH as a typed named-slot parameter
+ * and applies it (host-side, builds on `abstract.js`; engine-native splice via `pushMutation`). BRICK 1 of
+ * the conception build (doc/WIP/studies/2026-06-28-concept-as-graph-conception-assembled.md §3 / C2).
+ *
+ * The parameter is FIRST-ORDER in mechanics: a body is a PARAMETERIZED template (holes from
+ * `abstract.js#relativize`) bound BY NAME at a call site (`instantiate`) — never inferred. So "method takes
+ * a sub-graph" is decidable substitution, not higher-order unification.
+ *
+ * Landmines respected: each application gets a FRESH id-base (finding #30 — else N applications collapse
+ * onto one body via the existing-object merge path), the splice goes through the SEQUENCED `pushMutation`
+ * (determinism), and an unbound frontier ref THROWS (a leak) rather than splicing an unsound partial.
+ */
+const { instantiate, refHolesOf } = require('./abstract.js');
+
+/**
+ * Bind a parameterized body sub-graph to a NEW call site → a ground template. Throws on an unbound frontier
+ * ref (a leak) — never returns a partially-bound template.
+ * @param paramBody  parameterized template (holes via `relativize`)
+ * @param ctx        { base, refs:{name:id} }  the call site (fresh base + the slot's frontier ids)
+ * @returns the ground (bound) template
+ */
+function bindSubgraphArg( paramBody, ctx ) {
+	const bound = instantiate(paramBody, ctx);
+	if ( bound == null )
+		throw new Error('applySubgraphArg: unbound frontier ref (leak) for refs=' + JSON.stringify((ctx && ctx.refs) || {}));
+	return bound;
+}
+
+/**
+ * Bind a body sub-graph into a call-site SLOT and splice it SEQUENCED under the slot (parented via
+ * `_origin = targetId`).
+ * @param graph
+ * @param paramBody  the parameterized body
+ * @param ctx        { base, refs } the call site (fresh base + frontier ids)
+ * @param targetId   the slot object the splice mounts under (the parent)
+ * @param cb         called once the splice settles
+ * @returns the bound template
+ */
+function applySubgraphArg( graph, paramBody, ctx, targetId, cb ) {
+	const bound = bindSubgraphArg(paramBody, ctx);
+	graph.pushMutation(bound, targetId, false, undefined, undefined, cb);
+	return bound;
+}
+
+/**
+ * BUILD the MAP combinator's template (PURE — no graph mutation): apply a body sub-graph to EACH element of
+ * a collection, each instance with its OWN fresh id-base (so N elements never collide onto one body, #30).
+ * Returned as ONE combined template — a provider returns this via `cb` (the ENGINE applies it, parented under
+ * the cast slot), or `mapSubgraph` pushes it directly.
+ * @param opts.elements    [id]  the collection element node ids (the CASES)
+ * @param opts.body        the parameterized body (the PARAM); frontier `elem` is bound to each element
+ * @param opts.basePrefix  id-base prefix per element (default 'map' → map0, map1, …)
+ * @param opts.refsOf      optional (elem,i) => extra frontier refs to bind besides `elem`
+ * @returns the combined ground template (array)
+ */
+function mapTemplate( opts ) {
+	opts = opts || {};
+	const elements = opts.elements || [];
+	const prefix = opts.basePrefix || 'map';
+	const tpl = [];
+	elements.forEach(function ( elem, i ) {
+		const refs = Object.assign({ elem: elem }, opts.refsOf ? opts.refsOf(elem, i) : {});
+		tpl.push.apply(tpl, bindSubgraphArg(opts.body, { base: prefix + i, refs: refs }));
+	});
+	return tpl;
+}
+
+/**
+ * The MAP combinator, HOST-driven: build the fan-out template and splice it SEQUENCED under the slot.
+ * (The ENGINE-driven form is a provider returning `mapTemplate(...)` — see method-subgraph.test.js.)
+ * @param graph
+ * @param opts     as `mapTemplate` + `opts.slotId` (the map segment the bodies mount under)
+ * @param cb       called once the map settles
+ * @returns the combined ground template
+ */
+function mapSubgraph( graph, opts, cb ) {
+	const tpl = mapTemplate(opts);
+	if ( !tpl.length ) { if ( cb ) setTimeout(cb); return tpl; }
+	graph.pushMutation(tpl, opts.slotId, false, undefined, undefined, cb);
+	return tpl;
+}
+
+// ---------------------------------------------------------------------------- the method LINT (Brick 2)
+
+// kinds we treat as K1-typed slot containers; anything else (incl. these prose markers) is a memo footgun.
+const TYPED_KINDS = new Set(['enum', 'id', 'number', 'bool', 'list', 'subgraph']);
+const PROSE_TYPES = new Set(['prose', 'text', 'string', 'str', 'freetext', 'free-text']);
+
+// the fact keys a pre/post entry touches: the $refs it mentions, or — if it is a bare key (no $) — itself.
+function frameKeys( entries ) {
+	const keys = new Set();
+	for ( const e of (entries || []) ) {
+		if ( typeof e !== 'string' ) continue;
+		const refs = e.match(/\$\$?([A-Za-z_][\w.:]*)/g);
+		if ( refs ) refs.forEach(( r ) => keys.add(r.replace(/^\$\$?/, '')));
+		else keys.add(e.trim());
+	}
+	return keys;
+}
+
+const isTypedName = ( t, opts ) =>
+	typeof t === 'string' && t.length > 0 && !PROSE_TYPES.has(t.toLowerCase()) &&
+	(!opts || !opts.types || opts.types.indexOf(t) >= 0);
+
+/**
+ * lintMethod — enforce the decidability invariants + the footprint/frame check on a METHOD DEFINITION, so the
+ * "decidable line" is CHECKED, not emergent (design doc §3 / C4). Mirrors `validate.js`: `{ errors, warnings }`
+ * with records `{ method, kind, message, slot? }`. Errors = a method that breaks an invariant; an uncontracted
+ * method is a WARNING (the cost gradient — a runtime micro-LLM fallback, §0.1), not an error.
+ *
+ * @param def   { name, slots:{ <name>:{ role:'param'|'case', kind, frontier?, in?, out?, elem? } }, body?, contract? }
+ * @param opts  { types? }  optional host type-alphabet — if given, slot type names must be in it.
+ */
+function lintMethod( def, opts ) {
+	opts = opts || {};
+	const errors = [], warnings = [];
+	const method = (def && def.name) || '?';
+	const err = ( kind, message, slot ) => errors.push({ method, kind, message, slot });
+	const slots = (def && def.slots) || {};
+	const used = def && def.body != null ? refHolesOf(def.body) : null;
+
+	for ( const name of Object.keys(slots) ) {
+		const s = slots[name] || {};
+		if ( !name ) { err('unnamed-slot', 'a slot has an empty name'); continue; }                 // (a)
+		if ( s.infer ) err('inference-slot', `slot "${name}" is infer:true — a body is SUPPLIED, never solved-for (undecidable)`, name);   // (c)
+		if ( !TYPED_KINDS.has(s.kind) )                                                              // (b) K1
+			err('prose-slot', `slot "${name}" kind "${s.kind}" is not K1-typed — a prose/untyped key re-keys every run (memo death)`, name);
+		if ( s.kind === 'subgraph' ) {
+			if ( !isTypedName(s.in, opts) || !isTypedName(s.out, opts) )                             // (b) typed interface
+				err('prose-interface', `sub-graph slot "${name}" has a non-typed in/out interface (in=${s.in}, out=${s.out})`, name);
+			if ( s.role === 'param' && !('frontier' in s) )                                          // (c) supplied
+				err('unbound-param', `param sub-graph slot "${name}" has no frontier — it must be supplied by binding, not inferred`, name);
+			if ( 'frontier' in s && !Array.isArray(s.frontier) )                                     // (d) fixed tentacles
+				err('variable-tentacles', `slot "${name}" frontier must be a FIXED array, got ${JSON.stringify(s.frontier)}`, name);
+			if ( Array.isArray(s.frontier) && used )                                                 // (c2) decl ↔ impl
+				lintFrontierMatch(s.frontier, used, name, err);
+		}
+		if ( s.kind === 'list' && !isTypedName(s.elem, opts) )                                       // (b) typed elem
+			err('untyped-collection', `collection slot "${name}" has no typed elem type (got ${JSON.stringify(s.elem)})`, name);
+	}
+
+	const c = def && def.contract;                                                                   // (e) frame
+	if ( !c ) {
+		warnings.push({ method, kind: 'uncontracted', message: `method "${method}" declares no contract — composition falls back to a runtime micro-LLM (cost gradient, §0.1)` });
+	} else {
+		const read = new Set(c.read || []), write = new Set(c.write || []);
+		for ( const k of frameKeys(c.post) ) if ( !write.has(k) )
+			err('frame-violation', `postcondition key "${k}" is outside the declared write-footprint {${[...write].join(', ')}}`);
+		for ( const k of frameKeys(c.pre) ) if ( !read.has(k) )
+			err('frame-violation', `precondition key "${k}" is outside the declared read-footprint {${[...read].join(', ')}}`);
+	}
+	return { errors, warnings };
+}
+
+function lintFrontierMatch( frontier, used, name, err ) {
+	const declared = new Set(frontier);
+	for ( const d of declared ) if ( !used.has(d) )
+		err('frontier-mismatch', `slot "${name}" declares frontier ref "${d}" the body never uses`, name);
+	for ( const u of used ) if ( !declared.has(u) )
+		err('frontier-mismatch', `the body uses ref "${u}" not declared in slot "${name}" frontier`, name);
+}
+
+// ------------------------------------------------------------------ case-parameterized SELECTION (Brick 3)
+
+/**
+ * selectCluster — generate a concept-tree fragment of MUTUALLY-EXCLUSIVE, typed-gated SELECTORS that pick
+ * WHICH method applies to a problem from the CASE's structural (typed) facts, step by step (design doc §4A;
+ * "la bonne boucle est définie par les conditions initiales"). Selection lives in the CONCEPT layer (gated
+ * on the case facts already on the segment via the param/case role cut), NOT in a blind getPaths enumeration.
+ *
+ * Mutual exclusion is the confluence guarantee: at most one selector casts per segment. A `fallback` selector
+ * fires iff NO typed rule matched — that is the cost-gradient hand-off to a runtime micro-LLM (§0.1), not a
+ * hard failure. Each rule's provider must set the rule's `_name` cast marker (finding #33).
+ *
+ * @param rules  [{ name, when:"<assert expr over the case's typed facts>", provider:"Ns::fn" }]
+ * @param opts   { trigger:'toSelect', on:[factKeys that must be PRESENT to consider selection],
+ *                 fallback?:name, fallbackProvider?:"Ns::fn" }
+ * @returns a `childConcepts` map (drop into a concept tree under `common`).
+ */
+function selectCluster( rules, opts ) {
+	opts = opts || {};
+	const require = ['Segment', opts.trigger || 'toSelect'].concat(opts.on || []);
+	const childConcepts = {}, conds = [];
+	for ( const r of (rules || []) ) {
+		childConcepts[r.name] = { _id: r.name, _name: r.name, require: require.slice(), assert: [r.when], provider: [r.provider] };
+		conds.push('(' + r.when + ')');
+	}
+	if ( opts.fallback )                                              // fires iff NO typed rule matched → micro-LLM
+		childConcepts[opts.fallback] = { _id: opts.fallback, _name: opts.fallback, require: require.slice(),
+			assert: [conds.length ? '!(' + conds.join(' || ') + ')' : 'true'], provider: [opts.fallbackProvider] };
+	return childConcepts;
+}
+
+module.exports = { applySubgraphArg, mapSubgraph, mapTemplate, bindSubgraphArg, lintMethod, selectCluster };