@ruvector/ruvllm 3.0.0 → 4.0.1

package/package.json

@@ -1,136 +1,65 @@
 {
   "name": "@ruvector/ruvllm",
-  "version": "3.0.0",
-  "description": "Self-learning LLM runtime \u2014 TurboQuant KV-cache (6-8x compression), SONA adaptive learning, FlashAttention, speculative decoding, GGUF inference",
-  "main": "dist/cjs/index.js",
-  "module": "dist/esm/index.js",
-  "types": "dist/cjs/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/esm/index.d.ts",
-        "default": "./dist/esm/index.js"
-      },
-      "require": {
-        "types": "./dist/cjs/index.d.ts",
-        "default": "./dist/cjs/index.js"
-      }
-    },
-    "./simd": {
-      "import": {
-        "types": "./dist/esm/simd.d.ts",
-        "default": "./dist/esm/simd.js"
-      },
-      "require": {
-        "types": "./dist/cjs/simd.d.ts",
-        "default": "./dist/cjs/simd.js"
-      }
-    }
-  },
-  "bin": {
-    "ruvllm": "./bin/cli.js"
-  },
-  "napi": {
-    "name": "ruvllm",
-    "binaryName": "ruvllm",
-    "targets": [
-      "x86_64-unknown-linux-gnu",
-      "aarch64-unknown-linux-gnu",
-      "x86_64-apple-darwin",
-      "aarch64-apple-darwin",
-      "x86_64-pc-windows-msvc"
-    ]
-  },
-  "scripts": {
-    "artifacts": "napi artifacts",
-    "build": "npm run build:cjs && npm run build:esm",
-    "build:cjs": "tsc",
-    "build:esm": "tsc -p tsconfig.esm.json && node scripts/fix-esm-extensions.mjs",
-    "verify:esm": "node scripts/fix-esm-extensions.mjs --verify",
-    "build:native": "napi build --platform --release --cargo-cwd ../../../examples/ruvLLM --features napi,candle --cargo-flags=--lib",
-    "build:debug": "napi build --platform --cargo-cwd ../../../examples/ruvLLM --features napi,candle --cargo-flags=--lib",
-    "prepublishOnly": "npm run build",
-    "test": "node --test test/*.test.js",
-    "test:esm-smoke": "node scripts/smoke-esm.mjs",
-    "universal": "napi universal",
-    "version": "napi version",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
-  },
-  "devDependencies": {
-    "@napi-rs/cli": "^2.18.0",
-    "@types/node": "^20.10.5",
-    "typescript": "^5.3.3"
-  },
-  "dependencies": {
-    "chalk": "^4.1.2",
-    "commander": "^12.0.0",
-    "ora": "^5.4.1"
+  "version": "4.0.1",
+  "type": "module",
+  "description": "Bounded RuVLLM weight experiments, a durable GPU job loop with a Vast.ai host adapter, and verified paired measurements",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ruvnet/ruvllm.git",
+    "directory": "integrations/metaharness"
   },
