omgbase-surface 4.9.0

omgbase surface: the OQX query binding over the store, the document/block reads, the history reads and the MCP tool catalog as a library — Rust implementation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

//! # omgbase-surface
//!
//! The omgbase surface, Rust implementation of `spec/surface`: the OQX
//! **query binding** over [`omgbase_store::Store`] ([`context`], [`mod@query`],
//! the tier-3 pushdown [`planner`] and its [`translate`] seam, the
//! store-backed indexes nested blocks probe — [`store_index`]),
//! the dates and durations of §1.3 ([`dates`]),
//! the document and block **reads** ([`read`]), the **history** reads
//! ([`history`]), link health ([`links`]), the `graph` macro ([`graph`]), and
//! the **MCP tool catalog** as a library ([`catalog`]): a table of tools with
//! JSON-schema inputs and handlers dispatching into the store, with the
//! error envelope of §4. Transport-agnostic — the `omgbase` binary serves
//! [`catalog::Surface`] over MCP stdio.
//!
//! ```
//! use omgbase_store::Store;
//! use omgbase_surface::catalog::Surface;
//! use serde_json::json;
//!
//! let mut store = Store::open_in_memory()?;
//! let repo = store.create_repo("notes")?;
//! let mut surface = Surface::new(store, &repo, None);
//! let out = surface.call("observe", json!({ "path": "a.md", "content": "# Title\n\nFirst.\n" }));
//! assert!(!out.is_error);
//! let res = surface.call("query", json!({ "query": "select title from docs" }));
//! assert_eq!(res.body["hits"][0]["title"], "Title");
//! # Ok::<(), omgbase_store::Error>(())
//! ```

#![forbid(unsafe_code)]
// The error envelope carries a code, a message and an optional JSON `data`
// (~128 bytes); every failure is a cold path at the tool boundary, so the
// `Result` size is not worth boxing.
#![allow(clippy::result_large_err)]

pub mod arguments;
pub mod catalog;
pub mod context;
pub mod cursor;
pub mod dates;
pub mod descriptions;
pub mod error;
pub mod fixes;
pub mod graph;
pub mod history;
pub mod links;
pub mod names;
pub mod paths;
pub mod planner;
pub mod query;
pub mod read;
pub mod reference;
pub mod select;
pub mod store_index;
pub mod translate;
pub mod version;

pub use catalog::{MINIMAL_TOOLS, Profile, Surface, ToolOutcome, ToolSpec};
pub use context::{SemanticVec, StoreContext, Target, glob_to_like};
pub use cursor::{decode_cursor, decode_path_cursor, encode_cursor};
pub use error::{Result, SurfaceError};
pub use names::{UnknownNames, VocabularyCache};
pub use paths::{reference_path, storage_path};
pub use planner::SqlitePlanner;
pub use query::{
    OqxResult, QueryOptions, collect_semantic_phrases, embed_phrases, query, query_ast,
    rewrite_query,
};
pub use version::{BuildInfo, MCP_PROTOCOL_VERSION, version_info};

/// The `spec/surface/VERSION` this crate implements (`major.minor`).
pub const SPEC_VERSION: &str = "4.9";

/// This crate's own version (`Cargo.toml`), for the surface's `version` tool.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

#[cfg(test)]
mod version_tests {
    use super::SPEC_VERSION;

    /// The crate line tracks the spec it implements (AGENTS.md "Spec
    /// tracking"): `major.minor` of `Cargo.toml` equals `SPEC_VERSION`. Every
    /// other spec crate pins this; the surface had relied on `release plan`
    /// alone, so a 4.8 spec over a 4.7.x crate went unnoticed by `cargo test`.
    #[test]
    fn spec_version_matches_the_crate_line() {
        let crate_version = env!("CARGO_PKG_VERSION");
        assert!(
            crate_version.starts_with(&format!("{SPEC_VERSION}.")),
            "crate {crate_version} must track spec {SPEC_VERSION}.x"
        );
    }
}