skynet-graph 1.2.0

package/lib/authoring/lattice-pack.js

@@ -0,0 +1,148 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * lattice-pack — the `.sgc` TYPED-LATTICE PACKAGE (host-side, ZERO-CORE, fs-free). The THIRD sibling of
+ * `corpus-pack.js` (kind `'corpus'` = the authored grammar tree) and `method-pack.js` (kind `'methods'` =
+ * the learned method library): THIS one packages the REGISTRY — the typed isa/enum vocabulary + the
+ * synonym RINGS grown at runtime by the admission gate (`registry.js#decideRingAdmission` /
+ * `mergeRingProposals`) + their `ringProvenance`. So a GROWN lattice (the runtime-learned vocabulary edges,
+ * e.g. from the SemEval-T9 / hypernymy campaign) MOVES between deployments — not just survives a restart.
+ *
+ * One `.sgc` envelope (`format:'sgc'` + `sgcVersion` + `manifest`), discriminated by `kind` — here
+ * `'lattice'`. A reader dispatches on `kind`; corpus-pack / method-pack are untouched.
+ *
+ *   const bundle = packLattice(freezeRegistry(reg, 'v3'), { name: 'isa', version: 'v3' });   // .sgc JSON
+ *   const r = loadLattice(bundle, hostRegistry, { version: 'v3' });                          // grow the canon
+ *   //   r.registry = the host registry GROWN by the shipped rings (confluence-checked); r.admitted/rejected
+ *
+ * THE PORTABLE UNIT is the registry value object `{ version, frozen, keys:{ <key>:{ tier, enum, synonyms,
+ * grain, … } }, ringProvenance }` — already plain JSON and already version-stamped (`freezeRegistry` /
+ * `bumpVersion`), so packing is a clone + a derived, self-describing manifest.
+ *
+ * THE LOAD-BEARING SOUNDNESS LINE (the SAME B8 doctrine as method-pack, plus the ring's own admission gate):
+ *   The registry IS the closed typed vocabulary (any tier) + the defeasible ring envelope; its identity is
+ *   the version token. Loading a packaged lattice into a receiving host is sound IFF versions AGREE — else
+ *   the same key may now carry a DIFFERENT enum/ring, so no verbatim adoption (a stale ring would mis-canon
+ *   a downstream fact). So the gate covers loading:
+ *     - versions AGREE → grow the host: each shipped ring alias is re-proposed through `mergeRingProposals`,
+ *       so it enters ONLY if its member is a registered enum member of the host key AND the ring stays
+ *       CONFLUENT (the critical-pair check) — a conflicting shipped alias is REJECTED, never blindly merged.
+ *       With NO host registry, the packaged registry is ADOPTED wholesale (the portable canon).
+ *     - versions DIFFER → grow NOTHING (the host re-derives / re-learns). The bundle stays readable via
+ *       `unpackLattice` for a host that wants to inspect it ("refuse beats a stale canon").
+ *   Versions are opt-in (like `cache.js#version` / method-pack): the gate enforces iff BOTH sides declare a
+ *   version (absent ⇒ permissive — the host explicitly opted out of pinning).
+ */
+const { mergeRingProposals } = require('./registry.js');
+
+function clone( x ) { return x == null ? x : JSON.parse(JSON.stringify(x)); }
+
+// B8 gating (verbatim doctrine of method-pack#versionsAgree): active iff BOTH sides declare a version.
+function versionsAgree( vHost, vPkg ) {
+	if ( vHost == null || vPkg == null ) return true;   // no pinning requested → permissive
+	return vHost === vPkg;
+}
+
+/** the flat ring PROPOSALS of a registry — one `{key, member, alias}` per (member, alias) in every key's ring. */
+function ringsOf( reg ) {
+	const out = [], keys = (reg && reg.keys) || {};
+	for ( const key of Object.keys(keys) ) {
+		const syn = keys[key].synonyms;
+		if ( !syn ) continue;
+		for ( const member of Object.keys(syn) )
+			for ( const alias of (syn[member] || []) ) out.push({ key, member, alias });
+	}
+	return out;
+}
+
+/**
+ * Derive the self-describing SCHEMA of a registry — what a receiver needs to know without reading bodies.
+ * @returns {{ keyCount, tier1Keys, enumKeys:[…], ringMembers, ringAliases }}
+ */
+function deriveLatticeSchema( reg ) {
+	const keys = (reg && reg.keys) || {};
+	const enumKeys = []; let tier1 = 0, ringMembers = 0, ringAliases = 0;
+	for ( const k of Object.keys(keys) ) {
+		const e = keys[k];
+		if ( e.tier === 1 ) tier1++;
+		if ( e.enum ) enumKeys.push(k);
+		if ( e.synonyms ) for ( const m of Object.keys(e.synonyms) ) { ringMembers++; ringAliases += (e.synonyms[m] || []).length; }
+	}
+	return { keyCount: Object.keys(keys).length, tier1Keys: tier1, enumKeys: enumKeys.sort(), ringMembers, ringAliases };
+}
+
+/**
+ * Pack a registry (typed isa lattice + grown rings) into a portable `.sgc` lattice bundle (plain JSON).
+ * @param registry  a registry (from `deriveRegistry` / `freezeRegistry` / the merged runtime container).
+ * @param opts      { name, version, description } — version defaults to the registry's own stamp.
+ */
+function packLattice( registry, opts ) {
+	opts = opts || {};
+	registry = registry || { keys: {} };
+	return {
+		format    : 'sgc',
+		sgcVersion: 1,
+		kind      : 'lattice',
+		manifest  : {
+			name       : opts.name || 'lattice',
+			version    : opts.version || registry.version || '0.0.0',
+			description: opts.description || '',
+			frozen     : !!registry.frozen,
+			schema     : deriveLatticeSchema(registry)
+		},
+		registry  : clone(registry)
+	};
+}
+
+/**
+ * Unpack a `.sgc` lattice bundle. Pure read — returns the registry + manifest + a version-gate verdict (does
+ * NOT mutate any host). Throws on a non-lattice bundle.
+ * @param bundle  a packLattice() output
+ * @param opts    { hostVersion } — compared against the package version for `loadSafe`.
+ * @returns {{ registry, manifest, schema, versionPackage, loadSafe }}
+ */
+function unpackLattice( bundle, opts ) {
+	opts = opts || {};
+	if ( !bundle || bundle.format !== 'sgc' ) throw new Error('not an .sgc bundle');
+	if ( bundle.kind !== 'lattice' ) throw new Error('not a .sgc lattice bundle (kind=' + bundle.kind + ')');
+	const registry = bundle.registry || { keys: {} };
+	const manifest = bundle.manifest || {};
+	return {
+		registry, manifest, schema: manifest.schema || deriveLatticeSchema(registry),
+		versionPackage: manifest.version, loadSafe: versionsAgree(opts.hostVersion, manifest.version)
+	};
+}
+
+/**
+ * Load a `.sgc` lattice bundle INTO a host registry, gated by the version (B8). On a version MATCH it GROWS
+ * the host: with a host registry, each shipped ring alias is re-proposed through `mergeRingProposals` (member
+ * ∈ enum ∧ confluence re-checked) so a conflicting alias is REJECTED, never blindly merged; with NO host
+ * registry, the packaged registry is ADOPTED wholesale. On a MISMATCH it grows nothing (the host re-learns).
+ *
+ * @param bundle        a packLattice() output
+ * @param hostRegistry  the host registry to grow (or null/undefined to ADOPT the packaged one)
+ * @param opts          { version } — the host's canon version (B8). Omit to opt out of version pinning.
+ * @returns {{ registry, adopted, merged, admitted, rejected, skipped, loadSafe, versionHost, versionPackage }}
+ */
+function loadLattice( bundle, hostRegistry, opts ) {
+	opts = opts || {};
+	const hostVersion = opts.version != null ? opts.version : (hostRegistry && hostRegistry.version);
+	const { registry: pkg, versionPackage } = unpackLattice(bundle, { hostVersion });
+	const safe = versionsAgree(hostVersion, versionPackage);
+	const shipped = ringsOf(pkg);
+	if ( !safe )   // version mismatch → refuse to inject a stale canon; the host re-derives / re-learns.
+		return { registry: hostRegistry || null, adopted: false, merged: false, admitted: [], rejected: [], skipped: shipped.length, loadSafe: false, versionHost: hostVersion, versionPackage };
+	if ( !hostRegistry )   // no host canon → adopt the portable one wholesale (its own rings come along).
+		return { registry: clone(pkg), adopted: true, merged: false, admitted: shipped, rejected: [], skipped: 0, loadSafe: true, versionHost: hostVersion, versionPackage };
+	// grow the host by the shipped rings through the SAME admission gate (confluence-checked, provenance-tagged).
+	const proposals = shipped.map(( r ) => ({ key: r.key, member: r.member, alias: r.alias, via: 'loaded:' + (bundle.manifest && bundle.manifest.name || 'lattice') }));
+	const r = mergeRingProposals(hostRegistry, proposals);
+	return { registry: r.registry, adopted: false, merged: true, admitted: r.admitted, rejected: r.rejected, skipped: 0, loadSafe: true, versionHost: hostVersion, versionPackage };
+}
+
+module.exports = { packLattice, unpackLattice, loadLattice, deriveLatticeSchema, ringsOf };

package/lib/authoring/leaf-io.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * leaf-io — the TYPED LEAF I/O DISCIPLINE (ZERO-CORE, host-side). Closes the tiered-plan gap (ii): the executor's
+ * raw reply ("area=120", "72 km/h", "yes.") polluted the projection pool, so downstream leaves consumed garbage and
+ * the reassembled answer was unreadable. This generalizes the demo's execProgram/cellule idiom to prose leaves:
+ * the leaf's OUTPUT is parsed to a BARE TYPED VALUE (number | yes/no) or REFUSED — never carried garbled. Fail-closed:
+ * an ambiguous reply (two numbers, prose) is a typed refusal with a blame, not a guess.
+ *
+ *   const { parseLeafValue, LEAF_ANSWER_SYSTEM } = require('skynet-graph/lib/authoring/leaf-io');
+ *   const out = await ask({ system: LEAF_ANSWER_SYSTEM, user: leaf.prompt, maxTokens: 16 });
+ *   const v = parseLeafValue(out);              // { ok:true, kind:'number', value:24 } | { ok:false, blame }
+ *   if ( !v.ok ) refuseLeaf(v.blame); else post(v.value);
+ */
+
+// the executor-side contract matching the parser (kept WITH it so prompt and parse never drift apart).
+const LEAF_ANSWER_SYSTEM = 'Solve this single small step. Reply with ONLY the bare result: one number (no units, '
+	+ 'no commas, no symbols, no variable name), or yes/no. Nothing else.';
+// the any-kind contract (non-numeric domains, e.g. table lookups whose answer is a cell text): same discipline,
+// the text option is a VERBATIM copy (a name/label), never a sentence.
+const LEAF_ANSWER_SYSTEM_ANY = 'Solve this single small step. Reply with ONLY the bare result: one number (no units, '
+	+ 'no commas, no symbols, no variable name), yes/no, or the exact text value copied verbatim (a name or label, '
+	+ 'not a sentence). Nothing else.';
+
+// a short bare string that may enter the pool as a TEXT value — never a sentence, never a refusal phrase
+// (a "cannot/unknown" surface must stay a typed refusal: the pool feeds downstream leaves, garbage is worse there).
+const REFUSAL_RE = /\b(cannot|can't|unable|unknown|not sure|no answer|don't know|sorry)\b|^i\s/i;
+const isBareText = ( s ) => !!s && s.length <= 56 && !/\n/.test(s) && s.split(/\s+/).length <= 6 && !REFUSAL_RE.test(s);
+
+/**
+ * parseLeafValue(raw, opts) → { ok:true, kind:'number'|'bool'|'text', value } | { ok:false, blame, raw }
+ * Deterministic, fail-closed. Tolerated surface noise: a `name=`/`name:` echo (takes the RHS), one leading $, comma
+ * thousand-separators, a trailing unit word after the number, trailing punctuation, yes/no casing. REFUSED: empty,
+ * no numeric/boolean token, several DISTINCT numeric candidates (ambiguity is never resolved by guessing).
+ * @param opts.kind 'number' | 'bool' — restrict the accepted type ('auto' default accepts number|bool) ;
+ *        'text' — a short VERBATIM string only ; 'any' — number preferred, then bool, then short text (the
+ *        non-numeric front-door: a digit-bearing cell text like "32, 44" is TEXT under `any`, ambiguous under auto).
+ */
+function parseLeafValue( raw, opts ) {
+	opts = opts || {};
+	const want = opts.kind || 'auto';
+	let s = String(raw == null ? '' : raw).trim().replace(/^["'`\s]+|["'`.\s]+$/g, '');
+	if ( !s ) return { ok: false, blame: 'empty reply', raw: raw };
+	if ( s.indexOf('=') >= 0 ) s = s.slice(s.lastIndexOf('=') + 1).trim();   // "area=120" / "6*4=24" → the declared result (RHS)
+	const lbl = s.match(/^[a-z_][\w .]*:\s*(.+)$/i);                         // "result: 120" → the RHS (alphabetic label only — "2:30" stays ambiguous)
+	if ( lbl ) s = lbl[1].trim();
+	if ( want !== 'number' && want !== 'text' ) {
+		const b = s.match(/^(yes|no|true|false)\b[.!]?$/i);
+		if ( b ) { const y = /^(yes|true)/i.test(b[1]); return { ok: true, kind: 'bool', value: y ? 'yes' : 'no' }; }
+	}
+	if ( want === 'bool' ) return { ok: false, blame: 'not a yes/no reply', raw: raw };
+	if ( want !== 'text' ) {
+		// numeric: the reply must carry exactly ONE numeric value (a unit word after it is tolerated, a second number is not).
+		const nums = s.match(/-?\$?\d[\d,]*(?:\.\d+)?/g) || [];
+		const distinct = Array.from(new Set(nums.map(( n ) => Number(n.replace(/[$,]/g, '')) )));
+		if ( distinct.length === 1 ) {
+			// the remainder must be a value+unit surface, not a sentence re-stating the problem (fail-closed on prose).
+			const stripped = s.replace(/-?\$?\d[\d,]*(?:\.\d+)?/g, ' ').replace(/[%°]/g, ' ').trim();
+			if ( !(/\s/.test(stripped) && stripped.split(/\s+/).length > 2) ) return { ok: true, kind: 'number', value: distinct[0] };
+			if ( want !== 'any' ) return { ok: false, blame: 'prose reply, not a bare value', raw: raw };
+		}
+		else if ( want !== 'any' ) {
+			if ( distinct.length === 0 ) return { ok: false, blame: 'no numeric value in reply', raw: raw };
+			return { ok: false, blame: 'ambiguous reply (' + distinct.length + ' distinct numbers)', raw: raw };
+		}
+	}
+	// text (kind 'text' | 'any' fall-through): a short verbatim value, never prose, never a refusal phrase.
+	if ( isBareText(s) ) return { ok: true, kind: 'text', value: s };
+	return { ok: false, blame: 'not a bare short text value', raw: raw };
+}
+
+module.exports = { parseLeafValue, LEAF_ANSWER_SYSTEM, LEAF_ANSWER_SYSTEM_ANY };

package/lib/authoring/library.js

@@ -0,0 +1,156 @@
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * AGPL-3.0-or-later. See <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+/**
+ * library — the method-library INDEX + dispatch: the JUNCTURE of the two grammars (host-side, ZERO-CORE; study
+ * doc/WIP/studies/2026-06-30-creative-loop-two-level-grammar.md).
+ *
+ * The STRUCTURING grammar describes an abstract mechanism as a target FrontierSignature (params `role:sort` + the
+ * signature keys); the CONCEPT-DLL grammar is the learned library of crystallized methods. Dispatch = an **O(1)
+ * dictionary lookup on the canonical `libraryKey`** (the bucket) → refine the bucket by each candidate's APPLICATION
+ * CONDITIONS (the NACs) over the call-site scope → a RANKED list (weighted = "plusieurs façons"). It is NEVER a
+ * search/parse over the corpus — that is the HRG-parsing NP cliff (Lange-Welzl 1987). This is structure-mapping
+ * (Gentner): the abstract mechanism is the relational structure, the library methods are the source domains, a match
+ * is the analogy. The interface alphabet (`libraryKey` + `appConditions`) IS the snapped separator between the two
+ * grammars; keeping it K1-canonical is exactly what makes dispatch a lookup instead of a search.
+ *
+ *   const lib = makeLibrary();
+ *   indexMethod(lib, crystalCandidate, { weight: 2 });            // index a crystallizeStructural candidate
+ *   const r = dispatch(lib, { frontier, signatureKeys }, scopeFacts);
+ *   // r.candidates = ranked methods whose app-conditions hold at this site; r.scanned = bucket size (<< r.total)
+ */
+const { libraryKey } = require('./crystallize.js');
+const { holdsAtoms } = require('./contract.js');
+const { digest } = require('../providers/canonicalize.js');
+
+const frontierOf = ( c ) => c && (c.frontier || (c.schema && c.schema.frontier)) || { params: [] };
+const keyOf = ( c ) => (c && (c.libraryKey || (c.schema && c.schema.libraryKey))) || libraryKey(frontierOf(c), (c && c.signatureKeys) || []);
+
+/** A fresh, empty method library (a `libraryKey` → entries dictionary + a flat list). */
+function makeLibrary() { return { byKey: Object.create(null), methods: [] }; }
+
+/**
+ * Index a crystallized method under its `libraryKey`.
+ * @param candidate  a `crystallizeStructural` candidate ({ schema:{frontier,libraryKey,…}, signatureKeys, … }).
+ * @param opts.weight  production weight for ranking (default 1) — the home for `semiring.js`/inside-outside scores.
+ * @returns the libraryKey it was indexed under.
+ */
+function indexMethod( lib, candidate, opts ) {
+	opts = opts || {};
+	const key = keyOf(candidate);
+	const entry = { candidate, key, weight: opts.weight == null ? 1 : opts.weight };
+	(lib.byKey[key] = lib.byKey[key] || []).push(entry);
+	lib.methods.push(entry);
+	return key;
+}
+
+/** The O(1) bucket for a target signature — the LOOKUP (never a scan over the corpus). target = { frontier,
+ *  signatureKeys } | { libraryKey }. */
+function bucketOf( lib, target ) {
+	const key = (target && target.libraryKey) || libraryKey((target && target.frontier) || { params: [] }, (target && target.signatureKeys) || []);
+	return { key, entries: lib.byKey[key] || [] };
+}
+
+/** Do a method's application conditions (the NACs reified on its FrontierSignature) hold at a call site? require keys
+ *  must be PRESENT (engine semantics — present, not truthy); assert atoms must HOLD (`contract.holdsAtoms`, the single
+ *  source of truth, handles `$ref` + bare keys via the safe `expr.js`). An empty appConditions ⇒ trivially applicable. */
+function appConditionsHold( frontier, scopeFacts ) {
+	const ac = (frontier && frontier.appConditions) || {};
+	const facts = scopeFacts || {};
+	for ( const k of (ac.require || []) ) if ( !(k in facts) ) return false;
+	for ( const a of (ac.assert || []) ) if ( typeof a === 'string' && a.trim() && !holdsAtoms(facts, a) ) return false;
+	return true;
+}
+
+/**
+ * Dispatch a target FrontierSignature against the library: O(1) bucket lookup → refine by app-conditions over the
+ * scope → ranked candidates.
+ * @returns { key, candidates:[{candidate,weight,key}], scanned, total }
+ *   candidates  the bucket entries whose app-conditions hold, sorted by descending weight (ties keep index order).
+ *   scanned     the bucket size — proves dispatch touched ONLY the bucket, never the whole corpus (the lookup invariant).
+ *   total       the library size (for the scanned << total assertion).
+ */
+function dispatch( lib, target, scopeFacts, opts ) {
+	opts = opts || {};
+	const { key, entries } = bucketOf(lib, target);
+	const weightOf = opts.weight || (( e ) => e.weight);
+	const matched = entries
+		.filter(( e ) => appConditionsHold(frontierOf(e.candidate), scopeFacts))
+		.sort(( a, b ) => weightOf(b) - weightOf(a));
+	return { key, candidates: matched, scanned: entries.length, total: lib.methods.length };
+}
+
+/**
+ * The dropped NACs of a candidate at a site = the application-conditions that FAIL (so dispatch would drop it). The
+ * SAME predicates as `appConditionsHold` (`require` by PRESENCE — engine present-not-truthy, finding #32; `assert` by
+ * `holdsAtoms`), so the loosened path and the exact path never disagree. NEVER use `contract.satisfies` for the require
+ * half — it tests truthiness and disagrees on present-falsy keys (Laurie confront pt2). Empty ⇒ the appConditions hold.
+ */
+function droppedNACs( frontier, scopeFacts ) {
+	const ac = (frontier && frontier.appConditions) || {}, facts = scopeFacts || {};
+	const require = [], assert = [];
+	for ( const k of (ac.require || []) ) if ( !(k in facts) ) require.push(k);
+	for ( const a of (ac.assert || []) ) if ( typeof a === 'string' && a.trim() && !holdsAtoms(facts, a) ) assert.push(a);
+	return { require, assert };
+}
+
+/**
+ * §6.2 INTERFACE-ONLY (loosened) dispatch — the FUZZY-RECALL arm of the library (spec §3.4, refined by the Laurie
+ * confront). Same O(1) `libraryKey` bucket as `dispatch` (the structural interface — NEVER widened: fuzzing it is the
+ * GPTCache false-merge / K1 defeat, pt4), but instead of DROPPING the NAC-failing in-bucket candidates it SURFACES them
+ * as `proposals` — ADAPT-SKELETON sources (NOT replay candidates). The controller (adapt.js#adaptOrForge, interfaceRecall)
+ * re-forges the differing content into a NEW method with SITE-derived appConditions, then the EXACT verify gates THAT
+ * method's own contract — so a proposal can only MISS (→ fresh forge) or be REJECTED, never write an unsound fact.
+ * @returns { key, exact, proposals:[{candidate,weight,key,droppedNACs,dropCount}], scanned, total }
+ *   exact      — the bucket entries whose appConditions HOLD (== `dispatch` candidates), weight-ranked.
+ *   proposals  — NAC-failing in-bucket donors, ranked by VERSION-SPACE SPECIFICITY (fewest NACs dropped first, the
+ *                least-adaptation climb; weight tie-break), capped at opts.k (default 3).
+ */
+function dispatchInterface( lib, target, scopeFacts, opts ) {
+	opts = opts || {};
+	const { key, entries } = bucketOf(lib, target);
+	const weightOf = opts.weight || (( e ) => e.weight);
+	const exact = [], proposals = [];
+	for ( const e of entries ) {
+		const dropped = droppedNACs(frontierOf(e.candidate), scopeFacts);
+		if ( !dropped.require.length && !dropped.assert.length ) exact.push(e);
+		else proposals.push(Object.assign({}, e, { droppedNACs: dropped, dropCount: dropped.require.length + dropped.assert.length }));
+	}
+	exact.sort(( a, b ) => weightOf(b) - weightOf(a));
+	proposals.sort(( a, b ) => (a.dropCount - b.dropCount) || (weightOf(b) - weightOf(a)));
+	return { key, exact, proposals: proposals.slice(0, opts.k == null ? 3 : opts.k), scanned: entries.length, total: lib.methods.length };
+}
+
+/**
+ * DRIFT-side invalidation at the CATALOG grain — the companion of master-loop's `drift()` (which only
+ * evicts the exact-result cache + recall index). Without it, a drifted problem's next FORGE would
+ * re-dispatch the SAME stale method and re-`hit` its template at 0 calls — resurrecting exactly what
+ * drift invalidated (the correct-on-drift claim breaks). This deletes the template keyed by THIS
+ * site's signature from every in-bucket candidate: the stale unit only — the method skeleton, its
+ * other signature classes, and its class knowledge (frontier/contract/appConditions) survive, so the
+ * next solve re-adapts/re-forges just the violated entry (and re-indexes a fresh template).
+ * @param target      { frontier, signatureKeys } | { libraryKey }  — as `dispatch`.
+ * @param scopeFacts  the drifted call-site facts (the signature source).
+ * @returns { key, invalidated:[{ id, sig }] }
+ */
+function invalidateTemplate( lib, target, scopeFacts ) {
+	const { key, entries } = bucketOf(lib, target);
+	const invalidated = [];
+	for ( const e of entries ) {
+		const cand = e.candidate || {};
+		const proj = {};
+		for ( const k of (cand.signatureKeys || []) ) if ( scopeFacts && k in scopeFacts ) proj[k] = scopeFacts[k];
+		const sig = digest(proj);
+		if ( cand.templatesBySig && sig in cand.templatesBySig ) {
+			delete cand.templatesBySig[sig];
+			invalidated.push({ id: cand.schema && cand.schema._id, sig });
+		}
+	}
+	return { key, invalidated };
+}
+
+module.exports = { makeLibrary, indexMethod, bucketOf, appConditionsHold, dispatch, dispatchInterface, droppedNACs, frontierOf, invalidateTemplate };

package/lib/authoring/lifecycle.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';
+/**
+ * lifecycle — the UNIFIED plasticity ledger (host-side, ZERO-CORE; study
+ * doc/WIP/studies/2026-06-26-…, pass 4).
+ *
+ * Every concept (a mined mini-NN, an LLM-calling expert, a hand-written rule) carries ONE
+ * scalar — its **plasticity** p ∈ [0,1] — the unified creativity/learning knob:
+ *   p = 1  fully plastic   — learning ON / high creativity (NN: noise+lr; LLM: high temperature)
+ *   p = 0  frozen          — deterministic, memo-perfect, the consolidated spine (temperature 0)
+ *   0<p<1  partial          — the "personality" regime (some creativity retained)
+ * The discrete regimes {plastic, probationary, frozen} are just the rounding/banding of p.
+ *
+ * Consolidation = Complementary-Learning-Systems annealing: a concept is born plastic and p
+ * decays toward 0 as its reliability is PROVEN (the success of the derivations it's in, snapped
+ * to a band via stats.bandOf). A concept that doesn't prove out stays plastic (keeps exploring);
+ * a proven one freezes (joins the stable, auditable, memo-hot spine).
+ *
+ * DISCIPLINE (K1): plasticity lives HERE, in the ledger — it MODULATES a provider (temperature,
+ * learning-rate, exploration noise) and the host's promotion decisions; it is NEVER a fact that
+ * gates applicability (a continuous gate would churn the memo). And `record(name, ok)` takes the
+ * GENUINE outcome — a retraction that was the intended iterative trial (#15) is not a failure;
+ * the host decides `ok`, the ledger only tallies.
+ *
+ *   const lc = createLifecycle();
+ *   lc.register('Crystal_A_B');            // born plastic
+ *   lc.record('Crystal_A_B', verifiedOk);  // each verified outcome anneals p
+ *   const temp = lc.plasticity('Crystal_A_B');  // thread into the provider (LLM temp / NN noise)
+ */
+const { bandOf } = require('../providers/stats.js');
+
+const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+
+function createLifecycle( opts ) {
+	opts = opts || {};
+	const minTrials = opts.minTrials == null ? 2 : opts.minTrials;  // explore until there's evidence
+	const maxRank   = opts.maxRank == null ? 3 : opts.maxRank;       // bandOf's top rank (certain)
+	const bands     = opts.bands;
+	// Default anneal: plastic (1) until enough trials, then p decays with the snapped reliability
+	// band — unproven/low stays plastic, 'certain' freezes (p=0). Override via opts.anneal(rep).
+	const anneal = opts.anneal || function ( rep ) {
+		if ( rep.trials < minTrials ) return 1;
+		return clamp01(1 - rep.rank / maxRank);
+	};
+
+	const led = {};   // name -> { successes, trials, p }
+
+	function rep( name ) {
+		const e = led[name] || { successes: 0, trials: 0 };
+		const theta = e.trials ? e.successes / e.trials : 0;
+		const b = bandOf(theta, bands);
+		return { successes: e.successes, trials: e.trials, theta: theta, rank: b.rank, label: b.label };
+	}
+
+	return {
+		/** Register a concept — born fully plastic (p=1) unless opts.p0 given. */
+		register: function ( name, o ) { led[name] = { successes: 0, trials: 0, p: (o && o.p0 != null) ? clamp01(o.p0) : 1 }; return this; },
+		/** Record a GENUINE outcome; re-anneals plasticity. */
+		record: function ( name, ok ) {
+			const e = led[name] || (led[name] = { successes: 0, trials: 0, p: 1 });
+			e.trials++; if ( ok ) e.successes++;
+			e.p = anneal(rep(name));
+			return this;
+		},
+		/** The unified plasticity knob p∈[0,1] (default 1 for an unknown concept). */
+		plasticity: function ( name ) { return led[name] ? led[name].p : 1; },
+		/** The rounded regime of p — a convenience view, not a separate state. */
+		regime: function ( name ) { const p = this.plasticity(name); return p >= 0.75 ? 'plastic' : p < 0.25 ? 'frozen' : 'probationary'; },
+		/** {successes, trials, theta, rank, label} — the evidence behind p. */
+		reputation: function ( name ) { return rep(name); },
+		/** Snapshot of the whole pool. */
+		all: function () { const o = {}; for ( const k in led ) o[k] = { p: led[k].p, regime: this.regime(k), reputation: rep(k) }; return o; },
+	};
+}
+
+module.exports = { createLifecycle };