Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

54.7 KB
Raw Blame
use super::abi::*;
use super::config::DynamicProviderConfig;
use super::loader;
use crate::cache_runtime::provider::{CacheOperation, CacheProvider};
use crate::cache_runtime::{
    CacheError, CacheResult, Expiration, ListDirection, ListInsertPosition, ListInsertRequest,
    ListMoveRequest, ScriptRegistry, ScriptRequest, ScriptResult, ScriptValue, SetCondition,
    SetOptions, SetResult,
};
use async_trait::async_trait;
use bytes::Bytes;
use libloading::Library;
use std::alloc::{alloc, dealloc, Layout};
use std::collections::HashMap;
use std::ffi::c_void;
use std::mem::size_of;
use std::ptr;
use std::slice;
use std::sync::atomic::{AtomicU8, Ordering};
use std::sync::{Arc, Mutex, OnceLock, RwLock};

const LIFECYCLE_OPEN: u8 = 0;
const LIFECYCLE_CLOSING: u8 = 1;
const LIFECYCLE_CLOSED: u8 = 2;
const MAX_HOST_ALLOCATION_BYTES: usize = 128 * 1024 * 1024;
const MAX_BUFFER_BYTES: usize = 64 * 1024 * 1024;
const MAX_ERROR_BYTES: usize = 64 * 1024;
const MAX_ARRAY_ITEMS: usize = 100_000;
const MAX_AGGREGATE_BYTES: usize = 128 * 1024 * 1024;
const MAX_SCRIPT_DEPTH: usize = 64;
const MAX_SCRIPT_NODES: usize = 100_000;

static HOST_API: HostApiV1 = HostApiV1 {
    abi_version: ABI_VERSION_V1,
    struct_size: size_of::<HostApiV1>(),
    alloc: host_alloc,
    dealloc: host_dealloc,
};

pub(crate) struct DynamicProvider {
    state: Arc<DynamicState>,
    scripts: Arc<ScriptRegistry>,
}

struct DynamicState {
    _library: Library,
    api: ProviderApiV1,
    handle: *mut c_void,
    calls: RwLock<()>,
    lifecycle: AtomicU8,
}

// The ABI requires the provider handle to support concurrent calls. A provider
// backed by a non-thread-safe SDK must serialize or pool internally.
unsafe impl Send for DynamicState {}
unsafe impl Sync for DynamicState {}

impl DynamicProvider {
    pub(crate) async fn connect(
        config: DynamicProviderConfig,
        scripts: Arc<ScriptRegistry>,
    ) -> CacheResult<Self> {
        let state = tokio::task::spawn_blocking(move || connect_state(config))
            .await
            .map_err(|error| {
                CacheError::Internal(format!("dynamic provider create task failed: {error}"))
            })??;
        let provider = Self { state, scripts };
        if let Err(error) = provider.ping().await {
            let _ = provider.close().await;
            return Err(error);
        }
        Ok(provider)
    }

    async fn call<T, F>(&self, operation: &'static str, call: F) -> CacheResult<T>
    where
        T: Send + 'static,
        F: FnOnce(&DynamicState) -> CacheResult<T> + Send + 'static,
    {
        let state = Arc::clone(&self.state);
        tokio::task::spawn_blocking(move || call(&state))
            .await
            .map_err(|error| {
                CacheError::Internal(format!("dynamic provider {operation} task failed: {error}"))
            })?
    }

    async fn list_push(
        &self,
        operation: CacheOperation,
        key: &str,
        values: Vec<Bytes>,
    ) -> CacheResult<u64> {
        if values.is_empty() {
            return Err(CacheError::InvalidArgument(format!(
                "{} requires at least one value",
                operation.name()
            )));
        }
        let key = key.to_string();
        self.call(operation.name(), move |state| {
            state.with_call(operation.name(), |api, handle| {
                let callback = match operation {
                    CacheOperation::Lpush => required(api.lpush, operation)?,
                    CacheOperation::Rpush => required(api.rpush, operation)?,
                    _ => unreachable!("list_push only accepts push operations"),
                };
                let raw_values = byte_slices(&values);
                let mut length = 0;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        raw_values.as_ptr(),
                        raw_values.len(),
                        &mut length,
                        &mut error,
                    )
                };
                status_result(status, error, operation.name())?;
                Ok(length)
            })
        })
        .await
    }

    async fn list_pop(
        &self,
        operation: CacheOperation,
        key: &str,
        count: Option<u64>,
    ) -> CacheResult<Vec<Bytes>> {
        let key = key.to_string();
        self.call(operation.name(), move |state| {
            state.with_call(operation.name(), |api, handle| {
                let callback = match operation {
                    CacheOperation::Lpop => required(api.lpop, operation)?,
                    CacheOperation::Rpop => required(api.rpop, operation)?,
                    _ => unreachable!("list_pop only accepts pop operations"),
                };
                let mut output = OwnedBufferArrayV1::default();
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        u8::from(count.is_some()),
                        count.unwrap_or_default(),
                        &mut output,
                        &mut error,
                    )
                };
                take_output(
                    status,
                    error,
                    operation.name(),
                    output,
                    take_buffer_array,
                    discard_buffer_array,
                )
            })
        })
        .await
    }
}

fn connect_state(config: DynamicProviderConfig) -> CacheResult<Arc<DynamicState>> {
    let loaded = loader::load(&config.library_path)?;
    let create = loaded.api.create.expect("validated create callback");
    let mut handle = ptr::null_mut();
    let mut error = OwnedBufferV1::default();
    let params = ByteSliceV1::from_slice(config.params_json.as_bytes());
    let status = unsafe { create(&HOST_API, params, &mut handle, &mut error) };
    if let Err(error) = status_result(status, error, "create") {
        if !handle.is_null() {
            close_handle(loaded.api, handle);
        }
        return Err(error);
    }
    if handle.is_null() {
        return Err(CacheError::InvalidData(
            "dynamic provider create returned a null handle".into(),
        ));
    }

    Ok(Arc::new(DynamicState {
        _library: loaded.library,
        api: loaded.api,
        handle,
        calls: RwLock::new(()),
        lifecycle: AtomicU8::new(LIFECYCLE_OPEN),
    }))
}

