Crate omgbase_surface

Expand description

§omgbase-surface

The omgbase surface, Rust implementation of spec/surface: the OQX query binding over omgbase_store::Store (context, query, the tier-3 pushdown planner and its translate seam, the store-backed indexes nested blocks probe — store_index), 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");

Re-exports§

pub use catalog::Surface;
pub use catalog::ToolOutcome;
pub use catalog::ToolSpec;
pub use context::StoreContext;
pub use context::Target;
pub use context::glob_to_like;
pub use cursor::decode_cursor;
pub use cursor::decode_path_cursor;
pub use cursor::encode_cursor;
pub use error::Result;
pub use error::SurfaceError;
pub use paths::reference_path;
pub use paths::storage_path;
pub use planner::SqlitePlanner;
pub use query::OqxResult;
pub use query::QueryOptions;
pub use query::collect_semantic_phrases;
pub use query::query;
pub use query::rewrite_query;
pub use version::BuildInfo;
pub use version::MCP_PROTOCOL_VERSION;
pub use version::version_info;

Modules§

catalog: The MCP tool catalog (spec/surface/README.md §4) as a library: a table of ToolSpecs (name, JSON-schema input, description) and one dispatch (Surface::call) that runs a tool against the store and returns its JSON result or the error envelope. Transport-agnostic — a server wraps each outcome in one text content item. Port of packages/core/src/mcp/server.ts.
context: The query binding (spec/surface/README.md §1): a DataContext over the store, so the oqx in-memory engine reproduces the whole OQX surface — roots, intrinsics, reach-through, structural relations, the edge graph, the row functions — without a bespoke compiler. Port of packages/core/src/oqx-js/context.ts.
cursor: Keyset cursors (spec/surface/README.md §1.4): base64url(JSON [parts...]), one encoding for every paged surface — [path, id] for query, [path] for docs_list/docs_tree. Decoding requires exactly arity string parts; anything else is SurfaceError::cursor_invalid naming the surface.
error: The error envelope (spec/surface/README.md §4): { error, message, data?, retriable }. Every failure a tool can report is one of these; spec/mutate §8 codes come through unchanged, an OQX or cursor failure is filter_invalid, and anything unexpected is repo_not_found with its message (§9, pinned).
graph: The graph neighborhood macro (spec/surface/README.md §4): compiled to an OQX follow doc.out / doc.in walk run through the shared runner and shaped into { documents, edges, frontier }. Port of packages/core/src/mcp/graph.ts; nothing here walks the graph itself.
history: History (spec/surface/README.md §3): history_node, the block-grain diff, the Myers unified diff_unified over the two revisions’ reconstructed files (§3; positional before 1.1, §9), docs_history. Port of packages/core/src/graph/history.ts; changes_since is the store’s.
links: Link health (spec/graph §6, spec/surface §4 links_stale): dangling internal links are the open edges whose dst_node is a phantom:; external edges are counted, never verified. Port of packages/core/src/graph/link-health.ts.
paths: The two path forms (spec/surface §1 “Paths”, 2.0). The store keeps a document’s path in git’s repo-relative form (projects/oqx.md: docs.path, the adapters, every store/sync spec), while every reference an author writes — a Markdown link, a wikilink, a frontmatter relation — is root-absolute (/projects/oqx.md). The surface speaks the reference form: every path a query, a tool or a CLI verb RETURNS is /-rooted, and every path they ACCEPT tolerates both forms. These two functions are the whole conversion; the store never sees a rooted path and the surface never hands out a bare one. Port of packages/core/src/core/paths.ts.
planner: The tier-3 pushdown planner: reduces the row set a query scans by translating its pushable top-level where conjuncts into ONE SQL statement against the store, then handing the produced rows (plus the untranslatable residual) back to the in-memory engine to finish. Port of packages/core/src/oqx-js/planner.ts over the oqx seam (QueryPlanner, Plan, oqx::partition_pushable, oqx::residual_query, oqx::ROWS_ROOT).
query: The runner (spec/surface/README.md §1.4): parse the source, rewrite the row functions to $self methods, run it through the engine over the store context, and shape the engine’s result into the surface’s OqxResult (lean { id, path, … } hits, keyset paging, the consumer scalars). Port of packages/core/src/oqx-js/run.ts.
read: Reads (spec/surface/README.md §2): ref resolution, whole-document reads, block hydration at a resolution, the outline wire format, and the two path-ordered list surfaces. Port of packages/core/src/core/read/*. Result keys follow the reference’s spelling (docId, renderedHashMatch, …) — the fixtures are generated from it.
reference: The query_syntax text (spec/surface/README.md §4: reference prose, unpinned). A condensed distillation of docs/query-language.md.
store_index: Store-backed equality indexes for the OQX engine (DataContext::index_for): when a nested block’s receiver is a ROOT SCAN (^docs, ^edges, a bare docs at the root scope — a lazy crate::context marker) and its correlated or constant equality is on a column or property SQLite can look up — where $path == ^^$path, where customer == ^$path, where $dst == ^$id, where type == "order" — the probe runs ONE cached statement against the store’s indexes instead of materializing every row of the target and hashing it. The rows come back exactly as the root scan constructs them (same columns, same __path, same tag, same (path, id) order) under the same live-row and repo guards as the planner’s, so every intrinsic and relation keeps working downstream and the result cannot differ from the scan — only the work does. Port of packages/core/src/oqx-js/store-index.ts.
translate: Semantics-faithful OQX expression → SQLite translator: the pushdown seam of the tier-3 planner (crate::planner). Port of packages/core/src/oqx-js/sql/translate.ts.
version: The version tool (spec/surface §4, 1.4): which engine and which versions — the serving binary’s own, every component crate’s, the spec versions they were built against, the database schema, the MCP protocol, the runtime, the build’s commit and time.

Constants§

SPEC_VERSION: The spec/surface/VERSION this crate implements (major.minor).
VERSION: This crate’s own version (Cargo.toml), for the surface’s version tool.