{"record":{"id":"b32ba11d1b1bef24","repo":"affaan-m/ECC","slug":"unsupported-canonical-session-schema-version-sn","errorCode":null,"errorMessage":"Unsupported canonical session schema version: ${snapshot.schemaVersion}","messagePattern":"Unsupported canonical session schema version: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/session-adapters/canonical-session.js","lineNumber":169,"sourceCode":"  const completedCount = (workerStates.completed || 0)\n    + (workerStates.succeeded || 0)\n    + (workerStates.success || 0)\n    + (workerStates.done || 0);\n  if (completedCount === totalWorkers) {\n    return 'completed';\n  }\n\n  return 'idle';\n}\n\nfunction validateCanonicalSnapshot(snapshot) {\n  if (!isObject(snapshot)) {\n    throw new Error('Canonical session snapshot must be an object');\n  }\n\n  ensureString(snapshot.schemaVersion, 'schemaVersion');\n  if (snapshot.schemaVersion !== SESSION_SCHEMA_VERSION) {\n    throw new Error(`Unsupported canonical session schema version: ${snapshot.schemaVersion}`);\n  }\n\n  ensureString(snapshot.adapterId, 'adapterId');\n\n  if (!isObject(snapshot.session)) {\n    throw new Error('Canonical session snapshot requires session to be an object');\n  }\n\n  ensureString(snapshot.session.id, 'session.id');\n  ensureString(snapshot.session.kind, 'session.kind');\n  ensureString(snapshot.session.state, 'session.state');\n  ensureOptionalString(snapshot.session.repoRoot, 'session.repoRoot');\n\n  if (!isObject(snapshot.session.sourceTarget)) {\n    throw new Error('Canonical session snapshot requires session.sourceTarget to be an object');\n  }\n\n  ensureString(snapshot.session.sourceTarget.type, 'session.sourceTarget.type');","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/lib/session-adapters/canonical-session.js#L151-L187","documentation":"Thrown by validateCanonicalSnapshot when snapshot.schemaVersion is a non-empty string but does not equal the supported SESSION_SCHEMA_VERSION ('ecc.session.v1'). This guards against snapshots produced by a future or incompatible schema version being interpreted by this code.","triggerScenarios":"A snapshot whose schemaVersion is 'ecc.session.v2', '1.0', a typo, or any value other than 'ecc.session.v1'. Common when reading a recording written by a newer/older CLI, or a hand-built fixture with a guessed version.","commonSituations":"Upgrading the CLI and reading old recordings written under a different version label; downgrading; interop with a fork that uses a different version string; a test fixture with an invented schemaVersion.","solutions":["Always set schemaVersion to SESSION_SCHEMA_VERSION (exported from the module) when building snapshots.","Before reading a recording, check its schemaVersion and migrate or skip incompatible versions.","Regenerate stale recordings under the current CLI rather than patching the version string."],"exampleFix":"// before\nconst snap = { schemaVersion: '1.0', ... };\nvalidateCanonicalSnapshot(snap);\n\n// after\nconst { SESSION_SCHEMA_VERSION } = require('./canonical-session');\nconst snap = { schemaVersion: SESSION_SCHEMA_VERSION, ... };\nvalidateCanonicalSnapshot(snap);","handlingStrategy":"validation","validationCode":"const { SESSION_SCHEMA_VERSION } = require('./canonical-session');\nif (parsed.schemaVersion !== SESSION_SCHEMA_VERSION) {\n  // migrate or skip, do not validate under this code\n  return null;\n}\nvalidateCanonicalSnapshot(parsed);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set schemaVersion to the exported SESSION_SCHEMA_VERSION constant.","Gate reading old recordings on a version check and migrate explicitly.","Never guess or invent a version string."],"tags":["validation","session-schema","versioning","canonical-session"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}