impl DynamicState {
    fn with_call<T>(
        &self,
        operation: &str,
        call: impl FnOnce(&ProviderApiV1, *mut c_void) -> CacheResult<T>,
    ) -> CacheResult<T> {
        let _guard = self
            .calls
            .read()
            .map_err(|_| CacheError::Internal("dynamic provider call lock poisoned".into()))?;
        if self.lifecycle.load(Ordering::Acquire) != LIFECYCLE_OPEN {
            return Err(CacheError::Closed);
        }
        call(&self.api, self.handle).map_err(|error| match error {
            CacheError::UnsupportedOperation(_) => {
                CacheError::UnsupportedOperation(operation.to_string())
            }
            other => other,
        })
    }

    fn supports(&self, operation: CacheOperation) -> bool {
        match operation {
            CacheOperation::Get => self.api.get.is_some(),
            CacheOperation::Set => self.api.set.is_some(),
            CacheOperation::Del => self.api.del.is_some(),
            CacheOperation::Mget => self.api.mget.is_some(),
            CacheOperation::Mset => self.api.mset.is_some(),
            CacheOperation::IncrBy => self.api.incrby.is_some(),
            CacheOperation::Sismember => self.api.sismember.is_some(),
            CacheOperation::Smembers => self.api.smembers.is_some(),
            CacheOperation::Scard => self.api.scard.is_some(),
            CacheOperation::Lpush => self.api.lpush.is_some(),
            CacheOperation::Rpush => self.api.rpush.is_some(),
            CacheOperation::Lpop => self.api.lpop.is_some(),
            CacheOperation::Rpop => self.api.rpop.is_some(),
            CacheOperation::Llen => self.api.llen.is_some(),
            CacheOperation::Lrange => self.api.lrange.is_some(),
            CacheOperation::Lindex => self.api.lindex.is_some(),
            CacheOperation::Lset => self.api.lset.is_some(),
            CacheOperation::Ltrim => self.api.ltrim.is_some(),
            CacheOperation::Lrem => self.api.lrem.is_some(),
            CacheOperation::Linsert => self.api.linsert.is_some(),
            CacheOperation::Lmove => self.api.lmove.is_some(),
            CacheOperation::ExecuteScript => self.api.execute_script.is_some(),
        }
    }

    fn ping(&self) -> CacheResult<()> {
        self.with_call("ping", |api, handle| {
            let callback = api.ping.expect("validated ping callback");
            let mut error = OwnedBufferV1::default();
            let status = unsafe { callback(handle, &mut error) };
            status_result(status, error, "ping")
        })
    }

    fn close(&self) -> CacheResult<()> {
        match self.lifecycle.compare_exchange(
            LIFECYCLE_OPEN,
            LIFECYCLE_CLOSING,
            Ordering::AcqRel,
            Ordering::Acquire,
        ) {
            Ok(_) => {}
            Err(state) if matches!(state, LIFECYCLE_CLOSING | LIFECYCLE_CLOSED) => return Ok(()),
            Err(other) => {
                return Err(CacheError::Internal(format!(
                    "dynamic provider has invalid lifecycle state {other}"
                )))
            }
        }
        let _guard = self
            .calls
            .write()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        let callback = self.api.close.expect("validated close callback");
        let mut error = OwnedBufferV1::default();
        let status = unsafe { callback(self.handle, &mut error) };
        self.lifecycle.store(LIFECYCLE_CLOSED, Ordering::Release);
        status_result(status, error, "close")
    }
}

impl Drop for DynamicState {
    fn drop(&mut self) {
        if self
            .lifecycle
            .compare_exchange(
                LIFECYCLE_OPEN,
                LIFECYCLE_CLOSING,
                Ordering::AcqRel,
                Ordering::Acquire,
            )
            .is_ok()
        {
            let _guard = self
                .calls
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            close_handle(self.api, self.handle);
            self.lifecycle.store(LIFECYCLE_CLOSED, Ordering::Release);
        }
    }
}

#[async_trait]
impl CacheProvider for DynamicProvider {
    fn validate_operations(&self, operations: &[CacheOperation]) -> CacheResult<()> {
        if let Some(operation) = operations
            .iter()
            .copied()
            .find(|operation| !self.state.supports(*operation))
        {
            return Err(CacheError::UnsupportedOperation(
                operation.name().to_string(),
            ));
        }
        Ok(())
    }

