qualia_core_db/nlp/contracts/mod.rs
1//! Versioned annotation contracts and caller-buffered document views (NLP-100).
2//!
3//! **v1 ABI (honest):** in-process Rust records. Views may contain `&'static str`
4//! interned lexicon pointers and `usize` counts (native pointer width). They are
5//! **not** a C FFI layout. `#[repr(C)]` is not applied to fat-pointer views.
6//! Cross-language ABI notes belong to NLP-900.
7//!
8//! **v1 span model:** half-open UTF-8 byte [`crate::nlp::span::DocSpan`] on the
9//! immutable source. Distinct UTF-16 / code-point / grapheme / model-subtoken
10//! types and reversible alignment maps are NLP-101. Token layering (MWT) is
11//! NLP-103. Nested/discontinuous mention lists are NLP-405.
12//!
13//! **v1 state:** [`AnalysisState::Complete`] is the only constructed success
14//! state. Other variants are reserved for later processors; they are not
15//! emitted here. Oversize input on the buffered path is
16//! [`NlpContractError::SourceTooLarge`], not a `BudgetExceeded` summary.
17//!
18//! Hot-path records borrow the immutable source through `DocSpan`.
19//! Owned strings stay on the cold [`analyze_document`] adapter.
20
21mod analyze;
22mod error;
23mod views;
24
25pub use analyze::{
26 analyze_document, analyze_document_into, required_capacities, DocumentCapacities,
27};
28pub use error::{AnalysisState, BufferChannel, NlpContractError};
29pub use views::{
30 slice_source, DocumentSummary, DocumentViewBuffers, HitView, NormView, PlanView, SentenceView,
31 TokenView, NORM_INDEX_NONE, SENTENCE_ID_NONE,
32};
33
34/// Contract schema version for these view records.
35pub const ANNOTATION_CONTRACT_VERSION: u16 = 1;
36
37#[cfg(test)]
38mod tests;