Struct StateletClient 

pub struct StateletClient<T> { /* private fields */ }

Statelet key-value store RPC service.

All keys and values are raw bytes. Column families (cf) are identified by a uint32 id. Use USER_COLUMN_FAMILY_ID = 0 for the default user CF.

Implementations

impl StateletClient<Channel>

pub async fn connect<D>(dst: D) -> Result<Self, Error>

where D: TryInto<Endpoint>, D::Error: Into<StdError>,

Attempt to create a new client by connecting to a given endpoint.

impl<T> StateletClient<T>

where T: GrpcService<BoxBody>, T::Error: Into<StdError>, T::ResponseBody: Body<Data = Bytes> + Send + 'static, <T::ResponseBody as Body>::Error: Into<StdError> + Send,

pub fn new(inner: T) -> Self

pub fn with_origin(inner: T, origin: Uri) -> Self

pub fn with_interceptor<F>( inner: T, interceptor: F, ) -> StateletClient<InterceptedService<T, F>>

where F: Interceptor, T::ResponseBody: Default, T: Service<Request<BoxBody>, Response = Response<<T as GrpcService<BoxBody>>::ResponseBody>>, <T as Service<Request<BoxBody>>>::Error: Into<StdError> + Send + Sync,

pub fn send_compressed(self, encoding: CompressionEncoding) -> Self

Compress requests with the given encoding.

This requires the server to support it otherwise it might respond with an error.

pub fn accept_compressed(self, encoding: CompressionEncoding) -> Self

Enable decompressing responses.

pub fn max_decoding_message_size(self, limit: usize) -> Self

Limits the maximum size of a decoded message.

Default: 4MB

pub fn max_encoding_message_size(self, limit: usize) -> Self

Limits the maximum size of an encoded message.

Default: usize::MAX

pub async fn ping( &mut self, request: impl IntoRequest<PingRequest>, ) -> Result<Response<PingResponse>, Status>

Liveness check.

pub async fn put( &mut self, request: impl IntoRequest<PutRequest>, ) -> Result<Response<PutResponse>, Status>

Write a single key-value pair.

pub async fn get( &mut self, request: impl IntoRequest<GetRequest>, ) -> Result<Response<GetResponse>, Status>

Read the value for a key. Returns found=false when the key does not exist.

pub async fn delete( &mut self, request: impl IntoRequest<DeleteRequest>, ) -> Result<Response<DeleteResponse>, Status>

Delete a key.

pub async fn merge( &mut self, request: impl IntoRequest<MergeRequest>, ) -> Result<Response<MergeResponse>, Status>

Merge an operand into the existing value (requires a MergeOperator on the CF).

pub async fn batch_write( &mut self, request: impl IntoRequest<BatchWriteRequest>, ) -> Result<Response<BatchWriteResponse>, Status>

Atomically apply a batch of Put/Delete/Merge operations.

pub async fn conditional_batch_write( &mut self, request: impl IntoRequest<ConditionalBatchWriteRequest>, ) -> Result<Response<ConditionalBatchWriteResponse>, Status>

Atomically apply one conditional gate mutation plus plain trailing Put/Delete/Merge operations. The whole batch commits only when the gate predicate holds at the shard leader.

pub async fn conditional_set( &mut self, request: impl IntoRequest<ConditionalSetRequest>, ) -> Result<Response<ConditionalSetResponse>, Status>

Atomic set-if-(not-)exists (compare-and-swap on key presence) for a single key. The existence check and the write commit as one indivisible step at the owning shard leader, backing Redis SET … NX/XX, SETNX and GETSET through the gateway.

pub async fn batch_get( &mut self, request: impl IntoRequest<BatchGetRequest>, ) -> Result<Response<BatchGetResponse>, Status>

Read multiple keys in a single round-trip.

pub async fn text_put( &mut self, request: impl IntoRequest<TextPutRequest>, ) -> Result<Response<TextPutResponse>, Status>

Insert text: gateway embeds text, then stores KV metadata + vector.

pub async fn text_search( &mut self, request: impl IntoRequest<TextSearchRequest>, ) -> Result<Response<TextSearchResponse>, Status>

Search by text: gateway embeds query, runs vector search, hydrates KV metadata.

pub async fn text_graph_put( &mut self, request: impl IntoRequest<TextGraphPutRequest>, ) -> Result<Response<TextGraphPutResponse>, Status>

Embed text → GraphAddNode (with vector + properties) + optional GraphAddEdge.

pub async fn text_graph_search( &mut self, request: impl IntoRequest<TextGraphSearchRequest>, ) -> Result<Response<TextGraphSearchResponse>, Status>

Embed query → GraphSearch → hydrate node properties.

pub async fn text_graph_query_edges( &mut self, request: impl IntoRequest<TextGraphQueryEdgesRequest>, ) -> Result<Response<TextGraphQueryEdgesResponse>, Status>

Query edges for a graph node (delegates to GraphQueryEdges).

pub async fn text_graph_get_node( &mut self, request: impl IntoRequest<TextGraphGetNodeRequest>, ) -> Result<Response<TextGraphGetNodeResponse>, Status>

Get a graph node’s properties by ID.

pub async fn embed( &mut self, request: impl IntoRequest<EmbedRequest>, ) -> Result<Response<EmbedResponse>, Status>

── Embedding primitive (gateway-only) ─────────────────────────────────

Pure text→vector: embed each text with the gateway’s resident dense model and return the raw vectors, storing NOTHING. Lets a caller that owns its own storage pipeline (its own node ids, properties, graph structure) get statelet-local vectors and then write them via VectorPut / GraphAddNode — instead of depending on an external embedding API or ceding node construction to TextGraphPut. The model runs once, in the gateway.

pub async fn triple_put( &mut self, request: impl IntoRequest<TriplePutRequest>, ) -> Result<Response<TriplePutResponse>, Status>