    async fn get(&self, key: &str) -> CacheResult<Option<Bytes>> {
        let key = key.to_string();
        self.call("get", move |state| {
            state.with_call("get", |api, handle| {
                let callback = required(api.get, CacheOperation::Get)?;
                let mut output = OptionalOwnedBufferV1::default();
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        &mut output,
                        &mut error,
                    )
                };
                take_output(
                    status,
                    error,
                    "get",
                    output,
                    take_optional_buffer,
                    discard_optional_buffer,
                )
            })
        })
        .await
    }

    async fn set(&self, key: &str, value: Bytes, options: SetOptions) -> CacheResult<SetResult> {
        if options.keep_ttl && options.expiration.is_some() {
            return Err(CacheError::InvalidArgument(
                "set cannot combine expiration with keep_ttl".into(),
            ));
        }
        let options = set_options(options)?;
        let key = key.to_string();
        self.call("set", move |state| {
            state.with_call("set", |api, handle| {
                let callback = required(api.set, CacheOperation::Set)?;
                let mut result = SET_APPLIED;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        ByteSliceV1::from_slice(&value),
                        options,
                        &mut result,
                        &mut error,
                    )
                };
                status_result(status, error, "set")?;
                match result {
                    SET_APPLIED => Ok(SetResult::Applied),
                    SET_CONDITION_NOT_MET => Ok(SetResult::ConditionNotMet),
                    other => Err(CacheError::InvalidData(format!(
                        "dynamic provider set returned invalid result {other}"
                    ))),
                }
            })
        })
        .await
    }

    async fn del(&self, keys: &[String]) -> CacheResult<u64> {
        if keys.is_empty() {
            return Ok(0);
        }
        let keys = keys.to_vec();
        self.call("del", move |state| {
            state.with_call("del", |api, handle| {
                let callback = required(api.del, CacheOperation::Del)?;
                let raw_keys = string_slices(&keys);
                let mut removed = 0;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        raw_keys.as_ptr(),
                        raw_keys.len(),
                        &mut removed,
                        &mut error,
                    )
                };
                status_result(status, error, "del")?;
                Ok(removed)
            })
        })
        .await
    }

    async fn mget(&self, keys: &[String]) -> CacheResult<Vec<Option<Bytes>>> {
        if keys.is_empty() {
            return Ok(Vec::new());
        }
        let keys = keys.to_vec();
        self.call("mget", move |state| {
            state.with_call("mget", |api, handle| {
                let callback = required(api.mget, CacheOperation::Mget)?;
                let raw_keys = string_slices(&keys);
                let mut output = OptionalOwnedBufferArrayV1::default();
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        raw_keys.as_ptr(),
                        raw_keys.len(),
                        &mut output,
                        &mut error,
                    )
                };
                let values = take_output(
                    status,
                    error,
                    "mget",
                    output,
                    take_optional_buffer_array,
                    discard_optional_buffer_array,
                )?;
                if values.len() != keys.len() {
                    return Err(CacheError::InvalidData(format!(
                        "dynamic provider mget returned {} values for {} keys",
                        values.len(),
                        keys.len()
                    )));
                }
                Ok(values)
            })
        })
        .await
    }

    async fn mset(&self, entries: Vec<(String, Bytes)>) -> CacheResult<()> {
        if entries.is_empty() {
            return Ok(());
        }
        self.call("mset", move |state| {
            state.with_call("mset", |api, handle| {
                let callback = required(api.mset, CacheOperation::Mset)?;
                let raw_entries = entries
                    .iter()
                    .map(|(key, value)| KeyValueV1 {
                        key: ByteSliceV1::from_slice(key.as_bytes()),
                        value: ByteSliceV1::from_slice(value),
                    })
                    .collect::<Vec<_>>();
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(handle, raw_entries.as_ptr(), raw_entries.len(), &mut error)
                };
                status_result(status, error, "mset")
            })
        })
        .await
    }

    async fn incr_by(&self, key: &str, delta: i64) -> CacheResult<i64> {
        let key = key.to_string();
        self.call("incrby", move |state| {
            state.with_call("incrby", |api, handle| {
                let callback = required(api.incrby, CacheOperation::IncrBy)?;
                let mut value = 0;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        delta,
                        &mut value,
                        &mut error,
                    )
                };
                status_result(status, error, "incrby")?;
                Ok(value)
            })
        })
        .await
    }

    async fn sismember(&self, key: &str, member: &[u8]) -> CacheResult<bool> {
        let key = key.to_string();
        let member = member.to_vec();
        self.call("sismember", move |state| {
            state.with_call("sismember", |api, handle| {
                let callback = required(api.sismember, CacheOperation::Sismember)?;
                let mut present = 0;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        ByteSliceV1::from_slice(&member),
                        &mut present,
                        &mut error,
                    )
                };
                status_result(status, error, "sismember")?;
                take_bool(present, "sismember")
            })
        })
        .await
    }

    async fn smembers(&self, key: &str) -> CacheResult<Vec<Bytes>> {
        let key = key.to_string();
        self.call("smembers", move |state| {
            state.with_call("smembers", |api, handle| {
                let callback = required(api.smembers, CacheOperation::Smembers)?;
                let mut output = OwnedBufferArrayV1::default();
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        &mut output,
                        &mut error,
                    )
                };
                take_output(
                    status,
                    error,
                    "smembers",
                    output,
                    take_buffer_array,
                    discard_buffer_array,
                )
            })
        })
        .await
    }

    async fn scard(&self, key: &str) -> CacheResult<u64> {
        scalar_u64(self, CacheOperation::Scard, key).await
    }

    async fn lpush(&self, key: &str, values: Vec<Bytes>) -> CacheResult<u64> {
        self.list_push(CacheOperation::Lpush, key, values).await
    }

    async fn rpush(&self, key: &str, values: Vec<Bytes>) -> CacheResult<u64> {
        self.list_push(CacheOperation::Rpush, key, values).await
    }

    async fn lpop(&self, key: &str, count: Option<u64>) -> CacheResult<Vec<Bytes>> {
        self.list_pop(CacheOperation::Lpop, key, count).await
    }

    async fn rpop(&self, key: &str, count: Option<u64>) -> CacheResult<Vec<Bytes>> {
        self.list_pop(CacheOperation::Rpop, key, count).await
    }

    async fn llen(&self, key: &str) -> CacheResult<u64> {
        scalar_u64(self, CacheOperation::Llen, key).await
    }

    async fn lrange(&self, key: &str, start: i64, stop: i64) -> CacheResult<Vec<Bytes>> {
        let key = key.to_string();
        self.call("lrange", move |state| {
            state.with_call("lrange", |api, handle| {
                let callback = required(api.lrange, CacheOperation::Lrange)?;
                let mut output = OwnedBufferArrayV1::default();
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        start,
                        stop,
                        &mut output,
                        &mut error,
                    )
                };
                take_output(
                    status,
                    error,
                    "lrange",
                    output,
                    take_buffer_array,
                    discard_buffer_array,
                )
            })
        })
        .await
    }

    async fn lindex(&self, key: &str, index: i64) -> CacheResult<Option<Bytes>> {
        let key = key.to_string();
        self.call("lindex", move |state| {
            state.with_call("lindex", |api, handle| {
                let callback = required(api.lindex, CacheOperation::Lindex)?;
                let mut output = OptionalOwnedBufferV1::default();
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        index,
                        &mut output,
                        &mut error,
                    )
                };
                take_output(
                    status,
                    error,
                    "lindex",
                    output,
                    take_optional_buffer,
                    discard_optional_buffer,
                )
            })
        })
        .await
    }

    async fn lset(&self, key: &str, index: i64, value: Bytes) -> CacheResult<()> {
        let key = key.to_string();
        self.call("lset", move |state| {
            state.with_call("lset", |api, handle| {
                let callback = required(api.lset, CacheOperation::Lset)?;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        index,
                        ByteSliceV1::from_slice(&value),
                        &mut error,
                    )
                };
                status_result(status, error, "lset")
            })
        })
        .await
    }

    async fn ltrim(&self, key: &str, start: i64, stop: i64) -> CacheResult<()> {
        let key = key.to_string();
        self.call("ltrim", move |state| {
            state.with_call("ltrim", |api, handle| {
                let callback = required(api.ltrim, CacheOperation::Ltrim)?;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        start,
                        stop,
                        &mut error,
                    )
                };
                status_result(status, error, "ltrim")
            })
        })
        .await
    }

    async fn lrem(&self, key: &str, count: i64, value: Bytes) -> CacheResult<u64> {
        let key = key.to_string();
        self.call("lrem", move |state| {
            state.with_call("lrem", |api, handle| {
                let callback = required(api.lrem, CacheOperation::Lrem)?;
                let mut removed = 0;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        count,
                        ByteSliceV1::from_slice(&value),
                        &mut removed,
                        &mut error,
                    )
                };
                status_result(status, error, "lrem")?;
                Ok(removed)
            })
        })
        .await
    }

    async fn linsert(&self, request: ListInsertRequest) -> CacheResult<i64> {
        self.call("linsert", move |state| {
            state.with_call("linsert", |api, handle| {
                let callback = required(api.linsert, CacheOperation::Linsert)?;
                let position = match request.position {
                    ListInsertPosition::Before => LIST_BEFORE,
                    ListInsertPosition::After => LIST_AFTER,
                };
                let mut length = 0;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(request.key.as_bytes()),
                        position,
                        ByteSliceV1::from_slice(&request.pivot),
                        ByteSliceV1::from_slice(&request.value),
                        &mut length,
                        &mut error,
                    )
                };
                status_result(status, error, "linsert")?;
                Ok(length)
            })
        })
        .await
    }

    async fn lmove(&self, request: ListMoveRequest) -> CacheResult<Option<Bytes>> {
        self.call("lmove", move |state| {
            state.with_call("lmove", |api, handle| {
                let callback = required(api.lmove, CacheOperation::Lmove)?;
                let mut output = OptionalOwnedBufferV1::default();
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(request.source.as_bytes()),
                        ByteSliceV1::from_slice(request.destination.as_bytes()),
                        direction(request.source_direction),
                        direction(request.destination_direction),
                        &mut output,
                        &mut error,
                    )
                };
                take_output(
                    status,
                    error,
                    "lmove",
                    output,
                    take_optional_buffer,
                    discard_optional_buffer,
                )
            })
        })
        .await
    }

    async fn execute_script(&self, request: ScriptRequest) -> CacheResult<ScriptResult> {
        let script_source = self.scripts.resolve(&request.script_id)?.to_string();
        self.call("execute_script", move |state| {
            state.with_call("execute_script", |api, handle| {
                let callback = required(api.execute_script, CacheOperation::ExecuteScript)?;
                let raw_keys = string_slices(&request.keys);
                let raw_args = byte_slices(&request.args);
                let mut output = ScriptValueV1::default();
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(request.script_id.as_bytes()),
                        ByteSliceV1::from_slice(script_source.as_bytes()),
                        raw_keys.as_ptr(),
                        raw_keys.len(),
                        raw_args.as_ptr(),
                        raw_args.len(),
                        &mut output,
                        &mut error,
                    )
                };
                let value = take_output(
                    status,
                    error,
                    "execute_script",
                    output,
                    take_script_value,
                    discard_script_value,
                )?;
                let result = ScriptResult::encode(&value)?;
                if result.payload.len() > MAX_AGGREGATE_BYTES {
                    return Err(invalid_output(format!(
                        "encoded script result byte count {} exceeds limit {}",
                        result.payload.len(),
                        MAX_AGGREGATE_BYTES
                    )));
                }
                Ok(result)
            })
        })
        .await
    }

    async fn ping(&self) -> CacheResult<()> {
        self.call("ping", DynamicState::ping).await
    }

    async fn close(&self) -> CacheResult<()> {
        self.call("close", DynamicState::close).await
    }
}

