melete-ai 0.88.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shinnapat Phunsriphatchalakul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+<div align="center">
+
+<img src="assets/meli.svg" alt="Meli — the Melete mascot" width="130" />
+
+# Melete
+
+### The Sovereign Verifiable AI Analyst &amp; Optimizer
+
+**Find the best — and most *robust* — settings for any system you can measure, in the fewest experiments — then hand over a signed verdict anyone can re-verify offline.**
+
+🌐 Live demo → **[melete.mneme-ai.space](https://melete.mneme-ai.space)**
+
+`MIT` · zero runtime dependencies · runs on your machine
+
+</div>
+
+---
+
+## What it is (in one line)
+You have a system you can **measure** — an ML pipeline, a server/DB/network config, a recipe, a simulation. Melete proposes the next setting to try, you measure it (or give a formula), and it converges to the best **stable** answer — then explains *why* in plain language and signs a verdict you (or an auditor) can re-check offline. **Your data never leaves your machine.**
+
+## Use it in 60 seconds — 3 ways
+
+**1) Through the website (no code).** Open the [live demo](https://melete.mneme-ai.space), pick your field (Pharma · Semiconductor · AI/ML · …), press **Watch** to see it discover, or use **guided mode**: it proposes → you measure in real life → you type the score → repeat.
+
+**2) CLI / npm (on your own machine):**
+```bash
+npm i -g melete-ai
+melete bench            # measured: beats random / grid search
+melete gauntlet         # every engine's correctness check (must be 100)
+melete poopt cert.json  # verify a signed certificate offline
+```
+
+**3) API — connect your real process (air-gapped).**
+First, get an endpoint to call — two options:
+```bash
+# A) hosted demo (quick try):        base URL = https://melete.mneme-ai.space
+# B) self-host (sovereign — data never leaves your machine):
+npm i -g melete-ai
+melete-server                         # → serves on http://localhost:8790
+```
+Then POST to that base URL:
+```bash
+POST /next             { space, observations }              → the next setting to try
+POST /aegis            { space, objective, budget }         → the best ROBUST setting (survives wobble)
+POST /discover         { space, objective, budget }         → full run + signed Sovereign Verdict + Replay Token
+POST /sovereign/verify { …verdict }                         → re-verify provenance OFFLINE
+POST /replay/verify    { …token }                           → re-derive the decision step-by-step OFFLINE
+```
+…or skip HTTP entirely and call the library in-process: `import { sovereignAnalyze, aegisDiscover, proposeNext } from "melete-ai"`.
+
+## What's inside — 43 engines, 4 layers
+| | layer | what it does |
+|---|---|---|
+| 🔍 | **DISCOVER** | find the best setting in the fewest tries (adaptive ensemble) |
+| ◆ | **DECIDE** | the Φ brain's safety-first verdict + 🛡 AEGIS, the *robust* answer (not the fragile spike) |
+| 🔬 | **DIAGNOSE** | plain-language *why*: which knobs matter, where the cliffs are, the shape, the achievable ceiling |
+| 👑 | **CERTIFY** | an Ed25519 **Sovereign Verdict** + a **Replay Token** — signed, offline-verifiable, step-by-step replayable |
+
+## The moat
+- 🔒 **Sovereign** — runs air-gapped, on your machine; data never touches a cloud.
+- 👑 **Verifiable** — every verdict is Ed25519-signed; an auditor re-verifies it offline with the embedded public key, no trust in us required.
+- ⏪ **Replayable** — the engine is fully deterministic, so a signed Replay Token re-derives the exact decision, step by step, on any machine, forever.
+
+## Honest by design (DIAKRISIS)
+Melete is an **optimizer + analyst**, not a fortune-teller. "Verifiable" means **provenance + reproducibility** — proof of *what was tested and the result reached, unaltered and re-derivable* — **not** a proof that your code is bug-free or exploit-free (that is undecidable in general; we don't claim it). Efficiency, robustness, and Pareto results are exact and reproducible. Run `melete gauntlet` — every claim is a check you can re-run.
+
+---
+
+<div align="center">
+<sub>Mneme remembers; Melete discovers. · <a href="https://melete.mneme-ai.space/pitch">pitch</a> · <a href="https://melete.mneme-ai.space/docs">API docs</a></sub>
+</div>

package/bin/melete-server.mjs

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+/**
+ * Melete discovery-as-a-service HTTP server. Self-contained (node:http + node:vm). Stateless.
+ *   GET  /            → landing page (live demo)
+ *   GET  /health      → { ok, version }
+ *   POST /discover    → { space, objective, budget, goal, engine } → best + armStats + signed trace + verify
+ *   POST /verify      → { trace } → { ok, reason }
+ *
+ * The objective is evaluated in a frozen VM sandbox (Math only) with a timeout — a demo-grade safety
+ * boundary, not a hostile-multi-tenant guarantee. Budget is capped server-side.
+ */
+import { createServer } from "node:http";
+import { createContext, runInContext } from "node:vm";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import * as M from "../dist/index.js";
+import { createHash } from "node:crypto";
+
+const VERSION = (() => { try { return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version; } catch { return "0.2.0"; } })();
+const PORT = +(process.env.PORT || 8790); const HOST = process.env.HOST || "127.0.0.1";
+const MAX_BUDGET = +(process.env.MELETE_MAX_BUDGET || 120);
+
+const json = (res, code, obj) => { const b = JSON.stringify(obj); res.writeHead(code, { "content-type": "application/json", "access-control-allow-origin": "*", "content-length": Buffer.byteLength(b) }); res.end(b); };
+const readBody = (req) => new Promise((resolve) => { let d = ""; req.on("data", (c) => { d += c; if (d.length > 1e6) req.destroy(); }); req.on("end", () => { try { resolve(d ? JSON.parse(d) : {}); } catch { resolve(null); } }); });
+
+function makeOracle(space, objective) {
+  const ctx = createContext({ Math });   // sandbox has Math only (no require/process/fs); writable so dims can be bound
+  return (e) => { for (const d of space.dims) ctx[d.name] = e[d.name]; const v = Number(runInContext(objective, ctx, { timeout: 100 })); return Number.isFinite(v) ? v : -1e18; };
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url, "http://x"); const path = url.pathname;
+    if (req.method === "OPTIONS") return json(res, 204, {});
+    if (req.method === "GET" && path === "/") { const html = M.landingPage(VERSION); res.writeHead(200, { "content-type": "text/html; charset=utf-8" }); return res.end(html); }
+    if (req.method === "GET" && path === "/pitch") { const html = M.pitchDeck(VERSION); res.writeHead(200, { "content-type": "text/html; charset=utf-8" }); return res.end(html); }
+    if (req.method === "GET" && path === "/docs") { const html = M.docsPage(VERSION); res.writeHead(200, { "content-type": "text/html; charset=utf-8" }); return res.end(html); }
+    if (req.method === "GET" && path === "/health") return json(res, 200, { ok: true, version: VERSION, service: "melete" });
+
+    // ⏪ REPLAY — re-run a Replay Token OFFLINE: verify signature + deterministically reproduce step-by-step
+    if (req.method === "POST" && path === "/replay/verify") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      try { return json(res, 200, M.replayToken(body)); } catch (e) { return json(res, 400, { error: "replay failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // 🛡 IP SHIELD — re-verify a patent-grade IP audit trail OFFLINE
+    if (req.method === "POST" && path === "/ip-audit/verify") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      try { return json(res, 200, M.verifyIpAuditTrail(body)); } catch (e) { return json(res, 400, { error: "verify failed: " + e.message.slice(0, 120) }); }
+    }
+    // 🚨 GUARDIAN — one heartbeat: detect drift/breach in a live metric history + recommend a re-tune
+    if (req.method === "POST" && path === "/guardian/tick") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const history = Array.isArray(body.history) ? body.history.map(Number).filter(Number.isFinite) : [];
+      try { return json(res, 200, M.guardianTick(history, { baseline: body.baseline, lowerIsBetter: !!body.lowerIsBetter, breachFrac: body.breachFrac, degradeFrac: body.degradeFrac, window: body.window })); }
+      catch (e) { return json(res, 400, { error: "guardian failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // 👑 SOVEREIGN — re-verify a signed Sovereign Verdict OFFLINE (provenance + reproducibility)
+    if (req.method === "POST" && path === "/sovereign/verify") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      try { return json(res, 200, M.verifySovereign(body)); } catch (e) { return json(res, 400, { error: "verify failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // 🛡 AEGIS — the self-aware engine: returns the best ROBUST optimum (survives wobble), not the fragile spike
+    if (req.method === "POST" && path === "/aegis") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const space = { dims: Array.isArray(body.space) ? body.space : body.space?.dims };
+      if (!space.dims?.length) return json(res, 400, { error: "space must be a non-empty array of {name,type,min,max}" });
+      if (space.dims.length > 12) return json(res, 400, { error: "demo limit: ≤12 dimensions" });
+      if (typeof body.objective !== "string" || !body.objective.trim()) return json(res, 400, { error: "objective must be a JS expression string in your dimension names" });
+      const budget = Math.max(4, Math.min(MAX_BUDGET, (body.budget | 0) || 50));
+      let oracle; try { oracle = makeOracle(space, body.objective); oracle(Object.fromEntries(space.dims.map((d) => [d.name, (d.min + d.max) / 2]))); } catch (e) { return json(res, 400, { error: "objective failed to evaluate: " + e.message.slice(0, 120) }); }
+      const goal = body.goal === "minimize" ? "minimize" : "maximize";
+      try { const r = M.aegisDiscover({ space, oracle, budget, goal, seed: (body.seed | 0) || 1, robustWeight: typeof body.robustWeight === "number" ? body.robustWeight : 0.6 });
+        return json(res, 200, { best: r.best, rawBest: r.rawBest, robustnessOfBest: r.robustnessOfBest, tradedHeight: r.tradedHeight, evaluations: r.evaluations, goal }); }
+      catch (e) { return json(res, 400, { error: "aegis failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // 🛰 NOISE-ROBUST — trustworthy optimum under MEASUREMENT noise. Injects deterministic gaussian noise of
+    // the given std onto your objective (a stand-in for a noisy real oracle), replicate-measures, and returns
+    // the optimum you can trust (highest lower-confidence-bound) + the "lucky max" it rejected + a risk band.
+    if (req.method === "POST" && path === "/noise-robust") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const space = { dims: Array.isArray(body.space) ? body.space : body.space?.dims };
+      if (!space.dims?.length) return json(res, 400, { error: "space must be a non-empty array of {name,type,min,max}" });
+      if (space.dims.length > 12) return json(res, 400, { error: "demo limit: ≤12 dimensions" });
+      if (typeof body.objective !== "string" || !body.objective.trim()) return json(res, 400, { error: "objective must be a JS expression string in your dimension names" });
+      const budget = Math.max(12, Math.min(MAX_BUDGET, (body.budget | 0) || 110));
+      const noise = (typeof body.noise === "number" && body.noise >= 0) ? body.noise : 0.3;
+      let base; try { base = makeOracle(space, body.objective); base(Object.fromEntries(space.dims.map((d) => [d.name, (d.min + d.max) / 2]))); } catch (e) { return json(res, 400, { error: "objective failed to evaluate: " + e.message.slice(0, 120) }); }
+      const goal = body.goal === "minimize" ? "minimize" : "maximize";
+      const rng = M.lcg((body.seed | 0) || 1);
+      const noisyOracle = (e) => { const u1 = Math.max(1e-9, rng()), u2 = rng(); const g = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2); return base(e) + noise * g; };
+      try {
+        const r = M.noiseRobustDiscover({ space, oracle: noisyOracle, budget, goal, seed: (body.seed | 0) || 1, z: typeof body.z === "number" ? body.z : 1.85, replicates: (body.replicates | 0) || 5 });
+        return json(res, 200, { best: r.best, bestMean: r.bestMean, bestStd: r.bestStd, bestN: r.bestN, bestLcb: r.bestLcb, luckyMax: r.luckyMax, rejectedLucky: r.rejectedLucky, noiseFiltered: r.noiseFiltered, points: r.points.slice(0, 12), evaluations: r.evaluations, goal, noise });
+      } catch (e) { return json(res, 400, { error: "noise-robust failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // 🧩 MIXED-SPACE — optimize a space with categorical / integer / conditional knobs (not just continuous).
+    // Dims accept {type:"categorical",choices:[...]} and {activeWhen:{dim,equals}}; objective is a JS expr that
+    // may compare categoricals (e.g. engine==='B'?1:0.7). Returns the best full recipe + per-combo leaderboard.
+    if (req.method === "POST" && path === "/mixed") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const dims = Array.isArray(body.space) ? body.space : body.space?.dims;
+      if (!Array.isArray(dims) || !dims.length) return json(res, 400, { error: "space must be a non-empty array of dims" });
+      if (dims.length > 12) return json(res, 400, { error: "demo limit: ≤12 dimensions" });
+      if (dims.some((d) => d.type === "categorical" && (!Array.isArray(d.choices) || !d.choices.length))) return json(res, 400, { error: "each categorical dim needs a non-empty choices[]" });
+      if (typeof body.objective !== "string" || !body.objective.trim()) return json(res, 400, { error: "objective must be a JS expression string in your dimension names" });
+      const budget = Math.max(12, Math.min(600, (body.budget | 0) || 300));   // mixed is combo-heavy → its own cap
+      const goal = body.goal === "minimize" ? "minimize" : "maximize";
+      let oracle; try { oracle = makeOracle({ dims }, body.objective); } catch (e) { return json(res, 400, { error: "objective failed to compile: " + e.message.slice(0, 120) }); }
+      try {
+        const r = M.mixedDiscover({ space: { dims }, oracle, budget, goal, seed: (body.seed | 0) || 1 });
+        return json(res, 200, { best: r.best, bestCombo: r.bestCombo, byCombo: r.byCombo.slice(0, 12), evaluations: r.evaluations, comboCount: r.comboCount, sampledCombos: r.sampledCombos, goal });
+      } catch (e) { return json(res, 400, { error: "mixed failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // 📜 PROVENANCE — demo the O(1) tamper-evident audit trail: build a checkpoint over `count` synthetic
+    // events, sign it, and prove (a) the snapshot is bounded and (b) altering any past event is detected.
+    if (req.method === "POST" && path === "/provenance") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const count = Math.max(1, Math.min(200000, (body.count | 0) || 5000));
+      const windowSize = Math.max(1, Math.min(500, (body.windowSize | 0) || 50));
+      try {
+        const events = []; for (let i = 0; i < count; i++) events.push({ kind: i % 3 === 0 ? "decision" : "experiment", payload: { i, x: (i * 7) % 100 } });
+        const cp = M.signCheckpoint(M.buildCheckpoint(events, windowSize));
+        const sizeBytes = M.checkpointSize(cp);
+        const sigValid = M.verifyCheckpointSignature(cp).ok;
+        const intact = M.verifyAgainst(cp, events).ok;
+        // tamper an old event and show it's caught
+        const tampered = events.slice(); const pos = Math.floor(count / 2); tampered[pos] = { kind: tampered[pos].kind, payload: { i: pos, x: 999999 } };
+        const tamperDetected = !M.verifyAgainst(cp, tampered).ok;
+        return json(res, 200, { count: cp.count, windowSize, sizeBytes, foldedRoot: cp.foldedRoot, signatureValid: sigValid, intactVerifies: intact, tamperDetected, algo: cp.algo });
+      } catch (e) { return json(res, 400, { error: "provenance failed: " + e.message.slice(0, 120) }); }
+    }
+
+    if (req.method === "POST" && path === "/discover") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      // VERTICAL live-demo: load the domain-shaped (simulated) objective + space + goal from the gallery
+      const vert = (typeof body.vertical === "string" && M.VERTICALS && M.VERTICALS[body.vertical]) ? M.VERTICALS[body.vertical] : null;
+      if (vert) { body.space = vert.space.dims; body.objective = vert.objective; body.goal = vert.goal; if (!body.budget) body.budget = 50; }
+      const space = { dims: Array.isArray(body.space) ? body.space : body.space?.dims };
+      if (!space.dims?.length) return json(res, 400, { error: "space must be a non-empty array of {name,type,min,max}" });
+      if (space.dims.length > 12) return json(res, 400, { error: "demo limit: ≤12 dimensions" });
+      if (typeof body.objective !== "string" || !body.objective.trim()) return json(res, 400, { error: "objective must be a JS expression string in your dimension names" });
+      const budget = Math.max(2, Math.min(MAX_BUDGET, (body.budget | 0) || 40));
+      let oracle; try { oracle = makeOracle(space, body.objective); oracle(Object.fromEntries(space.dims.map((d) => [d.name, (d.min + d.max) / 2]))); } catch (e) { return json(res, 400, { error: "objective failed to evaluate: " + e.message.slice(0, 120) }); }
+      const goal = body.goal === "minimize" ? "minimize" : "maximize";
+      const sig = await M.discoverSigned({ space, oracle, budget, seed: (body.seed | 0) || 1, goal, engine: ["portfolio", "bayes", "resonance"].includes(body.engine) ? body.engine : "portfolio" });
+      // Discovery Map: for a 2-D problem, sample the learned surface on a grid so the client can show
+      // WHERE the brain searched and WHY — the visual "story" of the discovery.
+      let surface = null;
+      if (space.dims.length === 2) {
+        const [dx, dy] = space.dims; const N = 44; const z = [];
+        for (let j = 0; j < N; j++) for (let i = 0; i < N; i++) { const e = { [dx.name]: dx.min + (dx.max - dx.min) * (i / (N - 1)), [dy.name]: dy.min + (dy.max - dy.min) * (j / (N - 1)) }; let v = oracle(e); if (!Number.isFinite(v)) v = 0; z.push(v); }
+        surface = { nx: N, ny: N, xName: dx.name, yName: dy.name, xMin: dx.min, xMax: dx.max, yMin: dy.min, yMax: dy.max, z };
+      }
+      // per-experiment path WITH the strategy (arm) that proposed each — lets the client colour the
+      // discovery by strategy and replay it step by step.
+      const path = (sig.result.history || []).map((s) => ({ experiment: s.experiment, value: s.value, n: s.n, arm: (String(s.rationale || "").match(/^\[([^\]]+)\]/) || [, "seed"])[1] }));
+      const dims = space.dims.map((d) => ({ name: d.name, min: d.min, max: d.max, type: d.type }));
+      // FRONTIER: "should you have run more, or was this the practical best?" — decision support from the
+      // run's own diminishing-returns curve (honest; no fabricated $ unless the client supplies a cost).
+      const frontierObs = (sig.result.history || []).map((st) => ({ experiment: st.experiment, value: st.value }));
+      // RELIABLE MODE (opt-in): a Nelder–Mead memetic polish on the global best — the local exploiter that
+      // lifts hard curved valleys (Rosenbrock 59%→100%). Deterministic; the signed trace covers the global
+      // search, the polish is a reported refinement on top.
+      let best = sig.result.best; let extraEvals = 0; const reliable = !!body.reliable;
+      if (reliable) {
+        const localBudget = Math.max(20, Math.round(budget * 0.6));
+        const pol = M.polish(space, oracle, best.experiment, localBudget, goal); extraEvals = localBudget;
+        const improved = goal === "minimize" ? pol.value < best.value : pol.value > best.value;
+        if (improved) best = { experiment: pol.experiment, value: pol.value };
+        frontierObs.push({ experiment: best.experiment, value: best.value });
+      }
+      const cost = (typeof body.costPerExperiment === "number" && body.costPerExperiment > 0) ? body.costPerExperiment : null;
+      const frontier = M.stoppingAdvice(frontierObs, goal, cost);
+      // OPTIMALITY CERTIFICATE: a provable "within X% of the best possible" under a data-estimated Lipschitz bound.
+      const certificate = M.certifyOptimality(frontierObs, space, goal);
+      const totalEvals = sig.result.evaluations + extraEvals;
+      // BASELINE — a raw score means nothing without a reference. Compare Melete's best against (a) where you
+      // started and (b) a plain random search on the SAME budget, so the number becomes "X% better than random".
+      const startVal = frontierObs.length ? frontierObs[0].value : best.value;
+      const rng = M.lcg(987654321);
+      let randomBest = goal === "minimize" ? Infinity : -Infinity;
+      for (let i = 0; i < totalEvals; i++) { const e = {}; for (const dd of space.dims) { const lo2 = dd.min ?? 0, hi2 = dd.max ?? 1; let v = lo2 + (hi2 - lo2) * rng(); if (dd.type === "int") v = Math.round(v); e[dd.name] = v; } const val = oracle(e); if (Number.isFinite(val) && (goal === "minimize" ? val < randomBest : val > randomBest)) randomBest = val; }
+      const baseline = { start: startVal, random: Number.isFinite(randomBest) ? randomBest : null, best: best.value, evaluations: totalEvals };
+      // PROOF OF OPTIMIZATION — a portable, offline-verifiable certificate fusing efficiency + optimality + provenance.
+      let poopt = null;
+      try {
+        const traceHash = createHash("sha256").update(JSON.stringify(sig.trace)).digest("hex");
+        poopt = M.issueProofOfOptimization({
+          subject: typeof body.subject === "string" ? body.subject.slice(0, 80) : "optimization",
+          goal, dims: space.dims.length, experimentsUsed: totalEvals, bestValue: best.value,
+          certifiedWithinPct: certificate ? certificate.withinPct : null, traceHash, issuedAtMs: Date.now(),
+          energyPerExperimentKwh: typeof body.energyPerExperimentKwh === "number" ? body.energyPerExperimentKwh : null,
+          carbonKgPerKwh: typeof body.carbonKgPerKwh === "number" ? body.carbonKgPerKwh : null,
+        });
+      } catch { poopt = null; }
+      // SENSITIVITY — per-variable process tolerance + robustness of the optimum (Taguchi-style).
+      let sensitivity = null; try { sensitivity = M.analyzeSensitivity(frontierObs, space, goal); } catch { sensitivity = null; }
+      // NOISE — measurement-reliability / replication advisor.
+      let noise = null; try { noise = M.analyzeNoise(frontierObs, space, goal); } catch { noise = null; }
+      // INTERACTIONS — which variables are coupled (cannot be tuned independently).
+      let interactions = null; try { interactions = M.analyzeInteractions(frontierObs, space, goal); } catch { interactions = null; }
+      let coverage = null; try { coverage = M.coverageScore(frontierObs, space); } catch { coverage = null; }
+      // DRIFT — is the improvement caused by your variables, or confounded with a time-trend (a hidden factor)?
+      let drift = null; try { drift = M.analyzeDrift(frontierObs, space, goal); } catch { drift = null; }
+      // EFFICIENCY η = ∛(G·R·T) — one honest number: real gain × robust optimum × trustworthy (not confounded).
+      let efficiency = null; try { efficiency = M.discoveryEfficiency(frontierObs, space, goal); } catch { efficiency = null; }
+      // PRESCRIPTION — the plain-language action card: what to DO with this result.
+      let prescription = null; try { prescription = M.buildPrescription(frontierObs, space, goal); } catch { prescription = null; }
+      // DISCOVERY BRAIN — the improvement-lineage tree (search drawn as converging roots)
+      let lineage = null; try { lineage = M.buildLineage(frontierObs, space, goal); } catch { lineage = null; }
+      // SLOPPINESS — how many combinations of variables actually matter (effective dimensionality)
+      let sloppiness = null; try { sloppiness = M.analyzeSloppiness(frontierObs, space, goal); } catch { sloppiness = null; }
+      // CLIFFS — tipping points where a small change collapses the result
+      let cliffs = null; try { cliffs = M.analyzeCliffs(frontierObs, space, goal); } catch { cliffs = null; }
+      // BREAKTHROUGH RADAR — surprising results (potential breakthroughs / anomalies)
+      let surprise = null; try { surprise = M.analyzeSurprise(frontierObs, space, goal); } catch { surprise = null; }
+      // RASHOMON — the family of genuinely different recipes that all score near-best
+      let rashomon = null; try { rashomon = M.analyzeRashomon(frontierObs, space, goal); } catch { rashomon = null; }
+      // SHAPE — the geometry of the optimum (peak / ridge / saddle / plateau / bowl)
+      let shape = null; try { shape = M.analyzeShape(frontierObs, space, goal); } catch { shape = null; }
+      // ◆ MELETE PRIME — the Red Diamond: the unified brain that composes every lens into one decision
+      let prime = null; try { prime = M.meletePrime(frontierObs, space, goal); } catch { prime = null; }
+      // 👑 SOVEREIGN — the ecosystem verdict: 4 layers + an Ed25519 PROVENANCE certificate, offline-verifiable
+      let sovereign = null; try { sovereign = M.sovereignAnalyze(frontierObs, space, goal, { issuedAtMs: 0 }); } catch { sovereign = null; }
+      // ⏪ REPLAY TOKEN — deterministic, signed, offline step-by-step replay of this analysis (audit/compliance)
+      let replayToken = null; try { replayToken = M.issueReplayToken(frontierObs, space, goal, { issuedAtMs: 0 }); } catch { replayToken = null; }
+      // 🛡 AEGIS — the self-aware engine: the best ROBUST optimum (survives wobble) vs the raw peak
+      let aegis = null; try { const a = M.aegisDiscover({ space, oracle, budget: Math.min(60, Math.max(24, totalEvals)), goal, seed: (body.seed | 0) || 1, robustWeight: 0.65 }); aegis = { best: a.best, rawBest: a.rawBest, robustnessOfBest: a.robustnessOfBest, tradedHeight: a.tradedHeight }; } catch { aegis = null; }
+      // expose the space + a capped sample of observations so the browser can run the WHAT-IF twin (/predict)
+      const obsOut = (frontierObs || []).slice(0, 200).map((o) => ({ experiment: o.experiment, value: o.value }));
+      // 📡 AI JOURNALIST — Sci-Fi command-center narration of THIS real run (only real numbers), for the vertical gallery
+      let narration = null; if (vert) { try { narration = M.narrate(body.vertical, { best, evaluations: totalEvals, vsStartPct: prescription ? prescription.vsStartPct : undefined, verdictHash: sovereign ? sovereign.certify.payloadHash : undefined, robust: !!(aegis && aegis.robustnessOfBest > 0.5) }); } catch { narration = null; } }
+      const vertical = vert ? { key: vert.key, emoji: vert.emoji, title: vert.title, sector: vert.sector, knobsCopy: vert.knobsCopy, scoreCopy: vert.scoreCopy, scoreName: vert.scoreName, scoreUnit: vert.scoreUnit, realWorld: vert.realWorld } : null;
+      return json(res, 200, { best, evaluations: totalEvals, converged: sig.result.converged, engine: sig.engine, reliable, goal, dims, space: space.dims, observations: obsOut, armStats: sig.result.armStats ?? null, surface, path, frontier, certificate, baseline, poopt, sensitivity, noise, interactions, coverage, drift, efficiency, prescription, lineage, sloppiness, cliffs, surprise, rashomon, shape, aegis, prime, sovereign, replayToken, vertical, narration, trace: sig.trace, verify: M.verifyTrace(sig.trace).ok });
+    }
+
+    if (req.method === "POST" && path === "/next") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const space = { dims: Array.isArray(body.space) ? body.space : body.space?.dims };
+      if (!space.dims?.length) return json(res, 400, { error: "space must be a non-empty array of {name,type,min,max}" });
+      if (space.dims.length > 12) return json(res, 400, { error: "demo limit: ≤12 dimensions" });
+      const obs = Array.isArray(body.observations) ? body.observations.filter((o) => o && o.experiment && Number.isFinite(+o.value)).map((o) => ({ experiment: o.experiment, value: +o.value })) : [];
+      const goal = body.goal === "minimize" ? "minimize" : "maximize";
+      try {
+        const next = M.proposeNext(space, obs, goal, (body.seed | 0) || 1);
+        const best = obs.length ? obs.reduce((a, b) => (goal === "minimize" ? (b.value < a.value ? b : a) : (b.value > a.value ? b : a))) : null;
+        const cost = (typeof body.costPerExperiment === "number" && body.costPerExperiment > 0) ? body.costPerExperiment : null;
+        const advice = M.stoppingAdvice(obs, goal, cost);
+        const territory = M.assessTerritory(next, obs, space);
+        const confidence = M.stopConfidence(obs, goal);
+        // ACHIEVABILITY — if the user named a target, is it even reachable with these variables?
+        let achievability = null, inverse = null;
+        if (typeof body.target === "number" && Number.isFinite(body.target)) {
+          try { achievability = M.assessAchievability(obs, space, body.target, goal); } catch { achievability = null; }
+          // INVERSE DESIGN — the recipes that hit the target (needs a few measurements first)
+          if (obs.length >= 5) { try { inverse = M.inverseDesign(obs, space, body.target); } catch { inverse = null; } }
+        }
+        return json(res, 200, { next, t: obs.length, best, goal, advice, territory, confidence, achievability, inverse });
+      } catch (e) { return json(res, 400, { error: "propose failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // INVERSE DESIGN — "find the recipes that hit my target value" (the inverse of optimization)
+    if (req.method === "POST" && path === "/inverse") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const space = { dims: Array.isArray(body.space) ? body.space : body.space?.dims };
+      if (!space.dims?.length) return json(res, 400, { error: "space must be a non-empty array of {name,type,min,max}" });
+      if (space.dims.length > 12) return json(res, 400, { error: "demo limit: ≤12 dimensions" });
+      if (typeof body.target !== "number" || !Number.isFinite(body.target)) return json(res, 400, { error: "target must be a finite number" });
+      const obs = Array.isArray(body.observations) ? body.observations.filter((o) => o && o.experiment && Number.isFinite(+o.value)).map((o) => ({ experiment: o.experiment, value: +o.value })) : [];
+      try { return json(res, 200, M.inverseDesign(obs, space, body.target)); }
+      catch (e) { return json(res, 400, { error: "inverse failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // SAFE OPTIMIZATION — best setting within constraints + safety margins, and a safe next proposal
+    if (req.method === "POST" && path === "/safe") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const space = { dims: Array.isArray(body.space) ? body.space : body.space?.dims };
+      if (!space.dims?.length) return json(res, 400, { error: "space must be a non-empty array of {name,type,min,max}" });
+      const cons = Array.isArray(body.constraints) ? body.constraints.filter((c) => c && c.name) : [];
+      const obs = Array.isArray(body.observations) ? body.observations.filter((o) => o && o.experiment && Number.isFinite(+o.value)).map((o) => ({ experiment: o.experiment, value: +o.value, metrics: (o.metrics && typeof o.metrics === "object") ? o.metrics : undefined })) : [];
+      const goal = body.goal === "minimize" ? "minimize" : "maximize";
+      try { const report = M.bestFeasible(obs, goal, cons); const nextSafe = M.proposeNextSafe(space, obs, goal, cons, (body.seed | 0) || 1); return json(res, 200, { ...report, nextSafe }); }
+      catch (e) { return json(res, 400, { error: "safe failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // WHAT-IF TWIN — "what score would I get at THIS setting?" (predict without running it)
+    if (req.method === "POST" && path === "/predict") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const space = { dims: Array.isArray(body.space) ? body.space : body.space?.dims };
+      if (!space.dims?.length) return json(res, 400, { error: "space must be a non-empty array of {name,type,min,max}" });
+      const obs = Array.isArray(body.observations) ? body.observations.filter((o) => o && o.experiment && Number.isFinite(+o.value)).map((o) => ({ experiment: o.experiment, value: +o.value })) : [];
+      if (!body.query || typeof body.query !== "object") return json(res, 400, { error: "query must be a {name:value} setting object" });
+      try { return json(res, 200, M.predictAt(obs, space, body.query)); }
+      catch (e) { return json(res, 400, { error: "predict failed: " + e.message.slice(0, 120) }); }
+    }
+
+    // BATCH PLANNER — "give me the k best experiments to run in PARALLEL this round"
+    if (req.method === "POST" && path === "/batch") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const space = { dims: Array.isArray(body.space) ? body.space : body.space?.dims };
+      if (!space.dims?.length) return json(res, 400, { error: "space must be a non-empty array of {name,type,min,max}" });
+      if (space.dims.length > 12) return json(res, 400, { error: "demo limit: ≤12 dimensions" });
+      const obs = Array.isArray(body.observations) ? body.observations.filter((o) => o && o.experiment && Number.isFinite(+o.value)).map((o) => ({ experiment: o.experiment, value: +o.value })) : [];
+      const goal = body.goal === "minimize" ? "minimize" : "maximize";
+      const k = Math.max(1, Math.min(16, (body.k | 0) || 4));
+      try { return json(res, 200, { batch: M.proposeBatch(space, obs, goal, k, (body.seed | 0) || 1), k, t: obs.length, goal }); }
+      catch (e) { return json(res, 400, { error: "batch failed: " + e.message.slice(0, 120) }); }
+    }
+
+    if (req.method === "POST" && path === "/next-multi") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const space = { dims: Array.isArray(body.space) ? body.space : body.space?.dims };
+      if (!space.dims?.length) return json(res, 400, { error: "space must be a non-empty array of {name,type,min,max}" });
+      if (space.dims.length > 12) return json(res, 400, { error: "demo limit: ≤12 dimensions" });
+      const goals = Array.isArray(body.goals) ? body.goals.map((g) => ({ name: g?.name, goal: g?.goal === "minimize" ? "minimize" : "maximize" })) : null;
+      if (!goals || !goals.length) return json(res, 400, { error: "goals must be a non-empty array of {goal:'maximize'|'minimize'} — one per objective" });
+      if (goals.length > 8) return json(res, 400, { error: "demo limit: ≤8 objectives" });
+      const obs = Array.isArray(body.observations) ? body.observations.filter((o) => o && o.experiment && Array.isArray(o.values) && o.values.length === goals.length && o.values.every((v) => Number.isFinite(+v))).map((o) => ({ experiment: o.experiment, values: o.values.map(Number) })) : [];
+      try {
+        const next = M.proposeNextMulti(space, obs, goals, (body.seed | 0) || 1);
+        const pareto = M.paretoFront(obs, goals);
+        return json(res, 200, { next, t: obs.length, goals, paretoFront: pareto, paretoSize: pareto.length });
+      } catch (e) { return json(res, 400, { error: "propose failed: " + e.message.slice(0, 120) }); }
+    }
+
+    if (req.method === "POST" && path === "/verify") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const v = M.verifyTrace(body.trace || body); return json(res, 200, v);
+    }
+    if (req.method === "POST" && path === "/poopt/verify") {
+      const body = await readBody(req); if (!body) return json(res, 400, { error: "invalid JSON" });
+      const cert = body.poopt || body; const v = M.verifyProofOfOptimization(cert);
+      return json(res, 200, { ...v, subject: cert?.subject ?? null, efficiencyPct: cert?.efficiencyPct ?? null, experimentsSaved: cert?.experimentsSaved ?? null, co2SavedKg: cert?.co2SavedKg ?? null });
+    }
+    json(res, 404, { error: "no such endpoint", path, endpoints: M.ENDPOINTS });
+  } catch (e) { json(res, 500, { error: e.message }); }
+});
+server.listen(PORT, HOST, () => process.stdout.write(`🌟 Melete discovery-as-a-service on http://${HOST}:${PORT}  (max budget ${MAX_BUDGET})\n`));

package/bin/melete.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * melete — the Self-Driving Discovery Brain CLI.
+ *   melete bench                       prove the brain beats random/grid (measured)
+ *   melete gauntlet                    run every module's correctness gauntlet (must be 100)
+ *   melete discover [opts]             run a closed-loop discovery + write a signed discovery trace
+ *   melete verify <trace.json>         re-verify a discovery trace OFFLINE (signatures + hash chain)
+ *
+ * discover options:
+ *   --demo                             use the built-in 2D benchmark surface as the oracle
+ *   --objective "<js: x,y -> number>"  custom objective, e.g. --objective "-(x-3)**2-(y+1)**2"
+ *   --space '<json>'                   [{name,type,min,max}]   (default: x,y in [0,10])
+ *   --budget N        --seed N         --goal maximize|minimize    --engine bayes|resonance
+ *   --target N                         stop early once reached
+ *   --out trace.json                   write the signed trace (default: ./melete-trace.json)
+ */
+import { writeFileSync, readFileSync } from "node:fs";
+import { createContext, runInContext } from "node:vm";
+import * as M from "../dist/index.js";
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flag = (n, d) => { const i = argv.indexOf("--" + n); return i >= 0 ? (argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : true) : d; };
+const out = (s) => process.stdout.write(s + "\n");
+
+async function main() {
+  if (cmd === "gauntlet") {
+    const g = await M.meleteGauntlet();
+    out(`\n🧪 MELETE GAUNTLET: ${g.score}/100\n`);
+    for (const m of g.modules) { out(`  ${m.score === 100 ? "✅" : "❌"} ${m.name.padEnd(10)} ${m.score}/100`); for (const c of m.checks) if (!c.pass) out(`       ✗ ${c.name}`); }
+    process.exit(g.score === 100 ? 0 : 1);
+  }
+
+  if (cmd === "bench" && flag("robust")) {
+    out(`\n🌟 SUPER NOVA robustness — portfolio vs each single arm, mean best across landscapes (higher = better):\n`);
+    const rows = await M.robustnessBench(+(flag("seeds", 6)));
+    out(`   landscape      PORTFOLIO   kernel-ucb   cmaes     resonance   random`);
+    for (const r of rows) {
+      const f = (v) => v.toFixed(3).padStart(9);
+      out(`   ${r.landscape.padEnd(13)} ${f(r.portfolio)}${r.portfolioIsBest ? " 🏆" : "   "} ${f(r.kernelUcb)} ${f(r.cmaes)} ${f(r.resonance)} ${f(r.random)}`);
+    }
+    out(`\n   → the portfolio is never the worst, and on the rugged landscape the ensemble beats every single algorithm.`);
+    out(`   No-Free-Lunch made productive: one engine that adapts to the problem instead of being re-tuned per problem.`);
+    process.exit(0);
+  }
+
+  if (cmd === "bench") {
+    const budget = +(flag("budget", 150)), target = +(flag("target", 0.99)), seeds = +(flag("seeds", 30));
+    out(`\n⚗️  Discovery benchmark — experiments to reach ${target} of the optimum (lower = better):\n`);
+    const sd = await M.resonanceVsBayes({ budget, target, seeds });
+    const row = (n, v) => out(`   ${n.padEnd(22)} ${v == null ? "did not reach within " + budget : v + " experiments"}`);
+    row("BRAIN (bayes core)", sd.bayes); row("random search (avg)", sd.random); row("systematic grid", sd.grid); row("resonance (experimental)", sd.resonance);
+    if (sd.bayes && sd.random) out(`\n   → the brain is ${(sd.random / sd.bayes).toFixed(1)}× more sample-efficient than random. Each saved experiment = saved reagents / robot-time / money.`);
+    out(`   honest: measured on a smooth multimodal surface; the resonance engine is experimental and currently does not beat the core.`);
+    process.exit(0);
+  }
+
+  if (cmd === "discover") {
+    const space = flag("space") ? JSON.parse(flag("space")) : { dims: [{ name: "x", type: "real", min: 0, max: 10 }, { name: "y", type: "real", min: 0, max: 10 }] };
+    let oracle;
+    const obj = flag("objective");
+    if (obj && obj !== true) { const ctx = createContext({ Math }); oracle = (e) => { for (const k of Object.keys(e)) ctx[k] = e[k]; return Number(runInContext(obj, ctx, { timeout: 200 })); }; }
+    else oracle = (e) => M.multimodal(e);   // --demo / default
+    const budget = +(flag("budget", 60)), seed = +(flag("seed", 1));
+    const goal = flag("goal", "maximize"), engine = flag("engine", "portfolio");
+    const target = flag("target") ? +flag("target") : undefined;
+    out(`\n🔬 Discovering (${engine} engine, ${goal}, budget ${budget})…`);
+    const sig = await M.discoverSigned({ space, oracle, budget, seed, goal, engine, target });
+    out(`   best value: ${sig.result.best.value.toFixed(6)}`);
+    out(`   at:         ${JSON.stringify(sig.result.best.experiment)}`);
+    out(`   experiments: ${sig.result.evaluations}   converged: ${sig.result.converged}`);
+    const file = flag("out", "melete-trace.json");
+    writeFileSync(file, JSON.stringify(sig.trace, null, 2));
+    out(`\n   📜 signed discovery trace → ${file}  (${sig.trace.frames.length} frames)`);
+    out(`   verify it offline:  melete verify ${file}`);
+    process.exit(0);
+  }
+
+  if (cmd === "tune") {
+    // melete tune --cmd "node train.js --lr {lr} --depth {depth}" --space '[...]' [--budget N] [--goal min]
+    const space = flag("space") ? JSON.parse(flag("space")) : null;
+    const cmdTpl = flag("cmd");
+    if (!space || !Array.isArray(space) && !space.dims || typeof cmdTpl !== "string") { out('usage: melete tune --cmd "your-prog --a {a} --b {b}" --space \'[{"name":"a","type":"real","min":0,"max":1}]\' [--budget N] [--goal minimize]\n  {dim} placeholders are filled with each proposed value; the LAST number your command prints is the score. No dataset needed.'); process.exit(2); }
+    const dims = Array.isArray(space) ? space : space.dims;
+    const { execSync } = await import("node:child_process");
+    const oracle = (e) => { const c = cmdTpl.replace(/\{(\w+)\}/g, (_, k) => String(e[k])); const sresult = String(execSync(c, { encoding: "utf8", timeout: 600000, stdio: ["ignore", "pipe", "ignore"] })); const v = Number((sresult.match(/-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?/g) ?? []).at(-1)); if (!Number.isFinite(v)) throw new Error("command printed no number"); return v; };
+    const budget = +(flag("budget", 30)), goal = flag("goal", "maximize");
+    out(`\n🔧 Tuning via your command (${goal}, budget ${budget}) — running it ${budget}× to find the best params…`);
+    const sig = await M.discoverSigned({ space: { dims }, oracle, budget, seed: (+flag("seed", 1)) || 1, goal, engine: "portfolio" });
+    out(`   best params: ${JSON.stringify(sig.result.best.experiment)}`);
+    out(`   best score:  ${sig.result.best.value}`);
+    out(`   ran your command ${sig.result.evaluations}× · arms: ${(sig.result.armStats || []).filter(a => a.pulls).map(a => a.name + "×" + a.pulls).join(" ")}`);
+    const file = flag("out", "melete-trace.json"); writeFileSync(file, JSON.stringify(sig.trace, null, 2));
+    out(`   📜 signed trace → ${file}  ·  verify: melete verify ${file}`);
+    process.exit(0);
+  }
+
+  if (cmd === "replicate") {
+    // melete replicate --trace t.json (--cmd "prog --a {a}" | --objective "<js>") [--samples N] [--tol 1e-3]
+    const tf = argv[1] && !argv[1].startsWith("--") ? argv[1] : flag("trace");
+    if (!tf) { out('usage: melete replicate <trace.json> --cmd "your-prog --a {a}"   (or --objective "<js>")\n  re-runs the discovery\'s best + a sample of its path to certify it REPLICATES — cheap cross-agent trust.'); process.exit(2); }
+    const trace = JSON.parse(readFileSync(tf, "utf8"));
+    const claim = M.extractClaim(trace);
+    let oracle;
+    if (flag("cmd")) { const { execSync } = await import("node:child_process"); const tpl = flag("cmd"); oracle = (e) => { const c = tpl.replace(/\{(\w+)\}/g, (_, k) => String(e[k])); const s = String(execSync(c, { encoding: "utf8", timeout: 600000, stdio: ["ignore", "pipe", "ignore"] })); return Number((s.match(/-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?/g) ?? []).at(-1)); }; }
+    else if (flag("objective") && flag("objective") !== true) { const obj = flag("objective"); const ctx = createContext({ Math }); oracle = (e) => { for (const k of Object.keys(e)) ctx[k] = e[k]; return Number(runInContext(obj, ctx, { timeout: 200 })); }; }
+    else { out("provide how to re-score: --cmd \"<command with {dims}>\" or --objective \"<js expression>\""); process.exit(2); }
+    out(`\n🔁 Replicating a published discovery (re-running its best + sampled points)…`);
+    const report = await M.replicate({ claim, oracle, samples: +(flag("samples", 3)), tolerance: +(flag("tol", 1e-3)) });
+    out(`   ${report.replicates ? "✅ REPLICATES" : "❌ DOES NOT REPLICATE"}`);
+    out(`   best: claimed ${report.best.claimed} · re-scored ${report.best.measured} · ${report.best.match ? "match" : "MISMATCH"}`);
+    for (const s of report.samples) out(`   · ${JSON.stringify(s.experiment)} claimed ${s.claimed} re-scored ${s.measured} ${s.match ? "✓" : "✗"}`);
+    out(`   ${report.reEvaluations} re-evaluations verified a ${claim.path.length}-experiment discovery (cross-agent trust, ${(claim.path.length / Math.max(1, report.reEvaluations)).toFixed(0)}× cheaper than re-running it).`);
+    const cert = M.certifyReplication(report); const cf = flag("out", "replication-cert.json"); writeFileSync(cf, JSON.stringify(cert, null, 2));
+    out(`   📜 signed replication certificate → ${cf}  ·  verify: melete verify ${cf}`);
+    process.exit(report.replicates ? 0 : 2);
+  }
+
+  if (cmd === "verify") {
+    const path = argv[1]; if (!path) { out("usage: melete verify <trace.json>"); process.exit(2); }
+    const trace = JSON.parse(readFileSync(path, "utf8"));
+    const v = M.verifyTrace(trace);
+    out(`\n📜 ${v.ok ? "✅ VALID" : "❌ INVALID"} discovery trace — ${v.frames} frames`);
+    out(`   ${v.reason}`);
+    if (!v.ok && v.brokenAt != null) out(`   broken at frame ${v.brokenAt}`);
+    out(`   (verified OFFLINE with the embedded public key — no Melete, no network, no shared secret)`);
+    process.exit(v.ok ? 0 : 1);
+  }
+
+  if (cmd === "multi") {
+    const goals = [{ name: "f1", goal: "maximize" }, { name: "f2", goal: "maximize" }];
+    const space = { dims: [{ name: "x", type: "real", min: 0, max: 10 }] };
+    const f = (x) => [-((x - 2) ** 2), -((x - 8) ** 2)];   // f1 peaks at x=2, f2 at x=8 → they trade off
+    const obs = [];
+    for (let i = 0; i < 40; i++) { const e = M.proposeNextMulti(space, obs, goals, 7); const v = f(e.x ?? 0); obs.push({ experiment: e, values: v }); }
+    const front = M.paretoFront(obs, goals).sort((a, b) => (a.experiment.x ?? 0) - (b.experiment.x ?? 0));
+    out("\n🧬 Multi-objective demo — two goals that trade off (f1 peaks at x=2, f2 at x=8)");
+    out(`   Pareto front: ${front.length} non-dominated trade-offs`);
+    for (const o of front) out(`     x=${(o.experiment.x ?? 0).toFixed(2)}   f1=${o.values[0].toFixed(2)}   f2=${o.values[1].toFixed(2)}`);
+    out("   (real use: POST /next-multi with YOUR N objectives — Melete proposes, you measure each)");
+    process.exit(0);
+  }
+
+  if (cmd === "poopt") {
+    const path = argv[1]; if (!path) { out("usage: melete poopt <certificate.json>"); process.exit(2); }
+    const cert = JSON.parse(readFileSync(path, "utf8"));
+    const v = M.verifyProofOfOptimization(cert.poopt || cert);
+    out(`\n💠 ${v.ok ? "✅ VALID" : "❌ INVALID"} Proof of Optimization`);
+    out(`   ${v.reason}`);
+    if (v.recomputed) out(`   efficiency: ${v.recomputed.efficiencyPct}%  (${v.recomputed.experimentsSaved} experiments saved vs a full grid sweep)`);
+    out(`   (verified OFFLINE with the embedded public key — no Melete, no network)`);
+    process.exit(v.ok ? 0 : 1);
+  }
+
+  out("melete — the Self-Driving Discovery Brain\n");
+  out("  melete tune --cmd \"prog --a {a}\" --space '[...]'   tune ANY command/script (no dataset needed)");
+  out("  melete bench [--robust]      prove the brain beats random/grid");
+  out("  melete gauntlet              run all correctness gauntlets");
+  out("  melete discover --demo       run a discovery + write a signed trace");
+  out("  melete multi                 multi-objective demo — print the Pareto front");
+  out("  melete verify <trace.json>   re-verify a discovery trace offline");
+  out("  melete poopt <cert.json>     verify a Proof of Optimization offline");
+  process.exit(cmd ? 1 : 0);
+}
+main().catch((e) => { out("error: " + e.message); process.exit(1); });