── Triple store (epic #1432) ──────────────────────────────────────────

Write one (s, p, o, valid_from, valid_to, props?) triple into the per-graph triple CF t:{graph} (provisioned as an ordinary CfType::User CF). Terms are interned through the on-CF dictionary (T2ID/ID2T/META) and the three permutations (SPO authoritative + POS/OSP index-only), the LIT row (for a literal object), the dictionary rows and the bumped META high-water are all written in ONE atomic WriteBatch (one Raft entry), so the permutations and dictionary never diverge across a crash. Returns the interned subject/predicate/object ids. Gateway-only (Phase 1 of #1432).

pub async fn triple_query( &mut self, request: impl IntoRequest<TripleQueryRequest>, ) -> Result<Response<TripleQueryResponse>, Status>

Query one bound/unbound triple pattern (s?, p?, o?, as_of?) against the per-graph triple CF t:{graph}. The handler selects the SPO/POS/OSP index whose leading columns are bound (the 6-pattern BGP table), seek(prefix)s and iterates-while-prefix over the merged memtable+.sst view, applies the inverted-valid_from newest-wins ordering plus the optional as_of temporal filter, hides tombstoned triples, and resolves each TermId back to its string through the on-CF ID2T dictionary. Gateway-only (Phase 2 of #1432).

pub async fn triple_bgp( &mut self, request: impl IntoRequest<TripleBgpRequest>, ) -> Result<Response<TripleBgpResponse>, Status>

Evaluate a basic graph pattern (BGP): a list of triple patterns sharing variables. The handler runs a left-deep, selectivity-ordered index-nested-loop join (INLJ) over the Phase-2 single-pattern primitive — it orders patterns most-bound-first, binds variables left-to-right, and evaluates each pattern as a Phase-2 prefix scan parameterized by the current binding. Returns one row of variable→value bindings per solution. No cost-based planner in v1 (documented limitation; structural selectivity only). Gateway-only (Phase 3 of #1432).

pub async fn triple_link( &mut self, request: impl IntoRequest<TripleLinkRequest>, ) -> Result<Response<TripleLinkResponse>, Status>

Cross-modal linkage between the vector index (HNSW/SpFresh) and the triple store, exploiting the shared id space (term-id == node-id, no remap). Three modes generalize the existing temporal_join pattern:

1. VECTOR_TO_TRIPLE: HNSW.search(q,k) → node ids → SPO prefix-scan (id, P?, ?) to filter/re-rank by symbolic structure.
2. TRIPLE_TO_VECTOR: BGP/single-pattern → ids → HNSW.search for similar-but-unconnected entities.
3. VECTOR_GUIDED_KHOP: rank a triple frontier (k-hop expansion) by vector similarity, returning the top-N most semantically relevant neighbors. Gateway-only (Phase 3 of #1432).

pub async fn resolve_conflict( &mut self, request: impl IntoRequest<ResolveConflictRequest>, ) -> Result<Response<ResolveConflictResponse>, Status>

Resolve the conflict set containing a node: expand contradicts/gedge_rev edges, then return the authoritative claim, the dissenting set, and the policy rationale. Gateway-only; auditable “show consensus” endpoint.

pub async fn resolve_entities( &mut self, request: impl IntoRequest<ResolveEntitiesRequest>, ) -> Result<Response<ResolveEntitiesResponse>, Status>

(#828 LongMemEval Phase 5b) LLM-free entity-resolution candidate generation: given a graph (+ optional query terms) run the blocking-then-scoring resolver (alias rule + entity-mention ANN nearest-neighbor + lexical) and return the candidate clusters (canonical → surfaces, with method+score). Gateway-only; candidate primitive — transitive persistence is Phase 5c.

pub async fn create_vector_index( &mut self, request: impl IntoRequest<CreateVectorIndexRequest>, ) -> Result<Response<CreateVectorIndexResponse>, Status>

Create or reconfigure an HNSW vector index.

pub async fn drop_vector_index( &mut self, request: impl IntoRequest<DropVectorIndexRequest>, ) -> Result<Response<DropVectorIndexResponse>, Status>

Drop an HNSW vector index.

pub async fn vector_put( &mut self, request: impl IntoRequest<VectorPutRequest>, ) -> Result<Response<VectorPutResponse>, Status>

Insert or update a vector in the index.

pub async fn vector_delete( &mut self, request: impl IntoRequest<VectorDeleteRequest>, ) -> Result<Response<VectorDeleteResponse>, Status>

Remove a vector from the index.

pub async fn vector_search( &mut self, request: impl IntoRequest<VectorSearchRequest>, ) -> Result<Response<VectorSearchResponse>, Status>

Approximate nearest neighbor search.

pub async fn vector_get( &mut self, request: impl IntoRequest<VectorGetRequest>, ) -> Result<Response<VectorGetResponse>, Status>

Retrieve a stored vector by id.

pub async fn vector_batch_put( &mut self, request: impl IntoRequest<VectorBatchPutRequest>, ) -> Result<Response<VectorBatchPutResponse>, Status>

Batch insert vectors into the index.

pub async fn vector_batch_delete( &mut self, request: impl IntoRequest<VectorBatchDeleteRequest>, ) -> Result<Response<VectorBatchDeleteResponse>, Status>

Batch delete vectors from the index.

pub async fn vector_train( &mut self, request: impl IntoRequest<VectorTrainRequest>, ) -> Result<Response<VectorTrainResponse>, Status>

Train quantization parameters (PQ codebooks, IVF centroids) for an index.

pub async fn vector_sample( &mut self, request: impl IntoRequest<VectorSampleRequest>, ) -> Result<Response<VectorSampleResponse>, Status>

Sample random vectors from a named index on this node (used for global training).

pub async fn vector_export( &mut self, request: impl IntoRequest<VectorExportRequest>, ) -> Result<Response<VectorExportResponse>, Status>

Export live (id, vector) pairs from a LEGACY independent-family index, paginated by id. Retirement migration (P7) only; graph-backed and exempt index types return FailedPrecondition.

pub async fn sparse_ingest( &mut self, request: impl IntoRequest<SparseIngestRequest>, ) -> Result<Response<SparseIngestResponse>, Status>

Ingest sparse (term->weight) documents into a per-index inverted posting store.

pub async fn hybrid_search( &mut self, request: impl IntoRequest<HybridSearchRequest>, ) -> Result<Response<HybridSearchResponse>, Status>

Hybrid dense + sparse retrieval with RRF or weighted fusion.

pub async fn scan( &mut self, request: impl IntoRequest<ScanRequest>, ) -> Result<Response<ScanResponse>, Status>

Scan keys with an optional prefix filter. Returns a page of key-value pairs.

pub async fn delete_by_prefix( &mut self, request: impl IntoRequest<DeleteByPrefixRequest>, ) -> Result<Response<DeleteByPrefixResponse>, Status>

Delete all keys matching a prefix. Returns the number of keys deleted.

pub async fn get_node_stats( &mut self, request: impl IntoRequest<GetNodeStatsRequest>, ) -> Result<Response<GetNodeStatsResponse>, Status>

Collect per-shard / per-CF statistics from this data node.

pub async fn checkpoint( &mut self, request: impl IntoRequest<CheckpointRequest>, ) -> Result<Response<CheckpointResponse>, Status>

Admin: checkpoint this data node — force-flush every hosted shard’s state machine, advance idle shards’ WAL TRUNCATE floors, and GC reclaimable WAL segments. Called after bulk ingest so a subsequent restart replays a small WAL instead of the whole ingest burst (issue #754). Data-node only; the gateway exposes it as POST /api/v1/admin/checkpoint fanning out per node.

pub async fn get_cluster_clock( &mut self, request: impl IntoRequest<GetClusterClockRequest>, ) -> Result<Response<GetClusterClockResponse>, Status>

Admin: read this node’s Hybrid Logical Clock (epic #1478, Phase 1). Returns the current HLC reading plus whether cross-shard transactions are enabled, so the clock that orders cross-shard commits is observable. Sampling the clock advances it (it is a now()), so this is a lightweight admin probe, not a hot-path RPC.

pub async fn agent_add_step( &mut self, request: impl IntoRequest<AgentAddStepRequest>, ) -> Result<Response<AgentAddStepResponse>, Status>

Add a causal step (write props + content atomically).

pub async fn agent_add_edge( &mut self, request: impl IntoRequest<AgentAddEdgeRequest>, ) -> Result<Response<AgentAddEdgeResponse>, Status>

Add a causal edge (forward + reverse).

pub async fn agent_get_step( &mut self, request: impl IntoRequest<AgentGetStepRequest>, ) -> Result<Response<AgentGetStepResponse>, Status>

Get a causal step’s metadata.

pub async fn agent_get_content( &mut self, request: impl IntoRequest<AgentGetContentRequest>, ) -> Result<Response<AgentGetContentResponse>, Status>

Get a causal step’s content.

pub async fn agent_get_edges( &mut self, request: impl IntoRequest<AgentGetEdgesRequest>, ) -> Result<Response<AgentGetEdgesResponse>, Status>

Get edges for a step (incoming or outgoing).

pub async fn agent_local_traverse( &mut self, request: impl IntoRequest<AgentLocalTraverseRequest>, ) -> Result<Response<AgentLocalTraverseResponse>, Status>

Single-shard BFS traversal returning steps + edges from GraphSST.

pub async fn agent_cas_put( &mut self, request: impl IntoRequest<AgentCasPutRequest>, ) -> Result<Response<AgentCasPutResponse>, Status>

Compare-and-swap put.

pub async fn agent_txn_commit( &mut self, request: impl IntoRequest<AgentTxnCommitRequest>, ) -> Result<Response<AgentTxnCommitResponse>, Status>

Single-DBImpl optimistic transaction commit with snapshot-isolation conflict detection. The client buffers reads (cf, key, observed_seq) and writes (puts/deletes), then submits them in one call; the server takes sharded key locks, re-validates the read-set against the latest seqs, and atomically applies the writes (or aborts on conflict).

pub async fn agent_claim( &mut self, request: impl IntoRequest<AgentClaimRequest>, ) -> Result<Response<AgentClaimResponse>, Status>

Coordination primitives. A claim is an atomic SetIfNotExists(claim_key, agent_id); a lease adds a TTL so an un-renewed holder auto-expires; renew and release are fenced so only the live holder can act. Issue #691.

pub async fn agent_lease( &mut self, request: impl IntoRequest<AgentLeaseRequest>, ) -> Result<Response<AgentLeaseResponse>, Status>

pub async fn agent_renew( &mut self, request: impl IntoRequest<AgentRenewRequest>, ) -> Result<Response<AgentRenewResponse>, Status>

pub async fn agent_release( &mut self, request: impl IntoRequest<AgentReleaseRequest>, ) -> Result<Response<AgentReleaseResponse>, Status>

pub async fn agent_prewrite( &mut self, request: impl IntoRequest<AgentPrewriteRequest>, ) -> Result<Response<AgentPrewriteResponse>, Status>

Cross-shard ACID transactions — Phase 2 (epic #1478): the internal Percolator-style prewrite. Conditionally places a LockRecord intent on lock//<user_key> in the coordination CF and stages the provisional value, aborting on a conflicting lock or a newer committed version. Gated behind STATELET_CROSS_SHARD_TXN, DEFAULT OFF (returns FailedPrecondition when the flag is unset); commit/roll-forward arrive in Phase 3.

pub async fn agent_commit_primary( &mut self, request: impl IntoRequest<AgentCommitPrimaryRequest>, ) -> Result<Response<AgentCommitPrimaryResponse>, Status>

Cross-shard ACID transactions — Phase 3 (epic #1478): the internal commit point + resolution drivers, used by the gateway coordinator. AgentCommitPrimary is the single fence-gated CAS that flips the primary TxnStatus Prewritten->Committed (or Aborted); AgentRollForward replaces a secondary’s LockRecord with a WriteRecord and materializes the staged value; AgentRollback drops a secondary’s intent + staged value. All gated behind STATELET_CROSS_SHARD_TXN, DEFAULT OFF.

pub async fn agent_roll_forward( &mut self, request: impl IntoRequest<AgentRollForwardRequest>, ) -> Result<Response<AgentRollForwardResponse>, Status>

pub async fn agent_rollback( &mut self, request: impl IntoRequest<AgentRollbackRequest>, ) -> Result<Response<AgentRollbackResponse>, Status>

pub async fn agent_resolve_lock( &mut self, request: impl IntoRequest<AgentResolveLockRequest>, ) -> Result<Response<AgentResolveLockResponse>, Status>

Cross-shard ACID transactions — Phase 4 (epic #1478): the read-path lock resolver. Given a (cf, key) and a snapshot read_ts, resolves any blocking prewrite lock via the primary TxnStatus — rolling a committed secondary forward, cleaning an aborted/stale (TTL-expired) intent, or reporting the commit decision is still pending. Idempotent and callable by any reader. The gateway runs this as a pre-step before its causal/vector reads. Gated behind STATELET_CROSS_SHARD_TXN, DEFAULT OFF.

pub async fn agent_read_txn_status( &mut self, request: impl IntoRequest<AgentReadTxnStatusRequest>, ) -> Result<Response<AgentReadTxnStatusResponse>, Status>

Cross-shard ACID transactions (epic #1478, issue #1598): read the primary TxnStatus for a primary key from THIS node’s coordination shard. The primary commit record is written through the coordination Raft group, so a secondary OWNER shard whose node is not in the coordination shard’s replica set cannot read it locally (RF < node_count, disjoint replica sets). The owner-shard resolver routes the primary-status read here (to the coordination-shard leader) instead of its node-local store, mirroring the write side. Internal /admin-only and gated behind STATELET_CROSS_SHARD_TXN, DEFAULT OFF.

pub async fn agent_list_decided_primaries( &mut self, request: impl IntoRequest<AgentListDecidedPrimariesRequest>, ) -> Result<Response<AgentListDecidedPrimariesResponse>, Status>

Cross-shard ACID transactions (epic #1478, issue #1598): enumerate every DECIDED primary TxnStatus (Committed/Aborted) on the receiving node’s coordination shard, with its participant (cf,key) list. The gateway’s recovery sweep calls this on the coordination-shard leader (the primary statuses live there) and then fans a roll-forward / roll-back to each participant’s OWNER shard — the secondary locks the coordination shard cannot itself reach under RF < node_count. Internal/admin-only, gated behind STATELET_CROSS_SHARD_TXN (default OFF).

pub async fn cross_shard_txn_commit( &mut self, request: impl IntoRequest<CrossShardCommitRequest>, ) -> Result<Response<CrossShardCommitResponse>, Status>

Cross-shard ACID transactions — Phase 3 (epic #1478): the user-facing gateway coordinator RPC. Drives prewrite->commit->roll-forward for a write_set spanning any set of shards/Raft groups, returning an all-or-nothing commit decision. A single-shard write_set takes the optimistic fast path and bypasses 2PC. Gated behind STATELET_CROSS_SHARD_TXN, DEFAULT OFF (returns FailedPrecondition when the flag is unset).

pub async fn resolve_stale_txn( &mut self, request: impl IntoRequest<ResolveStaleTxnRequest>, ) -> Result<Response<ResolveStaleTxnResponse>, Status>

Cross-shard ACID transactions — Phase 5 (epic #1478): recovery & liveness. ResolveStaleTxn is the user-facing admin RPC that drives the idempotent stale-lock resolver — it consults each lock’s primary TxnStatus (Committed -> roll forward; absent/Prewritten + lock TTL expired -> roll back) and reclaims coordinator-crash / partition-orphaned intents. AgentResolveStaleTxn is the internal per-coordination-shard driver the gateway fans to. Both gated behind STATELET_CROSS_SHARD_TXN, DEFAULT OFF (FailedPrecondition when unset).

pub async fn agent_resolve_stale_txn( &mut self, request: impl IntoRequest<AgentResolveStaleTxnRequest>, ) -> Result<Response<AgentResolveStaleTxnResponse>, Status>

pub async fn agent_gc_expired_locks( &mut self, request: impl IntoRequest<AgentGcExpiredLocksRequest>, ) -> Result<Response<AgentGcExpiredLocksResponse>, Status>

AgentGcExpiredLocks is the internal per-OWNER-shard sweep the gateway fans to (issue #1795). The decided-primaries scan (AgentListDecidedPrimaries) only enumerates COMMITTED/ABORTED primaries from the coordination shard, so a coordinator that crashed after prewriting secondaries but BEFORE the commit point leaves its primary forever Prewritten — never enumerated, so its orphaned owner-shard intents are only reclaimed if a read happens to hit the exact key. This RPC scans the TTL-expired prewrite locks on one owner shard and resolves each against the coordination-shard primary status (rolling back the never-committed ones), so the gateway sweep reclaims still-Prewritten orphans across every participant shard without a read. Mirrors TiKV’s background ResolveLocks sweep over participant Regions. Gated behind STATELET_CROSS_SHARD_TXN, DEFAULT OFF.

pub async fn txn_begin( &mut self, request: impl IntoRequest<TxnBeginRequest>, ) -> Result<Response<TxnBeginResponse>, Status>

Cross-shard ACID transactions — Phase 6 (epic #1478): buffered BEGIN/COMMIT/ROLLBACK (TiKV-style optimistic 2PC). TxnBegin allocates a transaction handle (the primary key every prewrite will fence on); the client buffers its write_set locally and submits it at TxnCommit, which drives the same prewrite->commit->roll-forward as CrossShardTxnCommit but pinned to the begun primary. TxnRollback discards the handle (optimistic 2PC prewrites nothing before COMMIT, so it is a buffer-drop ack). All gated behind STATELET_CROSS_SHARD_TXN, DEFAULT OFF (FailedPrecondition when unset).

pub async fn txn_commit( &mut self, request: impl IntoRequest<TxnCommitRequest>, ) -> Result<Response<TxnCommitResponse>, Status>

pub async fn txn_rollback( &mut self, request: impl IntoRequest<TxnRollbackRequest>, ) -> Result<Response<TxnRollbackResponse>, Status>

pub async fn agent_expire_edge( &mut self, request: impl IntoRequest<AgentExpireEdgeRequest>, ) -> Result<Response<AgentExpireEdgeResponse>, Status>

Expire an existing edge (set valid_to).

pub async fn agent_cascade_expire( &mut self, request: impl IntoRequest<AgentCascadeExpireRequest>, ) -> Result<Response<AgentCascadeExpireResponse>, Status>

Cascade-expire (#693): retract a fact and recursively close every fact transitively derived from it — across agent boundaries — bitemporally, diamond/cycle-safe, with retraction provenance + change-feed emission.

pub async fn agent_supersede_fact( &mut self, request: impl IntoRequest<AgentSupersedeFactRequest>, ) -> Result<Response<AgentSupersedeFactResponse>, Status>

Supersede a fact with a replacement (#693 phase 4). Closes old_fact, records the Supersedes edge, and — when cascade=true — cascade-closes old_fact’s derived dependents (stamped Superseded/Cascaded provenance).

pub async fn agent_memory_ingest( &mut self, request: impl IntoRequest<AgentMemoryIngestRequest>, ) -> Result<Response<AgentMemoryIngestResponse>, Status>

Transactional memory ingest (#780): dedup / create + provenance edges / supersede candidates, all committed as ONE atomic, snapshot-isolated WriteBatch via the optimistic transaction manager. On a snapshot-isolation conflict the engine retries within a bounded budget, then returns action=Conflict (back-pressure) without writing.

pub async fn agent_edge_history( &mut self, request: impl IntoRequest<AgentEdgeHistoryRequest>, ) -> Result<Response<AgentEdgeHistoryResponse>, Status>

Get edge version history for a specific (src, dst, type) triple.

pub async fn agent_query_provenance( &mut self, request: impl IntoRequest<AgentQueryProvenanceRequest>, ) -> Result<Response<AgentQueryProvenanceResponse>, Status>

── Memory-scope provenance audit (#697 phase 4) ──────────────────────── Read back the immutable provenance log (one record per access decision: AddStep/GetStep/Traverse/FindSimilar/GetEdges, incl. AdminBypass). Gated by ManageMemoryScope. The result is materialized (not streamed) since the audit tool scans a bounded time window; large windows page via after_ts/after_seq.

pub async fn agent_manage_team_grant( &mut self, request: impl IntoRequest<AgentManageTeamGrantRequest>, ) -> Result<Response<AgentManageTeamGrantResponse>, Status>

── Memory-scope team-membership admin (#697 phase 2c / #794) ─────────── Grant or revoke an agent’s membership of a team. Durable through the metadata Raft group. Gated by ManageMemoryScope. The grant store is metadata-side, so on the raw Statelet leaf this is unimplemented — operators call it through AgentStateService, which authorizes then applies the op.

pub async fn agent_start_run( &mut self, request: impl IntoRequest<AgentStartRunRequest>, ) -> Result<Response<AgentStartRunResponse>, Status>

── Durable agent execution (#846, epic #699 / sub-epic #792) ─────────── Raft-backed run/step home: each write is a RAFT_TYPE_KV log entry on the owning shard, replicated to a quorum before ack, so a crashed multi-step agent resumes at the exact failed step on a new leader. RunStep/CompleteStep are split so the server never executes client code over the wire (Temporal/ DBOS record-before-effect across the network).

pub async fn agent_run_step( &mut self, request: impl IntoRequest<AgentRunStepRequest>, ) -> Result<Response<AgentRunStepResponse>, Status>

pub async fn agent_complete_step( &mut self, request: impl IntoRequest<AgentCompleteStepRequest>, ) -> Result<Response<AgentCompleteStepResponse>, Status>

pub async fn agent_checkpoint_get( &mut self, request: impl IntoRequest<AgentCheckpointGetRequest>, ) -> Result<Response<AgentCheckpointGetResponse>, Status>

pub async fn agent_checkpoint_latest( &mut self, request: impl IntoRequest<AgentCheckpointLatestRequest>, ) -> Result<Response<AgentCheckpointLatestResponse>, Status>

pub async fn agent_provenance_chain_query( &mut self, request: impl IntoRequest<AgentProvenanceChainQueryRequest>, ) -> Result<Response<AgentProvenanceChainQueryResponse>, Status>

pub async fn agent_resume_from_step( &mut self, request: impl IntoRequest<AgentResumeFromStepRequest>, ) -> Result<Response<AgentResumeFromStepResponse>, Status>

pub async fn agent_resume_semantic( &mut self, request: impl IntoRequest<AgentResumeSemanticRequest>, ) -> Result<Response<AgentResumeSemanticResponse>, Status>

pub async fn agent_get_run_status( &mut self, request: impl IntoRequest<AgentGetRunStatusRequest>, ) -> Result<Response<AgentGetRunStatusResponse>, Status>

pub async fn agent_fork_run( &mut self, request: impl IntoRequest<AgentForkRunRequest>, ) -> Result<Response<AgentForkRunResponse>, Status>

Phase 5 (#797): branch/time-travel resume — fork a run from any historical step_seq into a NEW AgentFork branch + child run, leaving the source run untouched (LangGraph “time-travel”). Leaf RPC homed on the source run’s shard.

pub async fn agent_fork_across_candidates( &mut self, request: impl IntoRequest<AgentForkAcrossCandidatesRequest>, ) -> Result<Response<AgentForkAcrossCandidatesResponse>, Status>

pub async fn agent_artifact_put( &mut self, request: impl IntoRequest<AgentArtifactPutRequest>, ) -> Result<Response<AgentArtifactPutResponse>, Status>

Phase 2 (#1699): content-addressed artifact records for large durable-run results. Leaf RPCs are homed on the owning run shard and authorized against RunRecord.agent_id.

pub async fn agent_artifact_get( &mut self, request: impl IntoRequest<AgentArtifactGetRequest>, ) -> Result<Response<AgentArtifactGetResponse>, Status>

pub async fn agent_artifact_resolve( &mut self, request: impl IntoRequest<AgentArtifactResolveRequest>, ) -> Result<Response<AgentArtifactResolveResponse>, Status>

pub async fn agent_team_snapshot_local( &mut self, request: impl IntoRequest<TeamSnapshotLocalRequest>, ) -> Result<Response<TeamSnapshotLocalResponse>, Status>

── Team time-travel (#787, epic #698 Phase 3) ────────────────────────── Leaf, single-shard “as-of-then” team belief reconstruction. The gateway fans these out to every shard, pins one committed ordinal per shard (the FoundationDB-style read version), merges/dedupes, paginates, and tolerates dead shards (partial view). Calls the in-process #724 operators CausalGraphManager::team_snapshot / team_diff.

pub async fn agent_team_diff_local( &mut self, request: impl IntoRequest<TeamDiffLocalRequest>, ) -> Result<Response<TeamDiffLocalResponse>, Status>

pub async fn agent_belief_query( &mut self, request: impl IntoRequest<AgentBeliefQueryRequest>, ) -> Result<Response<AgentBeliefQueryResponse>, Status>

── Bitemporal belief queries: “who believed what, when” ──────────────── Combined (valid-time as_of, transaction-time tx_as_of, author) query that reconstructs any agent’s (or the team’s) belief state at a past instant.

pub async fn agent_belief_divergence( &mut self, request: impl IntoRequest<AgentBeliefDivergenceRequest>, ) -> Result<Response<AgentBeliefDivergenceResponse>, Status>

Per-agent belief divergence at (as_of, tx_as_of): “A believes X, B believes ¬X”.

pub async fn agent_state_get( &mut self, request: impl IntoRequest<AgentStateGetRequest>, ) -> Result<Response<AgentStateGetResponse>, Status>

── Raw agent-state row access (P3) ──────────────────────────────────── Read rows out of an agent column family BY NAME, so a coordinator outside the storage process can drive agent semantics itself instead of asking the data node to. This is what lets the agent RPCs move to the gateway: the gateway already links the row codecs (one codebase), it was only missing the bytes.

Why a dedicated pair rather than the generic Get/Scan: the agent CFs live on the shared DB and are deliberately NOT registered in the metadata CF registry, so (cf, key) routing resolves nothing for them. Registering them would mint a SECOND Raft group over rows a different group already writes — a split-brain shape that has erased data in this system before. Instead these address the pinned coordination shard explicitly and are served ONLY by its leader, exactly like the claim/lease CAS path.

pub async fn agent_state_scan( &mut self, request: impl IntoRequest<AgentStateScanRequest>, ) -> Result<Response<AgentStateScanResponse>, Status>

pub async fn agent_append_provenance( &mut self, request: impl IntoRequest<AgentAppendProvenanceRequest>, ) -> Result<Response<AgentAppendProvenanceResponse>, Status>

Append one already-decided provenance record to the immutable audit log.

The scope DECISION moves to the gateway with the rest of agent semantics; the audit APPEND stays here. §4 of the design already excludes the provenance log from the triple-plane move, and keeping the append local avoids turning a best-effort local write into a cross-process failure mode on every audited read. The gateway sends the record it built; this RPC is internal-token gated, same as the rest of the agent surface, because a caller that could reach it directly could forge audit entries.

pub async fn agent_state_edges( &mut self, request: impl IntoRequest<AgentStateEdgesRequest>, ) -> Result<Response<AgentStateEdgesResponse>, Status>

Raw adjacency of one anchor, with the bitemporal filters applied and NO scope filtering. Edges are served from an in-memory index rebuilt at open, not read row-by-row, so AgentStateScan cannot reconstruct them — and reimplementing bitemporal visibility on the coordinator would put the subtlest filtering in this system in two places. Temporal filtering stays with the index; the scope decision is the caller’s.

Leaks peer ids by construction. Internal-token gated, never client-facing.

pub async fn agent_state_batch_get( &mut self, request: impl IntoRequest<AgentStateBatchGetRequest>, ) -> Result<Response<AgentStateBatchGetResponse>, Status>

Batch sibling of AgentStateGet over one role. A coordinator filtering an adjacency list has to check every peer’s scope; one round trip per peer is fine in-process and untenable across it, so the peers resolve in one call.

pub async fn agent_state_belief_divergence( &mut self, request: impl IntoRequest<AgentStateBeliefDivergenceRequest>, ) -> Result<Response<AgentStateBeliefDivergenceResponse>, Status>

Per-author belief resolution for one edge slot (“A believes X, B believes not-X”). Another reduction over the revision chain — this time grouped by author — so it stays with the index for the same reason the bitemporal form does. Returns every author’s belief unfiltered; the caller applies scope.

pub async fn agent_run_checkpoint_get( &mut self, request: impl IntoRequest<AgentRunCheckpointGetRequest>, ) -> Result<Response<AgentRunCheckpointGetResponse>, Status>

Fetch a run record together with one of its checkpoints, from the shard the run_id self-routes to (run_id >> 40) — NOT the coordination shard the causal primitives serve, because durable-execution state is homed per run shard.

Both in one call because the caller needs the run record to authorize the checkpoint at all: splitting them would make every checkpoint read two round trips to answer one question.

pub async fn agent_state_team_read( &mut self, request: impl IntoRequest<AgentStateTeamReadRequest>, ) -> Result<Response<AgentStateTeamReadResponse>, Status>

Team belief reconstruction / diff over one shard, UNFILTERED, together with that shard’s committed read version.

The graph operators (team_snapshot / team_diff) walk the in-memory index and the read version is the shard’s own MVCC seq, so both stay here; visibility filtering, the global sort and pagination are the caller’s. Answering the read version in the SAME call is the point — it is the FoundationDB-style per-shard fence the coordinator maxes across shards, and fetching it separately would fence against a different instant than the one the answer was computed at.

pub async fn agent_state_conditional_write( &mut self, request: impl IntoRequest<AgentStateConditionalWriteRequest>, ) -> Result<Response<ConditionalBatchWriteResponse>, Status>

Conditional write PINNED to the coordination shard’s Raft group.

The generic ConditionalBatchWrite routes by (cf, key), which for agent coordination state is the wrong group: those rows are written through the coordination shard, and ordering them in a different group would let two writers to the same claim key be serialized by two different logs. Same pinning the claim/lease CAS already relies on.

pub async fn agent_state_versions( &mut self, request: impl IntoRequest<AgentStateVersionsRequest>, ) -> Result<Response<AgentStateVersionsResponse>, Status>

Per-key engine VERSIONS (no values) for arbitrary (cf, key) pairs, read from the coordination shard together with that shard’s current sequence.

Versions only, deliberately. Optimistic-commit validation and conflict reporting need nothing else, and a versions-only surface is a far smaller capability than “read any CF by name” — it cannot disclose content. Serves the same admin-only callers AgentTxnCommit already restricts itself to.

pub async fn agent_state_alloc_ids( &mut self, request: impl IntoRequest<AgentStateAllocIdsRequest>, ) -> Result<Response<AgentStateAllocIdsResponse>, Status>

Allocate a contiguous block of causal step/fact ids from the ONE authority.

Uniqueness comes from a single in-process atomic on the coordination shard’s causal manager, not from anything a caller could reproduce: two coordinators running their own counters would hand out the same id. So a coordinator that needs ids asks for them, and amortizes the round trip by taking a block.

pub async fn agent_subscribe_writes( &mut self, request: impl IntoRequest<AgentSubscribeWritesRequest>, ) -> Result<Response<Streaming<AgentWriteEventProto>>, Status>

👎Deprecated

Subscribe to write events on this shard (server-streaming to gateway). DEPRECATED (CDC Phase 5b, issue #823): superseded by SubscribeCommitted, which is a durable, ordered, offset-addressable, resumable superset of this best-effort live-only feed. Prefer SubscribeCommitted for all new consumers; this RPC remains for backward compatibility and will be removed in a future major version.

pub async fn subscribe_committed( &mut self, request: impl IntoRequest<SubscribeCommittedRequest>, ) -> Result<Response<Streaming<CommittedFeedItem>>, Status>

Durable, ordered, offset-addressable, resumable change-feed (CDC) keyed on the stable Raft log index. Catch-up from a past offset (replayed from the durable log) then live-tail; consumer-checkpointed resume (issue #692).

pub async fn agent_fork( &mut self, request: impl IntoRequest<AgentForkRequest>, ) -> Result<Response<AgentForkResponse>, Status>

── Agent State: branch (fork) leaf operations ──────────────────────────

pub async fn agent_merge_branch( &mut self, request: impl IntoRequest<AgentMergeBranchRequest>, ) -> Result<Response<AgentMergeBranchResponse>, Status>

pub async fn agent_discard_branch( &mut self, request: impl IntoRequest<AgentDiscardBranchRequest>, ) -> Result<Response<AgentDiscardBranchResponse>, Status>

pub async fn agent_list_branches( &mut self, request: impl IntoRequest<AgentListBranchesRequest>, ) -> Result<Response<AgentListBranchesResponse>, Status>

pub async fn agent_branch_put( &mut self, request: impl IntoRequest<AgentBranchPutRequest>, ) -> Result<Response<AgentBranchPutResponse>, Status>

pub async fn agent_branch_get( &mut self, request: impl IntoRequest<AgentBranchGetRequest>, ) -> Result<Response<AgentBranchGetResponse>, Status>

pub async fn create_graph_index( &mut self, request: impl IntoRequest<CreateGraphIndexRequest>, ) -> Result<Response<CreateGraphIndexResponse>, Status>

Create a graph index (6 CFs + HNSW config).

pub async fn drop_graph_index( &mut self, request: impl IntoRequest<DropGraphIndexRequest>, ) -> Result<Response<DropGraphIndexResponse>, Status>

Drop a graph index and its CFs.

pub async fn graph_add_node( &mut self, request: impl IntoRequest<GraphAddNodeRequest>, ) -> Result<Response<GraphAddNodeResponse>, Status>

Add a node with optional vector and properties.

pub async fn graph_batch_add_node( &mut self, request: impl IntoRequest<GraphBatchAddNodeRequest>, ) -> Result<Response<GraphBatchAddNodeResponse>, Status>

Batch add multiple nodes with vectors and properties.

pub async fn graph_remove_node( &mut self, request: impl IntoRequest<GraphRemoveNodeRequest>, ) -> Result<Response<GraphRemoveNodeResponse>, Status>

Remove a node from the graph: evicts its vector from the HNSW index, deletes its properties and every temporal edge that touches it. Used by the conflict-resolver DELETE path so the graph and vector indexes never diverge.

pub async fn graph_add_edge( &mut self, request: impl IntoRequest<GraphAddEdgeRequest>, ) -> Result<Response<GraphAddEdgeResponse>, Status>

Add a temporal edge between two nodes.

pub async fn graph_batch_add_edge( &mut self, request: impl IntoRequest<GraphBatchAddEdgeRequest>, ) -> Result<Response<GraphBatchAddEdgeResponse>, Status>

Batch add multiple temporal edges in one atomic write (mirrors GraphBatchAddNode for edges). Collapses N per-edge proposals to ~1.

pub async fn graph_batch_write( &mut self, request: impl IntoRequest<GraphBatchWriteRequest>, ) -> Result<Response<GraphBatchWriteResponse>, Status>

Internal data-node RPC: apply a shard-local subset of graph writes. Used when a logical graph write spans multiple CF shards/leaders.

pub async fn graph_batch_read( &mut self, request: impl IntoRequest<GraphBatchReadRequest>, ) -> Result<Response<GraphBatchReadResponse>, Status>

Internal data-node RPC: read the current durable value of a shard-local subset of graph keys. Used to capture pre-images before a multi-leader graph write so a partial failure can be compensated (rows restored).

pub async fn graph_search( &mut self, request: impl IntoRequest<GraphSearchRequest>, ) -> Result<Response<GraphSearchResponse>, Status>

HNSW nearest neighbor search on graph vectors.

pub async fn graph_search_expand( &mut self, request: impl IntoRequest<GraphSearchExpandRequest>, ) -> Result<Response<GraphSearchExpandResponse>, Status>

Vector-anchored multi-hop expansion (GraphRAG primitive): vector search for anchor nodes, then BFS-expand the induced subgraph from those anchors with depth / edge-type / as_of filters — all in one server-side call.

pub async fn graph_rag_search( &mut self, request: impl IntoRequest<GraphRagSearchRequest>, ) -> Result<Response<GraphRagSearchResponse>, Status>

Unified GraphRAG retrieval (issue #696): one server-side call that does vector-seed -> graph expansion -> blended rerank by similarity + recency + graph-distance, scoped by valid-time / transaction-time and memory scope, returning ranked facts with provenance and bitemporal validity. Composes GraphSearch (anchors) + GraphQueryEdgesBatch (bitemporal BFS) + GraphGetNodesBatch (hydration). Served by the gateway only.

pub async fn graph_get_node( &mut self, request: impl IntoRequest<GraphGetNodeRequest>, ) -> Result<Response<GraphGetNodeResponse>, Status>

Get a graph node’s properties by ID (reads from graph node CF directly).

pub async fn graph_query_edges( &mut self, request: impl IntoRequest<GraphQueryEdgesRequest>, ) -> Result<Response<GraphQueryEdgesResponse>, Status>

Query temporal edges for a node.

pub async fn graph_query_edges_batch( &mut self, request: impl IntoRequest<GraphQueryEdgesBatchRequest>, ) -> Result<Response<GraphQueryEdgesBatchResponse>, Status>

Batched edge query: query temporal edges for many nodes at once, all routed to the same shard. Edge-type and as_of/time filters are applied at the data node. Used by the gateway’s cross-shard BFS to expand a whole per-shard frontier in one RPC (O(hops x shards) instead of O(visited)).

pub async fn graph_get_nodes_batch( &mut self, request: impl IntoRequest<GraphGetNodesBatchRequest>, ) -> Result<Response<GraphGetNodesBatchResponse>, Status>

Batched node-properties fetch: hydrate many nodes that route to the same shard in a single RPC. Used by cross-shard traversal prop hydration.

pub async fn graph_traverse( &mut self, request: impl IntoRequest<GraphTraverseRequest>, ) -> Result<Response<GraphTraverseResponse>, Status>

First-class multi-hop BFS traversal from a start node. Honors direction, depth, edge-type and as_of/time filters, and (on the gateway) drives cross-shard hops by re-dispatching frontiers to shard leaders.

pub async fn graph_nodes_by_label( &mut self, request: impl IntoRequest<GraphNodesByLabelRequest>, ) -> Result<Response<GraphNodesByLabelResponse>, Status>

Shard-local scan of the reverse label posting list (ROLE_LABEL_INDEX): resolve each label string to its interned label_id, prefix-seek the posting list, and return member node ids (optionally hydrated NodeProp JSON), capped. Multi-label = server-side conjunctive intersection (smallest posting list first). The gateway fans this out across the shard set and re-applies the global cap after merge. Used as the label+property MATCH anchor-resolution entry point (epic #1429).

pub async fn graph_temporal_join( &mut self, request: impl IntoRequest<GraphTemporalJoinRequest>, ) -> Result<Response<GraphTemporalJoinResponse>, Status>

Temporal join: align graph edges with KV time-series data. For each edge in the time range, looks up the corresponding KV entries at the edge’s timestamp. Used for news → price alignment.

pub async fn graph_analytics( &mut self, request: impl IntoRequest<GraphAnalyticsRequest>, ) -> Result<Response<GraphAnalyticsResponse>, Status>

Graph analytics: run PageRank / WCC / DegreeCentrality over a graph index’s edges. The gateway fans the computation out across every shard owning the graph’s edge CF, merges all local edge lists into one global adjacency, and runs a single global PageRank/WCC/DegreeCentrality (so masses sum to 1, WCC components are not split across shards, and DegreeCentrality normalizes over the full node set). Optionally writes scores back into node properties.

pub async fn graph_analytics_edges( &mut self, request: impl IntoRequest<GraphAnalyticsEdgesRequest>, ) -> Result<Response<GraphAnalyticsEdgesResponse>, Status>

Internal cross-shard fan-out helper for GraphAnalytics: dump one shard’s local analytics edge list (the same filtered/deduped (src,dst) pairs build_analytics_graph would feed the engine) as packed parallel u64 arrays, so the gateway can merge edges from all shards into one global adjacency. Not intended for direct client use.

pub async fn graph_analytics_write_scores( &mut self, request: impl IntoRequest<GraphAnalyticsWriteScoresRequest>, ) -> Result<Response<GraphAnalyticsWriteScoresResponse>, Status>

Internal cross-shard fan-out helper for GraphAnalytics write-back: persist a batch of (node_id, score, component) rows for nodes this shard owns into their ROLE_NodeProp “__analytics” sub-key. The gateway routes each node to its owning shard so a data node only receives its own nodes.

pub async fn graph_shortest_path( &mut self, request: impl IntoRequest<GraphShortestPathRequest>, ) -> Result<Response<GraphShortestPathResponse>, Status>

Weighted shortest-path / pathfinding (Dijkstra / A*, k-shortest via Yen’s) over user graph edges. Gateway-only: expands a cost-ordered frontier across shard leaders, decoding edge weights from edge properties.

pub async fn graph_query( &mut self, request: impl IntoRequest<GraphQueryRequest>, ) -> Result<Response<GraphQueryResponse>, Status>

Read-only declarative pattern-match graph query (an openCypher subset: MATCH path patterns with node/edge-type filters, WHERE on node properties plus an as_of temporal predicate, RETURN / LIMIT). Gateway-only: the query is parsed + planned, then compiled to existing engine traversal primitives (GraphTraverse / GraphShortestPath / GraphSearchExpand) and WHERE predicates are evaluated against hydrated ROLE_NodeProp JSON in the distributed-result merge stage. CREATE / MERGE are not supported.

Trait Implementations

impl<T: Clone> Clone for StateletClient<T>

fn clone(&self) -> StateletClient<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for StateletClient<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.