async fn scalar_u64(
    provider: &DynamicProvider,
    operation: CacheOperation,
    key: &str,
) -> CacheResult<u64> {
    let key = key.to_string();
    provider
        .call(operation.name(), move |state| {
            state.with_call(operation.name(), |api, handle| {
                let callback = match operation {
                    CacheOperation::Scard => required(api.scard, operation)?,
                    CacheOperation::Llen => required(api.llen, operation)?,
                    _ => unreachable!("scalar_u64 only accepts scalar operations"),
                };
                let mut value = 0;
                let mut error = OwnedBufferV1::default();
                let status = unsafe {
                    callback(
                        handle,
                        ByteSliceV1::from_slice(key.as_bytes()),
                        &mut value,
                        &mut error,
                    )
                };
                status_result(status, error, operation.name())?;
                Ok(value)
            })
        })
        .await
}

fn required<T: Copy>(callback: Option<T>, operation: CacheOperation) -> CacheResult<T> {
    callback.ok_or_else(|| CacheError::UnsupportedOperation(operation.name().to_string()))
}

fn set_options(options: SetOptions) -> CacheResult<SetOptionsV1> {
    let expiration_ms = match options.expiration {
        None => -1,
        Some(Expiration::After(duration)) => i64::try_from(duration.as_millis())
            .map_err(|_| CacheError::InvalidArgument("set expiration is too large".to_string()))?,
    };
    let condition = match options.condition {
        SetCondition::None => SET_CONDITION_NONE,
        SetCondition::Nx => SET_CONDITION_NX,
        SetCondition::Xx => SET_CONDITION_XX,
    };
    Ok(SetOptionsV1 {
        expiration_ms,
        condition,
        keep_ttl: u8::from(options.keep_ttl),
    })
}

fn direction(direction: ListDirection) -> u32 {
    match direction {
        ListDirection::Left => LIST_LEFT,
        ListDirection::Right => LIST_RIGHT,
    }
}

