Trait CapabilityQuery 

pub trait CapabilityQuery {
    // Required methods
    fn filter(&self, predicate: &Predicate) -> Vec<(u64, CapabilitySet)>;
    fn match_axis(
        &self,
        axis: TaxonomyAxis,
        key: &str,
        value: Option<&str>,
    ) -> Vec<(u64, CapabilitySet)>;
    fn aggregate<A>(&self, predicate: &Predicate, agg: A) -> A::Output
       where A: Aggregator;
    fn traverse(
        &self,
        start_node: u64,
        start_tag: &Tag,
        edge: EdgeKind,
        max_depth: u32,
    ) -> Vec<(u64, Tag)>;
    fn nearest<F: Fn(u64) -> Option<Duration>>(
        &self,
        predicate: &Predicate,
        rtt_lookup: F,
        n: usize,
    ) -> Vec<(u64, CapabilitySet, Option<Distance>)>;
}

Five composable operators over the capability index. This slice ships filter, match_axis, and aggregate; traverse and nearest land in slice 2 once their edge-kind / proximity-lookup contracts are scoped.

Reference impl previously lived on the legacy CapabilityIndex; that store was removed in Phase 3B of the multifold migration. Downstream consumers layer their own implementations (federated, in-memory test fixtures, the capability fold) without changing the trait surface.

Required Methods

fn filter(&self, predicate: &Predicate) -> Vec<(u64, CapabilitySet)>

Scan the index, returning (node_id, caps) pairs whose tags + metadata satisfy predicate. Ordering is implementation-defined; callers that need stable order sort the result.

fn match_axis( &self, axis: TaxonomyAxis, key: &str, value: Option<&str>, ) -> Vec<(u64, CapabilitySet)>

Type-aware match against a single axis-key. value = None matches any candidate carrying the axis-key (in either axis.key presence form or axis.key=value form); value = Some(s) requires exact value match against the axis.key=value form.

Cheaper than filter(Equals/Exists) — skips the predicate AST + the EvalContext materialization, walks each node’s tag set once.

fn aggregate<A>(&self, predicate: &Predicate, agg: A) -> A::Output

where A: Aggregator,

Run agg across every candidate satisfying predicate. Streaming: each match’s caps are observed in turn; no intermediate Vec allocation. Aggregator::finalize produces the typed output.

fn traverse( &self, start_node: u64, start_tag: &Tag, edge: EdgeKind, max_depth: u32, ) -> Vec<(u64, Tag)>

Walk capability-tag edges recursively. Starting from start_tag, follow EdgeKind-shaped parent links up to max_depth hops. Returns the chain of (node_id, tag) pairs visited, in walk order.

For EdgeKind::ForkOfParent: start_tag is a fork-of:<parent_origin_hex> tag. The walker:

1. Records the start node + tag.
2. Looks up nodes hosting causal:<parent_origin_hex> (the parent chain’s holders).
3. From each holder, reads any fork-of: tag — the grandparent — and recurses.
4. Terminates at max_depth hops OR when no fork-of: tag is found (root reached).

First parent’s host wins on ties — the index iteration order is implementation-defined; callers needing deterministic ordering across runs should snapshot the index outside this call.

max_depth = 0 returns just (start_node, start_tag) without recursing. start_node defaults to 0 if the caller doesn’t have a node id (the start tag itself is what matters for the walk).

fn nearest<F: Fn(u64) -> Option<Duration>>( &self, predicate: &Predicate, rtt_lookup: F, n: usize, ) -> Vec<(u64, CapabilitySet, Option<Distance>)>

Top-N candidates by proximity. Filters by predicate, then ranks survivors by rtt_lookup(node_id) (lower RTT first). Candidates with no RTT data sort to the back; ties broken by lex-NodeId for determinism.

n = 0 returns empty. The function clones the matching CapabilitySets into the result; callers that don’t need the caps for downstream work can use filter + their own ranking.

Distance closure decouples nearest from the substrate’s proximity-graph internals (which use a [u8; 32] node-id shape that this trait would otherwise have to know about). Same plumbing convention as Phase F’s RttLookup for placement scoring.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors