omgbase-surface 1.0.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

# omgbase-surface

The omgbase **surface**, Rust implementation of [`spec/surface`](../../spec/surface/README.md):
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`. Every query runs on the in-memory engine
  (the pushdown planner is a follow-up; a planner must be invisible).
- **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 positional
  `diff_unified`, `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.

```rust
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), `reads.json` (observation scripts whose `read` steps
call the catalog in-process) and `cursor.json`. 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.