{"record":{"id":"0b3e65b65c0dcdbc","repo":"ruvnet/ruflo","slug":"unsupported-proof-chain-version-data-version","errorCode":null,"errorMessage":"Unsupported proof chain version: ${data.version} (expected ${SERIALIZATION_VERSION})","messagePattern":"Unsupported proof chain version: (.+?) \\(expected (.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/guidance/src/proof.ts","lineNumber":302,"sourceCode":"  /**\n   * Export the chain as a serializable object.\n   */\n  export(): SerializedProofChain {\n    return {\n      envelopes: this.envelopes.map(e => ({ ...e })),\n      createdAt: new Date().toISOString(),\n      version: SERIALIZATION_VERSION,\n    };\n  }\n\n  /**\n   * Restore the chain from a previously exported object.\n   *\n   * Replaces the current chain contents entirely.\n   */\n  import(data: SerializedProofChain): void {\n    if (data.version !== SERIALIZATION_VERSION) {\n      throw new Error(\n        `Unsupported proof chain version: ${data.version} (expected ${SERIALIZATION_VERSION})`,\n      );\n    }\n    this.envelopes = data.envelopes.map(e => ({ ...e }));\n  }\n\n  // ===========================================================================\n  // Private helpers\n  // ===========================================================================\n\n  /**\n   * Compute the SHA-256 content hash of a RunEvent.\n   */\n  private computeContentHash(event: RunEvent): string {\n    const payload = JSON.stringify(event, Object.keys(event).sort());\n    return createHash('sha256').update(payload).digest('hex');\n  }\n","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/guidance/src/proof.ts#L284-L320","documentation":"ProofChain.import() restores a chain only from SerializedProofChain objects whose version equals the module's SERIALIZATION_VERSION (currently 1); export() stamps that version at export time. A mismatch means the serialized data was produced by a different release of @claude-flow/guidance (older or newer), or the payload was hand-edited/corrupted. The expected and actual versions are both included in the message.","triggerScenarios":"Importing chain JSON persisted by a different (older or newer) package version after an upgrade or downgrade; hand-editing an export; loading fixtures created under another release.","commonSituations":"Upgrading @claude-flow/guidance in one service while another still writes chains with the old version; restoring archived audit chains after a version bump; mixing fixture data across dependency updates.","solutions":["Pin the same @claude-flow/guidance version in every environment that writes and reads chain data","Before import(), check (data as SerializedProofChain).version — currently 1 — and reject or migrate mismatches explicitly","To migrate, verify the chain with the version that produced it, then re-append or re-export under the current version","If provenance cannot be established, start a fresh chain rather than importing unverifiable data"],"exampleFix":"// before\nchain.import(JSON.parse(await readFile('chain.json', 'utf-8'))); // version mismatch -> throws\n// after\nconst data = JSON.parse(await readFile('chain.json', 'utf-8')) as SerializedProofChain;\nif (data.version !== 1) {\n  throw new Error(`Chain file version ${data.version} not supported by this build; migrate it first`);\n}\nchain.import(data);","handlingStrategy":"type-guard","validationCode":"function isCompatibleSerializedChain(data: unknown): data is SerializedProofChain {\n  return (\n    typeof data === 'object' && data !== null &&\n    'version' in data && (data as SerializedProofChain).version === 1 &&\n    'envelopes' in data && Array.isArray((data as SerializedProofChain).envelopes)\n  );\n}\nconst data: unknown = JSON.parse(raw);\nif (!isCompatibleSerializedChain(data)) {\n  throw new Error(`Chain payload version unsupported; expected 1, got ${(data as { version?: unknown })?.version}`);\n}\nchain.import(data);","typeGuard":"function isCompatibleSerializedChain(data: unknown): data is SerializedProofChain {\n  return (\n    typeof data === 'object' && data !== null &&\n    (data as { version?: unknown }).version === 1 &&\n    Array.isArray((data as { envelopes?: unknown }).envelopes)\n  );\n}","tryCatchPattern":"try {\n  chain.import(data);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Unsupported proof chain version')) {\n    // data came from a different library release: pin versions or migrate via the producing version\n    throw new Error(`Chain data needs migration before import: ${err.message}`);\n  }\n  throw err;\n}","preventionTips":["Pin one @claude-flow/guidance version across all writers and readers of chain data","Stash the library version next to exported chain artifacts so migrations are traceable","Treat version-mismatched audit data as unverifiable: verify with the producing version before re-export"],"tags":["guidance","proof","serialization","version-mismatch","data-migration"],"backgroundTag":"serialization-version-mismatch","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}