{"record":{"id":"126be28e56ff9c1b","repo":"ruvnet/ruflo","slug":"unsupported-temporal-store-version-data-version","errorCode":null,"errorMessage":"Unsupported temporal store version: ${data.version} (expected ${SERIALIZATION_VERSION})","messagePattern":"Unsupported temporal store version: (.+?) \\(expected (.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/guidance/src/temporal.ts","lineNumber":540,"sourceCode":"      assertions.push({ ...assertion, metadata: { ...assertion.metadata } });\n    }\n\n    return {\n      assertions,\n      createdAt: new Date().toISOString(),\n      version: SERIALIZATION_VERSION,\n    };\n  }\n\n  /**\n   * Import previously exported assertions, replacing all current contents.\n   *\n   * @param data - Serialized store data\n   * @throws If the version is unsupported\n   */\n  importAssertions(data: SerializedTemporalStore): void {\n    if (data.version !== SERIALIZATION_VERSION) {\n      throw new Error(\n        `Unsupported temporal store version: ${data.version} (expected ${SERIALIZATION_VERSION})`,\n      );\n    }\n\n    this.assertions.clear();\n    const now = Date.now();\n\n    for (const assertion of data.assertions) {\n      const imported: TemporalAssertion = {\n        ...assertion,\n        tags: [...assertion.tags],\n        metadata: { ...assertion.metadata },\n      };\n      imported.status = computeStatus(imported, now);\n      this.assertions.set(imported.id, imported);\n    }\n  }\n","sourceCodeStart":522,"sourceCodeEnd":558,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/guidance/src/temporal.ts#L522-L558","documentation":"Thrown by TemporalStore.importAssertions(data) when the serialized payload's version field does not equal the module's SERIALIZATION_VERSION. The export format is versioned on purpose: incompatible payloads are rejected up front rather than silently mis-parsed, because importAssertions clears and replaces the entire store contents. It protects against restoring data produced by a different release of @claude-flow/guidance.","triggerScenarios":"Passing JSON from store.exportAssertions() that was produced by an older or newer build of the guidance package — e.g. restoring a persisted snapshot after an upgrade, or importing a blob shared between services running different versions.","commonSituations":"Upgrading @claude-flow/guidance across a serialization bump and replaying old backups; mixed-version fleets where one node exports and another imports; hand-edited or truncated export files; snapshots created in dev and loaded in a container built from a different base image.","solutions":["Re-export the assertions from a store running the same package version as the importer","Pin the @claude-flow/guidance version identically across every producer and consumer of the export","If you control both ends, write a one-time migration that rewrites the old payload to the current version field before importing"],"exampleFix":"// before\nstore.importAssertions(JSON.parse(rawFileContents)); // old snapshot -> version mismatch\n\n// after\nconst data = JSON.parse(rawFileContents);\nconst currentVersion = 1; // must equal the exporter's SERIALIZATION_VERSION\nif (data.version !== currentVersion) {\n  throw new Error(`snapshot is v${data.version}; re-export with the current guidance version`);\n}\nstore.importAssertions(data);","handlingStrategy":"validation","validationCode":"// Verify the payload version before mutating the store\nconst data = JSON.parse(raw) as SerializedTemporalStore & { version: number };\nconst exporterVersion = data.version;\nif (exporterVersion !== importerVersion) {\n  throw new Error(`snapshot v${exporterVersion} != importer v${importerVersion}; re-export or migrate`);\n}\nstore.importAssertions(data);","typeGuard":"function isCompatibleSnapshot(\n  v: number,\n): (d: unknown) => d is SerializedTemporalStore {\n  return (d): d is SerializedTemporalStore =>\n    typeof d === 'object' && d !== null && (d as { version?: unknown }).version === v;\n}","tryCatchPattern":"try {\n  store.importAssertions(data);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Unsupported temporal store version')) {\n    // store is untouched (throw happens before clear()) — safe to migrate and retry\n    store.importAssertions(migrateTemporal(data));\n    return;\n  }\n  throw e;\n}","preventionTips":["Stamp exported files with the package version and validate on restore","Pin @claude-flow/guidance across every environment that exchanges these exports","Never hand-edit serialized temporal store files"],"tags":["serialization","version-mismatch","temporal-store","guidance","import"],"backgroundTag":"serialization-version-mismatch","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}