{"record":{"id":"48f1e8cb170e7d48","repo":"affaan-m/ECC","slug":"unknown-state-store-schema-entity-entityname","errorCode":null,"errorMessage":"Unknown state-store schema entity: ${entityName}","messagePattern":"Unknown state-store schema entity: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/lib/state-store/schema.js","lineNumber":53,"sourceCode":"  }\n\n  cachedAjv = new Ajv({\n    allErrors: true,\n    strict: false,\n  });\n  return cachedAjv;\n}\n\nfunction getEntityValidator(entityName) {\n  if (cachedValidators.has(entityName)) {\n    return cachedValidators.get(entityName);\n  }\n\n  const schema = readSchema();\n  const definitionName = ENTITY_DEFINITIONS[entityName];\n\n  if (!definitionName || !schema.$defs || !schema.$defs[definitionName]) {\n    throw new Error(`Unknown state-store schema entity: ${entityName}`);\n  }\n\n  const validatorSchema = {\n    $schema: schema.$schema,\n    ...schema.$defs[definitionName],\n    $defs: schema.$defs,\n  };\n  const validator = getAjv().compile(validatorSchema);\n  cachedValidators.set(entityName, validator);\n  return validator;\n}\n\nfunction formatValidationErrors(errors = []) {\n  return errors\n    .map(error => `${error.instancePath || '/'} ${error.message}`)\n    .join('; ');\n}\n","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/lib/state-store/schema.js#L35-L71","documentation":"Thrown by getEntityValidator() in the state-store schema module when entityName is not a key in the ENTITY_DEFINITIONS map (session, skillRun, skillVersion, decision, installState, governanceEvent, workItem) or when the corresponding $defs entry is missing from the loaded JSON schema. The module compiles and caches an AJV validator per entity, so an unknown name is a programmer error rather than a runtime data error.","triggerScenarios":"Calling assertValidEntity('sessions', payload) (plural); calling validateEntity('task', payload) for a type that has no schema; typo like 'skilRun'; calling with a name whose definition was removed from state-store.schema.json; calling before the schema file is shipped (readSchema would have thrown earlier, but a missing $defs entry triggers this).","commonSituations":"Refactor renames an entity in the schema but callers still use the old name; a downstream feature assumes a new entity exists before the schema migration landed; copy-paste from a different version of the docs; IDE autocomplete suggests a similar-but-wrong name.","solutions":["Use one of the seven defined entity names exactly: session, skillRun, skillVersion, decision, installState, governanceEvent, workItem.","Import ENTITY_DEFINITIONS (or mirror its keys) and validate the name against Object.keys(ENTITY_DEFINITIONS) before calling.","If you genuinely need a new entity, add it to ENTITY_DEFINITIONS in scripts/lib/state-store/schema.js and add a matching $defs entry in schemas/state-store.schema.json.","Check casing: the names are camelCase, not PascalCase or kebab-case."],"exampleFix":"// before\nassertValidEntity('Sessions', row);  // -> Unknown state-store schema entity: Sessions\n\n// after\nconst ENTITY_DEFINITIONS = require('scripts/lib/state-store/schema');\n// or import the map directly if exposed\nassertValidEntity('session', row);","handlingStrategy":"type-guard","validationCode":"const ENTITY_DEFINITIONS = {\n  session: 'session', skillRun: 'skillRun', skillVersion: 'skillVersion',\n  decision: 'decision', installState: 'installState',\n  governanceEvent: 'governanceEvent', workItem: 'workItem',\n};\n\nfunction assertKnownEntity(entityName) {\n  if (!Object.prototype.hasOwnProperty.call(ENTITY_DEFINITIONS, entityName)) {\n    throw new Error(`Unsupported entity: ${entityName}. Known: ${Object.keys(ENTITY_DEFINITIONS).join(', ')}`);\n  }\n}\n\nassertKnownEntity(entityName);\nassertValidEntity(entityName, payload);","typeGuard":"const KNOWN_ENTITIES = new Set(['session','skillRun','skillVersion','decision','installState','governanceEvent','workItem']);\n\nfunction isStateStoreEntity(name) {\n  return typeof name === 'string' && KNOWN_ENTITIES.has(name);\n}","tryCatchPattern":"try {\n  assertValidEntity(entityName, payload);\n} catch (error) {\n  if (/Unknown state-store schema entity/.test(error.message)) {\n    // programmer error: log and re-throw with the list of valid names\n    throw new Error(`${error.message}. Valid: ${[...KNOWN_ENTITIES].join(', ')}`);\n  }\n  throw error;\n}","preventionTips":["Treat the entity name as a constant — never derive it from user input.","Mirror ENTITY_DEFINITIONS keys in your own code and unit-test that they stay in sync.","When you add a new entity, ship the schema $defs entry in the same commit.","Use TypeScript / JSDoc to narrow the type so the typo is caught at edit time."],"tags":["state-store","schema","validation","ajv","configuration"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}