pharos_native/runtime/

feature_runtime.rs

//! Runtime query and rendering support for compiled declarative features.

pub(super) mod logical;
mod media_input;
use std::collections::BTreeMap;
#[cfg(not(target_os = "wasi"))]
use std::collections::BTreeSet;
use std::fs;
use std::path::{Path, PathBuf};
#[cfg(not(target_os = "wasi"))]
use std::time::{SystemTime, UNIX_EPOCH};

use serde_json::{Map, Value};

use crate::config::AppRuntime;

#[cfg(not(target_os = "wasi"))]
const MAX_QUERY_FILTERS: usize = 32;
const MAX_QUERY_ROWS: usize = 100;

#[derive(Debug, Clone, Eq, PartialEq)]
/// Stable failure set returned by feature loading, validation, rendering, and execution.
///
/// # Variants
///
/// - `InvalidContract`: Supported `FeatureRuntimeError` variant.
/// - `InvalidInput`: Supported `FeatureRuntimeError` variant.
/// - `ValidationReport`: Supported `FeatureRuntimeError` variant.
/// - `MissingRecord`: Supported `FeatureRuntimeError` variant.
/// - `Conflict`: Supported `FeatureRuntimeError` variant.
/// - `DatabaseUnavailable`: Supported `FeatureRuntimeError` variant.
/// - `RenderFailed`: Supported `FeatureRuntimeError` variant.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::feature_runtime::FeatureRuntimeError::InvalidContract;
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for constructors, helpers, and neighboring runtime types.
pub enum FeatureRuntimeError {
    InvalidContract(String),
    InvalidInput(String),
    ValidationReport(String),
    MissingRecord(String),
    Conflict(String),
    DatabaseUnavailable,
    /// Classified failure from the configured generic database authority.
    Database(pharos_runtime_database::operations::DatabaseError),
    RenderFailed(String),
}

#[derive(Debug, Clone, Default)]
/// Request-scoped values exposed to feature queries and actions.
///
/// # Fields
///
/// - `request_target`: Original app-relative target used for declared action effects.
/// - `actor_id`: Stored field on `FeatureRequestContext`.
/// - `input`: Stored field on `FeatureRequestContext`.
/// - `path_params`: Stored field on `FeatureRequestContext`.
/// - `query_params`: Stored field on `FeatureRequestContext`.
/// - `bindings`: Stored field on `FeatureRequestContext`.
/// - `row`: Stored field on `FeatureRequestContext`.
/// - `generated`: Stored field on `FeatureRequestContext`.
/// - `protected`: Stored field on `FeatureRequestContext`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_native::runtime::feature_runtime::FeatureRequestContext>();
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for constructors, helpers, and neighboring runtime types.
pub struct FeatureRequestContext {
    pub request_target: String,
    pub actor_id: i64,
    pub input: Map<String, Value>,
    pub path_params: Map<String, Value>,
    pub query_params: Map<String, Value>,
    pub bindings: Map<String, Value>,
    pub row: Map<String, Value>,
    pub generated: Map<String, Value>,
    pub protected: Map<String, Value>,
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Framework-neutral action result returned by feature execution.
///
/// # Fields
///
/// - `status`: Stored field on `FeatureActionOutcome`.
/// - `fragment_html`: Stored field on `FeatureActionOutcome`.
/// - `redirect`: Stored field on `FeatureActionOutcome`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_native::runtime::feature_runtime::FeatureActionOutcome>();
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for constructors, helpers, and neighboring runtime types.
pub struct FeatureActionOutcome {
    pub status: u16,
    pub fragment_html: String,
    pub redirect: String,
    pub redirect_only: bool,
}

/// Resolves only declared path segments in a mutation redirect.
fn action_redirect_path(
    template: &str,
    path_params: &Map<String, Value>,
) -> Result<String, FeatureRuntimeError> {
    if !template.starts_with('/')
        || template.len() > 512
        || template.contains(['?', '#', '\r', '\n', '\0'])
    {
        return Err(FeatureRuntimeError::InvalidContract(
            "action redirect".to_owned(),
        ));
    }
    let mut result = String::with_capacity(template.len());
    for (index, segment) in template.split('/').enumerate() {
        if index > 0 {
            result.push('/');
        }
        let Some(parameter) = segment.strip_prefix(':') else {
            if segment == ".." || segment.contains(['%', '\\']) {
                return Err(FeatureRuntimeError::InvalidContract(
                    "action redirect".to_owned(),
                ));
            }
            result.push_str(segment);
            continue;
        };
        let value = path_params
            .get(parameter)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(parameter.to_owned()))?;
        let value = match value {
            Value::String(value) => value.clone(),
            Value::Number(value) => value.to_string(),
            _ => return Err(FeatureRuntimeError::InvalidInput(parameter.to_owned())),
        };
        if value.is_empty() || value.len() > 256 || matches!(value.as_str(), "." | "..") {
            return Err(FeatureRuntimeError::InvalidInput(parameter.to_owned()));
        }
        for byte in value.bytes() {
            if byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'~') {
                result.push(char::from(byte));
            } else {
                result.push_str(&format!("%{byte:02X}"));
            }
        }
    }
    Ok(result)
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Authorized private-asset location resolved from a declared ownership contract.
///
/// # Fields
///
/// - `private_root`: Stored field on `AuthorizedPrivateAsset`.
/// - `asset_key`: Stored field on `AuthorizedPrivateAsset`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_native::runtime::feature_runtime::AuthorizedPrivateAsset>();
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for constructors, helpers, and neighboring runtime types.
pub struct AuthorizedPrivateAsset {
    pub private_root: String,
    pub asset_key: String,
}

fn payment_provider_render_state_root(
    app: &AppRuntime,
    request_path: &str,
) -> Result<Option<Value>, FeatureRuntimeError> {
    let Some(app_root) = app.app_root.as_deref().map(Path::new) else {
        return Ok(None);
    };
    let Some(management) = pharos_runtime_payment::payment_provider_manifest_config(app_root)
    else {
        return Ok(None);
    };
    let Some(provider_id) = pharos_runtime_payment::payment_provider_primary_provider(app_root)
    else {
        return Ok(None);
    };
    if !super::app_uses_file_backed_runtime_state(app) {
        let store =
            super::database::runtime_logical_app_store(app).map_err(logical::map_database_error)?;
        let route_value =
            pharos_runtime_payment::payment_provider_owner_route_value(app_root, request_path);
        return pharos_runtime_database::payment::payment_render_state(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            &management,
            route_value.as_deref(),
            &provider_id,
        )
        .map(Some)
        .map_err(logical::map_database_error);
    }
    Ok(app
        .state_path
        .as_deref()
        .and_then(|path| super::json_commands::json_doc_load_file(Path::new(path))))
}

/// Loads the effective roles for an authenticated actor.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::actor_roles`].
/// - `actor_id`: Input consumed by [`crate::runtime::feature_runtime::actor_roles`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::feature_runtime::actor_roles`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::actor_roles(todo!(), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn actor_roles(
    app: &AppRuntime,
    actor_id: i64,
) -> Result<Vec<String>, pharos_runtime_database::operations::DatabaseError> {
    #[cfg(not(target_os = "wasi"))]
    {
        use pharos_runtime_database::operations::{Predicate, Query};

        if actor_id <= 0 {
            return Ok(Vec::new());
        }
        let store = super::database::runtime_logical_app_store(app)?;
        let read_roles =
            || -> Result<Vec<String>, pharos_runtime_database::operations::DatabaseError> {
                let account = store
                    .schema
                    .entities
                    .iter()
                    .find(|entity| entity.name == "user_account")
                    .ok_or(pharos_runtime_database::operations::DatabaseError::InvalidContract)?;
                let admission = if account.fields.iter().any(|field| {
                    field.name == "is_active"
                        && field.kind == pharos_runtime_database::operations::FieldType::Boolean
                }) {
                    Predicate::Equal("is_active".to_owned(), Value::Bool(true))
                } else if account.fields.iter().any(|field| {
                    field.name == "account_status"
                        && field.kind == pharos_runtime_database::operations::FieldType::Text
                }) {
                    Predicate::Equal(
                        "account_status".to_owned(),
                        Value::String("active".to_owned()),
                    )
                } else {
                    return Err(
                        pharos_runtime_database::operations::DatabaseError::InvalidContract,
                    );
                };
                let active = store.adapter.query(
                    &store.config,
                    &store.schema,
                    &Query {
                        entity: "user_account".to_owned(),
                        fields: vec!["id".to_owned()],
                        filter: Some(Predicate::All(vec![
                            Predicate::Equal("id".to_owned(), Value::from(actor_id)),
                            admission,
                        ])),
                        order: Vec::new(),
                        limit: 1,
                        offset: 0,
                    },
                )?;
                if active.is_empty() {
                    return Ok(Vec::new());
                }
                let mut roles = std::collections::BTreeSet::new();
                for (entity, actor_field, role_field) in [
                    ("user_profile", "user_id", "account_type"),
                    ("store_membership", "user_id", "role"),
                ] {
                    if !store
                        .schema
                        .entities
                        .iter()
                        .any(|declaration| declaration.name == entity)
                    {
                        continue;
                    }
                    let rows = store.adapter.query(
                        &store.config,
                        &store.schema,
                        &Query {
                            entity: entity.to_owned(),
                            fields: vec![role_field.to_owned()],
                            filter: Some(Predicate::Equal(
                                actor_field.to_owned(),
                                Value::from(actor_id),
                            )),
                            order: Vec::new(),
                            limit: 65,
                            offset: 0,
                        },
                    )?;
                    if rows.len() > 64 {
                        return Err(
                            pharos_runtime_database::operations::DatabaseError::CapacityExceeded,
                        );
                    }
                    for row in rows {
                        let role = row.get(role_field).and_then(Value::as_str).ok_or(
                            pharos_runtime_database::operations::DatabaseError::StorageFailure,
                        )?;
                        if sql_identifier(role).is_err() {
                            return Err(
                                pharos_runtime_database::operations::DatabaseError::InvalidInput,
                            );
                        }
                        roles.insert(role.to_owned());
                    }
                }
                Ok(roles.into_iter().collect())
            };
        read_roles()
    }
    #[cfg(target_os = "wasi")]
    {
        let _ = (app, actor_id);
        Err(pharos_runtime_database::operations::DatabaseError::Unsupported)
    }
}

/// Authorizes access to a private asset through the configured backend.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::authorize_private_asset`].
/// - `request_path`: Input consumed by [`crate::runtime::feature_runtime::authorize_private_asset`].
/// - `actor_id`: Input consumed by [`crate::runtime::feature_runtime::authorize_private_asset`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::authorize_private_asset`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::authorize_private_asset`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::authorize_private_asset(todo!(), "/", 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn authorize_private_asset(
    app: &AppRuntime,
    request_path: &str,
    actor_id: i64,
) -> Result<Option<AuthorizedPrivateAsset>, FeatureRuntimeError> {
    #[cfg(not(target_os = "wasi"))]
    {
        use pharos_runtime_database::operations::{Predicate, Query};

        if actor_id <= 0 {
            return Ok(None);
        }
        let root = artifact_root(app)?;
        let contract_path = root.join("data/contracts/protected-assets.json");
        if !contract_path.is_file() {
            return Ok(None);
        }
        let contract = load_json(&contract_path)?;
        let declarations = contract
            .get("assets")
            .and_then(Value::as_array)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract("protected assets".to_owned()))?;
        let mut matched = None;
        for declaration in declarations {
            let pattern = declaration
                .get("path")
                .and_then(Value::as_str)
                .ok_or_else(|| FeatureRuntimeError::InvalidContract("protected path".to_owned()))?;
            if let Ok(parameters) = path_parameters(pattern, request_path)
                && matched.replace((declaration, parameters)).is_some()
            {
                return Err(FeatureRuntimeError::InvalidContract(
                    "ambiguous protected route".to_owned(),
                ));
            }
        }
        let Some((declaration, parameters)) = matched else {
            return Ok(None);
        };
        let entity_id = declaration
            .get("entity")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract("protected entity".to_owned()))?;
        let store =
            super::database::runtime_logical_app_store(app).map_err(logical::map_database_error)?;
        let entity = store
            .schema
            .entities
            .iter()
            .find(|entity| entity.name == entity_id)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(entity_id.to_owned()))?;
        let identity_fields = entity.identity.fields();
        let identity_field = match identity_fields.as_slice() {
            [field] => *field,
            _ => {
                return Err(FeatureRuntimeError::InvalidContract(
                    "protected asset identity".to_owned(),
                ));
            }
        };
        let key_field = sql_identifier(
            declaration
                .get("key_field")
                .and_then(Value::as_str)
                .unwrap_or_default(),
        )?;
        let owner_field = sql_identifier(
            declaration
                .get("owner_field")
                .and_then(Value::as_str)
                .unwrap_or_default(),
        )?;
        let asset_field = sql_identifier(
            declaration
                .get("asset_field")
                .and_then(Value::as_str)
                .unwrap_or_default(),
        )?;
        if ![
            identity_field,
            key_field.as_str(),
            owner_field.as_str(),
            asset_field.as_str(),
        ]
        .iter()
        .all(|name| entity.fields.iter().any(|field| field.name == *name))
        {
            return Err(FeatureRuntimeError::InvalidContract(entity_id.to_owned()));
        }
        let key = parameters
            .values()
            .next()
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureRuntimeError::InvalidInput("protected key".to_owned()))?;
        let query = Query {
            entity: entity.name.clone(),
            fields: vec![identity_field.to_owned(), asset_field.clone()],
            filter: Some(Predicate::All(vec![
                Predicate::Equal(key_field, Value::String(key.to_owned())),
                Predicate::Equal(owner_field, Value::from(actor_id)),
            ])),
            order: Vec::new(),
            limit: 1,
            offset: 0,
        };
        let rows = store
            .adapter
            .query(&store.config, &store.schema, &query)
            .map_err(|_| FeatureRuntimeError::DatabaseUnavailable)?;
        let Some(row) = rows.first() else {
            return Ok(None);
        };
        let protected_id = row
            .get(identity_field)
            .and_then(Value::as_i64)
            .ok_or(FeatureRuntimeError::DatabaseUnavailable)?;
        let asset_key = row
            .get(&asset_field)
            .and_then(Value::as_str)
            .ok_or(FeatureRuntimeError::DatabaseUnavailable)?
            .to_owned();
        record_private_asset_authorization(app, declaration, actor_id, protected_id)?;
        Ok(Some(AuthorizedPrivateAsset {
            private_root: declaration
                .get("root")
                .and_then(Value::as_str)
                .unwrap_or_default()
                .to_owned(),
            asset_key,
        }))
    }
    #[cfg(target_os = "wasi")]
    {
        let _ = (app, request_path, actor_id);
        Err(FeatureRuntimeError::DatabaseUnavailable)
    }
}

/// Ensures a database identifier cannot change statement structure.
fn sql_identifier(value: &str) -> Result<String, FeatureRuntimeError> {
    if value.is_empty()
        || value.len() > 128
        || !value.bytes().enumerate().all(|(index, byte)| match byte {
            b'a'..=b'z' | b'A'..=b'Z' | b'_' => true,
            b'0'..=b'9' => index > 0,
            _ => false,
        })
    {
        return Err(FeatureRuntimeError::InvalidContract(value.to_owned()));
    }
    Ok(value.to_owned())
}

/// Loads one bounded JSON document from the built application artifact.
fn load_json(path: &Path) -> Result<Value, FeatureRuntimeError> {
    let text = std::fs::read_to_string(path)
        .map_err(|_| FeatureRuntimeError::InvalidContract(path.to_string_lossy().into_owned()))?;
    serde_json::from_str(&text)
        .map_err(|_| FeatureRuntimeError::InvalidContract(path.to_string_lossy().into_owned()))
}

fn manifest_declared_template_params(
    app: &AppRuntime,
) -> Result<Map<String, Value>, FeatureRuntimeError> {
    let mut params = Map::new();
    let app_root = artifact_root(app)?;
    let manifest_path = app_root.join("pharos.app.json");
    if !manifest_path.is_file() {
        return Ok(params);
    }
    let manifest = load_json(&manifest_path)?;
    let Some(payments) = manifest.get("payments").and_then(Value::as_object) else {
        return Ok(params);
    };
    if let Some(mode) = payments.get("checkout_mode").and_then(Value::as_str) {
        if mode.len() > 64 {
            return Err(FeatureRuntimeError::InvalidContract(
                "payments.checkout_mode".to_owned(),
            ));
        }
        let normalized_mode = match mode.trim().to_ascii_lowercase().as_str() {
            "live" => "live",
            _ => "demo",
        };
        let display_mode = if normalized_mode == "live" {
            "Live"
        } else {
            "Demo"
        };
        let mode_class = if normalized_mode == "live" {
            "payment-mode-live"
        } else {
            "payment-mode-demo"
        };
        params.insert(
            "payment_checkout_mode".to_owned(),
            Value::String(display_mode.to_owned()),
        );
        params.insert(
            "payment_checkout_mode_value".to_owned(),
            Value::String(normalized_mode.to_owned()),
        );
        params.insert(
            "payment_checkout_mode_class".to_owned(),
            Value::String(mode_class.to_owned()),
        );
        params.insert(
            "payment_checkout_demo_checked".to_owned(),
            Value::String(
                if normalized_mode == "demo" {
                    "checked"
                } else {
                    ""
                }
                .to_owned(),
            ),
        );
        params.insert(
            "payment_checkout_live_checked".to_owned(),
            Value::String(
                if normalized_mode == "live" {
                    "checked"
                } else {
                    ""
                }
                .to_owned(),
            ),
        );
        params.insert(
            "payment_checkout_notice_class".to_owned(),
            Value::String(
                if normalized_mode == "live" {
                    "checkout-notice-hidden"
                } else {
                    "demo-notice"
                }
                .to_owned(),
            ),
        );
        params.insert(
            "payment_checkout_decline_class".to_owned(),
            Value::String(
                if normalized_mode == "live" {
                    "checkout-action-hidden"
                } else {
                    ""
                }
                .to_owned(),
            ),
        );
        if normalized_mode == "live" {
            params.insert(
                "checkout_notice_title".to_owned(),
                Value::String(String::new()),
            );
            params.insert(
                "checkout_notice_body".to_owned(),
                Value::String(String::new()),
            );
            params.insert(
                "checkout_primary_action".to_owned(),
                Value::String("Purchase".to_owned()),
            );
        }
    }
    params.insert(
        "payment_provider_credentials_state".to_owned(),
        Value::String("not_saved".to_owned()),
    );
    params.insert(
        "payment_provider_credentials_state_display".to_owned(),
        Value::String("Not saved".to_owned()),
    );
    params.insert(
        "payment_provider_feedback_message".to_owned(),
        Value::String(String::new()),
    );
    if let Some(provider) = payments
        .get("supported_providers")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .find_map(Value::as_str)
    {
        if provider.len() > 64 {
            return Err(FeatureRuntimeError::InvalidContract(
                "payments.supported_providers".to_owned(),
            ));
        }
        params.insert(
            "payment_primary_provider".to_owned(),
            Value::String(provider.to_owned()),
        );
    }
    if let Some(copy) = payments.get("copy").and_then(Value::as_object) {
        if copy.len() > 64 {
            return Err(FeatureRuntimeError::InvalidContract(
                "payments.copy".to_owned(),
            ));
        }
        for (key, value) in copy {
            let key = sql_identifier(key)?;
            let scalar = match value {
                Value::String(text) if text.len() <= 4096 => Value::String(text.clone()),
                Value::Bool(flag) => Value::Bool(*flag),
                Value::Number(number) => Value::Number(number.clone()),
                Value::Null => Value::Null,
                _ => {
                    return Err(FeatureRuntimeError::InvalidContract(format!(
                        "payments.copy.{key}"
                    )));
                }
            };
            params.insert(key, scalar);
        }
    }
    if let Some(copy) = super::payment_provider::payment_provider_copy_entries(&app_root) {
        if copy.len() > 64 {
            return Err(FeatureRuntimeError::InvalidContract(
                "payments.provider_src".to_owned(),
            ));
        }
        for (key, value) in copy {
            params.insert(sql_identifier(&key)?, value);
        }
    }
    Ok(params)
}

