freenet_stdlib/

delegate_host.rs

//! Host function API for delegates.
//!
//! This module provides synchronous access to delegate context, secrets, and
//! contract state via host functions, eliminating the need for message round-trips.
//!
//! # Example
//!
//! ```ignore
//! use freenet_stdlib::prelude::*;
//!
//! #[delegate]
//! impl DelegateInterface for MyDelegate {
//!     fn process(
//!         ctx: &mut DelegateCtx,
//!         _params: Parameters<'static>,
//!         _attested: Option<&'static [u8]>,
//!         message: InboundDelegateMsg,
//!     ) -> Result<Vec<OutboundDelegateMsg>, DelegateError> {
//!         // Read/write temporary context
//!         let data = ctx.read();
//!         ctx.write(b"new state");
//!
//!         // Access persistent secrets
//!         if let Some(key) = ctx.get_secret(b"private_key") {
//!             // use key...
//!         }
//!         ctx.set_secret(b"new_secret", b"value");
//!
//!         // V2: Direct contract access (no round-trips!)
//!         let contract_id = [0u8; 32]; // your contract instance ID
//!         if let Some(state) = ctx.get_contract_state(&contract_id) {
//!             // process state...
//!         }
//!         ctx.put_contract_state(&contract_id, b"new state");
//!
//!         Ok(vec![])
//!     }
//! }
//! ```
//!
//! # Context vs Secrets vs Contracts
//!
//! - **Context** (`read`/`write`): Temporary state within a single message batch.
//!   Reset between separate runtime calls. Use for intermediate processing state.
//!
//! - **Secrets** (`get_secret`/`set_secret`): Persistent encrypted storage.
//!   Survives across all delegate invocations. Use for private keys, tokens, etc.
//!
//! - **Contracts** (`get_contract_state`/`put_contract_state`/`update_contract_state`/
//!   `subscribe_contract`/`list_subscriptions`): V2 host functions for direct
//!   contract state access. Synchronous local reads/writes — no
//!   request/response round-trips.
//!
//! # Adding a host function is the additive way to extend this API
//!
//! Host functions are resolved **by name at module instantiation**. A delegate
//! that imports one an older node does not provide fails to load, with a named
//! missing-import error; a delegate that does not import it is unaffected. So
//! adding a host function is additive for every existing delegate, and its
//! failure mode for a too-old node is loud and diagnosable at load time.
//!
//! Contrast the message API (`OutboundDelegateMsg`): a new variant sent to an
//! older host fails mid-protocol at bincode decode, with no way for the
//! delegate to have detected the host's version first. Where a capability can
//! be expressed either way, prefer the host function.
//!
//! # Error Codes
//!
//! Host functions return negative values to indicate errors:
//!
//! | Code | Meaning |
//! |------|---------|
//! | 0    | Success |
//! | -1   | Called outside process() context |
//! | -2   | Secret not found |
//! | -3   | Storage operation failed |
//! | -4   | Invalid parameter (e.g., negative length) |
//! | -5   | Context too large (exceeds i32::MAX) |
//! | -6   | Buffer too small |
//! | -7   | Contract not found in local store |
//! | -8   | Internal state store error |
//! | -9   | WASM memory bounds violation |
//! | -10  | Contract code not registered |
//!
//! The wrapper methods in [`DelegateCtx`] handle these error codes and present
//! a more ergonomic API.

/// Error codes returned by host functions.
///
/// Negative values indicate errors, non-negative values indicate success
/// (usually the number of bytes read/written).
pub mod error_codes {
    /// Operation succeeded.
    pub const SUCCESS: i32 = 0;
    /// Called outside of a process() context.
    pub const ERR_NOT_IN_PROCESS: i32 = -1;
    /// Secret not found.
    pub const ERR_SECRET_NOT_FOUND: i32 = -2;
    /// Storage operation failed.
    pub const ERR_STORAGE_FAILED: i32 = -3;
    /// Invalid parameter (e.g., negative length).
    pub const ERR_INVALID_PARAM: i32 = -4;
    /// Context too large (exceeds i32::MAX).
    pub const ERR_CONTEXT_TOO_LARGE: i32 = -5;
    /// Buffer too small to hold the data.
    pub const ERR_BUFFER_TOO_SMALL: i32 = -6;
    /// Contract not found in local store.
    pub const ERR_CONTRACT_NOT_FOUND: i32 = -7;
    /// Internal state store error.
    pub const ERR_STORE_ERROR: i32 = -8;
    /// WASM memory bounds violation (pointer/length out of range).
    pub const ERR_MEMORY_BOUNDS: i32 = -9;
    /// Contract code not registered in the index.
    pub const ERR_CONTRACT_CODE_NOT_REGISTERED: i32 = -10;
    /// Delegate creation depth limit exceeded.
    pub const ERR_DEPTH_EXCEEDED: i32 = -20;
    /// Per-call delegate creation limit exceeded.
    pub const ERR_CREATIONS_EXCEEDED: i32 = -21;
    /// Invalid WASM module (failed to construct DelegateContainer).
    pub const ERR_INVALID_WASM: i32 = -23;
    /// Failed to register delegate in secret/delegate store.
    pub const ERR_STORE_FAILED: i32 = -24;
}

/// Upper bound on the serialized subscription list a host may report from
/// `__frnt__delegate__list_subscriptions_len`, in bytes — 32 KiB, i.e. 1024
/// contract ids.
///
/// This exists because the delegate allocates on the strength of that number.
/// An allocation failure inside a delegate is an abort, not a value we can
/// return, so an implausible length has to be refused before `vec![0u8; len]`
/// rather than survived afterwards. A delegate holding a thousand subscriptions
/// is already well outside the intended shape.
pub const MAX_SUBSCRIPTION_LIST_BYTES: i64 = 32 * 1024;

// The cap is compared against a length that must also be a multiple of 32. If
// it ever stops being one, the upper bound becomes unreachable and the "1024
// contract ids" above becomes a lie, silently.
const _: () = assert!(MAX_SUBSCRIPTION_LIST_BYTES % 32 == 0);

/// What a delegate's subscribe request actually achieved.
///
/// Returned by
/// [`DelegateCtx::subscribe_contract_checked`](DelegateCtx::subscribe_contract_checked).
/// It exists because `Result<(), _>` has only two states and the subscribe path
/// has three: it can register against state the node holds, it can register
/// against nothing, or it can fail. Reusing `Err` for the middle case is wrong — delegates
/// legitimately subscribe before the node has settled, and a usually-transient
/// condition surfacing as a hard failure would break working delegates today.
///
/// This type is **not on the wire**. It is the decoded form of a non-negative
/// `i64` returned by a host function, so adding a variant costs no bincode
/// variant tag and cannot shift one.
///
/// See freenet-core#5565.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SubscribeOutcome {
    /// **The node holds state for this contract, and has recorded the
    /// delegate's interest in it.** Notifications have something to fire on.
    ///
    /// This is a statement about *now*, not a durability promise. Under
    /// demand-driven hosting **no subscription of any kind is an absolute
    /// pin**, and a delegate subscription is weaker still: it registers
    /// notification interest only. On freenet-core as it stands (pre-#4669) it
    /// contributes **no hosting demand**, so it does not affect eviction
    /// ordering at all — unlike a client subscription, which is a ranking
    /// dimension. freenet-core#5493 implements #4669 and is open now, so treat
    /// the "no demand" half as current behaviour rather than a fixed property. A delegate must not read this as "the node
    /// will keep this contract for me"; it means the subscription is not
    /// vacuous today.
    Pinned,
    /// Registered, but the node holds **no state** for the contract.
    ///
    /// This is the case [`DelegateCtx::subscribe_contract`]'s doc describes at
    /// length and cannot report. The subscription exists, and there is nothing
    /// for it to fire on: notifications arrive only if some *other* route
    /// causes this node to hold the contract. The common way to get here is
    /// subscribing at startup, before the node has fetched the contract.
    ///
    /// Treat it as "retry later" — and unlike a pin promise, this one does
    /// clear: it clears as soon as the node holds the state.
    NotPinned,
    /// The node reported an outcome this build of the stdlib does not know.
    ///
    /// A newer node may report an outcome added after this delegate was
    /// compiled. Treating it as [`Self::Pinned`] would reintroduce exactly the
    /// silent over-claim this type exists to remove, so it is surfaced.
    Unrecognized(i64),
}

impl SubscribeOutcome {
    /// Discriminant for [`Self::Pinned`] on the host-function return channel.
    pub const CODE_PINNED: i64 = 0;
    /// Discriminant for [`Self::NotPinned`] on the host-function return channel.
    pub const CODE_NOT_PINNED: i64 = 1;

    /// Decode a non-negative host return code.
    ///
    /// Negative codes are host **errors** and never reach here; the caller
    /// separates them first. An unrecognized non-negative code becomes
    /// [`Self::Unrecognized`] rather than being folded into a known outcome.
    pub fn from_code(code: i64) -> Self {
        match code {
            Self::CODE_PINNED => Self::Pinned,
            Self::CODE_NOT_PINNED => Self::NotPinned,
            other => Self::Unrecognized(other),
        }
    }

