Module book_export 

Bulk export of solved benchmark references into the SQLite opening book, and lookup of stored references to short-circuit repeated solves.

The book is keyed by the 18-byte canonical key (crate::state::State::canonical_key), which is byte-identical to the Python implementation’s, so the same SQLite file is portable across languages: a book built by quantik-core-rust can be read by opening_book.py and vice versa.

Orientation caveat — representative-only, on BOTH reads and writes: optimal moves are recorded as (shape, position) pairs in a specific board orientation, but the row is keyed by the canonical key, which is shared by up to eight symmetric orientations. The book does not (yet) store which symmetry transform maps the stored orientation to an arbitrary query, so moves cannot be translated across orientations. Both directions are therefore restricted to boards that are their own canonical representative (State::new(*bb).canonical_payload() == bb.to_le_bytes()):

• Writes (export_references, and crate::opening_book::OpeningBookDatabase::add_solved_position itself as defense in depth) silently skip any solved position that is not its own canonical representative. Without this guard, a row written from a rotated orientation would later be served — with wrong, possibly illegal moves — to a query on the representative board, which passes the read-side check below.
• Reads (lookup_reference) only return a hit when the query is its own canonical representative; together with the write guard this means stored moves are always in exactly the orientation of any board they are served for.

Full orientation tracking (storing the symmetry transform index so moves can be translated to any queried orientation) is the documented follow-up that would lift this restriction on both sides.

Functions

export_references

Upsert every eligible solved reference in dataset_payload (a dataset or bundle JSON artifact with a top-level positions array, each entry carrying qfen and an optional reference) into db. Positions with a null reference are skipped, and — per the module-level orientation caveat — so are solved positions that are not their own canonical representative (silently: their optimal moves are in their own orientation, which is the wrong orientation for the canonical key the row would be stored under). Returns the number of positions actually inserted.

lookup_reference

Probe the book for an exact reference at bb, reconstructing the JSON shape produced by crate::bench::reference::solve_position (minus a full principal variation — only the first optimal move is known).