omgbase_surface/lib.rs
1//! # omgbase-surface
2//!
3//! The omgbase surface, Rust implementation of `spec/surface`: the OQX
4//! **query binding** over [`omgbase_store::Store`] ([`context`], [`mod@query`],
5//! the tier-3 pushdown [`planner`] and its [`translate`] seam, the
6//! store-backed indexes nested blocks probe — [`store_index`]),
7//! the document and block **reads** ([`read`]), the **history** reads
8//! ([`history`]), link health ([`links`]), the `graph` macro ([`graph`]), and
9//! the **MCP tool catalog** as a library ([`catalog`]): a table of tools with
10//! JSON-schema inputs and handlers dispatching into the store, with the
11//! error envelope of §4. Transport-agnostic — the `omgbase` binary serves
12//! [`catalog::Surface`] over MCP stdio.
13//!
14//! ```
15//! use omgbase_store::Store;
16//! use omgbase_surface::catalog::Surface;
17//! use serde_json::json;
18//!
19//! let mut store = Store::open_in_memory()?;
20//! let repo = store.create_repo("notes")?;
21//! let mut surface = Surface::new(store, &repo, None);
22//! let out = surface.call("observe", json!({ "path": "a.md", "content": "# Title\n\nFirst.\n" }));
23//! assert!(!out.is_error);
24//! let res = surface.call("query", json!({ "query": "select title from docs" }));
25//! assert_eq!(res.body["hits"][0]["title"], "Title");
26//! # Ok::<(), omgbase_store::Error>(())
27//! ```
28
29#![forbid(unsafe_code)]
30// The error envelope carries a code, a message and an optional JSON `data`
31// (~128 bytes); every failure is a cold path at the tool boundary, so the
32// `Result` size is not worth boxing.
33#![allow(clippy::result_large_err)]
34
35pub mod arguments;
36pub mod catalog;
37pub mod context;
38pub mod cursor;
39pub mod descriptions;
40pub mod error;
41pub mod fixes;
42pub mod graph;
43pub mod history;
44pub mod links;
45pub mod names;
46pub mod paths;
47pub mod planner;
48pub mod query;
49pub mod read;
50pub mod reference;
51pub mod select;
52pub mod store_index;
53pub mod translate;
54pub mod version;
55
56pub use catalog::{MINIMAL_TOOLS, Profile, Surface, ToolOutcome, ToolSpec};
57pub use context::{SemanticVec, StoreContext, Target, glob_to_like};
58pub use cursor::{decode_cursor, decode_path_cursor, encode_cursor};
59pub use error::{Result, SurfaceError};
60pub use names::{UnknownNames, VocabularyCache};
61pub use paths::{reference_path, storage_path};
62pub use planner::SqlitePlanner;
63pub use query::{
64 OqxResult, QueryOptions, collect_semantic_phrases, embed_phrases, query, query_ast,
65 rewrite_query,
66};
67pub use version::{BuildInfo, MCP_PROTOCOL_VERSION, version_info};
68
69/// The `spec/surface/VERSION` this crate implements (`major.minor`).
70pub const SPEC_VERSION: &str = "4.7";
71
72/// This crate's own version (`Cargo.toml`), for the surface's `version` tool.
73pub const VERSION: &str = env!("CARGO_PKG_VERSION");