    /// Whether the node holds state for the contract and recorded the
    /// delegate's interest — i.e. whether the subscription can fire.
    ///
    /// False for [`Self::NotPinned`] and for [`Self::Unrecognized`] — an
    /// outcome this build cannot interpret is not evidence either way, and
    /// treating it as affirmative is the over-claim this type removes.
    ///
    /// Not a durability check. See [`Self::Pinned`]: nothing here promises the
    /// node keeps the contract.
    pub fn is_pinned(self) -> bool {
        matches!(self, Self::Pinned)
    }
}
/// Largest `tag` [`DelegateCtx::schedule_wakeup`] will send, in bytes.
///
/// freenet-core#3972 is **expected to** bound how many wakeups a delegate may
/// hold pending; **no host does today**, so that count cap is an obligation and
/// not a premise. Even once it exists, a count cap alone does not bound memory:
/// `tag` would be an unbounded byte channel sitting behind a limit that looks
/// bounded, which is the same defect as a cache capped by entry count while
/// holding caller-controlled values. Hence a size cap as well as a count cap.
///
/// Applied by [`DelegateCtx::schedule_wakeup`] before it calls the host. That
/// is fail-fast convenience for well-behaved callers, **not** a bound: a
/// delegate can declare the import itself and bypass the wrapper, so only the
/// host can enforce this.
///
/// 128 bytes comfortably holds a purpose string, a UUID, or a hash. A tag is an
/// identifier the delegate chose; it is not a place to carry state, which is
/// what secrets are for.
pub const MAX_WAKEUP_TAG_BYTES: usize = 128;

/// Shortest delay [`DelegateCtx::schedule_wakeup`] will request.
/// Anything below it is clamped **up** to it, by that function.
///
/// A delegate that re-arms inside its own `WakeupFired` handler with a zero or
/// near-zero delay would otherwise spin the node in a tight wake loop — the
/// same unbounded-work hazard a deadline in the past would have created, which
/// is why moving to a relative delay did not remove the need for this floor.
///
/// **The host must clamp too, and does not yet.** A delegate can declare the
/// import itself and bypass this wrapper, so the clamp here bounds only
/// well-behaved callers; only the host can make this a limit. That host-side
/// floor is an obligation on freenet-core#3972, not a property of anything
/// shipped.
///
/// A second obligation in the same place: for a long delay to be useful the
/// host must persist pending wakeups across a node restart. **No host does this
/// today.** The precedent runs the wrong way — `DELEGATE_SUBSCRIPTIONS`, the
/// one comparable piece of per-delegate host state, is in-memory and a restart
/// discards it entirely.
pub const MIN_WAKEUP_DELAY: std::time::Duration = std::time::Duration::from_secs(1);

/// Raise `after` to [`MIN_WAKEUP_DELAY`] if it is below it.
///
/// Pure, so host-side `cargo test` can exercise it. Used by
/// [`prepare_wakeup`], which is where the boundary actually sits: everything
/// up to and including the conversion to milliseconds runs on **both** targets,
/// and only the `extern "C"` call beneath it is `cfg(target_family = "wasm")`
/// and therefore never executed by CI — the wasm32 jobs build and lint but run
/// nothing.
pub fn clamp_wakeup_delay(after: std::time::Duration) -> std::time::Duration {
    if after < MIN_WAKEUP_DELAY {
        MIN_WAKEUP_DELAY
    } else {
        after
    }
}

/// Validate and normalise the arguments to [`DelegateCtx::schedule_wakeup`],
/// returning the delay in milliseconds for the host call.
///
/// This is the whole of that function except the FFI call itself, split out so
/// the parts that CI can execute are executed. It covers the tag-size refusal,
/// the [`MIN_WAKEUP_DELAY`] clamp, **the order of the two**, and the saturating
/// conversion to milliseconds — the last of which otherwise lives inside the
/// `cfg(target_family = "wasm")` block and would never run under test.
///
/// `schedule_wakeup` is a thin wrapper over this, so the wiring cannot be
/// deleted without breaking compilation. That matters: an earlier arrangement
/// clamped in the wrapper and discarded the result on the host target, so
/// removing the clamp entirely left the suite green.
fn prepare_wakeup(after: std::time::Duration, tag: &[u8]) -> Result<i64, i64> {
    if tag.len() > MAX_WAKEUP_TAG_BYTES {
        return Err(error_codes::ERR_INVALID_PARAM as i64);
    }
    let after = clamp_wakeup_delay(after);
    // Saturate rather than wrap: `as_millis` is u128, and a delay past
    // i64::MAX milliseconds is ~292 million years, so clamping loses nothing a
    // caller could have meant.
    Ok(i64::try_from(after.as_millis()).unwrap_or(i64::MAX))
}

// ============================================================================
// Host function declarations (WASM only)
// ============================================================================

#[cfg(target_family = "wasm")]
#[link(wasm_import_module = "freenet_delegate_ctx")]
extern "C" {
    /// Returns the current context length in bytes, or negative error code.
    fn __frnt__delegate__ctx_len() -> i32;
    /// Reads context into the buffer at `ptr` (max `len` bytes). Returns bytes written, or negative error code.
    fn __frnt__delegate__ctx_read(ptr: i64, len: i32) -> i32;
    /// Writes `len` bytes from `ptr` into the context, replacing existing content. Returns 0 on success, or negative error code.
    fn __frnt__delegate__ctx_write(ptr: i64, len: i32) -> i32;
}

#[cfg(target_family = "wasm")]
#[link(wasm_import_module = "freenet_delegate_secrets")]
extern "C" {
    /// Get a secret. Returns bytes written to `out_ptr`, or negative error code.
    fn __frnt__delegate__get_secret(key_ptr: i64, key_len: i32, out_ptr: i64, out_len: i32) -> i32;
    /// Get secret length without fetching value. Returns length, or negative error code.
    fn __frnt__delegate__get_secret_len(key_ptr: i64, key_len: i32) -> i32;
    /// Store a secret. Returns 0 on success, or negative error code.
    fn __frnt__delegate__set_secret(key_ptr: i64, key_len: i32, val_ptr: i64, val_len: i32) -> i32;
    /// Check if a secret exists. Returns 1 if yes, 0 if no, or negative error code.
    fn __frnt__delegate__has_secret(key_ptr: i64, key_len: i32) -> i32;
    /// Remove a secret. Returns 0 on success, or negative error code.
    fn __frnt__delegate__remove_secret(key_ptr: i64, key_len: i32) -> i32;
    /// Length (in bytes) of the serialized key list for all stored secret keys
    /// whose raw key starts with the `prefix_len`-byte prefix at `prefix_ptr`
    /// (an empty prefix matches every key). Returns the byte count to allocate
    /// before calling `__frnt__delegate__list_secrets`, or a negative error code.
    fn __frnt__delegate__list_secrets_len(prefix_ptr: i64, prefix_len: i32) -> i32;
    /// Enumerate stored secret keys matching the prefix. Writes a length-prefixed
    /// list to `out_ptr` (max `out_len` bytes): each record is a 4-byte
    /// little-endian length followed by that many key bytes. Returns the number
    /// of bytes written, or a negative error code.
    fn __frnt__delegate__list_secrets(
        prefix_ptr: i64,
        prefix_len: i32,
        out_ptr: i64,
        out_len: i32,
    ) -> i32;
}

#[cfg(target_family = "wasm")]
#[link(wasm_import_module = "freenet_delegate_contracts")]
extern "C" {
    /// Get contract state length. Returns byte count, or negative error code (i64).
    fn __frnt__delegate__get_contract_state_len(id_ptr: i64, id_len: i32) -> i64;
    /// Get contract state. Returns byte count written, or negative error code (i64).
    fn __frnt__delegate__get_contract_state(
        id_ptr: i64,
        id_len: i32,
        out_ptr: i64,
        out_len: i64,
    ) -> i64;
    /// Put (store) contract state. Returns 0 on success, or negative error code (i64).
    fn __frnt__delegate__put_contract_state(
        id_ptr: i64,
        id_len: i32,
        state_ptr: i64,
        state_len: i64,
    ) -> i64;
    /// Update contract state (requires existing state). Returns 0 on success, or negative error code (i64).
    fn __frnt__delegate__update_contract_state(
        id_ptr: i64,
        id_len: i32,
        state_ptr: i64,
        state_len: i64,
    ) -> i64;
    /// Subscribe to contract updates. Returns 0 on success, or negative error code (i64).
    fn __frnt__delegate__subscribe_contract(id_ptr: i64, id_len: i32) -> i64;

    /// Subscribe and report the *outcome*, not just success/failure.
    ///
    /// Returns a non-negative [`SubscribeOutcome`] discriminant, or a negative
    /// error code. Distinct from `__frnt__delegate__subscribe_contract`, whose
    /// `i64` is collapsed to a `bool` by its wrapper and so cannot express an
    /// outcome that is neither success nor failure. See freenet-core#5565.
    fn __frnt__delegate__subscribe_contract_checked(id_ptr: i64, id_len: i32) -> i64;
    /// Byte length of this delegate's serialized subscription list — always a
    /// multiple of 32, and never more than [`MAX_SUBSCRIPTION_LIST_BYTES`].
    /// Returns the count to allocate, or a negative error code (i64). Zero
    /// means "subscribed to nothing", which is distinct from an error and must
    /// stay so.
    fn __frnt__delegate__list_subscriptions_len() -> i64;
    /// Enumerate this delegate's current contract subscriptions: writes the raw
    /// 32-byte instance ids back to back into `out_ptr` (at most `out_len`
    /// bytes) and returns the number of bytes written, or a negative error code
    /// (i64).
    ///
    /// **The host MUST return `ERR_BUFFER_TOO_SMALL` (-6) rather than a partial
    /// list if the set no longer fits in `out_len`.** The set can change
    /// between the length call and this one, and a buffer filled exactly to
    /// `out_len` is indistinguishable from one the host wanted to overflow — so
    /// a silently truncated list would look complete to the delegate, which is
    /// the failure this API exists to remove. Writing more than `out_len` bytes
    /// is a contract violation in either direction.
    fn __frnt__delegate__list_subscriptions(out_ptr: i64, out_len: i64) -> i64;
}