fn string_slices(values: &[String]) -> Vec<ByteSliceV1> {
    values
        .iter()
        .map(|value| ByteSliceV1::from_slice(value.as_bytes()))
        .collect()
}

fn byte_slices(values: &[Bytes]) -> Vec<ByteSliceV1> {
    values
        .iter()
        .map(|value| ByteSliceV1::from_slice(value))
        .collect()
}

#[derive(Default)]
struct DecodeBudget {
    aggregate_bytes: usize,
    script_nodes: usize,
}

impl DecodeBudget {
    fn charge_bytes(&mut self, bytes: usize, label: &str) -> CacheResult<()> {
        self.aggregate_bytes = self
            .aggregate_bytes
            .checked_add(bytes)
            .ok_or_else(|| invalid_output(format!("{label} aggregate byte count overflowed")))?;
        if self.aggregate_bytes > MAX_AGGREGATE_BYTES {
            return Err(invalid_output(format!(
                "{label} aggregate byte count {} exceeds limit {}",
                self.aggregate_bytes, MAX_AGGREGATE_BYTES
            )));
        }
        Ok(())
    }

    fn charge_script_node(&mut self) -> CacheResult<()> {
        self.script_nodes = self
            .script_nodes
            .checked_add(1)
            .ok_or_else(|| invalid_output("script node count overflowed"))?;
        if self.script_nodes > MAX_SCRIPT_NODES {
            return Err(invalid_output(format!(
                "script node count {} exceeds limit {}",
                self.script_nodes, MAX_SCRIPT_NODES
            )));
        }
        Ok(())
    }
}

#[derive(Debug)]
struct RegisteredAllocation {
    data: *mut u8,
    layout: Layout,
}

impl Drop for RegisteredAllocation {
    fn drop(&mut self) {
        unsafe { dealloc(self.data, self.layout) };
    }
}

struct PendingBuffers {
    items: std::vec::IntoIter<OwnedBufferV1>,
}

impl Drop for PendingBuffers {
    fn drop(&mut self) {
        for item in self.items.by_ref() {
            discard_buffer(item);
        }
    }
}

struct PendingOptionalBuffers {
    items: std::vec::IntoIter<OptionalOwnedBufferV1>,
}

impl Drop for PendingOptionalBuffers {
    fn drop(&mut self) {
        for item in self.items.by_ref() {
            discard_buffer(item.value);
        }
    }
}

struct PendingScriptValues {
    items: std::vec::IntoIter<ScriptValueV1>,
}

impl Drop for PendingScriptValues {
    fn drop(&mut self) {
        for item in self.items.by_ref() {
            discard_script_value(item);
        }
    }
}

fn take_output<T, O>(
    status: i32,
    error: OwnedBufferV1,
    operation: &str,
    output: O,
    take: impl FnOnce(O) -> CacheResult<T>,
    discard: impl FnOnce(O),
) -> CacheResult<T> {
    match status_result(status, error, operation) {
        Ok(()) => take(output),
        Err(error) => {
            discard(output);
            Err(error)
        }
    }
}

fn status_result(status: i32, error: OwnedBufferV1, operation: &str) -> CacheResult<()> {
    let message = take_buffer_with_limit(error, MAX_ERROR_BYTES, "error buffer")?;
    if status == STATUS_OK {
        if message.is_empty() {
            return Ok(());
        }
        return Err(invalid_output(format!(
            "dynamic provider {operation} returned an error payload with success status"
        )));
    }
    let message = String::from_utf8_lossy(&message);
    let details = if message.is_empty() {
        format!("dynamic provider {operation} failed with status {status}")
    } else {
        format!("dynamic provider {operation}: {message}")
    };
    Err(match status {
        STATUS_TIMEOUT => CacheError::Timeout(details),
        STATUS_UNAVAILABLE => CacheError::Unavailable(details),
        STATUS_AUTHENTICATION => CacheError::Authentication(details),
        STATUS_PERMISSION_DENIED => CacheError::PermissionDenied(details),
        STATUS_INVALID_ARGUMENT => CacheError::InvalidArgument(details),
        STATUS_INVALID_DATA => CacheError::InvalidData(details),
        STATUS_CROSS_SLOT => CacheError::CrossSlot(details),
        STATUS_READ_ONLY => CacheError::ReadOnly(details),
        STATUS_UNSUPPORTED_OPERATION => CacheError::UnsupportedOperation(details),
        _ => CacheError::Internal(details),
    })
}

fn take_bool(value: u8, operation: &str) -> CacheResult<bool> {
    match value {
        0 => Ok(false),
        1 => Ok(true),
        other => Err(CacheError::InvalidData(format!(
            "dynamic provider {operation} returned invalid boolean {other}"
        ))),
    }
}

fn take_optional_buffer(value: OptionalOwnedBufferV1) -> CacheResult<Option<Bytes>> {
    match value.present {
        0 if is_empty_buffer(&value.value) => Ok(None),
        0 => {
            discard_buffer(value.value);
            Err(invalid_output(
                "absent optional buffer returned a non-empty value",
            ))
        }
        1 => take_buffer(value.value).map(Some),
        other => {
            discard_buffer(value.value);
            Err(invalid_output(format!(
                "dynamic provider returned invalid optional flag {other}"
            )))
        }
    }
}

fn take_buffer(buffer: OwnedBufferV1) -> CacheResult<Bytes> {
    take_buffer_with_limit(buffer, MAX_BUFFER_BYTES, "buffer")
}

fn take_buffer_with_limit(
    buffer: OwnedBufferV1,
    max_bytes: usize,
    label: &str,
) -> CacheResult<Bytes> {
    let mut budget = DecodeBudget::default();
    take_buffer_with_budget(buffer, max_bytes, label, &mut budget)
}

