{"record":{"id":"c6b4f58147838d55","repo":"affaan-m/ECC","slug":"canonical-session-snapshot-requires-fieldpath-t","errorCode":null,"errorMessage":"Canonical session snapshot requires ${fieldPath} to be a non-empty string","messagePattern":"Canonical session snapshot requires (.+?) to be a non-empty string","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/session-adapters/canonical-session.js","lineNumber":35,"sourceCode":"    .trim()\n    .replace(/[^A-Za-z0-9._-]+/g, '_')\n    .replace(/^_+|_+$/g, '') || 'unknown';\n}\n\nfunction parseContextSeedPaths(context) {\n  if (typeof context !== 'string' || context.trim().length === 0) {\n    return [];\n  }\n\n  return context\n    .split('\\n')\n    .map(line => line.trim())\n    .filter(Boolean);\n}\n\nfunction ensureString(value, fieldPath) {\n  if (typeof value !== 'string' || value.length === 0) {\n    throw new Error(`Canonical session snapshot requires ${fieldPath} to be a non-empty string`);\n  }\n}\n\nfunction ensureStringAllowEmpty(value, fieldPath) {\n  if (typeof value !== 'string') {\n    throw new Error(`Canonical session snapshot requires ${fieldPath} to be a string`);\n  }\n}\n\nfunction ensureOptionalString(value, fieldPath) {\n  if (value !== null && value !== undefined && typeof value !== 'string') {\n    throw new Error(`Canonical session snapshot requires ${fieldPath} to be a string or null`);\n  }\n}\n\nfunction ensureBoolean(value, fieldPath) {\n  if (typeof value !== 'boolean') {\n    throw new Error(`Canonical session snapshot requires ${fieldPath} to be a boolean`);","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/lib/session-adapters/canonical-session.js#L17-L53","documentation":"Thrown by the ensureString helper inside validateCanonicalSnapshot (and the normalize*/persist functions that call it) when a required canonical-session field is missing, empty, or not a string. Used for schemaVersion, adapterId, session.id, session.kind, session.state, session.sourceTarget.type/value, and worker id/label/state/health.","triggerScenarios":"A snapshot object where schemaVersion is undefined, session.id is an empty string, a worker is missing its label, or any required string field was set to null. Commonly hit when an adapter builds a snapshot and forgets to populate a required field, or when persisting a hand-constructed object.","commonSituations":"A new adapter that does not yet set all required fields; a session record from an older CLI version missing id/kind/state; an empty string where the schema requires content; a field accidentally deleted during normalization.","solutions":["Ensure every required string field is populated with a non-empty value before calling persistCanonicalSnapshot or a normalize function.","Run validateCanonicalSnapshot(snapshot) early during adapter development to catch missing fields.","Default-coalesce required fields from available data (e.g. worker.id from a slug).","Cross-check against SESSION_SCHEMA_VERSION ('ecc.session.v1') required fields in the validator."],"exampleFix":"// before\npersistCanonicalSnapshot({ schemaVersion: '', adapterId: 'x', session: { ... } });\n\n// after\npersistCanonicalSnapshot({\n  schemaVersion: SESSION_SCHEMA_VERSION,\n  adapterId: 'x',\n  session: { id: 'real-id', kind: 'history', state: 'recorded', ... },\n  ...\n});","handlingStrategy":"validation","validationCode":"// Pre-check required non-empty string fields before persisting.\nconst required = [snapshot.schemaVersion, snapshot.adapterId, snapshot.session && snapshot.session.id];\nif (required.some(v => typeof v !== 'string' || v.length === 0)) {\n  throw new Error('Snapshot is missing required string fields');\n}\npersistCanonicalSnapshot(snapshot);","typeGuard":"function hasRequiredStrings(s) {\n  return s && typeof s === 'object'\n    && typeof s.schemaVersion === 'string' && s.schemaVersion.length > 0\n    && typeof s.adapterId === 'string' && s.adapterId.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Use the exported normalize* helpers which populate required fields.","Reference SESSION_SCHEMA_VERSION instead of hardcoding the version string.","Run validateCanonicalSnapshot during adapter development to catch gaps."],"tags":["validation","session-schema","canonical-session"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}