# lodestone-client
`lodestone-client` is the current-only asynchronous Rust client for the
Lodestone API request/reply protocol and canonical subscription gRPC
stream. It depends on the generated leaf `lodestone-wire` DTO crate and
does not expose internal Core RPC, storage, authority, Elasticsearch, RESP, or
server types.
Cargo consumers declare only an exact `lodestone-client` version from
crates.io. The same-version `lodestone-wire` package is an exact transitive
dependency; a consumer does not need a direct wire dependency, Git pin, path
patch, or custom registry.
Construct one `CellTransport` per exact cell and operation class, then attach
lightweight `CollectionSession` values containing a validated connection
profile and caller-owned `CredentialProvider`. Sessions for different
Collections share the bounded transport only when endpoints, TLS server name
and trust, cluster/schema identity, operation class, and pool limits match
exactly. Credential material remains session-local and request-scoped. A
bounded transport LRU may retain only verified non-secret metadata, which each
session rechecks against its complete profile before use. Create `CallOptions`, then pass
those options to `CollectionSession::connect`. `Client` remains the ordinary
Collection-session spelling used by generated methods. `CallOptions::new` converts its duration to one absolute
deadline immediately; clones retain that exact deadline. Connection verifies
TLS and ALPN, authenticates, discovers the exact schema and stream, and
validates the cluster, Collection, expected principal, configuration generation,
and binding revision before returning. Reuse the same options for a caller workflow when
discovery, binding, preparation, submission, and resolution share one budget.
Endpoints rotate in profile order; a read may move to the next endpoint only
within its bounded retry policy. Mutations retry only before the submission
boundary.
State helpers accept a semantic `StateIndex`, enforce the 254-byte key bound,
and provide `get`, colocated `mget`, absolute-expiry `set`, and `delete`.
Callers retain a durable `StateActionId` for writes. The helpers perform
prepare/submit/resolve and return `StateWriteOutcome`, preserving retired,
reset, and indeterminate outcomes rather than claiming success. Secret
material is never `Clone`, `Debug`, serialized, or included in errors, and is
overwritten on drop.
`append_exact`, `mutate_document_exact`, and `reconcile_index_exact` share one
recovery contract. They retain the first absolute effect deadline, caller
action/request digest, exact cluster/collection/index scope, prepared locator,
and submission disposition. A durable `ExactWorkflowStore` adapts the sealed
local journal; callers without filesystem storage must persist the returned
`ExactWorkflowRecoveryV1` and pass it back with `with_recovery`. Once submission
may have happened, the helpers resolve the original locator and never prepare a
replacement action. `reconcile_index_exact` creates only an absent exact
definition and reports a conflict instead of updating an existing index.
This package is an unreleased development artifact. It has no protocol
downgrade or compatibility mode.
Document-bulk and retained-append callers derive the request `batch_id` with
the re-exported
`bulk_batch_id(&Identity, &Resource, &[Digest])`.
It rejects malformed, zero, duplicate, or over-bound action identities and
preserves caller order. There is no append-specific alias or predecessor hash.
The direct `hyper-util` and `tower` dependencies reuse versions already in
Core's dependency closure. Only `TokioIo` and `service_fn` are enabled so the
subscription channel can use the crate's TLS-1.3-only rustls connector instead
of a broader transport default. No native/system dependency is added.