-  "optionalDependencies": {
-    "@ruvector/ruvllm-linux-x64-gnu": "2.0.1",
-    "@ruvector/ruvllm-linux-arm64-gnu": "2.0.1",
-    "@ruvector/ruvllm-darwin-x64": "2.0.1",
-    "@ruvector/ruvllm-darwin-arm64": "2.0.1",
-    "@ruvector/ruvllm-win32-x64-msvc": "2.0.1"
+  "homepage": "https://github.com/ruvnet/ruvllm/tree/main/integrations/metaharness#readme",
+  "bugs": {
+    "url": "https://github.com/ruvnet/ruvllm/issues"
   },
   "keywords": [
     "ruvllm",
-    "llm",
-    "self-learning",
-    "adaptive-learning",
-    "sona",
+    "metaharness",
     "lora",
-    "ewc",
-    "hnsw",
-    "vector-database",
-    "fastgrnn",
-    "router",
-    "simd",
-    "inference",
-    "federated-learning",
-    "continual-learning",
-    "machine-learning",
-    "ai",
-    "deep-learning",
-    "napi",
-    "rust",
-    "ruvector",
-    "turboquant",
-    "kv-cache",
-    "quantization",
-    "flash-attention",
-    "speculative-decoding",
-    "gguf",
-    "mamba",
-    "transformer",
-    "edge-ai",
-    "local-llm",
-    "model-compression"
+    "gpu",
+    "vast.ai",
+    "evaluation",
+    "weight-editing"
   ],
-  "author": "rUv Team <team@ruv.io>",
-  "license": "MIT OR Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/ruvnet/ruvector.git",
-    "directory": "npm/packages/ruvllm"
+  "engines": {
+    "node": ">=22"
   },
-  "homepage": "https://github.com/ruvnet/ruvector/tree/main/examples/ruvLLM",
-  "bugs": {
-    "url": "https://github.com/ruvnet/ruvector/issues"
+  "bin": {
+    "ruvllm": "src/cli.mjs",
+    "ruvllm-gpu-loop": "src/gpu-loop-cli.mjs",
+    "ruvllm-adapters": "src/adapters-cli.mjs"
   },
-  "engines": {
-    "node": ">= 18"
+  "exports": {
+    ".": "./src/engine.mjs",
+    "./adapters": "./src/adapters.mjs",
+    "./fixture": "./src/fixture.mjs",
+    "./gpu-loop": "./src/gpu-loop.mjs",
+    "./gpu-host": "./src/gpu-host.mjs",
+    "./gpu-spool-adapter": "./src/gpu-spool-adapter.mjs",
+    "./vast-host-adapter": "./src/vast-host-adapter.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "examples/",
+    "README.md",
+    "GPU-LOOP.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "bench": "node bench/run.mjs",
+    "prepack": "cp ../../LICENSE ../../NOTICE .",
+    "postpack": "rm -f LICENSE NOTICE"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "files": [
-    "dist",
-    "bin",
-    "scripts",
-    "*.node",
-    "README.md"
-  ]
+  "dependencies": {
+    "@metaharness/darwin": "0.12.0",
+    "@metaharness/flywheel": "0.1.13",
+    "@metaharness/weight-eft": "0.1.2"
+  }
 }

package/src/adapters-cli.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { exportArchive, trainingPlan, selectDevelopmentCandidate } from './adapters.mjs';
+
+const operations = { export: exportArchive, 'training-plan': trainingPlan, select: selectDevelopmentCandidate };
+if (process.argv.length !== 3 || !Object.hasOwn(operations, process.argv[2])) {
+  process.stderr.write('Usage: node src/adapters-cli.mjs export|training-plan|select < input.json\nJSON data only; no training, inference or activation is executed.\n');
+  process.exitCode = process.argv[2] === '--help' ? 0 : 2;
+} else {
+  try {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+      bytes += chunk.length;
+      if (bytes > 16 * 1024 * 1024) throw new Error('Input exceeds 16 MiB');
+      chunks.push(chunk);
+    }
+    const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    process.stdout.write(JSON.stringify(await operations[process.argv[2]](input), null, 2) + '\n');
+  } catch (error) {
+    process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + '\n');
+    process.exitCode = 1;
+  }
+}

package/src/adapters.mjs

@@ -0,0 +1,91 @@
+// MetaHarness adapters are data-only: no provider requests, trainer launch or activation.
+import { createHash } from 'node:crypto';
+import { exportTrainingData, twoStagePlan } from '@metaharness/weight-eft';
+import { runContrastive, digestDocument } from '@metaharness/darwin/contrastive';
+
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const require = (condition, message) => { if (!condition) throw new Error(message); };
+const identifier = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(value);
+
+/** Export reviewed caller-asserted trajectories; held-out instance IDs are always excluded. */
+export function exportArchive({ archive, evalHoldout, maxTokens = 12000 }) {
+  require(Array.isArray(archive) && archive.length <= 10000, 'Archive limit is 10000 trajectories');
+  require(Array.isArray(evalHoldout) && evalHoldout.every(identifier), 'Explicit eval holdout IDs required');
+  require(Number.isInteger(maxTokens) && maxTokens >= 1 && maxTokens <= 32768, 'Invalid token budget');
+  require(Buffer.byteLength(JSON.stringify(archive)) <= 16 * 1024 * 1024, 'Archive exceeds 16 MiB');
+  for (const row of archive) {
+    require(row && identifier(row.instance_id) && typeof row.model === 'string' && row.model.length > 0,
+      'Invalid trajectory identity');
+    require(['cheap', 'frontier'].includes(row.tier) && typeof row.resolved === 'boolean', 'Invalid trajectory outcome');
+    require(typeof row.model_patch === 'string' && Array.isArray(row.messages) && row.messages.length <= 4096,
+      'Invalid trajectory content');
+    for (const message of row.messages) {
+      require(message && ['system', 'user', 'assistant', 'tool'].includes(message.role)
+        && (typeof message.content === 'string' || message.content === null), 'Invalid message');
+    }
+  }
+  const result = exportTrainingData(archive, {
+    evalHoldout, maxTokens, truncateOverLength: false, dropRewardHacked: true,
+  });
+  return {
+    schema: 'ruvllm-training-export/v1', ...result,
+    archiveSha256: hash(archive), holdoutSha256: hash(evalHoldout),
+    evidenceOrigin: 'caller-asserted-trajectories', trainingExecuted: false,
+    productionActivation: false,
+  };
+}
+
+/** Upstream command is informational; this checkout has no `ruvllm microlora` CLI. */
+export function trainingPlan({ base, sftPath, dpoPath, adapterPrefix }) {
+  require(base && typeof base.id === 'string' && Number.isFinite(base.paramsB), 'Invalid model');
+  for (const path of [sftPath, dpoPath, adapterPrefix]) require(typeof path === 'string' && path.length > 0, 'Path required');
+  return {
+    schema: 'ruvllm-training-plan/v1',
+    plans: twoStagePlan(base, sftPath, dpoPath, adapterPrefix),
+    executionStatus: 'not_executed',
+    runnerCompatibility: 'adapter-required',
+    reason: 'The upstream ruvllm microlora command is not implemented by this standalone checkout. Use a separately validated trainer; DPO requires an additional trainer implementation.',
+    productionActivation: false,
+  };
+}
+
+/** Replay bounded measured scores through Darwin. This ranks development evidence only. */
+export async function selectDevelopmentCandidate({ baseline, candidates, envelope }) {
+  require(envelope && typeof envelope === 'object' && !Array.isArray(envelope), 'Immutable experiment envelope required');
+  require(Array.isArray(candidates) && candidates.length > 0 && candidates.length <= 32, 'Expected 1..32 candidates');
+  const all = [baseline, ...candidates];
+  for (const candidate of all) {
+    require(candidate && identifier(candidate.id) && Number.isFinite(candidate.score)
+      && candidate.score >= 0 && candidate.score <= 1
+      && /^[a-f0-9]{64}$/.test(candidate.evidenceSha256), 'Invalid measured candidate');
+  }
+  require(new Set(all.map(row => row.id)).size === all.length, 'Duplicate candidate ID');
+  const byId = new Map(all.map(row => [row.id, { ...row }]));
+  const best = candidates.reduce((a, b) => b.score > a.score ? b : a);
+  const document = { components: [{ id: 'weight-candidate', scope: 'domain', content: { id: baseline.id } }] };
+  const result = await runContrastive({
+    tenantId: 'local', projectId: 'ruvllm', task: { purpose: 'development-candidate-selection' },
+    environment: { mode: 'evidence-replay' },
+    library: { tenantId: 'local', projectId: 'ruvllm', entries: [] },
+    envelope, baseline: document,
+    budget: { maxUsd: 0, maxCalls: 5, timeoutMs: 5000, probeUsd: 0, proposeUsd: 0, composeUsd: 0 },
+    evaluator: {
+      surfaceAware: true,
+      async probe({ candidate }) {
+        const row = byId.get(candidate.components[0].content.id);
+        require(row, 'Unmeasured candidate');
+        return { appliedDigest: digestDocument(candidate), score: row.score, costUsd: 0,
+          observations: [{ id: 'measured-failure', componentId: 'weight-candidate', message: `Bound evidence ${row.evidenceSha256}` }] };
+      },
+    },
+    proposer: {
+      async propose({ scope }) {
+        return { edits: scope === 'domain' ? [{ componentId: 'weight-candidate', content: { id: best.id },
+          citations: ['measured-failure'] }] : [], costUsd: 0 };
+      },
+    },
+  });
+  return { schema: 'ruvllm-development-selection/v1', selectedId: result.candidate.components[0].content.id,
+    envelopeSha256: hash(envelope), evidenceSha256: hash(all), evidenceMode: 'score-replay',
+    result, independentConfirmation: false, productionActivation: false };
+}

package/src/cli.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { runExperiment } from './engine.mjs';
+import { createFixture } from './fixture.mjs';
+
+const [command, ...args] = process.argv.slice(2);
+function options(allowed) {
+  const result = {};
+  for (let i = 0; i < args.length; i += 2) {
+    if (!allowed.includes(args[i]) || !args[i + 1] || Object.hasOwn(result, args[i])) throw new Error('Unknown, duplicate or missing argument');
+    result[args[i]] = args[i + 1];
+  }
+  return result;
+}
+try {
+  let result;
+  if (command === 'run') {
+    const flags = options(['--config', '--plan']);
+    result = await runExperiment({ configPath: flags['--config'], planPath: flags['--plan'] });
+  } else if (command === 'fixture') {
+    const flags = options(['--dir', '--binary']);
+    if (!flags['--dir'] || !flags['--binary']) throw new Error('fixture requires --dir and --binary');
+    result = await runExperiment(await createFixture({ directory: flags['--dir'], binaryPath: flags['--binary'] }));
+  } else if (command === '--help' || command === 'help') {
+    console.log('Usage: ruvllm-experiment run --config ABS --plan ABS\n       ruvllm-experiment fixture --dir NEW_ABS --binary ABS');
+    process.exit(0);
+  } else throw new Error('Expected run, fixture or --help');
+  console.log(JSON.stringify(result, null, 2));
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, error: error.message, productionActivation: false })); process.exitCode = 1;
+}

