Module access_path 

Access-path signal for CQL SELECT execution (Issue #960, Epic #951).

Why this exists

Correct result rows do not prove that a storage-layer prune/seek capability is actually wired into the CQL execution path. #949 returned the right rows while still scanning every SSTable and filtering in memory. Tests, reviewers, and (eventually) EXPLAIN output need an explicit, assertable signal for the access path a SELECT chose, so that an accidental fallback to a full scan cannot masquerade as a targeted lookup.

This module exposes:

1. AccessPath — a closed enum describing the access path a SELECT surface selected. Downstream issues (#958 work counters, #962 fast-path unification) consume this same enum, so the variant names are part of the public contract.
2. FallbackReason — a documented closed set of reasons a SELECT fell back to a full scan. Recording an honest reason here is mandatory: a path that still full-scans today MUST report AccessPath::FullScan or AccessPath::FallbackFullScan, never a fake targeted path.
3. A process-global probe (record, last, reset) that mirrors the scan_for_key_call_count pattern (issue #831). Because the streaming SELECT path executes inside a spawned task (a different thread), the probe is a process-global rather than a thread-local — that is the only mechanism observable from both the materializing and streaming paths and from an integration test without parsing logs. It is stored lock-free via arc_swap::ArcSwapOption (issue #1595): the signal was written on every SELECT, so a Mutex here was a process-wide serialization point (and a lock-poisoning surface) with no functional need.

Scope (per #960)

#960 only exposes and reports the path; it does not make every path targeted (that is #962 for the single-key metadata lookup and #1916 for the metadata IN (...) fan-out). The reported path must be honest — a metadata projection with no usable restriction still reports an honest AccessPath::FallbackFullScan, never a faked targeted path.

Enums

AccessPath

The access path a SELECT surface selected for a single SSTable-scan step.

FallbackReason

The documented, closed set of reasons a SELECT fell back to a full scan.

Functions

last

Read the most recently recorded access path, or None if none was recorded since the last reset.

record

Record the access path chosen by a SELECT SSTable-scan step.

reset

Clear the recorded access path. Tests call this before a query so a stale value from a previous query cannot satisfy the assertion.