{"record":{"id":"a565feffa0e1a0c9","repo":"ruvnet/ruflo","slug":"flashoptlevel-must-be-between-0-and-3","errorCode":null,"errorMessage":"flashOptLevel must be between 0 and 3","messagePattern":"flashOptLevel must be between 0 and 3","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/integration/src/attention-coordinator.ts","lineNumber":491,"sourceCode":"      memoryEfficiency: 1.0,\n      cacheHitRate: 0,\n      totalOperations: 0,\n      speedupFactor: 1.0,\n    };\n  }\n\n  private validateConfig(): void {\n    if (this.config.numHeads <= 0) {\n      throw new Error('numHeads must be positive');\n    }\n    if (this.config.headDim <= 0) {\n      throw new Error('headDim must be positive');\n    }\n    if (this.config.dropoutRate < 0 || this.config.dropoutRate > 1) {\n      throw new Error('dropoutRate must be between 0 and 1');\n    }\n    if (this.config.flashOptLevel < 0 || this.config.flashOptLevel > 3) {\n      throw new Error('flashOptLevel must be between 0 and 3');\n    }\n  }\n\n  private async prewarmCache(): Promise<void> {\n    // Pre-compute common attention patterns\n    // This is a no-op in the simplified implementation\n  }\n\n  /**\n   * Perform attention computation\n   *\n   * ADR-001: For sequences longer than 512 tokens, delegates to\n   * agentic-flow's native Flash Attention (approximate sparse attention;\n   * speedup unverified — see docs/reviews/intelligence-system-audit-2026-05-29.md).\n   */\n  private async performAttention(params: {\n    query: number[] | Float32Array;\n    key: number[] | Float32Array;","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/integration/src/attention-coordinator.ts#L473-L509","documentation":"Thrown by AttentionCoordinator#validateConfig (v3/@claude-flow/integration/src/attention-coordinator.ts:491) when config.flashOptLevel is outside 0–3 inclusive. The level selects a Flash Attention optimization tier (0 = off, 1–3 increasing aggressiveness); anything else has no defined behavior and is rejected.","triggerScenarios":"Passing flashOptLevel: 4 or higher after reading an outdated doc; a negative value to 'disable' instead of 0; values computed at runtime (e.g. from a heuristic) that are not clamped to the 0–3 enum.","commonSituations":"Version drift: an older/newer doc listing 0–5 levels; configs copied from another project with a wider scale; dynamically choosing the level from benchmark results without clamping.","solutions":["Use a value in 0, 1, 2, 3 — use 0 to disable flash optimization.","Clamp computed levels before constructing: Math.min(3, Math.max(0, level)).","Pin configs to the level enum documented in this package version and re-check after upgrades."],"exampleFix":"// before\nnew AttentionCoordinator({ flashOptLevel: tunedLevel }); // tunedLevel = 5\n\n// after\nconst flashOptLevel = Math.min(3, Math.max(0, Math.round(tunedLevel)));\nnew AttentionCoordinator({ flashOptLevel });","handlingStrategy":"validation","validationCode":"const raw = Number(cfg.flashOptLevel ?? 1);\nconst flashOptLevel = [0, 1, 2, 3].includes(raw) ? raw : 1;\nnew AttentionCoordinator({ ...cfg, flashOptLevel });","typeGuard":"function isFlashLevel(v: unknown): v is 0 | 1 | 2 | 3 {\n  return v === 0 || v === 1 || v === 2 || v === 3;\n}","tryCatchPattern":"try {\n  coord = new AttentionCoordinator(cfg);\n} catch (e) {\n  if ((e as Error).message === 'flashOptLevel must be between 0 and 3') {\n    coord = new AttentionCoordinator({ ...cfg, flashOptLevel: 0 });\n  } else throw e;\n}","preventionTips":["Clamp computed optimization levels: Math.min(3, Math.max(0, level)).","Use 0 to disable flash attention — never negative values.","Re-verify the allowed range after package upgrades."],"tags":["config-validation","attention","range-validation","flash-attention"],"backgroundTag":"invalid-config-value","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}