#[cfg(target_family = "wasm")]
#[link(wasm_import_module = "freenet_delegate_management")]
extern "C" {
    /// Ask the host to deliver an `InboundDelegateMsg::WakeupFired` once
    /// `after_millis` have elapsed, measured by the host from this call.
    ///
    /// `tag` is opaque to the host and echoed back on fire. Re-scheduling with
    /// the same `tag` replaces any prior pending wakeup for this
    /// `(delegate, tag)` pair. Returns 0 on success, negative on error.
    fn __frnt__delegate__schedule_wakeup(after_millis: i64, tag_ptr: i64, tag_len: i32) -> i64;

    /// Create a new delegate from WASM code + parameters.
    /// Returns 0 on success, negative error code on failure.
    /// On success, writes 32 bytes to out_key_ptr and 32 bytes to out_hash_ptr.
    fn __frnt__delegate__create_delegate(
        wasm_ptr: i64,
        wasm_len: i64,
        params_ptr: i64,
        params_len: i64,
        cipher_ptr: i64,
        nonce_ptr: i64,
        out_key_ptr: i64,
        out_hash_ptr: i64,
    ) -> i32;
}

// ============================================================================
// DelegateCtx - Unified handle to context, secrets, and contracts
// ============================================================================

/// Opaque handle to the delegate's execution environment.
///
/// Provides access to:
/// - **Temporary context**: State shared within a single message batch (reset between calls)
/// - **Persistent secrets**: Encrypted storage that survives across all invocations
/// - **Contract state** (V2): Direct synchronous access to local contract state
///
/// # Context Methods
/// - [`read`](Self::read), [`write`](Self::write), [`len`](Self::len), [`clear`](Self::clear)
///
/// # Secret Methods
/// - [`get_secret`](Self::get_secret), [`set_secret`](Self::set_secret),
///   [`has_secret`](Self::has_secret), [`remove_secret`](Self::remove_secret)
///
/// # Contract Methods (V2)
/// - [`get_contract_state`](Self::get_contract_state),
///   [`put_contract_state`](Self::put_contract_state),
///   [`update_contract_state`](Self::update_contract_state),
///   [`subscribe_contract`](Self::subscribe_contract),
///   [`list_subscriptions`](Self::list_subscriptions)
///
/// # Delegate Management Methods (V2)
/// - [`create_delegate`](Self::create_delegate)
#[derive(Default)]
#[repr(transparent)]
pub struct DelegateCtx {
    _private: (),
}

impl DelegateCtx {
    /// Creates the context handle.
    ///
    /// # Safety
    ///
    /// This should only be called by macro-generated code when the runtime
    /// has set up the delegate execution environment.
    #[doc(hidden)]
    pub unsafe fn __new() -> Self {
        Self { _private: () }
    }

    // ========================================================================
    // Context methods (temporary state within a batch)
    // ========================================================================

    /// Returns the current context length in bytes.
    #[inline]
    pub fn len(&self) -> usize {
        #[cfg(target_family = "wasm")]
        {
            let len = unsafe { __frnt__delegate__ctx_len() };
            if len < 0 {
                0
            } else {
                len as usize
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            0
        }
    }

    /// Returns `true` if the context is empty.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Read the current context bytes.
    ///
    /// Returns an empty `Vec` if no context has been written.
    pub fn read(&self) -> Vec<u8> {
        #[cfg(target_family = "wasm")]
        {
            let len = unsafe { __frnt__delegate__ctx_len() };
            if len <= 0 {
                return Vec::new();
            }
            let mut buf = vec![0u8; len as usize];
            let read = unsafe { __frnt__delegate__ctx_read(buf.as_mut_ptr() as i64, len) };
            buf.truncate(read.max(0) as usize);
            buf
        }
        #[cfg(not(target_family = "wasm"))]
        {
            Vec::new()
        }
    }

    /// Read context into a provided buffer.
    ///
    /// Returns the number of bytes actually read.
    pub fn read_into(&self, buf: &mut [u8]) -> usize {
        #[cfg(target_family = "wasm")]
        {
            let read =
                unsafe { __frnt__delegate__ctx_read(buf.as_mut_ptr() as i64, buf.len() as i32) };
            read.max(0) as usize
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = buf;
            0
        }
    }

    /// Write new context bytes, replacing any existing content.
    ///
    /// Returns `true` on success, `false` on error.
    pub fn write(&mut self, data: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result =
                unsafe { __frnt__delegate__ctx_write(data.as_ptr() as i64, data.len() as i32) };
            result == 0
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = data;
            false
        }
    }

    /// Clear the context.
    #[inline]
    pub fn clear(&mut self) {
        self.write(&[]);
    }

    // ========================================================================
    // Secret methods (persistent encrypted storage)
    // ========================================================================

    /// Get the length of a secret without retrieving its value.
    ///
    /// Returns `None` if the secret does not exist.
    pub fn get_secret_len(&self, key: &[u8]) -> Option<usize> {
        #[cfg(target_family = "wasm")]
        {
            let result =
                unsafe { __frnt__delegate__get_secret_len(key.as_ptr() as i64, key.len() as i32) };
            if result < 0 {
                None
            } else {
                Some(result as usize)
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = key;
            None
        }
    }

    /// Get a secret by key.
    ///
    /// Returns `None` if the secret does not exist.
    pub fn get_secret(&self, key: &[u8]) -> Option<Vec<u8>> {
        #[cfg(target_family = "wasm")]
        {
            // First get the length to allocate the right buffer size
            let len = self.get_secret_len(key)?;

            if len == 0 {
                return Some(Vec::new());
            }

            let mut out = vec![0u8; len];
            let result = unsafe {
                __frnt__delegate__get_secret(
                    key.as_ptr() as i64,
                    key.len() as i32,
                    out.as_mut_ptr() as i64,
                    out.len() as i32,
                )
            };
            if result < 0 {
                None
            } else {
                out.truncate(result as usize);
                Some(out)
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = key;
            None
        }
    }

    /// Store a secret.
    ///
    /// Returns `true` on success, `false` on error.
    pub fn set_secret(&mut self, key: &[u8], value: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result = unsafe {
                __frnt__delegate__set_secret(
                    key.as_ptr() as i64,
                    key.len() as i32,
                    value.as_ptr() as i64,
                    value.len() as i32,
                )
            };
            result == 0
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = (key, value);
            false
        }
    }

    /// Check if a secret exists.
    pub fn has_secret(&self, key: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result =
                unsafe { __frnt__delegate__has_secret(key.as_ptr() as i64, key.len() as i32) };
            result == 1
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = key;
            false
        }
    }

