crashlink.database
.cldb — CrashLink analysis database.
A companion file that sits next to a .hl/.dat bytecode file and stores only the analysis layer built on top of it: rename/comment patches (the "patch buffer"), cached decompiled pseudocode, and optional GUI session state. It never embeds the original bytecode — on load it's validated against the currently-open file by a SHA-256 hash, and refuses to apply anything if that doesn't match.
Container format (RIFF/PNG-style chunks, so unknown future tags are skippable):
magic: 4 bytes b"CLDB"
version: u16 LE (format version)
flags: u8 (bit0 = zlib-compressed body)
body: chunks, optionally zlib-compressed as a whole
chunk := tag(4 ASCII bytes) + length(u32 LE) + payload(<length> bytes)
Chunks: SRCI (source identity), ANNO (rename/comment patches), DCAC (decompiled pseudocode + opline-map cache), SESS (optional GUI session state).
Format versions: 1 is the original layout; 2 extends each DCAC entry with the rendered source's symbol spans, expression type spans and body_start, so a cached function can resolve symbols before the background redecompile finishes. Loaders accept both — a version-1 entry simply carries no spans.
class DatabaseError(Exception)
Raised for malformed/unreadable .cldb files.
class DatabaseInfo
Raw contents of a .cldb, read without validating against any bytecode file
— for standalone inspection (e.g. the crashlink db CLI).
format_version: int
source_basename: str
source_size: int
source_hash_hex: str
hl_version: int
nfunctions: int
renames: List[_RenameEntry]
comments: List[_CommentEntry]
cache_findices: List[int]
session: Optional[SessionState]
init
def __init__(format_version: int, source_basename: str, source_size: int, source_hash_hex: str, hl_version: int, nfunctions: int, renames: List[_RenameEntry], comments: List[_CommentEntry], cache_findices: List[int], session: Optional[SessionState]) -> None
class DatabaseLoadResult
renames_applied: int
renames_applied = 0
comments_applied: int
comments_applied = 0
cache: Dict[int, RenderedSource]
cache = field(default_factory=dict)
session: Optional[SessionState]
session = None
warnings: List[str]
warnings = field(default_factory=list)
matched: bool
False if the database was rejected outright (e.g. hash mismatch) —
every rejection path in load_database appends a warning and applies nothing.
init
def __init__(renames_applied: int = 0, comments_applied: int = 0, cache: Dict[int, RenderedSource] = dict(), session: Optional[SessionState] = None, warnings: List[str] = list()) -> None
class SessionState
view_mode: int
theme_name: str
open_findices: List[int]
current_tab_index: Optional[int]
init
def __init__(view_mode: int, theme_name: str, open_findices: List[int], current_tab_index: Optional[int]) -> None
hash_file
def hash_file(path: str) -> Tuple[bytes, int]
SHA-256 digest + byte size of a file on disk, read in chunks.
inspect_database
def inspect_database(path: str) -> DatabaseInfo
Read a .cldb's raw contents without needing (or validating against) the
original bytecode file — used by the crashlink db CLI.
load_database
def load_database(path: str, code: Bytecode, source_path: str) -> DatabaseLoadResult
Read a .cldb, validate it against the currently-open bytecode, and apply
renames/comments directly onto code.annotations. Applies nothing (just a
warning) if the database doesn't match the current file.
save_database
def save_database(path: str, code: Bytecode, source_path: str, class_results: Dict[str, Dict[int, Optional[str]]], opline_cache: Dict[int, Dict[int, int]], spans_cache: Optional[Dict[int, RenderedSource]] = None, session: Optional[SessionState] = None) -> None
Write a .cldb next to source_path, capturing code's annotations and the
given decompile caches. Never embeds the bytecode itself, only re-hashes it.
FLAG_COMPRESSED
FLAG_COMPRESSED = 1
FORMAT_VERSION
FORMAT_VERSION = 2
MAGIC
MAGIC = b'CLDB'
MIN_FORMAT_VERSION
MIN_FORMAT_VERSION = 1
TAG_ANNO
TAG_ANNO = b'ANNO'
TAG_DCAC
TAG_DCAC = b'DCAC'
TAG_SESS
TAG_SESS = b'SESS'
TAG_SRCI
TAG_SRCI = b'SRCI'