diff --git a/.github/workflows/ruvector-npm-ci.yml b/.github/workflows/ruvector-npm-ci.yml index 874184d81a..8961d03b12 100644 --- a/.github/workflows/ruvector-npm-ci.yml +++ b/.github/workflows/ruvector-npm-ci.yml @@ -140,22 +140,19 @@ jobs: run: node --test tests/*.test.mjs - name: weight-space absent — CLI/MCP install hint, require('ruvector') still loads - # @ruvector/weight-space is an optional peer and is not installed above; - # the test also hides it with a resolve shim, so it holds either way. + # @ruvector/weight-space is a hard dependency, so it is installed above; the + # test hides it with a resolve shim to prove a pruned install still degrades + # to the install hint instead of crashing. run: node test/weight-space-optional.js - name: weight-space present — ruvector weights CLI + weights_* MCP (real import) - # @ruvector/weight-space is not on npm yet: build and pack the sibling - # package, then install the tarball without saving it to package.json. - # --save-dev only picks the edge type: the package is a declared peer, and - # --legacy-peer-deps skips peer edges, so a plain --no-save install is a - # silent no-op ("up to date"). --no-save still leaves package.json alone. + # A plain install resolves the published dependency; fail loudly if it does + # not, rather than letting the CLI test skip. run: | set -e - (cd ../weight-space && npm install --no-workspaces --no-audit --no-fund && npm run build && npm pack --pack-destination "$RUNNER_TEMP") - npm install --no-save --save-dev --no-workspaces --no-audit --no-fund --legacy-peer-deps "$RUNNER_TEMP"/ruvector-weight-space-0.1.0.tgz node -e "require('@ruvector/weight-space')" node test/weight-space-cli.js + node test/weight-space-edit.js # ────────────────────────────────────────────────────────────────────────── # 3. FUNCTIONAL SMOKE — npx-style CLI works end-to-end diff --git a/docs/adr/ADR-358-weight-space-ruv-fann-registry.md b/docs/adr/ADR-358-weight-space-ruv-fann-registry.md index 18656d8089..56d5c6f00c 100644 --- a/docs/adr/ADR-358-weight-space-ruv-fann-registry.md +++ b/docs/adr/ADR-358-weight-space-ruv-fann-registry.md @@ -96,6 +96,40 @@ from the mirrored constants. loaded, path-confined to the working directory (the MCP rule from #1306/#1307), and print `npm i @ruvector/weight-space@0.1.0` when the package is absent. +### Amendment 2026-11-13: hard dependency (supersedes the optional peer above) + +The owner asked for `@ruvector/weight-space` to be a primary dependency of +`ruvector`, as `@ruvector/e-means` already is (#1489). The optional peer, and the +rule that a default install does not fetch it, are superseded. + +- It is an exact-pinned `dependencies` entry (`0.1.0`) and is removed from + `peerDependencies` and `peerDependenciesMeta`. +- Cost, measured on the registry: 175 KB unpacked for the package, plus `ruv-fann` + (19 KB) and its `ruv-fann-wasm` runtime. Nothing is loaded at start-up: the + `weights` commands and `weights_*` tools still `require` it inside the operation, + so `ruvector --help` and MCP start-up are unchanged (`test/startup-budget.js`). +- The "package absent" path stays, as a degradation path rather than the normal + case. A pruned install or a package manager that does not expose it still gets + `ERR_WEIGHT_SPACE_MISSING` and the install hint, not a crash. +- **Side effect on `neural-q`.** `ruv-fann` stays an optional peer of `ruvector`, but + it is now also a transitive dependency through `@ruvector/weight-space`. On a + default npm install it therefore resolves, and `neural-q` uses its MLP backend + instead of falling back to tabular `q-learning`. That is what the algorithm name + promises, and it only affects users who select `neural-q`. A strict layout such as + pnpm may not expose the transitive package to `ruvector`; those users install + `ruv-fann@0.1.0` directly, as before. +- `test/weight-space-cli.js` now fails, rather than skips, when the package does not + resolve, because a skip would hide a broken install. +- **Edit and fine-tune surface.** `ruvector weights set-layer|perturb|learn` and the MCP + tools `weights_set_layer|weights_perturb|weights_learn` expose the registry's + versioned edit and `learnFromOutcomes` operations (`bin/weights-edit.js`). Each writes a + child snapshot and never changes its parent. Inputs are bounded (epochs, rows, vector + and patch sizes, seeds), file inputs use the same working-directory confinement as + `save`, and a fine-tune that does not clear its held-out check writes nothing and + returns `accepted: false` rather than an error. These tools write to the registry, so + operators who expose the MCP server read-only should deny them with + `RUVECTOR_MCP_DENY` (ADR-256). + ## Evaluation The numbers below were measured on ruvultra (Linux x64, Node 22, ruv-fann diff --git a/npm/packages/ruvector/README.md b/npm/packages/ruvector/README.md index e31fd23db3..5a0fc94a3c 100644 --- a/npm/packages/ruvector/README.md +++ b/npm/packages/ruvector/README.md @@ -138,23 +138,29 @@ The engine adds 458 KB unpacked to an install. `npx ruvector --help` cold start ## Weight registry (`@ruvector/weight-space`) -`ruvector weights` stores [`ruv-fann`](https://www.npmjs.com/package/ruv-fann) model snapshots (`ruv-fann.dense-layers/1` JSON) in a versioned registry keyed by a task embedding, so you can find the snapshot saved for the most similar past task. It runs on the optional peer `@ruvector/weight-space`, which `ruvector` does not install. Without it, the command prints `npm i @ruvector/weight-space@0.1.0` and exits non-zero. +`ruvector weights` stores [`ruv-fann`](https://www.npmjs.com/package/ruv-fann) model snapshots (`ruv-fann.dense-layers/1` JSON) in a versioned registry keyed by a task embedding, so you can find the snapshot saved for the most similar past task. It runs on `@ruvector/weight-space`, a dependency of `ruvector` that installs with it and is loaded only when a `weights` command runs, so it adds nothing to `ruvector --help` start-up. If an install is incomplete (for example a pruned `node_modules`), the command prints `npm i @ruvector/weight-space@0.1.0` and exits non-zero. ```bash -npm i @ruvector/weight-space@0.1.0 npx ruvector weights save --model model.json --embedding 1,0,0 --task classify --tags v1 npx ruvector weights save --model model.json --text "classify support tickets" # ONNX embedding npx ruvector weights nearest --embedding 0.9,0.1,0 -k 5 npx ruvector weights lineage npx ruvector weights diff --json npx ruvector weights get + +# Edit and fine-tune: each writes a CHILD snapshot of ; the parent never changes +npx ruvector weights set-layer 0 --patch patch.json # {"bias":[...]} / weights / activation / steepness; shape cannot change +npx ruvector weights perturb --scale 0.05 --seed 7 # seeded Gaussian noise (same seed, same model); --layers 0,1 --no-bias --relative +npx ruvector weights learn --trajectories rows.json --epochs 300 --learning-rate 0.2 ``` -The registry is an append-only JSON-lines log, `.ruvector/weights.jsonl` by default (`--registry `), with a `.index.db` vector index beside it. All snapshots in one registry share one embedding dimension, so do not mix `--text` (384-d) and hand-written `--embedding` vectors in the same registry. Registry and model paths must be inside the working directory. MCP clients get `weights_save`, `weights_nearest`, `weights_diff` and `weights_lineage`, which take an explicit `embedding` array and apply the same path rule (plus `RUVECTOR_MCP_ROOTS`). +`learn` trains on rows of `{input, output, score, correction?}`: a row at or above `--success-threshold` (default 0.5) trains toward its `output`, and a failure trains toward its `correction` (failures without one are skipped). A child snapshot is written **only if** a held-out check improves by at least `--min-improvement` (default 1%); otherwise nothing is written and the result says why, with exit code 0. Epochs are capped at 10,000 and trajectories at 10,000 rows. + +The registry is an append-only JSON-lines log, `.ruvector/weights.jsonl` by default (`--registry `), with a `.index.db` vector index beside it. All snapshots in one registry share one embedding dimension, so do not mix `--text` (384-d) and hand-written `--embedding` vectors in the same registry. Registry and model paths must be inside the working directory. MCP clients get `weights_save`, `weights_nearest`, `weights_diff` and `weights_lineage`, which take an explicit `embedding` array, plus the writing tools `weights_set_layer`, `weights_perturb` and `weights_learn` (inline `patch` / `trajectories`, or a `patch_path` / `trajectories_path` file). All apply the same path rule (plus `RUVECTOR_MCP_ROOTS`). To expose only the read tools, use `RUVECTOR_MCP_DENY=weights_save,weights_set_layer,weights_perturb,weights_learn`. ## Recipe: route unseen states with `neural-q` (`ruv-fann`) -The tabular learning algorithms score a state they have never seen as all zeros. `neural-q` fits a small MLP Q-function over hashed state features, so `refactor:.rs` is routed from what was learned on `fix:.rs` and `edit:.rs`. It runs on the optional peer [`ruv-fann`](https://www.npmjs.com/package/ruv-fann). Without it, `neural-q` behaves exactly like `q-learning`, and `ruvector` does not install it by default. +The tabular learning algorithms score a state they have never seen as all zeros. `neural-q` fits a small MLP Q-function over hashed state features, so `refactor:.rs` is routed from what was learned on `fix:.rs` and `edit:.rs`. It runs on [`ruv-fann`](https://www.npmjs.com/package/ruv-fann), an optional peer of `ruvector`. `ruv-fann` is also a dependency of `@ruvector/weight-space`, which `ruvector` now installs, so a default npm install resolves it and `neural-q` uses the MLP. A package manager that does not expose transitive dependencies to `ruvector` (pnpm's strict layout, for example) may not; install `ruv-fann@0.1.0` yourself there. Where `ruv-fann` does not resolve, `neural-q` behaves exactly like `q-learning`. ```bash npm i ruvector ruv-fann@0.1.0 diff --git a/npm/packages/ruvector/bin/mcp-server.js b/npm/packages/ruvector/bin/mcp-server.js index 3861b99d75..989d0db34a 100644 --- a/npm/packages/ruvector/bin/mcp-server.js +++ b/npm/packages/ruvector/bin/mcp-server.js @@ -1902,7 +1902,7 @@ const TOOLS = [ } }, // ── Weight registry Tools (optional @ruvector/weight-space) ────────────── - // weights_save, weights_nearest, weights_diff, weights_lineage + // weights_save, weights_nearest, weights_diff, weights_lineage, weights_set_layer, weights_perturb, weights_learn ...weightsTools.MCP_TOOLS, // ── RVF Vector Store Tools ──────────────────────────────────────────────── { @@ -4223,6 +4223,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => { case 'weights_nearest': case 'weights_diff': case 'weights_lineage': + case 'weights_set_layer': + case 'weights_perturb': + case 'weights_learn': return await weightsTools.runMcpTool(name, args, validateRvfPath); // ── RVF Tool Handlers ───────────────────────────────────────────────── diff --git a/npm/packages/ruvector/bin/weights-edit.js b/npm/packages/ruvector/bin/weights-edit.js new file mode 100644 index 0000000000..806a09fb39 --- /dev/null +++ b/npm/packages/ruvector/bin/weights-edit.js @@ -0,0 +1,328 @@ +'use strict'; +/** + * Edit and fine-tune operations for the weight registry: `weights set-layer`, + * `weights perturb`, `weights learn`, and the matching `weights_set_layer`, + * `weights_perturb`, `weights_learn` MCP tools. Each one writes a CHILD snapshot of an + * existing snapshot (the registry is append-only and snapshots are immutable), so the + * lineage records exactly what was changed. + * + * This file holds only argument validation and the call into @ruvector/weight-space; + * the shared registry plumbing (path confinement, open/close, summaries) is injected + * from weights.js so the two files do not import each other. + */ + +const fs = require('fs'); + +const MAX_JSON_FILE_BYTES = 16 * 1024 * 1024; +const MAX_TRAJECTORIES = 10000; +const MAX_VECTOR_LEN = 4096; +const MAX_PATCH_VALUES = 1000000; +const MAX_LAYER_INDEX = 63; +const MAX_LAYER_LIST = 64; +const MAX_EPOCHS = 10000; +const MAX_SEED = 4294967295; +const PATCH_KEYS = new Set(['weights', 'bias', 'activation', 'steepness']); + +/** A finite number within bounds, from a number or a CLI string. `dflt` when absent. */ +function num(value, name, { min, max, int = false, dflt } = {}) { + if (value === undefined || value === null || value === '') return dflt; + const n = typeof value === 'number' ? value : Number(String(value).trim()); + if (!Number.isFinite(n)) throw new Error(`${name} must be a finite number`); + if (int && !Number.isInteger(n)) throw new Error(`${name} must be an integer`); + if (min !== undefined && n < min) throw new Error(`${name} must be at least ${min}`); + if (max !== undefined && n > max) throw new Error(`${name} must be at most ${max}`); + return n; +} + +function flag(value, name) { + if (value === undefined || value === null) return undefined; + if (typeof value !== 'boolean') throw new Error(`${name} must be true or false`); + return value; +} + +/** A layer index from a number or string. */ +function layerIndex(value, name = 'layer') { + const n = num(value, name, { min: 0, max: MAX_LAYER_INDEX, int: true }); + if (n === undefined) throw new Error(`${name} is required`); + return n; +} + +/** `--layers 0,1` or `[0,1]`: a short list of layer indexes. */ +function layerList(value) { + if (value === undefined || value === null || value === '') return undefined; + const list = Array.isArray(value) ? value : String(value).split(',').map((s) => s.trim()).filter(Boolean); + if (list.length === 0 || list.length > MAX_LAYER_LIST) throw new Error(`layers must list 1 to ${MAX_LAYER_LIST} layer indexes`); + return list.map((v, i) => layerIndex(v, `layers[${i}]`)); +} + +function finiteVector(value, name) { + if (!Array.isArray(value) || value.length === 0 || value.length > MAX_VECTOR_LEN) { + throw new Error(`${name} must be an array of 1 to ${MAX_VECTOR_LEN} numbers`); + } + for (const v of value) if (typeof v !== 'number' || !Number.isFinite(v)) throw new Error(`${name} must contain only finite numbers`); + return value; +} + +function readJsonFile(filePath, label) { + const st = fs.statSync(filePath); + if (!st.isFile()) throw new Error(`${label} file '${filePath}' is not a regular file`); + if (st.size > MAX_JSON_FILE_BYTES) throw new Error(`${label} file is larger than ${MAX_JSON_FILE_BYTES} bytes`); + try { + return JSON.parse(fs.readFileSync(filePath, 'utf8')); + } catch (e) { + throw new Error(`${label} file '${filePath}' is not valid JSON: ${e.message}`); + } +} + +/** Exactly one of an inline value or a confined file path. */ +function inlineOrFile(inline, filePath, label, resolvePath) { + const hasInline = inline !== undefined && inline !== null; + const hasFile = filePath !== undefined && filePath !== null && filePath !== ''; + if (hasInline === hasFile) throw new Error(`pass exactly one of ${label} or a ${label} file`); + return hasInline ? inline : readJsonFile(resolvePath(filePath), label); +} + +function validatePatch(patch) { + if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('patch must be an object'); + const keys = Object.keys(patch); + if (keys.length === 0) throw new Error('patch must change at least one of weights, bias, activation, steepness'); + for (const k of keys) if (!PATCH_KEYS.has(k)) throw new Error(`patch has an unsupported field '${k}' (allowed: ${[...PATCH_KEYS].join(', ')})`); + const out = {}; + if (patch.weights !== undefined) { + if (!Array.isArray(patch.weights) || patch.weights.length > MAX_PATCH_VALUES) throw new Error(`patch.weights must be an array of at most ${MAX_PATCH_VALUES} numbers`); + for (const v of patch.weights) if (typeof v !== 'number' || !Number.isFinite(v)) throw new Error('patch.weights must contain only finite numbers'); + out.weights = patch.weights; + } + if (patch.bias !== undefined) { + if (patch.bias !== null) { + if (!Array.isArray(patch.bias) || patch.bias.length > MAX_VECTOR_LEN) throw new Error(`patch.bias must be null or an array of at most ${MAX_VECTOR_LEN} numbers`); + for (const v of patch.bias) if (typeof v !== 'number' || !Number.isFinite(v)) throw new Error('patch.bias must contain only finite numbers'); + } + out.bias = patch.bias; + } + if (patch.activation !== undefined) { + if (typeof patch.activation !== 'string' || patch.activation.length > 64) throw new Error('patch.activation must be an activation name'); + out.activation = patch.activation; + } + if (patch.steepness !== undefined) out.steepness = num(patch.steepness, 'patch.steepness', { min: 0 }); + return out; +} + +function validateTrajectories(rows) { + if (!Array.isArray(rows) || rows.length === 0 || rows.length > MAX_TRAJECTORIES) { + throw new Error(`trajectories must be an array of 1 to ${MAX_TRAJECTORIES} rows`); + } + return rows.map((r, i) => { + if (!r || typeof r !== 'object' || Array.isArray(r)) throw new Error(`trajectories[${i}] must be an object`); + const row = { + input: finiteVector(r.input, `trajectories[${i}].input`), + output: finiteVector(r.output, `trajectories[${i}].output`), + score: num(r.score, `trajectories[${i}].score`), + }; + if (row.score === undefined) throw new Error(`trajectories[${i}].score is required`); + if (r.correction !== undefined && r.correction !== null) row.correction = finiteVector(r.correction, `trajectories[${i}].correction`); + return row; + }); +} + +function create(h) { + const { withRegistry, parseId, summarize, optionalString, parseTags, REGISTRY_PROP, NEEDS, MAX_NOTE_CHARS } = h; + + /** note/tags carried onto the child snapshot. */ + function childMeta(opts) { + const meta = {}; + const note = optionalString(opts.note, MAX_NOTE_CHARS, 'note'); + if (note !== undefined) meta.note = note; + const tags = parseTags(opts.tags); + if (tags !== undefined) meta.tags = tags; + return meta; + } + + async function setLayerOp(opts, resolvePath) { + const id = parseId(opts.id); + const index = layerIndex(opts.layer); + const patch = validatePatch(inlineOrFile(opts.patch, opts.patchPath, 'patch', resolvePath)); + const meta = childMeta(opts); + return withRegistry(opts.registry, resolvePath, async (reg, _ws, registryPath) => ({ + registry: registryPath, parent: id, snapshot: summarize(await reg.setLayer(id, index, patch, meta)), + })); + } + + async function perturbOp(opts, resolvePath) { + const id = parseId(opts.id); + const options = {}; + const scale = num(opts.scale, 'scale', { min: 0, max: 10 }); + if (scale !== undefined) options.scale = scale; + const seed = num(opts.seed, 'seed', { min: 0, max: MAX_SEED, int: true }); + if (seed !== undefined) options.seed = seed; + const layers = layerList(opts.layers); + if (layers !== undefined) options.layers = layers; + const bias = flag(opts.bias, 'bias'); + if (bias !== undefined) options.bias = bias; + const relative = flag(opts.relative, 'relative'); + if (relative !== undefined) options.relative = relative; + const meta = childMeta(opts); + return withRegistry(opts.registry, resolvePath, async (reg, _ws, registryPath) => ({ + registry: registryPath, parent: id, snapshot: summarize(await reg.perturb(id, options, meta)), + })); + } + + async function learnOp(opts, resolvePath) { + const id = parseId(opts.id); + const trajectories = validateTrajectories(inlineOrFile(opts.trajectories, opts.trajectoriesPath, 'trajectories', resolvePath)); + const options = {}; + const set = (key, value) => { if (value !== undefined) options[key] = value; }; + set('epochs', num(opts.epochs, 'epochs', { min: 1, max: MAX_EPOCHS, int: true })); + set('learningRate', num(opts.learningRate, 'learning rate', { min: 1e-9, max: 10 })); + set('seed', num(opts.seed, 'seed', { min: 0, max: MAX_SEED, int: true })); + set('successThreshold', num(opts.successThreshold, 'success threshold', { min: 0, max: 1 })); + set('holdoutFraction', num(opts.holdoutFraction, 'holdout fraction', { min: 0.01, max: 0.9 })); + set('minImprovement', num(opts.minImprovement, 'minimum improvement', { min: 0, max: 1 })); + if (opts.optimizer !== undefined && opts.optimizer !== null) { + if (opts.optimizer !== 'sgd' && opts.optimizer !== 'adamw') throw new Error("optimizer must be 'sgd' or 'adamw'"); + options.optimizer = opts.optimizer; + } + const note = optionalString(opts.note, MAX_NOTE_CHARS, 'note'); + if (note !== undefined) options.note = note; + return withRegistry(opts.registry, resolvePath, async (reg, _ws, registryPath) => { + const r = await reg.learnFromOutcomes(id, trajectories, options); + // `accepted: false` is a normal result (the held-out check did not improve), not an error. + return { + registry: registryPath, parent: r.parent, accepted: r.accepted, reason: r.reason, + child: r.child ? summarize(r.child) : null, rows: r.rows, holdoutMse: r.holdoutMse, trainLoss: r.trainLoss, + }; + }); + } + + const idProp = { type: 'string', description: 'Parent snapshot id (the registry is append-only: the result is a new child snapshot)' }; + const notes = { note: { type: 'string' }, tags: { type: 'array', items: { type: 'string' } } }; + const MCP_TOOLS = [ + { + name: 'weights_set_layer', + description: `Write a child snapshot with one layer patched (weights, bias, activation or steepness; the layer shape cannot change). ${NEEDS}`, + inputSchema: { + type: 'object', + properties: { + registry: REGISTRY_PROP, id: idProp, layer: { type: 'integer', minimum: 0, maximum: MAX_LAYER_INDEX }, + patch: { type: 'object', description: 'Fields to change: weights, bias, activation, steepness' }, + patch_path: { type: 'string', description: 'JSON file holding the patch (alternative to patch; confined to the working directory)' }, + ...notes, + }, + required: ['id', 'layer'], + }, + }, + { + name: 'weights_perturb', + description: `Write a child snapshot with seeded Gaussian noise added to the weights (same seed, same noise). ${NEEDS}`, + inputSchema: { + type: 'object', + properties: { + registry: REGISTRY_PROP, id: idProp, + scale: { type: 'number', minimum: 0, maximum: 10, description: 'Noise standard deviation (default 0.01)' }, + seed: { type: 'integer', minimum: 0, maximum: MAX_SEED, description: 'Default 1' }, + layers: { type: 'array', items: { type: 'integer', minimum: 0, maximum: MAX_LAYER_INDEX }, description: 'Layers to perturb (default all)' }, + bias: { type: 'boolean', description: 'Also perturb biases (default true)' }, + relative: { type: 'boolean', description: "Scale noise by each layer's weight RMS (default false)" }, + ...notes, + }, + required: ['id'], + }, + }, + { + name: 'weights_learn', + description: `Fine-tune a snapshot on outcome trajectories with ruv-fann. A child snapshot is written ONLY if a held-out check improves; otherwise nothing is written and the result says why. ${NEEDS}`, + inputSchema: { + type: 'object', + properties: { + registry: REGISTRY_PROP, id: idProp, + trajectories: { + type: 'array', maxItems: MAX_TRAJECTORIES, + description: 'Rows of {input, output, score, correction?}. score >= successThreshold trains toward output; a failure trains toward its correction (failures without one are skipped)', + items: { type: 'object' }, + }, + trajectories_path: { type: 'string', description: 'JSON file holding the rows (alternative to trajectories; confined to the working directory)' }, + epochs: { type: 'integer', minimum: 1, maximum: MAX_EPOCHS }, + learning_rate: { type: 'number', minimum: 1e-9, maximum: 10 }, + optimizer: { type: 'string', enum: ['sgd', 'adamw'] }, + seed: { type: 'integer', minimum: 0, maximum: MAX_SEED }, + success_threshold: { type: 'number', minimum: 0, maximum: 1 }, + holdout_fraction: { type: 'number', minimum: 0.01, maximum: 0.9 }, + min_improvement: { type: 'number', minimum: 0, maximum: 1 }, + note: { type: 'string' }, + }, + required: ['id'], + }, + }, + ]; + + /** MCP argument (snake_case) -> operation, keyed by tool name. */ + const RUNNERS = { + weights_set_layer: (a, rp) => setLayerOp({ registry: a.registry, id: a.id, layer: a.layer, patch: a.patch, patchPath: a.patch_path, note: a.note, tags: a.tags }, rp), + weights_perturb: (a, rp) => perturbOp({ registry: a.registry, id: a.id, scale: a.scale, seed: a.seed, layers: a.layers, bias: a.bias, relative: a.relative, note: a.note, tags: a.tags }, rp), + weights_learn: (a, rp) => learnOp({ + registry: a.registry, id: a.id, trajectories: a.trajectories, trajectoriesPath: a.trajectories_path, epochs: a.epochs, + learningRate: a.learning_rate, optimizer: a.optimizer, seed: a.seed, successThreshold: a.success_threshold, + holdoutFraction: a.holdout_fraction, minImprovement: a.min_improvement, note: a.note, + }, rp), + }; + + const PRINTERS = { + 'set-layer': (chalk, r) => printChild(chalk, r), + perturb: (chalk, r) => printChild(chalk, r), + learn: (chalk, r) => { + if (!r.accepted) { + console.log(chalk.yellow(`Not accepted: ${r.reason}`)); + } else { + console.log(chalk.green(`Accepted: child snapshot ${r.child.id} (v${r.child.version}) of ${r.parent}`)); + } + console.log(` held-out MSE: ${r.holdoutMse.before.toFixed(6)} -> ${r.holdoutMse.after.toFixed(6)}`); + console.log(` rows: train=${r.rows.train} holdout=${r.rows.holdout} successes=${r.rows.successes} corrections=${r.rows.corrections} skipped=${r.rows.skipped}`); + console.log(chalk.dim(` registry: ${r.registry}`)); + }, + }; + + function printChild(chalk, r) { + const s = r.snapshot; + console.log(chalk.green(`Wrote snapshot ${s.id} (v${s.version}, op=${s.op}) as a child of ${r.parent}`)); + console.log(` hash: ${s.hash}`); + console.log(chalk.dim(` registry: ${r.registry}`)); + } + + /** Register the three subcommands. `run` and `common` come from weights.js's CLI wiring. */ + function registerCommands(cmd, run, common, confine) { + common(cmd.command('set-layer ') + .description('Write a child snapshot with one layer patched') + .requiredOption('--patch ', 'JSON file with the fields to change (weights, bias, activation, steepness)') + .option('--note ', 'Free-form note') + .option('--tags ', 'Comma-separated tags')) + .action(run('set-layer', (id, layer, opts) => setLayerOp({ ...opts, id, layer, patchPath: opts.patch, patch: undefined }, confine))); + + common(cmd.command('perturb ') + .description('Write a child snapshot with seeded Gaussian noise added to the weights') + .option('--scale ', 'Noise standard deviation (default 0.01)') + .option('--seed ', 'Noise seed (default 1)') + .option('--layers ', 'Comma-separated layer indexes (default all)') + .option('--no-bias', 'Leave biases unchanged') + .option('--relative', "Scale noise by each layer's weight RMS") + .option('--note ', 'Free-form note') + .option('--tags ', 'Comma-separated tags')) + .action(run('perturb', (id, opts) => perturbOp({ ...opts, id, bias: opts.bias === false ? false : undefined, relative: opts.relative === true ? true : undefined }, confine))); + + common(cmd.command('learn ') + .description('Fine-tune a snapshot on outcome trajectories; a child is written only if a held-out check improves') + .requiredOption('--trajectories ', 'JSON file: rows of {input, output, score, correction?}') + .option('--epochs ', 'Training epochs') + .option('--learning-rate ', 'Learning rate') + .option('--optimizer ', 'sgd or adamw') + .option('--seed ', 'Seed for the holdout split') + .option('--success-threshold ', 'Score at or above this counts as a success (default 0.5)') + .option('--holdout-fraction ', 'Fraction of rows held out (default 0.25)') + .option('--min-improvement ', 'Required relative MSE reduction to accept (default 0.01)') + .option('--note ', 'Free-form note')) + .action(run('learn', (id, opts) => learnOp({ ...opts, id, trajectoriesPath: opts.trajectories, trajectories: undefined }, confine))); + } + + return { MCP_TOOLS, RUNNERS, PRINTERS, registerCommands, setLayerOp, perturbOp, learnOp }; +} + +module.exports = { create }; diff --git a/npm/packages/ruvector/bin/weights.js b/npm/packages/ruvector/bin/weights.js index 8621b4fa95..425676edb1 100644 --- a/npm/packages/ruvector/bin/weights.js +++ b/npm/packages/ruvector/bin/weights.js @@ -1,12 +1,13 @@ 'use strict'; /** - * `ruvector weights` CLI group and `weights_*` MCP tools, backed by the optional - * peer @ruvector/weight-space (versioned ruv-fann weight snapshots indexed by task - * embedding). + * `ruvector weights` CLI group and `weights_*` MCP tools, backed by the + * @ruvector/weight-space dependency (versioned ruv-fann weight snapshots indexed by + * task embedding). * * Nothing here loads @ruvector/weight-space (or the ONNX embedder) at require time: * both are required inside the operation that needs them, so `ruvector --help` and - * the MCP server start without them. When the package is absent every operation + * the MCP server start without them. The package is a hard dependency, so it is + * normally present; if an install is pruned or does not hoist it, every operation * fails with ERR_WEIGHT_SPACE_MISSING and the install hint below. * * Path handling: every operation takes a `resolvePath` function. The MCP server @@ -32,7 +33,7 @@ const MAX_TEXT_CHARS = 8192; function missingWeightSpaceError() { const err = new Error( - `${WEIGHT_SPACE_PKG} is not installed. It is an optional peer of ruvector; install it with: ${WEIGHT_SPACE_INSTALL_HINT}`, + `${WEIGHT_SPACE_PKG} is not installed, but it is a dependency of ruvector, so this install is incomplete. Install it with: ${WEIGHT_SPACE_INSTALL_HINT}`, ); err.code = 'ERR_WEIGHT_SPACE_MISSING'; err.install = WEIGHT_SPACE_INSTALL_HINT; @@ -260,9 +261,9 @@ const REGISTRY_PROP = { description: `Registry event log (JSON lines; confined to the working directory). Default ${DEFAULT_REGISTRY}`, }; const EMBEDDING_PROP = { type: 'array', items: { type: 'number' }, description: 'Task embedding (all snapshots in a registry share one dimension)' }; -const NEEDS = `Requires the optional peer ${WEIGHT_SPACE_PKG} (${WEIGHT_SPACE_INSTALL_HINT}).`; +const NEEDS = `Runs on ${WEIGHT_SPACE_PKG}; if it is missing, install it with: ${WEIGHT_SPACE_INSTALL_HINT}.`; -const MCP_TOOLS = [ +const BASE_MCP_TOOLS = [ { name: 'weights_save', description: `Save a ruv-fann model snapshot to a weight registry, keyed by a task embedding. ${NEEDS}`, @@ -309,6 +310,12 @@ const MCP_TOOLS = [ }, ]; +// Edit and fine-tune operations (set-layer, perturb, learn) live in weights-edit.js; +// the shared registry plumbing is injected so the two files do not import each other. +const edit = require('./weights-edit').create({ + withRegistry, parseId, summarize, optionalString, parseTags, REGISTRY_PROP, NEEDS, MAX_NOTE_CHARS, +}); +const MCP_TOOLS = [...BASE_MCP_TOOLS, ...edit.MCP_TOOLS]; const MCP_TOOL_NAMES = new Set(MCP_TOOLS.map((t) => t.name)); /** Run a weights_* MCP tool. `resolvePath` is the server's path validator. */ @@ -329,6 +336,8 @@ async function runMcpTool(name, args, resolvePath) { payload = await diffSnapshots({ registry: a.registry, idA: a.id_a, idB: a.id_b }, resolvePath); } else if (name === 'weights_lineage') { payload = await lineageOf({ registry: a.registry, id: a.id }, resolvePath); + } else if (Object.prototype.hasOwnProperty.call(edit.RUNNERS, name)) { + payload = await edit.RUNNERS[name](a, resolvePath); } else { throw new Error(`unknown weights tool '${name}'`); } @@ -376,14 +385,16 @@ function printHuman(chalk, kind, result) { console.log(` hash: ${s.hash}`); console.log(` topology: ${topologyLabel(s.topology)}`); console.log(` tags: ${s.tags.join(',') || '-'} note: ${s.note ?? '-'} outcomes: ${s.outcomes.length}`); + } else if (Object.prototype.hasOwnProperty.call(edit.PRINTERS, kind)) { + edit.PRINTERS[kind](chalk, result); } } -/** Register `ruvector weights save|nearest|diff|lineage|get` on a commander program. */ +/** Register `ruvector weights save|nearest|diff|lineage|get|set-layer|perturb|learn` on a commander program. */ function registerWeightsCommands(program, chalk) { const cmd = program .command('weights') - .description(`Versioned ruv-fann weight registry indexed by task embedding (optional peer ${WEIGHT_SPACE_PKG})`); + .description(`Versioned ruv-fann weight registry indexed by task embedding (${WEIGHT_SPACE_PKG})`); // Exit explicitly (the ONNX embedder can keep the event loop alive), but only // once stdout/stderr have drained: pipe writes are async on some platforms. @@ -446,6 +457,8 @@ function registerWeightsCommands(program, chalk) { .description('One snapshot, including its model and embedding')) .action(run('get', (id, opts) => getSnapshot({ ...opts, id }, confineToWorkingDir))); + edit.registerCommands(cmd, run, common, confineToWorkingDir); + return cmd; } diff --git a/npm/packages/ruvector/package.json b/npm/packages/ruvector/package.json index 6ce3d00e1c..b46924b373 100644 --- a/npm/packages/ruvector/package.json +++ b/npm/packages/ruvector/package.json @@ -12,7 +12,7 @@ "verify-dist": "node scripts/verify-dist.js", "prepack": "npm run build && npm run verify-dist", "prepublishOnly": "npm run build && npm run verify-dist", - "test": "node test/integration.js && node test/graph-modularity.js && node test/backend-fallback.js && node test/mincut-wasm.js && node test/graph-cli-e2e.js && node test/metaharness-sdk.js && node test/metaharness-optional-deps.js && node test/cli-commands.js && node test/metaharness-cli.js && node test/db-workflow.js && node test/fast-agentdb-native.js && node test/mcp-stdio.js && node test/metaharness-mcp.js && node test/sigterm-cleanup.js && node test/mcp-policy.js && node test/mcp-command-security.js && node test/mcp-exploit-regression.js && node test/mcp-handshake.js && node test/mcp-intel-durability.js && node test/add-extras.js && node test/rabitq-optional.js && node test/rabitq-recall.js && node test/diskann-cli.js && node test/skills-install.js && node test/manifest-ranges.js && node test/attention-panic.js && node test/mcp-extras.js && node test/rvf-e2e.js && node test/startup-budget.js && node test/rag-context-rerank.js && node test/neural-q.js && node test/learning-import-types.js && node test/weight-space-optional.js && node test/weight-space-cli.js && node test/e-means.mjs", + "test": "node test/integration.js && node test/graph-modularity.js && node test/backend-fallback.js && node test/mincut-wasm.js && node test/graph-cli-e2e.js && node test/metaharness-sdk.js && node test/metaharness-optional-deps.js && node test/cli-commands.js && node test/metaharness-cli.js && node test/db-workflow.js && node test/fast-agentdb-native.js && node test/mcp-stdio.js && node test/metaharness-mcp.js && node test/sigterm-cleanup.js && node test/mcp-policy.js && node test/mcp-command-security.js && node test/mcp-exploit-regression.js && node test/mcp-handshake.js && node test/mcp-intel-durability.js && node test/add-extras.js && node test/rabitq-optional.js && node test/rabitq-recall.js && node test/diskann-cli.js && node test/skills-install.js && node test/manifest-ranges.js && node test/attention-panic.js && node test/mcp-extras.js && node test/rvf-e2e.js && node test/startup-budget.js && node test/rag-context-rerank.js && node test/neural-q.js && node test/learning-import-types.js && node test/weight-space-optional.js && node test/weight-space-cli.js && node test/weight-space-edit.js && node test/e-means.mjs", "test:e-means": "node test/e-means.mjs" }, "keywords": [ @@ -53,7 +53,8 @@ "chalk": "^4.1.2", "commander": "^11.1.0", "ora": "^5.4.1", - "@ruvector/e-means": "0.1.0" + "@ruvector/e-means": "0.1.0", + "@ruvector/weight-space": "0.1.0" }, "optionalDependencies": { "@metaharness/darwin": "^0.13.0", @@ -107,8 +108,7 @@ "metaharness": "^0.4.20", "@ruvector/rabitq-wasm": "^0.1.1", "rvlite": "^0.2.0", - "ruv-fann": "0.1.0", - "@ruvector/weight-space": "0.1.0" + "ruv-fann": "0.1.0" }, "peerDependenciesMeta": { "@metaharness/darwin": { @@ -158,9 +158,6 @@ }, "ruv-fann": { "optional": true - }, - "@ruvector/weight-space": { - "optional": true } }, "engines": { diff --git a/npm/packages/ruvector/test/rabitq-optional.js b/npm/packages/ruvector/test/rabitq-optional.js index 36b827eb31..10269447d1 100644 --- a/npm/packages/ruvector/test/rabitq-optional.js +++ b/npm/packages/ruvector/test/rabitq-optional.js @@ -69,9 +69,11 @@ test('manifest: no new hard dependencies were added for extras', () => { const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')); // @ruvector/e-means (#1489) is a deliberate hard edge: a small pure-WASM // package that ruvector/clustering.mjs re-exports statically. + // @ruvector/weight-space (ADR-358 amendment) is the other deliberate hard edge: a small + // pure-JS package behind `ruvector weights`, lazy-loaded inside the commands. assert.deepStrictEqual(Object.keys(pkg.dependencies).sort(), [ '@modelcontextprotocol/sdk', '@ruvector/attention', '@ruvector/core', '@ruvector/e-means', - '@ruvector/gnn', '@ruvector/sona', 'chalk', 'commander', 'ora', + '@ruvector/gnn', '@ruvector/sona', '@ruvector/weight-space', 'chalk', 'commander', 'ora', ]); }); diff --git a/npm/packages/ruvector/test/weight-space-cli.js b/npm/packages/ruvector/test/weight-space-cli.js index cdf18d912a..57dfb90d9d 100644 --- a/npm/packages/ruvector/test/weight-space-cli.js +++ b/npm/packages/ruvector/test/weight-space-cli.js @@ -1,8 +1,8 @@ #!/usr/bin/env node /** * `ruvector weights` and the weights_* MCP tools against the real - * @ruvector/weight-space. Prints SKIP and exits 0 when the optional peer is not - * installed (CI installs it from the sibling package; see ruvector-npm-ci.yml). + * @ruvector/weight-space. It is a hard dependency of ruvector, so a missing install is a + * failure here, not a SKIP: a skip would hide a broken install. * * Uses explicit --embedding values only, so nothing is downloaded. */ @@ -20,8 +20,8 @@ let wsPath; try { wsPath = require.resolve('@ruvector/weight-space', { paths: [ROOT] }); } catch { - console.log(' SKIP @ruvector/weight-space not installed (npm i @ruvector/weight-space@0.1.0)'); - process.exit(0); + console.error(' FAIL @ruvector/weight-space is a dependency of ruvector but does not resolve (run npm install)'); + process.exit(1); } const work = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ruvector-ws-cli-'))); diff --git a/npm/packages/ruvector/test/weight-space-edit.js b/npm/packages/ruvector/test/weight-space-edit.js new file mode 100644 index 0000000000..3b8a463be1 --- /dev/null +++ b/npm/packages/ruvector/test/weight-space-edit.js @@ -0,0 +1,289 @@ +#!/usr/bin/env node +/** + * `ruvector weights set-layer | perturb | learn` and the weights_set_layer / weights_perturb / + * weights_learn MCP tools against the real @ruvector/weight-space. + * + * Each operation writes a CHILD snapshot (the registry is append-only), so these tests check + * lineage, determinism, that a rejected fine-tune writes nothing, input bounds, and that file + * inputs are confined to the working directory. + * + * Uses explicit --embedding values only, so nothing is downloaded. + */ + +const assert = require('assert'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); +const { spawn, spawnSync } = require('child_process'); + +const ROOT = path.join(__dirname, '..'); +const CLI = path.join(ROOT, 'bin', 'cli.js'); + +let ws; +try { + ws = require(require.resolve('@ruvector/weight-space', { paths: [ROOT] })); +} catch { + console.error(' FAIL @ruvector/weight-space is a dependency of ruvector but does not resolve (run npm install)'); + process.exit(1); +} + +const work = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ruvector-ws-edit-'))); +const outside = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ruvector-ws-edit-outside-'))); +const ENV = { ...process.env, HOME: work, NO_COLOR: '1' }; +const REGISTRY = path.join(work, '.ruvector', 'weights.jsonl'); + +const registryLines = () => fs.readFileSync(REGISTRY, 'utf8').split('\n').filter(Boolean).length; + +function cli(args) { + const r = spawnSync(process.execPath, [CLI, ...args], { cwd: work, env: ENV, encoding: 'utf8', timeout: 90000 }); + let json = null; + try { json = JSON.parse(r.stdout); } catch { /* human output */ } + return { status: r.status, stdout: r.stdout, stderr: r.stderr, json }; +} + +function ok(r, what) { + assert.strictEqual(r.status, 0, `${what} failed (exit ${r.status}): ${r.stdout}\n${r.stderr}`); + assert.ok(r.json && r.json.success === true, `${what}: expected success JSON, got ${r.stdout}`); + return r.json; +} + +function fails(r, pattern, what) { + assert.notStrictEqual(r.status, 0, `${what}: expected a non-zero exit`); + assert.ok(r.json && r.json.success === false, `${what}: expected an error JSON, got ${r.stdout}`); + if (pattern) assert.match(r.json.error, pattern, `${what}: ${r.json.error}`); + return r.json; +} + +let passed = 0; +let failed = 0; +async function test(name, fn) { + try { await fn(); passed++; console.log(` PASS ${name}`); } + catch (e) { failed++; console.log(` FAIL ${name}\n ${e.stack || e.message}`); } +} + +function mcpSession() { + const child = spawn(process.execPath, [CLI, 'mcp', 'start'], { cwd: work, env: ENV, stdio: ['pipe', 'pipe', 'pipe'] }); + let nextId = 1; + let buffer = ''; + const pending = new Map(); + child.stdout.on('data', (chunk) => { + buffer += chunk.toString(); + const lines = buffer.split(/\r?\n/); + buffer = lines.pop() || ''; + for (const line of lines) { + if (!line.trim()) continue; + let msg; + try { msg = JSON.parse(line); } catch { continue; } + const waiter = pending.get(msg.id); + if (waiter) { pending.delete(msg.id); waiter(msg); } + } + }); + const request = (method, params) => new Promise((resolve, reject) => { + const id = nextId++; + const timer = setTimeout(() => { pending.delete(id); reject(new Error(`timed out waiting for ${method}`)); }, 60000); + pending.set(id, (msg) => { clearTimeout(timer); resolve(msg); }); + child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`); + }); + const call = async (name, args) => { + const res = await request('tools/call', { name, arguments: args }); + return { isError: res.result.isError === true, payload: JSON.parse(res.result.content[0].text) }; + }; + return { child, request, call }; +} + +/** A [2, 4, 1] network: 2 inputs, 4 hidden units, 1 output. */ +const mlp = () => ws.createMlp([2, 4, 1], { seed: 3 }); + +/** Trajectories the model can learn: y = a*b. */ +const trajectories = (n = 64) => Array.from({ length: n }, (_, i) => { + const a = Math.sin(i * 1.7); + const b = Math.cos(i * 2.3); + return { input: [a, b], output: [a * b], score: 1 }; +}); + +async function main() { + console.log(`\nruvector weights edit + fine-tune (real @ruvector/weight-space)`); + fs.writeFileSync(path.join(work, 'model.json'), JSON.stringify(mlp())); + fs.writeFileSync(path.join(work, 'traj.json'), JSON.stringify(trajectories())); + fs.writeFileSync(path.join(outside, 'patch.json'), JSON.stringify({ bias: [0, 0, 0, 0] })); + fs.writeFileSync(path.join(outside, 'traj.json'), JSON.stringify(trajectories())); + + const root = ok(cli(['weights', 'save', '--model', 'model.json', '--embedding', '1,0,0', '--task', 'edit-root', '--json']), 'save root').snapshot; + + await test('set-layer: writes a child with op=setLayer, version+1 and the parent link; only that layer changes', () => { + fs.writeFileSync(path.join(work, 'patch.json'), JSON.stringify({ bias: [0.5, 0.5, 0.5, 0.5] })); + const r = ok(cli(['weights', 'set-layer', root.id, '0', '--patch', 'patch.json', '--note', 'raise bias', '--tags', 'edit', '--json']), 'set-layer'); + assert.strictEqual(r.parent, root.id); + assert.strictEqual(r.snapshot.op, 'setLayer'); + assert.strictEqual(r.snapshot.version, root.version + 1); + assert.strictEqual(r.snapshot.parent, root.id); + assert.strictEqual(r.snapshot.note, 'raise bias'); + assert.deepStrictEqual(r.snapshot.tags, ['edit']); + const d = ok(cli(['weights', 'diff', root.id, r.snapshot.id, '--json']), 'diff').diff; + assert.strictEqual(d.compatible, true); + assert.ok(d.layers.find((l) => l.index === 0).changed > 0, 'layer 0 changed'); + assert.strictEqual(d.layers.find((l) => l.index === 1).changed, 0, 'layer 1 untouched'); + const lin = ok(cli(['weights', 'lineage', r.snapshot.id, '--json']), 'lineage').lineage; + assert.deepStrictEqual(lin.map((s) => s.id), [root.id, r.snapshot.id]); + }); + + await test('set-layer: a shape change or an unsupported field is refused and writes nothing', () => { + const before = registryLines(); + fs.writeFileSync(path.join(work, 'bad-shape.json'), JSON.stringify({ weights: [1, 2, 3] })); + fails(cli(['weights', 'set-layer', root.id, '0', '--patch', 'bad-shape.json', '--json']), undefined, 'wrong weight count'); + fs.writeFileSync(path.join(work, 'bad-field.json'), JSON.stringify({ outputs: 9 })); + fails(cli(['weights', 'set-layer', root.id, '0', '--patch', 'bad-field.json', '--json']), /unsupported field 'outputs'/, 'unsupported field'); + fs.writeFileSync(path.join(work, 'empty.json'), '{}'); + fails(cli(['weights', 'set-layer', root.id, '0', '--patch', 'empty.json', '--json']), /at least one of/, 'empty patch'); + fails(cli(['weights', 'set-layer', root.id, '99', '--patch', 'patch.json', '--json']), /layer must be at most/, 'layer out of range'); + fails(cli(['weights', 'set-layer', 'ws-doesnotexist', '0', '--patch', 'patch.json', '--json']), undefined, 'unknown snapshot'); + assert.strictEqual(registryLines(), before, 'no snapshot was written by a refused edit'); + }); + + await test('perturb: seeded and deterministic; --no-bias leaves biases untouched', () => { + const a = ok(cli(['weights', 'perturb', root.id, '--scale', '0.05', '--seed', '7', '--json']), 'perturb a').snapshot; + const b = ok(cli(['weights', 'perturb', root.id, '--scale', '0.05', '--seed', '7', '--json']), 'perturb b').snapshot; + const c = ok(cli(['weights', 'perturb', root.id, '--scale', '0.05', '--seed', '8', '--json']), 'perturb c').snapshot; + assert.strictEqual(a.op, 'perturb'); + assert.strictEqual(a.parent, root.id); + assert.strictEqual(a.hash, b.hash, 'same seed gives the same model'); + assert.notStrictEqual(a.hash, c.hash, 'a different seed gives a different model'); + const nb = ok(cli(['weights', 'perturb', root.id, '--scale', '0.05', '--seed', '7', '--no-bias', '--json']), 'perturb no-bias').snapshot; + const parent = ok(cli(['weights', 'get', root.id, '--json']), 'get parent').snapshot.model; + const child = ok(cli(['weights', 'get', nb.id, '--json']), 'get child').snapshot.model; + parent.layers.forEach((l, i) => assert.deepStrictEqual(child.layers[i].bias, l.bias, `layer ${i} bias unchanged`)); + assert.notDeepStrictEqual(child.layers[0].weights, parent.layers[0].weights, 'weights did change'); + }); + + await test('perturb: bounds are enforced before anything is written', () => { + const before = registryLines(); + fails(cli(['weights', 'perturb', root.id, '--scale', '1000', '--json']), /scale must be at most/, 'scale too big'); + fails(cli(['weights', 'perturb', root.id, '--scale', 'NaN', '--json']), /finite number/, 'NaN scale'); + fails(cli(['weights', 'perturb', root.id, '--seed', '1.5', '--json']), /integer/, 'fractional seed'); + fails(cli(['weights', 'perturb', root.id, '--layers', '0,abc', '--json']), /layers\[1\]/, 'bad layer list'); + fails(cli(['weights', 'perturb', 'not an id', '--json']), /snapshot id/, 'bad id'); + assert.strictEqual(registryLines(), before); + }); + + await test('learn: an accepted fine-tune writes a child with op=finetune and a better held-out error', () => { + const r = ok(cli(['weights', 'learn', root.id, '--trajectories', 'traj.json', '--epochs', '300', '--learning-rate', '0.2', '--json']), 'learn'); + assert.strictEqual(r.accepted, true, r.reason); + assert.strictEqual(r.parent, root.id); + assert.strictEqual(r.child.op, 'finetune'); + assert.strictEqual(r.child.parent, root.id); + assert.ok(r.holdoutMse.after < r.holdoutMse.before, `holdout MSE improved: ${r.holdoutMse.before} -> ${r.holdoutMse.after}`); + assert.ok(r.rows.train > 0 && r.rows.holdout > 0); + }); + + await test('learn: a fine-tune that does not clear the held-out check is reported, not an error, and writes nothing', () => { + const before = registryLines(); + // Requiring a 100% error reduction cannot be met, so the result must be a rejection. + const r = ok(cli(['weights', 'learn', root.id, '--trajectories', 'traj.json', '--epochs', '5', '--min-improvement', '1', '--json']), 'learn rejected'); + assert.strictEqual(r.accepted, false); + assert.strictEqual(r.child, null); + assert.ok(typeof r.reason === 'string' && r.reason.length > 0, 'a reason is given'); + assert.strictEqual(registryLines(), before, 'a rejected fine-tune appends nothing'); + const human = cli(['weights', 'learn', root.id, '--trajectories', 'traj.json', '--epochs', '5', '--min-improvement', '1']); + assert.strictEqual(human.status, 0); + assert.match(human.stdout, /Not accepted:/); + }); + + await test('learn: bad trajectories and out-of-range options are refused before training', () => { + const before = registryLines(); + fs.writeFileSync(path.join(work, 'bad-rows.json'), JSON.stringify([{ input: [1, 2], output: [3] }])); + fails(cli(['weights', 'learn', root.id, '--trajectories', 'bad-rows.json', '--json']), /score/, 'missing score'); + fs.writeFileSync(path.join(work, 'bad-num.json'), JSON.stringify([{ input: [1, 'x'], output: [3], score: 1 }])); + fails(cli(['weights', 'learn', root.id, '--trajectories', 'bad-num.json', '--json']), /finite numbers/, 'non-numeric input'); + fs.writeFileSync(path.join(work, 'not-array.json'), JSON.stringify({ input: [1] })); + fails(cli(['weights', 'learn', root.id, '--trajectories', 'not-array.json', '--json']), /array of 1 to/, 'not an array'); + fails(cli(['weights', 'learn', root.id, '--trajectories', 'traj.json', '--epochs', '99999999', '--json']), /epochs must be at most/, 'epochs cap'); + fails(cli(['weights', 'learn', root.id, '--trajectories', 'traj.json', '--optimizer', 'rmsprop', '--json']), /optimizer must be/, 'optimizer'); + // Wrong input width for this model: the library rejects it. + fs.writeFileSync(path.join(work, 'wrong-width.json'), JSON.stringify([{ input: [1, 2, 3], output: [1], score: 1 }])); + fails(cli(['weights', 'learn', root.id, '--trajectories', 'wrong-width.json', '--json']), undefined, 'input width does not match the model'); + assert.strictEqual(registryLines(), before); + }); + + await test('confinement: patch and trajectories files outside the working directory are refused', () => { + const before = registryLines(); + fails(cli(['weights', 'set-layer', root.id, '0', '--patch', path.join(outside, 'patch.json'), '--json']), /outside the working directory/, 'patch outside'); + fails(cli(['weights', 'learn', root.id, '--trajectories', path.join(outside, 'traj.json'), '--json']), /outside the working directory/, 'trajectories outside'); + fails(cli(['weights', 'perturb', root.id, '--registry', path.join(outside, 'w.jsonl'), '--json']), /outside the working directory/, 'registry outside'); + assert.strictEqual(registryLines(), before); + assert.deepStrictEqual(fs.readdirSync(outside).sort(), ['patch.json', 'traj.json'], 'nothing written outside the workspace'); + }); + + await test('MCP: the three tools are listed, work, and enforce the same bounds and path confinement', async () => { + const { child, request, call } = mcpSession(); + try { + const init = await request('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'ws-edit-test', version: '1.0.0' } }); + assert.ok(init.result); + child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`); + const list = await request('tools/list', {}); + const names = list.result.tools.map((t) => t.name); + for (const n of ['weights_set_layer', 'weights_perturb', 'weights_learn']) assert.ok(names.includes(n), `${n} listed`); + + const set = await call('weights_set_layer', { id: root.id, layer: 1, patch: { bias: [0.25] }, note: 'via mcp' }); + assert.strictEqual(set.isError, false, JSON.stringify(set.payload)); + assert.strictEqual(set.payload.snapshot.op, 'setLayer'); + assert.strictEqual(set.payload.snapshot.parent, root.id); + + const per = await call('weights_perturb', { id: root.id, scale: 0.02, seed: 3, layers: [0], bias: false }); + assert.strictEqual(per.isError, false, JSON.stringify(per.payload)); + assert.strictEqual(per.payload.snapshot.op, 'perturb'); + + const learn = await call('weights_learn', { id: root.id, trajectories: trajectories(), epochs: 300, learning_rate: 0.2 }); + assert.strictEqual(learn.isError, false, JSON.stringify(learn.payload)); + assert.strictEqual(learn.payload.accepted, true, learn.payload.reason); + assert.strictEqual(learn.payload.child.op, 'finetune'); + + const before = registryLines(); + const rejected = await call('weights_learn', { id: root.id, trajectories: trajectories(), epochs: 5, min_improvement: 1 }); + assert.strictEqual(rejected.isError, false); + assert.strictEqual(rejected.payload.accepted, false); + assert.strictEqual(registryLines(), before); + + const both = await call('weights_set_layer', { id: root.id, layer: 0, patch: { bias: [0, 0, 0, 0] }, patch_path: 'patch.json' }); + assert.strictEqual(both.isError, true); + assert.match(both.payload.error, /exactly one of/); + const neither = await call('weights_learn', { id: root.id }); + assert.strictEqual(neither.isError, true); + assert.match(neither.payload.error, /exactly one of/); + const big = await call('weights_perturb', { id: root.id, scale: 99999 }); + assert.strictEqual(big.isError, true); + assert.match(big.payload.error, /scale must be at most/); + const epochs = await call('weights_learn', { id: root.id, trajectories: trajectories(4), epochs: 1e9 }); + assert.strictEqual(epochs.isError, true); + + const escPatch = await call('weights_set_layer', { id: root.id, layer: 0, patch_path: path.join(outside, 'patch.json') }); + assert.strictEqual(escPatch.isError, true); + assert.match(escPatch.payload.error, /outside the working directory/); + const escTraj = await call('weights_learn', { id: root.id, trajectories_path: '../' + path.basename(outside) + '/traj.json' }); + assert.strictEqual(escTraj.isError, true); + assert.match(escTraj.payload.error, /outside the working directory/); + const escReg = await call('weights_perturb', { id: root.id, registry: path.join(outside, 'w.jsonl') }); + assert.strictEqual(escReg.isError, true); + assert.match(escReg.payload.error, /outside the working directory/); + } finally { + child.stdin.end(); + child.kill('SIGTERM'); + } + }); + + await test('the registry still verifies after all the writes (hash chain replays)', () => { + const lin = ok(cli(['weights', 'lineage', root.id, '--json']), 'lineage after edits').lineage; + assert.strictEqual(lin[0].id, root.id); + const nearest = ok(cli(['weights', 'nearest', '--embedding', '1,0,0', '-k', '3', '--json']), 'nearest after edits'); + assert.strictEqual(nearest.results.length, 3); + }); + + console.log(`\nResults: ${passed} passed, ${failed} failed`); + process.exitCode = failed ? 1 : 0; +} + +main() + .catch((e) => { console.error(e); process.exitCode = 1; }) + .finally(() => { + fs.rmSync(work, { recursive: true, force: true }); + fs.rmSync(outside, { recursive: true, force: true }); + }); diff --git a/npm/packages/ruvector/test/weight-space-optional.js b/npm/packages/ruvector/test/weight-space-optional.js index ec86233f9a..c24919cac4 100644 --- a/npm/packages/ruvector/test/weight-space-optional.js +++ b/npm/packages/ruvector/test/weight-space-optional.js @@ -1,12 +1,13 @@ #!/usr/bin/env node /** - * @ruvector/weight-space is an optional peer of ruvector. + * @ruvector/weight-space is a hard dependency of ruvector (ADR-358 amendment). * - * (a) manifest: exact optional peer (0.1.0), never a dependency of any kind, so a - * default install does not fetch it. - * (b) absent: with the package hidden by a module-resolution shim (works whether or - * not it is installed), `ruvector weights ...` prints the install hint and exits - * non-zero, the weights_* MCP tools return a structured error with the hint, and + * (a) manifest: exact-pinned runtime dependency (0.1.0), no longer a peer of any kind. + * (b) degradation: the package stays lazy-loaded, so a broken or pruned install (for + * example a hoisting package manager or `npm i --omit=...`) degrades cleanly. With + * the package hidden by a module-resolution shim (works whether or not it is + * installed), `ruvector weights ...` prints the install hint and exits non-zero, + * the weights_* MCP tools return a structured error with the hint, and * require('ruvector') still loads. */ @@ -79,14 +80,13 @@ function mcpSession() { } async function main() { - console.log('\n@ruvector/weight-space optional peer'); + console.log('\n@ruvector/weight-space hard dependency, lazy-loaded'); - await test('manifest: exact optional peer 0.1.0, never a dependency', () => { + await test('manifest: exact runtime dependency 0.1.0, not a peer, dev or optional dependency', () => { const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')); const name = '@ruvector/weight-space'; - assert.strictEqual(pkg.peerDependencies[name], '0.1.0'); - assert.strictEqual(pkg.peerDependenciesMeta[name].optional, true); - for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) { + assert.strictEqual(pkg.dependencies[name], '0.1.0'); + for (const section of ['peerDependencies', 'peerDependenciesMeta', 'devDependencies', 'optionalDependencies']) { assert.ok(!(name in (pkg[section] || {})), `${name} must not be in ${section}`); } });