    /// Remove a secret.
    ///
    /// Returns `true` if the secret was removed, `false` if it didn't exist.
    pub fn remove_secret(&mut self, key: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result =
                unsafe { __frnt__delegate__remove_secret(key.as_ptr() as i64, key.len() as i32) };
            result == 0
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = key;
            false
        }
    }

    /// Enumerate the keys of every secret this delegate has stored whose raw
    /// key begins with `prefix` (pass an empty slice to list all keys).
    ///
    /// Returns the matching raw keys (the same byte strings originally passed
    /// to [`set_secret`](Self::set_secret)). Order is unspecified. The host
    /// caps the number of keys returned; if storage holds more matching keys
    /// than the cap, the list is truncated (callers needing exhaustive
    /// enumeration should narrow the prefix).
    ///
    /// This closes the gap that previously forced apps storing an open-ended
    /// key family (e.g. `room:<owner_vk>`) to maintain their own key registry:
    /// after a delegate-WASM rebuild the delegate can now rediscover what it
    /// has stored instead of probing a hardcoded key set.
    pub fn list_secrets(&self, prefix: &[u8]) -> Vec<Vec<u8>> {
        #[cfg(target_family = "wasm")]
        {
            let len = unsafe {
                __frnt__delegate__list_secrets_len(prefix.as_ptr() as i64, prefix.len() as i32)
            };
            if len <= 0 {
                // Negative => error; zero => no matching keys. Either way the
                // caller gets an empty list (errors are non-fatal: enumeration
                // is advisory).
                return Vec::new();
            }
            let mut out = vec![0u8; len as usize];
            let written = unsafe {
                __frnt__delegate__list_secrets(
                    prefix.as_ptr() as i64,
                    prefix.len() as i32,
                    out.as_mut_ptr() as i64,
                    out.len() as i32,
                )
            };
            if written < 0 {
                return Vec::new();
            }
            out.truncate(written as usize);
            decode_secret_key_list(&out)
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = prefix;
            Vec::new()
        }
    }

    // ========================================================================
    // Contract methods (V2 — direct synchronous access)
    // ========================================================================

    /// Get contract state by instance ID.
    ///
    /// Returns `Some(state_bytes)` if the contract exists locally,
    /// `None` if not found or on error.
    ///
    /// Uses a two-step protocol: first queries the state length, then reads
    /// the state bytes into an allocated buffer.
    pub fn get_contract_state(&self, instance_id: &[u8; 32]) -> Option<Vec<u8>> {
        #[cfg(target_family = "wasm")]
        {
            // Step 1: Get the state length
            let len = unsafe {
                __frnt__delegate__get_contract_state_len(instance_id.as_ptr() as i64, 32)
            };
            if len < 0 {
                return None;
            }
            let len = len as usize;
            if len == 0 {
                return Some(Vec::new());
            }

            // Step 2: Read the state bytes
            let mut buf = vec![0u8; len];
            let read = unsafe {
                __frnt__delegate__get_contract_state(
                    instance_id.as_ptr() as i64,
                    32,
                    buf.as_mut_ptr() as i64,
                    buf.len() as i64,
                )
            };
            if read < 0 {
                None
            } else {
                buf.truncate(read as usize);
                Some(buf)
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = instance_id;
            None
        }
    }

    /// Store (PUT) contract state by instance ID.
    ///
    /// The contract's code must already be registered in the runtime's contract
    /// store. Returns `true` on success, `false` on error.
    pub fn put_contract_state(&mut self, instance_id: &[u8; 32], state: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result = unsafe {
                __frnt__delegate__put_contract_state(
                    instance_id.as_ptr() as i64,
                    32,
                    state.as_ptr() as i64,
                    state.len() as i64,
                )
            };
            result == 0
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = (instance_id, state);
            false
        }
    }

    /// Update contract state by instance ID.
    ///
    /// Like `put_contract_state`, but only succeeds if the contract already has
    /// stored state. This performs a full state replacement (not a delta-based
    /// update through the contract's `update_state` logic). Returns `true` on
    /// success, `false` if no prior state exists or on other errors.
    pub fn update_contract_state(&mut self, instance_id: &[u8; 32], state: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result = unsafe {
                __frnt__delegate__update_contract_state(
                    instance_id.as_ptr() as i64,
                    32,
                    state.as_ptr() as i64,
                    state.len() as i64,
                )
            };
            result == 0
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = (instance_id, state);
            false
        }
    }

    /// Subscribe to contract updates by instance ID.
    ///
    /// Registers interest in receiving `ContractNotification` when the
    /// contract's state changes, covering state committed locally as well as
    /// state arriving from the network.
    ///
    /// **Delivery is best-effort and lossy.** The node drops notifications
    /// rather than blocking a state commit when the delivery channel is full,
    /// and if that channel is closed it removes the contract's subscription
    /// entry outright — silently, for every delegate subscribed to it. A
    /// delegate that needs to be sure should poll contract state as a fallback
    /// rather than treat a notification as guaranteed.
    ///
    /// # Whether this registers demand is a property of the NODE, not of this library
    ///
    /// Subscribing always installs a local notification hook. Whether it *also*
    /// registers demand — keeping the contract in the update mesh and
    /// protecting it from eviction — depends on the freenet-core the delegate
    /// happens to be running on, and **a delegate cannot detect which it has**.
    /// The call reports success either way.
    ///
    /// - **Nodes predating freenet-core#4669** register no demand at all:
    ///   `contract_in_use` has no delegate term, so the contract does not enter
    ///   the renewal set and is not exempt from eviction. Such a delegate sees
    ///   remote updates only while something else keeps the node subscribed to
    ///   that contract — typically an open UI client. Close the tab and the
    ///   notifications stop, with no error reported anywhere.
    /// - **Once #4669 lands**, a subscribe registers demand *when the node is
    ///   hosting the contract*. If the node can resolve the contract but is not
    ///   hosting it, the subscribe still succeeds and notifications still work,
    ///   but no demand is registered — registering demand for a contract the
    ///   node does not hold would create a pin that can be neither renewed nor
    ///   reclaimed. Closing that remaining gap needs a subscribe that can
    ///   bootstrap an unheld contract over the network.
    ///
    /// So do not write a delegate that assumes its subscription pins anything.
    /// This is documented at the call site rather than left in an issue
    /// precisely because nothing in the return value, the logs, or the
    /// delegate's own view distinguishes the cases. Tracked in
    /// freenet-core#4669, phase 1 of the freenet-core#5467 epic.
    ///
    /// Returns `true` on success, `false` if the contract is unknown or on
    /// error. Note that the contract must already be in the node's local store;
    /// subscribing does not fetch it.
    ///
    /// # The `bool` cannot express the case above
    ///
    /// `true` means "the node accepted the registration", and says nothing
    /// about whether there is anything for the subscription to fire on. A node
    /// that knows the contract's code but holds no state for it registers the
    /// interest and returns `true`, identically to one that holds the state —
    /// which is the ordinary situation at startup, before the node has fetched
    /// the contract. The `bool` also collapses every negative error code into
    /// `false`, so a transient failure is indistinguishable from an unknown
    /// contract.
    ///
    /// [`subscribe_contract_checked`](Self::subscribe_contract_checked) reports
    /// the outcome instead, and is what a delegate should use when its
    /// correctness depends on continuing to receive notifications. This method
    /// is deliberately left behaviourally unchanged, because altering what it
    /// returns would change the behaviour of already-deployed delegate WASM.
    pub fn subscribe_contract(&mut self, instance_id: &[u8; 32]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result =
                unsafe { __frnt__delegate__subscribe_contract(instance_id.as_ptr() as i64, 32) };
            result == 0
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = instance_id;
            false
        }
    }

    /// Subscribe to contract updates, and learn whether the node actually
    /// holds the contract the subscription is against.
    ///
    /// This is [`subscribe_contract`](Self::subscribe_contract) with the
    /// outcome preserved instead of collapsed into a `bool`. Use it whenever
    /// the delegate's correctness depends on the subscription being live — a
    /// missed notification on a payment address is money, and the failure is
    /// otherwise indistinguishable from "nothing has happened yet".
    ///
    /// [`SubscribeOutcome::NotPinned`] is a *retryable* condition, and it is
    /// the ordinary one at startup: it clears once the node holds the state.
    /// It is not a statement about eviction — see [`SubscribeOutcome::Pinned`],
    /// which is deliberately not a durability promise.
    ///
    /// # Compatibility
    ///
    /// This is a **host function**, not a wire-format variant, so it costs no
    /// bincode variant tag and is additive in both directions:
    ///
    /// - A delegate that does not call it is completely unaffected; host
    ///   imports resolve by name at module instantiation, so an unimported
    ///   function costs nothing.
    /// - A delegate that *does* call it, on a node too old to provide it, fails
    ///   to **instantiate** with a named missing-import error — loudly, at load
    ///   time, before the delegate has touched any state. A wire variant
    ///   instead fails mid-protocol at bincode decode, with no way for the
    ///   delegate to have checked first.
    ///
    /// Requires a node providing `__frnt__delegate__subscribe_contract_checked`
    /// in the `freenet_delegate_contracts` namespace. No released node does
    /// yet; the host half is freenet-core#5565.
    ///
    /// # Errors
    ///
    /// `Err(code)` carries the negative host error code and means the
    /// subscription did not happen at all. It is an `i64`, matching both the
    /// host function's own return type and
    /// [`list_subscriptions`](Self::list_subscriptions), rather than narrowing
    /// to `i32`: the codes in [`error_codes`] all fit in `i32`, but a narrowing
    /// conversion has to decide what to do with one that does not, and every
    /// available answer invents a code the host never sent. A call that succeeded but did not
    /// pin is `Ok(SubscribeOutcome::NotPinned)`, **not** an error — collapsing
    /// those two is the defect this method exists to fix.
    ///
    /// Off-WASM this always returns `Err(ERR_NOT_IN_PROCESS)` rather than a
    /// plausible-looking success, so a host-side test cannot read an outcome
    /// out of a stub that never subscribed to anything.
    pub fn subscribe_contract_checked(
        &mut self,
        instance_id: &[u8; 32],
    ) -> Result<SubscribeOutcome, i64> {
        #[cfg(target_family = "wasm")]
        {
            let code = unsafe {
                __frnt__delegate__subscribe_contract_checked(instance_id.as_ptr() as i64, 32)
            };
            if code < 0 {
                return Err(code);
            }
            Ok(SubscribeOutcome::from_code(code))
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = instance_id;
            Err(error_codes::ERR_NOT_IN_PROCESS as i64)
        }
    }

    /// List the contract instance ids this delegate is currently subscribed to.
    ///
    /// A delegate's subscription set lives in the node, not in the delegate:
    /// the WASM is instantiated per invocation and dropped immediately after,
    /// so between invocations the delegate has no view of it at all. Without
    /// this call it can only keep a parallel record in its own secrets, which
    /// drifts from the node's exactly in the cases that matter, or re-subscribe
    /// to everything on every wake.
    ///
    /// # What this does not yet solve
    ///
    /// **Today the node does not survive a restart with its delegate
    /// subscriptions intact — it loses them.** `DELEGATE_SUBSCRIPTIONS` is an
    /// in-memory map (freenet-core `wasm_runtime/native_api.rs`), so after a
    /// restart this call correctly returns `Ok(vec![])`, and a delegate should
    /// read that as "the node is holding nothing for me", not as "my
    /// subscriptions are gone but recoverable from somewhere else".
    ///
    /// So this call does **not**, on its own, deliver the restart-replay that
    /// freenet-core#5467 asks for. It is the read side of that capability, and
    /// it becomes load-bearing when #4669 part 3's durable
    /// delegate-subscription store lands and there is finally something
    /// persistent to read back. Until then its value is within a single node
    /// lifetime: learning what the node currently holds, without guessing.
    ///
    /// Order is unspecified; do not depend on it.
    ///
    /// # What this list means
    ///
    /// It answers **"which contracts will notify me"** — not "which contracts
    /// am I keeping alive". Those coincide today, and coincide in the common
    /// case once freenet-core#4669 lands, but they are not the same thing by
    /// construction.
    ///
    /// A delegate subscription is two records on the node: the notification
    /// hook, and (after #4669) the demand registration that actually pins the
    /// contract. They are written and torn down together on the ordinary paths,
    /// but not on all of them — an eviction that sheds a still-in-use contract
    /// clears the demand and leaves the hook standing, and the delegate is told
    /// nothing. A list sourced from the hook alone would therefore report a
    /// contract the delegate is no longer pinning.
    ///
    /// That "looks subscribed, is not pinned" state is exactly what
    /// freenet-core#5467 exists to make visible, so this call must not
    /// reproduce it in the API meant to reveal it. The host is expected to
    /// answer from records it can cross-check rather than from the hook alone.
    /// This documentation deliberately promises the narrower meaning, so
    /// tightening the host's answer later is a bug fix and not a breaking
    /// change.
    ///
    /// Both divergences, and why the two obvious fixes are wrong, are tracked
    /// in freenet-core#5487. They close together at #4669 part 3's durable
    /// delegate-subscription store, where the two records become one with one
    /// owner — so introspection built against the two-record shape will want
    /// rewriting when that lands.
    ///
    /// # Cost
    ///
    /// The node holds delegate subscriptions keyed contract → delegates, so
    /// answering this is a scan across every contract carrying any delegate
    /// subscription, filtered to the caller — **O(all such contracts), not
    /// O(this delegate's subscriptions)**. Call it on wake or after a restart,
    /// which is what it is for; do not call it in a loop or per message.
    ///
    /// # Why this returns a `Result`
    ///
    /// An empty list and a failed enumeration mean opposite things to the
    /// caller — "you hold no subscriptions, take them out again" versus "I
    /// could not tell you" — so they must not be represented by the same
    /// value. Collapsing them into an empty `Vec` is how a delegate ends up
    /// concluding its user's content is unpinned because a host call failed.
    /// The error is the raw host code (see [`error_codes`]).
    ///
    /// Off-WASM this is `Err(ERR_NOT_IN_PROCESS)` rather than an empty list,
    /// for the same reason: a host-side unit test must not be able to read
    /// "no subscriptions" out of a stub that never had any.
    ///
    /// **Host requirement:** the node must register these imports in its
    /// wasmtime linker. That is a freenet-core change, not a stdlib one — host
    /// functions are registered by name and reference no stdlib type, so the
    /// stdlib version a node was built against guarantees nothing here. **No
    /// released node provides them yet.** A delegate that calls this against a
    /// node that does not fails to instantiate, with a named missing-import
    /// error — loud and diagnosable at load time rather than silently
    /// mid-protocol, which is the reason for choosing a host function over a
    /// message variant.
    pub fn list_subscriptions(&self) -> Result<Vec<[u8; 32]>, i64> {
        #[cfg(target_family = "wasm")]
        {
            // Step 1: how many bytes to allocate. Zero is a valid answer and
            // means "subscribed to nothing".
            //
            // The decisions live in `validate_list_len` and `resolve_written`,
            // which are pure and compiled on every target, so they have
            // host-side tests. Only the two `unsafe` host calls are wasm-only —
            // otherwise these branches would be reachable by nothing but a
            // wasm32 runtime CI does not run.
            let len = unsafe { __frnt__delegate__list_subscriptions_len() };
            let capacity = validate_list_len(len)?;
            if capacity == 0 {
                return Ok(Vec::new());
            }

            let mut buf = vec![0u8; capacity];
            let written = unsafe {
                __frnt__delegate__list_subscriptions(buf.as_mut_ptr() as i64, buf.len() as i64)
            };
            buf.truncate(resolve_written(len, written)?);
            decode_contract_id_list(&buf).ok_or(error_codes::ERR_STORE_ERROR as i64)
        }
        #[cfg(not(target_family = "wasm"))]
        {
            Err(error_codes::ERR_NOT_IN_PROCESS as i64)
        }
    }

    /// Ask the host to wake this delegate once `after` has elapsed.
    ///
    /// The host delivers an `InboundDelegateMsg::WakeupFired` carrying `tag`
    /// verbatim. `tag` is opaque to the host and is how a delegate tells its
    /// own wakeups apart. Re-scheduling with the same `tag` **replaces** any
    /// prior pending wakeup for this `(delegate, tag)` pair, which is also how
    /// a wakeup is cancelled early — re-arm it far enough out.
    ///
    /// Lets an always-on delegate run periodic background work (key rotation,
    /// TTL pruning, scheduled publication) with no UI attached, instead of
    /// pushing it into a client sync loop that stops when the tab closes.
    /// Driving use case: freenet/river#228.
    ///
    /// # Why this is a host function and not an outbound message
    ///
    /// A delegate's outbound messages are serialized as **one batch**
    /// (`delegate_interface.rs`, `Result<Vec<OutboundDelegateMsg>, _>` in a
    /// single `bincode::serialize`) and decoded whole by the host. An outbound
    /// variant the host does not know therefore fails the **entire batch**, so
    /// a delegate built against a newer stdlib, returning
    /// `[ApplicationMessage(reply), ScheduleWakeup{..}]` to a current-release
    /// node, would have **the reply discarded along with the wakeup** — the
    /// user's action silently doing nothing.
    ///
    /// That is the direction ordinary rollout produces every time, because
    /// stdlib ships before core by policy. A host function fails the other way:
    /// an unimported function fails at **instantiation**, with a named missing
    /// import, loudly and once, rather than silently and per message.
    ///
    /// `WakeupFired` remains an inbound wire variant, which has no equivalent
    /// hazard: a delegate that cannot schedule never receives one.
    ///
    /// # Minimum delay
    ///
    /// `after` is clamped up to [`MIN_WAKEUP_DELAY`] **by this function**, so
    /// `Duration::ZERO` is a one-second delay rather than a tight wake loop.
    /// A delegate that re-arms inside its own `WakeupFired` handler would
    /// otherwise spin the node — the same unbounded-work hazard a deadline in
    /// the past would have created.
    ///
    /// The host is expected to clamp as well, and must, since a delegate can
    /// bypass this wrapper entirely (see the note on [`MAX_WAKEUP_TAG_BYTES`]).
    /// That host-side floor is **not implemented yet** — freenet-core#3972.
    /// The clamp here is what makes the guarantee true of *this* API today.
    ///
    /// Nothing promises precision in the other direction: the guarantee is
    /// "not before".
    ///
    /// # Errors
    ///
    /// `Err(code)` carries the negative host error code.
    /// [`error_codes::ERR_INVALID_PARAM`] is returned without calling the host
    /// if `tag` exceeds [`MAX_WAKEUP_TAG_BYTES`].
    ///
    /// Requires a node providing `__frnt__delegate__schedule_wakeup` in the
    /// `freenet_delegate_management` namespace. No released node does yet; the
    /// host half is freenet-core#3972, which must also persist pending wakeups
    /// across a restart — see [`MIN_WAKEUP_DELAY`] for why that is stated as an
    /// obligation rather than a guarantee.
    pub fn schedule_wakeup(&mut self, after: std::time::Duration, tag: &[u8]) -> Result<(), i64> {
        // Everything except the FFI call lives in `prepare_wakeup`, which runs
        // on both targets and is unit-tested. Binding its result here is what
        // wires it in: delete this line and the code does not compile.
        let after_millis = prepare_wakeup(after, tag)?;
        #[cfg(target_family = "wasm")]
        {
            let code = unsafe {
                __frnt__delegate__schedule_wakeup(
                    after_millis,
                    tag.as_ptr() as i64,
                    tag.len() as i32,
                )
            };
            if code < 0 {
                return Err(code);
            }
            Ok(())
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = after_millis;
            Err(error_codes::ERR_NOT_IN_PROCESS as i64)
        }
    }

    /// Create a new child delegate from WASM bytecode and parameters.
    ///
    /// This V2 host function allows a delegate to spawn new delegates at runtime.
    /// The child delegate is registered in the node's delegate store and secret store
    /// with the provided cipher and nonce.
    ///
    /// Returns `Ok((key_hash, code_hash))` where both are 32-byte arrays identifying
    /// the newly created delegate. Returns `Err(error_code)` on failure.
    ///
    /// # Resource Limits
    /// - Maximum creation depth: 4 (prevents fork bombs)
    /// - Maximum creations per process() call: 8
    ///
    /// # Error Codes
    /// - `-1`: Called outside process() context
    /// - `-4`: Invalid parameter
    /// - `-9`: WASM memory bounds violation
    /// - `-20`: Depth limit exceeded
    /// - `-21`: Per-call creation limit exceeded
    /// - `-23`: Invalid WASM module
    /// - `-24`: Store registration failed
    pub fn create_delegate(
        &mut self,
        wasm_code: &[u8],
        params: &[u8],
        cipher: &[u8; 32],
        nonce: &[u8; 24],
    ) -> Result<([u8; 32], [u8; 32]), i32> {
        #[cfg(target_family = "wasm")]
        {
            let mut key_buf = [0u8; 32];
            let mut hash_buf = [0u8; 32];
            let result = unsafe {
                __frnt__delegate__create_delegate(
                    wasm_code.as_ptr() as i64,
                    wasm_code.len() as i64,
                    params.as_ptr() as i64,
                    params.len() as i64,
                    cipher.as_ptr() as i64,
                    nonce.as_ptr() as i64,
                    key_buf.as_mut_ptr() as i64,
                    hash_buf.as_mut_ptr() as i64,
                )
            };
            if result == 0 {
                Ok((key_buf, hash_buf))
            } else {
                Err(result)
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = (wasm_code, params, cipher, nonce);
            Err(error_codes::ERR_NOT_IN_PROCESS)
        }
    }
}

