skynet-graph 1.2.0

package/lib/studio/public/app.js

@@ -0,0 +1,310 @@
+/*
+ * 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/>.
+ */
+import React, { useState, useEffect, useRef } from 'react';
+import { createRoot } from 'react-dom/client';
+import { html } from 'htm/react';
+import { connect } from '/ws.js';
+import { GraphCanvas, LAYOUT_NAMES } from '/components/GraphCanvas.js';
+import { Inspector } from '/components/Inspector.js';
+import { Timeline, DiffPanel } from '/components/Timeline.js';
+import { ConceptTree } from '/components/ConceptTree.js';
+import { ConceptEditor } from '/components/ConceptEditor.js';
+import { ForkTree } from '/components/ForkTree.js';
+import { TilingOverlay } from '/components/TilingOverlay.js';
+import { PromptConsole } from '/components/PromptConsole.js';
+import { GrammarGraph } from '/components/GrammarGraph.js';
+import { CorpusPanel } from '/components/CorpusPanel.js';
+import { ProviderTrace } from '/components/ProviderTrace.js';
+import { SessionSplit } from '/components/SessionSplit.js';
+import { LearningPanel } from '/components/LearningPanel.js';
+
+// a demo seed so you can watch a graph develop with one click
+const DEMO_SEED = { conceptMaps: [
+	{ _id: 'a', Node: true, Position: { lat: 48.85, lng: 2.35 } },
+	{ _id: 'b', Node: true, Position: { lat: 1.35, lng: 103.8 } },
+	{ _id: 's', Segment: true, originNode: 'a', targetNode: 'b' }
+] };
+
+function App() {
+	const [status, setStatus] = useState('connecting');
+	const [corpora, setCorpora] = useState([]);
+	const [corpus, setCorpus] = useState('');
+	const [graph, setGraph] = useState({ objects: [], currentRev: 0, revCount: 0, revs: [] });
+	const [applies, setApplies] = useState([]);
+	const [lastApply, setLastApply] = useState(null);
+	const [selectedId, setSelectedId] = useState(null);
+	const [layout, setLayout] = useState('elk');
+	const [relayout, setRelayout] = useState(0);
+	const [diffResult, setDiffResult] = useState(null);
+	const [conceptTree, setConceptTree] = useState({});
+	const [editing, setEditing] = useState(null);
+	const valTimer = useRef(null);                                   // debounce timer for in-editor live ref-checking
+	const [sessionId, setSessionId] = useState('root');
+	const [forks, setForks] = useState({ root: { id: 'root', parent: null } });
+	const [tiling, setTiling] = useState(null);
+	const [promptProgress, setPromptProgress] = useState([]);
+	const [promptAnswer, setPromptAnswer] = useState('');
+	const [promptRunning, setPromptRunning] = useState(false);
+	const [promptError, setPromptError] = useState('');
+	const [view, setView] = useState('data');         // 'data' (instance graph) | 'grammar' (concepts↔facts) | 'learning' (lattice registry)
+	const [grammar, setGrammar] = useState(null);
+	const [learning, setLearning] = useState(null);           // { registry, rings } — the LearningPanel readout
+	const [learnVerdict, setLearnVerdict] = useState(null);   // the last gate verdict { ok, text }
+	const [manifest, setManifest] = useState(null);
+	const [trace, setTrace] = useState([]);
+	const [lastRetract, setLastRetract] = useState(null);
+	const [split, setSplit] = useState(null);          // { parentId, forkId, parentObjects, forkObjects, preview }
+	const api = useRef(null);
+	const sessionRef = useRef('root'); // the active session — events for others are ignored
+
+	useEffect(() => {
+		const c = connect('ws://' + location.host, ( evt ) => {
+			if ( evt.type === 'forks' ) { setForks(evt.payload); return; }
+			if ( evt.sessionId && evt.sessionId !== sessionRef.current ) return; // not the active session
+			if ( evt.type === 'state' ) setGraph(evt.payload);
+			else if ( evt.type === 'conceptApply' ) { setApplies(( a ) => [...a, evt.payload]); setLastApply(evt.payload); }
+			else if ( evt.type === 'promptProgress' ) setPromptProgress(( p ) => [...p, evt.payload]);
+			else if ( evt.type === 'promptAnswer' ) { setPromptAnswer(evt.payload.answer); setPromptRunning(false); }
+			else if ( evt.type === 'retract' ) { setLastRetract(evt.payload); try { (window.__sgRetracts = window.__sgRetracts || []).push(evt.payload); } catch ( e ) {} }
+		});
+		c.onStatus(setStatus);
+		api.current = c;
+		try { window.__sgApi = c; } catch ( e ) {} // test hook (puppeteer)
+		c.call('listCorpora').then(setCorpora);
+	}, []);
+
+	const sid = () => sessionRef.current;
+
+	async function loadCorpus( name, seed ) {
+		const c = corpora.find(( x ) => x.name === name);
+		if ( !c ) return;
+		sessionRef.current = 'root'; setSessionId('root');
+		setForks({ root: { id: 'root', parent: null } });
+		setCorpus(name);
+		setApplies([]); setLastApply(null); setSelectedId(null);
+		await api.current.call('loadCorpus', { conceptsDir: c.dir, builtins: true, seed });
+		setGraph(await api.current.call('state', {}, 'root'));
+		setConceptTree(await api.current.call('conceptTree', {}, 'root'));
+		api.current.call('forkPlan', {}, 'root').then(setTiling).catch(() => setTiling(null));
+		refreshGrammar('root');
+		refreshTrace();
+	}
+
+	async function refreshGrammar( id ) {
+		try {
+			setGrammar(await api.current.call('grammarGraph', {}, id || sid()));
+			setManifest(await api.current.call('corpusManifest', { meta: { name: corpus || id } }, id || sid()));
+		} catch ( e ) { setGrammar(null); setManifest(null); }
+	}
+	async function refreshTrace() {
+		try { setTrace(await api.current.call('providerTrace', { n: 80 }, sid())); } catch ( e ) { setTrace([]); }
+	}
+
+	// --- learning (the typed lattice registry — every alias goes through THE admission gate) ---
+	async function refreshLearning( id ) {
+		try { setLearning(await api.current.call('registry', {}, id || sid())); } catch ( e ) { setLearning(null); }
+	}
+	async function declareKey( key, en ) {
+		setLearning(await api.current.call('declareKey', { key, enum: en }, sid()));
+		setLearnVerdict(null);
+	}
+	async function proposeAlias( key, member, alias ) {
+		const r = await api.current.call('proposeAlias', { key, member, alias }, sid());
+		setLearnVerdict(r.admitted.length
+			? { ok: true, text: 'ADMITTED — ' + alias + ' → ' + member + ' (gate: member ∈ enum ∧ confluence)' }
+			: { ok: false, text: 'REJECTED — ' + (r.rejected[0] && r.rejected[0].reason || 'gate refused') });
+		try { window.__sgLastVerdict = r; } catch ( e ) {}   // test hook (puppeteer)
+		await refreshLearning();
+	}
+	async function retractAlias( key, alias ) {
+		const r = await api.current.call('retractAlias', { key, alias }, sid());
+		setLearnVerdict({ ok: true, text: (r.retracted ? 'RETRACTED — ' : 'no-op — ') + alias + (r.member ? ' (was → ' + r.member + ')' : '') });
+		await refreshLearning();
+	}
+
+	// --- corpus exchange (.sgc) ---
+	async function exportCorpus() {
+		const bundle = await api.current.call('exportCorpus', { meta: { name: corpus || 'corpus', version: '1.0.0' } }, sid());
+		try { window.__sgLastBundle = bundle; } catch ( e ) {}
+		try {
+			const blob = new Blob([JSON.stringify(bundle, null, 2)], { type: 'application/json' });
+			const a = document.createElement('a');
+			a.href = URL.createObjectURL(blob); a.download = (bundle.manifest && bundle.manifest.name || 'corpus') + '.sgc';
+			a.click(); URL.revokeObjectURL(a.href);
+		} catch ( e ) {}
+		return bundle;
+	}
+	async function importCorpus( bundle, seed ) {
+		sessionRef.current = 'root'; setSessionId('root');
+		setForks({ root: { id: 'root', parent: null } });
+		setApplies([]); setLastApply(null); setSelectedId(null);
+		const res = await api.current.call('importCorpus', { bundle, opts: { builtins: true, seed } }, 'root');
+		if ( !res.ok ) { setPromptError('import failed: ' + (res.errors || []).map(( e ) => e.message).join('; ')); return res; }
+		setCorpus((bundle.manifest && bundle.manifest.name) || 'imported');
+		setGraph(await api.current.call('state', {}, 'root'));
+		setConceptTree(await api.current.call('conceptTree', {}, 'root'));
+		refreshGrammar('root');
+		return res;
+	}
+
+	// --- sub-graph split (parent ↔ fork side by side, with a merge preview) ---
+	async function openSplit() {
+		const forkId = sid();
+		if ( forkId === 'root' ) return;
+		const parentId = (forks[forkId] && forks[forkId].parent) || 'root';
+		const [parentObjects, forkState] = await Promise.all([
+			api.current.call('state', {}, parentId).then(( s ) => s.objects),
+			api.current.call('state', {}, forkId)
+		]);
+		const preview = await api.current.call('mergePreview', { template: { $$_id: forkId, forkResult: true }, opts: {} }, forkId).catch(() => null);
+		setSplit({ parentId, forkId, parentObjects, forkObjects: forkState.objects, preview });
+	}
+
+	async function selectSession( id ) {
+		sessionRef.current = id; setSessionId(id);
+		setApplies([]); setLastApply(null); setSelectedId(null);
+		setGraph(await api.current.call('state', {}, id));
+		refreshGrammar(id);
+	}
+	async function doFork() {
+		const { childId } = await api.current.call('fork', {}, sid());
+		await selectSession(childId);
+	}
+	async function doMerge( childId ) {
+		const parent = (forks[childId] && forks[childId].parent) || 'root';
+		await api.current.call('merge', { childId, targetId: childId }, parent); // forkResult lands on a <childId> node
+		await selectSession(parent);
+	}
+
+	async function runPrompt( text ) {
+		setPromptProgress([]); setPromptAnswer(''); setPromptError(''); setPromptRunning(true);
+		setApplies([]); setLastApply(null); setSelectedId(null);
+		try { await api.current.call('prompt', { text }, sid()); }
+		catch ( e ) { setPromptError(e.message); setPromptRunning(false); }
+	}
+
+	async function openEditor( name ) {
+		const schema = await api.current.call('getConcept', { nameOrId: name }, sid());
+		setEditing({ name, text: JSON.stringify(schema || {}, null, 2), validation: null });
+	}
+	function editorChange( text ) {
+		setEditing(( e ) => ({ ...e, text, validation: null }));
+		// in-editor ref-checking (track 4): debounce-validate the schema live as the operator types — reuses the
+		// author-time validator (unknown-ref / prose-on-dependency / unparseable-expr checks) so mistakes surface inline.
+		if ( valTimer.current ) clearTimeout(valTimer.current);
+		valTimer.current = setTimeout(async () => {
+			let schema;
+			try { schema = JSON.parse(text); }
+			catch ( err ) { return setEditing(( e ) => e && { ...e, validation: { ok: false, errors: ['invalid JSON: ' + err.message] } }); }
+			const v = await api.current.call('validateConcept', { schema }, sid());
+			setEditing(( e ) => e && { ...e, validation: v });
+		}, 400);
+	}
+	async function editorValidate() {
+		let schema;
+		try { schema = JSON.parse(editing.text); }
+		catch ( err ) { return setEditing(( e ) => ({ ...e, validation: { ok: false, errors: ['invalid JSON: ' + err.message] } })); }
+		const v = await api.current.call('validateConcept', { schema }, sid());
+		setEditing(( e ) => ({ ...e, validation: v }));
+	}
+	async function editorApply() {
+		let schema;
+		try { schema = JSON.parse(editing.text); } catch ( err ) { return; }
+		await api.current.call('patchConcept', { nameOrId: editing.name, updates: schema }, sid());
+		setEditing(null);
+		setGraph(await api.current.call('state', {}, sid()));
+	}
+	// CRUD completion: remove the concept (+ its subtree); un-casts it everywhere, then refresh the tree + grammar.
+	async function editorDelete() {
+		if ( !editing ) return;
+		await api.current.call('deleteConcept', { nameOrId: editing.name }, sid());
+		setEditing(null);
+		setGraph(await api.current.call('state', {}, sid()));
+		setConceptTree(await api.current.call('conceptTree', {}, sid()));
+		refreshGrammar(sid());
+	}
+
+	async function rollback( rev ) {
+		await api.current.call('rollback', { rev }, sid());
+		setGraph(await api.current.call('state', {}, sid()));
+	}
+	async function showDiff( a, b ) {
+		setDiffResult({ a, b, d: await api.current.call('diff', { a, b }, sid()) });
+	}
+
+	const selected = selectedId && graph.objects.find(( o ) => o._id === selectedId);
+
+	return html`
+		<div class="studio">
+			<header class="toolbar">
+				<strong>sg studio</strong>
+				<select value=${corpus} onChange=${( e ) => loadCorpus(e.target.value)}>
+					<option value="" disabled>corpus…</option>
+					${corpora.map(( c ) => html`<option key=${c.name} value=${c.name}>${c.name}</option>`)}
+				</select>
+				<button disabled=${!corpus} onClick=${() => loadCorpus(corpus, DEMO_SEED)}>seed demo</button>
+				<button disabled=${!corpus} onClick=${() => loadCorpus(corpus)}>reset</button>
+				<span class="sep"></span>
+				<label class="lyt">layout
+					<select value=${layout} onChange=${( e ) => setLayout(e.target.value)}>
+						${LAYOUT_NAMES.map(( n ) => html`<option key=${n} value=${n}>${n}</option>`)}
+					</select>
+				</label>
+				<button title="re-run layout" onClick=${() => setRelayout(( r ) => r + 1)}>↻</button>
+				<span class="sep"></span>
+				<div class="viewtoggle">
+					<button class=${view === 'data' ? 'on' : ''} onClick=${() => setView('data')}>data</button>
+					<button class=${view === 'grammar' ? 'on' : ''} onClick=${() => { setView('grammar'); if ( !grammar ) refreshGrammar(); }}>grammar</button>
+					<button class=${view === 'learning' ? 'on' : ''} onClick=${() => { setView('learning'); refreshLearning(); }}>learning</button>
+				</div>
+				<button title="open two sub-graphs side by side" disabled=${sessionId === 'root'} onClick=${openSplit}>split</button>
+				<span class="status ${status}">● ${status}</span>
+				<span class="rev">${sessionId !== 'root' ? sessionId + ' · ' : ''}rev ${graph.currentRev}/${graph.revCount} · ${graph.objects.length} obj</span>
+			</header>
+			<${Timeline} revs=${graph.revs} currentRev=${graph.currentRev} onRollback=${rollback} onDiff=${showDiff} />
+			<main class="panels">
+				<${ConceptTree} tree=${conceptTree} onEdit=${openEditor} />
+				${view === 'learning'
+					? html`<${LearningPanel} learning=${learning} verdict=${learnVerdict} onDeclare=${declareKey} onPropose=${proposeAlias} onRetract=${retractAlias} />`
+					: view === 'grammar'
+						? html`<${GrammarGraph} grammar=${grammar} onSelect=${( id ) => setSelectedId(null)} />`
+						: html`<${GraphCanvas} objects=${graph.objects} lastApply=${lastApply} lastRetract=${lastRetract} onSelect=${setSelectedId} layout=${layout} relayout=${relayout} />`}
+				${view === 'grammar'
+					? html`<${CorpusPanel} manifest=${manifest} grammar=${grammar} onExport=${exportCorpus} onImport=${importCorpus} />`
+					: html`<${Inspector} object=${selected} applies=${applies} />`}
+			</main>
+			<footer class="bottom">
+				<div class="trace-wrap">
+					<h3>trace</h3>
+					<div class="tracerow">
+						${applies.slice(-40).map(( r, i ) => html`
+							<span key=${i} class="tchip"><b>${r.conceptName}</b>→${r.targetId}</span>`)}
+					</div>
+				</div>
+				<${ForkTree} forks=${forks} active=${sessionId} onFork=${doFork} onSelect=${selectSession} onMerge=${doMerge} />
+				<${TilingOverlay} plan=${tiling} />
+				<${ProviderTrace} records=${trace} onRefresh=${refreshTrace} />
+			</footer>
+			<${PromptConsole} onRun=${runPrompt} progress=${promptProgress} answer=${promptAnswer} running=${promptRunning} error=${promptError} />
+			<${ConceptEditor} editing=${editing} onChange=${editorChange} onValidate=${editorValidate} onApply=${editorApply} onDelete=${editorDelete} onClose=${() => setEditing(null)} />
+			<${DiffPanel} result=${diffResult} onClose=${() => setDiffResult(null)} />
+			<${SessionSplit} open=${!!split} parentId=${split && split.parentId} forkId=${split && split.forkId} parentObjects=${split && split.parentObjects} forkObjects=${split && split.forkObjects} preview=${split && split.preview} onClose=${() => setSplit(null)} onMerge=${async () => { if ( split ) { await doMerge(split.forkId); setSplit(null); } }} />
+		</div>`;
+}
+
+createRoot(document.getElementById('app')).render(html`<${App} />`);

