Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
dcab21f
feat: add bounded WSP swarm toolkit and constellation tooling
Nov 11, 2026
a1f65d8
fix(huggingface): enforce deadlines for stalled transports and streams
ruvnet Nov 11, 2026
49327eb
test(toolkit): select SQL.js explicitly for buffered persistence probes
ruvnet Nov 11, 2026
0495d6f
feat(core): expose validated weight toolkit through explicit subpaths
ruvnet Nov 11, 2026
dc4d091
test(toolkit): isolate declaration checks from ancestor ambient types
ruvnet Nov 11, 2026
56ec9f5
fix(wsp): preserve loop authority and contain invalid callbacks
ruvnet Nov 11, 2026
b5faf4c
docs(core): illustrate the validated weight programming workflow
ruvnet Nov 11, 2026
2be509d
docs(core): explain toolkit capabilities, environments and safe weigh…
ruvnet Nov 11, 2026
fd7943c
ci: seal and publish thirteen exact toolkit and core archives
ruvnet Nov 11, 2026
64c3c41
fix(release): bind publication package identities and reject unsealed…
ruvnet Nov 11, 2026
2751aeb
ci: route core 0.2 qualification through the toolkit artifact lane
ruvnet Nov 11, 2026
48c9ae1
docs(wsp): prepare discoverable package metadata and release catalog
ruvnet Nov 11, 2026
e3b1b77
test(release): verify complete toolkit scenarios after fresh public i…
ruvnet Nov 11, 2026
6988b37
fix(release): prove packed payload matches tracked source and recover…
ruvnet Nov 11, 2026
bf9139e
test(release): reproduce ignored JavaScript inclusion without changin…
ruvnet Nov 11, 2026
b4d85e7
docs: illustrate bounded proposal gates and revision authority
ruvnet Nov 11, 2026
e573ed7
docs: explain toolkit packages, evaluation boundaries and protected r…
ruvnet Nov 11, 2026
fd64519
docs: pin animated diagrams and validate npm-friendly package crosslinks
ruvnet Nov 11, 2026
52b1fb6
ci: retire automatic legacy pair qualification and route current core…
ruvnet Nov 11, 2026
1bd72c0
docs(release): distinguish current toolkit CI from the frozen npm pair
ruvnet Nov 11, 2026
75e12b7
Merge remote-tracking branch 'origin/main' into review/pr218-toolkit
ruvnet Nov 11, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,13 @@ env:
RUST_BACKTRACE: 1

jobs:
# Current npm generation: core 0.2.0 plus twelve exact toolkit satellites.
# The former npm-modules.yml pair lane is manual/reusable for 0.1.2 refs only.
npm-toolkit:
uses: ./.github/workflows/wsp-toolkit.yml
with:
expected_sha: ${{ github.event.pull_request.head.sha || github.sha }}

wasm-targets:
uses: ./.github/workflows/wasm-build.yml

Expand Down
40 changes: 40 additions & 0 deletions .github/workflows/constellation-observatory.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
name: Constellation observatory

on:
workflow_dispatch:
inputs:
end:
description: Last complete UTC day (YYYY-MM-DD); blank uses yesterday
required: false
type: string

permissions:
contents: read

jobs:
report:
runs-on: ubuntu-24.04
timeout-minutes: 10
defaults:
run:
working-directory: packages/wsp-toolkit
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24.22.1'
package-manager-cache: false
- name: Install locked runtime packages without lifecycle scripts
run: npm ci --omit=dev --ignore-scripts --no-audit --no-fund
- name: Build public-only report without project adoption data
env:
CONSTELLATION_REPORT_END: ${{ inputs.end || '' }}
run: node scripts/constellation-report.mjs --output "$RUNNER_TEMP/constellation"
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: constellation-${{ github.sha }}-${{ github.run_id }}
path: ${{ runner.temp }}/constellation/
if-no-files-found: error
retention-days: 30
21 changes: 12 additions & 9 deletions .github/workflows/npm-modules.yml
Original file line number Diff line number Diff line change
@@ -1,20 +1,14 @@
name: npm modules

