Broken optionalDependencies in @ruvector/ruvllm@2.4.0–2.5.4 (pin to unpublished 2.3.0 native binaries)

[ruvnet]

Summary

@ruvector/ruvllm@2.4.0 through 2.5.4 (current latest on npm) declare
optionalDependencies for all five native binary packages pinned to
2.3.0 — but no native package was ever published at 2.3.0. The
highest published version of every platform binary is 2.0.1.

Net effect: the JS wrapper installs cleanly but the native loader has
nothing to load on any platform, because npm silently skips
optional deps it can't resolve. ruvllm@2.4.0+ is effectively broken-by-design
as published.

This package is pulled in transitively by @claude-flow/cli via
@claude-flow/memory@3.0.0-alpha.14 → agentdb@3.0.0-alpha.11 → @ruvector/ruvllm@2.5.4,
so any user installing claude-flow gets the broken wrapper.

Reproduce

$ npm view @ruvector/ruvllm@2.5.4 optionalDependencies
{
  '@ruvector/ruvllm-linux-x64-gnu': '2.3.0',
  '@ruvector/ruvllm-linux-arm64-gnu': '2.3.0',
  '@ruvector/ruvllm-darwin-x64': '2.3.0',
  '@ruvector/ruvllm-darwin-arm64': '2.3.0',
  '@ruvector/ruvllm-win32-x64-msvc': '2.3.0'
}

$ npm view @ruvector/ruvllm-darwin-arm64 versions
[ '0.2.0', '0.2.3', '2.0.0', '2.0.1' ]

$ npm view @ruvector/ruvllm-darwin-arm64@2.3.0
npm error 404 '@ruvector/ruvllm-darwin-arm64@2.3.0' is not in this registry.

All five native packages have the identical published version set
[0.2.0, 0.2.3, 2.0.0, 2.0.1].

Why it happened

.github/workflows/ruvllm-native.yml builds and publishes the platform
binaries on a ruvllm-v* tag, then publishes the main JS package in the
same job. Versions 2.4.0, 2.5.0–2.5.4 of the JS package were
published outside that flow (see
e9295556e,
3d7f31ce7,
e7e545e22) without rebuilding/republishing the
native binaries. Each release bumped the wrapper version and the
optionalDependencies pin to 2.3.0, but the native binaries never
caught up — they remain at 2.0.1 on npm.

Fix

Two-part:

1. Source fix (this PR-equivalent edit): point
   npm/packages/ruvllm/package.json optionalDependencies at the
   latest actually-published native version 2.0.1, so the next
   release of the wrapper resolves its native loader.
2. Republish: ship a new wrapper version (e.g. 2.5.5) with the
   corrected pin. Either:
   • keep pinning to the existing native 2.0.1 (cheapest, ships today), or
   • run the RuvLLM Native Build workflow with a fresh tag
     (ruvllm-v2.5.5) to rebuild + republish the native binaries at the
     same version as the wrapper. ADR-recommend the latter so the
     version space stays one-to-one going forward.

Process gap to close

The prepublishOnly script for @ruvector/ruvllm should
verify each optionalDependencies version exists on npm before letting
the publish proceed. A 6-line npm view ... version check would have
caught every one of the broken 2.4.x/2.5.x releases at publish time.

Affected versions

@ruvector/ruvllm → 2.4.0, 2.4.1, 2.5.0, 2.5.1, 2.5.2, 2.5.3, 2.5.4
(all currently resolvable, all silently broken on every platform).

[ruvnet]

Resolution — published @ruvector/ruvllm@2.5.5

Pinned optionalDependencies to the actually-published native version 2.0.1.

$ npm view @ruvector/ruvllm@2.5.5 optionalDependencies
{
  '@ruvector/ruvllm-linux-x64-gnu': '2.0.1',
  '@ruvector/ruvllm-linux-arm64-gnu': '2.0.1',
  '@ruvector/ruvllm-darwin-x64': '2.0.1',
  '@ruvector/ruvllm-darwin-arm64': '2.0.1',
  '@ruvector/ruvllm-win32-x64-msvc': '2.0.1'
}

End-to-end install proof (linux-x64)

Broken baseline (2.5.4):

$ npm install @ruvector/ruvllm@2.5.4
$ ls node_modules/@ruvector/
ruvllm                 ← wrapper only, NO native pkg

Fixed (2.5.5):

$ npm install @ruvector/ruvllm@2.5.5
$ ls node_modules/@ruvector/
ruvllm
ruvllm-linux-x64-gnu   ← native pkg installed
$ ls node_modules/@ruvector/ruvllm-linux-x64-gnu/
ruvllm.linux-x64-gnu.node    ← real binary

Still open (deferred from this fix)

1. Process gap — add a prepublishOnly guard that refuses to publish if any optionalDependencies version is missing on npm. Three lines of npm view will catch every recurrence at publish time.
2. Long-term — next ruvllm-v* tag should rebuild the platform binaries to a version that matches the wrapper (e.g., wrapper 2.5.6 ↔ native 2.5.6) so the version space goes back to one-to-one. Right now wrapper 2.5.5 correctly points at older native 2.0.1, which is fine for fixing the bug but leaves drift in place.