fn take_buffer_with_budget(
    buffer: OwnedBufferV1,
    max_bytes: usize,
    label: &str,
    budget: &mut DecodeBudget,
) -> CacheResult<Bytes> {
    if buffer.len == 0 {
        if buffer.data.is_null() {
            return Ok(Bytes::new());
        }
        release_registered(buffer.data);
        return Err(invalid_output(format!(
            "dynamic provider returned a non-null empty {label}"
        )));
    }
    if buffer.data.is_null() {
        return Err(invalid_output(format!(
            "dynamic provider returned a null {label}"
        )));
    }
    let allocation = claim_allocation::<u8>(buffer.data, buffer.len, max_bytes, label, budget)?;
    let value = Bytes::copy_from_slice(unsafe { slice::from_raw_parts(buffer.data, buffer.len) });
    drop(allocation);
    Ok(value)
}

fn take_buffer_array(array: OwnedBufferArrayV1) -> CacheResult<Vec<Bytes>> {
    let mut budget = DecodeBudget::default();
    take_buffer_array_with_budget(array, &mut budget)
}

fn take_buffer_array_with_budget(
    array: OwnedBufferArrayV1,
    budget: &mut DecodeBudget,
) -> CacheResult<Vec<Bytes>> {
    if array.len == 0 {
        if array.items.is_null() {
            return Ok(Vec::new());
        }
        release_registered(array.items.cast::<u8>());
        return Err(invalid_output(
            "dynamic provider returned a non-null empty buffer array",
        ));
    }
    if array.items.is_null() {
        return Err(invalid_output(
            "dynamic provider returned a null buffer array",
        ));
    }
    let items = take_raw_array(array.items, array.len, "buffer array", budget)?;
    let mut pending = PendingBuffers {
        items: items.into_iter(),
    };
    let mut values = Vec::with_capacity(array.len);
    while let Some(item) = pending.items.next() {
        values.push(take_buffer_with_budget(
            item,
            MAX_BUFFER_BYTES,
            "buffer array item",
            budget,
        )?);
    }
    Ok(values)
}

fn take_optional_buffer_array(
    array: OptionalOwnedBufferArrayV1,
) -> CacheResult<Vec<Option<Bytes>>> {
    let mut budget = DecodeBudget::default();
    if array.len == 0 {
        if array.items.is_null() {
            return Ok(Vec::new());
        }
        release_registered(array.items.cast::<u8>());
        return Err(invalid_output(
            "dynamic provider returned a non-null empty optional buffer array",
        ));
    }
    if array.items.is_null() {
        return Err(invalid_output(
            "dynamic provider returned a null optional buffer array",
        ));
    }
    let items = take_raw_array(array.items, array.len, "optional buffer array", &mut budget)?;
    let mut pending = PendingOptionalBuffers {
        items: items.into_iter(),
    };
    let mut values = Vec::with_capacity(array.len);
    while let Some(item) = pending.items.next() {
        values.push(take_optional_buffer_with_budget(item, &mut budget)?);
    }
    Ok(values)
}

fn take_script_value(value: ScriptValueV1) -> CacheResult<ScriptValue> {
    let mut budget = DecodeBudget::default();
    take_script_value_with_budget(value, 0, &mut budget)
}

fn take_script_value_with_budget(
    value: ScriptValueV1,
    depth: usize,
    budget: &mut DecodeBudget,
) -> CacheResult<ScriptValue> {
    if depth > MAX_SCRIPT_DEPTH {
        discard_script_value(value);
        return Err(invalid_output(format!(
            "script result depth {depth} exceeds limit {MAX_SCRIPT_DEPTH}"
        )));
    }
    if let Err(error) = budget.charge_script_node() {
        discard_script_value(value);
        return Err(error);
    }
    let ScriptValueV1 {
        bytes,
        items,
        items_len,
        integer,
        kind,
        boolean,
    } = value;
    match kind {
        SCRIPT_NULL => {
            ensure_unused_script_storage(bytes, items, items_len, "null")?;
            Ok(ScriptValue::Null)
        }
        SCRIPT_INTEGER => {
            ensure_unused_script_storage(bytes, items, items_len, "integer")?;
            Ok(ScriptValue::Integer(integer))
        }
        SCRIPT_BYTES => {
            ensure_empty_script_items(items, items_len, "bytes")?;
            take_buffer_with_budget(bytes, MAX_BUFFER_BYTES, "script bytes", budget)
                .map(|value| ScriptValue::Bytes(value.to_vec()))
        }
        SCRIPT_BOOLEAN => {
            ensure_unused_script_storage(bytes, items, items_len, "boolean")?;
            take_bool(boolean, "execute_script").map(ScriptValue::Boolean)
        }
        SCRIPT_ARRAY => {
            ensure_empty_script_buffer(bytes, "array")?;
            if items_len == 0 {
                if items.is_null() {
                    return Ok(ScriptValue::Array(Vec::new()));
                }
                release_registered(items.cast::<u8>());
                return Err(invalid_output(
                    "dynamic provider returned a non-null empty script array",
                ));
            }
            if items.is_null() {
                return Err(invalid_output(
                    "dynamic provider returned a null script array",
                ));
            }
            let raw_items = take_raw_array(items, items_len, "script array", budget)?;
            let mut pending = PendingScriptValues {
                items: raw_items.into_iter(),
            };
            let mut values = Vec::with_capacity(items_len);
            while let Some(item) = pending.items.next() {
                values.push(take_script_value_with_budget(item, depth + 1, budget)?);
            }
            Ok(ScriptValue::Array(values))
        }
        other => {
            discard_buffer(bytes);
            discard_script_items(items, items_len);
            Err(invalid_output(format!(
                "dynamic provider returned invalid script value kind {other}"
            )))
        }
    }
}

fn take_optional_buffer_with_budget(
    value: OptionalOwnedBufferV1,
    budget: &mut DecodeBudget,
) -> CacheResult<Option<Bytes>> {
    match value.present {
        0 if is_empty_buffer(&value.value) => Ok(None),
        0 => {
            discard_buffer(value.value);
            Err(invalid_output(
                "absent optional buffer returned a non-empty value",
            ))
        }
        1 => take_buffer_with_budget(value.value, MAX_BUFFER_BYTES, "optional buffer", budget)
            .map(Some),
        other => {
            discard_buffer(value.value);
            Err(invalid_output(format!(
                "dynamic provider returned invalid optional flag {other}"
            )))
        }
    }
}

