Struct Surface 

pub struct Surface { /* private fields */ }

The catalog bound to a store, a default repo and optional providers.

Implementations

impl Surface

pub fn new( store: Store, default_repo: &str, provider: Option<Box<dyn EmbeddingProvider>>, ) -> Self

A surface over store whose default repo is default_repo (an id). Mutations derive each repo’s root from its fs source.

pub fn with_profile(self, profile: Profile) -> Self

Serve profile (§4 “Profiles”): Surface::tools lists only its tools, so a host’s tools/list and its membership check follow; nothing else changes — the dispatch, the schemas and Surface::is_write_tool stay the full table’s.

pub fn profile(&self) -> Profile

The profile this surface serves.

pub fn with_provider_name(self, name: &str) -> Self

Name the configured embedding provider (embedding.provider) so a provider_unavailable error can say which one cannot rank.

pub fn with_actor(self, actor: &str) -> Self

Record actor on every write instead of ACTOR (the CLI’s human:<user> / --actor; the MCP server keeps the default).

pub fn set_actor(&mut self, actor: &str)

Change the actor of the writes that follow.

pub fn with_doc_store(self, doc_store: Box<dyn DocStore>) -> Self

Route every mutation’s file writes through doc_store regardless of the repo’s sources (a runner’s in-memory store).

pub fn with_clock(self, clock: impl FnMut() -> String + 'static) -> Self

Stamp commits with clock() instead of the wall clock.

pub fn with_mutation_hook(self, hook: impl FnMut() + 'static) -> Self

Called after every successful write (never after a dry run).

pub fn with_config(self, config: Config) -> Self

The matcher thresholds the observe tools pass through.

pub fn with_build_info(self, build_info: BuildInfo) -> Self

The serving binary’s identity for the version tool (§4, 1.4): its own version, spec/cli version, build commit and time, compiler. A library embedding keeps the default (this crate’s version, nulls).

pub fn store(&self) -> &Store

pub fn store_mut(&mut self) -> &mut Store

pub fn default_repo(&self) -> &str

pub fn tools(&self) -> Vec<ToolSpec>

The catalog this surface serves: the table filtered by its Profile (the whole table under Full).

pub fn is_write_tool(name: &str) -> bool

Whether name is a tool that can commit (a host serializes these under the writer lock of spec/sync §7; plan counts — it reads the working tree the writes race for).

pub fn call(&mut self, name: &str, args: Json) -> ToolOutcome

Run a tool: its JSON result, or the error envelope.

pub fn locate_document(&self, repo_id: &str, args: &Json) -> Result<String>

A document locator (id or path, either form) resolved to the live document’s id under the docs_update tool’s rules — the error a docs_update with that locator would raise (doc_missing with the given keys as data). The CLI’s local update <doc> resolves its target here before planning, as the reference’s requireDoc does.

pub fn call_result_with_plan( &mut self, name: &str, args: &Json, ) -> Result<(Json, Option<Json>)>

Run a write tool and hand back its result with the Plan it committed (spec/cli §4, the Receipt confirmation): a sugar tool’s or apply’s plan, whose preview.results[].ids realized through the receipt’s new_ids are the ids the CLI prints; None for a tool that planned nothing (a read, execute, an error). Not a tool: the CLI’s local seam, as the reference’s library-bound verbs hold the plan from applyEffectsDetailed.

pub fn preview_call(&mut self, name: &str, args: &Json) -> Result<Json>

The Plan a sugar tool would commit (spec/cli §3.6: every dry run is a plan) — the tool’s own ref resolution and pre-checks run, its effects are planned under the symbolic minter, nothing is written and no id is minted; the mutation hook stays quiet. apply previews its effects the same way. Not a tool: the catalog has no dry_run (4.0), a client previews with plan { effects }.

pub fn call_result(&mut self, name: &str, args: &Json) -> Result<Json>

Run a tool, returning its result or the error — every error of the effect tools carrying its corrected call (data.fix, spec/surface §4 “Teaching”, 4.4; crate::fixes).