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

omgbase_surface/
lib.rs