/// Resolves the built artifact root used by feature contracts and templates.
fn artifact_root(app: &AppRuntime) -> Result<PathBuf, FeatureRuntimeError> {
    app.artifact_dir
        .as_deref()
        .filter(|value| !value.is_empty())
        .map(PathBuf::from)
        .ok_or(FeatureRuntimeError::DatabaseUnavailable)
}

/// Loads all declared relational entities and their allowed fields.
/// Reads a dotted object path without permitting array or prototype-style traversal.
fn dotted_value<'a>(root: &'a Value, path: &str) -> Option<&'a Value> {
    path.split('.').try_fold(root, |current, segment| {
        (!segment.is_empty()).then_some(())?;
        current.as_object()?.get(segment)
    })
}

/// Resolves one declared request, subject, binding, or literal value.
fn resolve_value(
    declaration: &Value,
    context: &FeatureRequestContext,
) -> Result<Option<Value>, FeatureRuntimeError> {
    resolve_value_with_budget(declaration, context, 32)
}

/// Bounds recursive declared value evaluation before resolving request or query bindings.
fn resolve_value_with_budget(
    declaration: &Value,
    context: &FeatureRequestContext,
    remaining: usize,
) -> Result<Option<Value>, FeatureRuntimeError> {
    if remaining == 0 {
        return Err(FeatureRuntimeError::InvalidContract(
            "value nesting limit".into(),
        ));
    }
    if !declaration.is_object() && !declaration.is_string() {
        return Ok(Some(declaration.clone()));
    }
    let roots = serde_json::json!({
        "input": context.input,
        "path": context.path_params,
        "query_param": context.query_params,
        "query": context.bindings,
        "row": context.row,
        "generated": context.generated,
        "protected": context.protected,
        "subject": {"user_id": context.actor_id},
    });
    if let Some(text) = declaration.as_str() {
        if text == "server.now" {
            return Ok(Some(Value::String(super::current_timestamp_utc())));
        }
        if text == "server.date" {
            return Ok(Some(Value::String(
                super::current_timestamp_utc()[..10].to_owned(),
            )));
        }
        for prefix in [
            "input.",
            "path.",
            "query_param.",
            "query.",
            "row.",
            "generated.",
            "protected.",
            "subject.",
        ] {
            if text.starts_with(prefix) {
                return Ok(dotted_value(&roots, text).cloned());
            }
        }
        return Ok(Some(Value::String(text.to_owned())));
    }
    let object = declaration
        .as_object()
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("value source".to_owned()))?;
    if let Some(offset) = object.get("server_time_offset_seconds") {
        let seconds = offset
            .as_i64()
            .filter(|seconds| (-31_622_400..=31_622_400).contains(seconds))
            .filter(|_| object.len() == 1)
            .ok_or_else(|| {
                FeatureRuntimeError::InvalidContract("server_time_offset_seconds".into())
            })?;
        let now = super::runtime_timestamp_seconds(&super::current_timestamp_utc())
            .and_then(|now| now.checked_add_signed(seconds))
            .ok_or_else(|| {
                FeatureRuntimeError::InvalidContract("server_time_offset_seconds".into())
            })?;
        return Ok(Some(Value::String(
            pharos_runtime_core::time::timestamp_from_epoch_seconds(now),
        )));
    }
    if let Some(spec) = object.get("pluck").and_then(Value::as_object) {
        let field = spec
            .get("field")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract("pluck.field".into()))?;
        sql_identifier(field)?;
        let rows = resolve_value_with_budget(
            spec.get("source")
                .ok_or_else(|| FeatureRuntimeError::InvalidContract("pluck.source".into()))?,
            context,
            remaining - 1,
        )?
        .ok_or_else(|| FeatureRuntimeError::InvalidInput("pluck.source".into()))?;
        let rows = rows
            .as_array()
            .filter(|rows| rows.len() <= 64)
            .ok_or_else(|| FeatureRuntimeError::InvalidInput("pluck.source".into()))?;
        let values = rows
            .iter()
            .map(|row| {
                row.as_object()
                    .and_then(|row| row.get(field))
                    .cloned()
                    .ok_or_else(|| FeatureRuntimeError::InvalidInput("pluck.field".into()))
            })
            .collect::<Result<Vec<_>, _>>()?;
        return Ok(Some(Value::Array(values)));
    }
    if let Some(spec) = object.get("lookup").and_then(Value::as_object) {
        let values = spec
            .get("values")
            .and_then(Value::as_object)
            .filter(|values| !values.is_empty() && values.len() <= 64)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract("lookup.values".into()))?;
        let key = resolve_value_with_budget(
            spec.get("key")
                .ok_or_else(|| FeatureRuntimeError::InvalidContract("lookup.key".into()))?,
            context,
            remaining - 1,
        )?;
        let Some(key) = key else {
            return Ok(None);
        };
        let key = key
            .as_str()
            .filter(|key| key.len() <= 128)
            .ok_or_else(|| FeatureRuntimeError::InvalidInput("lookup.key".into()))?;
        if key.is_empty() {
            return Ok(None);
        }
        let value = values
            .get(key)
            .ok_or_else(|| FeatureRuntimeError::InvalidInput("lookup.key".into()))?;
        return if value.is_null() {
            Ok(None)
        } else {
            resolve_value_with_budget(value, context, remaining - 1)
        };
    }
    if let Some(values) = object.get("coalesce").and_then(Value::as_array) {
        if values.is_empty() || values.len() > 8 {
            return Err(FeatureRuntimeError::InvalidContract("coalesce".into()));
        }
        for value in values {
            if let Some(value) = resolve_value_with_budget(value, context, remaining - 1)?
                .filter(|value| !value.is_null())
            {
                return Ok(Some(value));
            }
        }
        return Ok(None);
    }
    if let Some(values) = object.get("add").and_then(Value::as_array) {
        if values.is_empty() || values.len() > 8 {
            return Err(FeatureRuntimeError::InvalidContract("add".into()));
        }
        let mut total = 0_i64;
        for value in values {
            let value = resolve_value_with_budget(value, context, remaining - 1)?
                .and_then(|value| value.as_i64())
                .ok_or_else(|| FeatureRuntimeError::InvalidInput("add".into()))?;
            total = total
                .checked_add(value)
                .ok_or_else(|| FeatureRuntimeError::Conflict("checked add".into()))?;
        }
        return Ok(Some(Value::from(total)));
    }
    if let Some(spec) = object.get("format_minor").and_then(Value::as_object) {
        let amount = resolve_value_with_budget(
            spec.get("amount").ok_or_else(|| {
                FeatureRuntimeError::InvalidContract("format_minor.amount".into())
            })?,
            context,
            remaining - 1,
        )?
        .and_then(|value| value.as_i64())
        .filter(|amount| *amount >= 0)
        .ok_or_else(|| FeatureRuntimeError::InvalidInput("format_minor.amount".into()))?;
        let currency = resolve_value_with_budget(
            spec.get("currency").ok_or_else(|| {
                FeatureRuntimeError::InvalidContract("format_minor.currency".into())
            })?,
            context,
            remaining - 1,
        )?
        .and_then(|value| value.as_str().map(str::to_owned))
        .ok_or_else(|| FeatureRuntimeError::InvalidInput("format_minor.currency".into()))?;
        let value = super::json_commands::currency_minor_text(amount, &currency)
            .ok_or_else(|| FeatureRuntimeError::InvalidInput("format_minor.currency".into()))?;
        return Ok(Some(Value::from(value)));
    }
    if let Some(value) = object.get("literal") {
        return Ok(Some(value.clone()));
    }
    for (key, root_name) in [
        ("input", "input"),
        ("path", "path"),
        ("query_param", "query_param"),
        ("binding", "query"),
        ("row", "row"),
        ("generated", "generated"),
        ("protected", "protected"),
        ("subject", "subject"),
    ] {
        if let Some(field) = object.get(key).and_then(Value::as_str) {
            return Ok(dotted_value(&roots, &format!("{root_name}.{field}")).cloned());
        }
    }
    if object.get("server").and_then(Value::as_str) == Some("now") {
        return Ok(Some(Value::String(super::current_timestamp_utc())));
    }
    if let Some(seconds) = object
        .get("server_now_minus_seconds")
        .and_then(Value::as_u64)
    {
        if seconds > 604_800 {
            return Err(FeatureRuntimeError::InvalidContract(
                "server_now_minus_seconds".to_owned(),
            ));
        }
        return Ok(Some(Value::String(timestamp_before_seconds_utc(seconds))));
    }
    if let Some(spec) = object.get("pad_integer").and_then(Value::as_object) {
        let width = spec
            .get("width")
            .and_then(Value::as_u64)
            .filter(|width| (1..=19).contains(width))
            .ok_or_else(|| FeatureRuntimeError::InvalidContract("pad_integer.width".to_owned()))?
            as usize;
        let value = resolve_value_with_budget(
            spec.get("value").ok_or_else(|| {
                FeatureRuntimeError::InvalidContract("pad_integer.value".to_owned())
            })?,
            context,
            remaining - 1,
        )?
        .and_then(|value| value.as_i64())
        .filter(|value| *value >= 0)
        .ok_or_else(|| FeatureRuntimeError::InvalidInput("pad_integer.value".to_owned()))?;
        let output = format!("{value:0width$}");
        if output.len() > width {
            return Err(FeatureRuntimeError::InvalidInput(
                "pad_integer.width".to_owned(),
            ));
        }
        return Ok(Some(Value::String(output)));
    }
    if let Some(parts) = object.get("concat").and_then(Value::as_array) {
        if parts.is_empty() || parts.len() > 16 {
            return Err(FeatureRuntimeError::InvalidContract("concat".to_owned()));
        }
        let mut output = String::new();
        for part in parts {
            let value = resolve_value_with_budget(part, context, remaining - 1)?
                .ok_or_else(|| FeatureRuntimeError::InvalidInput("concat".to_owned()))?;
            let text = value
                .as_str()
                .map(ToOwned::to_owned)
                .or_else(|| value.as_i64().map(|number| number.to_string()))
                .ok_or_else(|| FeatureRuntimeError::InvalidInput("concat".to_owned()))?;
            if output.len().saturating_add(text.len()) > 512 {
                return Err(FeatureRuntimeError::InvalidInput("concat".to_owned()));
            }
            output.push_str(&text);
        }
        return Ok(Some(Value::String(output)));
    }
    if let Some(sum) = object.get("sum").and_then(Value::as_object) {
        let query = sum
            .get("query")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract("sum.query".to_owned()))?;
        let field = sum
            .get("field")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract("sum.field".to_owned()))?;
        sql_identifier(query)?;
        sql_identifier(field)?;
        let max_items = sum
            .get("max_items")
            .and_then(Value::as_u64)
            .unwrap_or(20)
            .min(MAX_QUERY_ROWS as u64) as usize;
        let rows = context
            .bindings
            .get(query)
            .and_then(Value::as_array)
            .ok_or_else(|| FeatureRuntimeError::MissingRecord(query.to_owned()))?;
        if rows.is_empty() || rows.len() > max_items {
            return Err(FeatureRuntimeError::Conflict("bounded sum".to_owned()));
        }
        let total = rows.iter().try_fold(0i64, |total, row| {
            row.get(field)
                .and_then(Value::as_i64)
                .and_then(|value| total.checked_add(value))
        });
        return total
            .map(Value::from)
            .map(Some)
            .ok_or_else(|| FeatureRuntimeError::Conflict("checked sum".to_owned()));
    }
    Err(FeatureRuntimeError::InvalidContract(
        "value source".to_owned(),
    ))
}

/// Selects one contract variant using a previously validated scalar request value.
fn selected_contract_variant<'a>(
    contract: &'a Value,
    context: &FeatureRequestContext,
) -> Result<&'a Value, FeatureRuntimeError> {
    let Some(variants) = contract.get("variants").and_then(Value::as_object) else {
        return Ok(contract);
    };
    if variants.is_empty() || variants.len() > 16 {
        return Err(FeatureRuntimeError::InvalidContract(
            "contract variants".to_owned(),
        ));
    }
    let selector = contract
        .get("select")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("contract select".to_owned()))?;
    let selected = resolve_value(&Value::String(selector.to_owned()), context)?
        .and_then(|value| value.as_str().map(ToOwned::to_owned))
        .ok_or_else(|| FeatureRuntimeError::InvalidInput("contract select".to_owned()))?;
    sql_identifier(&selected)?;
    variants
        .get(&selected)
        .ok_or_else(|| FeatureRuntimeError::InvalidInput("contract variant".to_owned()))
}

/// Collects every named query binding referenced by a transaction declaration.
#[cfg(not(target_os = "wasi"))]
/// Performs referenced queries.
fn referenced_queries(value: &Value, output: &mut BTreeSet<String>) {
    match value {
        Value::Array(items) => {
            for item in items {
                referenced_queries(item, output);
            }
        }
        Value::Object(fields) => {
            if let Some(query) = fields.get("query").and_then(Value::as_str) {
                output.insert(query.to_owned());
            }
            if let Some(binding) = fields.get("binding").and_then(Value::as_str)
                && let Some(query) = binding.split('.').next()
                && !query.is_empty()
            {
                output.insert(query.to_owned());
            }
            for item in fields.values() {
                referenced_queries(item, output);
            }
        }
        Value::String(text) => {
            if let Some(binding) = text.strip_prefix("query.")
                && let Some(query) = binding.split('.').next()
                && !query.is_empty()
            {
                output.insert(query.to_owned());
            }
        }
        Value::Null | Value::Bool(_) | Value::Number(_) => {}
    }
}

/// Collects named opaque values referenced by one transaction declaration.
#[cfg(not(target_os = "wasi"))]
/// Performs generated values.
fn generated_values(value: &Value, output: &mut BTreeSet<String>) {
    match value {
        Value::Array(items) => {
            for item in items {
                generated_values(item, output);
            }
        }
        Value::Object(fields) => {
            if let Some(name) = fields.get("generated").and_then(Value::as_str) {
                output.insert(name.to_owned());
            }
            for item in fields.values() {
                generated_values(item, output);
            }
        }
        Value::String(text) => {
            if let Some(name) = text.strip_prefix("generated.")
                && !name.is_empty()
            {
                output.insert(name.to_owned());
            }
        }
        Value::Null | Value::Bool(_) | Value::Number(_) => {}
    }
}

/// Generates all transaction-scoped opaque values before the database transaction starts.
#[cfg(not(target_os = "wasi"))]
/// Performs populate generated values.
fn populate_generated_values(
    transaction: &Value,
    context: &mut FeatureRequestContext,
) -> Result<(), FeatureRuntimeError> {
    let mut names = BTreeSet::new();
    generated_values(transaction, &mut names);
    for name in names {
        sql_identifier(&name)?;
        let value = super::dynamic::random_secret_hex(16)
            .map_err(|_| FeatureRuntimeError::DatabaseUnavailable)?;
        context.generated.insert(name, Value::String(value));
    }
    Ok(())
}

/// Returns one bounded validation report payload for a feature action rejection.
fn validation_report(
    action_id: &str,
    errors: Vec<String>,
    field_error: Option<(String, String, String)>,
    form_error: Option<(String, String, String)>,
) -> String {
    let mut root = Map::new();
    root.insert(
        "schema".to_owned(),
        Value::String("pharos.validation.report.v1".to_owned()),
    );
    root.insert(
        "report_id".to_owned(),
        Value::String("pharos.validation.report.v1".to_owned()),
    );
    root.insert("action_id".to_owned(), Value::String(action_id.to_owned()));
    root.insert(
        "errors".to_owned(),
        Value::Array(errors.into_iter().take(8).map(Value::String).collect()),
    );
    let mut field_errors = Vec::new();
    if let Some((field_id, code, message)) = field_error {
        let mut entry = Map::new();
        entry.insert("field_id".to_owned(), Value::String(field_id));
        entry.insert("rule_id".to_owned(), Value::String(code.clone()));
        entry.insert("code".to_owned(), Value::String(code));
        entry.insert("message".to_owned(), Value::String(message));
        field_errors.push(Value::Object(entry));
    }
    let mut form_errors = Vec::new();
    if let Some((rule_id, code, message)) = form_error {
        let mut entry = Map::new();
        entry.insert("rule_id".to_owned(), Value::String(rule_id));
        entry.insert("code".to_owned(), Value::String(code));
        entry.insert("message".to_owned(), Value::String(message));
        form_errors.push(Value::Object(entry));
    }
    root.insert("field_errors".to_owned(), Value::Array(field_errors));
    root.insert("form_errors".to_owned(), Value::Array(form_errors));
    Value::Object(root).to_string()
}

fn validation_report_with_field_errors(
    action_id: &str,
    field_errors: Vec<(String, String, String)>,
) -> String {
    let errors = field_errors
        .iter()
        .take(8)
        .map(|(_, code, _)| Value::String(code.clone()))
        .collect::<Vec<_>>();
    let field_errors = field_errors
        .into_iter()
        .take(8)
        .map(|(field_id, code, message)| {
            let mut entry = Map::new();
            entry.insert("field_id".to_owned(), Value::String(field_id));
            entry.insert("rule_id".to_owned(), Value::String(code.clone()));
            entry.insert("code".to_owned(), Value::String(code));
            entry.insert("message".to_owned(), Value::String(message));
            Value::Object(entry)
        })
        .collect::<Vec<_>>();
    serde_json::json!({
        "schema": "pharos.validation.report.v1",
        "report_id": "pharos.validation.report.v1",
        "action_id": action_id,
        "errors": errors,
        "field_errors": field_errors,
        "form_errors": []
    })
    .to_string()
}

fn feature_field_validation_code(rules: &Value, default_code: &str) -> String {
    rules
        .get("validation_code")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .filter(|value| value.len() <= 80)
        .filter(|value| {
            value
                .chars()
                .all(|ch| ch.is_ascii_alphanumeric() || ch == '_' || ch == '-')
        })
        .unwrap_or(default_code)
        .to_owned()
}

/// Converts one JSON scalar request value into the string input form used by validators.
fn json_scalar_input(value: &Value) -> Option<String> {
    match value {
        Value::String(value) => Some(value.clone()),
        Value::Number(value) => Some(value.to_string()),
        Value::Bool(value) => Some(value.to_string()),
        Value::Null => None,
        _ => None,
    }
}

/// Resolves one request header without accepting folded lines.
fn request_header_value(request: &super::http::HttpRequest, header_name: &str) -> Option<String> {
    request.headers.lines().find_map(|line| {
        let (name, value) = line.split_once(':')?;
        name.trim()
            .eq_ignore_ascii_case(header_name)
            .then(|| value.trim().to_owned())
    })
}

/// Performs scalar value to text.
fn scalar_value_to_text(value: &Value) -> String {
    match value {
        Value::Null => String::new(),
        Value::Bool(value) => value.to_string(),
        Value::Number(value) => value.to_string(),
        Value::String(value) => value.clone(),
        Value::Array(_) | Value::Object(_) => String::new(),
    }
}