# Frozen publication contract for the ruv-fann-wasm/ruv-fann 0.1.2 pair.
# Invoke manually/reusably at a legacy source ref only. Current core and
# satellite qualification lives in wsp-toolkit.yml and is called by CI.
on:
workflow_call:
inputs:
release_tag:
required: false
type: string
pull_request:
branches: [main]
paths:
- 'packages/wasm/**'
- 'packages/core/**'
- 'scripts/npm-modules-*.mjs'
- 'scripts/npm-release-*.mjs'
- '.github/workflows/npm-modules.yml'
- '.github/workflows/protected-npm-modules.yml'
workflow_dispatch:

permissions:
Expand All @@ -30,6 +24,15 @@ jobs:
with:
persist-credentials: false
ref: ${{ github.event.pull_request.head.sha || github.sha }}
- name: Require the frozen legacy package generation
run: |
node --input-type=module <<'JS'
import {readFileSync} from 'node:fs';
const core=JSON.parse(readFileSync('packages/core/package.json','utf8'));
const wasm=JSON.parse(readFileSync('packages/wasm/package.json','utf8'));
if(core.version!=='0.1.2'||wasm.version!=='0.1.2'||core.dependencies?.['ruv-fann-wasm']!=='0.1.2')
throw Error('This manual legacy lane qualifies only the frozen core/WASM 0.1.2 pair; use wsp-toolkit.yml for core 0.2.0 and its satellites.');
JS
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '22.13.0'
Expand Down
85 changes: 85 additions & 0 deletions .github/workflows/protected-toolkit-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
name: protected-toolkit-release

on:
workflow_dispatch:
inputs:
expected_sha:
description: Exact qualified current main commit to publish
required: true
type: string

permissions:
contents: read
issues: read
actions: read

concurrency:
group: protected-toolkit-release
cancel-in-progress: false

jobs:
publish:
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-24.04
timeout-minutes: 60
permissions:
contents: write
issues: read
actions: read
id-token: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ inputs.expected_sha }}
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24.22.1'
registry-url: https://registry.npmjs.org
package-manager-cache: false
- name: Require exact current main and zero release blockers
env:
EXPECTED_SHA: ${{ inputs.expected_sha }}
GH_TOKEN: ${{ github.token }}
run: |
test "$GITHUB_REF" = refs/heads/main
test "$GITHUB_SHA" = "$EXPECTED_SHA"
test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
test "$(gh api repos/${GITHUB_REPOSITORY}/commits/main --jq .sha)" = "$EXPECTED_SHA"
test "$(gh api "repos/${GITHUB_REPOSITORY}/issues?labels=release-blocker&state=open&per_page=1" --jq length)" = 0
- name: Download and fully verify the successful exact-source qualification artifact
env:
GH_TOKEN: ${{ github.token }}
run: node scripts/toolkit-candidate-download.mjs --expected-sha "${{ inputs.expected_sha }}" --output "$RUNNER_TEMP/toolkit-candidate"
- name: Publish only sealed archives in dependency order with provenance
env:
GH_TOKEN: ${{ github.token }}
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
run: node scripts/toolkit-release-lane.mjs publish --directory "$RUNNER_TEMP/toolkit-candidate" --output "$RUNNER_TEMP/toolkit-publication"
- name: Install public-consumer tooling without executing lifecycle scripts
env:
NODE_AUTH_TOKEN: ''
run: |
npm ci --prefix packages/wsp-toolkit --ignore-scripts --no-audit --no-fund
npm run --prefix packages/wsp-toolkit setup:agentdb
packages/wsp-toolkit/node_modules/.bin/playwright install --with-deps chromium
- name: Require fresh-cache public bytes, sealed dependency lock, strict types and real Chromium/WASM consumer
env:
NODE_AUTH_TOKEN: ''
NPM_TOKEN: ''
run: node scripts/toolkit-release-lane.mjs public-consumer --directory "$RUNNER_TEMP/toolkit-candidate" --publication "$RUNNER_TEMP/toolkit-publication/publication.json" --output "$RUNNER_TEMP/toolkit-public-consumer.json"
- name: Create and download-verify the exact-source GitHub release and all sealed assets
env:
GH_TOKEN: ${{ github.token }}
run: node scripts/toolkit-release-lane.mjs github-release --directory "$RUNNER_TEMP/toolkit-candidate" --publication "$RUNNER_TEMP/toolkit-publication/publication.json" --public-consumer "$RUNNER_TEMP/toolkit-public-consumer.json" --output "$RUNNER_TEMP/toolkit-release-receipt.json"
- if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: toolkit-publication-${{ inputs.expected_sha }}
path: |
${{ runner.temp }}/toolkit-candidate/
${{ runner.temp }}/toolkit-publication/
${{ runner.temp }}/toolkit-public-consumer.json
${{ runner.temp }}/toolkit-release-receipt.json
if-no-files-found: error
retention-days: 90
3 changes: 3 additions & 0 deletions .github/workflows/wsp-modules.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ on:
paths:
- 'packages/wsp/**'
- 'scripts/wsp-*.mjs'
- 'scripts/constellation-oidc*.mjs'
- 'scripts/wsp-benchmark-tree.py'
- '.github/workflows/wsp-modules.yml'
- '.github/workflows/protected-wsp-release.yml'
Expand Down Expand Up @@ -50,6 +51,8 @@ jobs:
run: |
python -m venv "$RUNNER_TEMP/wsp-benchmark-python"
"$RUNNER_TEMP/wsp-benchmark-python/bin/python" -m pip install --require-hashes --only-binary=:all: -r packages/wsp/benchmarks/requirements.lock
- name: Validate tokenless publication context and existing release evidence guards
run: node --test scripts/constellation-oidc.test.mjs scripts/wsp-release-evidence.test.mjs
- name: Run source tests and require zero skips or todos on Node 22
run: node scripts/wsp-release-lane.mjs unit --output "$RUNNER_TEMP/wsp-receipts/node-22-unit.json"
- name: Pack candidate exactly once
Expand Down
91 changes: 91 additions & 0 deletions .github/workflows/wsp-toolkit.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
name: WSP toolkit qualification

