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;
24#[doc(hidden)]
25pub mod card_derive;
26#[doc(hidden)]
27pub mod card_input;
28#[doc(hidden)]
29pub mod card_queries;
30#[doc(hidden)]
31pub mod chunk_cache;
32#[doc(hidden)]
33pub mod dict;
34#[doc(hidden)]
35pub mod dictionary;
36#[doc(hidden)]
37pub mod extbuild;
38#[doc(hidden)]
39pub mod file;
40#[doc(hidden)]
41pub mod geo;
42pub mod geo3;
43#[doc(hidden)]
44pub mod header;
45#[doc(hidden)]
46pub mod index;
47
48pub mod ingest;
49pub mod iri;
50pub mod manifest;
51#[doc(hidden)]
52pub mod meta;
53#[cfg(feature = "parallel")]
54#[doc(hidden)]
55pub mod parallel;
56#[doc(hidden)]
57pub mod pyramid;
58#[doc(hidden)]
59pub mod reach;
60#[doc(hidden)]
61pub mod reader;
62#[doc(hidden)]
63pub mod reason;
64#[doc(hidden)]
65pub mod results;
66mod row;
67#[doc(hidden)]
68pub mod schema_pyramid;
69#[doc(hidden)]
70pub mod service;
71#[doc(hidden)]
72pub mod shacl;
73#[doc(hidden)]
74pub mod sparql;
75#[doc(hidden)]
76pub mod terms;
77#[doc(hidden)]
78pub mod text_index;
79#[doc(hidden)]
80pub mod tiling;
81#[doc(hidden)]
82pub mod triples;
83#[doc(hidden)]
84pub mod varint;
85
86/// Stable file-format, reader, and in-memory build API.
87pub mod format {
88    pub use crate::file::{
89        attach_build_info, plan_build_info, read_build_info, replace_metadata, verify,
90        BuildInfoPlan, ByteRange, DumpPlan, FileError, LayoutSegment, Rete, TermTriple,
91        TripleProvenance, CODEC_NONE, CODEC_ZSTD, RDF_TYPE,
92    };
93    pub use crate::header::{
94        Header, HeaderError, Section, SectionKind, CURRENT_FORMAT_VERSION, HEADER_LEN, MAGIC,
95        MIN_STABLE_READ_VERSION,
96    };
97    pub use crate::index::ScanPlan;
98    pub use crate::ingest::{
99        assemble_dataset, assemble_dataset_with, assemble_dataset_with_opts,
100        assemble_dataset_with_opts_algo, assemble_dataset_with_perms, parse, parse_quads,
101        parse_rdfxml, parse_statements, parse_statements_audited_surface, parse_turtle,
102        parse_turtle_surface, BuildStats, DeferredMetadata, FinalCounts, IngestError, IntoMetadata,
103        QuotedTripleSurface, RawQuad, RawTriple,
104    };
105}
106
107/// Stable **Dataset Card** API — both halves of a card, so that every writer
108/// (`rete build --card-file`, the browser builder, any language binding, any
109/// third-party tool) produces the same card from the same graph.
110///
111/// - The **curated** half ([`crate::card_input`]) is the write-time rules a
112///   hand-authored card document must satisfy: the reserved top level, the
113///   `theme` IRI requirement, the bounded `extra` bag.
114/// - The **derived** half ([`crate::card_derive`] + [`crate::card_queries`])
115///   is the profile computed from the
116///   graph's own statements — predicate/class histograms, vocabularies,
117///   datatypes, languages, the class-link quotient, hubs, affordance signals
118///   and the tiered starter-query library. [`card_derive::derive_card`] is the entry point
119///   for an in-memory quad slice; [`card_derive::derive_card_encoded`] for a streaming build
120///   that only has a dictionary + id-triples; [`card_derive::CardTripleSource`] for anything
121///   else.
122///
123/// Derivation is **opt-in**: it walks the graph a second time, so no build
124/// spends that pass unless the caller asks for a card.
125pub mod card {
126    pub use crate::card_derive::{
127        curated_counts_card, derive_card, derive_card_encoded, derive_card_from, load_card,
128        CardInput, CardTripleSource, ClassLink, Coherence, Creator, DatasetCard, ExampleQuery,
129        PermutationsSignal, Publisher, QuotedTriplesSignal, Signals, TextIndexSignal, Tier,
130        CARD_TOP_N, GEO_ASWKT, GEO_HASGEOMETRY, O_LITERAL, QUOTED_TRIPLE_SURFACE_RDF12,
131        QUOTED_TRIPLE_SURFACE_RDF_STAR,
132    };
133    pub use crate::card_input::{
134        canonicalize_json, check_description_len, compose_curated_card, json_depth,
135        normalize_description, normalize_extra, normalize_string_list, normalize_themes,
136        validate_curated_card, CARD_DESCRIPTION_MAX_BYTES, CARD_EXTRA_MAX_BYTES,
137        CARD_EXTRA_MAX_DEPTH, CARD_EXTRA_MAX_KEYS, CARD_EXTRA_MAX_KEY_BYTES, CURATED_CARD_FIELDS,
138        UNKNOWN_FIELD_HINT,
139    };
140    pub use crate::card_queries::{
141        audit, claim_of, generate, Claim, Finding, Observation, Recorded, Substitution, Verdict,
142    };
143}
144
145/// Stable SPARQL, graph-pattern, federation, and result API.
146pub mod query {
147    pub use crate::bgp::{Binding, PatternTerm, TriplePattern};
148    pub use crate::file::TripleProvenance;
149    pub use crate::results::{push_json_string, results_envelope_json};
150    pub use crate::service::{
151        parse_sparql_json_results, sparql_json_ask, sparql_json_results, ServiceClient,
152    };
153    pub use crate::sparql::{
154        eval_query, eval_query_reasoned, eval_query_with, eval_query_with_warnings,
155        eval_select_communities, eval_sparql, eval_sparql_reasoned, query_predicates,
156        routed_triple_pattern, summary_query_shape, warnings_json, CommunityPartial,
157        CommunitySelect, QueryOpts, QueryOutput, QueryWarning, RoutedTriplePattern, SparqlError,
158        SummaryQueryShape, WarningSeverity,
159    };
160}
161
162/// Stable byte-range and lazy-open API for local or remote `.rete` files.
163pub mod range {
164    pub use crate::block_cache::{auto_block, BlockCacheReader, DEFAULT_BLOCK, DEFAULT_CACHE_CAP};
165    pub use crate::file::{
166        read_card_and_build_info_ranged, read_card_and_build_info_with_header,
167        read_metadata_ranged, read_schema_coherence_ranged, read_schema_summary_ranged,
168        read_text_index_token_table_len_ranged, ByteRange, LayoutSegment, SearchView, SummaryView,
169    };
170    pub use crate::reader::{
171        detect_polyglot_base, CountingReader, OffsetReader, RangeReader, SliceReader,
172        POLYGLOT_DIGITS, POLYGLOT_MARKER,
173    };
174}
175
176/// Stable integrity and SHACL validation API.
177pub mod validation {
178    pub use crate::file::verify;
179    pub use crate::shacl::{
180        validate_shacl, DataGraph, GraphView, ReteGraph, Severity, ShaclError, ShaclShapes,
181        ValidationReport, ValidationResult,
182    };
183}
184
185/// Stable RDFS/OWL reasoning and schema-coherence API.
186pub mod reasoning {
187    pub use crate::file::{
188        read_schema_coherence_ranged, schema_coherence, schema_summary, TermTriple,
189    };
190    pub use crate::reason::{reason, Inconsistency, Reasoning, REASON_RULESET};
191    pub use crate::sparql::{eval_query_reasoned, eval_sparql_reasoned};
192}
193
194#[doc(hidden)]
195pub use bgp::{eval_bgp, Binding, PatternTerm, TriplePattern};
196#[doc(hidden)]
197pub use block_cache::{auto_block, BlockCacheReader, DEFAULT_BLOCK, DEFAULT_CACHE_CAP};
198#[doc(hidden)]
199pub use dict::{DictSection, DictSectionBuilder};
200#[doc(hidden)]
201pub use dictionary::{Dictionary, DictionaryBuilder};
202#[doc(hidden)]
203pub use file::{
204    attach_build_info, build_pyramid_meta, build_pyramid_meta_algo, build_pyramid_meta_with,
205    plan_build_info, read_build_info, read_card_and_build_info_ranged,
206    read_card_and_build_info_with_header, read_metadata_ranged, read_schema_coherence_ranged,
207    read_schema_summary_ranged, read_text_index_token_table_len_ranged, replace_metadata,
208    schema_classes, schema_coherence, schema_summary, split_memory_budget, verify, write_dataset,
209    write_dataset_with_metadata, write_file, BuildInfoPlan, ByteRange, DumpPlan, LayoutSegment,
210    MemoryBudget, Rete, SearchView, SummaryView, TermTriple, TripleProvenance, CODEC_NONE,
211    CODEC_ZSTD, DEFAULT_EXPORT_BUDGET_MB, DEFAULT_TILE_BUDGET, RDF_TYPE,
212};
213#[doc(hidden)]
214pub use header::{
215    Header, HeaderError, Section, SectionKind, CURRENT_FORMAT_VERSION, HEADER_LEN, MAGIC,
216    MIN_STABLE_READ_VERSION,
217};
218#[doc(hidden)]
219pub use index::{GraphIndex, GraphIndexBuilder, IndexPermutation, Pattern, PermSet, ScanPlan};
220pub use iri::{
221    iri_content_defect, sanitize_iri_content, sanitize_term, term_defect, IriDefect, IriReport,
222};
223#[doc(hidden)]
224pub use meta::{
225    CharSet, ClassNode, ClassRelation, CommunityDescriptor, LabelEntry, LevelLinks, LevelRollup,
226    PredStat, PyramidMeta,
227};
228#[doc(hidden)]
229pub use pyramid::{
230    build_dendrogram, louvain_one_level, louvain_one_level_stats, project_graph, Dendrogram, Graph,
231    LevelStats, Partition, PyramidAlgo, MAX_LOUVAIN_PASSES,
232};
233#[doc(hidden)]
234pub use reach::{batch_reach_serial, build_adjacency, reach_one};
235#[doc(hidden)]
236pub use reader::{
237    detect_polyglot_base, CountingReader, OffsetReader, RangeReader, SliceReader, POLYGLOT_DIGITS,
238    POLYGLOT_MARKER,
239};
240#[doc(hidden)]
241pub use reason::{reason, Inconsistency, Reasoning, REASON_RULESET};
242#[doc(hidden)]
243pub use results::{push_json_string, results_envelope_json};
244#[doc(hidden)]
245pub use schema_pyramid::build_schema_pyramid;
246#[doc(hidden)]
247pub use service::{parse_sparql_json_results, sparql_json_ask, sparql_json_results, ServiceClient};
248#[doc(hidden)]
249pub use shacl::{
250    validate_shacl, DataGraph, GraphView, ReteGraph, Severity, ShaclError, ShaclShapes,
251    ValidationReport, ValidationResult,
252};
253#[doc(hidden)]
254pub use sparql::{
255    eval_query, eval_query_reasoned, eval_query_with, eval_query_with_warnings,
256    eval_select_communities, eval_sparql, eval_sparql_reasoned, parse_select, query_predicates,
257    routed_triple_pattern, summary_query_shape, warnings_json, Agg, CommunityPartial,
258    CommunitySelect, FExpr, GraphTarget, GroupSpec, Op, PathAst, Plan, QueryOpts, QueryOutput,
259    QueryWarning, Rep, RoutedTriplePattern, Select, SparqlError, SummaryQueryShape,
260    WarningSeverity,
261};
262#[doc(hidden)]
263pub use terms::{NodeId, ObjectId, PredicateId, SubjectId, TermToken};
264#[doc(hidden)]
265pub use text_index::{tokenize, TextIndex, TextIndexBuilder};
266#[doc(hidden)]
267pub use tiling::{choose_round_for_budget, summarize, tile_by_community, SuperEdge, Tile};
268#[doc(hidden)]
269pub use triples::{GroupDirectory, Triple, TripleBlock, TripleBlockBuilder, ZoneMap};
rete_core/lib.rs

rete_core/
lib.rs
