{"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":"validation","errorClass":null,"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/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/session-adapters/canonical-session.js#L151-L187","documentation":"Canonical snapshots are versioned via schemaVersion, which must equal the library's SESSION_SCHEMA_VERSION constant. This error throws when schemaVersion is a string (that check passed) but does not match the supported version — e.g. a snapshot written by an older or newer adapter build. It prevents silently misinterpreting a differently-shaped snapshot.","triggerScenarios":"Reading a snapshot file persisted by a previous library version; hand-writing schemaVersion (or omitting the '1.0'-style value); a forward/backward incompatibility after upgrading the repo scripts.","commonSituations":"Upgrading the toolchain while old session files remain on disk; merging snapshots from different branches with divergent schema versions; typos in a hand-crafted snapshot like \"schemaVersion\": 2 (a number, or wrong string).","solutions":["Check the required version (SESSION_SCHEMA_VERSION) in canonical-session.js and the value in your snapshot","Re-run the original source through the current normalize* adapter to regenerate the snapshot with the correct schemaVersion","Migrate or delete stale on-disk snapshots from the older version","Update the library if your snapshot uses a newer schema than the installed code"],"exampleFix":"// before\n{ \"schemaVersion\": \"1\", \"adapterId\": \"dmux\" }\n// after\n{ \"schemaVersion\": \"2.0\", \"adapterId\": \"dmux\" } // match SESSION_SCHEMA_VERSION","handlingStrategy":"validation","validationCode":"if (snap.schemaVersion !== SESSION_SCHEMA_VERSION) throw new Error('schema version mismatch');","typeGuard":"const hasSupportedSchema = (v) => v?.schemaVersion === SESSION_SCHEMA_VERSION;","tryCatchPattern":"try { persistCanonicalSnapshot(snap); } catch (e) { if (/Unsupported canonical session schema version/.test(e.message)) { snap = regenerate(raw); } else throw e; }","preventionTips":["Import SESSION_SCHEMA_VERSION, never hardcode","Migrate stale snapshots after upgrades"],"tags":["validation","versioning","schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}