{"record":{"id":"28b4b757383b424d","repo":"ruvnet/ruflo","slug":"patternlearner-unsupported-schemaversion-decode","errorCode":null,"errorMessage":"PatternLearner: unsupported schemaVersion ${decoded.schemaVersion} (expected 1)","messagePattern":"PatternLearner: unsupported schemaVersion (.+?) \\(expected 1\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/neural/src/pattern-learner.ts","lineNumber":510,"sourceCode":"  /**\n   * Restore from a previously-serialized state. Replaces all current state.\n   * Event listeners NOT restored — re-register after deserialize() returns.\n   */\n  deserialize(state: unknown): void {\n    const decoded = deepDecode(state) as {\n      schemaVersion: number;\n      config: PatternLearnerConfig;\n      patterns: Map<string, Pattern>;\n      clusters: Array<{ clusterId: number; centroid: Float32Array; patternIds: string[] }>;\n      patternToCluster: Map<string, number>;\n      counters: {\n        matchCount: number; totalMatchTime: number;\n        extractionCount: number; totalExtractionTime: number;\n        evolutionCount: number; totalEvolutionTime: number;\n      };\n    };\n    if (decoded.schemaVersion !== 1) {\n      throw new Error(`PatternLearner: unsupported schemaVersion ${decoded.schemaVersion} (expected 1)`);\n    }\n    this.config = { ...this.config, ...decoded.config };\n    this.patterns = decoded.patterns;\n    this.clusters = decoded.clusters.map((c) => ({\n      clusterId: c.clusterId,\n      centroid: c.centroid,\n      patternIds: new Set(c.patternIds),\n    }));\n    this.patternToCluster = decoded.patternToCluster;\n    this.matchCount = decoded.counters.matchCount;\n    this.totalMatchTime = decoded.counters.totalMatchTime;\n    this.extractionCount = decoded.counters.extractionCount;\n    this.totalExtractionTime = decoded.counters.totalExtractionTime;\n    this.evolutionCount = decoded.counters.evolutionCount;\n    this.totalEvolutionTime = decoded.counters.totalEvolutionTime;\n  }\n\n  // ==========================================================================","sourceCodeStart":492,"sourceCodeEnd":528,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/neural/src/pattern-learner.ts#L492-L528","documentation":"PatternLearner.serialize() stamps snapshots with schemaVersion 1; deserialize() refuses any state whose schemaVersion differs, throwing with the found and expected version. The guard prevents silently loading an incompatible state shape (patterns, clusters, counters) written by another release — deserialization is all-or-nothing, so a bad version must fail before partial state is applied.","triggerScenarios":"Loading a snapshot produced by a newer/older @claude-flow/neural whose serialize() format changed; hand-edited JSON state files; feeding a ReasoningBank or SONAManager snapshot into PatternLearner.deserialize().","commonSituations":"Upgrading the package across a schema change and reusing persisted state; several services sharing state files while pinned to different versions.","solutions":["Regenerate the snapshot with the current version (serialize() again after a clean learn cycle)","Pin the library version that wrote the file, load it, migrate the state, re-serialize, then upgrade","Check state.schemaVersion === 1 before deserialize() and route older/newer files to a migration path"],"exampleFix":"// before\nlearner.deserialize(JSON.parse(fs.readFileSync(path, 'utf8')));\n\n// after\nconst state = JSON.parse(fs.readFileSync(path, 'utf8'));\nif (state?.schemaVersion !== 1) {\n  throw new Error(`Snapshot schema ${state?.schemaVersion} unsupported - regenerate or migrate it`);\n}\nlearner.deserialize(state);","handlingStrategy":"validation","validationCode":"const state = JSON.parse(fs.readFileSync(path, 'utf8')) as { schemaVersion?: number };\nif (state?.schemaVersion !== 1) {\n  throw new Error(`Snapshot schema ${state?.schemaVersion} unsupported (expected 1) - regenerate or migrate`);\n}\nlearner.deserialize(state);","typeGuard":"function isV1Snapshot(s: unknown): s is { schemaVersion: 1 } {\n  return !!s && typeof s === 'object' && (s as { schemaVersion?: unknown }).schemaVersion === 1;\n}","tryCatchPattern":null,"preventionTips":["Check schemaVersion before deserialize() and route mismatches to migration","Store the library version alongside each snapshot file","Regenerate snapshots after upgrading @claude-flow/neural"],"tags":["neural","persistence","serialization","versioning"],"backgroundTag":"schema-version-mismatch","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}