on:
workflow_call:
inputs:
expected_sha:
description: Exact reviewed source requested by the caller
required: true
type: string
pull_request:
branches: [main]
paths:
- 'packages/wsp-toolkit/**'
- 'packages/core/**'
- 'scripts/toolkit-*.mjs'
- 'scripts/constellation-oidc*.mjs'
- 'scripts/wsp-release-lane.mjs'
- '.github/workflows/protected-wsp-release.yml'
- '.github/workflows/protected-toolkit-release.yml'
- '.github/workflows/constellation-observatory.yml'
- '.github/workflows/wsp-toolkit.yml'
- '.github/workflows/ci.yml'
- '.github/workflows/npm-modules.yml'
- '.github/workflows/protected-npm-modules.yml'
- 'scripts/npm-release-*.mjs'
- 'scripts/npm-modules-*.mjs'
workflow_dispatch:
inputs:
expected_sha:
description: Exact reviewed commit to qualify
required: true
type: string

permissions:
contents: read

concurrency:
group: toolkit-qualification-${{ github.workflow }}-${{ github.event.pull_request.head.sha || inputs.expected_sha || github.sha }}
cancel-in-progress: false

jobs:
qualify:
name: Node 22/24 and Chromium, thirteen sealed archives
runs-on: ubuntu-24.04
timeout-minutes: 50
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.pull_request.head.sha || inputs.expected_sha || github.sha }}
persist-credentials: false
- name: Require exact requested source
env:
EXPECTED_SHA: ${{ github.event.pull_request.head.sha || inputs.expected_sha || github.sha }}
CALLER_SHA: ${{ inputs.expected_sha }}
run: |
test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
if test -n "$CALLER_SHA"; then test "$CALLER_SHA" = "$EXPECTED_SHA"; fi
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '22.23.2'
package-manager-cache: false
- name: Install locked tooling and real AgentDB integration without lifecycle scripts
run: |
npm ci --prefix packages/wsp-toolkit --ignore-scripts --no-audit --no-fund
npm run --prefix packages/wsp-toolkit setup:agentdb
packages/wsp-toolkit/node_modules/.bin/playwright install --with-deps chromium
- name: Require release guard mutation tests
run: node --test scripts/toolkit-release.test.mjs
- name: Pack all thirteen archives exactly once from clean source
run: node scripts/toolkit-release-lane.mjs pack --directory "$RUNNER_TEMP/toolkit-candidate"
- name: Qualify canonical archives, strict types, browser, integration, work benchmark and audits on Node 22
run: node scripts/toolkit-release-lane.mjs qualify --directory "$RUNNER_TEMP/toolkit-candidate"
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24.22.1'
package-manager-cache: false
- name: Qualify the same archives and Node 22 dependency resolution on Node 24
run: node scripts/toolkit-release-lane.mjs qualify --directory "$RUNNER_TEMP/toolkit-candidate"
- name: Seal source, dependency graph, package SRI and both non-skipped qualifications
env:
EXPECTED_SHA: ${{ github.event.pull_request.head.sha || inputs.expected_sha || github.sha }}
run: |
node scripts/toolkit-release-lane.mjs seal --expected-sha "$EXPECTED_SHA" --directory "$RUNNER_TEMP/toolkit-candidate"
node scripts/toolkit-release-lane.mjs verify --directory "$RUNNER_TEMP/toolkit-candidate"
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: toolkit-candidate-${{ github.event.pull_request.head.sha || inputs.expected_sha || github.sha }}
path: ${{ runner.temp }}/toolkit-candidate/
include-hidden-files: true
if-no-files-found: error
retention-days: 90
38 changes: 34 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# ruv-FANN
# ruv-FANN — neural networks, WebAssembly and weight-space programming

