Struct CompiledArtifact 

pub struct CompiledArtifact { /* private fields */ }

A byte engine bound to a vocabulary, shared by Arc across sequences and the FFI. Only mask_cache mutates after construction.

Implementations

impl CompiledArtifact

pub fn new( engine: RefEngine, vocab: Arc<Vocabulary>, provenance: Provenance, ) -> Result<Self, CompileError>

Binds engine to vocab under provenance, validating the result. Returns a structured error (never a partial artifact) if provenance, start state, or token-id bounds are invalid.

pub fn new_from_handle( handle: &VocabularyHandle, engine: RefEngine, provenance: Provenance, ) -> Result<Self, CompileError>

The safe public bind (naive mode): takes the canonical vocabulary from ONE VocabularyHandle, so the mask width and the id lookup always agree with each other by construction.

pub fn new_from_handle_shared( handle: &VocabularyHandle, engine: Arc<RefEngine>, provenance: Provenance, ) -> Result<Self, CompileError>

Naive binding from a vocabulary-neutral shared engine.

pub fn new_trie( engine: RefEngine, vocab: Arc<Vocabulary>, provenance: Provenance, mode: BindMode, trie: &VocabTrie, ) -> Result<Self, CompileError>

Binds engine to vocab from a borrowed trie: the eager delta walks (TrieJointByte/TrieJointClass) and the packed table (TrieJointBytePacked).

pub fn new_from_bound_trie( handle: &VocabularyHandle, engine: RefEngine, provenance: Provenance, mode: BindMode, bound: &BoundByteTrie, ) -> Result<Self, CompileError>

Binds engine to handle’s vocabulary using bound, a trie the trie cache already proved paired with SOME VocabularyHandle. Rejects bound if it was not proven paired with THIS

pub fn new_from_bound_trie_shared( handle: &VocabularyHandle, engine: Arc<RefEngine>, provenance: Provenance, mode: BindMode, bound: &BoundByteTrie, ) -> Result<Self, CompileError>

Binds a vocabulary-neutral shared engine without cloning its states or transition tables.

pub fn recommended_bind_mode( state_count: usize, mask_vocab_size: usize, bound: &BoundByteTrie, requested: BindMode, ) -> BindMode

Recommends requested as-is unless it is TrieJointBytePacked and either the packed byte budget (a safety limit) or the packed compile-latency budget (a policy target, see

pub fn mask_row_words(&self, s: StateId) -> Option<&[u32]>

The borrowed packed row for s in packed mode (no allocation), else None. The native zero-copy serving view; a Python view must hold an Arc to keep the artifact alive.

pub fn packed_mask_table_words(&self) -> Option<&[u32]>

The WHOLE packed mask matrix, borrowed flat as state_count() * words_per_row() little-endian u32 words (row s at [s*words_per_row .. (s+1)*words_per_row]), or None outside packed

pub fn packed_retained_bytes(&self) -> usize

Retained bytes of the packed mask matrix (0 when not in packed mode), for memory reporting.

pub fn index_retained_bytes(&self) -> usize

Retained bytes of the eager delta index (0 outside TrieJointByte/TrieJointClass modes), for the compiled-artifact cache’s byte-budget accounting.

pub fn engine_retained_bytes(&self) -> usize

Retained bytes of the byte engine itself (states, transitions, class table) - present in every bind mode, so the compiled-artifact cache charges it alongside the packed/index bytes

pub fn artifact_cache_charge_upper_bound(&self) -> usize

Conservative upper bound on total retained bytes, valid for ANY bind mode and stable for the artifact’s whole lifetime - safe to charge once at cache-admission time.

pub fn validate(&self) -> Result<(), CompileError>

Validates the bindings this layer owns: provenance, the start state in range, every bound token id inside the mask, and (unless the language is empty) at least one accepting state.

pub fn start(&self) -> StateId

The anchored start state.

pub fn dead(&self) -> StateId

The canonical DEAD state.

pub fn start_is_dead(&self) -> bool

Whether the start state is DEAD (the language accepts nothing). Diagnostic only.

pub fn provenance(&self) -> Provenance

The artifact’s provenance record.

pub fn vocab_size(&self) -> usize

The token-id space the mask covers (max_token_id + 1; EOS occupies a bit, never set).

pub fn state_count(&self) -> usize

The number of reference states, including DEAD. State ids span 0..state_count.

pub fn walk(&self, from: StateId, bytes: &[u8]) -> Option<StateId>

Walks bytes from from; None once DEAD (or an out-of-range state) is reached.

pub fn words_per_row(&self) -> usize

The number of packed u32 words in one mask row: ceil(vocab_size / 32).

pub fn is_accepting(&self, s: StateId) -> bool

Stopping at s yields a complete, valid instance.

pub fn can_continue(&self, s: StateId) -> bool

Some byte leads out of s toward an accepting state.

pub fn is_dead(&self, s: StateId) -> bool

s is the canonical dead sink.

pub fn eos_legal(&self, s: StateId) -> bool

EOS is legal exactly where s accepts. EOS is a side predicate, never a byte or a mask bit.

pub fn token_bytes(&self, token: TokenId) -> Option<&[u8]>

The bytes of token, or None if the id is not in the vocabulary.

pub fn token_ids(&self) -> Vec<TokenId>

The ordinary token ids bound to this artifact (EOS excluded). Order is unspecified.

pub fn bind_mode(&self) -> BindMode

How this artifact produces masks: the naive walk or a prebuilt trie index.

pub fn allowed_mask(&self, s: StateId) -> Result<Bitmask, CompileError>

The allowed ordinary-token mask at s (EOS excluded). Routes through the selected bind mode; every route is byte-identical to Naive.

pub fn allowed_ids(&self, s: StateId) -> Result<Vec<TokenId>, CompileError>

The ordinary token ids allowed at s (EOS excluded), read from the per-state mask cache so repeated queries on one state never re-walk the vocabulary. Ids are ascending.

pub fn mask_buffer_len( &self, states_len: usize, rows: Option<&[usize]>, ) -> Result<usize, CompileError>

The exact packed u32 length a mask buffer needs, all arithmetic checked (a length mismatch, a boundary row index, or an overflowing product is a structured error). Callers size from here.

pub fn write_mask_into( &self, states: &[StateId], out: &mut [u32], rows: Option<&[usize]>, ) -> Result<(), CompileError>

Fills caller-owned out with the packed masks for states (rows selects each target row, identity when None). out.len() must equal Self::mask_buffer_len; unused bits stay zero.

pub fn write_mask_le_bytes_into( &self, states: &[StateId], out: &mut [u8], rows: Option<&[usize]>, ) -> Result<(), CompileError>

Like write_mask_into, but writes little-endian bytes straight from the cached mask into out - no Vec<u32> intermediate. out.len() must equal 4 * mask_buffer_len(...).

Trait Implementations

impl Debug for CompiledArtifact

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.