{"record":{"id":"0c0f26cda3743727","repo":"ruvnet/ruflo","slug":"unsupported-uncertainty-ledger-version-data-ver","errorCode":null,"errorMessage":"Unsupported uncertainty ledger version: ${data.version} (expected ${SERIALIZATION_VERSION})","messagePattern":"Unsupported uncertainty ledger version: (.+?) \\(expected (.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/guidance/src/uncertainty.ts","lineNumber":570,"sourceCode":"   * @returns Serialized ledger data suitable for JSON.stringify\n   */\n  exportBeliefs(): SerializedUncertaintyLedger {\n    return {\n      beliefs: Array.from(this.beliefs.values()).map(b => ({ ...b })),\n      createdAt: new Date().toISOString(),\n      version: SERIALIZATION_VERSION,\n    };\n  }\n\n  /**\n   * Import previously exported beliefs, replacing all current contents.\n   *\n   * @param data - Serialized ledger data\n   * @throws If the version is unsupported\n   */\n  importBeliefs(data: SerializedUncertaintyLedger): void {\n    if (data.version !== SERIALIZATION_VERSION) {\n      throw new Error(\n        `Unsupported uncertainty ledger version: ${data.version} (expected ${SERIALIZATION_VERSION})`,\n      );\n    }\n    this.beliefs.clear();\n    for (const belief of data.beliefs) {\n      this.beliefs.set(belief.id, { ...belief });\n    }\n  }\n\n  /**\n   * Get the number of tracked beliefs.\n   */\n  get size(): number {\n    return this.beliefs.size;\n  }\n\n  /**\n   * Get the current configuration.","sourceCodeStart":552,"sourceCodeEnd":588,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/guidance/src/uncertainty.ts#L552-L588","documentation":"Thrown by UncertaintyLedger.importBeliefs(data) when the serialized payload's version differs from the module's SERIALIZATION_VERSION. The import replaces all current beliefs wholesale (beliefs.clear() then re-populate), so a version gate prevents a foreign-format payload from corrupting the ledger. It fires before any mutation happens, leaving the ledger untouched.","triggerScenarios":"Feeding a SerializedUncertaintyLedger produced by a different build of @claude-flow/guidance into importBeliefs — restoring a persisted ledger after a version upgrade, or receiving an export from another service/node running a different release.","commonSituations":"Rolling deployments with mixed package versions exchanging belief exports; long-lived snapshots loaded after dependency upgrades; copy-pasting fixtures between repos pinned to different versions.","solutions":["Re-export the ledger from an instance running the same guidance package version as the importer","Align @claude-flow/guidance versions across all producers and consumers (lockfile pinning)","Add a migration step that upgrades old payload versions to the current one before calling importBeliefs"],"exampleFix":"// before\nledger.importBeliefs(JSON.parse(backupJson)); // stale export -> throws\n\n// after\nconst data = JSON.parse(backupJson);\nif (data.version !== EXPECTED_VERSION) {\n  throw new Error(`ledger backup is v${data.version}; regenerate on current version`);\n}\nledger.importBeliefs(data);","handlingStrategy":"validation","validationCode":"const data = JSON.parse(raw) as SerializedUncertaintyLedger & { version: number };\nif (data.version !== importerVersion) {\n  throw new Error(`ledger v${data.version} incompatible; re-export on v${importerVersion}`);\n}\nledger.importBeliefs(data);","typeGuard":"function isCompatibleLedger(v: number): (d: unknown) => d is SerializedUncertaintyLedger {\n  return (d): d is SerializedUncertaintyLedger =>\n    typeof d === 'object' && d !== null && (d as { version?: unknown }).version === v;\n}","tryCatchPattern":"try {\n  ledger.importBeliefs(data);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Unsupported uncertainty ledger version')) {\n    // beliefs map untouched — safe to migrate payload and retry\n    ledger.importBeliefs(migrateBeliefs(data));\n    return;\n  }\n  throw e;\n}","preventionTips":["Record the producer version inside every persisted ledger export","Lock dependency versions in all services that share belief exports","Test import paths against fixtures from the current version in CI"],"tags":["serialization","version-mismatch","uncertainty","guidance","import"],"backgroundTag":"serialization-version-mismatch","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}