mindsmith 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# Mindsmith
+
+> **Pre-launch — nothing is field-adopted yet (rung 6/6 is empty on every bar below).**
+> We publish maturity per feature and keep refuted claims on the page. Honesty is the product's USP,
+> so it is also the documentation's. See [docs/honesty.html](docs/honesty.html).
+
+**Mindsmith is an external reasoning layer for your local LLM — an auditable critical mind, gated
+think-mode lanes, and verified-stock answers at zero frontier calls, from a mixture of certified
+graph-experts fronting your model. OpenAI-compatible endpoint + MCP tools over shareable `.sgc` rooms;
+nothing leaves your machine by default.**
+
+A small quantized gguf fits your VRAM, but quantization costs it judgment — and on its own it has no
+external check on its reasoning. Mindsmith, a thin surface over the
+[skynet-graph](https://github.com/9pings/skynet-graph) engine, hands the model tools it doesn't have
+alone: answers steered against a certified **method vocabulary** (covered queries served from verified
+local stock at 0 frontier calls); gated **assistant lanes** (`propose` / `hint` — an external think-mode
+that returns a tested verdict or refuses, never a guess); and an external **critical mind** (`critique` —
+weigh a question over a witness-gated pool of arguments, with an honest, certification-aware verdict).
+The judgment repair is measured on the same model at two quant levels (protocols in the engine repo):
+SQL covered queries low-quant **8→63 %** (high-quant reference 46→92 %, N=201) · finance-table traffic
+**7→62 %** (20→78 %, N=120) — zero big-model calls at runtime on the covered slice.
+
+No accounts, no catalog, no phone-home. Stocks live in a local **room** you own: build them with the
+engine's forge (0 false admissions across 3 datasets × 2 forge models; sha256 validation dossier per
+stock), freeze them, share them as files, import someone else's — a malformed bundle is refused at the
+gate, never written.
+
+## 60-second quickstart
+
+```bash
+# Pre-launch note: not on npm yet. Until the release:
+#   git clone <this repo> && cd mindsmith && npm install && npm test   # 26/26, GPU-free
+# Once published, the same commands work via:  npm i -g mindsmith   or   npx mindsmith
+
+# 1 — serve (embedded gguf as the escalation):
+FRONTIER_MODEL=/path/model.gguf mindsmith serve --room ./sgc
+# → mindsmith → http://127.0.0.1:4747/v1   (OpenAI-compatible)
+
+# 2 — point ANY OpenAI client at it (official SDKs, LangChain, Open WebUI, curl):
+#    baseURL = http://127.0.0.1:4747/v1     apiKey = anything
+curl -si http://127.0.0.1:4747/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -d '{"messages":[{"role":"user","content":"your question"}]}'
+# every completion carries provenance headers:
+#   x-sg-served-from: local|frontier · x-sg-arm · x-sg-cost · x-sg-coverage · x-sg-saved · x-sg-sgc-version
+
+# 3 — your stock rooms (local .sgc mini-repos, gate-checked):
+mindsmith rooms list                          # inventory: name@version, classes, sha256, ❄ frozen
+mindsmith rooms import ./fin-tables-stock.sgc # gate-checked (a bad bundle never lands)
+mindsmith rooms freeze fin-tables-stock       # writes the auditable sha256 dossier
+mindsmith rooms export fin-tables-stock ./out # bundle + dossier, ready to share
+
+# 4 — or as MCP tools for an agent host (Claude Code, any MCP client):
+claude mcp add mindsmith -- mindsmith mcp --routing routing.json
+# tools: ask · drift · metrics · lattice_load · hint · propose · critique
+```
+
+`GET /healthz` is the ops readout (no key, no query content): policy, configured vs reachable tiers,
+loaded `.sgc` versions, stock size.
+
+## Features × maturity
+
+Maturity uses a fixed 6-rung scale — 1 coherent idea · 2 design with pre-registered kill-gates ·
+3 mechanics proven · 4 measured at scale · 5 product-integrated · 6 field-adopted. Nothing is at 6:
+this is pre-launch. Scale details: [docs/honesty.html](docs/honesty.html).
+
+| Feature | Maturity | Measured | Docs |
+|---|---|---|---|
+| **F1 — Low-quant repair** (certified stock steers the model; covered → 0 frontier calls) | `█████░` 5/6 product-integrated | SQL 8→63 % (N=201) · finance tables 7→62 % (N=120) · forge 0 false admissions | [docs](docs/features.html#f1) |
+| **F4 — External think mode** (`propose` → gated verdict + blame + tested options; `hint` menu) | `█████░` 5/6 product-integrated | one dialogue round 17/24 → 24/24 at zero false admissions | [docs](docs/features.html#f4) |
+| **F5 — External critical mind** (`critique`: witness gate, anchored generation, honest verdict) | `█████░` 5/6 surface · campaign numbers at 4/6 | coverage 77 % vs 58 % (48 args) · certified perimeter 12/24 → 24/24 · 0 fabrication in negative controls | [docs](docs/features.html#f5) |
+| **F6 — Local `.sgc` rooms** (list/import/export/freeze, sha256 dossiers, engine-gated loads) | `█████░` 5/6 product-integrated | gate-checked import; loads never bypass the engine gates | [docs](docs/features.html#f6) |
+| **F2 — Piece-by-piece zoom** (typed DAG on big tasks) | `████░░` 4/6 measured — **library-only today, not surfaced here (the known gap)** | math word problems ×3.25 [2.4–4.8] · financial-table QA ×2.54 [1.96–3.5], 560 tasks | [docs](docs/features.html#f2-gap) |
+
+## Why not just…?
+
+- **…run a bigger model?** If it fits your VRAM, do. This exists for the model you *can* run:
+  certified-stock steering recovers most of what quantization broke (SQL 8→63 %, finance 7→62 %),
+  at 0 frontier calls on the covered slice.
+- **…use the model's think mode / a self-critique prompt?** The 2024-25 literature (and our own
+  3-form refutation) agree: self-critique underperforms *external* feedback with localized blame.
+  The `propose` gate and `critique` tool are that external feedback — structural, auditable, and
+  un-arguable-with (a forced write lands UNTRUSTED, never admitted).
+- **…RAG / a prompt library?** Retrieval trusts whatever is indexed. A room only admits what
+  passes the gate (0 false admissions measured at the forge), and every completion tells you
+  which slice you can trust (`x-sg-served-from`, `x-sg-coverage`).
+- **…an agent framework's memory?** None we checked reopens a task whose premise drifted; the
+  engine's typed task state retracts and reopens with the reason, at 0 model calls (surfaced here
+  via MCP `state_recall` / `plan_sync` on the engine side).
+
+## What actually runs
+
+- **`serve`** — `POST /v1/chat/completions`, `GET /v1/models`, `GET /healthz`. Default port 4747,
+  binds 127.0.0.1 on purpose. A covered query is served from verified local stock at 0 frontier calls;
+  a miss escalates (you always get an answer); the local side never fabricates — 0 hallucination by
+  construction on the covered slice.
+- **Escalation** — either a single frontier (`FRONTIER_MODEL=<path.gguf>` embedded, or `LLM_BASE=<url>`
+  any OpenAI-compatible endpoint), or **N-tier routing** (`--routing config.json`): ordered tiers, each
+  tagged with an egress class (`none` / `mid` / `frontier`), governed by a policy ceiling —
+  `no-egress` (default for routing configs) · `allow-mid` · `allow-all`. A query is **never** silently
+  sent to a forbidden tier: if the policy leaves nothing reachable, you get a typed `NO_REACHABLE_TIER`
+  refusal. The no-egress guarantee is enforced fail-closed on real sockets in the test suite, with a
+  negative control proving the guard has teeth.
+- **`mcp`** — the same verified stock + escalation over stdio (no HTTP socket). Tools:
+  `ask` (local-first, `{answer, source, cached, cost}`) · `drift` (invalidate a stale entry) ·
+  `metrics` (economy readout) · `lattice_load` (learn THROUGH the gate — the only registry write path) ·
+  `hint` (SOFT lane: advisory certified-shape menu, no guarantee attached) · `propose` (HARD lane: the
+  gate never yields; `force=true` records untrusted provenance, never admits) · `critique` (below).
+- **`rooms`** — `list | import <file> | export <name> <dest> | freeze <name>`. Import dry-loads the
+  bundle through the same gates the appliance uses; freeze writes the sha256 dossier that makes the
+  bundle a fixed, auditable reference.
+
+## The `critique` iteration contract
+
+`critique` runs the external critical mind on a question: declared viewpoints established through a
+witness gate over a statement pool, anchored generation of missing theses, a typed ledger, and a
+certification-aware verdict. The contract: **OPEN ledger points and an UNDECIDED verdict are a typed
+data request, not a dead end.** The tool cannot reach the web — the host (you, or your agent) gathers
+real statements that bear on the OPEN points, then calls `critique` again with `statements: [...]`
+(`"PRO: ..."` / `"CON: ..."` lines). The frame upgrades to MATERIAL and the margin can move honestly.
+A verdict is mechanical only at the measured margin bound (≥3 on free/declared frames, ≥2 on a
+certified perimeter); below it the deliverable is counts + coverage + an honest UNDECIDED — never a
+fake weighing.
+
+## Honest limits (what is NOT claimed)
+
+- **The guarantee is at stock admission, not at execution.** Runtime steering orients; a suggestion is
+  not a correctness proof. A runtime "trusted answers" cross-agreement tier was tested and **refuted**
+  — it was removed, and stays listed in [docs/honesty.html](docs/honesty.html).
+- **The win lives on the typed, recurrent slice of your traffic.** Coverage depends on your stocks;
+  forge yield is per-domain; amortization is a property of the domain's stereotypy.
+- **F2 zoom is not surfaced here.** The piece-by-piece decomposition is measured (rung 4/6) but
+  library-only in skynet-graph today; no MCP tool exposes it yet.
+- **`critique` bounds**: below the measured decidability margin the verdict is UNDECIDED by design;
+  entry templates are not yet form-robustness-tested; on FREE frames coverage is relative to the pool
+  (the payload says so).
+- Streaming is simulated; no per-tier timeout yet.
+- **Nothing is field-adopted (rung 6/6)** — no external replications yet. This is pre-launch.
+
+## Env / flags
+
+`FRONTIER_MODEL` (gguf, embedded) or `LLM_BASE` (any OpenAI-compatible endpoint) — the single-frontier
+escalation · `--routing <config.json>` / `$SG_ROUTING` (N-tier) + `--policy` / `$SG_POLICY`
+(`no-egress|allow-mid|allow-all`) · `LOCAL_MODEL` (gguf — semantic coverage: paraphrases hit the stock,
+opt-in) · `--room <dir>` (default `./sgc`) · `--store <f.json>` (durable cross-restart stock,
+default `.skynet-stock.json`) · `--port` (default 4747, binds 127.0.0.1).
+
+---
+
+AGPL-3.0-or-later · © 2026 Nathanael Braun · solo-author project ·
+engine: [github.com/9pings/skynet-graph](https://github.com/9pings/skynet-graph) ·
+docs site: [`docs/`](docs/) (GitHub Pages) ·
+**pre-launch — nothing is field-adopted yet (rung 6/6)**

package/bin/mindsmith

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+'use strict';
+// mindsmith — your low-quant local model, repaired and steered like a bigger one. Nothing leaves
+// the machine. An OpenAI-compatible endpoint over the skynet-graph engine + your local room of verified
+// `.sgc` stocks (community model: build/freeze/share/import your own — no catalog, no subscription).
+//
+//   mindsmith serve  [--port N] [--store <f.json>] [--room <dir>]
+//                             escalation, either:
+//                               N-tier routing: --routing <config.json> [--policy no-egress|allow-mid|allow-all]
+//                                               (tiers = backend presets + egress class; default no-egress)
+//                               single frontier: env FRONTIER_MODEL=<path.gguf> (embedded) | LLM_BASE (endpoint)
+//                             optional env LOCAL_MODEL=<path.gguf> (semantic coverage: paraphrases hit the stock)
+//   mindsmith mcp    same flags/env as serve, NO http socket — the MCP tool surface (stdio) over the
+//                             same verified stock + escalation; stdout = protocol.
+//                             Register:  claude mcp add mindsmith -- mindsmith mcp --routing <config.json>
+//   mindsmith rooms  list | import <file.sgc> | export <name> <destDir> | freeze <name>   [--room <dir>]
+//                             your local SGC room: inventory (sha256 + frozen dossiers), gate-checked import
+//                             (a malformed bundle is refused, never written), export with dossier, freeze
+//                             (writes the auditable sha256 dossier). Forge new stocks with `sg forge` (skynet-graph).
+const { createApp } = require('../lib/app.js');
+const rooms = require('../lib/rooms.js');
+const { resolveRouting } = require('../lib/serve-config.js');
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flag = ( n ) => { const i = argv.indexOf('--' + n); return i !== -1 ? argv[i + 1] : undefined; };
+const roomDir = flag('room') || flag('sgc') || 'sgc';
+
+// escalation resolution shared by serve + mcp: an N-tier routing config OR the legacy single frontier backend.
+function resolveEscalation( need ) {
+	const routing = resolveRouting(argv, process.env);
+	if ( routing ) return { tiers: routing.tiers, policy: routing.policy };
+	let frontierChat;
+	if ( process.env.FRONTIER_MODEL ) frontierChat = require('skynet-graph/lib/providers/llm-local.js').makeLocalAsk({ modelPath: process.env.FRONTIER_MODEL, reasoningBudget: 0 });
+	else if ( process.env.LLM_BASE ) frontierChat = require('skynet-graph/lib/providers/llm.js').makeAsk({ base: process.env.LLM_BASE, model: process.env.LLM_MODEL || 'default' });
+	else { console.error(need + ' needs an escalation: --routing <config.json>, or env FRONTIER_MODEL=<path.gguf> | LLM_BASE=<url>'); process.exit(1); }
+	return { frontierChat };
+}
+function buildApp( escalation, extra ) {
+	const localAsk = process.env.LOCAL_MODEL ? require('skynet-graph/lib/providers/llm-local.js').makeLocalAsk({ modelPath: process.env.LOCAL_MODEL, reasoningBudget: 0 }) : undefined;
+	return createApp(Object.assign({}, escalation, {
+		localAsk,
+		store: flag('store') || '.skynet-stock.json', sgcDir: roomDir,
+	}, extra));
+}
+
+if ( cmd === 'rooms' ) {
+	const sub = argv[1];
+	try {
+		if ( sub === 'list' || sub === undefined ) {
+			const rows = rooms.list(roomDir);
+			if ( !rows.length ) { console.log('(empty room: ' + roomDir + ' — import a .sgc, or forge one: sg forge …)'); process.exit(0); }
+			for ( const r of rows ) console.log(r.invalid
+				? '✗ ' + r.file + ' — INVALID: ' + r.invalid
+				: (r.frozen ? '❄ ' : '· ') + r.name + '@' + r.version + '  [' + r.kind + ', ' + r.classes + ' classes]  sha256 '
+					+ r.sha256.slice(0, 16) + '…  (' + r.file + (r.frozen ? ' + ' + r.dossier : '') + ')');
+		} else if ( sub === 'import' ) {
+			const r = rooms.importBundle(roomDir, argv[2] || '');
+			console.log('imported ' + r.name + '@' + r.version + ' [' + r.kind + ', ' + r.classes + ' classes] → ' + roomDir + '/' + r.file + '  sha256 ' + r.sha256.slice(0, 16) + '…');
+		} else if ( sub === 'export' ) {
+			const r = rooms.exportBundle(roomDir, argv[2] || '', argv[3] || '.');
+			console.log('exported ' + r.exported.join(' + ') + ' → ' + (argv[3] || '.'));
+		} else if ( sub === 'freeze' ) {
+			const r = rooms.freeze(roomDir, argv[2] || '');
+			console.log('frozen: ' + r.dossier + '  sha256 ' + r.sha256.slice(0, 16) + '…  (' + r.classes + ' classes)');
+		} else { console.error('usage: mindsmith rooms list|import <file>|export <name> <dest>|freeze <name> [--room <dir>]'); process.exit(1); }
+	} catch ( e ) { console.error(e.message); process.exit(1); }
+} else if ( cmd === 'serve' || cmd === undefined ) {
+	const app = buildApp(resolveEscalation('serve'), {
+		port: Number(flag('port')) || 4747,
+		onAnswer: ( row ) => console.error('[' + (row.source === 'local' ? 'cache' : 'frontier') + '] ' + row.query),
+		onRoute: ( r ) => console.error('[tier:' + r.tier + '] ' + r.query)
+	});
+	app.start(( first ) => {
+		const l = first.loaded;
+		console.log('mindsmith → http://127.0.0.1:' + (Number(flag('port')) || 4747) + '/v1   (OpenAI-compatible)');
+		console.log('room ' + roomDir + ': methods=' + l.methods.length + ' lattice=' + l.lattice.length + (l.skipped.length ? ' skipped=' + l.skipped.length : ''));
+	}).catch(( e ) => { console.error(e.message); process.exit(1); });
+	process.on('SIGINT', () => { app.stop(); process.exit(0); });
+} else if ( cmd === 'mcp' ) {
+	// the MCP stdio surface over the SAME verified stock + escalation as serve — no http socket.
+	// stdout is the PROTOCOL channel: everything human goes to stderr.
+	const app = buildApp(resolveEscalation('mcp'), { onAnswer: ( row ) => console.error('[' + (row.source === 'local' ? 'cache' : 'frontier') + '] ' + row.query) });
+	app.sync().then(( first ) => {
+		const { createMcpServer, defaultTools, startMcpStdio, stockWiring } = require('skynet-graph/lib/sg/mcp.js');
+		// the FULL tool surface over the room: proxy (ask/drift/metrics/lattice_load) + the ASSISTANT
+		// lanes over the room's methods stock (hint = certified menu · propose = gated admission) +
+		// the C9 critical mind on the escalation backend (critique).
+		const wiring = { proxy: app.proxy, critiqueAsk: app.escalationAsk };
+		const mf = first.loaded.methods[0];
+		if ( mf ) { try { Object.assign(wiring, stockWiring(JSON.parse(require('fs').readFileSync(require('path').join(app.sgcDir, mf), 'utf8')))); } catch ( e ) { console.error('room stock lanes unavailable: ' + e.message); } }
+		const server = createMcpServer({
+			tools: defaultTools(wiring),
+			serverInfo: { name: 'mindsmith', version: require('../package.json').version }
+		});
+		startMcpStdio({ server });
+		const l = first.loaded;
+		console.error('mindsmith mcp ready — tools: ' + server.tools.map(( t ) => t.name).join(', ')
+			+ '  · room: methods=' + l.methods.length + ' lattice=' + l.lattice.length);
+	}).catch(( e ) => { console.error(e.message); process.exit(1); });
+} else {
+	console.error('usage: mindsmith serve|mcp|rooms …');
+	process.exit(1);
+}

package/lib/app.js

@@ -0,0 +1,142 @@
+'use strict';
+/**
+ * mindsmith — the LOCAL APPLIANCE, a thin assembly over the skynet-graph engine:
+ *
+ *   [OpenAI client] → baseURL → [this app: serve handler → C6 proxy → verified stock (.sgc, gated)]
+ *                                                        ↘ (miss) frontier chat (local gguf or endpoint)
+ *   [local SGC ROOM] → loadBundles THROUGH the engine's gates (your own bundles: create/freeze/import/export)
+ *
+ * Guarantees carried from the engine: a covered query is served from VERIFIED stock at 0 frontier
+ * calls; the local side never fabricates (0 hallucination); a miss always answers. Personal data never
+ * leaves this process — the ONLY outbound destination is the declared frontier (no catalog, no phone-home).
+ *
+ * `createApp` takes injectable backends (tests run it with stubs, GPU-free); bin/mindsmith
+ * resolves the real ones (embedded gguf via env FRONTIER_MODEL, or an OpenAI-compat endpoint via LLM_BASE).
+ */
+const fs = require('fs');
+const path = require('path');
+const Graph = require('skynet-graph');
+const { createServeHandler, startServeServer } = require('skynet-graph/lib/sg/serve.js');
+
+/** Load every pulled `.sgc` bundle into the proxy THROUGH the gates (kind-dispatched; never a raw write).
+ *  `report.versions` = sorted `name@version` of what actually LOADED — the stock-freshness provenance. */
+function loadBundles( px, dir ) {
+	const report = { methods: [], lattice: [], skipped: [], versions: [] };
+	if ( !fs.existsSync(dir) ) return report;
+	for ( const f of fs.readdirSync(dir) ) {
+		if ( !/\.(json|sgc)$/.test(f) ) continue;
+		let art;
+		try { art = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')); } catch ( e ) { report.skipped.push(f); continue; }
+		if ( !art || art.format !== 'sgc' ) { report.skipped.push(f); continue; }
+		try {
+			if ( art.kind === 'methods' ) { px.load(art); report.methods.push(f); }
+			else if ( art.kind === 'lattice' ) { px.library.loadLattice(art); report.lattice.push(f); }   // version-gated, confluence-checked
+			else { report.skipped.push(f); continue; }
+			const man = art.manifest || {};
+			report.versions.push((man.name || f) + '@' + (man.version || '?'));
+		} catch ( e ) { report.skipped.push(f + ' (' + e.message + ')'); }
+	}
+	report.versions.sort();
+	return report;
+}
+
+/**
+ * Build the appliance (no socket yet — start() opens it).
+ * The escalation is either an N-tier ROUTER or a single frontier chat (give ONE of):
+ * @param cfg.tiers         [{ name, ask|backend, egressClass? }] — ordered answer tiers (local/mid/frontier);
+ *                          a tier is a ready chat `ask` or an R0 `backend` preset spec (built via Graph.backends).
+ * @param cfg.policy        { dataPolicy:'no-egress'(default)|'allow-mid'|'allow-all', order?:[name] } — the RGPD ceiling.
+ * @param cfg.frontierChat  a single async ({system,user,maxTokens,temperature}) -> text — the escalation truth
+ *                          (legacy shorthand; treated as one allow-all frontier tier).
+ * @param cfg.onRoute       optional ({query,tier}) -> void — provenance of which tier answered.
+ * @param cfg.localAsk      optional small-model chat → semantic coverage (paraphrases hit the stock).
+ * @param cfg.store         stock file (durable cross-restart). cfg.sgcDir  the local SGC room (default ./sgc).
+ * @param cfg.port/host     endpoint bind (default 4747 / 127.0.0.1 — LOCAL by default, on purpose).
+ */
+/** A routing tier spec -> {name, ask, egressClass}. Either a ready chat `ask`, or an R0 backend preset
+ *  built via `Graph.backends` (a backend's `egress:false` maps to the 'none' class unless egressClass is
+ *  set). This is where R0 (config) and the routing (policy) converge. */
+function resolveTier( t ) {
+	if ( typeof t.ask === 'function' ) return { name: t.name, ask: t.ask, egressClass: t.egressClass, egress: t.egress };
+	if ( t.backend ) {
+		const d = Graph.backends.resolveBackend(t.backend);
+		return { name: t.name || d.name, ask: Graph.backends.makeBackend(t.backend), egressClass: t.egressClass, egress: d.egress };
+	}
+	throw new Error('routing tier "' + (t.name || '?') + '" needs an `ask` or a `backend` spec');
+}
+
+/** Build the escalation ROUTER from cfg: an explicit N-tier list (`cfg.tiers` governed by `cfg.policy`,
+ *  default dataPolicy no-egress) generalizing the C6 ladder, OR the legacy single chat backend
+ *  (`cfg.frontierChat`) treated as an allow-all frontier tier. Either way the proxy sees one frontierAsk. */
+function buildRouter( cfg ) {
+	const { makeRouter } = require('./routing.js');
+	let tiers, policy;
+	if ( Array.isArray(cfg.tiers) && cfg.tiers.length ) {
+		tiers = cfg.tiers.map(resolveTier);
+		policy = cfg.policy;
+	} else if ( typeof cfg.frontierChat === 'function' ) {
+		tiers = [{ name: 'frontier', ask: cfg.frontierChat, egressClass: 'frontier' }];
+		policy = cfg.policy || { dataPolicy: 'allow-all' };   // a single declared frontier is reachable (today's behaviour)
+	} else {
+		throw new Error('createApp needs cfg.tiers (N-tier routing) or cfg.frontierChat (a single chat backend)');
+	}
+	return makeRouter({ tiers: tiers, policy: policy, onRoute: cfg.onRoute });
+}
+
+function createApp( cfg ) {
+	cfg = cfg || {};
+	const combos = Graph.combos;
+	const router = buildRouter(cfg);   // the escalation: N-tier policy-governed, or a single frontier
+	const semantic = cfg.localAsk ? combos.makeLocalCoverage({ localAsk: cfg.localAsk }) : {};
+	const px = combos.createProxyCache(Object.assign({
+		frontierAsk: combos.makeFrontierAsk(router.ask),
+		store: cfg.store, retention: true
+	}, semantic));
+	const sgcDir = path.resolve(cfg.sgcDir || 'sgc');
+	let sgcVersion = '';   // 'name@version,…' of the loaded bundles — refreshed by every sync, served live (x-sg-sgc-version)
+
+	async function sync() {
+		const loaded = loadBundles(px, sgcDir);   // (re)load the local room THROUGH the gates
+		sgcVersion = loaded.versions.join(',');
+		return { loaded };
+	}
+
+	// ops readout: up? which SGC bundles are loaded (stock freshness)? the routing posture (configured
+	// tiers, which are reachable under the policy, the dataPolicy ceiling). Safe to poll — GET, no key,
+	// no query content.
+	function health() {
+		const m = (px.metrics && px.metrics()) || {};
+		return {
+			status: 'ok',
+			policy: router.policy.dataPolicy,
+			tiers: { configured: router.tiers.map(( t ) => t.name), reachable: router.plan().map(( t ) => t.name) },
+			sgc: sgcVersion ? sgcVersion.split(',') : [],
+			stock: (m.stock && m.stock.size != null) ? m.stock.size : null
+		};
+	}
+
+	let srv = null;
+	return {
+		proxy: px, sync, health,
+		escalationAsk: router.ask,     // the escalation chat, reusable by other surfaces (mcp critique tool)
+		sgcDir,                        // where the room bundles live (mcp assistant lanes re-read them)
+		start: async function ( onReady ) {
+			const first = await sync();
+			const base = createServeHandler({ proxy: px, model: cfg.model, onAnswer: cfg.onAnswer, sgcVersion: () => sgcVersion });
+			// the serve handler contract is PURE: (requestDescriptor) -> responseDescriptor (startServeServer
+			// owns the socket). Intercept GET /healthz, delegate everything else to the OpenAI handler.
+			const handler = function ( reqd ) {
+				if ( reqd.method === 'GET' && String(reqd.url || '').split('?')[0] === '/healthz' ) {
+					return { status: 200, headers: { 'content-type': 'application/json' }, body: health() };
+				}
+				return base(reqd);
+			};
+			srv = startServeServer({ handler, port: cfg.port != null ? cfg.port : 4747, host: cfg.host || '127.0.0.1',
+				onReady: () => onReady && onReady(first) });
+			return srv;
+		},
+		stop: function () { if ( srv ) srv.close(); }
+	};
+}
+
+module.exports = { createApp, loadBundles };

package/lib/rooms.js

@@ -0,0 +1,107 @@
+'use strict';
+/**
+ * SGC rooms — LOCAL bundle management (the community model: no central catalog, no subscription — anyone
+ * builds, freezes, shares and imports their own `.sgc` mini-repos). A room is just a directory of
+ * self-verifiable bundles: each `.sgc`/`.json` carries its manifest, and `freeze` writes the companion
+ * dossier (`<base>.dossier.md`: sha256 + inventory) that makes the bundle a fixed, auditable reference.
+ *
+ * Everything content-bearing stays engine-gated: `import` DRY-LOADS the bundle through the same gates the
+ * appliance uses (a malformed or empty bundle is REJECTED, never written into the room), and the appliance
+ * itself re-loads the room through `loadBundles` (kind-dispatched, version-gated) at boot.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const sha256 = ( buf ) => crypto.createHash('sha256').update(buf).digest('hex');
+const baseOf = ( f ) => f.replace(/\.(json|sgc)$/, '');
+
+/** Parse + shape-check one bundle file. → { art, kind, name, version, classes } — throws on a non-bundle. */
+function inspectBundle( file ) {
+	const bytes = fs.readFileSync(file);
+	const art = JSON.parse(bytes.toString('utf8'));
+	if ( !art || art.format !== 'sgc' ) throw new Error('not an sgc bundle (format!=="sgc")');
+	const man = art.manifest || {};
+	let classes = [];
+	if ( art.kind === 'methods' ) {
+		// the same admission surface the assistant lanes use — throws on an EMPTY certified vocabulary
+		const { stockWiring } = require('skynet-graph/lib/sg/mcp.js');
+		classes = stockWiring(art).hints.certifiedShapes;
+	} else if ( art.kind === 'lattice' ) {
+		const keys = (art.registry && art.registry.keys) || {};
+		classes = Object.keys(keys).sort();
+		if ( !classes.length ) throw new Error('empty lattice bundle (no registry keys)');
+	} else {
+		throw new Error('unknown sgc kind "' + art.kind + '" (methods|lattice)');
+	}
+	return { art, kind: art.kind, name: man.name || baseOf(path.basename(file)), version: man.version || '?',
+		classes, sha256: sha256(bytes) };
+}
+
+/** Inventory of a room. → [{ file, kind, name, version, classes, sha256, frozen, dossier }] (invalid files flagged). */
+function list( dir ) {
+	if ( !fs.existsSync(dir) ) return [];
+	const rows = [];
+	for ( const f of fs.readdirSync(dir).sort() ) {
+		if ( !/\.(json|sgc)$/.test(f) ) continue;
+		const full = path.join(dir, f);
+		const dossier = ['.dossier.md', '.md'].map(( e ) => baseOf(f) + e ).find(( d ) => fs.existsSync(path.join(dir, d)) );
+		try {
+			const b = inspectBundle(full);
+			rows.push({ file: f, kind: b.kind, name: b.name, version: b.version, classes: b.classes.length,
+				sha256: b.sha256, frozen: !!dossier, dossier: dossier || null });
+		} catch ( e ) { rows.push({ file: f, invalid: e.message }); }
+	}
+	return rows;
+}
+
+/** Import a bundle INTO the room — gate-checked first (fail-closed: a bad bundle is never written). */
+function importBundle( dir, srcFile ) {
+	const b = inspectBundle(srcFile);   // throws → nothing written
+	fs.mkdirSync(dir, { recursive: true });
+	const dest = path.join(dir, path.basename(srcFile));
+	fs.copyFileSync(srcFile, dest);
+	return { file: path.basename(dest), kind: b.kind, name: b.name, version: b.version, classes: b.classes.length, sha256: b.sha256 };
+}
+
+/** Export a bundle (+ its dossier when present) OUT of the room. */
+function exportBundle( dir, fileOrName, destDir ) {
+	const rows = list(dir).filter(( r ) => !r.invalid );
+	const row = rows.find(( r ) => r.file === fileOrName || r.name === fileOrName );
+	if ( !row ) throw new Error('bundle "' + fileOrName + '" not in the room (' + rows.map(( r ) => r.name ).join(', ') + ')');
+	fs.mkdirSync(destDir, { recursive: true });
+	fs.copyFileSync(path.join(dir, row.file), path.join(destDir, row.file));
+	const out = { exported: [row.file] };
+	if ( row.dossier ) { fs.copyFileSync(path.join(dir, row.dossier), path.join(destDir, row.dossier)); out.exported.push(row.dossier); }
+	return out;
+}
+
+/** Freeze a bundle: write its dossier (sha256 + inventory) — the fixed, auditable reference for sharing. */
+function freeze( dir, fileOrName ) {
+	const rows = list(dir).filter(( r ) => !r.invalid );
+	const row = rows.find(( r ) => r.file === fileOrName || r.name === fileOrName );
+	if ( !row ) throw new Error('bundle "' + fileOrName + '" not in the room');
+	const b = inspectBundle(path.join(dir, row.file));
+	const dossierFile = baseOf(row.file) + '.dossier.md';
+	const md = [
+		'# ' + b.name + '@' + b.version + ' — dossier (frozen reference)',
+		'',
+		'- file: `' + row.file + '`',
+		'- kind: `' + b.kind + '`',
+		'- sha256: `' + b.sha256 + '`',
+		'- frozen: ' + new Date().toISOString(),
+		'',
+		'## ' + (b.kind === 'methods' ? 'Certified classes (' + b.classes.length + ')' : 'Registry keys (' + b.classes.length + ')'),
+		'',
+		...b.classes.map(( c ) => '- `' + c + '`' ),
+		'',
+		'A consumer verifies the bytes against the sha256 above; the appliance re-verifies the content',
+		'through the engine gates at load. A bundle whose bytes no longer match its dossier is NOT the',
+		'frozen reference anymore.',
+		''
+	].join('\n');
+	fs.writeFileSync(path.join(dir, dossierFile), md);
+	return { dossier: dossierFile, sha256: b.sha256, classes: b.classes.length };
+}
+
+module.exports = { list, importBundle, exportBundle, freeze, inspectBundle };

package/lib/routing.js

@@ -0,0 +1,89 @@
+'use strict';
+/**
+ * routing — the C6 ladder generalized from 2 tiers to N, governed by a POLICY.
+ *
+ * The verified stock stays the proxy's job (0-call, exact/semantic — it never egresses). This router is
+ * the GENERALIZED FRONTIER: an ordered list of answer tiers, each a chat `ask`
+ * (`async ({system,user,maxTokens,temperature}) -> text`), tagged with an EGRESS CLASS:
+ *
+ *   'none'      the answer never leaves the machine   (embedded gguf / a LAN model declared non-egressing)
+ *   'mid'       a hosted mid-quant tier                (the subscription's mid model — leaves, but contracted)
+ *   'frontier'  the user's own frontier provider       (leaves, to the user's chosen vendor)
+ *
+ * `policy.dataPolicy` is the RGPD ceiling — which classes may answer:
+ *   'no-egress' (DEFAULT) -> ['none']            nothing leaves; only local answers
+ *   'allow-mid'           -> ['none','mid']       up to the hosted mid tier
+ *   'allow-all'           -> ['none','mid','frontier']
+ *
+ * The router walks the reachable tiers in preference order (policy.order, else declaration order) and
+ * returns the first that answers; an unavailable tier falls through to the next reachable one. If the
+ * policy leaves NO reachable tier (or every reachable tier fails), it is a typed NO_REACHABLE_TIER
+ * refusal — a query is NEVER silently sent to a forbidden tier. This is the enforcement side of the M2
+ * no-egress guarantee: the default policy calls nothing that egresses. Converges with R0 backends.js — a
+ * tier is just a named `ask` (build it with `Graph.backends.makeBackend`) + an egress class (a backend's
+ * `egress:false` maps to 'none').
+ */
+const POLICY = {
+	'no-egress': ['none'],
+	'allow-mid': ['none', 'mid'],
+	'allow-all': ['none', 'mid', 'frontier']
+};
+
+function err( message, code, cause ) { const e = new Error(message); e.code = code; if ( cause ) e.cause = cause; return e; }
+
+// a tier's egress class: explicit wins; else inferred from an `egress` boolean (R0 convergence: a
+// non-egressing backend is 'none', an egressing one defaults to 'frontier' — the most-restricted class).
+function classOf( t ) {
+	if ( t.egressClass ) return t.egressClass;
+	if ( t.egress === false ) return 'none';
+	return 'frontier';
+}
+
+/**
+ * @param cfg.tiers    [{ name, ask, egressClass?|egress? }]  ordered answer tiers (each a chat ask).
+ * @param cfg.policy   { dataPolicy='no-egress', order?:[name] }
+ * @param cfg.onRoute  optional ({query,tier}) -> void — provenance of which tier answered.
+ */
+function makeRouter( cfg ) {
+	cfg = cfg || {};
+	const tiers = (cfg.tiers || []).map(function ( t ) { return { name: t.name, ask: t.ask, egressClass: classOf(t) }; });
+	for ( const t of tiers ) if ( typeof t.ask !== 'function' ) throw err('routing tier "' + t.name + '" needs an ask function', 'BAD_TIER');
+	const policy = Object.assign({ dataPolicy: 'no-egress' }, cfg.policy);
+	const allowed = POLICY[policy.dataPolicy];
+	if ( !allowed ) throw err('unknown dataPolicy "' + policy.dataPolicy + '" — known: ' + Object.keys(POLICY).join(', '), 'BAD_POLICY');
+	const onRoute = cfg.onRoute;
+
+	// the reachable tiers, in preference order (policy.order by name, else declaration order — stable).
+	function plan() {
+		let ordered = tiers;
+		if ( Array.isArray(policy.order) ) {
+			const rank = function ( name ) { const i = policy.order.indexOf(name); return i === -1 ? policy.order.length : i; };
+			ordered = tiers.map(( t, i ) => [t, i]).sort(( a, b ) => (rank(a[0].name) - rank(b[0].name)) || (a[1] - b[1])).map(( x ) => x[0]);
+		}
+		return ordered.filter(( t ) => allowed.indexOf(t.egressClass) !== -1);
+	}
+
+	// walk the reachable tiers; first success wins, an unavailable tier falls through. Typed refusal if
+	// the policy leaves nothing reachable, or every reachable tier failed.
+	async function route( chatArgs ) {
+		const candidates = plan();
+		if ( !candidates.length ) throw err('no tier reachable under dataPolicy "' + policy.dataPolicy + '" — a forbidden tier is never called', 'NO_REACHABLE_TIER');
+		let last = null;
+		for ( const t of candidates ) {
+			try {
+				const answer = await t.ask(chatArgs);
+				if ( onRoute ) onRoute({ query: chatArgs && chatArgs.user, tier: t.name });
+				return { answer: answer, tier: t.name };
+			} catch ( e ) { last = e; }
+		}
+		throw err('every reachable tier failed under dataPolicy "' + policy.dataPolicy + '"', 'NO_REACHABLE_TIER', last);
+	}
+
+	// chat-shaped: returns just the answer text, so `makeFrontierAsk(router.ask)` wraps it as the proxy's frontier.
+	async function ask( chatArgs ) { return (await route(chatArgs)).answer; }
+
+	return { plan: plan, route: route, ask: ask, policy: policy,
+		tiers: tiers.map(function ( t ) { return { name: t.name, egressClass: t.egressClass }; }) };
+}
+
+module.exports = { makeRouter: makeRouter, POLICY: POLICY };

package/lib/serve-config.js

@@ -0,0 +1,40 @@
+'use strict';
+/**
+ * serve-config — the bin's CLI/env -> routing config resolver, kept PURE (arg + env in, plain object out)
+ * so the `skynet-client serve` wiring is unit-testable without spawning a process.
+ *
+ * `--routing <file.json>` (or $SG_ROUTING) declares the N tiers + policy for the appliance:
+ *   { "tiers": [ { "name":"local", "egressClass":"none", "backend": { "preset":"local", "modelPath":"…" } },
+ *                { "name":"mid",   "egressClass":"mid",  "backend": { "preset":"custom", "base":"…", "key":"…" } },
+ *                { "name":"frontier","egressClass":"frontier","backend": { "preset":"deepseek" } } ],
+ *     "policy": { "dataPolicy":"no-egress", "order":["frontier","mid","local"] } }
+ * `--policy <no-egress|allow-mid|allow-all>` (or $SG_POLICY) overrides just the dataPolicy. Each tier's
+ * `backend` is an R0 preset spec (built by Graph.backends at createApp time). No routing config -> null,
+ * so the caller uses the legacy single-frontier path unchanged.
+ */
+const fs = require('fs');
+
+function readFlag( argv, name ) { const i = argv.indexOf('--' + name); return i !== -1 ? argv[i + 1] : undefined; }
+
+/**
+ * @param argv  process.argv.slice(2)-style array
+ * @param env   an environment object (process.env)
+ * @returns { tiers, policy } when an N-tier routing config is present, else null.
+ */
+function resolveRouting( argv, env ) {
+	argv = argv || [];
+	env = env || {};
+	const file = readFlag(argv, 'routing') || env.SG_ROUTING;
+	let tiers = null, policy = null;
+	if ( file ) {
+		const rc = JSON.parse(fs.readFileSync(file, 'utf8'));
+		tiers = rc.tiers || null;
+		policy = rc.policy || null;
+	}
+	if ( !tiers ) return null;   // no tiers declared -> not a routing config; the bin uses the single frontier
+	const dp = readFlag(argv, 'policy') || env.SG_POLICY;
+	if ( dp ) policy = Object.assign({}, policy, { dataPolicy: dp });
+	return { tiers: tiers, policy: policy || undefined };
+}
+
+module.exports = { resolveRouting: resolveRouting };