Skip to content

ruvnet.

Python

feat(ruvnet): bind change pages to content snapshots

rUv4a5a86084ad0
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index e160b6a..f450cb1 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -12,7 +12,7 @@
"name": "ruvnet",
"source": "./plugins/ruvnet",
"description": "RuV Stack skills and the federation MCP connector",
- "version": "0.4.0"
+ "version": "0.5.0"
}
]
}
diff --git a/README.md b/README.md
index ab99101..71c1034 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
> **Start with the RuV Stack:** [Install skills + marketplace](docs/entrypoint/INSTALL.md) · [CLI / MCP guide](plugins/ruvnet/docs/INSTALL.md#local-cli-and-mcp-companion) · [MetaHarness](https://github.com/ruvnet/metaharness)
> Claude Code: `/plugin marketplace add ruvnet/ruvnet`, then `/plugin install ruvnet@ruvnet`.
-> Reviewed changes: `node plugins/ruvnet/bin/ruvnet.mjs changes 5 ruflo security` · follow the returned opaque cursor for later pages · [Harness evidence](https://ruvnet-harness-evidence.ruv.chatgpt.site)
+> Reviewed changes: `node plugins/ruvnet/bin/ruvnet.mjs changes 5 ruflo security` · follow the returned cursor and snapshot ID for later pages · [Harness evidence](https://ruvnet-harness-evidence.ruv.chatgpt.site)
> **September 2026:** RuView and Ruflo remain the two distribution anchors. Fourteen repositories were added since August 10, weighted toward governed evolution and agent operations: Dream Machine, Autogenous, ruClip, openAVO, LatentMesh, and MoE Foundry.
diff --git a/docs/self-improvement/2026-09-17-benchmarks.json b/docs/self-improvement/2026-09-17-benchmarks.json
new file mode 100644
index 0000000..fac379d
--- /dev/null
+++ b/docs/self-improvement/2026-09-17-benchmarks.json
@@ -0,0 +1,42 @@
+{
+ "schemaVersion": 1,
+ "date": "2026-09-17",
+ "runner": "../bench-paired-20260916.mjs",
+ "seed": 1729,
+ "method": {
+ "pairedRuns": 15,
+ "order": "alternating",
+ "discoveryIterationsPerRun": 10000,
+ "coldCliIterationsPerRun": 20,
+ "summaryStatistic": "median of per-run p95 values; median for RSS"
+ },
+ "environment": {
+ "os": "Linux 6.18.44 x86_64",
+ "node": "v24.19.0",
+ "npm": "11.9.0"
+ },
+ "baseline": {
+ "revision": "846201b3baa898349f43a09348a7981353c27c6a",
+ "discoveryP95Ms": [0.0013419999999939591, 0.0014919999999989386, 0.0010520000000013852, 0.0009809999999959018, 0.0014919999999989386, 0.0009709999999998331, 0.001021000000001493, 0.001041999999998211, 0.0010219999999989682, 0.0014919999999989386, 0.0015420000000005984, 0.0015819999999990841, 0.000990999999999076, 0.0009719999999973084, 0.0013620000000003074],
+ "coldCliP95Ms": [72.11870899999985, 73.45984500000009, 68.64061300000003, 72.83660100000003, 74.09337900000003, 68.4855409999999, 69.94457899999998, 78.73462500000005, 71.93527800000001, 70.51316600000001, 71.04739600000016, 71.939394, 72.23714800000005, 223.85182399999985, 86.67642],
+ "rssBytes": [47898624, 48193536, 47841280, 47837184, 47570944, 47513600, 47792128, 47411200, 47669248, 47460352, 47685632, 48091136, 47964160, 47722496, 47681536]
+ },
+ "candidate": {
+ "discoveryP95Ms": [0.0013520000000042387, 0.0009809999999959018, 0.0009709999999998331, 0.0009719999999973084, 0.0013020000000025789, 0.001452000000000453, 0.0009510000000005903, 0.0009820000000004825, 0.0009319999999988227, 0.0009720000000044138, 0.0014029999999962683, 0.0015830000000036648, 0.00100100000000225, 0.0014419999999972788, 0.0010109999999983188],
+ "coldCliP95Ms": [78.187319, 72.9613240000001, 74.201843, 70.60781700000007, 76.14222799999999, 69.86386700000003, 69.11467900000002, 74.79459800000001, 73.65124399999999, 71.80238800000001, 75.23354900000004, 71.33741800000007, 77.32816300000002, 70.429127, 71.64915300000007],
+ "rssBytes": [48013312, 46981120, 48025600, 47616000, 48291840, 48181248, 47542272, 48009216, 47521792, 47484928, 48148480, 48156672, 47538176, 47759360, 47968256]
+ },
+ "summary": {
+ "baselineDiscoveryP95Ms": 0.0010520000000013852,
+ "candidateDiscoveryP95Ms": 0.00100100000000225,
+ "discoveryDeltaPercent": -4.847908745158548,
+ "baselineColdCliP95Ms": 72.11870899999985,
+ "candidateColdCliP95Ms": 72.9613240000001,
+ "coldCliDeltaMs": 0.8426150000002508,
+ "coldCliDeltaPercent": 1.1683722735528344,
+ "baselineRssBytes": 47722496,
+ "candidateRssBytes": 47968256,
+ "rssDeltaBytes": 245760,
+ "allFrozenPerformanceGatesPassed": true
+ }
+}
diff --git a/docs/self-improvement/2026-09-17-plan.json b/docs/self-improvement/2026-09-17-plan.json
new file mode 100644
index 0000000..1544404
--- /dev/null
+++ b/docs/self-improvement/2026-09-17-plan.json
@@ -0,0 +1,36 @@
+{
+ "date": "2026-09-17",
+ "candidate": "content-addressed-snapshot-contract",
+ "hypothesis": "Adding a deterministic snapshot identifier and an optional expected-snapshot precondition will let hosts detect mid-session provenance rollover before mixing pages, while preserving the companion's offline read-only boundary.",
+ "baseline": "846201b3baa898349f43a09348a7981353c27c6a",
+ "heldOutChecks": [
+ "every change page exposes a deterministic sha256 snapshot identifier",
+ "the identifier remains stable for identical evidence and changes when evidence changes",
+ "a matching expected snapshot continues to the exact next page without overlap or gaps",
+ "a mismatched expected snapshot fails closed before returning records",
+ "CLI accepts a matching snapshot precondition and rejects a mismatch with a nonzero exit",
+ "MCP exposes the snapshot precondition, rejects a mismatch, and the changes resource reports the same identifier"
+ ],
+ "acceptance": {
+ "heldOutChecksPassed": 6,
+ "existingTestsPassed": true,
+ "validationPassed": true,
+ "dependencyAuditHighOrCritical": 0,
+ "securityScanHighOrCritical": 0,
+ "metaharnessHardConstraints": "6/6",
+ "discoveryP95RegressionMaximumPercent": 20,
+ "coldCliP95RegressionMaximumPercent": 20,
+ "coldCliP95AbsoluteAllowanceMs": 5,
+ "rssIncreaseMaximumBytes": 5242880
+ },
+ "memoryDecision": {
+ "ruvectorWasm": "defer retrieval adoption until at least 100 sanitized provenance records support leakage-free exact, vector and fused comparisons; separately record the new supported MinCut WASM capability",
+ "gnn": "reject for the current corpus unless a held-out graph task demonstrates at least ten percentage points of task-success gain over exact filtering and a shuffled-graph control"
+ },
+ "forecast": {
+ "prediction": "Within 90 days, agent evidence and memory interfaces will increasingly expose content-addressed snapshot or receipt identifiers so caches, replay and audit can fail closed across state transitions.",
+ "confidencePercent": 82,
+ "horizonDate": "2026-12-16",
+ "falsifiableCriterion": "By 2026-12-16, at least two primary agent-memory, MCP, or run-evidence implementations newly publish digest-, receipt-, or revision-bound snapshot metadata used for cache invalidation or replay verification."
+ }
+}
diff --git a/plugins/ruvnet/.claude-plugin/plugin.json b/plugins/ruvnet/.claude-plugin/plugin.json
index efe391d..09e7e0f 100644
--- a/plugins/ruvnet/.claude-plugin/plugin.json
+++ b/plugins/ruvnet/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "ruvnet",
- "version": "0.4.0",
+ "version": "0.5.0",
"description": "Your entry point to the RuV Stack: discovery, federation and governed MetaHarness integration.",
"author": {
"name": "rUv",
diff --git a/plugins/ruvnet/.codex-plugin/plugin.json b/plugins/ruvnet/.codex-plugin/plugin.json
index 33ef582..ebb886a 100644
--- a/plugins/ruvnet/.codex-plugin/plugin.json
+++ b/plugins/ruvnet/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "ruvnet",
- "version": "0.4.0",
+ "version": "0.5.0",
"description": "Discover and integrate the RuV Stack with bounded skills and the Ruflo federation.",
"author": {
"name": "rUv",
diff --git a/plugins/ruvnet/bin/ruvnet.mjs b/plugins/ruvnet/bin/ruvnet.mjs
old mode 100755
new mode 100644
index d5b6588..e2d0f42
--- a/plugins/ruvnet/bin/ruvnet.mjs
+++ b/plugins/ruvnet/bin/ruvnet.mjs
@@ -4,16 +4,16 @@ import { VERSION, discover, project, changes, plan, connect } from '../lib/core.
async function main(args) {
const [command, ...rest] = args;
if (!command || command === 'help' || command === '--help') {
- console.log(`RuV Stack entrypoint ${VERSION}\n\nruvnet catalog [keywords] Discover source-linked projects\nruvnet project <id> Inspect one project with upstream provenance\nruvnet changes [limit] [project] [kind] [cursor] Page through reviewed upstream changes\nruvnet plan <goal> Advisory MetaHarness integration plan\nruvnet connect <host> chatgpt, claude, claude-code, lovable, codex, stdio\nruvnet mcp Local read-only MCP over stdio\n\nNo shell execution, repository writes, network calls or federation signing.\nHosted federation: ChatGPT https://x.ruv.io/chatgpt/mcp · other hosts https://x.ruv.io/mcp\nInstall: https://github.com/ruvnet/ruvnet/blob/main/docs/entrypoint/INSTALL.md`);
+ console.log(`RuV Stack entrypoint ${VERSION}\n\nruvnet catalog [keywords] Discover source-linked projects\nruvnet project <id> Inspect one project with upstream provenance\nruvnet changes [limit] [project] [kind] [cursor] [snapshot-id] Page one reviewed snapshot\nruvnet plan <goal> Advisory MetaHarness integration plan\nruvnet connect <host> chatgpt, claude, claude-code, lovable, codex, stdio\nruvnet mcp Local read-only MCP over stdio\n\nNo shell execution, repository writes, network calls or federation signing.\nHosted federation: ChatGPT https://x.ruv.io/chatgpt/mcp · other hosts https://x.ruv.io/mcp\nInstall: https://github.com/ruvnet/ruvnet/blob/main/docs/entrypoint/INSTALL.md`);
return;
}
if (command === '--version' && !rest.length) return console.log(VERSION);
if (command === 'mcp' && !rest.length) return (await import('../lib/mcp.mjs')).serve();
let result;
if (command === 'catalog') result = discover(rest.join(' '), 10);
- else if (command === 'changes' && rest.length <= 4) {
+ else if (command === 'changes' && rest.length <= 5) {
const limit = rest.length ? Number(rest[0]) : 10;
- result = changes(limit, Date.now(), { ...(rest[1] === undefined ? {} : { project: rest[1] }), ...(rest[2] === undefined ? {} : { kind: rest[2] }) }, rest[3]);
+ result = changes(limit, Date.now(), { ...(rest[1] === undefined ? {} : { project: rest[1] }), ...(rest[2] === undefined ? {} : { kind: rest[2] }) }, rest[3], rest[4]);
}
else if (command === 'plan') result = plan(rest.join(' '));
else if (command === 'project' && rest.length === 1) result = project(rest[0]);
diff --git a/plugins/ruvnet/data/upstream.json b/plugins/ruvnet/data/upstream.json
index 4905581..0b29257 100644
--- a/plugins/ruvnet/data/upstream.json
+++ b/plugins/ruvnet/data/upstream.json
@@ -1,15 +1,23 @@
{
"schemaVersion": 1,
- "observedAt": "2026-09-16T10:39:15Z",
+ "observedAt": "2026-09-17T10:37:27Z",
"retention": "This file is a reviewed current snapshot. Dated reports under docs/self-improvement preserve prior observations.",
"sources": [
- {"id":"ruflo","repository":"https://github.com/ruvnet/ruflo","revision":"a65bdf683a73dcc1f20d455658daab1cca07306b","committedAt":"2026-09-16T04:22:58Z","license":"MIT"},
+ {"id":"ruflo","repository":"https://github.com/ruvnet/ruflo","revision":"6f0ed7112873eedc7cfe17281a2585188190b790","committedAt":"2026-09-16T16:36:46Z","license":"MIT"},
{"id":"metaharness","repository":"https://github.com/ruvnet/metaharness","revision":"d5833dc6512ac1adeeef91a331c29055cd8a4dbb","committedAt":"2026-09-05T15:29:24Z","license":"MIT"},
- {"id":"ruvector","repository":"https://github.com/ruvnet/RuVector","revision":"115de07ce5222b761cc32bf1d9133247c753091b","committedAt":"2026-09-16T04:33:56Z","license":"MIT"},
+ {"id":"ruvector","repository":"https://github.com/ruvnet/RuVector","revision":"b336fbae8b15a5a487fc3e7c14a80dcb4984b04a","committedAt":"2026-09-16T20:32:22Z","license":"MIT"},
{"id":"agentdb","repository":"https://github.com/ruvnet/agentdb","revision":"6cdefe451f6afe7395bc88d3587a0225d161089b","committedAt":"2026-07-30T00:59:00Z","license":"MIT"},
{"id":"autogenous","repository":"https://github.com/ruvnet/autogenous","revision":"905aa6cbe213392f8b3cab5d4f17bc3a48e0a509","committedAt":"2026-09-16T01:58:33Z","license":"MIT"}
],
"changes": [
+ {"id":"ruvector-napi-binaries-refresh","project":"ruvector","revision":"b336fbae8b15a5a487fc3e7c14a80dcb4984b04a","committedAt":"2026-09-16T20:32:22Z","kind":"compatibility","summary":"Refreshes generated NAPI-RS binaries across supported target platforms; no performance claim is inferred from the artifact update.","evidence":"https://github.com/ruvnet/RuVector/commit/b336fbae8b15a5a487fc3e7c14a80dcb4984b04a"},
+ {"id":"ruvector-mincut-wasm-package-artifacts","project":"ruvector","revision":"07c7a4654be928cd7894f5c772a42108ad52eb97","committedAt":"2026-09-16T20:23:31Z","kind":"compatibility","summary":"Fixes publish-blocking MinCut crate version pins and adds generated Node and web WASM package artifacts.","evidence":"https://github.com/ruvnet/RuVector/commit/07c7a4654be928cd7894f5c772a42108ad52eb97"},
+ {"id":"ruvector-mincut-wasm-wrapper","project":"ruvector","revision":"b6921e79a0ad92b9caf3967075d35a6470a4c0d3","committedAt":"2026-09-16T20:23:09Z","kind":"spatial","summary":"Adds an optional MinCut WASM wrapper with exact TypeScript fallback plus dynamic cut and directed road-routing capabilities when the reviewed WASM package is available.","evidence":"https://github.com/ruvnet/RuVector/commit/b6921e79a0ad92b9caf3967075d35a6470a4c0d3"},
+ {"id":"ruvector-refuse-lossy-stub-writes","project":"ruvector","revision":"1e7c249753bd0f4ad6f4d0020d7af95767f0b7ba","committedAt":"2026-09-16T20:22:22Z","kind":"correctness","summary":"Stops treating RVF as a VectorDB-compatible backend and makes the last-resort stub refuse writes instead of returning identifiers for discarded data.","evidence":"https://github.com/ruvnet/RuVector/commit/1e7c249753bd0f4ad6f4d0020d7af95767f0b7ba"},
+ {"id":"ruflo-3-42-3-release","project":"ruflo","revision":"6f0ed7112873eedc7cfe17281a2585188190b790","committedAt":"2026-09-16T16:36:46Z","kind":"release","summary":"Ruflo 3.42.3 groups quote-aware hook parsing and Windows publish-path fixes verified upstream on a real Windows machine.","evidence":"https://github.com/ruvnet/ruflo/releases/tag/v3.42.3"},
+ {"id":"ruflo-windows-root-publish","project":"ruflo","revision":"6f0ed7112873eedc7cfe17281a2585188190b790","committedAt":"2026-09-16T16:36:46Z","kind":"compatibility","summary":"Spawns npm.cmd through the Windows shell in the root publish preparation path, matching the platform execution contract.","evidence":"https://github.com/ruvnet/ruflo/commit/6f0ed7112873eedc7cfe17281a2585188190b790"},
+ {"id":"ruflo-quote-aware-hook-override","project":"ruflo","revision":"cdc000fb418c1fedc6fa9b831c374342badc704e","committedAt":"2026-09-16T15:38:52Z","kind":"correctness","summary":"Uses quote-aware parsing for the test-only hook CLI override so Windows executable paths containing spaces remain one argument.","evidence":"https://github.com/ruvnet/ruflo/commit/cdc000fb418c1fedc6fa9b831c374342badc704e"},
+ {"id":"ruflo-policy-test-audit-isolation","project":"ruflo","revision":"5e634b396511420d254637b1af6d57290281d283","committedAt":"2026-09-16T14:45:11Z","kind":"evaluation","summary":"Uses UUID-scoped MCP policy audit paths to prevent parallel tests from colliding on the same timestamp-derived file.","evidence":"https://github.com/ruvnet/ruflo/commit/5e634b396511420d254637b1af6d57290281d283"},
{"id":"ruflo-learning-mode-shape","project":"ruflo","revision":"a65bdf683a73dcc1f20d455658daab1cca07306b","committedAt":"2026-09-16T04:22:58Z","kind":"learning","summary":"Passes the configured learning mode as the string expected by NeuralLearningSystem instead of an incompatible object shape.","evidence":"https://github.com/ruvnet/ruflo/commit/a65bdf683a73dcc1f20d455658daab1cca07306b"},
{"id":"ruvector-dependency-cve-fixes","project":"ruvector","revision":"3945d9f01a211a29c0db871c9ad037d637a4642d","committedAt":"2026-09-16T04:13:27Z","kind":"security","summary":"Updates locked Hono and fast-uri dependencies to versions identified upstream as CVE fixes.","evidence":"https://github.com/ruvnet/RuVector/commit/3945d9f01a211a29c0db871c9ad037d637a4642d"},
{"id":"ruvector-hnsw-stored-points","project":"ruvector","revision":"3d9cb89574d3c08f7a7d4dd653e854955afc19ed","committedAt":"2026-09-16T03:34:02Z","kind":"correctness","summary":"Fixes an HNSW search path that could silently omit stored points and adds recall, structural and issue-specific regression tests.","evidence":"https://github.com/ruvnet/RuVector/commit/3d9cb89574d3c08f7a7d4dd653e854955afc19ed"},
diff --git a/plugins/ruvnet/docs/INSTALL.md b/plugins/ruvnet/docs/INSTALL.md
index 0926774..5053539 100644
--- a/plugins/ruvnet/docs/INSTALL.md
+++ b/plugins/ruvnet/docs/INSTALL.md
@@ -67,11 +67,11 @@ Copy the returned `config.mcpServers.ruvnet-guide` object into a host that suppo
| --- | --- |
| `ruvnet_discover` | Search the dated catalog by exact keyword overlap. |
| `ruvnet_project` | Read a project, source links and its maturity boundary. |
-| `ruvnet_changes` | Page through the reviewed upstream snapshot with exact revisions, evidence links and freshness; optionally filter by the schema's exact `project` and `kind` enum values. |
+| `ruvnet_changes` | Page through one content-addressed upstream snapshot with exact revisions, evidence links and freshness; optionally filter by the schema's exact `project` and `kind` enum values. |
| `ruvnet_plan` | Return an advisory SPARC/MetaHarness plan, without executing it. |
| `ruvnet_connect` | Return connection guidance; it does not change configuration. |
-Resources: `ruv://catalog`, `ruv://changes`, `ruv://federation`. Prompt: `ruvnet-start` with a `goal` argument. The local process has no HTTP listener, network tools, shell execution or mutable memory. The changes resource returns the first unfiltered page. For more results, pass the returned opaque `nextCursor` to `ruvnet_changes` with the same `project` and `kind` filters, or run `changes [limit] [project] [kind] [cursor]`. A cursor is bound to its reviewed snapshot and filters; if it is rejected after a refresh, start again from the first page. Inspect `freshness.state` before relying on the data; `stale` begins at 72 hours and `clock-skew` means the observation appears to be in the future. An empty filtered result is not evidence that upstream has no matching change. A remote-only host cannot connect directly to local stdio.
+Resources: `ruv://catalog`, `ruv://changes`, `ruv://federation`. Prompt: `ruvnet-start` with a `goal` argument. The local process has no HTTP listener, network tools, shell execution or mutable memory. The changes resource returns the first unfiltered page. For more results, pass the returned opaque `nextCursor` and `snapshotId` to `ruvnet_changes` with the same filters, or run `changes [limit] [project] [kind] [cursor] [snapshot-id]`. The identifier covers the reviewed observation time, sources and ordered records. If its precondition is rejected after a refresh, discard cached pages and start again without the cursor or identifier. It checks consistency; it is not an authorization token or signature. Inspect `freshness.state` before relying on the data; `stale` begins at 72 hours and `clock-skew` means the observation appears to be in the future. An empty filtered result is not evidence that upstream has no matching change. A remote-only host cannot connect directly to local stdio.
## Codex repository marketplace
diff --git a/plugins/ruvnet/lib/core.mjs b/plugins/ruvnet/lib/core.mjs
index 60821d9..f92ae92 100644
--- a/plugins/ruvnet/lib/core.mjs
+++ b/plugins/ruvnet/lib/core.mjs
@@ -2,13 +2,33 @@ import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { createHash } from 'node:crypto';
-export const VERSION = '0.4.0';
+export const VERSION = '0.5.0';
export const FRESHNESS_MAX_AGE_HOURS = 72;
export const CATALOG = JSON.parse(readFileSync(new URL('../data/catalog.json', import.meta.url), 'utf8'));
export const UPSTREAM = JSON.parse(readFileSync(new URL('../data/upstream.json', import.meta.url), 'utf8'));
export const HOSTS = ['chatgpt', 'claude', 'claude-code', 'lovable', 'codex', 'stdio'];
export const CHANGE_PROJECTS = UPSTREAM.sources.map(source => source.id);
export const CHANGE_KINDS = [...new Set(UPSTREAM.changes.map(change => change.kind))].sort();
+function canonical(value, seen = new WeakSet()) {
+ if (value === null || typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value);
+ if (typeof value === 'number') {
+ if (!Number.isFinite(value)) throw new Error('snapshot evidence must contain finite JSON values');
+ return JSON.stringify(value);
+ }
+ if (!value || typeof value !== 'object' || seen.has(value)) throw new Error('snapshot evidence must be acyclic JSON data');
+ seen.add(value);
+ const result = Array.isArray(value)
+ ? `[${value.map(item => canonical(item, seen)).join(',')}]`
+ : `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key], seen)}`).join(',')}}`;
+ seen.delete(value);
+ return result;
+}
+export function snapshotIdentity(upstream = UPSTREAM) {
+ if (!upstream || typeof upstream !== 'object' || !Array.isArray(upstream.sources) || !Array.isArray(upstream.changes)) throw new Error('snapshot evidence must contain sources and changes arrays');
+ const evidence = { schemaVersion: upstream.schemaVersion, observedAt: upstream.observedAt, sources: upstream.sources, changes: upstream.changes };
+ return `sha256:${createHash('sha256').update(canonical(evidence)).digest('hex')}`;
+}
+export const SNAPSHOT_ID = snapshotIdentity();
const words = value => value.toLowerCase().match(/[a-z0-9]+/g) || [];
const index = new Map();
for (const project of CATALOG.projects) {
@@ -55,7 +75,7 @@ export function snapshotFreshness(observedAt, now = Date.now()) {
};
}
function cursorFingerprint(filters, offset) {
- return createHash('sha256').update(JSON.stringify({ version: 1, observedAt: UPSTREAM.observedAt, filters, offset })).digest('base64url').slice(0, 16);
+ return createHash('sha256').update(JSON.stringify({ version: 1, snapshotId: SNAPSHOT_ID, filters, offset })).digest('base64url').slice(0, 16);
}
function encodeCursor(filters, offset) {
return `v1.${cursorFingerprint(filters, offset)}.${offset.toString(36)}`;
@@ -71,7 +91,7 @@ function decodeCursor(cursor, filters, total) {
}
return offset;
}
-export function changes(limit = 10, now = Date.now(), filters = {}, cursor) {
+export function changes(limit = 10, now = Date.now(), filters = {}, cursor, expectedSnapshot) {
if (!Number.isInteger(limit) || limit < 1 || limit > 20) throw new Error('limit must be an integer from 1 to 20');
if (!filters || typeof filters !== 'object' || Array.isArray(filters) || Object.keys(filters).some(key => !['project', 'kind'].includes(key))) {
throw new Error('filters must be an object containing only project and kind');
@@ -85,12 +105,18 @@ export function changes(limit = 10, now = Date.now(), filters = {}, cursor) {
applied.kind = text(filters.kind, 'kind', 64);
if (!CHANGE_KINDS.includes(applied.kind)) throw new Error(`kind must be one of ${CHANGE_KINDS.join(', ')}`);
}
+ if (expectedSnapshot !== undefined) {
+ const checked = text(expectedSnapshot, 'snapshotId', 71);
+ if (!/^sha256:[a-f0-9]{64}$/.test(checked)) throw new Error('snapshotId must be a sha256 content identifier');
+ if (checked !== SNAPSHOT_ID) throw new Error('snapshot changed; restart without cursor or snapshotId');
+ }
const freshness = snapshotFreshness(UPSTREAM.observedAt, now);
const matches = UPSTREAM.changes.filter(change =>
(!applied.project || change.project === applied.project) && (!applied.kind || change.kind === applied.kind));
const offset = decodeCursor(cursor, applied, matches.length);
const nextOffset = offset + limit;
return {
+ snapshotId: SNAPSHOT_ID,
observedAt: UPSTREAM.observedAt,
freshness,
sourceCount: UPSTREAM.sources.length,
diff --git a/plugins/ruvnet/lib/mcp.mjs b/plugins/ruvnet/lib/mcp.mjs
index 76c2f26..224a0f8 100644
--- a/plugins/ruvnet/lib/mcp.mjs
+++ b/plugins/ruvnet/lib/mcp.mjs
@@ -8,7 +8,7 @@ const string = { type: 'string', minLength: 1, maxLength: 2000 };
export const TOOLS = [
{ name: 'ruvnet_discover', description: 'Find RuV Stack projects by exact keyword overlap. Read-only, offline, source-linked catalog; no live capability claims.', inputSchema: schema({ query: { type: 'string', maxLength: 2000 }, limit: { type: 'integer', minimum: 1, maximum: 10 } }) },
{ name: 'ruvnet_project', description: 'Read a known project’s purpose, source links and maturity boundary.', inputSchema: { ...schema({ id: string }), required: ['id'] } },
- { name: 'ruvnet_changes', description: 'Read and optionally filter the reviewed upstream change snapshot by project or kind. Follow nextCursor to continue the same snapshot and filters. Returns exact revisions, evidence links and bounded freshness state; this is not a live feed.', inputSchema: schema({ limit: { type: 'integer', minimum: 1, maximum: 20 }, project: { type: 'string', enum: CHANGE_PROJECTS }, kind: { type: 'string', enum: CHANGE_KINDS }, cursor: { type: 'string', minLength: 1, maxLength: 96, pattern: '^v1\\.[A-Za-z0-9_-]{16}\\.[0-9a-z]+$' } }) },
+ { name: 'ruvnet_changes', description: 'Read and optionally filter the reviewed upstream change snapshot by project or kind. Follow nextCursor with the returned snapshotId; a changed snapshot fails closed so hosts can restart without mixing evidence.', inputSchema: schema({ limit: { type: 'integer', minimum: 1, maximum: 20 }, project: { type: 'string', enum: CHANGE_PROJECTS }, kind: { type: 'string', enum: CHANGE_KINDS }, cursor: { type: 'string', minLength: 1, maxLength: 96, pattern: '^v1\\.[A-Za-z0-9_-]{16}\\.[0-9a-z]+$' }, snapshotId: { type: 'string', minLength: 71, maxLength: 71, pattern: '^sha256:[a-f0-9]{64}$' } }) },
{ name: 'ruvnet_plan', description: 'Return an advisory SPARC/MetaHarness integration plan. Does not execute, install, access repositories or publish.', inputSchema: { ...schema({ goal: string }), required: ['goal'] } },
{ name: 'ruvnet_connect', description: 'Get installation and connection guidance for a supported host. No configuration is changed.', inputSchema: { ...schema({ host: { type: 'string', enum: HOSTS } }), required: ['host'] } }
].map(t => ({ ...t, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } }));
@@ -21,7 +21,7 @@ export function dispatch(name, args = {}) {
argsOnly(args, Object.keys(tool.inputSchema.properties));
if (name === 'ruvnet_discover') return discover(args.query, args.limit);
if (name === 'ruvnet_project') return project(args.id);
- if (name === 'ruvnet_changes') return changes(args.limit, Date.now(), { ...(args.project === undefined ? {} : { project: args.project }), ...(args.kind === undefined ? {} : { kind: args.kind }) }, args.cursor);
+ if (name === 'ruvnet_changes') return changes(args.limit, Date.now(), { ...(args.project === undefined ? {} : { project: args.project }), ...(args.kind === undefined ? {} : { kind: args.kind }) }, args.cursor, args.snapshotId);
if (name === 'ruvnet_plan') return plan(args.goal);
return connect(args.host);
}
diff --git a/plugins/ruvnet/package-lock.json b/plugins/ruvnet/package-lock.json
index 1824161..b6590f9 100644
--- a/plugins/ruvnet/package-lock.json
+++ b/plugins/ruvnet/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@ruvnet/entrypoint",
- "version": "0.4.0",
+ "version": "0.5.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@ruvnet/entrypoint",
- "version": "0.4.0",
+ "version": "0.5.0",
"dependencies": {
"@modelcontextprotocol/sdk": "1.30.0"
},
diff --git a/plugins/ruvnet/package.json b/plugins/ruvnet/package.json
index 79b7239..e36094d 100644
--- a/plugins/ruvnet/package.json
+++ b/plugins/ruvnet/package.json
@@ -1,6 +1,6 @@
{
"name": "@ruvnet/entrypoint",
- "version": "0.4.0",
+ "version": "0.5.0",
"private": true,
"description": "Read-only RuV Stack discovery, integration plans, CLI and MCP",
"type": "module",
diff --git a/plugins/ruvnet/skills/ruvnet-start/SKILL.md b/plugins/ruvnet/skills/ruvnet-start/SKILL.md
index 88fb31f..534bfb3 100644
--- a/plugins/ruvnet/skills/ruvnet-start/SKILL.md
+++ b/plugins/ruvnet/skills/ruvnet-start/SKILL.md
@@ -8,7 +8,7 @@ description: Discover and integrate RuV Stack projects when the user asks where
Use the user's goal and target environment to choose the smallest useful stack.
Read [the catalog](../../data/catalog.json), or call `ruvnet_discover` if the local companion is connected. The catalog is curated, dated, and lexical, not a live semantic index. An empty search is not evidence that no project exists.
-Before using upstream-change guidance, call `ruvnet_changes` and inspect `freshness.state`. Use its exact `project` and `kind` filters when the full snapshot is unnecessary. Follow `nextCursor` with the same filters until it is absent; treat the cursor as opaque and start over if it is rejected because the reviewed snapshot changed. Refresh provenance rather than relying on a `stale` or `clock-skew` snapshot; an empty filtered result means no reviewed match, not that upstream has no matching change.
+Before using upstream-change guidance, call `ruvnet_changes` and inspect `freshness.state`. Use its exact `project` and `kind` filters when the full snapshot is unnecessary. Follow `nextCursor` with the same filters and returned `snapshotId` until the cursor is absent. Treat both as opaque; if the snapshot precondition is rejected, discard cached pages and restart without either value. Refresh provenance rather than relying on a `stale` or `clock-skew` snapshot; an empty filtered result means no reviewed match, not that upstream has no matching change.
Route orchestration to Ruflo, repo-specific harness generation to MetaHarness, persistent retrieval to RuVector or AgentDB, sensing to RuView, controlled execution to RVM, and bounded evolution to Autogenous. Read the selected repository's current guidance before using its APIs. Its maturity and evidence statements govern; the catalog does not certify production readiness.
diff --git a/plugins/ruvnet/test/core.test.mjs b/plugins/ruvnet/test/core.test.mjs
index ebc8f2a..f09b073 100644
--- a/plugins/ruvnet/test/core.test.mjs
+++ b/plugins/ruvnet/test/core.test.mjs
@@ -1,6 +1,6 @@
import test from 'node:test';
import assert from 'node:assert/strict';
-import {discover,project,changes,snapshotFreshness,plan,connect,HOSTS,CHANGE_PROJECTS,CHANGE_KINDS} from '../lib/core.mjs';
+import {discover,project,changes,snapshotFreshness,snapshotIdentity,SNAPSHOT_ID,UPSTREAM,plan,connect,HOSTS,CHANGE_PROJECTS,CHANGE_KINDS} from '../lib/core.mjs';
import {dispatch} from '../lib/mcp.mjs';
test('routing and unknown queries',()=>{
for(const [q,id] of [['swarm federation','ruflo'],['wifi csi','ruview'],['vector hnsw','ruvector'],['harness scaffold','metaharness'],['sandbox capabilities','rvm'],['latent alignment','latentmesh']])assert.equal(discover(q).matches[0].id,id);
@@ -14,6 +14,7 @@ test('untrusted input boundaries',()=>{
for(const limit of [0,21,1.2,'2',null])assert.throws(()=>changes(limit));
for(const filters of [null,[],{execute:true},{project:'unknown'},{kind:'unknown'},{project:'ruflo\n'}])assert.throws(()=>changes(1,Date.now(),filters));
for(const cursor of ['',42,'v1.bad.1','v1.AAAAAAAAAAAAAAAA.0','v1.AAAAAAAAAAAAAAAA.1','x'.repeat(97)])assert.throws(()=>changes(1,Date.now(),{},cursor));
+ for(const snapshot of ['',42,'sha256:bad',`sha256:${'A'.repeat(64)}`,`sha256:${'0'.repeat(64)}`])assert.throws(()=>changes(1,Date.now(),{},undefined,snapshot));
assert.throws(()=>plan(''));assert.throws(()=>dispatch('ruvnet_discover',{execute:true}));assert.throws(()=>dispatch('ruvnet_discover',[]));assert.throws(()=>dispatch('shell',{}));assert.throws(()=>connect('http://127.0.0.1'));
});
test('hostile goal remains data and cannot alter fixed command templates',()=>{
@@ -24,25 +25,32 @@ test('all supported hosts and dispatch paths',()=>{
for(const h of HOSTS){const c=connect(h);assert.equal(c.remoteMcp,h==='chatgpt'?'https://x.ruv.io/chatgpt/mcp':'https://x.ruv.io/mcp');assert.ok(!JSON.stringify(c).includes('Authorization:'));}
const c=connect('stdio').config.mcpServers['ruvnet-guide'];assert.ok(c.args[0].endsWith('/bin/ruvnet.mjs'));assert.equal(c.args[1],'mcp');
const ruflo=dispatch('ruvnet_project',{id:'ruflo'});assert.equal(ruflo.id,'ruflo');assert.match(ruflo.upstream.revision,/^[0-9a-f]{40}$/);
- const feed=dispatch('ruvnet_changes',{limit:2});assert.equal(feed.changes.length,2);assert.match(feed.note,/not a live feed/);assert.equal(feed.freshness.state,'current');
+ const feed=dispatch('ruvnet_changes',{limit:2});assert.equal(feed.changes.length,2);assert.match(feed.note,/not a live feed/);assert.equal(feed.freshness.state,'current');assert.equal(feed.snapshotId,SNAPSHOT_ID);
const security=dispatch('ruvnet_changes',{limit:2,project:'ruflo',kind:'security'});assert.deepEqual(security.filters,{project:'ruflo',kind:'security'});assert.equal(security.changes.length,2);assert.ok(security.changes.every(change=>change.project==='ruflo'&&change.kind==='security'));
- const securityNext=dispatch('ruvnet_changes',{limit:2,project:'ruflo',kind:'security',cursor:security.nextCursor});assert.equal(securityNext.offset,2);assert.ok(securityNext.changes.every(change=>change.project==='ruflo'&&change.kind==='security'));assert.equal(new Set([...security.changes,...securityNext.changes].map(change=>change.revision)).size,4);
+ const securityNext=dispatch('ruvnet_changes',{limit:2,project:'ruflo',kind:'security',cursor:security.nextCursor,snapshotId:security.snapshotId});assert.equal(securityNext.offset,2);assert.ok(securityNext.changes.every(change=>change.project==='ruflo'&&change.kind==='security'));assert.equal(new Set([...security.changes,...securityNext.changes].map(change=>change.id)).size,4);
assert.ok(CHANGE_PROJECTS.includes('ruflo'));assert.ok(CHANGE_KINDS.includes('security'));
assert.equal(dispatch('ruvnet_connect',{host:'lovable'}).host,'lovable');assert.equal(dispatch('ruvnet_plan',{goal:'harness'}).executed,false);assert.ok(dispatch('ruvnet_discover').matches.length);
});
test('change filters are exact, intersected and counted before limiting',()=>{
const byProject=changes(2,Date.now(),{project:'ruflo'});assert.equal(byProject.changes.length,2);assert.ok(byProject.totalMatches>2);assert.ok(byProject.changes.every(change=>change.project==='ruflo'));assert.match(byProject.nextCursor,/^v1\.[A-Za-z0-9_-]{16}\.[0-9a-z]+$/);
- const continued=changes(2,Date.now(),{project:'ruflo'},byProject.nextCursor);assert.equal(continued.offset,2);assert.equal(new Set([...byProject.changes,...continued.changes].map(change=>change.revision)).size,4);
+ const continued=changes(2,Date.now(),{project:'ruflo'},byProject.nextCursor);assert.equal(continued.offset,2);assert.equal(new Set([...byProject.changes,...continued.changes].map(change=>change.id)).size,4);
assert.throws(()=>changes(2,Date.now(),{kind:'security'},byProject.nextCursor));
const byKind=changes(20,Date.now(),{kind:'memory'});assert.ok(byKind.changes.length>=3);assert.ok(byKind.changes.every(change=>change.kind==='memory'));
const combined=changes(20,Date.now(),{project:'ruflo',kind:'memory'});assert.deepEqual(combined.filters,{project:'ruflo',kind:'memory'});assert.ok(combined.changes.length>=3);assert.ok(combined.changes.every(change=>change.project==='ruflo'&&change.kind==='memory'));
assert.deepEqual(changes(1).filters,{});
});
+test('snapshot identity is canonical and usable as a precondition',()=>{
+ assert.match(SNAPSHOT_ID,/^sha256:[a-f0-9]{64}$/);assert.equal(snapshotIdentity(),SNAPSHOT_ID);assert.equal(changes(1,Date.now(),{},undefined,SNAPSHOT_ID).snapshotId,SNAPSHOT_ID);
+ const reordered=JSON.parse(JSON.stringify(UPSTREAM),(key,value)=>value);assert.equal(snapshotIdentity(reordered),SNAPSHOT_ID);
+ const changed=structuredClone(UPSTREAM);changed.changes[0].summary+=' changed';assert.notEqual(snapshotIdentity(changed),SNAPSHOT_ID);
+ const cyclic=structuredClone(UPSTREAM);cyclic.changes[0].self=cyclic.changes[0];
+ assert.throws(()=>snapshotIdentity({}));assert.throws(()=>snapshotIdentity(cyclic));assert.throws(()=>changes(1,Date.now(),{},undefined,`sha256:${'0'.repeat(64)}`),/snapshot changed/);
+});
test('snapshot freshness is bounded and fails closed',()=>{
assert.deepEqual(snapshotFreshness('2026-09-12T00:00:00Z',Date.parse('2026-09-14T23:59:59Z')), {state:'current',ageHours:71.99,maxAgeHours:72,expiresAt:'2026-09-15T00:00:00.000Z'});
assert.equal(snapshotFreshness('2026-09-12T00:00:00Z',Date.parse('2026-09-15T00:00:00Z')).state,'stale');
assert.equal(snapshotFreshness('2026-09-15T00:00:00Z',Date.parse('2026-09-14T00:00:00Z')).state,'clock-skew');
- assert.match(changes(1,Date.parse('2026-09-20T00:00:00Z')).note,/Warning:.*stale/);
+ assert.match(changes(1,Date.parse(UPSTREAM.observedAt)+73*3600000).note,/Warning:.*stale/);
for(const observedAt of ['not-a-time','2026-09-12',null])assert.throws(()=>snapshotFreshness(observedAt,0));
for(const now of [NaN,Infinity,'2026-09-14T00:00:00Z',null])assert.throws(()=>snapshotFreshness('2026-09-12T00:00:00Z',now));
});
diff --git a/plugins/ruvnet/test/mcp.test.mjs b/plugins/ruvnet/test/mcp.test.mjs
index 9710800..d7f54b3 100644
--- a/plugins/ruvnet/test/mcp.test.mjs
+++ b/plugins/ruvnet/test/mcp.test.mjs
@@ -8,11 +8,11 @@ import {fileURLToPath} from 'node:url';
import {spawnSync} from 'node:child_process';
const bin=fileURLToPath(new URL('../bin/ruvnet.mjs',import.meta.url));
async function exercise(c){
- const t=await c.listTools();assert.equal(t.tools.length,5);assert.ok(t.tools.every(x=>x.annotations.readOnlyHint&&x.annotations.destructiveHint===false));const changesTool=t.tools.find(x=>x.name==='ruvnet_changes');assert.ok(changesTool.inputSchema.properties.cursor);assert.equal(changesTool.inputSchema.properties.cursor.maxLength,96);
+ const t=await c.listTools();assert.equal(t.tools.length,5);assert.ok(t.tools.every(x=>x.annotations.readOnlyHint&&x.annotations.destructiveHint===false));const changesTool=t.tools.find(x=>x.name==='ruvnet_changes');assert.ok(changesTool.inputSchema.properties.cursor);assert.equal(changesTool.inputSchema.properties.cursor.maxLength,96);assert.equal(changesTool.inputSchema.properties.snapshotId.maxLength,71);
for(const [name,args] of [['ruvnet_discover',{query:'wifi'}],['ruvnet_project',{id:'ruflo'}],['ruvnet_changes',{limit:2}],['ruvnet_changes',{limit:2,project:'ruflo',kind:'security'}],['ruvnet_plan',{goal:'build harness'}],['ruvnet_connect',{host:'chatgpt'}]]){const r=await c.callTool({name,arguments:args});assert.ok(!r.isError);assert.doesNotThrow(()=>JSON.parse(r.content[0].text));}
const chatgpt=await c.callTool({name:'ruvnet_connect',arguments:{host:'chatgpt'}});assert.equal(JSON.parse(chatgpt.content[0].text).remoteMcp,'https://x.ruv.io/chatgpt/mcp');
- const first=JSON.parse((await c.callTool({name:'ruvnet_changes',arguments:{limit:2,project:'ruflo',kind:'security'}})).content[0].text);const second=JSON.parse((await c.callTool({name:'ruvnet_changes',arguments:{limit:2,project:'ruflo',kind:'security',cursor:first.nextCursor}})).content[0].text);assert.equal(second.offset,2);assert.equal(new Set([...first.changes,...second.changes].map(change=>change.revision)).size,4);
- for(const [name,args] of [['ruvnet_project',{id:'../../etc/passwd'}],['ruvnet_changes',{limit:21}],['ruvnet_changes',{project:'unknown'}],['ruvnet_changes',{kind:'unknown'}],['ruvnet_changes',{limit:2,cursor:first.nextCursor}],['ruvnet_changes',{cursor:'v1.AAAAAAAAAAAAAAAA.1'}],['ruvnet_connect',{host:'evil'}],['ruvnet_plan',{}],['ruvnet_discover',{execute:true}],['publish',{}]])assert.equal((await c.callTool({name,arguments:args})).isError,true);
+ const first=JSON.parse((await c.callTool({name:'ruvnet_changes',arguments:{limit:2,project:'ruflo',kind:'security'}})).content[0].text);const second=JSON.parse((await c.callTool({name:'ruvnet_changes',arguments:{limit:2,project:'ruflo',kind:'security',cursor:first.nextCursor,snapshotId:first.snapshotId}})).content[0].text);assert.equal(second.offset,2);assert.equal(second.snapshotId,first.snapshotId);assert.equal(new Set([...first.changes,...second.changes].map(change=>change.id)).size,4);
+ for(const [name,args] of [['ruvnet_project',{id:'../../etc/passwd'}],['ruvnet_changes',{limit:21}],['ruvnet_changes',{project:'unknown'}],['ruvnet_changes',{kind:'unknown'}],['ruvnet_changes',{limit:2,cursor:first.nextCursor}],['ruvnet_changes',{cursor:'v1.AAAAAAAAAAAAAAAA.1'}],['ruvnet_changes',{snapshotId:`sha256:${'0'.repeat(64)}`}],['ruvnet_connect',{host:'evil'}],['ruvnet_plan',{}],['ruvnet_discover',{execute:true}],['publish',{}]])assert.equal((await c.callTool({name,arguments:args})).isError,true);
const rs=await c.listResources();assert.equal(rs.resources.length,3);for(const r of rs.resources){const read=await c.readResource({uri:r.uri});assert.ok(read.contents.length);if(r.uri==='ruv://changes'){const value=JSON.parse(read.contents[0].text);assert.ok(['current','stale','clock-skew'].includes(value.freshness.state));assert.match(value.freshness.expiresAt,/Z$/);}}
await assert.rejects(c.readResource({uri:'file:///etc/passwd'}));assert.equal((await c.listPrompts()).prompts[0].name,'ruvnet-start');assert.equal((await c.getPrompt({name:'ruvnet-start',arguments:{goal:'memory'}})).messages[0].role,'user');await assert.rejects(c.getPrompt({name:'other',arguments:{goal:'memory'}}));await assert.rejects(c.getPrompt({name:'ruvnet-start'}));await c.ping();
}
@@ -26,5 +26,5 @@ test('oversized stdin fails before SDK buffering',()=>{const r=spawnSync(process
test('CLI success and invalid-command exit codes',()=>{
for(const args of [[],['--help'],['--version'],['catalog','memory'],['project','ruflo'],['changes'],['changes','2'],['changes','2','ruflo','security'],['plan','harness'],['connect','stdio']]){const r=spawnSync(process.execPath,[bin,...args],{encoding:'utf8',timeout:5000});assert.equal(r.status,0);assert.equal(r.stderr,'');assert.ok(r.stdout);}
for(const args of [['nonsense'],['mcp','extra'],['project'],['changes','21'],['changes','2','unknown'],['changes','2','ruflo','unknown'],['changes','2','ruflo','security','extra'],['connect','evil'],['plan']]){const r=spawnSync(process.execPath,[bin,...args],{encoding:'utf8',timeout:5000});assert.equal(r.status,1);assert.equal(r.stdout,'');assert.ok(r.stderr);}
- const first=spawnSync(process.execPath,[bin,'changes','2','ruflo','security'],{encoding:'utf8',timeout:5000});const page=JSON.parse(first.stdout);const next=spawnSync(process.execPath,[bin,'changes','2','ruflo','security',page.nextCursor],{encoding:'utf8',timeout:5000});assert.equal(next.status,0);assert.equal(JSON.parse(next.stdout).offset,2);
+ const first=spawnSync(process.execPath,[bin,'changes','2','ruflo','security'],{encoding:'utf8',timeout:5000});const page=JSON.parse(first.stdout);const next=spawnSync(process.execPath,[bin,'changes','2','ruflo','security',page.nextCursor,page.snapshotId],{encoding:'utf8',timeout:5000});assert.equal(next.status,0);assert.equal(JSON.parse(next.stdout).offset,2);const stale=spawnSync(process.execPath,[bin,'changes','2','ruflo','security',page.nextCursor,`sha256:${'0'.repeat(64)}`],{encoding:'utf8',timeout:5000});assert.equal(stale.status,1);
});