Skip to main content

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'