docs: documentation improvements

evansims · evansims · commit 8dd11d400a65 · 2026-04-06T21:55:11.000-05:00
diff --git a/docs/README.md b/docs/README.md
@@ -89,6 +89,7 @@ Implementation details for contributors and advanced operators.
 | `UserService`            | User accounts, emails, verification                        |
 | `AppService`             | Application management, credentials, connections           |
 | `TokenService`           | JWT token lifecycle (sessions, vault tokens, signing keys) |
+| `InvitationService`      | Organization invitation lifecycle                          |
 | `EventsService`          | Audit event queries and ingestion                          |
 | `HealthService`          | Liveness, readiness, and dependency checks                 |
 | `SystemDiscoveryService` | Peer discovery and cluster bootstrap                       |
diff --git a/docs/adr/count-min-sketch-hot-key-detection.md b/docs/adr/count-min-sketch-hot-key-detection.md
@@ -115,7 +115,6 @@ Seahash produces a 64-bit hash formatted as a fixed 16-character hex string. Ope
 
 - `crates/raft/src/hot_key_detector.rs` — CMS implementation, rotating windows, top-k tracking
 - `crates/types/src/config.rs` — `HotKeyConfig` with defaults and validation
-- `crates/services/src/services/write.rs` — `record_hot_keys()` integration in write path
-- `crates/services/src/services/multi_region_write.rs` — Multi-region coordinator integration
+- `crates/services/src/services/write.rs` — `record_hot_keys()` integration in write path (includes multi-region coordinator)
 - `crates/raft/src/metrics.rs` — `record_hot_key_detected()` with seahash label
 - Cormode & Muthukrishnan, "An Improved Data Stream Summary: The Count-Min Sketch and its Applications" (2005)
diff --git a/docs/adr/network-trust-model.md b/docs/adr/network-trust-model.md
@@ -73,7 +73,7 @@ TLS is supported for transport encryption (defense in depth) but not enforced fo
 
 - Default `listen_addr` is `127.0.0.1:50051` (localhost-only) — requires explicit override for cluster deployment
 - Optional TLS for transport encryption within the private network
-- Input validation (Task 1) and rate limiting (Task 4) protect against malformed or excessive requests from buggy upstream callers
+- Input validation and rate limiting protect against malformed or excessive requests from buggy upstream callers
 - Audit logging records all mutations with caller slug for attribution
 
 ## References
