Crate omgbase_surface 

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 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::encode_cursor;

pub use error::Result;

pub use error::SurfaceError;

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;

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 (§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.

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.

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.

Constants

SPEC_VERSION

The spec/surface/VERSION this crate implements (major.minor).