{"record":{"id":"b88eb40342925642","repo":"ruvnet/ruflo","slug":"failed-to-load-unified-krr","errorCode":null,"errorMessage":"failed to load unified KRR","messagePattern":"failed to load unified KRR","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/ruvector/neural-router.ts","lineNumber":457,"sourceCode":"        if (!existsSync(path)) return null;\n        try {\n          const json = JSON.parse(readFileSync(path, 'utf8'));\n          const trained = mh.TrainedRouter.fromJSON(json);\n          const cands = json.candidates.map((c: { id: string; costPerMTok: number }) => ({ id: c.id, costPerMTok: c.costPerMTok }));\n          return {\n            route: (e: number[]) => {\n              const r = trained.route(e);\n              return { id: r.id, predictedQuality: r.predictedQuality, costPerMTok: r.costPerMTok, metBar: r.metBar };\n            },\n            predictAll: (e: number[]) => cands.map((c: { id: string; costPerMTok: number }) => ({\n              id: c.id, predictedQuality: trained.predict(c.id, e), costPerMTok: c.costPerMTok,\n            })).sort((a: { costPerMTok: number }, b: { costPerMTok: number }) => a.costPerMTok - b.costPerMTok),\n          };\n        } catch { return null; }\n      };\n\n      const unifiedRaw = loadKrr(cfg.bundledKrrPath);\n      if (!unifiedRaw) throw new Error('failed to load unified KRR');\n      const unified = wrapWithCalibrator(unifiedRaw, unifiedCalibrator);\n\n      // ADR-149 iter 16 — load per-bucket specialists if present. Each is a\n      // KRR fit only to its tier's rows (cheap → low.json, mid → med.json,\n      // strong → high.json). When tryCostOptimalRoute is called with a\n      // complexityBucket, the matching specialist is preferred over the\n      // unified router.\n      const bucketDir = cfg.bundledKrrPath.replace(/seed-router\\.krr\\.json$/, '');\n      const routerByBucket: Partial<Record<'low' | 'med' | 'high', PureRouter>> = {};\n      const loadedBuckets: string[] = [];\n      for (const bucket of ['low', 'med', 'high'] as const) {\n        const r = loadKrr(`${bucketDir}seed-router.krr.${bucket}.json`);\n        if (r) {\n          // iter 25 — prefer tier-specific calibrator for this bucket;\n          // fall back to the unified calibrator when no specialist exists.\n          routerByBucket[bucket] = wrapWithCalibrator(r, calibratorByBucket[bucket] ?? unifiedCalibrator);\n          loadedBuckets.push(bucket);\n        }","sourceCodeStart":439,"sourceCodeEnd":475,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/ruvector/neural-router.ts#L439-L475","documentation":"When building the routed engine, neural-router loads a trained-router artifact from cfg.bundledKrrPath (expected file seed-router.krr.json) via loadKrr(), which returns null when existsSync fails OR when reading/JSON.parse/TrainedRouter.fromJSON throws (all swallowed to null, neural-router.ts:438-454). A null unified artifact becomes this throw — the KRR (kernel routing rules) file is missing, unreadable, corrupt, or schema-incompatible.","triggerScenarios":"Package installed without the bundled .krr.json asset (files excluded from the npm tarball); cfg.bundledKrrPath overridden to a wrong or moved location; truncated/corrupt file from a partial download; version skew where TrainedRouter.fromJSON rejects the JSON layout of a newer artifact.","commonSituations":"Fresh installs or CI caches with pruned optional assets; bundlers (esbuild/webpack) that fail to copy JSON sidecars into dist; upgrading @claude-flow/cli or the MetaHarness writer so the old seed-router.krr.json no longer parses; custom deployment paths that drop data files.","solutions":["Verify the artifact: check existsSync(cfg.bundledKrrPath) and dry-run JSON.parse on it in a REPL to surface the real cause","Reinstall the package cleanly (rm -rf node_modules && npm install) so the bundled seed-router.krr.json is restored","If bundledKrrPath was customized, point it at a known-good seed-router.krr.json matching your package version","Fall back to the non-KRR routing path while regenerating or re-fetching the artifact"],"exampleFix":"// before\nconst router = tryCostOptimalRoute(...); // throws: failed to load unified KRR\n// after (diagnose first)\nimport { existsSync, readFileSync } from 'node:fs';\nconst p = cfg.bundledKrrPath; // e.g. .../seed-router.krr.json\nconsole.log('exists:', existsSync(p));\nif (existsSync(p)) JSON.parse(readFileSync(p, 'utf8')); // surfaces parse/schema error\n// then reinstall the package or fix bundledKrrPath before retrying","handlingStrategy":"fallback","validationCode":"import { existsSync, readFileSync } from 'node:fs';\nfunction krrIsLoadable(path: string): boolean {\n  try { return existsSync(path) && !!JSON.parse(readFileSync(path, 'utf8')); }\n  catch { return false; }\n}","typeGuard":"function isLoadableKrrPath(path: string): boolean {\n  if (!existsSync(path)) return false;\n  try { JSON.parse(readFileSync(path, 'utf8')); return true; } catch { return false; }\n}","tryCatchPattern":"try {\n  router = buildRoutedEngine(cfg);\n} catch (e) {\n  if (e instanceof Error && e.message === 'failed to load unified KRR') {\n    console.error(`KRR artifact missing/corrupt at ${cfg.bundledKrrPath} — using heuristic routing`);\n    router = heuristicRouter; // degrade, then fix the artifact out-of-band\n  } else throw e;\n}","preventionTips":["After install, smoke-test that the bundled seed-router.krr.json exists and parses before first run","If you override bundledKrrPath, validate the target in a startup check","Mark the .krr.json asset as an external asset in bundler configs so it ships with dist"],"tags":["neural-router","krr","bundled-asset","packaging","config"],"backgroundTag":"bundled-asset-missing","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}