claude-flow 3.76.1 → 3.77.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  {
2
- "adoptedAt": 1794515699232,
2
+ "adoptedAt": 1794520287185,
3
3
  "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
4
4
  "manifest": {
5
5
  "schema": "ruflo.proven-config/v1",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-flow",
3
- "version": "3.76.1",
3
+ "version": "3.77.0",
4
4
  "workspaces": [
5
5
  "v3/@claude-flow/codex",
6
6
  "v3/@claude-flow/mcp",
@@ -140,7 +140,11 @@ export class RvfaBuilder {
140
140
  buildRufloSection() {
141
141
  let packageMeta = null;
142
142
  try {
143
- const raw = execSync('npm pack ruflo@latest --dry-run --json 2>/dev/null', { encoding: 'utf-8', timeout: 15_000 });
143
+ const raw = execSync('npm pack ruflo@latest --dry-run --json', {
144
+ encoding: 'utf-8',
145
+ timeout: 15_000,
146
+ stdio: ['ignore', 'pipe', 'pipe'],
147
+ });
144
148
  const parsed = JSON.parse(raw);
145
149
  if (Array.isArray(parsed) && parsed.length > 0)
146
150
  packageMeta = parsed[0];
@@ -1317,7 +1317,21 @@ const depsCommand = {
1317
1317
  output.writeln(output.bold('Security Audit'));
1318
1318
  output.writeln(output.dim('-'.repeat(60)));
1319
1319
  try {
1320
- const auditRaw = execSync('npm audit --json 2>/dev/null', { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
1320
+ let auditRaw;
1321
+ try {
1322
+ auditRaw = execSync('npm audit --json', {
1323
+ encoding: 'utf-8',
1324
+ maxBuffer: 10 * 1024 * 1024,
1325
+ stdio: ['pipe', 'pipe', 'pipe'],
1326
+ });
1327
+ }
1328
+ catch (auditErr) {
1329
+ // npm audit exits non-zero when vulnerabilities found — stdout still has JSON
1330
+ const stdout = auditErr instanceof Error && 'stdout' in auditErr ? auditErr.stdout : '';
1331
+ if (!stdout)
1332
+ throw auditErr;
1333
+ auditRaw = stdout;
1334
+ }
1321
1335
  const audit = JSON.parse(auditRaw);
1322
1336
  const vulns = audit.metadata?.vulnerabilities || audit.vulnerabilities || {};
1323
1337
  const info = vulns.info || 0;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * `neural wsp` — ruv-FANN weight-space tooling (ADR-528).
3
+ *
4
+ * Read-only evidence over dense models: fingerprint, inspect, invariant
5
+ * checks and bounded-patch regression gates. Nothing here promotes a model,
6
+ * writes routing state or changes what `hooks route` does. The only write is
7
+ * `export-centroid`, which writes the file the user names.
8
+ *
9
+ * Backed by the optional dependencies ruv-fann-wsp, ruv-fann-wsp-invariants
10
+ * and ruv-fann-wsp-lifecycle; every subcommand reports cleanly when they are
11
+ * missing.
12
+ */
13
+ import type { Command } from '../types.js';
14
+ export declare const wspCommand: Command;
15
+ //# sourceMappingURL=neural-wsp.d.ts.map
@@ -0,0 +1,265 @@
1
+ /**
2
+ * `neural wsp` — ruv-FANN weight-space tooling (ADR-528).
3
+ *
4
+ * Read-only evidence over dense models: fingerprint, inspect, invariant
5
+ * checks and bounded-patch regression gates. Nothing here promotes a model,
6
+ * writes routing state or changes what `hooks route` does. The only write is
7
+ * `export-centroid`, which writes the file the user names.
8
+ *
9
+ * Backed by the optional dependencies ruv-fann-wsp, ruv-fann-wsp-invariants
10
+ * and ruv-fann-wsp-lifecycle; every subcommand reports cleanly when they are
11
+ * missing.
12
+ */
13
+ import { existsSync, writeFileSync } from 'node:fs';
14
+ import { resolve as resolvePath } from 'node:path';
15
+ import { output } from '../output.js';
16
+ function str(flags, name) {
17
+ const v = flags[name];
18
+ return typeof v === 'string' && v.length > 0 ? v : undefined;
19
+ }
20
+ function isJson(flags) {
21
+ return str(flags, 'format') === 'json';
22
+ }
23
+ function fail(message, json, exitCode = 1) {
24
+ if (json)
25
+ output.writeln(JSON.stringify({ ok: false, error: message }, null, 2));
26
+ else
27
+ output.printError(message);
28
+ return { success: false, exitCode, message };
29
+ }
30
+ async function requireWsp(json) {
31
+ const { loadWsp } = await import('../ruvector/ruv-fann-wsp.js');
32
+ const load = await loadWsp();
33
+ if (!load.available)
34
+ return { error: fail(`ruv-FANN WSP unavailable: ${load.reason}`, json, 2) };
35
+ return { mods: load.modules };
36
+ }
37
+ /** The shipped (or CLAUDE_FLOW_ROUTER_CENTROID_PATH) centroid artifact. */
38
+ async function loadCentroid() {
39
+ const { loadCentroidArtifact } = await import('../ruvector/centroid-router.js');
40
+ return loadCentroidArtifact();
41
+ }
42
+ /** `--model <file>` when given, else the centroid router as a dense model. */
43
+ async function resolveModel(flags) {
44
+ const w = await import('../ruvector/ruv-fann-wsp.js');
45
+ const file = str(flags, 'model');
46
+ if (file)
47
+ return { model: w.assertDenseModel(w.readJsonInput(file, 'model')), source: resolvePath(file), artifact: null };
48
+ const c = await loadCentroid();
49
+ if (!c.artifact)
50
+ throw new Error(`centroid router artifact unavailable: ${c.error}`);
51
+ return { model: w.centroidToDenseModel(c.artifact), source: `centroid router (${c.path})`, artifact: c.artifact };
52
+ }
53
+ const formatOpt = { name: 'format', short: 'f', type: 'string', description: 'Output format: table, json', default: 'table' };
54
+ const modelOpt = { name: 'model', short: 'm', type: 'string', description: 'ruv-fann.dense-layers/1 JSON file (default: the centroid router)' };
55
+ const statusCommand = {
56
+ name: 'status',
57
+ description: 'Show whether the ruv-FANN WSP packages are installed, their versions and limits',
58
+ options: [formatOpt],
59
+ action: async (ctx) => {
60
+ const json = isJson(ctx.flags);
61
+ const { loadWsp, wspVersions } = await import('../ruvector/ruv-fann-wsp.js');
62
+ const load = await loadWsp();
63
+ const versions = wspVersions();
64
+ const limits = load.available
65
+ ? { wsp: load.modules.wsp.WSP_LIMITS, invariants: load.modules.invariants.INVARIANT_LIMITS, lifecycle: load.modules.lifecycle.LIFECYCLE_LIMITS }
66
+ : null;
67
+ const data = { available: load.available, reason: load.available ? null : load.reason, versions, limits };
68
+ if (json)
69
+ output.writeln(JSON.stringify(data, null, 2));
70
+ else {
71
+ output.writeln(output.bold('ruv-FANN weight-space programming'));
72
+ output.writeln(` Available: ${load.available ? output.success('yes') : output.warning('no — ' + data.reason)}`);
73
+ for (const [k, v] of Object.entries(versions))
74
+ output.writeln(` ${k.padEnd(24)} ${v ?? output.dim('not installed')}`);
75
+ if (limits)
76
+ output.writeln(output.dim(` Patch limit: ${limits.wsp.maxEdits} edits · rows ≤ ${limits.wsp.maxRows} · params ≤ ${limits.wsp.maxParameters} · invariant cases ≤ ${limits.invariants.maxCases}`));
77
+ }
78
+ return { success: true, data };
79
+ },
80
+ };
81
+ const inspectCommand = {
82
+ name: 'inspect',
83
+ description: 'Fingerprint and describe a dense model (default: the centroid router)',
84
+ options: [modelOpt, formatOpt],
85
+ examples: [
86
+ { command: 'claude-flow neural wsp inspect', description: 'Hash and shape of the shipped centroid router' },
87
+ { command: 'claude-flow neural wsp inspect -m model.json -f json', description: 'Inspect your own ruv-FANN model' },
88
+ ],
89
+ action: async (ctx) => {
90
+ const json = isJson(ctx.flags);
91
+ const w = await requireWsp(json);
92
+ if ('error' in w)
93
+ return w.error;
94
+ try {
95
+ const { model, source } = await resolveModel(ctx.flags);
96
+ const inspection = await w.mods.wsp.inspectWeightModel(model);
97
+ const data = { source, ...inspection };
98
+ if (json)
99
+ output.writeln(JSON.stringify(data, null, 2));
100
+ else {
101
+ output.writeln(output.bold(`Model: ${source}`));
102
+ output.writeln(` Hash: ${inspection.baseHash}`);
103
+ output.writeln(` Shape: ${inspection.inputSize} → ${inspection.outputSize} (${inspection.parameterCount} parameters)`);
104
+ for (const l of inspection.layers) {
105
+ output.writeln(output.dim(` layer ${l.layer}: ${l.inputs}→${l.outputs} ${l.activation} (${l.parameterCount} params)`));
106
+ }
107
+ }
108
+ return { success: true, data };
109
+ }
110
+ catch (err) {
111
+ return fail(err instanceof Error ? err.message : String(err), json);
112
+ }
113
+ },
114
+ };
115
+ const checkCommand = {
116
+ name: 'check',
117
+ description: 'Run invariant checks: the built-in centroid self-routing suite, or --suite on --model',
118
+ options: [
119
+ modelOpt,
120
+ { name: 'suite', short: 's', type: 'string', description: 'ruv-fann.invariants/1 JSON file (required with --model)' },
121
+ { name: 'min-gap', type: 'number', description: 'Self-routing: required gap between a label and any other label on its own centroid', default: '0.05' },
122
+ formatOpt,
123
+ ],
124
+ examples: [
125
+ { command: 'claude-flow neural wsp check', description: 'Each centroid must route to its own label by a clear gap' },
126
+ { command: 'claude-flow neural wsp check -m model.json -s invariants.json', description: 'Your own model and suite' },
127
+ ],
128
+ action: async (ctx) => {
129
+ const json = isJson(ctx.flags);
130
+ const w = await requireWsp(json);
131
+ if ('error' in w)
132
+ return w.error;
133
+ const mod = await import('../ruvector/ruv-fann-wsp.js');
134
+ try {
135
+ const modelFile = str(ctx.flags, 'model');
136
+ const suiteFile = str(ctx.flags, 'suite');
137
+ let data, accepted;
138
+ if (!modelFile) {
139
+ if (suiteFile)
140
+ return fail('--suite needs --model; without --model the built-in self-routing suite runs', json);
141
+ const c = await loadCentroid();
142
+ if (!c.artifact)
143
+ return fail(`centroid router artifact unavailable: ${c.error}`, json);
144
+ const gapRaw = ctx.flags.minGap ?? ctx.flags['min-gap'];
145
+ const minGap = gapRaw === undefined ? undefined : Number(gapRaw);
146
+ if (minGap !== undefined && !(minGap > 0 && minGap < 1))
147
+ return fail('--min-gap must be in (0, 1)', json);
148
+ const r = await mod.checkCentroidSelfRouting(w.mods, c.artifact, { minGap });
149
+ accepted = r.accepted;
150
+ data = { suite: 'centroid-self-routing', source: c.path, ...r };
151
+ }
152
+ else {
153
+ if (!suiteFile)
154
+ return fail('--model needs --suite (a ruv-fann.invariants/1 file)', json);
155
+ const model = mod.assertDenseModel(mod.readJsonInput(modelFile, 'model'));
156
+ const suite = mod.readJsonInput(suiteFile, 'suite');
157
+ const r = await w.mods.invariants.checkModelInvariants(model, suite);
158
+ accepted = r.accepted === true;
159
+ data = { suite: resolvePath(suiteFile), source: resolvePath(modelFile), ...r };
160
+ }
161
+ if (json)
162
+ output.writeln(JSON.stringify(data, null, 2));
163
+ else {
164
+ output.writeln(accepted ? output.success(`Invariants hold (${data.checks} checks, ${data.backend})`) : output.warning(`Invariants FAILED (${data.checks} checks)`));
165
+ const v = data.violations ?? [];
166
+ for (const x of v.slice(0, 20))
167
+ output.writeln(output.dim(` ${x.case}: output ${x.output} ${x.constraint} — actual ${x.actual}, bound ${x.bound}`));
168
+ if (v.length > 20)
169
+ output.writeln(output.dim(` … ${v.length - 20} more`));
170
+ }
171
+ return { success: accepted, exitCode: accepted ? 0 : 1, data };
172
+ }
173
+ catch (err) {
174
+ return fail(err instanceof Error ? err.message : String(err), json);
175
+ }
176
+ },
177
+ };
178
+ const gateCommand = {
179
+ name: 'gate',
180
+ description: 'Regression-gate a bounded weight patch against one or more datasets (evidence only; never promotes)',
181
+ options: [
182
+ { name: 'model', short: 'm', type: 'string', description: 'ruv-fann.dense-layers/1 JSON file', required: true },
183
+ { name: 'patch', short: 'p', type: 'string', description: 'ruv-fann.weight-patch/1 JSON file (≤128 edits)', required: true },
184
+ { name: 'suites', short: 's', type: 'string', description: 'JSON array of {name, dataset:{inputs,targets,rows}, policy:{maxMSE,maxRegressionMSE}}', required: true },
185
+ formatOpt,
186
+ ],
187
+ examples: [
188
+ { command: 'claude-flow neural wsp gate -m model.json -p patch.json -s suites.json', description: 'Accept or reject a patch on every suite' },
189
+ ],
190
+ action: async (ctx) => {
191
+ const json = isJson(ctx.flags);
192
+ const w = await requireWsp(json);
193
+ if ('error' in w)
194
+ return w.error;
195
+ const mod = await import('../ruvector/ruv-fann-wsp.js');
196
+ try {
197
+ const m = str(ctx.flags, 'model'), p = str(ctx.flags, 'patch'), s = str(ctx.flags, 'suites');
198
+ if (!m || !p || !s)
199
+ return fail('--model, --patch and --suites are all required', json);
200
+ const model = mod.assertDenseModel(mod.readJsonInput(m, 'model'));
201
+ const patch = mod.readJsonInput(p, 'patch');
202
+ const suites = mod.readJsonInput(s, 'suites');
203
+ if (!Array.isArray(suites))
204
+ return fail('suites: expected a JSON array', json);
205
+ const r = await w.mods.lifecycle.runRegressionGate({ model, patch, suites });
206
+ if (json)
207
+ output.writeln(JSON.stringify(r, null, 2));
208
+ else {
209
+ output.writeln(r.accepted ? output.success('Patch ACCEPTED on every suite') : output.warning('Patch REJECTED'));
210
+ output.writeln(output.dim(` base ${r.baseHash.slice(0, 16)}… → candidate ${r.candidateHash.slice(0, 16)}…`));
211
+ for (const x of r.suites) {
212
+ const e = x.evaluation;
213
+ output.writeln(` ${x.name}: ${e.accepted ? 'pass' : 'fail'} mse ${e.baseline.mse.toFixed(6)} → ${e.candidate.mse.toFixed(6)}${e.reasons.length ? ' (' + e.reasons.join('; ') + ')' : ''}`);
214
+ }
215
+ output.writeln(output.dim(' Evidence only: nothing was promoted or written.'));
216
+ }
217
+ return { success: r.accepted, exitCode: r.accepted ? 0 : 1, data: r };
218
+ }
219
+ catch (err) {
220
+ return fail(err instanceof Error ? err.message : String(err), json);
221
+ }
222
+ },
223
+ };
224
+ const exportCentroidCommand = {
225
+ name: 'export-centroid',
226
+ description: 'Write the centroid router as a ruv-fann.dense-layers/1 model (one Linear layer)',
227
+ options: [
228
+ { name: 'output', short: 'o', type: 'string', description: 'Destination JSON file', required: true },
229
+ { name: 'force', type: 'boolean', description: 'Overwrite an existing file', default: 'false' },
230
+ ],
231
+ examples: [
232
+ { command: 'claude-flow neural wsp export-centroid -o centroid-router.json', description: 'Export for use with other ruv-FANN tooling' },
233
+ ],
234
+ action: async (ctx) => {
235
+ const out = str(ctx.flags, 'output');
236
+ if (!out)
237
+ return fail('--output is required', false);
238
+ const dest = resolvePath(out);
239
+ if (existsSync(dest) && ctx.flags.force !== true)
240
+ return fail(`${dest} exists; pass --force to overwrite`, false);
241
+ const c = await loadCentroid();
242
+ if (!c.artifact)
243
+ return fail(`centroid router artifact unavailable: ${c.error}`, false);
244
+ const { centroidToDenseModel } = await import('../ruvector/ruv-fann-wsp.js');
245
+ const model = centroidToDenseModel(c.artifact);
246
+ writeFileSync(dest, JSON.stringify(model) + '\n', { mode: 0o644 });
247
+ output.writeln(output.success(`Wrote ${dest}`));
248
+ output.writeln(output.dim(` ${c.artifact.labels.length} outputs (labels, in order): ${c.artifact.labels.join(', ')}`));
249
+ return { success: true, data: { path: dest, labels: c.artifact.labels } };
250
+ },
251
+ };
252
+ export const wspCommand = {
253
+ name: 'wsp',
254
+ description: 'ruv-FANN weight-space tooling: inspect, invariant checks, regression gates (ADR-528)',
255
+ subcommands: [statusCommand, inspectCommand, checkCommand, gateCommand, exportCentroidCommand],
256
+ examples: [
257
+ { command: 'claude-flow neural wsp status', description: 'Are the optional ruv-FANN packages installed?' },
258
+ { command: 'claude-flow neural wsp check', description: 'Self-routing invariants on the shipped centroid router' },
259
+ ],
260
+ action: async () => {
261
+ output.writeln('Use a subcommand: status | inspect | check | gate | export-centroid');
262
+ return { success: true };
263
+ },
264
+ };
265
+ //# sourceMappingURL=neural-wsp.js.map
@@ -6,6 +6,7 @@
6
6
  */
7
7
  import { output } from '../output.js';
8
8
  import { getProjectRoot } from '../services/project-root.js';
9
+ import { wspCommand } from './neural-wsp.js';
9
10
  // Train subcommand - REAL WASM training with RuVector
10
11
  const trainCommand = {
11
12
  name: 'train',
@@ -4323,7 +4324,7 @@ const distillCommand = {
4323
4324
  export const neuralCommand = {
4324
4325
  name: 'neural',
4325
4326
  description: 'Neural pattern training, MoE, Flash Attention, pattern learning',
4326
- subcommands: [trainCommand, statusCommand, patternsCommand, predictCommand, optimizeCommand, benchmarkCommand, listCommand, exportCommand, importCommand, routerCommand, distillCommand],
4327
+ subcommands: [trainCommand, statusCommand, patternsCommand, predictCommand, optimizeCommand, benchmarkCommand, listCommand, exportCommand, importCommand, routerCommand, distillCommand, wspCommand],
4327
4328
  examples: [
4328
4329
  { command: 'claude-flow neural status', description: 'Check neural system status' },
4329
4330
  { command: 'claude-flow neural train -p coordination', description: 'Train coordination patterns' },
@@ -489,7 +489,7 @@ const cveCommand = {
489
489
  // If --check CVE-XXXX is given, filter to that specific CVE ID.
490
490
  let auditJson;
491
491
  try {
492
- auditJson = execSync('npm audit --json 2>/dev/null', {
492
+ auditJson = execSync('npm audit --json', {
493
493
  encoding: 'utf-8',
494
494
  timeout: 30000,
495
495
  stdio: ['pipe', 'pipe', 'pipe'],
@@ -0,0 +1,129 @@
1
+ /**
2
+ * ruv-fann-wsp.ts — optional ruv-FANN weight-space tooling (ADR-528).
3
+ *
4
+ * Wraps three exact-pinned optional dependencies:
5
+ * - `ruv-fann-wsp` fingerprint, inspect, sensitivity
6
+ * - `ruv-fann-wsp-invariants` finite-domain output-bound checks
7
+ * - `ruv-fann-wsp-lifecycle` bounded-patch regression gates
8
+ *
9
+ * They share the `ruv-fann` core and `ruv-fann-wasm` runtime that agentdb and
10
+ * @metaharness/darwin already install, so they add no native code and no
11
+ * install scripts. The `ruv-fann` 0.3.0 facade is deliberately NOT used: it
12
+ * pulls esbuild (an install script) and a native RVF binding into every
13
+ * install for capabilities ruflo does not call.
14
+ *
15
+ * Every entry point loads the packages lazily. When they are absent the
16
+ * caller gets `{ available: false, reason }`; nothing else in the CLI
17
+ * imports this module, so cold start and routing are unchanged.
18
+ *
19
+ * Results are hash-bound evidence, not authority: nothing here promotes,
20
+ * writes or reroutes on its own.
21
+ *
22
+ * @module ruv-fann-wsp
23
+ */
24
+ import type { CentroidArtifact } from './centroid-router.js';
25
+ export declare const WSP_PACKAGES: readonly ["ruv-fann-wsp", "ruv-fann-wsp-invariants", "ruv-fann-wsp-lifecycle"];
26
+ export type WspPackage = (typeof WSP_PACKAGES)[number];
27
+ /** Upper bound for any JSON file this module reads (models, suites, patches). */
28
+ export declare const MAX_INPUT_BYTES: number;
29
+ /** INVARIANT_LIMITS.maxCases in ruv-fann-wsp-invariants 0.1.0. */
30
+ export declare const MAX_CASES_PER_SUITE = 16;
31
+ /** Centroids are stored rounded, so a centroid scores slightly below 1 against itself. */
32
+ export declare const SELF_SCORE_TOLERANCE = 0.00001;
33
+ export interface DenseLayer {
34
+ inputs: number;
35
+ outputs: number;
36
+ /** Row-major [outputs, inputs]. */
37
+ weights: number[];
38
+ bias?: number[] | null;
39
+ activation: string;
40
+ steepness: number;
41
+ }
42
+ export interface DenseModel {
43
+ schema: 'ruv-fann.dense-layers/1';
44
+ layers: DenseLayer[];
45
+ }
46
+ export interface InvariantCase {
47
+ name: string;
48
+ inputs: number[];
49
+ rows: number;
50
+ minimum?: number[];
51
+ maximum?: number[];
52
+ expected?: number[];
53
+ tolerance?: number;
54
+ }
55
+ export interface InvariantSuite {
56
+ schema: 'ruv-fann.invariants/1';
57
+ cases: InvariantCase[];
58
+ }
59
+ export interface WspModules {
60
+ wsp: Record<string, any>;
61
+ invariants: Record<string, any>;
62
+ lifecycle: Record<string, any>;
63
+ }
64
+ export type WspLoad = {
65
+ available: true;
66
+ modules: WspModules;
67
+ } | {
68
+ available: false;
69
+ reason: string;
70
+ };
71
+ export type Importer = (specifier: string) => Promise<Record<string, any>>;
72
+ /** Load all three packages once. Never throws. */
73
+ export declare function loadWsp(importer?: Importer): Promise<WspLoad>;
74
+ /**
75
+ * Installed version of each package, or null. `ruv-fann` is not a direct
76
+ * dependency, so it is looked up where ruv-fann-wsp resolves it: nested
77
+ * under it (pnpm, npm conflicts) or beside it (flat npm).
78
+ */
79
+ export declare function wspVersions(): Record<WspPackage | 'ruv-fann', string | null>;
80
+ /**
81
+ * The centroid router as a one-layer Linear ruv-FANN model. Output k is the
82
+ * dot product with centroid k, which is the router's cosine score for a
83
+ * unit-length query, so the model ranks labels exactly as `classify` does.
84
+ */
85
+ export declare function centroidToDenseModel(artifact: CentroidArtifact): DenseModel;
86
+ /**
87
+ * Self-routing invariants: fed its own centroid, each label must score
88
+ * 1 ± tolerance and every other label at most `1 - minGap`. A failure means
89
+ * two labels are (near-)duplicates or the artifact is corrupt — the router
90
+ * could not separate them even on their own means.
91
+ *
92
+ * Returned as several suites when there are more labels than one suite allows.
93
+ */
94
+ export declare function centroidSelfRoutingSuites(artifact: CentroidArtifact, opts?: {
95
+ tolerance?: number;
96
+ minGap?: number;
97
+ }): InvariantSuite[];
98
+ /**
99
+ * Read a JSON file the user named. Refuses non-regular files (FIFOs, devices,
100
+ * directories), symlinks that leave nothing to read, and anything larger
101
+ * than MAX_INPUT_BYTES, before reading it into memory.
102
+ */
103
+ export declare function readJsonInput(path: string, what: string, maxBytes?: number): unknown;
104
+ /** Shape check before handing a user model to WSP (which validates fully). */
105
+ export declare function assertDenseModel(x: unknown, what?: string): DenseModel;
106
+ export interface SelfRoutingResult {
107
+ accepted: boolean;
108
+ modelHash: string;
109
+ labels: number;
110
+ suites: number;
111
+ checks: number;
112
+ violations: Array<{
113
+ case: string;
114
+ output: string;
115
+ constraint: string;
116
+ actual: number;
117
+ bound: number;
118
+ }>;
119
+ backend: string;
120
+ ms: number;
121
+ }
122
+ /** Run the self-routing invariants against a centroid artifact. */
123
+ export declare function checkCentroidSelfRouting(mods: WspModules, artifact: CentroidArtifact, opts?: {
124
+ tolerance?: number;
125
+ minGap?: number;
126
+ }): Promise<SelfRoutingResult>;
127
+ /** Test hook. */
128
+ export declare function __resetWspForTests(): void;
129
+ //# sourceMappingURL=ruv-fann-wsp.d.ts.map
@@ -0,0 +1,221 @@
1
+ /**
2
+ * ruv-fann-wsp.ts — optional ruv-FANN weight-space tooling (ADR-528).
3
+ *
4
+ * Wraps three exact-pinned optional dependencies:
5
+ * - `ruv-fann-wsp` fingerprint, inspect, sensitivity
6
+ * - `ruv-fann-wsp-invariants` finite-domain output-bound checks
7
+ * - `ruv-fann-wsp-lifecycle` bounded-patch regression gates
8
+ *
9
+ * They share the `ruv-fann` core and `ruv-fann-wasm` runtime that agentdb and
10
+ * @metaharness/darwin already install, so they add no native code and no
11
+ * install scripts. The `ruv-fann` 0.3.0 facade is deliberately NOT used: it
12
+ * pulls esbuild (an install script) and a native RVF binding into every
13
+ * install for capabilities ruflo does not call.
14
+ *
15
+ * Every entry point loads the packages lazily. When they are absent the
16
+ * caller gets `{ available: false, reason }`; nothing else in the CLI
17
+ * imports this module, so cold start and routing are unchanged.
18
+ *
19
+ * Results are hash-bound evidence, not authority: nothing here promotes,
20
+ * writes or reroutes on its own.
21
+ *
22
+ * @module ruv-fann-wsp
23
+ */
24
+ import { lstatSync, readFileSync, realpathSync } from 'node:fs';
25
+ import { dirname, resolve as resolvePath } from 'node:path';
26
+ import { fileURLToPath } from 'node:url';
27
+ export const WSP_PACKAGES = ['ruv-fann-wsp', 'ruv-fann-wsp-invariants', 'ruv-fann-wsp-lifecycle'];
28
+ /** Upper bound for any JSON file this module reads (models, suites, patches). */
29
+ export const MAX_INPUT_BYTES = 2 * 1024 * 1024;
30
+ /** INVARIANT_LIMITS.maxCases in ruv-fann-wsp-invariants 0.1.0. */
31
+ export const MAX_CASES_PER_SUITE = 16;
32
+ /** Centroids are stored rounded, so a centroid scores slightly below 1 against itself. */
33
+ export const SELF_SCORE_TOLERANCE = 1e-5;
34
+ // A non-literal specifier keeps tsc from resolving the optional packages at
35
+ // build time; they are ESM-only, so `require` cannot load them.
36
+ const defaultImporter = (specifier) => import(specifier);
37
+ let _load = null;
38
+ function isMissingModule(err) {
39
+ const code = err?.code;
40
+ return code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND';
41
+ }
42
+ /** Load all three packages once. Never throws. */
43
+ export function loadWsp(importer = defaultImporter) {
44
+ if (importer !== defaultImporter)
45
+ return doLoad(importer);
46
+ if (!_load)
47
+ _load = doLoad(importer);
48
+ return _load;
49
+ }
50
+ async function doLoad(importer) {
51
+ const mods = {};
52
+ for (const name of WSP_PACKAGES) {
53
+ try {
54
+ mods[name] = await importer(name);
55
+ }
56
+ catch (err) {
57
+ const why = isMissingModule(err) ? 'is not installed' : `failed to load: ${err instanceof Error ? err.message : String(err)}`;
58
+ return { available: false, reason: `${name} ${why} (optional dependency of @claude-flow/cli)` };
59
+ }
60
+ }
61
+ return {
62
+ available: true,
63
+ modules: { wsp: mods['ruv-fann-wsp'], invariants: mods['ruv-fann-wsp-invariants'], lifecycle: mods['ruv-fann-wsp-lifecycle'] },
64
+ };
65
+ }
66
+ /** Package root of `name` at or above `dir`, or null. */
67
+ function packageRootAbove(dir, name) {
68
+ for (let i = 0; i < 4; i++) {
69
+ try {
70
+ const pkg = JSON.parse(readFileSync(resolvePath(dir, 'package.json'), 'utf8'));
71
+ if (pkg && pkg.name === name && typeof pkg.version === 'string')
72
+ return { root: dir, version: pkg.version };
73
+ }
74
+ catch { /* keep walking */ }
75
+ dir = dirname(dir);
76
+ }
77
+ return null;
78
+ }
79
+ /**
80
+ * Installed version of each package, or null. `ruv-fann` is not a direct
81
+ * dependency, so it is looked up where ruv-fann-wsp resolves it: nested
82
+ * under it (pnpm, npm conflicts) or beside it (flat npm).
83
+ */
84
+ export function wspVersions() {
85
+ const out = {};
86
+ let wspRoot = null;
87
+ for (const name of WSP_PACKAGES) {
88
+ out[name] = null;
89
+ try {
90
+ const found = packageRootAbove(dirname(fileURLToPath(import.meta.resolve(name))), name);
91
+ if (found) {
92
+ out[name] = found.version;
93
+ if (name === 'ruv-fann-wsp')
94
+ wspRoot = found.root;
95
+ }
96
+ }
97
+ catch { /* not installed */ }
98
+ }
99
+ out['ruv-fann'] = null;
100
+ if (wspRoot) {
101
+ for (const dir of [resolvePath(wspRoot, 'node_modules', 'ruv-fann'), resolvePath(wspRoot, '..', 'ruv-fann')]) {
102
+ const found = packageRootAbove(dir, 'ruv-fann');
103
+ if (found && found.root === dir) {
104
+ out['ruv-fann'] = found.version;
105
+ break;
106
+ }
107
+ }
108
+ }
109
+ return out;
110
+ }
111
+ /**
112
+ * The centroid router as a one-layer Linear ruv-FANN model. Output k is the
113
+ * dot product with centroid k, which is the router's cosine score for a
114
+ * unit-length query, so the model ranks labels exactly as `classify` does.
115
+ */
116
+ export function centroidToDenseModel(artifact) {
117
+ const weights = [];
118
+ for (const c of artifact.centroids)
119
+ for (const v of c)
120
+ weights.push(v);
121
+ return {
122
+ schema: 'ruv-fann.dense-layers/1',
123
+ layers: [{
124
+ inputs: artifact.dim,
125
+ outputs: artifact.labels.length,
126
+ weights,
127
+ bias: new Array(artifact.labels.length).fill(0),
128
+ activation: 'Linear',
129
+ steepness: 1,
130
+ }],
131
+ };
132
+ }
133
+ function caseName(prefix, label, i) {
134
+ const safe = label.replace(/[^A-Za-z0-9_.-]/g, '_');
135
+ return `${prefix}${i}-${safe}`.slice(0, 64);
136
+ }
137
+ /**
138
+ * Self-routing invariants: fed its own centroid, each label must score
139
+ * 1 ± tolerance and every other label at most `1 - minGap`. A failure means
140
+ * two labels are (near-)duplicates or the artifact is corrupt — the router
141
+ * could not separate them even on their own means.
142
+ *
143
+ * Returned as several suites when there are more labels than one suite allows.
144
+ */
145
+ export function centroidSelfRoutingSuites(artifact, opts = {}) {
146
+ const tol = opts.tolerance ?? SELF_SCORE_TOLERANCE;
147
+ const minGap = opts.minGap ?? 0.05;
148
+ if (!(tol >= 0 && tol < 0.5))
149
+ throw new RangeError('tolerance must be in [0, 0.5)');
150
+ if (!(minGap > 0 && minGap < 1))
151
+ throw new RangeError('minGap must be in (0, 1)');
152
+ const n = artifact.labels.length;
153
+ const cases = artifact.centroids.map((c, i) => ({
154
+ name: caseName('self-', artifact.labels[i], i),
155
+ inputs: c.slice(),
156
+ rows: 1,
157
+ // Unit vectors: every score is within [-1, 1]; pad by tol for rounding.
158
+ minimum: Array.from({ length: n }, (_, j) => (j === i ? 1 - tol : -1 - tol)),
159
+ maximum: Array.from({ length: n }, (_, j) => (j === i ? 1 + tol : 1 - minGap)),
160
+ }));
161
+ const suites = [];
162
+ for (let i = 0; i < cases.length; i += MAX_CASES_PER_SUITE) {
163
+ suites.push({ schema: 'ruv-fann.invariants/1', cases: cases.slice(i, i + MAX_CASES_PER_SUITE) });
164
+ }
165
+ return suites;
166
+ }
167
+ /**
168
+ * Read a JSON file the user named. Refuses non-regular files (FIFOs, devices,
169
+ * directories), symlinks that leave nothing to read, and anything larger
170
+ * than MAX_INPUT_BYTES, before reading it into memory.
171
+ */
172
+ export function readJsonInput(path, what, maxBytes = MAX_INPUT_BYTES) {
173
+ if (typeof path !== 'string' || path.length === 0 || path.includes('\0')) {
174
+ throw new Error(`${what}: a file path is required`);
175
+ }
176
+ const real = realpathSync(resolvePath(path));
177
+ const st = lstatSync(real);
178
+ if (!st.isFile())
179
+ throw new Error(`${what}: ${path} is not a regular file`);
180
+ if (st.size > maxBytes)
181
+ throw new Error(`${what}: ${path} is ${st.size} bytes; limit is ${maxBytes}`);
182
+ const text = readFileSync(real, 'utf8');
183
+ try {
184
+ return JSON.parse(text);
185
+ }
186
+ catch (err) {
187
+ throw new Error(`${what}: ${path} is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
188
+ }
189
+ }
190
+ /** Shape check before handing a user model to WSP (which validates fully). */
191
+ export function assertDenseModel(x, what = 'model') {
192
+ const m = x;
193
+ if (!m || typeof m !== 'object' || m.schema !== 'ruv-fann.dense-layers/1' || !Array.isArray(m.layers) || m.layers.length === 0) {
194
+ throw new Error(`${what}: expected a ruv-fann.dense-layers/1 model with at least one layer`);
195
+ }
196
+ return m;
197
+ }
198
+ /** Run the self-routing invariants against a centroid artifact. */
199
+ export async function checkCentroidSelfRouting(mods, artifact, opts = {}) {
200
+ const t0 = performance.now();
201
+ const model = centroidToDenseModel(artifact);
202
+ const suites = centroidSelfRoutingSuites(artifact, opts);
203
+ let accepted = true, checks = 0, backend = '', modelHash = '';
204
+ const violations = [];
205
+ for (const suite of suites) {
206
+ const r = await mods.invariants.checkModelInvariants(model, suite);
207
+ accepted &&= r.accepted === true;
208
+ checks += r.checks;
209
+ backend = r.backend;
210
+ modelHash = r.modelHash;
211
+ for (const v of r.violations) {
212
+ violations.push({ case: v.case, output: artifact.labels[v.output] ?? String(v.output), constraint: v.constraint, actual: v.actual, bound: v.bound });
213
+ }
214
+ }
215
+ return { accepted, modelHash, labels: artifact.labels.length, suites: suites.length, checks, violations, backend, ms: Math.round(performance.now() - t0) };
216
+ }
217
+ /** Test hook. */
218
+ export function __resetWspForTests() {
219
+ _load = null;
220
+ }
221
+ //# sourceMappingURL=ruv-fann-wsp.js.map
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@claude-flow/cli",
3
- "version": "3.76.1",
3
+ "version": "3.77.0",
4
4
  "type": "module",
5
5
  "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
6
6
  "main": "dist/src/index.js",
@@ -149,7 +149,10 @@
149
149
  "ruvector": "^0.3.13",
150
150
  "nostr-tools": "^2.7.0",
151
151
  "@ruvector/learning-wasm": "0.1.29",
152
- "agent-booster": "^0.2.2"
152
+ "agent-booster": "^0.2.2",
153
+ "ruv-fann-wsp": "0.2.0",
154
+ "ruv-fann-wsp-invariants": "0.1.0",
155
+ "ruv-fann-wsp-lifecycle": "0.1.0"
153
156
  },
154
157
  "peerDependencies": {
155
158
  "@metaharness/router": "^0.4.0",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@claude-flow/guidance",
3
- "version": "3.0.0",
3
+ "version": "3.0.1",
4
4
  "description": "Guidance Control Plane - Compiles, retrieves, enforces, and evolves guidance rules for Claude Code sessions",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",