/// Applies bounded derived-input hooks before typed validation.
fn apply_derived_input_hooks(
    mut raw: BTreeMap<String, String>,
    request: &super::http::HttpRequest,
    declared: &Map<String, Value>,
    hook_contract: Option<&Value>,
) -> Result<BTreeMap<String, String>, FeatureRuntimeError> {
    let query_params = query_parameters(&request.target)?;
    let Some(rows) = hook_contract
        .and_then(|value| value.get("derived_inputs"))
        .and_then(Value::as_array)
    else {
        return Ok(raw);
    };
    if rows.len() > MAX_QUERY_FILTERS {
        return Err(FeatureRuntimeError::InvalidContract(
            "hook_contract.derived_inputs".to_owned(),
        ));
    }
    for row in rows {
        let field = row
            .get("field")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty() && value.len() <= 128)
            .ok_or_else(|| {
                FeatureRuntimeError::InvalidContract(
                    "hook_contract.derived_inputs.field".to_owned(),
                )
            })?;
        if !declared.contains_key(field) {
            return Err(FeatureRuntimeError::InvalidContract(
                "hook_contract.derived_inputs.field".to_owned(),
            ));
        }
        if row
            .get("preserve_existing")
            .and_then(Value::as_bool)
            .unwrap_or(false)
            && raw.get(field).is_some_and(|value| !value.is_empty())
        {
            continue;
        }
        let source = row
            .get("source")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let derived = match source {
            "literal" => row
                .get("value")
                .map(scalar_value_to_text)
                .filter(|value| !value.is_empty()),
            "header" => row
                .get("header")
                .and_then(Value::as_str)
                .and_then(|header| request_header_value(request, header))
                .filter(|value| !value.is_empty()),
            "query" => row
                .get("param")
                .or_else(|| row.get("query_param"))
                .and_then(Value::as_str)
                .and_then(|field| query_params.get(field).cloned())
                .and_then(|value| value.as_str().map(ToOwned::to_owned))
                .filter(|value| !value.is_empty()),
            "form" => row
                .get("from_field")
                .or_else(|| row.get("input_field"))
                .and_then(Value::as_str)
                .and_then(|field| raw.get(field).cloned())
                .filter(|value| !value.is_empty()),
            "context_method" => (!request.method.is_empty()).then(|| request.method.clone()),
            "context_path" => request
                .target
                .split('?')
                .next()
                .filter(|value| !value.is_empty())
                .map(ToOwned::to_owned),
            _ => {
                return Err(FeatureRuntimeError::InvalidContract(
                    "hook_contract.derived_inputs.source".to_owned(),
                ));
            }
        };
        match derived {
            Some(value) => {
                raw.insert(field.to_owned(), value);
            }
            None => {
                raw.remove(field);
            }
        }
    }
    Ok(raw)
}

/// Performs apply default input hooks.
fn apply_default_input_hooks(
    mut raw: BTreeMap<String, String>,
    request: &super::http::HttpRequest,
    declared: &Map<String, Value>,
    hook_contract: Option<&Value>,
) -> Result<BTreeMap<String, String>, FeatureRuntimeError> {
    let query_params = query_parameters(&request.target)?;
    let Some(rows) = hook_contract
        .and_then(|value| value.get("default_inputs"))
        .and_then(Value::as_array)
    else {
        return Ok(raw);
    };
    if rows.len() > MAX_QUERY_FILTERS {
        return Err(FeatureRuntimeError::InvalidContract(
            "hook_contract.default_inputs".to_owned(),
        ));
    }
    for row in rows {
        let field = row
            .get("field")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty() && value.len() <= 128)
            .ok_or_else(|| {
                FeatureRuntimeError::InvalidContract(
                    "hook_contract.default_inputs.field".to_owned(),
                )
            })?;
        if !declared.contains_key(field) {
            return Err(FeatureRuntimeError::InvalidContract(
                "hook_contract.default_inputs.field".to_owned(),
            ));
        }
        if raw.get(field).is_some_and(|value| !value.is_empty()) {
            continue;
        }
        let source = row
            .get("source")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let derived = match source {
            "literal" => row.get("value").map(scalar_value_to_text),
            "header" => row
                .get("header")
                .and_then(Value::as_str)
                .and_then(|header| request_header_value(request, header))
                .filter(|value| !value.is_empty()),
            "query" => row
                .get("param")
                .or_else(|| row.get("query_param"))
                .and_then(Value::as_str)
                .and_then(|field| query_params.get(field).cloned())
                .and_then(|value| value.as_str().map(ToOwned::to_owned))
                .filter(|value| !value.is_empty()),
            "form" => row
                .get("from_field")
                .or_else(|| row.get("input_field"))
                .and_then(Value::as_str)
                .and_then(|field| raw.get(field).cloned())
                .filter(|value| !value.is_empty()),
            "context_method" => (!request.method.is_empty()).then(|| request.method.clone()),
            "context_path" => request
                .target
                .split('?')
                .next()
                .filter(|value| !value.is_empty())
                .map(ToOwned::to_owned),
            _ => {
                return Err(FeatureRuntimeError::InvalidContract(
                    "hook_contract.default_inputs.source".to_owned(),
                ));
            }
        };
        match derived {
            Some(value) => {
                raw.insert(field.to_owned(), value);
            }
            None => {
                raw.remove(field);
            }
        }
    }
    Ok(raw)
}

/// Applies one bounded string-normalization hook sequence to validated action input.
fn apply_input_normalization_hooks(
    mut input: Map<String, Value>,
    hook_contract: Option<&Value>,
) -> Result<Map<String, Value>, FeatureRuntimeError> {
    let Some(hooks) = hook_contract
        .and_then(|value| value.get("normalize_inputs"))
        .and_then(Value::as_array)
    else {
        return Ok(input);
    };
    for hook in hooks {
        let kind = hook
            .get("kind")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract("hook_contract.kind".to_owned()))?;
        let fields = hook
            .get("fields")
            .and_then(Value::as_array)
            .ok_or_else(|| {
                FeatureRuntimeError::InvalidContract("hook_contract.fields".to_owned())
            })?;
        for field in fields {
            let field = field.as_str().ok_or_else(|| {
                FeatureRuntimeError::InvalidContract("hook_contract.fields".to_owned())
            })?;
            if field.is_empty() || field.len() > 128 {
                return Err(FeatureRuntimeError::InvalidContract(
                    "hook_contract.fields".to_owned(),
                ));
            }
            let Some(current) = input.get(field).cloned() else {
                continue;
            };
            let Some(text) = current.as_str() else {
                continue;
            };
            let next = match kind {
                "trim" => Some(text.trim().to_owned()),
                "collapse_whitespace" => Some(
                    text.split_whitespace()
                        .filter(|segment| !segment.is_empty())
                        .collect::<Vec<_>>()
                        .join(" "),
                ),
                "lowercase" => Some(text.to_ascii_lowercase()),
                "uppercase" => Some(text.to_ascii_uppercase()),
                "empty_to_null" => (!text.trim().is_empty()).then_some(text.to_owned()),
                _ => {
                    return Err(FeatureRuntimeError::InvalidContract(
                        "hook_contract.kind".to_owned(),
                    ));
                }
            };
            match next {
                Some(value) => {
                    input.insert(field.to_owned(), Value::String(value));
                }
                None => {
                    input.remove(field);
                }
            }
        }
    }
    Ok(input)
}

/// Parses and validates URL-encoded action fields against an inline input contract.
fn declared_input_preflight_errors(
    declared: &Map<String, Value>,
    raw: &BTreeMap<String, String>,
) -> Vec<(String, String, String)> {
    let mut errors = Vec::new();
    for (field, rules) in declared {
        let Some(value) = raw.get(field) else {
            continue;
        };
        if rules.get("type").and_then(Value::as_str) == Some("enum")
            && !rules
                .get("values")
                .and_then(Value::as_array)
                .is_some_and(|values| values.iter().any(|item| item.as_str() == Some(value)))
        {
            errors.push((
                field.clone(),
                feature_field_validation_code(rules, "field_invalid"),
                "The supplied value is not one of the declared enum choices.".to_owned(),
            ));
        }
        if let Some(other_field) = rules.get("after_field").and_then(Value::as_str)
            && let Some(other_value) = raw.get(other_field)
            && !value.is_empty()
            && !other_value.is_empty()
            && value <= other_value
        {
            errors.push((
                field.clone(),
                feature_field_validation_code(rules, "field_invalid"),
                "The supplied value must be after the referenced field.".to_owned(),
            ));
        }
    }
    errors
}

fn validated_action_input(
    request: &super::http::HttpRequest,
    contract: &Value,
    hook_contract: Option<&Value>,
    action_id: &str,
) -> Result<Map<String, Value>, FeatureRuntimeError> {
    let large_text = contract
        .get("inline_fields")
        .and_then(Value::as_object)
        .is_some_and(|fields| {
            fields
                .values()
                .take(33)
                .any(|field| field.get("large_text") == Some(&Value::Bool(true)))
        });
    let body_limit = if large_text { 128 * 1024 } else { 64 * 1024 };
    if request.body.len() > body_limit || request.body_file_path.is_some() {
        return Err(FeatureRuntimeError::ValidationReport(validation_report(
            action_id,
            vec!["body_invalid".to_owned()],
            None,
            Some((
                "body_invalid".to_owned(),
                "body_invalid".to_owned(),
                "Request body must fit within the supported bounds.".to_owned(),
            )),
        )));
    }
    let declared = contract
        .get("inline_fields")
        .and_then(Value::as_object)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("input_contract".to_owned()))?;
    if declared.len() > MAX_QUERY_FILTERS {
        return Err(FeatureRuntimeError::InvalidContract(
            "input field count".to_owned(),
        ));
    }
    let mut raw = BTreeMap::new();
    if request
        .content_type
        .as_deref()
        .is_some_and(|value| value.starts_with("application/json"))
    {
        let body = std::str::from_utf8(&request.body).map_err(|_| {
            FeatureRuntimeError::ValidationReport(validation_report(
                action_id,
                vec!["json_object_required".to_owned()],
                None,
                Some((
                    "json_object_required".to_owned(),
                    "json_object_required".to_owned(),
                    "JSON request bodies must be valid top-level objects.".to_owned(),
                )),
            ))
        })?;
        let object = serde_json::from_str::<Value>(body)
            .ok()
            .and_then(|value| value.as_object().cloned())
            .ok_or_else(|| {
                FeatureRuntimeError::ValidationReport(validation_report(
                    action_id,
                    vec!["json_object_required".to_owned()],
                    None,
                    Some((
                        "json_object_required".to_owned(),
                        "json_object_required".to_owned(),
                        "JSON request bodies must be valid top-level objects.".to_owned(),
                    )),
                ))
            })?;
        for (key, value) in object {
            if !declared.contains_key(&key) {
                return Err(FeatureRuntimeError::ValidationReport(validation_report(
                    action_id,
                    vec!["undeclared_field".to_owned()],
                    Some((
                        key,
                        "undeclared_field".to_owned(),
                        "The request includes a field that is not part of the action contract."
                            .to_owned(),
                    )),
                    None,
                )));
            }
            let Some(value) = json_scalar_input(&value) else {
                return Err(FeatureRuntimeError::ValidationReport(validation_report(
                    action_id,
                    vec!["field_invalid".to_owned()],
                    Some((
                        key,
                        "field_invalid".to_owned(),
                        "Only scalar JSON values are accepted for declared input fields."
                            .to_owned(),
                    )),
                    None,
                )));
            };
            raw.insert(key, value);
        }
    } else {
        let body = std::str::from_utf8(&request.body).map_err(|_| {
            FeatureRuntimeError::ValidationReport(validation_report(
                action_id,
                vec!["body_invalid".to_owned()],
                None,
                Some((
                    "body_invalid".to_owned(),
                    "body_invalid".to_owned(),
                    "The request body could not be decoded.".to_owned(),
                )),
            ))
        })?;
        for pair in body.split('&').filter(|pair| !pair.is_empty()) {
            let (key, value) = pair.split_once('=').unwrap_or((pair, ""));
            let key = super::json_commands::url_decode(key).ok_or_else(|| {
                FeatureRuntimeError::ValidationReport(validation_report(
                    action_id,
                    vec!["field_invalid".to_owned()],
                    None,
                    Some((
                        "field_invalid".to_owned(),
                        "field_invalid".to_owned(),
                        "The request contained an invalid field encoding.".to_owned(),
                    )),
                ))
            })?;
            let value = super::json_commands::url_decode(value).ok_or_else(|| {
                FeatureRuntimeError::ValidationReport(validation_report(
                    action_id,
                    vec!["field_invalid".to_owned()],
                    Some((
                        key.clone(),
                        "field_invalid".to_owned(),
                        "The request contained an invalid field encoding.".to_owned(),
                    )),
                    None,
                ))
            })?;
            if key == "csrf_token" {
                continue;
            }
            if !declared.contains_key(&key) || raw.insert(key.clone(), value).is_some() {
                return Err(FeatureRuntimeError::ValidationReport(validation_report(
                    action_id,
                    vec!["undeclared_field".to_owned()],
                    Some((
                        key,
                        "undeclared_field".to_owned(),
                        "The request includes a field that is not part of the action contract."
                            .to_owned(),
                    )),
                    None,
                )));
            }
        }
    }
    raw = apply_derived_input_hooks(raw, request, declared, hook_contract)?;
    raw = apply_default_input_hooks(raw, request, declared, hook_contract)?;
    let preflight_errors = declared_input_preflight_errors(declared, &raw);
    if !preflight_errors.is_empty() {
        return Err(FeatureRuntimeError::ValidationReport(
            validation_report_with_field_errors(action_id, preflight_errors),
        ));
    }
    let mut input = Map::new();
    for (field, rules) in declared {
        sql_identifier(field)?;
        let required = rules
            .get("required")
            .and_then(Value::as_bool)
            .unwrap_or(false);
        let Some(mut value) = raw.remove(field) else {
            if required {
                let code = feature_field_validation_code(rules, "missing_required_field");
                return Err(FeatureRuntimeError::ValidationReport(validation_report(
                    action_id,
                    vec![code.clone()],
                    Some((
                        field.clone(),
                        code,
                        "A required field was not provided.".to_owned(),
                    )),
                    None,
                )));
            }
            continue;
        };
        let field_ceiling = match rules.get("large_text") {
            None | Some(Value::Bool(false)) => 8 * 1024,
            Some(Value::Bool(true))
                if rules.get("type").and_then(Value::as_str) == Some("string") =>
            {
                32 * 1024
            }
            _ => {
                return Err(FeatureRuntimeError::InvalidContract(
                    "input.large_text".to_owned(),
                ));
            }
        };
        let max_length = rules
            .get("max_length")
            .and_then(Value::as_u64)
            .unwrap_or(256)
            .min(field_ceiling) as usize;
        let min_length = rules
            .get("min_length")
            .and_then(Value::as_u64)
            .unwrap_or(0)
            .min(max_length as u64) as usize;
        if value.len() > max_length
            || value.len() < min_length
            || (required && value.trim().is_empty())
        {
            let code = feature_field_validation_code(rules, "field_invalid");
            return Err(FeatureRuntimeError::ValidationReport(validation_report(
                action_id,
                vec![code.clone()],
                Some((
                    field.clone(),
                    code,
                    "The supplied value does not satisfy the declared bounds.".to_owned(),
                )),
                None,
            )));
        }
        if !declared_input_format_valid(rules.get("format").and_then(Value::as_str), &value)? {
            return Err(FeatureRuntimeError::InvalidInput(field.clone()));
        }
        if rules.get("format").and_then(Value::as_str) == Some("date_or_timestamp")
            && value.len() == 10
        {
            value.push_str("T00:00:00Z");
        }
        if matches!(
            rules.get("format").and_then(Value::as_str),
            Some("timestamp" | "date_or_timestamp")
        ) && !value.is_empty()
        {
            value = pharos_runtime_database::operations::canonical_stored_timestamp(&value)
                .map_err(|_| FeatureRuntimeError::InvalidInput(field.clone()))?;
        }
        if matches!(
            rules.get("format").and_then(Value::as_str),
            Some("https_url" | "web_url")
        ) && !value.is_empty()
        {
            value = super::outbound_url::web_url(&value)
                .ok_or_else(|| FeatureRuntimeError::InvalidInput(field.clone()))?
                .to_string();
        }
        let typed = match rules
            .get("type")
            .and_then(Value::as_str)
            .unwrap_or("string")
        {
            "string" => Value::String(value),
            "integer" => Value::from(
                value
                    .parse::<i64>()
                    .ok()
                    .filter(|number| {
                        rules
                            .get("minimum")
                            .and_then(Value::as_i64)
                            .is_none_or(|minimum| *number >= minimum)
                            && rules
                                .get("maximum")
                                .and_then(Value::as_i64)
                                .is_none_or(|maximum| *number <= maximum)
                    })
                    .ok_or_else(|| {
                        FeatureRuntimeError::ValidationReport(validation_report(
                            action_id,
                            vec!["field_invalid".to_owned()],
                            Some((
                                field.clone(),
                                "field_invalid".to_owned(),
                                "The supplied integer value is outside the declared bounds."
                                    .to_owned(),
                            )),
                            None,
                        ))
                    })?,
            ),
            "boolean" => {
                let normalized = value.trim().to_ascii_lowercase();
                match normalized.as_str() {
                    "true" | "1" | "yes" | "on" => Value::Bool(true),
                    "false" | "0" | "no" | "off" => Value::Bool(false),
                    _ => {
                        return Err(FeatureRuntimeError::ValidationReport(validation_report(
                            action_id,
                            vec!["field_invalid".to_owned()],
                            Some((
                                field.clone(),
                                "field_invalid".to_owned(),
                                "The supplied boolean value is outside the declared bounds."
                                    .to_owned(),
                            )),
                            None,
                        )));
                    }
                }
            }
            "enum" => {
                if !rules
                    .get("values")
                    .and_then(Value::as_array)
                    .is_some_and(|values| values.iter().any(|item| item.as_str() == Some(&value)))
                {
                    let code = feature_field_validation_code(rules, "field_invalid");
                    return Err(FeatureRuntimeError::ValidationReport(validation_report(
                        action_id,
                        vec![code.clone()],
                        Some((
                            field.clone(),
                            code,
                            "The supplied value is not one of the declared enum choices."
                                .to_owned(),
                        )),
                        None,
                    )));
                }
                Value::String(value)
            }
            _ => {
                return Err(FeatureRuntimeError::InvalidContract(format!(
                    "input.{field}.type"
                )));
            }
        };
        input.insert(field.clone(), typed);
    }
    for (field, rules) in declared {
        if let Some(earlier) = rules.get("not_before").and_then(Value::as_str) {
            if !matches!(
                rules.get("format").and_then(Value::as_str),
                Some("timestamp" | "date_or_timestamp")
            ) || !matches!(
                declared
                    .get(earlier)
                    .and_then(|rules| rules.get("format"))
                    .and_then(Value::as_str),
                Some("timestamp" | "date_or_timestamp")
            ) {
                return Err(FeatureRuntimeError::InvalidContract(
                    "input.not_before".into(),
                ));
            }
            if let (Some(end), Some(start)) = (
                input.get(field).and_then(Value::as_str),
                input.get(earlier).and_then(Value::as_str),
            ) && !end.is_empty()
                && !start.is_empty()
                && end < start
            {
                return Err(FeatureRuntimeError::InvalidInput(field.clone()));
            }
        }
    }
    if !raw.is_empty() {
        return Err(FeatureRuntimeError::ValidationReport(validation_report(
            action_id,
            vec!["undeclared_field".to_owned()],
            None,
            Some((
                "undeclared_field".to_owned(),
                "undeclared_field".to_owned(),
                "The request includes a field that is not part of the action contract.".to_owned(),
            )),
        )));
    }
    apply_input_normalization_hooks(input, hook_contract)
}

/// Validates optional contact/link formats without changing existing string inputs.
fn declared_input_format_valid(
    format: Option<&str>,
    value: &str,
) -> Result<bool, FeatureRuntimeError> {
    match format {
        None => Ok(true),
        Some("email") => {
            Ok(value.is_empty() || super::json_commands::generated_surface_text_is_email(value))
        }
        Some("date") => Ok(value.is_empty()
            || value.len() == 10
                && pharos_runtime_database::operations::canonical_stored_timestamp(&format!(
                    "{value}T00:00:00Z"
                ))
                .is_ok()),
        Some("date_or_timestamp") => Ok(declared_input_format_valid(Some("date"), value)?
            || declared_input_format_valid(Some("timestamp"), value)?),
        Some("timestamp") => Ok(value.is_empty()
            || value
                .as_bytes()
                .get(10)
                .is_some_and(|ch| matches!(ch, b'T' | b't'))
                && (value.ends_with(['Z', 'z'])
                    || value
                        .get(19..)
                        .is_some_and(|tail| tail.contains(['+', '-'])))
                && pharos_runtime_database::operations::canonical_stored_timestamp(value).is_ok()),
        Some("utc_offset") => {
            let bytes = value.as_bytes();
            Ok(value.is_empty()
                || value == "UTC"
                || bytes.len() == 6
                    && matches!(bytes[0], b'+' | b'-')
                    && bytes[3] == b':'
                    && [1, 2, 4, 5].into_iter().all(|i| bytes[i].is_ascii_digit())
                    && value[1..3].parse::<u8>().is_ok_and(|hour| hour <= 23)
                    && value[4..6].parse::<u8>().is_ok_and(|minute| minute <= 59))
        }
        Some("https_url") => {
            Ok(value.is_empty() || super::outbound_url::https_url(value).is_some())
        }
        Some("web_url") => Ok(value.is_empty() || super::outbound_url::web_url(value).is_some()),
        Some(_) => Err(FeatureRuntimeError::InvalidContract(
            "input.format".to_owned(),
        )),
    }
}