impl std::fmt::Debug for DelegateCtx {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("DelegateCtx")
            .field("context_len", &self.len())
            .finish_non_exhaustive()
    }
}

// ============================================================================
// list_subscriptions host-return validation
//
// Split out from the wasm-only body on purpose. CI runs `cargo test` on the
// host target only — the wasm32 matrix entries build and lint but execute
// nothing — so logic left inside `#[cfg(target_family = "wasm")]` is
// type-checked and never run. These are the branches most worth running.
// ============================================================================

/// Validate the byte length the host reports before allocating on it.
///
/// Returns the capacity to allocate, or the error to hand back.
///
/// `usize` is 32 bits on wasm32, so an `as usize` cast on an unvalidated `i64`
/// truncates silently: a bogus `2^32` becomes `0` and surfaces as `Ok(vec![])`,
/// the "you hold no subscriptions" answer that this API's whole return type
/// exists to keep distinguishable from a failure. So the value is refused
/// rather than cast. The cap additionally keeps an implausible length away from
/// `vec![0u8; len]`, since an allocation failure inside a delegate is an abort
/// rather than an error anyone can return.
#[cfg_attr(not(target_family = "wasm"), allow(dead_code))]
fn validate_list_len(len: i64) -> Result<usize, i64> {
    if len < 0 {
        return Err(len);
    }
    if len % 32 != 0 || len > MAX_SUBSCRIPTION_LIST_BYTES {
        return Err(error_codes::ERR_STORE_ERROR as i64);
    }
    Ok(len as usize)
}