package/src/engine.mjs

@@ -0,0 +1,238 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { open, lstat, realpath, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve, dirname, join, relative, isAbsolute, parse } from 'node:path';
+import { meetsPromotionRule, gateFingerprint } from '@metaharness/flywheel';
+import { selectDevelopmentCandidate } from './adapters.mjs';
+
+const MAX_JSON = 1024 * 1024;
+const HASH = /^[a-f0-9]{64}$/;
+const inside = (root, path) => path === root || (!relative(root, path).startsWith('..') && !isAbsolute(relative(root, path)));
+const assert = (condition, message) => { if (!condition) throw new Error(message); };
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+
+function keys(value, required, optional = []) {
+  assert(value && typeof value === 'object' && !Array.isArray(value), 'Expected JSON object');
+  assert(required.every(k => Object.hasOwn(value, k)), `Missing fields: ${required.join(', ')}`);
+  assert(Object.keys(value).every(k => [...required, ...optional].includes(k)), 'Unknown object fields');
+}
+
+// Reject duplicate object keys and non-finite numbers before applying schemas.
+export function parseJson(bytes) {
+  const text = bytes.toString('utf8'); let index = 0;
+  const ws = () => { while (/[ \t\r\n]/.test(text[index] ?? '') && index < text.length) index++; };
+  function string() {
+    const start = index++; let escaped = false;
+    while (index < text.length) {
+      const c = text[index++];
+      if (c === '"' && !escaped) return JSON.parse(text.slice(start, index));
+      if (c === '\\' && !escaped) escaped = true; else escaped = false;
+    }
+    throw new Error('Unterminated JSON string');
+  }
+  function value(depth = 0) {
+    assert(depth < 64, 'JSON nesting limit'); ws();
+    if (text[index] === '"') return string();
+    if (text[index] === '{') {
+      index++; ws(); const result = Object.create(null); const seen = new Set();
+      if (text[index] === '}') { index++; return result; }
+      while (true) {
+        ws(); assert(text[index] === '"', 'Invalid JSON key'); const key = string();
+        assert(!seen.has(key), 'Duplicate JSON key'); seen.add(key); ws();
+        assert(text[index++] === ':', 'Invalid JSON separator'); result[key] = value(depth + 1); ws();
+        const end = text[index++]; if (end === '}') return result; assert(end === ',', 'Invalid JSON object');
+      }
+    }
+    if (text[index] === '[') {
+      index++; ws(); const result = []; if (text[index] === ']') { index++; return result; }
+      while (true) { result.push(value(depth + 1)); ws(); const end = text[index++]; if (end === ']') return result; assert(end === ',', 'Invalid JSON array'); }
+    }
+    const token = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(index));
+    assert(token, 'Invalid JSON value'); index += token[0].length; const result = JSON.parse(token[0]);
+    assert(typeof result !== 'number' || Number.isFinite(result), 'Non-finite JSON number'); return result;
+  }
+  const result = value(); ws(); assert(index === text.length, 'Trailing JSON data'); return result;
+}
+
+export async function checkedPath(path, { directory = false, roots } = {}) {
+  assert(typeof path === 'string' && isAbsolute(path) && !path.includes('\0'), 'Expected absolute path');
+  assert(path === resolve(path), 'Path must be canonical without traversal');
+  let cursor = parse(path).root;
+  for (const part of path.slice(cursor.length).split('/').filter(Boolean)) {
+    cursor = join(cursor, part); const stat = await lstat(cursor); assert(!stat.isSymbolicLink(), 'Symlinks are forbidden');
+  }
+  const canonical = await realpath(path); const stat = await lstat(canonical);
+  assert(directory ? stat.isDirectory() : stat.isFile(), directory ? 'Expected directory' : 'Expected regular file');
+  if (roots) assert(roots.some(root => inside(root, canonical)), 'Path outside configured read roots');
+  return canonical;
+}
+
+async function boundedRead(path, limit = MAX_JSON) {
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await file.stat(); assert(stat.isFile() && stat.size <= limit, 'Control file too large or not regular');
+    const bytes = Buffer.alloc(stat.size); const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+    assert(bytesRead === bytes.length, 'Control file changed during read'); return bytes;
+  } finally { await file.close(); }
+}
+
+export async function fileDigest(path) {
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    assert((await file.stat()).isFile(), 'Expected regular file');
+    const hash = createHash('sha256'); const bytes = Buffer.alloc(1024 * 1024); let position = 0;
+    while (true) { const { bytesRead } = await file.read(bytes, 0, bytes.length, position); if (!bytesRead) break; hash.update(bytes.subarray(0, bytesRead)); position += bytesRead; }
+    return hash.digest('hex');
+  } finally { await file.close(); }
+}
+
+async function identicalFiles(a, b) {
+  const first = await open(a, constants.O_RDONLY | constants.O_NOFOLLOW), second = await open(b, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const size = (await first.stat()).size; if (size !== (await second.stat()).size) return false;
+    const x = Buffer.alloc(Math.min(size, 1024 * 1024)), y = Buffer.alloc(x.length);
+    for (let position = 0; position < size; position += x.length) {
+      const length = Math.min(x.length, size - position);
+      const [rx, ry] = await Promise.all([first.read(x, 0, length, position), second.read(y, 0, length, position)]);
+      if (rx.bytesRead !== length || ry.bytesRead !== length || !x.subarray(0, length).equals(y.subarray(0, length))) return false;
+    }
+    return true;
+  } finally { await first.close(); await second.close(); }
+}
+
+async function save(path, value) { await writeFile(path, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 }); }
+
+async function runtime(configPath) {
+  configPath = await checkedPath(configPath); const bytes = await boundedRead(configPath); const config = parseJson(bytes);
+  keys(config, ['schema', 'binaryPath', 'binarySha256', 'readRoots', 'writeRoot', 'policySha256s', 'maxCandidates', 'timeoutMs']);
+  assert(config.schema === 'ruvllm-experiment-runtime/v1', 'Unsupported runtime schema');
+  assert(HASH.test(config.binarySha256), 'Invalid binary digest');
+  assert(Array.isArray(config.readRoots) && config.readRoots.length > 0 && config.readRoots.length <= 32, 'Invalid read roots');
+  assert(Array.isArray(config.policySha256s) && config.policySha256s.length > 0 && config.policySha256s.length <= 128 && config.policySha256s.every(x => HASH.test(x)), 'Invalid approved policy digests');
+  assert(Number.isInteger(config.maxCandidates) && config.maxCandidates >= 1 && config.maxCandidates <= 16, 'Candidate limit must be 1..16');
+  assert(Number.isInteger(config.timeoutMs) && config.timeoutMs >= 100 && config.timeoutMs <= 300000, 'Invalid timeout');
+  config.readRoots = await Promise.all(config.readRoots.map(path => checkedPath(path, { directory: true })));
+  config.writeRoot = await checkedPath(config.writeRoot, { directory: true });
+  config.binaryPath = await checkedPath(config.binaryPath);
+  assert(!inside(config.writeRoot, configPath) && !inside(config.writeRoot, config.binaryPath), 'Runtime config and binary must be outside write root');
+  const stat = await lstat(configPath); assert((stat.mode & 0o077) === 0, 'Runtime config must be owner-only');
+  assert(((await lstat(config.writeRoot)).mode & 0o077) === 0, 'Write root must be private');
+  assert(await fileDigest(config.binaryPath) === config.binarySha256, 'Binary digest mismatch');
+  return { ...config, configSha256: sha256(bytes) };
+}
+
+async function native(config, request) {
+  assert(await fileDigest(config.binaryPath) === config.binarySha256, 'Binary digest mismatch');
+  const input = JSON.stringify(request); assert(Buffer.byteLength(input) <= 64 * 1024, 'Native request limit');
+  return new Promise((accept, reject) => {
+    const environment = Object.fromEntries(['PATH', 'HOME', 'TMPDIR', 'LANG', 'LC_ALL'].filter(k => process.env[k]).map(k => [k, process.env[k]]));
+    const child = spawn(config.binaryPath, [], { stdio: ['pipe', 'pipe', 'pipe'], env: environment, shell: false });
+    let stdout = [], stderr = [], outSize = 0, errSize = 0, failure;
+    const fail = message => { failure ??= new Error(message); child.kill('SIGKILL'); };
+    const timer = setTimeout(() => fail('Native operation timed out'), config.timeoutMs);
+    child.stdout.on('data', bytes => { outSize += bytes.length; if (outSize > MAX_JSON) fail('Native stdout limit'); else stdout.push(bytes); });
+    child.stderr.on('data', bytes => { errSize += bytes.length; if (errSize > 64 * 1024) fail('Native stderr limit'); else stderr.push(bytes); });
+    child.on('error', error => { clearTimeout(timer); reject(error); });
+    child.stdin.on('error', () => {});
+    child.on('close', code => {
+      clearTimeout(timer); if (failure) return reject(failure);
+      if (code !== 0) return reject(new Error(`Native ${request.op} rejected: ${Buffer.concat(stderr).toString('utf8').slice(0, 2048)}`));
+      try { accept(parseJson(Buffer.concat(stdout))); } catch (error) { reject(error); }
+    });
+    child.stdin.end(input);
+  });
+}
+
+export async function runExperiment({ configPath, planPath }) {
+  const config = await runtime(configPath); planPath = await checkedPath(planPath, { roots: config.readRoots });
+  const planBytes = await boundedRead(planPath), plan = parseJson(planBytes);
+  keys(plan, ['schema', 'evidenceMode', 'source', 'policy', 'candidates']);
+  assert(plan.schema === 'ruvllm-experiment-plan/v1', 'Unsupported plan schema');
+  assert(['fixture', 'external'].includes(plan.evidenceMode), 'Explicit fixture or external evidence mode required');
+  assert(Array.isArray(plan.candidates) && plan.candidates.length >= 1 && plan.candidates.length <= config.maxCandidates, 'Candidate limit exceeded');
+  const source = await checkedPath(plan.source, { roots: config.readRoots });
+  const policyPath = await checkedPath(plan.policy, { roots: config.readRoots });
+  const policyBytes = await boundedRead(policyPath), policy = parseJson(policyBytes), policySha256 = sha256(policyBytes);
+  assert(config.policySha256s.includes(policySha256), 'Policy is not approved');
+  assert(Array.isArray(policy.allowed_tensors) && policy.allowed_tensors.length > 0 && policy.allowed_tensors.length <= 256, 'Invalid tensor selection');
+  const ids = new Set(), candidates = [];
+  for (const candidate of plan.candidates) {
+    keys(candidate, ['id', 'patch'], ['evaluation']);
+    assert(typeof candidate.id === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(candidate.id) && !ids.has(candidate.id), 'Invalid or duplicate candidate id'); ids.add(candidate.id);
+    const patchPath = await checkedPath(candidate.patch, { roots: config.readRoots }), patchBytes = await boundedRead(patchPath);
+    const entry = { ...candidate, patchBytes, patch: parseJson(patchBytes) };
+    if (candidate.evaluation) { const path = await checkedPath(candidate.evaluation, { roots: config.readRoots }); entry.evaluationBytes = await boundedRead(path); entry.evaluationValue = parseJson(entry.evaluationBytes); }
+    candidates.push(entry);
+  }
+  const runDirectory = join(config.writeRoot, `run-${randomUUID()}`); await mkdir(runDirectory, { mode: 0o700 });
+  await writeFile(join(runDirectory, 'plan.json'), planBytes, { flag: 'wx', mode: 0o600 });
+  const copiedPolicy = join(runDirectory, 'policy.json'); await writeFile(copiedPolicy, policyBytes, { flag: 'wx', mode: 0o600 });
+  const inspection = await native(config, { op: 'inspect', source, tensors: policy.allowed_tensors });
+  const reportPath = join(runDirectory, 'report.json');
+  const report = { schema: 'ruvllm-experiment-report/v1', evidenceMode: plan.evidenceMode, sourceSha256: inspection.source_sha256,
+    policySha256, planSha256: sha256(planBytes), binarySha256: config.binarySha256, configSha256: config.configSha256,
+    gateSha256: gateFingerprint(meetsPromotionRule), runDirectory, reportPath, productionActivation: false, activationAuthorized: false,
+    inferencePerformed: false, independentConfirmation: false, evaluationTrust: 'caller-supplied; not independent attestation', costMetered: false, candidates: [], selectedCandidateId: null };
+  let sharedEvaluation, baselineScore;
+  for (const candidate of candidates) {
+    const output = join(runDirectory, candidate.id); await mkdir(output, { mode: 0o700 });
+    const patch = join(output, 'patch.json'), checkpoint = join(output, 'candidate.safetensors'), receiptPath = join(output, 'receipt.json');
+    await writeFile(patch, candidate.patchBytes, { flag: 'wx', mode: 0o600 });
+    const result = { id: candidate.id, status: 'rejected', patchSha256: sha256(candidate.patchBytes), rollbackExact: false, rollbackVerified: false, rvfVerified: false, productionActivation: false };
+    let receipt;
+    try {
+      assert(candidate.patch.source_sha256 === report.sourceSha256, 'Patch source mismatch');
+      receipt = await native(config, { op: 'patch', source, output: checkpoint, patch, policy: copiedPolicy });
+      assert(receipt.source_sha256 === report.sourceSha256 && receipt.policy_sha256 === policySha256 && receipt.patch_sha256 === result.patchSha256 && receipt.activation_authorized === false, 'Native receipt binding mismatch');
+      await save(receiptPath, receipt); result.candidateSha256 = receipt.candidate_sha256; result.status = 'unqualified';
+      let evaluationPath;
+      if (candidate.evaluationBytes) {
+        evaluationPath = join(output, 'evaluation.json'); await writeFile(evaluationPath, candidate.evaluationBytes, { flag: 'wx', mode: 0o600 });
+        const value = candidate.evaluationValue;
+        result.evaluationSha256 = sha256(candidate.evaluationBytes);
+        // All candidates must use the same suite, baseline, runtime and protocol.
+        const signature = JSON.stringify([value.suite_sha256, value.protocol_sha256, value.baseline, value.total, value.baseline_correct, value.baseline_truncated, value.baseline_output_sha256]);
+        const validation = await native(config, { op: 'evaluate', evaluation: evaluationPath, receipt: receiptPath });
+        assert(validation.valid === true && validation.activation_authorized === false, 'Evaluation not valid');
+        if (sharedEvaluation) assert(sharedEvaluation === signature, 'Candidates evaluated against different baselines or suites'); else sharedEvaluation = signature;
+        const total = value.total;
+        assert(Number.isInteger(total) && total > 0, 'Evaluation total must be positive');
+        const score = (correct, truncated) => ({ primary: correct / total, noopRate: truncated / total, costPerWin: 0, regressed: false });
+        baselineScore = value.baseline_correct / total;
+        const gate = meetsPromotionRule({ baseline: score(value.baseline_correct, value.baseline_truncated), candidate: score(value.candidate_correct, value.candidate_truncated) });
+        if (value.candidate_correct <= value.baseline_correct) { gate.promote = false; gate.reasons.push('no_strict_accuracy_improvement'); }
+        result.gate = { ...gate, meaning: 'research qualification only; no activation authority' };
+        result.score = score(value.candidate_correct, value.candidate_truncated);
+        result.status = gate.promote ? 'qualified' : 'unqualified';
+      } else result.gate = { promote: false, reasons: ['missing_evaluation'] };
+      const artifact = join(output, 'evidence.rvf');
+      const exported = await native(config, { op: 'export', patch, policy: copiedPolicy, receipt: receiptPath, output: artifact, ...(evaluationPath ? { evaluation: evaluationPath } : {}) });
+      const verified = await native(config, { op: 'verify', artifact, expected_sha256: exported.sha256 });
+      assert(verified.integrity_verified === true && verified.activation_authorized === false, 'RVF verification failed'); result.rvfSha256 = exported.sha256; result.rvfVerified = true;
+    } catch (error) { result.status = 'rejected'; result.error = error.message; }
+    finally {
+      if (receipt) {
+        const restored = join(output, 'restored.safetensors');
+        const rollback = await native(config, { op: 'rollback', source: checkpoint, output: restored, patch, policy: copiedPolicy, receipt: receiptPath });
+        result.restoredSha256 = rollback.candidate_sha256;
+        result.rollbackExact = result.rollbackVerified = rollback.candidate_sha256 === report.sourceSha256 && await identicalFiles(source, restored);
+        assert(result.rollbackExact, 'Rollback did not restore original bytes');
+      }
+    }
+    report.candidates.push(result);
+  }
+  assert(await fileDigest(source) === report.sourceSha256, 'Source checkpoint changed during experiment');
+  const qualified = report.candidates.filter(candidate => candidate.status === 'qualified');
+  qualified.sort((a, b) => b.score.primary - a.score.primary || a.score.noopRate - b.score.noopRate || a.id.localeCompare(b.id));
+  if (qualified.length) {
+    report.developmentSelection = await selectDevelopmentCandidate({
+      baseline: { id: 'source.baseline', score: baselineScore, evidenceSha256: report.sourceSha256 },
+      candidates: qualified.map(candidate => ({ id: candidate.id, score: candidate.score.primary, evidenceSha256: candidate.evaluationSha256 })),
+      envelope: Object.fromEntries(['sourceSha256', 'policySha256', 'binarySha256', 'gateSha256', 'planSha256'].map(key => [key, report[key]])),
+    });
+    assert(qualified.some(candidate => candidate.id === report.developmentSelection.selectedId), 'Darwin selected an unqualified candidate');
+    report.selectedCandidateId = report.developmentSelection.selectedId;
+  }
+  await save(reportPath, report); return report;
+}