/// Converts one bound query result into the row-set shape used by aggregate guards.
#[cfg(not(target_os = "wasi"))]
/// Performs guard binding rows.
fn guard_binding_rows<'a>(
    query_id: &str,
    value: &'a Value,
) -> Result<Vec<&'a Map<String, Value>>, FeatureRuntimeError> {
    match value {
        Value::Array(rows) => rows
            .iter()
            .map(|row| {
                row.as_object()
                    .ok_or_else(|| FeatureRuntimeError::InvalidContract(query_id.to_owned()))
            })
            .collect(),
        Value::Object(row) => Ok(vec![row]),
        Value::Null => Ok(Vec::new()),
        _ => Err(FeatureRuntimeError::InvalidContract(query_id.to_owned())),
    }
}

/// Evaluates generic numeric comparisons for one declared guard metric.
#[cfg(not(target_os = "wasi"))]
/// Performs guard bounds satisfied.
fn guard_bounds_satisfied(actual: i64, guard: &Value) -> bool {
    guard
        .get("minimum")
        .and_then(Value::as_i64)
        .is_none_or(|minimum| actual >= minimum)
        && guard
            .get("maximum")
            .and_then(Value::as_i64)
            .is_none_or(|maximum| actual <= maximum)
        && guard
            .get("equals")
            .and_then(Value::as_i64)
            .is_none_or(|expected| actual == expected)
}

/// Rejects a transaction when one declared aggregate or existence guard fails.
#[cfg(not(target_os = "wasi"))]
/// Performs evaluate guard contract.
fn evaluate_guard_contract(
    action_id: &str,
    guard_contract: Option<&Value>,
    context: &FeatureRequestContext,
) -> Result<(), FeatureRuntimeError> {
    let Some(guards) = guard_contract
        .and_then(|contract| contract.get("guards"))
        .and_then(Value::as_array)
    else {
        return Ok(());
    };
    if guards.len() > 16 {
        return Err(FeatureRuntimeError::InvalidContract(format!(
            "{action_id}.guards"
        )));
    }
    for guard in guards {
        let guard_id = guard
            .get("guard_id")
            .and_then(Value::as_str)
            .unwrap_or("guard_failed");
        let kind = guard.get("kind").and_then(Value::as_str).ok_or_else(|| {
            FeatureRuntimeError::InvalidContract(format!("{action_id}.{guard_id}"))
        })?;
        let query_id = guard.get("query").and_then(Value::as_str).ok_or_else(|| {
            FeatureRuntimeError::InvalidContract(format!("{action_id}.{guard_id}"))
        })?;
        let binding = context
            .bindings
            .get(query_id)
            .ok_or_else(|| FeatureRuntimeError::MissingRecord(query_id.to_owned()))?;
        let rows = guard_binding_rows(query_id, binding)?;
        let add = guard
            .get("add")
            .map(|source| {
                resolve_value(source, context)?
                    .and_then(|value| value.as_i64())
                    .ok_or_else(|| {
                        FeatureRuntimeError::InvalidContract(format!("{action_id}.{guard_id}.add"))
                    })
            })
            .transpose()?
            .unwrap_or(0);
        let actual = match kind {
            "count" => i64::try_from(rows.len())
                .map_err(|_| {
                    FeatureRuntimeError::InvalidContract(format!("{action_id}.{guard_id}"))
                })?
                .checked_add(add)
                .ok_or_else(|| FeatureRuntimeError::Conflict(format!("{action_id}.{guard_id}")))?,
            "sum" => {
                let field = sql_identifier(
                    guard.get("field").and_then(Value::as_str).ok_or_else(|| {
                        FeatureRuntimeError::InvalidContract(format!(
                            "{action_id}.{guard_id}.field"
                        ))
                    })?,
                )?;
                rows.iter()
                    .try_fold(add, |total, row| {
                        row.get(&field)
                            .and_then(Value::as_i64)
                            .and_then(|value| total.checked_add(value))
                    })
                    .ok_or_else(|| {
                        FeatureRuntimeError::Conflict(format!("{action_id}.{guard_id}"))
                    })?
            }
            "exists" => i64::from(!rows.is_empty()),
            _ => {
                return Err(FeatureRuntimeError::InvalidContract(format!(
                    "{action_id}.{guard_id}"
                )));
            }
        };
        let satisfied = if kind == "exists"
            && guard.get("minimum").is_none()
            && guard.get("maximum").is_none()
            && guard.get("equals").is_none()
        {
            actual == 1
        } else {
            guard_bounds_satisfied(actual, guard)
        };
        if !satisfied {
            let message = guard
                .get("message")
                .and_then(Value::as_str)
                .unwrap_or("The action was rejected by a declared business-rule guard.");
            return Err(FeatureRuntimeError::ValidationReport(validation_report(
                action_id,
                vec![guard_id.to_owned()],
                None,
                Some((guard_id.to_owned(), guard_id.to_owned(), message.to_owned())),
            )));
        }
    }
    Ok(())
}

/// Converts one query result into the binding value used by later dependent queries.
fn query_binding_value(
    query_id: &str,
    result_kind: &str,
    rows: &[Map<String, Value>],
) -> Result<Value, FeatureRuntimeError> {
    match result_kind {
        "many" => Ok(Value::Array(
            rows.iter().cloned().map(Value::Object).collect(),
        )),
        "optional" => Ok(rows
            .first()
            .cloned()
            .map(Value::Object)
            .unwrap_or(Value::Null)),
        _ => rows
            .first()
            .cloned()
            .map(Value::Object)
            .ok_or_else(|| FeatureRuntimeError::MissingRecord(query_id.to_owned())),
    }
}

#[cfg(not(target_os = "wasi"))]
fn timestamp_before_seconds_utc(seconds_before_now: u64) -> String {
    let seconds = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs()
        .saturating_sub(seconds_before_now);
    super::chrono_like_timestamp(seconds)
}

/// Flattens map or ordered-step transaction syntax into one deterministic operation list.
/// Performs transaction operations.
fn transaction_operations(
    transaction: &Value,
) -> Result<Vec<(String, Value)>, FeatureRuntimeError> {
    let object = transaction
        .as_object()
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("transaction".to_owned()))?;
    if let Some(steps) = object.get("steps").and_then(Value::as_array) {
        if steps.is_empty() || steps.len() > 64 {
            return Err(FeatureRuntimeError::InvalidContract(
                "transaction.steps".to_owned(),
            ));
        }
        return steps
            .iter()
            .map(|step| {
                let operation = step.as_object().ok_or_else(|| {
                    FeatureRuntimeError::InvalidContract("transaction.step".to_owned())
                })?;
                if operation.len() != 1 {
                    return Err(FeatureRuntimeError::InvalidContract(
                        "transaction.step".to_owned(),
                    ));
                }
                let (kind, value) = operation.iter().next().expect("one operation");
                Ok((kind.clone(), value.clone()))
            })
            .collect();
    }
    Ok(object
        .iter()
        .filter(|(kind, _)| kind.as_str() != "idempotency")
        .map(|(kind, value)| (kind.clone(), value.clone()))
        .collect::<Vec<_>>())
}

/// Executes a declared transaction through the configured operation interface.
fn execute_feature_transaction(
    app: &AppRuntime,
    feature: &Value,
    transaction: &Value,
    guard_contract: Option<&Value>,
    context: FeatureRequestContext,
    action_id: &str,
) -> Result<(), FeatureRuntimeError> {
    logical::execute_logical_transaction(
        app,
        feature,
        transaction,
        guard_contract,
        context,
        action_id,
    )
}

/// Records one declared protected-asset authorization before streaming starts.
#[cfg(not(target_os = "wasi"))]
/// Records private asset authorization.
fn record_private_asset_authorization(
    app: &AppRuntime,
    declaration: &Value,
    actor_id: i64,
    protected_id: i64,
) -> Result<(), FeatureRuntimeError> {
    let Some(transaction) = declaration
        .get("on_authorized")
        .filter(|value| !value.is_null())
    else {
        return Ok(());
    };
    if actor_id <= 0 || protected_id <= 0 {
        return Err(FeatureRuntimeError::InvalidInput(
            "protected authorization".to_owned(),
        ));
    }
    let feature_id = declaration
        .get("feature_id")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("protected feature".to_owned()))?;
    let feature = load_feature(app, feature_id)?;
    let mut protected = Map::new();
    protected.insert("id".to_owned(), Value::from(protected_id));
    execute_feature_transaction(
        app,
        &feature,
        transaction,
        None,
        FeatureRequestContext {
            actor_id,
            protected,
            ..FeatureRequestContext::default()
        },
        "protected_asset_authorization",
    )
}

/// Executes declared queries through the configured operation interface.
fn execute_feature_queries(
    app: &AppRuntime,
    feature: &Value,
    query_ids: &[String],
    context: &FeatureRequestContext,
) -> Result<BTreeMap<String, Vec<Map<String, Value>>>, FeatureRuntimeError> {
    logical::execute_logical_queries(app, feature, query_ids, context)
}

/// Loads one compiled feature contract from the app artifact tree.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::load_feature`].
/// - `feature_id`: Input consumed by [`crate::runtime::feature_runtime::load_feature`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::load_feature`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::load_feature`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::feature_runtime::load_feature`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::load_feature(todo!(), "feature");
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn load_feature(app: &AppRuntime, feature_id: &str) -> Result<Value, FeatureRuntimeError> {
    let root = artifact_root(app)?;
    let document = load_json(&root.join("data/contracts/features.json"))?;
    document
        .get("features")
        .and_then(Value::as_array)
        .and_then(|features| {
            features.iter().find(|feature| {
                feature.get("feature_id").and_then(Value::as_str) == Some(feature_id)
            })
        })
        .cloned()
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(feature_id.to_owned()))
}

/// Loads one compiled feature action contract by its stable identifier.
fn load_feature_action(app: &AppRuntime, action_id: &str) -> Result<Value, FeatureRuntimeError> {
    let root = artifact_root(app)?;
    let document = load_json(&root.join("data/contracts/actions.json"))?;
    document
        .get("actions")
        .and_then(Value::as_array)
        .and_then(|actions| {
            actions.iter().find(|action| {
                action.get("action_id").and_then(Value::as_str) == Some(action_id)
                    && action.get("feature_id").and_then(Value::as_str).is_some()
            })
        })
        .cloned()
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))
}

/// Builds the fallback redirect target for a feature action.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::action_fallback_redirect`].
/// - `action_id`: Input consumed by [`crate::runtime::feature_runtime::action_fallback_redirect`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::action_fallback_redirect`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::action_fallback_redirect`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::action_fallback_redirect(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn action_fallback_redirect(
    app: &AppRuntime,
    action_id: &str,
) -> Result<String, FeatureRuntimeError> {
    load_feature_action(app, action_id)?
        .get("response_contract")
        .and_then(|value| value.get("fallback"))
        .and_then(|value| value.get("redirect"))
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))
}

/// Executes one declared feature action.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::execute_feature_action`].
/// - `route`: Input consumed by [`crate::runtime::feature_runtime::execute_feature_action`].
/// - `request`: Input consumed by [`crate::runtime::feature_runtime::execute_feature_action`].
/// - `actor_id`: Input consumed by [`crate::runtime::feature_runtime::execute_feature_action`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::execute_feature_action`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::execute_feature_action`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::feature_runtime::execute_feature_action`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::execute_feature_action(todo!(), todo!(), todo!(), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn execute_feature_action(
    app: &AppRuntime,
    route: &Value,
    request: &super::http::HttpRequest,
    actor_id: i64,
) -> Result<FeatureActionOutcome, FeatureRuntimeError> {
    let feature_id = route
        .get("feature_id")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("route.feature_id".to_owned()))?;
    let action_id = route
        .get("action_id")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("route.action_id".to_owned()))?;
    let feature = load_feature(app, feature_id)?;
    let action = load_feature_action(app, action_id)?;
    let mut media = media_input::prepare(
        app,
        request,
        action
            .get("input_contract")
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?,
    )?;
    let input = validated_action_input(
        &media.request,
        action
            .get("input_contract")
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?,
        action.get("hook_contract"),
        action_id,
    )?;
    let request_path = request.target.split('?').next().unwrap_or("/");
    let context = FeatureRequestContext {
        request_target: request.target.clone(),
        actor_id,
        input,
        path_params: path_parameters(
            route.get("path").and_then(Value::as_str).unwrap_or("/"),
            request_path,
        )?,
        query_params: query_parameters(&request.target)?,
        ..FeatureRequestContext::default()
    };
    let transaction = selected_contract_variant(
        action
            .get("transaction_contract")
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?,
        &context,
    )?;
    let response = selected_contract_variant(
        action
            .get("response_contract")
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?,
        &context,
    )?;
    let redirect_only_path =
        if response.get("response_kind").and_then(Value::as_str) == Some("redirect") {
            let redirect = response
                .get("fallback")
                .and_then(|value| value.get("redirect"))
                .and_then(Value::as_str)
                .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?;
            Some(action_redirect_path(redirect, &context.path_params)?)
        } else {
            None
        };
    execute_feature_transaction(
        app,
        &feature,
        transaction,
        action.get("guard_contract"),
        context.clone(),
        action_id,
    )?;
    media.commit();
    if let Some(redirect) = redirect_only_path {
        return Ok(FeatureActionOutcome {
            status: 200,
            fragment_html: String::new(),
            redirect,
            redirect_only: true,
        });
    }
    let query_ids = response
        .get("queries")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .map(|value| {
            value
                .as_str()
                .map(ToOwned::to_owned)
                .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))
        })
        .collect::<Result<Vec<_>, _>>()?;
    let params = render_query_params(app, &feature, &query_ids, &context)?;
    let template = response
        .get("template")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?;
    let root = artifact_root(app)?;
    let template_path = super::features::safe_feature_template_path(&root, template)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(template.to_owned()))?;
    let fragment_html =
        super::json_commands::template_render_file(&template_path, &Value::Object(params))
            .ok_or_else(|| FeatureRuntimeError::RenderFailed(template.to_owned()))?;
    let redirect = response
        .get("fallback")
        .and_then(|value| value.get("redirect"))
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?
        .to_owned();
    Ok(FeatureActionOutcome {
        status: response
            .get("status")
            .and_then(Value::as_u64)
            .and_then(|status| u16::try_from(status).ok())
            .filter(|status| (200..=599).contains(status))
            .unwrap_or(200),
        fragment_html,
        redirect,
        redirect_only: false,
    })
}

/// Appends a query and its declared query dependencies in executable order.
fn append_query_with_dependencies(
    queries: &Map<String, Value>,
    query_id: &str,
    output: &mut Vec<String>,
    visiting: &mut BTreeSet<String>,
) -> Result<(), FeatureRuntimeError> {
    if output.iter().any(|existing| existing == query_id) {
        return Ok(());
    }
    if !visiting.insert(query_id.to_owned()) {
        return Err(FeatureRuntimeError::InvalidContract(format!(
            "query dependency cycle: {query_id}"
        )));
    }
    let query = queries
        .get(query_id)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(query_id.to_owned()))?;
    let mut dependencies = BTreeSet::new();
    referenced_queries(query, &mut dependencies);
    for dependency in dependencies {
        if dependency != query_id {
            append_query_with_dependencies(queries, &dependency, output, visiting)?;
        }
    }
    visiting.remove(query_id);
    if !output.iter().any(|existing| existing == query_id) {
        output.push(query_id.to_owned());
    }
    Ok(())
}

/// Executes one declared feature action and returns a generated API JSON item response.
fn feature_json_payload_for_query(
    app: &AppRuntime,
    feature: &Value,
    payload_query: &str,
    context: &FeatureRequestContext,
) -> Result<Value, FeatureRuntimeError> {
    let queries = feature
        .get("queries")
        .and_then(Value::as_object)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("feature.queries".to_owned()))?;
    let mut query_ids = Vec::new();
    append_query_with_dependencies(queries, payload_query, &mut query_ids, &mut BTreeSet::new())?;
    let query_results = execute_feature_queries(app, feature, &query_ids, context)?;
    Ok(query_results
        .get(payload_query)
        .and_then(|rows| rows.first())
        .cloned()
        .map(Value::Object)
        .unwrap_or(Value::Null))
}

pub fn execute_feature_json_action(
    app: &AppRuntime,
    route_path: &str,
    request: &super::http::HttpRequest,
    actor_id: i64,
    action_id: &str,
) -> Result<(u16, Value), FeatureRuntimeError> {
    let action = load_feature_action(app, action_id)?;
    let feature_id = action
        .get("feature_id")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(format!("{action_id}.feature_id")))?;
    let feature = load_feature(app, feature_id)?;
    let mut media = media_input::prepare(
        app,
        request,
        action
            .get("input_contract")
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?,
    )?;
    let input = validated_action_input(
        &media.request,
        action
            .get("input_contract")
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?,
        action.get("hook_contract"),
        action_id,
    )?;
    let request_path = request.target.split('?').next().unwrap_or("/");
    let context = FeatureRequestContext {
        request_target: request.target.clone(),
        actor_id,
        input,
        path_params: path_parameters(route_path, request_path)?,
        query_params: query_parameters(&request.target)?,
        ..FeatureRequestContext::default()
    };
    let transaction = selected_contract_variant(
        action
            .get("transaction_contract")
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?,
        &context,
    )?;
    let response = selected_contract_variant(
        action
            .get("response_contract")
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(action_id.to_owned()))?,
        &context,
    )?;
    let payload_before = response
        .get("payload_query_before")
        .and_then(Value::as_str)
        .map(|query| feature_json_payload_for_query(app, &feature, query, &context))
        .transpose()?;
    execute_feature_transaction(
        app,
        &feature,
        transaction,
        action.get("guard_contract"),
        context.clone(),
        action_id,
    )?;
    media.commit();
    let status = response
        .get("status")
        .and_then(Value::as_u64)
        .and_then(|status| u16::try_from(status).ok())
        .filter(|status| (200..=599).contains(status))
        .unwrap_or(200);
    let surface = response
        .get("surface")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(format!("{action_id}.surface")))?;
    let payload = if let Some(payload) = payload_before {
        payload
    } else {
        let payload_query = response
            .get("payload_query")
            .and_then(Value::as_str)
            .ok_or_else(|| {
                FeatureRuntimeError::InvalidContract(format!("{action_id}.payload_query"))
            })?;
        feature_json_payload_for_query(app, &feature, payload_query, &context)?
    };
    Ok((
        status,
        serde_json::json!({
            "schema": "pharos.generated.api.item.v1",
            "surface": surface,
            "payload": payload
        }),
    ))
}

/// Builds the query-parameter map available to a feature request.
///
/// # Parameters
///
/// - `target`: Input consumed by [`crate::runtime::feature_runtime::query_parameters`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::query_parameters`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::query_parameters`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::feature_runtime::query_parameters`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::query_parameters("/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn query_parameters(target: &str) -> Result<Map<String, Value>, FeatureRuntimeError> {
    let query = target.split_once('?').map(|(_, query)| query).unwrap_or("");
    if query.len() > 8 * 1024 {
        return Err(FeatureRuntimeError::InvalidInput("query".to_owned()));
    }
    let mut values = Map::new();
    for pair in query.split('&').filter(|pair| !pair.is_empty()) {
        let (key, value) = pair.split_once('=').unwrap_or((pair, ""));
        let key = super::json_commands::url_decode(key)
            .ok_or_else(|| FeatureRuntimeError::InvalidInput("query".to_owned()))?;
        let value = super::json_commands::url_decode(value)
            .ok_or_else(|| FeatureRuntimeError::InvalidInput(key.clone()))?;
        sql_identifier(&key)?;
        if values.len() >= MAX_QUERY_FILTERS
            || values.insert(key.clone(), Value::String(value)).is_some()
        {
            return Err(FeatureRuntimeError::InvalidInput(key));
        }
    }
    Ok(values)
}

