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`], [`query`]),
5//! the document and block **reads** ([`read`]), the **history** reads
6//! ([`history`]), link health ([`links`]), the `graph` macro ([`graph`]), and
7//! the **MCP tool catalog** as a library ([`catalog`]): a table of tools with
8//! JSON-schema inputs and handlers dispatching into the store, with the
9//! error envelope of §4. Transport-agnostic — the `omgbase` binary serves
10//! [`catalog::Surface`] over MCP stdio.
11//!
12//! ```
13//! use omgbase_store::Store;
14//! use omgbase_surface::catalog::Surface;
15//! use serde_json::json;
16//!
17//! let mut store = Store::open_in_memory()?;
18//! let repo = store.create_repo("notes")?;
19//! let mut surface = Surface::new(store, &repo, None);
20//! let out = surface.call("observe", json!({ "path": "a.md", "content": "# Title\n\nFirst.\n" }));
21//! assert!(!out.is_error);
22//! let res = surface.call("query", json!({ "query": "select $title from docs" }));
23//! assert_eq!(res.body["hits"][0]["$title"], "Title");
24//! # Ok::<(), omgbase_store::Error>(())
25//! ```
26
27#![forbid(unsafe_code)]
28// The error envelope carries a code, a message and an optional JSON `data`
29// (~128 bytes); every failure is a cold path at the tool boundary, so the
30// `Result` size is not worth boxing.
31#![allow(clippy::result_large_err)]
32
33pub mod catalog;
34pub mod context;
35pub mod cursor;
36pub mod error;
37pub mod graph;
38pub mod history;
39pub mod links;
40pub mod query;
41pub mod read;
42pub mod reference;
43
44pub use catalog::{Surface, ToolOutcome, ToolSpec};
45pub use context::{StoreContext, glob_to_like};
46pub use cursor::{decode_cursor, encode_cursor};
47pub use error::{Result, SurfaceError};
48pub use query::{OqxResult, QueryOptions, collect_semantic_phrases, query};
49
50/// The `spec/surface/VERSION` this crate implements (`major.minor`).
51pub const SPEC_VERSION: &str = "1.0";