fn take_raw_array<T>(
    items: *mut T,
    len: usize,
    label: &str,
    budget: &mut DecodeBudget,
) -> CacheResult<Vec<T>> {
    if len > MAX_ARRAY_ITEMS {
        release_registered(items.cast::<u8>());
        return Err(invalid_output(format!(
            "{label} item count {len} exceeds limit {MAX_ARRAY_ITEMS}"
        )));
    }
    let allocation = claim_allocation::<T>(items, len, MAX_HOST_ALLOCATION_BYTES, label, budget)?;
    let mut values = Vec::with_capacity(len);
    for index in 0..len {
        values.push(unsafe { ptr::read(items.add(index)) });
    }
    drop(allocation);
    Ok(values)
}

fn claim_allocation<T>(
    data: *mut T,
    len: usize,
    max_bytes: usize,
    label: &str,
    budget: &mut DecodeBudget,
) -> CacheResult<RegisteredAllocation> {
    let layout = Layout::array::<T>(len)
        .map_err(|_| invalid_output(format!("{label} allocation size overflowed")))?;
    if layout.size() > isize::MAX as usize {
        release_registered(data.cast::<u8>());
        return Err(invalid_output(format!(
            "{label} allocation exceeds isize::MAX"
        )));
    }
    if layout.size() > max_bytes {
        release_registered(data.cast::<u8>());
        return Err(invalid_output(format!(
            "{label} byte count {} exceeds limit {max_bytes}",
            layout.size()
        )));
    }
    if (data as usize) % layout.align() != 0 {
        release_registered(data.cast::<u8>());
        return Err(invalid_output(format!(
            "{label} pointer is not aligned to {} bytes",
            layout.align()
        )));
    }
    if let Err(error) = budget.charge_bytes(layout.size(), label) {
        release_registered(data.cast::<u8>());
        return Err(error);
    }
    let actual = allocation_registry()
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner())
        .remove(&(data as usize))
        .ok_or_else(|| invalid_output(format!("{label} was not allocated by host->alloc")))?;
    if actual != layout {
        unsafe { dealloc(data.cast::<u8>(), actual) };
        return Err(invalid_output(format!(
            "{label} allocation layout does not match returned length/alignment"
        )));
    }
    Ok(RegisteredAllocation {
        data: data.cast::<u8>(),
        layout,
    })
}

fn allocation_registry() -> &'static Mutex<HashMap<usize, Layout>> {
    static ALLOCATIONS: OnceLock<Mutex<HashMap<usize, Layout>>> = OnceLock::new();
    ALLOCATIONS.get_or_init(|| Mutex::new(HashMap::new()))
}

#[cfg(test)]
fn host_allocation_is_registered(data: *mut u8) -> bool {
    allocation_registry()
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner())
        .contains_key(&(data as usize))
}

fn release_registered(data: *mut u8) {
    if data.is_null() {
        return;
    }
    let layout = allocation_registry()
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner())
        .remove(&(data as usize));
    if let Some(layout) = layout {
        unsafe { dealloc(data, layout) };
    }
}

fn discard_buffer(buffer: OwnedBufferV1) {
    release_registered(buffer.data);
}

fn discard_optional_buffer(buffer: OptionalOwnedBufferV1) {
    discard_buffer(buffer.value);
}

fn discard_buffer_array(array: OwnedBufferArrayV1) {
    if array.items.is_null() || array.len == 0 || array.len > MAX_ARRAY_ITEMS {
        release_registered(array.items.cast::<u8>());
        return;
    }
    let mut budget = DecodeBudget::default();
    match take_raw_array(
        array.items,
        array.len,
        "discarded buffer array",
        &mut budget,
    ) {
        Ok(items) => {
            for item in items {
                discard_buffer(item);
            }
        }
        Err(_) => release_registered(array.items.cast::<u8>()),
    }
}

fn discard_optional_buffer_array(array: OptionalOwnedBufferArrayV1) {
    if array.items.is_null() || array.len == 0 || array.len > MAX_ARRAY_ITEMS {
        release_registered(array.items.cast::<u8>());
        return;
    }
    let mut budget = DecodeBudget::default();
    match take_raw_array(
        array.items,
        array.len,
        "discarded optional buffer array",
        &mut budget,
    ) {
        Ok(items) => {
            for item in items {
                discard_optional_buffer(item);
            }
        }
        Err(_) => release_registered(array.items.cast::<u8>()),
    }
}

fn discard_script_items(items: *mut ScriptValueV1, len: usize) {
    if items.is_null() {
        return;
    }
    if len == 0 || len > MAX_ARRAY_ITEMS {
        release_registered(items.cast::<u8>());
        return;
    }
    let mut budget = DecodeBudget::default();
    match take_raw_array(items, len, "discarded script array", &mut budget) {
        Ok(values) => {
            for value in values {
                discard_script_value(value);
            }
        }
        Err(_) => release_registered(items.cast::<u8>()),
    }
}

fn discard_script_value(value: ScriptValueV1) {
    let mut pending = vec![value];
    let mut visited = 0usize;
    while let Some(value) = pending.pop() {
        visited += 1;
        let ScriptValueV1 {
            bytes,
            items,
            items_len,
            ..
        } = value;
        discard_buffer(bytes);
        if items.is_null() {
            continue;
        }
        if visited > MAX_SCRIPT_NODES || items_len == 0 || items_len > MAX_ARRAY_ITEMS {
            release_registered(items.cast::<u8>());
            continue;
        }
        let mut budget = DecodeBudget::default();
        match take_raw_array(items, items_len, "discarded script array", &mut budget) {
            Ok(mut values) => pending.append(&mut values),
            Err(_) => release_registered(items.cast::<u8>()),
        }
    }
}

fn ensure_unused_script_storage(
    bytes: OwnedBufferV1,
    items: *mut ScriptValueV1,
    items_len: usize,
    kind: &str,
) -> CacheResult<()> {
    ensure_empty_script_buffer(bytes, kind)?;
    ensure_empty_script_items(items, items_len, kind)
}