Small neural networks you can train, inspect and edit in Rust, Node.js and the browser. The repository also contains separate forecasting, agent, GPU-compute and image-processing projects.
Small neural networks you can train, inspect and edit in Rust, JavaScript, TypeScript and the browser. Add bounded weight search, independent model evaluation, finite-domain checks and explicit AgentDB revisions. The repository also contains separate forecasting, agent, GPU-compute and image-processing projects.

[![See the weights. Prove the change. An illustrated guide to inspecting a network, editing a weight and evaluating the result.](docs/assets/weight-space-story.svg)](https://ruvnet.github.io/ruv-FANN/)

Expand All @@ -10,7 +10,7 @@ Small neural networks you can train, inspect and edit in Rust, Node.js and the b
[![API documentation](https://docs.rs/ruv-fann/badge.svg)](https://docs.rs/ruv-fann)
[![CI](https://github.com/ruvnet/ruv-FANN/actions/workflows/ci.yml/badge.svg)](https://github.com/ruvnet/ruv-FANN/actions/workflows/ci.yml)

**For Rust, start with the `ruv-fann` crate. For JavaScript and TypeScript, start with the `ruv-fann` npm package.** Add `ruv-fann-wsp` when you want to propose direct weight edits, inspect what changed, and explicitly evaluate and version the result. The Rust core provides generic floating-point networks, training algorithms and model I/O inspired by [FANN](https://github.com/libfann/fann).
**For Rust, start with the `ruv-fann` crate. For JavaScript and TypeScript, start with the `ruv-fann` npm package.** Core npm 0.2.0 exposes the weight toolkit through explicit `ruv-fann/*` subpaths. Choose standalone `ruv-fann-wsp` for a smaller weight-editing installation, or individual toolkit packages for focused integrations. The Rust core provides generic floating-point networks, training algorithms and model I/O inspired by [FANN](https://github.com/libfann/fann).

![Repository map: five independent Rust workspaces for neural networks, agent tools, forecasting, CUDA source translation and image processing.](docs/assets/package-map.svg)

Expand All @@ -19,7 +19,8 @@ Small neural networks you can train, inspect and edit in Rust, Node.js and the b
| Location | Available behavior | Version / guide |
| --- | --- | --- |
| `packages/wsp/` | **`ruv-fann-wsp`**: inspect and trace models, build bounded weight patches, evaluate candidates, then promote or roll back | Published npm **[0.2.0](https://www.npmjs.com/package/ruv-fann-wsp)** · [WSP guide](packages/wsp/README.md) · [Interactive story](https://ruvnet.github.io/ruv-FANN/) |
| `packages/core/` | **`ruv-fann` for JavaScript/TypeScript**: typed dense models, reusable WASM batch inference, SGD and AdamW training | Published npm **[0.1.2](https://www.npmjs.com/package/ruv-fann)** · [JavaScript guide](packages/core/README.md) |
| `packages/core/` | **`ruv-fann` for JavaScript/TypeScript**: WASM inference/training plus fourteen explicit toolkit subpaths | npm release **[0.2.0](https://www.npmjs.com/package/ruv-fann)** · [JavaScript guide](packages/core/README.md) |
| `packages/wsp-toolkit/` | Twelve focused packages: bounded search, holdout gates, invariants, worker proposals, AgentDB authority, Hub/Workers adapters and constellation tools | **0.1.0** each · [Toolkit guide](packages/wsp-toolkit/README.md) · [Umbrella release](https://github.com/ruvnet/ruv-FANN/releases/tag/ruv-fann-toolkit-v0.2.0) |
| `packages/wasm/` | **`ruv-fann-wasm`**: direct WASM bindings, bundled runtime binaries and SIMD detection | Published npm **[0.1.2](https://www.npmjs.com/package/ruv-fann-wasm)** · [Runtime guide](packages/wasm/README.md) |
| Repository root | **`ruv-fann` for Rust**: train feedforward networks, prepare immutable CPU inference snapshots, and use optional WebGPU operations | Checkout `0.2.2` · [Crate](https://crates.io/crates/ruv-fann) · [Core example](examples/basic_usage.rs) · [API](https://docs.rs/ruv-fann) |
| `integrations/candle/` | Import actual Candle CPU linear layers and compare training gradients/SGD/AdamW with Candle | `ruv-fann-candle 0.1.0` · [Candle guide](integrations/candle/README.md) |
Expand Down Expand Up @@ -90,6 +91,35 @@ and 24, real Chromium checks, and 19 adversarial input checks. See the
[field guide](https://ruvnet.github.io/ruv-FANN/) for an illustrated explanation
of those results and their limits.

## Bounded weight improvement with independent evaluation

[![Workers propose weight edits, independent holdout and finite-domain gates check candidates, and AgentDB controls revision CAS and explicit rollback.](https://raw.githubusercontent.com/ruvnet/ruv-FANN/e573ed708dcc4a5705990f3a8991deaefcf8be74/docs/assets/wsp-toolkit-loop.svg)](https://ruvnet.github.io/ruv-FANN/)

**[Explore the animated field guide →](https://ruvnet.github.io/ruv-FANN/)**

The toolkit extends local weight editing into a bounded proposal/evaluation loop. Node.js workers explore development cases, while the coordinator keeps holdouts and output constraints separate. A passing candidate is re-proposed through the supplied authority and activated only with an expected-revision comparison. Rollback creates a new revision containing the chosen old weights.

```sh
npm install ruv-fann@0.2.0
```

| Need | Core import | Individual package |
| --- | --- | --- |
| Inspect weights and trace activations | `ruv-fann/wsp` | `ruv-fann-wsp@0.2.0` |
| Search a bounded parameter set | `ruv-fann/search` | `ruv-fann-wsp-search@0.1.0` |
| Test named independent datasets | `ruv-fann/lifecycle` | `ruv-fann-wsp-lifecycle@0.1.0` |
| Check finite-domain output constraints | `ruv-fann/invariants` | `ruv-fann-wsp-invariants@0.1.0` |
| Coordinate workers and bounded generations | `ruv-fann/swarm`, `ruv-fann/loop` | `ruv-fann-wsp-swarm`, `ruv-fann-wsp-loop` |
| Serialize AgentDB revisions and acknowledge persistence | `ruv-fann/registry` | `ruv-fann-wsp-registry@0.1.0` |
| Load a pinned checkpoint or build a stateless edge handler | `ruv-fann/huggingface`, `ruv-fann/cloudflare` | Hub and Cloudflare adapters |
| Plan packages, validate metadata and render observations | `ruv-fann/constellation`, `ruv-fann/contracts`, `ruv-fann/telemetry` | Three constellation packages |

Read the [complete runnable rejection→gate→promotion example](packages/wsp-toolkit/README.md#repair-xor-gate-it-independently-and-choose-a-revision), the [core environment matrix](packages/core/README.md#capability-entrypoints), or run the source toolkit's `npm run demo:loop` for actual AgentDB reopen and rollback. The complete facade installs the toolkit, including its build tooling; individual packages provide smaller dependency footprints. Existing satellite pins intentionally retain a nested core 0.1.2 runtime. AgentDB is separately installed and owned by the application.

The loop does not call an LLM provider, execute generated code or publish packages. Worker threads are execution contexts, not security sandboxes; finite-domain tests and hashes do not establish universal safety or generalization. Release publication is a separate protected workflow that verifies exact archives and public installations.

**Topics:** Rust neural networks · JavaScript machine learning · TypeScript · WebAssembly SIMD · weight-space programming · model evaluation · neural weight search · AgentDB persistence · Cloudflare Workers.

## Try the neural-network core

Install [Rust](https://www.rust-lang.org/tools/install), then run the included example:
Expand Down
Loading
Loading