@ruvector/ruvllm 3.0.0 → 4.0.1

package/README.md

@@ -1,388 +1,187 @@
-# @ruvector/ruvllm
+# MetaHarness weight experiments
 
-[![npm version](https://img.shields.io/npm/v/@ruvector/ruvllm.svg)](https://www.npmjs.com/package/@ruvector/ruvllm)
-[![Downloads](https://img.shields.io/npm/dm/@ruvector/ruvllm)](https://www.npmjs.com/package/@ruvector/ruvllm)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![GitHub Stars](https://img.shields.io/github/stars/ruvnet/ruvector?style=social)](https://github.com/ruvnet/ruvector)
+<p align="center"><img src="https://raw.githubusercontent.com/ruvnet/ruvllm/ruvllm-npm-v4.0.1/docs/assets/gpu-job-loop.svg" alt="The GPU job loop checks a spending ceiling, rents the offer and arms a destroy timer, runs the pinned job, pulls raw outputs, checks them locally, then destroys the rental and confirms it is gone." width="100%"></p>
 
-**Self-learning LLM runtime for Node.js** — GGUF inference, TurboQuant KV-cache compression (6-8x memory savings), SONA adaptive learning, FlashAttention, speculative decoding, and SIMD-optimized kernels. Built in Rust, runs everywhere.
+<p align="center"><img src="https://raw.githubusercontent.com/ruvnet/ruvllm/ruvllm-npm-v4.0.1/docs/assets/heldout-results.svg" alt="Held-out results on 256 untouched tasks: tool passes 149, 176 and 192 of 192 for base, coding-4b and coding-4b-r2; arithmetic 62, 64 and 46 of 64. coding-4b is kept; coding-4b-r2 is rejected." width="100%"></p>
 
-> Inference at **88-135 tok/s** on M4 Pro | **<1ms** SONA adaptation | **6-8x** KV-cache compression via TurboQuant
+Published on npm as `@ruvector/ruvllm`. Version 4.0.0 replaces the 3.x
+inference runtime from `ruvnet/ruvector` with this package, because ruvllm now
+lives in `ruvnet/ruvllm`. The 3.x API and its CLI subcommands are not part of
+4.x; pin `@ruvector/ruvllm@3` to keep using them. The npm package ships the
+JavaScript controller, GPU loop and Vast.ai host adapter. It does not ship the
+native `weight_evolution` binary, model weights or adapters. Build the binary
+from this repository and pass its path with `--binary`.
 
-## Installation
-
-```bash
+```sh
 npm install @ruvector/ruvllm
+npx ruvllm --help            # bounded weight-edit experiments
+npx ruvllm-gpu-loop status --config /abs/private/gpu-loop.json
 ```
 
-## Quick Start
-
-```typescript
-import { RuvLLM, RuvLLMConfig } from '@ruvector/ruvllm';
-
-// Initialize with default configuration
-const llm = new RuvLLM();
-
-// Or with custom configuration
-const llm = new RuvLLM({ embeddingDim: 384, learningEnabled: true });
-
-// Routing, memory and embeddings (no model needed)
-const decision = llm.route('Explain quantum computing');
-llm.addMemory('RuvLLM routes queries with FastGRNN', { source: 'docs' });
-const hits = llm.searchMemory('how are queries routed?', 3);
-const vec = llm.embed('Explain quantum computing');
-```
-
-## Text Generation (GGUF)
-
-Text comes only from a model you load. `loadModel()` runs a local GGUF file
-on the native candle backend (CPU; Metal on macOS builds with the `metal`
-feature):
-
-```typescript
-const llm = new RuvLLM();
-llm.loadModel('./qwen2.5-0.5b-instruct-q4_k_m.gguf', { maxContext: 4096 });
-
-const out = llm.chat([{ role: 'user', content: 'What is the capital of France?' }], {
-  maxTokens: 64,
-  temperature: 0,
-});
-// { text: 'The capital of France is Paris.', promptTokens: 15,
-//   completionTokens: 8, finishReason: 'stop' }
-```
-
-- **Architectures**: GGUF `llama`, `mistral`, `qwen2` (Qwen2.5) and `qwen3`.
-  Any other architecture (phi, gemma, qwen3.5, ...) fails to load with an error
-  naming it.
-- **Tokenizer**: a `tokenizer.json` next to the GGUF, else the tokenizer
-  embedded in the GGUF. The embedded one works for byte-level BPE (`gpt2`)
-  vocabularies such as Qwen and Llama 3; GGUFs with a SentencePiece vocabulary
-  (Llama 2, Mistral, TinyLlama) need the `tokenizer.json`, otherwise loading
-  fails with `RUVLLM_TOKENIZER_MISSING`.
-- **`chat()`** applies the model's chat template, read from the GGUF's
-  embedded `tokenizer.chat_template` (ChatML for Qwen). A `qwen2`/`qwen3` GGUF
-  whose template is not ChatML (e.g. DeepSeek-R1-Distill-Qwen) fails to load
-  with `RUVLLM_MODEL_LOAD_FAILED` rather than run under the wrong format.
-- **`generate()`** continues the prompt verbatim; **`query()`** routes, then
-  answers as a single chat message.
-- **Usage**: `promptTokens`/`completionTokens` are counted with the model's
-  tokenizer; `finishReason` is `stop` (end-of-sequence token or a stop
-  sequence) or `length` (`maxTokens` reached or the context is full).
-- **Blocking**: loading and generation are synchronous and block the event
-  loop; run them in a worker thread if that matters.
-
-Without a loaded model, `generate()`, `query()`, `chat()` and
-`generateDetailed()` throw `RUVLLM_NO_LANGUAGE_MODEL`; they never return text
-that is not model output. For demos and tests, `new RuvLLM({ allowPlaceholder:
-true })` (or `RUVLLM_ALLOW_MOCK=1`) makes `generate()`/`query()` return the
-labelled `PLACEHOLDER_TEXT` instead, with a one-time warning.
-
-### Native binary requirements
-
-Model loading needs a native binary built with the `candle` feature;
-`supportsModelLoading()` reports whether the installed one was.
-
-| Native binary | `loadModel()` |
-|---------------|---------------|
-| Built from this source (`npm run build:native`) | Works |
-| `@ruvector/ruvllm-<platform>` 3.x (built by the release workflow with `candle`) | Works |
-| `@ruvector/ruvllm-<platform>` 2.0.x | Throws `RUVLLM_NATIVE_TOO_OLD`: they predate model loading |
-| Built with `--features napi` only (no `candle`) | Throws `RUVLLM_NO_INFERENCE_BACKEND` |
-| None for your platform | Throws `RUVLLM_NATIVE_UNAVAILABLE` |
-
-To use a binary you built, point `RUVLLM_NATIVE_PATH` at it (it takes
-precedence over the installed platform package):
-
-```bash
-npm run build:native   # writes ruvllm.<platform>.node (needs a Rust toolchain)
-RUVLLM_NATIVE_PATH=$PWD/ruvllm.linux-x64-gnu.node node app.js
-```
-
-Until the 3.x platform packages are on npm, build the binary from source as
-above, or use the ruvllm CLI (`ruvllm serve <model>`, an OpenAI-compatible
-server that exits if the model fails to load).
-
-| Error code | Meaning |
-|------------|---------|
-| `RUVLLM_NO_LANGUAGE_MODEL` | Generation was requested with no model loaded |
-| `RUVLLM_NATIVE_UNAVAILABLE` | No native binary could be loaded |
-| `RUVLLM_NATIVE_TOO_OLD` | The native binary predates model loading (2.0.x platform packages) |
-| `RUVLLM_NO_INFERENCE_BACKEND` | The native binary was built without the `candle` backend |
-| `RUVLLM_MODEL_NOT_FOUND` | The model path does not exist |
-| `RUVLLM_MODEL_LOAD_FAILED` | The file could not be loaded (unsupported architecture, not GGUF, ...) |
-| `RUVLLM_TOKENIZER_MISSING` | Weights loaded but no usable tokenizer was found |
-
-## What's New in v2.5
-
-| Feature | Description |
-|---------|-------------|
-| **TurboQuant KV-Cache** | 2-4 bit asymmetric quantization with per-channel scale/zero-point — 6-8x memory reduction, <0.5% perplexity loss |
-| **TurboQuant Embedding Store** | Quantized vector storage with compressed search — 10-30x memory savings |
-| **H2O / PyramidKV Eviction** | Intelligent cache eviction policies for long-context inference |
-| **Optimized Inner Product** | Asymmetric distance on quantized data — skip decompression for 2-4x faster search |
-| **RuvLTRA Models** | Purpose-built 0.5B & 3B models for Claude Flow |
-| **Task-Specific LoRA** | 5 pre-trained adapters (coder, researcher, security, architect, reviewer) |
-| **HuggingFace Hub** | Download/upload models directly |
-| **Adapter Merging** | TIES, DARE, SLERP strategies |
-| **HNSW Routing** | 150x faster semantic matching |
-| **Evaluation Harness** | SWE-Bench testing with 5 ablation modes |
-| **mistral-rs Backend** | Production serving with PagedAttention, X-LoRA, ISQ |
-
-## TurboQuant — KV-Cache Compression
-
-Reduce inference memory by 6-8x with <0.5% quality loss:
-
-```typescript
-import { simd } from '@ruvector/ruvllm/simd';
-
-// TurboQuant compresses KV-cache entries at 2-4 bit precision
-// with per-channel asymmetric quantization (scale + zero-point).
-// Eviction policies (H2O, Sliding Window, PyramidKV) keep the
-// most important tokens in cache during long-context generation.
-
-// Supported bit widths: 2-bit (32x), 3-bit (10.7x), 4-bit (8x), 8-bit (4x)
-```
-
-| Bits | Compression | Perplexity Loss | Use Case |
-|------|-------------|-----------------|----------|
-| 2-bit | 32x | ~2% | Maximum compression, edge devices |
-| 3-bit | 10.7x | <1% | Balanced — recommended for most uses |
-| 4-bit | 8x | <0.5% | High quality, long-context inference |
-| 8-bit | 4x | ~0% | Baseline quantization |
-
-## CLI Usage
-
-```bash
-# Query a model (this package's `ruvllm` bin; needs --model, see above)
-ruvllm query "What is machine learning?" --model ./qwen2.5-0.5b-instruct-q4_k_m.gguf
-
-# The commands below are the Rust ruvllm CLI (crate ruvllm-cli)
-# Stream output
-ruvllm query --stream "Write a poem"
-
-# Download a model
-ruvllm download ruvector/ruvltra-small-q4km
-
-# Benchmark
-ruvllm bench ./models/model.gguf
-
-# Run evaluation (SWE-Bench)
-ruvllm eval --model ./models/model.gguf --subset lite --max-tasks 50
-```
-
-## API Reference
-
-### RuvLLM Class
-
-```typescript
-class RuvLLM {
-  constructor(config?: RuvLLMConfig);
-
-  // Language model (see "Text Generation" above)
-  loadModel(path: string, options?: LoadModelOptions): LoadedModelInfo;
-  unloadModel(): void;
-  isModelLoaded(): boolean;
-  modelInfo(): LoadedModelInfo | null;
-  supportsModelLoading(): boolean; // native binary can load models
-
-  // Generation; all throw RUVLLM_NO_LANGUAGE_MODEL without a loaded model
-  chat(messages: ChatMessage[], config?: GenerationConfig): GenerationResult;
-  generateDetailed(prompt: string, config?: GenerationConfig): GenerationResult;
-  generate(prompt: string, config?: GenerationConfig): string;
-  query(text: string, config?: GenerationConfig): QueryResponse; // routed, + token usage
-
-  // Routing, memory and embeddings
-  route(text: string): RoutingDecision;
-  addMemory(content: string, metadata?: Record<string, unknown>): MemoryId;
-  searchMemory(text: string, k?: number): MemoryResult[];
-  embed(text: string): Embedding;
-
-  // Not in this package: token streaming (StreamingGenerator chunks a
-  // finished generate() result), mistral-rs backends.
-
-  // Get SONA learning stats
-  sonaStats(): SonaStats | null;
-
-  // Adapt on feedback
-  adapt(input: Float32Array, quality: number): void;
-}
+Run multiple bounded RuVLLM edits against one unchanged checkpoint, validate
+supplied evaluations, package RVF evidence, restore every patched checkpoint,
+and rank research-qualified candidates through MetaHarness. This controller
+uses the actual Flywheel, Darwin and Weight-EFT packages pinned in
+[package-lock.json](package-lock.json).
+
+The runner does not perform inference, discover an effective weight edit, train
+an adapter or activate a model. CPU fixtures exercise real file editing and
+restoration with explicitly synthetic evaluation receipts. External evaluation
+files remain caller-supplied evidence; hashes do not authenticate their origin.
+
+## Install and run the CPU fixture
+
+Requirements: Linux or macOS, Node 22+, Python 3.12+, a C linker, and Rust 1.97.1
+as pinned by `native/rust-toolchain.toml`. Activate any locally installed Rust
+toolchain before using Cargo. From the repository root:
+
+```sh
+(cd integrations/metaharness && npm ci --ignore-scripts)
+(cd native && cargo build --locked --release --bin weight_evolution)
+python3 native/verify_source.py
+node integrations/metaharness/src/cli.mjs fixture \
+  --dir "$PWD/runtime/metaharness-fixture" \
+  --binary "$PWD/native/target/release/weight_evolution"
 ```
 
-### Configuration
-
-```typescript
-interface RuvLLMConfig {
-  modelPath?: string;              // GGUF to load in the constructor (throws if it cannot be loaded)
-  modelOptions?: LoadModelOptions; // { maxContext?: number } for modelPath
-  allowPlaceholder?: boolean;      // generate()/query() return PLACEHOLDER_TEXT instead of
-                                   // throwing when no model is loaded (default: false)
-  strict?: boolean;                // Throw instead of warning for unsupported options (`backend`)
-  // ...plus routing/memory options (embeddingDim, hnswM, ...), see types.ts
-}
+Create the fixture's parent directory first (`mkdir -p runtime`). Its own directory
+must not exist: exclusive creation prevents accidental replacement. For another
+fixture use a new directory. The report should select `fixture-improvement`, leave
+`unevaluated-control` unqualified, verify RVF and exact rollback for both, and
+report `inferencePerformed: false`, `independentConfirmation: false` and
+`productionActivation: false`. A selected synthetic candidate says nothing about
+actual model accuracy.
+
+## Configure real experiment inputs
+
+Prepare reviewed source checkpoint, patch, policy and optional evaluation JSON
+under explicit input roots. Native request/data contracts are described in the
+[native guide](../../native/README.md). Patch generation remains model specific;
+the controller does not guess useful tensor edits.
+
+Run the project-local installer with paths you control:
+
+```sh
+bash scripts/install-metaharness.sh \
+  --config-dir /absolute/private/operator-profile \
+  --read-root /absolute/checkpoints \
+  --read-root /absolute/experiment-inputs \
+  --policy /absolute/experiment-inputs/policy.json \
+  --output-root /absolute/private/experiment-outputs
 ```
 
-### Generation Config and Result
-
-```typescript
-interface GenerationConfig {
-  maxTokens?: number;          // default 256
-  temperature?: number;        // default 0.7; 0 = greedy
-  topP?: number;               // default 0.9, in (0, 1]
-  topK?: number;               // default 50; 0 disables
-  repetitionPenalty?: number;  // default 1.1
-  stopSequences?: string[];    // stop text is not included in the output
-  seed?: number;               // reproducible sampling at temperature > 0
-}
-
-interface GenerationResult {
-  text: string;
-  promptTokens: number;        // after the chat template, for chat()
-  completionTokens: number;    // includes an end-of-sequence token that ended generation
-  finishReason: 'stop' | 'length' | 'cancelled';
+It installs frozen npm dependencies without lifecycle scripts, builds the native
+binary, verifies native provenance and runs its smoke fixture. It creates a
+private runtime profile and Claude launcher without changing global settings.
+Repeat `--read-root`/`--policy` for additional approved inputs. Existing profile
+files are never replaced; use another directory for a new profile. Existing config
+and output directories must be owner-only. `--configure-only` skips installation
+and building but still checks native readiness.
+
+Example plan inside an approved read root:
+
+```json
+{
+  "schema": "ruvllm-experiment-plan/v1",
+  "evidenceMode": "external",
+  "source": "/absolute/checkpoints/source.safetensors",
+  "policy": "/absolute/experiment-inputs/policy.json",
+  "candidates": [
+    {
+      "id": "candidate-01",
+      "patch": "/absolute/experiment-inputs/patch.json",
+      "evaluation": "/absolute/experiment-inputs/evaluation.json"
+    }
+  ]
 }
 ```
 
-## SIMD Module
-
-For direct access to optimized SIMD kernels:
-
-```typescript
-import { simd } from '@ruvector/ruvllm/simd';
-
-// Dot product
-const result = simd.dotProduct(vecA, vecB);
-
-// Matrix multiplication
-const output = simd.matmul(matrix, vector);
-
-// Flash Attention
-const attended = simd.flashAttention(query, key, value, scale);
-
-// RMS Normalization
-simd.rmsNorm(hidden, weights, epsilon);
+```sh
+node integrations/metaharness/src/cli.mjs run \
+  --config /absolute/private/operator-profile/runtime.json \
+  --plan /absolute/experiment-inputs/plan.json
 ```
 
-## Performance (M4 Pro)
-
-| Operation | Performance |
-|-----------|-------------|
-| Inference | 88-135 tok/s |
-| Flash Attention | 320µs (seq=2048) |
-| HNSW Search | 17-62µs |
-| SONA Adapt | <1ms |
-| Evaluation | 5 ablation modes |
+Omit `evaluation` to run mechanical checks without qualification. After an external
+inference runner has evaluated a candidate, submit its hash-bound evaluation in a
+new plan/run. Candidate checkpoint hashes are deterministic for the same patch;
+new artifact paths do not relax identity checks. Paired baseline, protocol, suite,
+runtime, precision and output-budget consistency remain the evaluator's responsibility.
 
-## Evaluation Harness
+Runs use new private `run-*` directories and preserve rejected candidates. Reports
+bind config/plan/source/policy/binary/gate/patch/evaluation identities and record
+rollback and RVF verification. Native rejection records a reason. Structural or
+restoration failures abort; interrupted runs can leave artifacts. Reconcile those
+directories before retrying; never erase failed evidence to manufacture success.
 
-> **Not in this npm package**: `EvaluationHarness` and `AblationMode` are
-> not exported by `@ruvector/ruvllm`. The sketch below shows the intended API.
+## Claude Code and Ruflo
 
-Run model evaluations with SWE-Bench integration:
+Load [ruflo-metaharness](../../plugins/ruflo-metaharness/README.md) using the
+generated `launch-claude.sh`, or set `RUVLLM_EXPERIMENT_CONFIG` and use Claude's
+`--plugin-dir`. The `/ruflo-metaharness:weight-experiment` command and reviewer
+agent guide the bounded workflow. Its single MCP tool accepts a plan path; the
+model cannot override the operator configuration. The same stdio server can be
+registered in a Ruflo project's MCP configuration. Portable wire tests exercise
+the real engine; installed Claude/Ruflo client acceptance is separate.
 
-```typescript
-import { RuvLLM, EvaluationHarness, AblationMode } from '@ruvector/ruvllm';
+## Scheduled GPU work
 
-const harness = new EvaluationHarness({
-  modelPath: './models/model.gguf',
-  enableHnsw: true,
-  enableSona: true,
-});
+For scheduled GPU work, use the [durable GPU loop](GPU-LOOP.md). It supports
+host-owned ruOS secret references, Vast job descriptors, persisted reservations,
+deadline-aware polling and confirmed cleanup. Local contract tests require no
+live provider. The bundled file handoff keeps requests pending for a trusted host.
 
-// Run single evaluation
-const result = await harness.evaluate(
-  'Fix the null pointer exception',
-  'def process(data): return data.split()',
-  AblationMode.Full
-);
+## Weight-EFT data and plans
 
-console.log(`Success: ${result.success}, Quality: ${result.qualityScore}`);
+The data-only adapter CLI reads JSON stdin, with a 16 MiB bound:
 
-// Run ablation study (Baseline, RetrievalOnly, AdaptersOnly, R+A, Full)
-const report = await harness.runAblationStudy(tasks);
-for (const [mode, metrics] of Object.entries(report.modeMetrics)) {
-  console.log(`${mode}: ${metrics.successRate * 100}% success`);
-}
+```sh
+node integrations/metaharness/src/adapters-cli.mjs export < reviewed-archive-input.json > export.json
+node integrations/metaharness/src/adapters-cli.mjs training-plan < training-input.json > plan.json
+node integrations/metaharness/src/adapters-cli.mjs select < measured-candidates.json > selection.json
 ```
 
-## mistral-rs Backend (Production Serving)
-
-For production deployments with 10-100+ concurrent users, use the mistral-rs backend:
-
-```typescript
-import { RuvLLM, MistralBackend, PagedAttentionConfig } from '@ruvector/ruvllm';
-
-// Configure for production serving
-const backend = new MistralBackend({
-  // PagedAttention: 5-10x more concurrent users
-  pagedAttention: {
-    blockSize: 16,
-    maxBlocks: 4096,
-    gpuMemoryFraction: 0.9,
-    prefixCaching: true,
-  },
-  // X-LoRA: Per-token adapter routing
-  xlora: {
-    adapters: ['./adapters/coder', './adapters/researcher'],
-    topK: 2,
-  },
-  // ISQ: Runtime quantization
-  isq: {
-    bits: 4,
-    method: 'awq',
-  },
-});
-
-const llm = new RuvLLM({ backend });
-await llm.loadModel('mistralai/Mistral-7B-Instruct-v0.2');
-
-// Serve multiple concurrent requests
-const response = await llm.query('Write production code');
+`export` takes `{archive, evalHoldout, maxTokens?}`. Archive entries follow the
+pinned Weight-EFT `DarwinTrajectory` contract (`instance_id`, `model`, `tier`,
+boolean `resolved`, `messages`, `model_patch`). All actual evaluation instance IDs
+must be in `evalHoldout`. Output contains standard `sft`/`dpo` arrays, drop reports
+and input hashes. Reward-hacking filtering stays enabled, overlength traces are
+dropped, and tool calls are preserved. These filters cannot authenticate outcomes
+or detect all semantic contamination.
+
+`training-plan` takes `{base:{id,paramsB},sftPath,dpoPath,adapterPrefix}`. It emits
+upstream plans plus `executionStatus: not_executed` and
+`runnerCompatibility: adapter-required`. This repository has no upstream
+`ruvllm microlora` executable. Its existing fixed CUDA/PEFT experiment runner is
+not a configurable SFT/DPO trainer. No GPU, model download or paid job is started.
+
+`select` takes `{baseline,candidates,envelope}` with entries
+`{id,score,evidenceSha256}`. It replays finite, supplied scores through Darwin's
+contrastive engine. It is development ranking with an immutable envelope and no
+independent confirmation; it cannot authenticate caller-supplied evidence. The
+native runner applies its stricter qualification first.
+
+## Tests and benchmark
+
+```sh
+(cd integrations/metaharness && npm test)
+node --test plugins/ruflo-metaharness/test/*.test.mjs
+node integrations/metaharness/bench/run.mjs --iterations 7 --warmup 2 --candidates 2
 ```
 
-> **Not in this npm package**: `MistralBackend` is not exported, the
-> `backend` option is ignored (with a `RUVLLM_UNSUPPORTED_OPTION` warning), and
-> `loadModel()` takes a local GGUF path, not a Hub id. mistral-rs serving is a
-> feature of the Rust crate (`mistral-rs` feature).
-
-## Supported Models
-
-GGUF files loadable with `loadModel()` (architectures llama, mistral, qwen2, qwen3):
-
-- **RuvLTRA-Small** (494M) - Q4K, Q5K, Q8
-- **RuvLTRA-Medium** (3B) - Q4K, Q5K, Q8
-- **Qwen 2.5 / Qwen 3** (0.5B-72B)
-- **Llama 3.x** (8B-70B)
-- **Mistral** (7B-22B)
-
-Phi-3, Gemma-2 and Qwen3.5 GGUFs are not supported: loading fails with an
-error naming the architecture.
-
-## Platform Support
-
-The table covers routing, memory and embeddings. Model loading additionally
-needs a native binary built with the `candle` feature (see "Native binary
-requirements").
-
-| Platform | Architecture | Status |
-|----------|--------------|--------|
-| macOS | arm64 (M1-M4) | ✅ Full support |
-| macOS | x64 | ✅ Supported |
-| Linux | x64 | ✅ Supported |
-| Linux | arm64 | ✅ Supported |
-| Windows | x64 | ✅ Supported |
-
-## Related Packages
-
-- [@ruvector/core](https://www.npmjs.com/package/@ruvector/core) - Vector operations
-- [@ruvector/sona](https://www.npmjs.com/package/@ruvector/sona) - SONA learning engine
-- [@ruvector/ruvector](https://www.npmjs.com/package/@ruvector/ruvector) - Full Ruvector SDK
-
-## Links
-
-- [GitHub Repository](https://github.com/ruvnet/ruvector)
-- [API Documentation](https://docs.rs/ruvllm)
-- [Crate (Rust)](https://crates.io/crates/ruvllm)
-
-## License
-
-MIT OR Apache-2.0
+Tests require the built native binary. In restricted agent environments the Node
+test runner, native child processes and package fetching may require the host's
+supported execution permission. Verify actual subtest counts; a file-only runner
+summary is insufficient evidence. Do not disable TLS/checksums or native checks.
+
+The benchmark compares fresh versus reused Node processes on identical CPU
+fixtures, retaining raw latency samples and implementation/binary/lock hashes.
+The reused process matches the MCP server architecture. All native hashing,
+patch validation and byte restoration remain enabled. See the
+[benchmark report](../../docs/benchmarks/metaharness-cpu.md) for measured scope
+and limits; no model-performance claim follows from orchestration speed.
+
+Architecture and threat boundaries are recorded in
+[ADR 012](../../docs/adr/ADR-012-metaharness-bounded-experiment-runner.md),
+[ADR 013](../../docs/adr/ADR-013-training-and-development-selection.md) and
+[ADR 014](../../docs/adr/ADR-014-claude-ruflo-integration.md).

package/examples/gpu-loop.example.json

@@ -0,0 +1,26 @@
+{
+  "schema": "ruvllm-gpu-loop/v1",
+  "stateRoot": "/absolute/private/gpu-loop-state",
+  "intervalSeconds": 60,
+  "maxAttempts": 2,
+  "budgetUsd": 0,
+  "jobs": [
+    {
+      "id": "qwen35-4b-paired-evaluation",
+      "provider": "vast.ai",
+      "model": {
+        "repo": "Qwen/Qwen3.5-4B",
+        "revision": "851bf6e806efd8d0a36b00ddf55e13ccb7b8cd0a"
+      },
+      "task": "evaluate",
+      "secretRef": "ruos.vast.primary",
+      "resource": { "instanceId": "REPLACE_WITH_EXISTING_INSTANCE_ID" },
+      "maxCostUsd": 1,
+      "timeoutSeconds": 1800,
+      "experiment": {
+        "configPath": "/absolute/private/operator-profile/runtime.json",
+        "planPath": "/absolute/experiment-inputs/plan.json"
+      }
+    }
+  ]
+}