fn ensure_empty_script_buffer(buffer: OwnedBufferV1, kind: &str) -> CacheResult<()> {
    if is_empty_buffer(&buffer) {
        return Ok(());
    }
    discard_buffer(buffer);
    Err(invalid_output(format!(
        "script {kind} value returned an unexpected byte buffer"
    )))
}

fn ensure_empty_script_items(
    items: *mut ScriptValueV1,
    items_len: usize,
    kind: &str,
) -> CacheResult<()> {
    if items.is_null() && items_len == 0 {
        return Ok(());
    }
    discard_script_items(items, items_len);
    Err(invalid_output(format!(
        "script {kind} value returned unexpected child items"
    )))
}

fn is_empty_buffer(buffer: &OwnedBufferV1) -> bool {
    buffer.data.is_null() && buffer.len == 0
}

fn invalid_output(message: impl Into<String>) -> CacheError {
    CacheError::InvalidData(message.into())
}

fn close_handle(api: ProviderApiV1, handle: *mut c_void) {
    if handle.is_null() {
        return;
    }
    let mut error = OwnedBufferV1::default();
    if let Some(close) = api.close {
        unsafe {
            close(handle, &mut error);
        }
        let _ = take_buffer(error);
    }
}

unsafe extern "C" fn host_alloc(size: usize, alignment: usize) -> *mut u8 {
    if size == 0 || size > MAX_HOST_ALLOCATION_BYTES {
        return ptr::null_mut();
    }
    match Layout::from_size_align(size, alignment) {
        Ok(layout) => {
            let data = unsafe { alloc(layout) };
            if !data.is_null() {
                allocation_registry()
                    .lock()
                    .unwrap_or_else(|poisoned| poisoned.into_inner())
                    .insert(data as usize, layout);
            }
            data
        }
        Err(_) => ptr::null_mut(),
    }
}

unsafe extern "C" fn host_dealloc(data: *mut u8, size: usize, alignment: usize) {
    if data.is_null() || size == 0 {
        return;
    }
    if let Ok(expected) = Layout::from_size_align(size, alignment) {
        let mut allocations = allocation_registry()
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        if allocations.get(&(data as usize)) == Some(&expected) {
            allocations.remove(&(data as usize));
            drop(allocations);
            unsafe { dealloc(data, expected) };
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn script_result_rejects_excessive_nesting() {
        let mut value = ScriptValueV1 {
            kind: SCRIPT_NULL,
            ..ScriptValueV1::default()
        };
        for _ in 0..80 {
            let layout = Layout::array::<ScriptValueV1>(1).unwrap();
            let items =
                unsafe { host_alloc(layout.size(), layout.align()) }.cast::<ScriptValueV1>();
            assert!(!items.is_null());
            unsafe { ptr::write(items, value) };
            value = ScriptValueV1 {
                items,
                items_len: 1,
                kind: SCRIPT_ARRAY,
                ..ScriptValueV1::default()
            };
        }

        let error = take_script_value(value).unwrap_err();

        assert!(matches!(error, CacheError::InvalidData(message) if message.contains("depth")));
    }

    #[test]
    fn buffer_array_rejects_excessive_item_count() {
        const ITEM_COUNT: usize = 100_001;
        let layout = Layout::array::<OwnedBufferV1>(ITEM_COUNT).unwrap();
        let items = unsafe { host_alloc(layout.size(), layout.align()) }.cast::<OwnedBufferV1>();
        assert!(!items.is_null());
        for index in 0..ITEM_COUNT {
            unsafe { ptr::write(items.add(index), OwnedBufferV1::default()) };
        }

        let error = take_buffer_array(OwnedBufferArrayV1 {
            items,
            len: ITEM_COUNT,
        })
        .unwrap_err();

        assert!(
            matches!(error, CacheError::InvalidData(message) if message.contains("item count"))
        );
    }

    #[test]
    fn optional_array_failure_releases_all_host_allocations() {
        let first_data = unsafe { host_alloc(1, align_of::<u8>()) };
        let second_data = unsafe { host_alloc(1, align_of::<u8>()) };
        assert!(!first_data.is_null());
        assert!(!second_data.is_null());
        unsafe {
            *first_data = b'a';
            *second_data = b'b';
        }
        let layout = Layout::array::<OptionalOwnedBufferV1>(2).unwrap();
        let items =
            unsafe { host_alloc(layout.size(), layout.align()) }.cast::<OptionalOwnedBufferV1>();
        unsafe {
            ptr::write(
                items,
                OptionalOwnedBufferV1 {
                    value: OwnedBufferV1 {
                        data: first_data,
                        len: 1,
                    },
                    present: 2,
                },
            );
            ptr::write(
                items.add(1),
                OptionalOwnedBufferV1 {
                    value: OwnedBufferV1 {
                        data: second_data,
                        len: 1,
                    },
                    present: 1,
                },
            );
        }

        let result = take_optional_buffer_array(OptionalOwnedBufferArrayV1 { items, len: 2 });

        assert!(matches!(result, Err(CacheError::InvalidData(_))));
        assert!(!host_allocation_is_registered(first_data));
        assert!(!host_allocation_is_registered(second_data));
        assert!(!host_allocation_is_registered(items.cast::<u8>()));
    }

    #[test]
    fn checked_reader_rejects_overflow_and_misalignment() {
        let overflow = claim_allocation::<ScriptValueV1>(
            std::ptr::NonNull::dangling().as_ptr(),
            usize::MAX,
            MAX_HOST_ALLOCATION_BYTES,
            "overflow array",
            &mut DecodeBudget::default(),
        )
        .unwrap_err();
        assert!(
            matches!(overflow, CacheError::InvalidData(message) if message.contains("overflow"))
        );

        let misaligned = claim_allocation::<ScriptValueV1>(
            1usize as *mut ScriptValueV1,
            1,
            MAX_HOST_ALLOCATION_BYTES,
            "misaligned array",
            &mut DecodeBudget::default(),
        )
        .unwrap_err();
        assert!(
            matches!(misaligned, CacheError::InvalidData(message) if message.contains("aligned"))
        );
    }
}