Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

39.7 KB
Raw Blame
//! Engine host: the cache engine + Turso storage behind an async mutex.
//!
//! `cache-core`'s `Storage` futures are `MaybeSend` — `Send` on native
//! targets — so the engine is driven directly from the tauri/tokio runtime;
//! the async mutex serializes commands the same way the browser worker's
//! queue does. Turso work completes immediately on its native synchronous IO
//! driver, so holding a runtime thread through it is fine.
//!
//! Operation ids cross the IPC boundary as strings (`"{clientId}:{urqlKey}"`)
//! so multiple webviews can register operations against the one shared
//! engine without collisions; they're interned to the engine's `u64` ids
//! internally — the same scheme as the `cache-wasm` shell.

use cache_core::deps::OpId;
use cache_core::engine::{
    BeginOptimisticWrite, CommitOptimisticWriteResult, DeferOptimisticWriteResult, Engine,
    InitialClaimOutcome, NetworkWrite, QueryRegistration, ReadResult,
    RollbackOptimisticWriteResult, WriteResult,
};
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant, QueryInspection};
use cache_core::queue::{
    ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationUpsertKind,
};
use cache_core::record_selection::{SelectedRecord, cache::RecordSelectionCache};
use cache_core::revision::CacheRevision;
use cache_core::search::{SearchPage, SearchRequest};
use cache_core::value::EntityKey;
use cache_turso::{TursoStorage, TursoStorageCloseOutcome};
use serde::Serialize;
use std::collections::HashMap;
use std::sync::Arc;
mod access;
use access::EngineAccess;

mod calendar;
mod soup;
pub use calendar::CalendarRangeResultWire;
pub use soup::{
    EntityFilterRequest, EntityFilterResult, LiveQueryResult, PredicateBaselineEntry,
    PredicateFilterResult,
};

/// Mirrors `ReadResult` in `apps/web/src/lib/graphql-cache/protocol.ts`.
#[derive(Debug, Serialize)]
#[serde(tag = "kind", rename_all = "camelCase")]
pub enum ReadResultWire {
    /// Fully answerable from cache.
    Hit {
        /// Denormalized response data.
        data: serde_json::Value,
    },
    /// Not answerable; the exchange forwards to the network.
    Miss,
}

/// Mirrors `WriteResult` in `apps/web/src/lib/graphql-cache/protocol.ts`.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct WriteResultWire {
    /// Optional complete displayed-window invalidation proofs.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub unchanged_views: Option<Vec<String>>,
    /// Effective scalar patches; absent when a query reread is required.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub field_changes: Option<Vec<cache_core::field_changes::RecordFieldChange>>,
    /// Bindings omitted while preserving a normalizable server response.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub identity_errors: Vec<String>,
    /// Effective-view revision installed by this logical mutation.
    pub revision: String,
    /// Whether this write advanced `revision`.
    pub revision_advanced: bool,
    /// Known search changes for query responses; absent for conservative refreshes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub search_changed_buckets: Option<std::collections::BTreeSet<String>>,
    /// Entity keys whose records changed.
    pub changed: Vec<String>,
    /// Registered operation ids affected by the change (origin excluded).
    pub affected_ops: Vec<String>,
    /// True when the identity witness wiped and rebound the cache before
    /// this write (silent restart).
    pub reset: bool,
    /// Queries to fetch after successful optimistic settlement.
    pub revalidations: Vec<QueryRevalidation>,
    /// Stable caller identity on settlement.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mutation_uuid: Option<String>,
}

/// Internal hydration result used to fan out changes before returning only
/// the caller-visible projection across IPC.
pub struct HydrationWriteResultWire {
    /// Displayed windows proven unchanged by complete engine journal evidence.
    pub unchanged_views: Vec<String>,
    /// Quick Access buckets changed by hydration.
    pub search_changed_buckets: std::collections::BTreeSet<String>,
    /// Cache changes required for host notifications.
    pub write_result: WriteResultWire,
    /// Fields not marked `@cacheOnly`, or `None` when there are none.
    pub data: Option<serde_json::Value>,
}

/// Revision-qualified normalized record selection result.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RecordSelectionResultWire {
    /// Revision observed by record selection.
    pub revision: String,
    /// Selected normalized records.
    pub records: Vec<SelectedRecord>,
}

/// Revision-qualified affected operation ids.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AffectedOperationsResultWire {
    /// Revision installed by the invalidation or deletion.
    pub revision: String,
    /// Registered operation ids affected by the change.
    pub affected_ops: Vec<String>,
}

