{"record":{"id":"29882fca583bf8de","repo":"ruvnet/ruflo","slug":"unsupported-artifact-ledger-version-data-versio","errorCode":null,"errorMessage":"Unsupported artifact ledger version: ${data.version} (expected ${SERIALIZATION_VERSION})","messagePattern":"Unsupported artifact ledger version: (.+?) \\(expected (.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/guidance/src/artifacts.ts","lineNumber":429,"sourceCode":"   * @returns Serialized ledger data suitable for JSON.stringify\n   */\n  export(): SerializedArtifactLedger {\n    return {\n      artifacts: Array.from(this.artifacts.values()).map(a => ({ ...a })),\n      createdAt: new Date().toISOString(),\n      version: SERIALIZATION_VERSION,\n    };\n  }\n\n  /**\n   * Import a previously exported ledger, replacing all current contents.\n   *\n   * @param data - Serialized ledger data\n   * @throws If the version is unsupported\n   */\n  import(data: SerializedArtifactLedger): void {\n    if (data.version !== SERIALIZATION_VERSION) {\n      throw new Error(\n        `Unsupported artifact ledger version: ${data.version} (expected ${SERIALIZATION_VERSION})`,\n      );\n    }\n    this.artifacts.clear();\n    for (const artifact of data.artifacts) {\n      this.artifacts.set(artifact.artifactId, { ...artifact });\n    }\n  }\n\n  /**\n   * Get aggregate statistics about the ledger.\n   *\n   * @returns Counts by kind and total content size\n   */\n  getStats(): ArtifactStats {\n    const byKind = Object.fromEntries(\n      ALL_KINDS.map(k => [k, 0]),\n    ) as Record<ArtifactKind, number>;","sourceCodeStart":411,"sourceCodeEnd":447,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/guidance/src/artifacts.ts#L411-L447","documentation":"SerializedArtifactLedger payloads carry a SERIALIZATION_VERSION stamp (currently 1) written at export() time; import() rejects any payload whose version differs so a schema change cannot silently corrupt the ledger. This is a forward/backward-compatibility gate: the export and the importing code must come from the same serialization generation.","triggerScenarios":"Exporting a ledger with @claude-flow/guidance@X and importing it under version Y after SERIALIZATION_VERSION changed; hand-editing the exported JSON; truncated or partially written export files where the version field is wrong.","commonSituations":"Upgrading the guidance package across a serialization format bump; copying ledger dumps between staging and production running different package versions; restoring old backups.","solutions":["Re-export the ledger using the same package version that will import it","Pin both environments (source and target) to the same @claude-flow/guidance version","Write a one-off migration that reads the old-version payload and re-records artifacts into a fresh ledger via record(), then export","Validate `data.version` before calling import() and skip stale files"],"exampleFix":"// before\nledger.import(jsonFromFile); // throws if exported by an older version\n\n// after\nif (jsonFromFile.version !== ledger.export().version) {\n  // regenerate the dump with the current version, or migrate\n} else {\n  ledger.import(jsonFromFile);\n}","handlingStrategy":"validation","validationCode":"const currentVersion = ledger.export().version;\nif (data.version !== currentVersion) {\n  // stale or future payload — skip import, migrate, or regenerate\n}","typeGuard":null,"tryCatchPattern":"try {\n  ledger.import(data);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Unsupported artifact ledger version')) {\n    // keep current ledger contents; re-export from the matching package version\n  } else throw err;\n}","preventionTips":["Pin the same @claude-flow/guidance version wherever ledgers are exported and imported","Record the package version alongside ledger dumps","Never hand-edit serialized ledger JSON"],"tags":["serialization","version-mismatch","import-export","artifact-ledger","guidance"],"backgroundTag":"schema-version-mismatch","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}