package/lib/studio/public/components/ConceptEditor.js

@@ -0,0 +1,43 @@
+/*
+ * 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/>.
+ */
+import React from 'react';
+import { html } from 'htm/react';
+
+// modal to edit a concept's schema JSON, validate it (author-time), then patch it
+// live — the re-eval cascade is visible on the canvas.
+export function ConceptEditor( { editing, onChange, onValidate, onApply, onDelete, onClose } ) {
+	if ( !editing ) return null;
+	const { name, text, validation } = editing;
+	return html`
+		<div class="editor-modal" onClick=${( e ) => { if ( e.target.classList.contains('editor-modal') ) onClose(); }}>
+			<div class="em-box">
+				<div class="em-head">edit concept <b>${name}</b><button onClick=${onClose}>✕</button></div>
+				<textarea class="em-text" spellcheck="false" value=${text} onInput=${( e ) => onChange(e.target.value)}></textarea>
+				${validation ? html`
+					<div class="em-validation ${validation.ok ? 'ok' : 'bad'}">
+						${validation.ok ? '✓ valid' : '✗ ' + (validation.errors || []).join('; ')}
+						${(validation.warnings || []).length ? html`<div class="em-warn">⚠ ${validation.warnings.join('; ')}</div>` : null}
+					</div>` : null}
+				<div class="em-actions">
+					<button onClick=${onValidate}>validate</button>
+					${onDelete ? html`<button class="danger" onClick=${() => { if ( window.confirm('Delete concept "' + name + '" (and its subtree)? It will un-cast everywhere.') ) onDelete(); }}>delete</button>` : null}
+					<button class="primary" disabled=${validation && !validation.ok} onClick=${onApply}>apply (patch)</button>
+				</div>
+			</div>
+		</div>`;
+}