/// Result of durably enqueueing an optimistic mutation and attempting to
/// claim the strict queue head.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct EnqueueOptimisticMutationResultWire {
    /// Engine-assigned id; settle with commit/rollback. A string because JS
    /// numbers lose precision past 2^53 (same as the wasm shell).
    pub transaction_id: String,
    /// How the caller UUID changed the queue.
    pub upsert_kind: MutationUpsertKindWire,
    /// Visible composed-view changes caused by the new optimistic layer.
    #[serde(flatten)]
    pub result: WriteResultWire,
    /// Claim outcome determined before cache-change events are emitted.
    pub initial_claim: InitialMutationClaimWire,
}

/// Queue collision outcome serialized for the webview.
#[derive(Debug, Serialize)]
#[serde(
    tag = "kind",
    rename_all = "kebab-case",
    rename_all_fields = "camelCase"
)]
pub enum MutationUpsertKindWire {
    /// A new UUID was appended.
    Inserted,
    /// A pending row was removed and replaced at the tail.
    ReplacedPending {
        /// Removed queue transaction.
        removed_transaction_id: String,
    },
    /// A live row was retained and superseded.
    AppendedAfterActive {
        /// Still-active queue transaction.
        active_transaction_id: String,
    },
}

impl From<MutationUpsertKind> for MutationUpsertKindWire {
    fn from(kind: MutationUpsertKind) -> Self {
        match kind {
            MutationUpsertKind::Inserted => Self::Inserted,
            MutationUpsertKind::ReplacedPending { removed_id } => Self::ReplacedPending {
                removed_transaction_id: removed_id.to_string(),
            },
            MutationUpsertKind::AppendedAfterActive { active_id } => Self::AppendedAfterActive {
                active_transaction_id: active_id.to_string(),
            },
        }
    }
}

/// Tagged outcome of the initial strict-head claim attempt.
#[derive(Debug, Serialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
pub enum InitialMutationClaimWire {
    /// The strict queue head was durably leased.
    Claimed {
        /// Mutation request and lease metadata for the claimed head.
        mutation: ClaimedMutationWire,
    },
    /// The queue head is currently leased, deferred, or absent.
    NotRunnable,
    /// Enqueue succeeded, but the claim attempt failed.
    Failed {
        /// Diagnostic claim error.
        error: String,
    },
}

/// Claimed queue head returned to the JavaScript mutation runner.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ClaimedMutationWire {
    /// Opaque client correlation restored from the durable source.
    pub client_metadata: Option<serde_json::Value>,
    /// Durable mutation id.
    pub transaction_id: String,
    /// Caller coalescing UUID.
    pub uuid: String,
    /// Whether a newer current row superseded this request.
    pub superseded: bool,
    /// Whether settlement must recover a server identity before a replacement runs.
    pub requires_confirmation: bool,
    /// Claim generation required for settlement.
    pub lease_generation: String,
    /// GraphQL mutation document.
    pub query: String,
    /// Selected operation name.
    pub operation_name: Option<String>,
    /// Variables parsed from their durable canonical JSON representation.
    pub variables: serde_json::Value,
    /// Identity witness captured when the mutation was enqueued.
    pub identity: Option<String>,
    /// Number of network attempts including this claim.
    pub attempt_count: u32,
    /// Retryable server failures, excluding transport failures.
    pub server_failure_count: u32,
}

/// Tagged result of deferring or discarding a failed queue attempt.
#[derive(Debug, Serialize)]
#[serde(
    tag = "kind",
    rename_all = "kebab-case",
    rename_all_fields = "camelCase"
)]
pub enum DeferOptimisticWriteResultWire {
    /// Retry state was retained normally.
    Deferred,
    /// A superseded row was discarded instead of retried.
    DiscardedSuperseded {
        /// Current transaction carrying the newer intent.
        replacement_transaction_id: String,
        /// Cache changes caused by discarding the old layer.
        #[serde(flatten)]
        result: WriteResultWire,
    },
}

/// Tagged result of committing a current or superseded queue attempt.
#[derive(Debug, Serialize)]
#[serde(
    tag = "kind",
    rename_all = "kebab-case",
    rename_all_fields = "camelCase"
)]
pub enum CommitOptimisticWriteResultWire {
    /// Invalid response identity data permanently failed this attempt.
    Failed {
        /// Diagnostic for the cache error handler.
        error: String,
        /// Newer intent preserved when this attempt was superseded.
        #[serde(skip_serializing_if = "Option::is_none")]
        replacement_transaction_id: Option<String>,
        /// Cache changes caused by discarding the failed layer.
        #[serde(flatten)]
        result: WriteResultWire,
    },
    /// The current mutation committed normally.
    Committed {
        /// Cache changes caused by commit.
        #[serde(flatten)]
        result: WriteResultWire,
    },
    /// The response committed beneath a newer optimistic replacement.
    CommittedSuperseded {
        /// Current transaction carrying the newer intent.
        replacement_transaction_id: String,
        /// Cache changes caused by commit.
        #[serde(flatten)]
        result: WriteResultWire,
    },
}

