omgbase-surface

The omgbase surface, Rust implementation of spec/surface: what a client sees of an omgbase repository.

• The query binding (context, query): an oqx DataContext over omgbase_store::Store — the docs / blocks / nodes / edges roots, $repo, the per-target intrinsics, reach-through and relations, the property rule (spec/properties), the row functions (text, under, within, has_edge, semantic, …) — and the §1.4 runner: { id, path } injection, distinct by projection, top-level limit/offset, keyset paging with the base64url cursor, values, the consumer scalars, error normalization to filter_invalid.
• The pushdown planner (planner, translate): the tier-3 seam of oqx (QueryPlanner / Plan / ROWS_ROOT) over the store — a simple top-level scan's pushable where conjuncts ($path and the mapped intrinsics, doc columns and scalar properties, attrs.<k> and flattened attrs via json_extract, ==/!= as null-safe IS/IS NOT, the relational ops, case-sensitive startsWith/endsWith/contains) become one SQL statement; the residual finishes in memory over the produced rows. Invisible by construction: tests/spec.rs runs every corpus-backed query case planned AND in memory and fails on any difference, and tests/conformance.rs does the same over the reference's conformance list. QueryOptions::in_memory forces the pure in-memory engine.
• Reads (read): resolve_ref, docs_read(_many), docs_read_at, nodes_get(_many) at the five resolutions, the docs_outline wire format, docs_list / docs_tree paging.
• History (history): history_node, block-grain diff, the Myers unified diff_unified (unified_diff is the pure text → text function), docs_history; changes_since is the store's.
• The tool catalog (catalog): Surface — every tool of the §4 table with its JSON-schema input, repo scoping by slug, server-side ref and heading resolution, CAS pinning, the { error, message, data?, retriable } envelope, origin.actor = "agent:mcp", a post-mutation hook that dry runs never fire. Transport-agnostic: the omgbase binary serves it over MCP stdio.

use omgbase_store::Store;
use omgbase_surface::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);
surface.call("observe", json!({ "path": "a.md", "content": "# Title\n\nFirst.\n" }));
let res = surface.call("query", json!({ "query": "select $title from docs" }));
assert_eq!(res.body["hits"][0]["$title"], "Title");
# Ok::<(), omgbase_store::Error>(())

Conformance

tests/spec.rs runs every fixture under spec/surface/cases: the corpus-backed query suites (the reference's alchemy repository observed with the fixture minter; each query planned and in memory, which must agree), reads.json (observation scripts whose read steps call the catalog in-process) and cursor.json; interop.json (§7, run by the omgbase binary's tests/interop.rs) is shape-checked and skipped. While the port runs behind the fixtures, tests/spec-passing.txt names the cases that must pass; SURFACE_SPEC_UPDATE=1 cargo test -p omgbase-surface --test spec rewrites it. SPEC_VERSION tracks spec/surface/VERSION.

License

MIT.