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 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");

Re-exports§

pub use catalog::MINIMAL_TOOLS;
pub use catalog::Profile;
pub use catalog::Surface;
pub use catalog::ToolOutcome;
pub use catalog::ToolSpec;
pub use context::SemanticVec;
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 names::UnknownNames;
pub use names::VocabularyCache;
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::embed_phrases;
pub use query::query;
pub use query::query_ast;
pub use query::rewrite_query;
pub use version::BuildInfo;
pub use version::MCP_PROTOCOL_VERSION;
pub use version::version_info;

Modules§

arguments: Argument-shape errors (spec/surface/README.md §4 “Arguments”, 3.0): every tool call is checked against its ToolSpec’s JSON schema ahead of dispatch, and a malformed call is one filter_invalid whose message names what was expected — and, for an unknown argument name, the nearest valid one. The reference (packages/core/src/mcp/arguments.ts) composes the same messages byte for byte and the surface fixtures pin them (every argument-shape error carries data.hint = "arguments").
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.
dates: Dates and durations for the query binding (spec/surface §1.3 “Dates and durations”, 4.8): the Dataview-parity function set, served as omgbase HOST functions through oqx’s call_function / call_method seam. Port of the reference’s oqx-js/dates.ts, function for function.
descriptions: The tool descriptions of the catalog (spec/surface/README.md §4) — GENERATED from spec/surface/tool-descriptions.json by scripts/gen-tool-descriptions.mjs; do not edit by hand. That file is written by the reference (SURFACE_SPEC_UPDATE=1 on packages/core/corpus/surface/spec.test.ts) from the registrations in packages/core/src/mcp/server.ts, so both engines publish the same text byte for byte; tests/spec.rs fails when either side drifts.
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).
fixes: The corrected example an error teaches with (spec/mutate §8 “fix”, spec/surface §9; mutate 3.3 / surface 4.4): data.fix is a literal corrected call — the arguments as canonical JSON (§11.5), prefixed by the tool’s name and one space only when the corrected call is to another tool — rebuilt from the request that failed, never a prose template. Both engines compose the same bytes; the reference is mutate/canonical.ts (fixRequest, fixTool, narrowedTo) and plan.ts (planningFix, replanFix).
graph: The graph neighborhood macro (spec/surface/README.md §4): compiled to an OQX follow out_links collect { from dst } / follow in_links collect { from doc } walk over the link rows (3.0 follow-up: there are no out/in relations — dst is a link’s destination document, doc its source; an absent dst, an external or phantom target, contributes no successor) run through the shared runner and shaped into { documents, links, frontier }. Port of packages/core/src/mcp/graph.ts; nothing here walks the graph itself.
history: History (spec/surface/README.md §3): blocks_history, the block-grain diff, the Myers unified docs_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.
names: Unknown names (spec/surface §1.5, 4.6; port of the reference’s oqx-js/names.ts). A query that projects, filters or orders by a name no row of the scope’s kind can carry — select path, target from links (links have dst_path), where preview != "" on blocks — used to run silently: an absent column in every row, a predicate true or false of every row. This pass judges every name the query reads (oqx’s references, AST.md §5b) against the VOCABULARY of the row kind it is read from, statically — before any row is read, so the verdict never depends on the query’s own filter — and either records a hint or refuses the query.
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 (id, path, raw, the row rule of §1.2; 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. Byte for byte the reference’s packages/core/src/mcp/reference.ts — a test below compares the two when the monorepo is present, and another parses every example the text shows.
select: Query-directed planning (spec/mutate/README.md §11.8, mutate 3.1; spec/surface 4.1): an OQX selector plus effect templates compiled into the concrete effect list the planner lowers. The selector is a producer of effects, never a second write engine — the plan that comes out has today’s shape plus a frozen Selection. The reference is packages/core/src/mutate/select.ts; every rule and message here mirrors it.
store_index: Store-backed equality indexes for the OQX engine (DataContext::index_for): when a nested block’s receiver is a ROOT SCAN (^docs, ^links, 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 == ^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.