/// Tagged result of permanently failing or superseding a queue attempt.
#[derive(Debug, Serialize)]
#[serde(
    tag = "kind",
    rename_all = "kebab-case",
    rename_all_fields = "camelCase"
)]
pub enum RollbackOptimisticWriteResultWire {
    /// The current mutation permanently failed.
    RolledBack {
        /// Cache changes caused by rollback.
        #[serde(flatten)]
        result: WriteResultWire,
    },
    /// A superseded attempt was accepted and discarded.
    DiscardedSuperseded {
        /// Current transaction carrying the newer intent.
        replacement_transaction_id: String,
        /// Cache changes caused by discarding the old layer.
        #[serde(flatten)]
        result: WriteResultWire,
    },
}

impl TryFrom<ClaimedMutation> for ClaimedMutationWire {
    type Error = String;

    fn try_from(claimed: ClaimedMutation) -> Result<Self, Self::Error> {
        let requires_confirmation = claimed.queued.requires_confirmation();
        let client_metadata = cache_core::queue::decode_optimistic_source(
            &claimed.queued.optimistic.optimistic_data_json,
        )?
        .client_metadata;
        let request = claimed.queued.mutation.request;
        Ok(Self {
            client_metadata,
            transaction_id: claimed.queued.id.to_string(),
            uuid: claimed.queued.uuid.to_string(),
            superseded: claimed.queued.superseded,
            requires_confirmation,
            lease_generation: claimed.lease_generation.to_string(),
            query: request.query,
            operation_name: request.operation_name,
            variables: serde_json::from_str(&request.variables_json).map_err(|e| e.to_string())?,
            identity: request.identity,
            attempt_count: claimed.queued.mutation.attempt_count,
            server_failure_count: claimed.queued.mutation.server_failure_count,
        })
    }
}

/// Interns host-side string operation ids to engine `u64` ids.
#[derive(Default)]
struct OpInterner {
    by_name: HashMap<String, OpId>,
    by_id: HashMap<OpId, String>,
    next: OpId,
}

impl OpInterner {
    fn intern(&mut self, name: &str) -> OpId {
        if let Some(id) = self.by_name.get(name) {
            return *id;
        }
        self.next += 1;
        let id = self.next;
        self.by_name.insert(name.to_string(), id);
        self.by_id.insert(id, name.to_string());
        id
    }

    fn remove(&mut self, name: &str) -> Option<OpId> {
        let id = self.by_name.remove(name)?;
        self.by_id.remove(&id);
        Some(id)
    }

    fn names(&self, ids: impl IntoIterator<Item = OpId>) -> Vec<String> {
        ids.into_iter()
            .filter_map(|id| self.by_id.get(&id).cloned())
            .collect()
    }
}

type Variables = serde_json::Map<String, serde_json::Value>;

/// Optional active-query registration installed by a network write.
pub struct WriteRegistration {
    /// Host operation id.
    pub op_id: String,
    /// Synthetic read relations used by the query.
    pub entity_resolvers: Vec<EntityResolver>,
}

/// Owned inputs for a network response write.
pub struct WriteRequest {
    /// Origin operation excluded from immediate invalidation.
    pub origin_op_id: Option<String>,
    /// Active query registration to install.
    pub registration: Option<WriteRegistration>,
    /// GraphQL document.
    pub query: String,
    /// Selected operation name.
    pub operation_name: Option<String>,
    /// Operation variables.
    pub variables: Variables,
    /// GraphQL response data.
    pub data: serde_json::Value,
    /// Opaque identity witness.
    pub identity: Option<String>,
}

struct EngineState {
    engine: Engine<TursoStorage>,
    ops: OpInterner,
    selections: RecordSelectionCache,
}

/// Cheaply-clonable handle to the shared engine. Foreground methods serialize
/// through the async mutex. Hydration yields and refetches when superseded.
/// Errors are stringified for the IPC boundary
/// (the JS host rejects the pending call, and the exchange degrades to the
/// network).
#[derive(Clone)]
pub struct EngineHandle {
    inner: Arc<EngineAccess<EngineState>>,
    // Shared by cloned handles, changed when the native engine is reopened.
    // Revisions alone may repeat across process restarts.
    mail_generation: String,
}

