rete_core/
lib.rs

1//! Core on-disk types for the Rete graph file format.
2//!
3//! See `docs/SPEC.md` for the full design. This crate owns the byte-level
4//! layout (header, directory, blocks) and is deliberately free of any I/O or
5//! query logic so it compiles cleanly to both native and `wasm32`.
6
7#![deny(rustdoc::broken_intra_doc_links)]
8#![warn(missing_docs)]
9
10/// The engine version, as published on crates.io.
11///
12/// Language bindings re-export this so a caller can always tell which engine is
13/// embedded in their wheel, npm package, or bundle. That is the question behind
14/// "does my install support feature X?", and it is not answerable from the
15/// binding's own version, which tracks the binding. Client versions match this
16/// crate's `MAJOR.MINOR` (see `scripts/sync_versions.py`) while their patch
17/// component moves independently for binding-only fixes.
18pub const VERSION: &str = env!("CARGO_PKG_VERSION");
19
20#[doc(hidden)]
21pub mod bgp;
22#[doc(hidden)]
23pub mod block_cache;
24pub mod build_trace;
25#[doc(hidden)]
26pub mod card_derive;
27#[doc(hidden)]
28pub mod card_input;
29#[doc(hidden)]
30pub mod card_queries;
31#[doc(hidden)]
32pub mod chunk_cache;
33#[doc(hidden)]
34pub mod dict;
35#[doc(hidden)]
36pub mod dictionary;
37#[doc(hidden)]
38pub mod extbuild;
39mod extbuild_remap;
40mod extbuild_sections;
41mod extsort;
42#[doc(hidden)]
43pub mod file;
44#[doc(hidden)]
45pub mod geo;
46pub mod geo3;
47#[doc(hidden)]
48pub mod header;
49#[doc(hidden)]
50pub mod index;
51
52pub mod ingest;
53pub mod iri;
54pub mod label_index;
55pub mod manifest;
56#[doc(hidden)]
57pub mod meta;
58#[cfg(feature = "parallel")]
59#[doc(hidden)]
60pub mod parallel;
61#[doc(hidden)]
62pub mod pyramid;
63mod quad;
64#[doc(hidden)]
65pub mod reach;
66#[doc(hidden)]
67pub mod reader;
68#[doc(hidden)]
69pub mod reason;
70pub mod recard;
71#[doc(hidden)]
72pub mod results;
73mod row;
74#[doc(hidden)]
75pub mod schema_pyramid;
76pub mod schema_section;
77#[doc(hidden)]
78pub mod service;
79#[doc(hidden)]
80pub mod shacl;
81#[doc(hidden)]
82pub mod sparql;
83#[doc(hidden)]
84pub mod terms;
85#[doc(hidden)]
86pub mod text_index;
87mod text_index_spill;
88#[doc(hidden)]
89pub mod tiling;
90#[doc(hidden)]
91pub mod triples;
92#[doc(hidden)]
93pub mod varint;
94pub mod write_opts;
95
96/// Stable file-format, reader, and in-memory build API.
97pub mod format {
98    pub use crate::file::{
99        append_sections, attach_build_info, content_hash_parts, plan_build_info, read_build_info,
100        replace_metadata, verify, BuildInfoPlan, ByteRange, DumpPlan, FileError, LayoutSegment,
101        PyramidLayout, Rete, TermTriple, TripleProvenance, CODEC_NONE, CODEC_ZSTD, RDF_TYPE,
102    };
103    pub use crate::header::{
104        Header, HeaderError, Section, SectionKind, CURRENT_FORMAT_VERSION, HEADER_LEN, MAGIC,
105        MIN_STABLE_READ_VERSION,
106    };
107    pub use crate::index::ScanPlan;
108    pub use crate::ingest::{
109        assemble_dataset, assemble_dataset_with, assemble_dataset_with_layout,
110        assemble_dataset_with_opts, assemble_dataset_with_opts_algo, assemble_dataset_with_perms,
111        parse, parse_quads, parse_rdfxml, parse_statements, parse_statements_audited_surface,
112        parse_turtle, parse_turtle_surface, BuildStats, DeferredMetadata, FinalCounts, GraphLayout,
113        IngestError, IntoMetadata, QuotedTripleSurface, RawQuad, RawTriple,
114    };
115    #[cfg(not(target_arch = "wasm32"))]
116    pub use crate::recard::commit_card_append;
117    pub use crate::recard::{
118        card_append_hash, plan_card_append, plan_card_rewrite, rewrite_card, CardAppendPlan,
119        CardRewritePlan, REWRITE_CHUNK,
120    };
121}
122
123/// Stable **Dataset Card** API — both halves of a card, so that every writer
124/// (`rete build --card-file`, the browser builder, any language binding, any
125/// third-party tool) produces the same card from the same graph.
126///
127/// - The **curated** half ([`crate::card_input`]) is the write-time rules a
128///   hand-authored card document must satisfy: the reserved top level, the
129///   `theme` IRI requirement, the bounded `extra` bag.
130/// - The **derived** half ([`crate::card_derive`] + [`crate::card_queries`])
131///   is the profile computed from the
132///   graph's own statements — predicate/class histograms, vocabularies,
133///   datatypes, languages, the class-link quotient, hubs, affordance signals
134///   and the tiered starter-query library. [`card_derive::derive_card`] is the entry point
135///   for an in-memory quad slice; [`card_derive::derive_card_encoded`] for a streaming build
136///   that only has a dictionary + id-triples; [`card_derive::CardTripleSource`] for anything
137///   else.
138///
139/// Derivation is **opt-in**: it walks the graph a second time, so no build
140/// spends that pass unless the caller asks for a card.
141pub mod card {
142    pub use crate::card_derive::{
143        curated_counts_card, derive_card, derive_card_encoded, derive_card_from,
144        derive_card_streaming, load_card, CardInput, CardTripleSource, ClassLink, Coherence,
145        Creator, DatasetCard, ExampleQuery, LabelIndexSignal, PermutationsSignal, Publisher,
146        QuotedTriplesSignal, Signals, StreamReport, TextIndexSignal, Tier, CARD_TOP_N, GEO_ASWKT,
147        GEO_HASGEOMETRY, O_LITERAL, QUOTED_TRIPLE_SURFACE_RDF12, QUOTED_TRIPLE_SURFACE_RDF_STAR,
148    };
149    pub use crate::card_input::{
150        canonicalize_json, check_description_len, compose_curated_card, json_depth,
151        normalize_description, normalize_extra, normalize_string_list, normalize_themes,
152        validate_curated_card, CARD_DESCRIPTION_MAX_BYTES, CARD_EXTRA_MAX_BYTES,
153        CARD_EXTRA_MAX_DEPTH, CARD_EXTRA_MAX_KEYS, CARD_EXTRA_MAX_KEY_BYTES, CURATED_CARD_FIELDS,
154        UNKNOWN_FIELD_HINT,
155    };
156    pub use crate::card_queries::{
157        audit, audit_examples, claim_of, claim_of_query, example_query_id, generate, Claim,
158        Finding, Observation, Recorded, Substitution, Verdict, STARTER_MAX_BYTES,
159        STARTER_SCAN_BUDGET,
160    };
161}
162
163/// Stable SPARQL, graph-pattern, federation, and result API.
164pub mod query {
165    pub use crate::bgp::{Binding, PatternTerm, TriplePattern};
166    pub use crate::file::TripleProvenance;
167    pub use crate::results::{push_json_string, results_envelope_json};
168    pub use crate::service::{
169        parse_sparql_json_results, sparql_json_ask, sparql_json_results, ServiceClient,
170    };
171    pub use crate::sparql::{
172        eval_query, eval_query_partitioned, eval_query_reasoned, eval_query_with,
173        eval_query_with_warnings, eval_select_communities, eval_sparql, eval_sparql_reasoned,
174        partition_plan, query_predicates, routed_triple_pattern, summary_query_shape,
175        warnings_json, CommunityPartial, CommunitySelect, PartitionPlan, QueryOpts, QueryOutput,
176        QueryWarning, RoutedTriplePattern, SparqlError, SummaryQueryShape, WarningSeverity,
177    };
178}
179
180/// Stable byte-range and lazy-open API for local or remote `.rete` files.
181pub mod range {
182    pub use crate::block_cache::{auto_block, BlockCacheReader, DEFAULT_BLOCK, DEFAULT_CACHE_CAP};
183    pub use crate::file::{
184        read_card_and_build_info_ranged, read_card_and_build_info_with_header,
185        read_metadata_ranged, read_schema_coherence_ranged, read_schema_ranged,
186        read_schema_summary_ranged, read_text_index_token_table_len_ranged, ByteRange,
187        LayoutSegment, SearchView, SummaryView,
188    };
189    pub use crate::reader::{
190        detect_polyglot_base, CountingReader, OffsetReader, RangeReader, SliceReader,
191        POLYGLOT_DIGITS, POLYGLOT_MARKER,
192    };
193}
194
195/// Stable integrity and SHACL validation API.
196pub mod validation {
197    pub use crate::file::verify;
198    pub use crate::shacl::{
199        validate_shacl, DataGraph, GraphView, ReteGraph, Severity, ShaclError, ShaclShapes,
200        ValidationReport, ValidationResult,
201    };
202}
203
204/// Stable RDFS/OWL reasoning and schema-coherence API.
205pub mod reasoning {
206    pub use crate::file::{
207        read_schema_coherence_ranged, schema_coherence, schema_summary, TermTriple,
208    };
209    pub use crate::reason::{reason, Inconsistency, Reasoning, REASON_RULESET};
210    pub use crate::sparql::{eval_query_reasoned, eval_sparql_reasoned};
211}
212
213#[doc(hidden)]
214pub use bgp::{eval_bgp, Binding, PatternTerm, TriplePattern};
215#[doc(hidden)]
216pub use block_cache::{auto_block, BlockCacheReader, DEFAULT_BLOCK, DEFAULT_CACHE_CAP};
217#[doc(hidden)]
218pub use dict::{DictSection, DictSectionBuilder};
219#[doc(hidden)]
220pub use dictionary::{Dictionary, DictionaryBuilder};
221#[doc(hidden)]
222pub use file::{
223    append_sections, attach_build_info, build_pyramid_meta, build_pyramid_meta_algo,
224    build_pyramid_meta_layout, build_pyramid_meta_with, compute_text_index, plan_build_info,
225    read_build_info, read_card_and_build_info_ranged, read_card_and_build_info_with_header,
226    read_metadata_ranged, read_schema_coherence_ranged, read_schema_ranged,
227    read_schema_summary_ranged, read_text_index_token_table_len_ranged, replace_metadata,
228    schema_classes, schema_coherence, schema_summary, spill_threshold_for, split_memory_budget,
229    verify, verify_ranged, write_dataset, write_dataset_with_metadata, write_file, BuildInfoPlan,
230    ByteRange, DumpPlan, FixedOverhead, LayoutSegment, MemoryBudget, PyramidLayout, Rete,
231    SearchView, SummaryView, TermTriple, TripleProvenance, CODEC_NONE, CODEC_ZSTD,
232    DEFAULT_EXPORT_BUDGET_MB, DEFAULT_QUERY_BUDGET_MB, DEFAULT_TILE_BUDGET, RDF_TYPE,
233};
234#[doc(hidden)]
235pub use header::{
236    Header, HeaderError, Section, SectionKind, CURRENT_FORMAT_VERSION, HEADER_LEN, MAGIC,
237    MIN_STABLE_READ_VERSION,
238};
239#[doc(hidden)]
240pub use index::{GraphIndex, GraphIndexBuilder, IndexPermutation, Pattern, PermSet, ScanPlan};
241pub use ingest::GraphLayout;
242pub use iri::{
243    iri_content_defect, sanitize_iri_content, sanitize_term, term_defect, IriDefect, IriReport,
244};
245#[doc(hidden)]
246pub use label_index::{read_label_index_entries_ranged, LabelIndex};
247#[doc(hidden)]
248pub use meta::{
249    CharSet, ClassNode, ClassRelation, CommunityDescriptor, LabelEntry, LevelLinks, LevelRollup,
250    PredStat, PyramidMeta,
251};
252#[doc(hidden)]
253pub use pyramid::{
254    build_dendrogram, louvain_one_level, louvain_one_level_stats, project_graph, Dendrogram, Graph,
255    LevelStats, Partition, PyramidAlgo, MAX_LOUVAIN_PASSES,
256};
257#[doc(hidden)]
258pub use reach::{batch_reach_serial, build_adjacency, reach_one};
259#[doc(hidden)]
260pub use reader::{
261    detect_polyglot_base, CountingReader, OffsetReader, RangeReader, SliceReader, POLYGLOT_DIGITS,
262    POLYGLOT_MARKER,
263};
264#[doc(hidden)]
265pub use reason::{reason, Inconsistency, Reasoning, REASON_RULESET};
266#[doc(hidden)]
267pub use results::{push_json_string, results_envelope_json};
268#[doc(hidden)]
269pub use schema_pyramid::build_schema_pyramid;
270#[doc(hidden)]
271pub use schema_section::SchemaMeta;
272#[doc(hidden)]
273pub use service::{parse_sparql_json_results, sparql_json_ask, sparql_json_results, ServiceClient};
274#[doc(hidden)]
275pub use shacl::{
276    validate_shacl, DataGraph, GraphView, ReteGraph, Severity, ShaclError, ShaclShapes,
277    ValidationReport, ValidationResult,
278};
279#[doc(hidden)]
280pub use sparql::{
281    eval_query, eval_query_partitioned, eval_query_reasoned, eval_query_with,
282    eval_query_with_warnings, eval_select_communities, eval_sparql, eval_sparql_reasoned,
283    parse_select, partition_plan, query_predicates, routed_triple_pattern, summary_query_shape,
284    warnings_json, Agg, CommunityPartial, CommunitySelect, FExpr, GraphTarget, GroupSpec, Op,
285    PartitionPlan, PathAst, Plan, QueryOpts, QueryOutput, QueryWarning, Rep, RoutedTriplePattern,
286    Select, SparqlError, SummaryQueryShape, WarningSeverity,
287};
288#[doc(hidden)]
289pub use terms::{NodeId, ObjectId, PredicateId, SubjectId, TermToken};
290#[doc(hidden)]
291pub use text_index::{
292    tokenize, IntoTextIndex, TextIndex, TextIndexBuilder, TextIndexGraphs, TextIndexPredicates,
293    TextIndexScope,
294};
295#[doc(hidden)]
296pub use tiling::{choose_round_for_budget, summarize, tile_by_community, SuperEdge, Tile};
297#[doc(hidden)]
298pub use triples::{GroupDirectory, Triple, TripleBlock, TripleBlockBuilder, ZoneMap};
rete_core/lib.rs

rete_core/
lib.rs