/// Decide how much of the buffer to keep, given what the host reports writing.
///
/// `written < len` is accepted as a complete list: the import contract requires
/// the host to return `ERR_BUFFER_TOO_SMALL` rather than truncate, so a short
/// write means the set shrank between the two calls, not that it was cut off.
/// Completeness therefore rests on the host honouring that contract, which is
/// why the contract is stated on the import rather than left implied.
///
/// An earlier version re-called the length function whenever the buffer came
/// back exactly full, meaning to catch a set that had grown. That was wrong
/// twice over: an exactly-full buffer is the *normal* result, not an edge case,
/// so it doubled a scan documented as expensive on every non-empty call — and
/// it could fail a correct read, by reporting `ERR_BUFFER_TOO_SMALL` for a
/// complete list when a subscription happened to arrive in between.
#[cfg_attr(not(target_family = "wasm"), allow(dead_code))]
fn resolve_written(len: i64, written: i64) -> Result<usize, i64> {
    if written < 0 {
        return Err(written);
    }
    if written > len {
        // Writing past the buffer we advertised is a host bug. Left unchecked,
        // `truncate` is a no-op and the zero-filled tail decodes as
        // valid-looking all-zero contract ids.
        return Err(error_codes::ERR_STORE_ERROR as i64);
    }
    if written % 32 != 0 {
        return Err(error_codes::ERR_STORE_ERROR as i64);
    }
    Ok(written as usize)
}

// ============================================================================
// Contract-id-list wire codec (shared host↔delegate contract for
// list_subscriptions)
// ============================================================================

/// Serialize contract instance ids for [`DelegateCtx::list_subscriptions`]: the
/// raw 32 bytes of each id, back to back, with no framing.
///
/// Ids are fixed width, so unlike the secret-key list below they need no length
/// prefix. The encoding lives here rather than only in the host so that both
/// sides and the round-trip tests share one authoritative definition — a codec
/// written twice is a codec that will disagree with itself eventually.
pub fn encode_contract_id_list<'a, I>(ids: I) -> Vec<u8>
where
    I: IntoIterator<Item = &'a [u8; 32]>,
{
    let mut out = Vec::new();
    for id in ids {
        out.extend_from_slice(id);
    }
    out
}

/// Decode the format written by [`encode_contract_id_list`], or `None` if the
/// buffer is not a whole number of ids.
///
/// This is deliberately stricter than [`decode_secret_key_list`], which
/// tolerates a truncated trailing record. Ids are fixed width, so a length that
/// is not a multiple of 32 cannot be a short read of a valid list — it is a
/// host-side bug or a corrupted buffer, and the only honest answer is that the
/// enumeration failed. Silently dropping a partial id would hand the delegate
/// a list that looks complete and is not, which is precisely the class of
/// failure this API exists to remove.
pub fn decode_contract_id_list(buf: &[u8]) -> Option<Vec<[u8; 32]>> {
    let chunks = buf.chunks_exact(32);
    if !chunks.remainder().is_empty() {
        return None;
    }
    Some(
        chunks
            .map(|chunk| {
                let mut id = [0u8; 32];
                id.copy_from_slice(chunk);
                id
            })
            .collect(),
    )
}

// ============================================================================
// Secret-key-list wire codec (shared host↔delegate contract for list_secrets)
// ============================================================================

/// Serialize a list of raw secret keys into the wire format read back by
/// [`decode_secret_key_list`]: for each key, a 4-byte little-endian length
/// followed by that many key bytes. This is the encoding the host
/// (`__frnt__delegate__list_secrets`) writes into the delegate's output buffer.
///
/// Kept in stdlib (rather than only in the host) so the format has exactly one
/// authoritative definition that both sides — and the round-trip tests — share.
pub fn encode_secret_key_list<'a, I>(keys: I) -> Vec<u8>
where
    I: IntoIterator<Item = &'a [u8]>,
{
    let mut buf = Vec::new();
    for key in keys {
        buf.extend_from_slice(&(key.len() as u32).to_le_bytes());
        buf.extend_from_slice(key);
    }
    buf
}

/// Inverse of [`encode_secret_key_list`]. A truncated trailing record (which can
/// only happen if the buffer was clipped mid-record) is dropped rather than
/// panicking, so a short read degrades to "fewer keys" instead of a trap.
pub fn decode_secret_key_list(buf: &[u8]) -> Vec<Vec<u8>> {
    let mut keys = Vec::new();
    let mut pos = 0usize;
    while pos + 4 <= buf.len() {
        let len = u32::from_le_bytes([buf[pos], buf[pos + 1], buf[pos + 2], buf[pos + 3]]) as usize;
        pos += 4;
        if pos + len > buf.len() {
            // Truncated record: stop here rather than over-read.
            break;
        }
        keys.push(buf[pos..pos + len].to_vec());
        pos += len;
    }
    keys
}