fn wire_write_result(ops: &OpInterner, result: WriteResult) -> WriteResultWire {
    WriteResultWire {
        unchanged_views: None,
        field_changes: result.field_changes,
        identity_errors: result.identity_errors,
        revision: result.revision.to_string(),
        revision_advanced: result.revision_advanced,
        search_changed_buckets: result.search_changed_buckets,
        changed: result
            .changed
            .into_iter()
            .map(|key| key.0.into_owned())
            .collect(),
        affected_ops: ops.names(result.affected_ops),
        reset: result.reset,
        revalidations: result.revalidations,
        mutation_uuid: result.mutation_uuid,
    }
}

fn parse_u64(value: &str, label: &str) -> Result<u64, String> {
    value
        .parse::<u64>()
        .map_err(|_| format!("invalid {label} `{value}`"))
}

fn parse_transaction_id(id: &str) -> Result<u64, String> {
    parse_u64(id, "optimistic transaction id")
}

impl EngineHandle {
    /// Wraps an opened storage backend. A `hot_capacity` of 0 is treated as
    /// unset (engine default).
    pub fn new(storage: TursoStorage, hot_capacity: Option<u32>) -> Self {
        Self::with_schema(storage, hot_capacity, cache_core::meta::bundled_schema())
    }

    /// Constructs the native engine with metadata loaded from its frontend bundle.
    pub fn with_schema(
        storage: TursoStorage,
        hot_capacity: Option<u32>,
        schema: Arc<cache_core::meta::Schema>,
    ) -> Self {
        let engine = Engine::with_schema(
            storage,
            hot_capacity
                .filter(|c| *c > 0)
                .map_or(cache_core::engine::DEFAULT_HOT_CAPACITY, |c| c as usize),
            schema,
        );
        EngineHandle {
            mail_generation: soup_filter_cache_adapter::mail::new_generation(),
            inner: Arc::new(EngineAccess::new(EngineState {
                engine,
                ops: OpInterner::default(),
                selections: RecordSelectionCache::default(),
            })),
        }
    }

    /// Consumes the sole handle and explicitly closes native Turso storage.
    pub fn shutdown(self) -> Result<(), String> {
        let mutex = Arc::try_unwrap(self.inner)
            .map_err(|_| "graphql cache still has active command handles".to_string())?;
        let state = mutex.into_inner();
        let outcome = state
            .engine
            .into_storage()
            .try_close()
            .map_err(|error| error.to_string())?;
        match outcome {
            TursoStorageCloseOutcome::Healthy | TursoStorageCloseOutcome::ResetRequired(_) => {
                Ok(())
            }
        }
    }

    /// Returns the current in-memory cache revision.
    pub async fn current_revision(&self) -> CacheRevision {
        self.inner.lock().await.engine.current_revision()
    }

    /// Returns the durable cache generation, initializing it when absent.
    pub async fn current_storage_generation(&self) -> Result<String, String> {
        self.inner
            .lock()
            .await
            .engine
            .current_storage_generation()
            .await
            .map(|generation| generation.to_string())
            .map_err(|error| error.to_string())
    }

    /// Validates and persists compatible metadata before publishing it to native operations.
    pub async fn install_schema(
        &self,
        schema: &cache_core::meta::Schema,
        path: &std::path::Path,
    ) -> Result<(), String> {
        let mut state = self.inner.lock().await;
        let merged = state
            .engine
            .schema()
            .merge(schema)
            .map_err(|e| e.to_string())?;
        persist_schema(path, &merged)?;
        state
            .engine
            .install_schema(&merged)
            .map_err(|e| e.to_string())
    }

    /// Cache read; registers `op_id` as active when given.
    #[tracing::instrument(name = "graphql_cache.native.read", skip_all, err)]
    pub async fn read(
        &self,
        op_id: Option<String>,
        query: String,
        operation_name: Option<String>,
        variables: Variables,
        entity_resolvers: Vec<EntityResolver>,
    ) -> Result<ReadResultWire, String> {
        let mut state = self.inner.lock().await;
        let EngineState { engine, ops, .. } = &mut *state;
        let op = op_id.map(|name| ops.intern(&name));
        engine
            .read_query_with_entity_resolvers(
                op,
                &query,
                operation_name.as_deref(),
                &variables,
                &entity_resolvers,
            )
            .await
            .map(|result| match result {
                ReadResult::Hit { data } => ReadResultWire::Hit { data },
                ReadResult::Miss => ReadResultWire::Miss,
            })
            .map_err(|e| e.to_string())
    }

