refactor(reads): remove leader consistency selector

Author: Geoffrey Ragot

cmd/ledgerctl/main.go

@@ -119,8 +119,8 @@ func newRootCommand() *cobra.Command {
 	rootCmd.PersistentFlags().String("response-verify-key", "", "Path to Ed25519 seed file for verifying server response signatures (env: LEDGERCTL_RESPONSE_VERIFY_KEY)")
 
 	// Add persistent flag for read consistency level.
-	rootCmd.PersistentFlags().String("consistency", "", "Read consistency level: stale, leader, or linearizable (default) (env: LEDGERCTL_CONSISTENCY)")
-	cmdutil.RegisterEnumCompletion(rootCmd, "consistency", "stale", "leader", "linearizable")
+	rootCmd.PersistentFlags().String("consistency", "", "Read consistency level: stale or linearizable (default) (env: LEDGERCTL_CONSISTENCY)")
+	cmdutil.RegisterEnumCompletion(rootCmd, "consistency", "stale", "linearizable")
 
 	// Add persistent flag for bearer token authentication.
 	rootCmd.PersistentFlags().String("auth-token", "", "Bearer token for authentication (JWT string or @path-to-file) (env: LEDGERCTL_AUTH_TOKEN)")

docs/ops/cli.md

@@ -41,7 +41,7 @@ These flags are available for all commands:
 | `--signing-key` | | Path to Ed25519 private key file (seed: 32 bytes raw or hex-encoded) |
 | `--signing-key-id` | `default` | Key ID for request signatures |
 | `--response-verify-key` | | Path to Ed25519 public key file for verifying server response signatures |
-| `--consistency` | | Read consistency level: `stale`, `leader`, or `linearizable` (default) |
+| `--consistency` | | Read consistency level: `stale` or `linearizable` (default) |
 | `--auth-token` | | Bearer token for authentication (JWT string or `@path-to-file`) |
 
 ### TLS server name (verifying by name while dialing by IP)
@@ -88,20 +88,13 @@ make independently asynchronous projections linearizable; endpoint sections
 document those exceptions. The barrier can block during maintenance windows
 (e.g. mirror sync or snapshot creation) when the FSM is frozen.
 
-Two alternative consistency levels are available:
+One alternative consistency level is available:
 
 - **`stale`** — Skip the Raft ReadIndex barrier and read from local state, which
   may lag behind the latest committed index. A read can still wait for an
   explicitly requested `--min-log-sequence` or for mandatory secondary-index
   alignment. Useful for monitoring, dashboards, and non-critical queries where
   quorum-confirmed freshness is unnecessary.
-- **`leader`** — Route the read to the node currently considered leader. When
-  the request is forwarded, the remote node applies its default ReadIndex
-  barrier. When the receiving node already considers itself leader, it serves
-  the read locally without a barrier. Because `CheckQuorum` is disabled, an
-  isolated former leader can therefore return stale state in this mode; use the
-  default `linearizable` mode when quorum-confirmed freshness is required.
-
 `chapters list` is leader-routed independently of this selector and does not
 perform a ReadIndex barrier. If it reaches an isolated node that still considers
 itself leader, it can return stale chapter rows. Filtered `audit list` also has
@@ -111,9 +104,6 @@ an endpoint-specific asynchronous-index caveat; see its consistency note below.
 # Stale read (no Raft barrier; may lag)
 ledgerctl --consistency stale ledgers get my-ledger
 
-# Leader-routed read (may be stale from an isolated former leader)
-ledgerctl --consistency leader ledgers list
-
 # Default linearizable read
 ledgerctl ledgers list
 ```

docs/technical/architecture/data-flows.md

@@ -556,10 +556,9 @@ config:
 node currently considered leader. `ListChapters` bypasses the normal read
 consistency selector and does not perform a ReadIndex barrier; a node that still
 considers itself leader serves its persisted chapter rows locally. Other live
-reads normally use the ReadIndex mechanism (see below), but callers can
-explicitly select `x-consistency: leader`. That mode also routes the read to the
-perceived leader; if the receiving node already considers itself leader, the
-local shortcut does not perform a ReadIndex barrier.
+reads normally use the ReadIndex mechanism (see below). The unreleased v3
+`x-consistency: leader` selector was removed by EN-1946; callers choose between
+the default linearizable route and an explicit `stale` local read.
 
 ### Forwarding Flow
 

docs/technical/architecture/subsystems/consensus/raft-consensus.md

@@ -574,15 +574,6 @@ indexes need their own progress barrier:
 - `x-consistency: stale` bypasses `ReadIndex` and reads the local store directly;
   it may return an older view, but any projection it uses is still aligned to
   the fixed applied index of that local main-store snapshot.
-- `x-consistency: leader` routes the read to the node currently considered
-  leader. A call forwarded to a remote node does not propagate the consistency
-  metadata, so the remote call defaults to linearizable mode and performs its
-  quorum barrier. However, if the receiving node already considers itself
-  leader, `getLeaderCtrl` returns the local controller directly and skips
-  `ReadIndex`. Because `CheckQuorum` is disabled, an isolated former leader can
-  therefore serve stale local state in this mode. Projection-backed reads still
-  align to that local main-store snapshot even though no quorum horizon `R` is
-  available.
 - If a non-leader node is syncing or cannot complete its local barrier,
   `RoutedController` can transparently retry the read against the leader. The
   forwarded attempt can still fail when the leader is unavailable. If

docs/technical/architecture/subsystems/read-path/prepared-queries.md

@@ -72,8 +72,8 @@ A compile error at FSM time is hash-bound as an `AuditFailure`, so a checker run
 1. Opens the fixed main-store snapshot, then reads both the ledger schema and prepared query from that snapshot. This prevents a concurrent query/schema update or deletion from being combined with entities from a newer state. Because the stored definition determines whether an index will be used, the executor briefly reserves the event-history floor before opening the snapshot and releases it immediately when the loaded shape needs no index alignment.
 2. Verifies the requested mode is compatible with the query's `target` (e.g. `AGGREGATE_VOLUMES` only makes sense for accounts).
 3. Enters the standard read route. Default live consistency establishes a
-   `ReadIndexAndWait` horizon; `stale`, leader-local, and checkpoint reads have
-   the documented exceptions. The executor waits for read-index alignment only
+   `ReadIndexAndWait` horizon; `stale` and checkpoint reads have the documented
+   exceptions. The executor waits for read-index alignment only
    when `AlignmentOwed` is true — a non-nil filter or a LOGS target — then calls
    `Compile(indexSnap, kb, pq.GetFilter(), ...)` and executes the iterator.
 4. For `LIST`, streams the matching entities through the standard cursor pipeline (see [query-pipeline.md](query-pipeline.md)).

docs/technical/architecture/subsystems/read-path/query-pipeline.md

@@ -82,7 +82,7 @@ was used.
 
 Once both succeed, the local Pebble snapshot reflects state at least as fresh as the moment the request reached the cluster. This guarantees **linearizable reads on any node**: a read started after a successful write returns at least that write's effects, regardless of which node serves the read.
 
-If the node is syncing or otherwise unable to confirm `ReadIndex`, the call fails — callers either retry or forward to the leader. The explicit `leader` consistency mode remains available at this stage: a remote hop defaults to the linearizable path, while a node that already considers itself leader serves locally without `R` and still aligns every projection it uses to the fixed local `H` below.
+If the node is syncing or otherwise unable to confirm `ReadIndex`, the call fails — callers either retry or forward to the leader.
 
 ## Projection alignment — fixed Raft horizon
 

docs/technical/architecture/subsystems/read-path/query-profile.md

@@ -107,7 +107,7 @@ which:
 
 - **`min_log_sequence` catch-up.** `waitMinLogSequence` charges the
   `WaitForSequence` wait regardless of consistency level, and it runs before
-  routing — so `--consistency leader --min-log-sequence N` yields a non-zero
+  routing — so `--consistency stale --min-log-sequence N` yields a non-zero
   barrier on a perfectly healthy cluster, with no failed attempt anywhere.
 - **A failed `ReadIndex` attempt.** The syncing-follower fallback in
   `RoutedController.readCtrl` records the attempt and may then forward after it
@@ -245,9 +245,9 @@ locally-served one.
 
 ## Known gaps
 
-- **Leader-forwarded reads report only the local hop.** When a follower forwards
-  a read (`ConsistencyLeader`, or the syncing-node fallback in
-  `RoutedController.readCtrl`), the upstream RPC is charged to the local
+- **Leader-forwarded reads report only the local hop.** When a syncing follower
+  falls back to the leader in `RoutedController.readCtrl`, the upstream RPC is
+  charged to the local
   `execute` phase, so `execute` there conflates network hops, leader-side
   prepare, leader-side barrier and leader-side execution. `barrier_duration_us`
   covers only what this node attempted locally.

internal/adapter/grpc/consistency.go

@@ -15,10 +15,6 @@ const (
 	// ConsistencyStale skips the ReadIndex barrier and reads from the local store directly.
 	// Data may lag behind the latest committed index.
 	ConsistencyStale = "stale"
-	// ConsistencyLeader routes the read to the node currently considered leader.
-	// A remote leader applies the default ReadIndex barrier, but a node that
-	// already considers itself leader serves the read locally without one.
-	ConsistencyLeader = "leader"
 )
 
 const metadataKeyConsistency = "x-consistency"
@@ -86,7 +82,7 @@ func extractConsistency(ctx context.Context) context.Context {
 
 	level := strings.ToLower(strings.TrimSpace(vals[0]))
 	switch level {
-	case ConsistencyStale, ConsistencyLeader:
+	case ConsistencyStale:
 		return WithConsistency(ctx, level)
 	default:
 		return ctx

internal/adapter/grpc/consistency_test.go

@@ -16,14 +16,6 @@ func TestWithConsistency(t *testing.T) {
 	require.Equal(t, ConsistencyStale, level)
 }
 
-func TestWithConsistency_Leader(t *testing.T) {
-	t.Parallel()
-
-	ctx := WithConsistency(context.Background(), ConsistencyLeader)
-	level := ConsistencyFromContext(ctx)
-	require.Equal(t, ConsistencyLeader, level)
-}
-
 func TestConsistencyFromContext_Default(t *testing.T) {
 	t.Parallel()
 
@@ -82,15 +74,15 @@ func TestExtractConsistency_Stale(t *testing.T) {
 	require.Equal(t, ConsistencyStale, level)
 }
 
-func TestExtractConsistency_Leader(t *testing.T) {
+func TestExtractConsistency_LeaderIsNotSupported(t *testing.T) {
 	t.Parallel()
 
 	md := metadata.New(map[string]string{metadataKeyConsistency: "leader"})
 	ctx := metadata.NewIncomingContext(context.Background(), md)
 
 	ctx = extractConsistency(ctx)
 	level := ConsistencyFromContext(ctx)
-	require.Equal(t, ConsistencyLeader, level)
+	require.Equal(t, ConsistencyLinearizable, level)
 }
 
 func TestExtractConsistency_CaseInsensitive(t *testing.T) {
@@ -119,10 +111,10 @@ func TestExtractConsistency_Linearizable(t *testing.T) {
 func TestExtractConsistency_WhitespaceHandling(t *testing.T) {
 	t.Parallel()
 
-	md := metadata.New(map[string]string{metadataKeyConsistency: "  leader  "})
+	md := metadata.New(map[string]string{metadataKeyConsistency: "  stale  "})
 	ctx := metadata.NewIncomingContext(context.Background(), md)
 
 	ctx = extractConsistency(ctx)
 	level := ConsistencyFromContext(ctx)
-	require.Equal(t, ConsistencyLeader, level)
+	require.Equal(t, ConsistencyStale, level)
 }

internal/bootstrap/controller_routed.go

@@ -53,8 +53,6 @@ func (b *RoutedController) getLeaderCtrl() (ctrl.Controller, error) {
 // The consistency level is determined from the context (set by the gRPC interceptor):
 //   - linearizable (default): ReadIndex+WaitForApplied barrier on the local node
 //   - stale: skip the barrier and read from the local store directly
-//   - leader: route the read to the node currently considered leader; the local
-//     leader shortcut does not perform a ReadIndex barrier
 //
 // For linearizable reads, if the local node is still syncing the read is
 // transparently forwarded to the leader.
@@ -65,30 +63,10 @@ func (b *RoutedController) readCtrl(ctx context.Context) (ctrl.Controller, *node
 		trace.WithAttributes(attribute.String("consistency", consistency)))
 	defer span.End()
 
-	switch consistency {
-	case grpcadp.ConsistencyStale:
+	if consistency == grpcadp.ConsistencyStale {
 		span.SetAttributes(attribute.String("route", "local_stale"))
 
 		return b.localController, nil, nil
-	case grpcadp.ConsistencyLeader:
-		span.SetAttributes(attribute.String("route", "leader"))
-
-		c, err := b.getLeaderCtrl()
-		if err != nil {
-			return nil, nil, err
-		}
-
-		// When getLeaderCtrl returns a remote controller, that node runs its own
-		// ReadIndex barrier (x-consistency is not propagated, so it defaults to
-		// linearizable there). The remote barrier and execution are invisible to
-		// this profile — the whole remote cost arrives as row-production time
-		// inside the local execute phase, and this node's barrier_duration_us stays
-		// 0. Flag it so a reader does not take that 0 to mean "no barrier was
-		// needed" (EN-1859). When this node already considers itself leader,
-		// getLeaderCtrl returns the local controller and no barrier is performed.
-		b.markForwardedIfRemote(ctx, c)
-
-		return c, nil, nil
 	}
 
 	// The ReadIndex quorum round-trip plus the local WaitForApplied catch-up is
@@ -154,15 +132,6 @@ func (b *RoutedController) finishLeaderFallback(ctx context.Context, selected ct
 	return selected, nil, nil
 }
 
-// markForwardedIfRemote preserves the query-profile contract that Forwarded
-// means another node served the read. The explicit leader-consistency path can
-// resolve to the local controller when this node considers itself leader.
-func (b *RoutedController) markForwardedIfRemote(ctx context.Context, selected ctrl.Controller) {
-	if selected != b.localController {
-		query.ProfileFromContext(ctx).MarkForwarded()
-	}
-}
-
 func (b *RoutedController) withLocalBarrierHorizon(ctx context.Context, selected ctrl.Controller, barrier *node.ReadBarrierInfo) context.Context {
 	if selected == b.localController && barrier != nil {
 		return query.WithReadBarrierHorizon(ctx, barrier.CommitIndex)