# WDB reader ABI and indexed histories
`native/wdb.cpp` uses the installed reader to import declarations and index selected stored bytes. `src/backends/wdb.rs` copies observations into the common query engine. Rustdoc in `src/lib.rs` defines feature selection and runtime setup.
## The selected installation is an ABI boundary
The adapter uses private C++ interfaces. Exported symbols alone do not establish layout compatibility. The build checks required symbols and the reader's kernel dependency. Before a native session starts, the adapter checks the loaded reader, kernel and data-directory paths against the build selection. These checks do not qualify another ABI that happens to export the same names. The build selects a complete installed `rdi` or `xv` reader/kernel pair and checks the corresponding dependency.
The executable depends on the installed shared libraries. A missing library or incompatible C++ runtime can stop process startup before Rust runs. The adapter copies no vendor library into the crate. A short or invalid container header is rejected before SDK entry; an unknown container version is unsupported. This check does not validate the complete recording. After a failed SDK open, the adapter can compare the embedded DBG version with the expected signature referenced by the selected reader. A confirmed newer DBG is unsupported. Unknown reader signatures or container framing preserve the original failure; they do not justify a version skip. Native exceptions can become Rust errors; native faults and process termination cannot.
Each open waveform owns its native session; a clean close can leave one validated owner for the next logical open. SDK calls and destruction share one adapter lock. Immutable copied declaration tables need no SDK call. Values are copied before unlocking, and user visitors run after the lock is released. A visitor can query another waveform. The lock does not coordinate unrelated SDK users in the application.
## Storage and presentation have different representations
The SDK builds byte-history indexes for selected physical extents. On the byte path, a recognised multi-bucket event database may scan its already-created history groups on a bounded number of local threads when a large load qualifies. Small loads, other database layouts, the bit path and a missing runtime capability keep the serial scan, and the resulting indexes and query values are the same. The adapter merges exact-resolution byte cursors and applies all bytes at one tick before conversion. A declaration's complete physical extent and bit offset select its stored value. Vendor conversion supplies the logical bits. Point reads use the same indexed bytes and decoder. The SDK typed point-value transport is not interchangeable with stored memory, especially for enum values.
The older `rdi` reader can lose final updates after an intermediate return to an earlier byte value within one tick. For this reader, the adapter requests eight SDK bit indexes per physical byte and assembles the stored bytes before conversion. Point reads and traversal use the same indexes. This requires more SDK indexes and cursors than the `xv` reader's byte path. Both paths keep histories in SDK-owned storage.
Native enum tables supply codes and labels. Ordinal VHDL enums and discrete SV enums have different conversions. A table or constant does not establish that a producer recorded later changes. Real storage also needs independent qualification: the generic type bit metric can differ from the native encoder's binary64 storage.
Logic-array dimensions are flattened in vendor bit order. A top dimension whose range does not span the complete logical vector is not exposed as a single HDL bit range. Typed enum elements and unpacked members retain separate declarations where the reader supplies them. Native integral conversion preserves the complete declared width even when the text formatter omits leading zeroes. The native carrier's signed flag does not establish HDL signedness; unknown signedness stays absent. `reader_name` preserves native spelling. Logical names remove verified SV escape syntax or VHDL extended-identifier syntax; the Verilog escape flag applies only to SV names.
## Declaration support does not establish recording support
Static one-dimensional VHDL CHARACTER arrays have qualified String histories, including ascending and descending indices. The common ASCII contract preserves embedded NUL and rejects non-ASCII values. Dynamic SystemVerilog String and named Event values have no qualified read path. Selecting these declarations returns `UnsupportedSignal`. The tested read paths did not produce usable dynamic String values. This does not establish whether those values are present in an existing recording or define a WDB format limit.
Changing unsigned 129-bit enum values are also unqualified. In a tested A-to-B-to-C sequence, native reads kept the initial A code. The cause remains unresolved between recording and reading. These histories can therefore return stale values instead of an error. Successful constant values and native enum tables do not qualify changing values. Changing 65-bit X/Z enums have separate positive coverage. Neither an altered producer nor a plain bit-vector control establishes support for existing unsigned 129-bit enum recordings.
Unrecorded supported declarations remain Missing. The native waveform-presence flag can be true for a declaration with no stored updates, so it is not used to manufacture an initial value. Unsupported per-declaration layouts do not hide other histories. The adapter identifies unsupported types before requesting value constraints: an SDK constraint query can recurse through a cyclic class graph even when that class will never be read. Missing ABI symbols, inconsistent storage extents and invalid metadata remain file-level errors.
## First access builds SDK history indexes
First access to unindexed bytes loads their SDK histories, including times after the query end. A point or early stop can therefore pay the full selected-history loading cost. Every waveform drop deletes all adapter-created SDK history indexes after clearing traversal state and cursors. A later logical open of the same unchanged file reuses at most one idle native owner and its immutable declarations, and builds its histories again on first access. The adapter does not keep a second copy of the histories. A drop also releases the SDK temporary backing storage when the reader kernel provides that cleanup entry point; a kernel without it closes the owner instead of reusing it, so queries keep their ordinary behaviour. An idle owner still holds its descriptor and copied declarations. Those costs are SDK and allocator behaviour, not a fixed ceiling.
## Sequential opens reuse one validated owner
An unchanged file may be reopened without a new native reader. The adapter keeps at most one closed owner between consecutive logical opens and destroys it on a different path, on a metadata-only request and on a failed identity. A native or decode error belongs to the live reader that hit it: it makes that reader's owner unparkable for the rest of its life, and the owner is destroyed when the reader is dropped. It never destroys a different idle owner. Independent live waveforms remain independent, each with its own native reader; only the closed one waits, and no handle is shared between logical readers.
Unwinding follows the same rule. A panic that passes through the backend while it is reading native state leaves that reader's owner unparkable, even when the caller catches the panic and drops the waveform later. A panic raised by a late callback over results that the backend already completed and copied changes nothing: no native traversal or cursor is live, the copied values belong to Rust, and the interrupted common query state is not carried into a new waveform. When the caller catches that panic, the reader may still pass its owner to the next logical open.
Reuse requires the exact path bytes and the full file identity: device, inode, size, modification and change times with nanosecond precision, and a streamed SHA-256 of the whole file. The digest is read through a separate descriptor whose metadata and path metadata must agree before and after hashing. Size and modification time alone are not a freshness proof, so a same-size rewrite with a restored modification time is not reused. The digest is paid on every ordinary waveform open, a cold miss included, not only when an owner is reused: the identity must describe the file that the owner was created from.
Every logical open still checks the container header, repeats the reader-data-directory and loaded-library guards, maps metadata and gets a fresh hierarchy identity. Signatures and handles from an earlier open are rejected, and a retained owner never serves another path. Retained declaration tables, their strings and the SDK reader descriptor stay allocated while the owner waits; the parked owner is one owner, not a memory limit. The identity assumes a stable input file: a writer that changes the file during hashing or opening is not promised an atomic snapshot, and the next open simply fails the identity check or reads the new content.
A clean close releases every adapter-created SDK history index; the traversal and its cursors go first. When the reader kernel exports the storage cleanup entry point, the same close also releases the SDK temporary backing storage, so the waiting owner holds no history index and no history storage. A kernel without that entry point closes the owner instead of parking it: only reuse is lost and queries are unaffected. The next logical open of the same unchanged file reuses the owner and its declarations and creates and loads its histories again on first access. A different path, a metadata-only request or a failed identity destroys the owner. A native or decode failure makes the current owner unparkable, and its indexes are released when the reader is dropped. A failed release also keeps the owner out of the idle slot, so the ordinary close path handles it. Normal process exit destroys a parked owner on a best-effort basis while the SDK and owner locks are uncontended; an exit that finds them busy skips that cleanup.
Bit point reads seek indexed bytes and compare earlier projected values to establish `changed_at`. A constant projection can still require many predecessor lookups. Packed `logic` and `reg` arrays whose storage the adapter qualifies decode from their two stored planes instead of the vendor formatter, and a slice of one such array compares only the stored bits it depends on when the whole extent is recorded from tick zero. Other layouts, and histories that start later, keep the previous paths. Range reads with a normalized entering checkpoint seek to their start. Compositions whose intermediate values are positive whole copies of one source can use the same point state, including source-width-aligned slices. Each output preserves the source's Missing state and change times. Other value classes and compositions can still require a prefix traversal. Opening imports all native declarations, including declarations with no recorded history. It can therefore do substantially more metadata work than another format containing only logged declarations.
The common engine supplies completed-tick samples, slices, compositions, query callbacks and Trace normalization. A traversal guard releases native cursor state on completion, `Break`, error or a Rust visitor panic. Early stopping bounds delivery; it does not undo SDK opening, metadata import, history loading or the alignment and digest of a later reopen. Compare opening plus first access and the close when measuring total cost. OPB distinguishes complete requests (R), fresh prepared readers (P) and readers with an explicit query history (S).