rete-core 0.4.0

//! Core on-disk types for the Rete graph file format.
//!
//! See `docs/SPEC.md` for the full design. This crate owns the byte-level
//! layout (header, directory, blocks) and is deliberately free of any I/O or
//! query logic so it compiles cleanly to both native and `wasm32`.

#![deny(rustdoc::broken_intra_doc_links)]
#![warn(missing_docs)]

/// The engine version, as published on crates.io.
///
/// Language bindings re-export this so a caller can always tell which engine is
/// embedded in their wheel, npm package, or bundle. That is the question behind
/// "does my install support feature X?", and it is not answerable from the
/// binding's own version, which tracks the binding. Client versions match this
/// crate's `MAJOR.MINOR` (see `scripts/sync_versions.py`) while their patch
/// component moves independently for binding-only fixes.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

#[doc(hidden)]
pub mod bgp;
#[doc(hidden)]
pub mod block_cache;
pub mod build_trace;
#[doc(hidden)]
pub mod card_derive;
#[doc(hidden)]
pub mod card_input;
#[doc(hidden)]
pub mod card_queries;
#[doc(hidden)]
pub mod chunk_cache;
#[doc(hidden)]
pub mod dict;
#[doc(hidden)]
pub mod dictionary;
#[doc(hidden)]
pub mod extbuild;
mod extbuild_sections;
mod extsort;
#[doc(hidden)]
pub mod file;
#[doc(hidden)]
pub mod geo;
pub mod geo3;
#[doc(hidden)]
pub mod header;
#[doc(hidden)]
pub mod index;

pub mod ingest;
pub mod iri;
pub mod label_index;
pub mod manifest;
#[doc(hidden)]
pub mod meta;
#[cfg(feature = "parallel")]
#[doc(hidden)]
pub mod parallel;
#[doc(hidden)]
pub mod pyramid;
mod quad;
#[doc(hidden)]
pub mod reach;
#[doc(hidden)]
pub mod reader;
#[doc(hidden)]
pub mod reason;
pub mod recard;
#[doc(hidden)]
pub mod results;
mod row;
#[doc(hidden)]
pub mod schema_pyramid;
pub mod schema_section;
#[doc(hidden)]
pub mod service;
#[doc(hidden)]
pub mod shacl;
#[doc(hidden)]
pub mod sparql;
#[doc(hidden)]
pub mod terms;
#[doc(hidden)]
pub mod text_index;
mod text_index_spill;
#[doc(hidden)]
pub mod tiling;
#[doc(hidden)]
pub mod triples;
#[doc(hidden)]
pub mod varint;
pub mod write_opts;

/// Stable file-format, reader, and in-memory build API.
pub mod format {
    pub use crate::file::{
        append_sections, attach_build_info, content_hash_parts, plan_build_info, read_build_info,
        replace_metadata, verify, BuildInfoPlan, ByteRange, DumpPlan, FileError, LayoutSegment,
        PyramidLayout, Rete, TermTriple, TripleProvenance, CODEC_NONE, CODEC_ZSTD, RDF_TYPE,
    };
    pub use crate::header::{
        Header, HeaderError, Section, SectionKind, CURRENT_FORMAT_VERSION, HEADER_LEN, MAGIC,
        MIN_STABLE_READ_VERSION,
    };
    pub use crate::index::ScanPlan;
    pub use crate::ingest::{
        assemble_dataset, assemble_dataset_with, assemble_dataset_with_layout,
        assemble_dataset_with_opts, assemble_dataset_with_opts_algo, assemble_dataset_with_perms,
        parse, parse_quads, parse_rdfxml, parse_statements, parse_statements_audited_surface,
        parse_turtle, parse_turtle_surface, BuildStats, DeferredMetadata, FinalCounts, GraphLayout,
        IngestError, IntoMetadata, QuotedTripleSurface, RawQuad, RawTriple,
    };
    pub use crate::recard::{plan_card_rewrite, rewrite_card, CardRewritePlan, REWRITE_CHUNK};
}

