{"record":{"id":"0de5ff2b1dcd65f9","repo":"HKUDS/Vibe-Trading","slug":"payload-must-not-set-reserved-chain-fields-sorte","errorCode":null,"errorMessage":"payload must not set reserved chain fields: {sorted(reserved_used)}","messagePattern":"payload must not set reserved chain fields: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"agent/src/governance/ledger.py","lineNumber":410,"sourceCode":"            directory the first time the file is created (default ``True``,\n            matching ``TraceWriter``'s per-record durability guarantee — see\n            module docstring for why the compliance ledger did not have this\n            before). ``False`` issues no fsync syscalls at all.\n        dir_mode: Permission bits for the parent directory when created.\n\n    Returns:\n        The full record as written: ``payload`` merged with ``seq``,\n        ``prev_record_hash``, ``record_hash``.\n\n    Raises:\n        ValueError: ``payload`` sets a reserved chain-field key.\n        LedgerCorruptionError: The ledger's existing chain is already broken\n            (a prior record was edited or deleted) — the append is refused\n            rather than silently extended on top of unknown history.\n    \"\"\"\n    reserved_used = _CHAIN_FIELDS & payload.keys()\n    if reserved_used:\n        raise ValueError(f\"payload must not set reserved chain fields: {sorted(reserved_used)}\")\n\n    path.parent.mkdir(parents=True, exist_ok=True, mode=dir_mode)\n    created = not path.exists()\n\n    handle = open(path, \"a+b\")\n    try:\n        _lock_exclusive(handle)\n        try:\n            handle.seek(0)\n            existing_text = handle.read().decode(\"utf-8\")\n            # Sealed segments come first: after rotate_if_needed the active\n            # file starts partway through the chain, and walking it as if it\n            # 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:","sourceCodeStart":392,"sourceCodeEnd":428,"githubUrl":"https://github.com/HKUDS/Vibe-Trading/blob/80ffdda44c5c4db0dd84d70e051cca591cea67df/agent/src/governance/ledger.py#L392-L428","documentation":"append_record refuses payloads containing chain-managed fields (seq, prev_hash, hash, etc., i.e. _CHAIN_FIELDS). These are computed by the ledger itself; letting callers set them would break the hash chain's integrity model.","triggerScenarios":"Calling append_record(path, payload={..., \"seq\": 6}) or including prev_hash/hash/record_hash keys in the payload dict.","commonSituations":"Round-tripping a read record straight back into append_record without stripping chain fields; building payloads from templates that include chain metadata.","solutions":["Strip reserved keys before appending: {k: v for k, v in payload.items() if k not in _CHAIN_FIELDS}","Re-read the ledger API docs — chain fields are outputs, never inputs","Add a helper that sanitizes replayed records"],"exampleFix":"# before\nappend_record(path, payload=dict(old_record))  # old_record has seq/prev_hash/hash\n# after\nreserved = {\"seq\", \"prev_hash\", \"hash\", \"record_hash\"}\nappend_record(path, payload={k: v for k, v in old_record.items() if k not in reserved})","handlingStrategy":"validation","validationCode":"payload = {k: v for k, v in payload.items() if k not in _CHAIN_FIELDS}","typeGuard":"def is_appendable_payload(payload: dict, chain_fields: set) -> bool:\n    return not (chain_fields & payload.keys())","tryCatchPattern":"except ValueError as e: if 'reserved chain fields' in str(e): strip the listed keys and retry append_record","preventionTips":["Never feed read-back records into append_record unfiltered","Wrap append_record with a sanitizing helper","Treat chain fields as read-only outputs"],"tags":["ledger","append-only-log","reserved-fields","python"],"backgroundTag":"reserved-field-rejected","analyzedSha":"80ffdda44c5c4db0dd84d70e051cca591cea67df","analyzedAt":"2026-08-28T12:46:38.989Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}