Struct SubstrateCoordinator 

pub struct SubstrateCoordinator { /* private fields */ }

Cross-backend dispatch layer.

Owns node-to-backend location (D2), cross-backend link stamping (D3), fan-out entity/note search with RRF (D4), traversal (D5, future), and partition tolerance (D6, future).

Implementations

impl SubstrateCoordinator

pub fn new(registry: BackendRegistry) -> Self

Construct from a BackendRegistry.

pub fn with_locator_ttl(registry: BackendRegistry, ttl: Duration) -> Self

Construct from a BackendRegistry with a custom locator TTL.

pub fn single(runtime: Arc<KhiveRuntime>) -> Self

Construct with a single backend (single-backend deployment default).

pub fn registry(&self) -> &BackendRegistry

The underlying BackendRegistry.

pub fn locator_cache(&self) -> &Arc<LocatorCache>

A shared reference to the locator cache (D2).

pub fn primary_runtime(&self) -> Option<Arc<KhiveRuntime>>

The primary backend’s runtime, or None if the registry is empty.

pub fn backend_ids(&self) -> Vec<BackendId>

List all registered backend ids.

pub fn backend_count(&self) -> usize

Number of registered backends.

pub fn is_single_backend(&self) -> bool

True when this is a single-backend deployment.

pub async fn locate(&self, id: Uuid, namespace: &Namespace) -> Option<BackendId>

Resolve which backend owns the substrate node identified by id.

Namespace-agnostic per ADR-007 Rev 3: presence of the record on a backend is sufficient — the stored namespace is NOT compared to the caller namespace. The namespace parameter is used only for runtime.authorize() capability checks.

Delegates to the private locate_endpoint, which resolves in the same substrate order as get (entity/note/event, then edge — #674), so a full-UUID link endpoint locates exactly what get resolves for the same UUID.

pub fn record_created(&self, id: Uuid, backend_id: BackendId)

Prewarm the locator cache after a successful create.

Called by the SubstrateCoordinatorService so that the first locate() for a newly-created record is a cache hit rather than a backend scan.

pub fn invalidate(&self, id: Uuid)

Invalidate the locator cache entry for id.

pub async fn link_cross_backend( &self, namespace: &Namespace, source_id: Uuid, target_id: Uuid, relation: EdgeRelation, weight: f64, metadata: Option<Value>, ) -> Result<Edge, String>

Create an edge whose endpoints may be on different backends (ADR-029 D3).

Locates both source_id and target_id. When they are on different backends, the edge is written on the source backend with target_backend stamped to the target backend id. When both endpoints are on the same backend, delegates to the normal link path (no target_backend stamp).

The coordinator validates endpoints via validate_link_endpoints on the source backend’s runtime before writing the edge.

pub async fn link_cross_backend_observed( &self, namespace: &Namespace, source_id: Uuid, target_id: Uuid, relation: EdgeRelation, weight: f64, metadata: Option<Value>, resurrect: bool, ) -> Result<EdgeUpsertResult, String>

Observable, policy-aware form of Self::link_cross_backend.

pub async fn fan_out_search( &self, request: &ValidatedSearchRequest, namespace: &Namespace, ) -> (Vec<SearchHit>, Vec<NoteSearchHit>, Vec<BackendSearchResult>)

Broadcast a validated KG search request to all registered backends in parallel. One selected backend passes its ranking evidence through; multiple selected backends use outer RRF (k=60). Every filter in the request reaches the matching runtime search method on every backend.

Per-backend errors are captured in BackendSearchResult::error — a single failing backend does NOT abort the fan-out.

Authorizes each backend token against namespace alone (visible set [namespace]) — see Self::fan_out_search_with_visibility for the caller-widened-visibility variant the MCP coordinator boundary uses.

pub async fn fan_out_search_with_visibility( &self, request: &ValidatedSearchRequest, namespace: &Namespace, extra_visible: &[Namespace], ) -> (Vec<SearchHit>, Vec<NoteSearchHit>, Vec<BackendSearchResult>)

Same as Self::fan_out_search, but authorizes each backend token with an explicit extra read-visibility set (MAJ-3 fix).

extra_visible mirrors the normal registry dispatch path’s ['local'] ∪ visible_namespaces widening (khive_runtime::pack::VerbRegistry::dispatch_with_identity) — pass &[] (equivalent to Self::fan_out_search) to authorize against namespace alone, or the caller’s resolved extra-visible set to widen read visibility the same way the single-backend registry path does. An explicit namespace= request parameter intentionally narrows visibility and must be passed as &[] by the caller — this method does not itself distinguish explicit from default namespace resolution.