package/lib/studio/public/components/ConceptTree.js

@@ -0,0 +1,43 @@
+/*
+ * 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/>.
+ */
+import React from 'react';
+import { html } from 'htm/react';
+
+function children( node, onEdit, depth ) {
+	const kids = node && node.childConcepts;
+	if ( !kids ) return null;
+	return Object.keys(kids).map(( name ) => html`
+		<div key=${name} class="cnode">
+			<span class="cname" style=${{ paddingLeft: (depth * 12) + 'px' }} onClick=${() => onEdit(name)}>${name}</span>
+			${children(kids[name], onEdit, depth + 1)}
+		</div>`);
+}
+
+// left panel: the loaded concept corpus (sets -> nested concepts); click to edit.
+export function ConceptTree( { tree, onEdit } ) {
+	const sets = Object.keys(tree || {});
+	return html`
+		<aside class="concepts">
+			<h3>concepts</h3>
+			${sets.length === 0 ? html`<div class="empty">load a corpus</div>` : sets.map(( set ) => html`
+				<div key=${set} class="cset">
+					<div class="csetname">${set}</div>
+					${children(tree[set], onEdit, 0)}
+				</div>`)}
+		</aside>`;
+}

package/lib/studio/public/components/CorpusPanel.js

@@ -0,0 +1,68 @@
+/*
+ * 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/>.
+ */
+import React, { useRef } from 'react';
+import { html } from 'htm/react';
+
+// The corpus side-panel for the grammar view: the derived manifest (produces/consumes alphabet,
+// required providers), the cross-corpus links + silent writer-collisions, a polarity legend, and
+// the .sgc import/export controls. `manifest`/`grammar` come from the corpusManifest/grammarGraph
+// ops; onExport()/onImport(bundle) round-trip the portable bundle.
+export function CorpusPanel( { manifest, grammar, onExport, onImport } ) {
+	const fileRef = useRef(null);
+	const g = grammar || {};
+	const m = manifest || {};
+
+	function pickFile( e ) {
+		const f = e.target.files && e.target.files[0];
+		if ( !f ) return;
+		const r = new FileReader();
+		r.onload = () => { try { onImport(JSON.parse(r.result)); } catch ( err ) { alert('bad .sgc: ' + err.message); } };
+		r.readAsText(f);
+		e.target.value = '';
+	}
+
+	return html`
+		<aside class="corpus-panel">
+			<div class="cp-actions">
+				<button class="cp-export" onClick=${onExport}>export .sgc</button>
+				<button class="cp-import" onClick=${() => fileRef.current && fileRef.current.click()}>import .sgc</button>
+				<input type="file" accept=".sgc,.json" ref=${fileRef} style=${{ display: 'none' }} onChange=${pickFile} />
+			</div>
+			<div class="cp-legend">
+				<span class="lg lg-w">writes</span><span class="lg lg-rp">reads +</span>
+				<span class="lg lg-rn">reads − (defeasance)</span><span class="lg lg-sep">separator</span>
+			</div>
+			${m.name ? html`
+				<div class="cp-manifest">
+					<div class="cp-row"><b>${m.name}</b> <span class="cp-v">v${m.version}</span> · ${m.conceptCount} concepts</div>
+					<div class="cp-row">providers: ${(m.providersRequired || []).length ? (m.providersRequired || []).map(( p ) => html`<span key=${p} class="cp-prov">${p}</span>`) : '∅'}</div>
+					<div class="cp-row">produces: <span class="cp-alpha">${(m.alphabet && m.alphabet.produces || []).join(', ')}</span></div>
+					<div class="cp-row">consumes: <span class="cp-alpha">${(m.alphabet && m.alphabet.consumes || []).join(', ') || '∅'}</span></div>
+				</div>` : null}
+			${(g.crossCorpus || []).length ? html`
+				<div class="cp-cross">
+					<h4>cross-corpus links</h4>
+					${g.crossCorpus.map(( l, i ) => html`<div key=${i} class="cp-link">${l.fromSet} <b>${l.fact}</b> → ${l.toSet}</div>`)}
+				</div>` : null}
+			${(g.collisions || []).length ? html`
+				<div class="cp-coll">
+					<h4>⚠ fact collisions</h4>
+					${g.collisions.map(( c, i ) => html`<div key=${i} class="cp-clash"><b>${c.fact}</b> written by ${c.sets.join(' & ')}</div>`)}
+				</div>` : null}
+		</aside>`;
+}