#[cfg(test)]
mod secret_key_list_codec_tests {
    use super::{decode_secret_key_list, encode_secret_key_list};

    #[test]
    fn round_trip_multiple_keys() {
        let keys: Vec<&[u8]> = vec![b"room:alice", b"room:bob", b"private_key"];
        let encoded = encode_secret_key_list(keys.iter().copied());
        let decoded = decode_secret_key_list(&encoded);
        assert_eq!(
            decoded,
            vec![
                b"room:alice".to_vec(),
                b"room:bob".to_vec(),
                b"private_key".to_vec()
            ]
        );
    }

    #[test]
    fn round_trip_empty_list() {
        let encoded = encode_secret_key_list(std::iter::empty::<&[u8]>());
        assert!(encoded.is_empty());
        assert!(decode_secret_key_list(&encoded).is_empty());
    }

    #[test]
    fn round_trip_empty_key() {
        // A zero-length key is a legal (if unusual) record.
        let encoded = encode_secret_key_list([b"".as_slice()]);
        assert_eq!(encoded, vec![0, 0, 0, 0]);
        assert_eq!(decode_secret_key_list(&encoded), vec![Vec::<u8>::new()]);
    }

    #[test]
    fn truncated_trailing_record_is_dropped() {
        let mut encoded = encode_secret_key_list([b"abc".as_slice(), b"defgh".as_slice()]);
        // Clip mid-way through the second record's payload.
        encoded.truncate(encoded.len() - 2);
        assert_eq!(decode_secret_key_list(&encoded), vec![b"abc".to_vec()]);
    }
}

#[cfg(test)]
mod contract_id_list_codec_tests {
    use super::{decode_contract_id_list, encode_contract_id_list};

    /// Off-WASM, `list_subscriptions` must report an error rather than an
    /// empty list.
    ///
    /// The whole argument for its `Result` return type is that "you hold no
    /// subscriptions" and "I could not tell you" must not share a
    /// representation. A stub that returned `Ok(vec![])` would let a host-side
    /// test read "no subscriptions" out of something that never had any — the
    /// exact conflation the type exists to prevent, reintroduced at the one
    /// place nobody looks.
    #[test]
    #[cfg(not(target_family = "wasm"))]
    fn list_subscriptions_off_wasm_is_an_error_not_an_empty_list() {
        // SAFETY: `__new` builds a zero-sized handle; off-WASM every method on
        // it takes the non-WASM branch and touches no host state.
        let ctx = unsafe { super::DelegateCtx::__new() };
        assert_eq!(
            ctx.list_subscriptions(),
            Err(super::error_codes::ERR_NOT_IN_PROCESS as i64),
            "off-WASM must be distinguishable from a successful empty enumeration"
        );
    }

    #[test]
    fn round_trips_multiple_ids() {
        let ids = [[0x01u8; 32], [0xFEu8; 32], [0x00u8; 32]];
        let encoded = encode_contract_id_list(ids.iter());
        assert_eq!(
            encoded.len(),
            96,
            "ids are fixed width, so the encoding carries no framing"
        );
        assert_eq!(decode_contract_id_list(&encoded), Some(ids.to_vec()));
    }

    #[test]
    fn round_trips_the_empty_list() {
        let encoded = encode_contract_id_list(std::iter::empty::<&[u8; 32]>());
        assert!(encoded.is_empty());
        assert_eq!(
            decode_contract_id_list(&encoded),
            Some(vec![]),
            "an empty buffer is a successful enumeration of nothing, NOT an error — \
             a delegate must be able to tell those apart"
        );
    }

    #[test]
    fn rejects_a_truncated_trailing_id() {
        let mut encoded = encode_contract_id_list([&[0xAAu8; 32], &[0xBBu8; 32]]);
        encoded.truncate(encoded.len() - 1);
        assert_eq!(
            decode_contract_id_list(&encoded),
            None,
            "a partial id means the buffer is wrong; returning the ids that did parse \
             would hand the caller a list that looks complete and is not"
        );
    }
}

#[cfg(test)]
mod list_subscriptions_guard_tests {
    use super::{error_codes, resolve_written, validate_list_len, MAX_SUBSCRIPTION_LIST_BYTES};

    const STORE_ERR: i64 = error_codes::ERR_STORE_ERROR as i64;

    #[test]
    fn a_negative_length_is_passed_through_as_the_host_error() {
        assert_eq!(
            validate_list_len(error_codes::ERR_NOT_IN_PROCESS as i64),
            Err(error_codes::ERR_NOT_IN_PROCESS as i64),
            "a host error code must reach the caller unchanged, not be reshaped"
        );
    }

    #[test]
    fn zero_is_a_successful_empty_enumeration() {
        assert_eq!(
            validate_list_len(0),
            Ok(0),
            "zero means 'subscribed to nothing' and must NOT be an error"
        );
    }

    #[test]
    fn a_length_that_is_not_a_whole_number_of_ids_is_refused() {
        assert_eq!(validate_list_len(33), Err(STORE_ERR));
        assert_eq!(validate_list_len(31), Err(STORE_ERR));
    }

    #[test]
    fn an_implausible_length_is_refused_before_it_reaches_an_allocation() {
        assert_eq!(
            validate_list_len(MAX_SUBSCRIPTION_LIST_BYTES + 32),
            Err(STORE_ERR)
        );
        assert_eq!(
            validate_list_len(MAX_SUBSCRIPTION_LIST_BYTES),
            Ok(MAX_SUBSCRIPTION_LIST_BYTES as usize),
            "the cap itself is allowed"
        );
    }

    /// The wasm32 truncation this guard exists for: `usize` is 32 bits there,
    /// so `2^32 as usize` is `0` and would have surfaced as an empty list.
    #[test]
    fn a_length_that_would_truncate_to_zero_on_wasm32_is_refused() {
        assert_eq!(validate_list_len(1i64 << 32), Err(STORE_ERR));
    }

    #[test]
    fn a_negative_write_is_passed_through_as_the_host_error() {
        assert_eq!(
            resolve_written(320, error_codes::ERR_STORE_ERROR as i64),
            Err(STORE_ERR)
        );
    }

    #[test]
    fn writing_past_the_advertised_buffer_is_refused() {
        assert_eq!(
            resolve_written(320, 352),
            Err(STORE_ERR),
            "truncate would be a no-op, leaving a zero-filled tail to decode as \
             valid-looking all-zero contract ids"
        );
    }

    #[test]
    fn a_partial_id_written_is_refused() {
        assert_eq!(resolve_written(320, 300), Err(STORE_ERR));
    }

    #[test]
    fn an_exactly_full_buffer_is_the_normal_case_and_is_accepted() {
        assert_eq!(
            resolve_written(320, 320),
            Ok(320),
            "len comes from the same set the read serialises, so exactly-full is \
             the ordinary outcome — treating it as suspicious cost a second scan \
             on every call and could fail a correct read"
        );
    }