/// Stable **Dataset Card** API — both halves of a card, so that every writer
/// (`rete build --card-file`, the browser builder, any language binding, any
/// third-party tool) produces the same card from the same graph.
///
/// - The **curated** half ([`crate::card_input`]) is the write-time rules a
///   hand-authored card document must satisfy: the reserved top level, the
///   `theme` IRI requirement, the bounded `extra` bag.
/// - The **derived** half ([`crate::card_derive`] + [`crate::card_queries`])
///   is the profile computed from the
///   graph's own statements — predicate/class histograms, vocabularies,
///   datatypes, languages, the class-link quotient, hubs, affordance signals
///   and the tiered starter-query library. [`card_derive::derive_card`] is the entry point
///   for an in-memory quad slice; [`card_derive::derive_card_encoded`] for a streaming build
///   that only has a dictionary + id-triples; [`card_derive::CardTripleSource`] for anything
///   else.
///
/// Derivation is **opt-in**: it walks the graph a second time, so no build
/// spends that pass unless the caller asks for a card.
pub mod card {
    pub use crate::card_derive::{
        curated_counts_card, derive_card, derive_card_encoded, derive_card_from,
        derive_card_streaming, load_card, CardInput, CardTripleSource, ClassLink, Coherence,
        Creator, DatasetCard, ExampleQuery, LabelIndexSignal, PermutationsSignal, Publisher,
        QuotedTriplesSignal, Signals, StreamReport, TextIndexSignal, Tier, CARD_TOP_N, GEO_ASWKT,
        GEO_HASGEOMETRY, O_LITERAL, QUOTED_TRIPLE_SURFACE_RDF12, QUOTED_TRIPLE_SURFACE_RDF_STAR,
    };
    pub use crate::card_input::{
        canonicalize_json, check_description_len, compose_curated_card, json_depth,
        normalize_description, normalize_extra, normalize_string_list, normalize_themes,
        validate_curated_card, CARD_DESCRIPTION_MAX_BYTES, CARD_EXTRA_MAX_BYTES,
        CARD_EXTRA_MAX_DEPTH, CARD_EXTRA_MAX_KEYS, CARD_EXTRA_MAX_KEY_BYTES, CURATED_CARD_FIELDS,
        UNKNOWN_FIELD_HINT,
    };
    pub use crate::card_queries::{
        audit, audit_examples, claim_of, claim_of_query, example_query_id, generate, Claim,
        Finding, Observation, Recorded, Substitution, Verdict, STARTER_MAX_BYTES,
        STARTER_SCAN_BUDGET,
    };
}

/// Stable SPARQL, graph-pattern, federation, and result API.
pub mod query {
    pub use crate::bgp::{Binding, PatternTerm, TriplePattern};
    pub use crate::file::TripleProvenance;
    pub use crate::results::{push_json_string, results_envelope_json};
    pub use crate::service::{
        parse_sparql_json_results, sparql_json_ask, sparql_json_results, ServiceClient,
    };
    pub use crate::sparql::{
        eval_query, eval_query_partitioned, eval_query_reasoned, eval_query_with,
        eval_query_with_warnings, eval_select_communities, eval_sparql, eval_sparql_reasoned,
        partition_plan, query_predicates, routed_triple_pattern, summary_query_shape,
        warnings_json, CommunityPartial, CommunitySelect, PartitionPlan, QueryOpts, QueryOutput,
        QueryWarning, RoutedTriplePattern, SparqlError, SummaryQueryShape, WarningSeverity,
    };
}

/// Stable byte-range and lazy-open API for local or remote `.rete` files.
pub mod range {
    pub use crate::block_cache::{auto_block, BlockCacheReader, DEFAULT_BLOCK, DEFAULT_CACHE_CAP};
    pub use crate::file::{
        read_card_and_build_info_ranged, read_card_and_build_info_with_header,
        read_metadata_ranged, read_schema_coherence_ranged, read_schema_ranged,
        read_schema_summary_ranged, read_text_index_token_table_len_ranged, ByteRange,
        LayoutSegment, SearchView, SummaryView,
    };
    pub use crate::reader::{
        detect_polyglot_base, CountingReader, OffsetReader, RangeReader, SliceReader,
        POLYGLOT_DIGITS, POLYGLOT_MARKER,
    };
}

/// Stable integrity and SHACL validation API.
pub mod validation {
    pub use crate::file::verify;
    pub use crate::shacl::{
        validate_shacl, DataGraph, GraphView, ReteGraph, Severity, ShaclError, ShaclShapes,
        ValidationReport, ValidationResult,
    };
}

/// Stable RDFS/OWL reasoning and schema-coherence API.
pub mod reasoning {
    pub use crate::file::{
        read_schema_coherence_ranged, schema_coherence, schema_summary, TermTriple,
    };
    pub use crate::reason::{reason, Inconsistency, Reasoning, REASON_RULESET};
    pub use crate::sparql::{eval_query_reasoned, eval_sparql_reasoned};
}