/// Builds the path-parameter map available to a feature request.
///
/// # Parameters
///
/// - `pattern`: Input consumed by [`crate::runtime::feature_runtime::path_parameters`].
/// - `path`: Input consumed by [`crate::runtime::feature_runtime::path_parameters`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::path_parameters`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::path_parameters`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::feature_runtime::path_parameters`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::path_parameters(todo!(), std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
fn path_parameter_value(parameter: &str, decoded: &str) -> Value {
    if (parameter == "id" || parameter.ends_with("_id"))
        && decoded.len() <= 18
        && decoded.chars().all(|character| character.is_ascii_digit())
        && let Ok(value) = decoded.parse::<i64>()
    {
        return Value::from(value);
    }
    Value::String(decoded.to_owned())
}

pub fn path_parameters(
    pattern: &str,
    path: &str,
) -> Result<Map<String, Value>, FeatureRuntimeError> {
    let pattern_parts = pattern.trim_matches('/').split('/').collect::<Vec<_>>();
    let path_parts = path.trim_matches('/').split('/').collect::<Vec<_>>();
    if pattern_parts.len() != path_parts.len() {
        return Err(FeatureRuntimeError::InvalidInput("path".to_owned()));
    }
    let mut values = Map::new();
    for (declared, actual) in pattern_parts.into_iter().zip(path_parts) {
        let parameter = declared.strip_prefix(':').or_else(|| {
            declared
                .strip_prefix('{')
                .and_then(|value| value.strip_suffix('}'))
        });
        if let Some(parameter) = parameter {
            sql_identifier(parameter)?;
            let decoded = super::json_commands::url_decode(actual)
                .ok_or_else(|| FeatureRuntimeError::InvalidInput(parameter.to_owned()))?;
            if decoded.is_empty() || decoded.len() > 256 || decoded.contains('/') {
                return Err(FeatureRuntimeError::InvalidInput(parameter.to_owned()));
            }
            values.insert(
                parameter.to_owned(),
                path_parameter_value(parameter, &decoded),
            );
        } else if declared != actual {
            return Err(FeatureRuntimeError::InvalidInput("path".to_owned()));
        }
    }
    Ok(values)
}

fn missing_template_keys(template_path: &Path, params: &Map<String, Value>) -> Vec<String> {
    let Ok(template_text) = fs::read_to_string(template_path) else {
        return vec!["<template unreadable>".to_owned()];
    };
    let mut missing = Vec::new();
    let mut cursor = 0usize;
    while let Some(offset) = template_text[cursor..].find('{') {
        let open = cursor + offset;
        let Some(close_offset) = template_text[open + 1..].find('}') else {
            missing.push("<unclosed placeholder>".to_owned());
            break;
        };
        let close = open + 1 + close_offset;
        let raw = &template_text[open + 1..close];
        let key = raw.split_once(':').map_or(raw, |(_, key)| key);
        if !params.contains_key(key) {
            missing.push(key.to_owned());
        }
        cursor = close + 1;
    }
    missing.sort();
    missing.dedup();
    missing
}

/// Renders selected query rows through app-owned row templates and scalar outputs.
fn query_render_params(
    artifact_root: &Path,
    feature: &Value,
    results: &BTreeMap<String, Vec<Map<String, Value>>>,
    base_params: &Map<String, Value>,
) -> Result<Map<String, Value>, FeatureRuntimeError> {
    // HTML form controls use numeric flags. Keep that presentation conversion
    // separate from typed query bindings and transactional read guards.
    let mut rendered_results = results.clone();
    for rows in rendered_results.values_mut() {
        for row in rows {
            for value in row.values_mut() {
                if let Some(flag) = value.as_bool() {
                    *value = Value::from(i64::from(flag));
                }
            }
        }
    }
    let results = &rendered_results;
    let queries = feature
        .get("queries")
        .and_then(Value::as_object)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("feature.queries".to_owned()))?;
    let mut params = base_params.clone();
    for (query_id, rows) in results {
        let query = queries
            .get(query_id)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(query_id.clone()))?;
        params.insert(format!("{query_id}_count"), Value::from(rows.len()));
        if let Some(aggregates) = query.get("aggregates").and_then(Value::as_object) {
            if aggregates.len() > 16 {
                return Err(FeatureRuntimeError::InvalidContract(format!(
                    "{query_id}.aggregates"
                )));
            }
            for (output, aggregate) in aggregates {
                sql_identifier(output)?;
                let operation = aggregate
                    .get("operation")
                    .and_then(Value::as_str)
                    .ok_or_else(|| {
                        FeatureRuntimeError::InvalidContract(format!(
                            "{query_id}.aggregates.{output}"
                        ))
                    })?;
                let value = match operation {
                    "count" => i64::try_from(rows.len()).map_err(|_| {
                        FeatureRuntimeError::InvalidContract(format!(
                            "{query_id}.aggregates.{output}"
                        ))
                    })?,
                    "sum" => {
                        let field = sql_identifier(
                            aggregate
                                .get("field")
                                .and_then(Value::as_str)
                                .unwrap_or_default(),
                        )?;
                        rows.iter()
                            .try_fold(0i64, |total, row| {
                                row.get(&field)
                                    .and_then(Value::as_i64)
                                    .and_then(|value| total.checked_add(value))
                            })
                            .ok_or_else(|| {
                                FeatureRuntimeError::Conflict(format!(
                                    "{query_id}.aggregates.{output}"
                                ))
                            })?
                    }
                    _ => {
                        return Err(FeatureRuntimeError::InvalidContract(format!(
                            "{query_id}.aggregates.{output}"
                        )));
                    }
                };
                params.insert(output.clone(), Value::from(value));
            }
        }
        if let Some(outputs) = query.get("outputs").and_then(Value::as_object) {
            let first = rows.first();
            for (output, field) in outputs {
                sql_identifier(output)?;
                let field = field.as_str().ok_or_else(|| {
                    FeatureRuntimeError::InvalidContract(format!("{query_id}.outputs"))
                })?;
                params.insert(
                    output.clone(),
                    first
                        .and_then(|row| row.get(field))
                        .cloned()
                        .unwrap_or(Value::Null),
                );
            }
        }
    }
    // Resolve every scalar output before rendering dependent rows; map ordering cannot hide cross-query bindings.
    let scalar_params = params.clone();
    for (query_id, rows) in results {
        let query = queries
            .get(query_id)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(query_id.clone()))?;
        let Some(render) = query.get("render") else {
            continue;
        };
        let template = render
            .get("template")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(format!("{query_id}.render")))?;
        let output = sql_identifier(render.get("output").and_then(Value::as_str).ok_or_else(
            || FeatureRuntimeError::InvalidContract(format!("{query_id}.render.output")),
        )?)?;
        let template_path = super::features::safe_feature_template_path(artifact_root, template)
            .ok_or_else(|| FeatureRuntimeError::InvalidContract(template.to_owned()))?;
        let mut html = String::new();
        for row in rows {
            let mut row_params = scalar_params.clone();
            row_params.extend(row.clone());
            html.push_str(
                &super::json_commands::template_render_file(
                    &template_path,
                    &Value::Object(row_params.clone()),
                )
                .ok_or_else(|| {
                    eprintln!(
                        "feature row template render failed: template={} missing_keys={:?}",
                        template,
                        missing_template_keys(&template_path, &row_params)
                    );
                    FeatureRuntimeError::RenderFailed(template.to_owned())
                })?,
            );
        }
        if rows.is_empty()
            && let Some(empty_template) = render.get("empty_template").and_then(Value::as_str)
        {
            let empty_path =
                super::features::safe_feature_template_path(artifact_root, empty_template)
                    .ok_or_else(|| {
                        FeatureRuntimeError::InvalidContract(empty_template.to_owned())
                    })?;
            html = super::json_commands::template_render_file(
                &empty_path,
                &Value::Object(scalar_params.clone()),
            )
            .ok_or_else(|| {
                eprintln!(
                    "feature empty template render failed: template={} missing_keys={:?}",
                    empty_template,
                    missing_template_keys(&empty_path, &scalar_params)
                );
                FeatureRuntimeError::RenderFailed(empty_template.to_owned())
            })?;
        }
        params.insert(output, Value::String(html));
    }
    Ok(params)
}

/// Builds template parameters for a feature query result.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::render_query_params`].
/// - `feature`: Input consumed by [`crate::runtime::feature_runtime::render_query_params`].
/// - `query_ids`: Input consumed by [`crate::runtime::feature_runtime::render_query_params`].
/// - `context`: Input consumed by [`crate::runtime::feature_runtime::render_query_params`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::render_query_params`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::render_query_params`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::render_query_params(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn execute_feature_query_rows_json(
    app: &AppRuntime,
    feature_id: &str,
    query_ids: &[String],
    context: &FeatureRequestContext,
) -> Result<Value, FeatureRuntimeError> {
    if query_ids.len() > MAX_QUERY_FILTERS {
        return Err(FeatureRuntimeError::InvalidContract(
            "query count".to_owned(),
        ));
    }
    let feature = load_feature(app, feature_id)?;
    let mut results = None;
    for attempt in 0..40 {
        match execute_feature_queries(app, &feature, query_ids, context) {
            Ok(query_results) => {
                results = Some(query_results);
                break;
            }
            Err(FeatureRuntimeError::DatabaseUnavailable) if attempt < 39 => {
                std::thread::sleep(std::time::Duration::from_millis(50));
            }
            Err(error) => return Err(error),
        }
    }
    let results = results.ok_or(FeatureRuntimeError::DatabaseUnavailable)?;
    let mut root = Map::new();
    root.insert(
        "schema".to_owned(),
        Value::String("pharos.feature-query-result.v1".to_owned()),
    );
    root.insert(
        "feature_id".to_owned(),
        Value::String(feature_id.to_owned()),
    );
    let mut query_root = Map::new();
    for (query_id, rows) in results {
        query_root.insert(
            query_id,
            Value::Array(rows.into_iter().map(Value::Object).collect()),
        );
    }
    root.insert("queries".to_owned(), Value::Object(query_root));
    Ok(Value::Object(root))
}

pub fn render_query_params(
    app: &AppRuntime,
    feature: &Value,
    query_ids: &[String],
    context: &FeatureRequestContext,
) -> Result<Map<String, Value>, FeatureRuntimeError> {
    if query_ids.len() > MAX_QUERY_FILTERS {
        return Err(FeatureRuntimeError::InvalidContract(
            "query count".to_owned(),
        ));
    }
    let mut results = None;
    for attempt in 0..40 {
        match execute_feature_queries(app, feature, query_ids, context) {
            Ok(query_results) => {
                results = Some(query_results);
                break;
            }
            Err(FeatureRuntimeError::DatabaseUnavailable) if attempt < 39 => {
                std::thread::sleep(std::time::Duration::from_millis(50));
            }
            Err(error) => return Err(error),
        }
    }
    let results = results.ok_or(FeatureRuntimeError::DatabaseUnavailable)?;
    let base_params = manifest_declared_template_params(app)?;
    query_render_params(&artifact_root(app)?, feature, &results, &base_params)
}

/// Renders a feature page body with an attached error state.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body_with_error`].
/// - `route`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body_with_error`].
/// - `target`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body_with_error`].
/// - `actor_id`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body_with_error`].
/// - `csrf_token`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body_with_error`].
/// - `error_message`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body_with_error`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::render_feature_page_body_with_error`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::render_feature_page_body_with_error`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::feature_runtime::render_feature_page_body_with_error`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::render_feature_page_body_with_error(todo!(), todo!(), "/", 1, todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn render_feature_page_body_with_error(
    app: &AppRuntime,
    route: &Value,
    target: &str,
    actor_id: i64,
    csrf_token: &str,
    error_message: Option<&str>,
) -> Result<String, FeatureRuntimeError> {
    render_feature_page_body_with_error_and_params(
        app,
        route,
        target,
        actor_id,
        csrf_token,
        error_message,
        Map::new(),
    )
}

/// Renders a feature page body with additional caller-supplied template params.
pub fn render_feature_page_body_with_error_and_params(
    app: &AppRuntime,
    route: &Value,
    target: &str,
    actor_id: i64,
    csrf_token: &str,
    error_message: Option<&str>,
    extra_params: Map<String, Value>,
) -> Result<String, FeatureRuntimeError> {
    let feature_id = route
        .get("feature_id")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("route.feature_id".to_owned()))?;
    let page_id = route
        .get("page_id")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("route.page_id".to_owned()))?;
    let feature = load_feature(app, feature_id)?;
    let query_ids = route
        .get("queries")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .map(|value| {
            value
                .as_str()
                .map(ToOwned::to_owned)
                .ok_or_else(|| FeatureRuntimeError::InvalidContract("route.queries".to_owned()))
        })
        .collect::<Result<Vec<_>, _>>()?;
    let request_path = target.split('?').next().unwrap_or("/");
    let context = FeatureRequestContext {
        actor_id,
        path_params: path_parameters(
            route.get("path").and_then(Value::as_str).unwrap_or("/"),
            request_path,
        )?,
        request_target: target.to_owned(),
        query_params: query_parameters(target)?,
        ..FeatureRequestContext::default()
    };
    let root = artifact_root(app)?;
    let mut params = render_query_params(app, &feature, &query_ids, &context)?;
    params.insert(
        "pharos_idempotency_key".to_owned(),
        Value::String(
            super::dynamic::random_secret_hex(24)
                .map_err(|_| FeatureRuntimeError::RenderFailed(page_id.to_owned()))?,
        ),
    );
    if page_id == "login" {
        let next_path = context
            .query_params
            .get("next")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let auth_params =
            super::json_commands::template_login_page_json(&root, error_message, Some(next_path))
                .and_then(|json| serde_json::from_str::<Value>(&json).ok())
                .and_then(|value| value.as_object().cloned())
                .ok_or_else(|| FeatureRuntimeError::RenderFailed(page_id.to_owned()))?;
        for (key, value) in auth_params {
            params.insert(key, value);
        }
    }
    if let Some(state_root) = payment_provider_render_state_root(app, request_path)? {
        for (key, value) in super::payment_provider::payment_provider_render_params(
            &state_root,
            &root,
            request_path,
        ) {
            params.insert(key, value);
        }
    }
    for (key, value) in extra_params {
        params.insert(key, value);
    }
    let page_relative = super::json_commands::declared_page_relative_path(&root, page_id)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(page_id.to_owned()))?;
    let page_spec = load_json(&root.join(page_relative))?;
    let template = page_spec
        .get("template_file")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(page_id.to_owned()))?;
    let template_path = super::features::safe_feature_template_path(&root, template)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(template.to_owned()))?;
    let body =
        super::json_commands::template_render_file(&template_path, &Value::Object(params.clone()))
            .ok_or_else(|| {
                eprintln!(
                    "feature page template render failed: page={} template={} missing_keys={:?}",
                    page_id,
                    template,
                    missing_template_keys(&template_path, &params)
                );
                FeatureRuntimeError::RenderFailed(template.to_owned())
            })?;
    let body = super::json_commands::template_apply_base_path(&body, app.base_path.as_deref())
        .ok_or_else(|| FeatureRuntimeError::RenderFailed(page_id.to_owned()))?;
    Ok(super::dynamic::csrf_inject_hidden_inputs(
        &root, &body, csrf_token,
    ))
}

/// Renders a feature page body.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body`].
/// - `route`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body`].
/// - `target`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body`].
/// - `actor_id`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body`].
/// - `csrf_token`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_body`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::render_feature_page_body`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::render_feature_page_body`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::render_feature_page_body(todo!(), todo!(), "/", 1, todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn render_feature_page_body(
    app: &AppRuntime,
    route: &Value,
    target: &str,
    actor_id: i64,
    csrf_token: &str,
) -> Result<String, FeatureRuntimeError> {
    render_feature_page_body_with_error(app, route, target, actor_id, csrf_token, None)
}

fn role_fragment_key(role: &str) -> Option<String> {
    if role.is_empty()
        || role.len() > 64
        || !role
            .chars()
            .all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '_')
    {
        return None;
    }
    Some(format!("{role}_nav_html"))
}

fn role_nav_fragment_html(root: &Path, role: &str) -> String {
    let Some(key) = role_fragment_key(role) else {
        return String::new();
    };
    let Some(role_stem) = key.strip_suffix("_html") else {
        return String::new();
    };
    let fragment_path = root
        .join("templates/layout/fragments")
        .join(format!("{role_stem}.html"));
    if !fragment_path.is_file() {
        return String::new();
    }
    super::json_commands::template_render_file(&fragment_path, &serde_json::json!({}))
        .unwrap_or_default()
}

fn layout_role_nav_params(layout_path: &Path) -> serde_json::Map<String, Value> {
    let mut params = serde_json::Map::new();
    let Ok(layout) = fs::read_to_string(layout_path) else {
        return params;
    };
    for segment in layout.split("{html:").skip(1) {
        let Some((key, _)) = segment.split_once('}') else {
            continue;
        };
        if key.ends_with("_nav_html")
            && key
                .chars()
                .all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '_')
        {
            params.insert(key.to_owned(), Value::String(String::new()));
        }
    }
    params
}

fn insert_actor_role_nav_params(
    app: &AppRuntime,
    root: &Path,
    actor_id: i64,
    params: &mut serde_json::Map<String, Value>,
) -> Result<(), FeatureRuntimeError> {
    if actor_id <= 0 {
        return Ok(());
    }
    if params.contains_key("authenticated_user_nav_html") {
        params.insert(
            "authenticated_user_nav_html".to_owned(),
            Value::String(role_nav_fragment_html(root, "authenticated_user")),
        );
    }
    for role in actor_roles(app, actor_id).map_err(logical::map_database_error)? {
        if let Some(key) = role_fragment_key(&role)
            && params.contains_key(&key)
        {
            params.insert(key, Value::String(role_nav_fragment_html(root, &role)));
        }
    }
    Ok(())
}

/// Renders a full feature page with an attached error state.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html_with_error`].
/// - `route`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html_with_error`].
/// - `target`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html_with_error`].
/// - `actor_id`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html_with_error`].
/// - `has_user`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html_with_error`].
/// - `csrf_token`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html_with_error`].
/// - `error_message`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html_with_error`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::render_feature_page_html_with_error`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::render_feature_page_html_with_error`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::render_feature_page_html_with_error(todo!(), todo!(), "/", 1, todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn render_feature_page_html_with_error(
    app: &AppRuntime,
    route: &Value,
    target: &str,
    actor_id: i64,
    has_user: bool,
    csrf_token: &str,
    error_message: Option<&str>,
) -> Result<String, FeatureRuntimeError> {
    let feature_id = route
        .get("feature_id")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("route.feature_id".to_owned()))?;
    let page_id = route
        .get("page_id")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract("route.page_id".to_owned()))?;
    let body = render_feature_page_body_with_error(
        app,
        route,
        target,
        actor_id,
        csrf_token,
        error_message,
    )?;
    let root = artifact_root(app)?;
    let page_relative = super::json_commands::declared_page_relative_path(&root, page_id)
        .ok_or_else(|| FeatureRuntimeError::InvalidContract(page_id.to_owned()))?;
    let page_spec = load_json(&root.join(page_relative))?;
    let title = page_spec
        .get("title")
        .and_then(Value::as_str)
        .unwrap_or(page_id);
    let layout_id = route
        .get("layout_id")
        .and_then(Value::as_str)
        .or_else(|| page_spec.get("layout_id").and_then(Value::as_str));
    if layout_id == Some("architect_shell") {
        let html = super::json_commands::template_layout_page_html(
            &root,
            app.base_path.as_deref(),
            layout_id,
            Some("en"),
            title,
            &body,
            Some(target),
            has_user,
            if super::actor_has_route_policy(app, actor_id, "manage_llm_vendors")
                .map_err(logical::map_database_error)?
            {
                1
            } else {
                0
            },
        )
        .ok_or_else(|| FeatureRuntimeError::RenderFailed(page_id.to_owned()))?;
        return Ok(super::dynamic::csrf_inject_hidden_inputs(
            &root, &html, csrf_token,
        ));
    }
    let _ = (feature_id, layout_id, target);
    let layout_path = root.join("templates/layout/base.html");
    let mut layout_params = serde_json::Map::from_iter([
        ("current_lang".to_owned(), Value::String("en".to_owned())),
        (
            "title".to_owned(),
            Value::String(super::json_commands::layout_browser_title(&root, title)),
        ),
        ("body".to_owned(), Value::String(body)),
        ("has_user".to_owned(), Value::Bool(has_user)),
    ]);
    for (key, value) in layout_role_nav_params(&layout_path) {
        layout_params.insert(key, value);
    }
    insert_actor_role_nav_params(app, &root, actor_id, &mut layout_params)?;
    let rendered =
        super::json_commands::template_render_file(&layout_path, &Value::Object(layout_params))
            .ok_or_else(|| FeatureRuntimeError::RenderFailed(page_id.to_owned()))?;
    let html = super::json_commands::template_apply_base_path(&rendered, app.base_path.as_deref())
        .ok_or_else(|| FeatureRuntimeError::RenderFailed(page_id.to_owned()))?;
    Ok(super::dynamic::csrf_inject_hidden_inputs(
        &root, &html, csrf_token,
    ))
}

