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 catalog;
36pub mod context;
37pub mod cursor;
38pub mod error;
39pub mod graph;
40pub mod history;
41pub mod links;
42pub mod paths;
43pub mod planner;
44pub mod query;
45pub mod read;
46pub mod reference;
47pub mod store_index;
48pub mod translate;
49pub mod version;
50
51pub use catalog::{Surface, ToolOutcome, ToolSpec};
52pub use context::{StoreContext, Target, glob_to_like};
53pub use cursor::{decode_cursor, decode_path_cursor, encode_cursor};
54pub use error::{Result, SurfaceError};
55pub use paths::{reference_path, storage_path};
56pub use planner::SqlitePlanner;
57pub use query::{OqxResult, QueryOptions, collect_semantic_phrases, query, rewrite_query};
58pub use version::{BuildInfo, MCP_PROTOCOL_VERSION, version_info};
59
60/// The `spec/surface/VERSION` this crate implements (`major.minor`).
61pub const SPEC_VERSION: &str = "2.0";
62
63/// This crate's own version (`Cargo.toml`), for the surface's `version` tool.
64pub const VERSION: &str = env!("CARGO_PKG_VERSION");