lustr.h¶
Ludus Wiki · API overview · Browse API
File
LUSTR cooked string dictionary format (Ludus::StringDictionaryFormat).
This header is the single contract between the dictionary writer used by cookers (Ludus::StringDictionaryWriter) and the validating runtime reader (Ludus::StringDictionary). It is owned by neither side and depends on nothing but FoundationBase. See docs/architecture/strings.md, "Cooked dictionaries and
persistence", for the design contract.
A dictionary is little-endian and tightly packed, in this order: a HEADER_BYTES header; EntryCount directory entries of DIRECTORY_ENTRY_BYTES each; BlobBytes of spelling bytes. The offsets below are the exact wire layout, derived from the field widths rather than from any host struct, so host endianness and padding never leak into files.
Version 1 dictionaries are canonical, so equal spelling sets always encode to equal bytes:
- Entry 0 is the empty spelling at blob offset 0.
- Spellings are unique and strictly increasing in unsigned byte order.
- Each spelling is followed by one zero byte. Entry i + 1 starts immediately after entry i's terminator, and the last terminator ends the blob.
- Lengths exclude the terminator and are authoritative; spellings never contain a zero byte. BYTE_POLICY_UTF8 spellings are also strict UTF-8.
Directory indices are meaningful only together with the dictionary that holds them, identified by its revision digest. They are not process-local table IDs.