    /// Incrementally project a query; operation teardown releases its bindings.
    #[tracing::instrument(name = "graphql_cache.native.watch", skip_all, err)]
    pub async fn watch(
        &self,
        op_id: String,
        query: String,
        operation_name: Option<String>,
        variables: Variables,
        entity_resolvers: Vec<EntityResolver>,
        since: Option<String>,
    ) -> Result<cache_core::engine::watch_query::QueryUpdate, String> {
        let since = since
            .map(|value| value.parse::<CacheRevision>())
            .transpose()
            .map_err(|error| error.to_string())?;
        let mut state = self.inner.lock().await;
        let EngineState { engine, ops, .. } = &mut *state;
        let op = ops.intern(&op_id);
        engine
            .watch_query(
                op,
                &query,
                operation_name.as_deref(),
                &variables,
                &entity_resolvers,
                since,
            )
            .await
            .map_err(|error| error.to_string())
    }

    /// Projects explicit normalized entity keys without scanning storage.
    pub async fn read_records_by_keys(
        &self,
        document: String,
        fragment_name: String,
        keys: Vec<String>,
    ) -> Result<RecordSelectionResultWire, String> {
        let mut state = self.inner.lock().await;
        let schema = state.engine.schema_snapshot();
        let selection = state
            .selections
            .get(&schema, document, fragment_name)
            .map_err(|error| error.to_string())?;
        let keys: Vec<_> = keys.into_iter().map(|key| EntityKey(key.into())).collect();
        state
            .engine
            .read_records_by_keys(&selection, &keys)
            .await
            .map(|result| RecordSelectionResultWire {
                revision: result.revision.to_string(),
                records: result.value,
            })
            .map_err(|error| error.to_string())
    }

    /// Searches the compact materialized projection without record scans.
    pub async fn search(&self, request: SearchRequest) -> Result<SearchPage, String> {
        self.inner
            .lock()
            .await
            .engine
            .search(&request)
            .await
            .map_err(|error| error.to_string())
    }

    /// Evaluates a Soup predicate or a cached Mail page.
    pub async fn entity_filter(
        &self,
        request: EntityFilterRequest,
    ) -> Result<EntityFilterResult, String> {
        let mut state = self.inner.lock().await;
        let state = &mut *state;
        soup::filter(
            &mut state.engine,
            &mut state.selections,
            &self.mail_generation,
            request,
        )
        .await
    }

    /// Reads a retained live view, atomically checking its specification identity.
    pub async fn resume_entity_filter(
        &self,
        id: String,
        registration_id: cache_core::engine::live_query::LiveQueryRegistration,
        since: Option<String>,
    ) -> Result<Option<soup::LiveQueryResult>, String> {
        let since = since
            .map(|revision| revision.parse())
            .transpose()
            .map_err(|error: cache_core::revision::ParseCacheRevisionError| error.to_string())?;
        self.inner
            .lock()
            .await
            .engine
            .resume_live_query(&id, registration_id, since)
            .await
            .map(|update| update.map(|update| soup::LiveQueryResult::LiveQuery { update }))
            .map_err(|error| error.to_string())
    }

    /// Recovers cached query variables without materializing each variant.
    pub async fn inspect_query_variants(
        &self,
        query: String,
        operation_name: Option<String>,
        path: Vec<String>,
    ) -> Result<Vec<CachedQueryVariant>, String> {
        self.inner
            .lock()
            .await
            .engine
            .inspect_query_variants(&QueryInspection {
                query,
                operation_name,
                path,
                variable_filters: Vec::new(),
            })
            .await
            .map_err(|error| error.to_string())
    }

    /// Enumerates and materializes cached variants of one generated query field.
    pub async fn inspect_query(
        &self,
        query: String,
        operation_name: Option<String>,
        path: Vec<String>,
        variable_filters: Vec<serde_json::Map<String, serde_json::Value>>,
    ) -> Result<Vec<CachedQueryInstance>, String> {
        self.inner
            .lock()
            .await
            .engine
            .inspect_query(&QueryInspection {
                query,
                operation_name,
                path,
                variable_filters,
            })
            .await
            .map_err(|error| error.to_string())
    }

