{"record":{"id":"3289f9a2df0c0d29","repo":"affaan-m/ECC","slug":"capsule-invalid-entry","errorCode":"capsule.invalid_entry","errorMessage":"${errors.join('; ')}","messagePattern":"\\$\\{errors\\.join\\('; '\\)\\}","errorType":"exception","errorClass":"CapsuleError","httpStatus":null,"severity":"error","filePath":"scripts/lib/eval-harness/capsule.js","lineNumber":212,"sourceCode":"        throw new CapsuleError('capsule.payload_denied', `payload keys not allowlisted: ${dropped.join(', ')}`, { dropped });\n      }\n      const body = {\n        schema: envelope.SCHEMA_VERSION,\n        run_id: state.meta.run_id,\n        capsule_id: state.meta.capsule_id,\n        seq: state.entries.length,\n        ts: nowIso(this.clock),\n        lineage,\n        kind,\n        effect_class: effectClass,\n        harness_version: state.meta.harness_version,\n        task_family: state.meta.task_family,\n        parent_hash: state.root_hash,\n        payload: clean,\n      };\n      const entry = { ...body, entry_hash: envelope.computeEntryHash(body) };\n      const errors = envelope.validateEnvelope(entry);\n      if (errors.length > 0) throw new CapsuleError('capsule.invalid_entry', errors.join('; '));\n      const bytes = Buffer.from(canonicalJson(entry) + '\\n', 'utf8');\n      const fd = fs.openSync(this.journalPath, 'a');\n      try {\n        let offset = 0;\n        while (offset < bytes.length) {\n          const written = fs.writeSync(fd, bytes, offset, bytes.length - offset, null);\n          if (written <= 0) throw new CapsuleError('capsule.write_failed', 'journal write made no progress');\n          offset += written;\n        }\n        fs.fsyncSync(fd);\n      } finally {\n        fs.closeSync(fd);\n      }\n      // These fields remain observable for compatibility, but are never used as\n      // authoritative append state. A preopened handle always reloads above.\n      this.meta = state.meta;\n      this.lastHash = entry.entry_hash;\n      this.nextSeq = entry.seq + 1;","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/eval-harness/capsule.js#L194-L230","documentation":"After building the entry envelope (schema version, run_id, capsule_id, seq, parent hash, payload) and computing its entry hash, append() runs envelope.validateEnvelope() as a final self-check. Any structural violation is thrown as 'capsule.invalid_entry' with all violations joined by ';'. This is an internal consistency gate — it fires when the assembled entry does not satisfy the envelope schema, usually because payload redaction or metadata produced an unexpected shape.","triggerScenarios":"append() called on a capsule whose meta is incomplete (missing run_id/capsule_id) or whose state produced an out-of-spec entry — e.g. empty required fields, wrong seq type, or a redacted payload that ended up violating envelope constraints after the earlier payload checks.","commonSituations":"A capsule initialized by a different library version with a mismatched SCHEMA_VERSION; corrupted meta.json fields; a custom/patched envelope module partially applied; upgrading the library so old capsules no longer satisfy the new validator.","solutions":["Read the ';'-joined violations to identify which envelope fields fail validation.","Verify the capsule meta (run_id, capsule_id, task_family, schema version) is complete and matches the current SCHEMA_VERSION.","Re-create the capsule if it was produced by an incompatible library version; do not patch entries by hand.","Ensure you are not mixing envelope module versions (e.g. a stale patched copy of scripts/lib/eval-harness/envelope.js)."],"exampleFix":"// before: appending to a capsule created by an older schema\nawait capsule.append('fix', 'note', { msg: 'x' }); // capsule.invalid_entry\n\n// after: check compatibility first\nconst state = readCapsule(capsule.dir);\nif (state.ok && state.meta.schema !== envelope.SCHEMA_VERSION) {\n  throw new Error(`capsule schema ${state.meta.schema} != library ${envelope.SCHEMA_VERSION}; re-create capsule`);\n}\nawait capsule.append('fix', 'note', { msg: 'x' });","handlingStrategy":"try-catch","validationCode":"import { SCHEMA_VERSION } from './envelope.js';\nconst state = readCapsule(capsule.dir);\nif (!state.ok || state.meta.schema !== SCHEMA_VERSION) throw new Error('capsule/library schema mismatch; re-create capsule');","typeGuard":null,"tryCatchPattern":"try {\n  await capsule.append(lineage, kind, payload);\n} catch (e) {\n  if (e instanceof CapsuleError && e.code === 'capsule.invalid_entry') {\n    throw new Error(`entry failed envelope validation: ${e.message}; check library/capsule version compatibility`);\n  }\n  throw e;\n}","preventionTips":["Pin one version of the eval-harness library per capsule's lifetime.","Re-create capsules after major library upgrades instead of appending across versions.","Keep meta.json fields (run_id, capsule_id, task_family) intact.","Add an integration test that appends once to a freshly created capsule in CI."],"tags":["schema","integrity","envelope"],"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"}