package/lib/studio/public/components/ForkTree.js

@@ -0,0 +1,36 @@
+/*
+ * 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/>.
+ */
+import React from 'react';
+import { html } from 'htm/react';
+
+// the session tree: fork the active graph into an independent child (a sub-agent),
+// switch between sessions, merge a fork's result back into its parent.
+export function ForkTree( { forks, active, onFork, onSelect, onMerge } ) {
+	const ids = Object.keys(forks || {});
+	return html`
+		<div class="forks">
+			<div class="fk-head">forks<button onClick=${onFork} title="fork the active session">+ fork</button></div>
+			<div class="fk-list">
+				${ids.map(( id ) => html`
+					<div key=${id} class=${'fk-item' + (id === active ? ' active' : '')}>
+						<span class="fk-id" onClick=${() => onSelect(id)}>${id}${forks[id].parent ? '' : ' · root'}</span>
+						${forks[id].parent ? html`<button class="fk-merge" title="merge into parent" onClick=${() => onMerge(id)}>merge ↩</button>` : null}
+					</div>`)}
+			</div>
+		</div>`;
+}

package/lib/studio/public/components/GrammarGraph.js

@@ -0,0 +1,99 @@
+/*
+ * 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/>.
+ */
+import React, { useRef, useEffect } from 'react';
+import { html } from 'htm/react';
+import cytoscape from 'cytoscape';
+import fcose from 'cytoscape-fcose';
+
+let _reg = false;
+function register() { if ( _reg ) return; try { cytoscape.use(fcose); } catch ( e ) {} _reg = true; }
+
+// per-set hue so concepts from different corpora are visually distinct
+const SET_HUES = ['#6ea8fe', '#3ad29f', '#f5a524', '#c084fc', '#fb7185', '#22d3ee'];
+function setColor( sets, set ) { const i = sets.indexOf(set); return SET_HUES[(i < 0 ? 0 : i) % SET_HUES.length]; }
+
+// the second, orthogonal graph: concepts ↔ facts. A concept WRITES facts (green) and READS them
+// (blue = positive support, red dashed = a negated / defeasance dependency). Separator facts (the
+// tree-decomposition narrow waist) are highlighted as gold diamonds; entry-point facts are hollow.
+function toElements( g ) {
+	const sets = [...new Set(g.concepts.map(( c ) => c.set))].sort();
+	const seps = new Set((g.tiling && g.tiling.separators) || []);
+	const entry = new Set(g.entryPoints || []);
+	const els = [];
+	for ( const c of g.concepts )
+		els.push({ data: { id: 'c:' + c.name, label: c.name, kind: c.kind, color: setColor(sets, c.set) }, classes: 'concept kind-' + c.kind });
+	for ( const f of g.facts ) {
+		const cls = ['fact'];
+		if ( seps.has(f.key) ) cls.push('separator');
+		if ( entry.has(f.key) ) cls.push('entry');
+		els.push({ data: { id: 'f:' + f.key, label: f.key }, classes: cls.join(' ') });
+	}
+	const seen = new Set();
+	for ( const e of g.edges ) {
+		const a = e.kind === 'writes' ? 'c:' + e.concept : 'f:' + e.fact;
+		const b = e.kind === 'writes' ? 'f:' + e.fact : 'c:' + e.concept;
+		const cls = e.kind === 'writes' ? 'writes' : (e.polarity === '-' ? 'reads-neg' : 'reads-pos');
+		const id = cls + ':' + a + '>' + b;
+		if ( seen.has(id) ) continue;            // collapse duplicate read edges (assert+ensure on same fact)
+		seen.add(id);
+		els.push({ data: { id, source: a, target: b }, classes: cls });
+	}
+	return els;
+}
+
+const STYLE = [
+	{ selector: 'node.concept', style: { 'background-color': 'data(color)', 'label': 'data(label)', 'shape': 'round-rectangle', 'color': '#0f1419', 'font-size': '10px', 'font-weight': 'bold', 'text-valign': 'center', 'text-halign': 'center', 'width': 'label', 'height': 22, 'padding': '6px' } },
+	{ selector: 'node.kind-llm', style: { 'border-width': 2, 'border-color': '#fde047', 'border-style': 'double' } },
+	{ selector: 'node.kind-provider', style: { 'border-width': 2, 'border-color': '#0f1419' } },
+	{ selector: 'node.fact', style: { 'background-color': '#1f2733', 'label': 'data(label)', 'shape': 'ellipse', 'color': '#cdd6e0', 'font-size': '9px', 'text-valign': 'center', 'text-halign': 'center', 'width': 'label', 'height': 18, 'padding': '4px', 'border-width': 1, 'border-color': '#3a4757' } },
+	{ selector: 'node.entry', style: { 'background-opacity': 0.15, 'border-style': 'dashed' } },
+	{ selector: 'node.separator', style: { 'background-color': '#f5a524', 'shape': 'diamond', 'color': '#0f1419', 'border-width': 2, 'border-color': '#fff7e6' } },
+	{ selector: 'node:selected', style: { 'border-color': '#fff', 'border-width': 3 } },
+	{ selector: 'edge', style: { 'curve-style': 'bezier', 'target-arrow-shape': 'triangle', 'width': 1.5, 'arrow-scale': 0.8 } },
+	{ selector: 'edge.writes', style: { 'line-color': '#3ad29f', 'target-arrow-color': '#3ad29f' } },
+	{ selector: 'edge.reads-pos', style: { 'line-color': '#6ea8fe', 'target-arrow-color': '#6ea8fe' } },
+	{ selector: 'edge.reads-neg', style: { 'line-color': '#fb7185', 'target-arrow-color': '#fb7185', 'line-style': 'dashed' } }
+];
+
+const FCOSE = { name: 'fcose', animate: true, animationDuration: 350, randomize: true, padding: 40, nodeSeparation: 110, idealEdgeLength: 80 };
+
+export function GrammarGraph( { grammar, onSelect } ) {
+	const ref = useRef(null);
+	const cyRef = useRef(null);
+
+	useEffect(() => {
+		register();
+		const cy = cytoscape({ container: ref.current, style: STYLE, wheelSensitivity: 0.2 });
+		cy.on('tap', 'node', ( e ) => onSelect && onSelect(e.target.id()));
+		cyRef.current = cy;
+		try { window.__sgGrammarCy = cy; } catch ( e ) {} // puppeteer introspection hook
+		return () => cy.destroy();
+	}, []);
+
+	useEffect(() => {
+		const cy = cyRef.current;
+		if ( !cy ) return;
+		cy.elements().remove();
+		if ( grammar && grammar.concepts ) {
+			cy.add(toElements(grammar));
+			if ( cy.elements().length ) cy.layout(FCOSE).run();
+		}
+	}, [grammar]);
+
+	return html`<div class="cy grammar-cy" ref=${ref}></div>`;
+}