/// Renders a full feature page.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html`].
/// - `route`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html`].
/// - `target`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html`].
/// - `actor_id`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html`].
/// - `has_user`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html`].
/// - `csrf_token`: Input consumed by [`crate::runtime::feature_runtime::render_feature_page_html`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::feature_runtime::render_feature_page_html`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::feature_runtime::render_feature_page_html`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::feature_runtime::render_feature_page_html(todo!(), todo!(), "/", 1, todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::feature_runtime`] for adjacent helpers that share the same runtime surface.
pub fn render_feature_page_html(
    app: &AppRuntime,
    route: &Value,
    target: &str,
    actor_id: i64,
    has_user: bool,
    csrf_token: &str,
) -> Result<String, FeatureRuntimeError> {
    render_feature_page_html_with_error(app, route, target, actor_id, has_user, csrf_token, None)
}

#[cfg(test)]
mod tests {
    /// Projects only declared relation fields and bounds typed IN predicates without broadening empty selections.
    #[test]
    fn relation_projection_and_membership_are_bounded_and_typed() {
        use serde_json::json;
        let mut context = super::FeatureRequestContext::default();
        context.bindings.insert(
            "links".into(),
            json!([{"id":1,"private":"not selected"},{"id":2,"private":"not selected"}]),
        );
        let before =
            crate::runtime::runtime_timestamp_seconds(&crate::runtime::current_timestamp_utc())
                .unwrap()
                .saturating_sub(30 * 86400);
        let cutoff =
            super::resolve_value(&json!({"server_time_offset_seconds":-2592000}), &context)
                .unwrap()
                .unwrap();
        let after =
            crate::runtime::runtime_timestamp_seconds(&crate::runtime::current_timestamp_utc())
                .unwrap()
                .saturating_sub(30 * 86400);
        let actual = crate::runtime::runtime_timestamp_seconds(cutoff.as_str().unwrap()).unwrap();
        assert!((before..=after).contains(&actual));
        for invalid in [
            json!({"server_time_offset_seconds":"-2592000"}),
            json!({"server_time_offset_seconds":i64::MIN}),
            json!({"server_time_offset_seconds":0,"extra":true}),
        ] {
            assert!(super::resolve_value(&invalid, &context).is_err());
        }
        let expression = json!({"pluck":{"source":"query.links","field":"id"}});
        assert_eq!(
            super::resolve_value(&expression, &context).unwrap(),
            Some(json!([1, 2]))
        );
        let schema=serde_json::from_value(json!({"app_id":"relation_test","entities":[{"name":"record","identity":{"auto_integer":"id"},"fields":[{"name":"id","kind":"integer","nullable":false,"constraints":[]}],"unique":[],"indexes":[],"conditional_indexes":[]}]})).unwrap();
        let filters = json!({"id":{"operator":"in","value":expression}});
        assert!(
            super::logical::predicate_for_filters(filters.as_object(), &context, &schema, "record")
                .unwrap()
                .is_some()
        );
        context.bindings.insert("links".into(), json!([]));
        assert_eq!(
            super::resolve_value(&expression, &context).unwrap(),
            Some(json!([]))
        );
        assert!(
            super::logical::predicate_for_filters(filters.as_object(), &context, &schema, "record")
                .unwrap()
                .is_some()
        );
        context
            .bindings
            .insert("links".into(), json!([{"id":"1 OR 1=1"}]));
        assert!(
            super::logical::predicate_for_filters(filters.as_object(), &context, &schema, "record")
                .is_err()
        );
        context
            .bindings
            .insert("links".into(), json!([{"unrelated":1}]));
        assert!(super::resolve_value(&expression, &context).is_err());
        context
            .bindings
            .insert("links".into(), json!(vec![json!({"id":1}); 65]));
        assert!(super::resolve_value(&expression, &context).is_err());
        for offset in ["UTC", "+14:00", "-05:30"] {
            assert!(super::declared_input_format_valid(Some("utc_offset"), offset).unwrap());
        }
        let choice =
            json!({"lookup":{"key":"query_param.type","values":{"DJ":["DJ","dj"],"all":null}}});
        context.query_params.insert("type".into(), json!("DJ"));
        assert_eq!(
            super::resolve_value(&choice, &context).unwrap(),
            Some(json!(["DJ", "dj"]))
        );
        context.query_params.insert("type".into(), json!("all"));
        assert_eq!(super::resolve_value(&choice, &context).unwrap(), None);
        context
            .query_params
            .insert("type".into(), json!("unrecognized"));
        assert!(super::resolve_value(&choice, &context).is_err());
        for offset in ["+24:00", "+01:99", "Europe/Unknown", "+é:10"] {
            assert!(!super::declared_input_format_valid(Some("utc_offset"), offset).unwrap());
        }
    }
    /// Retains source date precision and validates real calendar days without admitting ambiguous local clock times.
    #[test]
    fn date_or_timestamp_retains_day_precision() {
        use serde_json::json;
        let contract = json!({"inline_fields":{"start":{"type":"string","format":"date_or_timestamp","required":true},"end":{"type":"string","format":"date_or_timestamp","not_before":"start"}}});
        let mut request = crate::runtime::http::HttpRequest {
            method: "POST".into(),
            content_type: Some("application/json".into()),
            ..Default::default()
        };
        for value in ["2026-10-17", "2026-10-17T20:00:00Z"] {
            request.body = serde_json::to_vec(&json!({"start":value,"end":""})).unwrap();
            let parsed = super::validated_action_input(&request, &contract, None, "save").unwrap();
            assert!(
                parsed["start"]
                    .as_str()
                    .unwrap()
                    .starts_with(&value[..value.len().min(19)])
            );
        }
        for value in ["2026-02-30", "2026-10-17T20:00:00", "not a date"] {
            assert!(!super::declared_input_format_valid(Some("date_or_timestamp"), value).unwrap());
        }
        request.body =
            serde_json::to_vec(&json!({"start":"2026-10-17","end":"2026-10-16"})).unwrap();
        assert!(super::validated_action_input(&request, &contract, None, "save").is_err());
    }

    /// Normalizes explicit offsets and rejects ambiguous or reversed event times before persistence.
    #[test]
    fn timestamp_inputs_require_zones_and_ordered_end_times() {
        for invalid in ["2027-01-01 20:00:00", "1800000000", "2027-02-30T20:00:00Z"] {
            assert!(!super::declared_input_format_valid(Some("timestamp"), invalid).unwrap());
        }
        let mut request = crate::runtime::http::HttpRequest {
            method: "POST".into(),
            target: "/save".into(),
            content_type: Some("application/json".into()),
            ..Default::default()
        };
        let contract = serde_json::json!({"inline_fields":{"start":{"type":"string","format":"timestamp","required":true},"end":{"type":"string","format":"timestamp","not_before":"start"}}});
        request.body = serde_json::to_vec(
            &serde_json::json!({"start":"2027-01-01T20:00:00+01:00","end":"2027-01-01T20:00:00Z"}),
        )
        .unwrap();
        let parsed = super::validated_action_input(&request, &contract, None, "save").unwrap();
        assert!(
            parsed["start"]
                .as_str()
                .unwrap()
                .starts_with("2027-01-01T19:00:00")
        );
        request.body = serde_json::to_vec(
            &serde_json::json!({"start":"2027-01-01T20:00:00Z","end":"2027-01-01T19:00:00Z"}),
        )
        .unwrap();
        assert!(super::validated_action_input(&request, &contract, None, "save").is_err());
        request.body =
            serde_json::to_vec(&serde_json::json!({"start":"2027-01-01T20:00:00","end":""}))
                .unwrap();
        assert!(super::validated_action_input(&request, &contract, None, "save").is_err());
    }
    /// Existing limits remain fixed unless an authored string field explicitly admits a bounded biography.
    #[test]
    fn declared_large_text_admits_biographies_with_fixed_request_and_field_bounds() {
        let mut request = crate::runtime::http::HttpRequest {
            method: "POST".into(),
            target: "/save".into(),
            content_type: Some("application/json".into()),
            ..Default::default()
        };
        request.body =
            serde_json::to_vec(&serde_json::json!({"biography":"a".repeat(9000)})).unwrap();
        let mut contract =
            serde_json::json!({"inline_fields":{"biography":{"type":"string","max_length":32768}}});
        assert!(super::validated_action_input(&request, &contract, None, "save").is_err());
        contract["inline_fields"]["biography"]["large_text"] = serde_json::json!(true);
        assert_eq!(
            super::validated_action_input(&request, &contract, None, "save").unwrap()["biography"]
                .as_str()
                .unwrap()
                .len(),
            9000
        );
        request.body =
            serde_json::to_vec(&serde_json::json!({"biography":"a".repeat(32769)})).unwrap();
        assert!(super::validated_action_input(&request, &contract, None, "save").is_err());
    }
    /// Validates CRM contacts and public sources before any declared mutation executes.
    #[test]
    fn declared_contact_formats_reject_unsafe_links_and_bad_contacts() {
        assert!(super::declared_input_format_valid(Some("email"), "person@example.org").unwrap());
        assert!(!super::declared_input_format_valid(Some("email"), "not-an-email").unwrap());
        assert!(super::declared_input_format_valid(Some("email"), "").unwrap());
        assert!(
            super::declared_input_format_valid(Some("https_url"), "https://events.example/path")
                .unwrap()
        );
        assert!(
            !super::declared_input_format_valid(Some("https_url"), "javascript:alert(1)").unwrap()
        );
        assert!(
            !super::declared_input_format_valid(
                Some("https_url"),
                "https://secret@example.org/path"
            )
            .unwrap()
        );
        assert!(super::declared_input_format_valid(Some("unknown"), "").is_err());
    }

    use serde_json::Value;

    use super::{
        FeatureRequestContext, FeatureRuntimeError, action_redirect_path, execute_feature_action,
        manifest_declared_template_params, path_parameters, query_parameters,
    };

    /// Checks typed table defaults, checked arithmetic and exact monetary values before workflow use.
    #[test]
    fn bounded_site_value_sources_preserve_typed_defaults_and_money() {
        let mut context = FeatureRequestContext {
            request_target: "/".into(),
            actor_id: 1,
            input: Default::default(),
            path_params: Default::default(),
            query_params: Default::default(),
            bindings: Default::default(),
            row: Default::default(),
            generated: Default::default(),
            protected: Default::default(),
        };
        let source = serde_json::json!({"coalesce":["path.table_id",1]});
        assert_eq!(
            super::resolve_value(&source, &context).unwrap(),
            Some(Value::from(1))
        );
        context
            .path_params
            .insert("table_id".into(), Value::from(2));
        assert_eq!(
            super::resolve_value(&source, &context).unwrap(),
            Some(Value::from(2))
        );
        context
            .path_params
            .insert("table_id".into(), Value::from("invalid"));
        assert_eq!(
            super::resolve_value(&source, &context).unwrap(),
            Some(Value::from("invalid"))
        );
        assert_eq!(
            super::resolve_value(&serde_json::json!({"add":[40,-1]}), &context).unwrap(),
            Some(Value::from(39))
        );
        assert!(super::resolve_value(&serde_json::json!({"add":[i64::MAX,1]}), &context).is_err());
        assert!(
            super::resolve_value(&serde_json::json!({"add":["untrusted",1]}), &context).is_err()
        );
        for (currency, expected) in [("USD", "$12.50"), ("JPY", "¥1250")] {
            assert_eq!(
                super::resolve_value(
                    &serde_json::json!({"format_minor":{"amount":1250,"currency":currency}}),
                    &context
                )
                .unwrap(),
                Some(Value::from(expected))
            );
            assert_eq!(
                crate::runtime::json_commands::render_template_text_with_default_kind(
                    "{currency_minor:amount}",
                    &serde_json::json!({"amount":1250,"currency":currency}),
                    "text"
                )
                .as_deref(),
                Some(expected)
            );
        }
        assert!(
            super::resolve_value(
                &serde_json::json!({"format_minor":{"amount":-1,"currency":"USD"}}),
                &context
            )
            .is_err()
        );
        let mut nested = Value::from(1);
        for _ in 0..33 {
            nested = serde_json::json!({"coalesce":[nested]});
        }
        assert!(super::resolve_value(&nested, &context).is_err());
    }

    /// Verifies scalar outputs from later-sorted queries are available in dependent row and empty templates.
    #[test]
    fn feature_rows_receive_cross_query_scalar_outputs() {
        let root = test_root("query-output-alias");
        std::fs::create_dir_all(root.join("templates")).unwrap();
        std::fs::write(
            root.join("templates/alias_row.html"),
            "{current_table_id}:{title}",
        )
        .unwrap();
        std::fs::write(
            root.join("templates/alias_empty.html"),
            "{current_table_id}",
        )
        .unwrap();
        let feature = serde_json::json!({"queries": {
            "a_items":{"render":{"template":"templates/alias_row.html","empty_template":"templates/alias_empty.html","output":"item_rows"}},
            "z_table":{"outputs":{"current_table_id":"id"}}
        }});
        let mut results = std::collections::BTreeMap::from([
            (
                "a_items".into(),
                vec![serde_json::Map::from_iter([(
                    "title".into(),
                    Value::from("Pizza"),
                )])],
            ),
            (
                "z_table".into(),
                vec![serde_json::Map::from_iter([("id".into(), Value::from(2))])],
            ),
        ]);
        let params =
            super::query_render_params(&root, &feature, &results, &Default::default()).unwrap();
        assert_eq!(params["item_rows"], "2:Pizza");
        results.insert("a_items".into(), vec![]);
        let params =
            super::query_render_params(&root, &feature, &results, &Default::default()).unwrap();
        assert_eq!(params["item_rows"], "2");
        std::fs::remove_dir_all(root).unwrap();
    }

    #[test]
    /// Resolves an app-owned redirect without allowing a path value to escape its segment.
    fn declared_redirect_keeps_path_parameter_in_one_segment() {
        let parameters = serde_json::Map::from_iter([(
            "business_slug".to_owned(),
            Value::String("one?two".to_owned()),
        )]);
        assert_eq!(
            action_redirect_path("/businesses/:business_slug/services/", &parameters)
                .expect("encoded redirect"),
            "/businesses/one%3Ftwo/services/"
        );
        assert!(action_redirect_path("/businesses/:missing/", &parameters).is_err());
        let traversal = serde_json::Map::from_iter([(
            "business_slug".to_owned(),
            Value::String("..".to_owned()),
        )]);
        assert!(action_redirect_path("/businesses/:business_slug/", &traversal).is_err());
    }

    /// Creates one unique filesystem root for a direct feature runtime test.
    fn test_root(label: &str) -> std::path::PathBuf {
        let nonce = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .expect("clock")
            .as_nanos();
        std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tmp")
            .join(format!(
                "pharos-feature-runtime-{label}-{}-{nonce}",
                std::process::id()
            ))
    }

    /// Writes one test fixture below a unique temporary root.
    fn write(root: &std::path::Path, relative: &str, content: &str) {
        let path = root.join(relative);
        std::fs::create_dir_all(path.parent().expect("parent")).expect("directories");
        std::fs::write(path, content).expect("fixture");
        if relative == "data/contracts/entities.json" {
            write_logical_test_contract(root, content);
        }
    }

    /// Applies the declared logical schema and seed records through one adapter.
    fn initialize_logical_test_records(root: &std::path::Path, records: &Value) -> i32 {
        let contract = pharos_runtime_database::contract::load_contract(
            &root.join("data/contracts/database.json"),
            "feature_test",
        )
        .expect("logical feature test contract");
        let store = super::super::database::logical_app_store(root, None, "feature_test")
            .expect("feature test operation store");
        store
            .adapter
            .apply_contract(&store.config, &contract)
            .expect("apply feature schema");
        let records: Vec<pharos_runtime_database::operations::Record> =
            serde_json::from_value(records.clone()).expect("logical feature seeds");
        if !records.is_empty() {
            store
                .adapter
                .import_batch(&store.config, &store.schema, &records)
                .expect("feature seed records");
        }
        0
    }

    /// Checks changed records without a vendor query or projection export.
    fn logical_test_value(
        root: &std::path::Path,
        entity: &str,
        field: &str,
        filter: Option<pharos_runtime_database::operations::Predicate>,
    ) -> Option<String> {
        use pharos_runtime_database::operations::{Aggregate, AggregateQuery, Query};
        let store = super::super::database::logical_app_store(root, None, "feature_test")
            .expect("feature test operation store");
        let value = if field == "COUNT(*)" {
            store
                .adapter
                .aggregate(
                    &store.config,
                    &store.schema,
                    &AggregateQuery {
                        entity: entity.to_owned(),
                        filter,
                        aggregate: Aggregate::Count,
                    },
                )
                .ok()?
        } else {
            store
                .adapter
                .query(
                    &store.config,
                    &store.schema,
                    &Query {
                        entity: entity.to_owned(),
                        fields: vec![field.to_owned()],
                        filter,
                        order: Vec::new(),
                        limit: 1,
                        offset: 0,
                    },
                )
                .ok()?
                .first()?
                .get(field)?
                .clone()
        };
        Some(
            value
                .as_str()
                .map(ToOwned::to_owned)
                .unwrap_or_else(|| value.to_string()),
        )
    }

    /// Declares the test schema explicitly so feature tests exercise the logical executor.
    fn write_logical_test_contract(root: &std::path::Path, content: &str) {
        use pharos_runtime_database::contract::{
            AppDataContract, migration_checksum, schema_from_entity_catalog,
        };
        use pharos_runtime_database::operations::{Migration, SchemaChange};
        let mut document: Value = serde_json::from_str(content).expect("entity catalog");
        for entity in document["entities"].as_array_mut().expect("entities") {
            for field in entity["fields"].as_array_mut().expect("fields") {
                let name = field["field_id"].as_str().expect("field name").to_owned();
                let kind = match name.as_str() {
                    "id" | "user_id" | "cart_id" | "product_id" | "price_minor"
                    | "available_quantity" => "integer",
                    "added_at" | "reserved_at" | "released_at" | "confirmed_at" => "timestamp",
                    "title" | "slug" | "status" | "reservation_status" | "release_reason" => "text",
                    _ => panic!("missing logical test field declaration: {name}"),
                };
                let nullable = matches!(name.as_str(), "released_at" | "confirmed_at");
                field["field_type"] = Value::String(kind.to_owned());
                field["nullable"] = Value::Bool(nullable);
                if name == "release_reason" {
                    field["field_default"] = serde_json::json!({"literal":""});
                }
            }
            entity["unique_keys"] = match entity["entity_id"].as_str().expect("entity name") {
                "cart" => serde_json::json!([["user_id"]]),
                "cart_item" => serde_json::json!([["cart_id", "product_id"]]),
                _ => serde_json::json!([]),
            };
        }
        let names = document["entities"]
            .as_array()
            .expect("entities")
            .iter()
            .map(|entity| entity["entity_id"].as_str().expect("entity name"))
            .collect::<Vec<_>>();
        let schema =
            schema_from_entity_catalog(&document, "feature_test", &names).expect("logical schema");
        let changes = schema
            .entities
            .iter()
            .cloned()
            .map(SchemaChange::CreateEntity)
            .collect::<Vec<_>>();
        let migration = Migration {
            app_id: "feature_test".to_owned(),
            id: "feature_schema".to_owned(),
            checksum: migration_checksum("feature_test", "feature_schema", &changes)
                .expect("checksum"),
            changes,
        };
        let contract = AppDataContract {
            schema,
            migrations: vec![migration],
            legacy_adoption: None,
        };
        std::fs::write(
            root.join("data/contracts/database.json"),
            serde_json::to_vec(&contract).expect("contract JSON"),
        )
        .expect("logical contract");
    }