    /// Normalizes and stores a network response.
    #[tracing::instrument(name = "graphql_cache.native.write", skip_all, err)]
    pub async fn write(&self, request: WriteRequest) -> Result<WriteResultWire, String> {
        let WriteRequest {
            origin_op_id,
            registration,
            query,
            operation_name,
            variables,
            data,
            identity,
        } = request;
        let mut state = self.inner.write().await;
        let EngineState { engine, ops, .. } = &mut *state;
        let origin = origin_op_id.map(|name| ops.intern(&name));
        let registration = registration.map(|registration| {
            let op_id = ops.intern(&registration.op_id);
            (op_id, registration.entity_resolvers)
        });
        let projections = soup::write_projections(
            engine,
            &query,
            operation_name.as_deref(),
            &variables,
            &data,
            identity.as_deref(),
        )
        .await?;
        engine
            .write_query_with_registration_and_projections(
                origin,
                registration
                    .as_ref()
                    .map(|(op_id, entity_resolvers)| QueryRegistration {
                        op_id: *op_id,
                        entity_resolvers,
                    }),
                NetworkWrite {
                    query: &query,
                    operation_name: operation_name.as_deref(),
                    variables: &variables,
                    data: &data,
                    identity: identity.as_deref(),
                },
                projections,
            )
            .await
            .map(|result| wire_write_result(ops, result))
            .map_err(|e| e.to_string())
    }

    /// Stores a query response and returns only fields not marked
    /// `@cacheOnly`.
    #[tracing::instrument(name = "graphql_cache.native.hydrate_query", skip_all, err)]
    pub async fn hydrate_query(
        &self,
        query: String,
        operation_name: Option<String>,
        variables: Variables,
        data: serde_json::Value,
        identity: Option<String>,
    ) -> Result<HydrationWriteResultWire, String> {
        let mut state = self.inner.hydrate().await?;
        let EngineState { engine, ops, .. } = &mut *state;
        let projections = soup::write_projections(
            engine,
            &query,
            operation_name.as_deref(),
            &variables,
            &data,
            identity.as_deref(),
        )
        .await?;
        let result = engine
            .hydrate_query_with_projections(
                &query,
                operation_name.as_deref(),
                &variables,
                &data,
                identity.as_deref(),
                projections,
            )
            .await
            .map_err(|error| error.to_string())?;
        // Invalidation evidence is optional: a failed proof must not reject a committed hydration.
        let unchanged_views = engine
            .unchanged_observed_windows()
            .await
            .unwrap_or_default();
        Ok(HydrationWriteResultWire {
            unchanged_views,
            search_changed_buckets: result.search_changed_buckets,
            write_result: wire_write_result(ops, result.write_result),
            data: result.data,
        })
    }

    /// Durably queues a mutation and its optimistic layer, then attempts to
    /// claim the strict queue head while retaining the same engine lock.
    #[allow(clippy::too_many_arguments)]
    pub async fn enqueue_optimistic_mutation(
        &self,
        origin_op_id: Option<String>,
        uuid: String,
        query: String,
        operation_name: Option<String>,
        variables: Variables,
        data: serde_json::Value,
        link_patches: Vec<OptimisticLinkPatch>,
        revalidations: Vec<QueryRevalidation>,
        identity_bindings: Vec<cache_core::identity::IdentityBinding>,
        created_at_ms: i64,
        lease_owner: String,
        now_ms: i64,
        lease_expires_at_ms: i64,
        client_metadata: Option<serde_json::Value>,
        uncertain_calendar_event_keys: Vec<String>,
    ) -> Result<EnqueueOptimisticMutationResultWire, String> {
        let mut state = self.inner.write().await;
        let EngineState { engine, ops, .. } = &mut *state;
        let origin = origin_op_id.map(|name| ops.intern(&name));
        let projections = soup::optimistic_projections(
            engine,
            &query,
            operation_name.as_deref(),
            &variables,
            &data,
            created_at_ms,
        )
        .await?;
        let result = engine
            .enqueue_optimistic_mutation_with_calendar(
                origin,
                BeginOptimisticWrite {
                    client_metadata: client_metadata.as_ref(),
                    uuid: &uuid,
                    query: &query,
                    operation_name: operation_name.as_deref(),
                    variables: &variables,
                    data: &data,
                    link_patches: &link_patches,
                    revalidations: &revalidations,
                    created_at_ms,
                    identity_bindings: &identity_bindings,
                },
                MutationClaimRequest {
                    owner: lease_owner,
                    now_ms,
                    lease_expires_at_ms,
                },
                projections,
                uncertain_calendar_event_keys
                    .into_iter()
                    .map(|key| EntityKey(key.into()))
                    .collect(),
            )
            .await
            .map_err(|error| error.to_string())?;
        let initial_claim = match result.initial_claim {
            InitialClaimOutcome::Claimed(claimed) => InitialMutationClaimWire::Claimed {
                mutation: ClaimedMutationWire::try_from(*claimed)?,
            },
            InitialClaimOutcome::NotRunnable => InitialMutationClaimWire::NotRunnable,
            InitialClaimOutcome::Failed(error) => InitialMutationClaimWire::Failed {
                error: error.to_string(),
            },
        };
        Ok(EnqueueOptimisticMutationResultWire {
            transaction_id: result.transaction_id.to_string(),
            upsert_kind: result.upsert_kind.into(),
            result: wire_write_result(ops, result.write_result),
            initial_claim,
        })
    }

