[FEATURE] Add metadata RPC support for namespace index registration

[SophiaUgo]

Background

The MCP server work tracked in (#354) exposes the existing read-only agent surface over a standard transport, allowing remote clients to query namespace metadata through the existing AgentNamespace interface.

Namespace index registration, however, remains available only through the embedded NoKvFs::register_namespace_index() implementation. Remote deployments can query existing indexes, but there is currently no corresponding metadata RPC operation for registering or updating them.

As a result, namespace index registration is currently available only to embedded deployments, creating a capability gap between embedded and remote metadata services.

Relevant code

• crates/nokv-meta/src/service/agent.rs
  • register_namespace_index()
• crates/nokv-protocol/src/lib.rs
  • MetadataRpcRequest
• crates/nokv-client/src/agent.rs
• docs/development/nokv-agent.md
• bench/src/bin/yanex-agent-bench.rs

Proposed scope

Introduce a metadata RPC path for namespace index registration so that remote metadata clients can register namespace indexes in the same way embedded deployments currently can.

The implementation should preserve the existing behaviour and validation of register_namespace_index() while extending the metadata RPC surface with the necessary protocol, client, and server support.

The goal is to make the existing capability available to remote deployments without changing its semantics.

Non-goals

• No changes to the existing AgentNamespace read-only surface.
• No new write verbs for MCP or agent-facing tools.
• No changes to the behaviour of register_namespace_index().
• No changes to namespace index query behaviour.

Possible implementation

• Add a RegisterNamespaceIndex request to MetadataRpcRequest.
• Implement the corresponding server-side metadata handler.
• Add the corresponding client-side RPC support.
• Preserve the existing validation and metadata predicate fencing behaviour.
• Add integration or regression tests covering remote namespace index registration.

This proposal intentionally focuses on the metadata RPC layer. It does not propose exposing namespace index registration through the existing read-only AgentNamespace interface.

Open questions

• Should namespace index registration remain outside AgentNamespace as a metadata-management operation?
• Should the network path preserve the same validation and durability guarantees as the embedded implementation?
• Are there deployment or permission considerations that should influence how namespace index registration is exposed remotely?

Status

Proposed.

This issue is intended as a follow-up to the discussion during #354, where network namespace index registration was identified as a v1 constraint for the initial MCP implementation.

[wchwawa]

@SophiaUgo Thank you for proposing this, the RPC support for namespace index is matter when agent perform cross workspace query.

Something I would suggest: The RPC request must route by the registered namespace path, use protocol-owned wire DTOs, return Unit, and remain a metadata-client management API rather than an AgentNamespace or MCP write tool.

Would you like to work on this issue?

[SophiaUgo]

@wchwawa Yes, I’d be happy to work on this issue. Thank you for the guidance and the architectural suggestions. I’ll start by tracing the existing metadata RPC flow and follow the current implementation patterns. I may have a few questions as I work through the codebase. Thanks!

[SophiaUgo]

@wchwawa regarding the protocol-owned DTOs: would you prefer introducing a WireNamespaceIndexRegistration (with corresponding wire types for fields and rows) in nokv-protocol, or is there an existing protocol type you'd prefer this RPC to reuse?

[wchwawa]

@SophiaUgo Thanks for checking. Please introduce WireNamespaceIndexRegistration, WireNamespaceIndexField, and WireNamespaceIndexRow in nokv-protocol, while reusing the existing leaf DTOs:

• WireNamespaceFindField
• WireNamespacePredicateOp
• WireNamespaceIndexValue
• WireNamespacePredicateValue

WireNamespaceFilterCapability is not sufficient here because it does not carry sortable and facetable.

The request shape should be:

RegisterNamespaceIndex {
    registration: Box<WireNamespaceIndexRegistration>,
}

Please route it through the shared request_routing_key() using RoutingKey::Path(&registration.path). This means the registration root, not an individual row path or a control-plane shard prefix. The registration root owns the materialized catalog and row set, so routing must remain based on registration.path even if a row path matches a more-specific shard route. At the server boundary, convert the wire DTO into nokv_meta::NamespaceIndexRegistration, call the existing NoKvFs::register_namespace_index() once, and return MetadataRpcResult::Unit.

Please keep normalization, row-containment checks, value validation, and the predicate-fenced full-replace transaction in nokv-meta; the RPC/client layers should not duplicate or strengthen those semantics. Also classify this request as a metadata write so the existing metadata log-ref publication path runs. The public client API should remain an inherent MetadataClient::register_namespace_index() management method. Please do not add it to AgentNamespace or expose it as an MCP write tool.