    #[test]
    fn a_short_write_is_accepted_as_a_set_that_shrank() {
        assert_eq!(
            resolve_written(320, 288),
            Ok(288),
            "the import contract requires ERR_BUFFER_TOO_SMALL rather than \
             truncation, so a short write means the set shrank"
        );
    }
}

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

    #[test]
    fn known_codes_decode_to_their_outcomes() {
        assert_eq!(
            SubscribeOutcome::from_code(SubscribeOutcome::CODE_PINNED),
            SubscribeOutcome::Pinned
        );
        assert_eq!(
            SubscribeOutcome::from_code(SubscribeOutcome::CODE_NOT_PINNED),
            SubscribeOutcome::NotPinned
        );
    }

    /// The two discriminants are part of the host ABI. Changing either
    /// reassigns the meaning of a value already returned by deployed nodes, so
    /// they are pinned rather than left to whatever order the enum happens to
    /// be written in.
    #[test]
    fn outcome_codes_are_pinned() {
        assert_eq!(SubscribeOutcome::CODE_PINNED, 0);
        assert_eq!(SubscribeOutcome::CODE_NOT_PINNED, 1);
    }

    /// An outcome added by a newer node must not be read as a pin. This is the
    /// whole point of the type: the failure being removed is a delegate
    /// concluding it holds durable interest when it does not.
    #[test]
    fn an_unknown_outcome_is_not_read_as_pinned() {
        let future = SubscribeOutcome::from_code(7);
        assert_eq!(future, SubscribeOutcome::Unrecognized(7));
        assert!(
            !future.is_pinned(),
            "an outcome this build cannot interpret must never report as pinned"
        );
    }

    /// The type must be re-exported from the prelude. `use
    /// freenet_stdlib::prelude::*` is what a delegate writes, and the whole
    /// point of this type is to be matched on — needing a second, differently
    /// shaped import for the match arms would be a papercut on every consumer.
    ///
    /// The path is named in full, deliberately. A `use crate::prelude::*` here
    /// would prove nothing: this module already has `use super::*` in scope, so
    /// the name resolves whether or not the prelude re-exports it, and the test
    /// passes with the re-export deleted. Verified — the first version of this
    /// test did exactly that.
    #[test]
    fn the_type_is_re_exported_from_the_prelude() {
        let outcome = crate::prelude::SubscribeOutcome::from_code(
            crate::prelude::SubscribeOutcome::CODE_NOT_PINNED,
        );
        assert!(matches!(
            outcome,
            crate::prelude::SubscribeOutcome::NotPinned
        ));
    }

    #[test]
    fn only_pinned_reports_pinned() {
        assert!(SubscribeOutcome::Pinned.is_pinned());
        assert!(!SubscribeOutcome::NotPinned.is_pinned());
        assert!(!SubscribeOutcome::Unrecognized(1_000).is_pinned());
    }

    /// Off-WASM the host function does not exist, so the stub must report an
    /// error and never a plausible-looking outcome. A stub returning
    /// `Ok(Pinned)` would let a host-side test read a pin out of a call that
    /// subscribed to nothing — the same "absence reported as fact" defect the
    /// method exists to remove, reintroduced in the test harness. This mirrors
    /// `list_subscriptions_off_wasm_is_an_error_not_an_empty_list`.
    #[test]
    fn the_off_wasm_stub_reports_an_error_not_an_outcome() {
        // SAFETY: off-WASM every method on this handle is a stub that touches
        // no runtime state; the safety contract concerns the WASM execution
        // environment, which does not exist in a host-side test.
        let mut ctx = unsafe { DelegateCtx::__new() };
        let result = ctx.subscribe_contract_checked(&[0u8; 32]);
        assert_eq!(
            result,
            Err(error_codes::ERR_NOT_IN_PROCESS as i64),
            "the off-WASM stub must not fabricate a subscribe outcome"
        );
    }
}

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

    /// The cap is applied before the host call so a well-behaved caller fails
    /// fast with a clear error rather than a remote one.
    ///
    /// **This is convenience, not a bound, and the host must check too.**
    /// `__frnt__delegate__schedule_wakeup` is an ordinary WASM import: any
    /// delegate can declare its own `extern "C"` block for
    /// `freenet_delegate_management` and pass a 10 MB tag without ever
    /// constructing a `DelegateCtx`. The guest controls its own imports, so no
    /// guest-side check can ever bound what the host receives. Only the host
    /// can make 128 bytes a limit — freenet-core#3972.
    ///
    /// That holds for every bound this crate documents, not just this one.
    #[test]
    fn an_oversized_tag_is_refused_without_calling_the_host() {
        // SAFETY: off-WASM every method on this handle is a stub touching no
        // runtime state; the safety contract concerns the WASM environment.
        let mut ctx = unsafe { DelegateCtx::__new() };
        let too_big = vec![0u8; MAX_WAKEUP_TAG_BYTES + 1];
        assert_eq!(
            ctx.schedule_wakeup(std::time::Duration::from_secs(60), &too_big),
            Err(error_codes::ERR_INVALID_PARAM as i64),
            "a tag over the cap must be refused as an invalid parameter"
        );
    }

    /// A tag exactly at the cap is legal. Pinned because an off-by-one here
    /// silently narrows the usable tag space rather than failing loudly.
    #[test]
    fn a_tag_exactly_at_the_cap_is_not_refused_for_being_too_big() {
        let mut ctx = unsafe { DelegateCtx::__new() };
        let exactly = vec![0u8; MAX_WAKEUP_TAG_BYTES];
        // Off-WASM this reaches the stub, so the error must be the stub's
        // "not in process" and *not* the size rejection above.
        assert_eq!(
            ctx.schedule_wakeup(std::time::Duration::from_secs(60), &exactly),
            Err(error_codes::ERR_NOT_IN_PROCESS as i64),
            "a tag exactly at the cap must pass the size check"
        );
    }

    /// Off-WASM the host function does not exist, so the stub must report an
    /// error and never a plausible success — a stub returning `Ok(())` would
    /// let a host-side test read "wakeup scheduled" out of a call that
    /// scheduled nothing.
    #[test]
    fn the_off_wasm_stub_reports_an_error_not_success() {
        let mut ctx = unsafe { DelegateCtx::__new() };
        assert_eq!(
            ctx.schedule_wakeup(std::time::Duration::from_secs(60), b"rotate"),
            Err(error_codes::ERR_NOT_IN_PROCESS as i64),
            "the off-WASM stub must not report a scheduled wakeup"
        );
    }

    /// The prologue as one unit: cap, clamp, ordering, and the millisecond
    /// conversion. `schedule_wakeup` is a thin wrapper over `prepare_wakeup`,
    /// so these cover everything in that function except the `extern "C"` call.
    #[test]
    fn prepare_returns_the_clamped_delay_in_milliseconds() {
        assert_eq!(
            prepare_wakeup(std::time::Duration::ZERO, b"t"),
            Ok(MIN_WAKEUP_DELAY.as_millis() as i64),
            "a zero delay must reach the host as the floor, not as zero"
        );
        assert_eq!(
            prepare_wakeup(std::time::Duration::from_secs(604_800), b"t"),
            Ok(604_800_000),
            "a week must survive the conversion unchanged"
        );
    }

    /// An oversized tag is refused even when the delay *also* needs correcting,
    /// so the two checks cannot mask each other.
    ///
    /// This deliberately does **not** claim to pin their order. Swapping them
    /// is an equivalent mutant — verified: moving the tag check below the clamp
    /// leaves all seven tests passing — because `clamp_wakeup_delay` is pure,
    /// infallible, and its result is discarded on the error path. There is no
    /// observation that distinguishes the two orders, so no test can, and an
    /// ordering test here would be a name asserting coverage it does not have.
    #[test]
    fn an_oversized_tag_is_refused_even_when_the_delay_also_needs_clamping() {
        let too_big = vec![0u8; MAX_WAKEUP_TAG_BYTES + 1];
        assert_eq!(
            prepare_wakeup(std::time::Duration::ZERO, &too_big),
            Err(error_codes::ERR_INVALID_PARAM as i64),
            "an oversized tag must be refused even when the delay also needs correcting"
        );
    }

    /// `as_millis` is `u128`. Saturating rather than wrapping is what stops an
    /// absurd delay becoming a small or negative one at the FFI boundary — a
    /// wrap here would turn "never" into "immediately". This conversion sat
    /// inside the `cfg(target_family = "wasm")` block before `prepare_wakeup`
    /// existed, so nothing executed it.
    #[test]
    fn an_absurd_delay_saturates_rather_than_wrapping() {
        assert_eq!(
            prepare_wakeup(std::time::Duration::MAX, b"t"),
            Ok(i64::MAX),
            "a delay past i64::MAX ms must saturate, never wrap to a small value"
        );
    }

    /// The floor is a documented host contract, so the constant is pinned:
    /// a delegate author relies on it, and silently lowering it would let the
    /// tight-wake-loop hazard back in without any test noticing.
    #[test]
    fn the_documented_bounds_are_pinned() {
        assert_eq!(MAX_WAKEUP_TAG_BYTES, 128);
        assert_eq!(MIN_WAKEUP_DELAY, std::time::Duration::from_secs(1));
    }
}

#[cfg(test)]
mod wakeup_delay_clamp_tests {
    use super::*;
    use std::time::Duration;

    /// `Duration::ZERO` is the case the floor exists for: a delegate re-arming
    /// inside its own `WakeupFired` handler with no delay spins the node.
    #[test]
    fn zero_is_raised_to_the_floor() {
        assert_eq!(clamp_wakeup_delay(Duration::ZERO), MIN_WAKEUP_DELAY);
    }

    #[test]
    fn anything_below_the_floor_is_raised() {
        assert_eq!(
            clamp_wakeup_delay(Duration::from_millis(1)),
            MIN_WAKEUP_DELAY
        );
        assert_eq!(
            clamp_wakeup_delay(MIN_WAKEUP_DELAY - Duration::from_nanos(1)),
            MIN_WAKEUP_DELAY
        );
    }

    /// The floor must not become a rounding-up of ordinary delays. A week is a
    /// week, and exactly-the-floor is already legal — clamping is `<`, not
    /// `<=`, so a caller asking for precisely the minimum is not perturbed.
    #[test]
    fn the_floor_and_anything_above_it_pass_through_unchanged() {
        assert_eq!(clamp_wakeup_delay(MIN_WAKEUP_DELAY), MIN_WAKEUP_DELAY);
        let week = Duration::from_secs(604_800);
        assert_eq!(clamp_wakeup_delay(week), week);
        assert_eq!(clamp_wakeup_delay(Duration::MAX), Duration::MAX);
    }
}