    /// Reads queued operations without acquiring their leases.
    pub async fn inspect_mutations(
        &self,
    ) -> Result<Vec<cache_core::queue::MutationInspection>, String> {
        let state = self.inner.lock().await;
        state
            .engine
            .inspect_mutations()
            .await
            .map_err(|error| error.to_string())
    }

    /// Claims the strict mutation queue head when it is runnable.
    pub async fn claim_next_mutation(
        &self,
        owner: String,
        now_ms: i64,
        lease_expires_at_ms: i64,
    ) -> Result<Option<ClaimedMutationWire>, String> {
        let mut state = self.inner.lock().await;
        state
            .engine
            .claim_next_mutation(MutationClaimRequest {
                owner,
                now_ms,
                lease_expires_at_ms,
            })
            .await
            .map_err(|e| e.to_string())?
            .map(ClaimedMutationWire::try_from)
            .transpose()
    }

    /// Retains a retryable mutation and releases its claim.
    pub async fn defer_optimistic_write(
        &self,
        transaction_id: String,
        lease_owner: String,
        lease_generation: String,
        next_attempt_at_ms: i64,
        error: String,
        server_failure: bool,
    ) -> Result<DeferOptimisticWriteResultWire, String> {
        let transaction = parse_transaction_id(&transaction_id)?;
        let claim = MutationClaimToken {
            owner: lease_owner,
            generation: parse_u64(&lease_generation, "lease generation")?,
        };
        let mut state = self.inner.lock().await;
        let EngineState { engine, ops, .. } = &mut *state;
        match engine
            .defer_optimistic_write(
                transaction,
                claim,
                next_attempt_at_ms,
                error,
                server_failure,
            )
            .await
            .map_err(|e| e.to_string())?
        {
            DeferOptimisticWriteResult::Deferred => Ok(DeferOptimisticWriteResultWire::Deferred),
            DeferOptimisticWriteResult::DiscardedSuperseded(result) => {
                Ok(DeferOptimisticWriteResultWire::DiscardedSuperseded {
                    replacement_transaction_id: result.replacement_transaction_id.to_string(),
                    result: wire_write_result(ops, result.write_result),
                })
            }
        }
    }

    /// Replaces a claimed optimistic layer with the real network response.
    pub async fn commit_optimistic_write(
        &self,
        transaction_id: String,
        lease_owner: String,
        lease_generation: String,
        query: String,
        operation_name: Option<String>,
        variables: Variables,
        data: serde_json::Value,
    ) -> Result<CommitOptimisticWriteResultWire, String> {
        let transaction = parse_transaction_id(&transaction_id)?;
        let claim = MutationClaimToken {
            owner: lease_owner,
            generation: parse_u64(&lease_generation, "lease generation")?,
        };
        let mut state = self.inner.write().await;
        let EngineState { engine, ops, .. } = &mut *state;
        let projections = soup::write_projections(
            engine,
            &query,
            operation_name.as_deref(),
            &variables,
            &data,
            None,
        )
        .await?;
        match engine
            .commit_optimistic_write_with_projections_outcome(
                transaction,
                claim,
                &query,
                operation_name.as_deref(),
                &variables,
                &data,
                projections,
            )
            .await
            .map_err(|e| e.to_string())?
        {
            CommitOptimisticWriteResult::Failed(result) => {
                Ok(CommitOptimisticWriteResultWire::Failed {
                    error: result.error,
                    replacement_transaction_id: result
                        .replacement_transaction_id
                        .map(|id| id.to_string()),
                    result: wire_write_result(ops, result.write_result),
                })
            }
            CommitOptimisticWriteResult::Committed(result) => {
                Ok(CommitOptimisticWriteResultWire::Committed {
                    result: wire_write_result(ops, result),
                })
            }
            CommitOptimisticWriteResult::CommittedSuperseded(result) => {
                Ok(CommitOptimisticWriteResultWire::CommittedSuperseded {
                    replacement_transaction_id: result.replacement_transaction_id.to_string(),
                    result: wire_write_result(ops, result.write_result),
                })
            }
        }
    }