    #[test]
    /// Keeps untrusted query text in a typed predicate for adapter-owned binding.
    fn query_values_are_bound_and_never_interpolated() {
        use pharos_runtime_database::operations::{
            AppSchema, Entity, Field, FieldType, Identity, Predicate,
        };
        let fields = ["id", "title", "status"]
            .into_iter()
            .map(|name| Field {
                name: name.to_owned(),
                kind: if name == "id" {
                    FieldType::Integer
                } else {
                    FieldType::Text
                },
                nullable: false,
                max_length: None,
                default: None,
                references: None,
                on_delete: None,
                constraints: Vec::new(),
            })
            .collect();
        let schema = AppSchema {
            app_id: "feature_test".to_owned(),
            entities: vec![Entity {
                name: "item".to_owned(),
                identity: Identity::AutoInteger("id".to_owned()),
                fields,
                unique: Vec::new(),
                indexes: Vec::new(),
                conditional_indexes: Vec::new(),
            }],
        };
        let context = FeatureRequestContext {
            query_params: serde_json::Map::from_iter([(
                "q".to_owned(),
                Value::String("%' OR 1=1 --".to_owned()),
            )]),
            ..FeatureRequestContext::default()
        };
        let filters =
            serde_json::json!({"title": {"value": {"query_param": "q"}, "operator": "contains"}});
        let predicate =
            super::logical::predicate_for_filters(filters.as_object(), &context, &schema, "item")
                .expect("typed predicate");
        assert_eq!(
            predicate,
            Some(Predicate::Contains(
                "title".to_owned(),
                "%' OR 1=1 --".to_owned()
            ))
        );
        let filters = serde_json::json!({"status": {"operator": "is_null"}});
        let predicate =
            super::logical::predicate_for_filters(filters.as_object(), &context, &schema, "item")
                .expect("typed null eligibility");
        assert_eq!(predicate, Some(Predicate::IsNull("status".to_owned())));
        let filters = serde_json::json!({"unknown": {"operator": "is_null"}});
        assert!(
            super::logical::predicate_for_filters(filters.as_object(), &context, &schema, "item")
                .is_err()
        );
    }

    #[test]
    /// Performs query and path inputs are bounded and duplicate free.
    fn query_and_path_inputs_are_bounded_and_duplicate_free() {
        let query = query_parameters("/?genre=house&q=kick+loop").expect("query");
        assert_eq!(query.get("q").and_then(Value::as_str), Some("kick loop"));
        assert!(query_parameters("/?q=one&q=two").is_err());
        let path = path_parameters("/packs/:slug", "/packs/neon-house").expect("path");
        assert_eq!(path.get("slug").and_then(Value::as_str), Some("neon-house"));
        assert!(path_parameters("/packs/:slug", "/packs/a/b").is_err());
    }

