surrealdb-core 3.3.1

use std::any::TypeId;
use std::borrow::Cow;
#[cfg(not(target_family = "wasm"))]
use std::collections::HashMap;
#[cfg(not(target_family = "wasm"))]
use std::collections::hash_map::Entry;
use std::collections::{BinaryHeap, HashSet};
use std::fmt::{self, Display};
#[cfg(storage)]
use std::path::PathBuf;
use std::pin::pin;
use std::sync::Arc;
use std::task::{Poll, ready};
use std::time::Duration;

#[allow(unused_imports)]
use anyhow::bail;
use anyhow::{Context as _, Result, ensure};
use arc_swap::ArcSwap;
use async_channel::Sender;
use bytes::{Bytes, BytesMut};
use common::time::{Instant, sleep, timeout, timeout_at};
use futures::{Future, Stream};
use rand::Rng;
use rand::distr::{Alphanumeric, SampleString};
use reblessive::TreeStack;
use surrealdb_cnf::ConfigMap;
use surrealdb_cnf::dynamic::DynamicConfiguration;
use surrealdb_datastore::triggers::CommitTriggers;
use surrealdb_datastore::values::graph::GraphFoldScope;
use surrealdb_kvs::TransactionType::*;
use surrealdb_kvs::{DestroyRange, DestroyRangeHandle, TransactionType};
use surrealdb_types::{AuthError, Error as TypesError, SurrealValue, object};
#[cfg(not(target_family = "wasm"))]
use tokio::spawn;
use tokio_util::sync::CancellationToken;
use tracing::{debug, instrument, trace, warn};
use uuid::Uuid;

use super::tx::Transaction;
use super::version::{MajorVersion, MigrationRecord, StorageVersion, VersionHistoryEntry};
use super::{INDEX_COMPACTION_QUEUE_BATCH_SIZE, migration};
use crate::api::err::ApiError;
use crate::api::invocation::process_api_request;
use crate::api::request::ApiRequest;
use crate::api::response::ApiResponse;
use crate::buc::manager::BucketsManager;
use crate::catalog::providers::{
	CatalogProvider, DatabaseProvider, NamespaceProvider, NodeProvider, RootProvider,
	TableProvider, UserProvider,
};
use crate::catalog::{Index, NodeLiveQuery};
use crate::config::RuntimeConfig;
use crate::ctx::{CancelHandle, Context, FrozenContext};
#[cfg(feature = "jwks")]
use crate::dbs::capabilities::NetTarget;
use crate::dbs::capabilities::{
	ArbitraryQueryTarget, EvalQueryTarget, ExperimentalTarget, MethodTarget, RouteTarget,
};
use crate::dbs::node::{Node, Timestamp};
use crate::dbs::{
	Capabilities, DurableSession, Executor, MessageBroker, Options, QueryResult,
	QueryResultBuilder, QueryStreamItem, QueryStreamJob, Session, TopLevelStatement,
	durable_session, restore_session,
};
use crate::doc::process_next_events_batch;
use crate::err::{EngineError, Error};
use crate::exe::FlowResultExt as _;
use crate::exec::Error as ExecError;
use crate::exec::config::ExecConfig;
use crate::exec::function::FunctionRegistry;
use crate::expr::model::get_model_path;
use crate::expr::statements::define::DefineKind;
use crate::expr::statements::{DefineModelStatement, DefineStatement, DefineUserStatement};
use crate::expr::user::UserDuration;
use crate::expr::{Base, Expr, Idiom, Literal, LogicalPlan, TopLevelExpr};
#[cfg(feature = "http")]
use crate::http::HttpClient;
use crate::iam::{Action, Auth, PolicyError, Resource, ResourceKind, Role, ScramCredential};
use crate::idx::IndexKeyBase;
use crate::idx::index::IndexOperation;
use crate::idx::trees::hnsw::index::HnswCompactionOutcome;
use crate::idx::trees::store::IndexStores;
use crate::key::reclaim::{Expunge, ReclaimKind, ReclaimState};
use crate::key::schema::{
	BootstrapKey, DbRoot, DocKeyPrefix, DocLookupIdentityPrefix, DocLookupPrefix, DocPendingPrefix,
	GraphFoldDirPrefix, GraphFoldKey, GraphFoldPrefix, IdxRoot, IndexCompactionIxPrefix,
	IndexCompactionKey, IndexCompactionPrefix, MigrationKey, MigrationPrefix, NodeKey,
	NodeLiveQueryKey, NodeLiveQueryPrefix, NsRoot, ReclaimKey, ReclaimPrefix, SessionKey,
	SessionPrefix, StorageVersionKey, SubscriptionKey, VersionHistoryPrefix, VersionKey,
};
use crate::key::{
	AnyRange, KVKey, KVKeyDecode, KVSubspace, KVValue, Key, KeyRange, RawRange, Resumable,
};
use crate::kvs::cache::ds::DatastoreCache;
use crate::kvs::clock::SystemClock;
use crate::kvs::index::{IndexBuilder, build_owner_is_live, build_owner_is_live_locked};
use crate::kvs::paging::{PageCompanion, PagedDelete, PagedOutcome};
use crate::kvs::request::{Dialect, QueryRequest, QuerySource};
use crate::kvs::sequences::Sequences;
use crate::kvs::slowlog::SlowLog;
use crate::kvs::tasklease::{LeaseHandler, TaskLeaseType};
#[cfg(test)]
use crate::kvs::testing::{
	NonRetryableErrorSite, RetryableConflictSite, maybe_inject_non_retryable_error,
	maybe_inject_retryable_conflict,
};
use crate::kvs::{
	CHANGEFEED_GC_PASS_KEY_BUDGET, DatastoreError, Direction, NORMAL_BATCH_SIZE,
	RECLAIM_BATCH_SIZE, RECLAIM_PASS_ENTRY_QUOTA, RECLAIM_PASS_KEY_BUDGET, TransactionFactory,
	is_retryable_transaction_conflict,
};
use crate::lq::LiveQueryRouter;
use crate::observe::ExecutionObserver;
use crate::options::EngineOptions;
use crate::sql::Ast;
#[cfg(feature = "surrealism")]
use crate::surrealism::cache::SurrealismCache;
use crate::syn::parser::{ParserSettings, StatementStream};
use crate::syn::{ParseError, ParserConfig};
use crate::types::{PublicNotification, PublicValue, PublicVariables};
use crate::val::{MAX_VALUE_DEPTH, convert_value_to_public_value};
use crate::{CommunityComposer, syn};

mod builder;
pub(crate) mod config;

pub use builder::Builder;
pub use config::LiveQueryEngine;

const TARGET: &str = "surrealdb::core::kvs::ds";
const NODE_DELETE_TIMEOUT: Duration = Duration::from_secs(60);

/// How long [`Datastore::shutdown`] waits for the maintenance tasks to finish
/// their in-flight pass before giving up on a clean stop.
///
/// A pass is left to finish because the storage engine shutdown that follows
/// refuses every commit, so an interrupted pass fails rather than completes.
/// That cannot be an unbounded wait: an async event runs user-defined
/// SurrealQL, whose duration nothing here bounds, so a single non-terminating
/// event would otherwise hold shutdown open forever. On expiry the remaining
/// handles are dropped and shutdown proceeds; the abandoned pass then has its
/// commits refused, which is the same outcome as a crash at that instant.
const MAINTENANCE_SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(30);

/// How long [`Datastore::retry_bootstrap`] waits for storage to become able to
/// serve the version bootstrap before giving up.
///
/// Sized to outlast the cluster formation of a distributed backend, which is
/// the condition it exists to wait out. The server's own
/// `SURREAL_STARTUP_OPERATION_TIMEOUT` is a shorter ceiling by default and is
/// the knob an operator reaches for; this bound only stops an embedder that has
/// no such ceiling from waiting forever.
const BOOTSTRAP_RETRY_BUDGET: Duration = Duration::from_secs(120);

/// How long one bootstrap attempt may run before it is abandoned and retried.
const BOOTSTRAP_RETRY_ATTEMPT_TIMEOUT: Duration = Duration::from_secs(10);

/// The gap before the first bootstrap retry, doubled on each further attempt up
/// to [`BOOTSTRAP_RETRY_MAX_BACKOFF`].
const BOOTSTRAP_RETRY_MIN_BACKOFF: Duration = Duration::from_millis(100);

/// The longest gap between two bootstrap attempts.
const BOOTSTRAP_RETRY_MAX_BACKOFF: Duration = Duration::from_secs(5);

/// How many times the back-off may double, which is as many as it takes to
/// reach [`BOOTSTRAP_RETRY_MAX_BACKOFF`] from
/// [`BOOTSTRAP_RETRY_MIN_BACKOFF`].
const BOOTSTRAP_RETRY_MAX_DOUBLINGS: u32 = 6;

// Capping the exponent is only sound while the cap still reaches the ceiling:
// stop short of it and the back-off would silently settle below its documented
// maximum if either bound were retuned.
const _: () = assert!(
	BOOTSTRAP_RETRY_MIN_BACKOFF.as_millis() << BOOTSTRAP_RETRY_MAX_DOUBLINGS
		>= BOOTSTRAP_RETRY_MAX_BACKOFF.as_millis(),
	"the bootstrap back-off cannot double its way up to its own ceiling"
);

/// How often a bootstrap that is still retrying reports that it is still going.
///
/// The cadence is on the log, not on the retries: attempts run as fast as the
/// back-off allows, and one in every interval is reported.
const BOOTSTRAP_RETRY_LOG_INTERVAL: Duration = Duration::from_secs(5);

/// The role assigned to the initial user created when starting the server with
/// credentials for the first time
const INITIAL_USER_ROLE: &str = "owner";

/// Whether a reclaim pass emptied the prefix it was given.
///
/// `Complete` licenses the caller to retire the queue entry. `Incomplete` means
/// the entry's durable resume cursor has advanced but keys remain, so the entry
/// must stay queued for a later pass to finish — retiring it then would orphan
/// the remainder with nothing left to find it.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ReclaimOutcome {
	Complete,
	Incomplete,
	/// The queue entry was deleted by someone else while the reclaim was
	/// running, withdrawing the claim that the prefix is orphaned. Nothing more
	/// may be deleted from it.
	Cancelled,
	/// The task lease passed to another node mid-reclaim. Like `Incomplete` for
	/// this entry, but the pass itself must stop rather than move on to the next
	/// entry: a lease check is throttled to one datastore read per maintenance
	/// period, so the reclaim consumed the read a fresh check here would depend
	/// on and that check would report the lease held without asking.
	LeaseLost,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ShutdownNodeDeleteOutcome {
	Archived,
	Failed,
	TimedOut,
}

async fn await_node_step<T, Fut>(
	deadline: Instant,
	timeout_duration: Duration,
	canceller: Option<&CancellationToken>,
	step: Fut,
) -> Result<T>
where
	Fut: Future<Output = Result<T>>,
{
	if let Some(canceller) = canceller {
		tokio::select! {
			biased;
			_ = canceller.cancelled() => bail!(EngineError::QueryCancelled),
			result = timeout_at(deadline, step) => match result {
				Ok(result) => result,
				Err(_) => bail!(EngineError::QueryTimedout(timeout_duration)),
			},
		}
	} else {
		match timeout_at(deadline, step).await {
			Ok(result) => result,
			Err(_) => bail!(EngineError::QueryTimedout(timeout_duration)),
		}
	}
}

async fn await_node_tx_step<T, Fut>(
	txn: &Transaction,
	deadline: Instant,
	timeout_duration: Duration,
	canceller: Option<&CancellationToken>,
	step: Fut,
) -> Result<T>
where
	Fut: Future<Output = Result<T>>,
{
	let result = if let Some(canceller) = canceller {
		tokio::select! {
			biased;
			_ = canceller.cancelled() => {
				let _ = txn.cancel().await;
				bail!(EngineError::QueryCancelled);
			}
			result = timeout_at(deadline, step) => result,
		}
	} else {
		timeout_at(deadline, step).await
	};

	match result {
		Ok(Ok(value)) => Ok(value),
		Ok(Err(e)) => {
			let _ = txn.cancel().await;
			Err(e)
		}
		Err(_) => {
			let _ = txn.cancel().await;
			bail!(EngineError::QueryTimedout(timeout_duration))
		}
	}
}

fn archive_node_for_shutdown(
	timeout_duration: Duration,
	result: Result<()>,
) -> ShutdownNodeDeleteOutcome {
	match result {
		Ok(()) => ShutdownNodeDeleteOutcome::Archived,
		Err(e) => {
			if matches!(crate::err::engine_error(&e), Some(EngineError::QueryTimedout(_))) {
				warn!(
					target: TARGET,
					timeout = ?timeout_duration,
					"Timed out archiving node during shutdown; continuing shutdown"
				);
				return ShutdownNodeDeleteOutcome::TimedOut;
			}

			warn!(
				target: TARGET,
				error = %e,
				"Failed to archive node during shutdown; continuing shutdown"
			);
			ShutdownNodeDeleteOutcome::Failed
		}
	}
}

/// The underlying datastore instance which stores the dataset.
pub struct Datastore {
	transaction_factory: TransactionFactory,
	/// Cancellation for this datastore's own background work, tripped by
	/// [`Self::shutdown`].
	shutdown: CancellationToken,
	/// Handles for this datastore's maintenance tasks, so [`Self::shutdown`]
	/// can wait for them to stop.
	///
	/// A datastore is not a working database without them — index compaction,
	/// tombstone reclaim, changefeed GC, index-build recovery and the cluster
	/// heartbeat all live there — so the builder starts them rather than
	/// leaving it to the embedder. `None` for a datastore built with
	/// [`Builder::without_maintenance_tasks`](self::builder::Builder::without_maintenance_tasks),
	/// until [`Self::start_maintenance_tasks`] is called on it.
	maintenance: parking_lot::Mutex<Option<crate::kvs::tasks::Tasks>>,
	/// The cadences the maintenance tasks run at, kept so
	/// [`Self::start_maintenance_tasks`] starts them on the same schedule the
	/// builder was given rather than on whatever its caller passes in.
	engine_options: EngineOptions,
	/// Serialises [`Self::shutdown`] across the holders of this datastore.
	///
	/// The sequence has to run start to finish for exactly one caller at a time:
	/// it stops the maintenance tasks *before* closing the storage engine, and a
	/// second caller that skipped straight to the storage shutdown would close
	/// the engine out from under a pass the first caller is still waiting on.
	/// Later callers therefore block here and observe the completed sequence.
	shutdown_lock: tokio::sync::Mutex<()>,
	/// The unique id of this datastore, used in notifications.
	id: Uuid,
	/// Whether this process created the datastore's storage.
	///
	/// Latched by [`Self::check_version`], because the underlying signal is
	/// one-shot: it comes from writing the version key, and a caller that
	/// retries after a later failure would otherwise see the key already there
	/// and be told the datastore is pre-existing.
	created_here: std::sync::atomic::AtomicBool,
	/// Whether authentication is enabled on this datastore.
	auth_enabled: bool,
	/// The maximum duration timeout for running multiple statements in a query.
	dynamic_configuration: DynamicConfiguration,
	/// The slow log configuration determining when a query should be logged
	slow_log: Option<SlowLog>,
	/// The maximum duration timeout for running multiple statements in a
	/// transaction.
	transaction_timeout: Option<Duration>,
	/// The security and feature capabilities for this datastore.
	capabilities: ArcSwap<Capabilities>,
	/// Broker used to deliver live-query notifications after their write commits.
	///
	/// `Some` iff live-query subscribers exist for this datastore (the broker owns the sender
	/// half of the notification channel internally). `None` disables live-query work entirely
	/// at the executor boundary.
	live_query_broker: Option<Arc<dyn MessageBroker>>,
	/// Per-node live-query router state (the tail cursor over the `lqe`
	/// keyspace). Only used when `config.datastore.live_query_engine` is
	/// `Router`, where the router is the sole notification delivery path. See
	/// [`crate::lq`].
	live_query_router: Arc<LiveQueryRouter>,
	/// Public HTTP endpoint this datastore publishes on its `Node` catalog row so other
	/// cluster members can route cross-node messages (e.g. live-query relay) to it.
	/// `None` in deployments that don't expose such an endpoint.
	http_endpoint: Option<String>,
	// The index store cache
	index_stores: IndexStores,
	// The cross transaction cache
	cache: Arc<DatastoreCache>,
	/// Cache of generated GraphQL schemas, shared across every transport that
	/// serves GraphQL: the HTTP `/graphql` route, GraphQL-over-WebSocket
	/// subscriptions, the `graphql` RPC method, and the MCP `graphql` tool.
	/// Keyed by `(ns, db, config, schema-fingerprint)` so DDL changes invalidate
	/// it automatically.
	#[cfg(all(feature = "graphql", not(target_family = "wasm")))]
	graphql_schema_cache: crate::graphql::cache::GraphQLSchemaCache,
	/// Registry of built-in scalar, aggregate, projection and index
	/// functions, along with the method-dispatch table. Built once when the
	/// datastore is constructed and shared across all transactions via the
	/// `Arc`. The executor clones this `Arc` onto the `RootContext` of every
	/// statement rather than rebuilding the registry, which is otherwise the
	/// single biggest per-query cost.
	function_registry: Arc<FunctionRegistry>,
	// The index asynchronous builder
	index_builder: IndexBuilder,
	#[cfg(storage)]
	// The temporary directory
	temporary_directory: Option<Arc<PathBuf>>,
	// Map of bucket connections
	buckets: BucketsManager,
	// The sequences
	sequences: Sequences,
	// The surrealism cache
	#[cfg(feature = "surrealism")]
	surrealism_cache: Arc<SurrealismCache>,
	/// When `true`, surrealism modules are loaded lazily on first use
	/// instead of being eagerly compiled at startup.
	#[cfg(feature = "surrealism")]
	lazy_surrealism: bool,
	/// Post-commit wake-ups shared with every transaction: async event
	/// processing, and index compaction so the compactor runs on the write
	/// instead of waiting out its interval.
	triggers: Arc<CommitTriggers>,
	/// The per-layer configuration every query executed on this datastore
	/// reaches through its context, plus the datastore's own knobs.
	config: Arc<RuntimeConfig>,
	/// The parser depth limits applied to every query text parsed for this
	/// datastore. Shared with the transports, which decode request bodies
	/// against the same limits.
	parser_config: Arc<ParserConfig>,
	// Http client used to make requests.
	#[cfg(feature = "http")]
	http_client: ArcSwap<HttpClient>,
	/// Observer invoked on significant events. Defaults to [`NoopObserver`].
	observer: Arc<dyn ExecutionObserver>,
}

pub(crate) use surrealdb_kvs::{Metrics, TransactionBuilder};

/// Transaction-builder construction result with router startup state.
///
/// The datastore consumes `builder`; server startup threads `router_state` into
/// the router factory so embedders can make immutable handles available to
/// their HTTP routes without process globals.
pub struct TransactionBuilderParts<S> {
	/// Transaction builder consumed by the datastore.
	pub builder: Box<dyn TransactionBuilder>,
	/// Immutable router startup state produced by the composer.
	pub router_state: S,
}

impl<S> TransactionBuilderParts<S> {
	/// Construct transaction-builder parts with router startup state.
	pub fn new(builder: Box<dyn TransactionBuilder>, router_state: S) -> Self {
		Self {
			builder,
			router_state,
		}
	}
}

impl TransactionBuilderParts<()> {
	/// Construct transaction-builder parts for composers without router state.
	pub fn without_router_state(builder: Box<dyn TransactionBuilder>) -> Self {
		Self::new(builder, ())
	}
}

/// Factory that parses a datastore path and returns a concrete `TransactionBuilder`.
///
/// Implementations can decide how to interpret connection strings (e.g. "memory",
/// "rocksdb:...", "tikv:...") and which clock to use. This lets the CLI and
/// server be generic over different storage backends without hard-coding them.
///
/// The `path_valid` helper is used by the CLI to validate the path early and
/// provide better error messages before starting the runtime.
pub trait TransactionBuilderFactory: Send + Sync + 'static {
	/// Immutable state threaded into router construction after datastore startup.
	type RouterState: Clone + Send + Sync + 'static;

	/// Create a new transaction builder for the datastore.
	///
	/// # Parameters
	/// - `path`: Database connection path string
	/// - `canceller`: Token for graceful shutdown and cancellation of long-running operations
	fn new_transaction_builder(
		&self,
		path: &str,
		canceller: CancellationToken,
		config: ConfigMap,
	) -> impl Future<Output = Result<TransactionBuilderParts<Self::RouterState>>> + Send;

	/// Validate a datastore path string.
	fn path_valid(&self, v: &str) -> Result<String>;

	/// Returns the stable datastore node id used for live-query ownership metadata.
	///
	/// Composers that run SurrealDB inside a clustered product should return a deterministic
	/// value so remote writers can route notifications back to the node that owns each
	/// subscriber connection.
	fn datastore_node_id(&self) -> Option<[u8; 16]> {
		None
	}

	/// Creates the broker that receives buffered live-query notifications after commit.
	///
	/// The default broker is local-only and preserves community behaviour. Clustered composers
	/// can return a broker that forwards remote targets without changing transaction results on
	/// delivery failure.
	fn live_query_broker(&self, channel: Sender<PublicNotification>) -> Arc<dyn MessageBroker> {
		crate::dbs::LocalMessageBroker::new(channel)
	}

	/// Public HTTP endpoint this datastore should publish for cross-node messaging.
	///
	/// Clustered composers surface their local node's endpoint here so the [`Datastore`]
	/// can record it on the `Node` catalog row, making it discoverable by peer nodes
	/// (e.g. for the live-query relay). Returns `None` in single-node and shared-backend
	/// deployments that don't expose a cross-node messaging endpoint.
	fn http_endpoint(&self) -> Option<String> {
		None
	}
}

impl TransactionBuilderFactory for CommunityComposer {
	type RouterState = ();

	async fn new_transaction_builder(
		&self,
		path: &str,
		canceller: CancellationToken,
		config: ConfigMap,
	) -> Result<TransactionBuilderParts<Self::RouterState>> {
		let builder = surrealdb_kvs_any::Backends::community()
			.new_transaction_builder(path, canceller, config)
			.await?;
		Ok(TransactionBuilderParts::without_router_state(builder))
	}

	fn path_valid(&self, v: &str) -> Result<String> {
		Ok(surrealdb_kvs_any::Backends::community().path_valid(v)?)
	}
}

impl Display for Datastore {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		f.write_str(self.transaction_factory.backend_name())
	}
}

/// One reclaim queue entry in the running for this pass's key budget.
///
/// Ordered by how long the entry has been waiting — oldest observation first,
/// and the queue's key order between entries observed in the same millisecond so
/// selection is deterministic. Held in a max-heap capped at
/// [`RECLAIM_PASS_ENTRY_QUOTA`], where "greatest" is the newest and so the first
/// to lose its place.
struct ReclaimCandidate {
	/// When the reclaim task first observed the entry. Zero only where the grace
	/// is disabled, in which case every candidate ties and key order decides.
	observed_ms: u64,
	/// The queue key, as the scan returned it.
	key: Vec<u8>,
	/// The state read during the walk, carrying the resume cursor the delete
	/// continues from.
	state: ReclaimState,
}

impl Ord for ReclaimCandidate {
	fn cmp(&self, other: &Self) -> std::cmp::Ordering {
		self.observed_ms.cmp(&other.observed_ms).then_with(|| self.key.cmp(&other.key))
	}
}

impl PartialOrd for ReclaimCandidate {
	fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
		Some(self.cmp(other))
	}
}

impl PartialEq for ReclaimCandidate {
	fn eq(&self, other: &Self) -> bool {
		self.cmp(other) == std::cmp::Ordering::Equal
	}
}

impl Eq for ReclaimCandidate {}

impl Datastore {
	pub fn builder() -> Builder {
		Builder::new()
	}

	async fn retry_index_operation_conflict(
		err: &anyhow::Error,
		operation: impl Into<String>,
	) -> bool {
		if is_retryable_transaction_conflict(err) {
			let operation = operation.into();
			debug!(
				target: TARGET,
				operation = %operation,
				error = %err,
				"retryable index operation conflict, retrying"
			);
			sleep(Duration::from_millis(100)).await;
			true
		} else {
			false
		}
	}

	async fn cancel_and_retry_index_operation_conflict(
		txn: &Transaction,
		err: &anyhow::Error,
		operation: impl Into<String>,
	) -> bool {
		let _ = txn.cancel().await;
		Self::retry_index_operation_conflict(err, operation).await
	}

	/// Creates a new datastore instance
	///
	/// # Examples
	///
	/// ```rust,no_run
	/// # use surrealdb_core::kvs::Datastore;
	/// # use anyhow::Error;
	/// # #[tokio::main]
	/// # async fn main() -> Result<(),Error> {
	/// let ds = Datastore::new("memory").await?;
	/// # Ok(())
	/// # }
	/// ```
	///
	/// Or to create a file-backed store:
	///
	/// ```rust,no_run
	/// # use surrealdb_core::kvs::Datastore;
	/// # use anyhow::Error;
	/// # #[tokio::main]
	/// # async fn main() -> Result<(),Error> {
	/// let ds = Datastore::new("surrealkv://temp.skv").await?;
	/// # Ok(())
	/// # }
	/// ```
	///
	/// Or to connect to a tikv-backed distributed store:
	///
	/// ```rust,no_run
	/// # use surrealdb_core::kvs::Datastore;
	/// # use anyhow::Error;
	/// # #[tokio::main]
	/// # async fn main() -> Result<(),Error> {
	/// let ds = Datastore::new("tikv://127.0.0.1:2379").await?;
	/// # Ok(())
	/// # }
	/// ```
	/// The datastore is returned shared, because it starts background
	/// maintenance tasks that hold a [`Weak`](std::sync::Weak) reference to it.
	/// Because those tasks write, this also settles the datastore's storage
	/// version before any of them starts, so the datastore is handed back
	/// already stamped; [`Self::check_version`] is still what checks that this
	/// build can read what was found, and what runs any migrations owed.
	///
	/// Use [`Builder::without_maintenance_tasks`] for a quiescent datastore, or
	/// for one whose tasks start later under the caller's own ordering.
	pub async fn new(path: &str) -> Result<Arc<Self>> {
		Builder::new().build_with_path(path).await
	}

	/// Registers metrics for the current datastore flavor if supported.
	///
	/// This will return a list of available metrics and their descriptions.
	pub fn register_metrics(&self) -> Option<Metrics> {
		self.transaction_factory.register_metrics()
	}

	/// Collects a specific u64 metric by name if supported by the datastore flavor.
	///
	/// - `metric`: The name of the metric to collect.
	pub fn collect_u64_metric(&self, metric: &str) -> Option<u64> {
		self.transaction_factory.collect_u64_metric(metric)
	}

	/// The currently installed observer. Cheap to clone; internal handle is
	/// an `Arc`.
	///
	/// Exposed so higher layers (server, SDK) can emit transport-layer events
	/// such as session connect/disconnect that the core engine never sees.
	pub fn observer(&self) -> &Arc<dyn ExecutionObserver> {
		&self.observer
	}

	/// Create a new datastore with the same persistent data (inner), with
	/// flushed cache. Simulating a server restart
	///
	/// The restarted datastore carries **no** maintenance tasks: it is returned
	/// unshared, so there is nothing for a task to hold a `Weak` to. Callers
	/// that need them call [`Self::start_maintenance_tasks`] once they have
	/// shared it.
	pub fn restart(self) -> Self {
		self.buckets.clear();
		Self {
			shutdown: CancellationToken::new(),
			maintenance: parking_lot::Mutex::new(None),
			engine_options: self.engine_options,
			shutdown_lock: tokio::sync::Mutex::new(()),
			id: self.id,
			auth_enabled: self.auth_enabled,
			dynamic_configuration: DynamicConfiguration::default(),
			slow_log: self.slow_log,
			transaction_timeout: self.transaction_timeout,
			capabilities: ArcSwap::new(self.capabilities.load_full()),
			live_query_broker: self.live_query_broker,
			// Fresh router cursor: a restarted node re-establishes its baseline.
			live_query_router: Arc::new(LiveQueryRouter::new()),
			http_endpoint: self.http_endpoint,
			index_stores: IndexStores::new(
				self.config.idx.hnsw_cache_size,
				self.config.idx.diskann_cache_size,
				self.config.idx.graph_resolve_cache_size,
				self.config.idx.segment_dictionary_path.clone(),
			),
			index_builder: IndexBuilder::new(self.transaction_factory.clone()),
			#[cfg(storage)]
			temporary_directory: self.temporary_directory,
			cache: Arc::new(DatastoreCache::new(self.config.datastore.datastore_cache_size)),
			#[cfg(all(feature = "graphql", not(target_family = "wasm")))]
			graphql_schema_cache: crate::graphql::cache::GraphQLSchemaCache::default(),
			function_registry: Arc::new(FunctionRegistry::with_builtins()),
			buckets: self.buckets,
			sequences: Sequences::new(self.transaction_factory.clone(), self.id),
			transaction_factory: self.transaction_factory,
			created_here: std::sync::atomic::AtomicBool::new(false),
			triggers: self.triggers,
			#[cfg(feature = "surrealism")]
			surrealism_cache: Arc::new(SurrealismCache::new(
				self.config.surrealism.surrealism_cache_size,
			)),
			#[cfg(feature = "surrealism")]
			lazy_surrealism: self.lazy_surrealism,
			#[cfg(feature = "http")]
			http_client: self.http_client,
			observer: self.observer,
			config: self.config,
			parser_config: self.parser_config,
		}
	}

	/// Create a test-only datastore facade that shares the same durable KV engine
	/// while resetting process-local state.
	///
	/// This lets unit tests model two SurrealDB compute nodes connected to the
	/// same storage backend without starting an external service. The cloned
	/// facade deliberately reuses the transaction factory, but gets its own node
	/// id, index builder, index stores, datastore cache, sequences, and other
	/// process-local caches. Tests that exercise cluster liveness should call
	/// [`Self::insert_node`] for both the original datastore and the fork.
	#[cfg(test)]
	#[cfg_attr(not(feature = "kv-mem"), allow(dead_code))]
	pub(crate) fn fork_for_test_with_node_id(&self, id: Uuid) -> Self {
		let transaction_factory = self.transaction_factory.clone();
		Self {
			// A fork is unshared, so it carries no maintenance tasks.
			shutdown: CancellationToken::new(),
			maintenance: parking_lot::Mutex::new(None),
			engine_options: self.engine_options,
			shutdown_lock: tokio::sync::Mutex::new(()),
			id,
			auth_enabled: self.auth_enabled,
			dynamic_configuration: self.dynamic_configuration.clone(),
			slow_log: self.slow_log.clone(),
			transaction_timeout: self.transaction_timeout,
			capabilities: ArcSwap::new(self.capabilities.load_full()),
			live_query_broker: self.live_query_broker.clone(),
			// A fork models a separate node, so it gets its own router cursor.
			live_query_router: Arc::new(LiveQueryRouter::new()),
			http_endpoint: self.http_endpoint.clone(),
			index_stores: IndexStores::new(
				self.config.idx.hnsw_cache_size,
				self.config.idx.diskann_cache_size,
				self.config.idx.graph_resolve_cache_size,
				self.config.idx.segment_dictionary_path.clone(),
			),
			index_builder: IndexBuilder::new(transaction_factory.clone()),
			#[cfg(storage)]
			temporary_directory: self.temporary_directory.clone(),
			cache: Arc::new(DatastoreCache::new(self.config.datastore.datastore_cache_size)),
			#[cfg(all(feature = "graphql", not(target_family = "wasm")))]
			graphql_schema_cache: crate::graphql::cache::GraphQLSchemaCache::default(),
			function_registry: Arc::new(FunctionRegistry::with_builtins()),
			buckets: self.buckets.clone(),
			sequences: Sequences::new(transaction_factory.clone(), id),
			transaction_factory,
			created_here: std::sync::atomic::AtomicBool::new(false),
			triggers: Arc::clone(&self.triggers),
			#[cfg(feature = "surrealism")]
			surrealism_cache: Arc::new(SurrealismCache::new(
				self.config.surrealism.surrealism_cache_size,
			)),
			#[cfg(feature = "surrealism")]
			lazy_surrealism: self.lazy_surrealism,
			#[cfg(feature = "http")]
			http_client: ArcSwap::new(self.http_client.load_full()),
			observer: Arc::clone(&self.observer),
			config: Arc::clone(&self.config),
			parser_config: Arc::clone(&self.parser_config),
		}
	}

	/// Set the node id for this datastore.
	pub fn with_node_id(mut self, id: Uuid) -> Self {
		self.id = id;
		self
	}

	/// Set a global transaction timeout for this Datastore
	pub fn with_transaction_timeout(mut self, duration: Option<Duration>) -> Self {
		self.transaction_timeout = duration;
		self
	}

	/// Get the configured transaction timeout, if any
	pub(crate) fn transaction_timeout(&self) -> Option<Duration> {
		self.transaction_timeout
	}

	/// The configured write-cardinality limit for statement transactions
	/// (`transaction_max_write_keys`), or `None` when the guard is disabled.
	pub(crate) fn transaction_max_write_keys(&self) -> Option<std::num::NonZeroU64> {
		std::num::NonZeroU64::new(self.transaction_factory.max_write_keys())
	}

	/// Get the configured global query timeout, if any.
	///
	/// This is the deadline set by `--query-timeout` /
	/// `SURREAL_QUERY_TIMEOUT`. Beyond being applied as an executor deadline
	/// in [`Self::setup_ctx`], the transports reuse this value as a
	/// wall-clock guard so a non-yielding hang (or engine work not bounded by
	/// the deadline) still terminates the request. A return value of `None`
	/// means no timeout is enforced.
	pub fn query_timeout(&self) -> Option<Duration> {
		self.dynamic_configuration.get_query_timeout()
	}

	/// Returns the broker used to flush live-query notifications after commit.
	pub(crate) fn live_query_broker(&self) -> Option<Arc<dyn MessageBroker>> {
		self.live_query_broker.clone()
	}

	/// Looks up the public HTTP endpoint that the cluster member with `node_id`
	/// has published on its `Node` catalog row.
	///
	/// Returns `Ok(None)` when the row exists but no endpoint is set, or when
	/// no such node has registered. Used by clustered live-query relays to
	/// resolve the target node's address at delivery time without consulting
	/// any in-memory cluster topology.
	pub async fn lookup_node_endpoint(&self, node_id: Uuid) -> Result<Option<String>> {
		let txn = self.transaction(Read).await?;
		let key = NodeKey {
			nd: node_id,
		};
		let res = txn.get_key(&key, None).await?;
		// Always cancel a read transaction; we don't write through it.
		let _ = txn.cancel().await;
		Ok(res.and_then(|node: Node| node.http_endpoint))
	}

	#[cfg(storage)]
	/// Set a temporary directory for ordering of large result sets
	pub fn with_temporary_directory(mut self, path: Option<PathBuf>) -> Self {
		self.temporary_directory = path.map(Arc::new);
		self
	}

	/// Configure whether surrealism modules are loaded lazily on first use
	/// rather than eagerly at startup.
	#[cfg(feature = "surrealism")]
	pub fn with_lazy_surrealism(mut self, lazy: bool) -> Self {
		self.lazy_surrealism = lazy;
		self
	}

	/// Returns `true` if surrealism modules are loaded lazily.
	#[cfg(feature = "surrealism")]
	pub fn is_lazy_surrealism(&self) -> bool {
		self.lazy_surrealism
	}

	pub fn index_store(&self) -> &IndexStores {
		&self.index_stores
	}

	/// Is authentication enabled for this Datastore?
	pub fn is_auth_enabled(&self) -> bool {
		self.auth_enabled
	}

	pub fn id(&self) -> Uuid {
		self.id
	}

	/// Does the datastore allow excecuting an RPC method?
	///
	/// Dispatch enforces this itself, so a transport does not have to. It is
	/// public so a transport can also *report* the answer ahead of time: the
	/// gRPC service advertises the methods an operator has denied, so a client
	/// can avoid calls it already knows will be refused.
	pub fn allows_rpc_method(&self, method_target: &MethodTarget) -> bool {
		self.capabilities.load().allows_rpc_method(method_target)
	}

	/// Does the datastore allow requesting an HTTP route?
	/// This function needs to be public to allow access from the CLI crate.
	pub fn allows_http_route(&self, route_target: &RouteTarget) -> bool {
		self.capabilities.load().allows_http_route(route_target)
	}

	/// Is the user allowed to query?
	pub fn allows_query_by_subject(&self, subject: impl Into<ArbitraryQueryTarget>) -> bool {
		self.capabilities.load().allows_query(&subject.into())
	}

	/// Is the user allowed to invoke the `eval::*` functions?
	pub fn allows_eval_query_by_subject(&self, subject: impl Into<EvalQueryTarget>) -> bool {
		self.capabilities.load().allows_eval_query(&subject.into())
	}

	/// Does the datastore allow connections to a network target?
	#[cfg(feature = "jwks")]
	pub(crate) fn allows_network_target(&self, net_target: &NetTarget) -> bool {
		self.capabilities.load().allows_network_target(net_target)
	}

	/// The datastore's current capabilities snapshot.
	pub fn get_capabilities(&self) -> Arc<Capabilities> {
		self.capabilities.load_full()
	}

	/// Replace the datastore's capabilities at runtime.
	///
	/// The swap is atomic and lock-free. In-flight queries keep the snapshot
	/// they captured when they started (the executor clones the `Arc` once at
	/// query start), so only queries begun after this call observe the new
	/// capabilities. This cannot exceed what the binary was compiled to
	/// support — a capability whose machinery is not compiled in stays inert
	/// regardless of what is set here.
	///
	/// When the `http` feature is enabled this also rebuilds the outbound HTTP
	/// client so its redirect and DNS net filter track the new `allow_net` /
	/// `deny_net`. Without that, a runtime net *tightening* would be enforced on
	/// a request's initial URL (checked against the live snapshot) but not on
	/// redirect hops, whose filter is baked in at client construction. Building
	/// the client can fail, hence the `Result`; on failure the capabilities are
	/// left unchanged.
	pub fn set_capabilities(&self, capabilities: Capabilities) -> anyhow::Result<()> {
		#[cfg(feature = "http")]
		let http_client = HttpClient::new(
			capabilities.allow_net.clone(),
			capabilities.deny_net.clone(),
			&self.config.http,
		)?;
		self.capabilities.store(Arc::new(capabilities));
		#[cfg(feature = "http")]
		self.http_client.store(Arc::new(http_client));
		Ok(())
	}

	#[cfg(feature = "jwks")]
	pub(crate) fn cache(&self) -> &Arc<DatastoreCache> {
		&self.cache
	}

	/// The function registry every query on this datastore resolves names
	/// through. Handed to the executor, which seats it on the `RootContext`
	/// of each statement.
	pub(crate) fn function_registry(&self) -> &Arc<FunctionRegistry> {
		&self.function_registry
	}

	pub(super) fn clock_now(&self) -> Timestamp {
		SystemClock::new().now()
	}

	/// Verifies the datastore's storage version and applies any data migrations
	/// it owes, returning that version and whether this process created the
	/// datastore.
	///
	/// **Call this before serving any query against a datastore that may
	/// predate this build.** A datastore is not fully readable until its
	/// migrations have run: [`Datastore::new`] and the builder do not call this,
	/// so an embedder that skips it against pre-3.3 storage sees sequences that
	/// appear not to exist — which `DEFINE SEQUENCE ... IF NOT EXISTS` will then
	/// recreate, resetting an allocator that has already issued values.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn check_version(&self) -> Result<(MajorVersion, bool)> {
		let (version, is_new) = self.settle_storage_version().await?;
		// Check we are running the latest version
		if !version.is_latest() {
			bail!(DatastoreError::OutdatedStorageVersion {
				expected: MajorVersion::latest().into(),
				actual: version.into(),
			});
		}
		// `get_version` reports a datastore as new only on the start that wrote
		// `!v`. Everything below can fail transiently and be retried by the
		// caller, and that retry finds the key present — so the flag is latched on
		// the datastore rather than re-derived, or a caller keying default
		// namespace creation off it would silently skip that on the second pass.
		let is_new =
			self.created_here.fetch_or(is_new, std::sync::atomic::Ordering::SeqCst) || is_new;
		// Bring the datastore's semantic version stamp up to this build, applying
		// any data migrations the gap between the two calls for. Not wrapped in
		// `retry`, which caps each attempt at ten seconds: a migration may run for
		// much longer, and the driver handles contention itself through a task
		// lease.
		migration::run(self, is_new).await?;
		// Everything ok
		Ok((version, is_new))
	}

	/// Settles the datastore's major storage version, stamping it if it carries
	/// none, and reports whether this call was the one that stamped it.
	///
	/// The marker half of [`Self::check_version`], separated because the builder
	/// owes it before it starts any writer but must not do the rest: the
	/// migrations that follow the gate run under a lease with no bound on how
	/// long they take, which is not something a constructor may hold a caller
	/// for.
	///
	/// Retries because the storage layer may not be able to serve a transaction
	/// yet, and because concurrent instances conflict over the version key.
	/// Callers that want the gate — the check that this build can read what it
	/// found — want [`Self::check_version`].
	pub(crate) async fn settle_storage_version(&self) -> Result<(MajorVersion, bool)> {
		Self::retry_bootstrap("Check version", || self.get_version()).await
	}

	/// The full semantic version the datastore has been advanced to.
	///
	/// `None` for a datastore last written before 3.3, the release that
	/// introduced the stamp. Its major version is still available from
	/// [`Self::get_version`].
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn storage_version(&self) -> Result<Option<StorageVersion>> {
		let txn = self.transaction(Read).await?;
		let version = catch!(txn, txn.get_key(&StorageVersionKey {}, None).await);
		txn.cancel().await?;
		Ok(version)
	}

	/// Every version this datastore has been advanced to, oldest first.
	///
	/// One entry per version transition, not per startup: a node that starts
	/// against a datastore already stamped at its own version adds nothing.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn version_history(&self) -> Result<Vec<VersionHistoryEntry>> {
		let txn = self.transaction(Read).await?;
		let range = catch!(txn, VersionHistoryPrefix {}.range());
		let entries = catch!(txn, txn.getr(range, None).await);
		txn.cancel().await?;
		Ok(entries.into_iter().map(|(_, entry)| entry).collect())
	}

	/// Every data migration applied to this datastore, in the order they were
	/// declared.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip_all)]
	/// Paired with the ledger id the entry was filed under, which is a
	/// migration's identity; the name in the record is documentation and may be
	/// reworded between releases.
	pub async fn applied_migrations(&self) -> Result<Vec<(u32, MigrationRecord)>> {
		Ok(self
			.applied_migration_ids()
			.await?
			.into_iter()
			.filter_map(|(id, record)| record.map(|r| (id, r)))
			.collect())
	}

	/// Every applied migration's ledger id, with its record when that record is
	/// readable by this build.
	///
	/// A record written in a revision this build does not know decodes to
	/// `None` rather than failing the call. The id comes from the key, and the
	/// key's presence is what marks a migration as applied — so a record this
	/// build cannot read must still be reportable, since that is exactly the
	/// state a downgrade needs to be told about.
	pub async fn applied_migration_ids(&self) -> Result<Vec<(u32, Option<MigrationRecord>)>> {
		let txn = self.transaction(Read).await?;
		let range = catch!(txn, MigrationPrefix {}.range());
		let rows = catch!(txn, txn.getr_raw(range, None).await);
		txn.cancel().await?;
		rows.into_iter()
			.map(|(key, value)| {
				let id = MigrationKey::decode_key(&key)?.id;
				Ok((id, MigrationRecord::kv_decode_value(&value, ()).ok()))
			})
			.collect()
	}

	/// Reads the datastore's major storage version, stamping it on a datastore
	/// that carries none, and reports whether this call was the one that
	/// stamped it.
	///
	/// # What `!v`'s absence means
	///
	/// `!v` was introduced in 2.0, so a datastore that holds data but no `!v`
	/// was either written by a build that predates it — a genuine v1 store,
	/// which must be refused as out of date — or created by a later build whose
	/// bootstrap was interrupted after something else wrote but before `!v`
	/// landed. Nothing in the bytes tells those apart, so the second case
	/// records itself: [`BootstrapKey`] is committed before `!v` and removed in
	/// the same transaction that writes it, and its presence is what licenses
	/// this call to complete the interrupted bootstrap instead of refusing it.
	/// Without it, `MajorVersion::v1()` is the only safe reading, and an
	/// interrupted bootstrap would be stamped v1 permanently.
	///
	/// # Ordering
	///
	/// The sentinel is only a fallback: nothing may write to a datastore before
	/// its version is settled. That ordering is structural — the builder settles
	/// the version before it starts any maintenance task, and a caller that
	/// starts them itself does so after this has run (see
	/// [`Datastore::start_maintenance_tasks`]). The sentinel is what keeps a
	/// writer that escapes it anyway — a future job, a storage engine with keys
	/// of its own — from turning a fresh datastore into an unstartable one.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn get_version(&self) -> Result<(MajorVersion, bool)> {
		#[cfg(test)]
		maybe_inject_non_retryable_error(NonRetryableErrorSite::VersionBootstrapBegin, self.id)?;
		// Start a new writeable transaction
		let txn = self.transaction(Write).await?.enclose();
		// Create the key where the version is stored
		let key = VersionKey {};
		// Check if a version is already set in storage
		if let Some(val) = catch!(txn, txn.get_key(&key, None).await) {
			// We didn't write anything, so just rollback
			catch!(txn, txn.cancel().await);
			// Return the current version
			return Ok((val, false));
		}
		// No version is set. Either nothing has ever stamped this datastore, or
		// a previous start began stamping it and did not finish.
		if let Some(target) = catch!(txn, txn.get_key(&BootstrapKey {}, None).await) {
			// An interrupted bootstrap left the sentinel behind, so whatever is
			// in storage was written by a versioned build and no pre-versioning
			// layout can be present: the sentinel is only ever written after the
			// probe below has found the datastore empty, and from that moment
			// the only writers are versioned builds, none of which can serve a
			// query until this call has passed. That is what licenses completing
			// the job rather than refusing it — but not at just any version.
			//
			// The two directions are not symmetric. Finishing a bootstrap an
			// *older* build began is sound at this build's own version: the
			// residue such a build can leave is cluster state a newer build
			// reads, and no user data can exist to owe a migration, because
			// serving a query requires the stamp this call has not yet written.
			// Finishing one a *newer* build began is not: stamping the datastore
			// down a major version would pass this build's own gate against
			// bytes it may not understand, and would leave the build that
			// started the job reading back a stamp it refuses. So that case is
			// declined without writing, which keeps the sentinel intact for the
			// build that can finish it, and returns the target so the gate above
			// reports what is actually on disk.
			if u16::from(target) > MajorVersion::LATEST {
				catch!(txn, txn.cancel().await);
				warn!(
					target: TARGET,
					target = u16::from(target),
					running = MajorVersion::LATEST,
					"This datastore's initialisation was begun by a newer version of SurrealDB \
					and can only be completed by it. Run that version, or use a clean storage \
					directory if this is intended to be a new instance."
				);
				return Ok((target, false));
			}
			let version = MajorVersion::latest();
			warn!(
				target: TARGET,
				target = u16::from(target),
				version = u16::from(version),
				"Completing a datastore initialisation that a previous start left unfinished."
			);
			catch!(txn, txn.replace_key(&key, &version).await);
			catch!(txn, txn.del_key(&BootstrapKey {}).await);
			catch!(txn, txn.commit().await);
			return Ok((version, true));
		}
		// Fetch any key at all, other than the version keys themselves. This has
		// to span the whole byte space rather than the declared root: the point
		// of the probe is data this release does not describe, which by
		// definition need not sit under `/`. Finding any such key means the
		// store predates versioning and must not be stamped as current.
		let range = RawRange::every_key_after(&VersionKey {}.encode_key()?);
		let keys = catch!(txn, txn.keys_raw(range, 1, 0, None).await);
		if !keys.is_empty() {
			// There were keys in storage, so this is an upgrade.
			// Log the first key found for diagnostic purposes.
			warn!(
				target: TARGET,
				first_key = ?keys.first().map(|k| format!("{:?}", k)),
				"No version key found but existing data detected in storage. \
				This storage contains data from a previous SurrealDB version. \
				The server will not start until the data is migrated or removed."
			);
			let version = MajorVersion::v1();
			catch!(txn, txn.replace_key(&key, &version).await);
			catch!(txn, txn.commit().await);
			return Ok((version, true));
		}
		// The datastore is empty, so this start is creating it. Claim it with the
		// sentinel in a transaction of its own: the two writes cannot share one,
		// because the whole point is for the sentinel to outlive a failure of the
		// stamp below. The sentinel sorts before `!v` and so below the probe
		// above, which is what keeps a datastore holding nothing else reading as
		// empty rather than as data of unknown provenance.
		let version = MajorVersion::latest();
		catch!(txn, txn.set_key(&BootstrapKey {}, &version).await);
		catch!(txn, txn.commit().await);
		// Stamp the version and retire the sentinel. Should this fail, the next
		// attempt takes the resume branch above and finishes the job.
		#[cfg(test)]
		maybe_inject_non_retryable_error(NonRetryableErrorSite::VersionBootstrapStamp, self.id)?;
		self.finish_bootstrap(version).await
	}

	/// Stamps `!v` and retires the sentinel, completing a bootstrap this node
	/// claimed.
	///
	/// Re-reads `!v` rather than writing over it blindly, for two reasons that
	/// both come from this being a second transaction. Another node may have
	/// claimed the same empty datastore, seen this node's sentinel and finished
	/// the job in between, in which case this node did not create the datastore
	/// and must not report that it did — two nodes both returning `is_new` have
	/// both of them creating the default namespace, and the loser fails startup
	/// on a namespace that already exists. And reading the key in the same
	/// transaction that writes it is what arms a write conflict on backends that
	/// detect one, which a blind replace would not.
	pub(crate) async fn finish_bootstrap(
		&self,
		version: MajorVersion,
	) -> Result<(MajorVersion, bool)> {
		let key = VersionKey {};
		let txn = self.transaction(Write).await?.enclose();
		if let Some(existing) = catch!(txn, txn.get_key(&key, None).await) {
			catch!(txn, txn.cancel().await);
			return Ok((existing, false));
		}
		catch!(txn, txn.replace_key(&key, &version).await);
		catch!(txn, txn.del_key(&BootstrapKey {}).await);
		catch!(txn, txn.commit().await);
		Ok((version, true))
	}

	// --------------------------------------------------
	// Initialisation functions
	// --------------------------------------------------

	/// Setup the initial cluster access credentials
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn initialise_credentials(&self, user: &str, pass: &str) -> Result<()> {
		// Retry because concurrent instances may conflict when creating the root user
		Self::retry("Initialise credentials", || self.initialise_credentials_attempt(user, pass))
			.await
	}

	/// Single attempt to create the root user if none exists.
	/// Separated from `initialise_credentials` so it can be wrapped in the retry loop.
	async fn initialise_credentials_attempt(&self, user: &str, pass: &str) -> Result<()> {
		// Start a new writeable transaction
		let txn = self.transaction(Write).await?.enclose();
		// Fetch the root users from the storage
		let users = catch!(txn, txn.all_root_users(None).await);
		// Process credentials, depending on existing users
		if users.is_empty() {
			// Display information in the logs
			info!(target: TARGET, "Credentials were provided, and no root users were found. The root user '{user}' will be created");
			// Create and new root user definition
			let stm = define_user_statement_new_with_password(
				Base::Root,
				user.to_owned(),
				pass,
				INITIAL_USER_ROLE.to_owned(),
			);
			let opt = Options::new(&ExecConfig::default())
				.with_auth(Arc::new(Auth::for_root(Role::Owner)));
			let mut ctx = self.setup_ctx()?;
			ctx.set_transaction(Arc::clone(&txn));
			let ctx = ctx.freeze();
			let mut stack = TreeStack::new();
			let res = stack
				.enter(|stk| {
					crate::legacy::define_user_statement_compute(&stm, stk, &ctx, &opt, None)
				})
				.finish()
				.await;
			catch!(txn, res);
			// We added a user, so commit the transaction
			txn.commit().await
		} else {
			// Display information in the logs
			warn!(target: TARGET, "Credentials were provided, but existing root users were found. The root user '{user}' will not be created");
			warn!(target: TARGET, "Consider removing the --user and --pass arguments from the server start command");
			// We didn't write anything, so just rollback
			txn.cancel().await
		}
	}

	/// Setup the default namespace and database
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn initialise_defaults(&self, namespace: &str, database: &str) -> Result<()> {
		info!(target: TARGET, "This is a new SurrealDB instance. Initialising default namespace '{namespace}' and database '{database}'");
		// Create the SQL statement
		let sql = r"
			DEFINE NAMESPACE $namespace COMMENT 'Default namespace generated by SurrealDB';
		USE NS $namespace;
		DEFINE DATABASE $database COMMENT 'Default database generated by SurrealDB';
		DEFINE CONFIG DEFAULT NAMESPACE $namespace DATABASE $database;
		"
		.to_string();

		// Create the variables
		let vars = map! {
			"namespace".to_string() => namespace.to_string().into_value(),
			"database".to_string() => database.to_string().into_value(),
		};

		// Execute the SQL statement
		self.execute(
			&sql,
			&Session::owner(),
			Some(vars.into_iter().collect::<std::collections::BTreeMap<_, _>>().into()),
		)
		.await?;
		// Everything ok
		Ok(())
	}

	/// Performs a database import from SQL, for a startup script.
	///
	/// Delegates to [`Self::import`] rather than repeating it, so that a dump
	/// restored by `--import-file` is parsed under the same profile as one
	/// restored by `surreal import`. Parsed under the datastore's configured
	/// query limits instead, this entry point would refuse depths that an
	/// export is required to be able to write back.
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn startup(&self, sql: &str, sess: &Session) -> Result<Vec<QueryResult>> {
		// Output function invocation details to logs
		trace!(target: TARGET, "Running datastore startup import script");
		// Execute the SQL import
		self.import(sql, sess).await
	}

	/// Starts this datastore's maintenance tasks, if they are not already
	/// running.
	///
	/// The builder starts them itself, and settles the storage version first, so
	/// this exists for a caller that built with
	/// [`Builder::without_maintenance_tasks`] in order to own that ordering.
	/// Such a caller owes the same sequence, because these tasks write: the
	/// node-membership refresh blindly upserts this node's row, and every leased
	/// job writes its lease. A write that lands before `!v` does makes a
	/// datastore this process created indistinguishable from one written before
	/// `!v` existed, which [`Datastore::get_version`] is obliged to refuse as
	/// out of date. Call this only once [`Datastore::check_version`] has
	/// returned.
	///
	/// Idempotent: a datastore that already carries its tasks is left alone.
	pub fn start_maintenance_tasks(self: &Arc<Self>) {
		let mut maintenance = self.maintenance.lock();
		if maintenance.is_some() {
			return;
		}
		*maintenance =
			Some(crate::kvs::tasks::init(self, self.shutdown.clone(), &self.engine_options));
	}

	/// Whether this datastore's maintenance tasks are running.
	///
	/// A datastore that never starts them is a database with no index
	/// compaction, no tombstone reclaim, no changefeed GC, no index-build
	/// recovery and no cluster heartbeat — none of which announces itself, so a
	/// caller that defers the start with
	/// [`Builder::without_maintenance_tasks`](self::builder::Builder::without_maintenance_tasks)
	/// has this to assert against.
	pub fn maintenance_tasks_running(&self) -> bool {
		self.maintenance.lock().is_some()
	}

	/// Run the datastore shutdown tasks, performing any necessary cleanup
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn shutdown(&self) -> Result<()> {
		// Output function invocation details to logs
		trace!(target: TARGET, "Running datastore shutdown operations");
		// One caller runs the whole sequence at a time. The steps below are
		// ordered — tasks stopped before the storage engine closes — and a
		// concurrent caller that found the handles already taken would otherwise
		// skip the wait and close the engine while the first caller's pass was
		// still using it. Later callers block here and return once the sequence
		// they were waiting on has finished.
		let _shutting_down = self.shutdown_lock.lock().await;
		// Stop this datastore's maintenance tasks first. They open transactions
		// of their own, and the storage engine shutdown below refuses every
		// commit once it has run, so a pass still in flight would fail rather
		// than finish. Cancelling is idempotent, so a caller that already
		// cancelled its own token — as the server and the embedded engine do —
		// loses nothing by reaching here.
		self.shutdown.cancel();
		// Taken rather than borrowed: the guard must not be held across the
		// await, and the handles are consumed by resolving them.
		let tasks = self.maintenance.lock().take();
		if let Some(tasks) = tasks {
			// Bounded: a pass runs user-defined SurrealQL in the async event
			// case, so waiting for one to finish cannot be waiting forever.
			if timeout(MAINTENANCE_SHUTDOWN_TIMEOUT, tasks.resolve()).await.is_err() {
				warn!(
					target: TARGET,
					"Maintenance tasks did not stop within {MAINTENANCE_SHUTDOWN_TIMEOUT:?}; \
					 continuing shutdown without them"
				);
			}
		}
		// Local index builder tasks are deliberately left running: the storage
		// engine shutdown below stops the commit coordinator first, after which
		// every commit is refused before it applies (see the engine
		// `Transaction::commit` gate). An in-flight build therefore makes no
		// durable change during shutdown and stays at its last committed
		// checkpoint, so the periodic resume scan continues it after restart —
		// exactly as it would after a crash.
		// Archive this datastore in the cluster, but don't let a blocked
		// metadata transaction prevent storage engine shutdown.
		let _ = archive_node_for_shutdown(
			NODE_DELETE_TIMEOUT,
			self.delete_node_with_timeout(NODE_DELETE_TIMEOUT).await,
		);
		// Run any storage engine shutdown tasks
		self.transaction_factory.shutdown().await
	}

	/// Waits until the storage backend is able to serve transactions.
	///
	/// Startup awaits this before opening its first transaction. A backend that
	/// can serve as soon as it is built returns immediately; one that has to
	/// join a cluster and catch up first blocks here for as long as that takes,
	/// which keeps a legitimately slow join from being charged against a
	/// caller's retry budget. `Err` means the backend will never serve.
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn wait_until_serve_ready(&self) -> Result<()> {
		self.transaction_factory.wait_until_serve_ready().await
	}

	/// Drop every version of every key in the half-open range `[start, end)`
	/// **outside** any user transaction.
	///
	/// Resolves the backend's [`DestroyRange`] capability through the
	/// [`TransactionBuilder::extension`] hook and delegates to it. A backend
	/// that does not offer the capability yields
	/// [`crate::kvs::Error::RangeDestroyNotSupported`]: nothing was deleted, so
	/// a caller holding a transactional fallback matches on that error and
	/// takes it, and every other caller propagates rather than mistaking an
	/// unperformed destroy for a completed one.
	///
	/// The destruction bypasses MVCC, so the caller owns two guarantees: the
	/// data is already logically inaccessible (typically because a committed
	/// transaction cleared the catalog entry naming it), and any snapshot that
	/// could still read it has expired.
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip(self), fields(rng = range.to_string()))]
	pub async fn unsafe_destroy_range(&self, range: KeyRange<'static>) -> Result<()> {
		let Some(ops) = self.destroy_range_ops() else {
			return Err(crate::kvs::Error::RangeDestroyNotSupported.into());
		};
		ops.destroy_range(range).await.map_err(Into::into)
	}

	/// Resolve the backend's out-of-transaction range-destroy capability.
	///
	/// `None` means the backend cannot destroy a range outside a transaction —
	/// either it has no such primitive, or its current configuration cannot use
	/// the one it has. Resolved by capability rather than by backend name, so
	/// callers stay free of per-backend `cfg` arms and a new capable backend
	/// needs no change here.
	fn destroy_range_ops(&self) -> Option<Arc<dyn DestroyRange>> {
		let ext = self.transaction_factory.extension(TypeId::of::<DestroyRangeHandle>())?;
		let handle = ext.downcast::<DestroyRangeHandle>().ok()?;
		Some(Arc::clone(&handle.0))
	}

	/// Advance the MVCC garbage-collection safepoint by `lifetime`.
	///
	/// Routes through the backend's [`TransactionBuilder::extension`] hook;
	/// no-op on backends other than TiKV. Background tasks call this on
	/// `EngineOptions::tikv_gc_interval` and shutdown runs one final
	/// advisory pass.
	pub(crate) async fn run_mvcc_gc(&self, lifetime: Duration) -> Result<()> {
		#[cfg(feature = "kv-tikv")]
		if let Some(ops) = self.tikv_ops() {
			return ops.run_mvcc_gc(lifetime).await.map_err(Into::into);
		}
		let _ = lifetime;
		Ok(())
	}

	/// Resolve stale transactional locks left by crashed clients.
	///
	/// Routes through the backend's [`TransactionBuilder::extension`] hook;
	/// no-op on backends other than TiKV. Background tasks call this on
	/// `EngineOptions::tikv_lock_cleanup_interval`.
	pub(crate) async fn run_lock_cleanup(&self, lifetime: Duration) -> Result<()> {
		#[cfg(feature = "kv-tikv")]
		if let Some(ops) = self.tikv_ops() {
			return ops.run_lock_cleanup(lifetime).await.map_err(Into::into);
		}
		let _ = lifetime;
		Ok(())
	}

	/// Number of in-flight transactions tracked by the backend, when
	/// available. `None` indicates the backend does not track this.
	pub fn in_flight_transaction_count(&self) -> Option<usize> {
		#[cfg(feature = "kv-tikv")]
		if let Some(ops) = self.tikv_ops() {
			return Some(ops.in_flight_transaction_count());
		}
		None
	}

	/// Resolve the TiKV operational extension handle, if the backend is
	/// TiKV. Returns `None` for every other flavour.
	#[cfg(feature = "kv-tikv")]
	fn tikv_ops(&self) -> Option<Arc<surrealdb_kvs_any::tikv::TikvOpsHandle>> {
		let ext = self
			.transaction_factory
			.extension(TypeId::of::<surrealdb_kvs_any::tikv::TikvOpsHandle>())?;
		ext.downcast::<surrealdb_kvs_any::tikv::TikvOpsHandle>().ok()
	}

	// --------------------------------------------------
	// Surrealism eager loading
	// --------------------------------------------------

	/// Pre-load all Surrealism module runtimes into the cache so that
	/// subsequent query planning can resolve function metadata (e.g. the
	/// `writeable` flag) without triggering on-demand compilation.
	///
	/// Modules are loaded in parallel using a `JoinSet`. Any individual
	/// failure is logged but does not abort the overall loading process.
	#[cfg(feature = "surrealism")]
	pub async fn eager_load_surrealism_modules(&self) {
		use crate::catalog::providers::{DatabaseProvider, NamespaceProvider};
		use crate::surrealism::cache::SurrealismCacheLookup;

		let txn = match self.transaction(Read).await {
			Ok(txn) => Arc::new(txn),
			Err(e) => {
				warn!(target: TARGET, error = %e, "Surrealism eager load: failed to open transaction");
				return;
			}
		};

		let mut ctx = match self.setup_ctx() {
			Ok(ctx) => ctx,
			Err(e) => {
				warn!(target: TARGET, error = %e, "Surrealism eager load: failed to set up context");
				return;
			}
		};
		ctx.set_transaction(Arc::clone(&txn));
		let ctx = ctx.freeze();

		let nss = match txn.all_ns(None).await {
			Ok(nss) => nss,
			Err(e) => {
				warn!(target: TARGET, error = %e, "Surrealism eager load: failed to list namespaces");
				return;
			}
		};

		// Collect all module lookups first, then load in parallel.
		struct ModuleLookup {
			ns_id: crate::catalog::NamespaceId,
			db_id: crate::catalog::DatabaseId,
			bucket: String,
			key: String,
			display_name: String,
		}

		let mut lookups = Vec::new();
		for ns in nss.iter() {
			let dbs = match txn.all_db(ns.namespace_id, None).await {
				Ok(dbs) => dbs,
				Err(e) => {
					warn!(
						target: TARGET,
						error = %e, ns = %ns.name,
						"Surrealism eager load: failed to list databases"
					);
					continue;
				}
			};
			for db in dbs.iter() {
				let modules = match txn.all_db_modules(ns.namespace_id, db.database_id, None).await
				{
					Ok(m) => m,
					Err(e) => {
						warn!(
							target: TARGET,
							error = %e, ns = %ns.name, db = %db.name,
							"Surrealism eager load: failed to list modules"
						);
						continue;
					}
				};
				for md in modules.iter() {
					if let crate::catalog::ModuleExecutable::Surrealism(s) = &md.executable {
						lookups.push(ModuleLookup {
							ns_id: ns.namespace_id,
							db_id: db.database_id,
							bucket: s.bucket.clone(),
							key: s.key.clone(),
							display_name: md
								.name
								.clone()
								.unwrap_or_else(|| "<unnamed>".to_string()),
						});
					}
				}
			}
		}

		if lookups.is_empty() {
			debug!(target: TARGET, "Surrealism eager load: no modules to load");
			return;
		}

		let total = lookups.len();
		debug!(target: TARGET, count = total, "Surrealism eager load: loading modules");

		let concurrency =
			std::thread::available_parallelism().map(|n| n.get()).unwrap_or(8).clamp(2, 16);
		let load_sem = std::sync::Arc::new(tokio::sync::Semaphore::new(concurrency));

		let mut join_set = tokio::task::JoinSet::new();
		for lookup in lookups {
			let ctx = Arc::clone(&ctx);
			let load_sem = Arc::clone(&load_sem);
			join_set.spawn(async move {
				let _permit = load_sem
					.acquire_owned()
					.await
					.expect("Surrealism eager load semaphore must not be closed");
				let cache_lookup = SurrealismCacheLookup::File(
					&lookup.ns_id,
					&lookup.db_id,
					&lookup.bucket,
					&lookup.key,
				);
				match ctx.get_surrealism_runtime(cache_lookup).await {
					Ok(_) => {
						debug!(
							target: TARGET,
							module = %lookup.display_name,
							"Surrealism eager load: loaded module"
						);
						true
					}
					Err(e) => {
						warn!(
							target: TARGET,
							module = %lookup.display_name,
							error = %e,
							"Surrealism eager load: failed to load module"
						);
						false
					}
				}
			});
		}

		let mut loaded = 0usize;
		let mut failed = 0usize;
		while let Some(result) = join_set.join_next().await {
			match result {
				Ok(true) => loaded += 1,
				Ok(false) => failed += 1,
				Err(e) => {
					warn!(target: TARGET, error = %e, "Surrealism eager load: task panicked");
					failed += 1;
				}
			}
		}

		if failed > 0 {
			warn!(
				target: TARGET,
				loaded, failed, total,
				"Surrealism eager load: completed with failures"
			);
		} else {
			tracing::info!(
				target: TARGET,
				loaded, total,
				"Surrealism eager load: all modules loaded"
			);
		}
	}

	// --------------------------------------------------
	// Node functions
	// --------------------------------------------------

	/// Initialise the cluster and run bootstrap utilities
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn bootstrap(&self) -> Result<()> {
		// Each bootstrap step is retried independently, because concurrent instances
		// writing to the same cluster metadata keys may cause transaction conflicts.
		// Insert this node in the cluster
		Self::retry("Insert node", || self.insert_node()).await?;
		// Mark inactive nodes as archived
		Self::retry("Expire nodes", || self.expire_nodes()).await?;
		// Remove archived nodes
		Self::retry("Remove nodes", || self.remove_nodes()).await?;
		// Everything ok
		Ok(())
	}

	/// Runs a startup precondition until it succeeds or its budget runs out,
	/// retrying *every* failure rather than only a transaction conflict.
	///
	/// Almost every failure [`Self::get_version`] can report is the storage
	/// layer declining to serve a transaction. On a distributed backend that is
	/// what forming a cluster looks like from the outside — a replica refuses
	/// writes while a view change is in flight — and it clears on its own once
	/// formation settles. Those refusals are not distinguishable from each other
	/// by class, which is why the loop retries by default rather than by
	/// allow-list.
	///
	/// The exception is [`Self::is_permanent_bootstrap_failure`]: a marker whose
	/// bytes this build cannot read is a property of the disk, and waiting on it
	/// costs twice over — the caller waits out the whole budget, and the server,
	/// whose own ceiling is shorter, then reports a timeout in place of the error
	/// that would have named the problem.
	///
	/// The wait is bounded, and progress is reported on a fixed cadence rather
	/// than per attempt, so a long formation is visible in the log without the
	/// log growing with the retry rate.
	///
	/// The server wraps this in its own `SURREAL_STARTUP_OPERATION_TIMEOUT`
	/// budget, which is the operator-facing ceiling and is shorter than
	/// [`BOOTSTRAP_RETRY_BUDGET`] by default. This bound is what stops an
	/// embedder, which has no such wrapper, from waiting forever.
	/// Whether a bootstrap failure is a property of the bytes on disk rather
	/// than of the storage layer's availability.
	///
	/// These name a datastore this build cannot read, and no amount of waiting
	/// changes that. Matched by type rather than by rendered text, which is what
	/// the server's equivalent has to fall back on across the crate boundary.
	fn is_permanent_bootstrap_failure(err: &anyhow::Error) -> bool {
		err.chain().any(|e| {
			matches!(
				e.downcast_ref::<DatastoreError>(),
				Some(
					DatastoreError::InvalidStorageVersion
						| DatastoreError::OutdatedStorageVersion { .. }
						| DatastoreError::MigratedBeyondStorageVersion { .. }
				)
			)
		})
	}

	async fn retry_bootstrap<F, Fut, R>(task: &str, func: F) -> Result<R>
	where
		F: Fn() -> Fut,
		Fut: Future<Output = Result<R>>,
	{
		let started = Instant::now();
		let mut last_reported = started;
		let mut attempt = 1u32;
		// `None` after an attempt that never answered, which has no error to
		// carry; the report below distinguishes the two.
		let mut last_error = None;
		loop {
			let remaining = BOOTSTRAP_RETRY_BUDGET.saturating_sub(started.elapsed());
			if remaining.is_zero() {
				break;
			}
			// Bound the attempt itself as well as the budget: a backend that
			// accepts the transaction and then never answers would otherwise
			// spend the whole budget on one attempt.
			let attempt_timeout = BOOTSTRAP_RETRY_ATTEMPT_TIMEOUT.min(remaining);
			match timeout(attempt_timeout, func()).await {
				Ok(Ok(result)) => {
					if attempt > 1 {
						info!(
							target: TARGET,
							task, attempt, elapsed = ?started.elapsed(),
							"Storage became available and the startup step completed."
						);
					}
					return Ok(result);
				}
				Ok(Err(e)) if Self::is_permanent_bootstrap_failure(&e) => return Err(e),
				Ok(Err(e)) => last_error = Some(e),
				Err(_) => last_error = None,
			}
			// One line per interval, whatever the attempt rate, and the first
			// failure always reports so a wait is never silent.
			if attempt == 1 || last_reported.elapsed() >= BOOTSTRAP_RETRY_LOG_INTERVAL {
				last_reported = Instant::now();
				match &last_error {
					Some(e) => info!(
						target: TARGET,
						task, attempt, elapsed = ?started.elapsed(),
						budget = ?BOOTSTRAP_RETRY_BUDGET, error = %e,
						"Storage is not ready for the startup step yet; still retrying."
					),
					None => info!(
						target: TARGET,
						task, attempt, elapsed = ?started.elapsed(),
						budget = ?BOOTSTRAP_RETRY_BUDGET,
						timeout = ?attempt_timeout,
						"The startup step did not answer within its attempt timeout; still retrying."
					),
				}
			}
			let remaining = BOOTSTRAP_RETRY_BUDGET.saturating_sub(started.elapsed());
			if remaining.is_zero() {
				break;
			}
			// Exponential back-off with jitter, so the nodes of a cluster that
			// all restarted together do not retry in lockstep. The exponent is
			// capped before it is applied, not after: `Duration`'s multiplication
			// panics on overflow, so a doubling left to run free would abort the
			// process rather than saturate at the ceiling below it.
			let doublings = (attempt - 1).min(BOOTSTRAP_RETRY_MAX_DOUBLINGS);
			let backoff = (BOOTSTRAP_RETRY_MIN_BACKOFF * 2u32.pow(doublings))
				.min(BOOTSTRAP_RETRY_MAX_BACKOFF)
				.mul_f64(rand::rng().random_range(0.5..=1.5))
				.min(remaining);
			sleep(backoff).await;
			attempt = attempt.saturating_add(1);
		}
		match last_error {
			Some(e) => Err(e).context(format!(
				"{task} failed after {attempt} attempts over {:?}",
				started.elapsed()
			)),
			None => bail!(EngineError::Internal(format!(
				"{task} timed out after {attempt} attempts over {:?}",
				started.elapsed()
			))),
		}
	}

	/// Retries an async operation until it succeeds or the global timeout elapses.
	///
	/// Only [`TransactionConflict`](crate::kvs::Error::TransactionConflict)
	/// errors are retried; any other error is returned immediately to the
	/// caller. On each retryable failure a randomized delay (0–10 s) is
	/// applied before the next attempt, adding jitter to reduce repeated
	/// collisions when multiple instances start concurrently against the
	/// same storage backend.
	///
	/// The global timeout is checked only after a *failed* attempt; a successful
	/// result is always returned immediately, even if the elapsed time
	/// exceeds the budget. Each attempt's timeout is the lesser of its
	/// natural timeout (10 s * attempt number) and the remaining global
	/// budget, so total wall-clock time never significantly exceeds the
	/// global timeout. If no attempt succeeds within the budget, an error
	/// is returned.
	async fn retry<F, Fut, R>(task: &str, func: F) -> Result<R>
	where
		F: Fn() -> Fut,
		Fut: Future<Output = Result<R>>,
	{
		let global_timeout = Duration::from_secs(120);
		let per_attempt_timeout = Duration::from_secs(10);
		let time = Instant::now();
		let mut last_error = None;
		let mut attempt = 1;
		loop {
			// Cap each attempt to the remaining global budget
			let remaining = global_timeout.saturating_sub(time.elapsed());
			if remaining.is_zero() {
				break;
			}
			let attempt_timeout = (per_attempt_timeout * attempt).min(remaining);
			if let Ok(result) = timeout(attempt_timeout, func()).await {
				match result {
					Ok(result) => return Ok(result),
					Err(e) => {
						// Only retry on transaction conflict errors. Both the
						// bare `kvs::Error` and the `err::Error::Kvs`-wrapped
						// shape occur here: every `Transaction` write goes
						// through `.map_err(Error::from)`, and the operations
						// this loop retries all reach the store that way, so a
						// backend that surfaces a conflict at set/delete time
						// rather than at commit produces the wrapped one.
						if crate::kvs::is_retryable_transaction_conflict(&e) {
							last_error = Some(e);
						} else {
							return Err(e);
						}
					}
				}
			}
			// Check if the global timeout has been exceeded
			if time.elapsed() >= global_timeout {
				break;
			}
			// Randomized back-off capped to the remaining budget
			let remaining = global_timeout.saturating_sub(time.elapsed());
			if remaining.is_zero() {
				break;
			}
			let tempo = Duration::from_secs(rand::rng().random_range(0..10)).min(remaining);
			sleep(tempo).await;
			attempt += 1;
		}
		if let Some(e) = last_error {
			error!(target: TARGET, "{task} - All {attempt} attempts failed. Last error: {e}");
		} else {
			error!(target: TARGET, "{task} - All {attempt} attempts failed.");
		}
		bail!(EngineError::Internal(format!(
			"{task} failed after {attempt} attempts due to timeout"
		)));
	}

	/// Registers this node's cluster membership entry with a fresh heartbeat.
	///
	/// Must be run at server or database startup. The write is idempotent:
	/// the entry at `Nd::new(self.id)` is owned by this node, so the call
	/// upserts the row whether or not a previous lifetime of the same node
	/// id left a record behind. This supports deployments where the node id
	/// is stable across restarts (e.g. a stateful cluster member reusing
	/// its durable storage) without forcing the operator to clean up state
	/// between runs.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn insert_node(&self) -> Result<()> {
		// Log when this method is run
		trace!(target: TARGET, id = %self.id,"Inserting node in the cluster");
		// Refresh system usage metrics
		crate::sys::refresh().await;
		// Open transaction and set node data
		let txn = self.transaction(Write).await?;
		let key = NodeKey {
			nd: self.id,
		};
		let now = self.clock_now();
		let node = Node::new_with_endpoint(self.id, now, false, self.http_endpoint.clone());
		run!(txn, txn.set_key(&key, &node).await)
	}

	/// Updates an already existing node in the cluster.
	///
	/// This function should be run periodically at a regular interval.
	///
	/// This function updates the entry for this node with an up-to-date
	/// timestamp. This ensures that the node is not marked as expired by any
	/// garbage collection tasks, preventing any data cleanup for this node.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn update_node(&self) -> Result<()> {
		// Log when this method is run
		trace!(target: TARGET, id = %self.id, "Updating node in the cluster");
		// Open transaction and set node data
		let txn = self.transaction(Write).await?;
		let key = NodeKey {
			nd: self.id,
		};
		let now = self.clock_now();
		let node = Node::new_with_endpoint(self.id, now, false, self.http_endpoint.clone());
		run!(txn, txn.replace_key(&key, &node).await)
	}

	/// Updates this node, bounding each step and explicitly cancelling any
	/// open write transaction before returning on timeout or cancellation.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self, canceller))]
	pub(crate) async fn update_node_with_timeout(
		&self,
		timeout_duration: Duration,
		canceller: &CancellationToken,
	) -> Result<()> {
		trace!(target: TARGET, id = %self.id, timeout = ?timeout_duration, "Updating node in the cluster with timeout");

		let deadline = Instant::now() + timeout_duration;

		let txn =
			await_node_step(deadline, timeout_duration, Some(canceller), self.transaction(Write))
				.await?;
		let key = NodeKey {
			nd: self.id,
		};
		let now = self.clock_now();
		let node = Node::new_with_endpoint(self.id, now, false, self.http_endpoint.clone());

		await_node_tx_step(
			&txn,
			deadline,
			timeout_duration,
			Some(canceller),
			txn.replace_key(&key, &node),
		)
		.await?;
		await_node_tx_step(&txn, deadline, timeout_duration, Some(canceller), txn.commit()).await
	}

	/// Deletes a node from the cluster.
	///
	/// This function should be run when a node is shutting down.
	///
	/// This function marks the node as archived, ready for garbage collection.
	/// Later on when garbage collection is running the live queries assigned
	/// to this node will be removed, along with the node itself.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn delete_node(&self) -> Result<()> {
		// Log when this method is run
		trace!(target: TARGET, id = %self.id, "Archiving node in the cluster");
		// Open transaction and set node data
		let txn = self.transaction(Write).await?;
		let key = NodeKey {
			nd: self.id,
		};
		let Some(val) = catch!(txn, txn.get_node(self.id).await) else {
			// Nothing to archive: this node either never registered, or a peer's
			// expiry scan has already reaped the row. Neither is a failure of
			// this shutdown, and reporting one would put an error above whatever
			// actually stopped the node.
			let _ = txn.cancel().await;
			return Ok(());
		};
		let node = val.as_ref().archive();
		run!(txn, txn.replace_key(&key, &node).await)
	}

	/// Archives this node, bounding each step and explicitly cancelling any
	/// open write transaction before returning on timeout.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn delete_node_with_timeout(&self, timeout_duration: Duration) -> Result<()> {
		trace!(target: TARGET, id = %self.id, timeout = ?timeout_duration, "Archiving node in the cluster with timeout");

		let deadline = Instant::now() + timeout_duration;
		let txn =
			await_node_step(deadline, timeout_duration, None, self.transaction(Write)).await?;
		let key = NodeKey {
			nd: self.id,
		};
		let val = await_node_tx_step(&txn, deadline, timeout_duration, None, txn.get_node(self.id))
			.await?;
		let Some(val) = val else {
			// Nothing to archive; see `delete_node`.
			let _ = txn.cancel().await;
			return Ok(());
		};
		let node = val.as_ref().archive();

		await_node_tx_step(&txn, deadline, timeout_duration, None, txn.replace_key(&key, &node))
			.await?;
		await_node_tx_step(&txn, deadline, timeout_duration, None, txn.commit()).await
	}

	/// Expires nodes which have timedout from the cluster.
	///
	/// This function should be run periodically at an interval.
	///
	/// This function marks the node as archived, ready for garbage collection.
	/// Later on when garbage collection is running the live queries assigned
	/// to this node will be removed, along with the node itself.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn expire_nodes(&self) -> Result<()> {
		// Log when this method is run
		trace!(target: TARGET, "Archiving expired nodes in the cluster");
		// Fetch all of the inactive nodes
		let inactive = {
			let txn = self.transaction(Read).await?;
			let nds = catch!(txn, txn.all_nodes().await);
			let now = self.clock_now();
			catch!(txn, txn.cancel().await);
			// Filter the inactive nodes
			nds.iter()
				.filter_map(|n| {
					// Check that the node is active and has expired
					match n.is_active() && n.heartbeat < now - Duration::from_secs(30) {
						true => Some(n.to_owned()),
						false => None,
					}
				})
				.collect::<Vec<_>>()
		};
		// Check if there are inactive nodes
		if !inactive.is_empty() {
			// Open a writeable transaction
			let txn = self.transaction(Write).await?;
			// Whether any candidate still qualified once re-read below.
			let mut expired = false;
			// Archive the inactive nodes
			for nd in inactive.iter() {
				// Get the key for the node entry
				let key = NodeKey {
					nd: nd.id,
				};
				// The candidate set was sampled in an earlier transaction. A node
				// id that survives a restart can be re-registered inside that
				// window — `insert_node` upserts an active row under the same id,
				// with a fresh heartbeat — and archiving it here would retire a
				// live member. The write is therefore conditional on the heartbeat
				// the scan saw: a row whose heartbeat has moved has re-registered
				// or refreshed itself, and is no longer the row that expired.
				//
				// That closes the window in both directions. A commit that landed
				// before this transaction's snapshot is visible to this re-read,
				// and one racing this transaction writes the same key, which the
				// engine's write-conflict detection rejects.
				let current = catch!(txn, txn.get_key(&key, None).await);
				let Some(current) =
					current.filter(|n| n.is_active() && n.heartbeat == nd.heartbeat)
				else {
					trace!(target: TARGET, id = %nd.id, "Skipping node that is no longer expired");
					continue;
				};
				// Log the node archival
				trace!(target: TARGET, id = %nd.id, "Archiving node in the cluster");
				// Mark the node as archived, carrying the re-read row forward so
				// no field of the stale snapshot is written back
				let node = current.archive();
				// Update the node entry
				catch!(txn, txn.replace_key(&key, &node).await);
				expired = true;
			}
			// Commit the changes, or release the transaction when every candidate
			// turned out to be live after all
			match expired {
				true => catch!(txn, txn.commit().await),
				false => catch!(txn, txn.cancel().await),
			}
		}
		// Everything was successful
		Ok(())
	}

	/// Removes and cleans up nodes which are no longer in this cluster.
	///
	/// This function should be run periodically at an interval.
	///
	/// This function clears up all nodes which have been marked as archived.
	/// When a matching node is found, all node queries, and table queries are
	/// garbage collected, before the node itself is completely deleted.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn remove_nodes(&self) -> Result<()> {
		// Log when this method is run
		trace!(target: TARGET, "Cleaning up archived nodes in the cluster");
		// Fetch all of the archived nodes
		let archived = {
			let txn = self.transaction(Read).await?;
			let nds = catch!(txn, txn.all_nodes().await);
			catch!(txn, txn.cancel().await);
			// Filter the archived nodes
			nds.iter().filter_map(Node::archived).collect::<Vec<_>>()
		};
		// Loop over the archived nodes
		for id in archived.iter() {
			// Open a writeable transaction
			let mut next = Some(
				NodeLiveQueryPrefix {
					nd: *id,
				}
				.range()?,
			);
			let txn = self.transaction(Write).await?;
			{
				// The archived set was sampled in an earlier transaction. A node
				// id that survives a restart can be re-registered inside that
				// window — `insert_node` upserts an active row under the same id
				// — and reaping it here would delete a live member along with the
				// live queries it has already registered. Re-read the row in this
				// transaction and only proceed while it is still archived.
				let key = NodeKey {
					nd: *id,
				};
				let node = catch!(txn, txn.get_key(&key, None).await);
				if !node.is_some_and(|nd| nd.is_archived()) {
					trace!(target: TARGET, id = %id, "Skipping node that is no longer archived");
					catch!(txn, txn.cancel().await);
					continue;
				}
			}
			{
				// Log the live query scanning
				trace!(target: TARGET, id = %id, "Deleting live queries for node");
				// Scan the live queries for this node
				while let Some(rng) = next {
					// Fetch the next batch of keys and values
					let res = catch!(
						txn,
						txn.batch_keys_vals(rng.clone(), NORMAL_BATCH_SIZE, None).await
					);
					// A full page carries a continuation: resume the range after
					// the last key this page returned.
					next = match (&res.next, res.result.last()) {
						(Some(_), Some((k, _))) => Some(rng.resume_after(k, Direction::Forward)),
						_ => None,
					};
					for (k, v) in res.result.iter() {
						// Decode the data for this live query
						let val: NodeLiveQuery = KVValue::kv_decode_value(v, ())?;
						// Get the key for this node live query
						let nlq = catch!(txn, NodeLiveQueryKey::decode_key(k));
						// Check that the node for this query is archived
						if archived.contains(&nlq.nd) {
							// Get the key for this table live query
							let tlq = SubscriptionKey {
								ns: val.ns,
								db: val.db,
								tb: Cow::Borrowed(&val.tb),
								lq: nlq.lq,
							};
							// Delete the table live query
							catch!(txn, txn.clr_key(&tlq).await);
							// Delete the node live query
							catch!(txn, txn.clr_key(&nlq).await);
						}
					}
					// Pause and yield execution
					yield_now!();
				}
			}
			{
				// Log the node deletion
				trace!(target: TARGET, id = %id, "Deleting node from the cluster");
				// Get the key for the node entry
				let key = NodeKey {
					nd: *id,
				};
				// Delete the cluster node entry
				catch!(txn, txn.clr_key(&key).await);
			}
			// Commit the changes
			catch!(txn, txn.commit().await);
		}
		// Everything was successful
		Ok(())
	}

	// ------------------------------
	// Durable RPC session functions
	// ------------------------------

	/// Creates or replaces the durable copy of a client-attached RPC session,
	/// expiring `ttl` from now (an unconditional upsert).
	///
	/// Session creation goes through [`create_rpc_session`](Self::create_rpc_session)
	/// (insert-if-absent), local changes through
	/// [`update_rpc_session`](Self::update_rpc_session) (update-if-present),
	/// and cross-node reconciliation through
	/// [`load_rpc_session`](Self::load_rpc_session), so none resurrects or
	/// duplicates a session across nodes. This blind upsert is retained as a
	/// primitive for callers that own the id exclusively (and for test setup).
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self, session))]
	pub async fn persist_rpc_session(
		&self,
		id: Uuid,
		session: &Session,
		ttl: Duration,
	) -> Result<()> {
		// Log when this method is run
		trace!(target: TARGET, id = %id, "Persisting durable RPC session");
		// Capture the durable form with a refreshed expiry
		let expires_at = self.clock_now().value + ttl.as_millis() as u64;
		let value = durable_session(session, expires_at);
		// Open transaction and set the session data
		let key = SessionKey {
			id,
		};
		let txn = self.transaction(Write).await?;
		run!(txn, txn.set_key(&key, &value).await)
	}

	/// Creates the durable copy of a client-attached RPC session, but only if
	/// one does not already exist. Returns `true` if it created the entry,
	/// `false` if a session with this id already exists.
	///
	/// Uses a conditional insert (`put_compare_key` with no expected value),
	/// which is atomic even on last-writer-wins backends (TiKV) — a blind
	/// `set` is not — so two concurrent `attach`es for the same id on
	/// different nodes cannot both create it: one wins and the other is
	/// reported as an existing session, letting `attach` return
	/// `session_exists` instead of silently overwriting.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self, session))]
	pub async fn create_rpc_session(
		&self,
		id: Uuid,
		session: &Session,
		ttl: Duration,
	) -> Result<bool> {
		trace!(target: TARGET, id = %id, "Creating durable RPC session");
		let key = SessionKey {
			id,
		};
		let expires_at = self.clock_now().value + ttl.as_millis() as u64;
		let value = durable_session(session, expires_at);
		let txn = self.transaction(Write).await?;
		// `put_compare_key(.., None)` writes only if the key is absent.
		match txn.put_compare_key(&key, &value, None).await {
			Ok(()) => match txn.commit().await {
				Ok(()) => Ok(true),
				// Cancel after any failed commit (a conflict or otherwise), so
				// the transaction is rolled back consistently with the `run!`
				// macro; only the error classification differs.
				Err(e) if super::is_conditional_write_conflict(&e) => {
					let _ = txn.cancel().await;
					Ok(false)
				}
				Err(e) => {
					let _ = txn.cancel().await;
					Err(e)
				}
			},
			Err(e) => {
				let _ = txn.cancel().await;
				if super::is_conditional_write_conflict(&e) {
					Ok(false)
				} else {
					Err(e)
				}
			}
		}
	}

	/// Refreshes the durable copy of an *existing* RPC session with the given
	/// value, expiring `ttl` from now, **without recreating it** if it is gone.
	///
	/// Returns `true` if the entry was present and updated, `false` if it no
	/// longer exists (or was changed on another node). Uses a conditional
	/// write (`put_compare_key` guarded by the value just read), so it is
	/// atomic on last-writer-wins backends (TiKV): a session deleted elsewhere
	/// between the read and the write is neither resurrected nor clobbered — a
	/// blind `set` would be last-writer-wins and could resurrect it. This is
	/// the "push a local change to storage" path (a session-mutating method);
	/// the authoritative *reload* path is
	/// [`load_rpc_session`](Self::load_rpc_session).
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self, session))]
	pub async fn update_rpc_session(
		&self,
		id: Uuid,
		session: &Session,
		ttl: Duration,
	) -> Result<bool> {
		trace!(target: TARGET, id = %id, "Updating durable RPC session");
		let key = SessionKey {
			id,
		};
		let txn = self.transaction(Write).await?;
		// Read the current stored value to use as the conditional-write guard.
		let Some(current) = catch!(txn, txn.get_key(&key, None).await) else {
			let _ = txn.cancel().await;
			return Ok(false);
		};
		let expires_at = self.clock_now().value + ttl.as_millis() as u64;
		let value = durable_session(session, expires_at);
		// Write only if the stored value is still the one we read, so a delete
		// or change committed on another node in between wins (no resurrection,
		// no clobber) instead of being overwritten by this blind write.
		match txn.put_compare_key(&key, &value, Some(&current)).await {
			Ok(()) => match txn.commit().await {
				Ok(()) => Ok(true),
				// Cancel after any failed commit (a conflict or otherwise), so
				// the transaction is rolled back consistently with the `run!`
				// macro; only the error classification differs.
				Err(e) if super::is_conditional_write_conflict(&e) => {
					let _ = txn.cancel().await;
					Ok(false)
				}
				Err(e) => {
					let _ = txn.cancel().await;
					Err(e)
				}
			},
			Err(e) => {
				let _ = txn.cancel().await;
				if super::is_conditional_write_conflict(&e) {
					Ok(false)
				} else {
					Err(e)
				}
			}
		}
	}

	/// Loads the current durable copy of a client-attached RPC session — the
	/// authoritative cross-node state — returning the restored session and its
	/// absolute expiry (ms since the UNIX epoch), or `None` if it is gone or
	/// expired.
	///
	/// This is a pure read plus lazy expiry: an entry past its `expires_at` is
	/// deleted and reported as a miss, but a live entry is returned **without**
	/// being rewritten. It never extends a session's life, so it is safe to
	/// call before the caller is authorized — both when `get_session`
	/// rehydrates an evicted session and when the transport reconciles a
	/// cached session against storage before dispatch. The TTL is slid only
	/// after authorization, by [`update_rpc_session`](Self::update_rpc_session).
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn load_rpc_session(&self, id: Uuid) -> Result<Option<(Session, u64)>> {
		// Log when this method is run
		trace!(target: TARGET, id = %id, "Loading durable RPC session");
		let key = SessionKey {
			id,
		};
		let now = self.clock_now().value;
		// Pure read.
		let durable = {
			let txn = self.transaction(Read).await?;
			let val = catch!(txn, txn.get_key(&key, None).await);
			catch!(txn, txn.cancel().await);
			val
		};
		let Some(durable) = durable else {
			return Ok(None);
		};
		// Lazily delete an expired entry with a conditional delete guarded by
		// the value we read, so a refresh committed on another node between the
		// read and the delete is not clobbered (a blind `clr` is
		// last-writer-wins on TiKV). On a condition conflict the entry changed
		// — leave it and report a miss for this request; it rehydrates fresh on
		// the next one.
		if durable.expires_at <= now {
			trace!(target: TARGET, id = %id, "Durable RPC session has expired");
			let txn = self.transaction(Write).await?;
			match txn.del_compare_key(&key, Some(&durable)).await {
				Ok(()) => match txn.commit().await {
					Ok(()) => {}
					Err(e) if super::is_conditional_write_conflict(&e) => {
						let _ = txn.cancel().await;
					}
					Err(e) => {
						let _ = txn.cancel().await;
						return Err(e);
					}
				},
				Err(e) => {
					let _ = txn.cancel().await;
					if !super::is_conditional_write_conflict(&e) {
						return Err(e);
					}
				}
			}
			return Ok(None);
		}
		// Restore the in-memory session without touching the durable copy,
		// handing back the stored expiry so the caller can enforce the TTL.
		let expires_at = durable.expires_at;
		restore_session(durable).map(|session| Some((session, expires_at)))
	}

	/// Deletes the durable copy of a client-attached RPC session, when it is
	/// still the value being torn down.
	///
	/// Run on detach/teardown so the session cannot be rehydrated. It reads the
	/// current value and deletes only that (`del_compare_key`), rather than
	/// clearing the key blindly: a blind `clr` is last-writer-wins on TiKV, so
	/// a slow detach could otherwise delete a *newer* session that another node
	/// re-attached under the same id after the old one was removed. An entry
	/// already absent is a no-op.
	///
	/// A condition conflict — the stored value changed between the read and the
	/// delete (a concurrent refresh/re-attach on another node) — is surfaced as
	/// an **error**, not swallowed: the durable copy was *not* removed, so
	/// reporting success would let [`RpcProtocol::forget_session`]/`detach`
	/// claim the session was torn down while it remains rehydratable. The
	/// caller (whose `del_session` removes the durable copy before local state)
	/// then fails the teardown and can retry, keeping detach fail-closed. In
	/// the supported single-node-per-session model such a conflict does not
	/// arise (the owning node serializes the session's writes).
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn delete_rpc_session(&self, id: Uuid) -> Result<()> {
		// Log when this method is run
		trace!(target: TARGET, id = %id, "Deleting durable RPC session");
		let key = SessionKey {
			id,
		};
		let txn = self.transaction(Write).await?;
		// Read the value we intend to remove; if it is already gone, done.
		let Some(current) = catch!(txn, txn.get_key(&key, None).await) else {
			let _ = txn.cancel().await;
			return Ok(());
		};
		// Delete only if the stored value is still the one we read. A conflict
		// (value changed concurrently) means the delete did not happen, so it
		// is surfaced as an error rather than reported as a successful teardown.
		match txn.del_compare_key(&key, Some(&current)).await {
			Ok(()) => match txn.commit().await {
				Ok(()) => Ok(()),
				Err(e) => {
					let _ = txn.cancel().await;
					Err(e)
				}
			},
			Err(e) => {
				let _ = txn.cancel().await;
				Err(e)
			}
		}
	}

	/// Purges expired durable RPC sessions.
	///
	/// This function should be run periodically at a regular interval.
	///
	/// It uses a distributed task lease so only one node in the cluster
	/// performs the purge per interval. Entries are scanned in batches, and
	/// only entries whose expiry has passed are deleted; an entry that fails
	/// to decode (for example one written by a newer node during a rolling
	/// upgrade) is skipped, never deleted.
	///
	/// # Arguments
	/// * `interval` - The interval between purge runs, to calculate the lease duration
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub(crate) async fn purge_expired_rpc_sessions(&self, interval: &Duration) -> Result<()> {
		// Output function invocation details to logs
		trace!(target: TARGET, "Attempting expired RPC session purge");
		// Create a new lease handler
		let lh = LeaseHandler::new(
			self.sequences.clone(),
			self.id,
			self.transaction_factory.clone(),
			TaskLeaseType::RpcSessionCleanup,
			*interval * 2,
		)?;
		// If we don't get the lease, another node is handling this task
		if !lh.has_lease().await? {
			return Ok(());
		}
		// Output function invocation details to logs
		trace!(target: TARGET, "Purging expired RPC sessions");
		let now = self.clock_now().value;
		// Scan the durable session entries in batches under read transactions,
		// deleting each expired entry in its own conditional-delete write
		// transaction. The delete is guarded by the value read
		// (`del_compare_key`), so a request that refreshed the session after
		// the scan read the old expired value is not clobbered — a blind `clr`
		// is last-writer-wins on TiKV. A per-entry transaction keeps one such
		// conflict from aborting the whole purge.
		let mut next = Some(SessionPrefix {}.range()?);
		while let Some(rng) = next {
			// Fetch the next batch of keys and values under a read transaction.
			let batch = {
				let txn = self.transaction(Read).await?;
				let res =
					catch!(txn, txn.batch_keys_vals(rng.clone(), NORMAL_BATCH_SIZE, None).await);
				catch!(txn, txn.cancel().await);
				res
			};
			// A full page carries a continuation: resume the range after the last
			// key this page returned.
			next = match (&batch.next, batch.result.last()) {
				(Some(_), Some((k, _))) => Some(rng.resume_after(k, Direction::Forward)),
				_ => None,
			};
			for (k, v) in batch.result.iter() {
				// Decode the data for this session entry. Skip (but never
				// delete) an entry we cannot decode: it may have been written
				// by a newer node during a rolling upgrade.
				let val: DurableSession = match KVValue::kv_decode_value(v, ()) {
					Ok(val) => val,
					Err(e) => {
						warn!(target: TARGET, "Skipping undecodable durable RPC session entry: {e}");
						continue;
					}
				};
				// Only delete an expired entry, and only if it is still the
				// value we read.
				if val.expires_at <= now {
					let key = SessionKey::decode_key(k)?;
					trace!(target: TARGET, id = %key.id, "Purging expired RPC session");
					let txn = self.transaction(Write).await?;
					match txn.del_compare_key(&key, Some(&val)).await {
						Ok(()) => match txn.commit().await {
							Ok(()) => {}
							// Refreshed concurrently at commit (TiKV): leave it.
							Err(e) if super::is_conditional_write_conflict(&e) => {
								let _ = txn.cancel().await;
							}
							Err(e) => {
								let _ = txn.cancel().await;
								return Err(e);
							}
						},
						Err(e) => {
							let _ = txn.cancel().await;
							if !super::is_conditional_write_conflict(&e) {
								return Err(e);
							}
						}
					}
				}
			}
			// Pause and yield execution
			yield_now!();
		}
		// Everything was successful
		Ok(())
	}

	// --------------------------------------------------
	// Live query functions
	// --------------------------------------------------

	/// Clean up the live queries for a disconnected connection.
	///
	/// This function should be run when a WebSocket disconnects.
	///
	/// This function clears up the live queries on the current node, which
	/// are specified by uique live query UUIDs. This is necessary when a
	/// WebSocket disconnects, and any associated live queries need to be
	/// cleaned up and removed.
	#[instrument(err, level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn delete_queries(&self, ids: Vec<uuid::Uuid>) -> Result<()> {
		// Log the node deletion
		trace!(target: TARGET, "Deleting live queries for a connection");
		// Fetch expired nodes
		let txn = self.transaction(Write).await?;
		// Loop over the live query unique ids
		for id in ids {
			// Get the key for this node live query
			let nlq = NodeLiveQueryKey {
				nd: self.id(),
				lq: id,
			};
			// Fetch the LIVE meta data node entry
			if let Some(lq) = catch!(txn, txn.get_key(&nlq, None).await) {
				// Get the key for this node live query
				let nlq = NodeLiveQueryKey {
					nd: self.id(),
					lq: id,
				};
				// Get the key for this table live query
				let tlq = SubscriptionKey {
					ns: lq.ns,
					db: lq.db,
					tb: Cow::Borrowed(&lq.tb),
					lq: id,
				};
				// Delete the table live query
				catch!(txn, txn.clr_key(&tlq).await);
				// Delete the node live query
				catch!(txn, txn.clr_key(&nlq).await);
			}
		}
		// Commit the changes
		catch!(txn, txn.commit().await);
		// All ok
		Ok(())
	}

	// --------------------------------------------------
	// Changefeed functions
	// --------------------------------------------------

	/// Performs changefeed garbage collection as a background task.
	///
	/// This method is responsible for cleaning up old changefeed data across
	/// all databases. It uses a distributed task lease mechanism to coordinate
	/// which node performs this maintenance operation. Once a batch starts it
	/// runs to completion even if the lease expires, so brief overlap is
	/// possible.
	///
	/// The process involves:
	/// 1. Acquiring a lease for the ChangeFeedCleanup task
	/// 2. Cleaning up old changefeed data from all databases
	///
	/// # Arguments
	/// * `interval` - The interval between compaction runs, to calculate the lease duration
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip(self))]
	pub async fn changefeed_process(
		&self,
		interval: &Duration,
		canceller: &CancellationToken,
	) -> Result<()> {
		self.changefeed_process_bounded(interval, CHANGEFEED_GC_PASS_KEY_BUDGET, canceller).await
	}

	/// [`Self::changefeed_process`] with the per-pass key budget lowered, so a
	/// test can drive a pass that stops mid-backlog and inspect what it left
	/// behind.
	#[cfg(test)]
	#[cfg_attr(not(feature = "kv-mem"), allow(dead_code))]
	pub(crate) async fn changefeed_gc_with_budget(
		&self,
		interval: &Duration,
		budget: u64,
		canceller: &CancellationToken,
	) -> Result<()> {
		self.changefeed_process_bounded(interval, budget, canceller).await
	}

	/// One changefeed-collection pass, deleting at most `budget` entries from
	/// each keyspace it collects.
	///
	/// The changefeed backlog and, under the Router engine, the live-query event
	/// backlog are both sized by write throughput rather than by the catalog, so
	/// neither is deleted in one transaction: each is paged behind committed
	/// transactions of at most one page (see [`crate::kvs::paging`]). A pass
	/// therefore costs a bounded amount of work however far either backlog has
	/// run ahead, and the next tick resumes at the head of what survives.
	///
	/// The two keyspaces share this pass's lease but hold separate budgets. The
	/// same writes fill both, so a budget spanning them would let whichever is
	/// collected first spend it whenever the write rate outran it, leaving the
	/// other uncollected on every pass and growing on disk without limit.
	async fn changefeed_process_bounded(
		&self,
		interval: &Duration,
		budget: u64,
		canceller: &CancellationToken,
	) -> Result<()> {
		// Output function invocation details to logs
		trace!(target: TARGET, "Attempting changefeed garbage collection");
		// Create a new lease handler
		let lh = LeaseHandler::new(
			self.sequences.clone(),
			self.id,
			self.transaction_factory.clone(),
			TaskLeaseType::ChangeFeedCleanup,
			*interval * 2,
		)?;
		// If we don't get the lease, another node is handling this task
		if !lh.has_lease().await? {
			return Ok(());
		}
		// Output function invocation details to logs
		trace!(target: TARGET, "Running changefeed garbage collection");
		// Entries this pass may delete from the changefeed keyspace, shared out
		// across the databases it visits.
		let mut cf_budget = budget;
		// Perform the changefeed garbage collection. A pass that lost the lease
		// ends this one: the live-query collector below shares the lease, and its
		// own first check would be answered from the maintenance throttle by the
		// very check that lost it — so it would delete alongside the new holder.
		if !crate::cf::gc_all_at(self, &lh, canceller, &mut cf_budget).await? {
			return Ok(());
		}
		// When the Router engine is active, also garbage-collect the dedicated
		// live-query event keyspace, retaining entries for the configured window so
		// reconnecting/lagging subscribers can still replay. This shares the
		// pass's lease with the changefeed GC above and spends its own budget.
		if self.config.datastore.live_query_engine == LiveQueryEngine::Router {
			let retention = self.config.datastore.live_query_retention;
			let mut lq_budget = budget;
			crate::lq::gc::gc_all_at(self, &lh, retention, canceller, &mut lq_budget).await?;
		}
		// Everything ok
		Ok(())
	}

	/// Run one live-query router pass.
	///
	/// Under the [`LiveQueryEngine::Router`] engine this tails the dedicated
	/// `lqe` keyspace since the node's cursor and delivers notifications off the
	/// write path (see [`crate::lq::router`]); it is the sole delivery path in
	/// that mode. Under the default [`LiveQueryEngine::Inline`] engine it is a
	/// cheap no-op, so the engine's background task can call it unconditionally.
	/// Unlike changefeed GC this runs on every node without a lease: each node
	/// delivers only to the subscriptions it owns.
	#[instrument(level = "trace", target = "surrealdb::core::lq", skip(self))]
	pub(crate) async fn live_query_router_process(&self) -> Result<()> {
		// Only the Router engine delivers via the router.
		if self.config.datastore.live_query_engine != LiveQueryEngine::Router {
			return Ok(());
		}
		crate::lq::router::process(self, &self.live_query_router).await
	}

	// --------------------------------------------------
	// Indexing functions
	// --------------------------------------------------

	pub(crate) fn ensure_not_cancelled(canceller: &CancellationToken) -> Result<()> {
		if canceller.is_cancelled() {
			bail!(EngineError::QueryCancelled);
		}
		Ok(())
	}

	/// Processes the index compaction queue.
	///
	/// This method is called periodically by the index compaction thread to
	/// process indexes that have been marked for compaction. It acquires a
	/// distributed lease to coordinate compaction across the cluster. Once a
	/// batch starts it runs to completion even if the lease expires, so brief
	/// overlap is possible.
	///
	/// The method scans the index compaction queue (stored as `Ic` keys) and
	/// delegates to [`Self::index_compaction_loop`], which compacts each
	/// distinct index exactly once — duplicate queue entries for the same
	/// index are skipped. On native targets compaction tasks run in parallel
	/// (one spawned task per index), while on wasm they run sequentially.
	/// Indexes that support compaction include full-text, count, and HNSW.
	///
	/// The queue is read in a short-lived read transaction so that user
	/// transactions enqueueing new compaction requests do not conflict with
	/// the compaction cycle. Each index compaction runs on its own write
	/// transaction. Once all compactions have completed, a separate write
	/// transaction removes the processed queue entries. Compaction failures
	/// are logged but do not prevent other indexes from being processed.
	///
	/// # Arguments
	/// * `dbs` - The shared datastore instance, cloned into each compaction task
	/// * `interval` - The interval between compaction runs, used to calculate the lease duration
	/// * `canceller` - Token checked before starting each lease, batch, and compaction unit
	///
	/// # Returns
	/// A tuple `(iterations, errors)` where `iterations` is the number of
	/// compaction batches processed and `errors` is the total number of
	/// individual index compaction failures across all batches.
	/// Resume index builds stranded by a crashed or expired owner node.
	///
	/// A `CONCURRENTLY` index build runs as a detached task. If its owning node
	/// dies mid-build, nothing waits on that generation again, so the durable
	/// build state stays in `Building`/`Closing` and the index reports
	/// `status: indexing` with a frozen counter indefinitely. This scan adopts
	/// such builds — once their owner lease has expired — via the existing
	/// expired-lease takeover (see [`IndexBuilder::resume_stalled`]) and drives
	/// them to completion.
	///
	/// The scan is lease-guarded so a single node runs it per cluster; the
	/// per-index takeover is additionally CAS-guarded, so correctness does not
	/// depend on the lease. Enumeration walks the catalog, so cost is
	/// proportional to the total index count; operators who prefer to recover
	/// stalled builds manually (with `REBUILD INDEX`) can disable the scan by
	/// setting its interval to zero.
	///
	/// Recovery is serialized: a pass adopts at most one stalled build, and
	/// no pass adopts anything while a local builder task is still running.
	/// A restart with several stranded builds (for example multiple full-text
	/// indexes on a small instance) therefore rebuilds them one at a time
	/// instead of multiplying the node's memory and CPU footprint; every
	/// stalled build is still recovered, one scan pass after the previous one
	/// finishes. User-initiated `REBUILD INDEX` is not throttled by this.
	///
	/// Returns the number of stalled builds adopted this pass.
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip(self, canceller))]
	pub(crate) async fn resume_stalled_index_builds(
		&self,
		interval: Duration,
		canceller: CancellationToken,
	) -> Result<usize> {
		Self::ensure_not_cancelled(&canceller)?;
		// Single-node-per-cluster guard. The lease lasts two intervals so an
		// in-flight scan isn't preempted between ticks.
		let lh = LeaseHandler::new_with_canceller(
			self.sequences.clone(),
			self.id,
			self.transaction_factory.clone(),
			TaskLeaseType::IndexBuildResume,
			interval * 2,
			canceller.clone(),
		)?;
		if !lh.has_lease().await? {
			return Ok(0);
		}
		// Serialize recovery: while any local builder task is still running
		// (a previously adopted build or a user-started one), defer further
		// adoptions to a later pass. Without this, a restart with several
		// stranded builds starts them all at once, and the concurrent initial
		// scans can overwhelm a small instance's memory and CPU.
		if self.index_builder.has_unfinished_build().await {
			trace!(
				target: TARGET,
				"Deferring stalled index build adoption; a local index build is still running"
			);
			return Ok(0);
		}
		// Snapshot the (ns, db, table, index) hierarchy in a short read
		// transaction. Index definitions are cloned out so the per-index
		// build-state checks below don't hold the catalog transaction open.
		let mut candidates = Vec::new();
		{
			let txn = self.transaction(Read).await?;
			let res: Result<()> = async {
				for ns in txn.all_ns(None).await?.iter() {
					for db in txn.all_db(ns.namespace_id, None).await?.iter() {
						for tb in txn.all_tb(ns.namespace_id, db.database_id, None).await?.iter() {
							for ix in txn
								.all_tb_indexes(
									ns.namespace_id,
									db.database_id,
									&tb.name.clone(),
									None,
								)
								.await?
								.iter()
							{
								// Indexes pending removal are cleared by the
								// tombstone reaper, not resumed.
								if ix.prepare_remove {
									continue;
								}
								candidates.push((
									ns.namespace_id,
									ns.name.clone(),
									db.database_id,
									db.name.clone(),
									tb.table_id,
									Arc::new(ix.clone()),
								));
							}
						}
					}
				}
				Ok(())
			}
			.await;
			let _ = txn.cancel().await;
			res?;
		}
		// Attempt a takeover for each candidate. `resume_stalled` is a cheap
		// no-op for healthy/online/live builds, so this is safe to call for
		// every index every pass.
		let index_builder = &self.index_builder;
		let mut resumed = 0;
		for (ns_id, ns_name, db_id, db_name, tb_id, ix) in candidates {
			Self::ensure_not_cancelled(&canceller)?;
			lh.try_maintain_lease().await?;
			let ctx = self.setup_ctx()?.freeze();
			let opt = self.setup_options(
				&Session::owner().with_ns(ns_name.as_str()).with_db(db_name.as_str()),
			);
			match index_builder
				.resume_stalled(&ctx, opt, ns_id, db_id, tb_id, Arc::clone(&ix))
				.await
			{
				Ok(true) => {
					resumed += 1;
					info!(
						target: TARGET,
						"Resuming stalled index build '{}' on table '{}'",
						ix.name, ix.table_name
					);
					// One adoption per pass: a later pass adopts the next
					// stalled build once this one has finished, keeping
					// recovery sequential on this node.
					break;
				}
				Ok(false) => {}
				Err(e) => {
					warn!(
						target: TARGET,
						"Failed to resume stalled index build '{}' on table '{}': {e}",
						ix.name, ix.table_name
					);
				}
			}
		}
		Ok(resumed)
	}

	/// Drains the index-compaction queue (`/!ic` keys) in bounded batches.
	///
	/// Each iteration scans at most [`INDEX_COMPACTION_QUEUE_BATCH_SIZE`]
	/// queue keys, compacts every distinct index they reference, and then
	/// deletes exactly those keys in one write transaction, so no single
	/// transaction's key cardinality exceeds the batch size regardless of how
	/// many entries have accumulated. Entries enqueued after a batch's scan
	/// are untouched by its cleanup and are picked up by a later iteration
	/// (or a later invocation), so a queue entry is only ever removed after
	/// its index has been compacted at-or-after the entry was written.
	///
	/// Batches rotate across indexes: each batch's scan resumes past the last
	/// index the previous batch covered and wraps at the end of the queue
	/// range, so every index with pending entries is visited once per
	/// rotation regardless of relative enqueue and drain rates — an index
	/// sustaining a full batch of new entries per iteration still cannot pin
	/// the scan to itself (a start-anchored or key-successor scan only stays
	/// fair while the drain outpaces the enqueue).
	///
	/// Under sustained enqueue the drain keeps running — every iteration
	/// stays bounded — and stops when the queue empties, the lease is lost,
	/// or the task is cancelled.
	///
	/// Coordinated across the cluster by a [`TaskLeaseType::IndexCompaction`]
	/// lease. Returns the number of processed batches and the number of
	/// indexes that failed to compact.
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip(dbs, canceller))]
	pub async fn index_compaction(
		dbs: Arc<Datastore>,
		interval: Duration,
		canceller: CancellationToken,
	) -> Result<(usize, usize)> {
		// Output function invocation details to logs
		trace!(target: TARGET, "Attempting index compaction process");
		// Create a new lease handler
		let lh = LeaseHandler::new_with_canceller(
			dbs.sequences.clone(),
			dbs.id,
			dbs.transaction_factory.clone(),
			TaskLeaseType::IndexCompaction,
			interval * 2,
			canceller.clone(),
		)?;
		let mut count_iteration = 0;
		let mut count_error = 0;
		// The queue range and a rotating window within it. After each batch
		// the window resumes past the last index that batch covered, so
		// indexes later in the keyspace are reached even while an
		// earlier-sorting index keeps enqueueing new entries (queue keys
		// sort by ns/db/tb/ix before their time-ordered UUID, so a hot
		// index would otherwise pin a start-anchored scan to itself). When
		// the scan reaches the end of the range it wraps to the start, and
		// a wrap that finds nothing means the queue is drained.
		let queue = IndexCompactionPrefix {}.range()?;
		let mut window = queue.clone();
		// We continue without interruptions while there are keys and the lease
		'compaction: loop {
			Self::ensure_not_cancelled(&canceller)?;
			// Attempt to acquire a lease for the IndexCompaction task
			// If we don't get the lease, another node is handling this task
			if !lh.has_lease().await? {
				return Ok((count_iteration, count_error));
			}
			Self::ensure_not_cancelled(&canceller)?;
			// Output function invocation details to logs
			trace!(target: TARGET, "Running index compaction process");
			// Read one bounded batch of queue keys in a short-lived read
			// transaction. The queue holds one entry per indexed record
			// write since it last drained, so an unbounded snapshot would
			// make the cleanup transaction below arbitrarily large — every
			// key it deletes is a per-replica write reservation on
			// distributed backends. Queue values carry no payload, so a
			// keys-only scan suffices.
			let keys = {
				let txn = dbs.transaction(Read).await?;
				let res =
					txn.keys(window.clone(), INDEX_COMPACTION_QUEUE_BATCH_SIZE, 0, None).await;
				let _ = txn.cancel().await;
				res?
			};
			Self::ensure_not_cancelled(&canceller)?;
			if keys.is_empty() {
				if window.start() == queue.start() {
					// Nothing left anywhere in the queue.
					return Ok((count_iteration, count_error));
				}
				// End of the range: wrap to re-scan entries that were
				// skipped when the window seeked past a partially-drained
				// index.
				window = queue.clone();
				continue;
			}
			// Compact each distinct index referenced by this batch before
			// deleting the batch's queue entries: an entry may only be
			// removed once its index has been compacted at-or-after the
			// entry was enqueued.
			count_iteration += 1;
			count_error +=
				Self::index_compaction_loop(Arc::clone(&dbs), &lh, &keys, canceller.clone())
					.await?;
			// Seek the next batch past the last index this batch covered.
			// Entries of that index beyond this batch are picked up again
			// after the window wraps, so a continuously-refilling index
			// cannot starve later-sorting ones. A key that fails to decode
			// cannot name an index to seek past: fall back to resuming
			// immediately after the key itself, so the scan still advances and
			// the cleanup below still removes the undecodable entry (it
			// references no valid index, so deleting it cannot violate the
			// compact-before-delete invariant).
			if let Some(last_key) = keys.last() {
				window = match IndexCompactionKey::decode_key(last_key) {
					Ok(last) => {
						// The first key ordering after the whole index's run of
						// queue entries.
						let covered = IndexCompactionIxPrefix {
							ns: last.ns,
							db: last.db,
							tb: Cow::Owned(last.tb.into_owned()),
							ix: last.ix,
						}
						.skip_extensions()?;
						queue.clone().resume_after(&covered, Direction::Forward)
					}
					Err(e) => {
						warn!(target: TARGET, "Skipping undecodable index compaction queue entry: {e}");
						queue.clone().resume_after(last_key, Direction::Forward)
					}
				};
			}
			// Delete this batch's queue entries in a separate write
			// transaction, bounded by the batch size. This avoids conflicts
			// with concurrent user transactions that may enqueue new
			// compaction requests. Failed indexes are not re-enqueued here;
			// the next user write to the affected index will naturally
			// trigger a new compaction request.
			loop {
				let txn = dbs.transaction(Write).await?;
				if let Err(e) = Self::ensure_not_cancelled(&canceller) {
					let _ = txn.cancel().await;
					return Err(e);
				}
				// Deleted as bytes rather than through the decoded key, because
				// the batch deliberately includes entries that do not decode. An
				// undecodable entry names no index, so it can never be compacted
				// and a typed delete could never address it; leaving it would
				// park it at the head of the queue forever.
				for k in &keys {
					if let Err(e) = txn.del(Key::from(k)).await {
						warn!(target: TARGET, "Failed to delete compaction queue entry: {e}");
					}
				}
				if let Err(e) = Self::ensure_not_cancelled(&canceller) {
					let _ = txn.cancel().await;
					return Err(e);
				}
				#[cfg(test)]
				if let Err(e) = maybe_inject_retryable_conflict(
					RetryableConflictSite::IndexCompactionQueueCleanup,
					dbs.id,
				) {
					if Self::cancel_and_retry_index_operation_conflict(
						&txn,
						&e,
						"Retryable conflict committing compaction queue cleanup, retrying",
					)
					.await
					{
						continue;
					}
					warn!(target: TARGET, "Failed to commit compaction queue cleanup: {e}");
					break 'compaction;
				}
				if let Err(e) = txn.commit().await {
					if Self::cancel_and_retry_index_operation_conflict(
						&txn,
						&e,
						"Retryable conflict committing compaction queue cleanup, retrying",
					)
					.await
					{
						continue;
					}
					warn!(target: TARGET, "Failed to commit compaction queue cleanup: {e}");
					break 'compaction;
				}
				break;
			}
		}
		Ok((count_iteration, count_error))
	}

	/// Periodically drains the background reclaim queue (`/!rc` keys),
	/// destroying the data prefix of namespaces/databases/indexes that were
	/// removed by a committed `REMOVE` statement.
	///
	/// `REMOVE NAMESPACE/DATABASE/INDEX` delete only the catalog definition
	/// inside the user transaction and enqueue a [`ReclaimKey`]; this task
	/// performs the expensive data deletion out-of-band so the user statement
	/// returns immediately and never trips a request/transaction timeout.
	///
	/// Coordinated across the cluster by a [`TaskLeaseType::ReclaimTombstones`]
	/// lease so only one node reclaims at a time. The queue is walked in batches
	/// of at most [`RECLAIM_BATCH_SIZE`] entries, each read in a short-lived
	/// read transaction and each retired or stamped in one write transaction of
	/// its own, so neither the pass's snapshot nor its queue update grows with
	/// the number of pending removals. Each prefix is then destroyed
	/// independently and idempotently — in one out-of-transaction call on a
	/// backend offering [`DestroyRange`], otherwise in bounded pages, each
	/// committed together with the resume cursor that accounts for it. A queue
	/// entry is retired only once its prefix is empty, so a crash or an
	/// exhausted budget mid-reclaim resumes from the committed cursor on a later
	/// pass instead of restarting the prefix.
	///
	/// One pass deletes at most [`RECLAIM_PASS_KEY_BUDGET`] data keys in total,
	/// so a prefix larger than that is finished over several ticks rather than
	/// monopolising the schedule this task shares. That budget is divided among
	/// the entries a batch still has to visit, floored at one page each: an
	/// entry naming an oversized prefix takes a page and yields to the next
	/// instead of spending the whole pass on itself, so each of the first
	/// `RECLAIM_PASS_KEY_BUDGET / RECLAIM_BATCH_SIZE` entries that still hold
	/// data makes progress on every pass.
	///
	/// Snapshot safety: a queued removal is only reclaimed once it has been
	/// *observed* by this task for at least `grace`. The reclaim task destroys
	/// data out-of-band, and on a backend offering out-of-transaction range
	/// destruction that destruction bypasses MVCC, so a read transaction whose
	/// snapshot predates the `REMOVE` must be given time to finish first. On
	/// first sight the task stamps the entry's
	/// [`ReclaimState::observed_ms`]; aging is measured from there, not from the
	/// key's `uid` (a UUIDv7 stamped while the `REMOVE` statement runs, which can
	/// be arbitrarily earlier than the commit inside a long `BEGIN`/`COMMIT`
	/// block). Because the task only ever reads committed entries, `observed_ms`
	/// is always at or after the removal's commit, so `age >= grace` implies the
	/// commit is at least `grace` old — equivalent to it having fallen behind the
	/// MVCC GC safepoint (`now - tikv_gc_lifetime`) when `grace >= tikv_gc_lifetime`,
	/// by which point any transaction that could still read the data has expired.
	/// A `grace` of zero reclaims immediately without stamping (used by tests and
	/// the language-test harness teardown, where there are no concurrent readers).
	///
	/// Returns `(iterations, errors)`.
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip(dbs, canceller))]
	pub async fn reclaim_tombstones(
		dbs: Arc<Datastore>,
		interval: Duration,
		grace: Duration,
		canceller: CancellationToken,
	) -> Result<(usize, usize)> {
		Self::reclaim_tombstones_bounded(dbs, interval, grace, RECLAIM_PASS_KEY_BUDGET, canceller)
			.await
	}

	/// [`Self::reclaim_tombstones`] with the per-pass key budget lowered, so a
	/// test can drive a pass that stops mid-prefix and inspect what it left
	/// behind.
	#[cfg(test)]
	#[cfg_attr(
		not(any(feature = "kv-mem", feature = "kv-rocksdb", feature = "kv-surrealkv")),
		allow(dead_code)
	)]
	pub(crate) async fn reclaim_tombstones_with_budget(
		dbs: Arc<Datastore>,
		interval: Duration,
		grace: Duration,
		budget: u64,
		canceller: CancellationToken,
	) -> Result<(usize, usize)> {
		Self::reclaim_tombstones_bounded(dbs, interval, grace, budget, canceller).await
	}

	/// One reclaim pass, deleting at most `budget` data keys in total.
	///
	/// The pass walks the whole queue and spends its key budget on part of it,
	/// which are two different bounds and are enforced separately.
	///
	/// The walk is unconditional. Stamping an entry's first sighting and ageing it
	/// against the grace costs at most one write per entry, so that work scales
	/// with the number of pending removals — catalog scale — and not with the data
	/// they name. Gating it on the key budget would leave an entry beyond the
	/// budget's reach unstamped, and an unstamped entry has `observed_ms == 0`, so
	/// its grace has not started and it is not yet even a candidate for reclaim.
	/// The queue is walked in bounded batches, each batch's stamps committed in one
	/// transaction, so the walk's memory and write batches stay proportional to one
	/// batch however long the queue is.
	///
	/// The key budget is then spent on the [`RECLAIM_PASS_ENTRY_QUOTA`]
	/// longest-observed eligible entries, selected while walking so only that many
	/// are ever held. Oldest-first rather than queue order: key order makes the
	/// entries that happen to sort lowest the only ones ever served while they hold
	/// data, whereas the wait an operator cares about is how long a removal has
	/// gone unreclaimed. Spreading the budget across every eligible entry instead
	/// would shrink each share towards one key as the queue grows.
	async fn reclaim_tombstones_bounded(
		dbs: Arc<Datastore>,
		interval: Duration,
		grace: Duration,
		budget: u64,
		canceller: CancellationToken,
	) -> Result<(usize, usize)> {
		trace!(target: TARGET, "Attempting tombstone reclaim process");
		// Data keys this pass may still delete, shared out across the entries it
		// serves. Spent to zero ends the spend with every cursor committed.
		let mut budget = budget;
		// Coordinate across the cluster so only one node reclaims at a time.
		let lh = LeaseHandler::new_with_canceller(
			dbs.sequences.clone(),
			dbs.id,
			dbs.transaction_factory.clone(),
			TaskLeaseType::ReclaimTombstones,
			interval * 2,
			canceller.clone(),
		)?;
		let mut count_iteration = 0;
		let mut count_error = 0;
		// The queue range and a window within it, advanced past each batch the
		// walk reads. Reading the queue in bounded batches is what keeps both the
		// snapshot the pass holds and the write transaction that updates it
		// proportional to one batch rather than to the number of pending removals.
		let queue = ReclaimPrefix {}.range()?;
		let mut window = queue.clone();
		// The longest-observed eligible entries seen so far, at most
		// `RECLAIM_PASS_ENTRY_QUOTA` of them. A max-heap ordered oldest-first, so
		// the entry discarded when the quota is exceeded is the newest held.
		let mut candidates: BinaryHeap<ReclaimCandidate> = BinaryHeap::new();
		// Whether the walk finished holding the lease. Losing it mid-walk ends the
		// pass: the deletes below would otherwise run against a prefix the node
		// that holds the lease now is already working on.
		let mut lease_held = true;
		// Walk the queue: stamp, age, and select. No deletes, so no budget.
		loop {
			Self::ensure_not_cancelled(&canceller)?;
			// If we don't hold the lease, another node is handling this task.
			if !lh.has_lease().await? {
				lease_held = false;
				break;
			}
			Self::ensure_not_cancelled(&canceller)?;
			// Read one bounded batch of queue entries in a short-lived read
			// transaction, to avoid holding a write lock across the entire
			// reclaim cycle. Values are read as bytes so that an entry this node
			// cannot decode is skipped with a warning rather than failing the
			// whole pass.
			let items = {
				let txn = dbs.transaction(Read).await?;
				let res = txn.scan_raw(window.clone(), RECLAIM_BATCH_SIZE, 0, None).await;
				let _ = txn.cancel().await;
				res?
			};
			Self::ensure_not_cancelled(&canceller)?;
			let Some((last, _)) = items.last().cloned() else {
				// The window has run off the end of the queue: everything queued
				// has been walked.
				break;
			};
			count_iteration += 1;
			// Current wall-clock time (unix millis), used to age each entry
			// against `grace` and to stamp first observations.
			let now_ms = web_time::SystemTime::now()
				.duration_since(web_time::SystemTime::UNIX_EPOCH)
				.map(|d| d.as_millis() as u64)
				.unwrap_or(0);
			let grace_ms = grace.as_millis() as u64;
			// Queue states to initialise or repair. The raw value read with each
			// one is the compare-and-set guard, so a concurrent cursor advance or
			// cancellation cannot be overwritten by this batch.
			let mut to_stamp: Vec<(Vec<u8>, Vec<u8>, ReclaimState)> = Vec::new();
			for (k, v) in items.iter() {
				Self::ensure_not_cancelled(&canceller)?;
				if let Err(e) = ReclaimKey::decode_key(k) {
					count_error += 1;
					warn!(target: TARGET, "Failed to decode reclaim queue entry: {e}");
					continue;
				}
				// The state carries both the observation stamp the grace is
				// measured from and the resume cursor a partly-reclaimed prefix
				// continues at, so it is read before either is consulted.
				// A value this node cannot read still names a prefix whose catalog
				// entry is committed-removed, so the entry is restarted rather than
				// skipped: skipping it strands data that nothing else can reach,
				// because the queue entry is the only remaining name for it.
				// Restarting is safe in both fields — treating the entry as never
				// observed keeps the grace gate conservative, and discarding an
				// unreadable cursor only re-scans pages that may already be empty,
				// which a delete tolerates.
				let state = match ReclaimState::kv_decode_value(v, ()) {
					Ok(s) => s,
					Err(e) => {
						count_error += 1;
						warn!(
							target: TARGET,
							"Restarting a reclaim queue entry whose state could not be read: {e}",
						);
						// Repair the unreadable state conditionally before attempting
						// the reclaim. A typed cursor CAS cannot use unreadable bytes as
						// its expected value, and a blind repair could resurrect a claim
						// concurrently cancelled on another node.
						let repaired = ReclaimState {
							observed_ms: if grace.is_zero() {
								0
							} else {
								now_ms
							},
							cursor: None,
						};
						to_stamp.push((k.clone(), v.clone(), repaired.clone()));
						// Zero-grace callers may reclaim immediately after the
						// conditional repair commits. If that repair loses a race, the
						// page's own CAS sees that `repaired` is not current and stops.
						if grace.is_zero() {
							candidates.push(ReclaimCandidate {
								observed_ms: repaired.observed_ms,
								key: k.clone(),
								state: repaired,
							});
							if candidates.len() > RECLAIM_BATCH_SIZE as usize {
								candidates.pop();
							}
						}
						continue;
					}
				};
				// A zero grace reclaims immediately, skipping the
				// observe-then-age dance (tests / harness teardown — no
				// concurrent readers).
				if !grace.is_zero() {
					if state.observed_ms == 0 {
						// First sighting of this committed entry — record an
						// observation time (>= commit) and defer reclaim. Aging
						// is measured from here, never from the pre-commit
						// `uid`. Not a candidate this pass: its grace starts now.
						to_stamp.push((
							k.clone(),
							v.clone(),
							ReclaimState {
								observed_ms: now_ms,
								cursor: state.cursor.clone(),
							},
						));
						continue;
					}
					// Snapshot-safety gate: only destroy data once it has been
					// observed for at least `grace`, by which point any
					// transaction that could still read it is behind the MVCC
					// GC safepoint.
					if now_ms.saturating_sub(state.observed_ms) < grace_ms {
						continue;
					}
				}
				candidates.push(ReclaimCandidate {
					observed_ms: state.observed_ms,
					key: k.clone(),
					state,
				});
				if candidates.len() > RECLAIM_BATCH_SIZE as usize {
					// The newest held entry gives up its place: it has waited
					// least, so it loses to every other candidate. Held up to one
					// batch rather than up to the share divisor, because an entry
					// whose reclaim spends nothing — an already-empty prefix, or a
					// backend that drops the range in one call — costs no budget,
					// and the spend below walks through as many of those as it
					// finds. Capping the set at the divisor would stop that at the
					// divisor and throttle the backends where reclaim is cheapest.
					// One batch of candidates is the memory the pass already holds
					// for one batch of scanned entries.
					candidates.pop();
				}
			}
			// Persist this batch's stamps in one write transaction, bounded by the
			// batch as the paged data delete is bounded by the page. Done
			// separately from the read scan so we don't conflict with concurrent
			// enqueues.
			if !to_stamp.is_empty() {
				let txn = dbs.transaction(Write).await?;
				if let Err(e) = Self::ensure_not_cancelled(&canceller) {
					let _ = txn.cancel().await;
					return Err(e);
				}
				let mut condition_failed = false;
				for (k, expected, state) in &to_stamp {
					let value = match state.kv_encode_value() {
						Ok(value) => value,
						Err(e) => {
							let _ = txn.cancel().await;
							return Err(e);
						}
					};
					match txn.put_compare(Key::from(k.clone()), value, Some(expected.clone())).await
					{
						Ok(()) => {}
						Err(e) if super::is_conditional_write_conflict(&e) => {
							condition_failed = true;
							break;
						}
						Err(e) => {
							warn!(target: TARGET, "Failed to stamp reclaim queue entry: {e}");
						}
					}
				}
				if condition_failed {
					let _ = txn.cancel().await;
				} else {
					// A stamp that does not land leaves the entry unobserved, so the
					// next pass starts its grace instead. Counted rather than silent:
					// an uncounted failure here reports as a healthy pass while the
					// entry's clock never starts.
					if let Err(e) = txn.commit().await {
						let _ = txn.cancel().await;
						if !super::is_conditional_write_conflict(&e) {
							count_error += 1;
							warn!(target: TARGET, "Failed to commit reclaim queue stamps: {e}");
							return Ok((count_iteration, count_error));
						}
					}
				}
			}
			// Seek past the batch just walked; the window advancing is also what
			// terminates the walk, at the end of the queue.
			window = queue.clone().resume_after(&last, Direction::Forward);
		}
		if !lease_held {
			return Ok((count_iteration, count_error));
		}
		// Spend the key budget on the selected entries, longest-observed first.
		// `into_sorted_vec` is ascending in the candidate order, which is the
		// oldest observation first and the queue's key order between entries
		// observed in the same millisecond.
		let selected = candidates.into_sorted_vec();
		// Entries whose prefix this pass emptied, to delete from the queue. An
		// entry the pass only partly emptied is left queued for a later pass.
		let mut done: Vec<Vec<u8>> = Vec::with_capacity(selected.len());
		// How many of the selected entries are still to spend from the budget, so
		// each takes its slice of what is left rather than all of it.
		let mut remaining = selected.len() as u64;
		for candidate in selected {
			Self::ensure_not_cancelled(&canceller)?;
			// Stop at the entry the lease was lost on. The queue update below
			// still commits what this pass emptied, and whichever node holds
			// the lease now continues from the durable cursors. The answer has
			// to be read rather than discarded: a lease check is throttled to
			// one datastore read per maintenance period, so a call that drops
			// it consumes the read the page loop's own check depends on and
			// leaves that check answering affirmatively without asking.
			if !lh.try_maintain_lease().await? {
				break;
			}
			let ReclaimCandidate {
				key,
				state,
				..
			} = candidate;
			// Decoded during the walk that selected it, so this cannot fail; a
			// failure is still counted rather than panicking on it.
			let rc = match ReclaimKey::decode_key(&key) {
				Ok(rc) => rc,
				Err(e) => {
					count_error += 1;
					warn!(target: TARGET, "Failed to decode reclaim queue entry: {e}");
					remaining = remaining.saturating_sub(1);
					continue;
				}
			};
			// Keys this entry may delete before the pass moves on: its share of
			// what the budget has left, across the entries still to spend from
			// it, capped at the budget so the tail of a pass hands out only what
			// remains. An entry naming a prefix larger than its share therefore
			// cannot take the whole budget and leave its siblings untouched.
			// Floored at one key rather than one page: a share below a page
			// still deletes, since the page size caps a transaction rather than
			// setting a minimum.
			// The divisor is the entries still to spend, capped at the quota: a
			// pass holding a batch of candidates would otherwise cut every share
			// to a thousandth of the budget, so no entry would delete a useful
			// amount. Capped, each served entry gets about a page and the pass
			// stops when the budget runs out — which is what makes the
			// oldest-first order above decide who is served.
			let divisor = remaining.min(RECLAIM_PASS_ENTRY_QUOTA as u64);
			let share = (budget / divisor.max(1)).max(1).min(budget);
			remaining = remaining.saturating_sub(1);
			let mut left = share;
			// Whether the lease passed to another node mid-entry. Recorded
			// rather than broken on directly, so the budget below is charged
			// for the pages this entry did commit before the pass ends.
			let mut lease_lost = false;
			match dbs.reclaim_decoded(&rc, &state, &lh, &canceller, &mut left).await {
				// The prefix is empty, so the entry has nothing left to
				// name and can be retired.
				Ok(ReclaimOutcome::Complete) => done.push(key),
				// Progress is durable but keys remain: leaving the entry
				// queued is what lets a later pass resume it.
				Ok(ReclaimOutcome::Incomplete) => {}
				// The entry is already gone, so it must not be added to
				// `done`: that would delete whatever a concurrent writer
				// put at the same key.
				Ok(ReclaimOutcome::Cancelled) => {}
				// Whichever node holds the lease now resumes from the
				// cursors this pass committed.
				Ok(ReclaimOutcome::LeaseLost) => lease_lost = true,
				// Shutdown. Not a failure of this entry, so it is neither
				// counted nor logged; the queue update below refuses to
				// commit and the pass ends there.
				Err(e)
					if matches!(
						crate::err::engine_error(&e),
						Some(EngineError::QueryCancelled)
					) =>
				{
					break;
				}
				Err(e) => {
					count_error += 1;
					warn!(target: TARGET, "Tombstone reclaim failed for a queue entry: {e}");
				}
			}
			// Charge what the entry deleted, not what it was offered.
			budget = budget.saturating_sub(share.saturating_sub(left));
			if lease_lost {
				// The queue update below still commits what this pass
				// emptied; the node holding the lease now takes the rest.
				break;
			}
			if budget == 0 {
				// The pass has spent its key budget. Every cursor it
				// advanced is committed, so the next tick continues from
				// there rather than repeating this work.
				break;
			}
		}
		// Retire the entries this pass emptied, in one write transaction bounded
		// by the entry quota.
		if !done.is_empty() {
			let txn = dbs.transaction(Write).await?;
			if let Err(e) = Self::ensure_not_cancelled(&canceller) {
				let _ = txn.cancel().await;
				return Err(e);
			}
			// Retire only the value currently stored. This prevents a stale
			// completion from deleting a state advanced by another node, and
			// makes a concurrent cancellation win cleanly on TiKV.
			let mut condition_failed = false;
			for k in &done {
				let current = match txn.get(Key::from(k), None).await {
					Ok(Some(current)) => current,
					Ok(None) => continue,
					Err(e) => {
						warn!(target: TARGET, "Failed to read reclaim queue entry: {e}");
						continue;
					}
				};
				match txn.del_compare(Key::from(k), Some(&current)).await {
					Ok(()) => {}
					Err(e) if super::is_conditional_write_conflict(&e) => {
						condition_failed = true;
						break;
					}
					Err(e) => {
						warn!(target: TARGET, "Failed to delete reclaim queue entry: {e}");
					}
				}
			}
			if condition_failed {
				let _ = txn.cancel().await;
				return Ok((count_iteration, count_error));
			}
			// A pass whose queue update does not land has reclaimed data
			// without recording that it did, so it is counted: an uncounted
			// failure here reports as a healthy pass and leaves nothing for an
			// operator to see but the next tick repeating the same work.
			if let Err(e) = txn.commit().await {
				let _ = txn.cancel().await;
				if !super::is_conditional_write_conflict(&e) {
					count_error += 1;
					warn!(target: TARGET, "Failed to commit reclaim queue update: {e}");
				}
			}
		}
		Ok((count_iteration, count_error))
	}

	/// Whether the table a queue entry names still has a consumer of the
	/// shared doc-ID space: a doc-ID index, or the `graph_doc_ids` marker a
	/// numeric graph fold records (its blocks resolve through the space). A
	/// table with no definition has no consumer — its whole keyspace is
	/// reclaimed separately.
	async fn tb_has_doc_id_consumer(&self, rc: &ReclaimKey<'_>) -> Result<bool> {
		let txn = self.transaction(Read).await?;
		let res = async {
			let Some(tb) = txn.get_tb(rc.ns, rc.db, rc.tb.as_ref(), None).await? else {
				return Ok(false);
			};
			if tb.graph_doc_ids {
				return Ok(true);
			}
			let ixs = txn.all_tb_indexes(rc.ns, rc.db, rc.tb.as_ref(), None).await?;
			Ok(ixs.iter().any(|ix| ix.uses_shared_doc_ids()))
		}
		.await;
		let _ = txn.cancel().await;
		res
	}

	/// Destroy the data prefix a decoded reclaim queue entry names.
	///
	/// Resolves the entry's kind to the byte range beneath it and hands that
	/// range to [`Self::reclaim_range`]. All of these kinds name a subtree holding
	/// keys of more than one type, so the range is resolved as bytes.
	async fn reclaim_decoded(
		&self,
		rc: &ReclaimKey<'_>,
		state: &ReclaimState,
		lh: &LeaseHandler,
		canceller: &CancellationToken,
		budget: &mut u64,
	) -> Result<ReclaimOutcome> {
		let prefix = match rc.kind {
			ReclaimKind::Namespace => NsRoot {
				ns: rc.ns,
			}
			.raw_range()?,
			ReclaimKind::Database => DbRoot {
				ns: rc.ns,
				db: rc.db,
			}
			.raw_range()?,
			ReclaimKind::Index => IdxRoot {
				ns: rc.ns,
				db: rc.db,
				tb: Cow::Borrowed(rc.tb.as_ref()),
				ix: rc.ix,
			}
			.raw_range()?,
			// The bands of a table's shared doc-ID space, each its own entry so
			// each carries its own resume cursor. `rc.ix` is unused for these:
			// the space belongs to the table, not to any one index.
			//
			// The space is only orphaned while the table has no doc-ID consumer.
			// A consumer present here means one was defined after the entry was
			// queued without cancelling it — a node too old to know these kinds,
			// or too old to know the `graph_doc_ids` marker, is the case that
			// matters — so the reclaim obligation has lapsed and the entry is
			// retired with whatever the space still holds left in place.
			// Deleting from it would strip mappings the live consumer resolves
			// its entries through.
			//
			// The consumer check is resolved once, ahead of the prefix arms
			// below, because it opens a read transaction and scans the table's
			// index list.
			// Matched through the same predicate that keeps these kinds off the
			// out-of-transaction destroy, so the two cannot disagree about which
			// kinds hold a revocable claim.
			kind if kind.is_doc_id() && self.tb_has_doc_id_consumer(rc).await? => {
				// A cursor means this entry had already deleted part of the
				// space, so what the consumer adopted is torn: a `!di` mapping
				// whose `!dd` twin is gone resolves to no record. Nothing here
				// can repair it — the keys are already deleted, and the reaper
				// must not delete further from a space a live index is reading —
				// so the tear is reported for an operator to rebuild the table's
				// doc-ID indexes.
				if state.cursor.is_some() {
					warn!(
						target: TARGET,
						"A doc-ID index was defined over a partly-reclaimed doc-ID space \
						 ({}:{}:{}): the space is torn and the table's doc-ID indexes \
						 need rebuilding",
						rc.ns,
						rc.db,
						rc.tb.as_ref(),
					);
				}
				return Ok(ReclaimOutcome::Complete);
			}
			ReclaimKind::DocKey => {
				DocKeyPrefix::new(rc.ns, rc.db, Cow::Borrowed(rc.tb.as_ref())).raw_range()?
			}
			ReclaimKind::DocLookup => {
				DocLookupPrefix::new(rc.ns, rc.db, Cow::Borrowed(rc.tb.as_ref())).raw_range()?
			}
			ReclaimKind::DocLookupIdentity => {
				DocLookupIdentityPrefix::new(rc.ns, rc.db, Cow::Borrowed(rc.tb.as_ref()))
					.raw_range()?
			}
			ReclaimKind::DocPending => {
				DocPendingPrefix::new(rc.ns, rc.db, Cow::Borrowed(rc.tb.as_ref())).raw_range()?
			}
		};
		self.reclaim_range(rc, state, prefix, lh, canceller, budget).await
	}

	/// Destroy every key beneath `prefix`, resuming from the queue entry's
	/// committed cursor and stopping once `budget` keys have gone.
	///
	/// `budget` is this entry's allowance out of the pass's, and is decremented by
	/// what the entry actually deletes. Returning [`ReclaimOutcome::Incomplete`]
	/// with it spent leaves a durable cursor for the next turn this entry gets.
	///
	/// A backend offering [`DestroyRange`] empties the whole prefix in one
	/// out-of-transaction call, and the pass is complete. Every other backend
	/// pages the delete: each round opens one write transaction, scans a bounded
	/// page of keys, deletes exactly those keys, writes the resume cursor, and
	/// commits. Memory is therefore O(page) whatever the prefix's cardinality.
	///
	/// The cursor and the page of deletions it accounts for commit in the same
	/// transaction, so every key at or before the cursor is durably gone and
	/// progress is monotonic: a restart, a lost lease or an exhausted budget
	/// resumes at the cursor instead of rescanning the prefix. Resuming is also
	/// what keeps each scan off the delete tombstones the retired pages left
	/// behind. [`ReclaimState::observed_ms`] is carried through every cursor
	/// write unchanged — the grace gate measures from the first observation, and
	/// restamping here would let a prefix too large for one pass reset its own
	/// grace and never age past it.
	///
	/// Giving up single-transaction atomicity is sound because the catalog entry
	/// naming this prefix is already committed-removed: a partly-destroyed
	/// prefix is unreachable garbage, not partial state any reader can observe.
	///
	/// Idempotent: a re-run on an already-empty prefix scans one empty page and
	/// reports [`ReclaimOutcome::Complete`].
	async fn reclaim_range(
		&self,
		rc: &ReclaimKey<'_>,
		state: &ReclaimState,
		prefix: RawRange,
		lh: &LeaseHandler,
		canceller: &CancellationToken,
		budget: &mut u64,
	) -> Result<ReclaimOutcome> {
		// A backend that can drop the range outside a transaction destroys
		// every version in it in one call, so it needs neither pages nor a
		// cursor and ignores `expunge` — the catalog entry is already gone, so
		// there is nothing to retain. A failure here is propagated rather than
		// retried through the paged path: the entry stays queued and the next
		// pass tries again, so a transient storage failure is never mistaken
		// for an absent capability.
		//
		// Not taken for a table's shared doc-ID prefixes, whose claim is
		// revocable: `DEFINE INDEX` cancels the reclaim to keep the mappings the
		// space still holds. An out-of-transaction destroy neither joins that
		// transaction's conflict domain nor re-reads the claim, so it would go on
		// to delete mappings the new index has already adopted, leaving entries
		// pointing at doc-IDs that resolve to no record. The paged path re-reads
		// the claim inside every page's transaction, which is what lets the
		// cancellation stop it; its cursor is also what tells the next
		// `DEFINE INDEX` that the space was left torn.
		if !rc.kind.is_doc_id()
			&& let Some(ops) = self.destroy_range_ops()
		{
			trace!(
				target: TARGET,
				mechanism = ops.mechanism(),
				"Destroying a reclaimed prefix out-of-transaction",
			);
			ops.destroy_range(prefix.into_key_range()).await?;
			return Ok(ReclaimOutcome::Complete);
		}
		// Resume past the last key whose deletion is durable, but only where the
		// cursor names a key this prefix covers. A cursor at or past the prefix's
		// end would leave an empty window, which the delete cannot tell from a
		// drained prefix: it would report the entry complete, retire the only
		// remaining name for the data, and strand whatever the prefix still holds.
		// Restarting from the head instead re-scans pages that may already be
		// empty, which a delete tolerates.
		let resumable = state
			.cursor
			.as_deref()
			.is_some_and(|c| c >= prefix.start().as_slice() && c < prefix.end().as_slice());
		let window = match &state.cursor {
			Some(cursor) if resumable => prefix.resume_after(cursor, Direction::Forward),
			Some(_) => {
				warn!(
					target: TARGET,
					"Restarting a reclaim from the head of its prefix: the resume cursor \
					 names a key outside it",
				);
				prefix
			}
			None => prefix,
		};
		let outcome = PagedDelete {
			window,
			companion: PageCompanion::ReclaimEntry {
				rc,
				state: state.clone(),
			},
			expunge: rc.expunge == Expunge::Expunge,
			page: RECLAIM_BATCH_SIZE,
		}
		.run(self, lh, canceller, budget)
		.await?;
		Ok(match outcome {
			PagedOutcome::Complete => ReclaimOutcome::Complete,
			PagedOutcome::Incomplete => ReclaimOutcome::Incomplete,
			PagedOutcome::Cancelled => ReclaimOutcome::Cancelled,
			PagedOutcome::LeaseLost => ReclaimOutcome::LeaseLost,
		})
	}

	#[cfg(not(target_family = "wasm"))]
	async fn await_index_compaction_handle(
		ikb: &IndexKeyBase,
		handle: &mut tokio::task::JoinHandle<Result<()>>,
		canceller: &CancellationToken,
	) {
		match handle.await {
			Ok(Ok(())) => {}
			Ok(Err(e))
				if canceller.is_cancelled()
					&& matches!(
						crate::err::engine_error(&e),
						Some(EngineError::QueryCancelled)
					) => {}
			Ok(Err(e)) => {
				warn!("Index compaction {ikb} fails while awaiting cancellation: {e}");
			}
			Err(e) => {
				warn!("Index compaction {ikb} join fails while awaiting cancellation: {e}");
			}
		}
	}

	#[cfg(not(target_family = "wasm"))]
	async fn await_index_compaction_handles(
		handles: &mut Vec<(IndexKeyBase, tokio::task::JoinHandle<Result<()>>)>,
		canceller: &CancellationToken,
	) {
		while let Some((ikb, mut handle)) = handles.pop() {
			Self::await_index_compaction_handle(&ikb, &mut handle, canceller).await;
		}
	}

	/// Compacts each distinct index referenced by the given queue keys.
	///
	/// Folds queued graph adjacency scopes into packed blocks.
	///
	/// Modeled on [`Self::index_compaction`]: leased so one node drains the
	/// queue at a time, a rotating window so a hot table cannot starve
	/// later-sorting ones, bounded read batches, and queue cleanup in
	/// separate bounded write transactions. Before the leased drain, this
	/// node's read-path observations are flushed into the durable queue —
	/// they are held in memory because a read cannot write a queue entry.
	///
	/// The pass runs regardless of `graph_fold_threshold`: a zero threshold
	/// disables new read-path observations (fold initiation), never debt
	/// repayment — edge deletes on already-folded tables keep writing
	/// tombstones and queueing durable triggers whatever the threshold, and
	/// leaving those queued would grow the queue and the per-read tombstone
	/// subtraction without bound.
	pub async fn graph_fold(
		dbs: Arc<Datastore>,
		interval: Duration,
		canceller: CancellationToken,
	) -> Result<(usize, usize)> {
		trace!(target: TARGET, "Attempting graph fold process");
		Self::flush_graph_fold_observations(&dbs).await?;
		let lh = LeaseHandler::new_with_canceller(
			dbs.sequences.clone(),
			dbs.id,
			dbs.transaction_factory.clone(),
			TaskLeaseType::GraphFold,
			interval * 2,
			canceller.clone(),
		)?;
		let batch = dbs.config.idx.graph_fold_batch;
		let mut count_iteration = 0;
		let mut count_error = 0;
		let queue = GraphFoldPrefix {}.range()?;
		let mut window = queue.clone();
		// Whether the sweep since the last window wrap deleted a queue entry
		// or folded a scope. A wrap-around re-scan retries entries retained
		// by failed folds; without progress between two wraps every remaining
		// entry has just failed again, so the call yields to the next
		// interval instead of hot-looping on a poison scope.
		let mut progressed = false;
		'fold: loop {
			Self::ensure_not_cancelled(&canceller)?;
			// Without the lease, another node is draining the queue.
			if !lh.has_lease().await? {
				break 'fold;
			}
			Self::ensure_not_cancelled(&canceller)?;
			trace!(target: TARGET, "Running graph fold process");
			// One bounded, keys-only batch of queue entries per iteration,
			// in a short-lived read transaction.
			let keys = {
				let txn = dbs.transaction(Read).await?;
				let res =
					txn.keys(window.clone(), INDEX_COMPACTION_QUEUE_BATCH_SIZE, 0, None).await;
				let _ = txn.cancel().await;
				res?
			};
			Self::ensure_not_cancelled(&canceller)?;
			if keys.is_empty() {
				if window.start() == queue.start() || !progressed {
					// Nothing left anywhere in the queue, or everything left
					// belongs to scopes that failed this sweep.
					break 'fold;
				}
				// End of the range: wrap to re-scan entries skipped when the
				// window seeked past a partially-drained scope, or retained
				// when a scope's fold failed.
				progressed = false;
				window = queue.clone();
				continue;
			}
			count_iteration += 1;
			// The distinct scopes this batch names, in queue order, and each
			// entry's scope for the cleanup below. Entries that fail to
			// decode name nothing foldable; the cleanup removes them.
			let mut scopes: Vec<GraphFoldScope> = Vec::new();
			let mut seen: HashSet<GraphFoldScope> = HashSet::new();
			let mut key_scopes: Vec<Option<GraphFoldScope>> = Vec::with_capacity(keys.len());
			for key in &keys {
				match GraphFoldKey::decode_key(key) {
					Ok(key) => {
						let scope = GraphFoldScope {
							ns: key.ns,
							db: key.db,
							tb: key.tb.into_owned(),
							id: key.id.into_owned(),
							dir: key.dir,
						};
						if seen.insert(scope.clone()) {
							scopes.push(scope.clone());
						}
						key_scopes.push(Some(scope));
					}
					Err(e) => {
						warn!(target: TARGET, "Skipping undecodable graph fold queue entry: {e}");
						key_scopes.push(None);
					}
				}
			}
			// The scopes whose drain completed; only their queue entries are
			// deleted below. A failed scope keeps its entries, so its fold
			// debt survives for the wrap-around re-scan and later calls.
			let mut folded: HashSet<GraphFoldScope> = HashSet::with_capacity(scopes.len());
			for scope in scopes {
				match Self::fold_queued_scope(&dbs, &scope, batch, &canceller).await {
					Ok(()) => {
						folded.insert(scope);
					}
					Err(e) => {
						if canceller.is_cancelled() {
							return Err(e);
						}
						count_error += 1;
						warn!(target: TARGET, "Graph fold failed for a queued scope: {e}");
					}
				}
			}
			// Seek the next batch past the last scope's run of queue entries,
			// so a scope that keeps re-enqueueing cannot pin the window.
			if let Some(last_key) = keys.last() {
				window = match GraphFoldKey::decode_key(last_key) {
					Ok(last) => {
						let covered = GraphFoldDirPrefix {
							ns: last.ns,
							db: last.db,
							tb: Cow::Owned(last.tb.into_owned()),
							id: Cow::Owned(last.id.into_owned()),
							dir: last.dir,
						}
						.skip_extensions()?;
						queue.clone().resume_after(&covered, Direction::Forward)
					}
					Err(_) => queue.clone().resume_after(last_key, Direction::Forward),
				};
			}
			// Delete this batch's consumed queue entries in a separate bounded
			// write transaction: entries whose scope folded, and undecodable
			// entries — which can never be folded — deleted as bytes so they
			// do not park at the head of the queue forever.
			let deletable: Vec<&Vec<u8>> = keys
				.iter()
				.zip(&key_scopes)
				.filter(|(_, scope)| scope.as_ref().is_none_or(|s| folded.contains(s)))
				.map(|(k, _)| k)
				.collect();
			if deletable.is_empty() {
				continue;
			}
			progressed = true;
			loop {
				let txn = dbs.transaction(Write).await?;
				if let Err(e) = Self::ensure_not_cancelled(&canceller) {
					let _ = txn.cancel().await;
					return Err(e);
				}
				for k in &deletable {
					if let Err(e) = txn.del(Key::from(k.as_slice())).await {
						warn!(target: TARGET, "Failed to delete graph fold queue entry: {e}");
					}
				}
				if let Err(e) = txn.commit().await {
					if Self::cancel_and_retry_index_operation_conflict(
						&txn,
						&e,
						"Retryable conflict committing graph fold queue cleanup, retrying",
					)
					.await
					{
						continue;
					}
					warn!(target: TARGET, "Failed to commit graph fold queue cleanup: {e}");
					break 'fold;
				}
				break;
			}
		}
		Ok((count_iteration, count_error))
	}

	/// Writes this node's read-path fold observations into the durable
	/// queue: blind puts of per-observation keys, so nothing contends.
	async fn flush_graph_fold_observations(dbs: &Arc<Datastore>) -> Result<()> {
		let observations = dbs.triggers.drain_graph_fold_observations();
		if observations.is_empty() {
			return Ok(());
		}
		let txn = dbs.transaction(Write).await?;
		for scope in &observations {
			let key = GraphFoldKey {
				ns: scope.ns,
				db: scope.db,
				tb: Cow::Borrowed(&scope.tb),
				id: Cow::Borrowed(&scope.id),
				dir: scope.dir,
				nid: dbs.id,
				uid: Uuid::now_v7(),
			};
			if let Err(e) = txn.put_key(&key, &()).await {
				let _ = txn.cancel().await;
				return Err(e);
			}
		}
		txn.commit().await
	}

	/// Drains one queued scope: bounded fold passes, each in its own
	/// transaction, retrying a bounded number of times when a concurrent
	/// edge write conflicts with a pass.
	async fn fold_queued_scope(
		dbs: &Arc<Datastore>,
		scope: &GraphFoldScope,
		batch: usize,
		canceller: &CancellationToken,
	) -> Result<()> {
		// The catalog write that marks the vertex table folded addresses the
		// namespace and database by name. A namespace or database dropped
		// since the entry was queued leaves nothing to fold.
		let (ns_name, db_name) = {
			let txn = dbs.transaction(Read).await?;
			let ns = txn
				.all_ns(None)
				.await?
				.iter()
				.find(|n| n.namespace_id == scope.ns)
				.map(|n| n.name.to_string());
			let db = txn
				.all_db(scope.ns, None)
				.await?
				.iter()
				.find(|d| d.database_id == scope.db)
				.map(|d| d.name.to_string());
			let _ = txn.cancel().await;
			match (ns, db) {
				(Some(ns), Some(db)) => (ns, db),
				_ => return Ok(()),
			}
		};
		let vertex = crate::val::RecordId::new(scope.tb.clone(), scope.id.clone());
		let mut retries = 0;
		loop {
			Self::ensure_not_cancelled(canceller)?;
			let txn = Arc::new(dbs.transaction(Write).await?);
			// The environment the fold's doc-ID assignment reads: the
			// production `IndexEnv` is the query context, built the same way
			// the index-compaction processors build theirs.
			let mut env = dbs.setup_ctx()?;
			env.set_transaction(Arc::clone(&txn));
			let env = env.freeze();
			let outcome = match crate::idx::adjacency::fold_scope(
				&env, scope.ns, scope.db, &ns_name, &db_name, &vertex, scope.dir, batch,
			)
			.await
			{
				Ok(outcome) => outcome,
				Err(e) => {
					let _ = txn.cancel().await;
					return Err(e);
				}
			};
			match txn.commit().await {
				Ok(()) => {
					retries = 0;
					if !outcome.has_more {
						return Ok(());
					}
				}
				Err(e) => {
					// A concurrent RELATE or DELETE on the scope beat this
					// pass; take a fresh snapshot and try again, bounded so a
					// write-hot vertex cannot spin the task.
					if surrealdb_datastore::is_retryable_transaction_conflict(&e) && retries < 5 {
						retries += 1;
						continue;
					}
					return Err(e);
				}
			}
		}
	}

	/// On native targets, compaction tasks are spawned in parallel — one per
	/// distinct index — and joined afterwards. Duplicate queue entries for
	/// the same index are deduplicated via a [`HashMap`] so only one task is
	/// spawned per index. Failures are logged but do not abort the loop.
	///
	/// Returns the number of indexes that failed to compact.
	#[cfg(not(target_family = "wasm"))]
	async fn index_compaction_loop(
		dbs: Arc<Datastore>,
		lh: &LeaseHandler,
		keys: &[Vec<u8>],
		canceller: CancellationToken,
	) -> Result<usize> {
		let mut compacted_indexes = HashMap::new();
		for k in keys {
			Self::ensure_not_cancelled(&canceller)?;
			lh.try_maintain_lease().await?;
			// An undecodable entry names no index to compact; skip it here
			// and let the batch cleanup delete it, so one corrupt key cannot
			// wedge every future compaction cycle.
			let ic = match IndexCompactionKey::decode_key(k) {
				Ok(ic) => ic,
				Err(e) => {
					warn!(target: TARGET, "Skipping undecodable index compaction queue entry: {e}");
					continue;
				}
			};
			let ikb = IndexKeyBase::new(ic.ns, ic.db, ic.tb.as_ref().clone(), ic.ix);
			if let Entry::Vacant(e) = compacted_indexes.entry(ikb) {
				e.insert(());
			}
		}
		let mut error_count = 0;
		let mut handles: Vec<(IndexKeyBase, tokio::task::JoinHandle<Result<()>>)> =
			Vec::with_capacity(compacted_indexes.len());
		for (ikb, _) in compacted_indexes {
			if let Err(e) = Self::ensure_not_cancelled(&canceller) {
				Self::await_index_compaction_handles(&mut handles, &canceller).await;
				return Err(e);
			}
			let dbs = Arc::clone(&dbs);
			let canceller = canceller.clone();
			let task_ikb = ikb.clone();
			let jh = spawn(async move { dbs.process_index_compaction(&task_ikb, canceller).await });
			handles.push((ikb, jh));
		}
		while let Some((ikb, mut jh)) = handles.pop() {
			let res = tokio::select! {
				biased;
				_ = canceller.cancelled() => {
					Self::await_index_compaction_handle(&ikb, &mut jh, &canceller).await;
					Self::await_index_compaction_handles(&mut handles, &canceller).await;
					bail!(EngineError::QueryCancelled);
				}
				res = &mut jh => res?,
			};
			if let Err(e) = res {
				if canceller.is_cancelled() {
					Self::await_index_compaction_handles(&mut handles, &canceller).await;
					return Err(e);
				}
				error_count += 1;
				warn!("Index compaction {ikb} fails: {e}");
			}
		}
		Ok(error_count)
	}

	/// Compacts each distinct index referenced by the given queue keys.
	///
	/// On wasm, `tokio::spawn` is unavailable so compactions run
	/// sequentially. A [`HashSet`] is used to skip duplicate queue entries
	/// for the same index. Failures are logged but do not abort the loop,
	/// matching the non-wasm behavior so that a single transient failure
	/// does not prevent other indexes from being compacted.
	///
	/// Returns the number of indexes that failed to compact.
	#[cfg(target_family = "wasm")]
	async fn index_compaction_loop(
		dbs: Arc<Datastore>,
		lh: &LeaseHandler,
		keys: &[Vec<u8>],
		canceller: CancellationToken,
	) -> Result<usize> {
		let mut seen = HashSet::new();
		let mut error_count = 0;
		for k in keys {
			Self::ensure_not_cancelled(&canceller)?;
			lh.try_maintain_lease().await?;
			// An undecodable entry names no index to compact; skip it here
			// and let the batch cleanup delete it, so one corrupt key cannot
			// wedge every future compaction cycle.
			let ic = match IndexCompactionKey::decode_key(k) {
				Ok(ic) => ic,
				Err(e) => {
					warn!(target: TARGET, "Skipping undecodable index compaction queue entry: {e}");
					continue;
				}
			};
			let ikb = IndexKeyBase::new(ic.ns, ic.db, ic.tb.as_ref().clone(), ic.ix);
			if !seen.insert(ikb.clone()) {
				continue;
			}
			let res: Result<()> =
				async { dbs.process_index_compaction(&ikb, canceller.clone()).await }.await;
			if let Err(e) = res {
				if canceller.is_cancelled() {
					return Err(e);
				}
				error_count += 1;
				warn!("Index compaction {ikb} fails: {e}");
			}
		}
		Ok(error_count)
	}

	/// Performs the actual compaction of a single index.
	///
	/// Looks up the index definition identified by `ikb` and dispatches to
	/// the appropriate compaction implementation based on the index type:
	/// full-text, count, HNSW, or DiskANN. Indexes that are being removed
	/// (`prepare_remove`), not found, or of an unsupported type are silently
	/// skipped with a trace log.
	async fn process_index_compaction(
		&self,
		ikb: &IndexKeyBase,
		canceller: CancellationToken,
	) -> Result<()> {
		Self::ensure_not_cancelled(&canceller)?;
		// The catalog definition and the index's durable build state, read
		// together so the ownership decision below costs no extra transaction.
		let (ix, build_owner_live) = {
			let txn = self.transaction(Read).await?;
			let res = async {
				let ix = txn
					.get_tb_index_by_id(ikb.ns(), ikb.db(), ikb.table(), ikb.index(), None)
					.await?;
				let live = build_owner_is_live(&txn, ikb).await?;
				Ok::<_, anyhow::Error>((ix, live))
			}
			.await;
			let _ = txn.cancel().await;
			res?
		};
		Self::ensure_not_cancelled(&canceller)?;
		match ix {
			Some(ix) if !ix.prepare_remove => {
				// A vector index whose build is still in flight is left to that
				// build's own drain, because only the drain knows which on-disk
				// layout to compact into. A `REBUILD INDEX` that migrates
				// `format_version` holds the new definition in its uncommitted
				// statement transaction, so the catalog read above still reports the
				// retired one. Compacting from here would fold the pendings into the
				// retired layout and leave the published index without them; and
				// because the process-local vector-index wrapper is keyed without the
				// format version, the two compactors would also evict each other's
				// graph on every access.
				//
				// Durable state is the whole test, on every node including the one
				// running the build. It is committed before the builder is
				// registered locally and held until the statement that publishes
				// the definition closes its transaction, so it already covers every
				// window in which this catalog read can be stale. A process-local
				// check would only add the tail between that release and the
				// builder task's exit, where the build has finished publishing and
				// skipping would discard the request that release just queued.
				//
				// The queue entry that led here is dropped with the rest of its
				// batch, and for these two kinds that loses nothing: their builders
				// drain the index's pendings before returning, so the entry is
				// already redundant. Full-text and count builders have no such drain,
				// which is why the test is scoped to the kinds that do rather than
				// applied to every index — dropping one of their requests would leave
				// deltas uncompacted until the next write to the index.
				let drains_own_pendings = match &ix.index {
					Index::Hnsw(_) => true,
					#[cfg(diskann)]
					Index::DiskAnn(_) => true,
					_ => false,
				};
				if drains_own_pendings && build_owner_live {
					trace!(target: TARGET, "Index compaction: Index {ikb:?} is being built, leaving it to its builder");
					return Ok(());
				}
				match &ix.index {
					Index::FullText(p) => {
						self.process_fulltext_compaction(ikb, p, &canceller).await?;
					}
					Index::Count(_) => {
						self.process_count_compaction(ikb, &canceller).await?;
					}
					Index::Hnsw(_) => {
						// HNSW compaction owns its pending-key allocation and pending-range
						// drain semantics separately from full-text/count compaction.
						self.process_hnsw_compaction(ikb, ix.format_version, &canceller).await?;
					}
					#[cfg(diskann)]
					Index::DiskAnn(_) => {
						self.process_diskann_compaction(ikb, &canceller).await?;
					}
					_ => {
						trace!(target: TARGET, "Index compaction: Index {:?} does not support compaction, skipping", ikb);
					}
				}
			}
			_ => {
				trace!(target: TARGET, "Index compaction: Index {:?} not found, skipping", ikb);
			}
		}
		Ok(())
	}

	/// Discards the process-local HNSW wrapper and element caches for one index
	/// after a compaction write that reached the graph and did not commit.
	///
	/// Neither half of that state can be validated against the store. The
	/// element caches carry no version at all. A graph layer carries one, but
	/// it is a counter each writer advances in its own copy as it applies, so
	/// two writers applying the same batch from the same version reach the same
	/// one: the rolled-back topology is then indistinguishable to a state check
	/// from the topology the winning commit stored, and a later apply would
	/// write node changes derived from it over the winner's nodes. An apply
	/// that failed part-way is worse still — it can mutate a layer before
	/// reaching the `save_nodes` that advances the version at all.
	///
	/// The next access rebuilds the wrapper and reloads every layer from
	/// persisted state, which is the cost this pays. A write that stopped at
	/// the compaction guards never reached the graph and must not come here.
	async fn discard_hnsw_index(
		&self,
		tb: crate::catalog::TableId,
		ikb: &IndexKeyBase,
		format_version: u16,
	) {
		if let Err(e) = self.index_stores.remove_hnsw_index(tb, ikb.clone(), format_version).await {
			warn!(target: TARGET, "Failed to evict HNSW index after an uncommitted compaction write: {e}");
		}
	}

	/// Runs HNSW compaction as bounded read-plan/write-apply batches.
	///
	/// Pending entries are captured in a read transaction and conditionally
	/// deleted in a short write transaction before graph mutation. A write that
	/// reached the graph in place and then did not commit leaves the
	/// process-local wrapper holding a topology and caches the store never
	/// took, so the wrapper is discarded; a write that was staged, or that
	/// stopped at the guards, left the wrapper untouched and keeps it. The
	/// discard targets the format version the write phase applied through — a
	/// `REBUILD INDEX` can bump the catalog format after `format_version` was
	/// captured, and both the wrapper and the cache entries are scoped per
	/// format.
	async fn process_hnsw_compaction(
		&self,
		ikb: &IndexKeyBase,
		format_version: u16,
		canceller: &CancellationToken,
	) -> Result<()> {
		loop {
			Self::ensure_not_cancelled(canceller)?;
			let prepared = {
				let txn = Arc::new(self.transaction(Read).await?);
				let res: Result<
					Option<(
						crate::catalog::TableId,
						crate::idx::trees::hnsw::index::HnswCompactionPlan,
					)>,
				> = async {
					let Some(tb) = txn.get_tb(ikb.ns(), ikb.db(), ikb.table(), None).await? else {
						return Ok(None);
					};
					match txn
						.get_tb_index_by_id(ikb.ns(), ikb.db(), ikb.table(), ikb.index(), None)
						.await?
					{
						Some(ix) if !ix.prepare_remove && matches!(&ix.index, Index::Hnsw(_)) => {
							let mut ctx = self.setup_ctx()?;
							ctx.set_transaction(Arc::clone(&txn));
							let ctx = ctx.freeze();
							let plan = IndexOperation::prepare_hnsw_compaction(&ctx, ikb).await?;
							Ok(Some((tb.table_id, plan)))
						}
						_ => Ok(None),
					}
				}
				.await;
				let _ = txn.cancel().await;
				res?
			};
			let Some((tb, plan)) = prepared else {
				return Ok(());
			};
			if !plan.has_work() {
				return Ok(());
			}
			let has_more = plan.has_more();
			Self::ensure_not_cancelled(canceller)?;

			let txn = Arc::new(self.transaction(Write).await?);
			// The apply phase re-reads the catalog and mutates the wrapper and
			// cache belonging to that fresh format, so every failure-side
			// recovery below must clear the same format, not the one captured at
			// dispatch time.
			let mut applied_format = format_version;
			let res: Result<HnswCompactionOutcome> = async {
				// Re-tested inside the write transaction, and under a conflict
				// registration. The dispatch-time test was a snapshot in a
				// transaction that has since been cancelled, so a build acquired
				// after it would otherwise be invisible to this apply; the
				// registration makes such an acquisition conflict this commit
				// instead, and the retry re-reads it.
				if build_owner_is_live_locked(&txn, ikb).await? {
					return Ok(HnswCompactionOutcome::Skipped);
				}
				match txn
					.get_tb_index_by_id(ikb.ns(), ikb.db(), ikb.table(), ikb.index(), None)
					.await?
				{
					Some(ix) if !ix.prepare_remove => match &ix.index {
						Index::Hnsw(p) => {
							applied_format = ix.format_version;
							let mut ctx = self.setup_ctx()?;
							ctx.set_transaction(Arc::clone(&txn));
							let ctx = ctx.freeze();
							IndexOperation::apply_hnsw_compaction(
								&ctx,
								&self.index_stores,
								ikb,
								p,
								ix.format_version,
								plan,
							)
							.await
						}
						_ => Ok(HnswCompactionOutcome::Skipped),
					},
					_ => Ok(HnswCompactionOutcome::Skipped),
				}
			}
			.await;
			match res {
				Ok(outcome) if outcome.applied() => {
					// Only an in-place batch reaches the graph before its commit; a
					// staged one publishes from the commit itself, so a transaction
					// that does not commit leaves its wrapper untouched.
					let in_place = outcome == HnswCompactionOutcome::InPlace;
					if let Err(e) = Self::ensure_not_cancelled(canceller) {
						let _ = txn.cancel().await;
						if in_place {
							self.discard_hnsw_index(tb, ikb, applied_format).await;
						}
						return Err(e);
					}
					#[cfg(test)]
					if let Err(e) = maybe_inject_retryable_conflict(
						RetryableConflictSite::HnswCompaction,
						self.id,
					) {
						let _ = txn.cancel().await;
						if in_place {
							self.discard_hnsw_index(tb, ikb, applied_format).await;
						}
						if Self::retry_index_operation_conflict(
							&e,
							format!(
								"Retryable conflict committing HNSW compaction for {ikb}, retrying"
							),
						)
						.await
						{
							continue;
						}
						return Err(e);
					}
					if let Err(e) = txn.commit().await {
						let _ = txn.cancel().await;
						if in_place {
							self.discard_hnsw_index(tb, ikb, applied_format).await;
						}
						if Self::retry_index_operation_conflict(
							&e,
							format!(
								"Retryable conflict committing HNSW compaction for {ikb}, retrying"
							),
						)
						.await
						{
							continue;
						}
						return Err(e);
					}
				}
				Ok(_) => {
					let _ = txn.cancel().await;
					return Ok(());
				}
				Err(e) => {
					let _ = txn.cancel().await;
					self.discard_hnsw_index(tb, ikb, applied_format).await;
					if Self::retry_index_operation_conflict(
						&e,
						format!("Retryable conflict applying HNSW compaction for {ikb}, retrying"),
					)
					.await
					{
						continue;
					}
					return Err(e);
				}
			}
			Self::ensure_not_cancelled(canceller)?;
			if !has_more {
				return Ok(());
			}
			// Defense-in-depth: every match arm above either commits (Ok(true))
			// or cancels (Ok(false)/Err) the tx, so by here `closed()` should
			// always be true. Catch any future regression where a `?` between
			// the match and this point bypasses finalization. No-op today.
			if !txn.closed() {
				let _ = txn.cancel().await;
			}
		}
	}

	#[cfg(diskann)]
	/// Runs DiskANN compaction as bounded read-plan/write-apply batches.
	async fn process_diskann_compaction(
		&self,
		ikb: &IndexKeyBase,
		canceller: &CancellationToken,
	) -> Result<()> {
		loop {
			Self::ensure_not_cancelled(canceller)?;
			let prepared = {
				let txn = Arc::new(self.transaction(Read).await?);
				let res: Result<
					Option<(
						crate::catalog::TableId,
						crate::idx::trees::diskann::index::DiskAnnCompactionPlan,
					)>,
				> = async {
					let Some(tb) = txn.get_tb(ikb.ns(), ikb.db(), ikb.table(), None).await? else {
						return Ok(None);
					};
					match txn
						.get_tb_index_by_id(ikb.ns(), ikb.db(), ikb.table(), ikb.index(), None)
						.await?
					{
						Some(ix)
							if !ix.prepare_remove && matches!(&ix.index, Index::DiskAnn(_)) =>
						{
							let mut ctx = self.setup_ctx()?;
							ctx.set_transaction(Arc::clone(&txn));
							let ctx = ctx.freeze();
							let plan =
								IndexOperation::prepare_diskann_compaction(&ctx, ikb).await?;
							Ok(Some((tb.table_id, plan)))
						}
						_ => Ok(None),
					}
				}
				.await;
				let _ = txn.cancel().await;
				res?
			};
			let Some((_tb, plan)) = prepared else {
				return Ok(());
			};
			if !plan.requires_apply() {
				return Ok(());
			}
			let has_more = plan.has_more();
			Self::ensure_not_cancelled(canceller)?;

			let txn = Arc::new(self.transaction(Write).await?);
			let res: Result<bool> = async {
				// See the HNSW counterpart: the dispatch-time ownership test is
				// a cancelled snapshot, so it is re-tested here under a conflict
				// registration that a concurrent build acquisition trips.
				if build_owner_is_live_locked(&txn, ikb).await? {
					return Ok(false);
				}
				match txn
					.get_tb_index_by_id(ikb.ns(), ikb.db(), ikb.table(), ikb.index(), None)
					.await?
				{
					Some(ix) if !ix.prepare_remove => match &ix.index {
						Index::DiskAnn(p) => {
							let mut ctx = self.setup_ctx()?;
							ctx.set_transaction(Arc::clone(&txn));
							let ctx = ctx.freeze();
							IndexOperation::apply_diskann_compaction(
								&ctx,
								&self.index_stores,
								ikb,
								p,
								ix.format_version,
								plan,
							)
							.await
						}
						_ => Ok(false),
					},
					_ => Ok(false),
				}
			}
			.await;
			// `apply_diskann_compaction` normally owns the transaction's
			// lifecycle (commits on success, cancels on apply failure while
			// holding the graph write lock — closing the #7318 race). A few
			// pre-apply paths inside `IndexOperation::apply_diskann_compaction`
			// (missing table or catalog lookup errors) can return without
			// finalizing the tx, so we add an idempotent safety net here:
			// cancel only if the tx is still open. Cancel on an already-closed
			// tx returns `TransactionFinished` and is harmlessly discarded.
			if !txn.closed() {
				let _ = txn.cancel().await;
			}
			match res {
				Ok(true) => {}
				Ok(false) => return Ok(()),
				Err(e) => return Err(e),
			}
			Self::ensure_not_cancelled(canceller)?;
			if !has_more {
				return Ok(());
			}
		}
	}

	/// Runs full-text compaction as a read-plan followed by a guarded write.
	///
	/// This avoids holding a mutable range scan over `!dc`/`!tt`; deltas
	/// committed after the read snapshot remain for a later compaction.
	async fn process_fulltext_compaction(
		&self,
		ikb: &IndexKeyBase,
		p: &crate::catalog::FullTextParams,
		canceller: &CancellationToken,
	) -> Result<()> {
		loop {
			Self::ensure_not_cancelled(canceller)?;
			let plan = {
				let txn = self.transaction(Read).await?;
				let ix = txn
					.get_tb_index_by_id(ikb.ns(), ikb.db(), ikb.table(), ikb.index(), None)
					.await?
					.filter(|ix| !ix.prepare_remove);
				let res = IndexOperation::prepare_fulltext_compaction(
					&self.index_stores,
					ikb,
					&txn,
					p,
					&self.config.idx.file_allowlist,
					match &ix {
						Some(ix) if matches!(ix.index, crate::catalog::Index::FullText(_)) => {
							ix.format_version
						}
						_ => return Ok(()),
					},
				)
				.await;
				let _ = txn.cancel().await;
				res?
			};
			if !plan.has_work() {
				return Ok(());
			}
			let has_more = plan.has_more();
			Self::ensure_not_cancelled(canceller)?;

			let txn = self.transaction(Write).await?;
			let res = async {
				match txn
					.get_tb_index_by_id(ikb.ns(), ikb.db(), ikb.table(), ikb.index(), None)
					.await?
				{
					Some(ix) if !ix.prepare_remove => match &ix.index {
						Index::FullText(p) => {
							IndexOperation::apply_fulltext_compaction(
								&self.index_stores,
								ikb,
								&txn,
								p,
								&self.config.idx.file_allowlist,
								ix.format_version,
								plan,
							)
							.await
						}
						_ => Ok(false),
					},
					_ => Ok(false),
				}
			}
			.await;
			match res {
				Ok(true) => {
					if let Err(e) = Self::ensure_not_cancelled(canceller) {
						let _ = txn.cancel().await;
						return Err(e);
					}
					#[cfg(test)]
					if let Err(e) = maybe_inject_retryable_conflict(
						RetryableConflictSite::FullTextCompaction,
						self.id,
					) {
						if Self::cancel_and_retry_index_operation_conflict(
							&txn,
							&e,
							format!(
								"Retryable conflict committing full-text compaction for {ikb}, retrying"
							),
						)
						.await
						{
							continue;
						}
						return Err(e);
					}
					if let Err(e) = txn.commit().await {
						if Self::cancel_and_retry_index_operation_conflict(
							&txn,
							&e,
							format!(
								"Retryable conflict committing full-text compaction for {ikb}, retrying"
							),
						)
						.await
						{
							continue;
						}
						return Err(e);
					}
				}
				Ok(false) => {
					let _ = txn.cancel().await;
					return Ok(());
				}
				Err(e) => {
					let _ = txn.cancel().await;
					if Self::retry_index_operation_conflict(
						&e,
						format!(
							"Retryable conflict applying full-text compaction for {ikb}, retrying"
						),
					)
					.await
					{
						continue;
					}
					return Err(e);
				}
			}
			Self::ensure_not_cancelled(canceller)?;
			if !has_more {
				return Ok(());
			}
			// Defense-in-depth: every match arm above either commits (Ok(true))
			// or cancels (Ok(false)/Err) the tx, so by here `closed()` should
			// always be true. Catch any future regression where a `?` between
			// the match and this point bypasses finalization. No-op today.
			if !txn.closed() {
				let _ = txn.cancel().await;
			}
		}
	}

	/// Runs count-index compaction as a read-plan followed by a guarded write.
	///
	/// The write phase deletes only keys captured in the plan, so concurrent
	/// `!iu` deltas are preserved and included by later reads/compactions.
	async fn process_count_compaction(
		&self,
		ikb: &IndexKeyBase,
		canceller: &CancellationToken,
	) -> Result<()> {
		loop {
			Self::ensure_not_cancelled(canceller)?;
			let plan = {
				let txn = self.transaction(Read).await?;
				let res = IndexOperation::prepare_count_compaction(ikb, &txn).await;
				let _ = txn.cancel().await;
				res?
			};
			if !plan.has_work() {
				return Ok(());
			}
			let has_more = plan.has_more();
			Self::ensure_not_cancelled(canceller)?;

			let txn = self.transaction(Write).await?;
			let res = async {
				match txn
					.get_tb_index_by_id(ikb.ns(), ikb.db(), ikb.table(), ikb.index(), None)
					.await?
				{
					Some(ix) if !ix.prepare_remove && matches!(&ix.index, Index::Count(_)) => {
						IndexOperation::apply_count_compaction(ikb, &txn, plan).await
					}
					_ => Ok(false),
				}
			}
			.await;
			match res {
				Ok(true) => {
					if let Err(e) = Self::ensure_not_cancelled(canceller) {
						let _ = txn.cancel().await;
						return Err(e);
					}
					#[cfg(test)]
					if let Err(e) = maybe_inject_retryable_conflict(
						RetryableConflictSite::CountCompaction,
						self.id,
					) {
						if Self::cancel_and_retry_index_operation_conflict(
							&txn,
							&e,
							format!(
								"Retryable conflict committing count compaction for {ikb}, retrying"
							),
						)
						.await
						{
							continue;
						}
						return Err(e);
					}
					if let Err(e) = txn.commit().await {
						if Self::cancel_and_retry_index_operation_conflict(
							&txn,
							&e,
							format!(
								"Retryable conflict committing count compaction for {ikb}, retrying"
							),
						)
						.await
						{
							continue;
						}
						return Err(e);
					}
				}
				Ok(false) => {
					let _ = txn.cancel().await;
					return Ok(());
				}
				Err(e) => {
					let _ = txn.cancel().await;
					if Self::retry_index_operation_conflict(
						&e,
						format!("Retryable conflict applying count compaction for {ikb}, retrying"),
					)
					.await
					{
						continue;
					}
					return Err(e);
				}
			}
			Self::ensure_not_cancelled(canceller)?;
			if !has_more {
				return Ok(());
			}
		}
	}

	/// Process queued async events using a distributed lease to coordinate batches.
	/// Once a batch starts it runs to completion even if the lease expires, so
	/// brief overlap is possible.
	///
	/// Returns as soon as `canceller` is tripped, at the next batch boundary. The
	/// events themselves are user-defined SurrealQL that nothing here bounds, so
	/// this bounds the wait to one batch rather than to the whole queue — which
	/// is what stops a busy queue from holding [`Self::shutdown`] open for as
	/// long as writes keep arriving.
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip(self, canceller))]
	pub(crate) async fn event_processing(
		&self,
		interval: Duration,
		canceller: &CancellationToken,
	) -> Result<()> {
		// Output function invocation details to logs
		trace!(target: TARGET, "Attempting event processing process");
		// Create a new lease handler
		let lh = LeaseHandler::new(
			self.sequences.clone(),
			self.id,
			self.transaction_factory.clone(),
			TaskLeaseType::EventProcessing,
			interval * 2,
		)?;
		// We continue while there are keys, the lease, and no cancellation
		loop {
			// Stop between batches once shutdown starts. Cancellation is not a
			// failure: the queue is durable, so whatever is left is processed by
			// the next pass on this node or another.
			if canceller.is_cancelled() {
				return Ok(());
			}
			// Attempt to acquire a lease for the EventProcessing task
			// If we don't get the lease, another node is handling this task
			if !lh.has_lease().await? {
				return Ok(());
			}
			// Output function invocation details to logs
			trace!(target: TARGET, "Running event processing process");
			if process_next_events_batch(self, Some(&lh)).await? == 0 {
				// The last batch didn't have any events to process,
				// we can sleep until the next wake-up call
				return Ok(());
			}
		}
	}

	// --------------------------------------------------
	// Other functions
	// --------------------------------------------------

	/// Create a new transaction on this datastore
	///
	/// ```rust,no_run
	/// use surrealdb_core::kvs::{Datastore, TransactionType::*};
	/// use anyhow::Error;
	///
	/// #[tokio::main]
	/// async fn main() -> Result<(),Error> {
	///     let ds = Datastore::new("rocksdb://database.db").await?;
	///     let mut tx = ds.transaction(Write).await?;
	///     tx.cancel().await?;
	///     Ok(())
	/// }
	/// ```
	pub async fn transaction(&self, write: TransactionType) -> Result<Transaction> {
		self.transaction_factory.transaction(write, self.sequences.clone()).await
	}

	pub(crate) fn sequences(&self) -> &Sequences {
		&self.sequences
	}

	pub(crate) fn transaction_factory(&self) -> &TransactionFactory {
		&self.transaction_factory
	}

	#[cfg(test)]
	#[cfg_attr(not(feature = "kv-mem"), allow(dead_code))]
	pub(crate) fn index_builder(&self) -> &IndexBuilder {
		&self.index_builder
	}
	/// The post-commit wake-ups the background tasks wait on.
	pub fn commit_triggers(&self) -> &Arc<CommitTriggers> {
		&self.triggers
	}

	/// The live-query engine this datastore delivers notifications through.
	///
	/// Selected from the datastore configuration at construction and fixed for
	/// the datastore's lifetime. The engine's background tasks read it to decide
	/// whether to run the per-node live-query router at all: under
	/// [`LiveQueryEngine::Inline`] the router has nothing to deliver, so no task
	/// is spawned for it.
	pub fn live_query_engine(&self) -> LiveQueryEngine {
		self.config.datastore.live_query_engine
	}

	pub async fn health_check(&self) -> Result<()> {
		let tx = self.transaction(Read).await?;

		// Cancel the transaction
		trace!("Cancelling health check transaction");
		// Read a declared key rather than a probe byte: whether it is present says
		// nothing here, only that the store answered.
		match tx.get_key(&VersionKey {}, None).await {
			Err(err) => {
				// Ensure the transaction is cancelled
				let _ = tx.cancel().await;
				// Return an error for this endpoint
				Err(err)
			}
			Ok(_) => {
				// Ensure the transaction is cancelled
				let _ = tx.cancel().await;
				// Return success for this endpoint
				Ok(())
			}
		}
	}

	/// Returns how long ago the current node last refreshed its cluster
	/// heartbeat, or `None` when this node has no cluster membership row.
	///
	/// The node-membership refresh background task rewrites this node's
	/// heartbeat to the KV store every `node_membership_refresh_interval`. A
	/// small age therefore confirms, from work the node already performs, that
	/// the refresh task is running and that both the storage write path (the
	/// heartbeat was recently committed) and read path (it is readable here in
	/// a fresh transaction) are healthy. Readiness probes use this instead of a
	/// dedicated health check to avoid duplicating that work.
	///
	/// An absent row is `None` rather than an error, because it is an ordinary
	/// state of a live node and not a failure to read: `insert_node` writes the
	/// row during startup, a peer that archives this node deletes it again, and
	/// either way the next refresh tick writes it back. A caller can therefore
	/// tell "no heartbeat yet" from "storage did not answer", which only `Err`
	/// reports. `/ready` depends on the distinction.
	pub async fn node_heartbeat_age(&self) -> Result<Option<Duration>> {
		// Open a fresh read transaction so the lookup misses the per-transaction
		// cache and actually reads the node key from storage.
		let tx = self.transaction(Read).await?;
		let res = tx.get_node(self.id).await;
		// Always release the transaction, regardless of the lookup result.
		let _ = tx.cancel().await;
		let Some(node) = res? else {
			return Ok(None);
		};
		// Heartbeats are stored as milliseconds since the epoch; saturate to
		// avoid underflow from minor clock skew between writes and this read.
		let now = self.clock_now();
		Ok(Some(Duration::from_millis(now.value.saturating_sub(node.heartbeat.value))))
	}

	/// Run a query.
	///
	/// Every buffered query entry point that takes a whole query is this one:
	/// a [`QueryRequest`] describes what to run, who runs it, and the
	/// conditions — a caller-owned transaction, bound variables, a
	/// cancellation handle — independently of one another, so the
	/// combinations do not need a method each. Import is the exception: it
	/// consumes a byte stream and keeps its own preflight, whose session
	/// errors differ from this one's.
	///
	/// The source is split into statements before the session preflight, so a
	/// caller that submitted unparsable text learns that from the call
	/// whatever else is wrong with the request. SurrealQL statements stay in
	/// surface form; see [`Self::statements_for`].
	///
	/// See [`Self::run_streaming`] to receive results as they are produced
	/// rather than all at once.
	///
	/// ```rust,no_run
	/// use anyhow::Error;
	/// use surrealdb_core::kvs::{Datastore, QueryRequest};
	/// use surrealdb_core::dbs::Session;
	///
	/// #[tokio::main]
	/// async fn main() -> Result<(),Error> {
	///     let ds = Datastore::new("memory").await?;
	///     let ses = Session::owner();
	///     let sql = "USE NS test DB test; SELECT * FROM person;";
	///     let res = ds.run(QueryRequest::new(sql, &ses)).await?;
	///     Ok(())
	/// }
	/// ```
	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn run(
		&self,
		req: QueryRequest<'_>,
	) -> std::result::Result<Vec<QueryResult>, TypesError> {
		let QueryRequest {
			source,
			session,
			variables,
			transaction,
			cancel,
		} = req;
		let statements = self.statements_for(source)?;
		let (opt, ctx) = self.setup_query(session, variables, transaction.as_ref(), cancel)?;
		match transaction {
			Some(_) => {
				Executor::execute_statements_with_transaction(self, ctx, opt, statements).await
			}
			None => Executor::execute_statements(self, ctx, opt, statements).await,
		}
		// `anyhow_to_types_error`, not a downcast to `err::Error`: that enum
		// holds a handful of residual variants, so a bare layer error
		// (`ExecError::DbEmpty` from `Options::ns_db()`, say) misses and
		// reaches the client as `internal` where it used to be a validation
		// failure. The helper walks the whole registry.
		.map_err(crate::err::anyhow_to_types_error)
	}

	/// Prepare a query to stream its results.
	///
	/// Where [`Self::run`] answers with every statement's result at once, this
	/// sends [`QueryStreamItem`]s into `items` as the executor produces them,
	/// so a caller can forward rows before the query finishes. See the
	/// [`stream`](crate::dbs::QueryStreamItem) module for what a consumer may
	/// assume about them — chiefly that rows are provisional until their
	/// statement's terminal item arrives.
	///
	/// Parsing and the session checks happen here, so their failures are
	/// reported instead of a job. Everything after that is reported by driving
	/// [`QueryStreamJob::run`].
	///
	/// A streaming caller wants [`QueryRequest::cancel`]: a consumer that stops
	/// reading is only noticed at the next send otherwise, so a query in a
	/// phase that emits nothing for a while — a sort, an aggregate — would run
	/// to completion after the client had gone.
	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub fn run_streaming(
		self: &Arc<Self>,
		req: QueryRequest<'_>,
		items: Sender<QueryStreamItem>,
	) -> std::result::Result<QueryStreamJob, TypesError> {
		let QueryRequest {
			source,
			session,
			variables,
			transaction,
			cancel,
		} = req;
		let statements = self.statements_for(source)?;
		let (opt, ctx) = self.setup_query(session, variables, transaction.as_ref(), cancel)?;
		let in_transaction = transaction.is_some();
		// The count is known now because parsing is done, which is what lets a
		// transport announce it before the first result exists.
		let statement_count = statements.len();
		let kvs = Arc::clone(self);
		Ok(QueryStreamJob {
			statement_count,
			run: Box::pin(async move {
				let executed = if in_transaction {
					Executor::execute_statements_streaming_with_transaction(
						&kvs, ctx, opt, statements, items,
					)
					.await
				} else {
					Executor::execute_statements_streaming(&kvs, ctx, opt, statements, items).await
				};
				executed.map_err(crate::err::anyhow_to_types_error)
			}),
		})
	}

	/// Split a [`QuerySource`] into the statements the executor runs.
	///
	/// Parsed SurrealQL stays in surface form: the executor converts each
	/// statement when it is about to run it, rather than converting the batch
	/// before the first one does. GQL has no SurrealQL surface form — it lowers
	/// straight to a plan — so it arrives at the executor already lowered, as
	/// does a source a caller lowered itself.
	fn statements_for(
		&self,
		source: QuerySource<'_>,
	) -> std::result::Result<Vec<TopLevelStatement>, TypesError> {
		fn lowered(plan: LogicalPlan) -> Vec<TopLevelStatement> {
			plan.expressions.into_iter().map(TopLevelStatement::Plan).collect()
		}

		let ast = match source {
			QuerySource::Text {
				text,
				dialect: Dialect::SurrealQl,
			} => syn::parse_with_capabilities(text, &self.capabilities.load(), &self.parser_config)
				.map_err(|e| TypesError::validation(e.to_string(), None))?,
			QuerySource::Text {
				text,
				dialect: Dialect::Gql,
			} => return Ok(lowered(self.parse_gql(text)?)),
			QuerySource::Ast(ast) => ast,
			QuerySource::Plan(plan) => return Ok(lowered(plan)),
		};
		Ok(ast.expressions.into_iter().map(TopLevelStatement::Ast).collect())
	}

	/// Parse and lower GQL query text to the plan the executor runs.
	///
	/// The plan is returned bare rather than in its `PreparedGqlQuery`
	/// wrapper: that type comes from the `gql` crate, so naming it here would
	/// leave the signature unbuildable on a build without the feature.
	#[cfg(feature = "gql")]
	fn parse_gql(&self, text: &str) -> std::result::Result<LogicalPlan, TypesError> {
		crate::gql::parse_with_capabilities(text, &self.capabilities.load(), &self.parser_config)
			.map(|prepared| prepared.0)
			.map_err(|e| TypesError::validation(e.to_string(), None))
	}

	/// The dialect exists on every build because it is chosen from what a
	/// client sent; the front end that would parse it does not.
	#[cfg(not(feature = "gql"))]
	fn parse_gql(&self, _text: &str) -> std::result::Result<LogicalPlan, TypesError> {
		Err(TypesError::configuration(
			"This build does not support GQL queries".to_string(),
			surrealdb_types::ConfigurationError::DialectNotSupported,
		))
	}

	/// The preflight a query runs: the session checks, and the options and
	/// context the statements execute against.
	///
	/// [`Self::execute_import`] does not come through here. It repeats these
	/// checks inline and reports an expired session and an anonymous actor as
	/// `DatastoreError`/`PolicyError` where this reports `TypesError`, so a
	/// check added here does not reach the import path.
	///
	/// A caller-owned transaction is prepared here rather than by the executor.
	/// It carries the session's tenant identity so the emitted
	/// [`crate::observe::TransactionEvent`] names the active namespace,
	/// database and user; and the write-cardinality guard is armed on it
	/// because statements running inside a client-owned transaction (RPC
	/// `begin`, SDK-managed transactions) are subject to the same configured
	/// limit as executor-created statement transactions — wrapping a statement
	/// in an explicit transaction must not bypass the guard.
	fn setup_query(
		&self,
		sess: &Session,
		vars: Option<PublicVariables>,
		tx: Option<&Arc<Transaction>>,
		cancel: Option<CancelHandle>,
	) -> std::result::Result<(Options, FrozenContext), TypesError> {
		// Check if the session has expired
		if sess.expired() {
			return Err(TypesError::not_allowed(
				"The session has expired".to_string(),
				AuthError::SessionExpired,
			));
		}

		// Check if anonymous actors can execute queries when auth is enabled
		// TODO(sgirones): Check this as part of the authorisation layer
		if let Err(e) = self.check_anon(sess) {
			return Err(TypesError::not_allowed(
				format!("Anonymous access not allowed: {e}"),
				AuthError::NotAllowed {
					actor: "anonymous".to_owned(),
					action: "process".to_owned(),
					resource: "query".to_owned(),
				},
			));
		}

		// Create a new query options
		let opt = self.setup_options(sess);

		// Create a default context.
		//
		// `anyhow_to_types_error`, not a downcast to `err::Error`: that enum
		// holds a handful of residual variants, so a bare layer error
		// (`ExecError::DbEmpty` from `Options::ns_db()`, say) misses and
		// reaches the client as `internal` where it used to be a validation
		// failure. The helper walks the whole registry.
		let mut ctx = self.setup_ctx().map_err(crate::err::anyhow_to_types_error)?;

		// Install the external cancellation handle if one was supplied. The
		// executor checks `Context::done` between statements and in iterator
		// hot loops, so flipping the flag mid-query causes the next yield to
		// return `EngineError::QueryCancelled` and the executor's error path
		// finalises the transaction cleanly. Bare-await sites (`SLEEP`)
		// `select!` against the handle's awaitable view. This is a flag rather
		// than the caller dropping the execution future because dropping the
		// future would drop an open transaction with it.
		if let Some(cancel) = cancel {
			ctx.set_cancellation(&cancel);
		}

		// Start an execution context
		ctx.attach_session(sess).map_err(crate::err::into_types_error)?;

		// Store the query variables
		if let Some(vars) = vars {
			ctx.attach_variables(vars.into()).map_err(crate::err::into_types_error)?;
		}

		// Prepare an externally-supplied transaction. See the method docs for
		// why the identity and the guard are applied here.
		if let Some(tx) = tx {
			if let Some(identity) = ctx.tenant_identity() {
				tx.set_tenant_identity(Arc::clone(identity));
			}
			tx.arm_write_keys_limit(self.transaction_max_write_keys());
			ctx.set_transaction(Arc::clone(tx));
		}

		Ok((opt, ctx.freeze()))
	}

	/// Parse and execute an SQL query
	///
	/// ```rust,no_run
	/// use anyhow::Error;
	/// use surrealdb_core::kvs::Datastore;
	/// use surrealdb_core::dbs::Session;
	///
	/// #[tokio::main]
	/// async fn main() -> Result<(),Error> {
	///     let ds = Datastore::new("memory").await?;
	///     let ses = Session::owner();
	///     let ast = "USE NS test DB test; SELECT * FROM person;";
	///     let res = ds.execute(ast, &ses, None).await?;
	///     Ok(())
	/// }
	/// ```
	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn execute(
		&self,
		txt: &str,
		sess: &Session,
		vars: Option<PublicVariables>,
	) -> std::result::Result<Vec<QueryResult>, TypesError> {
		self.run(QueryRequest::new(txt, sess).with_variables(vars)).await
	}

	/// Execute a pre-parsed SQL query
	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn process(
		&self,
		ast: Ast,
		sess: &Session,
		vars: Option<PublicVariables>,
	) -> std::result::Result<Vec<QueryResult>, TypesError> {
		self.run(QueryRequest::new(ast, sess).with_variables(vars)).await
	}

	/// The parser settings an import is read under.
	///
	/// An import is this engine's own export read back, so its depth ceiling
	/// is derived from the deepest value the storage layer accepts
	/// ([`MAX_VALUE_DEPTH`]) rather than from the configured query limits:
	/// whatever was legal to write has to be legal to restore, on any node and
	/// under any configuration. A ceiling below that caps a restore short of
	/// what the writer accepts, and the shortfall shows up only as one failed
	/// statement inside an otherwise successful restore.
	///
	/// The grammar gates are derived from the caller's live capabilities:
	/// import text is a fresh statement at the query boundary, not text this
	/// engine previously rendered, so the experimental-syntax gates apply to
	/// it as they do to any other operator-supplied query.
	fn import_parser_settings(capabilities: &Capabilities) -> ParserSettings {
		ParserSettings {
			files_enabled: capabilities.allows_experimental(&ExperimentalTarget::Files),
			surrealism_enabled: capabilities.allows_experimental(&ExperimentalTarget::Surrealism),
			..ParserSettings::for_value_depth(MAX_VALUE_DEPTH)
		}
	}

	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn execute_import<S>(
		&self,
		sess: &Session,
		vars: Option<PublicVariables>,
		query: S,
	) -> Result<Vec<QueryResult>>
	where
		S: Stream<Item = Result<Bytes>>,
	{
		// Check if the session has expired
		ensure!(!sess.expired(), DatastoreError::ExpiredSession);

		// Check if anonymous actors can execute queries when auth is enabled
		// TODO(sgirones): Check this as part of the authorisation layer
		self.check_anon(sess).map_err(|_| {
			Error::from(PolicyError::NotAllowed {
				actor: "anonymous".to_string(),
				action: "process".to_string(),
				resource: "query".to_string(),
			})
		})?;

		// Create a new query options
		let opt = self.setup_options(sess);

		// Create a default context
		let mut ctx = self.setup_ctx()?;
		// Start an execution context
		ctx.attach_session(sess)?;
		// Store the query variables
		if let Some(vars) = vars {
			ctx.attach_variables(vars.into())?;
		}
		// Process all statements

		let parser_settings = Self::import_parser_settings(&ctx.get_capabilities());
		let mut statements_stream = StatementStream::new_with_settings(parser_settings);
		let mut buffer = BytesMut::new();
		let mut parse_size = 4096;
		let mut bytes_stream = pin!(query);
		let mut complete = false;
		let mut filling = true;

		let stream = futures::stream::poll_fn(move |cx| {
			loop {
				// fill the buffer to at least parse_size when filling is required.
				while filling {
					let bytes = ready!(bytes_stream.as_mut().poll_next(cx));
					let bytes = match bytes {
						Some(Err(e)) => return Poll::Ready(Some(Err(e))),
						Some(Ok(x)) => x,
						None => {
							complete = true;
							filling = false;
							break;
						}
					};

					buffer.extend_from_slice(&bytes);
					filling = buffer.len() < parse_size
				}

				// if we finished streaming we can parse with complete so that the parser can be
				// sure of it's results.
				if complete {
					return match statements_stream.parse_complete(&mut buffer) {
						Err(e) => {
							Poll::Ready(Some(Err(anyhow::Error::new(ParseError::InvalidQuery(e)))))
						}
						Ok(None) => Poll::Ready(None),
						Ok(Some(x)) => Poll::Ready(Some(Ok(x))),
					};
				}

				// otherwise try to parse a single statement.
				match statements_stream.parse_partial(&mut buffer) {
					Err(e) => {
						return Poll::Ready(Some(Err(anyhow::Error::new(
							ParseError::InvalidQuery(e),
						))));
					}
					Ok(Some(x)) => return Poll::Ready(Some(Ok(x))),
					Ok(None) => {
						// Couldn't parse a statement for sure.
						if buffer.len() >= parse_size && parse_size < u32::MAX as usize {
							// the buffer already contained more or equal to parse_size bytes
							// this means we are trying to parse a statement of more then buffer
							// size. so we need to increase the buffer size.
							parse_size = (parse_size + 1).next_power_of_two();
						}
						// start filling the buffer again.
						filling = true;
					}
				}
			}
		});

		Executor::execute_stream(self, Arc::new(ctx), opt, true, stream).await
	}

	/// Evaluates a SQL [`Value`] without checking authenticating config
	/// This is used in very specific cases, where we do not need to check
	/// whether authentication is enabled, or guest access is disabled.
	/// For example, this is used when processing a record access SIGNUP or
	/// SIGNIN clause, which still needs to work without guest access.
	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub(crate) async fn evaluate(
		&self,
		val: &Expr,
		sess: &Session,
		vars: Option<PublicVariables>,
	) -> Result<PublicValue> {
		// Check if the session has expired
		ensure!(!sess.expired(), DatastoreError::ExpiredSession);
		// Create a new memory stack
		let mut stack = TreeStack::new();
		// Create a new query options
		let opt = self.setup_options(sess);
		// Create a default context
		let mut ctx = self.setup_ctx()?;
		// Set the global query timeout
		if let Some(timeout) = self.dynamic_configuration.get_query_timeout() {
			ctx.add_timeout(timeout)?;
		}

		let txn_type = if val.read_only() {
			TransactionType::Read
		} else {
			TransactionType::Write
		};
		// Start a new transaction. Tenant identity is attached up-front so the
		// emitted [`crate::observe::TransactionEvent`] carries the session's
		// namespace, database, user, etc. The write-cardinality guard is
		// armed like any other statement execution: this path evaluates
		// owner-defined record-access clauses (SIGNUP/SIGNIN/AUTHENTICATE)
		// on behalf of unauthenticated callers, so its fan-out must be
		// subject to the same configured limit.
		let txn = self
			.transaction(txn_type)
			.await?
			.with_tenant_identity(Some(Arc::new(crate::observe::TenantIdentity::from(sess))))
			.with_write_keys_limit(self.transaction_max_write_keys())
			.enclose();
		// Store the transaction
		ctx.set_transaction(Arc::clone(&txn));

		// Start an execution context
		ctx.attach_session(sess)?;
		// Store the query variables
		if let Some(vars) = vars {
			ctx.attach_public_variables(vars)?;
		}

		// Freeze the context
		let ctx = ctx.freeze();
		// Compute the value
		let res = stack
			.enter(|stk| crate::legacy::expr_compute(val, stk, &ctx, &opt, None))
			.finish()
			.await
			.catch_return();
		// Store any data
		if res.is_ok() && txn_type == TransactionType::Write {
			// If the compute was successful, then commit if writeable
			txn.commit().await?;
		} else {
			// Cancel if the compute was an error, or if readonly
			txn.cancel().await?;
		};
		// Return result
		convert_value_to_public_value(res?)
	}

	/// Performs a database import from SQL
	///
	/// The text is parsed under [`Self::import_parser_settings`] rather than
	/// the datastore's configured query limits, so that this entry point and
	/// [`Self::execute_import`] restore the same exports. Everything after
	/// parsing is an ordinary query execution.
	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn import(&self, sql: &str, sess: &Session) -> Result<Vec<QueryResult>> {
		// Check if the session has expired
		ensure!(!sess.expired(), DatastoreError::ExpiredSession);
		// Parse the import under the import profile.
		//
		// Classified as the caller's mistake, as `Datastore::execute` classifies
		// the same failure: a truncated or hand-edited dump is a malformed
		// request, and retrying it unchanged cannot succeed. Left to rise as a
		// bare `ParseError` it reaches every transport as an unclassified
		// internal fault, which reads as a server problem worth retrying.
		let ast = syn::parse_with_settings(
			sql.as_bytes(),
			Self::import_parser_settings(&self.capabilities.load()),
			async |parser, stk| parser.parse_query(stk).await,
		)
		.map_err(|e| TypesError::validation(e.to_string(), None))?;
		// Execute the SQL import
		self.process(ast, sess, None).await.map_err(|e| anyhow::anyhow!(e))
	}

	/// Performs a database import from SQL
	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn import_stream<S>(&self, sess: &Session, stream: S) -> Result<Vec<QueryResult>>
	where
		S: Stream<Item = Result<Bytes>>,
	{
		// Check if the session has expired
		ensure!(!sess.expired(), DatastoreError::ExpiredSession);
		// Execute the SQL import
		self.execute_import(sess, None, stream).await
	}

	/// Performs a full database export as SQL
	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn export(
		&self,
		sess: &Session,
		chn: Sender<Vec<u8>>,
	) -> Result<impl Future<Output = Result<()>>> {
		// Create a default export config
		let cfg = surrealdb_rpc::export::Config::default();
		self.export_with_config(sess, chn, cfg).await
	}

	/// Performs a full database export as SQL
	#[instrument(level = "debug", target = "surrealdb::core::kvs::ds", skip_all)]
	pub async fn export_with_config(
		&self,
		sess: &Session,
		chn: Sender<Vec<u8>>,
		cfg: surrealdb_rpc::export::Config,
	) -> Result<impl Future<Output = Result<()>> + 'static> {
		// Check if the session has expired
		ensure!(!sess.expired(), DatastoreError::ExpiredSession);
		// A dump carries the current state of each record and has no grammar for a
		// record's history, so an export cannot answer a request for versions.
		//
		// Refused here rather than inside the returned job, because a transport that
		// streams the export has already sent a success status and opened the body by
		// the time that job runs: a refusal raised in there reaches the caller as an
		// empty dump that claims to have succeeded. Every caller awaits this function
		// before it awaits the job, so this is the last point common to all of them
		// that still precedes a response.
		//
		// Raised as a structured validation error rather than a bare message, so each
		// transport classifies it as the caller's mistake: the request named an option
		// the format has no representation for, and retrying it unchanged cannot
		// succeed.
		if cfg.versions {
			bail!(TypesError::validation(
				"Versioned export is not supported: a dump carries the current state of each \
				 record only"
					.to_owned(),
				surrealdb_types::ValidationError::InvalidRequest,
			));
		}
		// Retrieve the provided NS and DB
		let (ns, db) = crate::iam::check::check_ns_db(sess)?;
		// Create a new readonly transaction
		let txn = self.transaction(Read).await?;
		let batch_size = self.config.datastore.export_batch_size;
		// Return an async export job
		Ok(async move {
			// Process the export
			let res = super::export::export(&txn, &ns, &db, cfg, batch_size, chn).await;
			txn.cancel().await?;
			res
		})
	}

	/// Checks the required permissions level for this session
	#[instrument(level = "trace", target = "surrealdb::core::kvs::ds", skip(self, sess))]
	#[allow(clippy::needless_pass_by_value)] // Public API: ergonomic for callers passing `ResourceKind::X.on_db(ns, db)` inline.
	pub fn check(&self, sess: &Session, action: Action, resource: Resource) -> Result<()> {
		// Check if the session has expired
		ensure!(!sess.expired(), DatastoreError::ExpiredSession);
		// Skip auth for Anonymous users if auth is disabled
		let skip_auth = !self.is_auth_enabled() && sess.au.is_anon();
		if !skip_auth {
			sess.au.is_allowed(action, &resource).map_err(crate::err::Error::from)?;
		}
		// All ok
		Ok(())
	}

	pub fn setup_options(&self, sess: &Session) -> Options {
		Options::new(&self.config.exec)
			.with_ns(sess.ns())
			.with_db(sess.db())
			.with_auth(Arc::clone(&sess.au))
	}

	pub fn setup_ctx(&self) -> Result<Context> {
		let ctx = Context::from_ds(
			self.id,
			self.auth_enabled,
			self.dynamic_configuration.clone(),
			self.dynamic_configuration.get_query_timeout(),
			self.slow_log.clone(),
			self.capabilities.load_full(),
			self.index_stores.clone(),
			self.index_builder.clone(),
			self.sequences.clone(),
			Arc::clone(&self.cache),
			#[cfg(feature = "http")]
			self.http_client.load_full(),
			#[cfg(storage)]
			self.temporary_directory.clone(),
			self.buckets.clone(),
			Arc::clone(&self.config),
			#[cfg(feature = "surrealism")]
			Arc::clone(&self.surrealism_cache),
		)?;
		Ok(ctx)
	}

	/// check for disallowed anonymous users
	pub fn check_anon(&self, sess: &Session) -> Result<(), PolicyError> {
		if self.auth_enabled && sess.au.is_anon() && !self.capabilities.load().allows_guest_access()
		{
			Err(PolicyError::NotAllowed {
				actor: "anonymous".to_string(),
				action: String::new(),
				resource: String::new(),
			})
		} else {
			Ok(())
		}
	}

	/// SECURITY: `USE NS` implicitly creates the namespace when it does
	/// not exist. `DEFINE NAMESPACE` requires `Edit` on `Namespace`@`Root`,
	/// so the same authorization must gate the materialization step in
	/// `USE`. Returns `true` if the caller may proceed with
	/// `get_or_add_ns` — either because the namespace already exists
	/// (in which case the call is a no-op lookup) or because the caller
	/// has the necessary authorization. Returns `false` when the
	/// namespace does not exist *and* the caller lacks permission;
	/// callers that still want to set the session context for a later
	/// authenticated step (the typical pre-signin RPC `USE` pattern)
	/// can do so without triggering creation. See `SECURITY_GUIDE.md`
	/// section 3.
	pub(crate) async fn should_materialize_ns_on_use(
		&self,
		tx: &Transaction,
		auth: &Auth,
		ns: &str,
	) -> Result<bool> {
		if tx.get_ns_by_name(ns, None).await?.is_some() {
			return Ok(true);
		}
		if !self.auth_enabled && auth.is_anon() {
			return Ok(true);
		}
		Ok(auth.is_allowed(Action::Edit, &ResourceKind::Namespace.on_root()).is_ok())
	}

	/// SECURITY: counterpart to [`Self::should_materialize_ns_on_use`]
	/// for the database half of `USE`. Implicit creation requires the
	/// same authorization as `DEFINE DATABASE` (`Edit` on `Database`@`Ns`),
	/// AND the parent namespace must already exist or the caller must
	/// also be authorized to create it — `ensure_ns_db` is
	/// `get_or_add_db_upwards(..., upwards = true)` and will silently
	/// `get_or_add_ns` the parent when it is missing
	/// (`kvs/tx.rs::get_or_add_db_upwards`). Without the second check a
	/// namespace-level Editor on a stale token (the namespace was
	/// dropped after the token was issued) could recreate the parent
	/// namespace as a side effect of `USE NS dropped DB anything`.
	pub(crate) async fn should_materialize_db_on_use(
		&self,
		tx: &Transaction,
		auth: &Auth,
		ns: &str,
		db: &str,
	) -> Result<bool> {
		if tx.get_db_by_name(ns, db, None).await?.is_some() {
			return Ok(true);
		}
		if !self.auth_enabled && auth.is_anon() {
			return Ok(true);
		}
		// Block the upwards-create side effect: if the parent namespace
		// is missing and the caller can't create namespaces, refuse.
		if tx.get_ns_by_name(ns, None).await?.is_none()
			&& auth.is_allowed(Action::Edit, &ResourceKind::Namespace.on_root()).is_err()
		{
			return Ok(false);
		}
		Ok(auth.is_allowed(Action::Edit, &ResourceKind::Database.on_ns(ns)).is_ok())
	}

	pub async fn process_use(
		&self,
		ctx: Option<&dyn crate::catalog::providers::CancellationProbe>,
		session: &mut Session,
		namespace: Option<String>,
		database: Option<String>,
	) -> std::result::Result<QueryResult, TypesError> {
		let new_tx = || async {
			self.transaction(Write).await.map_err(|err| TypesError::internal(err.to_string()))
		};
		let commit_tx = |txn: Transaction| async move {
			txn.commit().await.map_err(|err| TypesError::internal(err.to_string()))
		};

		let query_result = QueryResultBuilder::started_now();
		// SECURITY: `process_use` may be called before the caller has
		// authenticated (e.g. SDKs that call `use` before `signin`). To
		// preserve that pattern without re-opening the bypass that this
		// guard closes, we set the session context but only commit
		// implicit `DEFINE NAMESPACE` / `DEFINE DATABASE`-equivalent
		// creation when the caller has authorization for it. Callers
		// without permission end up with a session that targets a
		// resource that may not exist; downstream operations surface a
		// clean `NsNotFound` / `DbNotFound` rather than a silently
		// auto-created namespace they should not have been able to
		// create. See `SECURITY_GUIDE.md` section 3.
		let map_internal = |err: anyhow::Error| TypesError::internal(err.to_string());
		// SECURITY (GHSA-2v9j): tenant-boundary gate, mirroring the SurrealQL
		// `USE` statement handler (`dbs::executor`) and the RPC `use` handler
		// (`rpc::protocol::yuse`). This path (`process_use`) serves the embedded
		// SDK `Command::Use` and the PostgreSQL wire; the WS/HTTP/gRPC RPC `use`
		// method carries its own copy of this gate in `yuse`. An authenticated
		// Database-, Namespace- or Record-level principal must be verified as
		// authorized for the target namespace/database before the session is
		// pivoted, or it could switch into a foreign tenant and reach any table
		// there with satisfiable PERMISSIONS. The authenticated Auth level is the
		// source of truth; a switch that changes only one of ns/db keeps the
		// other from the current session. Root and anonymous (`Level::No`, e.g.
		// `use` before `signin`) principals are unrestricted by `can_access_ns_db`,
		// preserving the pre-signin `use` pattern.
		{
			let target_ns = namespace.as_deref().or(session.ns.as_deref());
			let target_db = database.as_deref().or(session.db.as_deref());
			if let Some(ns_name) = target_ns {
				let db_name = target_db.unwrap_or_default();
				if !session.au.can_access_ns_db(ns_name, db_name) {
					let err = if session.au.level().ns() == Some(ns_name) {
						ExecError::DbNotAllowed {
							db: db_name.to_owned(),
						}
					} else {
						ExecError::NsNotAllowed {
							ns: ns_name.to_owned(),
						}
					};
					return Err(TypesError::not_allowed(err.to_string(), None));
				}
			}
		}
		match (namespace, database) {
			(Some(ns), Some(db)) => {
				let tx = new_tx().await?;
				let create_ns = self
					.should_materialize_ns_on_use(&tx, &session.au, &ns)
					.await
					.map_err(map_internal)?;
				let create_db = create_ns
					&& self
						.should_materialize_db_on_use(&tx, &session.au, &ns, &db)
						.await
						.map_err(map_internal)?;
				if create_db {
					tx.ensure_ns_db(ctx, &ns, &db).await.map_err(map_internal)?;
					commit_tx(tx).await?;
				} else if create_ns {
					tx.get_or_add_ns(ctx, &ns).await.map_err(map_internal)?;
					commit_tx(tx).await?;
				} else {
					let _ = tx.cancel().await;
				}
				session.ns = Some(ns);
				session.db = Some(db);
			}
			(Some(ns), None) => {
				let tx = new_tx().await?;
				let create_ns = self
					.should_materialize_ns_on_use(&tx, &session.au, &ns)
					.await
					.map_err(map_internal)?;
				if create_ns {
					tx.get_or_add_ns(ctx, &ns).await.map_err(map_internal)?;
					commit_tx(tx).await?;
				} else {
					let _ = tx.cancel().await;
				}
				session.ns = Some(ns);
			}
			(None, Some(db)) => {
				let Some(ns) = session.ns.clone() else {
					return Err(TypesError::validation(
						"Cannot use database without namespace".to_string(),
						None,
					));
				};
				let tx = new_tx().await?;
				let create_db = self
					.should_materialize_db_on_use(&tx, &session.au, &ns, &db)
					.await
					.map_err(map_internal)?;
				if create_db {
					tx.ensure_ns_db(ctx, &ns, &db).await.map_err(map_internal)?;
					commit_tx(tx).await?;
				} else {
					let _ = tx.cancel().await;
				}
				session.db = Some(db);
			}
			// An empty `USE` asks for the configured default, not for the
			// session to be cleared. A session that has already selected a
			// namespace — from a token, say — keeps it, so this only ever fills
			// in what is missing.
			(None, None) if session.ns.is_none() => {
				let tx = new_tx().await?;
				let default = match tx.get_default_config().await {
					Ok(config) => config.map(|c| (c.namespace.clone(), c.database.clone())),
					Err(e) => {
						let _ = tx.cancel().await;
						return Err(map_internal(e));
					}
				};

				// The default names a namespace and database a fresh datastore
				// may not have materialised yet. Creating them is gated on the
				// same authorization an explicit `DEFINE NAMESPACE` /
				// `DEFINE DATABASE` needs, as the arms above are: a caller
				// without it still gets the selection, and a later operation
				// reports a clean `NsNotFound` rather than silently having
				// created what it could not have defined. See
				// `SECURITY_GUIDE.md` section 3.
				if let Some((Some(ns), db)) = default {
					// SECURITY (GHSA-2v9j): the default names a namespace/database
					// to a scoped principal just as an explicit `USE` would, so gate
					// the resolved default the same way before selecting or creating
					// it. Root and anonymous principals are unrestricted by
					// `can_access_ns_db`; a scoped principal is confined to its own
					// namespace/database. Mirrors the executor's `USE DEFAULT` path.
					if !session.au.can_access_ns_db(&ns, db.as_deref().unwrap_or_default()) {
						let _ = tx.cancel().await;
						let err = if session.au.level().ns() == Some(ns.as_str()) {
							ExecError::DbNotAllowed {
								db: db.clone().unwrap_or_default(),
							}
						} else {
							ExecError::NsNotAllowed {
								ns: ns.clone(),
							}
						};
						return Err(TypesError::not_allowed(err.to_string(), None));
					}
					let create_ns = self
						.should_materialize_ns_on_use(&tx, &session.au, &ns)
						.await
						.map_err(map_internal)?;
					if create_ns && let Err(e) = tx.get_or_add_ns(ctx, &ns).await {
						let _ = tx.cancel().await;
						return Err(map_internal(e));
					}
					if let Some(db) = db {
						let create_db = create_ns
							&& self
								.should_materialize_db_on_use(&tx, &session.au, &ns, &db)
								.await
								.map_err(map_internal)?;
						if create_db && let Err(e) = tx.ensure_ns_db(ctx, &ns, &db).await {
							let _ = tx.cancel().await;
							return Err(map_internal(e));
						}
						session.db = Some(db);
					}
					session.ns = Some(ns);
				}

				commit_tx(tx).await?;
			}
			(None, None) => {}
		}

		let value = PublicValue::from_t(object! {
			namespace: session.ns.clone(),
			database: session.db.clone(),
		});

		Ok(query_result.finish_with_result(Ok(value)))
	}

	/// Get a db model by name.
	///
	/// TODO: This should not be public, but it is used by callers outside the
	/// `surrealdb-core` crate (the SDK's local engine and the server's ML route).
	pub async fn get_db_model(
		&self,
		ns: &str,
		db: &str,
		model_name: &str,
		model_version: &str,
	) -> Result<Option<Arc<crate::catalog::StoredMlModelDefinition>>> {
		let tx = self.transaction(Read).await?;
		let db = tx.expect_db_by_name(ns, db).await?;
		let model = tx
			.get_db_model(db.namespace_id, db.database_id, model_name, model_version, None)
			.await?;
		tx.cancel().await?;
		Ok(model.map(|m| Arc::new(m.to_stored())))
	}

	/// Invoke an API handler.
	///
	/// TODO: This should not need to be public, but it is used by the server's
	/// HTTP API route (outside the `surrealdb-core` crate).
	pub async fn invoke_api_handler(
		&self,
		ns: &str,
		db: &str,
		path: &str,
		session: &Session,
		mut req: ApiRequest,
	) -> Result<ApiResponse> {
		// Enforce the tenant boundary before resolving or dispatching anything.
		// The namespace/database come from caller-controlled input (the
		// `/api/:ns/:db/:endpoint` URL path) and the HTTP route has already
		// overwritten the session's selected ns/db with them, so the
		// authenticated level is the only trustworthy scope. A principal
		// authenticated for one tenant must not be able to invoke another
		// tenant's custom API — whose handler runs with permissions disabled
		// (GHSA-848m-r628-vrxw).
		if !session.au.can_access_ns_db(ns, db) {
			debug!(
				request_id = %req.request_id,
				"Custom API request denied: URL namespace/database is outside the authenticated session scope"
			);
			return Ok(ApiResponse::from_error(ApiError::PermissionDenied, req.request_id.clone()));
		}

		let tx = Arc::new(self.transaction(TransactionType::Write).await?);
		// Custom API handlers evaluate owner-defined expressions on behalf of
		// external callers — statement execution in everything but name — so
		// the write-cardinality guard applies exactly as it does to executor
		// statements and explicit client-owned transactions.
		tx.arm_write_keys_limit(self.transaction_max_write_keys());

		// `tx` is open and writeable from here until the commit/cancel below, so
		// every fallible step in between cancels before returning. A bare `?`
		// would drop the transaction without committing or cancelling it,
		// tripping `Transactor::drop`'s "a transaction was dropped without being
		// committed or cancelled" error and leaving it to be reaped rather than
		// rolled back promptly. `catch!` is the cancel-then-propagate form.
		let db = catch!(tx, tx.ensure_ns_db(None, ns, db).await);

		let segments: Vec<&str> = path.split('/').filter(|x| !x.is_empty()).collect();

		// Routes on the stored definitions and compiles only the one that
		// handles this request: this transaction is opened per request, so the
		// compiled catalog cache is always cold, and compiling the whole list
		// would parse every handler body in the database to dispatch one.
		let routed = catch!(
			tx,
			tx.find_db_api(db.namespace_id, db.database_id, &segments, req.method).await
		);
		let res = match routed {
			Some((api, params)) => {
				let api = &api;
				debug!(
					request_id = %req.request_id,
					path = %path,
					"API definition found, dispatching to process_api_request"
				);
				req.params = catch!(tx, params.try_into());

				let opt = self.setup_options(session);

				let mut ctx = catch!(tx, self.setup_ctx());
				ctx.set_transaction(Arc::clone(&tx));
				// Not `catch!`: like `try_into` above, this error needs
				// converting into the function's error type.
				if let Err(e) = ctx.attach_session(session) {
					let _ = tx.cancel().await;
					return Err(e.into());
				}
				let ctx = &ctx.freeze();

				process_api_request(ctx, &opt, api, req).await
			}
			None => {
				trace!(
					request_id = %req.request_id,
					path = %path,
					"No API definition found for path"
				);
				tx.cancel().await?;
				return Ok(ApiResponse::from_error(ApiError::NotFound, req.request_id.clone()));
			}
		};

		// Handle committing or cancelling the transaction
		if res.is_ok() {
			tx.commit().await?;
		} else {
			tx.cancel().await?;
		}

		res
	}

	pub async fn put_ml_model(
		&self,
		session: &Session,
		name: &str,
		version: &str,
		description: &str,
		data: Vec<u8>,
	) -> Result<()> {
		let ns = session.ns.as_ref().context("Namespace is required")?;
		let db = session.db.as_ref().context("Database is required")?;

		self.check(session, Action::Edit, ResourceKind::Model.on_db(ns, db))?;

		// Calculate the hash of the model file
		let hash = crate::obs::hash(&data);
		// Calculate the path of the model file
		let path = get_model_path(ns, db, name, version, &hash);
		// Insert the file data in to the store
		crate::obs::put(&path, data).await?;
		// Insert the model in to the database
		let model = DefineModelStatement {
			name: name.to_string().into(),
			version: version.to_string().into(),
			comment: Expr::Literal(Literal::String(description.into())),
			hash: hash.into(),
			kind: Default::default(),
			permissions: Default::default(),
		};

		let q = LogicalPlan {
			expressions: vec![TopLevelExpr::Expr(Expr::Define(Box::new(DefineStatement::Model(
				model,
			))))],
		};

		self.run(QueryRequest::new(q, session)).await.map_err(|e| anyhow::anyhow!(e))?;

		Ok(())
	}

	/// The per-layer configuration this datastore was built with. Cheap to
	/// clone; the inner handle is an `Arc`. Crate-internal: these are operator
	/// knobs, not API — callers outside core take the specific settings they
	/// need, as the server does through [`Self::parser_config`].
	pub(crate) fn config(&self) -> Arc<RuntimeConfig> {
		Arc::clone(&self.config)
	}

	/// The parser depth limits this datastore parses query text with.
	///
	/// Transports that decode request bodies (RPC, WebSocket, export) apply the
	/// same limits, so they read them from here rather than from their own
	/// defaults. Cheap to clone; the inner handle is an `Arc`.
	pub fn parser_config(&self) -> Arc<ParserConfig> {
		Arc::clone(&self.parser_config)
	}

	/// Retrieve (or generate and cache) the GraphQL schema for the namespace
	/// and database selected on `session`. Backed by the datastore-wide schema
	/// cache so every transport (HTTP `/graphql`, WebSocket subscriptions, the
	/// `graphql` RPC method, the MCP `graphql` tool) shares one set of compiled
	/// schemas and a single DDL-driven invalidation path.
	#[cfg(all(feature = "graphql", not(target_family = "wasm")))]
	pub async fn graphql_schema(
		self: &Arc<Self>,
		session: &Session,
	) -> Result<async_graphql::dynamic::Schema, crate::graphql::GraphqlError> {
		self.graphql_schema_cache.get_schema(self, session).await
	}

	#[cfg(feature = "http")]
	pub fn http_client(&self) -> Arc<HttpClient> {
		self.http_client.load_full()
	}

	/// Builds a [`NodeEndpointResolver`] backed by this datastore's catalog. Used by the
	/// builder to hand a resolver to clustered message brokers after the datastore is
	/// fully constructed.
	///
	/// Only available on non-WASM targets: the underlying transaction types are not
	/// `Send + Sync` under the WASM single-threaded model, and cross-node delivery
	/// (the only consumer) doesn't apply to in-browser datastores.
	#[cfg(not(target_family = "wasm"))]
	pub(crate) fn endpoint_resolver(&self) -> Arc<dyn crate::dbs::NodeEndpointResolver> {
		Arc::new(CatalogNodeEndpointResolver {
			transaction_factory: self.transaction_factory.clone(),
			sequences: self.sequences.clone(),
		})
	}
}

/// Catalog-backed [`NodeEndpointResolver`] handed to clustered brokers post-construction.
///
/// Holds clones of the transaction factory and sequences (both cheap `Arc`-based clones) so
/// it can open read transactions independently of the [`Datastore`] struct, avoiding any
/// reference cycle between the broker and the datastore.
#[cfg(not(target_family = "wasm"))]
#[derive(Clone)]
struct CatalogNodeEndpointResolver {
	transaction_factory: TransactionFactory,
	sequences: Sequences,
}

#[cfg(not(target_family = "wasm"))]
impl std::fmt::Debug for CatalogNodeEndpointResolver {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		f.debug_struct("CatalogNodeEndpointResolver").finish_non_exhaustive()
	}
}

#[cfg(not(target_family = "wasm"))]
impl crate::dbs::NodeEndpointResolver for CatalogNodeEndpointResolver {
	fn resolve(
		&self,
		target_node: [u8; 16],
	) -> std::pin::Pin<Box<dyn std::future::Future<Output = Option<String>> + Send + '_>> {
		Box::pin(async move {
			let uuid = Uuid::from_bytes(target_node);
			let txn =
				self.transaction_factory.transaction(Read, self.sequences.clone()).await.ok()?;
			let key = NodeKey {
				nd: uuid,
			};
			let node: Option<Node> = txn.get_key(&key, None).await.ok()?;
			let _ = txn.cancel().await;
			node.and_then(|n| n.http_endpoint)
		})
	}
}

pub(crate) fn define_user_statement_new_with_password(
	base: Base,
	user: String,
	pass: &str,
	role: String,
) -> DefineUserStatement {
	DefineUserStatement {
		kind: DefineKind::Default,
		base,
		name: Expr::Idiom(Idiom::field(user)),
		hash: crate::iam::hash_password(pass),
		code: Alphanumeric.sample_string(&mut rand::rng(), 128),
		roles: vec![role],
		duration: UserDuration::default(),
		comment: Expr::Literal(Literal::None),
		scram: Some(ScramCredential::generate(pass)),
	}
}

#[cfg(test)]
mod test {
	use std::collections::BTreeMap;
	use std::future::pending;

	use surrealdb_strand::TableName;

	use super::*;
	use crate::catalog::providers::{
		CatalogProvider, DatabaseProvider, NamespaceProvider, TableProvider,
	};
	use crate::iam::verify::verify_root_creds;
	use crate::key::schema::{DocKeyPrefix, DocLookupPrefix, IndexCountKey, IndexCountPrefix};
	use crate::kvs::test_support::{WriteTxSizeObserver, cleanup_sizes};
	use crate::kvs::testing::{
		NonRetryableErrorSite, RetryableConflictSite, inject_non_retryable_error,
		inject_non_retryable_errors, inject_retryable_conflict, inject_retryable_conflicts,
		retryable_conflict_count,
	};
	use crate::types::{PublicValue, PublicVariables};

	async fn new_index_compaction_test_ds() -> Result<(Arc<Datastore>, Session)> {
		new_index_compaction_test_ds_with_config(ConfigMap::empty()).await
	}

	/// [`new_index_compaction_test_ds`], with one configuration key set.
	async fn new_index_compaction_test_ds_with(
		key: &str,
		value: &str,
	) -> Result<(Arc<Datastore>, Session)> {
		new_index_compaction_test_ds_with_config(ConfigMap::empty().with_key_value(key, value))
			.await
	}

	async fn new_index_compaction_test_ds_with_config(
		config: ConfigMap,
	) -> Result<(Arc<Datastore>, Session)> {
		// These tests decide when compaction runs and observe the wake-up that
		// drives it. `CommitTriggers::index_compaction` is a `notify_one`, so a
		// background compactor would take the permit a test is waiting on.
		let ds = Datastore::builder()
			.without_maintenance_tasks()
			.with_config(config)
			.build_with_path("memory")
			.await?;
		let session = Session::owner().with_ns("test").with_db("test");
		let txn = ds.transaction(Write).await?;
		txn.ensure_ns_db(None, "test", "test").await?;
		txn.commit().await?;
		Ok((ds, session))
	}

	async fn execute_all(ds: &Datastore, session: &Session, sql: &str) -> Result<()> {
		for result in ds.execute(sql, session, None).await? {
			result.result?;
		}
		Ok(())
	}

	#[tokio::test]
	async fn record_auth_is_scoped_to_its_ns_db() -> Result<()> {
		// A record-scoped principal is only authorized for the namespace and
		// database it authenticated against. If the session context drifts to
		// another namespace or database (via a USE statement or connection
		// headers), every document operation must be rejected — even when the
		// target table's PERMISSIONS clauses would otherwise allow the
		// operation for record users.
		let ds = Datastore::new("memory").await?;
		let txn = ds.transaction(Write).await?;
		txn.ensure_ns_db(None, "first", "first").await?;
		txn.ensure_ns_db(None, "first", "other").await?;
		txn.ensure_ns_db(None, "second", "second").await?;
		txn.commit().await?;
		// Victim data in `second/second` with fully permissive permissions
		let owner = Session::owner().with_ns("second").with_db("second");
		execute_all(
			&ds,
			&owner,
			"DEFINE TABLE thing SCHEMALESS PERMISSIONS FULL; CREATE thing:1 SET secret = 'v';",
		)
		.await?;
		// A record principal authenticated against `first/first`, whose
		// session context has drifted to `second/second`
		let mut rec = Session::for_record(
			"first",
			"first",
			"user",
			surrealdb_types::Value::RecordId(surrealdb_types::RecordId::new("user", "tester")),
		);
		rec.ns = Some("second".to_owned());
		rec.db = Some("second".to_owned());
		// Every write into the drifted scope must be rejected
		for query in [
			"CREATE thing:2 SET secret = 'w'",
			"UPDATE thing:1 SET secret = 'w'",
			"UPSERT thing:1 SET secret = 'w'",
			"DELETE thing:1",
			"INSERT INTO thing { id: thing:3, secret: 'w' }",
		] {
			let err = execute_all(&ds, &rec, query)
				.await
				.expect_err(&format!("record user expected to be denied: {query}"));
			assert!(
				err.to_string().contains("namespace"),
				"expected a namespace authorization error for {query}, got: {err}"
			);
		}
		// Reads from the drifted scope must be rejected as well
		let err = execute_all(&ds, &rec, "SELECT * FROM thing")
			.await
			.expect_err("record user expected to be denied: SELECT");
		assert!(
			err.to_string().contains("namespace"),
			"expected a namespace authorization error for SELECT, got: {err}"
		);
		// A drift within the same namespace but to a different database must
		// also be rejected
		let owner = Session::owner().with_ns("first").with_db("other");
		execute_all(
			&ds,
			&owner,
			"DEFINE TABLE thing SCHEMALESS PERMISSIONS FULL; CREATE thing:1 SET secret = 'v';",
		)
		.await?;
		let mut rec = Session::for_record(
			"first",
			"first",
			"user",
			surrealdb_types::Value::RecordId(surrealdb_types::RecordId::new("user", "tester")),
		);
		rec.db = Some("other".to_owned());
		let err = execute_all(&ds, &rec, "UPDATE thing:1 SET secret = 'w'")
			.await
			.expect_err("record user expected to be denied in a sibling database");
		assert!(
			err.to_string().contains("database"),
			"expected a database authorization error, got: {err}"
		);
		// The victim data must be unchanged
		let owner = Session::owner().with_ns("second").with_db("second");
		let mut res = ds.execute("SELECT VALUE secret FROM thing", &owner, None).await?;
		let val = res.remove(0).result?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array!["v"]),
			"victim data was modified by an out-of-scope record user"
		);
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_is_available_without_the_experimental_capability() -> Result<()> {
		let ds = Datastore::new("memory").await?;
		let ses = Session::owner().with_ns("test").with_db("test");
		// GQL is on by default: it must not be refused as an experimental
		// capability (any other error — e.g. missing namespace — is irrelevant).
		if let Err(err) =
			ds.run(QueryRequest::new(QuerySource::gql("MATCH (n:person) RETURN n"), &ses)).await
		{
			assert!(
				!err.to_string().contains("Experimental capability `gql` is not enabled"),
				"GQL was still gated: {err}"
			);
		}
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_text_parses_lowers_and_executes() -> Result<()> {
		use crate::dbs::capabilities::Targets;
		let ds = Datastore::builder()
			.with_capabilities(Capabilities::all().with_experimental(Targets::All))
			.build_with_path("memory")
			.await?;
		let ses = Session::owner().with_ns("test").with_db("test");
		let txn = ds.transaction(Write).await?;
		txn.ensure_ns_db(None, "test", "test").await?;
		txn.commit().await?;
		execute_all(&ds, &ses, "CREATE person:tobie SET name = 'Tobie';").await?;
		// A valid GQL query parses, lowers, and executes through the
		// SurrealQL pipeline
		let mut res = ds
			.run(QueryRequest::new(
				QuerySource::gql("MATCH (n:person) RETURN n.name AS name"),
				&ses,
			))
			.await?;
		assert_eq!(res.len(), 1);
		let val = res.remove(0).result?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { name: "Tobie" }]));
		// An invalid GQL query reports a parse error rather than a
		// capability error
		let err =
			ds.run(QueryRequest::new(QuerySource::gql("MATCH RETURN"), &ses)).await.unwrap_err();
		assert!(!err.to_string().contains("experimental"), "unexpected error: {err}");
		Ok(())
	}

	/// `set_capabilities` must take effect on an already-built datastore without
	/// a rebuild: a capability-gated operation (scripting) flips from denied to
	/// allowed after a live swap, proving the executor observes the new
	/// `ArcSwap` snapshot.
	#[cfg(feature = "scripting")]
	#[tokio::test]
	async fn set_capabilities_swaps_live() -> Result<()> {
		let ds = Datastore::new("memory").await?;
		let ses = Session::owner().with_ns("test").with_db("test");
		let txn = ds.transaction(Write).await?;
		txn.ensure_ns_db(None, "test", "test").await?;
		txn.commit().await?;

		// Default capabilities: scripting functions are denied.
		let mut before = ds.execute("RETURN function() { return 1; }", &ses, None).await?;
		assert!(
			before.remove(0).result.is_err(),
			"scripting should be denied under default capabilities"
		);

		// Swap in capabilities that enable scripting — no rebuild, same datastore.
		ds.set_capabilities(Capabilities::all())?;

		// The same datastore now permits scripting, proving the executor
		// observes the new `ArcSwap` snapshot.
		let mut after = ds.execute("RETURN function() { return 1; }", &ses, None).await?;
		assert!(
			after.remove(0).result.is_ok(),
			"scripting should be allowed after the capability swap"
		);
		Ok(())
	}

	/// A datastore with the `gql` capability and an initialised `test/test`
	/// namespace/database, for the GQL mutation tests.
	#[cfg(feature = "gql")]
	async fn gql_test_ds() -> Result<(Arc<Datastore>, Session)> {
		use crate::dbs::capabilities::Targets;
		let ds = Datastore::builder()
			.with_capabilities(Capabilities::all().with_experimental(Targets::All))
			.build_with_path("memory")
			.await?;
		let ses = Session::owner().with_ns("test").with_db("test");
		let txn = ds.transaction(Write).await?;
		txn.ensure_ns_db(None, "test", "test").await?;
		txn.commit().await?;
		Ok((ds, ses))
	}

	/// Run one GQL query, asserting a single statement result, and return it.
	#[cfg(feature = "gql")]
	async fn run_gql(ds: &Datastore, ses: &Session, query: &str) -> Result<PublicValue> {
		let mut res = ds.run(QueryRequest::new(QuerySource::gql(query), ses)).await?;
		assert_eq!(res.len(), 1, "expected one result for {query:?}");
		Ok(res.remove(0).result?)
	}

	/// Run one GQL query expecting failure (parse/lowering rejection or a
	/// per-statement execution error), returning the rendered error.
	#[cfg(feature = "gql")]
	async fn run_gql_err(ds: &Datastore, ses: &Session, query: &str) -> String {
		match ds.run(QueryRequest::new(QuerySource::gql(query), ses)).await {
			Ok(mut res) => match res.remove(0).result {
				Ok(value) => panic!("expected {query:?} to fail, got {value:?}"),
				Err(e) => e.to_string(),
			},
			Err(e) => e.to_string(),
		}
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_set_updates_and_returns_after_image() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A', age = 30;").await?;
		// SET returns the post-mutation value.
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (n:person) WHERE n.name = 'A' SET n.age = 31 RETURN n.age AS age",
		)
		.await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { age: 31 }]));
		// And it persisted.
		let val = run_gql(&ds, &ses, "MATCH (n:person) RETURN n.age AS age").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { age: 31 }]));
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_remove_unsets_field_and_returns_empty() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A', age = 30;").await?;
		// A mutation-only query returns an empty array.
		let val = run_gql(&ds, &ses, "MATCH (n:person) REMOVE n.age").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![]));
		// The field is gone: a filter on the old value no longer matches.
		let val =
			run_gql(&ds, &ses, "MATCH (n:person) WHERE n.age = 30 RETURN n.name AS name").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![]));
		// The record itself survives.
		let val = run_gql(&ds, &ses, "MATCH (n:person) RETURN n.name AS name").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { name: "A" }]));
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_delete_nodetach_errors_with_edges_then_detach_succeeds() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(
			&ds,
			&ses,
			"CREATE person:1 SET name = 'A'; CREATE person:2 SET name = 'B'; \
			RELATE person:1->knows->person:2;",
		)
		.await?;
		// NODETACH (the default) on a node that still has edges errors.
		let err = run_gql_err(&ds, &ses, "MATCH (n:person) WHERE n.name = 'A' DELETE n").await;
		assert!(err.contains("connected edges"), "{err}");
		// The failed delete rolled back: A is still present.
		let val =
			run_gql(&ds, &ses, "MATCH (n:person) RETURN n.name AS name ORDER BY name").await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![
				object! { name: "A" },
				object! { name: "B" }
			])
		);
		// DETACH DELETE removes A and its edge.
		let val = run_gql(&ds, &ses, "MATCH (n:person) WHERE n.name = 'A' DETACH DELETE n").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![]));
		let val =
			run_gql(&ds, &ses, "MATCH (n:person) RETURN n.name AS name ORDER BY name").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { name: "B" }]));
		// The knows edge is gone too.
		let val =
			run_gql(&ds, &ses, "MATCH (a:person)-[:knows]->(b:person) RETURN a.name AS a").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![]));
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_insert_node_and_edge() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		// A leading INSERT (no MATCH) creates a node exactly once.
		let val = run_gql(&ds, &ses, "INSERT (p:person {name: 'A'})").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![]));
		run_gql(&ds, &ses, "INSERT (p:person {name: 'B'})").await?;
		let val =
			run_gql(&ds, &ses, "MATCH (n:person) RETURN n.name AS name ORDER BY name").await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![
				object! { name: "A" },
				object! { name: "B" }
			])
		);
		// INSERT an edge between two MATCH-bound nodes.
		run_gql(
			&ds,
			&ses,
			"MATCH (a:person WHERE a.name = 'A') MATCH (b:person WHERE b.name = 'B') \
			INSERT (a)-[:knows]->(b)",
		)
		.await?;
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (a:person)-[:knows]->(b:person) RETURN a.name AS a, b.name AS b",
		)
		.await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { a: "A", b: "B" }]));
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_label_mutation_rejected() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A';").await?;
		let err = run_gql_err(&ds, &ses, "MATCH (n:person) SET n:Archived").await;
		assert!(err.contains("Label mutation is not supported"), "{err}");
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_set_all_properties_replaces_and_multi_item() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A', age = 30, city = 'L';").await?;
		// `SET n = {…}` replaces ALL user properties (age is dropped).
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (n:person) SET n = {name: 'A2', city: 'X'} RETURN n.name AS name, n.city AS city",
		)
		.await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![object! { name: "A2", city: "X" }])
		);
		// The dropped `age` no longer matches.
		let val =
			run_gql(&ds, &ses, "MATCH (n:person) WHERE n.age = 30 RETURN n.name AS name").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![]));
		// Multi-item SET on distinct properties.
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (n:person) SET n.age = 5, n.city = 'Z' RETURN n.age AS age, n.city AS city",
		)
		.await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { age: 5, city: "Z" }]));
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_multi_statement_set_last_wins() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A', age = 1;").await?;
		// Two SET statements in one query: the second sees the first's write.
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (n:person) SET n.age = 5 SET n.age = n.age + 1 RETURN n.age AS age",
		)
		.await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { age: 6 }]));
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_edge_set_remove_delete() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(
			&ds,
			&ses,
			"CREATE person:1 SET name = 'A'; CREATE person:2 SET name = 'B'; \
			RELATE person:1->knows->person:2 SET since = 2020;",
		)
		.await?;
		// SET a property on a bound edge.
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (a:person)-[k:knows]->(b:person) SET k.since = 2099 RETURN k.since AS since",
		)
		.await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { since: 2099 }]));
		// DELETE a bound edge (NODETACH default is fine: an edge has no sub-edges).
		let val = run_gql(&ds, &ses, "MATCH (a:person)-[k:knows]->(b:person) DELETE k").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![]));
		let val =
			run_gql(&ds, &ses, "MATCH (a:person)-[:knows]->(b:person) RETURN a.name AS a").await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![]));
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_fanout_set_is_consistent_per_row() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(
			&ds,
			&ses,
			"CREATE person:1 SET name = 'A', age = 30; CREATE person:2 SET name = 'B'; \
			CREATE person:3 SET name = 'C'; RELATE person:1->knows->person:2; \
			RELATE person:1->knows->person:3;",
		)
		.await?;
		// `a` fans out to two rows; SET a.age = 7 must show a consistent AFTER image
		// on both rows (the §1 fix — no stale pre-mutation binding on a duplicate).
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (a:person)-[:knows]->(b:person) WHERE a.name = 'A' SET a.age = 7 \
			RETURN a.age AS age, b.name AS b ORDER BY b",
		)
		.await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![
				object! { age: 7, b: "B" },
				object! { age: 7, b: "C" }
			])
		);
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_detach_delete_nulls_cascaded_edge_binding() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(
			&ds,
			&ses,
			"CREATE person:1 SET name = 'A'; CREATE person:2 SET name = 'B'; \
			RELATE person:1->knows->person:2 SET since = 2020;",
		)
		.await?;
		// DETACH DELETE on `a` cascades the `k` edge; the §3 fix nulls `k` in the
		// RETURN rather than surfacing the stale (deleted) edge.
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (a:person)-[k:knows]->(b:person) WHERE a.name = 'A' DETACH DELETE a \
			RETURN a AS a, k AS k, b.name AS b",
		)
		.await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![object! {
				a: PublicValue::Null,
				k: PublicValue::Null,
				b: "B"
			}])
		);
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_insert_left_edge_chain_and_repeated_anon() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A'; CREATE person:2 SET name = 'B';")
			.await?;
		// A left-pointing INSERT edge relates b -> a.
		run_gql(
			&ds,
			&ses,
			"MATCH (a:person WHERE a.name = 'A') MATCH (b:person WHERE b.name = 'B') \
			INSERT (a)<-[:knows]-(b)",
		)
		.await?;
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (x:person)-[:knows]->(y:person) RETURN x.name AS x, y.name AS y",
		)
		.await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { x: "B", y: "A" }]));
		// A chained INSERT creates three new nodes and two edges.
		run_gql(
			&ds,
			&ses,
			"INSERT (x:item {n: 1})-[:link]->(y:item {n: 2})-[:link]->(z:item {n: 3})",
		)
		.await?;
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (a:item)-[:link]->(b:item) RETURN a.n AS a, b.n AS b ORDER BY a",
		)
		.await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![
				object! { a: 1, b: 2 },
				object! { a: 2, b: 3 }
			])
		);
		// Repeated anonymous nodes in one INSERT create distinct records.
		run_gql(&ds, &ses, "INSERT (:tag {v: 1}), (:tag {v: 1})").await?;
		let val = run_gql(&ds, &ses, "MATCH (t:tag) RETURN t.v AS v ORDER BY v").await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![object! { v: 1 }, object! { v: 1 }])
		);
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_mutation_rejection_ledger() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		// Each lowers (or parses) to a precise rejection. No data needed — these
		// fail before execution.
		let cases: &[(&str, &str)] = &[
			// Mutating a variable not bound by the read body.
			("MATCH (n:person) SET x.age = 1", "Unknown variable"),
			// Mutating a path variable (a composite, not a record).
			("MATCH p = (a:person)-[:knows]->(b:person) SET p.x = 1", "group or path variable"),
			// `SET a = {…}` setting a reserved key.
			("MATCH (n:person) SET n = {id: 1}", "reserved `id` key"),
			// Per-property SET of a reserved edge endpoint (the native write path
			// would otherwise silently re-stamp `out`, so it is rejected up front).
			("MATCH (a:person)-[k:knows]->(b:person) SET k.out = 1", "reserved `out` key"),
			// Label mutation via REMOVE.
			("MATCH (n:person) REMOVE n:Foo", "Label mutation is not supported"),
			// INSERT re-declaring a MATCH-bound variable as a new (labelled) node.
			("MATCH (a:person) INSERT (a:thing)", "already bound"),
			// INSERT node that is neither labelled nor a bound-variable reference.
			("INSERT (x)", "must declare a label"),
			// Undirected INSERT edge.
			("INSERT (a:person)~[:knows]~(b:person)", "Undirected INSERT edges"),
			// DELETE of a non-variable expression.
			("MATCH (n:person) DELETE n.age", "bound variable"),
		];
		for (query, expected) in cases {
			let err = run_gql_err(&ds, &ses, query).await;
			assert!(err.contains(expected), "query {query:?}: expected {expected:?}, got: {err}");
		}
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_mutation_respects_record_permissions() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		// Owner: a table that denies create/update (but allows select), seeded
		// with one row.
		execute_all(
			&ds,
			&ses,
			"DEFINE TABLE person SCHEMALESS \
			PERMISSIONS FOR select FULL, FOR create NONE, FOR update NONE, FOR delete NONE; \
			CREATE person:1 SET name = 'A', age = 30;",
		)
		.await?;
		// A record-scoped session: table PERMISSIONS clauses apply (a role-based
		// system session would bypass them, so this is the meaningful test).
		let rec = Session::for_record(
			"test",
			"test",
			"user",
			surrealdb_types::Value::RecordId(surrealdb_types::RecordId::new("user", "tester")),
		);
		// Each write goes through the native document pipeline, so each is denied:
		// INSERT (create), SET (update), DELETE (delete) all leave the row intact.
		let _ = ds
			.run(QueryRequest::new(QuerySource::gql("INSERT (p:person {name: 'B'})"), &rec))
			.await;
		let _ = ds
			.run(QueryRequest::new(QuerySource::gql("MATCH (n:person) SET n.age = 99"), &rec))
			.await;
		let _ = ds
			.run(QueryRequest::new(QuerySource::gql("MATCH (n:person) DETACH DELETE n"), &rec))
			.await;
		// As owner: exactly the original row remains, unchanged.
		let val =
			run_gql(&ds, &ses, "MATCH (n:person) RETURN n.name AS name, n.age AS age").await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![object! { name: "A", age: 30 }])
		);
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_nodetach_probe_ignores_select_permissions() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		// `person` is fully visible/deletable to a record session, but the `knows`
		// edge table hides SELECT from it. Seed a node with one connected edge.
		execute_all(
			&ds,
			&ses,
			"DEFINE TABLE person SCHEMALESS \
			PERMISSIONS FOR select FULL, FOR create FULL, FOR update FULL, FOR delete FULL; \
			DEFINE TABLE knows SCHEMALESS \
			PERMISSIONS FOR select NONE, FOR create FULL, FOR update FULL, FOR delete FULL; \
			CREATE person:1 SET name = 'A'; CREATE person:2 SET name = 'B'; \
			RELATE person:1->knows->person:2;",
		)
		.await?;
		let rec = Session::for_record(
			"test",
			"test",
			"user",
			surrealdb_types::Value::RecordId(surrealdb_types::RecordId::new("user", "tester")),
		);
		// The NODETACH (default) connected-edge probe runs with permissions
		// DISABLED, so it sees the `knows` edge the record session cannot SELECT and
		// errors — rather than passing the guard and letting the native DELETE
		// silently cascade an edge the caller opted out of removing.
		let err = run_gql_err(&ds, &rec, "MATCH (n:person WHERE n.name = 'A') DELETE n").await;
		assert!(err.contains("connected edges"), "{err}");
		// The node (and its edge) survive the rejected delete.
		let val =
			run_gql(&ds, &ses, "MATCH (n:person) RETURN n.name AS name ORDER BY name").await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![
				object! { name: "A" },
				object! { name: "B" }
			])
		);
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_match_after_set_rereads_live_state() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(
			&ds,
			&ses,
			"CREATE person:1 SET name = 'A', tier = 'bronze'; \
			CREATE person:2 SET name = 'B', tier = 'gold';",
		)
		.await?;
		// A read step after a write re-scans the live (post-write) state in the same
		// transaction: promoting A to gold and then MATCHing on `tier = 'gold'` finds
		// both A (just written) and B.
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (n:person WHERE n.name = 'A') SET n.tier = 'gold' \
			MATCH (m:person WHERE m.tier = 'gold') RETURN m.name AS name ORDER BY name",
		)
		.await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![
				object! { name: "A" },
				object! { name: "B" }
			])
		);
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_match_after_delete_rereads_live_state() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A'; CREATE person:2 SET name = 'B';")
			.await?;
		// The trailing MATCH no longer observes the row the DELETE removed.
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (n:person WHERE n.name = 'A') DETACH DELETE n \
			MATCH (m:person) RETURN m.name AS name ORDER BY name",
		)
		.await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { name: "B" }]));
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_match_after_insert_sees_new_node_and_anchors_on_binding() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A', age = 20;").await?;
		// A trailing MATCH re-scans and observes the just-inserted node, and can join
		// on the binding the INSERT created (`a.age` anchors the predicate on `b`).
		let val = run_gql(
			&ds,
			&ses,
			"INSERT (a:person {name: 'New', age: 20}) \
			MATCH (b:person WHERE b.age = a.age) RETURN b.name AS name ORDER BY name",
		)
		.await?;
		assert_eq!(
			val,
			PublicValue::Array(surrealdb_types::array![
				object! { name: "A" },
				object! { name: "New" }
			])
		);
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_optional_match_after_set_rereads_live_state() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A'; CREATE person:2 SET name = 'B';")
			.await?;
		// An OPTIONAL block after a write takes the general left-join path (the
		// mutating accumulator is the join's probe side, the OPTIONAL read is its
		// build side). The OPTIONAL must still observe the write: after promoting A
		// to gold, `OPTIONAL MATCH (m:person WHERE m.tier = 'gold')` matches A (just
		// written), so `m` is bound, NOT null-filled.
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (n:person WHERE n.name = 'A') SET n.tier = 'gold' \
					OPTIONAL MATCH (m:person WHERE m.tier = 'gold') \
					RETURN n.name AS n, m.name AS m",
		)
		.await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { n: "A", m: "A" }]));
		Ok(())
	}

	#[cfg(feature = "gql")]
	#[tokio::test]
	async fn gql_optional_match_after_insert_sees_new_node() -> Result<()> {
		let (ds, ses) = gql_test_ds().await?;
		execute_all(&ds, &ses, "CREATE person:1 SET name = 'A';").await?;
		// An OPTIONAL block after an INSERT must see the just-created node. The
		// INSERT runs once per matched `person`; the trailing OPTIONAL re-scans
		// `tag` and binds `m` to the new node rather than null-filling it.
		let val = run_gql(
			&ds,
			&ses,
			"MATCH (a:person WHERE a.name = 'A') INSERT (t:tag {name: 'X'}) \
			OPTIONAL MATCH (m:tag) \
			RETURN m.name AS m",
		)
		.await?;
		assert_eq!(val, PublicValue::Array(surrealdb_types::array![object! { m: "X" }]));
		Ok(())
	}

	async fn index_key_base(ds: &Datastore, table: &str, index: &str) -> Result<IndexKeyBase> {
		let txn = ds.transaction(Read).await?;
		let ns = txn.get_ns_by_name("test", None).await?.unwrap();
		let db = txn.get_db_by_name("test", "test", None).await?.unwrap();
		let table = TableName::from(table);
		let ix =
			txn.get_tb_index(ns.namespace_id, db.database_id, &table, index, None).await?.unwrap();
		txn.cancel().await?;
		Ok(IndexKeyBase::new(ns.namespace_id, db.database_id, table, ix.index_id))
	}

	async fn assert_index_compaction_commit_retry(
		site: RetryableConflictSite,
		table: &str,
		index: &str,
		sql: &str,
	) -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		execute_all(&ds, &session, sql).await?;
		let ikb = index_key_base(&ds, table, index).await?;
		let node_id = ds.id();
		let _guard = inject_retryable_conflict(site, node_id);

		ds.process_index_compaction(&ikb, CancellationToken::new()).await?;

		assert_eq!(retryable_conflict_count(site, node_id), 0);
		Ok(())
	}

	const COUNT_COMPACTION_SQL: &str = "
		DEFINE TABLE user SCHEMALESS;
	DEFINE INDEX count_idx ON user COUNT;
	CREATE user:1 SET name = 'one' RETURN NONE;
	CREATE user:2 SET name = 'two' RETURN NONE;
	";

	const FULLTEXT_COMPACTION_SQL: &str = "
		DEFINE ANALYZER simple TOKENIZERS blank FILTERS lowercase;
	DEFINE TABLE doc SCHEMALESS;
	DEFINE INDEX ft_idx ON doc FIELDS text FULLTEXT ANALYZER simple BM25 HIGHLIGHTS;
	CREATE doc:1 SET text = 'alpha beta' RETURN NONE;
	CREATE doc:2 SET text = 'beta gamma' RETURN NONE;
	";

	const HNSW_COMPACTION_SQL: &str = "
		DEFINE TABLE vec SCHEMALESS;
	DEFINE INDEX hnsw_idx ON vec FIELDS vector HNSW DIMENSION 2 DIST EUCLIDEAN TYPE F32 EFC 16 M 4;
	CREATE vec:1 SET vector = [1, 2] RETURN NONE;
	CREATE vec:2 SET vector = [2, 3] RETURN NONE;
	";

	#[tokio::test]
	async fn count_index_compaction_retries_commit_conflict() -> Result<()> {
		assert_index_compaction_commit_retry(
			RetryableConflictSite::CountCompaction,
			"user",
			"count_idx",
			COUNT_COMPACTION_SQL,
		)
		.await
	}

	#[tokio::test]
	async fn fulltext_index_compaction_retries_commit_conflict() -> Result<()> {
		assert_index_compaction_commit_retry(
			RetryableConflictSite::FullTextCompaction,
			"doc",
			"ft_idx",
			FULLTEXT_COMPACTION_SQL,
		)
		.await
	}

	#[tokio::test]
	async fn hnsw_index_compaction_retries_commit_conflict() -> Result<()> {
		assert_index_compaction_commit_retry(
			RetryableConflictSite::HnswCompaction,
			"vec",
			"hnsw_idx",
			HNSW_COMPACTION_SQL,
		)
		.await
	}

	/// The process-local HNSW wrapper for one index, resolved the way the query
	/// path resolves it, so a test holds the same instance the compaction and
	/// the executor reach for.
	async fn loaded_hnsw_index(
		ds: &Datastore,
		table: &str,
		index: &str,
	) -> Result<crate::idx::trees::store::hnsw::SharedHnswIndex> {
		let table = TableName::from(table);
		let txn = Arc::new(ds.transaction(Read).await?);
		let ns = txn.get_ns_by_name("test", None).await?.unwrap();
		let db = txn.get_db_by_name("test", "test", None).await?.unwrap();
		let tb = txn.get_tb(ns.namespace_id, db.database_id, &table, None).await?.unwrap();
		let ix =
			txn.get_tb_index(ns.namespace_id, db.database_id, &table, index, None).await?.unwrap();
		let Index::Hnsw(p) = &ix.index else {
			panic!("{index} is not an HNSW index");
		};
		let ikb = IndexKeyBase::new(ns.namespace_id, db.database_id, table, ix.index_id);
		let mut ctx = ds.setup_ctx()?;
		ctx.set_transaction(Arc::clone(&txn));
		let ctx = ctx.freeze();
		let hi =
			ds.index_store().get_index_hnsw(&ctx, tb.table_id, &ikb, p, ix.format_version).await?;
		txn.cancel().await?;
		Ok(hi)
	}

	/// The entries an HNSW compaction still has to apply, across both pending
	/// families.
	async fn hnsw_pending_len(ds: &Datastore, ikb: &IndexKeyBase) -> Result<usize> {
		let txn = ds.transaction(Read).await?;
		let records = txn.getr(ikb.new_hr_range()?, None).await?.len();
		let appends = txn.getr_raw(ikb.new_hp_range()?, None).await?.len();
		txn.cancel().await?;
		Ok(records + appends)
	}

	/// The layer versions the store holds for one HNSW index, layer 0 first.
	async fn hnsw_layer_versions(ds: &Datastore, ikb: &IndexKeyBase) -> Result<Vec<u64>> {
		let txn = ds.transaction(Read).await?;
		let state: surrealdb_datastore::values::hnsw::HnswState =
			txn.get_key(&ikb.new_hs_key(), None).await?.unwrap_or_default();
		txn.cancel().await?;
		let mut versions = Vec::with_capacity(1 + state.layers.len());
		versions.push(state.layer0.version);
		versions.extend(state.layers.iter().map(|l| l.version));
		Ok(versions)
	}

	/// A filtered kNN search must not evaluate its residual condition against a
	/// legacy pending entry that carries no vectors to score.
	#[tokio::test]
	async fn hnsw_legacy_pending_delete_entry_is_not_where_evaluated() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		execute_all(
			&ds,
			&session,
			"DEFINE TABLE vec SCHEMALESS;
			 DEFINE INDEX hnsw_idx ON vec FIELDS vector HNSW DIMENSION 2 DIST EUCLIDEAN TYPE F32 EFC 16 M 4;
			 CREATE vec:2 SET vector = [5, 5], bad = 5 RETURN NONE;
			 CREATE vec:1 SET bad = 'x' RETURN NONE;",
		)
		.await?;
		let ikb = index_key_base(&ds, "vec", "hnsw_idx").await?;

		// Put vec:2 in the graph, then inject the shape of a pre-v3.1 legacy
		// delete that an upgraded node can still encounter while draining `!hp`.
		ds.process_index_compaction(&ikb, CancellationToken::new()).await?;
		{
			let txn = ds.transaction(Write).await?;
			let key = surrealdb_datastore::key::schema::HnswPendingLegacyKey::new(
				ikb.ns(),
				ikb.db(),
				Cow::Borrowed(ikb.table()),
				ikb.index(),
				0,
			);
			let pending = surrealdb_datastore::values::hnsw::VectorPendingUpdate {
				id: surrealdb_datastore::values::hnsw::VectorId::RecordKey(Arc::new(
					crate::val::RecordIdKey::Number(1),
				)),
				old_vectors: vec![],
				new_vectors: vec![],
			};
			txn.set_key(&key, &pending).await?;
			txn.commit().await?;
		}

		let mut response = ds
			.execute(
				"SELECT id FROM vec WHERE vector <|5,40|> [0, 0] AND type::int(bad) > 0;",
				&session,
				None,
			)
			.await?;
		let rows = match response.remove(0).result {
			Ok(PublicValue::Array(rows)) => rows,
			Ok(other) => panic!("expected an array result, got {other:?}"),
			Err(error) => panic!(
				"the excluded vec:1 legacy delete must not have its residual condition evaluated: {error}"
			),
		};
		assert_eq!(rows.len(), 1, "only vec:2 satisfies the query: {rows:?}");
		Ok(())
	}

	/// A compaction apply that reached the graph in place and then failed to
	/// commit must not leave that graph reachable.
	///
	/// The apply advances the in-memory version of every layer it writes, and
	/// that version is a plain per-layer counter: a peer applying the same
	/// batch from the same version lands on the same one. This fixture pins the
	/// arithmetic — one staged record advances layer 0 by exactly one — so the
	/// rolled-back copy and a peer's committed copy stand at the same version
	/// with topologies that need not match, and a state check comparing
	/// versions would keep the copy the store never took. The wrapper goes
	/// instead, and the next access rebuilds it from persisted state.
	///
	/// The index engines are configured serial, so the insertion is applied in
	/// place; see the staged counterpart below for the default. The injected
	/// conflict classifies as retryable, so the compaction rolls its write
	/// back, discards the wrapper, and applies again; the call returns once
	/// that attempt commits. That attempt drains the queue, so the records the
	/// index then answers over come from the graph alone.
	#[tokio::test]
	async fn hnsw_index_compaction_commit_failure_evicts_the_loaded_index() -> Result<()> {
		let (ds, session) =
			new_index_compaction_test_ds_with("hnsw_build_parallelism", "serial").await?;
		execute_all(&ds, &session, HNSW_COMPACTION_SQL).await?;
		let ikb = index_key_base(&ds, "vec", "hnsw_idx").await?;
		let site = RetryableConflictSite::HnswCompaction;
		let node_id = ds.id();

		// Hold the wrapper the query path uses, with its graph resident.
		let before = loaded_hnsw_index(&ds, "vec", "hnsw_idx").await?;
		ds.process_index_compaction(&ikb, CancellationToken::new()).await?;
		let versions = hnsw_layer_versions(&ds, &ikb).await?;

		// One more pending, and a commit conflict to roll its apply back.
		execute_all(&ds, &session, "CREATE vec:3 SET vector = [8, 9] RETURN NONE;").await?;
		assert_eq!(hnsw_pending_len(&ds, &ikb).await?, 1, "the record must be staged, not indexed");
		let _guard = inject_retryable_conflict(site, node_id);
		ds.process_index_compaction(&ikb, CancellationToken::new()).await?;
		assert_eq!(retryable_conflict_count(site, node_id), 0, "the conflict must have fired");
		assert_eq!(
			hnsw_pending_len(&ds, &ikb).await?,
			0,
			"the attempt after the rollback must have applied the pending it rolled back"
		);

		// The advance the rolled-back apply staged in memory, and that the
		// attempt after it then committed: one batch of one record, one layer-0
		// version. A peer applying that same batch reproduces it exactly, which
		// is why the version cannot certify the rolled-back topology.
		let applied = hnsw_layer_versions(&ds, &ikb).await?;
		assert_eq!(
			applied[0],
			versions[0] + 1,
			"one staged record must advance layer 0 by exactly one: {versions:?} -> {applied:?}"
		);

		// The wrapper the rollback mutated is gone; the attempt after it ran on
		// one rebuilt from the store.
		let after = loaded_hnsw_index(&ds, "vec", "hnsw_idx").await?;
		assert!(
			!Arc::ptr_eq(&before, &after),
			"a rolled-back compaction write must not leave its graph reachable"
		);

		// With the queue drained, every record answered for comes from the
		// graph, which the rebuilt wrapper took from the store.
		let mut response =
			ds.execute("SELECT id FROM vec WHERE vector <|3,40|> [1, 2];", &session, None).await?;
		let PublicValue::Array(rows) = response.remove(0).result? else {
			panic!("expected an array result");
		};
		assert_eq!(rows.len(), 3, "the recovered index must return every record: {rows:?}");
		Ok(())
	}

	/// A staged compaction whose commit fails leaves the loaded index in place.
	///
	/// A batch that only adds vectors builds its graph changes into its
	/// transaction and publishes them into the resident graph from the commit,
	/// so a commit that fails leaves the resident graph at the committed state:
	/// there is nothing to discard, and the retry runs on the same wrapper. The
	/// retry advances layer 0 by exactly one, as the in-place apply does, and
	/// once it has drained the queue the graph answers for every record.
	#[tokio::test]
	async fn hnsw_staged_compaction_commit_failure_keeps_the_loaded_index() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		execute_all(&ds, &session, HNSW_COMPACTION_SQL).await?;
		let ikb = index_key_base(&ds, "vec", "hnsw_idx").await?;
		let site = RetryableConflictSite::HnswCompaction;
		let node_id = ds.id();

		let before = loaded_hnsw_index(&ds, "vec", "hnsw_idx").await?;
		ds.process_index_compaction(&ikb, CancellationToken::new()).await?;
		let versions = hnsw_layer_versions(&ds, &ikb).await?;

		execute_all(&ds, &session, "CREATE vec:3 SET vector = [8, 9] RETURN NONE;").await?;
		assert_eq!(hnsw_pending_len(&ds, &ikb).await?, 1, "the record must be staged, not indexed");
		let _guard = inject_retryable_conflict(site, node_id);
		ds.process_index_compaction(&ikb, CancellationToken::new()).await?;
		assert_eq!(retryable_conflict_count(site, node_id), 0, "the conflict must have fired");
		assert_eq!(
			hnsw_pending_len(&ds, &ikb).await?,
			0,
			"the attempt after the rollback must have applied the pending it rolled back"
		);
		let applied = hnsw_layer_versions(&ds, &ikb).await?;
		assert_eq!(
			applied[0],
			versions[0] + 1,
			"one staged batch must advance layer 0 by exactly one: {versions:?} -> {applied:?}"
		);

		let after = loaded_hnsw_index(&ds, "vec", "hnsw_idx").await?;
		assert!(
			Arc::ptr_eq(&before, &after),
			"a staged batch that did not commit must leave the loaded index in place"
		);
		let mut response =
			ds.execute("SELECT id FROM vec WHERE vector <|3,40|> [1, 2];", &session, None).await?;
		let PublicValue::Array(rows) = response.remove(0).result? else {
			panic!("expected an array result");
		};
		assert_eq!(rows.len(), 3, "the index must return every record: {rows:?}");
		Ok(())
	}

	/// An apply error can land after a layer mutates but before `save_nodes`
	/// advances its version, leaving a resident topology the store never took
	/// under the version the store already holds. That path must evict the
	/// wrapper too.
	#[tokio::test]
	async fn hnsw_index_compaction_apply_error_evicts_the_loaded_index() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		execute_all(&ds, &session, HNSW_COMPACTION_SQL).await?;
		let ikb = index_key_base(&ds, "vec", "hnsw_idx").await?;
		ds.process_index_compaction(&ikb, CancellationToken::new()).await?;

		// Hold the query-path wrapper with the two-node graph resident. Element
		// ids follow the two separately keyed pending records: vec:1 is 0 and
		// vec:2 is 1.
		let before = loaded_hnsw_index(&ds, "vec", "hnsw_idx").await?;
		let (table_id, format_version, entry_point) = {
			let txn = ds.transaction(Read).await?;
			let ns = txn.get_ns_by_name("test", None).await?.unwrap();
			let db = txn.get_db_by_name("test", "test", None).await?.unwrap();
			let table = TableName::from("vec");
			let tb = txn.get_tb(ns.namespace_id, db.database_id, &table, None).await?.unwrap();
			let ix = txn
				.get_tb_index(ns.namespace_id, db.database_id, &table, "hnsw_idx", None)
				.await?
				.unwrap();
			let state: surrealdb_datastore::values::hnsw::HnswState =
				txn.get_key(&ikb.new_hs_key(), None).await?.unwrap();
			txn.cancel().await?;
			(tb.table_id, ix.format_version, state.enter_point.unwrap())
		};
		assert!(entry_point <= 1, "the two-node fixture has an unexpected entry point");

		// Delete the non-entry-point record. Its layer-0 removal mutates the
		// resident graph before resolving the remaining neighbour's vector.
		let removed_element = 1 - entry_point;
		let delete = format!("DELETE vec:{} RETURN NONE;", removed_element + 1);
		execute_all(&ds, &session, &delete).await?;
		assert_eq!(hnsw_pending_len(&ds, &ikb).await?, 1);

		// Force that neighbour lookup to the store, then corrupt its encoded
		// vector. The apply now errors after `remove_node_and_bidirectional_edges`
		// but before `save_nodes` can version the mutated layer.
		ds.index_store().invalidate_hnsw_index_caches(table_id, &ikb, format_version).await;
		let entry_vector_key = surrealdb_datastore::key::schema::HnswVectorKey::new(
			ikb.ns(),
			ikb.db(),
			Cow::Borrowed(ikb.table()),
			ikb.index(),
			entry_point,
		);
		let txn = ds.transaction(Write).await?;
		txn.set(entry_vector_key.encode_key()?, vec![0xff]).await?;
		txn.commit().await?;

		ds.process_index_compaction(&ikb, CancellationToken::new())
			.await
			.expect_err("the malformed neighbour vector must fail the graph apply");
		assert_eq!(
			hnsw_pending_len(&ds, &ikb).await?,
			1,
			"the failed apply must roll back its conditional pending delete"
		);

		let after = loaded_hnsw_index(&ds, "vec", "hnsw_idx").await?;
		assert!(
			!Arc::ptr_eq(&before, &after),
			"an apply error before versioning must evict the mutated wrapper"
		);
		Ok(())
	}

	#[tokio::test]
	async fn index_compaction_retries_queue_cleanup_commit_conflict() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		execute_all(&ds, &session, COUNT_COMPACTION_SQL).await?;
		let site = RetryableConflictSite::IndexCompactionQueueCleanup;
		let node_id = ds.id();
		let _guard = inject_retryable_conflict(site, node_id);

		let (_, errors) =
			Datastore::index_compaction(ds, Duration::from_secs(1), CancellationToken::new())
				.await?;

		assert_eq!(errors, 0);
		assert_eq!(retryable_conflict_count(site, node_id), 0);
		Ok(())
	}

	/// The compaction-queue drain must never delete more than one batch of
	/// `/!ic` entries per write transaction: the queue grows by one entry per
	/// indexed record write, so an unbounded cleanup transaction would carry
	/// one write per accumulated entry — the per-key reservation profile that
	/// can starve distributed backends.
	#[tokio::test]
	async fn index_compaction_queue_cleanup_is_bounded() -> Result<()> {
		let batch = INDEX_COMPACTION_QUEUE_BATCH_SIZE as usize;
		// A backlog of 2.5 batches forces multiple drain iterations.
		let backlog = batch * 2 + batch / 2;
		let observer = Arc::new(WriteTxSizeObserver::default());
		// Background jobs are off so the only transactions observed are the
		// ones this test drives. The maintenance task runs this very function
		// on the same datastore, and its lease admits a second pass on the same
		// node, so one landing inside this drain both conflicts with the
		// cleanup commit — making it retry and re-observe its keys — and
		// commits batches of its own that the observer cannot distinguish from
		// this drain's.
		let ds = Datastore::builder()
			.without_maintenance_tasks()
			.with_observer(Arc::clone(&observer) as Arc<dyn ExecutionObserver>)
			.build_with_path("memory")
			.await?;
		let session = Session::owner().with_ns("test").with_db("test");
		{
			let txn = ds.transaction(Write).await?;
			txn.ensure_ns_db(None, "test", "test").await?;
			txn.commit().await?;
		}
		// A real index for the queue entries to reference. The table stays
		// empty (no record writes, which would each enqueue an entry of
		// their own), so compacting it performs no index writes and the
		// cycle's only large write transactions are the queue cleanups.
		execute_all(
			&ds,
			&session,
			"DEFINE ANALYZER simple TOKENIZERS blank FILTERS lowercase;
			 DEFINE TABLE doc SCHEMALESS;
			 DEFINE INDEX ft_idx ON doc FIELDS text FULLTEXT ANALYZER simple BM25;",
		)
		.await?;
		let ikb = index_key_base(&ds, "doc", "ft_idx").await?;
		let node_id = ds.id();
		// Enqueue the backlog directly: each key is unique, exactly as the
		// per-record-write enqueue path produces them.
		{
			let txn = ds.transaction(Write).await?;
			for _ in 0..backlog {
				txn.set_key(&ikb.new_ic_key(node_id), &()).await?;
			}
			txn.commit().await?;
		}
		// Only observe the compaction cycle's own transactions.
		observer.clear();

		let (batches, errors) = Datastore::index_compaction(
			Arc::clone(&ds),
			Duration::from_secs(60),
			CancellationToken::new(),
		)
		.await?;
		assert_eq!(errors, 0);
		assert_eq!(batches, 3, "expected the backlog to drain in ceil(2.5) batches");

		// The queue is fully drained.
		let remaining = {
			let txn = ds.transaction(Read).await?;
			let res = txn.keys(IndexCompactionPrefix {}.range()?, u32::MAX, 0, None).await;
			let _ = txn.cancel().await;
			res?
		};
		assert!(remaining.is_empty(), "queue not drained: {} entries left", remaining.len());

		// No write transaction exceeded the batch bound, and the cleanups
		// were exactly [batch, batch, batch/2].
		let sizes = observer.sizes();
		assert!(
			sizes.iter().all(|&n| n <= batch as u64),
			"a write transaction exceeded the {batch}-key bound: {sizes:?}"
		);
		let cleanups = cleanup_sizes(&sizes);
		assert_eq!(
			cleanups,
			vec![batch as u64, batch as u64, (batch / 2) as u64],
			"unexpected cleanup transaction sizes"
		);
		Ok(())
	}

	/// Queue keys sort by index before their time-ordered UUID, so a
	/// start-anchored scan would keep serving an early-sorting index for as
	/// long as it has (or keeps receiving) entries. The drain must instead
	/// rotate: after a batch, the scan resumes past that batch's last index,
	/// reaching later-sorting indexes before returning for the remainder.
	#[tokio::test]
	async fn index_compaction_queue_drain_rotates_across_indexes() -> Result<()> {
		let batch = INDEX_COMPACTION_QUEUE_BATCH_SIZE as usize;
		let observer = Arc::new(WriteTxSizeObserver::default());
		// Background jobs are off, for the same reason as the bounded test
		// above: the maintenance task runs this very function, and a second
		// pass inside this drain would both conflict with the cleanup commits
		// and contribute batches of its own to the observed sequence.
		let ds = Datastore::builder()
			.without_maintenance_tasks()
			.with_observer(Arc::clone(&observer) as Arc<dyn ExecutionObserver>)
			.build_with_path("memory")
			.await?;
		let session = Session::owner().with_ns("test").with_db("test");
		{
			let txn = ds.transaction(Write).await?;
			txn.ensure_ns_db(None, "test", "test").await?;
			txn.commit().await?;
		}
		// Two empty indexed tables whose names order their queue entries:
		// `aaa` sorts before `zzz`.
		execute_all(
			&ds,
			&session,
			"DEFINE ANALYZER simple TOKENIZERS blank FILTERS lowercase;
			 DEFINE TABLE aaa SCHEMALESS;
			 DEFINE TABLE zzz SCHEMALESS;
			 DEFINE INDEX ft_a ON aaa FIELDS text FULLTEXT ANALYZER simple BM25;
			 DEFINE INDEX ft_z ON zzz FIELDS text FULLTEXT ANALYZER simple BM25;",
		)
		.await?;
		let ikb_a = index_key_base(&ds, "aaa", "ft_a").await?;
		let ikb_z = index_key_base(&ds, "zzz", "ft_z").await?;
		let node_id = ds.id();
		// 1.5 batches for the early index, a handful for the late one.
		{
			let txn = ds.transaction(Write).await?;
			for _ in 0..(batch + batch / 2) {
				txn.set_key(&ikb_a.new_ic_key(node_id), &()).await?;
			}
			for _ in 0..10 {
				txn.set_key(&ikb_z.new_ic_key(node_id), &()).await?;
			}
			txn.commit().await?;
		}
		observer.clear();

		let (batches, errors) = Datastore::index_compaction(
			Arc::clone(&ds),
			Duration::from_secs(60),
			CancellationToken::new(),
		)
		.await?;
		assert_eq!(errors, 0);
		assert_eq!(batches, 3);

		// The queue is fully drained. An abandoned cleanup leaves entries
		// behind without moving `errors` or `batches`, so the sequence below
		// cannot stand in for this.
		let remaining = {
			let txn = ds.transaction(Read).await?;
			let res = txn.keys(IndexCompactionPrefix {}.range()?, u32::MAX, 0, None).await;
			let _ = txn.cancel().await;
			res?
		};
		assert!(remaining.is_empty(), "queue not drained: {} entries left", remaining.len());

		// Rotation signature: after the first full batch of the early index,
		// the late index is served before the early index's remainder.
		let sizes = observer.sizes();
		let cleanups = cleanup_sizes(&sizes);
		assert_eq!(
			cleanups,
			vec![batch as u64, 10, (batch / 2) as u64],
			"expected the late-sorting index to be drained between the early index's batches"
		);
		Ok(())
	}

	/// One statement writing many documents must leave exactly one `!iu`
	/// count-delta entry and one `/!ic` compaction request, not one of each per
	/// document.
	///
	/// Reads of a COUNT index sum every un-compacted `!iu` entry, so the
	/// per-document fan-out made `count()` cost scale with write volume and made
	/// the compaction queue grow at the same rate. Aggregating per transaction
	/// keeps the contention-free property the delta log exists for (the entry is
	/// still a blind write under a key no other transaction shares) while
	/// removing that scaling.
	#[tokio::test]
	async fn count_index_writes_one_delta_per_transaction() -> Result<()> {
		const ROWS: usize = 500;
		let (ds, session) = new_index_compaction_test_ds().await?;
		execute_all(
			&ds,
			&session,
			"DEFINE TABLE item SCHEMALESS;
			 DEFINE INDEX idx_total ON item COUNT;",
		)
		.await?;
		let ikb = index_key_base(&ds, "item", "idx_total").await?;

		execute_all(&ds, &session, &format!("CREATE |item:1..={ROWS}| RETURN NONE")).await?;

		let (deltas, queued) = {
			let txn = ds.transaction(Read).await?;
			let iu = IndexCountPrefix {
				ns: ikb.ns(),
				db: ikb.db(),
				tb: Cow::Borrowed(ikb.table()),
				ix: ikb.index(),
			}
			.range()?;
			let deltas = catch!(txn, txn.keys(iu, u32::MAX, 0, None).await);
			let queued =
				catch!(txn, txn.keys(IndexCompactionPrefix {}.range()?, u32::MAX, 0, None).await);
			let _ = txn.cancel().await;
			(deltas, queued)
		};

		assert_eq!(
			deltas.len(),
			1,
			"{ROWS} rows in one statement must leave one count-delta entry, found {}",
			deltas.len()
		);
		assert_eq!(
			queued.len(),
			1,
			"{ROWS} rows in one statement must enqueue one compaction request, found {}",
			queued.len()
		);

		// The single entry carries the net delta, so the count is still right.
		let sum = {
			let mut sum: i64 = 0;
			for key in &deltas {
				let iu = IndexCountKey::decode_key(key)?;
				let delta = i64::try_from(iu.count).expect("count delta out of range");
				sum += if iu.pos {
					delta
				} else {
					-delta
				};
			}
			sum
		};
		assert_eq!(sum, ROWS as i64, "the aggregated entry must carry the net delta");
		Ok(())
	}

	/// A commit that queues compaction work must wake the compactor, rather
	/// than leaving the queue to sit until the next tick.
	///
	/// The compaction interval and the write rate are otherwise unrelated, and
	/// that gap is what lets a count index's delta log — which every read of the
	/// index sums — grow without bound. The notification is what ties the two
	/// together.
	#[tokio::test]
	async fn commit_queuing_compaction_work_wakes_the_compactor() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		execute_all(
			&ds,
			&session,
			"DEFINE TABLE item SCHEMALESS;
			 DEFINE INDEX idx_total ON item COUNT;",
		)
		.await?;

		// Wait on the trigger the background compactor waits on. Registering
		// before the write is what makes this deterministic rather than a race:
		// `Notify` also stores one permit, so a notification that lands before
		// the await still satisfies it.
		let triggers = Arc::clone(ds.commit_triggers());
		let waiter = tokio::spawn(async move {
			triggers.index_compaction.notified().await;
		});

		execute_all(&ds, &session, "CREATE item:1 RETURN NONE").await?;

		tokio::time::timeout(Duration::from_secs(5), waiter)
			.await
			.expect("a commit that queues compaction work must notify the compactor")
			.expect("the waiter task must not panic");
		Ok(())
	}

	/// A commit that queues no compaction work must not wake the compactor, so
	/// unrelated write traffic does not keep the lease check spinning.
	#[tokio::test]
	async fn commit_without_compaction_work_does_not_wake_the_compactor() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		// No COUNT (or other compaction-eligible) index, so nothing to queue.
		execute_all(&ds, &session, "DEFINE TABLE item SCHEMALESS;").await?;

		let triggers = Arc::clone(ds.commit_triggers());
		let waiter = tokio::spawn(async move {
			triggers.index_compaction.notified().await;
		});

		execute_all(&ds, &session, "CREATE item:1 RETURN NONE").await?;

		let woke = tokio::time::timeout(Duration::from_millis(300), waiter).await;
		assert!(woke.is_err(), "a write with no compaction work must not wake the compactor");
		Ok(())
	}

	/// Queues `count` async events and returns how many the event ran.
	async fn queue_async_events(ds: &Datastore, session: &Session, count: usize) -> Result<()> {
		execute_all(
			ds,
			session,
			"DEFINE TABLE person SCHEMALESS;
			 DEFINE TABLE logged SCHEMALESS;
			 DEFINE EVENT log ON person ASYNC THEN (CREATE logged SET who = $after.id);",
		)
		.await?;
		execute_all(ds, session, &format!("CREATE |person:{count}| RETURN NONE;")).await
	}

	async fn logged_count(ds: &Datastore, session: &Session) -> Result<usize> {
		let mut res = ds.execute("SELECT * FROM logged", session, None).await?;
		match res.remove(0).result? {
			PublicValue::Array(a) => Ok(a.len()),
			other => panic!("expected an array, got {other:?}"),
		}
	}

	/// Defines an async event with the given `RETRY` budget and queues exactly
	/// one of it.
	async fn queue_one_async_event(ds: &Datastore, session: &Session, retry: u16) -> Result<()> {
		execute_all(
			ds,
			session,
			&format!(
				"DEFINE TABLE person SCHEMALESS;
				 DEFINE TABLE logged SCHEMALESS;
				 DEFINE EVENT log ON person ASYNC RETRY {retry} \
				 THEN (CREATE logged SET who = $after.id);"
			),
		)
		.await?;
		execute_all(ds, session, "CREATE person:1 RETURN NONE;").await
	}

	/// Drains the queue the way [`Datastore::event_processing`] does, but with a
	/// bound, so a queue that stops draining fails the test instead of hanging
	/// it — which is the shape the failures under test take.
	async fn drain_event_queue(ds: &Datastore) -> Result<()> {
		for _ in 0..20 {
			if process_next_events_batch(ds, None).await? == 0 {
				return Ok(());
			}
		}
		panic!("the async event queue did not drain");
	}

	/// A retryable conflict on the commit that ends a queued event reports
	/// contention, not a failure of the event: the event still has to run, has
	/// to run exactly once, and must not spend the `RETRY` budget the definition
	/// reserved for a failing event. `RETRY 0` is what makes that last part
	/// observable — one charged attempt would drop the event instead of running
	/// it.
	///
	/// It pins the recovery path as well. `Transaction::commit` leaves the
	/// transaction finished whether or not it succeeds, so cancelling it
	/// afterwards reports `TransactionFinished` in place of the conflict; the
	/// entry is then neither re-run nor removed, and every later batch fetches
	/// and fails it again.
	#[test_log::test(tokio::test)]
	async fn a_queued_event_survives_commit_conflicts_without_spending_its_retries() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		queue_one_async_event(&ds, &session, 0).await?;

		let site = RetryableConflictSite::AsyncEventCommit;
		// Fewer than the in-place bound, so every conflict is absorbed there.
		let _guard = inject_retryable_conflicts(site, ds.id(), 2);

		// Counting passes is what separates the two failures. Both conflicts are
		// absorbed within the pass that picked the entry up, so the first pass
		// finishes the event and the second finds the queue empty. An attempt
		// that ended by reporting `TransactionFinished` would leave the entry
		// for a later pass to fetch and fail again, and the second pass would
		// still find it.
		assert_eq!(
			process_next_events_batch(&ds, None).await?,
			1,
			"the queued event must be the one entry this pass picks up"
		);
		assert_eq!(
			process_next_events_batch(&ds, None).await?,
			0,
			"the entry must be gone: its conflicts belong to the pass that ran it"
		);

		assert_eq!(
			retryable_conflict_count(site, ds.id()),
			0,
			"both injected conflicts must have been raised, or the commit was never re-driven"
		);
		assert_eq!(
			logged_count(&ds, &session).await?,
			1,
			"the event must run exactly once; the conflicting attempts are rolled back"
		);
		Ok(())
	}

	/// Conflicts that outlast the in-place bound fall through to the
	/// definition's own `RETRY` budget, so an event that never wins the race
	/// still reaches a decision and its entry leaves the queue. Without that the
	/// drain loop does not return: it re-scans and re-fails the same entry for
	/// as long as this node holds the lease.
	#[test_log::test(tokio::test)]
	async fn a_queued_event_that_keeps_conflicting_leaves_the_queue() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		queue_one_async_event(&ds, &session, 0).await?;

		let site = RetryableConflictSite::AsyncEventCommit;
		// More than any run can consume, so no attempt ever commits.
		let _guard = inject_retryable_conflicts(site, ds.id(), usize::MAX);

		drain_event_queue(&ds).await?;

		assert_eq!(
			logged_count(&ds, &session).await?,
			0,
			"no attempt committed, so the event left nothing behind"
		);
		Ok(())
	}

	/// Reads the queue the way a batch does, without running anything.
	async fn fetch_event_queue(ds: &Datastore) -> Result<Vec<(Vec<u8>, Vec<u8>)>> {
		let tx = ds.transaction(Read).await?;
		let res =
			tx.scan_raw(crate::key::schema::EventQueuePrefix {}.range()?, 1000, 0, None).await;
		tx.cancel().await?;
		res
	}

	/// A batch that fetched an entry another consumer has since run must not
	/// run it again. Batches overlap once the event-processing lease lapses, so
	/// two nodes can hold the same entry; only the first to commit runs it.
	#[test_log::test(tokio::test)]
	async fn an_event_run_by_an_overlapping_batch_is_not_run_again() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		queue_one_async_event(&ds, &session, 1).await?;

		let stale = fetch_event_queue(&ds).await?;
		assert_eq!(stale.len(), 1, "the queued event must be the one entry fetched");
		drain_event_queue(&ds).await?;
		assert_eq!(logged_count(&ds, &session).await?, 1, "the first batch runs the event");

		crate::doc::process_events_batch(&ds, stale, None).await?;

		assert_eq!(
			logged_count(&ds, &session).await?,
			1,
			"the overlapping batch must find the entry gone rather than run it again"
		);
		assert!(
			fetch_event_queue(&ds).await?.is_empty(),
			"the overlapping batch must not requeue an entry that already ran"
		);
		Ok(())
	}

	/// A commit that applied but reported an unknown outcome has run the event
	/// and removed its entry. Requeueing on that report would run the event
	/// twice: `RETRY 1` is what makes that observable, since a charged attempt
	/// would put the entry back for a second pass to run.
	#[test_log::test(tokio::test)]
	async fn an_event_whose_commit_applied_unknown_is_not_run_again() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		queue_one_async_event(&ds, &session, 1).await?;

		let site = NonRetryableErrorSite::AsyncEventCommitAppliedUnknown;
		let _guard = inject_non_retryable_error(site, ds.id());

		assert_eq!(process_next_events_batch(&ds, None).await?, 1);
		assert_eq!(
			process_next_events_batch(&ds, None).await?,
			0,
			"the applied commit removed the entry, so nothing may have put it back"
		);
		assert_eq!(logged_count(&ds, &session).await?, 1, "the event must run exactly once");
		Ok(())
	}

	/// A commit that reported an unknown outcome without applying has neither
	/// run the event nor removed its entry. Deleting the entry on that report
	/// would lose the event: `RETRY 0` is what makes that observable, since a
	/// charged attempt would exhaust the budget and delete it.
	#[test_log::test(tokio::test)]
	async fn an_event_whose_commit_was_discarded_unknown_still_runs() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		queue_one_async_event(&ds, &session, 0).await?;

		let site = NonRetryableErrorSite::AsyncEventCommitDiscardedUnknown;
		let _guard = inject_non_retryable_error(site, ds.id());

		assert_eq!(process_next_events_batch(&ds, None).await?, 1);
		assert_eq!(
			process_next_events_batch(&ds, None).await?,
			0,
			"the unknown outcome belongs to the pass that ran the event"
		);
		assert_eq!(logged_count(&ds, &session).await?, 1, "the event must still run, once");
		Ok(())
	}

	/// An outcome that stays unknown past the in-place bound is never charged
	/// to the `RETRY` budget: the entry is left as the last commit left it, and
	/// a later pass runs it or finds it gone. `RETRY 0` is what makes that
	/// observable, since a charged attempt would delete the entry.
	#[test_log::test(tokio::test)]
	async fn an_event_whose_commit_outcome_stays_unknown_is_left_queued() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		queue_one_async_event(&ds, &session, 0).await?;

		let site = NonRetryableErrorSite::AsyncEventCommitDiscardedUnknown;
		// Every attempt of the first pass: the first run and each in-place re-run.
		let _guard = inject_non_retryable_errors(site, ds.id(), 4);

		assert_eq!(process_next_events_batch(&ds, None).await?, 1);
		assert_eq!(logged_count(&ds, &session).await?, 0, "no attempt of the first pass applied");
		assert_eq!(
			fetch_event_queue(&ds).await?.len(),
			1,
			"an unknown outcome must leave the entry queued rather than delete it"
		);

		drain_event_queue(&ds).await?;
		assert_eq!(logged_count(&ds, &session).await?, 1, "a later pass runs the event");
		Ok(())
	}

	/// A cancelled pass must return at the next batch boundary rather than drain
	/// the queue. Async events run user-defined SurrealQL of unbounded duration,
	/// so a pass that ignored cancellation would hold [`Datastore::shutdown`]
	/// open for as long as the queue kept refilling.
	#[test_log::test(tokio::test)]
	async fn event_processing_returns_immediately_once_cancelled() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		queue_async_events(&ds, &session, 50).await?;

		let canceller = CancellationToken::new();
		canceller.cancel();
		// Cancellation is not an error: the queue is durable, so what is left is
		// picked up by the next pass here or on another node.
		ds.event_processing(Duration::from_secs(1), &canceller).await?;
		assert_eq!(
			logged_count(&ds, &session).await?,
			0,
			"a cancelled pass must not process the queue"
		);
		Ok(())
	}

	/// The control for the test above: with a live token the same queue drains,
	/// so the early return is cancellation and not a broken pass.
	#[test_log::test(tokio::test)]
	async fn event_processing_drains_the_queue_when_not_cancelled() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		queue_async_events(&ds, &session, 50).await?;

		ds.event_processing(Duration::from_secs(1), &CancellationToken::new()).await?;
		assert_eq!(
			logged_count(&ds, &session).await?,
			50,
			"an uncancelled pass must drain the queue"
		);
		Ok(())
	}

	/// Two owners of one datastore may both call `shutdown`, which the sequence
	/// serialises so a second caller cannot close the storage engine while the
	/// first is still waiting on a maintenance pass.
	///
	/// This covers the liveness half of that: both callers complete and neither
	/// blocks on the other's guard. The exclusion itself is a property of holding
	/// the guard across the whole sequence, not something observable from
	/// outside without a test hook in the shutdown path.
	#[test_log::test(tokio::test)]
	async fn concurrent_shutdown_calls_both_complete() -> Result<()> {
		let ds = Datastore::new("memory").await?;
		let (first, second) = tokio::time::timeout(Duration::from_secs(30), async {
			tokio::join!(ds.shutdown(), ds.shutdown())
		})
		.await
		.map_err(|_| anyhow::anyhow!("concurrent shutdown deadlocked"))?;
		first?;
		second?;
		Ok(())
	}

	/// Mutations that cancel out within one transaction write no entry at all,
	/// and a read inside that transaction still sees its own uncommitted work.
	#[tokio::test]
	async fn count_index_nets_out_within_a_transaction() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		execute_all(
			&ds,
			&session,
			"DEFINE TABLE item SCHEMALESS;
			 DEFINE INDEX idx_total ON item COUNT;",
		)
		.await?;
		let ikb = index_key_base(&ds, "item", "idx_total").await?;

		// A create and a delete of the same rows inside one transaction net to
		// zero, so there is no delta worth recording.
		execute_all(
			&ds,
			&session,
			"BEGIN;
			 CREATE |item:1..=50| RETURN NONE;
			 DELETE item:1..=50 RETURN NONE;
			 COMMIT;",
		)
		.await?;

		let deltas = {
			let txn = ds.transaction(Read).await?;
			let iu = IndexCountPrefix {
				ns: ikb.ns(),
				db: ikb.db(),
				tb: Cow::Borrowed(ikb.table()),
				ix: ikb.index(),
			}
			.range()?;
			let res = catch!(txn, txn.keys(iu, u32::MAX, 0, None).await);
			let _ = txn.cancel().await;
			res
		};
		assert!(
			deltas.is_empty(),
			"a net-zero transaction must write no delta, found {}",
			deltas.len()
		);

		// A read later in the same transaction as its writes must observe them,
		// even though the aggregate is not flushed until commit.
		let res = ds
			.execute(
				"BEGIN;
				 CREATE |item:100..=109| RETURN NONE;
				 SELECT count() FROM item GROUP ALL;
				 COMMIT;",
				&session,
				None,
			)
			.await?;
		// Locate the SELECT's result by content rather than by position, so the
		// assertion does not depend on how many results the surrounding
		// BEGIN/COMMIT contribute.
		let mut counted = None;
		for r in res {
			let rendered = format!("{:?}", r.result?);
			if rendered.contains("count") {
				counted = Some(rendered);
			}
		}
		let counted = counted.expect("the SELECT must produce a result");
		assert!(
			counted.contains("Int(10)"),
			"a read must see its own transaction's buffered deltas, got {counted}"
		);
		Ok(())
	}

	/// An undecodable `/!ic` entry must not wedge the drain: it names no
	/// index to compact, so the cycle skips it with a warning, deletes it
	/// with its batch, and continues serving the decodable entries.
	#[tokio::test]
	async fn index_compaction_quarantines_undecodable_queue_keys() -> Result<()> {
		let (ds, session) = new_index_compaction_test_ds().await?;
		let ds = ds;
		execute_all(
			&ds,
			&session,
			"DEFINE ANALYZER simple TOKENIZERS blank FILTERS lowercase;
			 DEFINE TABLE doc SCHEMALESS;
			 DEFINE INDEX ft_idx ON doc FIELDS text FULLTEXT ANALYZER simple BM25;",
		)
		.await?;
		let ikb = index_key_base(&ds, "doc", "ft_idx").await?;
		let node_id = ds.id();
		{
			let txn = ds.transaction(Write).await?;
			// The corrupt entry's 0xff lead byte sorts it after every valid
			// entry, so it lands last in the batch and exercises the
			// cursor-seek decode fallback as well as the dedupe-loop skip.
			for _ in 0..5 {
				txn.set_key(&ikb.new_ic_key(node_id), &()).await?;
			}
			txn.set(Key::from(b"/!ic\xff-not-a-valid-entry".to_vec()), vec![]).await?;
			txn.commit().await?;
		}

		let (batches, errors) = Datastore::index_compaction(
			Arc::clone(&ds),
			Duration::from_secs(60),
			CancellationToken::new(),
		)
		.await?;
		assert!(batches >= 1);
		assert_eq!(errors, 0, "a corrupt queue entry must not count as a compaction failure");

		// The queue is fully drained, corrupt entry included.
		let remaining = {
			let txn = ds.transaction(Read).await?;
			let res = txn.keys(IndexCompactionPrefix {}.range()?, u32::MAX, 0, None).await;
			let _ = txn.cancel().await;
			res?
		};
		assert!(remaining.is_empty(), "queue not drained: {} entries left", remaining.len());
		Ok(())
	}

	#[tokio::test]
	async fn archive_node_for_shutdown_reports_success() {
		let outcome = archive_node_for_shutdown(Duration::from_secs(60), Ok(()));

		assert_eq!(outcome, ShutdownNodeDeleteOutcome::Archived);
	}

	#[tokio::test]
	async fn archive_node_for_shutdown_reports_failure() {
		let outcome = archive_node_for_shutdown(
			Duration::from_secs(60),
			Err(anyhow::anyhow!("delete failed")),
		);

		assert_eq!(outcome, ShutdownNodeDeleteOutcome::Failed);
	}

	#[tokio::test]
	async fn archive_node_for_shutdown_reports_timeout() {
		let outcome = archive_node_for_shutdown(
			Duration::from_millis(1),
			Err(anyhow::Error::new(EngineError::QueryTimedout(Duration::from_millis(1)))),
		);

		assert_eq!(outcome, ShutdownNodeDeleteOutcome::TimedOut);
	}

	#[tokio::test]
	async fn node_tx_step_cancels_after_timeout() {
		let ds = Datastore::new("memory").await.unwrap();
		let txn = ds.transaction(Write).await.unwrap();
		let timeout_duration = Duration::from_millis(10);

		let err = await_node_tx_step(
			&txn,
			Instant::now() + timeout_duration,
			timeout_duration,
			None,
			pending::<Result<()>>(),
		)
		.await
		.unwrap_err();

		assert!(matches!(crate::err::engine_error(&err), Some(EngineError::QueryTimedout(_))));
		assert!(txn.closed());
	}

	#[tokio::test]
	async fn node_tx_step_cancels_after_cancellation() {
		let ds = Datastore::new("memory").await.unwrap();
		let txn = ds.transaction(Write).await.unwrap();
		let canceller = CancellationToken::new();
		canceller.cancel();

		let err = await_node_tx_step(
			&txn,
			Instant::now() + Duration::from_secs(60),
			Duration::from_secs(60),
			Some(&canceller),
			pending::<Result<()>>(),
		)
		.await
		.unwrap_err();

		assert!(matches!(crate::err::engine_error(&err), Some(EngineError::QueryCancelled)));
		assert!(txn.closed());
	}

	#[tokio::test]
	async fn node_tx_step_cancels_after_error() {
		let ds = Datastore::new("memory").await.unwrap();
		let txn = ds.transaction(Write).await.unwrap();

		let err = await_node_tx_step(
			&txn,
			Instant::now() + Duration::from_secs(60),
			Duration::from_secs(60),
			None,
			async { Err::<(), _>(anyhow::anyhow!("step failed")) },
		)
		.await
		.unwrap_err();

		assert_eq!(err.to_string(), "step failed");
		assert!(txn.closed());
	}

	#[tokio::test]
	async fn node_tx_step_success_leaves_transaction_open() {
		let ds = Datastore::new("memory").await.unwrap();
		let txn = ds.transaction(Write).await.unwrap();

		await_node_tx_step(
			&txn,
			Instant::now() + Duration::from_secs(60),
			Duration::from_secs(60),
			None,
			async { Ok::<_, anyhow::Error>(()) },
		)
		.await
		.unwrap();

		assert!(!txn.closed());
		txn.commit().await.unwrap();
		assert!(txn.closed());
	}

	#[tokio::test]
	async fn node_heartbeat_age_is_small_after_insert() {
		let ds = Datastore::new("memory").await.unwrap();
		// `insert_node` writes the current node's heartbeat at `clock_now()`.
		ds.insert_node().await.unwrap();
		let age = ds.node_heartbeat_age().await.unwrap().expect("the node row was just written");
		assert!(age < Duration::from_secs(5), "heartbeat should be fresh, got {age:?}");
	}

	/// A node with no membership row reports no heartbeat, rather than the read
	/// failure `get_node` raises for the same state. Readiness depends on the
	/// distinction: before `insert_node` runs, and after a peer archives and
	/// reaps this node, the row is legitimately absent.
	#[tokio::test]
	async fn node_heartbeat_age_is_absent_without_a_node_row() {
		let ds = Datastore::new("memory").await.unwrap();
		assert!(
			ds.node_heartbeat_age().await.unwrap().is_none(),
			"an unregistered node reported a heartbeat"
		);
	}

	#[tokio::test]
	async fn node_heartbeat_age_reflects_a_stale_heartbeat() {
		let ds = Datastore::new("memory").await.unwrap();
		// Write this node's registration with a heartbeat 60s in the past.
		let now = ds.clock_now().value;
		let stale = Node::new(
			ds.id(),
			Timestamp {
				value: now.saturating_sub(60_000),
			},
			false,
		);
		let key = NodeKey {
			nd: ds.id(),
		};
		let txn = ds.transaction(Write).await.unwrap();
		txn.set_key(&key, &stale).await.unwrap();
		txn.commit().await.unwrap();
		// The reported age should reflect the stale heartbeat.
		let age = ds.node_heartbeat_age().await.unwrap().expect("the node row was just written");
		assert!(age >= Duration::from_secs(59), "heartbeat should be stale, got {age:?}");
	}

	#[tokio::test]
	async fn test_setup_superuser() {
		let ds = Datastore::new("memory").await.unwrap();
		let username = "root";
		let password = "root";

		// Setup the initial user if there are no root users
		{
			let txn = ds.transaction(Read).await.unwrap();
			assert_eq!(txn.all_root_users(None).await.unwrap().len(), 0);
			txn.cancel().await.unwrap();
		}
		ds.initialise_credentials(username, password).await.unwrap();
		{
			let txn = ds.transaction(Read).await.unwrap();
			assert_eq!(txn.all_root_users(None).await.unwrap().len(), 1);
			txn.cancel().await.unwrap();
		}
		verify_root_creds(&ds, username, password).await.unwrap();

		// Do not setup the initial root user if there are root users:
		// Test the scenario by making sure the custom password doesn't change.
		let sql = "DEFINE USER root ON ROOT PASSWORD 'test' ROLES OWNER";
		let sess = Session::owner();
		ds.execute(sql, &sess, None).await.unwrap();
		let pass_hash = {
			let txn = ds.transaction(Read).await.unwrap();
			let res = txn.expect_root_user(username).await.unwrap().hash.clone();
			txn.cancel().await.unwrap();
			res
		};

		ds.initialise_credentials(username, password).await.unwrap();
		{
			let txn = ds.transaction(Read).await.unwrap();
			assert_eq!(pass_hash, txn.expect_root_user(username).await.unwrap().hash.clone());
			txn.cancel().await.unwrap();
		}
	}

	#[tokio::test]
	pub async fn very_deep_query() -> Result<()> {
		use reblessive::{Stack, Stk};

		use crate::expr::{BinaryOperator, Expr, Literal};
		use crate::kvs::Datastore;
		use crate::val::{Number, Value};

		// build query manually to bypass query limits.
		let mut stack = Stack::new();
		async fn build_query(stk: &mut Stk, depth: usize) -> Expr {
			if depth == 0 {
				Expr::Binary {
					left: Box::new(Expr::Literal(Literal::Integer(1))),
					op: BinaryOperator::Add,
					right: Box::new(Expr::Literal(Literal::Integer(1))),
				}
			} else {
				let q = stk.run(|stk| build_query(stk, depth - 1)).await;
				Expr::Binary {
					left: Box::new(q),
					op: BinaryOperator::Add,
					right: Box::new(Expr::Literal(Literal::Integer(1))),
				}
			}
		}
		let val = stack.enter(|stk| build_query(stk, 1000)).finish();

		let dbs = Datastore::builder()
			.with_capabilities(Capabilities::all())
			.build_with_path("memory")
			.await
			.unwrap();

		let opt = Options::new(&dbs.config().exec)
			.with_ns(Some("test".into()))
			.with_db(Some("test".into()))
			.with_max_computation_depth(u32::MAX);

		// Create a default context
		let mut ctx = dbs.setup_ctx()?;
		// Start a new transaction
		let txn = dbs.transaction(TransactionType::Read).await?.enclose();
		// Store the transaction
		ctx.set_transaction(Arc::clone(&txn));
		// Freeze the context
		let ctx = ctx.freeze();
		// Compute the value
		let mut stack = reblessive::tree::TreeStack::new();
		let res = stack
			.enter(|stk| crate::legacy::expr_compute(&val, stk, &ctx, &opt, None))
			.finish()
			.await
			.catch_return()
			.unwrap();
		assert_eq!(res, Value::Number(Number::Int(1002)));
		txn.cancel().await?;
		Ok(())
	}

	#[tokio::test]
	async fn cross_transaction_caching_uuids_updated() -> Result<()> {
		let (send, _recv) = crate::channel::bounded(surrealdb_cnf::NOTIFICATIONS_CHANNEL_SIZE);
		let ds = Datastore::builder()
			.with_capabilities(Capabilities::all())
			.with_notify(send)
			.build_with_path("memory")
			.await?;
		let ses = Session::owner().with_ns("test").with_db("test").with_rt(true);

		let db = {
			let txn = ds.transaction(TransactionType::Write).await?;
			let db = txn.ensure_ns_db(None, "test", "test").await?;
			txn.commit().await?;
			db
		};

		// Define the table, set the initial uuids
		let initial = {
			let sql = r"DEFINE TABLE test;".to_owned();
			let res = &mut ds.execute(&sql, &ses, None).await?;
			assert_eq!(res.len(), 1);
			res.remove(0).result.unwrap();
			// Obtain the initial uuids
			let txn = ds.transaction(TransactionType::Read).await?;
			let tb = TableName::from("test");
			let initial = txn.get_tb(db.namespace_id, db.database_id, &tb, None).await?.unwrap();
			txn.cancel().await?;
			initial
		};

		// Define some resources to refresh the UUIDs
		let lqid = {
			let sql = r"
				DEFINE FIELD test ON test;
			DEFINE EVENT test ON test WHEN {} THEN {};
			DEFINE TABLE view AS SELECT * FROM test;
			DEFINE INDEX test ON test FIELDS test;
			LIVE SELECT * FROM test;
			"
			.to_owned();
			let res = &mut ds.execute(&sql, &ses, None).await?;
			assert_eq!(res.len(), 5);
			res.remove(0).result.unwrap();
			res.remove(0).result.unwrap();
			res.remove(0).result.unwrap();
			res.remove(0).result.unwrap();
			let lqid = res.remove(0).result?;
			assert!(matches!(lqid, PublicValue::Uuid(_)));
			lqid
		};

		// Obtain the uuids after definitions
		let after_define = {
			let txn = ds.transaction(TransactionType::Read).await?;
			let tb = TableName::from("test");
			let after_define =
				txn.get_tb(db.namespace_id, db.database_id, &tb, None).await?.unwrap();
			txn.cancel().await?;
			// Compare uuids after definitions
			assert_ne!(initial.cache_indexes_ts, after_define.cache_indexes_ts);
			assert_ne!(initial.cache_tables_ts, after_define.cache_tables_ts);
			assert_ne!(initial.cache_events_ts, after_define.cache_events_ts);
			assert_ne!(initial.cache_fields_ts, after_define.cache_fields_ts);
			// LIVE bumped the committed live-query cache timestamp.
			assert_ne!(initial.cache_lives_ts, after_define.cache_lives_ts);
			after_define
		};

		// Remove the defined resources to refresh the UUIDs
		{
			let sql = r"
				REMOVE FIELD test ON test;
			REMOVE EVENT test ON test;
			REMOVE TABLE view;
			REMOVE INDEX test ON test;
			KILL $lqid;
			"
			.to_owned();
			let vars =
				PublicVariables::from(BTreeMap::from_iter(map! { "lqid".to_string() => lqid }));
			let res = &mut ds.execute(&sql, &ses, Some(vars)).await?;
			assert_eq!(res.len(), 5);
			res.remove(0).result.unwrap();
			res.remove(0).result.unwrap();
			res.remove(0).result.unwrap();
			res.remove(0).result.unwrap();
			res.remove(0).result.unwrap();
		}
		// Obtain the uuids after definitions
		{
			let txn = ds.transaction(TransactionType::Read).await?;
			let tb = TableName::from("test");
			let after_remove =
				txn.get_tb(db.namespace_id, db.database_id, &tb, None).await?.unwrap();
			txn.cancel().await?;
			// Compare uuids after definitions
			assert_ne!(after_define.cache_fields_ts, after_remove.cache_fields_ts);
			assert_ne!(after_define.cache_events_ts, after_remove.cache_events_ts);
			assert_ne!(after_define.cache_tables_ts, after_remove.cache_tables_ts);
			assert_ne!(after_define.cache_indexes_ts, after_remove.cache_indexes_ts);
			// KILL bumped the committed live-query cache timestamp.
			assert_ne!(after_define.cache_lives_ts, after_remove.cache_lives_ts);
		}
		//
		Ok(())
	}

	/// Exact-count accounting for the durable commits an indexed write incurs
	/// beyond its own statement transaction.
	///
	/// Groups every observed transaction completion by outcome, type and
	/// `keys_written`, so a per-record commit is distinguishable from a
	/// per-record cancel: a cancel costs nothing on a remote backend, a commit
	/// is a full durability round trip.
	#[derive(Default)]
	struct TxOutcomeObserver(std::sync::Mutex<Vec<(&'static str, bool, u64)>>);

	impl ExecutionObserver for TxOutcomeObserver {
		fn on_transaction_complete(&self, event: &crate::observe::TransactionEvent) {
			self.0.lock().unwrap().push((
				event.safe.outcome.as_label(),
				event.safe.write,
				event.safe.metrics.keys_written,
			));
		}
	}

	impl TxOutcomeObserver {
		fn take(&self) -> Vec<(&'static str, bool, u64)> {
			let mut g = self.0.lock().unwrap();
			std::mem::take(&mut *g)
		}
	}

	#[tokio::test]
	async fn doc_id_allocation_commits_per_record() -> Result<()> {
		// Windowed allocation makes the commit count flat in the row count. The
		// doc-ID window is `table_doc_ids_batch_size` wide (1000), so none of
		// these sizes exhausts one, and the builder commits per batch of
		// `INDEXING_BATCH_SIZE`. Persisting per allocation instead put this at
		// one commit per row, which is what the bounds below rule out: they sit
		// far under the smallest row count, so a per-row commit breaches them at
		// every size.
		const ROWS: [usize; 3] = [100, 200, 400];
		const INSERT_MAX: usize = 16;
		const BUILD_MAX: usize = 48;

		let mut observed = Vec::with_capacity(ROWS.len());
		for rows in ROWS {
			let (insert, build) = measure_doc_id_commits(rows).await?;
			assert!(
				insert <= INSERT_MAX,
				"{rows} indexed inserts took {insert} durable write commits, over the {INSERT_MAX} \
				 a windowed allocator needs"
			);
			assert!(
				build <= BUILD_MAX,
				"a DEFINE INDEX over {rows} rows took {build} durable write commits, over the \
				 {BUILD_MAX} a windowed allocator needs"
			);
			observed.push((insert, build));
		}

		// Flat in the row count, not merely bounded: quadrupling the rows must
		// not multiply the commits. A per-row commit shows up here as growth
		// proportional to `ROWS`, even were the caps above ever loosened.
		let (first_insert, first_build) = observed[0];
		let (last_insert, last_build) = observed[ROWS.len() - 1];
		let (first_rows, last_rows) = (ROWS[0], ROWS[ROWS.len() - 1]);
		assert!(
			last_insert <= first_insert * 2,
			"inserting {last_rows} rows took {last_insert} commits against {first_insert} for \
			 {first_rows}: the cost is tracking the row count"
		);
		assert!(
			last_build <= first_build * 2,
			"building over {last_rows} rows took {last_build} commits against {first_build} for \
			 {first_rows}: the cost is tracking the row count"
		);

		Ok(())
	}

	async fn measure_doc_id_commits(rows: usize) -> Result<(usize, usize)> {
		let observer = Arc::new(TxOutcomeObserver::default());
		let ds = Datastore::builder()
			.with_observer(Arc::clone(&observer) as Arc<dyn ExecutionObserver>)
			.without_maintenance_tasks()
			.build_with_path("memory")
			.await?;
		let session = Session::owner().with_ns("test").with_db("test");
		{
			let txn = ds.transaction(Write).await?;
			txn.ensure_ns_db(None, "test", "test").await?;
			txn.commit().await?;
		}

		let report = |label: &str, obs: Vec<(&'static str, bool, u64)>| -> usize {
			let mut h: BTreeMap<(&'static str, bool, u64), usize> = BTreeMap::new();
			for e in &obs {
				*h.entry(*e).or_default() += 1;
			}
			// A rollback reports `Outcome::Cancelled`, so a `success` write
			// completion is exactly a durable commit. Of those, the single-key
			// ones are the sequence state writes this test is about: nothing
			// else on this path commits exactly one key.
			let durable_writes = obs.iter().filter(|(o, w, _)| *o == "success" && *w).count();
			let seq_state = obs.iter().filter(|(o, w, k)| *o == "success" && *w && *k == 1).count();
			let per_row = durable_writes as f64 / rows as f64;
			println!(
				"  {label}: {durable_writes} durable write commits ({per_row:.3}/row), of which {seq_state} single-key sequence-state; {} completions total",
				obs.len()
			);
			for ((outcome, write, keys), n) in h {
				let kind = if write {
					"write"
				} else {
					"read "
				};
				println!("      {n:>4} x [{outcome:>9} {kind} keys_written={keys}]");
			}
			durable_writes
		};

		// Case A: inserts into a table that already carries a b-tree index.
		execute_all(
			&ds,
			&session,
			"DEFINE TABLE item SCHEMALESS;
			 DEFINE INDEX idx_name ON item FIELDS name;",
		)
		.await?;
		let _ = observer.take();
		execute_all(&ds, &session, &format!("CREATE |item:1..={rows}| SET name = 'x' RETURN NONE"))
			.await?;
		let insert_obs = observer.take();

		// Case B: DEFINE INDEX over rows that already exist.
		execute_all(&ds, &session, "DEFINE TABLE other SCHEMALESS;").await?;
		execute_all(
			&ds,
			&session,
			&format!("CREATE |other:1..={rows}| SET name = 'x' RETURN NONE"),
		)
		.await?;
		let _ = observer.take();
		execute_all(&ds, &session, "DEFINE INDEX idx_other ON other FIELDS name;").await?;
		let build_obs = observer.take();

		println!("\n  rows={rows}");
		let insert = report("insert", insert_obs);
		let build = report("build ", build_obs);

		Ok((insert, build))
	}

	/// A doc-ID is issued once. The forward map (record -> id) and the reverse
	/// map (id -> record) therefore hold one entry per record: reissuing an id
	/// overwrites a reverse entry, which leaves the reverse map short while the
	/// forward map stays whole.
	///
	/// The restart lands mid-window — the doc-ID batch is 1000 and far fewer
	/// records are written — which is the case a persisted per-allocation
	/// cursor used to cover and the window's committed end covers now. A
	/// restart keeps the node id, which is what makes the persisted allocator
	/// state reachable at all: it is keyed per node.
	#[tokio::test]
	async fn doc_ids_stay_unique_across_mid_batch_restart() -> Result<()> {
		const BEFORE: usize = 30;
		const AFTER: usize = 30;

		let (ds, session) = new_index_compaction_test_ds().await?;
		execute_all(
			&ds,
			&session,
			"DEFINE TABLE item SCHEMALESS;
			 DEFINE INDEX idx_tag ON item FIELDS tag;",
		)
		.await?;
		execute_all(
			&ds,
			&session,
			&format!("CREATE |item:1..={BEFORE}| SET tag = 'x' RETURN NONE"),
		)
		.await?;

		let ds = Arc::new(Arc::into_inner(ds).expect("sole owner of the datastore").restart());
		let lo = BEFORE + 1;
		let hi = BEFORE + AFTER;
		execute_all(&ds, &session, &format!("CREATE |item:{lo}..={hi}| SET tag = 'x' RETURN NONE"))
			.await?;

		let (forward, reverse) = doc_id_map_sizes(&ds, "item", "idx_tag").await?;

		assert_eq!(forward, BEFORE + AFTER, "one forward doc-ID mapping per record");
		assert_eq!(
			reverse,
			BEFORE + AFTER,
			"a reissued doc-ID overwrites a reverse mapping, leaving this map short"
		);

		Ok(())
	}

	/// The sizes of a table's doc-ID maps: the forward map keyed by record and
	/// the reverse map keyed by id. They hold one entry per record while every
	/// id is distinct; a reissued id overwrites a reverse entry, so the reverse
	/// map is where a collision becomes visible.
	async fn doc_id_map_sizes(ds: &Datastore, tb: &str, ix: &str) -> Result<(usize, usize)> {
		let ikb = index_key_base(ds, tb, ix).await?;
		let txn = ds.transaction(Read).await?;
		let forward = catch!(
			txn,
			txn.keys(
				DocLookupPrefix::new(ikb.ns(), ikb.db(), Cow::Borrowed(ikb.table())).range()?,
				u32::MAX,
				0,
				None
			)
			.await
		);
		let reverse = catch!(
			txn,
			txn.keys(
				DocKeyPrefix::new(ikb.ns(), ikb.db(), Cow::Borrowed(ikb.table())).range()?,
				u32::MAX,
				0,
				None
			)
			.await
		);
		let _ = txn.cancel().await;
		Ok((forward.len(), reverse.len()))
	}

	/// A record nested to [`MAX_VALUE_DEPTH`], the deepest the storage layer
	/// accepts.
	///
	/// It is grown one level per statement so no statement in the source is
	/// itself deeply nested: the depth reaches storage without ever passing
	/// through the query parser, which is what a restore has to read back.
	async fn seed_deepest_storable_record(ds: &Datastore, session: &Session) -> Result<()> {
		execute_all(ds, session, "CREATE deep:1 SET data = 'leaf' RETURN NONE;").await?;
		// The record object is the first level and the leaf the last, so the
		// wrappers between them carry the rest.
		for _ in 0..MAX_VALUE_DEPTH - 2 {
			execute_all(ds, session, "UPDATE deep:1 SET data = { l: data } RETURN NONE;").await?;
		}
		Ok(())
	}

	/// The SurrealQL an export renders a database as.
	async fn export_sql(ds: &Datastore, session: &Session) -> Result<String> {
		let (tx, rx) = crate::channel::bounded::<Vec<u8>>(16);
		let task = ds.export(session, tx).await?;
		let collector = tokio::spawn(async move {
			let mut out = Vec::new();
			while let Ok(chunk) = rx.recv().await {
				out.extend_from_slice(&chunk);
			}
			out
		});
		task.await?;
		Ok(String::from_utf8(collector.await?)?)
	}

	async fn empty_datastore(session: &Session) -> Result<Arc<Datastore>> {
		let ds = Datastore::new("memory").await?;
		let txn = ds.transaction(Write).await?;
		txn.ensure_ns_db(None, session.ns().unwrap().as_ref(), session.db().unwrap().as_ref())
			.await?;
		txn.commit().await?;
		Ok(ds)
	}

	/// A record at the deepest depth the storage layer accepts survives an
	/// export and a restore through both import entry points: what the writer
	/// accepted, an import can read back.
	///
	/// The comparison is between exports rather than query results: a
	/// statement result nests the record one level further than storage does,
	/// which the public-value conversion rejects, so a `SELECT` cannot observe
	/// a record at this depth at all.
	#[tokio::test]
	async fn deepest_storable_record_survives_the_round_trip() -> Result<()> {
		let session = Session::owner().with_ns("test").with_db("test");
		let source = empty_datastore(&session).await?;
		seed_deepest_storable_record(&source, &session).await?;
		let sql = export_sql(&source, &session).await?;

		let text_target = empty_datastore(&session).await?;
		for result in text_target.import(&sql, &session).await? {
			result.result?;
		}
		assert_eq!(export_sql(&text_target, &session).await?, sql, "restored from text");

		let stream_target = empty_datastore(&session).await?;
		let bytes = Bytes::from(sql.clone().into_bytes());
		let stream = futures::stream::once(async move { Ok(bytes) });
		for result in stream_target.import_stream(&session, stream).await? {
			result.result?;
		}
		assert_eq!(export_sql(&stream_target, &session).await?, sql, "restored from a stream");

		Ok(())
	}

	/// Every depth budget an import is read under stays above the deepest
	/// value the storage layer accepts. Raising [`MAX_VALUE_DEPTH`] without
	/// the parser profile, or narrowing the profile, would re-open the gap
	/// where a record can be written but the export of it cannot be restored.
	#[test]
	fn import_profile_clears_the_storable_value_depth() {
		let settings = Datastore::import_parser_settings(&Capabilities::default());
		for (budget, limit) in [
			("object", settings.object_recursion_limit),
			("query", settings.query_recursion_limit),
			("expression", settings.expr_recursion_limit),
		] {
			assert!(
				limit > MAX_VALUE_DEPTH,
				"the {budget} budget ({limit}) must clear the storable value depth \
				 ({MAX_VALUE_DEPTH})"
			);
		}
	}

	/// The deepest literal the import profile accepts is formatted, lowered
	/// and dropped within the call stack a worker thread running statements is
	/// guaranteed.
	///
	/// Parsing recurses on a heap-allocated `reblessive` stack, so depth alone
	/// costs nothing there; the `sql -> expr` lowering that follows, `ToSql`
	/// and the tree's own `Drop` recurse on the call stack, where exhaustion
	/// aborts the process rather than returning an error. A ceiling raised
	/// past what those survive fails here instead.
	///
	/// The budget is a fraction of `SURREAL_RUNTIME_STACK_SIZE`, which the
	/// server sizes well above this in both profiles precisely because these
	/// walks recurse. It cannot be set to the smallest stack an embedded
	/// caller might supply: frames are several times larger without
	/// optimisation, and this test runs unoptimised.
	///
	/// So what this bounds is the server. `SURREAL_RUNTIME_STACK_SIZE` is a
	/// server-only setting, and [`Datastore::import`] is also the embedded
	/// path — `EmbeddedEngine::import`, and `SurrealWasmEngine::import` under
	/// it. A wasm build takes the linker's default shadow stack, which this
	/// repository does not raise, and there a stack overflow is an unrecoverable
	/// trap rather than an abort a supervisor can restart. An embedded caller
	/// that accepts untrusted dumps is not covered by what is asserted here.
	#[test]
	fn import_profile_ceiling_is_stack_safe() {
		std::thread::Builder::new()
			.stack_size(8 * 1024 * 1024)
			.spawn(|| {
				let settings = Datastore::import_parser_settings(&Capabilities::default());
				let parse = |depth: usize| {
					let source = format!("{}'leaf'{}", "{ l: ".repeat(depth), " }".repeat(depth));
					crate::syn::parse_with_settings(
						source.as_bytes(),
						settings.clone(),
						async |parser, stk| parser.parse_expr_field(stk).await,
					)
				};

				// The deepest literal the profile accepts, so the tree the
				// recursive consumers below are handed is its worst case.
				let mut depth = settings.expr_recursion_limit;
				while parse(depth).is_err() {
					depth -= 1;
					assert!(
						depth > MAX_VALUE_DEPTH,
						"the profile accepts a literal at the storable value depth"
					);
				}
				assert!(parse(depth + 1).is_err(), "the search stopped at the ceiling");

				let expr = parse(depth).expect("the deepest accepted literal parses");
				// `ToSql` recurses once per node.
				assert!(surrealdb_types::ToSql::to_sql(&expr).contains("leaf"));
				// The lowering recurses once per node, and dropping what it
				// produces recurses once per node again.
				drop(crate::expr::Expr::from(expr));
			})
			.unwrap()
			.join()
			.unwrap();
	}
}