package/src/fixture.mjs

@@ -0,0 +1,38 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fileDigest, sha256, checkedPath } from './engine.mjs';
+
+// This deterministic fixture measures contracts and native I/O, never model quality.
+export async function createFixture({ directory, binaryPath }) {
+  directory = resolve(directory); binaryPath = await checkedPath(resolve(binaryPath));
+  await mkdir(directory, { mode: 0o700 });
+  const inputs = join(directory, 'inputs'), outputs = join(directory, 'outputs');
+  await mkdir(inputs, { mode: 0o700 }); await mkdir(outputs, { mode: 0o700 });
+  async function json(name, value) {
+    const path = join(inputs, name), bytes = Buffer.from(JSON.stringify(value, null, 2) + '\n');
+    await writeFile(path, bytes, { flag: 'wx', mode: 0o600 }); return { path, sha256: sha256(bytes) };
+  }
+  const rawHeader = JSON.stringify({ 'layer.weight': { dtype: 'BF16', shape: [4], data_offsets: [0, 8] } });
+  const header = Buffer.from(rawHeader + ' '.repeat((8 - Buffer.byteLength(rawHeader) % 8) % 8));
+  const size = Buffer.alloc(8); size.writeBigUInt64LE(BigInt(header.length));
+  const values = Buffer.alloc(8); [0x3f80, 0x4000, 0x4040, 0x4080].forEach((value, i) => values.writeUInt16LE(value, i * 2));
+  const original = Buffer.concat([size, header, values]), source = join(inputs, 'original.safetensors');
+  await writeFile(source, original, { flag: 'wx', mode: 0o600 });
+  const candidate = Buffer.from(original); candidate.writeUInt16LE(0x4020, candidate.length - 6);
+  const policy = await json('policy.json', { allowed_tensors: ['layer.weight'], max_changed_values: 1, max_l2: 0.5, max_abs_delta: 0.5, max_relative_l2: 1, protected: [] });
+  const patch = await json('patch.json', { schema: 'ruvllm.weight_patch.v1', source_sha256: sha256(original), edits: [{ tensor: 'layer.weight', index: 1, old_bits: 0x4000, new_bits: 0x4020 }] });
+  const binding = { runtime_sha256: await fileDigest(binaryPath), topology_sha256: '2'.repeat(64), protocol_sha256: '3'.repeat(64), toolchain_sha256: '4'.repeat(64) };
+  const evaluation = await json('fixture-evaluation.json', {
+    schema: 'ruvllm.weight_evaluation.v1',
+    baseline: { ...binding, model_generation: 0, model_sha256: sha256(original), patch_sha256: '0'.repeat(64) },
+    candidate: { ...binding, model_generation: 1, model_sha256: sha256(candidate), patch_sha256: patch.sha256 },
+    suite_sha256: '5'.repeat(64), protocol_sha256: binding.protocol_sha256,
+    baseline_output_sha256: '6'.repeat(64), candidate_output_sha256: '7'.repeat(64),
+    evaluator_identity: 'synthetic-fixture-evaluator', proposer_identity: 'synthetic-fixture-proposer',
+    total: 2, baseline_correct: 0, candidate_correct: 1, baseline_truncated: 1, candidate_truncated: 0,
+  });
+  const plan = await json('plan.json', { schema: 'ruvllm-experiment-plan/v1', evidenceMode: 'fixture', source, policy: policy.path, candidates: [{ id: 'fixture-improvement', patch: patch.path, evaluation: evaluation.path }, { id: 'unevaluated-control', patch: patch.path }] });
+  const configPath = join(directory, 'runtime.json');
+  await writeFile(configPath, JSON.stringify({ schema: 'ruvllm-experiment-runtime/v1', binaryPath, binarySha256: binding.runtime_sha256, readRoots: [inputs], writeRoot: outputs, policySha256s: [policy.sha256], maxCandidates: 16, timeoutMs: 30000 }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  return { configPath, planPath: plan.path };
+}