{"record":{"id":"279f87ad072b2eab","repo":"HKUDS/Vibe-Trading","slug":"verification-first-break","errorCode":null,"errorMessage":"{verification.first_break}","messagePattern":"\\{verification\\.first_break\\}","errorType":"error_code","errorClass":"LedgerCorruptionError","httpStatus":null,"severity":"critical","filePath":"agent/src/governance/ledger.py","lineNumber":441,"sourceCode":"            # began at genesis would report every rotated ledger as corrupt.\n            # Continuing from the newest segment is also what makes deleting a\n            # whole segment leave a detectable seam.\n            start_seq, start_prev = 1, GENESIS_PREV_HASH\n            segments = archive_segments(path)\n            if segments:\n                tail = _read_raw_records(segments[-1])\n                if tail:\n                    start_seq = int(tail[-1][\"seq\"]) + 1\n                    start_prev = str(tail[-1][\"record_hash\"])\n\n            verification, last_seq, last_hash = _walk_chain(\n                _iter_parsed_lines(existing_text.splitlines()),\n                start_seq=start_seq,\n                start_prev_hash=start_prev,\n            )\n            if not verification.ok:\n                assert verification.first_break is not None\n                raise LedgerCorruptionError(verification.first_break)\n\n            seq = last_seq + 1\n            record_hash = compute_record_hash(seq, last_hash, payload)\n            full_record: dict[str, Any] = {\n                **payload,\n                \"seq\": seq,\n                \"prev_record_hash\": last_hash,\n                \"record_hash\": record_hash,\n            }\n            line = (json.dumps(full_record, ensure_ascii=False) + \"\\n\").encode(\"utf-8\")\n\n            handle.seek(0, os.SEEK_END)\n            handle.write(line)\n            handle.flush()\n            if fsync:\n                try:\n                    os.fsync(handle.fileno())\n                except OSError as exc:","sourceCodeStart":423,"sourceCodeEnd":459,"githubUrl":"https://github.com/HKUDS/Vibe-Trading/blob/80ffdda44c5c4db0dd84d70e051cca591cea67df/agent/src/governance/ledger.py#L423-L459","documentation":"append_record verifies the existing chain before extending it; if a prior record was edited, deleted, or corrupted, it raises LedgerCorruptionError with the first break's description instead of appending onto unknown history.","triggerScenarios":"append_record on a ledger file where some line was modified, a middle record removed, or the file was truncated/corrupted (e.g. partial write, manual edit).","commonSituations":"Disk issues or interrupted writes; someone edited the .jsonl ledger by hand; buggy tooling rewrote the file losing a record.","solutions":["Quarantine the corrupt file and start a fresh ledger, preserving the original for forensics","If the tail is a truncated partial record from a crash, remove the incomplete line and re-verify (only if you can prove the break is truncation at the end)","Audit writers to ensure only append_record touches the file; enable fsync"],"exampleFix":"# before\nappend_record(ledger_path, payload)  # raises LedgerCorruptionError\n# after (quarantine + restart)\nshutil.move(ledger_path, quarantine_dir / ledger_path.name)\nappend_record(ledger_path, payload)  # fresh chain, old file preserved","handlingStrategy":"fallback","validationCode":"result = verify_chain(path)\nif not result.ok:\n    quarantine(path)  # move aside before any append","typeGuard":"def ledger_is_healthy(path) -> bool:\n    return verify_chain(path).ok","tryCatchPattern":"except LedgerCorruptionError as e: log first_break, quarantine the file, start a fresh ledger, alert — never overwrite the corrupt file","preventionTips":["Run verify_chain periodically in monitoring","Keep fsync enabled for ledger writes","Restrict file access to the ledger writer process only"],"tags":["ledger","tamper-detection","hash-chain","corruption","python"],"backgroundTag":"audit-log-tamper-detected","analyzedSha":"80ffdda44c5c4db0dd84d70e051cca591cea67df","analyzedAt":"2026-08-28T12:46:38.989Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}