#[doc(hidden)]
pub use bgp::{eval_bgp, Binding, PatternTerm, TriplePattern};
#[doc(hidden)]
pub use block_cache::{auto_block, BlockCacheReader, DEFAULT_BLOCK, DEFAULT_CACHE_CAP};
#[doc(hidden)]
pub use dict::{DictSection, DictSectionBuilder};
#[doc(hidden)]
pub use dictionary::{Dictionary, DictionaryBuilder};
#[doc(hidden)]
pub use file::{
    append_sections, attach_build_info, build_pyramid_meta, build_pyramid_meta_algo,
    build_pyramid_meta_layout, build_pyramid_meta_with, compute_text_index, plan_build_info,
    read_build_info, read_card_and_build_info_ranged, read_card_and_build_info_with_header,
    read_metadata_ranged, read_schema_coherence_ranged, read_schema_ranged,
    read_schema_summary_ranged, read_text_index_token_table_len_ranged, replace_metadata,
    schema_classes, schema_coherence, schema_summary, spill_threshold_for, split_memory_budget,
    verify, verify_ranged, write_dataset, write_dataset_with_metadata, write_file, BuildInfoPlan,
    ByteRange, DumpPlan, FixedOverhead, LayoutSegment, MemoryBudget, PyramidLayout, Rete,
    SearchView, SummaryView, TermTriple, TripleProvenance, CODEC_NONE, CODEC_ZSTD,
    DEFAULT_EXPORT_BUDGET_MB, DEFAULT_QUERY_BUDGET_MB, DEFAULT_TILE_BUDGET, RDF_TYPE,
};
#[doc(hidden)]
pub use header::{
    Header, HeaderError, Section, SectionKind, CURRENT_FORMAT_VERSION, HEADER_LEN, MAGIC,
    MIN_STABLE_READ_VERSION,
};
#[doc(hidden)]
pub use index::{GraphIndex, GraphIndexBuilder, IndexPermutation, Pattern, PermSet, ScanPlan};
pub use ingest::GraphLayout;
pub use iri::{
    iri_content_defect, sanitize_iri_content, sanitize_term, term_defect, IriDefect, IriReport,
};
#[doc(hidden)]
pub use label_index::{read_label_index_entries_ranged, LabelIndex};
#[doc(hidden)]
pub use meta::{
    CharSet, ClassNode, ClassRelation, CommunityDescriptor, LabelEntry, LevelLinks, LevelRollup,
    PredStat, PyramidMeta,
};
#[doc(hidden)]
pub use pyramid::{
    build_dendrogram, louvain_one_level, louvain_one_level_stats, project_graph, Dendrogram, Graph,
    LevelStats, Partition, PyramidAlgo, MAX_LOUVAIN_PASSES,
};
#[doc(hidden)]
pub use reach::{batch_reach_serial, build_adjacency, reach_one};
#[doc(hidden)]
pub use reader::{
    detect_polyglot_base, CountingReader, OffsetReader, RangeReader, SliceReader, POLYGLOT_DIGITS,
    POLYGLOT_MARKER,
};
#[doc(hidden)]
pub use reason::{reason, Inconsistency, Reasoning, REASON_RULESET};
#[doc(hidden)]
pub use results::{push_json_string, results_envelope_json};
#[doc(hidden)]
pub use schema_pyramid::build_schema_pyramid;
#[doc(hidden)]
pub use schema_section::SchemaMeta;
#[doc(hidden)]
pub use service::{parse_sparql_json_results, sparql_json_ask, sparql_json_results, ServiceClient};
#[doc(hidden)]
pub use shacl::{
    validate_shacl, DataGraph, GraphView, ReteGraph, Severity, ShaclError, ShaclShapes,
    ValidationReport, ValidationResult,
};
#[doc(hidden)]
pub use sparql::{
    eval_query, eval_query_partitioned, eval_query_reasoned, eval_query_with,
    eval_query_with_warnings, eval_select_communities, eval_sparql, eval_sparql_reasoned,
    parse_select, partition_plan, query_predicates, routed_triple_pattern, summary_query_shape,
    warnings_json, Agg, CommunityPartial, CommunitySelect, FExpr, GraphTarget, GroupSpec, Op,
    PartitionPlan, PathAst, Plan, QueryOpts, QueryOutput, QueryWarning, Rep, RoutedTriplePattern,
    Select, SparqlError, SummaryQueryShape, WarningSeverity,
};
#[doc(hidden)]
pub use terms::{NodeId, ObjectId, PredicateId, SubjectId, TermToken};
#[doc(hidden)]
pub use text_index::{
    tokenize, IntoTextIndex, TextIndex, TextIndexBuilder, TextIndexGraphs, TextIndexPredicates,
    TextIndexScope,
};
#[doc(hidden)]
pub use tiling::{choose_round_for_budget, summarize, tile_by_community, SuperEdge, Tile};
#[doc(hidden)]
pub use triples::{GroupDirectory, Triple, TripleBlock, TripleBlockBuilder, ZoneMap};