    /// Permanently fails a claimed mutation and drops its optimistic layer.
    pub async fn rollback_optimistic_write(
        &self,
        transaction_id: String,
        lease_owner: String,
        lease_generation: String,
    ) -> Result<RollbackOptimisticWriteResultWire, String> {
        let transaction = parse_transaction_id(&transaction_id)?;
        let claim = MutationClaimToken {
            owner: lease_owner,
            generation: parse_u64(&lease_generation, "lease generation")?,
        };
        let mut state = self.inner.write().await;
        let EngineState { engine, ops, .. } = &mut *state;
        match engine
            .rollback_optimistic_write_with_outcome(transaction, claim)
            .await
            .map_err(|e| e.to_string())?
        {
            RollbackOptimisticWriteResult::RolledBack(result) => {
                Ok(RollbackOptimisticWriteResultWire::RolledBack {
                    result: wire_write_result(ops, result),
                })
            }
            RollbackOptimisticWriteResult::DiscardedSuperseded(result) => {
                Ok(RollbackOptimisticWriteResultWire::DiscardedSuperseded {
                    replacement_transaction_id: result.replacement_transaction_id.to_string(),
                    result: wire_write_result(ops, result.write_result),
                })
            }
        }
    }

    /// Evicts records by entity key; returns the affected registered op ids.
    pub async fn invalidate(
        &self,
        keys: Vec<String>,
    ) -> Result<AffectedOperationsResultWire, String> {
        let mut state = self.inner.write().await;
        let EngineState { engine, ops, .. } = &mut *state;
        let projections = soup::invalidation_projections(engine, &keys).await?;
        let keys: Vec<EntityKey<'static>> =
            keys.into_iter().map(|key| EntityKey(key.into())).collect();
        let affected = engine
            .invalidate_keys_with_projections(&keys, projections)
            .await
            .map_err(|error| error.to_string())?;
        Ok(AffectedOperationsResultWire {
            revision: affected.revision.to_string(),
            affected_ops: ops.names(affected.value),
        })
    }

    /// Deletes stale records from durable and hot storage and returns the
    /// registered operations that traversed them.
    pub async fn delete_records(
        &self,
        keys: Vec<String>,
    ) -> Result<AffectedOperationsResultWire, String> {
        let mut state = self.inner.write().await;
        let EngineState { engine, ops, .. } = &mut *state;
        let projections = soup::deletion_projections(engine, &keys).await?;
        let keys: Vec<EntityKey<'static>> =
            keys.into_iter().map(|key| EntityKey(key.into())).collect();
        let affected = engine
            .delete_keys_with_projection_changes(&keys, projections)
            .await
            .map_err(|e| e.to_string())?;
        Ok(AffectedOperationsResultWire {
            revision: affected.revision.to_string(),
            affected_ops: ops.names(affected.value),
        })
    }

    /// Unregisters an operation (urql teardown).
    pub async fn teardown(&self, op_id: String) -> Result<(), String> {
        let mut state = self.inner.lock().await;
        let EngineState { engine, ops, .. } = &mut *state;
        if let Some(id) = ops.remove(&op_id) {
            engine.teardown_operation(id);
        }
        Ok(())
    }

    /// Drops all cached state (logout).
    pub async fn clear(&self) -> Result<CacheRevision, String> {
        let mut state = self.inner.write().await;
        state.engine.clear().await.map_err(|e| e.to_string())
    }
}

#[cfg(test)]
mod test;

/// Atomically persists metadata separately from user records; no database reset occurs.
pub(crate) fn persist_schema(
    path: &std::path::Path,
    schema: &cache_core::meta::Schema,
) -> Result<(), String> {
    let bytes = serde_json::to_vec(schema.artifact()).map_err(|e| e.to_string())?;
    let temporary = path.with_extension("json.tmp");
    use std::io::Write;
    let mut file = std::fs::File::create(&temporary).map_err(|e| e.to_string())?;
    file.write_all(&bytes).map_err(|e| e.to_string())?;
    file.sync_all().map_err(|e| e.to_string())?;
    drop(file);
    std::fs::rename(&temporary, path).map_err(|e| e.to_string())?;
    #[cfg(unix)]
    if let Some(parent) = path.parent() {
        std::fs::File::open(parent)
            .and_then(|dir| dir.sync_all())
            .map_err(|e| e.to_string())?;
    }
    Ok(())
}