    #[test]
    /// Performs manifest declared payment copy exposes bounded template params.
    fn manifest_declared_payment_copy_exposes_template_params() {
        let root = test_root("payment-copy");
        std::fs::create_dir_all(&root).expect("root");
        std::fs::create_dir_all(root.join("data")).expect("data");
        write(
            &root,
            "pharos.app.json",
            r#"{"app_id":"feature_test","payments":{"checkout_mode":"demo","supported_providers":["stripe"],"provider_src":"data/payment_provider.yml","copy":{"checkout_headline":"Demo checkout","owner_gross_label":"Gross demo sales"}}}"#,
        );
        write(
            &root,
            "data/payment_provider.yml",
            "owner_resource_type: merchant\nsupported_providers:\n  - provider: stripe\ncopy:\n  owner_payment_provider_setup_headline: Connect Payment Provider\n",
        );
        let app = crate::config::AppRuntime {
            app_id: Some("feature_test".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            artifact_dir: Some(root.to_string_lossy().into_owned()),
            ..crate::config::AppRuntime::default()
        };
        let params = manifest_declared_template_params(&app).expect("manifest params");
        assert_eq!(
            params.get("payment_checkout_mode").and_then(Value::as_str),
            Some("Demo")
        );
        assert_eq!(
            params
                .get("payment_primary_provider")
                .and_then(Value::as_str),
            Some("stripe")
        );
        assert_eq!(
            params.get("owner_gross_label").and_then(Value::as_str),
            Some("Gross demo sales")
        );
        assert_eq!(
            params
                .get("owner_payment_provider_setup_headline")
                .and_then(Value::as_str),
            Some("Connect Payment Provider")
        );
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[cfg(all(feature = "sqlite", not(target_os = "wasi")))]
    #[test]
    /// Performs feature action commits once and renders refreshed fragment.
    fn feature_action_commits_once_and_renders_refreshed_fragment() {
        let root = test_root("action");
        let database_path = root.join("feature.sqlite3");
        std::fs::create_dir_all(&root).expect("root");
        write(
            &root,
            "pharos.app.yml",
            "app_id: feature_test\nname: Feature Test\nversion: 1.0.0\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        );
        write(
            &root,
            "app.conf",
            &format!("db_backend=sqlite\ndb_path={}\n", database_path.display()),
        );
        write(
            &root,
            "data/contracts/migrations.json",
            r#"{"state_cutover_mode":"relational_runtime_authority"}"#,
        );
        write(
            &root,
            "data/contracts/entities.json",
            r#"{"entities":[
              {"entity_id":"product","table":"product","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"status"}]},
              {"entity_id":"cart","table":"cart","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"user_id"}]},
              {"entity_id":"cart_item","table":"cart_item","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"cart_id"},{"field_id":"user_id"},{"field_id":"product_id"}]}
            ]}"#,
        );
        write(
            &root,
            "data/contracts/features.json",
            r#"{"features":[{"feature_id":"cart","queries":{
              "published_product":{"entity":"product","fields":["id","status"],"filters":{"id":"input.product_id","status":"published"},"result":"one"},
              "current_cart":{"entity":"cart","fields":["id","user_id"],"filters":{"user_id":"subject.user_id"},"result":"one"},
              "current_cart_items":{"entity":"cart_item","fields":["id","user_id","product_id"],"filters":{"user_id":"subject.user_id"},"result":"many","limit":20}
            }}]}"#,
        );
        write(
            &root,
            "data/contracts/actions.json",
            r#"{"actions":[{"action_id":"add_item","feature_id":"cart","input_contract":{"inline_fields":{"product_id":{"type":"integer","required":true,"minimum":1}},"reject_unknown":true},"transaction_contract":{"require":{"query":"published_product"},"upsert":{"entity":"cart_item","unique_by":["cart_id","product_id"],"values":{"cart_id":"query.current_cart.id","user_id":"subject.user_id","product_id":"input.product_id"}}},"response_contract":{"response_kind":"fragment","template":"templates/fragments/cart_summary.html","target":"cart-panel","queries":["current_cart_items"],"fallback":{"redirect":"/"}}}]}"#,
        );
        write(
            &root,
            "templates/fragments/cart_summary.html",
            r#"<aside id="cart-panel">{current_cart_items_count}</aside>"#,
        );
        assert_eq!(
            initialize_logical_test_records(
                &root,
                &serde_json::json!([{"entity":"product","fields":{"id":7,"status":"published"}},{"entity":"cart","fields":{"id":3,"user_id":42}}])
            ),
            0
        );
        let app = crate::config::AppRuntime {
            app_id: Some("feature_test".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            artifact_dir: Some(root.to_string_lossy().into_owned()),
            ..crate::config::AppRuntime::default()
        };
        let route = serde_json::json!({
            "path":"/cart/items",
            "feature_id":"cart",
            "action_id":"add_item"
        });
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/cart/items".to_owned(),
            content_type: Some("application/x-www-form-urlencoded".to_owned()),
            body: b"product_id=7&csrf_token=test".to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let first = execute_feature_action(&app, &route, &request, 42).expect("first action");
        let second = execute_feature_action(&app, &route, &request, 42).expect("idempotent action");
        assert!(first.fragment_html.contains(">1</aside>"));
        assert_eq!(second.fragment_html, first.fragment_html);
        assert_eq!(
            logical_test_value(&root, "cart_item", "COUNT(*)", None).as_deref(),
            Some("1")
        );
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[cfg(all(feature = "sqlite", not(target_os = "wasi")))]
    #[test]
    /// Performs feature action accepts JSON input for declared fields.
    fn feature_action_accepts_json_input_for_declared_fields() {
        let root = test_root("json-action");
        let database_path = root.join("feature.sqlite3");
        std::fs::create_dir_all(&root).expect("root");
        write(
            &root,
            "pharos.app.yml",
            "app_id: feature_test\nname: Feature Test\nversion: 1.0.0\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        );
        write(
            &root,
            "app.conf",
            &format!("db_backend=sqlite\ndb_path={}\n", database_path.display()),
        );
        write(
            &root,
            "data/contracts/migrations.json",
            r#"{"state_cutover_mode":"relational_runtime_authority"}"#,
        );
        write(
            &root,
            "data/contracts/entities.json",
            r#"{"entities":[
              {"entity_id":"product","table":"product","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"status"}]},
              {"entity_id":"cart","table":"cart","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"user_id"}]},
              {"entity_id":"cart_item","table":"cart_item","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"cart_id"},{"field_id":"user_id"},{"field_id":"product_id"}]}
            ]}"#,
        );
        write(
            &root,
            "data/contracts/features.json",
            r#"{"features":[{"feature_id":"cart","queries":{
              "published_product":{"entity":"product","fields":["id","status"],"filters":{"id":"input.product_id","status":"published"},"result":"one"},
              "current_cart":{"entity":"cart","fields":["id","user_id"],"filters":{"user_id":"subject.user_id"},"result":"one"},
              "current_cart_items":{"entity":"cart_item","fields":["id","user_id","product_id"],"filters":{"user_id":"subject.user_id"},"result":"many","limit":20}
            }}]}"#,
        );
        write(
            &root,
            "data/contracts/actions.json",
            r#"{"actions":[{"action_id":"add_item","feature_id":"cart","input_contract":{"inline_fields":{"product_id":{"type":"integer","required":true,"minimum":1}},"reject_unknown":true},"transaction_contract":{"require":{"query":"published_product"},"upsert":{"entity":"cart_item","unique_by":["cart_id","product_id"],"values":{"cart_id":"query.current_cart.id","user_id":"subject.user_id","product_id":"input.product_id"}}},"response_contract":{"response_kind":"fragment","template":"templates/fragments/cart_summary.html","target":"cart-panel","queries":["current_cart_items"],"fallback":{"redirect":"/"}},"guard_contract":{"guards":[]}}]}"#,
        );
        write(
            &root,
            "templates/fragments/cart_summary.html",
            r#"<aside id="cart-panel">{current_cart_items_count}</aside>"#,
        );
        assert_eq!(
            initialize_logical_test_records(
                &root,
                &serde_json::json!([{"entity":"product","fields":{"id":7,"status":"published"}},{"entity":"cart","fields":{"id":3,"user_id":42}}])
            ),
            0
        );
        let app = crate::config::AppRuntime {
            app_id: Some("feature_test".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            artifact_dir: Some(root.to_string_lossy().into_owned()),
            ..crate::config::AppRuntime::default()
        };
        let route = serde_json::json!({
            "path":"/cart/items",
            "feature_id":"cart",
            "action_id":"add_item"
        });
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/cart/items".to_owned(),
            content_type: Some("application/json".to_owned()),
            body: br#"{"product_id":7}"#.to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let outcome = execute_feature_action(&app, &route, &request, 42).expect("json action");
        assert!(outcome.fragment_html.contains(">1</aside>"));
        write(
            &root,
            "templates/connections.page.json",
            r#"{"page_id":"connections","template_file":"templates/fragments/connections.html"}"#,
        );
        write(
            &root,
            "templates/fragments/connections.html",
            r#"<div hx-get="/__pharos/social/youtube/status"></div><a href="/feature-test/owner">Owner</a>"#,
        );
        let mut mounted = app.clone();
        mounted.base_path = Some("/feature-test".into());
        let page = serde_json::json!({"path":"/connections","feature_id":"cart","page_id":"connections","queries":[]});
        let fragment =
            super::render_feature_page_body(&mounted, &page, "/connections", 42, "csrf").unwrap();
        assert!(fragment.contains("hx-get=\"/feature-test/__pharos/social/youtube/status\""));
        assert!(fragment.contains("href=\"/feature-test/owner\""));
        assert!(!fragment.contains("/feature-test/feature-test/"));
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[cfg(all(feature = "sqlite", not(target_os = "wasi")))]
    #[test]
    /// Performs feature action normalizes declared string input.
    fn feature_action_normalizes_declared_string_input() {
        let root = test_root("normalized-action");
        let database_path = root.join("feature.sqlite3");
        std::fs::create_dir_all(&root).expect("root");
        write(
            &root,
            "pharos.app.yml",
            "app_id: feature_test\nname: Feature Test\nversion: 1.0.0\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        );
        write(
            &root,
            "app.conf",
            &format!("db_backend=sqlite\ndb_path={}\n", database_path.display()),
        );
        write(
            &root,
            "data/contracts/migrations.json",
            r#"{"state_cutover_mode":"relational_runtime_authority"}"#,
        );
        write(
            &root,
            "data/contracts/entities.json",
            r#"{"entities":[
              {"entity_id":"note","table":"note","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"title"},{"field_id":"user_id"}]}
            ]}"#,
        );
        write(
            &root,
            "data/contracts/features.json",
            r#"{"features":[{"feature_id":"notes","queries":{
              "my_notes":{"entity":"note","fields":["id","title"],"filters":{"user_id":"subject.user_id"},"result":"many","limit":20}
            }}]}"#,
        );
        write(
            &root,
            "data/contracts/actions.json",
            r#"{"actions":[{"action_id":"add_note","feature_id":"notes","input_contract":{"inline_fields":{"title":{"type":"string","required":true,"min_length":1,"max_length":80}},"reject_unknown":true},"hook_contract":{"normalize_inputs":[{"kind":"trim","fields":["title"]},{"kind":"collapse_whitespace","fields":["title"]}]},"transaction_contract":{"insert":{"entity":"note","values":{"title":"input.title","user_id":"subject.user_id"}}},"response_contract":{"response_kind":"fragment","template":"templates/fragments/note_summary.html","target":"note-panel","queries":["my_notes"],"fallback":{"redirect":"/"}}}]}"#,
        );
        write(
            &root,
            "templates/fragments/note_summary.html",
            r#"<aside id="note-panel">{my_notes_count}</aside>"#,
        );
        assert_eq!(
            initialize_logical_test_records(&root, &serde_json::json!([])),
            0
        );
        let app = crate::config::AppRuntime {
            app_id: Some("feature_test".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            artifact_dir: Some(root.to_string_lossy().into_owned()),
            ..crate::config::AppRuntime::default()
        };
        let route = serde_json::json!({
            "path":"/notes",
            "feature_id":"notes",
            "action_id":"add_note"
        });
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/notes".to_owned(),
            content_type: Some("application/x-www-form-urlencoded".to_owned()),
            body: b"title=++Alpha+++Beta++&csrf_token=test".to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let outcome = execute_feature_action(&app, &route, &request, 42).expect("action");
        assert!(outcome.fragment_html.contains(">1</aside>"));
        assert_eq!(
            logical_test_value(
                &root,
                "note",
                "title",
                Some(pharos_runtime_database::operations::Predicate::Equal(
                    "user_id".to_owned(),
                    serde_json::json!(42)
                ))
            )
            .as_deref(),
            Some("Alpha Beta")
        );
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Performs validated action input applies default inputs before required checks.
    fn validated_action_input_applies_default_inputs_before_required_checks() {
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/snapshots/create".to_owned(),
            content_type: Some("application/x-www-form-urlencoded".to_owned()),
            body: b"csrf_token=test".to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let contract = serde_json::json!({
            "inline_fields": {
                "snapshot_label": {"type":"string","required":true,"min_length":1,"max_length":80}
            },
            "reject_unknown": true
        });
        let hook_contract = serde_json::json!({
            "default_inputs": [
                {"field":"snapshot_label","source":"literal","value":"initial-proof"}
            ]
        });
        let input = super::validated_action_input(
            &request,
            &contract,
            Some(&hook_contract),
            "snapshot_board_tasks",
        )
        .expect("default input");
        assert_eq!(
            input.get("snapshot_label").and_then(Value::as_str),
            Some("initial-proof")
        );
    }

    #[test]
    /// Performs validated action input preserves explicit empty literal defaults for optional fields.
    fn validated_action_input_preserves_empty_literal_default_inputs() {
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/snapshots/create".to_owned(),
            content_type: Some("application/x-www-form-urlencoded".to_owned()),
            body: b"title=Proof&csrf_token=test".to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let contract = serde_json::json!({
            "inline_fields": {
                "title": {"type":"string","required":true,"min_length":1,"max_length":80},
                "amount": {"type":"string","required":false,"max_length":120}
            },
            "reject_unknown": true
        });
        let hook_contract = serde_json::json!({
            "default_inputs": [
                {"field":"amount","source":"literal","value":""}
            ]
        });
        let input = super::validated_action_input(
            &request,
            &contract,
            Some(&hook_contract),
            "snapshot_board_tasks",
        )
        .expect("empty default input");
        assert_eq!(input.get("amount").and_then(Value::as_str), Some(""));
    }

    #[test]
    /// Performs validated action input accepts derived header and query values.
    fn validated_action_input_accepts_derived_header_and_query_values() {
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/notes/create?source=release-page".to_owned(),
            headers: "X-Feature-Title:   Header   Title  \r\n".to_owned(),
            content_type: Some("application/x-www-form-urlencoded".to_owned()),
            body: b"csrf_token=test".to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let contract = serde_json::json!({
            "inline_fields": {
                "title": {"type":"string","required":true,"min_length":1,"max_length":80},
                "source_label": {"type":"string","required":true,"min_length":1,"max_length":80}
            },
            "reject_unknown": true
        });
        let hook_contract = serde_json::json!({
            "derived_inputs": [
                {"field":"title","source":"header","header":"X-Feature-Title"},
                {"field":"source_label","source":"query","param":"source"}
            ],
            "normalize_inputs": [
                {"kind":"trim","fields":["title"]},
                {"kind":"collapse_whitespace","fields":["title"]}
            ]
        });
        let input =
            super::validated_action_input(&request, &contract, Some(&hook_contract), "add_note")
                .expect("derived input");
        assert_eq!(
            input.get("title").and_then(Value::as_str),
            Some("Header Title")
        );
        assert_eq!(
            input.get("source_label").and_then(Value::as_str),
            Some("release-page")
        );
    }

    #[cfg(all(feature = "sqlite", not(target_os = "wasi")))]
    #[test]
    /// Performs feature action guard returns structured validation report.
    fn feature_action_guard_returns_structured_validation_report() {
        let root = test_root("guard-action");
        let database_path = root.join("feature.sqlite3");
        std::fs::create_dir_all(&root).expect("root");
        write(
            &root,
            "pharos.app.yml",
            "app_id: feature_test\nname: Feature Test\nversion: 1.0.0\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        );
        write(
            &root,
            "app.conf",
            &format!("db_backend=sqlite\ndb_path={}\n", database_path.display()),
        );
        write(
            &root,
            "data/contracts/migrations.json",
            r#"{"state_cutover_mode":"relational_runtime_authority"}"#,
        );
        write(
            &root,
            "data/contracts/entities.json",
            r#"{"entities":[
              {"entity_id":"product","table":"product","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"status"},{"field_id":"price_minor"}]},
              {"entity_id":"cart","table":"cart","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"user_id"}]},
              {"entity_id":"cart_item","table":"cart_item","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"cart_id"},{"field_id":"user_id"},{"field_id":"product_id"},{"field_id":"price_minor"}]}
            ]}"#,
        );
        write(
            &root,
            "data/contracts/features.json",
            r#"{"features":[{"feature_id":"cart","queries":{
              "published_product":{"entity":"product","fields":["id","status","price_minor"],"filters":{"id":"input.product_id","status":"published"},"result":"one"},
              "current_cart":{"entity":"cart","fields":["id","user_id"],"filters":{"user_id":"subject.user_id"},"result":"one"},
              "current_cart_items":{"entity":"cart_item","fields":["id","user_id","product_id","price_minor"],"filters":{"user_id":"subject.user_id"},"result":"many","limit":20}
            }}]}"#,
        );
        write(
            &root,
            "data/contracts/actions.json",
            r#"{"actions":[{"action_id":"add_item","feature_id":"cart","input_contract":{"inline_fields":{"product_id":{"type":"integer","required":true,"minimum":1}},"reject_unknown":true},"transaction_contract":{"steps":[{"require":{"query":"published_product"}},{"require":{"query":"current_cart"}},{"upsert":{"entity":"cart_item","unique_by":["cart_id","product_id"],"values":{"cart_id":"query.current_cart.id","user_id":"subject.user_id","product_id":"input.product_id","price_minor":"query.published_product.price_minor"}}}]},"response_contract":{"response_kind":"fragment","template":"templates/fragments/cart_summary.html","target":"cart-panel","queries":["current_cart_items"],"fallback":{"redirect":"/"}},"guard_contract":{"guards":[{"guard_id":"demo_cart_total_minor_cap","kind":"sum","query":"current_cart_items","field":"price_minor","add":"query.published_product.price_minor","maximum":6000,"message":"Demo cart total is capped at $60 before checkout."}]}}]}"#,
        );
        write(
            &root,
            "templates/fragments/cart_summary.html",
            r#"<aside id="cart-panel">{current_cart_items_count}</aside>"#,
        );
        assert_eq!(
            initialize_logical_test_records(
                &root,
                &serde_json::json!([{"entity":"product","fields":{"id":1,"status":"published","price_minor":2900}},{"entity":"product","fields":{"id":2,"status":"published","price_minor":3400}},{"entity":"cart","fields":{"id":3,"user_id":42}},{"entity":"cart_item","fields":{"id":9,"cart_id":3,"user_id":42,"product_id":1,"price_minor":2900}}])
            ),
            0
        );
        let app = crate::config::AppRuntime {
            app_id: Some("feature_test".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            artifact_dir: Some(root.to_string_lossy().into_owned()),
            ..crate::config::AppRuntime::default()
        };
        let route = serde_json::json!({
            "path":"/cart/items",
            "feature_id":"cart",
            "action_id":"add_item"
        });
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/cart/items".to_owned(),
            content_type: Some("application/json".to_owned()),
            body: br#"{"product_id":2}"#.to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let error =
            execute_feature_action(&app, &route, &request, 42).expect_err("guard rejection");
        match error {
            FeatureRuntimeError::ValidationReport(report) => {
                assert!(report.contains("demo_cart_total_minor_cap"));
                assert!(report.contains("Demo cart total is capped at $60 before checkout."));
            }
            other => panic!("unexpected error: {other:?}"),
        }
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[cfg(all(feature = "sqlite", not(target_os = "wasi")))]
    #[test]
    /// Performs feature action reserve releases expired rows before capacity check.
    fn feature_action_reserve_releases_expired_rows_before_capacity_check() {
        let root = test_root("reserve-expiry-action");
        let database_path = root.join("feature.sqlite3");
        std::fs::create_dir_all(&root).expect("root");
        write(
            &root,
            "pharos.app.yml",
            "app_id: feature_test\nname: Feature Test\nversion: 1.0.0\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        );
        write(
            &root,
            "app.conf",
            &format!("db_backend=sqlite\ndb_path={}\n", database_path.display()),
        );
        write(
            &root,
            "data/contracts/migrations.json",
            r#"{"state_cutover_mode":"relational_runtime_authority"}"#,
        );
        write(
            &root,
            "data/contracts/entities.json",
            r#"{"entities":[
              {"entity_id":"product","table":"product","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"status"},{"field_id":"slug"},{"field_id":"title"},{"field_id":"price_minor"}]},
              {"entity_id":"cart","table":"cart","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"user_id"}]},
              {"entity_id":"cart_item","table":"cart_item","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"cart_id"},{"field_id":"user_id"},{"field_id":"product_id"},{"field_id":"price_minor"},{"field_id":"added_at"}]},
              {"entity_id":"product_inventory","table":"product_inventory","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"product_id"},{"field_id":"available_quantity"}]},
              {"entity_id":"inventory_reservation","table":"inventory_reservation","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"cart_id"},{"field_id":"user_id"},{"field_id":"product_id"},{"field_id":"reservation_status"},{"field_id":"reserved_at"},{"field_id":"released_at"},{"field_id":"release_reason"}]}
            ]}"#,
        );
        write(
            &root,
            "data/contracts/features.json",
            r#"{"features":[{"feature_id":"cart","queries":{
              "published_product":{"entity":"product","fields":["id","status","slug","title","price_minor"],"filters":{"id":"input.product_id","status":"published"},"result":"one"},
              "current_cart":{"entity":"cart","fields":["id","user_id"],"filters":{"user_id":"subject.user_id"},"result":"one"},
              "current_cart_items":{"entity":"cart_item","fields":["id","user_id","product_id","price_minor","added_at"],"filters":{"user_id":"subject.user_id","added_at":{"value":{"server_now_minus_seconds":3600},"operator":"gt"}},"result":"many","limit":20},
              "product_inventory":{"entity":"product_inventory","fields":["id","product_id","available_quantity"],"filters":{"product_id":"input.product_id"},"result":"one"}
            }}]}"#,
        );
        write(
            &root,
            "data/contracts/actions.json",
            r#"{"actions":[{"action_id":"add_item","feature_id":"cart","input_contract":{"inline_fields":{"product_id":{"type":"integer","required":true,"minimum":1}},"reject_unknown":true},"transaction_contract":{"steps":[{"require":{"query":"published_product"}},{"require":{"query":"current_cart"}},{"require":{"query":"product_inventory"}},{"reserve":{"entity":"inventory_reservation","status_field":"reservation_status","active_statuses":["reserved","confirmed"],"expires_after_seconds":3600,"owner_filters":{"cart_id":"query.current_cart.id","product_id":"query.published_product.id"},"scope_filters":{"product_id":"query.published_product.id"},"capacity":"query.product_inventory.available_quantity","on_conflict":{"code":"inventory_reserved_out","message":"Inventory is fully reserved."},"values":{"cart_id":"query.current_cart.id","user_id":"subject.user_id","product_id":"query.published_product.id","reservation_status":"reserved","reserved_at":"server.now"}}},{"upsert":{"entity":"cart_item","unique_by":["cart_id","product_id"],"update_on_conflict":true,"values":{"cart_id":"query.current_cart.id","user_id":"subject.user_id","product_id":"query.published_product.id","price_minor":"query.published_product.price_minor","added_at":"server.now"}}}]},"response_contract":{"response_kind":"fragment","template":"templates/fragments/cart_summary.html","target":"cart-panel","queries":["current_cart_items"],"fallback":{"redirect":"/"}}}]}"#,
        );
        write(
            &root,
            "templates/fragments/cart_summary.html",
            r#"<aside id="cart-panel">{current_cart_items_count}</aside>"#,
        );
        assert_eq!(
            initialize_logical_test_records(
                &root,
                &serde_json::json!([{"entity":"product","fields":{"id":1,"status":"published","slug":"neon","title":"Neon","price_minor":2900}},{"entity":"cart","fields":{"id":3,"user_id":42}},{"entity":"cart","fields":{"id":5,"user_id":7}},{"entity":"cart_item","fields":{"id":4,"cart_id":3,"user_id":42,"product_id":1,"price_minor":2900,"added_at":"2026-08-30T00:00:00Z"}},{"entity":"product_inventory","fields":{"id":1,"product_id":1,"available_quantity":1}},{"entity":"inventory_reservation","fields":{"id":9,"cart_id":5,"user_id":7,"product_id":1,"reservation_status":"reserved","reserved_at":"2026-08-30T00:00:00Z","release_reason":""}},{"entity":"inventory_reservation","fields":{"id":10,"cart_id":3,"user_id":42,"product_id":1,"reservation_status":"reserved","reserved_at":"2026-08-30T00:00:00Z","release_reason":""}}])
            ),
            0
        );
        let app = crate::config::AppRuntime {
            app_id: Some("feature_test".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            artifact_dir: Some(root.to_string_lossy().into_owned()),
            ..crate::config::AppRuntime::default()
        };
        let route = serde_json::json!({
            "path":"/cart/items",
            "feature_id":"cart",
            "action_id":"add_item"
        });
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/cart/items".to_owned(),
            content_type: Some("application/json".to_owned()),
            body: br#"{"product_id":1}"#.to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let outcome = execute_feature_action(&app, &route, &request, 42).expect("reserve action");
        assert!(outcome.fragment_html.contains(r#"id="cart-panel""#));
        assert_eq!(
            logical_test_value(
                &root,
                "inventory_reservation",
                "reservation_status",
                Some(pharos_runtime_database::operations::Predicate::Equal(
                    "id".to_owned(),
                    serde_json::json!(9)
                ))
            )
            .as_deref(),
            Some("released")
        );
        assert_eq!(
            logical_test_value(
                &root,
                "inventory_reservation",
                "reservation_status",
                Some(pharos_runtime_database::operations::Predicate::Equal(
                    "id".to_owned(),
                    serde_json::json!(10)
                ))
            )
            .as_deref(),
            Some("released")
        );
        assert_eq!(
            logical_test_value(
                &root,
                "inventory_reservation",
                "release_reason",
                Some(pharos_runtime_database::operations::Predicate::Equal(
                    "id".to_owned(),
                    serde_json::json!(9)
                ))
            )
            .as_deref(),
            Some("reservation_expired")
        );
        assert_eq!(
            logical_test_value(
                &root,
                "inventory_reservation",
                "COUNT(*)",
                Some(pharos_runtime_database::operations::Predicate::Equal(
                    "reservation_status".to_owned(),
                    serde_json::json!("reserved")
                ))
            )
            .as_deref(),
            Some("1")
        );
        assert_ne!(
            logical_test_value(
                &root,
                "cart_item",
                "added_at",
                Some(pharos_runtime_database::operations::Predicate::Equal(
                    "id".to_owned(),
                    serde_json::json!(4)
                ))
            )
            .as_deref(),
            Some("2026-08-30T00:00:00Z")
        );
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[cfg(all(feature = "sqlite", not(target_os = "wasi")))]
    #[test]
    /// Performs feature action reserve returns structured conflict report.
    fn feature_action_reserve_returns_structured_conflict_report() {
        let root = test_root("reserve-action");
        let database_path = root.join("feature.sqlite3");
        std::fs::create_dir_all(&root).expect("root");
        write(
            &root,
            "pharos.app.yml",
            "app_id: feature_test\nname: Feature Test\nversion: 1.0.0\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        );
        write(
            &root,
            "app.conf",
            &format!("db_backend=sqlite\ndb_path={}\n", database_path.display()),
        );
        write(
            &root,
            "data/contracts/migrations.json",
            r#"{"state_cutover_mode":"relational_runtime_authority"}"#,
        );
        write(
            &root,
            "data/contracts/entities.json",
            r#"{"entities":[
              {"entity_id":"product","table":"product","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"status"},{"field_id":"slug"},{"field_id":"title"},{"field_id":"price_minor"}]},
              {"entity_id":"cart","table":"cart","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"user_id"}]},
              {"entity_id":"cart_item","table":"cart_item","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"cart_id"},{"field_id":"user_id"},{"field_id":"product_id"},{"field_id":"price_minor"}]},
              {"entity_id":"product_inventory","table":"product_inventory","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"product_id"},{"field_id":"available_quantity"}]},
              {"entity_id":"inventory_reservation","table":"inventory_reservation","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"cart_id"},{"field_id":"user_id"},{"field_id":"product_id"},{"field_id":"reservation_status"},{"field_id":"reserved_at"},{"field_id":"released_at"},{"field_id":"release_reason"}]}
            ]}"#,
        );
        write(
            &root,
            "data/contracts/features.json",
            r#"{"features":[{"feature_id":"cart","queries":{
              "published_product":{"entity":"product","fields":["id","status","slug","title","price_minor"],"filters":{"id":"input.product_id","status":"published"},"result":"one"},
              "current_cart":{"entity":"cart","fields":["id","user_id"],"filters":{"user_id":"subject.user_id"},"result":"one"},
              "current_cart_items":{"entity":"cart_item","fields":["id","user_id","product_id","price_minor"],"filters":{"user_id":"subject.user_id"},"result":"many","limit":20},
              "product_inventory":{"entity":"product_inventory","fields":["id","product_id","available_quantity"],"filters":{"product_id":"input.product_id"},"result":"one"}
            }}]}"#,
        );
        write(
            &root,
            "data/contracts/actions.json",
            r#"{"actions":[{"action_id":"add_item","feature_id":"cart","input_contract":{"inline_fields":{"product_id":{"type":"integer","required":true,"minimum":1}},"reject_unknown":true},"transaction_contract":{"steps":[{"require":{"query":"published_product"}},{"require":{"query":"current_cart"}},{"require":{"query":"product_inventory"}},{"reserve":{"entity":"inventory_reservation","status_field":"reservation_status","active_statuses":["reserved","confirmed"],"owner_filters":{"cart_id":"query.current_cart.id","product_id":"query.published_product.id"},"scope_filters":{"product_id":"query.published_product.id"},"capacity":"query.product_inventory.available_quantity","on_conflict":{"code":"inventory_reserved_out","message":"Inventory is fully reserved."},"values":{"cart_id":"query.current_cart.id","user_id":"subject.user_id","product_id":"query.published_product.id","reservation_status":"reserved","reserved_at":"server.now"}}},{"insert":{"entity":"cart_item","values":{"cart_id":"query.current_cart.id","user_id":"subject.user_id","product_id":"query.published_product.id","price_minor":"query.published_product.price_minor"}}}]},"response_contract":{"response_kind":"fragment","template":"templates/fragments/cart_summary.html","target":"cart-panel","queries":["current_cart_items"],"fallback":{"redirect":"/"}}}]}"#,
        );
        write(
            &root,
            "templates/fragments/cart_summary.html",
            r#"<aside id="cart-panel">{current_cart_items_count}</aside>"#,
        );
        assert_eq!(
            initialize_logical_test_records(
                &root,
                &serde_json::json!([{"entity":"product","fields":{"id":1,"status":"published","slug":"neon","title":"Neon","price_minor":2900}},{"entity":"cart","fields":{"id":3,"user_id":42}},{"entity":"cart","fields":{"id":5,"user_id":7}},{"entity":"product_inventory","fields":{"id":1,"product_id":1,"available_quantity":1}},{"entity":"inventory_reservation","fields":{"id":9,"cart_id":5,"user_id":7,"product_id":1,"reservation_status":"reserved","reserved_at":"2026-08-30T00:00:00Z","release_reason":""}}])
            ),
            0
        );
        let app = crate::config::AppRuntime {
            app_id: Some("feature_test".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            artifact_dir: Some(root.to_string_lossy().into_owned()),
            ..crate::config::AppRuntime::default()
        };
        let route = serde_json::json!({
            "path":"/cart/items",
            "feature_id":"cart",
            "action_id":"add_item"
        });
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/cart/items".to_owned(),
            content_type: Some("application/json".to_owned()),
            body: br#"{"product_id":1}"#.to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let error =
            execute_feature_action(&app, &route, &request, 42).expect_err("reservation rejection");
        match error {
            FeatureRuntimeError::ValidationReport(report) => {
                assert!(report.contains("inventory_reserved_out"));
                assert!(report.contains("Inventory is fully reserved."));
            }
            other => panic!("unexpected error: {other:?}"),
        }
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[cfg(all(feature = "sqlite", not(target_os = "wasi")))]
    #[test]
    /// Performs feature action confirm transitions reserved row.
    fn feature_action_confirm_transitions_reserved_row() {
        let root = test_root("confirm-action");
        let database_path = root.join("feature.sqlite3");
        std::fs::create_dir_all(&root).expect("root");
        write(
            &root,
            "pharos.app.yml",
            "app_id: feature_test\nname: Feature Test\nversion: 1.0.0\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        );
        write(
            &root,
            "app.conf",
            &format!("db_backend=sqlite\ndb_path={}\n", database_path.display()),
        );
        write(
            &root,
            "data/contracts/migrations.json",
            r#"{"state_cutover_mode":"relational_runtime_authority"}"#,
        );
        write(
            &root,
            "data/contracts/entities.json",
            r#"{"entities":[
              {"entity_id":"cart","table":"cart","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"user_id"}]},
              {"entity_id":"inventory_reservation","table":"inventory_reservation","identity_field":"id","fields":[{"field_id":"id"},{"field_id":"cart_id"},{"field_id":"user_id"},{"field_id":"product_id"},{"field_id":"reservation_status"},{"field_id":"reserved_at"},{"field_id":"confirmed_at"},{"field_id":"released_at"},{"field_id":"release_reason"}]}
            ]}"#,
        );
        write(
            &root,
            "data/contracts/features.json",
            r#"{"features":[{"feature_id":"cart","queries":{
              "current_cart":{"entity":"cart","fields":["id","user_id"],"filters":{"user_id":"subject.user_id"},"result":"one"}
            }}]}"#,
        );
        write(
            &root,
            "data/contracts/actions.json",
            r#"{"actions":[{"action_id":"confirm_item","feature_id":"cart","input_contract":{"inline_fields":{"product_id":{"type":"integer","required":true,"minimum":1}},"reject_unknown":true},"transaction_contract":{"steps":[{"require":{"query":"current_cart"}},{"confirm":{"entity":"inventory_reservation","status_field":"reservation_status","active_statuses":["reserved"],"owner_filters":{"cart_id":"query.current_cart.id","product_id":"input.product_id","user_id":"subject.user_id"},"scope_filters":{"product_id":"input.product_id"},"capacity":1,"to_status":"confirmed","values":{"confirmed_at":"server.now","release_reason":""}}}]},"response_contract":{"response_kind":"fragment","template":"templates/fragments/cart_summary.html","target":"cart-panel","queries":[],"fallback":{"redirect":"/"}}}]}"#,
        );
        write(
            &root,
            "templates/fragments/cart_summary.html",
            r#"<aside id="cart-panel">ok</aside>"#,
        );
        assert_eq!(
            initialize_logical_test_records(
                &root,
                &serde_json::json!([{"entity":"cart","fields":{"id":3,"user_id":42}},{"entity":"inventory_reservation","fields":{"id":9,"cart_id":3,"user_id":42,"product_id":1,"reservation_status":"reserved","reserved_at":"2026-08-30T00:00:00Z","release_reason":""}}])
            ),
            0
        );
        let app = crate::config::AppRuntime {
            app_id: Some("feature_test".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            artifact_dir: Some(root.to_string_lossy().into_owned()),
            ..crate::config::AppRuntime::default()
        };
        let route = serde_json::json!({
            "path":"/cart/confirm",
            "feature_id":"cart",
            "action_id":"confirm_item"
        });
        let request = super::super::http::HttpRequest {
            method: "POST".to_owned(),
            target: "/cart/confirm".to_owned(),
            content_type: Some("application/json".to_owned()),
            body: br#"{"product_id":1}"#.to_vec(),
            ..super::super::http::HttpRequest::default()
        };
        let outcome = execute_feature_action(&app, &route, &request, 42).expect("confirm action");
        assert!(outcome.fragment_html.contains("ok"));
        assert_eq!(
            logical_test_value(
                &root,
                "inventory_reservation",
                "reservation_status",
                Some(pharos_runtime_database::operations::Predicate::Equal(
                    "id".to_owned(),
                    serde_json::json!(9)
                ))
            )
            .as_deref(),
            Some("confirmed")
        );
        std::fs::remove_dir_all(root).expect("cleanup");
    }
}