diff --git a/docs/adr/server-assigned-sequences.md b/docs/adr/server-assigned-sequences.md
@@ -92,7 +92,7 @@ enum WriteErrorCode {
 
 | Aspect                | Old (Sequence-Based)                     | New (UUID-Based)                                |
 | --------------------- | ---------------------------------------- | ----------------------------------------------- |
-| **Key**               | `(ns_id, vault_id, client_id, sequence)` | `(ns_id, vault_id, client_id, idempotency_key)` |
+| **Key**               | `(org_id, vault_id, client_id, sequence)` | `(org_id, vault_id, client_id, idempotency_key)` |
 | **Assignment**        | Client                                   | Client (key), Server (sequence)                 |
 | **Validation**        | `seq == last + 1`                        | Key exists in cache?                            |
 | **Retry**             | Same sequence returns cached result      | Same UUID returns cached result                 |
diff --git a/docs/client/admin.md b/docs/client/admin.md
@@ -184,7 +184,7 @@ Only works on vaults in `DIVERGED` state unless `force: true` is set.
 
 Simulates vault divergence for testing recovery procedures. Forces a vault into the `DIVERGED` state without actual data corruption.
 
-**Note**: Only available when the server is built with the `test-utils` feature.
+Only available when the server is built with the `test-utils` feature.
 
 ```bash
 grpcurl -plaintext \
diff --git a/docs/client/api.md b/docs/client/api.md
@@ -2,7 +2,7 @@
 
 # Client API
 
-This document covers read and write operations, error handling, and pagination.
+Read and write operations, error handling, and pagination for Ledger's gRPC API.
 
 ## gRPC Services Overview
 
@@ -16,6 +16,7 @@ This document covers read and write operations, error handling, and pagination.
 | `UserService`         | User CRUD, emails, credentials (passkey/TOTP/recovery), TOTP verification |
 | `AppService`          | App lifecycle, credentials, vault connections                             |
 | `TokenService`        | JWT sessions, refresh, signing key management                             |
+| `InvitationService`   | Organization invitation lifecycle                                         |
 | `EventsService`       | Audit event listing, filtering, ingestion                                 |
 | `HealthService`       | Readiness, liveness, startup probes                                       |
 | `DiscoveryService`    | Endpoint discovery, region topology                                       |
@@ -63,7 +64,7 @@ All operations are idempotent, resolved by Raft total ordering:
 | `DeleteEntity`       | exists     | deleted    | Transaction succeeds         |
 | `DeleteEntity`       | not exists | no change  | Transaction succeeds (no-op) |
 
-Note: `WriteResponse` is transaction-level (success or error), not per-operation. All operations in a transaction either succeed together or fail together.
+`WriteResponse` is transaction-level (success or error), not per-operation. All operations in a transaction either succeed together or fail together.
 
 ### Conditional Writes
 
diff --git a/docs/client/errors.md b/docs/client/errors.md
@@ -129,19 +129,15 @@ grpcurl -plaintext \
 
 **Resolution**: Retry with exponential backoff. Election should complete within seconds.
 
-```go
-// Example retry logic
-maxRetries := 5
-for i := 0; i < maxRetries; i++ {
-    resp, err := client.Write(ctx, req)
-    if status.Code(err) == codes.Unavailable {
-        time.Sleep(time.Duration(1<<i) * 100 * time.Millisecond)
-        continue
-    }
-    return resp, err
-}
+```bash
+# Retry with exponential backoff until leader is elected
+grpcurl -plaintext \
+  -d '{"organization_slug": {"id": "1"}, "client_id": {"id": "c1"}, "sequence": "1", ...}' \
+  localhost:50051 ledger.v1.WriteService/Write
 ```
 
+The SDK handles retries automatically. See [SDK Guide](../client/sdk.md) for retry configuration.
+
 ### RATE_LIMITED
 
 **Code**: `RESOURCE_EXHAUSTED`
@@ -235,7 +231,7 @@ Token-related operations (via `TokenService`) return specific error conditions:
 | `InvalidRefreshToken` | `UNAUTHENTICATED` | Refresh token is invalid or expired          |
 | `RefreshTokenReuse`   | `UNAUTHENTICATED` | Refresh token reuse detected; family revoked |
 
-> **Note:** Refresh token reuse triggers family poisoning — all tokens in the same family are eventually revoked. This is a theft detection mechanism and cannot be reversed.
+Refresh token reuse triggers family poisoning — all tokens in the same family are eventually revoked. This is a theft detection mechanism and cannot be reversed.
 
 ## Error Details
 
@@ -337,4 +333,4 @@ grpcurl -plaintext \
 
 The idempotency cache ensures the operation is only applied once.
 
-> **Note**: The idempotency cache is replicated via Raft and survives leader failover within the 24-hour TTL window. Retried requests with matching `(client_id, sequence)` return `ALREADY_COMMITTED` after leader change.
+The idempotency cache is replicated via Raft and survives leader failover within the 24-hour TTL window. Retried requests with matching `(client_id, sequence)` return `ALREADY_COMMITTED` after leader change.
diff --git a/docs/client/idempotency.md b/docs/client/idempotency.md
@@ -2,7 +2,7 @@
 
 # Idempotency & Retry Semantics
 
-This document covers transaction identification, sequence tracking, and retry behavior.
+Transaction identification, sequence tracking, and retry behavior for Ledger writes.
 
 ## Transaction Identification
 
@@ -120,8 +120,8 @@ Client state is tracked at two levels:
 
 | Write Scope           | GetClientState Call                          | Use Case                         |
 | --------------------- | -------------------------------------------- | -------------------------------- |
-| Organization entities | `GetClientState(ns_id, client_id)`           | Control writing users, sessions  |
-| Vault relationships   | `GetClientState(ns_id, vault_id, client_id)` | App writing authorization tuples |
+| Organization entities | `GetClientState(org_slug, client_id)`           | Control writing users, sessions  |
+| Vault relationships   | `GetClientState(org_slug, vault_slug, client_id)` | App writing authorization tuples |
 
 A single client can have separate sequence streams for each scope.
 
diff --git a/docs/client/sdk.md b/docs/client/sdk.md
@@ -489,11 +489,11 @@ let stream = client.watch_blocks(
 use inferadb_ledger_types::Region;
 
 // Create organization (requires a region for data residency)
-let ns = client.create_organization("my_app", Region::US_EAST_VA).await?;
-println!("Organization ID: {}", ns.id);
+let org = client.create_organization("my_app", Region::US_EAST_VA).await?;
+println!("Organization ID: {}", org.id);
 
 // Get organization info
-let info = client.get_organization(ns.id).await?;
+let info = client.get_organization(org.id).await?;
 println!("Status: {:?}", info.status);
 
 // List organizations
@@ -594,7 +594,7 @@ for key in &keys {
 }
 ```
 
-> **Note:** Refresh tokens use rotate-on-use semantics. Each refresh token can be used at most once — reuse triggers family poisoning (theft detection), revoking all tokens in that family.
+Refresh tokens use rotate-on-use semantics. Each refresh token can be used at most once — reuse triggers family poisoning (theft detection), revoking all tokens in that family.
 
 ## Organization Operations
 
@@ -780,7 +780,7 @@ async fn handle_errors(client: &LedgerClient) -> Result<()> {
 use inferadb_ledger_sdk::SdkError;
 use tonic::Code;
 
-match client.write(ns, vault, ops, None).await {
+match client.write(org_slug, vault, ops, None).await {
     Ok(result) => {
         println!("Committed: {}", result.tx_id);
     }
@@ -817,7 +817,7 @@ The SDK automatically retries transient errors. For custom retry logic:
 use inferadb_ledger_sdk::with_retry;
 
 let result = with_retry(&retry_policy, || async {
-    client.read(ns, None, "key").await
+    client.read(org_slug, None, "key").await
 }).await?;
 ```
 
@@ -936,11 +936,11 @@ Prefer batch operations for bulk work:
 
 ```rust
 // Good: single round-trip
-let results = client.batch_read(ns, None, keys).await?;
+let results = client.batch_read(org_slug, None, keys).await?;
 
 // Bad: N round-trips
 for key in keys {
-    let result = client.read(ns, None, key).await?;
+    let result = client.read(org_slug, None, key).await?;
 }
 ```
 
diff --git a/docs/development/architecture.md b/docs/development/architecture.md
@@ -47,7 +47,7 @@ Foundational types used by all other crates.
 - `hash.rs` - SHA-256 and seahash implementations
 - `merkle.rs` - Merkle tree and proof types
 - `error.rs` - Error types with snafu
-- `identifiers.rs` - OrganizationSlug, VaultId, NodeId, etc.
+- `types/ids.rs` - OrganizationSlug, VaultId, NodeId, etc.
 
 **Design principle:** No I/O, no external dependencies beyond crypto.
 
@@ -111,6 +111,7 @@ gRPC service implementations and server assembly.
 - `UserService` - User accounts, emails, verification
 - `AppService` - Application management, credentials, connections
 - `TokenService` - JWT token lifecycle (sessions, vault tokens, signing keys)
+- `InvitationService` - Organization invitation lifecycle
 - `EventsService` - Audit event queries and ingestion
 - `HealthService` - Health checks with dependency probes
 - `RaftService` - Node-to-node Raft RPCs
@@ -123,7 +124,7 @@ Generated protobuf code and domain type conversions.
 **Key modules:**
 
 - `generated/` - Auto-generated from `proto/ledger/v1/ledger.proto`
-- `convert.rs` - `From`/`TryFrom` conversions between proto and domain types
+- `convert/` - `From`/`TryFrom` conversions between proto and domain types
 
 ### `inferadb-ledger-server`
 
diff --git a/docs/internals/consensus.md b/docs/internals/consensus.md
@@ -199,13 +199,13 @@ Multiple vaults share a Raft group (region). A `state_root` divergence in one va
 ### Vault Health States
 
 ```rust
-// crates/types/src/types.rs - public API type
+// crates/types/src/types/enums.rs - public API type
 enum VaultHealth {
     Healthy,
     Diverged { expected: Hash, computed: Hash, at_height: u64 },
 }
 
-// crates/raft/src/log_storage.rs - internal runtime type
+// crates/raft/src/log_storage/types.rs - internal runtime type
 enum VaultHealthStatus {
     Healthy,
     Diverged { expected: Hash, computed: Hash, at_height: u64 },
diff --git a/docs/internals/discovery.md b/docs/internals/discovery.md
@@ -235,7 +235,7 @@ Local cache? ─── Hit ──→ Fresh? ─── Yes ──→ Connect to r
        └─ Miss              └─ No
             │                    │
             ▼                    ▼
-    Query _system: ns:1 ────────┘
+    Query _system: org:1 ────────┘
             │
             ▼
     Connect to region leader
diff --git a/docs/internals/storage.md b/docs/internals/storage.md
@@ -42,7 +42,7 @@ Each region's Raft group gets isolated database files under a dedicated director
 
 Ledger uses a custom B+ tree storage engine providing ACID transactions with MVCC. Each region has four databases (state.db, blocks.db, raft.db, events.db).
 
-### Raft Log Storage (log.db)
+### Raft Log Storage (raft.db)
 
 ```rust
 const LOG_ENTRIES: TableDefinition<u64, &[u8]> = TableDefinition::new("log");
diff --git a/docs/operations/metrics-reference.md b/docs/operations/metrics-reference.md
@@ -355,7 +355,7 @@ apiVersion: monitoring.coreos.com/v1
 kind: ServiceMonitor
 metadata:
   name: ledger
-  organization: inferadb
+  namespace: inferadb
 spec:
   selector:
     matchLabels:
@@ -364,7 +364,7 @@ spec:
     - port: metrics
       interval: 15s
       path: /metrics
-  organizationSelector:
+  namespaceSelector:
     matchNames:
       - inferadb
 ```
diff --git a/docs/operations/multi-region.md b/docs/operations/multi-region.md
@@ -71,7 +71,7 @@ apiVersion: apps/v1
 kind: StatefulSet
 metadata:
   name: ledger
-  organization: ledger-us-east
+  namespace: ledger-us-east
 spec:
   replicas: 3
   template:
@@ -254,7 +254,7 @@ Moving an organization to a different region:
 
 ```bash
 grpcurl -plaintext target-region-ledger:50051 \
-  -d '{"name": "migrating_ns"}' \
+  -d '{"name": "migrating_org"}' \
   ledger.v1.AdminService/CreateOrganization
 ```
 
@@ -263,7 +263,7 @@ grpcurl -plaintext target-region-ledger:50051 \
 ```bash
 # Export all entities and relationships
 grpcurl -plaintext source-region-ledger:50051 \
-  -d '{"organization_slug": {"id": "OLD_NS"}}' \
+  -d '{"organization_slug": {"slug": 7890123456}}' \
   ledger.v1.ReadService/ExportOrganization > export.json
 ```
 
@@ -285,12 +285,12 @@ Update Control's routing table to point to new region.
 ```bash
 # Verify data integrity
 grpcurl -plaintext target-region-ledger:50051 \
-  -d '{"organization_slug": {"id": "NEW_NS"}}' \
+  -d '{"organization_slug": {"slug": 1234567890}}' \
   ledger.v1.AdminService/CheckIntegrity
 
 # Delete from source (after verification period)
 grpcurl -plaintext source-region-ledger:50051 \
-  -d '{"organization_slug": {"id": "OLD_NS"}}' \
+  -d '{"organization_slug": {"slug": 7890123456}}' \
   ledger.v1.AdminService/DeleteOrganization
 ```
 
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -185,19 +185,19 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let client = LedgerClient::new(config).await?;
 
     // Create organization
-    let ns = client.create_organization("my_app", Region::US_EAST_VA).await?;
-    println!("Created organization: {}", ns.slug);
+    let org = client.create_organization("my_app", Region::US_EAST_VA).await?;
+    println!("Created organization: {}", org.slug);
 
     // Create vault (returns a Snowflake vault slug)
-    let vault = client.create_vault(ns.slug).await?;
+    let vault = client.create_vault(org.slug).await?;
     println!("Created vault: {}", vault.vault_slug);
 
     // Write entity
     let ops = vec![Operation::set_entity("user:alice", b"Alice".to_vec())];
-    client.write(ns.slug, None, ops).await?;
+    client.write(org.slug, None, ops).await?;
 
     // Read it back
-    let entity = client.read(ns.slug, None, "user:alice").await?;
+    let entity = client.read(org.slug, None, "user:alice").await?;
     println!("Read: {:?}", entity);
 
     Ok(())
