pharos_native/runtime/

json_commands.rs

#![allow(clippy::too_many_arguments)]

use std::fs;

use std::path::{Component, Path, PathBuf};

use saphyr::LoadableYamlNode;
use serde_json::{Map, Value};
use sha2::{Digest, Sha256};

use crate::config;

pub use super::database::{
    dynamic_relational_backend, dynamic_relational_runtime_audit_count,
    dynamic_relational_runtime_export_json, dynamic_relational_runtime_import_state,
    dynamic_runtime_prepare, dynamic_runtime_ready, load_cli_backend_config,
};
use super::generated;

#[derive(Debug, Clone, Eq, PartialEq)]
struct MultipartPart {
    name: String,
    text: Option<String>,
    filename: Option<String>,
    content: Vec<u8>,
}

#[derive(Debug, Clone, Eq, PartialEq)]
pub struct MultipartFilePart {
    pub filename: String,
    pub content: Vec<u8>,
}

/// Reads JSON file.
fn read_json_file(path: &Path) -> Option<Value> {
    serde_json::from_str(&fs::read_to_string(path).ok()?).ok()
}

/// Performs JSON string.
fn json_string<'a>(value: &'a Value, key: &str) -> Option<&'a str> {
    value.get(key).and_then(Value::as_str)
}

/// Bundles manifest slice order lines.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::bundle_manifest_slice_order_lines`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::bundle_manifest_slice_order_lines`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::bundle_manifest_slice_order_lines`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::bundle_manifest_slice_order_lines(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn bundle_manifest_slice_order_lines(path: &Path) -> Option<Vec<String>> {
    let root = read_json_file(path)?;
    let mut lines = Vec::new();
    if let Some(slices) = root.get("slices").and_then(Value::as_array) {
        for item in slices {
            if let Some(path) = json_string(item, "path") {
                lines.push(path.to_owned());
            }
        }
    }
    if lines.is_empty()
        && let Some(slice_order) = root.get("slice_order").and_then(Value::as_array)
    {
        for item in slice_order {
            if let Some(text) = item.as_str() {
                lines.push(text.to_owned());
            }
        }
    }
    (!lines.is_empty()).then_some(lines)
}

/// Bundles manifest layer for slice.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::bundle_manifest_layer_for_slice`].
/// - `slice_name`: Input consumed by [`crate::runtime::json_commands::bundle_manifest_layer_for_slice`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::bundle_manifest_layer_for_slice`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::bundle_manifest_layer_for_slice`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::bundle_manifest_layer_for_slice(std::path::Path::new("fixture.json"), "slice");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn bundle_manifest_layer_for_slice(path: &Path, slice_name: &str) -> Option<Option<String>> {
    if slice_name.is_empty() {
        return None;
    }
    let root = read_json_file(path)?;
    let slices = root.get("slices").and_then(Value::as_array)?;
    for item in slices {
        if json_string(item, "path") == Some(slice_name) {
            return Some(
                json_string(item, "materialize_from_runtime_layer").map(ToOwned::to_owned),
            );
        }
    }
    Some(None)
}

/// Performs request compact JSON.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::request_compact_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_compact_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_compact_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_compact_json("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_compact_json(text: &str) -> Option<String> {
    serde_json::from_str::<Value>(text)
        .ok()
        .and_then(|value| serde_json::to_string(&value).ok())
}

/// Performs request compact object.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::request_compact_object`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::request_compact_object`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_compact_object`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_compact_object("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_compact_object(text: &str) -> String {
    match serde_json::from_str::<Value>(text) {
        Ok(value) if value.is_object() => {
            serde_json::to_string(&value).unwrap_or_else(|_| "{}".to_owned())
        }
        _ => "{}".to_owned(),
    }
}

/// Performs request compact object strict.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::request_compact_object_strict`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_compact_object_strict`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_compact_object_strict`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_compact_object_strict("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_compact_object_strict(text: &str) -> Option<String> {
    let value = serde_json::from_str::<Value>(text).ok()?;
    value
        .is_object()
        .then(|| serde_json::to_string(&value).ok())
        .flatten()
}

/// Performs request field.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::request_field`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::request_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_field`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_field("{}", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_field(text: &str, field: &str) -> Option<String> {
    if field.is_empty() {
        return None;
    }
    serde_json::from_str::<Value>(text)
        .ok()?
        .as_object()?
        .get(field)?
        .as_str()
        .map(ToOwned::to_owned)
}

/// Performs manifest fixture path raw.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::manifest_fixture_path_raw`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::manifest_fixture_path_raw`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::manifest_fixture_path_raw`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::manifest_fixture_path_raw(std::path::Path::new("fixture.json"), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn manifest_fixture_path_raw(path: &Path, key: &str) -> Option<String> {
    if key.is_empty() {
        return None;
    }
    let root = read_json_file(path)?;
    json_string(&root, key)
        .or_else(|| {
            root.get("fixtures")
                .and_then(|value| json_string(value, key))
        })
        .or_else(|| {
            root.get("database")
                .and_then(|value| json_string(value, key))
        })
        .map(ToOwned::to_owned)
}

/// Performs manifest app root.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::manifest_app_root`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::manifest_app_root`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::manifest_app_root(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn manifest_app_root(path: &Path) -> Option<String> {
    json_string(&read_json_file(path)?, "app_root").map(ToOwned::to_owned)
}

/// Performs URL decode component.
fn url_decode_component(text: &str) -> Option<String> {
    let bytes = text.as_bytes();
    let mut out = Vec::with_capacity(text.len());
    let mut index = 0usize;
    while index < bytes.len() {
        match bytes[index] {
            b'+' => {
                out.push(b' ');
                index += 1;
            }
            b'%' if index + 2 < bytes.len() => {
                let hex = std::str::from_utf8(&bytes[index + 1..index + 3]).ok()?;
                let value = u8::from_str_radix(hex, 16).ok()?;
                out.push(value);
                index += 3;
            }
            b'%' => return None,
            value => {
                out.push(value);
                index += 1;
            }
        }
    }
    String::from_utf8(out).ok()
}

/// Ensures percent-decoded bytes become UTF-8 once, preserving editor labels and user copy.
#[cfg(test)]
#[test]
fn form_components_preserve_utf8() {
    assert_eq!(
        url_decode_component("action+%E2%80%94+caf%C3%A9"),
        Some("action — café".into())
    );
    assert_eq!(url_decode_component("日本語"), Some("日本語".into()));
    assert_eq!(url_decode_component("%FF"), None);
    assert_eq!(url_decode_component("%E2%"), None);
}

/// Percent-encodes one bounded query value for safe reuse in generated links.
pub(super) fn url_encode_query_component(value: &str) -> String {
    const HEX: &[u8; 16] = b"0123456789ABCDEF";
    let mut encoded = String::with_capacity(value.len());
    for byte in value.bytes() {
        if byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'.' | b'_' | b'~') {
            encoded.push(char::from(byte));
        } else {
            encoded.push('%');
            encoded.push(char::from(HEX[usize::from(byte >> 4)]));
            encoded.push(char::from(HEX[usize::from(byte & 0x0f)]));
        }
    }
    encoded
}

/// Performs request query value.
///
/// # Parameters
///
/// - `query`: Input consumed by [`crate::runtime::json_commands::request_query_value`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::request_query_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_query_value`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_query_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_query_value("page=1", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_query_value(query: &str, key: &str) -> Option<String> {
    if key.is_empty() {
        return None;
    }
    for pair in query.split('&') {
        let (raw_key, raw_value) = pair.split_once('=').unwrap_or((pair, ""));
        if url_decode_component(raw_key).as_deref() == Some(key) {
            return url_decode_component(raw_value);
        }
    }
    None
}

/// Performs request form value.
///
/// # Parameters
///
/// - `form_body`: Input consumed by [`crate::runtime::json_commands::request_form_value`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::request_form_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_form_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_form_value("name=value", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_form_value(form_body: &str, key: &str) -> Option<String> {
    request_query_value(form_body, key)
}

/// Performs multipart boundary.
fn multipart_boundary(content_type: &str) -> Option<String> {
    let boundary_start = content_type.find("boundary=")? + 9;
    let suffix = &content_type[boundary_start..];
    if let Some(stripped) = suffix.strip_prefix('"') {
        let end = stripped.find('"')?;
        return Some(stripped[..end].to_owned());
    }
    let end = suffix
        .find(|ch: char| ch == ';' || ch.is_ascii_whitespace())
        .unwrap_or(suffix.len());
    (end > 0).then(|| suffix[..end].to_owned())
}

/// Finds bytes.
fn find_bytes(haystack: &[u8], needle: &[u8], start: usize) -> Option<usize> {
    if needle.is_empty() || haystack.len() < needle.len() || start >= haystack.len() {
        return None;
    }
    haystack[start..]
        .windows(needle.len())
        .position(|window| window == needle)
        .map(|offset| start + offset)
}

/// Performs multipart header param.
fn multipart_header_param(headers_text: &str, key: &str) -> Option<String> {
    let pattern = format!("{key}=\"");
    let match_index = headers_text.find(&pattern)? + pattern.len();
    let suffix = &headers_text[match_index..];
    let end = suffix.find('"')?;
    Some(suffix[..end].to_owned())
}

/// Performs multipart find part from body.
fn multipart_parts_from_body(
    body: &[u8],
    content_type: &str,
    field_name: &str,
    max_parts: usize,
    max_total_bytes: usize,
) -> Vec<MultipartPart> {
    if body.is_empty() || field_name.is_empty() || max_parts == 0 {
        return Vec::new();
    }

    let Some(boundary) = multipart_boundary(content_type) else {
        return Vec::new();
    };
    if boundary.is_empty() {
        return Vec::new();
    }

    let delimiter = format!("--{boundary}").into_bytes();
    let delimiter_lf = format!("\n--{boundary}").into_bytes();
    let Some(mut cursor) = find_bytes(body, &delimiter, 0) else {
        return Vec::new();
    };
    let mut parts = Vec::new();
    let mut total_bytes = 0usize;
    let mut scanned_parts = 0usize;

    while cursor + delimiter.len() <= body.len() {
        scanned_parts += 1;
        if scanned_parts > 1024 {
            return Vec::new();
        }
        let mut part_cursor = cursor + delimiter.len();
        if part_cursor + 2 <= body.len()
            && body[part_cursor] == b'-'
            && body[part_cursor + 1] == b'-'
        {
            break;
        }
        if part_cursor + 2 <= body.len()
            && body[part_cursor] == b'\r'
            && body[part_cursor + 1] == b'\n'
        {
            part_cursor += 2;
        } else if part_cursor < body.len() && body[part_cursor] == b'\n' {
            part_cursor += 1;
        }

        // Header searches must not rescan the remaining file payload for each part.
        let header_limit = body.len().min(part_cursor.saturating_add(16 * 1024));
        let next_crlf = find_bytes(&body[..header_limit], b"\r\n\r\n", part_cursor);
        let next_lf = find_bytes(&body[..header_limit], b"\n\n", part_cursor);
        let (header_end, header_sep_len) = match (next_crlf, next_lf) {
            (Some(crlf), Some(lf)) if crlf <= lf => (crlf, 4usize),
            (Some(crlf), None) => (crlf, 4usize),
            (None, Some(lf)) => (lf, 2usize),
            _ => break,
        };

        let headers_text = String::from_utf8_lossy(&body[part_cursor..header_end]).into_owned();
        let part_name = multipart_header_param(&headers_text, "name");
        let filename = multipart_header_param(&headers_text, "filename");
        let content_start = header_end + header_sep_len;

        let next_marker = find_bytes(body, &delimiter_lf, content_start)
            .map(|marker| {
                if marker > content_start && body[marker - 1] == b'\r' {
                    marker - 1
                } else {
                    marker
                }
            })
            .unwrap_or(body.len());

        if part_name.as_deref() == Some(field_name) || field_name == "*" {
            let content = body[content_start..next_marker].to_vec();
            total_bytes = total_bytes.saturating_add(content.len());
            if parts.len() >= max_parts || total_bytes > max_total_bytes {
                return Vec::new();
            }
            let text = String::from_utf8(content.clone()).ok();
            parts.push(MultipartPart {
                name: part_name.unwrap_or_default(),
                text,
                filename,
                content,
            });
        }

        if next_marker >= body.len() {
            break;
        }
        cursor = if body[next_marker] == b'\r' {
            next_marker + 2
        } else {
            next_marker + 1
        };
        let Some(next_cursor) = find_bytes(body, &delimiter, cursor) else {
            break;
        };
        cursor = next_cursor;
    }

    parts
}

/// Parses bounded named parts for declared multipart actions using the shared parser.
pub(super) fn request_multipart_named_parts(
    content_type: &str,
    body: &[u8],
    max_parts: usize,
    max_bytes: usize,
) -> Vec<(String, Option<String>, Vec<u8>)> {
    multipart_parts_from_body(body, content_type, "*", max_parts, max_bytes)
        .into_iter()
        .map(|part| (part.name, part.filename, part.content))
        .collect()
}

fn multipart_find_part_from_body(
    body: &[u8],
    content_type: &str,
    field_name: &str,
) -> Option<MultipartPart> {
    multipart_parts_from_body(body, content_type, field_name, 1, body.len())
        .into_iter()
        .next()
}

/// Extracts one text field from an in-memory multipart request body.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::request_multipart_field_value`].
/// - `body`: Input consumed by [`crate::runtime::json_commands::request_multipart_field_value`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::request_multipart_field_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_multipart_field_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_multipart_field_value(todo!(), b"", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_multipart_field_value(
    content_type: &str,
    body: &[u8],
    field_name: &str,
) -> Option<String> {
    multipart_find_part_from_body(body, content_type, field_name).and_then(|part| part.text)
}

/// Extracts all uploaded files for one multipart field from an in-memory request body.
pub fn request_multipart_file_parts(
    content_type: &str,
    body: &[u8],
    field_name: &str,
    max_parts: usize,
    max_total_bytes: usize,
) -> Vec<MultipartFilePart> {
    multipart_uploaded_file_parts(
        content_type,
        body,
        field_name,
        max_parts,
        max_total_bytes,
        false,
    )
}

/// Extracts bounded source uploads while preserving legitimate empty source files.
pub fn request_multipart_source_file_parts(
    content_type: &str,
    body: &[u8],
    field_name: &str,
    max_parts: usize,
    max_total_bytes: usize,
) -> Vec<MultipartFilePart> {
    multipart_uploaded_file_parts(
        content_type,
        body,
        field_name,
        max_parts,
        max_total_bytes,
        true,
    )
}

/// Applies filename validation and the caller's empty-file policy to bounded multipart parts.
fn multipart_uploaded_file_parts(
    content_type: &str,
    body: &[u8],
    field_name: &str,
    max_parts: usize,
    max_total_bytes: usize,
    allow_empty: bool,
) -> Vec<MultipartFilePart> {
    multipart_parts_from_body(body, content_type, field_name, max_parts, max_total_bytes)
        .into_iter()
        .filter_map(|part| {
            let filename = part.filename?;
            (!filename.trim().is_empty() && (allow_empty || !part.content.is_empty())).then_some(
                MultipartFilePart {
                    filename,
                    content: part.content,
                },
            )
        })
        .collect()
}

/// Performs request form field value.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::request_form_field_value`].
/// - `form_body`: Input consumed by [`crate::runtime::json_commands::request_form_field_value`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::request_form_field_value`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::request_form_field_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_form_field_value`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_form_field_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_form_field_value(todo!(), "name=value", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_form_field_value(
    content_type: Option<&str>,
    form_body: Option<&str>,
    body_path: Option<&Path>,
    field_name: &str,
) -> Option<String> {
    if field_name.is_empty() {
        return None;
    }
    if content_type.is_some_and(|value| value.starts_with("multipart/form-data")) {
        let body = fs::read(body_path?).ok()?;
        return multipart_find_part_from_body(&body, content_type?, field_name)
            .and_then(|part| part.text);
    }

    let raw_form = if let Some(path) = body_path.filter(|path| path.exists()) {
        fs::read_to_string(path)
            .ok()
            .unwrap_or_else(|| form_body.unwrap_or("").to_owned())
    } else {
        form_body.unwrap_or("").to_owned()
    };
    if content_type.is_some_and(|value| value.starts_with("application/json")) {
        return serde_json::from_str::<Value>(&raw_form)
            .ok()
            .and_then(|value| value.as_object().cloned())
            .and_then(|object| object.get(field_name).cloned())
            .and_then(|value| match value {
                Value::String(value) => Some(value),
                Value::Number(value) => Some(value.to_string()),
                Value::Bool(value) => Some(value.to_string()),
                Value::Null => None,
                _ => None,
            });
    }
    request_query_value(&raw_form, field_name)
}

/// Performs dynamic multipart filename.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_filename`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_filename`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_filename`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_multipart_filename`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_multipart_filename(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_multipart_filename(
    content_type: &str,
    body_path: &Path,
    field_name: &str,
) -> Option<String> {
    multipart_find_part_from_body(&fs::read(body_path).ok()?, content_type, field_name)?.filename
}

/// Performs dynamic multipart extract text.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_extract_text`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_extract_text`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_extract_text`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_multipart_extract_text`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_multipart_extract_text(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_multipart_extract_text(
    content_type: &str,
    body_path: &Path,
    field_name: &str,
) -> Option<String> {
    multipart_find_part_from_body(&fs::read(body_path).ok()?, content_type, field_name)?.text
}

/// Performs dynamic multipart extract file.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_extract_file`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_extract_file`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_extract_file`].
/// - `output_path`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_extract_file`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::dynamic_multipart_extract_file`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_multipart_extract_file(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_multipart_extract_file(
    content_type: &str,
    body_path: &Path,
    field_name: &str,
    output_path: &Path,
) -> i32 {
    if output_path.as_os_str().is_empty() {
        return 64;
    }
    let Some(part) = fs::read(body_path)
        .ok()
        .and_then(|body| multipart_find_part_from_body(&body, content_type, field_name))
    else {
        return 1;
    };
    if part.content.is_empty() {
        return 1;
    }
    super::fs::write_binary_file(output_path, &part.content, 0o640)
        .map(|_| 0)
        .unwrap_or(73)
}

/// Performs request booking options JSON from form.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::request_booking_options_json_from_form`].
/// - `form_body`: Input consumed by [`crate::runtime::json_commands::request_booking_options_json_from_form`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::request_booking_options_json_from_form`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_booking_options_json_from_form`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_booking_options_json_from_form`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_booking_options_json_from_form(todo!(), "name=value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_booking_options_json_from_form(
    content_type: Option<&str>,
    form_body: Option<&str>,
    body_path: Option<&Path>,
) -> Option<String> {
    let count_value =
        request_form_field_value(content_type, form_body, body_path, "booking_option_count")
            .filter(|value| value.chars().all(|ch| ch.is_ascii_digit()))
            .and_then(|value| value.parse::<usize>().ok())
            .map(|value| value.min(64))
            .unwrap_or(0);

    let mut raw_lines = Vec::new();
    if count_value > 0 {
        for index in 1..=count_value {
            let label = request_form_field_value(
                content_type,
                form_body,
                body_path,
                &format!("booking_option_label_{index}"),
            )
            .unwrap_or_default();
            let duration = request_form_field_value(
                content_type,
                form_body,
                body_path,
                &format!("booking_option_duration_{index}"),
            )
            .unwrap_or_default();
            let cost = request_form_field_value(
                content_type,
                form_body,
                body_path,
                &format!("booking_option_cost_{index}"),
            )
            .unwrap_or_default();
            if !(label.is_empty() && duration.is_empty() && cost.is_empty()) {
                raw_lines.push(format!("{label}|{duration}|{cost}"));
            }
        }
    }
    if raw_lines.is_empty()
        && let Some(raw) =
            request_form_field_value(content_type, form_body, body_path, "booking_options")
        && !raw.is_empty()
    {
        raw_lines = raw.lines().map(ToOwned::to_owned).collect();
    }
    if raw_lines.is_empty() {
        return Some("[]".to_owned());
    }

    let mut rows = Vec::new();
    for line in raw_lines {
        let mut parts = line.splitn(3, '|');
        let label = parts.next().unwrap_or_default();
        let duration_text = parts.next().unwrap_or_default();
        let cost = parts.next().unwrap_or_default();
        if label.is_empty() && duration_text.is_empty() && cost.is_empty() {
            continue;
        }
        let duration = if duration_text.chars().all(|ch| ch.is_ascii_digit()) {
            duration_text.parse::<u64>().ok().unwrap_or(0)
        } else {
            0
        };
        rows.push(serde_json::json!({
            "label": label,
            "duration_minutes": duration,
            "cost": cost,
        }));
    }
    serde_json::to_string(&rows).ok()
}

/// Performs request cookie value.
///
/// # Parameters
///
/// - `cookie_header`: Input consumed by [`crate::runtime::json_commands::request_cookie_value`].
/// - `name`: Input consumed by [`crate::runtime::json_commands::request_cookie_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_cookie_value`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_cookie_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_cookie_value("session=abc", "name");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_cookie_value(cookie_header: &str, name: &str) -> Option<String> {
    if name.is_empty() {
        return None;
    }
    for segment in cookie_header.split(';') {
        let (key, value) = segment.trim().split_once('=')?;
        if key.trim() == name {
            return Some(value.trim().to_owned());
        }
    }
    None
}

/// Handles bundle manifest slice order command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_bundle_manifest_slice_order_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_bundle_manifest_slice_order_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_bundle_manifest_slice_order_command(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_bundle_manifest_slice_order_command(path: &Path) -> Option<String> {
    bundle_manifest_slice_order_lines(path).map(|lines| lines.join("\n"))
}

/// Handles bundle manifest layer for slice command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_bundle_manifest_layer_for_slice_command`].
/// - `slice_name`: Input consumed by [`crate::runtime::json_commands::handle_bundle_manifest_layer_for_slice_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_bundle_manifest_layer_for_slice_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_bundle_manifest_layer_for_slice_command(std::path::Path::new("fixture.json"), "slice");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_bundle_manifest_layer_for_slice_command(
    path: &Path,
    slice_name: &str,
) -> Option<String> {
    bundle_manifest_layer_for_slice(path, slice_name).flatten()
}

/// Handles request query value command.
///
/// # Parameters
///
/// - `query`: Input consumed by [`crate::runtime::json_commands::handle_request_query_value_command`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::handle_request_query_value_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_query_value_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_query_value_command("page=1", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_query_value_command(query: &str, key: &str) -> Option<String> {
    request_query_value(query, key)
}

/// Handles request form value command.
///
/// # Parameters
///
/// - `form_body`: Input consumed by [`crate::runtime::json_commands::handle_request_form_value_command`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::handle_request_form_value_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_form_value_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_form_value_command("name=value", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_form_value_command(form_body: &str, key: &str) -> Option<String> {
    request_form_value(form_body, key)
}

/// Handles request form field command.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::handle_request_form_field_command`].
/// - `form_body`: Input consumed by [`crate::runtime::json_commands::handle_request_form_field_command`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::handle_request_form_field_command`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::handle_request_form_field_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_form_field_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_form_field_command(todo!(), "name=value", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_form_field_command(
    content_type: Option<&str>,
    form_body: Option<&str>,
    body_path: Option<&Path>,
    field_name: &str,
) -> Option<String> {
    request_form_field_value(content_type, form_body, body_path, field_name)
}

/// Handles request cookie value command.
///
/// # Parameters
///
/// - `cookie_header`: Input consumed by [`crate::runtime::json_commands::handle_request_cookie_value_command`].
/// - `name`: Input consumed by [`crate::runtime::json_commands::handle_request_cookie_value_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_cookie_value_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_cookie_value_command("session=abc", "name");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_cookie_value_command(cookie_header: &str, name: &str) -> Option<String> {
    request_cookie_value(cookie_header, name)
}

/// Handles dynamic multipart filename command.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_filename_command`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_filename_command`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_filename_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_multipart_filename_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_multipart_filename_command(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_multipart_filename_command(
    content_type: &str,
    body_path: &Path,
    field_name: &str,
) -> Option<String> {
    dynamic_multipart_filename(content_type, body_path, field_name)
}

/// Handles dynamic multipart extract text command.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_extract_text_command`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_extract_text_command`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_extract_text_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_multipart_extract_text_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_multipart_extract_text_command(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_multipart_extract_text_command(
    content_type: &str,
    body_path: &Path,
    field_name: &str,
) -> Option<String> {
    dynamic_multipart_extract_text(content_type, body_path, field_name)
}

/// Handles dynamic multipart extract file command.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_extract_file_command`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_extract_file_command`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_extract_file_command`].
/// - `output_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_multipart_extract_file_command`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::handle_dynamic_multipart_extract_file_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_multipart_extract_file_command(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_multipart_extract_file_command(
    content_type: &str,
    body_path: &Path,
    field_name: &str,
    output_path: &Path,
) -> i32 {
    dynamic_multipart_extract_file(content_type, body_path, field_name, output_path)
}

/// Handles request booking options JSON from form command.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::handle_request_booking_options_json_from_form_command`].
/// - `form_body`: Input consumed by [`crate::runtime::json_commands::handle_request_booking_options_json_from_form_command`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::handle_request_booking_options_json_from_form_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_booking_options_json_from_form_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_booking_options_json_from_form_command(todo!(), "name=value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_booking_options_json_from_form_command(
    content_type: Option<&str>,
    form_body: Option<&str>,
    body_path: Option<&Path>,
) -> Option<String> {
    request_booking_options_json_from_form(content_type, form_body, body_path)
}

/// Handles request compact JSON command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_request_compact_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_compact_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_compact_json_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_compact_json_command(text: &str) -> Option<String> {
    request_compact_json(text)
}

/// Handles request compact object command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_request_compact_object_command`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::handle_request_compact_object_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_compact_object_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_compact_object_command(text: &str) -> String {
    request_compact_object(text)
}

/// Handles request compact object strict command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_request_compact_object_strict_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_compact_object_strict_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_compact_object_strict_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_compact_object_strict_command(text: &str) -> Option<String> {
    request_compact_object_strict(text)
}

/// Handles request field command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_request_field_command`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::handle_request_field_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_field_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_field_command("{}", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_field_command(text: &str, field: &str) -> Option<String> {
    request_field(text, field)
}

/// Handles manifest fixture path raw command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_manifest_fixture_path_raw_command`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::handle_manifest_fixture_path_raw_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_manifest_fixture_path_raw_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_manifest_fixture_path_raw_command(std::path::Path::new("fixture.json"), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_manifest_fixture_path_raw_command(path: &Path, key: &str) -> Option<String> {
    manifest_fixture_path_raw(path, key)
}

/// Handles manifest app root command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_manifest_app_root_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_manifest_app_root_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_manifest_app_root_command(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_manifest_app_root_command(path: &Path) -> Option<String> {
    manifest_app_root(path)
}

/// Finds form field value.
fn find_form_field_value<'a>(root: &'a Value, form_id: &str, field_id: &str) -> Option<&'a Value> {
    let forms = root.get("forms")?.as_array()?;
    for form in forms {
        if json_string(form, "form_id") != Some(form_id) {
            continue;
        }
        let fields = form.get("fields")?.as_array()?;
        for field in fields {
            if json_string(field, "field_id") == Some(field_id) {
                return Some(field);
            }
        }
    }
    None
}

/// Performs form field JSON.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::form_field_json`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::form_field_json`].
/// - `field_id`: Input consumed by [`crate::runtime::json_commands::form_field_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::form_field_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::form_field_json(std::path::Path::new("fixture.json"), "form", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn form_field_json(path: &Path, form_id: &str, field_id: &str) -> Option<String> {
    if form_id.is_empty() || field_id.is_empty() {
        return None;
    }
    let root = read_json_file(path)?;
    serde_json::to_string(find_form_field_value(&root, form_id, field_id)?).ok()
}

/// Performs form field JSON lines.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::form_field_json_lines`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::form_field_json_lines`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::form_field_json_lines`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::form_field_json_lines`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::form_field_json_lines(std::path::Path::new("fixture.json"), "form");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn form_field_json_lines(path: &Path, form_id: &str) -> Option<Vec<String>> {
    if form_id.is_empty() {
        return None;
    }
    let root = read_json_file(path)?;
    let forms = root.get("forms")?.as_array()?;
    for form in forms {
        if json_string(form, "form_id") != Some(form_id) {
            continue;
        }
        let mut lines = Vec::new();
        for field in form.get("fields")?.as_array()? {
            lines.push(serde_json::to_string(field).ok()?);
        }
        return Some(lines);
    }
    Some(Vec::new())
}

/// Performs form options csv.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::form_options_csv`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::form_options_csv`].
/// - `field_id`: Input consumed by [`crate::runtime::json_commands::form_options_csv`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::form_options_csv`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::form_options_csv`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::form_options_csv(std::path::Path::new("fixture.json"), "form", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn form_options_csv(path: &Path, form_id: &str, field_id: &str) -> Option<String> {
    if form_id.is_empty() || field_id.is_empty() {
        return None;
    }
    let root = read_json_file(path)?;
    let field = find_form_field_value(&root, form_id, field_id)?;
    let mut values = Vec::new();
    for option in field.get("options")?.as_array()? {
        if let Some(value) = json_string(option, "value") {
            values.push(value.to_owned());
        }
    }
    Some(values.join(","))
}

/// Performs form options HTML.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::form_options_html`].
/// - `fixture_path`: Input consumed by [`crate::runtime::json_commands::form_options_html`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::form_options_html`].
/// - `field_id`: Input consumed by [`crate::runtime::json_commands::form_options_html`].
/// - `selected`: Input consumed by [`crate::runtime::json_commands::form_options_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::form_options_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::form_options_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::form_options_html(std::path::Path::new("apps/dev_docs"), todo!(), "form", "field", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn form_options_html(
    app_root: &Path,
    fixture_path: &Path,
    form_id: &str,
    field_id: &str,
    selected: Option<&str>,
) -> Option<String> {
    if app_root.as_os_str().is_empty() || form_id.is_empty() || field_id.is_empty() {
        return None;
    }
    let root = read_json_file(fixture_path)?;
    let field = find_form_field_value(&root, form_id, field_id)?;
    let mut out = String::new();
    for option in field.get("options")?.as_array()? {
        let Some(value) = json_string(option, "value") else {
            continue;
        };
        let value = value.to_owned();
        let label = json_string(option, "label")
            .map(ToOwned::to_owned)
            .unwrap_or_else(|| value.clone());
        let params = serde_json::Map::from_iter([
            ("option_value".to_owned(), Value::String(value.to_string())),
            (
                "selected_attr".to_owned(),
                Value::String(
                    if selected == Some(value.as_str()) {
                        " selected"
                    } else {
                        Default::default()
                    }
                    .to_owned(),
                ),
            ),
            ("option_label".to_owned(), Value::String(label.to_string())),
        ]);
        out.push_str(
            &generated::render_generated_admin_fragment_from_value_runtime(
                app_root,
                "templates/shared/fragments/select_option.html",
                &params,
            )?,
        );
    }
    Some(out)
}

/// Handles form field JSON command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_form_field_json_command`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::handle_form_field_json_command`].
/// - `field_id`: Input consumed by [`crate::runtime::json_commands::handle_form_field_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_form_field_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_form_field_json_command(std::path::Path::new("fixture.json"), "form", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_form_field_json_command(
    path: &Path,
    form_id: &str,
    field_id: &str,
) -> Option<String> {
    form_field_json(path, form_id, field_id)
}

/// Handles form field JSON lines command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_form_field_json_lines_command`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::handle_form_field_json_lines_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_form_field_json_lines_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_form_field_json_lines_command(std::path::Path::new("fixture.json"), "form");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_form_field_json_lines_command(path: &Path, form_id: &str) -> Option<String> {
    form_field_json_lines(path, form_id).map(|lines| lines.join("\n"))
}

/// Handles form options csv command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_form_options_csv_command`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::handle_form_options_csv_command`].
/// - `field_id`: Input consumed by [`crate::runtime::json_commands::handle_form_options_csv_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_form_options_csv_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_form_options_csv_command(std::path::Path::new("fixture.json"), "form", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_form_options_csv_command(
    path: &Path,
    form_id: &str,
    field_id: &str,
) -> Option<String> {
    form_options_csv(path, form_id, field_id)
}

/// Handles form options HTML command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_form_options_html_command`].
/// - `fixture_path`: Input consumed by [`crate::runtime::json_commands::handle_form_options_html_command`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::handle_form_options_html_command`].
/// - `field_id`: Input consumed by [`crate::runtime::json_commands::handle_form_options_html_command`].
/// - `selected`: Input consumed by [`crate::runtime::json_commands::handle_form_options_html_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_form_options_html_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_form_options_html_command(std::path::Path::new("apps/dev_docs"), todo!(), "form", "field", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_form_options_html_command(
    app_root: &Path,
    fixture_path: &Path,
    form_id: &str,
    field_id: &str,
    selected: Option<&str>,
) -> Option<String> {
    form_options_html(app_root, fixture_path, form_id, field_id, selected)
}

/// Performs object value at path in value.
fn object_value_at_path_in_value<'a>(root: &'a Value, path: &str) -> Option<&'a Value> {
    if path.is_empty() {
        return None;
    }
    let mut current = root;
    for segment in path.split('.') {
        if segment.is_empty() {
            return None;
        }
        current = current.as_object()?.get(segment)?;
    }
    Some(current)
}

/// Performs object field string.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_field_string`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::object_field_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_field_string`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_field_string`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_field_string("{}", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_field_string(text: &str, field: &str) -> Option<String> {
    if field.is_empty() {
        return None;
    }
    serde_json::from_str::<Value>(text)
        .ok()?
        .as_object()?
        .get(field)?
        .as_str()
        .map(ToOwned::to_owned)
}

/// Performs object field number.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_field_number`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::object_field_number`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_field_number`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_field_number`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_field_number("{}", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_field_number(text: &str, field: &str) -> Option<i64> {
    if field.is_empty() {
        return None;
    }
    Some(
        serde_json::from_str::<Value>(text)
            .ok()?
            .as_object()?
            .get(field)
            .and_then(Value::as_i64)
            .unwrap_or(0),
    )
}

/// Performs object field text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_field_text`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::object_field_text`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_field_text`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_field_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_field_text("{}", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_field_text(text: &str, field: &str) -> Option<String> {
    if field.is_empty() {
        return None;
    }
    let value = serde_json::from_str::<Value>(text)
        .ok()?
        .as_object()?
        .get(field)?
        .clone();
    (!value.is_null()).then(|| match value {
        Value::String(text) => text,
        other => serde_json::to_string(&other).unwrap_or_default(),
    })
}

/// Performs object array length.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_array_length`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_array_length`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_array_length`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_array_length("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_array_length(text: &str) -> Option<usize> {
    Some(
        serde_json::from_str::<Value>(text)
            .ok()?
            .as_array()
            .map(Vec::len)
            .unwrap_or(0),
    )
}

/// Performs object array all integers.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_array_all_integers`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_array_all_integers`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_array_all_integers`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_array_all_integers("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_array_all_integers(text: &str) -> Option<bool> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    let Some(items) = root.as_array() else {
        return Some(false);
    };
    Some(
        items
            .iter()
            .all(|item| item.as_i64().is_some() || item.as_u64().is_some()),
    )
}

/// Performs object path JSON.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_path_json`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::object_path_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_path_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_path_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_path_json("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_path_json(text: &str, path: &str) -> Option<String> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    let Some(value) = object_value_at_path_in_value(&root, path) else {
        return Some("null".to_owned());
    };
    serde_json::to_string(value).ok()
}

/// Performs object path string.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_path_string`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::object_path_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_path_string`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_path_string`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_path_string("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_path_string(text: &str, path: &str) -> Option<String> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    object_value_at_path_in_value(&root, path)?
        .as_str()
        .map(ToOwned::to_owned)
}

/// Performs object path number.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_path_number`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::object_path_number`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_path_number`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_path_number`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_path_number("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_path_number(text: &str, path: &str) -> Option<i64> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    Some(
        object_value_at_path_in_value(&root, path)
            .and_then(Value::as_i64)
            .unwrap_or(0),
    )
}

/// Performs object path bool.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_path_bool`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::object_path_bool`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_path_bool`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_path_bool`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_path_bool("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_path_bool(text: &str, path: &str) -> Option<bool> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    Some(
        object_value_at_path_in_value(&root, path)
            .and_then(Value::as_bool)
            .unwrap_or(false),
    )
}

/// Handles object field string command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_field_string_command`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::handle_object_field_string_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_field_string_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_field_string_command("{}", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_field_string_command(text: &str, field: &str) -> Option<String> {
    object_field_string(text, field)
}

/// Handles object field number command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_field_number_command`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::handle_object_field_number_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_field_number_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_field_number_command("{}", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_field_number_command(text: &str, field: &str) -> Option<i64> {
    object_field_number(text, field)
}

/// Handles object field text command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_field_text_command`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::handle_object_field_text_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_field_text_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_field_text_command("{}", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_field_text_command(text: &str, field: &str) -> Option<String> {
    object_field_text(text, field)
}

/// Handles object array length command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_array_length_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_array_length_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_array_length_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_array_length_command(text: &str) -> Option<usize> {
    object_array_length(text)
}

/// Handles object array all integers command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_array_all_integers_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_array_all_integers_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_array_all_integers_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_array_all_integers_command(text: &str) -> Option<bool> {
    object_array_all_integers(text)
}

/// Handles object path JSON command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_path_json_command`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_object_path_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_path_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_path_json_command("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_path_json_command(text: &str, path: &str) -> Option<String> {
    object_path_json(text, path)
}

/// Handles object path string command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_path_string_command`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_object_path_string_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_path_string_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_path_string_command("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_path_string_command(text: &str, path: &str) -> Option<String> {
    object_path_string(text, path)
}

/// Handles object path number command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_path_number_command`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_object_path_number_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_path_number_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_path_number_command("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_path_number_command(text: &str, path: &str) -> Option<i64> {
    object_path_number(text, path)
}

/// Handles object path bool command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_path_bool_command`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_object_path_bool_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_path_bool_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_path_bool_command("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_path_bool_command(text: &str, path: &str) -> Option<bool> {
    object_path_bool(text, path)
}

/// Performs object path array length.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_path_array_length`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::object_path_array_length`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_path_array_length`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_path_array_length`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_path_array_length("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_path_array_length(text: &str, path: &str) -> Option<usize> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    Some(
        object_value_at_path_in_value(&root, path)
            .and_then(Value::as_array)
            .map(Vec::len)
            .unwrap_or(0),
    )
}

/// Performs object array item JSON lines.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_array_item_json_lines`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_array_item_json_lines`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_array_item_json_lines`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_array_item_json_lines("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_array_item_json_lines(text: &str) -> Option<Vec<String>> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    let mut lines = Vec::new();
    for item in root.as_array()? {
        lines.push(serde_json::to_string(item).ok()?);
    }
    Some(lines)
}

/// Performs object array lines.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_array_lines`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_array_lines`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_array_lines`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_array_lines("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_array_lines(text: &str) -> Option<Vec<String>> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    let mut lines = Vec::new();
    for item in root.as_array()? {
        match item {
            Value::String(text) => lines.push(text.clone()),
            other => lines.push(serde_json::to_string(other).ok()?),
        }
    }
    Some(lines)
}

/// Performs object relative path array to absolute JSON.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_relative_path_array_to_absolute_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::object_relative_path_array_to_absolute_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_relative_path_array_to_absolute_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_relative_path_array_to_absolute_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_relative_path_array_to_absolute_json("{}", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_relative_path_array_to_absolute_json(text: &str, app_root: &Path) -> Option<String> {
    if app_root.as_os_str().is_empty() {
        return None;
    }
    let root = serde_json::from_str::<Value>(text).ok()?;
    let Some(items) = root.as_array() else {
        return Some("[]".to_owned());
    };
    let absolute: Vec<Value> = items
        .iter()
        .filter_map(|item| item.as_str())
        .map(|value| {
            if value.starts_with('/') {
                Value::String(value.to_owned())
            } else {
                Value::String(app_root.join(value).to_string_lossy().into_owned())
            }
        })
        .collect();
    serde_json::to_string(&absolute).ok()
}

/// Handles object path array length command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_path_array_length_command`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_object_path_array_length_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_path_array_length_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_path_array_length_command("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_path_array_length_command(text: &str, path: &str) -> Option<usize> {
    object_path_array_length(text, path)
}

/// Handles object array item JSON lines command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_array_item_json_lines_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_array_item_json_lines_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_array_item_json_lines_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_array_item_json_lines_command(text: &str) -> Option<String> {
    object_array_item_json_lines(text).map(|lines| lines.join("\n"))
}

/// Handles object array lines command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_array_lines_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_array_lines_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_array_lines_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_array_lines_command(text: &str) -> Option<String> {
    object_array_lines(text).map(|lines| lines.join("\n"))
}

/// Handles object relative path array to absolute JSON command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_object_relative_path_array_to_absolute_json_command`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_object_relative_path_array_to_absolute_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_relative_path_array_to_absolute_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_relative_path_array_to_absolute_json_command("{}", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_relative_path_array_to_absolute_json_command(
    text: &str,
    app_root: &Path,
) -> Option<String> {
    object_relative_path_array_to_absolute_json(text, app_root)
}

/// Performs file compact object.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::file_compact_object`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::file_compact_object`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::file_compact_object(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn file_compact_object(path: &Path) -> Option<String> {
    let root = read_json_file(path)?;
    if !root.is_object() {
        return Some("{}".to_owned());
    }
    serde_json::to_string(&root).ok()
}

/// Performs file field string.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::file_field_string`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::file_field_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::file_field_string`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::file_field_string(std::path::Path::new("fixture.json"), "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn file_field_string(path: &Path, field: &str) -> Option<String> {
    if field.is_empty() {
        return None;
    }
    read_json_file(path)?
        .as_object()?
        .get(field)?
        .as_str()
        .map(ToOwned::to_owned)
}

/// Performs file field number.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::file_field_number`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::file_field_number`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::file_field_number`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::file_field_number(std::path::Path::new("fixture.json"), "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn file_field_number(path: &Path, field: &str) -> Option<i64> {
    if field.is_empty() {
        return None;
    }
    Some(
        read_json_file(path)?
            .as_object()?
            .get(field)
            .and_then(Value::as_i64)
            .unwrap_or(0),
    )
}

/// Performs file section length.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::file_section_length`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::file_section_length`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::file_section_length`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::file_section_length(std::path::Path::new("fixture.json"), "items");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn file_section_length(path: &Path, section: &str) -> Option<usize> {
    if section.is_empty() {
        return None;
    }
    Some(
        read_json_file(path)?
            .as_object()?
            .get(section)
            .and_then(Value::as_array)
            .map(Vec::len)
            .unwrap_or(0),
    )
}

/// Handles file compact object command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_file_compact_object_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_file_compact_object_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_file_compact_object_command(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_file_compact_object_command(path: &Path) -> Option<String> {
    file_compact_object(path)
}

/// Handles file field string command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_file_field_string_command`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::handle_file_field_string_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_file_field_string_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_file_field_string_command(std::path::Path::new("fixture.json"), "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_file_field_string_command(path: &Path, field: &str) -> Option<String> {
    file_field_string(path, field)
}

/// Handles file field number command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_file_field_number_command`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::handle_file_field_number_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_file_field_number_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_file_field_number_command(std::path::Path::new("fixture.json"), "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_file_field_number_command(path: &Path, field: &str) -> Option<i64> {
    file_field_number(path, field)
}

/// Handles file section length command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_file_section_length_command`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::handle_file_section_length_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_file_section_length_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_file_section_length_command(std::path::Path::new("fixture.json"), "items");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_file_section_length_command(path: &Path, section: &str) -> Option<usize> {
    file_section_length(path, section)
}

/// Performs manifest database contract path.
///
/// # Parameters
///
/// - `app_root`: Application root whose manifest-owned database contract path is being resolved.
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::manifest_database_contract_path`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::manifest_database_contract_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::manifest_database_contract_path(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub(crate) fn manifest_database_contract_path(app_root: &Path) -> Option<String> {
    let manifest_path = if app_root.join("pharos.app.json").exists() {
        app_root.join("pharos.app.json")
    } else {
        app_root.join("pharos.app.yml")
    };
    let manifest = read_json_or_yaml_file(&manifest_path)?;
    manifest
        .get("database")?
        .get("migration_contract")?
        .as_str()
        .filter(|path| !path.trim().is_empty())
        .map(ToOwned::to_owned)
}

/// Declared database ownership never falls back to file state after a resolution failure.
pub(crate) fn manifest_declares_database(app_root: &Path) -> bool {
    let manifest_path = if app_root.join("pharos.app.yml").exists() {
        app_root.join("pharos.app.yml")
    } else {
        app_root.join("pharos.app.json")
    };
    manifest_path.exists()
        && read_json_or_yaml_file(&manifest_path)
            .is_none_or(|manifest| manifest.get("database").is_some())
}

/// Performs relational runtime authority enabled.
fn relational_runtime_authority_enabled(app_root: &Path) -> bool {
    super::database::relational_runtime_authority_enabled(app_root)
}

/// Performs dynamic config value.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_config_value`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::dynamic_config_value`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::dynamic_config_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_config_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_config_value(std::path::Path::new("apps/dev_docs"), todo!(), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_config_value(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    key: &str,
) -> Option<String> {
    super::cache::dynamic_config_allowlist_value(app_root, runtime_conf_path, key)
}

/// Performs dynamic safe upload filename.
///
/// # Parameters
///
/// - `raw_name`: Input consumed by [`crate::runtime::json_commands::dynamic_safe_upload_filename`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_safe_upload_filename`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_safe_upload_filename`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_safe_upload_filename(Some("file.txt"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_safe_upload_filename(raw_name: Option<&str>) -> Option<String> {
    let mut base_name = raw_name.unwrap_or("");
    if let Some(index) = base_name.rfind(['/', '\\']) {
        base_name = &base_name[index + 1..];
    }
    let mut safe_name = String::with_capacity(base_name.len());
    for ch in base_name.chars() {
        if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '_' | '-') {
            safe_name.push(ch);
        } else {
            safe_name.push('_');
        }
    }
    let safe_name = safe_name
        .trim_start_matches(['_', '.', '-'])
        .trim_end_matches(['_', '.', '-'])
        .to_owned();
    Some(safe_name)
}

/// Performs dynamic media disk path.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::json_commands::dynamic_media_disk_path`].
/// - `media_url`: Input consumed by [`crate::runtime::json_commands::dynamic_media_disk_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_media_disk_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_media_disk_path(std::path::Path::new("build/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_media_disk_path(artifact_dir: &Path, media_url: &str) -> Option<String> {
    if artifact_dir.as_os_str().is_empty()
        || !media_url.starts_with("/media/")
        || media_url[7..]
            .split('/')
            .any(|part| part.is_empty() || part == ".." || part.contains(['\\', '\0']))
    {
        return None;
    }
    Some(
        super::config::app_media_root(artifact_dir)?
            .join(&media_url[7..])
            .to_string_lossy()
            .into_owned(),
    )
}

/// Performs dynamic ensure business media tree.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::json_commands::dynamic_ensure_business_media_tree`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_ensure_business_media_tree`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::dynamic_ensure_business_media_tree`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_ensure_business_media_tree`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_ensure_business_media_tree(std::path::Path::new("build/dev_docs"), "demo");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_ensure_business_media_tree(artifact_dir: &Path, business_slug: &str) -> i32 {
    if artifact_dir.as_os_str().is_empty() || business_slug.is_empty() {
        return 64;
    }
    let Some(policy_root) = super::declarative::declarative_source_load_fixture(
        artifact_dir,
        "data/contracts/media-policy",
    ) else {
        return 69;
    };
    let Some(entries) = policy_root.get("media_subtrees").and_then(Value::as_array) else {
        return 69;
    };
    let Some(entry) = entries.iter().find(|entry| {
        entry
            .get("entity_type")
            .and_then(Value::as_str)
            .is_some_and(|value| value == "business")
    }) else {
        return 0;
    };
    let Some(base_template) = entry.get("base_path_template").and_then(Value::as_str) else {
        return 64;
    };
    let base_path = base_template.replace("{slug}", business_slug);
    let Some(media_root) = super::config::app_media_root(artifact_dir) else {
        return 64;
    };
    let Some(relative) = base_path.strip_prefix("media/") else {
        return 64;
    };
    let base_path = media_root.join(relative);
    if fs::create_dir_all(&base_path).is_err() {
        return 69;
    }
    if let Some(subdirs) = entry.get("subdirectories").and_then(Value::as_array) {
        for subdir in subdirs.iter().filter_map(Value::as_str) {
            if fs::create_dir_all(base_path.join(subdir)).is_err() {
                return 69;
            }
        }
    }
    0
}

/// Performs dynamic remove business media URL file.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::json_commands::dynamic_remove_business_media_url_file`].
/// - `media_url`: Input consumed by [`crate::runtime::json_commands::dynamic_remove_business_media_url_file`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::dynamic_remove_business_media_url_file`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_remove_business_media_url_file(std::path::Path::new("build/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_remove_business_media_url_file(artifact_dir: &Path, media_url: &str) -> i32 {
    if artifact_dir.as_os_str().is_empty() || !media_url.starts_with("/media/businesses/") {
        return 0;
    }
    if let Some(disk_path) = dynamic_media_disk_path(artifact_dir, media_url) {
        let path = Path::new(&disk_path);
        if path.exists() {
            let _ = fs::remove_file(path);
        }
    }
    0
}

/// Performs dynamic store uploaded media.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media`].
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media`].
/// - `target_url_dir`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media`].
/// - `fallback_filename`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_store_uploaded_media`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_store_uploaded_media(std::path::Path::new("build/dev_docs"), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_store_uploaded_media(
    artifact_dir: &Path,
    content_type: &str,
    body_path: &Path,
    field_name: &str,
    target_url_dir: &str,
    fallback_filename: Option<&str>,
) -> Option<String> {
    dynamic_store_uploaded_media_bytes(
        artifact_dir,
        content_type,
        &fs::read(body_path).ok()?,
        field_name,
        target_url_dir,
        fallback_filename,
    )
}

/// Stores one uploaded media part from an in-memory multipart body.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media_from_body`].
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media_from_body`].
/// - `body`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media_from_body`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media_from_body`].
/// - `target_url_dir`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media_from_body`].
/// - `fallback_filename`: Input consumed by [`crate::runtime::json_commands::dynamic_store_uploaded_media_from_body`].
///
/// # Returns
///
/// Returns [`Some`] when one non-empty media part was stored and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_store_uploaded_media_from_body(std::path::Path::new("build/dev_docs"), todo!(), b"", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_store_uploaded_media_from_body(
    artifact_dir: &Path,
    content_type: &str,
    body: &[u8],
    field_name: &str,
    target_url_dir: &str,
    fallback_filename: Option<&str>,
) -> Option<String> {
    dynamic_store_uploaded_media_bytes(
        artifact_dir,
        content_type,
        body,
        field_name,
        target_url_dir,
        fallback_filename,
    )
}

/// Performs dynamic store uploaded media bytes.
fn dynamic_store_uploaded_media_bytes(
    artifact_dir: &Path,
    content_type: &str,
    body: &[u8],
    field_name: &str,
    target_url_dir: &str,
    fallback_filename: Option<&str>,
) -> Option<String> {
    if artifact_dir.as_os_str().is_empty()
        || content_type.is_empty()
        || field_name.is_empty()
        || target_url_dir.is_empty()
    {
        return None;
    }
    let part = multipart_find_part_from_body(body, content_type, field_name)?;
    if part.content.is_empty() {
        return None;
    }
    let mut safe_filename = dynamic_safe_upload_filename(part.filename.as_deref())?;
    if safe_filename.is_empty() {
        safe_filename = dynamic_safe_upload_filename(fallback_filename)?.to_owned();
    }
    if safe_filename.is_empty() {
        return None;
    }
    let target_dir = artifact_dir.join(target_url_dir.trim_start_matches('/'));
    fs::create_dir_all(&target_dir).ok()?;
    super::fs::write_file_within(
        artifact_dir,
        &target_dir.join(&safe_filename),
        &part.content,
        0o640,
    )
    .ok()?;
    Some(format!("{target_url_dir}/{safe_filename}"))
}

/// Handles dynamic config value command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_config_value_command`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_config_value_command`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_config_value_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_config_value_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_config_value_command(std::path::Path::new("apps/dev_docs"), todo!(), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_config_value_command(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    key: &str,
) -> Option<String> {
    dynamic_config_value(app_root, runtime_conf_path, key)
}

/// Handles dynamic relational backend command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_backend_command`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_backend_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_relational_backend_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_relational_backend_command(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_relational_backend_command(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
) -> Option<String> {
    dynamic_relational_backend(app_root, runtime_conf_path)
}

/// Handles dynamic safe upload filename command.
///
/// # Parameters
///
/// - `raw_name`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_safe_upload_filename_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_safe_upload_filename_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_safe_upload_filename_command(Some("file.txt"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_safe_upload_filename_command(raw_name: Option<&str>) -> Option<String> {
    dynamic_safe_upload_filename(raw_name)
}

/// Handles dynamic media disk path command.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_media_disk_path_command`].
/// - `media_url`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_media_disk_path_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_media_disk_path_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_media_disk_path_command(std::path::Path::new("build/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_media_disk_path_command(
    artifact_dir: &Path,
    media_url: &str,
) -> Option<String> {
    dynamic_media_disk_path(artifact_dir, media_url)
}

/// Handles dynamic ensure business media tree command.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_ensure_business_media_tree_command`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_ensure_business_media_tree_command`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::handle_dynamic_ensure_business_media_tree_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_ensure_business_media_tree_command(std::path::Path::new("build/dev_docs"), "demo");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_ensure_business_media_tree_command(
    artifact_dir: &Path,
    business_slug: &str,
) -> i32 {
    dynamic_ensure_business_media_tree(artifact_dir, business_slug)
}

/// Handles dynamic remove media URL file command.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_remove_media_url_file_command`].
/// - `media_url`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_remove_media_url_file_command`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::handle_dynamic_remove_media_url_file_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_remove_media_url_file_command(std::path::Path::new("build/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_remove_media_url_file_command(artifact_dir: &Path, media_url: &str) -> i32 {
    dynamic_remove_business_media_url_file(artifact_dir, media_url)
}

/// Handles dynamic store uploaded media command.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_store_uploaded_media_command`].
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_store_uploaded_media_command`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_store_uploaded_media_command`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_store_uploaded_media_command`].
/// - `target_url_dir`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_store_uploaded_media_command`].
/// - `fallback_filename`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_store_uploaded_media_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_store_uploaded_media_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_store_uploaded_media_command(std::path::Path::new("build/dev_docs"), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_store_uploaded_media_command(
    artifact_dir: &Path,
    content_type: &str,
    body_path: &Path,
    field_name: &str,
    target_url_dir: &str,
    fallback_filename: Option<&str>,
) -> Option<String> {
    dynamic_store_uploaded_media(
        artifact_dir,
        content_type,
        body_path,
        field_name,
        target_url_dir,
        fallback_filename,
    )
}

/// Returns whether safe SQL identifier.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::is_safe_sql_identifier`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::is_safe_sql_identifier`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::is_safe_sql_identifier`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::is_safe_sql_identifier("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn is_safe_sql_identifier(text: &str) -> bool {
    !text.is_empty()
        && text
            .chars()
            .all(|ch| ch.is_ascii_alphanumeric() || ch == '_')
}

/// Computes a SHA-256 checksum without invoking a host utility.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::checksum_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::checksum_string`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::checksum_string("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn checksum_string(value: &str) -> Option<String> {
    Some(migration_sha256_text(value))
}

/// Performs dynamic file signature.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::dynamic_file_signature`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_file_signature`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_file_signature`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_file_signature(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_file_signature(path: &Path) -> Option<String> {
    if path.as_os_str().is_empty() {
        return None;
    }
    if !path.exists() {
        return Some("missing".to_owned());
    }
    let bytes = fs::read(path).ok()?;
    let mut hash = 1469598103934665603u64;
    for value in &bytes {
        hash ^= u64::from(*value);
        hash = hash.wrapping_mul(1099511628211);
    }
    Some(format!("{hash:016x}:{}", bytes.len()))
}

/// Handles dynamic file signature command.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_file_signature_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_file_signature_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_file_signature_command(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_file_signature_command(path: &Path) -> Option<String> {
    dynamic_file_signature(path)
}

/// Reports declared, applied, interrupted, and live-schema migration drift.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_migration_drift_report`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::dynamic_migration_drift_report`].
/// - `app_id`: Input consumed by [`crate::runtime::json_commands::dynamic_migration_drift_report`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_migration_drift_report`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_migration_drift_report(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_migration_drift_report(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    app_id: Option<&str>,
) -> Option<Value> {
    super::database::dynamic_migration_drift_report(app_root, runtime_conf_path, app_id)
}

/// Handles dynamic relational runtime export JSON command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_export_json_command`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_export_json_command`].
/// - `app_id`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_export_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_relational_runtime_export_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_relational_runtime_export_json_command(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_relational_runtime_export_json_command(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    app_id: Option<&str>,
) -> Option<String> {
    dynamic_relational_runtime_export_json(app_root, runtime_conf_path, app_id)
}

/// Handles dynamic relational runtime audit count command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_audit_count_command`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_audit_count_command`].
/// - `app_id`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_audit_count_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_dynamic_relational_runtime_audit_count_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_relational_runtime_audit_count_command(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_relational_runtime_audit_count_command(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    app_id: Option<&str>,
) -> Option<String> {
    dynamic_relational_runtime_audit_count(app_root, runtime_conf_path, app_id)
}

/// Handles dynamic relational runtime import state command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_import_state_command`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_import_state_command`].
/// - `app_id`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_import_state_command`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_import_state_command`].
/// - `expected_audit_count`: Input consumed by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_import_state_command`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::handle_dynamic_relational_runtime_import_state_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_dynamic_relational_runtime_import_state_command(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_dynamic_relational_runtime_import_state_command(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    app_id: Option<&str>,
    state_path: &Path,
    expected_audit_count: Option<&str>,
) -> i32 {
    dynamic_relational_runtime_import_state(
        app_root,
        runtime_conf_path,
        app_id,
        state_path,
        expected_audit_count,
    )
}

/// Performs file normalize runtime state.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::file_normalize_runtime_state`].
/// - `schema_value`: Input consumed by [`crate::runtime::json_commands::file_normalize_runtime_state`].
/// - `sections_csv`: Input consumed by [`crate::runtime::json_commands::file_normalize_runtime_state`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::file_normalize_runtime_state`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::file_normalize_runtime_state`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::file_normalize_runtime_state(std::path::Path::new("fixture.json"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn file_normalize_runtime_state(
    path: &Path,
    schema_value: Option<&str>,
    sections_csv: Option<&str>,
) -> Option<String> {
    if path.as_os_str().is_empty() {
        return None;
    }
    let mut root = read_json_file(path)?;
    let object = root.as_object_mut()?;
    if let Some(schema_value) = schema_value.filter(|value| !value.is_empty())
        && !object.contains_key("schema")
    {
        object.insert("schema".to_owned(), Value::String(schema_value.to_owned()));
    }
    if let Some(sections_csv) = sections_csv.filter(|value| !value.is_empty()) {
        for token in sections_csv.split(',') {
            let key = token.trim();
            if !key.is_empty() && !object.contains_key(key) {
                object.insert(key.to_owned(), Value::Array(Vec::new()));
            }
        }
    }
    serde_json::to_string(&root).ok()
}

/// Performs request checkbox ID array JSON.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::request_checkbox_id_array_json`].
/// - `prefix`: Input consumed by [`crate::runtime::json_commands::request_checkbox_id_array_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_checkbox_id_array_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_checkbox_id_array_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_checkbox_id_array_json("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_checkbox_id_array_json(text: &str, prefix: &str) -> Option<String> {
    if prefix.is_empty() {
        return None;
    }
    let mut values: Vec<i64> = Vec::new();
    for pair in text.split('&') {
        let Some((key, value)) = pair.split_once('=') else {
            continue;
        };
        if !key.starts_with(prefix) || value.is_empty() {
            continue;
        }
        let suffix = &key[prefix.len()..];
        if suffix.is_empty() || !suffix.chars().all(|ch| ch.is_ascii_digit()) {
            continue;
        }
        let Some(parsed) = value.parse::<i64>().ok() else {
            continue;
        };
        if !values.contains(&parsed) && values.len() < 512 {
            values.push(parsed);
        }
    }
    serde_json::to_string(&values).ok()
}

/// Performs request lines to booking options JSON.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::request_lines_to_booking_options_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::request_lines_to_booking_options_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::request_lines_to_booking_options_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::request_lines_to_booking_options_json("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn request_lines_to_booking_options_json(text: &str) -> Option<String> {
    let mut rows = Vec::new();
    for line in text.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }
        let mut parts = trimmed.splitn(3, '|');
        let label = parts.next().unwrap_or_default().trim();
        let duration_text = parts.next().unwrap_or_default().trim();
        let cost = parts.next().unwrap_or_default().trim();
        if label.is_empty() && duration_text.is_empty() && cost.is_empty() {
            continue;
        }
        let duration =
            if !duration_text.is_empty() && duration_text.chars().all(|ch| ch.is_ascii_digit()) {
                duration_text.parse::<u64>().ok().unwrap_or(0)
            } else {
                0
            };
        rows.push(serde_json::json!({
            "label": label,
            "duration_minutes": duration,
            "cost": cost,
        }));
    }
    serde_json::to_string(&rows).ok()
}

/// Handles request checkbox ID array JSON command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_request_checkbox_id_array_json_command`].
/// - `prefix`: Input consumed by [`crate::runtime::json_commands::handle_request_checkbox_id_array_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_checkbox_id_array_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_checkbox_id_array_json_command("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_checkbox_id_array_json_command(text: &str, prefix: &str) -> Option<String> {
    request_checkbox_id_array_json(text, prefix)
}

/// Handles request lines to booking options JSON command.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::handle_request_lines_to_booking_options_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_request_lines_to_booking_options_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_request_lines_to_booking_options_json_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_request_lines_to_booking_options_json_command(text: &str) -> Option<String> {
    request_lines_to_booking_options_json(text)
}

/// Handles object merge command.
///
/// # Parameters
///
/// - `base_json`: Input consumed by [`crate::runtime::json_commands::handle_object_merge_command`].
/// - `overlay_json`: Input consumed by [`crate::runtime::json_commands::handle_object_merge_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_merge_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_merge_command("{}", "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_merge_command(base_json: &str, overlay_json: &str) -> Option<String> {
    object_merge(base_json, overlay_json)
}

/// Handles object build command.
///
/// # Parameters
///
/// - `ops`: Input consumed by [`crate::runtime::json_commands::handle_object_build_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_object_build_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_object_build_command(&[]);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_object_build_command(ops: &[ObjectBuildOp]) -> Option<String> {
    object_build(ops)
}

/// Performs object merge.
///
/// # Parameters
///
/// - `base_json`: Input consumed by [`crate::runtime::json_commands::object_merge`].
/// - `overlay_json`: Input consumed by [`crate::runtime::json_commands::object_merge`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_merge`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_merge`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_merge("{}", "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_merge(base_json: &str, overlay_json: &str) -> Option<String> {
    let mut base = serde_json::from_str::<Value>(base_json).ok()?;
    let overlay = serde_json::from_str::<Value>(overlay_json).ok()?;
    let base_obj = base.as_object_mut()?;
    let overlay_obj = overlay.as_object()?;
    for (key, value) in overlay_obj {
        base_obj.insert(key.clone(), value.clone());
    }
    serde_json::to_string(&base).ok()
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Public enum `ObjectBuildOp` used by the runtime JSON-command surface.
///
/// # Variants
///
/// - `String`: Supported `ObjectBuildOp` variant.
/// - `Number`: Supported `ObjectBuildOp` variant.
/// - `Bool`: Supported `ObjectBuildOp` variant.
/// - `Null`: Supported `ObjectBuildOp` variant.
/// - `Json`: Supported `ObjectBuildOp` variant.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::json_commands::ObjectBuildOp::String("title".to_owned(), "Example".to_owned());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for constructors, helpers, and neighboring runtime types.
pub enum ObjectBuildOp {
    String(String, String),
    Number(String, i64),
    Bool(String, bool),
    Null(String),
    Json(String, String),
}

/// Performs object build.
///
/// # Parameters
///
/// - `ops`: Input consumed by [`crate::runtime::json_commands::object_build`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_build`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_build`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_build(&[]);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_build(ops: &[ObjectBuildOp]) -> Option<String> {
    let mut object = serde_json::Map::new();
    for op in ops {
        match op {
            ObjectBuildOp::String(key, value) => {
                object.insert(key.clone(), Value::String(value.clone()));
            }
            ObjectBuildOp::Number(key, value) => {
                object.insert(key.clone(), serde_json::json!(*value));
            }
            ObjectBuildOp::Bool(key, value) => {
                object.insert(key.clone(), serde_json::json!(*value));
            }
            ObjectBuildOp::Null(key) => {
                object.insert(key.clone(), Value::Null);
            }
            ObjectBuildOp::Json(key, value) => {
                object.insert(key.clone(), serde_json::from_str::<Value>(value).ok()?);
            }
        }
    }
    serde_json::to_string(&Value::Object(object)).ok()
}

/// Performs template reference contains unsafe char.
fn template_reference_contains_unsafe_char(text: &str) -> bool {
    text.bytes().any(|ch| ch < 0x20 || ch == 0x7f)
}

/// Performs template reference has scheme.
fn template_reference_has_scheme(text: &str) -> bool {
    let mut chars = text.chars();
    let Some(first) = chars.next() else {
        return false;
    };
    if !first.is_ascii_alphabetic() {
        return false;
    }
    for ch in chars {
        if ch == ':' {
            return true;
        }
        if !(ch.is_ascii_alphanumeric() || matches!(ch, '+' | '-' | '.')) {
            return false;
        }
    }
    false
}

/// Performs template path reference allowed.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::template_path_reference_allowed`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::template_path_reference_allowed`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_path_reference_allowed("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_path_reference_allowed(text: &str) -> bool {
    if text.is_empty() {
        return true;
    }
    !template_reference_contains_unsafe_char(text) && !template_reference_has_scheme(text)
}

/// Performs template URL reference allowed.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::template_url_reference_allowed`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::template_url_reference_allowed`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_url_reference_allowed("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_url_reference_allowed(text: &str) -> bool {
    if text.is_empty() {
        return true;
    }
    if template_reference_contains_unsafe_char(text) {
        return false;
    }
    if text.starts_with("https://")
        || text.starts_with("http://")
        || text.starts_with("mailto:")
        || text.starts_with("tel:")
    {
        return true;
    }
    !template_reference_has_scheme(text)
}

/// Performs join base relative path.
///
/// # Parameters
///
/// - `base_path`: Input consumed by [`crate::runtime::json_commands::join_base_relative_path`].
/// - `relative_path`: Input consumed by [`crate::runtime::json_commands::join_base_relative_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::join_base_relative_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::join_base_relative_path("/app", "page");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn join_base_relative_path(base_path: &str, relative_path: &str) -> Option<String> {
    if base_path.is_empty() || relative_path.is_empty() {
        return None;
    }
    Some(format!("{base_path}/{relative_path}"))
}

/// Renders file template.
///
/// # Parameters
///
/// - `template_file`: Input consumed by [`crate::runtime::json_commands::render_file_template`].
/// - `params_root`: Input consumed by [`crate::runtime::json_commands::render_file_template`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_file_template`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::render_file_template`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_file_template(std::path::Path::new("template.html"), &serde_json::json!({}));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_file_template(template_file: &Path, params_root: &Value) -> Option<String> {
    if template_file.as_os_str().is_empty() || !params_root.is_object() {
        return None;
    }
    let text = fs::read_to_string(template_file).ok()?;
    let text = if text.contains("{include:") {
        let root = template_file
            .ancestors()
            .find(|path| path.file_name().is_some_and(|name| name == "templates"))?
            .canonicalize()
            .ok()?;
        expand_template_includes(&root, &text, 0, &mut 64)?
    } else {
        text
    };
    render_template_text_with_default_kind(&text, params_root, "text")
}

/// Expands app-owned HTML fragments before binding values, with bounded depth,
/// reads and output. Canonical paths must stay within the templates directory.
fn expand_template_includes(
    root: &Path,
    text: &str,
    depth: usize,
    remaining: &mut usize,
) -> Option<String> {
    const LIMIT: usize = 1024 * 1024;
    if depth > 16 || text.len() > LIMIT {
        return None;
    }
    let mut output = String::new();
    let mut cursor = 0;
    while let Some(offset) = text[cursor..].find("{include:") {
        let start = cursor + offset;
        let path_start = start + "{include:".len();
        let end = text[path_start..].find('}')? + path_start;
        let relative = Path::new(&text[path_start..end]);
        if !relative
            .components()
            .all(|part| matches!(part, std::path::Component::Normal(_)))
            || relative.extension().is_none_or(|ext| ext != "html")
        {
            return None;
        }
        *remaining = remaining.checked_sub(1)?;
        let path = root.join(relative).canonicalize().ok()?;
        if !path.starts_with(root) || fs::metadata(&path).ok()?.len() > LIMIT as u64 {
            return None;
        }
        let child =
            expand_template_includes(root, &fs::read_to_string(path).ok()?, depth + 1, remaining)?;
        if output
            .len()
            .checked_add(start - cursor)?
            .checked_add(child.len())?
            > LIMIT
        {
            return None;
        }
        output.push_str(&text[cursor..start]);
        output.push_str(&child);
        cursor = end + 1;
    }
    if output.len().checked_add(text.len() - cursor)? > LIMIT {
        return None;
    }
    output.push_str(&text[cursor..]);
    Some(output)
}

/// Performs HTML escape text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::html_escape_text`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::html_escape_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::html_escape_text("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn html_escape_text(text: &str) -> String {
    text.replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
        .replace('"', "&quot;")
        .replace('\'', "&#39;")
}

/// Performs YAML to JSON value.
fn yaml_to_json_value(value: &saphyr::Yaml<'_>) -> Option<Value> {
    match value {
        saphyr::Yaml::BadValue | saphyr::Yaml::Alias(_) | saphyr::Yaml::Representation(_, _, _) => {
            None
        }
        saphyr::Yaml::Tagged(_, node) => yaml_to_json_value(node),
        saphyr::Yaml::Sequence(items) => items
            .iter()
            .map(yaml_to_json_value)
            .collect::<Option<Vec<_>>>()
            .map(Value::Array),
        saphyr::Yaml::Mapping(entries) => {
            let mut map = serde_json::Map::new();
            for (key, entry) in entries {
                let key = if let Some(text) = key.as_str() {
                    text.to_owned()
                } else if let Some(number) = key.as_integer() {
                    number.to_string()
                } else if let Some(flag) = key.as_bool() {
                    flag.to_string()
                } else {
                    let number = key.clone().into_floating_point()?;
                    number.to_string()
                };
                map.insert(key, yaml_to_json_value(entry)?);
            }
            Some(Value::Object(map))
        }
        saphyr::Yaml::Value(scalar) => match scalar {
            saphyr::Scalar::Null => Some(Value::Null),
            saphyr::Scalar::Boolean(flag) => Some(Value::Bool(*flag)),
            saphyr::Scalar::Integer(number) => Some(Value::Number((*number).into())),
            saphyr::Scalar::FloatingPoint(number) => {
                serde_json::Number::from_f64((*number).into()).map(Value::Number)
            }
            saphyr::Scalar::String(text) => Some(Value::String(text.to_string())),
        },
    }
}

/// Reads JSON or YAML file.
fn read_json_or_yaml_file(path: &Path) -> Option<Value> {
    match path.extension().and_then(|value| value.to_str()) {
        Some("yml") | Some("yaml") => {
            let text = fs::read_to_string(path).ok()?;
            pharos_runtime_core::yaml::validate_unique_mapping_keys(&text).ok()?;
            let documents = saphyr::Yaml::load_from_str(&text).ok()?;
            yaml_to_json_value(&documents.into_iter().next()?)
        }
        _ => read_json_file(path),
    }
}

/// Performs app root relative path.
fn app_root_relative_path(app_root: &Path, relative_path: &str) -> Option<String> {
    if app_root.as_os_str().is_empty() || relative_path.is_empty() {
        return None;
    }
    Some(app_root.join(relative_path).to_string_lossy().into_owned())
}

/// Performs runtime find declared fragment relative path in directory.
fn runtime_find_declared_fragment_relative_path_in_directory(
    absolute_dir: &Path,
    relative_dir: &str,
    stem: &str,
    suffixes: &[&str],
) -> Option<String> {
    if absolute_dir.as_os_str().is_empty() || stem.is_empty() {
        return None;
    }
    let entries = fs::read_dir(absolute_dir).ok()?;
    for entry in entries {
        let entry = entry.ok()?;
        let path = entry.path();
        let file_name = entry.file_name();
        let file_name = file_name.to_string_lossy();
        if file_name == "." || file_name == ".." {
            continue;
        }
        let relative_child = if relative_dir.is_empty() {
            file_name.to_string()
        } else {
            format!("{relative_dir}/{file_name}")
        };
        if path.is_dir() {
            if let Some(found) = runtime_find_declared_fragment_relative_path_in_directory(
                &path,
                &relative_child,
                stem,
                suffixes,
            ) {
                return Some(found);
            }
            continue;
        }
        for suffix in suffixes {
            if let Some(candidate_stem) = file_name.strip_suffix(suffix)
                && candidate_stem == stem
            {
                return Some(relative_child);
            }
        }
    }
    None
}

/// Finds one bounded page declaration by its explicit `page_id` field.
fn declared_page_relative_path_by_id(app_root: &Path, page_id: &str) -> Option<String> {
    const MAX_PAGE_DECLARATION_FILES: usize = 4_096;
    const MAX_PAGE_DECLARATION_DEPTH: usize = 32;
    let templates_root = app_root.join("templates");
    let mut directories = vec![(templates_root, 0_usize)];
    let mut matching_path = None;
    let mut visited_files = 0_usize;

    while let Some((directory, depth)) = directories.pop() {
        if depth > MAX_PAGE_DECLARATION_DEPTH {
            return None;
        }
        let mut entries = fs::read_dir(&directory)
            .ok()?
            .collect::<Result<Vec<_>, _>>()
            .ok()?;
        entries.sort_by_key(|entry| entry.file_name());
        for entry in entries {
            let path = entry.path();
            let metadata = fs::symlink_metadata(&path).ok()?;
            if metadata.file_type().is_symlink() {
                return None;
            }
            if metadata.is_dir() {
                directories.push((path, depth + 1));
                continue;
            }
            if !metadata.is_file() {
                continue;
            }
            visited_files += 1;
            if visited_files > MAX_PAGE_DECLARATION_FILES {
                return None;
            }
            let file_name = path.file_name()?.to_str()?;
            if ![".page.json", ".page.yml", ".page.yaml"]
                .iter()
                .any(|suffix| file_name.ends_with(suffix))
            {
                continue;
            }
            let declaration = read_json_or_yaml_file(&path)?;
            if declaration.get("page_id").and_then(Value::as_str) != Some(page_id) {
                continue;
            }
            let relative = path
                .strip_prefix(app_root)
                .ok()?
                .to_string_lossy()
                .into_owned();
            if matching_path.replace(relative).is_some() {
                return None;
            }
        }
    }
    matching_path
}

/// Resolves a page declaration by conventional filename or explicit `page_id`.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::declared_page_relative_path`].
/// - `page_id`: Input consumed by [`crate::runtime::json_commands::declared_page_relative_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::declared_page_relative_path`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::declared_page_relative_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::declared_page_relative_path(std::path::Path::new("apps/dev_docs"), "home");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn declared_page_relative_path(app_root: &Path, page_id: &str) -> Option<String> {
    if app_root.as_os_str().is_empty() || page_id.is_empty() {
        return None;
    }
    let direct_patterns = [
        format!("templates/{page_id}.page.json"),
        format!("templates/{page_id}.page.yml"),
        format!("templates/{page_id}/{page_id}.page.json"),
        format!("templates/{page_id}/{page_id}.page.yml"),
    ];
    for relative in direct_patterns {
        if app_root.join(&relative).exists() {
            return Some(relative);
        }
    }
    runtime_find_declared_fragment_relative_path_in_directory(
        &app_root.join("templates"),
        "templates",
        &format!("{page_id}.page"),
        &[".json", ".yml", ".yaml"],
    )
    .or_else(|| declared_page_relative_path_by_id(app_root, page_id))
}

/// Performs template declared page contract.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_declared_page_contract`].
/// - `page_id`: Input consumed by [`crate::runtime::json_commands::template_declared_page_contract`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_declared_page_contract`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_declared_page_contract(std::path::Path::new("apps/dev_docs"), "home");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_declared_page_contract(app_root: &Path, page_id: &str) -> Option<String> {
    let relative_path = declared_page_relative_path(app_root, page_id)?;
    let spec_path = app_root.join(&relative_path);
    let root = read_json_or_yaml_file(&spec_path)?;
    let template_rel = root
        .get("template_file")
        .and_then(Value::as_str)
        .unwrap_or_default();
    let title = root
        .get("title")
        .and_then(Value::as_str)
        .unwrap_or_default();
    let layout_id = root
        .get("layout_id")
        .and_then(Value::as_str)
        .unwrap_or_default();
    serde_json::to_string(&serde_json::json!({
        "spec_path": spec_path.to_string_lossy(),
        "template_path": app_root.join(template_rel).to_string_lossy(),
        "title": title,
        "layout_id": layout_id,
    }))
    .ok()
}

/// Performs template render path.
///
/// # Parameters
///
/// - `template_path`: Input consumed by [`crate::runtime::json_commands::template_render_path`].
/// - `params_root`: Input consumed by [`crate::runtime::json_commands::template_render_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_render_path`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::template_render_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_render_path("template.html", &serde_json::json!({}));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_render_path(template_path: &str, params_root: &Value) -> Option<String> {
    if template_path.is_empty() || !params_root.is_object() {
        return None;
    }
    let params = params_root.as_object()?;
    let mut out = String::with_capacity(template_path.len() + 32);
    let mut cursor = 0usize;
    while let Some(relative_open) = template_path[cursor..].find('{') {
        let open = cursor + relative_open;
        out.push_str(&template_path[cursor..open]);
        let key_start = open + 1;
        let relative_close = template_path[key_start..].find('}')?;
        let close = key_start + relative_close;
        let key = &template_path[key_start..close];
        let value = params.get(key)?;
        let rendered = match value {
            Value::String(text) => text.clone(),
            Value::Number(number) => number.to_string(),
            Value::Bool(flag) => flag.to_string(),
            Value::Null => String::new(),
            _ => serde_json::to_string(value).ok()?,
        };
        if !template_path_reference_allowed(&rendered) {
            return None;
        }
        out.push_str(&rendered);
        cursor = close + 1;
    }
    out.push_str(&template_path[cursor..]);
    Some(out)
}

/// Performs template render file.
///
/// # Parameters
///
/// - `template_file`: Input consumed by [`crate::runtime::json_commands::template_render_file`].
/// - `params_root`: Input consumed by [`crate::runtime::json_commands::template_render_file`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_render_file`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_render_file(std::path::Path::new("template.html"), &serde_json::json!({}));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_render_file(template_file: &Path, params_root: &Value) -> Option<String> {
    render_file_template(template_file, params_root)
}

/// Handles template render path command.
///
/// # Parameters
///
/// - `template_path`: Input consumed by [`crate::runtime::json_commands::handle_template_render_path_command`].
/// - `params_root`: Input consumed by [`crate::runtime::json_commands::handle_template_render_path_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_render_path_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_render_path_command("template.html", &serde_json::json!({}));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_render_path_command(
    template_path: &str,
    params_root: &Value,
) -> Option<String> {
    template_render_path(template_path, params_root)
}

/// Handles template render file command.
///
/// # Parameters
///
/// - `template_file`: Input consumed by [`crate::runtime::json_commands::handle_template_render_file_command`].
/// - `params_root`: Input consumed by [`crate::runtime::json_commands::handle_template_render_file_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_render_file_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_render_file_command(std::path::Path::new("template.html"), &serde_json::json!({}));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_render_file_command(
    template_file: &Path,
    params_root: &Value,
) -> Option<String> {
    template_render_file(template_file, params_root)
}

/// Performs template declared fragment path.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_declared_fragment_path`].
/// - `fragment_id`: Input consumed by [`crate::runtime::json_commands::template_declared_fragment_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_declared_fragment_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_declared_fragment_path(std::path::Path::new("apps/dev_docs"), "header");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_declared_fragment_path(app_root: &Path, fragment_id: &str) -> Option<String> {
    if app_root.as_os_str().is_empty() || fragment_id.is_empty() {
        return None;
    }
    app_root_relative_path(
        app_root,
        &runtime_find_declared_fragment_relative_path_in_directory(
            &app_root.join("templates"),
            "templates",
            fragment_id,
            &[".html"],
        )?,
    )
}

/// Performs template apply base path.
///
/// # Parameters
///
/// - `html`: Input consumed by [`crate::runtime::json_commands::template_apply_base_path`].
/// - `base_path`: Input consumed by [`crate::runtime::json_commands::template_apply_base_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_apply_base_path`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::template_apply_base_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_apply_base_path(todo!(), "/app");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_apply_base_path(html: &str, base_path: Option<&str>) -> Option<String> {
    let base_path = base_path.unwrap_or("");
    if base_path.is_empty() || base_path == "/" {
        return Some(html.to_owned());
    }
    let prefixes = [
        "href=\"/",
        "src=\"/",
        "action=\"/",
        "formaction=\"/",
        "hx-post=\"/",
        "hx-get=\"/",
        "hx-put=\"/",
        "hx-delete=\"/",
        "value=\"/",
    ];
    let mut out = String::with_capacity(html.len() + 64);
    let mut index = 0usize;
    while index < html.len() {
        let mut matched = false;
        for prefix in prefixes {
            if html[index..].starts_with(prefix) {
                let suffix_index = index + prefix.len() - 1;
                let already_scoped = html[suffix_index..].starts_with(base_path)
                    && matches!(
                        html[suffix_index + base_path.len()..].chars().next(),
                        Some('/') | Some('"') | None
                    );
                if already_scoped {
                    out.push_str(prefix);
                } else {
                    out.push_str(&prefix[..prefix.len() - 1]);
                    out.push_str(base_path);
                    out.push('/');
                }
                index += prefix.len();
                matched = true;
                break;
            }
        }
        if matched {
            continue;
        }
        out.push(html[index..].chars().next()?);
        index += html[index..].chars().next()?.len_utf8();
    }
    Some(out)
}

/// Renders fragment with params.
fn render_fragment_with_params(
    app_root: &Path,
    relative_path: &str,
    params: serde_json::Map<String, Value>,
) -> Option<String> {
    generated::render_generated_admin_fragment_from_value_runtime(app_root, relative_path, &params)
}

fn app_navigation_text(app_root: &Path, item_id: &str) -> Option<(String, String)> {
    let manifest = read_json_or_yaml_file(&app_root.join("pharos.app.json"))
        .or_else(|| read_json_or_yaml_file(&app_root.join("pharos.app.yml")))
        .or_else(|| read_json_or_yaml_file(&app_root.join("pharos.app.yaml")))?;
    let items = manifest
        .get("ui")
        .and_then(|ui| ui.get("navigation"))
        .and_then(Value::as_array)?;
    let item = items
        .iter()
        .find(|item| json_string(item, "item_id") == Some(item_id))?;
    let label = json_string(item, "label")?.to_owned();
    let title = json_string(item, "title")
        .map(ToOwned::to_owned)
        .unwrap_or_else(|| label.clone());
    Some((label, title))
}

/// Renders error alert HTML.
fn render_error_alert_html(app_root: &Path, message: &str) -> Option<String> {
    if message.is_empty() {
        return Some(String::new());
    }
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/error_alert.html",
        serde_json::Map::from_iter([("message".to_owned(), Value::String(message.to_owned()))]),
    )
    .or_else(|| {
        Some(format!(
            "<p class=\"error-message\" role=\"alert\">{}</p>",
            html_escape_text(message)
        ))
    })
}

/// Renders hidden next input HTML inner.
fn render_hidden_next_input_html_inner(app_root: &Path, next_path: &str) -> Option<String> {
    if next_path.is_empty() {
        return Some(String::new());
    }
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/ui_hidden_input.html",
        Map::from_iter([
            ("id".to_owned(), Value::String("next".to_owned())),
            ("name".to_owned(), Value::String("next".to_owned())),
            ("value".to_owned(), Value::String(next_path.to_owned())),
            ("attributes_html".to_owned(), Value::String(String::new())),
        ]),
    )
    .or_else(|| {
        Some(format!(
            "<input type=\"hidden\" name=\"next\" value=\"{}\">",
            html_escape_text(next_path)
        ))
    })
}

/// Performs template page params JSON.
fn template_page_params_json(
    error_html: &str,
    next_input: &str,
    login_action_path: &str,
    account_type_options_html: &str,
    no_email_access_html: &str,
    reset_post_path: &str,
    invite_email: &str,
    invite_path: &str,
    return_path: &str,
    invite_kind: &str,
    target_html: &str,
    form_action: &str,
) -> Option<String> {
    serde_json::to_string(&serde_json::json!({
        "error_html": error_html,
        "next_input": next_input,
        "login_action_path": login_action_path,
        "account_type_options_html": account_type_options_html,
        "no_email_access_html": no_email_access_html,
        "reset_post_path": reset_post_path,
        "invite_email": invite_email,
        "invite_path": invite_path,
        "return_path": return_path,
        "invite_kind": invite_kind,
        "target_html": target_html,
        "form_action": form_action,
    }))
    .ok()
}

/// Renders the shared inline error fragment used by declarative form pages.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_error_alert_html`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::template_error_alert_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_error_alert_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_error_alert_html(std::path::Path::new("apps/dev_docs"), "example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_error_alert_html(app_root: &Path, message: &str) -> Option<String> {
    render_error_alert_html(app_root, message)
}

/// Performs template login page JSON.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_login_page_json`].
/// - `error_message`: Input consumed by [`crate::runtime::json_commands::template_login_page_json`].
/// - `next_path`: Input consumed by [`crate::runtime::json_commands::template_login_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_login_page_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_login_page_json(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_login_page_json(
    app_root: &Path,
    error_message: Option<&str>,
    next_path: Option<&str>,
) -> Option<String> {
    let login_action_path = crate::config::app_local_conf_path(app_root)
        .and_then(|path| crate::config::dynamic_config_lookup_raw(&path, "base_path"))
        .filter(|value| value.starts_with('/') && !value.contains(['\r', '\n']))
        .filter(|value| value != "/")
        .map(|base_path| format!("{}/accounts/login/", base_path.trim_end_matches('/')))
        .unwrap_or_else(|| "/accounts/login/".to_owned());
    template_page_params_json(
        &render_error_alert_html(app_root, error_message.unwrap_or_default())?,
        &render_hidden_next_input_html_inner(app_root, next_path.unwrap_or_default())?,
        &login_action_path,
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
    )
}

/// Performs template register page JSON.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_register_page_json`].
/// - `error_message`: Input consumed by [`crate::runtime::json_commands::template_register_page_json`].
/// - `next_path`: Input consumed by [`crate::runtime::json_commands::template_register_page_json`].
/// - `account_type_options_html`: Input consumed by [`crate::runtime::json_commands::template_register_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_register_page_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_register_page_json(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_register_page_json(
    app_root: &Path,
    error_message: Option<&str>,
    next_path: Option<&str>,
    account_type_options_html: Option<&str>,
) -> Option<String> {
    template_page_params_json(
        &render_error_alert_html(app_root, error_message.unwrap_or_default())?,
        &render_hidden_next_input_html_inner(app_root, next_path.unwrap_or_default())?,
        "",
        account_type_options_html.unwrap_or_default(),
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
    )
}

/// Performs template password reset request page JSON.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_password_reset_request_page_json`].
/// - `error_message`: Input consumed by [`crate::runtime::json_commands::template_password_reset_request_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_password_reset_request_page_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_password_reset_request_page_json(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_password_reset_request_page_json(
    app_root: &Path,
    error_message: Option<&str>,
) -> Option<String> {
    template_page_params_json(
        &render_error_alert_html(app_root, error_message.unwrap_or_default())?,
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
    )
}

/// Performs template password reset sent page JSON.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_password_reset_sent_page_json`].
/// - `preview_path`: Input consumed by [`crate::runtime::json_commands::template_password_reset_sent_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_password_reset_sent_page_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_password_reset_sent_page_json(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_password_reset_sent_page_json(
    app_root: &Path,
    preview_path: Option<&str>,
) -> Option<String> {
    let preview_path = preview_path.unwrap_or_default();
    if preview_path.is_empty() {
        return template_page_params_json("", "", "", "", "", "", "", "", "", "", "", "");
    }
    let no_email_access_html = render_fragment_with_params(
        app_root,
        "templates/shared/fragments/no_email_access_link.html",
        serde_json::Map::from_iter([
            (
                "intro_text".to_owned(),
                Value::String(
                    "Email delivery is unavailable. Use this local access link:".to_owned(),
                ),
            ),
            (
                "href_path".to_owned(),
                Value::String(preview_path.to_owned()),
            ),
            (
                "access_path".to_owned(),
                Value::String(preview_path.to_owned()),
            ),
        ]),
    )?;
    template_page_params_json(
        "",
        "",
        "",
        "",
        &no_email_access_html,
        "",
        "",
        "",
        "",
        "",
        "",
        "",
    )
}

/// Performs template password reset complete page JSON.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_password_reset_complete_page_json`].
/// - `error_message`: Input consumed by [`crate::runtime::json_commands::template_password_reset_complete_page_json`].
/// - `reset_post_path`: Input consumed by [`crate::runtime::json_commands::template_password_reset_complete_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_password_reset_complete_page_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_password_reset_complete_page_json(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_password_reset_complete_page_json(
    app_root: &Path,
    error_message: Option<&str>,
    reset_post_path: Option<&str>,
) -> Option<String> {
    template_page_params_json(
        &render_error_alert_html(app_root, error_message.unwrap_or_default())?,
        "",
        "",
        "",
        "",
        &html_escape_text(reset_post_path.unwrap_or_default()),
        "",
        "",
        "",
        "",
        "",
        "",
    )
}

/// Performs template invite created page JSON.
///
/// # Parameters
///
/// - `invite_email`: Input consumed by [`crate::runtime::json_commands::template_invite_created_page_json`].
/// - `invite_path`: Input consumed by [`crate::runtime::json_commands::template_invite_created_page_json`].
/// - `return_path`: Input consumed by [`crate::runtime::json_commands::template_invite_created_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_invite_created_page_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_invite_created_page_json(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_invite_created_page_json(
    invite_email: Option<&str>,
    invite_path: Option<&str>,
    return_path: Option<&str>,
) -> Option<String> {
    template_page_params_json(
        "",
        "",
        "",
        "",
        "",
        "",
        &html_escape_text(invite_email.unwrap_or_default()),
        &html_escape_text(invite_path.unwrap_or_default()),
        &html_escape_text(return_path.unwrap_or_default()),
        "",
        "",
        "",
    )
}

/// Performs template invite accept page JSON.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_invite_accept_page_json`].
/// - `invite_kind`: Input consumed by [`crate::runtime::json_commands::template_invite_accept_page_json`].
/// - `target_business_name`: Input consumed by [`crate::runtime::json_commands::template_invite_accept_page_json`].
/// - `error_message`: Input consumed by [`crate::runtime::json_commands::template_invite_accept_page_json`].
/// - `invite_email`: Input consumed by [`crate::runtime::json_commands::template_invite_accept_page_json`].
/// - `form_action`: Input consumed by [`crate::runtime::json_commands::template_invite_accept_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_invite_accept_page_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_invite_accept_page_json(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_invite_accept_page_json(
    app_root: &Path,
    invite_kind: Option<&str>,
    target_business_name: Option<&str>,
    error_message: Option<&str>,
    invite_email: Option<&str>,
    form_action: Option<&str>,
) -> Option<String> {
    let target_html = if let Some(target_business_name) =
        target_business_name.filter(|value| !value.is_empty())
    {
        render_fragment_with_params(
            app_root,
            "templates/shared/fragments/invite_target.html",
            serde_json::Map::from_iter([(
                "business_name".to_owned(),
                Value::String(target_business_name.to_owned()),
            )]),
        )?
    } else {
        String::new()
    };
    template_page_params_json(
        &render_error_alert_html(app_root, error_message.unwrap_or_default())?,
        "",
        "",
        "",
        "",
        "",
        &html_escape_text(invite_email.unwrap_or_default()),
        "",
        "",
        &html_escape_text(invite_kind.unwrap_or("account_invite")),
        &target_html,
        &html_escape_text(form_action.unwrap_or_default()),
    )
}

/// Renders select fragment.
fn render_select_fragment(
    app_root: &Path,
    relative_path: &str,
    value: &str,
    selected: bool,
    label: &str,
) -> Option<String> {
    render_fragment_with_params(
        app_root,
        relative_path,
        serde_json::Map::from_iter([
            ("option_value".to_owned(), Value::String(value.to_owned())),
            (
                "selected_attr".to_owned(),
                Value::String(if selected { " selected" } else { "" }.to_owned()),
            ),
            ("option_label".to_owned(), Value::String(label.to_owned())),
        ]),
    )
}

/// Builds layout page params JSON.
fn build_layout_page_params_json(
    app_root: &Path,
    layout_id: Option<&str>,
    title: &str,
    body: &str,
    current_lang: Option<&str>,
    current_request_target: Option<&str>,
    has_user: bool,
    managed_business_count: i64,
) -> Option<String> {
    let effective_layout_id = layout_id
        .filter(|value| !value.is_empty())
        .unwrap_or("default_shell");
    let resolved_lang = current_lang
        .filter(|value| !value.is_empty())
        .unwrap_or("en");
    let (nav_home_path, nav_primary, nav_account): (String, String, String);

    let languages = [
        ("en", "English"),
        ("ja", "日本語"),
        ("es", "Español"),
        ("fr", "Français"),
        ("de", "Deutsch"),
        ("pt", "Português"),
    ];
    let mut language_options_html = String::new();
    for (code, label) in languages {
        language_options_html.push_str(&render_select_fragment(
            app_root,
            "templates/layout/fragments/language_option.html",
            code,
            resolved_lang == code,
            label,
        )?);
    }
    let language_select_ui_html = render_fragment_with_params(
        app_root,
        "templates/shared/fragments/ui_select.html",
        serde_json::Map::from_iter([
            ("id".to_owned(), Value::String("language-select".to_owned())),
            ("name".to_owned(), Value::String("language".to_owned())),
            ("label".to_owned(), Value::String("Language".to_owned())),
            (
                "label_class".to_owned(),
                Value::String("sr-only".to_owned()),
            ),
            (
                "class_name".to_owned(),
                Value::String("form-control".to_owned()),
            ),
            ("attributes_html".to_owned(), Value::String(String::new())),
            (
                "options_html".to_owned(),
                Value::String(language_options_html),
            ),
            ("help_html".to_owned(), Value::String(String::new())),
        ]),
    )?;
    let language_form_html = render_fragment_with_params(
        app_root,
        "templates/layout/fragments/language_form.html",
        serde_json::Map::from_iter([
            (
                "current_request_target".to_owned(),
                Value::String(current_request_target.unwrap_or("/").to_owned()),
            ),
            (
                "language_select_ui_html".to_owned(),
                Value::String(language_select_ui_html),
            ),
        ]),
    )?;

    if has_user {
        let mut resolved_nav_home_path = "/".to_owned();
        let nav_primary_value: String;
        if effective_layout_id == "architect_shell" {
            let (home_label, home_title) = app_navigation_text(app_root, "home")?;
            let home_link_html = render_fragment_with_params(
                app_root,
                "templates/layout/fragments/nav_link.html",
                serde_json::Map::from_iter([
                    ("link_path".to_owned(), Value::String("/".to_owned())),
                    ("link_label".to_owned(), Value::String(home_label)),
                    ("link_title".to_owned(), Value::String(home_title)),
                    (
                        "class_name".to_owned(),
                        Value::String("nav-icon-button architect-nav-home-link".to_owned()),
                    ),
                    (
                        "attributes_html".to_owned(),
                        Value::String(" data-pharos-nav=\"architect-main\"".to_owned()),
                    ),
                ]),
            )?;
            let (file_label, file_title) = app_navigation_text(app_root, "file")?;
            let file_link_html = render_fragment_with_params(
                app_root,
                "templates/layout/fragments/nav_link.html",
                serde_json::Map::from_iter([
                    ("link_path".to_owned(), Value::String("/editor".to_owned())),
                    ("link_label".to_owned(), Value::String(file_label)),
                    ("link_title".to_owned(), Value::String(file_title)),
                    (
                        "class_name".to_owned(),
                        Value::String("nav-icon-button architect-nav-file-link".to_owned()),
                    ),
                    (
                        "attributes_html".to_owned(),
                        Value::String(" data-pharos-nav=\"architect-main\"".to_owned()),
                    ),
                ]),
            )?;
            let settings_link_html = if managed_business_count > 0 {
                let (settings_label, settings_title) = app_navigation_text(app_root, "settings")?;
                render_fragment_with_params(
                    app_root,
                    "templates/layout/fragments/nav_link.html",
                    serde_json::Map::from_iter([
                        (
                            "link_path".to_owned(),
                            Value::String("/settings".to_owned()),
                        ),
                        ("link_label".to_owned(), Value::String(settings_label)),
                        ("link_title".to_owned(), Value::String(settings_title)),
                        (
                            "class_name".to_owned(),
                            Value::String("nav-icon-button architect-nav-settings-link".to_owned()),
                        ),
                        (
                            "attributes_html".to_owned(),
                            Value::String(" data-pharos-nav=\"architect-main\"".to_owned()),
                        ),
                    ]),
                )?
            } else {
                String::new()
            };
            let logout_button_ui_html = render_fragment_with_params(
                app_root,
                "templates/layout/fragments/nav_logout_button.html",
                serde_json::Map::new(),
            )?;
            let logout_form_html = render_fragment_with_params(
                app_root,
                "templates/layout/fragments/logout_form.html",
                serde_json::Map::from_iter([(
                    "logout_button_ui_html".to_owned(),
                    Value::String(logout_button_ui_html),
                )]),
            )?;
            nav_home_path = "/".to_owned();
            nav_primary = format!("{home_link_html} {file_link_html}");
            nav_account = format!("{settings_link_html}{logout_form_html}");
            let browser_title = layout_browser_title(app_root, title);
            return serde_json::to_string(&serde_json::json!({
                "current_lang": resolved_lang,
                "current_request_target": current_request_target.unwrap_or("/"),
                "title": browser_title,
                "nav_home_path": nav_home_path,
                "nav_primary": nav_primary,
                "nav_account": nav_account,
                "body": body,
            }))
            .ok();
        }
        let appointments_link_html = render_fragment_with_params(
            app_root,
            "templates/layout/fragments/nav_link.html",
            serde_json::Map::from_iter([
                (
                    "link_path".to_owned(),
                    Value::String("/appointments/".to_owned()),
                ),
                (
                    "link_label".to_owned(),
                    Value::String("Appointments".to_owned()),
                ),
            ]),
        )?;
        let profile_link_html = render_fragment_with_params(
            app_root,
            "templates/layout/fragments/nav_link.html",
            serde_json::Map::from_iter([
                (
                    "link_path".to_owned(),
                    Value::String("/profile/".to_owned()),
                ),
                ("link_label".to_owned(), Value::String("Profile".to_owned())),
            ]),
        )?;
        let logout_button_ui_html = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/ui_button.html",
            serde_json::Map::from_iter([
                ("id".to_owned(), Value::String("logout_button".to_owned())),
                ("button_type".to_owned(), Value::String("submit".to_owned())),
                (
                    "class_name".to_owned(),
                    Value::String("btn btn-secondary".to_owned()),
                ),
                ("attributes_html".to_owned(), Value::String(String::new())),
                (
                    "content_html".to_owned(),
                    Value::String("Log out".to_owned()),
                ),
            ]),
        )?;
        let logout_form_html = render_fragment_with_params(
            app_root,
            "templates/layout/fragments/logout_form.html",
            serde_json::Map::from_iter([(
                "logout_button_ui_html".to_owned(),
                Value::String(logout_button_ui_html),
            )]),
        )?;
        if matches!(
            effective_layout_id,
            "public_catalog_shell" | "public_business_shell"
        ) {
            if effective_layout_id == "public_business_shell" && managed_business_count > 0 {
                let manage_business_link_html = render_fragment_with_params(
                    app_root,
                    "templates/layout/fragments/nav_link.html",
                    serde_json::Map::from_iter([
                        (
                            "link_path".to_owned(),
                            Value::String("/businesses/".to_owned()),
                        ),
                        (
                            "link_label".to_owned(),
                            Value::String("Manage Businesses".to_owned()),
                        ),
                    ]),
                )?;
                nav_primary_value = format!("{appointments_link_html} {manage_business_link_html}");
            } else {
                nav_primary_value = appointments_link_html;
            }
            resolved_nav_home_path = "/explore/".to_owned();
        } else if matches!(effective_layout_id, "business_shell" | "account_shell")
            || managed_business_count > 0
        {
            let manage_business_link_html = render_fragment_with_params(
                app_root,
                "templates/layout/fragments/nav_link.html",
                serde_json::Map::from_iter([
                    (
                        "link_path".to_owned(),
                        Value::String("/businesses/".to_owned()),
                    ),
                    (
                        "link_label".to_owned(),
                        Value::String("Manage Businesses".to_owned()),
                    ),
                ]),
            )?;
            nav_primary_value = format!("{appointments_link_html} {manage_business_link_html}");
            resolved_nav_home_path = "/explore/".to_owned();
        } else {
            nav_primary_value = String::new();
        }
        nav_home_path = resolved_nav_home_path;
        nav_primary = nav_primary_value;
        nav_account = format!("{language_form_html} {profile_link_html}{logout_form_html}");
    } else if effective_layout_id == "architect_shell" {
        nav_home_path = "/accounts/login/".to_owned();
        nav_primary = String::new();
        nav_account = language_form_html;
    } else {
        nav_home_path = "/accounts/login/".to_owned();
        let login_link_html = render_fragment_with_params(
            app_root,
            "templates/layout/fragments/nav_link.html",
            serde_json::Map::from_iter([
                (
                    "link_path".to_owned(),
                    Value::String("/accounts/login/".to_owned()),
                ),
                ("link_label".to_owned(), Value::String("Log in".to_owned())),
            ]),
        )?;
        let register_link_html = render_fragment_with_params(
            app_root,
            "templates/layout/fragments/nav_link.html",
            serde_json::Map::from_iter([
                (
                    "link_path".to_owned(),
                    Value::String("/accounts/register/".to_owned()),
                ),
                ("link_label".to_owned(), Value::String("Sign Up".to_owned())),
            ]),
        )?;
        nav_primary = format!("{login_link_html} {register_link_html}");
        nav_account = language_form_html;
    }

    let browser_title = layout_browser_title(app_root, title);
    serde_json::to_string(&serde_json::json!({
        "current_lang": resolved_lang,
        "current_request_target": current_request_target.unwrap_or("/"),
        "title": browser_title,
        "nav_home_path": nav_home_path,
        "nav_primary": nav_primary,
        "nav_account": nav_account,
        "body": body,
    }))
    .ok()
}

pub(crate) fn layout_browser_title(app_root: &Path, title: &str) -> String {
    let page_title = title.trim();
    let app_name = read_json_or_yaml_file(&app_root.join("pharos.app.json"))
        .or_else(|| read_json_or_yaml_file(&app_root.join("pharos.app.yml")))
        .or_else(|| read_json_or_yaml_file(&app_root.join("pharos.app.yaml")))
        .and_then(|manifest| {
            manifest
                .get("name")
                .and_then(Value::as_str)
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .map(ToOwned::to_owned)
        });
    let Some(app_name) = app_name else {
        return page_title.to_owned();
    };
    let page_title = page_title
        .strip_prefix(&format!("{app_name} — "))
        .or_else(|| page_title.strip_prefix(&format!("{app_name} - ")))
        .or_else(|| page_title.strip_suffix(&format!(" — {app_name}")))
        .or_else(|| page_title.strip_suffix(&format!(" - {app_name}")))
        .unwrap_or(page_title)
        .trim();
    if page_title.is_empty() || page_title == app_name {
        app_name
    } else {
        format!("{app_name} - {page_title}")
    }
}

/// Performs template layout page JSON.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_layout_page_json`].
/// - `layout_id`: Input consumed by [`crate::runtime::json_commands::template_layout_page_json`].
/// - `current_lang`: Input consumed by [`crate::runtime::json_commands::template_layout_page_json`].
/// - `title`: Input consumed by [`crate::runtime::json_commands::template_layout_page_json`].
/// - `body`: Input consumed by [`crate::runtime::json_commands::template_layout_page_json`].
/// - `current_request_target`: Input consumed by [`crate::runtime::json_commands::template_layout_page_json`].
/// - `has_user`: Input consumed by [`crate::runtime::json_commands::template_layout_page_json`].
/// - `managed_business_count`: Input consumed by [`crate::runtime::json_commands::template_layout_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_layout_page_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_layout_page_json(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), b"", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_layout_page_json(
    app_root: &Path,
    layout_id: Option<&str>,
    current_lang: Option<&str>,
    title: &str,
    body: &str,
    current_request_target: Option<&str>,
    has_user: bool,
    managed_business_count: i64,
) -> Option<String> {
    if app_root.as_os_str().is_empty() || title.is_empty() || body.is_empty() {
        return None;
    }
    build_layout_page_params_json(
        app_root,
        layout_id,
        title,
        body,
        current_lang,
        current_request_target,
        has_user,
        managed_business_count,
    )
}

/// Performs template layout page HTML.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::template_layout_page_html`].
/// - `base_path`: Input consumed by [`crate::runtime::json_commands::template_layout_page_html`].
/// - `layout_id`: Input consumed by [`crate::runtime::json_commands::template_layout_page_html`].
/// - `current_lang`: Input consumed by [`crate::runtime::json_commands::template_layout_page_html`].
/// - `title`: Input consumed by [`crate::runtime::json_commands::template_layout_page_html`].
/// - `body`: Input consumed by [`crate::runtime::json_commands::template_layout_page_html`].
/// - `current_request_target`: Input consumed by [`crate::runtime::json_commands::template_layout_page_html`].
/// - `has_user`: Input consumed by [`crate::runtime::json_commands::template_layout_page_html`].
/// - `managed_business_count`: Input consumed by [`crate::runtime::json_commands::template_layout_page_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::template_layout_page_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::template_layout_page_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_layout_page_html(std::path::Path::new("apps/dev_docs"), "/app", todo!(), todo!(), todo!(), b"", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_layout_page_html(
    app_root: &Path,
    base_path: Option<&str>,
    layout_id: Option<&str>,
    current_lang: Option<&str>,
    title: &str,
    body: &str,
    current_request_target: Option<&str>,
    has_user: bool,
    managed_business_count: i64,
) -> Option<String> {
    let render_params_json = build_layout_page_params_json(
        app_root,
        layout_id,
        title,
        body,
        current_lang,
        current_request_target,
        has_user,
        managed_business_count,
    )?;
    let render_params_root = serde_json::from_str::<Value>(&render_params_json).ok()?;
    let rendered = render_file_template(
        &app_root.join("templates/layout/base.html"),
        &render_params_root,
    )?;
    template_apply_base_path(&rendered, base_path)
}

/// Performs validation empty report.
///
/// # Parameters
///
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::validation_empty_report`].
/// - `action_id`: Input consumed by [`crate::runtime::json_commands::validation_empty_report`].
/// - `actor_scope`: Input consumed by [`crate::runtime::json_commands::validation_empty_report`].
/// - `tenant_scope`: Input consumed by [`crate::runtime::json_commands::validation_empty_report`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::validation_empty_report`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::validation_empty_report("form", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn validation_empty_report(
    form_id: Option<&str>,
    action_id: Option<&str>,
    actor_scope: Option<&str>,
    tenant_scope: Option<&str>,
) -> Option<String> {
    serde_json::to_string(&serde_json::json!({
        "schema": "pharos.validation.report.v1",
        "report_id": "pharos.validation.report.v1",
        "form_id": form_id.unwrap_or_default(),
        "action_id": action_id.unwrap_or_default(),
        "field_errors": [],
        "form_errors": [],
        "actor_scope": actor_scope.unwrap_or("anonymous"),
        "tenant_scope": tenant_scope.unwrap_or("global"),
    }))
    .ok()
}

/// Appends validation error.
fn append_validation_error(
    report_json: &str,
    array_name: &str,
    field_id: Option<&str>,
    rule_id: Option<&str>,
    code_text: Option<&str>,
    message: Option<&str>,
) -> Option<String> {
    let mut root = serde_json::from_str::<Value>(report_json).ok()?;
    let object = root.as_object_mut()?;
    if !matches!(object.get(array_name), Some(Value::Array(_))) {
        object.insert(array_name.to_owned(), Value::Array(Vec::new()));
    }
    let errors = object.get_mut(array_name)?.as_array_mut()?;
    let mut entry = serde_json::Map::new();
    if let Some(field_id) = field_id.filter(|value| !value.is_empty()) {
        entry.insert("field_id".to_owned(), Value::String(field_id.to_owned()));
    }
    entry.insert(
        "rule_id".to_owned(),
        Value::String(rule_id.unwrap_or_default().to_owned()),
    );
    entry.insert(
        "code".to_owned(),
        Value::String(code_text.unwrap_or_default().to_owned()),
    );
    entry.insert(
        "message".to_owned(),
        Value::String(message.unwrap_or_default().to_owned()),
    );
    errors.push(Value::Object(entry));
    serde_json::to_string(&root).ok()
}

/// Performs validation add field error.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::validation_add_field_error`].
/// - `field_id`: Input consumed by [`crate::runtime::json_commands::validation_add_field_error`].
/// - `rule_id`: Input consumed by [`crate::runtime::json_commands::validation_add_field_error`].
/// - `code_text`: Input consumed by [`crate::runtime::json_commands::validation_add_field_error`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::validation_add_field_error`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::validation_add_field_error`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::validation_add_field_error("{}", "field", todo!(), todo!(), "example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn validation_add_field_error(
    report_json: &str,
    field_id: Option<&str>,
    rule_id: Option<&str>,
    code_text: Option<&str>,
    message: Option<&str>,
) -> Option<String> {
    append_validation_error(
        report_json,
        "field_errors",
        field_id,
        rule_id,
        code_text,
        message,
    )
}

/// Performs validation add form error.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::validation_add_form_error`].
/// - `rule_id`: Input consumed by [`crate::runtime::json_commands::validation_add_form_error`].
/// - `code_text`: Input consumed by [`crate::runtime::json_commands::validation_add_form_error`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::validation_add_form_error`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::validation_add_form_error`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::validation_add_form_error("{}", todo!(), todo!(), "example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn validation_add_form_error(
    report_json: &str,
    rule_id: Option<&str>,
    code_text: Option<&str>,
    message: Option<&str>,
) -> Option<String> {
    append_validation_error(
        report_json,
        "form_errors",
        None,
        rule_id,
        code_text,
        message,
    )
}

/// Performs validation has errors.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::validation_has_errors`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::validation_has_errors`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::validation_has_errors`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::validation_has_errors("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn validation_has_errors(report_json: &str) -> Option<bool> {
    let Some(root) = serde_json::from_str::<Value>(report_json).ok() else {
        return Some(false);
    };
    let field_count = root
        .get("field_errors")
        .and_then(Value::as_array)
        .map(Vec::len)
        .unwrap_or(0);
    let form_count = root
        .get("form_errors")
        .and_then(Value::as_array)
        .map(Vec::len)
        .unwrap_or(0);
    Some(field_count + form_count > 0)
}

/// Performs validation summary text.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::validation_summary_text`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::validation_summary_text`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::validation_summary_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::validation_summary_text("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn validation_summary_text(report_json: &str) -> Option<String> {
    let root = serde_json::from_str::<Value>(report_json).ok()?;
    let object = root.as_object()?;
    let mut items = Vec::new();
    for array_name in ["field_errors", "form_errors"] {
        if let Some(errors) = object.get(array_name).and_then(Value::as_array) {
            for item in errors {
                let rule_id = item
                    .get("rule_id")
                    .and_then(Value::as_str)
                    .unwrap_or_default();
                let message = item
                    .get("message")
                    .and_then(Value::as_str)
                    .unwrap_or_default();
                if !message.is_empty() {
                    items.push(format!("[{rule_id}] {message}"));
                }
            }
        }
    }
    Some(items.join(" "))
}

/// Performs validation field list HTML.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::validation_field_list_html`].
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::validation_field_list_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::validation_field_list_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::validation_field_list_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::validation_field_list_html(std::path::Path::new("apps/dev_docs"), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn validation_field_list_html(app_root: &Path, report_json: &str) -> Option<String> {
    if app_root.as_os_str().is_empty() {
        return None;
    }
    let root = serde_json::from_str::<Value>(report_json).ok()?;
    let object = root.as_object()?;
    let mut out = String::new();
    if let Some(errors) = object.get("field_errors").and_then(Value::as_array) {
        for item in errors {
            let rule_id = item
                .get("rule_id")
                .and_then(Value::as_str)
                .unwrap_or_default();
            let field_id = item
                .get("field_id")
                .and_then(Value::as_str)
                .unwrap_or_default();
            let message = item
                .get("message")
                .and_then(Value::as_str)
                .unwrap_or_default();
            out.push_str(&render_fragment_with_params(
                app_root,
                "templates/shared/fragments/validation_field_error_item.html",
                serde_json::Map::from_iter([
                    ("rule_id".to_owned(), Value::String(rule_id.to_owned())),
                    ("field_id".to_owned(), Value::String(field_id.to_owned())),
                    ("message".to_owned(), Value::String(message.to_owned())),
                ]),
            )?);
        }
    }
    if let Some(errors) = object.get("form_errors").and_then(Value::as_array) {
        for item in errors {
            let rule_id = item
                .get("rule_id")
                .and_then(Value::as_str)
                .unwrap_or_default();
            let message = item
                .get("message")
                .and_then(Value::as_str)
                .unwrap_or_default();
            out.push_str(&render_fragment_with_params(
                app_root,
                "templates/shared/fragments/validation_form_error_item.html",
                serde_json::Map::from_iter([
                    ("rule_id".to_owned(), Value::String(rule_id.to_owned())),
                    ("message".to_owned(), Value::String(message.to_owned())),
                ]),
            )?);
        }
    }
    Some(out)
}

/// Trims ascii whitespace range.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::trim_ascii_whitespace_range`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::trim_ascii_whitespace_range`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::trim_ascii_whitespace_range("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn trim_ascii_whitespace_range(text: &str) -> (usize, usize) {
    let bytes = text.as_bytes();
    let mut start = 0usize;
    let mut end = bytes.len();
    while start < end && bytes[start].is_ascii_whitespace() {
        start += 1;
    }
    while end > start && bytes[end - 1].is_ascii_whitespace() {
        end -= 1;
    }
    (start, end)
}

/// Performs JSON string array lines.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::json_string_array_lines`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_string_array_lines`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::json_string_array_lines`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_string_array_lines("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_string_array_lines(text: &str) -> Option<Vec<String>> {
    serde_json::from_str::<Value>(text)
        .ok()?
        .as_array()?
        .iter()
        .map(|value| value.as_str().map(ToOwned::to_owned))
        .collect()
}

/// Renders empty card list item.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_empty_card_list_item`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::render_empty_card_list_item`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_empty_card_list_item`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_empty_card_list_item(std::path::Path::new("apps/dev_docs"), "example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_empty_card_list_item(app_root: &str, message: &str) -> Option<String> {
    super::business::render_empty_card_list_item_business_logic_local(app_root, message)
}

/// Performs surface find by ID.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::surface_find_by_id`].
/// - `surface_id`: Input consumed by [`crate::runtime::json_commands::surface_find_by_id`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::surface_find_by_id`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::surface_find_by_id`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::surface_find_by_id(std::path::Path::new("."), "surface");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn surface_find_by_id(root: &Value, surface_id: &str) -> Option<String> {
    root.get("surfaces")?
        .as_array()?
        .iter()
        .find(|surface| {
            surface.get("id").and_then(Value::as_str) == Some(surface_id)
                || surface.get("surface_id").and_then(Value::as_str) == Some(surface_id)
        })
        .and_then(compact)
}

/// Performs error envelope.
///
/// # Parameters
///
/// - `error_type`: Input consumed by [`crate::runtime::json_commands::error_envelope`].
/// - `error_code`: Input consumed by [`crate::runtime::json_commands::error_envelope`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::error_envelope`].
/// - `actor_scope`: Input consumed by [`crate::runtime::json_commands::error_envelope`].
/// - `tenant_scope`: Input consumed by [`crate::runtime::json_commands::error_envelope`].
/// - `details_json`: Input consumed by [`crate::runtime::json_commands::error_envelope`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::error_envelope`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::error_envelope`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::error_envelope(todo!(), todo!(), "example", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn error_envelope(
    error_type: Option<&str>,
    error_code: Option<&str>,
    message: Option<&str>,
    actor_scope: Option<&str>,
    tenant_scope: Option<&str>,
    details_json: Option<&str>,
) -> Option<String> {
    let details = details_json
        .filter(|value| !value.is_empty())
        .and_then(|value| serde_json::from_str::<Value>(value).ok());
    let mut envelope = pharos_runtime_core::error::envelope(
        pharos_runtime_core::error::ErrorCode::InvalidInput,
        message.unwrap_or_default(),
        None,
    );
    let error = envelope.get_mut("error")?.as_object_mut()?;
    error.insert(
        "context".to_owned(),
        Value::String(error_type.unwrap_or_default().to_owned()),
    );
    error.insert(
        "declared_code".to_owned(),
        Value::String(error_code.unwrap_or_default().to_owned()),
    );
    error.insert(
        "actor_scope".to_owned(),
        Value::String(actor_scope.unwrap_or("anonymous").to_owned()),
    );
    error.insert(
        "tenant_scope".to_owned(),
        Value::String(tenant_scope.unwrap_or("global").to_owned()),
    );
    error.insert("details".to_owned(), details.unwrap_or(Value::Null));
    serde_json::to_string(&envelope).ok()
}

/// Performs validation error envelope.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::validation_error_envelope`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::validation_error_envelope`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::validation_error_envelope`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::validation_error_envelope("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn validation_error_envelope(report_json: &str) -> Option<String> {
    let root = serde_json::from_str::<Value>(report_json).ok()?;
    let actor_scope = root
        .get("actor_scope")
        .and_then(Value::as_str)
        .unwrap_or("anonymous");
    let tenant_scope = root
        .get("tenant_scope")
        .and_then(Value::as_str)
        .unwrap_or("global");
    let mut envelope = pharos_runtime_core::error::envelope(
        pharos_runtime_core::error::ErrorCode::InvalidInput,
        "Validation failed.",
        None,
    );
    let error = envelope.get_mut("error")?.as_object_mut()?;
    error.insert(
        "context".to_owned(),
        Value::String("validation_error".to_owned()),
    );
    error.insert(
        "declared_code".to_owned(),
        Value::String("validation_failed".to_owned()),
    );
    error.insert(
        "actor_scope".to_owned(),
        Value::String(actor_scope.to_owned()),
    );
    error.insert(
        "tenant_scope".to_owned(),
        Value::String(tenant_scope.to_owned()),
    );
    error.insert("details".to_owned(), root);
    serde_json::to_string(&envelope).ok()
}

/// Handles validation empty report command.
///
/// # Parameters
///
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::handle_validation_empty_report_command`].
/// - `action_id`: Input consumed by [`crate::runtime::json_commands::handle_validation_empty_report_command`].
/// - `actor_scope`: Input consumed by [`crate::runtime::json_commands::handle_validation_empty_report_command`].
/// - `tenant_scope`: Input consumed by [`crate::runtime::json_commands::handle_validation_empty_report_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_validation_empty_report_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_validation_empty_report_command("form", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_validation_empty_report_command(
    form_id: Option<&str>,
    action_id: Option<&str>,
    actor_scope: Option<&str>,
    tenant_scope: Option<&str>,
) -> Option<String> {
    validation_empty_report(form_id, action_id, actor_scope, tenant_scope)
}

/// Handles validation add field error command.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::handle_validation_add_field_error_command`].
/// - `field_id`: Input consumed by [`crate::runtime::json_commands::handle_validation_add_field_error_command`].
/// - `rule_id`: Input consumed by [`crate::runtime::json_commands::handle_validation_add_field_error_command`].
/// - `code_text`: Input consumed by [`crate::runtime::json_commands::handle_validation_add_field_error_command`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::handle_validation_add_field_error_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_validation_add_field_error_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_validation_add_field_error_command("{}", "field", todo!(), todo!(), "example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_validation_add_field_error_command(
    report_json: &str,
    field_id: Option<&str>,
    rule_id: Option<&str>,
    code_text: Option<&str>,
    message: Option<&str>,
) -> Option<String> {
    validation_add_field_error(report_json, field_id, rule_id, code_text, message)
}

/// Handles validation add form error command.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::handle_validation_add_form_error_command`].
/// - `rule_id`: Input consumed by [`crate::runtime::json_commands::handle_validation_add_form_error_command`].
/// - `code_text`: Input consumed by [`crate::runtime::json_commands::handle_validation_add_form_error_command`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::handle_validation_add_form_error_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_validation_add_form_error_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_validation_add_form_error_command("{}", todo!(), todo!(), "example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_validation_add_form_error_command(
    report_json: &str,
    rule_id: Option<&str>,
    code_text: Option<&str>,
    message: Option<&str>,
) -> Option<String> {
    validation_add_form_error(report_json, rule_id, code_text, message)
}

/// Handles validation has errors command.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::handle_validation_has_errors_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_validation_has_errors_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_validation_has_errors_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_validation_has_errors_command(report_json: &str) -> Option<bool> {
    validation_has_errors(report_json)
}

/// Handles validation summary text command.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::handle_validation_summary_text_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_validation_summary_text_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_validation_summary_text_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_validation_summary_text_command(report_json: &str) -> Option<String> {
    validation_summary_text(report_json)
}

/// Handles validation field list HTML command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_validation_field_list_html_command`].
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::handle_validation_field_list_html_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_validation_field_list_html_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_validation_field_list_html_command(std::path::Path::new("apps/dev_docs"), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_validation_field_list_html_command(
    app_root: &Path,
    report_json: &str,
) -> Option<String> {
    validation_field_list_html(app_root, report_json)
}

/// Handles error envelope command.
///
/// # Parameters
///
/// - `error_type`: Input consumed by [`crate::runtime::json_commands::handle_error_envelope_command`].
/// - `error_code`: Input consumed by [`crate::runtime::json_commands::handle_error_envelope_command`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::handle_error_envelope_command`].
/// - `actor_scope`: Input consumed by [`crate::runtime::json_commands::handle_error_envelope_command`].
/// - `tenant_scope`: Input consumed by [`crate::runtime::json_commands::handle_error_envelope_command`].
/// - `details_json`: Input consumed by [`crate::runtime::json_commands::handle_error_envelope_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_error_envelope_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_error_envelope_command(todo!(), todo!(), "example", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_error_envelope_command(
    error_type: Option<&str>,
    error_code: Option<&str>,
    message: Option<&str>,
    actor_scope: Option<&str>,
    tenant_scope: Option<&str>,
    details_json: Option<&str>,
) -> Option<String> {
    error_envelope(
        error_type,
        error_code,
        message,
        actor_scope,
        tenant_scope,
        details_json,
    )
}

/// Handles validation error envelope command.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::json_commands::handle_validation_error_envelope_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_validation_error_envelope_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_validation_error_envelope_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_validation_error_envelope_command(report_json: &str) -> Option<String> {
    validation_error_envelope(report_json)
}

/// Performs route template params.
fn route_template_params(
    template_path: &str,
    request_path: &str,
) -> Option<serde_json::Map<String, Value>> {
    if template_path.is_empty() || request_path.is_empty() {
        return None;
    }
    let template_segments: Vec<&str> = template_path.trim_matches('/').split('/').collect();
    let request_segments: Vec<&str> = request_path
        .split('?')
        .next()
        .unwrap_or_default()
        .trim_matches('/')
        .split('/')
        .collect();
    if template_segments.len() != request_segments.len() {
        return None;
    }
    let mut params = serde_json::Map::new();
    for (template, actual) in template_segments.iter().zip(request_segments.iter()) {
        if let Some(name) = template
            .strip_prefix('{')
            .and_then(|value| value.strip_suffix('}'))
        {
            if name.is_empty() || actual.is_empty() {
                return None;
            }
            params.insert(name.to_owned(), Value::String((*actual).to_owned()));
        } else if template != actual {
            return None;
        }
    }
    Some(params)
}

/// Matches one request against generated API/admin operation declarations in a contract file.
///
/// # Parameters
///
/// - `file_path`: Input consumed by [`crate::runtime::json_commands::file_generated_surface_match`].
/// - `method`: Input consumed by [`crate::runtime::json_commands::file_generated_surface_match`].
/// - `request_path`: Input consumed by [`crate::runtime::json_commands::file_generated_surface_match`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::file_generated_surface_match`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::file_generated_surface_match`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::file_generated_surface_match(todo!(), todo!(), "/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn file_generated_surface_match(
    file_path: &Path,
    method: &str,
    request_path: &str,
) -> Option<String> {
    if file_path.as_os_str().is_empty() || method.is_empty() || request_path.is_empty() {
        return None;
    }
    let root = read_json_file(file_path)?;
    for surface in root.get("surfaces").and_then(Value::as_array)? {
        if !matches!(
            surface.get("surface_kind").and_then(Value::as_str),
            Some("generated_api") | Some("generated_admin")
        ) {
            continue;
        }
        let Some(operations) = surface.get("operations").and_then(Value::as_object) else {
            continue;
        };
        for (operation_name, operation_config) in operations {
            let operation_method = operation_config
                .get("method")
                .and_then(Value::as_str)
                .unwrap_or("GET");
            let operation_path = operation_config.get("path").and_then(Value::as_str)?;
            if operation_method != method {
                continue;
            }
            let Some(params) = route_template_params(operation_path, request_path) else {
                continue;
            };
            return serde_json::to_string(&serde_json::json!({
                "surface": surface,
                "operation": operation_name,
                "operation_config": operation_config,
                "params": Value::Object(params),
            }))
            .ok();
        }
    }
    None
}

/// Performs generated surface label.
fn generated_surface_label(field_name: &str) -> String {
    field_name
        .split('_')
        .filter(|part| !part.is_empty())
        .map(|part| {
            let mut chars = part.chars();
            match chars.next() {
                Some(first) => format!("{}{}", first.to_ascii_uppercase(), chars.as_str()),
                None => String::new(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ")
}

/// Returns generated-admin list-column metadata, applying the native fallback contract.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_list_columns`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_list_columns`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_list_columns`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_list_columns("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_list_columns(surface_json: &str) -> Option<String> {
    let root = serde_json::from_str::<Value>(surface_json).ok()?;
    if let Some(columns) = root
        .get("admin")
        .and_then(|value| value.get("list_columns"))
        .filter(|value| value.is_array())
    {
        return serde_json::to_string(columns).ok();
    }
    let mut columns = Vec::new();
    for field in root.get("response_fields").and_then(Value::as_array)? {
        let Some(field_name) = field.as_str() else {
            continue;
        };
        if matches!(field_name, "id" | "business_id") || columns.len() >= 4 {
            continue;
        }
        columns.push(serde_json::json!({
            "field": field_name,
            "label": generated_surface_label(field_name),
        }));
    }
    serde_json::to_string(&Value::Array(columns)).ok()
}

/// Builds the context and identity parameter object used by generated routes.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_params`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_params`].
/// - `identity_value`: Input consumed by [`crate::runtime::json_commands::generated_surface_params`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_params`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_params`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_params("{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_params(
    surface_json: &str,
    context_json: &str,
    identity_value: Option<&str>,
) -> Option<String> {
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let context = serde_json::from_str::<Value>(context_json).ok()?;
    let mut params = serde_json::Map::new();
    if let Some(param) = surface
        .get("context_binding")
        .and_then(|value| value.get("param"))
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        && let Some(value) = context.get("context_value")
        && !value.is_null()
    {
        params.insert(param.to_owned(), value.clone());
    }
    if let Some(param) = surface
        .get("identity_param")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        && let Some(identity_value) = identity_value.filter(|value| !value.is_empty())
    {
        params.insert(param.to_owned(), Value::String(identity_value.to_owned()));
    }
    serde_json::to_string(&Value::Object(params)).ok()
}

/// Converts one generated-surface field value to the native display-text contract.
///
/// # Parameters
///
/// - `item_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_display_value`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::generated_surface_display_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_display_value`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_display_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_display_value("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_display_value(item_json: &str, field_name: &str) -> Option<String> {
    if field_name.is_empty() {
        return None;
    }
    let root = serde_json::from_str::<Value>(item_json).ok()?;
    let value = root.get(field_name);
    match value {
        None | Some(Value::Null) => Some(String::new()),
        Some(Value::Array(items)) => Some(
            items
                .iter()
                .map(|item| match item {
                    Value::Bool(flag) => {
                        if *flag {
                            "yes".to_owned()
                        } else {
                            "no".to_owned()
                        }
                    }
                    _ => value_to_text(item),
                })
                .collect::<Vec<_>>()
                .join(", "),
        ),
        Some(Value::Bool(flag)) => Some(if *flag { "yes" } else { "no" }.to_owned()),
        Some(value) => Some(value_to_text(value)),
    }
}

/// Performs value to text.
fn value_to_text(value: &Value) -> String {
    match value {
        Value::Null => String::new(),
        Value::String(text) => text.clone(),
        Value::Bool(flag) => flag.to_string(),
        Value::Number(number) => number.to_string(),
        _ => serde_json::to_string(value).unwrap_or_default(),
    }
}

/// Renders UI element HTML.
fn render_ui_element_html(
    app_root: &Path,
    element_type: &str,
    input_type: Option<&str>,
    id: &str,
    name: &str,
    label: &str,
    value: &str,
    options_html: &str,
) -> Option<String> {
    let params = super::ui::ui_render_param_map(
        id,
        input_type,
        Some(if element_type == "button" {
            "submit"
        } else {
            "button"
        }),
        name,
        label,
        label,
        value,
        None,
        None,
        "",
        options_html,
        "",
        value,
        element_type,
    )?;
    let fragment_path = match element_type {
        "select" => "templates/shared/fragments/ui_select.html",
        "textarea" => "templates/shared/fragments/ui_textarea.html",
        "checkbox" => "templates/shared/fragments/ui_checkbox.html",
        _ => "templates/shared/fragments/ui_input.html",
    };
    generated::render_generated_admin_fragment_from_value_runtime(app_root, fragment_path, &params)
}

/// Renders select options from one generated-surface field declaration.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::generated_surface_select_options_html`].
/// - `field_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_select_options_html`].
/// - `selected_value`: Input consumed by [`crate::runtime::json_commands::generated_surface_select_options_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_select_options_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_select_options_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_select_options_html(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_select_options_html(
    app_root: &Path,
    field_json: &str,
    selected_value: Option<&str>,
) -> Option<String> {
    if app_root.as_os_str().is_empty() {
        return None;
    }
    let field = serde_json::from_str::<Value>(field_json).ok()?;
    let mut out = String::new();
    let mut selected_found = false;
    for option in field.get("options").and_then(Value::as_array)? {
        let value = option
            .get("value")
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .or_else(|| option.get("id").map(value_to_text))
            .or_else(|| option.get("name").map(value_to_text))?;
        let label = option
            .get("label")
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .or_else(|| option.get("name").map(value_to_text))
            .unwrap_or_else(|| value.clone());
        let selected = selected_value == Some(value.as_str());
        selected_found |= selected;
        out.push_str(&render_fragment_with_params(
            app_root,
            "templates/shared/fragments/select_option.html",
            serde_json::Map::from_iter([
                ("option_value".to_owned(), Value::String(value)),
                (
                    "selected_attr".to_owned(),
                    Value::String(if selected { " selected" } else { "" }.to_owned()),
                ),
                ("option_label".to_owned(), Value::String(label)),
            ]),
        )?);
    }
    if !selected_found && let Some(selected) = selected_value.filter(|value| !value.is_empty()) {
        out.push_str(&render_fragment_with_params(
            app_root,
            "templates/shared/fragments/select_option.html",
            serde_json::Map::from_iter([
                (
                    "option_value".to_owned(),
                    Value::String(selected.to_owned()),
                ),
                (
                    "selected_attr".to_owned(),
                    Value::String(" selected".to_owned()),
                ),
                (
                    "option_label".to_owned(),
                    Value::String(selected.to_owned()),
                ),
            ]),
        )?);
    }
    Some(out)
}

/// Renders generated-surface filter controls from a query string and declaration.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::generated_surface_filter_controls_html`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_filter_controls_html`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::generated_surface_filter_controls_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_filter_controls_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_filter_controls_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_filter_controls_html(std::path::Path::new("apps/dev_docs"), "{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_filter_controls_html(
    app_root: &Path,
    surface_json: &str,
    raw_query: &str,
) -> Option<String> {
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let mut out = String::new();
    for filter in surface.get("filters").and_then(Value::as_array)? {
        let query = filter
            .get("query")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let field = filter.get("field").and_then(Value::as_str).unwrap_or(query);
        if query.is_empty() {
            continue;
        }
        let label = filter
            .get("label")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .unwrap_or(if field.is_empty() { query } else { field });
        let match_kind = filter
            .get("match")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .unwrap_or("exact");
        let value = request_query_value(raw_query, query)
            .filter(|value| !value.is_empty())
            .or_else(|| filter.get("default").map(value_to_text))
            .unwrap_or_default();
        let options = if match_kind == "boolean" {
            render_fragment_with_params(
                app_root,
                "templates/shared/fragments/boolean_filter_options.html",
                serde_json::Map::from_iter([
                    (
                        "selected_true_attr".to_owned(),
                        Value::String(
                            if value.is_empty() || value == "true" {
                                " selected"
                            } else {
                                ""
                            }
                            .to_owned(),
                        ),
                    ),
                    (
                        "selected_false_attr".to_owned(),
                        Value::String(if value == "false" { " selected" } else { "" }.to_owned()),
                    ),
                    (
                        "selected_all_attr".to_owned(),
                        Value::String(if value == "all" { " selected" } else { "" }.to_owned()),
                    ),
                ]),
            )?
        } else {
            let mut html = render_fragment_with_params(
                app_root,
                "templates/shared/fragments/select_option.html",
                serde_json::Map::from_iter([
                    ("option_value".to_owned(), Value::String(String::new())),
                    (
                        "selected_attr".to_owned(),
                        Value::String(if value.is_empty() { " selected" } else { "" }.to_owned()),
                    ),
                    ("option_label".to_owned(), Value::String("All".to_owned())),
                ]),
            )?;
            html.push_str(&generated_surface_select_options_html(
                app_root,
                &serde_json::to_string(filter).ok()?,
                Some(&value),
            )?);
            html
        };
        let element = if match_kind == "boolean" || filter.get("options").is_some() {
            "select"
        } else {
            "input"
        };
        let html = render_ui_element_html(
            app_root,
            element,
            Some(if match_kind == "array_contains_integer" {
                "number"
            } else {
                "text"
            }),
            query,
            query,
            label,
            &value,
            &options,
        )?;
        out.push_str(&html);
    }
    Some(out)
}

/// Renders generated-surface sort options using the native selected-sort rules.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::generated_surface_sort_options_html`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_sort_options_html`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::generated_surface_sort_options_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_sort_options_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_sort_options_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_sort_options_html(std::path::Path::new("apps/dev_docs"), "{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_sort_options_html(
    app_root: &Path,
    surface_json: &str,
    raw_query: &str,
) -> Option<String> {
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let current = request_query_value(raw_query, "sort")
        .filter(|value| !value.is_empty())
        .or_else(|| {
            surface
                .get("default_sort")
                .and_then(Value::as_str)
                .map(ToOwned::to_owned)
        })
        .unwrap_or_default();
    let mut out = String::new();
    for sort in surface.get("sorts").and_then(Value::as_array)? {
        let key = sort.get("key").and_then(Value::as_str).unwrap_or_default();
        if key.is_empty() {
            continue;
        }
        let label = sort
            .get("label")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .unwrap_or(key);
        out.push_str(&render_fragment_with_params(
            app_root,
            "templates/shared/fragments/select_option.html",
            serde_json::Map::from_iter([
                ("option_value".to_owned(), Value::String(key.to_owned())),
                (
                    "selected_attr".to_owned(),
                    Value::String(if current == key { " selected" } else { "" }.to_owned()),
                ),
                ("option_label".to_owned(), Value::String(label.to_owned())),
            ]),
        )?);
    }
    Some(out)
}

/// Performs state option i64.
fn state_option_i64(options: &Value, key: &str, default_value: i64) -> i64 {
    options
        .get(key)
        .and_then(|value| match value {
            Value::Number(number) => number.as_i64(),
            Value::String(text) => text.parse::<i64>().ok(),
            _ => None,
        })
        .unwrap_or(default_value)
}

/// Performs state option string.
fn state_option_string<'a>(options: &'a Value, key: &str) -> Option<&'a str> {
    options
        .get(key)
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
}

/// Performs state rows.
fn state_rows<'a>(root: &'a Value, section: &str) -> &'a [Value] {
    root.get(section)
        .and_then(Value::as_array)
        .map(Vec::as_slice)
        .unwrap_or(&[])
}

/// Performs state row by ID.
fn state_row_by_id<'a>(root: &'a Value, section: &str, id: i64) -> Option<&'a Value> {
    (id > 0).then_some(())?;
    state_rows(root, section).iter().find(|row| {
        row.get("id").and_then(Value::as_i64) == Some(id)
            || row
                .get("id")
                .and_then(Value::as_str)
                .and_then(|value| value.parse::<i64>().ok())
                == Some(id)
    })
}

/// Performs state row by text.
fn state_row_by_text<'a>(
    root: &'a Value,
    section: &str,
    field: &str,
    wanted: &str,
) -> Option<&'a Value> {
    if field.is_empty() || wanted.is_empty() {
        return None;
    }
    state_rows(root, section)
        .iter()
        .find(|row| row.get(field).and_then(Value::as_str) == Some(wanted))
}

/// Performs state JSON or empty.
fn state_json_or_empty(value: Option<&Value>) -> String {
    value
        .and_then(|value| serde_json::to_string(value).ok())
        .unwrap_or_else(|| "{}".to_owned())
}

/// Performs state lines.
fn state_lines(rows: &[Value], field: &str) -> String {
    rows.iter()
        .filter_map(|row| row.get(field))
        .map(value_to_text)
        .filter(|value| !value.is_empty())
        .collect::<Vec<_>>()
        .join("\n")
}

/// Performs state next ID.
fn state_next_id(root: &Value, section: &str) -> i64 {
    state_rows(root, section)
        .iter()
        .filter_map(|row| row.get("id"))
        .filter_map(|value| {
            value
                .as_i64()
                .or_else(|| value.as_str()?.parse::<i64>().ok())
        })
        .max()
        .unwrap_or(0)
        + 1
}

/// Performs state active token.
fn state_active_token<'a>(
    root: &'a Value,
    section: &str,
    token_hash: &str,
    now_iso: &str,
) -> Option<&'a Value> {
    state_rows(root, section).iter().find(|row| {
        row.get("token_hash").and_then(Value::as_str) == Some(token_hash)
            && row
                .get("claimed_at")
                .is_none_or(|value| value.is_null() || value.as_str() == Some(""))
            && row
                .get("expires_at")
                .and_then(Value::as_str)
                .is_some_and(|expires| expires > now_iso)
    })
}

/// Performs state write.
fn state_write(root: &Value, state_path: &Path) -> Result<String, i32> {
    if generated::write_json_file(state_path, root) {
        Ok(String::new())
    } else {
        Err(69)
    }
}

/// Executes one state JSON command against the persisted runtime-state contract.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::state_named_command`].
/// - `name`: Input consumed by [`crate::runtime::json_commands::state_named_command`].
/// - `options_json`: Input consumed by [`crate::runtime::json_commands::state_named_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::json_commands::state_named_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::json_commands::state_named_command`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::state_named_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::state_named_command(todo!(), "name", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn state_named_command(
    state_path: &Path,
    name: &str,
    options_json: &str,
) -> Result<String, i32> {
    if state_path.as_os_str().is_empty() || name.is_empty() {
        return Err(64);
    }
    let mut root = read_json_file(state_path).ok_or(66)?;
    if !root.is_object() {
        return Err(66);
    }
    let options = if options_json.is_empty() {
        serde_json::json!({})
    } else {
        serde_json::from_str::<Value>(options_json).map_err(|_| 64)?
    };
    if !options.is_object() {
        return Err(64);
    }

    let id = |key: &str| state_option_i64(&options, key, 0);
    let text = |key: &str| state_option_string(&options, key).unwrap_or_default();
    let output_json = |value: Option<&Value>| Ok(state_json_or_empty(value));

    match name {
        "import-row-json-lines" => {
            let section = text("section");
            let rows = options.get("rows").and_then(Value::as_array).ok_or(64)?.clone();
            if section.is_empty() { return Err(64); }
            let target = root.as_object_mut().ok_or(66)?.entry(section.to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)?;
            target.extend(rows.into_iter().filter(Value::is_object));
            state_write(&root, state_path)
        }
        "business-json-by-slug" => output_json(generated::dynamic_find_business_by_slug(&root, text("slug"))),
        "business-id-by-slug" => Ok(state_row_by_text(&root, "businesses", "slug", text("slug"))
            .and_then(|row| row.get("id"))
            .map(value_to_text)
            .unwrap_or_else(|| "0".to_owned())),
        "tenant-id-for-business-slug" => {
            let business_id = state_row_by_text(&root, "businesses", "slug", text("slug"))
                .and_then(|row| row.get("id"))
                .and_then(|value| value.as_i64())
                .unwrap_or(0);
            Ok(super::business::tenant_id_for_business_base(&root, business_id).to_string())
        }
        "tenant-id-for-business-id" => Ok(super::business::tenant_id_for_business_base(&root, id("business_id")).to_string()),
        "tenant-id-for-service-id" => {
            let service_id = id("service_id");
            let business_id = state_row_by_id(&root, "services", service_id)
                .and_then(|row| row.get("business_id"))
                .and_then(Value::as_i64)
                .unwrap_or(0);
            Ok(super::business::tenant_id_for_business_base(&root, business_id).to_string())
        }
        "tenant-id-for-technician-id" => {
            let business_id = state_row_by_id(&root, "technicians", id("technician_id"))
                .and_then(|row| row.get("business_id"))
                .and_then(Value::as_i64)
                .unwrap_or(0);
            Ok(super::business::tenant_id_for_business_base(&root, business_id).to_string())
        }
        "appointment-json-by-id" => output_json(state_row_by_id(&root, "appointments", id("appointment_id"))),
        "service-json-by-id" => output_json(state_row_by_id(&root, "services", id("service_id"))),
        "service-duration-minutes" => Ok(state_row_by_id(&root, "services", id("service_id"))
            .and_then(|row| row.get("duration_minutes"))
            .map(value_to_text)
            .unwrap_or_else(|| "45".to_owned())),
        "user-json-by-id" => output_json(state_row_by_id(&root, "users", id("user_id"))),
        "user-json-by-username" => output_json(state_row_by_text(&root, "users", "username", text("username"))),
        "user-json-by-email" => output_json(state_rows(&root, "users").iter().find(|row| {
            row.get("email").and_then(Value::as_str).is_some_and(|email| email.eq_ignore_ascii_case(text("email")))
        })),
        "business-name-by-id" | "business-slug-by-id" | "business-time-format-by-id" => {
            let field = match name {
                "business-name-by-id" => "name",
                "business-slug-by-id" => "slug",
                _ => "time_format",
            };
            Ok(state_row_by_id(&root, "businesses", id("business_id"))
                .and_then(|row| row.get(field))
                .map(value_to_text)
                .unwrap_or_else(|| if field == "time_format" { "am_pm" } else { "" }.to_owned()))
        }
        "business-image-url-by-slug" => Ok(state_row_by_text(&root, "businesses", "slug", text("slug"))
            .and_then(|row| row.get("image_url"))
            .map(value_to_text)
            .unwrap_or_default()),
        "service-image-url-for-business" => Ok(state_rows(&root, "services").iter().find(|row| {
            row.get("id").and_then(Value::as_i64) == Some(id("service_id"))
                && row.get("business_id").and_then(Value::as_i64) == Some(id("business_id"))
        }).and_then(|row| row.get("image_url")).map(value_to_text).unwrap_or_default()),
        "service-json-for-business" => output_json(state_rows(&root, "services").iter().find(|row| {
            row.get("id").and_then(Value::as_i64) == Some(id("service_id"))
                && row.get("business_id").and_then(Value::as_i64) == Some(id("business_id"))
        })),
        "first-service-json-for-business" => output_json(state_rows(&root, "services").iter().filter(|row| {
            row.get("business_id").and_then(Value::as_i64) == Some(id("business_id"))
        }).min_by_key(|row| row.get("sort_order").and_then(Value::as_i64).unwrap_or_else(|| row.get("id").and_then(Value::as_i64).unwrap_or(i64::MAX)))),
        "service-sort-order-for-business" => Ok(state_rows(&root, "services").iter().find(|row| {
            row.get("id").and_then(Value::as_i64) == Some(id("service_id"))
                && row.get("business_id").and_then(Value::as_i64) == Some(id("business_id"))
        }).and_then(|row| row.get("sort_order")).map(value_to_text).unwrap_or_else(|| id("service_id").max(1).to_string())),
        "business-availability-json-for-business" => output_json(state_rows(&root, "business_availability").iter().find(|row| {
            row.get("id").and_then(Value::as_i64) == Some(id("availability_id"))
                && row.get("business_id").and_then(Value::as_i64) == Some(id("business_id"))
        })),
        "technician-json-for-business" => output_json(state_rows(&root, "technicians").iter().find(|row| {
            row.get("id").and_then(Value::as_i64) == Some(id("technician_id"))
                && row.get("business_id").and_then(Value::as_i64) == Some(id("business_id"))
        })),
        "booking-json-for-user" => output_json(state_rows(&root, "bookings").iter().find(|row| {
            row.get("id").and_then(Value::as_i64) == Some(id("booking_id"))
                && row.get("user_id").and_then(Value::as_i64) == Some(id("user_id"))
        })),
        "service-booking-options-array-json" => Ok(state_row_by_id(&root, "services", id("service_id"))
            .and_then(|row| row.get("booking_options"))
            .and_then(|value| serde_json::to_string(value).ok())
            .unwrap_or_else(|| "[]".to_owned())),
        "service-booking-options-json" => {
            let service = state_row_by_id(&root, "services", id("service_id"));
            let mut rows = Vec::new();
            if let Some(service) = service {
                rows.push(serde_json::json!({
                    "label": service.get("name").cloned().unwrap_or(Value::String(String::new())),
                    "duration_minutes": service.get("duration_minutes").cloned().unwrap_or(Value::Number(45.into())),
                    "cost": service.get("cost").cloned().unwrap_or(Value::String(String::new())),
                }));
                if let Some(options) = service.get("booking_options").and_then(Value::as_array) {
                    rows.extend(options.iter().cloned());
                }
            }
            Ok(serde_json::to_string(&rows).unwrap_or_else(|_| "[]".to_owned()))
        }
        "service-selected-booking-option-json" => {
            let options = state_row_by_id(&root, "services", id("service_id"))
                .and_then(|row| row.get("booking_options"))
                .and_then(Value::as_array);
            let index = id("booking_option_index").max(0) as usize;
            output_json(options.and_then(|items| items.get(index).or_else(|| items.first())))
        }
        "active-email-verification-json" => output_json(state_active_token(&root, "email_verifications", text("token_hash"), text("now_iso"))),
        "active-password-reset-json" => output_json(state_active_token(&root, "password_resets", text("token_hash"), text("now_iso"))),
        "active-invite-json" => output_json(state_active_token(&root, "invites", text("token_hash"), text("now_iso"))),
        "active-session-json" => output_json(state_rows(&root, "sessions").iter().find(|row| {
            row.get("session_token_hash").and_then(Value::as_str) == Some(text("session_token_hash"))
                && row.get("revoked_at").is_none_or(|value| value.is_null() || value.as_str() == Some(""))
                && row.get("expires_at").and_then(Value::as_str).is_some_and(|expires| expires > text("now_iso"))
        })),
        "current-user-json" => {
            let user_id = state_rows(&root, "sessions").iter().find(|row| {
                row.get("session_token_hash").and_then(Value::as_str) == Some(text("session_token_hash"))
                    && row.get("revoked_at").is_none_or(|value| value.is_null() || value.as_str() == Some(""))
                    && row.get("expires_at").and_then(Value::as_str).is_some_and(|expires| expires > text("now_iso"))
            }).and_then(|row| row.get("user_id")).and_then(Value::as_i64).unwrap_or(0);
            output_json(state_row_by_id(&root, "users", user_id).filter(|row| row.get("is_active").and_then(Value::as_bool) != Some(false)))
        }
        "authenticate-user-json" => output_json(state_row_by_text(&root, "users", "username", text("username")).filter(|row| row.get("is_active").and_then(Value::as_bool) != Some(false))),
        "active-tenant-ids-lines" => Ok(state_lines(state_rows(&root, "tenants"), "id")),
        "user-membership-tenant-ids-json" => {
            let ids: Vec<Value> = state_rows(&root, "tenant_memberships").iter().filter(|row| {
                row.get("user_id").and_then(Value::as_i64) == Some(id("user_id"))
                    && !matches!(row.get("membership_status").and_then(Value::as_str), Some("disabled" | "revoked"))
            }).filter_map(|row| row.get("tenant_id").cloned()).collect();
            Ok(serde_json::to_string(&ids).unwrap_or_else(|_| "[]".to_owned()))
        }
        "next-id" => Ok(state_next_id(&root, text("section")).to_string()),
        "append-record" => {
            let section = text("section");
            let record = options.get("record_json").cloned().ok_or(64)?;
            if !record.is_object() || section.is_empty() { return Err(64); }
            let root_map = root.as_object_mut().ok_or(66)?;
            let rows = root_map.entry(section.to_owned()).or_insert_with(|| Value::Array(Vec::new()));
            rows.as_array_mut().ok_or(69)?.push(record);
            state_write(&root, state_path)
        }
        "update-record-by-id" => {
            let section = text("section");
            let record_id = id("record_id");
            let patch = options.get("patch_json").and_then(Value::as_object).ok_or(64)?.clone();
            let row = root.get_mut(section).and_then(Value::as_array_mut).and_then(|rows| rows.iter_mut().find(|row| row.get("id").and_then(Value::as_i64) == Some(record_id))).ok_or(66)?;
            let row_map = row.as_object_mut().ok_or(69)?;
            for (key, value) in patch { row_map.insert(key, value); }
            state_write(&root, state_path)
        }
        "remove-record-by-id" => {
            let section = text("section");
            let record_id = id("record_id");
            let rows = root.get_mut(section).and_then(Value::as_array_mut).ok_or(66)?;
            let before = rows.len();
            rows.retain(|row| row.get("id").and_then(Value::as_i64) != Some(record_id));
            if rows.len() == before { return Err(66); }
            state_write(&root, state_path)
        }
        "rate-limit-event-count" => {
            let count = state_rows(&root, "rate_limit_events").iter().filter(|row| {
                row.get("policy_key").and_then(Value::as_str) == Some(text("policy_key"))
                    && row.get("bucket_key").and_then(Value::as_str) == Some(text("bucket_key"))
                    && row.get("created_at").and_then(Value::as_str).is_some_and(|created| created >= text("window_start"))
                    && (text("ip_address").is_empty() || row.get("ip_address").and_then(Value::as_str) == Some(text("ip_address")))
            }).count();
            Ok(count.to_string())
        }
        "record-rate-limit-event" => {
            let event = serde_json::json!({
                "id": state_next_id(&root, "rate_limit_events"),
                "policy_key": text("policy_key"),
                "bucket_key": text("bucket_key"),
                "ip_address": if text("ip_address").is_empty() { Value::Null } else { Value::String(text("ip_address").to_owned()) },
                "outcome": text("outcome"),
                "created_at": text("created_at"),
            });
            root.as_object_mut().ok_or(66)?.entry("rate_limit_events".to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)?.push(event);
            state_write(&root, state_path)
        }
        "prune-rate-limit-events" => {
            let cutoff = text("cutoff_iso");
            root.as_object_mut().ok_or(66)?.entry("rate_limit_events".to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)?.retain(|row| row.get("created_at").and_then(Value::as_str).is_some_and(|created| created >= cutoff));
            state_write(&root, state_path)
        }
        "business-technician-ids-lines" => Ok(state_lines(&state_rows(&root, "technicians").iter().filter(|row| row.get("business_id").map(value_to_text).as_deref() == Some(id("business_id").to_string().as_str())).cloned().collect::<Vec<_>>(), "id")),
        "service-assigned-technician-ids-lines" => {
            let service = state_row_by_id(&root, "services", id("service_id"));
            let ids = service.and_then(|row| row.get("technician_ids")).and_then(Value::as_array).map(|items| items.iter().map(value_to_text).collect::<Vec<_>>().join("\n")).unwrap_or_default();
            Ok(ids)
        }
        "business-availability-lines" => Ok(state_rows(&root, "business_availability").iter().filter(|row| row.get("business_id").map(value_to_text).as_deref() == Some(id("business_id").to_string().as_str()) && (text("day_of_week").is_empty() || row.get("day_of_week").and_then(Value::as_str) == Some(text("day_of_week")))).map(|row| serde_json::to_string(row).unwrap_or_default()).collect::<Vec<_>>().join("\n")),
        "technician-availability-lines" => Ok(state_rows(&root, "technician_availability").iter().filter(|row| row.get("technician_id").map(value_to_text).as_deref() == Some(id("technician_id").to_string().as_str()) && (text("day_of_week").is_empty() || row.get("day_of_week").and_then(Value::as_str) == Some(text("day_of_week")))).map(|row| serde_json::to_string(row).unwrap_or_default()).collect::<Vec<_>>().join("\n")),
        "technician-appointments-lines" => Ok(state_rows(&root, "appointments").iter().filter(|row| row.get("technician_id").map(value_to_text).as_deref() == Some(id("technician_id").to_string().as_str()) && (text("date").is_empty() || row.get("date").and_then(Value::as_str) == Some(text("date")))).map(|row| serde_json::to_string(row).unwrap_or_default()).collect::<Vec<_>>().join("\n")),
        "public-business-cards-json" => Ok(serde_json::to_string(&state_rows(&root, "businesses").iter().map(|row| {
            serde_json::json!({ "id": row.get("id").cloned().unwrap_or(Value::Null), "slug": row.get("slug").cloned().unwrap_or(Value::String(String::new())), "name": row.get("name").cloned().unwrap_or(Value::String(String::new())), "image_url": row.get("image_url").cloned().unwrap_or(Value::String(String::new())) })
        }).collect::<Vec<_>>()).unwrap_or_else(|_| "[]".to_owned())),
        "manageable-business-cards-json" => {
            let tenant_ids = options.get("tenant_ids_json").and_then(Value::as_array).cloned().unwrap_or_default();
            let cards = state_rows(&root, "businesses").iter().filter(|business| {
                let business_id = business.get("id").map(value_to_text);
                let tenant_id = state_rows(&root, "tenants").iter().find(|tenant| tenant.get("source_business_id").map(value_to_text) == business_id).and_then(|tenant| tenant.get("id")).map(value_to_text);
                tenant_ids.iter().map(value_to_text).any(|wanted| tenant_id.as_deref() == Some(wanted.as_str())) || business.get("owner_id").map(value_to_text).as_deref() == Some(id("user_id").to_string().as_str())
            }).cloned().collect::<Vec<_>>();
            Ok(serde_json::to_string(&cards).unwrap_or_else(|_| "[]".to_owned()))
        }
        "managed-appointments-json" | "user-appointments-json" => {
            let rows = state_rows(&root, "appointments").iter().filter(|row| {
                if name == "user-appointments-json" { row.get("user_id").map(value_to_text).as_deref() == Some(id("user_id").to_string().as_str()) } else { true }
            }).cloned().collect::<Vec<_>>();
            Ok(serde_json::to_string(&rows).unwrap_or_else(|_| "[]".to_owned()))
        }
        "profile-page-json" => output_json(state_row_by_id(&root, "users", id("user_id"))),
        "appointments-page-json" => Ok(serde_json::to_string(&state_rows(&root, "appointments").iter().filter(|row| row.get("user_id").map(value_to_text).as_deref() == Some(id("user_id").to_string().as_str())).cloned().collect::<Vec<_>>()).unwrap_or_else(|_| "[]".to_owned())),
        "business-admin-service-rows-json" => Ok(serde_json::to_string(&state_rows(&root, "services").iter().filter(|row| row.get("business_id").map(value_to_text).as_deref() == Some(id("business_id").to_string().as_str())).cloned().collect::<Vec<_>>()).unwrap_or_else(|_| "[]".to_owned())),
        "business-admin-technician-rows-json" => Ok(serde_json::to_string(&state_rows(&root, "technicians").iter().filter(|row| row.get("business_id").map(value_to_text).as_deref() == Some(id("business_id").to_string().as_str())).cloned().collect::<Vec<_>>()).unwrap_or_else(|_| "[]".to_owned())),
        "event-stream-row-json-lines" => {
            let since_id = id("since_id");
            let limit = id("limit").clamp(1, 100) as usize;
            Ok(state_rows(&root, "event_stream").iter().filter(|row| row.get("id").map(value_to_text).and_then(|value| value.parse::<i64>().ok()).is_some_and(|value| value > since_id)).take(limit).map(|row| serde_json::to_string(row).unwrap_or_default()).collect::<Vec<_>>().join("\n"))
        }
        "append-audit-event" | "append-workflow-event" => {
            let section = if name == "append-audit-event" { "audit_log" } else { "workflow_execution_events" };
            let mut event = options.get("payload_json").cloned().filter(Value::is_object).unwrap_or_else(|| serde_json::json!({}));
            let object = event.as_object_mut().ok_or(69)?;
            if name == "append-audit-event" { object.insert("event".to_owned(), Value::String(text("event_kind").to_owned())); } else { object.insert("event_kind".to_owned(), Value::String(text("event_kind").to_owned())); object.insert("id".to_owned(), Value::Number(state_next_id(&root, section).into())); }
            object.insert("created_at".to_owned(), Value::String(text("created_at").to_owned()));
            root.as_object_mut().ok_or(66)?.entry(section.to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)?.push(event);
            state_write(&root, state_path)
        }
        "issue-browser-session" => {
            let event = serde_json::json!({ "id": state_next_id(&root, "sessions"), "user_id": id("user_id"), "session_token_hash": text("session_token_hash"), "session_kind": "browser_session", "current_tenant_id": Value::Null, "expires_at": text("expires_at"), "revoked_at": Value::Null, "created_at": text("created_at"), "user_agent": if text("user_agent").is_empty() { Value::Null } else { Value::String(text("user_agent").to_owned()) }, "ip_address": if text("ip_address").is_empty() { Value::Null } else { Value::String(text("ip_address").to_owned()) } });
            root.as_object_mut().ok_or(66)?.entry("sessions".to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)?.push(event);
            state_write(&root, state_path)
        }
        "revoke-session-hash" => {
            let hash = text("session_token_hash").to_owned();
            for row in root.as_object_mut().ok_or(66)?.entry("sessions".to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)? {
                if row.get("session_token_hash").and_then(Value::as_str) == Some(hash.as_str()) && row.get("revoked_at").is_none_or(|value| value.is_null() || value.as_str() == Some("")) { row.as_object_mut().ok_or(69)?.insert("revoked_at".to_owned(), Value::String(text("revoked_at").to_owned())); }
            }
            state_write(&root, state_path)
        }
        "issue-email-verification" | "issue-password-reset" => {
            let section = if name == "issue-email-verification" { "email_verifications" } else { "password_resets" };
            let user_id = id("user_id");
            let next_id = state_next_id(&root, section);
            let token_hash = text("token_hash").to_owned();
            let expires_at = text("expires_at").to_owned();
            let created_at = text("created_at").to_owned();
            let rows = root.as_object_mut().ok_or(66)?.entry(section.to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)?;
            rows.retain(|row| row.get("user_id").map(value_to_text).and_then(|value| value.parse::<i64>().ok()) != Some(user_id) || !row.get("claimed_at").is_none_or(|value| value.is_null() || value.as_str() == Some("")));
            rows.push(serde_json::json!({ "id": next_id, "user_id": user_id, "token_hash": token_hash, "expires_at": expires_at, "claimed_at": Value::Null, "created_at": created_at }));
            state_write(&root, state_path)
        }
        "claim-email-verification" => {
            let verification_id = id("verification_id");
            for row in root.as_object_mut().ok_or(66)?.entry("email_verifications".to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)? { if row.get("id").map(value_to_text).and_then(|value| value.parse::<i64>().ok()) == Some(verification_id) { row.as_object_mut().ok_or(69)?.insert("claimed_at".to_owned(), Value::String(text("claimed_at").to_owned())); } }
            if let Some(user) = state_row_by_id(&root, "users", id("user_id")).cloned() { let _ = user; }
            state_write(&root, state_path)
        }
        "issue-invite" => {
            let email = text("email").to_owned();
            let kind = text("invite_kind").to_owned();
            let next_id = state_next_id(&root, "invites");
            let account_type = text("account_type").to_owned();
            let token_hash = text("token_hash").to_owned();
            let expires_at = text("expires_at").to_owned();
            let created_at = text("created_at").to_owned();
            let rows = root.as_object_mut().ok_or(66)?.entry("invites".to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)?;
            rows.retain(|row| !(row.get("email").and_then(Value::as_str).is_some_and(|value| value.eq_ignore_ascii_case(&email)) && row.get("invite_kind").and_then(Value::as_str) == Some(kind.as_str()) && row.get("claimed_at").is_none_or(|value| value.is_null() || value.as_str() == Some(""))));
            rows.push(serde_json::json!({ "id": next_id, "email": email, "account_type": account_type, "invite_kind": kind, "token_hash": token_hash, "expires_at": expires_at, "claimed_at": Value::Null, "created_at": created_at, "target_tenant_id": if id("target_tenant_id") > 0 { Value::Number(id("target_tenant_id").into()) } else { Value::Null }, "role_hint": if text("role_hint").is_empty() { Value::Null } else { Value::String(text("role_hint").to_owned()) }, "invited_by_user_id": if id("invited_by_user_id") > 0 { Value::Number(id("invited_by_user_id").into()) } else { Value::Null }, "accepted_user_id": Value::Null }));
            state_write(&root, state_path)
        }
        "claim-invite" => {
            let invite_id = id("invite_id");
            for row in root.as_object_mut().ok_or(66)?.entry("invites".to_owned()).or_insert_with(|| Value::Array(Vec::new())).as_array_mut().ok_or(69)? { if row.get("id").map(value_to_text).and_then(|value| value.parse::<i64>().ok()) == Some(invite_id) { let object = row.as_object_mut().ok_or(69)?; object.insert("accepted_user_id".to_owned(), Value::Number(id("accepted_user_id").into())); object.insert("claimed_at".to_owned(), Value::String(text("claimed_at").to_owned())); } }
            state_write(&root, state_path)
        }
        "business-open-for-slot" => {
            let business_id = id("business_id");
            let day = text("date");
            let open = state_rows(&root, "business_availability").iter().any(|row| row.get("business_id").map(value_to_text).as_deref() == Some(business_id.to_string().as_str()) && (day.is_empty() || row.get("date").and_then(Value::as_str).is_none_or(|value| value == day)));
            Ok(if open { "1" } else { "0" }.to_owned())
        }
        "technician-booked-for-slot" => {
            let booked = state_rows(&root, "appointments").iter().any(|row| row.get("technician_id").map(value_to_text).as_deref() == Some(id("technician_id").to_string().as_str()) && row.get("date").and_then(Value::as_str) == Some(text("date")) && row.get("time").and_then(Value::as_str) == Some(text("time")));
            Ok(if booked { "1" } else { "0" }.to_owned())
        }
        "assign-technician-for-slot" => {
            let selected = state_rows(&root, "technicians").iter().find(|technician| {
                technician.get("business_id").map(value_to_text).as_deref() == Some(id("business_id").to_string().as_str()) && !state_rows(&root, "appointments").iter().any(|appointment| appointment.get("technician_id").map(value_to_text) == technician.get("id").map(value_to_text) && appointment.get("date").and_then(Value::as_str) == Some(text("date")) && appointment.get("time").and_then(Value::as_str) == Some(text("time")))
            });
            Ok(selected.and_then(|row| row.get("id")).map(value_to_text).unwrap_or_else(|| "0".to_owned()))
        }
        "google-calendar-connection-for-business" => output_json(state_rows(&root, "google_calendar_connections").iter().find(|row| row.get("business_id").map(value_to_text).as_deref() == Some(id("business_id").to_string().as_str()))),
        "business-dashboard-page-json" | "explore-page-json" | "business-admin-page-json" => {
            let slug = text("slug");
            let business = if slug.is_empty() { None } else { state_row_by_text(&root, "businesses", "slug", slug) };
            Ok(serde_json::to_string(&serde_json::json!({
                "business": business,
                "businesses": state_rows(&root, "businesses"),
                "services": business.map(|row| state_rows(&root, "services").iter().filter(|service| service.get("business_id").map(value_to_text) == row.get("id").map(value_to_text)).cloned().collect::<Vec<_>>()).unwrap_or_default(),
                "technicians": business.map(|row| state_rows(&root, "technicians").iter().filter(|technician| technician.get("business_id").map(value_to_text) == row.get("id").map(value_to_text)).cloned().collect::<Vec<_>>()).unwrap_or_default(),
            })).unwrap_or_else(|_| "{}".to_owned()))
        }
        "business-public-page-json" | "business-edit-page-json" | "business-public-render-page-json" => output_json(state_row_by_text(&root, "businesses", "slug", text("slug"))),
        "service-edit-page-json" | "service-book-form-page-json" => output_json(state_row_by_id(&root, "services", id("service_id"))),
        "business-calendar-page-json" | "business-calendar-render-page-json" => Ok(serde_json::to_string(&state_rows(&root, "appointments").iter().filter(|row| row.get("business_id").map(value_to_text).as_deref() == state_row_by_text(&root, "businesses", "slug", text("slug")).and_then(|business| business.get("id")).map(value_to_text).as_deref()).cloned().collect::<Vec<_>>()).unwrap_or_else(|_| "[]".to_owned())),
        "profile-render-page-json" => output_json(state_row_by_id(&root, "users", id("user_id"))),
        "service-visual-html" => service_visual_html(Path::new(text("app_root")), Some(text("image_url")), text("service_name"), Some(text("primary_color"))).ok_or(69),
        "service-sort-order-options-html" => service_sort_order_options_html(Path::new(text("app_root")), &root, id("business_id"), id("selected_order"), id("include_append") != 0).ok_or(69),
        "service-booking-options-editor-html" => service_booking_options_editor_html(Path::new(text("app_root")), &root, id("service_id")).ok_or(69),
        "service-technician-checkboxes-html" => technician_checkboxes_html(Path::new(text("app_root")), &root, id("business_id"), id("service_id"), text("empty_message"), false).ok_or(69),
        "business-technician-checkboxes-html" => technician_checkboxes_html(Path::new(text("app_root")), &root, id("business_id"), 0, text("empty_message"), true).ok_or(69),
        _ => Err(78),
    }
}

/// Performs generated surface context value.
fn generated_surface_context_value(surface: &Value, params: &Value) -> Option<(String, String)> {
    let binding = surface.get("context_binding")?;
    let param = binding
        .get("param")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())?;
    let value = params
        .get(param)
        .map(value_to_text)
        .filter(|value| !value.is_empty())?;
    Some((param.to_owned(), value))
}

/// Resolves generated-surface context, tenant scope, and context record metadata.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_context_json`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_context_json`].
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_context_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_context_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_context_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_context_json(todo!(), "{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_context_json(
    state_path: &Path,
    surface_json: &str,
    params_json: &str,
) -> Option<String> {
    let state = read_json_file(state_path)?;
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let params = serde_json::from_str::<Value>(params_json).ok()?;
    let binding = surface.get("context_binding");
    let Some((param, context_value)) = generated_surface_context_value(&surface, &params) else {
        return serde_json::to_string(&serde_json::json!({
            "ok": false,
            "error_code": "missing_context_parameter",
            "message": "Missing route parameter."
        }))
        .ok();
    };
    let state_collection = binding
        .and_then(|value| value.get("state_collection"))
        .and_then(Value::as_str)
        .unwrap_or("businesses");
    let match_field = binding
        .and_then(|value| value.get("match_field"))
        .and_then(Value::as_str)
        .unwrap_or("slug");
    let record = state_row_by_text(&state, state_collection, match_field, &context_value)?;
    let context_id_field = binding
        .and_then(|value| value.get("context_id_field"))
        .and_then(Value::as_str)
        .unwrap_or("id");
    let label_field = binding
        .and_then(|value| value.get("context_label_field"))
        .and_then(Value::as_str)
        .unwrap_or("name");
    let context_id = record.get(context_id_field).cloned().unwrap_or(Value::Null);
    let tenant_collection = binding
        .and_then(|value| value.get("tenant_collection"))
        .and_then(Value::as_str)
        .unwrap_or("tenants");
    let tenant_match_field = binding
        .and_then(|value| value.get("tenant_match_field"))
        .and_then(Value::as_str)
        .unwrap_or("source_business_id");
    let tenant_match_from = binding
        .and_then(|value| value.get("tenant_match_from_context_field"))
        .and_then(Value::as_str)
        .unwrap_or("id");
    let tenant_value = record
        .get(tenant_match_from)
        .map(value_to_text)
        .unwrap_or_default();
    let tenant_id = state_rows(&state, tenant_collection)
        .iter()
        .find(|row| {
            row.get(tenant_match_field).map(value_to_text).as_deref() == Some(tenant_value.as_str())
        })
        .and_then(|row| row.get("id"))
        .cloned()
        .unwrap_or(Value::Number(0.into()));
    let tenant_id_text = value_to_text(&tenant_id);
    serde_json::to_string(&serde_json::json!({
        "ok": true,
        "tenant_id": tenant_id,
        "tenant_scope": if tenant_id_text == "0" || tenant_id_text.is_empty() { "global".to_owned() } else { format!("tenant:{tenant_id_text}") },
        "context_id": context_id,
        "context_param": param,
        "context_value": context_value,
        "context_label": record.get(label_field).map(value_to_text).unwrap_or_default(),
        "record": record,
    })).ok()
}

/// Performs generated surface filter matches.
fn generated_surface_filter_matches(item: &Value, filter: &Value, raw_query: &str) -> bool {
    let query = filter
        .get("query")
        .and_then(Value::as_str)
        .unwrap_or_default();
    if query.is_empty() {
        return true;
    }
    let wanted =
        request_query_value(raw_query, query).or_else(|| filter.get("default").map(value_to_text));
    let Some(wanted) = wanted.filter(|value| !value.is_empty() && value != "all") else {
        return true;
    };
    let field = filter.get("field").and_then(Value::as_str).unwrap_or(query);
    let actual = item.get(field);
    match filter
        .get("match")
        .and_then(Value::as_str)
        .unwrap_or("exact")
    {
        "contains" => actual.map(value_to_text).is_some_and(|value| {
            value
                .to_ascii_lowercase()
                .contains(&wanted.to_ascii_lowercase())
        }),
        "boolean" => actual
            .map(value_to_text)
            .is_some_and(|value| value.eq_ignore_ascii_case(&wanted)),
        "array_contains_integer" => actual.and_then(Value::as_array).is_some_and(|values| {
            values
                .iter()
                .map(value_to_text)
                .any(|value| value == wanted)
        }),
        _ => actual
            .map(value_to_text)
            .is_some_and(|value| value == wanted),
    }
}

/// Builds a filtered, sorted, paginated generated-surface list result.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_list_result_json`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_list_result_json`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_list_result_json`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::generated_surface_list_result_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_list_result_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_list_result_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_list_result_json(todo!(), "{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_list_result_json(
    state_path: &Path,
    surface_json: &str,
    context_json: &str,
    raw_query: &str,
) -> Option<String> {
    let state = read_json_file(state_path)?;
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let context = serde_json::from_str::<Value>(context_json).ok()?;
    let collection = surface.get("entity_collection").and_then(Value::as_str)?;
    let scope_field = surface.get("scope_field").and_then(Value::as_str);
    let context_id = context
        .get("context_id")
        .map(value_to_text)
        .unwrap_or_default();
    let mut rows: Vec<Value> = state_rows(&state, collection)
        .iter()
        .filter(|row| {
            let scope_matches = scope_field
                .map(|field| {
                    row.get(field).map(value_to_text).as_deref() == Some(context_id.as_str())
                })
                .unwrap_or(true);
            scope_matches
                && surface
                    .get("filters")
                    .and_then(Value::as_array)
                    .map(|filters| {
                        filters
                            .iter()
                            .all(|filter| generated_surface_filter_matches(row, filter, raw_query))
                    })
                    .unwrap_or(true)
        })
        .cloned()
        .collect();
    let sort_key = request_query_value(raw_query, "sort").or_else(|| {
        surface
            .get("default_sort")
            .and_then(Value::as_str)
            .map(ToOwned::to_owned)
    });
    if let Some(sort_key) = sort_key.clone().filter(|value| !value.is_empty()) {
        let descending = sort_key.starts_with('-');
        let field = sort_key.trim_start_matches('-').to_owned();
        rows.sort_by(|left, right| {
            let ordering = value_to_text(left.get(&field).unwrap_or(&Value::Null))
                .cmp(&value_to_text(right.get(&field).unwrap_or(&Value::Null)));
            if descending {
                ordering.reverse()
            } else {
                ordering
            }
        });
    }
    let page = request_query_value(raw_query, "page")
        .and_then(|value| value.parse::<usize>().ok())
        .filter(|value| *value > 0)
        .unwrap_or(1);
    let page_default = surface
        .get("page_size_default")
        .and_then(Value::as_u64)
        .unwrap_or(25) as usize;
    let page_max = surface
        .get("page_size_max")
        .and_then(Value::as_u64)
        .unwrap_or(100) as usize;
    let page_size = request_query_value(raw_query, "page_size")
        .and_then(|value| value.parse::<usize>().ok())
        .filter(|value| *value > 0)
        .unwrap_or(page_default)
        .min(page_max);
    let total_items = rows.len();
    let start = page
        .saturating_sub(1)
        .saturating_mul(page_size)
        .min(total_items);
    let end = start.saturating_add(page_size).min(total_items);
    let response_fields = surface.get("response_fields").and_then(Value::as_array);
    let items: Vec<Value> = rows[start..end]
        .iter()
        .map(|row| {
            if let Some(fields) = response_fields {
                let mut object = serde_json::Map::new();
                for field in fields.iter().filter_map(Value::as_str) {
                    object.insert(
                        field.to_owned(),
                        row.get(field).cloned().unwrap_or(Value::Null),
                    );
                }
                Value::Object(object)
            } else {
                row.clone()
            }
        })
        .collect();
    serde_json::to_string(&serde_json::json!({
        "items": items,
        "pagination": { "page": page, "page_size": page_size, "total_items": total_items, "total_pages": if page_size == 0 { 1 } else { total_items.div_ceil(page_size) } },
        "sort": sort_key,
    })).ok()
}

/// Builds a default generated-surface candidate from existing, declared, and submitted values.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_default_candidate_json`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_default_candidate_json`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_default_candidate_json`].
/// - `existing_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_default_candidate_json`].
/// - `submitted_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_default_candidate_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_default_candidate_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_default_candidate_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_default_candidate_json(todo!(), "{}", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_default_candidate_json(
    state_path: &Path,
    surface_json: &str,
    context_json: &str,
    existing_json: Option<&str>,
    submitted_json: Option<&str>,
) -> Option<String> {
    let state = read_json_file(state_path)?;
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let context = serde_json::from_str::<Value>(context_json).ok()?;
    let mut candidate = serde_json::Map::new();
    for source in [existing_json, None] {
        if let Some(text) = source.filter(|value| !value.is_empty())
            && let Some(object) = serde_json::from_str::<Value>(text).ok()?.as_object()
        {
            candidate.extend(object.clone());
        }
    }
    if let Some(defaults) = surface.get("defaults").and_then(Value::as_object) {
        for (key, value) in defaults {
            candidate
                .entry(key.clone())
                .or_insert_with(|| value.clone());
        }
    }
    if let Some(text) = submitted_json.filter(|value| !value.is_empty())
        && let Some(object) = serde_json::from_str::<Value>(text).ok()?.as_object()
    {
        candidate.extend(object.clone());
    }
    if let Some(scope_field) = surface
        .get("scope_field")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        && let Some(context_id) = context.get("context_id")
    {
        candidate.insert(scope_field.to_owned(), context_id.clone());
    }
    if existing_json.is_none()
        && let (Some(sequence_field), Some(collection)) = (
            surface.get("auto_sequence_field").and_then(Value::as_str),
            surface.get("entity_collection").and_then(Value::as_str),
        )
    {
        let scope_field = surface.get("scope_field").and_then(Value::as_str);
        let context_id = context
            .get("context_id")
            .map(value_to_text)
            .unwrap_or_default();
        let next = state_rows(&state, collection)
            .iter()
            .filter(|row| {
                scope_field
                    .map(|field| {
                        row.get(field).map(value_to_text).as_deref() == Some(context_id.as_str())
                    })
                    .unwrap_or(true)
            })
            .filter_map(|row| {
                row.get(sequence_field)
                    .map(value_to_text)
                    .and_then(|value| value.parse::<i64>().ok())
            })
            .max()
            .unwrap_or(0)
            + 1;
        candidate.insert(sequence_field.to_owned(), Value::Number(next.into()));
    }
    generated::generated_surface_coerce_candidate_json(
        &surface,
        &serde_json::to_string(&candidate).ok()?,
    )
    .or_else(|| serde_json::to_string(&candidate).ok())
}

/// Renders generated-surface form controls from the app-owned form declaration.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::generated_surface_form_fields_html`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_form_fields_html`].
/// - `fixture_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_form_fields_html`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_form_fields_html`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_form_fields_html`].
/// - `item_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_form_fields_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_form_fields_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_form_fields_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_form_fields_html(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), "{}", todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_form_fields_html(
    app_root: &Path,
    state_path: &Path,
    fixture_path: &Path,
    surface_json: &str,
    context_json: &str,
    item_json: Option<&str>,
) -> Option<String> {
    let _state = read_json_file(state_path)?;
    let fixture = read_json_file(fixture_path)?;
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let _context = serde_json::from_str::<Value>(context_json).ok()?;
    let item = item_json
        .filter(|value| !value.is_empty())
        .and_then(|value| serde_json::from_str::<Value>(value).ok())
        .unwrap_or_else(|| serde_json::json!({}));
    let form_id = surface.get("form_id").and_then(Value::as_str)?;
    let form = fixture
        .get("forms")
        .and_then(Value::as_array)?
        .iter()
        .find(|form| form.get("form_id").and_then(Value::as_str) == Some(form_id))?;
    let mut out = String::new();
    for field in form.get("fields").and_then(Value::as_array)? {
        let field_id = field
            .get("field_id")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())?;
        let widget = field
            .get("widget")
            .and_then(Value::as_str)
            .unwrap_or("text");
        let label = field
            .get("label")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .map(ToOwned::to_owned)
            .unwrap_or_else(|| generated_surface_label(field_id));
        let value = item.get(field_id).map(value_to_text).unwrap_or_default();
        let options = if widget == "select" {
            generated_surface_select_options_html(
                app_root,
                &serde_json::to_string(field).ok()?,
                Some(&value),
            )?
        } else {
            String::new()
        };
        out.push_str(&render_ui_element_html(
            app_root,
            if widget == "select" {
                "select"
            } else if widget == "textarea" {
                "textarea"
            } else if widget == "checkbox" {
                "checkbox"
            } else {
                "input"
            },
            Some(widget),
            field_id,
            field_id,
            &label,
            &value,
            &options,
        )?);
    }
    Some(out)
}

/// Renders relation checkbox options and the app-owned checkbox group fragment.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::generated_surface_relation_checkboxes_html`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_relation_checkboxes_html`].
/// - `relation_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_relation_checkboxes_html`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_relation_checkboxes_html`].
/// - `selected_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_relation_checkboxes_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_relation_checkboxes_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_relation_checkboxes_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_relation_checkboxes_html(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_relation_checkboxes_html(
    app_root: &Path,
    state_path: &Path,
    relation_json: &str,
    context_json: &str,
    selected_json: Option<&str>,
) -> Option<String> {
    let state = read_json_file(state_path)?;
    let relation = serde_json::from_str::<Value>(relation_json).ok()?;
    let context = serde_json::from_str::<Value>(context_json).ok()?;
    let selected = selected_json
        .and_then(|text| serde_json::from_str::<Value>(text).ok())
        .unwrap_or_else(|| Value::Array(Vec::new()));
    let relation_field = relation
        .get("field")
        .and_then(Value::as_str)
        .unwrap_or("relation");
    let collection = relation
        .get("related_collection")
        .and_then(Value::as_str)
        .unwrap_or_default();
    let scope_field = relation.get("related_scope_field").and_then(Value::as_str);
    let context_id = context
        .get("context_id")
        .map(value_to_text)
        .unwrap_or_default();
    let label_field = relation
        .get("label_field")
        .and_then(Value::as_str)
        .unwrap_or("name");
    let prefix = relation
        .get("form_checkbox_prefix")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .unwrap_or(relation_field);
    let mut options_html = String::new();
    for row in state_rows(&state, collection) {
        if !scope_field
            .map(|field| row.get(field).map(value_to_text).as_deref() == Some(context_id.as_str()))
            .unwrap_or(true)
        {
            continue;
        }
        let row_id = row
            .get("id")
            .map(value_to_text)
            .filter(|value| !value.is_empty())?;
        let row_label = row
            .get(label_field)
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| row_id.clone());
        let selected = selected
            .as_array()
            .map(|items| items.iter().map(value_to_text).any(|value| value == row_id))
            .unwrap_or(false);
        let params = super::ui::ui_render_param_map(
            &format!("{prefix}{row_id}"),
            Some("checkbox"),
            Some("button"),
            &format!("{prefix}{row_id}"),
            &row_label,
            &row_label,
            &row_id,
            Some(""),
            Some(""),
            if selected { " checked" } else { "" },
            "",
            "",
            &row_label,
            "checkbox",
        )?;
        options_html.push_str(
            &generated::render_generated_admin_fragment_from_value_runtime(
                app_root,
                "templates/shared/fragments/ui_checkbox.html",
                &params,
            )?,
        );
    }
    if options_html.is_empty() {
        options_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/shared/fragments/muted_text.html",
            serde_json::Map::from_iter([(
                "message".to_owned(),
                Value::String(
                    relation
                        .get("empty_options_text")
                        .and_then(Value::as_str)
                        .unwrap_or("No related records available.")
                        .to_owned(),
                ),
            )]),
        )?);
    }
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/ui_checkbox_group.html",
        serde_json::Map::from_iter([
            ("id".to_owned(), Value::String(relation_field.to_owned())),
            (
                "class_name".to_owned(),
                Value::String("form-group".to_owned()),
            ),
            (
                "label".to_owned(),
                Value::String(
                    relation
                        .get("label")
                        .and_then(Value::as_str)
                        .unwrap_or(relation_field)
                        .to_owned(),
                ),
            ),
            ("help_html".to_owned(), Value::String(String::new())),
            ("options_html".to_owned(), Value::String(options_html)),
        ]),
    )
}

/// Builds the generated-admin table fragments and column count.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_table_json`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_table_json`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_table_json`].
/// - `list_result_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_table_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_manage_table_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_manage_table_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_manage_table_json(std::path::Path::new("apps/dev_docs"), "{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_manage_table_json(
    app_root: &Path,
    surface_json: &str,
    context_json: &str,
    list_result_json: &str,
) -> Option<String> {
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let list = serde_json::from_str::<Value>(list_result_json).ok()?;
    let columns = surface
        .get("admin")
        .and_then(|value| value.get("list_columns"))
        .cloned()
        .or_else(|| surface.get("response_fields").cloned())
        .unwrap_or_else(|| Value::Array(Vec::new()));
    let mut header = String::new();
    if !generated::runtime_generated_surface_append_table_header_cells_html(
        &mut header,
        &columns,
        app_root,
    ) {
        return None;
    }
    let fields: Vec<String> = columns
        .as_array()
        .map(|items| {
            items
                .iter()
                .filter_map(|item| {
                    item.get("field")
                        .and_then(Value::as_str)
                        .or_else(|| item.as_str())
                })
                .map(ToOwned::to_owned)
                .collect()
        })
        .unwrap_or_default();
    let mut rows_html = String::new();
    for row in list.get("items").and_then(Value::as_array)? {
        let mut cells = String::new();
        for field in &fields {
            let field_value =
                html_escape_text(&value_to_text(row.get(field).unwrap_or(&Value::Null)));
            let cell = render_fragment_with_params(
                app_root,
                "templates/generated_admin/fragments/table_row_cell.html",
                serde_json::Map::from_iter([(
                    "field_value".to_owned(),
                    Value::String(field_value),
                )]),
            )?;
            cells.push_str(&cell);
        }
        rows_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/generated_admin/fragments/table_row.html",
            serde_json::Map::from_iter([
                ("cells_html".to_owned(), Value::String(cells)),
                ("action_cell_html".to_owned(), Value::String(String::new())),
            ]),
        )?);
    }
    let _ = context_json;
    serde_json::to_string(&serde_json::json!({ "header_html": header, "row_html": rows_html, "column_count": fields.len() })).ok()
}

/// Builds the generated-admin manage-page JSON contract.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_page_json`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_page_json`].
/// - `fixture_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_page_json`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_page_json`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_page_json`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::generated_surface_manage_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_manage_page_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_manage_page_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_manage_page_json(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), "{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_manage_page_json(
    app_root: &Path,
    state_path: &Path,
    fixture_path: &Path,
    surface_json: &str,
    context_json: &str,
    raw_query: &str,
) -> Option<String> {
    let list_result =
        generated_surface_list_result_json(state_path, surface_json, context_json, raw_query)?;
    let table =
        generated_surface_manage_table_json(app_root, surface_json, context_json, &list_result)?;
    let form_fields = generated_surface_form_fields_html(
        app_root,
        state_path,
        fixture_path,
        surface_json,
        context_json,
        None,
    )?;
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let context = serde_json::from_str::<Value>(context_json).ok()?;
    let path_for = |operation: &str| {
        let context_value = surface
            .get("context_binding")
            .and_then(|value| value.get("param"))
            .and_then(Value::as_str)
            .and_then(|param| context.get(param))
            .map(value_to_text);
        generated::runtime_generated_surface_operation_path(
            &surface,
            context_value.as_deref(),
            operation,
            None,
        )
        .unwrap_or_default()
    };
    serde_json::to_string(&serde_json::json!({
        "title": surface.get("admin").and_then(|value| value.get("manage_title")).and_then(Value::as_str).unwrap_or("Manage records"),
        "manage_path": path_for("manage"),
        "create_path": path_for("create"),
        "back_path": path_for("manage"),
        "list_result": serde_json::from_str::<Value>(&list_result).ok()?,
        "manage_table": serde_json::from_str::<Value>(&table).ok()?,
        "form_fields_html": form_fields,
        "filter_controls_html": generated_surface_filter_controls_html(app_root, surface_json, raw_query).unwrap_or_default(),
        "sort_options_html": generated_surface_sort_options_html(app_root, surface_json, raw_query).unwrap_or_default(),
    })).ok()
}

/// Renders the service visual using the app-owned image or badge fragment.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::service_visual_html`].
/// - `image_url`: Input consumed by [`crate::runtime::json_commands::service_visual_html`].
/// - `service_name`: Input consumed by [`crate::runtime::json_commands::service_visual_html`].
/// - `primary_color`: Input consumed by [`crate::runtime::json_commands::service_visual_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::service_visual_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::service_visual_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::service_visual_html(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn service_visual_html(
    app_root: &Path,
    image_url: Option<&str>,
    service_name: &str,
    primary_color: Option<&str>,
) -> Option<String> {
    if let Some(image_url) = image_url.filter(|value| !value.is_empty() && *value != "null") {
        return render_fragment_with_params(
            app_root,
            "templates/shared/fragments/visual_image.html",
            serde_json::Map::from_iter([
                (
                    "wrapper_class".to_owned(),
                    Value::String("service-visual service-visual-image".to_owned()),
                ),
                ("image_url".to_owned(), Value::String(image_url.to_owned())),
                (
                    "image_alt".to_owned(),
                    Value::String(service_name.to_owned()),
                ),
            ]),
        );
    }
    let initials = dynamic_service_abbreviation(service_name);
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/visual_badge.html",
        serde_json::Map::from_iter([
            (
                "wrapper_class".to_owned(),
                Value::String("service-visual service-visual-badge".to_owned()),
            ),
            (
                "style_attr".to_owned(),
                Value::String(format!(
                    "background:{};color:#fff;",
                    primary_color
                        .filter(|value| !value.is_empty())
                        .unwrap_or("#2563eb")
                )),
            ),
            (
                "text_value".to_owned(),
                Value::String(if initials.is_empty() {
                    "XX".to_owned()
                } else {
                    initials
                }),
            ),
        ]),
    )
}

/// Renders service sort-order options through the shared select-option fragment.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::service_sort_order_options_html`].
/// - `state_root`: Input consumed by [`crate::runtime::json_commands::service_sort_order_options_html`].
/// - `business_id`: Input consumed by [`crate::runtime::json_commands::service_sort_order_options_html`].
/// - `selected_order`: Input consumed by [`crate::runtime::json_commands::service_sort_order_options_html`].
/// - `include_append`: Input consumed by [`crate::runtime::json_commands::service_sort_order_options_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::service_sort_order_options_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::service_sort_order_options_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::service_sort_order_options_html(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn service_sort_order_options_html(
    app_root: &Path,
    state_root: &Value,
    business_id: i64,
    selected_order: i64,
    include_append: bool,
) -> Option<String> {
    let count = state_rows(state_root, "services")
        .iter()
        .filter(|row| {
            row.get("business_id")
                .map(value_to_text)
                .and_then(|value| value.parse::<i64>().ok())
                == Some(business_id)
                && row
                    .get("is_active")
                    .and_then(Value::as_bool)
                    .unwrap_or(true)
        })
        .count() as i64;
    let max_order = if include_append { count + 1 } else { count }.max(1);
    let selected = if selected_order > 0 && selected_order <= max_order {
        selected_order
    } else {
        max_order
    };
    let mut out = String::new();
    for order in 1..=max_order {
        out.push_str(&render_fragment_with_params(
            app_root,
            "templates/shared/fragments/select_option.html",
            serde_json::Map::from_iter([
                ("option_value".to_owned(), Value::String(order.to_string())),
                (
                    "selected_attr".to_owned(),
                    Value::String(if order == selected { " selected" } else { "" }.to_owned()),
                ),
                ("option_label".to_owned(), Value::String(order.to_string())),
            ]),
        )?);
    }
    Some(out)
}

/// Renders the booking-option editor from one service state record.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::service_booking_options_editor_html`].
/// - `state_root`: Input consumed by [`crate::runtime::json_commands::service_booking_options_editor_html`].
/// - `service_id`: Input consumed by [`crate::runtime::json_commands::service_booking_options_editor_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::service_booking_options_editor_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::service_booking_options_editor_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::service_booking_options_editor_html(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn service_booking_options_editor_html(
    app_root: &Path,
    state_root: &Value,
    service_id: i64,
) -> Option<String> {
    let options = state_row_by_id(state_root, "services", service_id)
        .and_then(|row| row.get("booking_options"))
        .and_then(Value::as_array)
        .cloned()
        .unwrap_or_default();
    let mut rows_html = String::new();
    for (index, option) in options.iter().enumerate() {
        rows_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/service_booking_option_row.html",
            serde_json::Map::from_iter([
                (
                    "option_index".to_owned(),
                    Value::String((index + 1).to_string()),
                ),
                (
                    "label_value".to_owned(),
                    Value::String(option.get("label").map(value_to_text).unwrap_or_default()),
                ),
                (
                    "duration_value".to_owned(),
                    Value::String(
                        option
                            .get("duration_minutes")
                            .map(value_to_text)
                            .unwrap_or_else(|| "45".to_owned()),
                    ),
                ),
                (
                    "cost_value".to_owned(),
                    Value::String(option.get("cost").map(value_to_text).unwrap_or_default()),
                ),
            ]),
        )?);
    }
    render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/service_booking_options_editor.html",
        serde_json::Map::from_iter([
            (
                "option_count".to_owned(),
                Value::String(options.len().to_string()),
            ),
            (
                "option_count_text".to_owned(),
                Value::String(options.len().to_string()),
            ),
            ("option_rows_html".to_owned(), Value::String(rows_html)),
        ]),
    )
}

/// Renders technician assignment checkbox fragments for one business/service.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::technician_checkboxes_html`].
/// - `state_root`: Input consumed by [`crate::runtime::json_commands::technician_checkboxes_html`].
/// - `business_id`: Input consumed by [`crate::runtime::json_commands::technician_checkboxes_html`].
/// - `service_id`: Input consumed by [`crate::runtime::json_commands::technician_checkboxes_html`].
/// - `empty_message`: Input consumed by [`crate::runtime::json_commands::technician_checkboxes_html`].
/// - `select_all`: Input consumed by [`crate::runtime::json_commands::technician_checkboxes_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::technician_checkboxes_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::technician_checkboxes_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::technician_checkboxes_html(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn technician_checkboxes_html(
    app_root: &Path,
    state_root: &Value,
    business_id: i64,
    service_id: i64,
    empty_message: &str,
    select_all: bool,
) -> Option<String> {
    let assigned = state_row_by_id(state_root, "services", service_id)
        .and_then(|row| row.get("technician_ids"))
        .and_then(Value::as_array)
        .cloned()
        .unwrap_or_default();
    let mut out = String::new();
    for technician in state_rows(state_root, "technicians").iter().filter(|row| {
        row.get("business_id")
            .map(value_to_text)
            .and_then(|value| value.parse::<i64>().ok())
            == Some(business_id)
            && row.get("is_active").and_then(Value::as_bool) != Some(false)
    }) {
        let id = technician.get("id").map(value_to_text).unwrap_or_default();
        let checked = select_all || assigned.iter().map(value_to_text).any(|value| value == id);
        let technician_name = technician
            .get("name")
            .map(value_to_text)
            .unwrap_or_default();
        let label_html = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/ui_label_technician_assignment.html",
            serde_json::Map::from_iter([(
                "technician_name".to_owned(),
                Value::String(technician_name.clone()),
            )]),
        )?;
        let technician_assignment_checkbox_ui_html = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/ui_checkbox.html",
            serde_json::Map::from_iter([
                ("id".to_owned(), Value::String(format!("technician-{id}"))),
                ("name".to_owned(), Value::String(format!("technician_{id}"))),
                ("class_name".to_owned(), Value::String(String::new())),
                ("value".to_owned(), Value::String(id)),
                ("label_class".to_owned(), Value::String(String::new())),
                (
                    "attributes_html".to_owned(),
                    Value::String(if checked { " checked" } else { "" }.to_owned()),
                ),
                ("label_html".to_owned(), Value::String(label_html)),
                ("help_html".to_owned(), Value::String(String::new())),
            ]),
        )?;
        out.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/technician_checkbox.html",
            serde_json::Map::from_iter([(
                "technician_assignment_checkbox_ui_html".to_owned(),
                Value::String(technician_assignment_checkbox_ui_html),
            )]),
        )?);
    }
    if out.is_empty() {
        render_fragment_with_params(
            app_root,
            "templates/shared/fragments/muted_text.html",
            serde_json::Map::from_iter([(
                "message".to_owned(),
                Value::String(empty_message.to_owned()),
            )]),
        )
    } else {
        Some(out)
    }
}

/// Builds the generated-admin edit-page JSON contract for one existing item.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::generated_surface_edit_page_json`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_edit_page_json`].
/// - `fixture_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_edit_page_json`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_edit_page_json`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_edit_page_json`].
/// - `item_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_edit_page_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_edit_page_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_edit_page_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_edit_page_json(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), "{}", todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_edit_page_json(
    app_root: &Path,
    state_path: &Path,
    fixture_path: &Path,
    surface_json: &str,
    context_json: &str,
    item_json: &str,
) -> Option<String> {
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let context = serde_json::from_str::<Value>(context_json).ok()?;
    let item = serde_json::from_str::<Value>(item_json).ok()?;
    let identity_field = surface
        .get("identity_field")
        .and_then(Value::as_str)
        .unwrap_or("id");
    let identity = item
        .get(identity_field)
        .map(value_to_text)
        .unwrap_or_default();
    let context_value = surface
        .get("context_binding")
        .and_then(|value| value.get("param"))
        .and_then(Value::as_str)
        .and_then(|param| context.get(param))
        .map(value_to_text);
    let form_fields = generated_surface_form_fields_html(
        app_root,
        state_path,
        fixture_path,
        surface_json,
        context_json,
        Some(item_json),
    )?;
    let title_field = surface
        .get("admin")
        .and_then(|value| value.get("item_title_field"))
        .and_then(Value::as_str)
        .unwrap_or("name");
    let title_value = generated_surface_display_value(item_json, title_field)
        .unwrap_or_else(|| format!("Record {identity}"));
    serde_json::to_string(&serde_json::json!({
        "title": format!("Edit {title_value}"),
        "manage_path": generated::runtime_generated_surface_operation_path(&surface, context_value.as_deref(), "manage", None).unwrap_or_default(),
        "update_path": generated::runtime_generated_surface_operation_path(&surface, context_value.as_deref(), "update", Some(&identity)).unwrap_or_default(),
        "form_fields_html": form_fields,
        "save_button_label": surface.get("admin").and_then(|value| value.get("save_button_label")).and_then(Value::as_str).unwrap_or("Save"),
        "delete_form_html": "",
    })).ok()
}

const MAX_TEXT_BYTES: usize = 2 * 1024 * 1024;
const MAX_STATE_ROWS_JSON: usize = 16 * 1024;
const MAX_OUTPUT_ROWS_JSON: usize = 4096;

/// Performs compact.
fn compact(value: &Value) -> Option<String> {
    let text = serde_json::to_string(value).ok()?;
    (text.len() <= MAX_TEXT_BYTES).then_some(text)
}

/// Returns compact JSON text for a JSON value.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::emit_compact_json_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_compact_json_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_compact_json_value("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_compact_json_value(value: &Value) -> Option<String> {
    compact(value)
}

/// Returns compact JSON text or an empty object for invalid input.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::emit_json_text`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::emit_json_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_json_text("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_json_text(value: &Value) -> String {
    compact(value).unwrap_or_else(|| "{}".to_owned())
}

/// Returns compact JSON text or an empty object for invalid serialized input.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::emit_json_or_empty`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::emit_json_or_empty`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_json_or_empty`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_json_or_empty("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_json_or_empty(text: &str) -> String {
    serde_json::from_str::<Value>(text)
        .ok()
        .and_then(|value| compact(&value))
        .unwrap_or_else(|| "{}".to_owned())
}

/// Serializes one string as a JSON string.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::emit_json_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_json_string`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_json_string("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_json_string(text: &str) -> Option<String> {
    compact(&Value::String(text.to_owned()))
}

/// Serializes one signed integer as JSON text.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::emit_long`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::emit_long`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_long("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_long(value: i64) -> String {
    value.to_string()
}

/// Serializes a boolean as the native numeric flag representation.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::emit_digit_bool`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::emit_digit_bool`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_digit_bool("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_digit_bool(value: bool) -> &'static str {
    if value { "1" } else { "0" }
}

/// Returns a bounded line with a trailing newline.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::emit_text_line`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_text_line`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_text_line`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_text_line("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_text_line(text: &str) -> Option<String> {
    if text.len() >= MAX_TEXT_BYTES || text.chars().any(char::is_control) {
        return None;
    }
    Some(format!("{text}\n"))
}

/// Adds a nullable string field to an object.
///
/// # Parameters
///
/// - `object`: Input consumed by [`crate::runtime::json_commands::add_json_string_or_null`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::add_json_string_or_null`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::add_json_string_or_null`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::add_json_string_or_null`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::add_json_string_or_null(todo!(), "key", "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn add_json_string_or_null(
    object: &mut Map<String, Value>,
    key: &str,
    value: Option<&str>,
) -> bool {
    if key.is_empty() {
        return false;
    }
    object.insert(
        key.to_owned(),
        value.map_or(Value::Null, |text| Value::String(text.to_owned())),
    );
    true
}

/// Returns an optional string field from JSON text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::json_option_value`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_option_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_option_value`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::json_option_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_option_value("{}", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_option_value(text: &str, key: &str) -> Option<String> {
    if key.is_empty() {
        return None;
    }
    serde_json::from_str::<Value>(text)
        .ok()?
        .get(key)
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
}

/// Compares one JSON field with exact text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::json_value_equals`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_value_equals`].
/// - `expected`: Input consumed by [`crate::runtime::json_commands::json_value_equals`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::json_value_equals`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_value_equals("{}", "key", "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_value_equals(text: &str, key: &str, expected: &str) -> bool {
    json_option_value(text, key).as_deref() == Some(expected)
}

/// Returns a JSON object field as text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::emit_object_string_field`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::emit_object_string_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_object_string_field`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_object_string_field("{}", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_object_string_field(text: &str, key: &str) -> Option<String> {
    json_option_value(text, key)
}

/// Returns a JSON value at a dotted object path.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::object_value_at_path`].
/// - `path`: Input consumed by [`crate::runtime::json_commands::object_value_at_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::object_value_at_path`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::object_value_at_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::object_value_at_path("{}", std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn object_value_at_path(text: &str, path: &str) -> Option<String> {
    if path.is_empty() {
        return None;
    }
    let mut value = serde_json::from_str::<Value>(text).ok()?;
    for segment in path.split('.') {
        if segment.is_empty() {
            return None;
        }
        value = value.get(segment)?.clone();
    }
    compact(&value)
}

/// Finds an array item by a string field.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::find_array_item_by_string_field`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::find_array_item_by_string_field`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::find_array_item_by_string_field`].
/// - `expected`: Input consumed by [`crate::runtime::json_commands::find_array_item_by_string_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::find_array_item_by_string_field`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::find_array_item_by_string_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::find_array_item_by_string_field("{}", "items", "field", "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn find_array_item_by_string_field(
    text: &str,
    section: &str,
    field: &str,
    expected: &str,
) -> Option<String> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    root.get(section)
        .and_then(Value::as_array)?
        .iter()
        .find(|item| item.get(field).and_then(Value::as_str) == Some(expected))
        .and_then(compact)
}

/// Finds a state user by numeric id.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::state_find_user_by_id`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::state_find_user_by_id`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::state_find_user_by_id`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::state_find_user_by_id`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::state_find_user_by_id("{}", 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn state_find_user_by_id(text: &str, user_id: i64) -> Option<String> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    root.get("users")
        .and_then(Value::as_array)?
        .iter()
        .find(|row| row.get("id").and_then(Value::as_i64) == Some(user_id))
        .and_then(compact)
}

/// Finds an appointment by numeric id.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::state_find_appointment_by_id`].
/// - `appointment_id`: Input consumed by [`crate::runtime::json_commands::state_find_appointment_by_id`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::state_find_appointment_by_id`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::state_find_appointment_by_id`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::state_find_appointment_by_id("{}", 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn state_find_appointment_by_id(text: &str, appointment_id: i64) -> Option<String> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    root.get("appointments")
        .and_then(Value::as_array)?
        .iter()
        .find(|row| row.get("id").and_then(Value::as_i64) == Some(appointment_id))
        .and_then(compact)
}

/// Finds a user by case-insensitive email.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::state_find_user_by_email`].
/// - `email`: Input consumed by [`crate::runtime::json_commands::state_find_user_by_email`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::state_find_user_by_email`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::state_find_user_by_email`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::state_find_user_by_email("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn state_find_user_by_email(text: &str, email: &str) -> Option<String> {
    let root = serde_json::from_str::<Value>(text).ok()?;
    root.get("users")
        .and_then(Value::as_array)?
        .iter()
        .find(|row| {
            row.get("email")
                .and_then(Value::as_str)
                .is_some_and(|value| value.eq_ignore_ascii_case(email))
        })
        .and_then(compact)
}

/// Finds a user by exact username.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::state_find_user_by_username`].
/// - `username`: Input consumed by [`crate::runtime::json_commands::state_find_user_by_username`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::state_find_user_by_username`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::state_find_user_by_username("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn state_find_user_by_username(text: &str, username: &str) -> Option<String> {
    find_array_item_by_string_field(text, "users", "username", username)
}

/// Adds an array field to an object if it is absent.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::ensure_mut_array_field`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::ensure_mut_array_field`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::ensure_mut_array_field`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::ensure_mut_array_field(std::path::Path::new("."), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn ensure_mut_array_field(root: &mut Map<String, Value>, key: &str) -> bool {
    if key.is_empty() {
        return false;
    }
    root.entry(key.to_owned())
        .or_insert_with(|| Value::Array(Vec::new()))
        .is_array()
}

/// Finds a multipart text field using the existing bounded multipart parser.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::multipart_find_part`].
/// - `body_path`: Input consumed by [`crate::runtime::json_commands::multipart_find_part`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::multipart_find_part`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::multipart_find_part`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::multipart_find_part(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn multipart_find_part(
    content_type: &str,
    body_path: &Path,
    field_name: &str,
) -> Option<String> {
    dynamic_multipart_extract_text(content_type, body_path, field_name)
}

/// Exports relational runtime state through the configured native adapter.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_runtime_state_export_json_runtime`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::dynamic_runtime_state_export_json_runtime`].
/// - `app_id`: Input consumed by [`crate::runtime::json_commands::dynamic_runtime_state_export_json_runtime`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_runtime_state_export_json_runtime`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_runtime_state_export_json_runtime(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_runtime_state_export_json_runtime(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    app_id: Option<&str>,
) -> Option<String> {
    dynamic_relational_runtime_export_json(app_root, runtime_conf_path, app_id)
}

/// Imports relational runtime state through the configured native adapter.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_runtime_state_import_json_runtime`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::dynamic_runtime_state_import_json_runtime`].
/// - `app_id`: Input consumed by [`crate::runtime::json_commands::dynamic_runtime_state_import_json_runtime`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::dynamic_runtime_state_import_json_runtime`].
/// - `expected_audit_count`: Input consumed by [`crate::runtime::json_commands::dynamic_runtime_state_import_json_runtime`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::dynamic_runtime_state_import_json_runtime`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_runtime_state_import_json_runtime(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_runtime_state_import_json_runtime(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    app_id: Option<&str>,
    state_path: &Path,
    expected_audit_count: Option<&str>,
) -> i32 {
    dynamic_relational_runtime_import_state(
        app_root,
        runtime_conf_path,
        app_id,
        state_path,
        expected_audit_count,
    )
}

/// Dispatches a named JSON command against a persisted state file.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::dispatch_json_command_entries`].
/// - `command`: Input consumed by [`crate::runtime::json_commands::dispatch_json_command_entries`].
/// - `options_json`: Input consumed by [`crate::runtime::json_commands::dispatch_json_command_entries`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::json_commands::dispatch_json_command_entries`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::json_commands::dispatch_json_command_entries`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dispatch_json_command_entries(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dispatch_json_command_entries(
    state_path: &Path,
    command: &str,
    options_json: &str,
) -> Result<String, i32> {
    state_named_command(state_path, command, options_json)
}

/// Dispatches the native JSON command surface without a shell bridge.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_json_command`].
/// - `command`: Input consumed by [`crate::runtime::json_commands::handle_json_command`].
/// - `options_json`: Input consumed by [`crate::runtime::json_commands::handle_json_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::json_commands::handle_json_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::json_commands::handle_json_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_json_command(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_json_command(
    state_path: &Path,
    command: &str,
    options_json: &str,
) -> Result<String, i32> {
    dispatch_json_command_entries(state_path, command, options_json)
}

/// Returns generated-surface list-column metadata.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_list_columns_runtime`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_list_columns_runtime`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_list_columns_runtime("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_list_columns_runtime(surface_json: &str) -> Option<String> {
    generated_surface_list_columns(surface_json)
}

/// Handles state named command.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_state_named_command`].
/// - `name`: Input consumed by [`crate::runtime::json_commands::handle_state_named_command`].
/// - `options_json`: Input consumed by [`crate::runtime::json_commands::handle_state_named_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::json_commands::handle_state_named_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::json_commands::handle_state_named_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_state_named_command(todo!(), "name", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_state_named_command(
    state_path: &Path,
    name: &str,
    options_json: &str,
) -> Result<String, i32> {
    state_named_command(state_path, name, options_json)
}

/// Handles file generated surface match command.
///
/// # Parameters
///
/// - `file_path`: Input consumed by [`crate::runtime::json_commands::handle_file_generated_surface_match_command`].
/// - `method`: Input consumed by [`crate::runtime::json_commands::handle_file_generated_surface_match_command`].
/// - `request_path`: Input consumed by [`crate::runtime::json_commands::handle_file_generated_surface_match_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_file_generated_surface_match_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_file_generated_surface_match_command(todo!(), todo!(), "/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_file_generated_surface_match_command(
    file_path: &Path,
    method: &str,
    request_path: &str,
) -> Option<String> {
    file_generated_surface_match(file_path, method, request_path)
}

/// Handles generated surface list columns JSON command.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_list_columns_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_list_columns_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_list_columns_json_command("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_list_columns_json_command(surface_json: &str) -> Option<String> {
    generated_surface_list_columns(surface_json)
}

/// Returns generated-surface request parameters.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_params_runtime`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_params_runtime`].
/// - `identity_value`: Input consumed by [`crate::runtime::json_commands::generated_surface_params_runtime`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_params_runtime`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_params_runtime("{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_params_runtime(
    surface_json: &str,
    context_json: &str,
    identity_value: Option<&str>,
) -> Option<String> {
    generated_surface_params(surface_json, context_json, identity_value)
}

/// Handles generated surface params JSON command.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_params_json_command`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_params_json_command`].
/// - `identity_value`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_params_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_params_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_params_json_command("{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_params_json_command(
    surface_json: &str,
    context_json: &str,
    identity_value: Option<&str>,
) -> Option<String> {
    generated_surface_params(surface_json, context_json, identity_value)
}

/// Returns generated-surface display text for a field.
///
/// # Parameters
///
/// - `item_json`: Input consumed by [`crate::runtime::json_commands::generated_surface_display_value_runtime`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::generated_surface_display_value_runtime`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_display_value_runtime`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_display_value_runtime("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_display_value_runtime(
    item_json: &str,
    field_name: &str,
) -> Option<String> {
    generated_surface_display_value(item_json, field_name)
}

/// Handles generated surface display value command.
///
/// # Parameters
///
/// - `item_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_display_value_command`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_display_value_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_display_value_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_display_value_command("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_display_value_command(
    item_json: &str,
    field_name: &str,
) -> Option<String> {
    generated_surface_display_value(item_json, field_name)
}

/// Handles generated surface select options HTML command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_select_options_html_command`].
/// - `field_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_select_options_html_command`].
/// - `selected_value`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_select_options_html_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_select_options_html_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_select_options_html_command(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_select_options_html_command(
    app_root: &Path,
    field_json: &str,
    selected_value: Option<&str>,
) -> Option<String> {
    generated_surface_select_options_html(app_root, field_json, selected_value)
}

/// Handles generated surface relation checkboxes HTML command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_relation_checkboxes_html_command`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_relation_checkboxes_html_command`].
/// - `relation_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_relation_checkboxes_html_command`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_relation_checkboxes_html_command`].
/// - `selected_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_relation_checkboxes_html_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_relation_checkboxes_html_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_relation_checkboxes_html_command(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_relation_checkboxes_html_command(
    app_root: &Path,
    state_path: &Path,
    relation_json: &str,
    context_json: &str,
    selected_json: Option<&str>,
) -> Option<String> {
    generated_surface_relation_checkboxes_html(
        app_root,
        state_path,
        relation_json,
        context_json,
        selected_json,
    )
}

/// Handles generated surface manage table JSON command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_table_json_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_table_json_command`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_table_json_command`].
/// - `list_result_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_table_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_manage_table_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_manage_table_json_command(std::path::Path::new("apps/dev_docs"), "{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_manage_table_json_command(
    app_root: &Path,
    surface_json: &str,
    context_json: &str,
    list_result_json: &str,
) -> Option<String> {
    generated_surface_manage_table_json(app_root, surface_json, context_json, list_result_json)
}

/// Handles generated surface form fields HTML command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_form_fields_html_command`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_form_fields_html_command`].
/// - `fixture_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_form_fields_html_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_form_fields_html_command`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_form_fields_html_command`].
/// - `item_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_form_fields_html_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_form_fields_html_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_form_fields_html_command(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), "{}", todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_form_fields_html_command(
    app_root: &Path,
    state_path: &Path,
    fixture_path: &Path,
    surface_json: &str,
    context_json: &str,
    item_json: Option<&str>,
) -> Option<String> {
    generated_surface_form_fields_html(
        app_root,
        state_path,
        fixture_path,
        surface_json,
        context_json,
        item_json,
    )
}

/// Handles generated surface filter controls HTML command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_filter_controls_html_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_filter_controls_html_command`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_filter_controls_html_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_filter_controls_html_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_filter_controls_html_command(std::path::Path::new("apps/dev_docs"), "{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_filter_controls_html_command(
    app_root: &Path,
    surface_json: &str,
    raw_query: &str,
) -> Option<String> {
    generated_surface_filter_controls_html(app_root, surface_json, raw_query)
}

/// Handles generated surface sort options HTML command.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_sort_options_html_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_sort_options_html_command`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_sort_options_html_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_sort_options_html_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_sort_options_html_command(std::path::Path::new("apps/dev_docs"), "{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_sort_options_html_command(
    app_root: &Path,
    surface_json: &str,
    raw_query: &str,
) -> Option<String> {
    generated_surface_sort_options_html(app_root, surface_json, raw_query)
}

/// Handles generated surface context command.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_context_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_context_command`].
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_context_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_context_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_context_command(todo!(), "{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_context_command(
    state_path: &Path,
    surface_json: &str,
    params_json: &str,
) -> Option<String> {
    generated_surface_context_json(state_path, surface_json, params_json)
}

/// Handles generated surface submitted command.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_submitted_command`].
/// - `request_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_submitted_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_submitted_command`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::handle_generated_surface_submitted_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_submitted_command("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_submitted_command(
    surface_json: &str,
    request_json: &str,
) -> Option<String> {
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    let payload = serde_json::from_str::<Value>(request_json).ok()?;
    let form_root = serde_json::json!({
        "forms": [{
            "form_id": surface.get("form_id").and_then(Value::as_str).unwrap_or_default(),
            "fields": surface
                .get("fields")
                .and_then(Value::as_array)
                .cloned()
                .unwrap_or_default()
        }]
    });
    generated::generated_surface_submitted_json(&surface, &form_root, &payload)
        .or_else(|| compact(&payload))
}

/// Handles generated surface list result command.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_list_result_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_list_result_command`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_list_result_command`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_list_result_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_list_result_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_list_result_command(todo!(), "{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_list_result_command(
    state_path: &Path,
    surface_json: &str,
    context_json: &str,
    raw_query: &str,
) -> Option<String> {
    generated_surface_list_result_json(state_path, surface_json, context_json, raw_query)
}

/// Handles generated surface default candidate command.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_default_candidate_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_default_candidate_command`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_default_candidate_command`].
/// - `existing_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_default_candidate_command`].
/// - `submitted_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_default_candidate_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_default_candidate_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_default_candidate_command(todo!(), "{}", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_default_candidate_command(
    state_path: &Path,
    surface_json: &str,
    context_json: &str,
    existing_json: Option<&str>,
    submitted_json: Option<&str>,
) -> Option<String> {
    generated_surface_default_candidate_json(
        state_path,
        surface_json,
        context_json,
        existing_json,
        submitted_json,
    )
}

/// Handles generated surface validation report command.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_validation_report_command`].
/// - `action_id`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_validation_report_command`].
/// - `actor_scope`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_validation_report_command`].
/// - `tenant_scope`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_validation_report_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_validation_report_command`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::handle_generated_surface_validation_report_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_validation_report_command("{}", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_validation_report_command(
    surface_json: &str,
    action_id: Option<&str>,
    actor_scope: Option<&str>,
    tenant_scope: Option<&str>,
) -> Option<String> {
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    generated::generated_surface_validation_report_empty(
        surface.get("form_id").and_then(Value::as_str),
        action_id,
        actor_scope,
        tenant_scope,
    )
}

/// Handles generated surface mutate command.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_mutate_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_mutate_command`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_mutate_command`].
/// - `candidate_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_mutate_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_mutate_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_mutate_command(todo!(), "{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_mutate_command(
    state_path: &Path,
    surface_json: &str,
    context_json: &str,
    candidate_json: &str,
) -> Option<String> {
    generated_surface_default_candidate_json(
        state_path,
        surface_json,
        context_json,
        None,
        Some(candidate_json),
    )
}

/// Validates a generated-surface candidate through the existing typed helper.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_coerce_candidate_command`].
/// - `candidate_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_coerce_candidate_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_coerce_candidate_command`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::handle_generated_surface_coerce_candidate_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_coerce_candidate_command("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_coerce_candidate_command(
    surface_json: &str,
    candidate_json: &str,
) -> Option<String> {
    let surface_root = serde_json::from_str::<Value>(surface_json).ok()?;
    generated::generated_surface_coerce_candidate_json(&surface_root, candidate_json)
}

/// Builds the generated-surface edit page JSON.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_edit_page_json_command`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_edit_page_json_command`].
/// - `fixture_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_edit_page_json_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_edit_page_json_command`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_edit_page_json_command`].
/// - `item_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_edit_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_edit_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_edit_page_json_command(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), "{}", todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_edit_page_json_command(
    app_root: &Path,
    state_path: &Path,
    fixture_path: &Path,
    surface_json: &str,
    context_json: &str,
    item_json: &str,
) -> Option<String> {
    generated_surface_edit_page_json(
        app_root,
        state_path,
        fixture_path,
        surface_json,
        context_json,
        item_json,
    )
}

/// Builds the generated-surface management page JSON.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_page_json_command`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_page_json_command`].
/// - `fixture_path`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_page_json_command`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_page_json_command`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_page_json_command`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_manage_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_manage_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_manage_page_json_command(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), "{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_manage_page_json_command(
    app_root: &Path,
    state_path: &Path,
    fixture_path: &Path,
    surface_json: &str,
    context_json: &str,
    raw_query: &str,
) -> Option<String> {
    generated_surface_manage_page_json(
        app_root,
        state_path,
        fixture_path,
        surface_json,
        context_json,
        raw_query,
    )
}

/// Performs object from text.
fn object_from_text(text: &str) -> Option<Value> {
    let value = serde_json::from_str::<Value>(text).ok()?;
    value.is_object().then_some(value)
}

/// Performs bounded state array.
fn bounded_state_array<'a>(root: &'a Value, section: &str) -> &'a [Value] {
    root.get(section)
        .and_then(Value::as_array)
        .map(|items| &items[..items.len().min(MAX_STATE_ROWS_JSON)])
        .unwrap_or(&[])
}

/// Appends an audit event to a mutable generated-surface state document.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::generated_surface_append_audit_event_mut`].
/// - `event`: Input consumed by [`crate::runtime::json_commands::generated_surface_append_audit_event_mut`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::generated_surface_append_audit_event_mut`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_append_audit_event_mut(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_append_audit_event_mut(root: &mut Value, event: Value) -> bool {
    let Some(object) = root.as_object_mut() else {
        return false;
    };
    if !event.is_object() {
        return false;
    }
    let events = object
        .entry("audit_events".to_owned())
        .or_insert_with(|| Value::Array(Vec::new()));
    let Some(items) = events.as_array_mut() else {
        return false;
    };
    if items.len() >= MAX_STATE_ROWS_JSON {
        return false;
    }
    items.push(event);
    true
}

/// Tests whether an array contains an exact string value.
///
/// # Parameters
///
/// - `values`: Input consumed by [`crate::runtime::json_commands::generated_surface_array_contains_string`].
/// - `expected`: Input consumed by [`crate::runtime::json_commands::generated_surface_array_contains_string`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::generated_surface_array_contains_string`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_array_contains_string`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_array_contains_string(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_array_contains_string(values: &Value, expected: &str) -> bool {
    !expected.is_empty()
        && values
            .as_array()
            .is_some_and(|items| items.iter().any(|item| item.as_str() == Some(expected)))
}

/// Normalizes generated-surface order values to stable positive integers.
///
/// # Parameters
///
/// - `values`: Input consumed by [`crate::runtime::json_commands::generated_surface_normalize_order_mut`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::generated_surface_normalize_order_mut`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::generated_surface_normalize_order_mut`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_normalize_order_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_normalize_order_mut(todo!(), "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_normalize_order_mut(values: &mut Value, field: &str) -> bool {
    if field.is_empty() {
        return false;
    }
    let Some(items) = values.as_array_mut() else {
        return false;
    };
    for (index, item) in items.iter_mut().enumerate() {
        let Some(object) = item.as_object_mut() else {
            return false;
        };
        let value = object
            .get(field)
            .and_then(Value::as_i64)
            .filter(|value| *value > 0)
            .unwrap_or(index as i64 + 1);
        object.insert(field.to_owned(), Value::from(value));
    }
    true
}

/// Validates that every relation value is an integer identifier.
///
/// # Parameters
///
/// - `values`: Input consumed by [`crate::runtime::json_commands::generated_surface_relation_array_all_integers`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::generated_surface_relation_array_all_integers`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_relation_array_all_integers`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_relation_array_all_integers(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_relation_array_all_integers(values: &Value) -> bool {
    values.as_array().is_some_and(|items| {
        items
            .iter()
            .all(|item| item.as_i64().is_some() || item.as_u64().is_some())
    })
}

/// Adds one field error to a mutable validation report.
///
/// # Parameters
///
/// - `report`: Input consumed by [`crate::runtime::json_commands::generated_surface_report_add_field_error`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::generated_surface_report_add_field_error`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::generated_surface_report_add_field_error`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::generated_surface_report_add_field_error`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_report_add_field_error(todo!(), "field", "example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_report_add_field_error(
    report: &mut Value,
    field: &str,
    message: &str,
) -> bool {
    if field.is_empty() || message.is_empty() {
        return false;
    }
    let Some(object) = report.as_object_mut() else {
        return false;
    };
    let errors = object
        .entry("field_errors".to_owned())
        .or_insert_with(|| Value::Object(Map::new()));
    let Some(error_map) = errors.as_object_mut() else {
        return false;
    };
    error_map.insert(field.to_owned(), Value::String(message.to_owned()));
    true
}

/// Performs valid date text.
fn valid_date_text(text: &str) -> bool {
    let parts: Vec<_> = text.split('-').collect();
    parts.len() == 3
        && parts[0].len() == 4
        && parts[1].len() == 2
        && parts[2].len() == 2
        && parts
            .iter()
            .all(|part| part.bytes().all(|byte| byte.is_ascii_digit()))
        && (1..=12).contains(&parts[1].parse::<u8>().unwrap_or(0))
        && (1..=31).contains(&parts[2].parse::<u8>().unwrap_or(0))
}

/// Validates the date text accepted by generated-surface filters.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::generated_surface_text_is_date`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::generated_surface_text_is_date`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_text_is_date("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_text_is_date(text: &str) -> bool {
    valid_date_text(text)
}

/// Validates a bounded decimal amount without accepting exponent syntax.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::generated_surface_text_is_decimal`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::generated_surface_text_is_decimal`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_text_is_decimal`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_text_is_decimal("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_text_is_decimal(text: &str) -> bool {
    if text.is_empty() || text.len() > 64 {
        return false;
    }
    let mut separator_seen = false;
    let digits = text.strip_prefix('-').unwrap_or(text);
    !digits.is_empty()
        && digits.bytes().all(|byte| match byte {
            b'0'..=b'9' => true,
            b'.' if !separator_seen => {
                separator_seen = true;
                true
            }
            _ => false,
        })
}

/// Validates a basic user-facing email value.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::generated_surface_text_is_email`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::generated_surface_text_is_email`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_text_is_email`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_text_is_email("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_text_is_email(text: &str) -> bool {
    let Some((local, domain)) = text.split_once('@') else {
        return false;
    };
    !local.is_empty()
        && local.len() <= 128
        && !local.contains(char::is_whitespace)
        && domain.len() <= 253
        && domain.contains('.')
        && domain.split('.').all(|part| {
            !part.is_empty()
                && !part.starts_with('-')
                && !part.ends_with('-')
                && part
                    .bytes()
                    .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
        })
}

/// Validates an HH:MM or HH:MM:SS time value.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::generated_surface_text_is_time`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::generated_surface_text_is_time`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::generated_surface_text_is_time`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_text_is_time("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_text_is_time(text: &str) -> bool {
    let parts: Vec<_> = text.split(':').collect();
    (parts.len() == 2 || parts.len() == 3)
        && parts
            .iter()
            .all(|part| part.len() == 2 && part.bytes().all(|byte| byte.is_ascii_digit()))
        && parts[0].parse::<u8>().is_ok_and(|value| value < 24)
        && parts[1].parse::<u8>().is_ok_and(|value| value < 60)
        && parts
            .get(2)
            .is_none_or(|part| part.parse::<u8>().is_ok_and(|value| value < 60))
}

/// Returns the greatest positive id in one state section.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::max_id_in_state_section`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::max_id_in_state_section`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::max_id_in_state_section`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::max_id_in_state_section`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::max_id_in_state_section(std::path::Path::new("."), "items");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn max_id_in_state_section(root: &Value, section: &str) -> i64 {
    bounded_state_array(root, section)
        .iter()
        .filter_map(|row| row.get("id").and_then(Value::as_i64))
        .filter(|id| *id > 0)
        .max()
        .unwrap_or(0)
}

/// Merges an object patch into a mutable object document.
///
/// # Parameters
///
/// - `target`: Input consumed by [`crate::runtime::json_commands::merge_patch_into_mut_object`].
/// - `patch`: Input consumed by [`crate::runtime::json_commands::merge_patch_into_mut_object`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::merge_patch_into_mut_object`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::merge_patch_into_mut_object`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::merge_patch_into_mut_object("/", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn merge_patch_into_mut_object(target: &mut Value, patch: &Value) -> bool {
    let (Some(target), Some(patch)) = (target.as_object_mut(), patch.as_object()) else {
        return false;
    };
    for (key, value) in patch {
        if value.is_null() {
            target.remove(key);
        } else {
            target.insert(key.clone(), value.clone());
        }
    }
    true
}

/// Returns a mutable normalized payload object, rejecting non-object input.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::normalized_payload_object_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::normalized_payload_object_mut`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::normalized_payload_object_mut("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn normalized_payload_object_mut(value: &mut Value) -> Option<&mut Map<String, Value>> {
    value.as_object_mut()
}

/// Returns the JSON text for a user's booking selected by user id.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::state_find_booking_for_user`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::state_find_booking_for_user`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::state_find_booking_for_user`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::state_find_booking_for_user`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::state_find_booking_for_user(std::path::Path::new("."), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn state_find_booking_for_user(root: &Value, user_id: i64) -> Option<String> {
    bounded_state_array(root, "bookings")
        .iter()
        .find(|row| row.get("user_id").and_then(Value::as_i64) == Some(user_id))
        .and_then(compact)
}

/// Returns the JSON text for a record selected by a string field.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::surface_find_record_by_string_field`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::surface_find_record_by_string_field`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::surface_find_record_by_string_field`].
/// - `expected`: Input consumed by [`crate::runtime::json_commands::surface_find_record_by_string_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::surface_find_record_by_string_field`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::surface_find_record_by_string_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::surface_find_record_by_string_field(std::path::Path::new("."), "items", "field", "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn surface_find_record_by_string_field(
    root: &Value,
    section: &str,
    field: &str,
    expected: &str,
) -> Option<String> {
    bounded_state_array(root, section)
        .iter()
        .find(|row| row.get(field).and_then(Value::as_str) == Some(expected))
        .and_then(compact)
}

/// Emits active tenant identifiers for one user as newline-delimited text.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_active_tenant_ids_lines`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_active_tenant_ids_lines`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::emit_active_tenant_ids_lines`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_active_tenant_ids_lines`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_active_tenant_ids_lines(std::path::Path::new("."), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_active_tenant_ids_lines(root: &Value, user_id: i64) -> String {
    bounded_state_array(root, "tenant_memberships")
        .iter()
        .filter(|row| row.get("user_id").and_then(Value::as_i64) == Some(user_id))
        .filter(|row| {
            row.get("membership_status")
                .and_then(Value::as_str)
                .is_none_or(|status| status.is_empty() || status == "active")
        })
        .filter_map(|row| row.get("tenant_id").and_then(Value::as_i64))
        .take(MAX_OUTPUT_ROWS_JSON)
        .map(|id| id.to_string())
        .collect::<Vec<_>>()
        .join("\n")
}

/// Performs rows as JSON.
fn rows_as_json(root: &Value, section: &str, predicate: impl Fn(&Value) -> bool) -> Option<String> {
    let rows: Vec<Value> = bounded_state_array(root, section)
        .iter()
        .filter(|row| predicate(row))
        .take(MAX_OUTPUT_ROWS_JSON)
        .cloned()
        .collect();
    compact(&Value::Array(rows))
}

/// Emits appointments visible to one user.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_user_appointments`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_user_appointments`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_user_appointments`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_user_appointments(std::path::Path::new("."), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_user_appointments(root: &Value, user_id: i64) -> Option<String> {
    rows_as_json(root, "appointments", |row| {
        row.get("user_id").and_then(Value::as_i64) == Some(user_id)
    })
}

/// Emits appointments visible to a managed user, preserving state order.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_managed_appointments`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_managed_appointments`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_managed_appointments`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_managed_appointments`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_managed_appointments(std::path::Path::new("."), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_managed_appointments(root: &Value, user_id: i64) -> Option<String> {
    let business_ids: Vec<i64> = bounded_state_array(root, "businesses")
        .iter()
        .filter(|row| row.get("owner_id").and_then(Value::as_i64) == Some(user_id))
        .filter_map(|row| row.get("id").and_then(Value::as_i64))
        .collect();
    rows_as_json(root, "appointments", |row| {
        row.get("business_id")
            .and_then(Value::as_i64)
            .is_some_and(|id| business_ids.contains(&id))
    })
}

/// Emits the tenant ids associated with one user's active memberships as JSON.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_user_membership_tenant_ids`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_user_membership_tenant_ids`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_user_membership_tenant_ids`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_user_membership_tenant_ids`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_user_membership_tenant_ids(std::path::Path::new("."), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_user_membership_tenant_ids(root: &Value, user_id: i64) -> Option<String> {
    let ids: Vec<Value> = bounded_state_array(root, "tenant_memberships")
        .iter()
        .filter(|row| row.get("user_id").and_then(Value::as_i64) == Some(user_id))
        .filter(|row| {
            row.get("membership_status")
                .and_then(Value::as_str)
                .is_none_or(|status| status.is_empty() || status == "active")
        })
        .filter_map(|row| row.get("tenant_id").cloned())
        .take(MAX_OUTPUT_ROWS_JSON)
        .collect();
    compact(&Value::Array(ids))
}

/// Emits public business cards from state.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_public_business_cards`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_public_business_cards`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_public_business_cards`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_public_business_cards(std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_public_business_cards(root: &Value) -> Option<String> {
    let cards: Vec<Value> = bounded_state_array(root, "businesses")
        .iter()
        .map(|row| serde_json::json!({"id": row.get("id").cloned().unwrap_or(Value::Null), "slug": row.get("slug").cloned().unwrap_or(Value::Null), "name": row.get("name").cloned().unwrap_or(Value::Null), "description": row.get("description").cloned().unwrap_or(Value::Null), "image_url": row.get("image_url").cloned().unwrap_or(Value::Null)}))
        .take(MAX_OUTPUT_ROWS_JSON)
        .collect();
    compact(&Value::Array(cards))
}

/// Emits business cards managed by one user.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_manageable_business_cards`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_manageable_business_cards`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_manageable_business_cards`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_manageable_business_cards`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_manageable_business_cards(std::path::Path::new("."), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_manageable_business_cards(root: &Value, user_id: i64) -> Option<String> {
    let cards: Vec<Value> = bounded_state_array(root, "businesses")
        .iter()
        .filter(|row| {
            row.get("owner_id").and_then(Value::as_i64) == Some(user_id)
                || row.get("owner_user_id").and_then(Value::as_i64) == Some(user_id)
        })
        .take(MAX_OUTPUT_ROWS_JSON)
        .cloned()
        .collect();
    compact(&Value::Array(cards))
}

/// Writes a bounded mutable JSON document through the native filesystem surface.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::write_mutable_json_doc`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::write_mutable_json_doc`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::write_mutable_json_doc`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::write_mutable_json_doc(std::path::Path::new("fixture.json"), "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn write_mutable_json_doc(path: &Path, value: &Value) -> i32 {
    let Some(text) = compact(value) else {
        return 75;
    };
    super::fs::write_text_file(path, &text)
}

/// Compacts a mutable JSON document read from disk.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::emit_compact_mutable_json_doc`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_compact_mutable_json_doc`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_compact_mutable_json_doc(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_compact_mutable_json_doc(path: &Path) -> Option<String> {
    compact(&read_json_file(path)?)
}

/// Captures a stable checksum string using the configured native checksum tool.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::capture_checksum_output`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::capture_checksum_output`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::capture_checksum_output("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn capture_checksum_output(value: &str) -> Option<String> {
    checksum_string(value)
}

/// Returns a JSON value with its template text rendered from bounded parameters.
///
/// # Parameters
///
/// - `template_path`: Input consumed by [`crate::runtime::json_commands::emit_template`].
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::emit_template`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_template`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_template("template.html", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_template(template_path: &Path, params_json: &str) -> Option<String> {
    let params = object_from_text(params_json)?;
    render_file_template(template_path, &params)
}

/// Emits an escaped text line without writing to a process-global stream.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_sorted_section_lines`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::emit_sorted_section_lines`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::emit_sorted_section_lines`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_sorted_section_lines`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_sorted_section_lines`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_sorted_section_lines(std::path::Path::new("."), "items", "field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_sorted_section_lines(root: &Value, section: &str, field: &str) -> Option<String> {
    let mut values: Vec<String> = bounded_state_array(root, section)
        .iter()
        .filter_map(|row| row.get(field).map(value_to_text))
        .filter(|value| !value.is_empty())
        .collect();
    values.sort();
    values.dedup();
    Some(values.join("\n"))
}

/// Emits template page parameters as compact JSON.
///
/// # Parameters
///
/// - `params`: Input consumed by [`crate::runtime::json_commands::emit_template_page_params`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_template_page_params`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_template_page_params(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_template_page_params(params: &Value) -> Option<String> {
    compact(params)
}

/// Appends a text line to a bounded output buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::emit_text_line_to_buffer`].
/// - `text`: Input consumed by [`crate::runtime::json_commands::emit_text_line_to_buffer`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::emit_text_line_to_buffer`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_text_line_to_buffer(todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_text_line_to_buffer(output: &mut String, text: &str) -> bool {
    let Some(line) = emit_text_line(text) else {
        return false;
    };
    if output.len().saturating_add(line.len()) > MAX_TEXT_BYTES {
        return false;
    }
    output.push_str(&line);
    true
}

/// Returns a mutable state row selected by a positive integer field.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::find_mut_array_item_by_long_field`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::find_mut_array_item_by_long_field`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::find_mut_array_item_by_long_field`].
/// - `wanted`: Input consumed by [`crate::runtime::json_commands::find_mut_array_item_by_long_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::find_mut_array_item_by_long_field`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::find_mut_array_item_by_long_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::find_mut_array_item_by_long_field(std::path::Path::new("."), "items", "field", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn find_mut_array_item_by_long_field<'a>(
    root: &'a mut Value,
    section: &str,
    field: &str,
    wanted: i64,
) -> Option<&'a mut Value> {
    if section.is_empty() || field.is_empty() || wanted <= 0 {
        return None;
    }
    root.get_mut(section)?
        .as_array_mut()?
        .iter_mut()
        .find(|item| item.get(field).and_then(Value::as_i64) == Some(wanted))
}

/// Finds an active token record for one user and token value.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::find_active_token_record`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::find_active_token_record`].
/// - `token`: Input consumed by [`crate::runtime::json_commands::find_active_token_record`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::find_active_token_record`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::find_active_token_record`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::find_active_token_record(std::path::Path::new("."), 1, todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn find_active_token_record(root: &Value, user_id: i64, token: &str) -> Option<String> {
    if user_id <= 0 || token.is_empty() {
        return None;
    }
    bounded_state_array(root, "tokens")
        .iter()
        .find(|row| {
            row.get("user_id").and_then(Value::as_i64) == Some(user_id)
                && row.get("token").and_then(Value::as_str) == Some(token)
                && row.get("revoked").and_then(Value::as_bool) != Some(true)
        })
        .and_then(compact)
}

/// Normalizes one persisted runtime state file and returns its compact text.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::handle_file_normalize_runtime_state_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::json_commands::handle_file_normalize_runtime_state_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::json_commands::handle_file_normalize_runtime_state_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_file_normalize_runtime_state_command(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_file_normalize_runtime_state_command(path: &Path) -> Result<String, i32> {
    let root = read_json_file(path).ok_or(66)?;
    let text = compact(&root).ok_or(75)?;
    if super::fs::write_text_file(path, &text) != 0 {
        return Err(73);
    }
    Ok(text)
}

/// Matches a route template and stores its path parameters in an object.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::route_template_match_into_mut_obj`].
/// - `template_path`: Input consumed by [`crate::runtime::json_commands::route_template_match_into_mut_obj`].
/// - `request_path`: Input consumed by [`crate::runtime::json_commands::route_template_match_into_mut_obj`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::route_template_match_into_mut_obj`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::route_template_match_into_mut_obj(todo!(), "template.html", "/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn route_template_match_into_mut_obj(
    output: &mut Map<String, Value>,
    template_path: &str,
    request_path: &str,
) -> bool {
    let Some(params) = route_template_params(template_path, request_path) else {
        return false;
    };
    output.extend(params);
    true
}

/// Handles the state event-row JSON command from an already-loaded row.
///
/// # Parameters
///
/// - `row`: Input consumed by [`crate::runtime::json_commands::handle_state_event_stream_row_json_lines_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_state_event_stream_row_json_lines_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_state_event_stream_row_json_lines_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_state_event_stream_row_json_lines_command(row: &Value) -> Option<String> {
    compact(row)
}

/// Handles importing one bounded JSON row into a mutable state document.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::handle_state_import_row_json_lines_command`].
/// - `row_text`: Input consumed by [`crate::runtime::json_commands::handle_state_import_row_json_lines_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::json_commands::handle_state_import_row_json_lines_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::json_commands::handle_state_import_row_json_lines_command`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::handle_state_import_row_json_lines_command`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_state_import_row_json_lines_command(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_state_import_row_json_lines_command(
    root: &mut Value,
    row_text: &str,
) -> Result<String, i32> {
    let row = serde_json::from_str::<Value>(row_text).map_err(|_| 65)?;
    if !row.is_object() || !generated_surface_append_audit_event_mut(root, row.clone()) {
        return Err(65);
    }
    compact(&row).ok_or(75)
}

/// Applies a template base path to URL-bearing attributes.
///
/// # Parameters
///
/// - `html`: Input consumed by [`crate::runtime::json_commands::handle_template_apply_base_path_command`].
/// - `base_path`: Input consumed by [`crate::runtime::json_commands::handle_template_apply_base_path_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_apply_base_path_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_apply_base_path_command(todo!(), "/app");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_apply_base_path_command(
    html: &str,
    base_path: Option<&str>,
) -> Option<String> {
    template_apply_base_path(html, base_path)
}

/// Resolves a declared fragment path for a command caller.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_template_declared_fragment_path_command`].
/// - `fragment_id`: Input consumed by [`crate::runtime::json_commands::handle_template_declared_fragment_path_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_declared_fragment_path_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_declared_fragment_path_command(std::path::Path::new("apps/dev_docs"), "header");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_declared_fragment_path_command(
    app_root: &Path,
    fragment_id: &str,
) -> Option<String> {
    template_declared_fragment_path(app_root, fragment_id)
}

/// Resolves a declared page contract for a command caller.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_template_declared_page_contract_command`].
/// - `page_id`: Input consumed by [`crate::runtime::json_commands::handle_template_declared_page_contract_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_declared_page_contract_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_declared_page_contract_command(std::path::Path::new("apps/dev_docs"), "home");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_declared_page_contract_command(
    app_root: &Path,
    page_id: &str,
) -> Option<String> {
    template_declared_page_contract(app_root, page_id)
}

/// Renders one named page JSON contract from a parameter document.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_template_layout_page_json_command`].
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_template_layout_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_layout_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_layout_page_json_command(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_layout_page_json_command(
    app_root: &Path,
    params_json: &str,
) -> Option<String> {
    let params = object_from_text(params_json)?;
    template_layout_page_json(
        app_root,
        params.get("layout_id").and_then(Value::as_str),
        params.get("current_lang").and_then(Value::as_str),
        params
            .get("title")
            .and_then(Value::as_str)
            .unwrap_or_default(),
        params
            .get("body")
            .and_then(Value::as_str)
            .unwrap_or_default(),
        params.get("current_request_target").and_then(Value::as_str),
        params
            .get("has_user")
            .and_then(Value::as_bool)
            .unwrap_or(false),
        params
            .get("managed_business_count")
            .and_then(Value::as_i64)
            .unwrap_or(0),
    )
}

/// Renders one named layout page as HTML from a parameter document.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_template_layout_page_html_command`].
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_template_layout_page_html_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_layout_page_html_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_layout_page_html_command(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_layout_page_html_command(
    app_root: &Path,
    params_json: &str,
) -> Option<String> {
    let params = object_from_text(params_json)?;
    template_layout_page_html(
        app_root,
        params.get("base_path").and_then(Value::as_str),
        params.get("layout_id").and_then(Value::as_str),
        params.get("current_lang").and_then(Value::as_str),
        params
            .get("title")
            .and_then(Value::as_str)
            .unwrap_or_default(),
        params
            .get("body")
            .and_then(Value::as_str)
            .unwrap_or_default(),
        params.get("current_request_target").and_then(Value::as_str),
        params
            .get("has_user")
            .and_then(Value::as_bool)
            .unwrap_or(false),
        params
            .get("managed_business_count")
            .and_then(Value::as_i64)
            .unwrap_or(0),
    )
}

/// Performs template command params.
fn template_command_params(params_json: &str) -> Option<Value> {
    let params = serde_json::from_str::<Value>(params_json).ok()?;
    params.is_object().then_some(params)
}

/// Builds the login page parameter JSON for a command caller.
///
/// # Parameters
///
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_template_login_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_login_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_login_page_json_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_login_page_json_command(params_json: &str) -> Option<String> {
    let params = template_command_params(params_json)?;
    compact(&params)
}

/// Builds the registration page parameter JSON for a command caller.
///
/// # Parameters
///
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_template_register_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_register_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_register_page_json_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_register_page_json_command(params_json: &str) -> Option<String> {
    let params = template_command_params(params_json)?;
    compact(&params)
}

/// Builds the password-reset request page parameter JSON.
///
/// # Parameters
///
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_template_password_reset_request_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_password_reset_request_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_password_reset_request_page_json_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_password_reset_request_page_json_command(
    params_json: &str,
) -> Option<String> {
    let params = template_command_params(params_json)?;
    compact(&params)
}

/// Builds the password-reset sent page parameter JSON.
///
/// # Parameters
///
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_template_password_reset_sent_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_password_reset_sent_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_password_reset_sent_page_json_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_password_reset_sent_page_json_command(params_json: &str) -> Option<String> {
    let params = template_command_params(params_json)?;
    compact(&params)
}

/// Builds the password-reset complete page parameter JSON.
///
/// # Parameters
///
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_template_password_reset_complete_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_password_reset_complete_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_password_reset_complete_page_json_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_password_reset_complete_page_json_command(
    params_json: &str,
) -> Option<String> {
    let params = template_command_params(params_json)?;
    compact(&params)
}

/// Builds the invite-created page parameter JSON.
///
/// # Parameters
///
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_template_invite_created_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_invite_created_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_invite_created_page_json_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_invite_created_page_json_command(params_json: &str) -> Option<String> {
    let params = template_command_params(params_json)?;
    compact(&params)
}

/// Builds the invite-accept page parameter JSON.
///
/// # Parameters
///
/// - `params_json`: Input consumed by [`crate::runtime::json_commands::handle_template_invite_accept_page_json_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_template_invite_accept_page_json_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_template_invite_accept_page_json_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_template_invite_accept_page_json_command(params_json: &str) -> Option<String> {
    let params = template_command_params(params_json)?;
    compact(&params)
}

/// Renders a shared empty fragment through the declared application template.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_app_empty_fragment`].
/// - `message`: Input consumed by [`crate::runtime::json_commands::render_app_empty_fragment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_app_empty_fragment`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_app_empty_fragment(std::path::Path::new("apps/dev_docs"), "example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_app_empty_fragment(app_root: &Path, message: &str) -> Option<String> {
    let params = Map::from_iter([("message".to_owned(), Value::String(message.to_owned()))]);
    generated::render_generated_admin_fragment_from_value_runtime(
        app_root,
        "templates/shared/fragments/empty.html",
        &params,
    )
}

/// Returns the declared empty dashboard copy without embedding a page shell.
///
/// # Parameters
///
/// - `message`: Input consumed by [`crate::runtime::json_commands::render_business_dashboard_empty_html`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::render_business_dashboard_empty_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_business_dashboard_empty_html("example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_business_dashboard_empty_html(message: &str) -> String {
    html_escape_text(message)
}

/// Builds a generated-surface filter control fragment from contract metadata.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_filter_controls_html`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_filter_controls_html`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_filter_controls_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::build_generated_surface_filter_controls_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::build_generated_surface_filter_controls_html(std::path::Path::new("apps/dev_docs"), "{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn build_generated_surface_filter_controls_html(
    app_root: &Path,
    surface_json: &str,
    raw_query: &str,
) -> Option<String> {
    generated_surface_filter_controls_html(app_root, surface_json, raw_query)
}

/// Builds generated-surface form fields from contract metadata.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_form_fields_html`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_form_fields_html`].
/// - `fixture_path`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_form_fields_html`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_form_fields_html`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_form_fields_html`].
/// - `item_json`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_form_fields_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::build_generated_surface_form_fields_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::build_generated_surface_form_fields_html(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), "{}", todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn build_generated_surface_form_fields_html(
    app_root: &Path,
    state_path: &Path,
    fixture_path: &Path,
    surface_json: &str,
    context_json: &str,
    item_json: Option<&str>,
) -> Option<String> {
    generated_surface_form_fields_html(
        app_root,
        state_path,
        fixture_path,
        surface_json,
        context_json,
        item_json,
    )
}

/// Builds generated-surface sort options from contract metadata.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_sort_options_html`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_sort_options_html`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_sort_options_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::build_generated_surface_sort_options_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::build_generated_surface_sort_options_html(std::path::Path::new("apps/dev_docs"), "{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn build_generated_surface_sort_options_html(
    app_root: &Path,
    surface_json: &str,
    raw_query: &str,
) -> Option<String> {
    generated_surface_sort_options_html(app_root, surface_json, raw_query)
}

/// Builds generated-surface management table parts from a bounded JSON value.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_manage_table_parts`].
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_manage_table_parts`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_manage_table_parts`].
/// - `list_result_json`: Input consumed by [`crate::runtime::json_commands::build_generated_surface_manage_table_parts`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::build_generated_surface_manage_table_parts`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::build_generated_surface_manage_table_parts(std::path::Path::new("apps/dev_docs"), "{}", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn build_generated_surface_manage_table_parts(
    app_root: &Path,
    surface_json: &str,
    context_json: &str,
    list_result_json: &str,
) -> Option<String> {
    generated_surface_manage_table_json(app_root, surface_json, context_json, list_result_json)
}

/// Applies one generated-surface filter item to a record.
///
/// # Parameters
///
/// - `item`: Input consumed by [`crate::runtime::json_commands::surface_filter_item`].
/// - `filter`: Input consumed by [`crate::runtime::json_commands::surface_filter_item`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::surface_filter_item`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::surface_filter_item`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::surface_filter_item(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn surface_filter_item(item: &Value, filter: &Value, raw_query: &str) -> bool {
    generated_surface_filter_matches(item, filter, raw_query)
}

/// Builds active filter state from a raw query string.
///
/// # Parameters
///
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::surface_build_active_filters`].
/// - `filters`: Input consumed by [`crate::runtime::json_commands::surface_build_active_filters`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::surface_build_active_filters`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::surface_build_active_filters`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::surface_build_active_filters(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn surface_build_active_filters(raw_query: &str, filters: &Value) -> Option<String> {
    let mut active = Map::new();
    for filter in filters.as_array()? {
        let key = filter.get("field").and_then(Value::as_str)?;
        if let Some(value) = request_query_value(raw_query, key) {
            active.insert(key.to_owned(), Value::String(value));
        }
    }
    compact(&Value::Object(active))
}

/// Builds stable sort configuration from a JSON contract and query string.
///
/// # Parameters
///
/// - `options`: Input consumed by [`crate::runtime::json_commands::surface_build_sort_config`].
/// - `raw_query`: Input consumed by [`crate::runtime::json_commands::surface_build_sort_config`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::surface_build_sort_config`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::surface_build_sort_config(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn surface_build_sort_config(options: &Value, raw_query: &str) -> Option<String> {
    let field = request_query_value(raw_query, "sort").or_else(|| {
        options
            .get("default")
            .and_then(Value::as_str)
            .map(ToOwned::to_owned)
    });
    compact(
        &serde_json::json!({"field": field, "direction": request_query_value(raw_query, "direction").unwrap_or_else(|| "asc".to_owned())}),
    )
}

/// Sorts a bounded list using a declared string or numeric field.
///
/// # Parameters
///
/// - `items`: Input consumed by [`crate::runtime::json_commands::surface_sort_items`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::surface_sort_items`].
/// - `descending`: Input consumed by [`crate::runtime::json_commands::surface_sort_items`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::surface_sort_items`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::surface_sort_items(todo!(), "field", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn surface_sort_items(items: &mut Value, field: &str, descending: bool) -> bool {
    let Some(values) = items.as_array_mut() else {
        return false;
    };
    values.sort_by(|left, right| {
        let ordering = match (left.get(field), right.get(field)) {
            (Some(Value::Number(left)), Some(Value::Number(right))) => left
                .as_f64()
                .partial_cmp(&right.as_f64())
                .unwrap_or(std::cmp::Ordering::Equal),
            _ => value_to_text(left.get(field).unwrap_or(&Value::Null))
                .cmp(&value_to_text(right.get(field).unwrap_or(&Value::Null))),
        };
        if descending {
            ordering.reverse()
        } else {
            ordering
        }
    });
    true
}

/// Finds an element in a UI ledger by its stable element id.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::find_ui_ledger_element`].
/// - `element_id`: Input consumed by [`crate::runtime::json_commands::find_ui_ledger_element`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::find_ui_ledger_element`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::find_ui_ledger_element`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::find_ui_ledger_element(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn find_ui_ledger_element(root: &Value, element_id: &str) -> Option<String> {
    let elements = root.get("elements").and_then(Value::as_array)?;
    elements
        .iter()
        .find(|item| item.get("id").and_then(Value::as_str) == Some(element_id))
        .and_then(compact)
}

/// Performs business by slug.
fn business_by_slug<'a>(root: &'a Value, slug: &str) -> Option<&'a Value> {
    bounded_state_array(root, "businesses")
        .iter()
        .find(|business| business.get("slug").and_then(Value::as_str) == Some(slug))
}

/// Emits the business edit-page JSON contract.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_business_edit_page`].
/// - `slug`: Input consumed by [`crate::runtime::json_commands::emit_business_edit_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_business_edit_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_business_edit_page`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_business_edit_page(std::path::Path::new("."), todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_business_edit_page(root: &Value, slug: &str, app_root: &Path) -> Option<String> {
    let _ = app_root;
    let business = business_by_slug(root, slug)?;
    compact(&serde_json::json!({"business": business, "mode": "edit"}))
}

/// Emits the public business page JSON contract.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_business_public_page`].
/// - `slug`: Input consumed by [`crate::runtime::json_commands::emit_business_public_page`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_business_public_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_business_public_page`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_business_public_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_business_public_page(std::path::Path::new("."), todo!(), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_business_public_page(root: &Value, slug: &str, user_id: i64) -> Option<String> {
    let business = business_by_slug(root, slug)?;
    let business_id = business.get("id").and_then(Value::as_i64).unwrap_or(0);
    let services: Vec<Value> = bounded_state_array(root, "services")
        .iter()
        .filter(|service| service.get("business_id").and_then(Value::as_i64) == Some(business_id))
        .take(MAX_OUTPUT_ROWS_JSON)
        .cloned()
        .collect();
    let subscribed = bounded_state_array(root, "subscriptions")
        .iter()
        .any(|row| {
            row.get("business_id").and_then(Value::as_i64) == Some(business_id)
                && row.get("user_id").and_then(Value::as_i64) == Some(user_id)
        });
    compact(
        &serde_json::json!({"business": business, "services": services, "subscribed": subscribed}),
    )
}

/// Emits service rows for a business administration page.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_business_admin_service_rows`].
/// - `business_id`: Input consumed by [`crate::runtime::json_commands::emit_business_admin_service_rows`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_business_admin_service_rows`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_business_admin_service_rows(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_business_admin_service_rows(root: &Value, business_id: i64) -> Option<String> {
    rows_as_json(root, "services", |row| {
        row.get("business_id").and_then(Value::as_i64) == Some(business_id)
    })
}

/// Emits technician rows for a business administration page.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_business_admin_technician_rows`].
/// - `business_id`: Input consumed by [`crate::runtime::json_commands::emit_business_admin_technician_rows`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_business_admin_technician_rows`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_business_admin_technician_rows(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_business_admin_technician_rows(root: &Value, business_id: i64) -> Option<String> {
    rows_as_json(root, "technicians", |row| {
        row.get("business_id").and_then(Value::as_i64) == Some(business_id)
    })
}

/// Emits the business calendar page contract.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_business_calendar_page`].
/// - `slug`: Input consumed by [`crate::runtime::json_commands::emit_business_calendar_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_business_calendar_page`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_business_calendar_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_business_calendar_page(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_business_calendar_page(root: &Value, slug: &str) -> Option<String> {
    let business = business_by_slug(root, slug)?;
    let business_id = business.get("id").and_then(Value::as_i64).unwrap_or(0);
    let availability: Vec<Value> = bounded_state_array(root, "business_availability")
        .iter()
        .filter(|row| row.get("business_id").and_then(Value::as_i64) == Some(business_id))
        .take(MAX_OUTPUT_ROWS_JSON)
        .cloned()
        .collect();
    compact(&serde_json::json!({"business": business, "availability": availability}))
}

/// Emits the rendered business-calendar page contract.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_business_calendar_render_page`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::emit_business_calendar_render_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_business_calendar_render_page`].
/// - `selected_year`: Input consumed by [`crate::runtime::json_commands::emit_business_calendar_render_page`].
/// - `selected_month`: Input consumed by [`crate::runtime::json_commands::emit_business_calendar_render_page`].
/// - `selected_date`: Input consumed by [`crate::runtime::json_commands::emit_business_calendar_render_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_business_calendar_render_page`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_business_calendar_render_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_business_calendar_render_page(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_business_calendar_render_page(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
    selected_year: Option<&str>,
    selected_month: Option<&str>,
    selected_date: Option<&str>,
) -> Option<String> {
    let _ = app_root;
    let page = emit_business_calendar_page(root, business_slug)?;
    let page = serde_json::from_str::<Value>(&page).ok()?;
    compact(&serde_json::json!({
        "page": page,
        "selected_year": selected_year,
        "selected_month": selected_month,
        "selected_date": selected_date,
    }))
}

/// Emits the business public page with its render context.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_business_public_render_page`].
/// - `slug`: Input consumed by [`crate::runtime::json_commands::emit_business_public_render_page`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_business_public_render_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_business_public_render_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_business_public_render_page`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_business_public_render_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_business_public_render_page(std::path::Path::new("."), todo!(), 1, std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_business_public_render_page(
    root: &Value,
    slug: &str,
    user_id: i64,
    app_root: &Path,
) -> Option<String> {
    let _ = app_root;
    let page = emit_business_public_page(root, slug, user_id)?;
    compact(&serde_json::json!({"page": serde_json::from_str::<Value>(&page).ok()?}))
}

/// Emits a business dashboard page scoped to tenant identifiers.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_business_dashboard_page`].
/// - `tenant_ids`: Input consumed by [`crate::runtime::json_commands::emit_business_dashboard_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_business_dashboard_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_business_dashboard_page`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_business_dashboard_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_business_dashboard_page(std::path::Path::new("."), todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_business_dashboard_page(
    root: &Value,
    tenant_ids: &Value,
    app_root: &Path,
) -> Option<String> {
    let _ = app_root;
    let businesses: Vec<Value> = bounded_state_array(root, "businesses")
        .iter()
        .filter(|business| {
            let id = business.get("id").and_then(Value::as_i64).unwrap_or(0);
            tenant_ids
                .as_array()
                .is_none_or(|ids| ids.iter().any(|item| item.as_i64() == Some(id)))
        })
        .take(MAX_OUTPUT_ROWS_JSON)
        .cloned()
        .collect();
    compact(&serde_json::json!({"businesses": businesses}))
}

/// Emits the business administration page contract.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_business_admin_page`].
/// - `slug`: Input consumed by [`crate::runtime::json_commands::emit_business_admin_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_business_admin_page`].
/// - `invite_account_type_options_html`: Input consumed by [`crate::runtime::json_commands::emit_business_admin_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_business_admin_page`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_business_admin_page(std::path::Path::new("."), todo!(), std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_business_admin_page(
    root: &Value,
    slug: &str,
    app_root: &Path,
    invite_account_type_options_html: Option<&str>,
) -> Option<String> {
    let _ = app_root;
    let business = business_by_slug(root, slug)?;
    compact(
        &serde_json::json!({"business": business, "invite_account_type_options_html": invite_account_type_options_html.unwrap_or_default()}),
    )
}

/// Builds explore-page parameters from the public business collection.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::build_explore_page_params`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::build_explore_page_params`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::build_explore_page_params`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::build_explore_page_params(std::path::Path::new("."), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn build_explore_page_params(root: &Value, app_root: &Path) -> Option<String> {
    let _ = app_root;
    emit_public_business_cards(root)
}

/// Emits the explore page contract.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_explore_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_explore_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_explore_page`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_explore_page(std::path::Path::new("."), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_explore_page(root: &Value, app_root: &Path) -> Option<String> {
    build_explore_page_params(root, app_root)
}

/// Emits a rendered profile page for one user.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_profile_page`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_profile_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_profile_page`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_profile_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_profile_page(std::path::Path::new("."), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_profile_page(root: &Value, user_id: i64) -> Option<String> {
    let user = bounded_state_array(root, "users")
        .iter()
        .find(|row| row.get("id").and_then(Value::as_i64) == Some(user_id))?;
    compact(&serde_json::json!({"user": user}))
}

/// Emits profile-page render context.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_profile_render_page`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_profile_render_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_profile_render_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_profile_render_page`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_profile_render_page(std::path::Path::new("."), 1, std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_profile_render_page(root: &Value, user_id: i64, app_root: &Path) -> Option<String> {
    let _ = app_root;
    emit_profile_page(root, user_id)
}

/// Emits appointments visible to a user and selected tenant ids.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_appointments_page`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::emit_appointments_page`].
/// - `tenant_ids`: Input consumed by [`crate::runtime::json_commands::emit_appointments_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_appointments_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_appointments_page`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_appointments_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_appointments_page(std::path::Path::new("."), 1, todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_appointments_page(
    root: &Value,
    user_id: i64,
    tenant_ids: &Value,
    app_root: &Path,
) -> Option<String> {
    let _ = app_root;
    let appointments: Vec<Value> = bounded_state_array(root, "appointments")
        .iter()
        .filter(|row| row.get("user_id").and_then(Value::as_i64) == Some(user_id))
        .filter(|row| {
            tenant_ids.as_array().is_none_or(|ids| {
                ids.iter()
                    .any(|item| item.as_i64() == row.get("tenant_id").and_then(Value::as_i64))
            })
        })
        .take(MAX_OUTPUT_ROWS_JSON)
        .cloned()
        .collect();
    compact(&Value::Array(appointments))
}

/// Emits the service booking form contract.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_service_book_form_page`].
/// - `slug`: Input consumed by [`crate::runtime::json_commands::emit_service_book_form_page`].
/// - `service_id`: Input consumed by [`crate::runtime::json_commands::emit_service_book_form_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_service_book_form_page`].
/// - `error_message`: Input consumed by [`crate::runtime::json_commands::emit_service_book_form_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_service_book_form_page`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_service_book_form_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_service_book_form_page(std::path::Path::new("."), todo!(), todo!(), std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_service_book_form_page(
    root: &Value,
    slug: &str,
    service_id: i64,
    app_root: &Path,
    error_message: Option<&str>,
) -> Option<String> {
    let _ = app_root;
    let service = bounded_state_array(root, "services").iter().find(|row| {
        row.get("id").and_then(Value::as_i64) == Some(service_id)
            && business_by_slug(root, slug).is_some()
    })?;
    compact(
        &serde_json::json!({"service": service, "error_message": error_message.unwrap_or_default()}),
    )
}

/// Emits the service-edit page contract.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::emit_service_edit_page`].
/// - `service_id`: Input consumed by [`crate::runtime::json_commands::emit_service_edit_page`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::emit_service_edit_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_service_edit_page`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::emit_service_edit_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_service_edit_page(std::path::Path::new("."), todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_service_edit_page(root: &Value, service_id: i64, app_root: &Path) -> Option<String> {
    let _ = app_root;
    let service = bounded_state_array(root, "services")
        .iter()
        .find(|row| row.get("id").and_then(Value::as_i64) == Some(service_id))?;
    compact(&serde_json::json!({"service": service, "mode": "edit"}))
}

/// Records one pair in a bounded seen-pair set and reports whether it was new.
///
/// # Parameters
///
/// - `seen`: Input consumed by [`crate::runtime::json_commands::seen_long_pair`].
/// - `left`: Input consumed by [`crate::runtime::json_commands::seen_long_pair`].
/// - `right`: Input consumed by [`crate::runtime::json_commands::seen_long_pair`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::seen_long_pair`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::seen_long_pair(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn seen_long_pair(seen: &mut Vec<(i64, i64)>, left: i64, right: i64) -> bool {
    if seen.contains(&(left, right)) {
        return false;
    }
    if seen.len() >= MAX_OUTPUT_ROWS_JSON {
        return false;
    }
    seen.push((left, right));
    true
}

/// Converts one event row into the safe Rust event-stream representation.
///
/// # Parameters
///
/// - `row`: Input consumed by [`crate::runtime::json_commands::collect_event_stream_row`].
/// - `native_order`: Input consumed by [`crate::runtime::json_commands::collect_event_stream_row`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::collect_event_stream_row`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::collect_event_stream_row(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn collect_event_stream_row(
    row: &Value,
    native_order: i64,
) -> Option<super::json_ops::EventStreamRowRuntime> {
    row.is_object()
        .then(|| super::json_ops::EventStreamRowRuntime {
            created_at: row
                .get("created_at")
                .and_then(Value::as_str)
                .map(ToOwned::to_owned),
            source: row
                .get("source")
                .and_then(Value::as_str)
                .map(ToOwned::to_owned),
            native_order,
        })
}

/// Releases all event rows owned by a caller.
///
/// # Parameters
///
/// - `rows`: Input consumed by [`crate::runtime::json_commands::free_event_stream_row_list`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::free_event_stream_row_list`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::free_event_stream_row_list(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn free_event_stream_row_list(rows: &mut Vec<super::json_ops::EventStreamRowRuntime>) {
    rows.clear();
}

/// Appends one event-stream row to a bounded JSON array.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::append_event_stream_row`].
/// - `row`: Input consumed by [`crate::runtime::json_commands::append_event_stream_row`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::append_event_stream_row`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::append_event_stream_row(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn append_event_stream_row(output: &mut Vec<Value>, row: &Value) -> bool {
    if output.len() >= MAX_OUTPUT_ROWS_JSON || !row.is_object() {
        return false;
    }
    output.push(row.clone());
    true
}

/// Appends relation checkbox HTML using the app-owned generated fragment contract.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_relation_checkboxes_html`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_relation_checkboxes_html`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_relation_checkboxes_html`].
/// - `relation_json`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_relation_checkboxes_html`].
/// - `context_json`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_relation_checkboxes_html`].
/// - `selected_json`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_relation_checkboxes_html`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::append_generated_surface_relation_checkboxes_html`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::append_generated_surface_relation_checkboxes_html(todo!(), std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn append_generated_surface_relation_checkboxes_html(
    output: &mut String,
    app_root: &Path,
    state_path: &Path,
    relation_json: &str,
    context_json: &str,
    selected_json: Option<&str>,
) -> bool {
    let Some(fragment) = generated_surface_relation_checkboxes_html(
        app_root,
        state_path,
        relation_json,
        context_json,
        selected_json,
    ) else {
        return false;
    };
    if output.len().saturating_add(fragment.len()) > MAX_TEXT_BYTES {
        return false;
    }
    output.push_str(&fragment);
    true
}

/// Appends generated select options using the app-owned fragment contract.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_select_options_html`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_select_options_html`].
/// - `field_json`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_select_options_html`].
/// - `selected`: Input consumed by [`crate::runtime::json_commands::append_generated_surface_select_options_html`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::append_generated_surface_select_options_html`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::append_generated_surface_select_options_html(todo!(), std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn append_generated_surface_select_options_html(
    output: &mut String,
    app_root: &Path,
    field_json: &str,
    selected: Option<&str>,
) -> bool {
    let Some(fragment) = generated_surface_select_options_html(app_root, field_json, selected)
    else {
        return false;
    };
    if output.len().saturating_add(fragment.len()) > MAX_TEXT_BYTES {
        return false;
    }
    output.push_str(&fragment);
    true
}

/// Performs a bounded case-insensitive substring test.
///
/// # Parameters
///
/// - `haystack`: Input consumed by [`crate::runtime::json_commands::contains_casefold`].
/// - `needle`: Input consumed by [`crate::runtime::json_commands::contains_casefold`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::contains_casefold`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::contains_casefold(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn contains_casefold(haystack: &str, needle: &str) -> bool {
    !needle.is_empty()
        && haystack
            .to_ascii_lowercase()
            .contains(&needle.to_ascii_lowercase())
}

/// Returns whether text is non-empty ASCII decimal digits.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::is_nonempty_ascii_digits`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::is_nonempty_ascii_digits`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::is_nonempty_ascii_digits`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::is_nonempty_ascii_digits("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn is_nonempty_ascii_digits(text: &str) -> bool {
    !text.is_empty() && text.bytes().all(|byte| byte.is_ascii_digit())
}

/// Returns an owned non-empty value or the supplied default.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::dup_or_default`].
/// - `default_value`: Input consumed by [`crate::runtime::json_commands::dup_or_default`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::dup_or_default`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dup_or_default("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dup_or_default(value: Option<&str>, default_value: &str) -> String {
    value
        .filter(|value| !value.is_empty())
        .unwrap_or(default_value)
        .to_owned()
}

/// Emits a compact mutable JSON value and retains the caller's mutation ownership.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::emit_compact_json_mut_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_compact_json_mut_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_compact_json_mut_value("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_compact_json_mut_value(value: &mut Value) -> Option<String> {
    compact(value)
}

/// Emits one compact JSON value followed by a newline.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::emit_json_line`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::emit_json_line`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::emit_json_line("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn emit_json_line(value: &Value) -> Option<String> {
    Some(format!("{}\n", compact(value)?))
}

/// Checks whether one event row is visible within a user and tenant scope.
///
/// # Parameters
///
/// - `row`: Input consumed by [`crate::runtime::json_commands::event_stream_allowed_by_scope`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::event_stream_allowed_by_scope`].
/// - `tenant_id`: Input consumed by [`crate::runtime::json_commands::event_stream_allowed_by_scope`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::event_stream_allowed_by_scope`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::event_stream_allowed_by_scope(todo!(), 1, todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn event_stream_allowed_by_scope(row: &Value, user_id: i64, tenant_id: i64) -> bool {
    let row_user = row.get("user_id").and_then(Value::as_i64);
    let row_tenant = row.get("tenant_id").and_then(Value::as_i64);
    (row_user.is_none() || row_user == Some(user_id))
        && (row_tenant.is_none() || row_tenant == Some(tenant_id))
}

/// Matches event-stream filters declared as a JSON object.
///
/// # Parameters
///
/// - `row`: Input consumed by [`crate::runtime::json_commands::event_stream_matches_filters`].
/// - `filters`: Input consumed by [`crate::runtime::json_commands::event_stream_matches_filters`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::event_stream_matches_filters`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::event_stream_matches_filters`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::event_stream_matches_filters(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn event_stream_matches_filters(row: &Value, filters: &Value) -> bool {
    filters.as_object().is_none_or(|entries| {
        entries
            .iter()
            .all(|(key, expected)| row.get(key).is_some_and(|actual| actual == expected))
    })
}

/// Returns a bounded event resource identifier.
///
/// # Parameters
///
/// - `row`: Input consumed by [`crate::runtime::json_commands::event_stream_resource_id`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::event_stream_resource_id`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::event_stream_resource_id(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn event_stream_resource_id(row: &Value) -> Option<String> {
    row.get("resource_id")
        .or_else(|| row.get("id"))
        .map(value_to_text)
        .filter(|value| !value.is_empty())
}

/// Returns a positive event tenant identifier.
///
/// # Parameters
///
/// - `row`: Input consumed by [`crate::runtime::json_commands::event_stream_tenant_id`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::event_stream_tenant_id`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::event_stream_tenant_id(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn event_stream_tenant_id(row: &Value) -> i64 {
    row.get("tenant_id")
        .and_then(Value::as_i64)
        .unwrap_or(0)
        .max(0)
}

/// Finds an array row by a positive integer field.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::find_array_item_by_long_field`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::find_array_item_by_long_field`].
/// - `field`: Input consumed by [`crate::runtime::json_commands::find_array_item_by_long_field`].
/// - `wanted`: Input consumed by [`crate::runtime::json_commands::find_array_item_by_long_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::find_array_item_by_long_field`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::find_array_item_by_long_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::find_array_item_by_long_field(std::path::Path::new("."), "items", "field", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn find_array_item_by_long_field(
    root: &Value,
    section: &str,
    field: &str,
    wanted: i64,
) -> Option<String> {
    bounded_state_array(root, section)
        .iter()
        .find(|item| item.get(field).and_then(Value::as_i64) == Some(wanted))
        .and_then(compact)
}

/// Releases one optional event-stream row.
///
/// # Parameters
///
/// - `row`: Input consumed by [`crate::runtime::json_commands::free_event_stream_row`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::free_event_stream_row`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::free_event_stream_row(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn free_event_stream_row(row: &mut Option<super::json_ops::EventStreamRowRuntime>) {
    *row = None;
}

/// Produces the canonical generated-surface label for one field.
///
/// # Parameters
///
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::generated_surface_label_from_field`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::generated_surface_label_from_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_label_from_field(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_label_from_field(field_name: &str) -> String {
    super::dynamic::generated_surface_label(Some(field_name)).unwrap_or_default()
}

/// Appends one JSON value to an owned list.
///
/// # Parameters
///
/// - `list`: Input consumed by [`crate::runtime::json_commands::json_value_list_append`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_value_list_append`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::json_value_list_append`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_value_list_append(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_value_list_append(
    list: &mut super::dynamic::RuntimeJsonValueList,
    value: &Value,
) -> bool {
    super::dynamic::runtime_json_value_list_append(list, value)
}

/// Frees all values from an owned JSON list.
///
/// # Parameters
///
/// - `list`: Input consumed by [`crate::runtime::json_commands::json_value_list_free`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::json_value_list_free`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_value_list_free(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_value_list_free(list: &mut super::dynamic::RuntimeJsonValueList) {
    super::dynamic::runtime_json_value_list_free(list);
}

/// Applies the native truthiness contract to a JSON value.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_value_truthy`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::json_value_truthy`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_value_truthy("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_value_truthy(value: &Value) -> bool {
    match value {
        Value::Null => false,
        Value::Bool(value) => *value,
        Value::Number(value) => {
            value.as_i64().is_some_and(|value| value != 0)
                || value.as_f64().is_some_and(|value| value != 0.0)
        }
        Value::String(value) => {
            !value.is_empty() && !matches!(value.as_str(), "0" | "false" | "off" | "no")
        }
        Value::Array(value) => !value.is_empty(),
        Value::Object(value) => !value.is_empty(),
    }
}

/// Returns the first string value from a payload object or array.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::payload_first_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::payload_first_string`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::payload_first_string`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::payload_first_string("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn payload_first_string(value: &Value) -> Option<String> {
    match value {
        Value::String(value) if !value.is_empty() => Some(value.clone()),
        Value::Array(items) => items.iter().find_map(payload_first_string),
        Value::Object(object) => object.values().find_map(payload_first_string),
        _ => None,
    }
}

/// Reads a content-disposition parameter using strict quoted-field parsing.
///
/// # Parameters
///
/// - `headers`: Input consumed by [`crate::runtime::json_commands::content_disposition_param`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::content_disposition_param`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::content_disposition_param`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::content_disposition_param("host: example", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn content_disposition_param(headers: &str, key: &str) -> Option<String> {
    multipart_header_param(headers, key)
}

/// Returns the decoded value for one query key.
///
/// # Parameters
///
/// - `query`: Input consumed by [`crate::runtime::json_commands::query_value_decoded`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::query_value_decoded`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::query_value_decoded`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::query_value_decoded("page=1", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn query_value_decoded(query: &str, key: &str) -> Option<String> {
    request_query_value(query, key)
}

/// Classifies a resource identifier by its stable prefix.
///
/// # Parameters
///
/// - `resource_id`: Input consumed by [`crate::runtime::json_commands::resource_kind_from_resource_id`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::resource_kind_from_resource_id`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::resource_kind_from_resource_id`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::resource_kind_from_resource_id(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn resource_kind_from_resource_id(resource_id: &str) -> Option<&'static str> {
    let prefix = resource_id.split(':').next()?;
    match prefix {
        "user" => Some("user"),
        "business" => Some("business"),
        "service" => Some("service"),
        "technician" => Some("technician"),
        "appointment" => Some("appointment"),
        "tenant" => Some("tenant"),
        _ => None,
    }
}

/// Compares two surface values for stable sorting.
///
/// # Parameters
///
/// - `left`: Input consumed by [`crate::runtime::json_commands::surface_compare_sort_values`].
/// - `right`: Input consumed by [`crate::runtime::json_commands::surface_compare_sort_values`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::surface_compare_sort_values`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::surface_compare_sort_values(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn surface_compare_sort_values(left: &Value, right: &Value) -> std::cmp::Ordering {
    value_to_text(left).cmp(&value_to_text(right))
}

/// Finds one form declaration by its id.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::surface_find_form`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::surface_find_form`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::surface_find_form`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::surface_find_form`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::surface_find_form(std::path::Path::new("."), "form");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn surface_find_form(root: &Value, form_id: &str) -> Option<String> {
    root.get("forms")?
        .as_array()?
        .iter()
        .find(|form| form.get("form_id").and_then(Value::as_str) == Some(form_id))
        .and_then(compact)
}

/// Returns the first position of a byte needle in a bounded byte slice.
///
/// # Parameters
///
/// - `haystack`: Input consumed by [`crate::runtime::json_commands::memmem`].
/// - `needle`: Input consumed by [`crate::runtime::json_commands::memmem`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::memmem`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::memmem(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn memmem(haystack: &[u8], needle: &[u8]) -> Option<usize> {
    if needle.is_empty() {
        return Some(0);
    }
    haystack
        .windows(needle.len())
        .position(|window| window == needle)
}

/// Renders one generated-surface action link from an app-owned fragment.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_action_link`].
/// - `action_path`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_action_link`].
/// - `label`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_action_link`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_generated_surface_action_link`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_generated_surface_action_link(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_generated_surface_action_link(
    app_root: &Path,
    action_path: &str,
    label: &str,
) -> Option<String> {
    let params = Map::from_iter([
        (
            "action_path".to_owned(),
            Value::String(action_path.to_owned()),
        ),
        ("button_label".to_owned(), Value::String(label.to_owned())),
        (
            "button_class".to_owned(),
            Value::String("btn-secondary".to_owned()),
        ),
    ]);
    generated::render_generated_admin_fragment_from_value_runtime(
        app_root,
        "templates/shared/fragments/action_link.html",
        &params,
    )
}

/// Renders one generated-surface delete form from a validated action path.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_delete_form`].
/// - `action_path`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_delete_form`].
/// - `label`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_delete_form`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_generated_surface_delete_form`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_generated_surface_delete_form(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_generated_surface_delete_form(
    app_root: &Path,
    action_path: &str,
    label: &str,
) -> Option<String> {
    let params = Map::from_iter([
        (
            "action_path".to_owned(),
            Value::String(action_path.to_owned()),
        ),
        ("button_label".to_owned(), Value::String(label.to_owned())),
    ]);
    generated::render_generated_admin_fragment_from_value_runtime(
        app_root,
        "templates/generated_admin/fragments/delete_form.html",
        &params,
    )
}

/// Renders a generated-surface table header cell.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_header_cell`].
/// - `label`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_header_cell`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_generated_surface_table_header_cell`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_generated_surface_table_header_cell(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_generated_surface_table_header_cell(app_root: &Path, label: &str) -> Option<String> {
    generated::render_generated_admin_fragment_from_value_runtime(
        app_root,
        "templates/generated_admin/fragments/table_header_cell.html",
        &Map::from_iter([("column_label".to_owned(), Value::String(label.to_owned()))]),
    )
}

/// Renders a generated-surface table row cell.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_row_cell`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_row_cell`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_generated_surface_table_row_cell`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_generated_surface_table_row_cell(std::path::Path::new("apps/dev_docs"), "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_generated_surface_table_row_cell(app_root: &Path, value: &str) -> Option<String> {
    generated::render_generated_admin_fragment_from_value_runtime(
        app_root,
        "templates/generated_admin/fragments/table_row_cell.html",
        &Map::from_iter([("field_value".to_owned(), Value::String(value.to_owned()))]),
    )
}

/// Renders the action cell of one generated-surface row.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_action_cell`].
/// - `edit_path`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_action_cell`].
/// - `delete_path`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_action_cell`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_generated_surface_table_action_cell`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_generated_surface_table_action_cell(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_generated_surface_table_action_cell(
    app_root: &Path,
    edit_path: Option<&str>,
    delete_path: Option<&str>,
) -> Option<String> {
    let mut output = String::new();
    if let Some(path) = edit_path.filter(|value| !value.is_empty()) {
        output.push_str(&render_generated_surface_action_link(
            app_root, path, "Edit",
        )?);
    }
    if let Some(path) = delete_path.filter(|value| !value.is_empty()) {
        output.push_str(&render_generated_surface_delete_form(
            app_root, path, "Delete",
        )?);
    }
    Some(output)
}

/// Renders one generated-surface table row from cell values.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_row`].
/// - `cells_html`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_row`].
/// - `action_cell_html`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_table_row`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_generated_surface_table_row`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_generated_surface_table_row(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_generated_surface_table_row(
    app_root: &Path,
    cells_html: &str,
    action_cell_html: &str,
) -> Option<String> {
    generated::render_generated_admin_fragment_from_value_runtime(
        app_root,
        "templates/generated_admin/fragments/table_row.html",
        &Map::from_iter([
            (
                "cells_html".to_owned(),
                Value::String(cells_html.to_owned()),
            ),
            (
                "action_cell_html".to_owned(),
                Value::String(action_cell_html.to_owned()),
            ),
        ]),
    )
}

/// Tests whether an array contains a positive integer.
///
/// # Parameters
///
/// - `values`: Input consumed by [`crate::runtime::json_commands::json_array_contains_long`].
/// - `wanted`: Input consumed by [`crate::runtime::json_commands::json_array_contains_long`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::json_array_contains_long`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::json_array_contains_long`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_array_contains_long(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_array_contains_long(values: &Value, wanted: i64) -> bool {
    values
        .as_array()
        .is_some_and(|items| items.iter().any(|item| item.as_i64() == Some(wanted)))
}

/// Returns the first positive integer in a payload.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::payload_first_long`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::payload_first_long`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::payload_first_long`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::payload_first_long("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn payload_first_long(value: &Value) -> Option<i64> {
    match value {
        Value::Number(value) => value.as_i64().filter(|value| *value > 0),
        Value::Array(items) => items.iter().find_map(payload_first_long),
        Value::Object(object) => object.values().find_map(payload_first_long),
        _ => None,
    }
}

/// Tests one JSON value against a signed integer.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::value_long_equals`].
/// - `wanted`: Input consumed by [`crate::runtime::json_commands::value_long_equals`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::value_long_equals`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::value_long_equals("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn value_long_equals(value: &Value, wanted: i64) -> bool {
    value.as_i64() == Some(wanted)
}

/// Returns the bounded weekday rank used by calendar sorting.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::weekday_rank`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::weekday_rank`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::weekday_rank("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn weekday_rank(value: &str) -> u8 {
    match value.to_ascii_lowercase().as_str() {
        "mon" | "monday" => 1,
        "tue" | "tuesday" => 2,
        "wed" | "wednesday" => 3,
        "thu" | "thursday" => 4,
        "fri" | "friday" => 5,
        "sat" | "saturday" => 6,
        "sun" | "sunday" => 7,
        _ => 0,
    }
}

/// Performs a case-insensitive equality check.
///
/// # Parameters
///
/// - `left`: Input consumed by [`crate::runtime::json_commands::streq_casefold`].
/// - `right`: Input consumed by [`crate::runtime::json_commands::streq_casefold`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::streq_casefold`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::streq_casefold(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn streq_casefold(left: &str, right: &str) -> bool {
    left.eq_ignore_ascii_case(right)
}

/// Returns the JSON array for one state section.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::state_array`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::state_array`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::state_array`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::state_array(std::path::Path::new("."), "items");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn state_array(root: &Value, section: &str) -> Option<Vec<Value>> {
    Some(bounded_state_array(root, section).to_vec())
}

/// Matches a generated-surface context against a request context.
///
/// # Parameters
///
/// - `surface`: Input consumed by [`crate::runtime::json_commands::surface_context_match`].
/// - `context`: Input consumed by [`crate::runtime::json_commands::surface_context_match`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::surface_context_match`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::surface_context_match(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn surface_context_match(surface: &Value, context: &Value) -> bool {
    surface
        .get("context_binding")
        .and_then(Value::as_object)
        .is_none_or(|binding| {
            binding
                .get("param")
                .and_then(Value::as_str)
                .is_none_or(|param| surface.get(param) == context.get(param))
        })
}

/// Renders a generated-surface submit button through the app-owned fragment.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_submit_button`].
/// - `label`: Input consumed by [`crate::runtime::json_commands::render_generated_surface_submit_button`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_generated_surface_submit_button`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_generated_surface_submit_button(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_generated_surface_submit_button(app_root: &Path, label: &str) -> Option<String> {
    generated::render_generated_admin_fragment_from_value_runtime(
        app_root,
        "templates/shared/fragments/submit_button.html",
        &Map::from_iter([("button_label".to_owned(), Value::String(label.to_owned()))]),
    )
}

/// Tests whether a bounded integer array contains one value.
///
/// # Parameters
///
/// - `values`: Input consumed by [`crate::runtime::json_commands::long_in_array`].
/// - `wanted`: Input consumed by [`crate::runtime::json_commands::long_in_array`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::long_in_array`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::long_in_array(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn long_in_array(values: &Value, wanted: i64) -> bool {
    json_array_contains_long(values, wanted)
}

/// Decodes one URL query component with plus and percent handling.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::url_decode`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::url_decode`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::url_decode("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn url_decode(value: &str) -> Option<String> {
    url_decode_component(value)
}

/// Matches one generated API/admin operation in a contract file.
///
/// # Parameters
///
/// - `file_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_api_match`].
/// - `method`: Input consumed by [`crate::runtime::json_commands::generated_surface_api_match`].
/// - `request_path`: Input consumed by [`crate::runtime::json_commands::generated_surface_api_match`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_surface_api_match`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_api_match(todo!(), todo!(), "/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_api_match(
    file_path: &Path,
    method: &str,
    request_path: &str,
) -> Option<String> {
    file_generated_surface_match(file_path, method, request_path)
}

/// Releases an owned generated-surface match result.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::generated_surface_api_match_free`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::generated_surface_api_match_free`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_api_match_free("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_api_match_free(value: &mut Option<String>) {
    value.take();
}

/// Matches a dynamic dispatch request against an app-owned route contract.
///
/// # Parameters
///
/// - `file_path`: Input consumed by [`crate::runtime::json_commands::dynamic_dispatch_match`].
/// - `method`: Input consumed by [`crate::runtime::json_commands::dynamic_dispatch_match`].
/// - `request_path`: Input consumed by [`crate::runtime::json_commands::dynamic_dispatch_match`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_dispatch_match`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_dispatch_match(todo!(), todo!(), "/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_dispatch_match(
    file_path: &Path,
    method: &str,
    request_path: &str,
) -> Option<String> {
    generated_surface_api_match(file_path, method, request_path)
}

/// Resolves a route fixture path below an app root without traversal.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_dispatch_resolve_route_fixture`].
/// - `relative_path`: Input consumed by [`crate::runtime::json_commands::dynamic_dispatch_resolve_route_fixture`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_dispatch_resolve_route_fixture`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_dispatch_resolve_route_fixture`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_dispatch_resolve_route_fixture(std::path::Path::new("apps/dev_docs"), "page");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_dispatch_resolve_route_fixture(
    app_root: &Path,
    relative_path: &str,
) -> Option<String> {
    if app_root.as_os_str().is_empty()
        || relative_path.is_empty()
        || Path::new(relative_path).is_absolute()
        || relative_path.split('/').any(|segment| segment == "..")
    {
        return None;
    }
    let path = app_root.join(relative_path);
    path.is_file().then(|| path.to_string_lossy().into_owned())
}

/// Reads a bounded response file below an app artifact root.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_dispatch_response_file`].
/// - `relative_path`: Input consumed by [`crate::runtime::json_commands::dynamic_dispatch_response_file`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_dispatch_response_file`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_dispatch_response_file`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_dispatch_response_file(std::path::Path::new("apps/dev_docs"), "page");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_dispatch_response_file(app_root: &Path, relative_path: &str) -> Option<String> {
    let path = dynamic_dispatch_resolve_route_fixture(app_root, relative_path)?;
    let text = fs::read_to_string(path).ok()?;
    (text.len() <= MAX_TEXT_BYTES).then_some(text)
}

/// Recognizes static media and static asset request paths.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::dynamic_media_is_static_path`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::dynamic_media_is_static_path`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_media_is_static_path(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_media_is_static_path(path: &str) -> bool {
    path.starts_with("/static/") || path.starts_with("/media/")
}

/// Extracts the query component without decoding its individual values.
///
/// # Parameters
///
/// - `target`: Input consumed by [`crate::runtime::json_commands::extract_query`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::extract_query`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::extract_query`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::extract_query("/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn extract_query(target: &str) -> String {
    target
        .split_once('?')
        .map(|(_, query)| query.split('#').next().unwrap_or_default().to_owned())
        .unwrap_or_default()
}

/// Handles a framework webhook request using the shared endpoint contract.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::handle_framework_webhook_request`].
/// - `endpoint_id`: Input consumed by [`crate::runtime::json_commands::handle_framework_webhook_request`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_framework_webhook_request`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::handle_framework_webhook_request`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_framework_webhook_request(std::path::Path::new("."), "webhook");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_framework_webhook_request(root: &Value, endpoint_id: &str) -> Option<String> {
    if endpoint_id.is_empty() {
        return None;
    }
    bounded_state_array(root, "webhook_events")
        .iter()
        .find(|row| row.get("endpoint_id").and_then(Value::as_str) == Some(endpoint_id))
        .and_then(compact)
}

/// Handles one generated-surface API request from a route-match document.
///
/// # Parameters
///
/// - `match_json`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_api_request`].
/// - `state_root`: Input consumed by [`crate::runtime::json_commands::handle_generated_surface_api_request`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_generated_surface_api_request`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::handle_generated_surface_api_request`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_generated_surface_api_request(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_api_request(
    match_json: &str,
    state_root: &Value,
) -> Option<String> {
    let matched = serde_json::from_str::<Value>(match_json).ok()?;
    let operation = matched.get("operation").and_then(Value::as_str)?;
    compact(&serde_json::json!({"operation": operation, "state": state_root}))
}

/// Handles one page route by returning its declared template path.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::handle_page_route`].
/// - `page_id`: Input consumed by [`crate::runtime::json_commands::handle_page_route`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_page_route`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_page_route(std::path::Path::new("apps/dev_docs"), "home");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_page_route(app_root: &Path, page_id: &str) -> Option<String> {
    declared_page_relative_path(app_root, page_id)
}

/// Handles one action route by returning its declared operation path.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::handle_action_route`].
/// - `operation`: Input consumed by [`crate::runtime::json_commands::handle_action_route`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::handle_action_route`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::handle_action_route`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::handle_action_route("{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn handle_action_route(surface_json: &str, operation: &str) -> Option<String> {
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    surface
        .get("operations")?
        .get(operation)?
        .get("path")
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
}

/// Removes query and fragment components from a route request path.
///
/// # Parameters
///
/// - `target`: Input consumed by [`crate::runtime::json_commands::route_request_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::route_request_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::route_request_path("/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn route_request_path(target: &str) -> Option<String> {
    super::http::request_path_without_query(target)
}

/// Performs safe contract relative path.
fn safe_contract_relative_path(root: &Path, relative: &str) -> Option<PathBuf> {
    let path = Path::new(relative);
    if relative.is_empty() || path.is_absolute() {
        return None;
    }
    if path.components().any(|component| {
        matches!(
            component,
            Component::ParentDir | Component::RootDir | Component::Prefix(_)
        )
    }) {
        return None;
    }
    Some(root.join(path))
}

/// Computes a lowercase SHA-256 digest without invoking an external process.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::migration_sha256_text`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::migration_sha256_text`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::migration_sha256_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::migration_sha256_text("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn migration_sha256_text(value: &str) -> String {
    let digest = Sha256::digest(value.as_bytes());
    digest.iter().map(|byte| format!("{byte:02x}")).collect()
}

/// Returns a JSON literal string, preserving the caller-supplied literal text.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_literal`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::json_literal`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_literal("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_literal(value: &str) -> String {
    value.to_owned()
}

/// Serializes an optional string as JSON, using the JSON null literal when absent.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_nullable_string`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::json_nullable_string`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_nullable_string("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_nullable_string(value: Option<&str>) -> String {
    value
        .filter(|text| !text.is_empty())
        .map(|text| serde_json::to_string(text).unwrap_or_else(|_| "null".to_owned()))
        .unwrap_or_else(|| "null".to_owned())
}

/// Serializes a JSON value or returns a validated fallback literal.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_value_or_literal`].
/// - `fallback`: Input consumed by [`crate::runtime::json_commands::json_value_or_literal`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::json_value_or_literal`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_value_or_literal("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_value_or_literal(value: Option<&Value>, fallback: &str) -> String {
    value
        .and_then(|item| serde_json::to_string(item).ok())
        .unwrap_or_else(|| fallback.to_owned())
}

/// Serializes an object string field with a plain-string fallback.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_object_string_json`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_object_string_json`].
/// - `fallback`: Input consumed by [`crate::runtime::json_commands::json_object_string_json`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::json_object_string_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_object_string_json("value", "key", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_object_string_json(value: &Value, key: &str, fallback: &str) -> String {
    let text = value.get(key).and_then(Value::as_str).unwrap_or(fallback);
    serde_json::to_string(text).unwrap_or_else(|_| "\"\"".to_owned())
}

/// Serializes an integer as JSON number text.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::long_json`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::long_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::long_json("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn long_json(value: i64) -> String {
    value.to_string()
}

/// Appends one serialized item to a JSON array under construction.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::json_commands::append_json_item`].
/// - `json_item`: Input consumed by [`crate::runtime::json_commands::append_json_item`].
/// - `first`: Input consumed by [`crate::runtime::json_commands::append_json_item`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::append_json_item`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::append_json_item(&mut [], todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn append_json_item(buffer: &mut String, json_item: &str, first: &mut bool) -> bool {
    if json_item.is_empty() {
        return false;
    }
    if *first {
        buffer.push('[');
        *first = false;
    } else if buffer.is_empty() || buffer.ends_with(']') {
        return false;
    } else {
        buffer.push(',');
    }
    buffer.push_str(json_item);
    true
}

/// Serializes and appends one string item to a JSON array under construction.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::json_commands::append_json_string_item`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::append_json_string_item`].
/// - `first`: Input consumed by [`crate::runtime::json_commands::append_json_string_item`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::append_json_string_item`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::append_json_string_item(&mut [], "value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn append_json_string_item(buffer: &mut String, value: Option<&str>, first: &mut bool) -> bool {
    let item = serde_json::to_string(value.unwrap_or_default()).ok();
    item.as_deref()
        .is_some_and(|json| append_json_item(buffer, json, first))
}

/// Completes a JSON array under construction.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::json_commands::finish_json_array`].
/// - `first`: Input consumed by [`crate::runtime::json_commands::finish_json_array`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::finish_json_array`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::finish_json_array(&mut [], todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn finish_json_array(buffer: &mut String, first: bool) -> Option<String> {
    if first {
        return Some("[]".to_owned());
    }
    if !buffer.starts_with('[') || buffer.ends_with(']') {
        return None;
    }
    buffer.push(']');
    Some(buffer.clone())
}

/// Checks a seed row count against exact and minimum expectations.
///
/// # Parameters
///
/// - `row_count`: Observed seeded row count.
/// - `minimum_rows`: Optional minimum row threshold to enforce.
/// - `exact_rows`: Optional exact row count to enforce.
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::json_commands::seed_expectation_satisfied`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::json_commands::seed_expectation_satisfied`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::seed_expectation_satisfied(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn seed_expectation_satisfied(
    row_count: i64,
    minimum_rows: Option<i64>,
    exact_rows: Option<i64>,
) -> Result<(), &'static str> {
    if exact_rows.is_some_and(|expected| row_count != expected) {
        return Err("exact_rows_mismatch");
    }
    if minimum_rows.is_some_and(|minimum| row_count < minimum) {
        return Err("minimum_rows_not_met");
    }
    Ok(())
}

/// Checks whether an applied migration checksum matches any accepted checksum.
///
/// # Parameters
///
/// - `applied`: Input consumed by [`crate::runtime::json_commands::migration_checksum_matches`].
/// - `applied_checksum`: Input consumed by [`crate::runtime::json_commands::migration_checksum_matches`].
/// - `expected_checksum`: Input consumed by [`crate::runtime::json_commands::migration_checksum_matches`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::migration_checksum_matches`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::migration_checksum_matches(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn migration_checksum_matches(
    applied: bool,
    applied_checksum: Option<&str>,
    expected_checksum: Option<&str>,
) -> bool {
    let Some(applied_checksum) = applied_checksum.filter(|value| !value.is_empty()) else {
        return false;
    };
    if !applied {
        return false;
    }
    expected_checksum == Some(applied_checksum)
}

/// Returns a migration contract path declared by an app manifest.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::migration_fixture_path_dup_runtime_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::migration_fixture_path_dup_runtime_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::migration_fixture_path_dup_runtime_local(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn migration_fixture_path_dup_runtime_local(app_root: &Path) -> Option<PathBuf> {
    let relative = manifest_database_contract_path(app_root)?;
    safe_contract_relative_path(app_root, &relative)
}

/// Returns a backend record from an array of JSON objects by exact string field.
///
/// # Parameters
///
/// - `array`: Input consumed by [`crate::runtime::json_commands::json_find_object_by_string_field`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::json_find_object_by_string_field`].
/// - `expected_value`: Input consumed by [`crate::runtime::json_commands::json_find_object_by_string_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_find_object_by_string_field`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::json_find_object_by_string_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_find_object_by_string_field(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_find_object_by_string_field<'a>(
    array: &'a Value,
    field_name: &str,
    expected_value: &str,
) -> Option<&'a Value> {
    array
        .as_array()?
        .iter()
        .find(|item| item.get(field_name).and_then(Value::as_str) == Some(expected_value))
}

/// Finds a migration record by its stable migration id.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::json_find_migration_by_id`].
/// - `migration_id`: Input consumed by [`crate::runtime::json_commands::json_find_migration_by_id`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_find_migration_by_id`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_find_migration_by_id(std::path::Path::new("."), "001_init");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_find_migration_by_id<'a>(root: &'a Value, migration_id: &str) -> Option<&'a Value> {
    json_find_object_by_string_field(root.get("migrations")?, "migration_id", migration_id)
}

/// Computes a bounded content signature for relational state synchronization.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::dynamic_relational_file_signature`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_relational_file_signature`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_relational_file_signature`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_relational_file_signature(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_relational_file_signature(path: &Path) -> Option<String> {
    if path.as_os_str().is_empty() {
        return None;
    }
    if !path.exists() {
        return Some("missing".to_owned());
    }
    let bytes = fs::read(path).ok()?;
    let mut hash = 1469598103934665603u64;
    for byte in &bytes {
        hash ^= u64::from(*byte);
        hash = hash.wrapping_mul(1099511628211);
    }
    Some(format!("{hash:016x}:{}", bytes.len()))
}

/// Emits a generated-surface schema response from contract JSON.
///
/// # Parameters
///
/// - `surface_json`: Input consumed by [`crate::runtime::json_commands::write_generated_surface_schema_response`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::write_generated_surface_schema_response`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::write_generated_surface_schema_response`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::write_generated_surface_schema_response("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn write_generated_surface_schema_response(surface_json: &str) -> Option<String> {
    let surface = serde_json::from_str::<Value>(surface_json).ok()?;
    compact(surface.get("schema").unwrap_or(&surface))
}

/// Renders a bounded path template with explicit placeholder replacement.
///
/// # Parameters
///
/// - `template`: Input consumed by [`crate::runtime::json_commands::render_path_template_text`].
/// - `values`: Input consumed by [`crate::runtime::json_commands::render_path_template_text`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_path_template_text`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::render_path_template_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_path_template_text(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_path_template_text(template: &str, values: &Value) -> Option<String> {
    if template.len() > 64 * 1024 {
        return None;
    }
    let mut output = template.to_owned();
    if let Some(map) = values.as_object() {
        for (key, value) in map {
            let text = value
                .as_str()
                .or_else(|| {
                    value
                        .as_i64()
                        .map(|number| Box::leak(number.to_string().into_boxed_str()) as &str)
                })
                .unwrap_or_default();
            output = output.replace(&format!("{{{key}}}"), text);
        }
    }
    Some(output)
}

/// Serializes one JSON value using the compact runtime policy.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_value_tostring`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_value_tostring`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_value_tostring("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_value_tostring(value: &Value) -> Option<String> {
    serde_json::to_string(value).ok()
}

/// Resolves the declared deletion strategy with a safe default.
///
/// # Parameters
///
/// - `surface`: Input consumed by [`crate::runtime::json_commands::generated_surface_delete_strategy`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::generated_surface_delete_strategy`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_surface_delete_strategy(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_delete_strategy(surface: &Value) -> String {
    surface
        .get("delete_strategy")
        .and_then(Value::as_str)
        .filter(|value| matches!(*value, "soft" | "hard" | "none"))
        .unwrap_or("soft")
        .to_owned()
}

/// Renders a public-state button fragment with HTML-escaped business context.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_render_business_admin_public_state_button_html`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_render_business_admin_public_state_button_html`].
/// - `is_public`: Input consumed by [`crate::runtime::json_commands::dynamic_render_business_admin_public_state_button_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_render_business_admin_public_state_button_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_render_business_admin_public_state_button_html(std::path::Path::new("apps/dev_docs"), "demo", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_render_business_admin_public_state_button_html(
    app_root: &Path,
    business_slug: &str,
    is_public: bool,
) -> Option<String> {
    if app_root.as_os_str().is_empty()
        || business_slug.is_empty()
        || business_slug.contains(['/', '\\'])
    {
        return None;
    }
    let button_label = if is_public { "Public" } else { "Private" };
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/public_state_toggle_button.html",
        serde_json::Map::from_iter([
            (
                "button_label".to_owned(),
                Value::String(button_label.to_owned()),
            ),
            ("is_public".to_owned(), Value::String(is_public.to_string())),
            (
                "state_class".to_owned(),
                Value::String(
                    if is_public {
                        "business-is-public"
                    } else {
                        "business-is-private"
                    }
                    .to_owned(),
                ),
            ),
        ]),
    )
}

/// Renders availability rows from an app-owned state document.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_render_business_admin_availability_rows_html`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_render_business_admin_availability_rows_html`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_render_business_admin_availability_rows_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_render_business_admin_availability_rows_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_render_business_admin_availability_rows_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_render_business_admin_availability_rows_html(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_render_business_admin_availability_rows_html(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    if app_root.as_os_str().is_empty() || business_slug.is_empty() {
        return None;
    }
    let business_id = state_row_by_id(
        &serde_json::json!({
            "businesses": bounded_state_array(root, "businesses")
                .iter()
                .filter(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))
                .cloned()
                .collect::<Vec<_>>()
        }),
        "businesses",
        bounded_state_array(root, "businesses")
            .iter()
            .find(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))
            .and_then(|row| row.get("id").and_then(Value::as_i64))?,
    )?
    .get("id")
    .and_then(Value::as_i64)?;
    let mut availability_rows = bounded_state_array(root, "business_availability")
        .iter()
        .filter(|row| row.get("business_id").and_then(Value::as_i64) == Some(business_id))
        .collect::<Vec<_>>();
    availability_rows.sort_by_key(|row| {
        (
            weekday_rank(
                &row.get("day_of_week")
                    .map(value_to_text)
                    .unwrap_or_default(),
            ),
            row.get("start_time").map(value_to_text).unwrap_or_default(),
            row.get("id").and_then(Value::as_i64).unwrap_or_default(),
        )
    });
    let mut output = String::new();
    for row in availability_rows {
        let availability_id = row.get("id").and_then(Value::as_i64)?;
        let day_of_week = row
            .get("day_of_week")
            .map(value_to_text)
            .unwrap_or_default();
        let start_time = row
            .get("start_time")
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "09:00".to_owned());
        let end_time = row
            .get("end_time")
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "17:00".to_owned());
        let hidden_day_input = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/ui_hidden_input.html",
            serde_json::Map::from_iter([
                (
                    "id".to_owned(),
                    Value::String("availability_row_day_hidden_input".to_owned()),
                ),
                ("name".to_owned(), Value::String("day_of_week".to_owned())),
                ("value".to_owned(), Value::String(day_of_week.clone())),
                ("attributes_html".to_owned(), Value::String(String::new())),
            ]),
        )?;
        let start_input = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/ui_input.html",
            serde_json::Map::from_iter([
                (
                    "id".to_owned(),
                    Value::String("availability_row_start_time_input".to_owned()),
                ),
                ("input_type".to_owned(), Value::String("time".to_owned())),
                ("name".to_owned(), Value::String("start_time".to_owned())),
                ("label".to_owned(), Value::String("Start time".to_owned())),
                (
                    "label_class".to_owned(),
                    Value::String("sr-only".to_owned()),
                ),
                (
                    "class_name".to_owned(),
                    Value::String("form-control availability-inline-input".to_owned()),
                ),
                ("value".to_owned(), Value::String(start_time.clone())),
                (
                    "attributes_html".to_owned(),
                    Value::String(" aria-label=\"Start time\"".to_owned()),
                ),
                ("help_html".to_owned(), Value::String(String::new())),
            ]),
        )?;
        let end_input = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/ui_input.html",
            serde_json::Map::from_iter([
                (
                    "id".to_owned(),
                    Value::String("availability_row_end_time_input".to_owned()),
                ),
                ("input_type".to_owned(), Value::String("time".to_owned())),
                ("name".to_owned(), Value::String("end_time".to_owned())),
                ("label".to_owned(), Value::String("End time".to_owned())),
                (
                    "label_class".to_owned(),
                    Value::String("sr-only".to_owned()),
                ),
                (
                    "class_name".to_owned(),
                    Value::String("form-control availability-inline-input".to_owned()),
                ),
                ("value".to_owned(), Value::String(end_time.clone())),
                (
                    "attributes_html".to_owned(),
                    Value::String(" aria-label=\"End time\"".to_owned()),
                ),
                ("help_html".to_owned(), Value::String(String::new())),
            ]),
        )?;
        let save_button = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/ui_button.html",
            serde_json::Map::from_iter([
                (
                    "id".to_owned(),
                    Value::String("availability_row_save_button".to_owned()),
                ),
                ("button_type".to_owned(), Value::String("submit".to_owned())),
                (
                    "class_name".to_owned(),
                    Value::String(
                        "btn btn-success btn-icon btn-icon-sm business-admin-save-button"
                            .to_owned(),
                    ),
                ),
                (
                    "attributes_html".to_owned(),
                    Value::String(
                        " title=\"Save Availability\" aria-label=\"Save Availability\"".to_owned(),
                    ),
                ),
                (
                    "content_html".to_owned(),
                    Value::String(
                        generated::render_generated_admin_fragment_from_value_runtime(
                            app_root,
                            "templates/shared/fragments/ui_content_save_availability.html",
                            &serde_json::Map::new(),
                        )?,
                    ),
                ),
            ]),
        )?;
        let delete_button = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/ui_button.html",
            serde_json::Map::from_iter([
                (
                    "id".to_owned(),
                    Value::String("availability_row_delete_button".to_owned()),
                ),
                ("button_type".to_owned(), Value::String("button".to_owned())),
                (
                    "class_name".to_owned(),
                    Value::String("btn btn-danger btn-icon btn-icon-sm".to_owned()),
                ),
                (
                    "attributes_html".to_owned(),
                    Value::String(format!(
                        " title=\"Delete Availability\" aria-label=\"Delete Availability\" hx-post=\"/businesses/{business_slug}/availability/{availability_id}/delete/\" hx-include=\"closest form\" hx-target=\"#business-availability-rows\" hx-swap=\"innerHTML\""
                    )),
                ),
                (
                    "content_html".to_owned(),
                    Value::String(
                        generated::render_generated_admin_fragment_from_value_runtime(
                            app_root,
                            "templates/shared/fragments/ui_content_delete_availability.html",
                            &serde_json::Map::new(),
                        )?,
                    ),
                ),
            ]),
        )?;
        output.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_admin_availability_row.html",
            serde_json::Map::from_iter([
                ("day_of_week".to_owned(), Value::String(day_of_week)),
                (
                    "start_display".to_owned(),
                    Value::String(start_time.clone()),
                ),
                ("end_display".to_owned(), Value::String(end_time.clone())),
                (
                    "save_path".to_owned(),
                    Value::String(format!(
                        "/businesses/{business_slug}/availability/{availability_id}/edit/"
                    )),
                ),
                (
                    "availability_row_day_hidden_input_ui_html".to_owned(),
                    Value::String(hidden_day_input),
                ),
                (
                    "availability_row_start_time_input_ui_html".to_owned(),
                    Value::String(start_input),
                ),
                (
                    "availability_row_end_time_input_ui_html".to_owned(),
                    Value::String(end_input),
                ),
                (
                    "availability_row_save_button_ui_html".to_owned(),
                    Value::String(save_button),
                ),
                (
                    "availability_row_delete_button_ui_html".to_owned(),
                    Value::String(delete_button),
                ),
            ]),
        )?);
    }
    Some(output)
}

/// Performs page params value.
fn page_params_value(root: &Value, page_id: &str, extra: Map<String, Value>) -> Option<String> {
    if page_id.is_empty() {
        return None;
    }
    let mut params = Map::new();
    params.insert("page_id".to_owned(), Value::String(page_id.to_owned()));
    params.insert("state".to_owned(), Value::Object(extra));
    params.insert(
        "record_count".to_owned(),
        Value::from(root.as_object().map(|object| object.len()).unwrap_or(0)),
    );
    compact(&Value::Object(params))
}

fn row_i64_value(row: &Value, field: &str) -> Option<i64> {
    row.get(field).and_then(Value::as_i64).or_else(|| {
        row.get(field)
            .and_then(Value::as_str)
            .and_then(|value| value.parse::<i64>().ok())
    })
}

fn state_row_by_i64<'a>(
    root: &'a Value,
    section: &str,
    field: &str,
    expected: i64,
) -> Option<&'a Value> {
    bounded_state_array(root, section)
        .iter()
        .find(|row| row_i64_value(row, field) == Some(expected))
}

fn row_date_time(row: &Value) -> (String, String) {
    let date = row
        .get("date")
        .map(value_to_text)
        .filter(|value| !value.is_empty())
        .or_else(|| {
            row.get("start_time")
                .map(value_to_text)
                .and_then(|value| value.get(0..10).map(ToOwned::to_owned))
        })
        .unwrap_or_default();
    let time = row
        .get("time")
        .map(value_to_text)
        .filter(|value| !value.is_empty())
        .or_else(|| {
            row.get("start_time")
                .map(value_to_text)
                .and_then(|value| value.get(11..16).map(ToOwned::to_owned))
        })
        .unwrap_or_default();
    (date, time)
}

/// Builds the availability edit page parameters from persisted state.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::dynamic_business_availability_edit_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_availability_edit_page_params_json`].
/// - `availability_id`: Input consumed by [`crate::runtime::json_commands::dynamic_business_availability_edit_page_params_json`].
/// - `error_text`: Input consumed by [`crate::runtime::json_commands::dynamic_business_availability_edit_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_availability_edit_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_availability_edit_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_availability_edit_page_params_json(todo!(), "demo", todo!(), todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_availability_edit_page_params_json(
    state_path: &Path,
    business_slug: &str,
    availability_id: i64,
    error_text: &str,
    app_root: &Path,
) -> Option<String> {
    let root = json_doc_load_file(state_path)?;
    let mut extra = Map::new();
    extra.insert("business_slug".into(), Value::String(business_slug.into()));
    extra.insert("availability_id".into(), Value::from(availability_id));
    extra.insert("error".into(), Value::String(error_text.into()));
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    page_params_value(&root, "business-availability-edit", extra)
}

/// Builds the business delete confirmation page parameters.
///
/// # Parameters
///
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_delete_confirm_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_delete_confirm_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_delete_confirm_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_delete_confirm_page_params_json("demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_delete_confirm_page_params_json(
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("business_slug".into(), Value::String(business_slug.into()));
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    page_params_value(&Value::Object(Map::new()), "business-delete-confirm", extra)
}

/// Builds the invite-accept page parameter document.
///
/// # Parameters
///
/// - `token`: Input consumed by [`crate::runtime::json_commands::dynamic_invite_accept_page_params_json`].
/// - `error_text`: Input consumed by [`crate::runtime::json_commands::dynamic_invite_accept_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_invite_accept_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_invite_accept_page_params_json(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_invite_accept_page_params_json(token: &str, error_text: &str) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("token".into(), Value::String(token.into()));
    extra.insert("error".into(), Value::String(error_text.into()));
    page_params_value(&Value::Null, "invite-accept", extra)
}

/// Builds a validated generated-admin operation URL.
///
/// # Parameters
///
/// - `base_path`: Input consumed by [`crate::runtime::json_commands::generated_admin_operation_path_dup_business_logic_local`].
/// - `operation`: Input consumed by [`crate::runtime::json_commands::generated_admin_operation_path_dup_business_logic_local`].
/// - `record_id`: Input consumed by [`crate::runtime::json_commands::generated_admin_operation_path_dup_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::generated_admin_operation_path_dup_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::generated_admin_operation_path_dup_business_logic_local("/app", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn generated_admin_operation_path_dup_business_logic_local(
    base_path: &str,
    operation: &str,
    record_id: i64,
) -> Option<String> {
    if operation.is_empty() || record_id <= 0 || base_path.contains(['\r', '\n']) {
        return None;
    }
    Some(format!(
        "{}/{}/{}",
        base_path.trim_end_matches('/'),
        operation,
        record_id
    ))
}

/// Builds generated-admin management page parameters from state.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_generated_admin_manage_page_params_json`].
/// - `collection`: Input consumed by [`crate::runtime::json_commands::dynamic_generated_admin_manage_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_generated_admin_manage_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_generated_admin_manage_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_generated_admin_manage_page_params_json(std::path::Path::new("."), todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_generated_admin_manage_page_params_json(
    root: &Value,
    collection: &str,
    app_root: &Path,
) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("collection".into(), Value::String(collection.into()));
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    extra.insert(
        "rows".into(),
        Value::Array(bounded_state_array(root, collection).to_vec()),
    );
    page_params_value(root, "generated-admin-manage", extra)
}

/// Converts a JSON value to its compact scalar representation.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_value_tostring_dup_runtime_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_value_tostring_dup_runtime_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_value_tostring_dup_runtime_local("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_value_tostring_dup_runtime_local(value: &Value) -> Option<String> {
    compact(value)
}

/// Returns a bounded composition string from a surface value.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::runtime_generated_surface_composition_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::runtime_generated_surface_composition_string`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_generated_surface_composition_string("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_composition_string(value: &Value) -> Option<String> {
    value
        .as_str()
        .map(strdup)
        .filter(|value| value.len() <= MAX_TEXT_BYTES)
}

/// Returns the generated delete-button label.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::runtime_generated_surface_delete_button_label`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_generated_surface_delete_button_label();
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_delete_button_label() -> String {
    "Delete".to_owned()
}

/// Converts one display value to escaped text.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::runtime_generated_surface_display_value`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::runtime_generated_surface_display_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_generated_surface_display_value("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_display_value(value: &Value) -> String {
    html_escape_text(&value_to_text(value))
}

/// Returns a generated field label from a field declaration.
///
/// # Parameters
///
/// - `field`: Input consumed by [`crate::runtime::json_commands::runtime_generated_surface_label`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::runtime_generated_surface_label`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_generated_surface_label("field");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_label(field: &Value) -> String {
    field
        .get("label")
        .and_then(Value::as_str)
        .or_else(|| field.get("field_id").and_then(Value::as_str))
        .map(strdup)
        .unwrap_or_default()
}

/// Takes a text buffer and leaves it empty.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::json_commands::runtime_text_buffer_take`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::runtime_text_buffer_take`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_text_buffer_take(&mut []);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_text_buffer_take(buffer: &mut String) -> String {
    std::mem::take(buffer)
}

/// Builds appointments page parameters from a state root.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_appointments_page_params_from_root_json`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::dynamic_appointments_page_params_from_root_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_appointments_page_params_from_root_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_appointments_page_params_from_root_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_appointments_page_params_from_root_json(std::path::Path::new("."), 1, std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_appointments_page_params_from_root_json(
    root: &Value,
    user_id: i64,
    app_root: &Path,
) -> Option<String> {
    if user_id <= 0 {
        return None;
    }
    let mut rows_html = String::new();
    for row in bounded_state_array(root, "appointments")
        .iter()
        .filter(|row| row_i64_value(row, "user_id") == Some(user_id))
    {
        let service = row_i64_value(row, "service_id")
            .and_then(|id| state_row_by_i64(root, "services", "id", id));
        let business = row_i64_value(row, "business_id")
            .and_then(|id| state_row_by_i64(root, "businesses", "id", id));
        let service_name = service
            .and_then(|value| value.get("name"))
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "Appointment".to_owned());
        let business_name = business
            .and_then(|value| value.get("name"))
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "Business".to_owned());
        let business_slug = business
            .and_then(|value| value.get("slug"))
            .map(value_to_text)
            .unwrap_or_default();
        let (date, time) = row_date_time(row);
        let status = row
            .get("status")
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "scheduled".to_owned());
        let payment_status = row
            .get("payment_status")
            .map(value_to_text)
            .unwrap_or_default();
        let meta_line_one = if date.is_empty() && time.is_empty() {
            business_name.clone()
        } else {
            format!(
                "{} at {}",
                date,
                formatted_clock_time_business_logic_local(&time)
            )
        };
        let meta_line_two = if payment_status.is_empty() {
            business_name
        } else {
            format!("{business_name} · Payment: {payment_status}")
        };
        rows_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/shared/fragments/appointment_row.html",
            Map::from_iter([
                ("service_name".to_owned(), Value::String(service_name)),
                ("status_value".to_owned(), Value::String(status)),
                ("meta_line_one".to_owned(), Value::String(meta_line_one)),
                (
                    "meta_line_one_style".to_owned(),
                    Value::String(String::new()),
                ),
                ("meta_line_two".to_owned(), Value::String(meta_line_two)),
                (
                    "meta_line_two_style".to_owned(),
                    Value::String(String::new()),
                ),
                ("tertiary_line".to_owned(), Value::String(String::new())),
                (
                    "tertiary_line_style".to_owned(),
                    Value::String("display:none;".to_owned()),
                ),
                (
                    "notes_text".to_owned(),
                    Value::String(row.get("notes").map(value_to_text).unwrap_or_default()),
                ),
                (
                    "notes_style".to_owned(),
                    Value::String(
                        if row
                            .get("notes")
                            .map(value_to_text)
                            .unwrap_or_default()
                            .is_empty()
                        {
                            "display:none;".to_owned()
                        } else {
                            String::new()
                        },
                    ),
                ),
                (
                    "detail_path".to_owned(),
                    Value::String(if business_slug.is_empty() {
                        "/appointments/".to_owned()
                    } else {
                        format!("/b/{business_slug}/")
                    }),
                ),
                (
                    "detail_link_style".to_owned(),
                    Value::String("display:none;".to_owned()),
                ),
                (
                    "request_cancel_path".to_owned(),
                    Value::String(format!(
                        "/appointments/{}/request-cancel/",
                        row_i64_value(row, "id").unwrap_or(0)
                    )),
                ),
                (
                    "request_cancel_style".to_owned(),
                    Value::String("display:none;".to_owned()),
                ),
                (
                    "request_cancel_button_ui_html".to_owned(),
                    Value::String(String::new()),
                ),
                (
                    "complete_path".to_owned(),
                    Value::String(format!(
                        "/appointments/{}/complete/",
                        row_i64_value(row, "id").unwrap_or(0)
                    )),
                ),
                (
                    "complete_style".to_owned(),
                    Value::String("display:none;".to_owned()),
                ),
                (
                    "complete_button_ui_html".to_owned(),
                    Value::String(String::new()),
                ),
                (
                    "cancel_path".to_owned(),
                    Value::String(format!(
                        "/appointments/{}/cancel/",
                        row_i64_value(row, "id").unwrap_or(0)
                    )),
                ),
                (
                    "cancel_style".to_owned(),
                    Value::String("display:none;".to_owned()),
                ),
                (
                    "cancel_button_ui_html".to_owned(),
                    Value::String(String::new()),
                ),
            ]),
        )?);
    }
    if rows_html.is_empty() {
        rows_html = render_fragment_with_params(
            app_root,
            "templates/appointments/fragments/appointments_empty_manage.html",
            Map::new(),
        )?;
    }
    compact(&Value::Object(Map::from_iter([
        (
            "heading".to_owned(),
            Value::String("Appointments".to_owned()),
        ),
        ("appointment_items".to_owned(), Value::String(rows_html)),
        ("tips_style".to_owned(), Value::String(String::new())),
    ])))
}

/// Loads appointments page parameters from a state file.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::dynamic_appointments_page_params_json`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::dynamic_appointments_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_appointments_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_appointments_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_appointments_page_params_json(todo!(), 1, std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_appointments_page_params_json(
    state_path: &Path,
    user_id: i64,
    app_root: &Path,
) -> Option<String> {
    dynamic_appointments_page_params_from_root_json(
        &json_doc_load_file(state_path)?,
        user_id,
        app_root,
    )
}

/// Builds the booking form parameter document.
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_booking_form_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_booking_form_page_params_json();
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_booking_form_page_params_json() -> Option<String> {
    page_params_value(&Value::Null, "booking-form", Map::new())
}

/// Builds bookings page parameters from state.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_bookings_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_bookings_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_bookings_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_bookings_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_bookings_page_params_json(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_bookings_page_params_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("business_slug".into(), Value::String(business_slug.into()));
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    extra.insert(
        "bookings".into(),
        Value::Array(bounded_state_array(root, "bookings").to_vec()),
    );
    page_params_value(root, "bookings", extra)
}

pub fn dynamic_user_bookings_page_params_from_root_json(
    root: &Value,
    user_id: i64,
    app_root: &Path,
) -> Option<String> {
    if user_id <= 0 {
        return None;
    }
    let mut rows_html = String::new();
    for row in bounded_state_array(root, "bookings")
        .iter()
        .filter(|row| row_i64_value(row, "user_id") == Some(user_id))
    {
        let (date, time) = row_date_time(row);
        rows_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/bookings/fragments/booking_row.html",
            Map::from_iter([
                (
                    "booking_title".to_owned(),
                    Value::String(
                        row.get("title")
                            .map(value_to_text)
                            .filter(|value| !value.is_empty())
                            .unwrap_or_else(|| "Booking".to_owned()),
                    ),
                ),
                (
                    "status_value".to_owned(),
                    Value::String(
                        row.get("status")
                            .map(value_to_text)
                            .filter(|value| !value.is_empty())
                            .unwrap_or_else(|| "confirmed".to_owned()),
                    ),
                ),
                ("date_value".to_owned(), Value::String(date)),
                (
                    "time_value".to_owned(),
                    Value::String(formatted_clock_time_business_logic_local(&time)),
                ),
            ]),
        )?);
    }
    if rows_html.is_empty() {
        rows_html = render_fragment_with_params(
            app_root,
            "templates/bookings/bookings_empty.html",
            Map::new(),
        )?;
    }
    compact(&Value::Object(Map::from_iter([
        (
            "create_path".to_owned(),
            Value::String("/bookings/new/".to_owned()),
        ),
        (
            "error_style".to_owned(),
            Value::String("display:none;".to_owned()),
        ),
        ("error_message".to_owned(), Value::String(String::new())),
        ("booking_rows_html".to_owned(), Value::String(rows_html)),
    ])))
}

/// Builds the business admin page parameter document.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_admin_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_admin_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_admin_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_admin_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_admin_page_params_json(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_admin_page_params_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    dynamic_bookings_page_params_json(root, business_slug, app_root)
}

/// Builds the business calendar page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_from_root_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_from_root_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_from_root_json`].
/// - `year`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_from_root_json`].
/// - `month`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_from_root_json`].
/// - `date`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_from_root_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_calendar_page_params_from_root_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_from_root_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_calendar_page_params_from_root_json(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_calendar_page_params_from_root_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
    year: Option<&str>,
    month: Option<&str>,
    date: Option<&str>,
) -> Option<String> {
    let mut extra = Map::new();
    for (key, value) in [
        ("business_slug", business_slug),
        ("year", year.unwrap_or_default()),
        ("month", month.unwrap_or_default()),
        ("date", date.unwrap_or_default()),
    ] {
        extra.insert(key.into(), Value::String(value.into()));
    }
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    extra.insert(
        "appointments".into(),
        Value::Array(bounded_state_array(root, "appointments").to_vec()),
    );
    page_params_value(root, "business-calendar", extra)
}

/// Loads business calendar parameters from state.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_json`].
/// - `year`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_json`].
/// - `month`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_json`].
/// - `date`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_calendar_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_calendar_page_params_json(todo!(), "demo", std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_calendar_page_params_json(
    state_path: &Path,
    business_slug: &str,
    app_root: &Path,
    year: Option<&str>,
    month: Option<&str>,
    date: Option<&str>,
) -> Option<String> {
    dynamic_business_calendar_page_params_from_root_json(
        &json_doc_load_file(state_path)?,
        business_slug,
        app_root,
        year,
        month,
        date,
    )
}

/// Renders icon button fragment.
fn render_icon_button_fragment(
    app_root: &Path,
    id: &str,
    button_type: &str,
    class_name: &str,
    attributes_html: &str,
    content_fragment: &str,
    content_params: serde_json::Map<String, Value>,
) -> Option<String> {
    let content_html = render_fragment_with_params(app_root, content_fragment, content_params)?;
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/ui_button.html",
        serde_json::Map::from_iter([
            ("id".to_owned(), Value::String(id.to_owned())),
            (
                "button_type".to_owned(),
                Value::String(button_type.to_owned()),
            ),
            (
                "class_name".to_owned(),
                Value::String(class_name.to_owned()),
            ),
            (
                "attributes_html".to_owned(),
                Value::String(attributes_html.to_owned()),
            ),
            ("content_html".to_owned(), Value::String(content_html)),
        ]),
    )
}

/// Renders compact input fragment.
fn render_compact_input_fragment(
    app_root: &Path,
    id: &str,
    input_type: &str,
    name: &str,
    label: &str,
    value: &str,
    class_name: &str,
    attributes_html: &str,
) -> Option<String> {
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/ui_input.html",
        serde_json::Map::from_iter([
            ("id".to_owned(), Value::String(id.to_owned())),
            (
                "input_type".to_owned(),
                Value::String(input_type.to_owned()),
            ),
            ("name".to_owned(), Value::String(name.to_owned())),
            ("label".to_owned(), Value::String(label.to_owned())),
            (
                "label_class".to_owned(),
                Value::String("sr-only".to_owned()),
            ),
            (
                "class_name".to_owned(),
                Value::String(class_name.to_owned()),
            ),
            ("value".to_owned(), Value::String(value.to_owned())),
            (
                "attributes_html".to_owned(),
                Value::String(attributes_html.to_owned()),
            ),
            ("help_html".to_owned(), Value::String(String::new())),
        ]),
    )
}

/// Renders compact select fragment.
fn render_compact_select_fragment(
    app_root: &Path,
    id: &str,
    name: &str,
    label: &str,
    class_name: &str,
    attributes_html: &str,
    options_html: String,
) -> Option<String> {
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/ui_select.html",
        serde_json::Map::from_iter([
            ("id".to_owned(), Value::String(id.to_owned())),
            ("name".to_owned(), Value::String(name.to_owned())),
            ("label".to_owned(), Value::String(label.to_owned())),
            (
                "label_class".to_owned(),
                Value::String("sr-only".to_owned()),
            ),
            (
                "class_name".to_owned(),
                Value::String(class_name.to_owned()),
            ),
            (
                "attributes_html".to_owned(),
                Value::String(attributes_html.to_owned()),
            ),
            ("options_html".to_owned(), Value::String(options_html)),
            ("help_html".to_owned(), Value::String(String::new())),
        ]),
    )
}

/// Renders hidden input fragment.
fn render_hidden_input_fragment(
    app_root: &Path,
    id: &str,
    name: &str,
    value: &str,
) -> Option<String> {
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/ui_hidden_input.html",
        serde_json::Map::from_iter([
            ("id".to_owned(), Value::String(id.to_owned())),
            ("name".to_owned(), Value::String(name.to_owned())),
            ("value".to_owned(), Value::String(value.to_owned())),
            ("attributes_html".to_owned(), Value::String(String::new())),
        ]),
    )
}

/// Renders textarea fragment.
fn render_textarea_fragment(
    app_root: &Path,
    id: &str,
    name: &str,
    label: &str,
    value: &str,
    class_name: &str,
    attributes_html: &str,
) -> Option<String> {
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/ui_textarea.html",
        serde_json::Map::from_iter([
            ("id".to_owned(), Value::String(id.to_owned())),
            ("name".to_owned(), Value::String(name.to_owned())),
            ("label".to_owned(), Value::String(label.to_owned())),
            (
                "label_class".to_owned(),
                Value::String("sr-only".to_owned()),
            ),
            (
                "class_name".to_owned(),
                Value::String(class_name.to_owned()),
            ),
            ("value".to_owned(), Value::String(value.to_owned())),
            (
                "attributes_html".to_owned(),
                Value::String(attributes_html.to_owned()),
            ),
            ("help_html".to_owned(), Value::String(String::new())),
        ]),
    )
}

/// Renders day select options.
fn render_day_select_options(
    app_root: &Path,
    selected: &str,
    include_groups: bool,
) -> Option<String> {
    let mut options_html = String::new();
    if include_groups {
        for (value, label) in [("Weekdays", "Weekdays"), ("Weekends", "Weekends")] {
            options_html.push_str(&render_fragment_with_params(
                app_root,
                "templates/shared/fragments/select_option.html",
                Map::from_iter([
                    ("option_value".to_owned(), Value::String(value.to_owned())),
                    ("option_label".to_owned(), Value::String(label.to_owned())),
                    (
                        "selected_attr".to_owned(),
                        Value::String(if selected == value { " selected" } else { "" }.to_owned()),
                    ),
                ]),
            )?);
        }
    }
    for day in ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] {
        options_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/shared/fragments/select_option.html",
            Map::from_iter([
                ("option_value".to_owned(), Value::String(day.to_owned())),
                ("option_label".to_owned(), Value::String(day.to_owned())),
                (
                    "selected_attr".to_owned(),
                    Value::String(if selected == day { " selected" } else { "" }.to_owned()),
                ),
            ]),
        )?);
    }
    Some(options_html)
}

/// Performs business day matches group.
fn business_day_matches_group(day: &str, selected: &str) -> bool {
    match selected {
        "Weekdays" => matches!(day, "Mon" | "Tue" | "Wed" | "Thu" | "Fri"),
        "Weekends" => matches!(day, "Sat" | "Sun"),
        _ => day == selected,
    }
}

/// Performs dynamic business admin service cards HTML.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_admin_service_cards_html`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_admin_service_cards_html`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_admin_service_cards_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_admin_service_cards_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_business_admin_service_cards_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_admin_service_cards_html(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_admin_service_cards_html(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    let business = bounded_state_array(root, "businesses")
        .iter()
        .find(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))?;
    let business_id = business.get("id").and_then(Value::as_i64)?;
    let mut services: Vec<&Value> = bounded_state_array(root, "services")
        .iter()
        .filter(|row| row.get("business_id").and_then(Value::as_i64) == Some(business_id))
        .filter(|row| row.get("is_active").and_then(Value::as_bool) != Some(false))
        .collect();
    services.sort_by_key(|row| {
        row.get("sort_order")
            .and_then(Value::as_i64)
            .filter(|value| *value > 0)
            .unwrap_or_else(|| row.get("id").and_then(Value::as_i64).unwrap_or(0))
    });
    let mut output = String::new();
    for service in services {
        let service_id = service.get("id").and_then(Value::as_i64)?;
        let service_name = service.get("name").map(value_to_text).unwrap_or_default();
        let description = service
            .get("description")
            .map(value_to_text)
            .unwrap_or_default();
        let description_html = if description.is_empty() {
            String::new()
        } else {
            render_fragment_with_params(
                app_root,
                "templates/businesses/fragments/business_admin_service_description.html",
                Map::from_iter([("description".to_owned(), Value::String(description.clone()))]),
            )?
        };
        let order_value = service
            .get("sort_order")
            .and_then(Value::as_i64)
            .filter(|value| *value > 0)
            .unwrap_or(service_id);
        let summary = format!(
            "Order {} · ${} · {} min",
            order_value,
            service.get("cost").map(value_to_text).unwrap_or_default(),
            service
                .get("duration_minutes")
                .map(value_to_text)
                .filter(|value| !value.is_empty())
                .unwrap_or_else(|| "45".to_owned())
        );
        let booking_options: Vec<String> = service
            .get("booking_options")
            .and_then(Value::as_array)
            .map(|rows| {
                rows.iter()
                    .filter_map(|row| {
                        let label = row
                            .get("label")
                            .or_else(|| row.get("name"))
                            .map(value_to_text)
                            .unwrap_or_default();
                        if label.is_empty() {
                            return None;
                        }
                        let cost = row.get("cost").map(value_to_text).unwrap_or_default();
                        Some(if cost.is_empty() {
                            label
                        } else {
                            format!("{label} ${cost}")
                        })
                    })
                    .collect()
            })
            .unwrap_or_default();
        let booking_options_html = if booking_options.is_empty() {
            String::new()
        } else {
            render_fragment_with_params(
                app_root,
                "templates/businesses/fragments/business_admin_service_options.html",
                Map::from_iter([(
                    "options".to_owned(),
                    Value::String(booking_options.join(", ")),
                )]),
            )?
        };
        let assigned_technician_ids: Vec<String> = service
            .get("assigned_technician_ids")
            .or_else(|| service.get("technician_ids"))
            .and_then(Value::as_array)
            .map(|rows| rows.iter().map(value_to_text).collect())
            .unwrap_or_default();
        let technician_names: Vec<String> = bounded_state_array(root, "technicians")
            .iter()
            .filter(|row| row.get("business_id").and_then(Value::as_i64) == Some(business_id))
            .filter(|row| {
                assigned_technician_ids
                    .iter()
                    .any(|id| row.get("id").map(value_to_text).as_deref() == Some(id.as_str()))
            })
            .filter_map(|row| {
                row.get("name")
                    .map(value_to_text)
                    .filter(|name| !name.is_empty())
            })
            .collect();
        let technicians_html = if technician_names.is_empty() {
            String::new()
        } else {
            render_fragment_with_params(
                app_root,
                "templates/businesses/fragments/business_admin_service_technicians.html",
                Map::from_iter([(
                    "technicians".to_owned(),
                    Value::String(technician_names.join(", ")),
                )]),
            )?
        };
        let image_url = service
            .get("image_url")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let image_html = if image_url.is_empty() {
            service_visual_html(
                app_root,
                None,
                &service_name,
                service.get("primary_color").and_then(Value::as_str),
            )?
        } else {
            render_fragment_with_params(
                app_root,
                "templates/businesses/fragments/business_admin_service_image.html",
                Map::from_iter([
                    ("image_url".to_owned(), Value::String(image_url.to_owned())),
                    ("image_alt".to_owned(), Value::String(service_name.clone())),
                ]),
            )?
        };
        output.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_admin_service_card.html",
            serde_json::Map::from_iter([
                (
                    "delete_path".to_owned(),
                    Value::String(format!(
                        "/businesses/{business_slug}/services/{service_id}/delete/"
                    )),
                ),
                (
                    "edit_path".to_owned(),
                    Value::String(format!(
                        "/businesses/{business_slug}/services/{service_id}/edit/"
                    )),
                ),
                ("image_html".to_owned(), Value::String(image_html)),
                ("service_name".to_owned(), Value::String(service_name)),
                ("service_summary".to_owned(), Value::String(summary)),
                (
                    "service_description_html".to_owned(),
                    Value::String(description_html),
                ),
                (
                    "booking_options_html".to_owned(),
                    Value::String(booking_options_html),
                ),
                (
                    "technicians_html".to_owned(),
                    Value::String(technicians_html),
                ),
            ]),
        )?);
    }
    Some(output)
}

/// Builds business admin page params from a loaded state root.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_generated_admin_manage_sections_html`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_generated_admin_manage_sections_html`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_generated_admin_manage_sections_html`].
/// - `target`: Input consumed by [`crate::runtime::json_commands::dynamic_generated_admin_manage_sections_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_generated_admin_manage_sections_html`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_generated_admin_manage_sections_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_generated_admin_manage_sections_html(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"), "/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_generated_admin_manage_sections_html(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
    target: &str,
) -> Option<String> {
    let services_path = format!("/businesses/{business_slug}/services/");
    let availability_path = format!("/businesses/{business_slug}/availability/");
    if target.contains("/availability/") {
        let availability_rows_html =
            dynamic_render_business_admin_availability_rows_html(root, business_slug, app_root)?;
        let availability_body_html = render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_admin_availability_body.html",
            serde_json::Map::from_iter([
                (
                    "availability_rows_html".to_owned(),
                    Value::String(availability_rows_html),
                ),
                (
                    "availability_create_path".to_owned(),
                    Value::String(format!("/businesses/{business_slug}/availability/new/")),
                ),
                (
                    "business_admin_availability_day_select_ui_html".to_owned(),
                    Value::String(render_compact_select_fragment(
                        app_root,
                        &format!("availability-manage-day-{business_slug}"),
                        "day_of_week",
                        "Day",
                        "form-control form-control-compact availability-inline-input",
                        " autocomplete=\"off\"",
                        render_day_select_options(app_root, "Mon", true)?,
                    )?),
                ),
                (
                    "business_admin_availability_start_time_input_ui_html".to_owned(),
                    Value::String(render_compact_input_fragment(
                        app_root,
                        &format!("availability-manage-start-{business_slug}"),
                        "time",
                        "start_time",
                        "Start",
                        "09:00",
                        "form-control form-control-compact availability-inline-input",
                        " autocomplete=\"off\"",
                    )?),
                ),
                (
                    "business_admin_availability_end_time_input_ui_html".to_owned(),
                    Value::String(render_compact_input_fragment(
                        app_root,
                        &format!("availability-manage-end-{business_slug}"),
                        "time",
                        "end_time",
                        "End",
                        "17:00",
                        "form-control form-control-compact availability-inline-input",
                        " autocomplete=\"off\"",
                    )?),
                ),
                (
                    "business_admin_availability_submit_button_ui_html".to_owned(),
                    Value::String(render_icon_button_fragment(
                        app_root,
                        &format!("availability-manage-submit-{business_slug}"),
                        "submit",
                        "btn btn-success btn-icon btn-icon-lg business-admin-save-button",
                        "",
                        "templates/shared/fragments/ui_content_apply_hours.html",
                        serde_json::Map::new(),
                    )?),
                ),
            ]),
        )?;
        return render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_admin_availability_manage.html",
            serde_json::Map::from_iter([
                ("services_path".to_owned(), Value::String(services_path)),
                (
                    "availability_body_html".to_owned(),
                    Value::String(availability_body_html),
                ),
            ]),
        );
    }

    let business = bounded_state_array(root, "businesses")
        .iter()
        .find(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))?;
    let business_id = business.get("id").and_then(Value::as_i64)?;
    let service_rows_html =
        dynamic_business_admin_service_cards_html(root, business_slug, app_root)?;
    let service_create_technician_rows_html =
        technician_checkboxes_html(app_root, root, business_id, 0, "No technicians yet.", true)?;
    let services_body_html = render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_admin_services_body.html",
        serde_json::Map::from_iter([
            (
                "service_rows_html".to_owned(),
                Value::String(service_rows_html),
            ),
            (
                "service_create_path".to_owned(),
                Value::String(format!("/businesses/{business_slug}/services/new/")),
            ),
            (
                "business_admin_service_name_input_ui_html".to_owned(),
                Value::String(render_compact_input_fragment(
                    app_root,
                    &format!("service-manage-name-{business_slug}"),
                    "text",
                    "name",
                    "Service name",
                    "",
                    "form-control",
                    " required",
                )?),
            ),
            (
                "business_admin_service_cost_input_ui_html".to_owned(),
                Value::String(render_compact_input_fragment(
                    app_root,
                    &format!("service-manage-cost-{business_slug}"),
                    "number",
                    "cost",
                    "Cost",
                    "",
                    "form-control",
                    " min=\"0\" step=\"0.01\"",
                )?),
            ),
            (
                "business_admin_service_duration_input_ui_html".to_owned(),
                Value::String(render_compact_input_fragment(
                    app_root,
                    &format!("service-manage-duration-{business_slug}"),
                    "number",
                    "duration_minutes",
                    "Duration",
                    "45",
                    "form-control",
                    " min=\"1\" step=\"1\"",
                )?),
            ),
            (
                "business_admin_service_sort_order_select_ui_html".to_owned(),
                Value::String(render_compact_select_fragment(
                    app_root,
                    &format!("service-manage-order-{business_slug}"),
                    "sort_order",
                    "Order",
                    "form-control",
                    "",
                    service_sort_order_options_html(app_root, root, business_id, 0, true)?,
                )?),
            ),
            (
                "business_admin_service_description_textarea_ui_html".to_owned(),
                Value::String(render_textarea_fragment(
                    app_root,
                    &format!("service-manage-description-{business_slug}"),
                    "description",
                    "Description",
                    "",
                    "form-control",
                    " rows=\"4\" aria-label=\"Description\"",
                )?),
            ),
            (
                "business_admin_service_image_input_ui_html".to_owned(),
                Value::String(render_fragment_with_params(
                    app_root,
                    "templates/shared/fragments/ui_input.html",
                    serde_json::Map::from_iter([
                        (
                            "id".to_owned(),
                            Value::String("service-create-image".to_owned()),
                        ),
                        ("input_type".to_owned(), Value::String("file".to_owned())),
                        ("name".to_owned(), Value::String("service_image".to_owned())),
                        (
                            "label".to_owned(),
                            Value::String("Service image".to_owned()),
                        ),
                        (
                            "label_class".to_owned(),
                            Value::String("sr-only".to_owned()),
                        ),
                        ("class_name".to_owned(), Value::String(String::new())),
                        ("value".to_owned(), Value::String(String::new())),
                        (
                            "attributes_html".to_owned(),
                            Value::String(" accept=\"image/*\" hidden".to_owned()),
                        ),
                        ("help_html".to_owned(), Value::String(String::new())),
                    ]),
                )?),
            ),
            (
                "business_admin_service_submit_button_ui_html".to_owned(),
                Value::String(render_icon_button_fragment(
                    app_root,
                    &format!("service-manage-submit-{business_slug}"),
                    "submit",
                    "btn btn-success btn-icon btn-icon-lg business-admin-save-button",
                    " title=\"Save Service\" aria-label=\"Save Service\"",
                    "templates/shared/fragments/ui_content_save_service.html",
                    serde_json::Map::new(),
                )?),
            ),
            (
                "service_create_technicians_empty_style".to_owned(),
                Value::String("display:none;".to_owned()),
            ),
            (
                "service_create_technicians_empty_message".to_owned(),
                Value::String("No technicians yet.".to_owned()),
            ),
            (
                "service_create_technician_assignment_rows_html".to_owned(),
                Value::String(service_create_technician_rows_html),
            ),
        ]),
    )?;
    render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_admin_services_manage.html",
        serde_json::Map::from_iter([
            (
                "availability_path".to_owned(),
                Value::String(availability_path),
            ),
            (
                "services_body_html".to_owned(),
                Value::String(services_body_html),
            ),
        ]),
    )
}

/// Performs dynamic business detail admin page params from root JSON.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_detail_admin_page_params_from_root_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_detail_admin_page_params_from_root_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_detail_admin_page_params_from_root_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_detail_admin_page_params_from_root_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_business_detail_admin_page_params_from_root_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_detail_admin_page_params_from_root_json(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_detail_admin_page_params_from_root_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    if std::env::var("PHAROS_TRACE_ADMIN_RENDER").ok().as_deref() == Some("1") {
        eprintln!("TRACE admin render start slug={business_slug}");
    }
    let business = bounded_state_array(root, "businesses")
        .iter()
        .find(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))?;
    let business_id = business.get("id").and_then(Value::as_i64)?;
    let business_name = business.get("name").map(value_to_text).unwrap_or_default();
    let landing_path = format!("/b/{business_slug}/");
    let calendar_path = format!("/business/{business_slug}/calendar/");
    let edit_path = format!("/businesses/{business_slug}/edit/");
    let toggle_path = format!("/businesses/{business_slug}/toggle-public/");
    let delete_path = format!("/businesses/{business_slug}/delete/");
    let invite_create_path = format!("/businesses/{business_slug}/invites/new/");
    let service_create_path = format!("/businesses/{business_slug}/services/new/");
    let technician_create_path = format!("/businesses/{business_slug}/technicians/new/");
    let availability_create_path = format!("/businesses/{business_slug}/availability/new/");
    let is_public = business
        .get("is_public")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let summary = root.get("business_summary")?;
    let appointment_count = summary.get("appointment_count")?.as_u64()?;
    let technician_count = summary.get("technician_count")?.as_u64()?;
    let unassigned_count = summary.get("unassigned_count")?.as_u64()?;
    let (payment_provider_id, payment_provider_label) =
        business_payment_provider_ui_config(app_root);
    let (payment_provider_status_label, payment_provider_status_detail) =
        business_payment_provider_status(
            root,
            business_id,
            &payment_provider_id,
            &payment_provider_label,
        );
    let (
        payment_provider_connect_path,
        payment_provider_refresh_path,
        payment_provider_disconnect_path,
    ) = business_payment_provider_paths(business_slug, &payment_provider_id);
    let connection_status =
        if state_find_google_calendar_connection_for_business_logic_local(root, business_id)
            .is_some()
        {
            "Connected"
        } else {
            "Disconnected"
        };
    let public_toggle_button =
        dynamic_render_business_admin_public_state_button_html(app_root, business_slug, is_public)?;
    if std::env::var("PHAROS_TRACE_ADMIN_RENDER").ok().as_deref() == Some("1") {
        eprintln!("TRACE admin render public_toggle_button ok");
    }
    let delete_open_button = render_icon_button_fragment(
        app_root,
        "business_admin_delete_dialog_open_button",
        "button",
        "btn btn-danger btn-icon btn-icon-lg",
        " title=\"Delete Business\" aria-label=\"Delete Business\" data-dialog-open=\"business-delete-dialog\"",
        "templates/shared/fragments/ui_content_delete_business.html",
        serde_json::Map::new(),
    )?;
    let toolbar_html = render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_admin_summary_toolbar.html",
        serde_json::Map::from_iter([
            (
                "landing_path".to_owned(),
                Value::String(landing_path.clone()),
            ),
            (
                "calendar_path".to_owned(),
                Value::String(calendar_path.clone()),
            ),
            ("edit_path".to_owned(), Value::String(edit_path.clone())),
            ("toggle_path".to_owned(), Value::String(toggle_path.clone())),
            (
                "business_public_state_toggle_button_ui_html".to_owned(),
                Value::String(public_toggle_button),
            ),
            (
                "business_admin_delete_dialog_open_button_ui_html".to_owned(),
                Value::String(delete_open_button),
            ),
        ]),
    )?;
    if std::env::var("PHAROS_TRACE_ADMIN_RENDER").ok().as_deref() == Some("1") {
        eprintln!("TRACE admin render toolbar ok");
    }
    let mut summary_body_params = serde_json::Map::from_iter([
        (
            "public_url_path".to_owned(),
            Value::String(landing_path.clone()),
        ),
        (
            "payment_provider_status_label".to_owned(),
            Value::String(payment_provider_status_label),
        ),
        (
            "payment_provider_status_detail".to_owned(),
            Value::String(payment_provider_status_detail),
        ),
        (
            "connection_status".to_owned(),
            Value::String(connection_status.to_owned()),
        ),
        (
            "appointment_count".to_owned(),
            Value::String(appointment_count.to_string()),
        ),
        (
            "unassigned_count".to_owned(),
            Value::String(unassigned_count.to_string()),
        ),
        (
            "technician_count".to_owned(),
            Value::String(technician_count.to_string()),
        ),
        (
            "payment_provider_setup_path".to_owned(),
            Value::String(format!("/businesses/{business_slug}/connect-stripe/")),
        ),
        (
            "payment_provider_connect_path".to_owned(),
            Value::String(payment_provider_connect_path),
        ),
        (
            "payment_provider_refresh_path".to_owned(),
            Value::String(payment_provider_refresh_path),
        ),
        (
            "payment_provider_disconnect_path".to_owned(),
            Value::String(payment_provider_disconnect_path),
        ),
        (
            "business_admin_refresh_payment_provider_button_ui_html".to_owned(),
            Value::String(payment_provider_action_button_html(
                app_root,
                "business_admin_refresh_payment_provider_button",
                "Refresh status",
                "btn btn-secondary",
            )?),
        ),
        (
            "business_admin_disconnect_payment_provider_button_ui_html".to_owned(),
            Value::String(payment_provider_action_button_html(
                app_root,
                "business_admin_disconnect_payment_provider_button",
                "Disconnect",
                "btn btn-danger",
            )?),
        ),
        (
            "business_admin_google_mode_input_ui_html".to_owned(),
            Value::String(render_hidden_input_fragment(
                app_root,
                "business_admin_google_mode_input",
                "mode",
                "business",
            )?),
        ),
        (
            "business_admin_google_slug_input_ui_html".to_owned(),
            Value::String(render_hidden_input_fragment(
                app_root,
                "business_admin_google_slug_input",
                "business_slug",
                business_slug,
            )?),
        ),
        (
            "business_admin_google_next_input_ui_html".to_owned(),
            Value::String(render_hidden_input_fragment(
                app_root,
                "business_admin_google_next_input",
                "next",
                &format!("/businesses/{business_slug}/"),
            )?),
        ),
        (
            "business_admin_connect_google_button_ui_html".to_owned(),
            Value::String(render_fragment_with_params(
                app_root,
                "templates/shared/fragments/ui_button.html",
                Map::from_iter([
                    (
                        "id".to_owned(),
                        Value::String("business_admin_connect_google_button".to_owned()),
                    ),
                    ("button_type".to_owned(), Value::String("submit".to_owned())),
                    (
                        "class_name".to_owned(),
                        Value::String("btn btn-primary".to_owned()),
                    ),
                    ("attributes_html".to_owned(), Value::String(String::new())),
                    (
                        "content_html".to_owned(),
                        Value::String("Connect Google Calendar".to_owned()),
                    ),
                ]),
            )?),
        ),
    ]);
    for (key, value) in super::payment_provider::payment_provider_template_params(
        root,
        app_root,
        business_slug,
        &payment_provider_id,
    ) {
        summary_body_params.insert(key, value);
    }
    for key in [
        "owner_payment_provider_status_label",
        "owner_payment_provider_status_icon",
        "owner_payment_provider_mode_demo_label",
        "owner_payment_provider_mode_live_label",
        "owner_payment_provider_credentials_state_label",
        "owner_payment_provider_setup_eyebrow",
        "owner_payment_provider_credentials_headline",
        "owner_payment_provider_credentials_body",
        "owner_payment_provider_client_id_label",
        "owner_payment_provider_client_id_placeholder",
        "owner_payment_provider_client_secret_label",
        "owner_payment_provider_client_secret_placeholder",
        "owner_payment_provider_save_credentials_label",
        "owner_payment_provider_delete_credentials_label",
        "owner_payment_provider_connect_label",
        "owner_payment_provider_refresh_label",
    ] {
        if let Some(value) = super::payment_provider::payment_provider_copy_value(app_root, key) {
            summary_body_params.insert(key.to_owned(), Value::String(value));
        }
    }
    summary_body_params.insert(
        "owner_payment_provider_action_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/test/"
        )),
    );
    summary_body_params.insert(
        "owner_payment_provider_refresh_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/refresh/"
        )),
    );
    summary_body_params.insert(
        "owner_payment_provider_credentials_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/credentials/"
        )),
    );
    summary_body_params.insert(
        "owner_payment_provider_credentials_delete_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/credentials/delete/"
        )),
    );
    summary_body_params.insert(
        "owner_payment_provider_mode_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/mode/"
        )),
    );
    summary_body_params.insert(
        "payment_provider_feedback_message".to_owned(),
        Value::String(String::new()),
    );
    let summary_body_html = render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_admin_summary_body.html",
        summary_body_params,
    )?;
    if std::env::var("PHAROS_TRACE_ADMIN_RENDER").ok().as_deref() == Some("1") {
        eprintln!("TRACE admin render summary_body ok");
    }
    let invite_body_html = render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_admin_invite_body.html",
        serde_json::Map::from_iter([
            (
                "invite_create_path".to_owned(),
                Value::String(invite_create_path.clone()),
            ),
            (
                "business_admin_invite_email_input_ui_html".to_owned(),
                Value::String(render_compact_input_fragment(
                    app_root,
                    "business_admin_invite_email_input",
                    "email",
                    "email",
                    "Email",
                    "",
                    "form-control form-control-compact",
                    " placeholder=\"Email\" autocomplete=\"email\" aria-label=\"Email\" required",
                )?),
            ),
            (
                "business_admin_invite_account_type_select_ui_html".to_owned(),
                Value::String(render_compact_select_fragment(
                    app_root,
                    "business_admin_invite_account_type_select",
                    "account_type",
                    "Account type",
                    "form-control form-control-compact",
                    " aria-label=\"Account type\"",
                    [
                        ("business_customer", "Customer", true),
                        ("business_manager", "Manager", false),
                        ("business_technician", "Technician", false),
                    ]
                    .into_iter()
                    .map(|(value, label, selected)| {
                        render_fragment_with_params(
                            app_root,
                            "templates/shared/fragments/select_option.html",
                            Map::from_iter([
                                ("option_value".to_owned(), Value::String(value.to_owned())),
                                ("option_label".to_owned(), Value::String(label.to_owned())),
                                (
                                    "selected_attr".to_owned(),
                                    Value::String(
                                        if selected { " selected" } else { "" }.to_owned(),
                                    ),
                                ),
                            ]),
                        )
                    })
                    .collect::<Option<Vec<_>>>()?
                    .join(""),
                )?),
            ),
            (
                "business_admin_invite_submit_button_ui_html".to_owned(),
                Value::String(render_icon_button_fragment(
                    app_root,
                    "business_admin_invite_submit_button",
                    "submit",
                    "btn btn-success btn-icon btn-icon-sm business-admin-save-button",
                    " title=\"Send\" aria-label=\"Send\"",
                    "templates/shared/fragments/ui_content_create_invite.html",
                    serde_json::Map::new(),
                )?),
            ),
        ]),
    )?;
    let top_grid_html = render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_admin_top_grid.html",
        Map::from_iter([
            (
                "business_name".to_owned(),
                Value::String(business_name.clone()),
            ),
            ("toolbar_html".to_owned(), Value::String(toolbar_html)),
            (
                "summary_body_html".to_owned(),
                Value::String(summary_body_html),
            ),
            (
                "invite_body_html".to_owned(),
                Value::String(invite_body_html),
            ),
        ]),
    )?;
    let service_rows_html =
        dynamic_business_admin_service_cards_html(root, business_slug, app_root)?;
    let service_create_technician_rows_html =
        technician_checkboxes_html(app_root, root, business_id, 0, "No technicians yet.", true)
            .or_else(|| {
                render_fragment_with_params(
                    app_root,
                    "templates/shared/fragments/muted_text.html",
                    Map::from_iter([(
                        "message".to_owned(),
                        Value::String("No technicians yet.".to_owned()),
                    )]),
                )
            })?;
    let services_panel_html = render_workspace_panel_html_business_logic_local(
        app_root,
        "card business-admin-services-card",
        "business-admin-services-header",
        "Services",
        "",
        &render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_admin_services_body.html",
            serde_json::Map::from_iter([
                (
                    "service_rows_html".to_owned(),
                    Value::String(service_rows_html),
                ),
                (
                    "service_create_path".to_owned(),
                    Value::String(service_create_path),
                ),
                (
                    "business_admin_service_name_input_ui_html".to_owned(),
                    Value::String(render_compact_input_fragment(
                        app_root,
                        "business_admin_service_name_input",
                        "text",
                        "name",
                        "Name",
                        "",
                        "form-control form-control-compact",
                        " placeholder=\"Name\" autocomplete=\"false\" aria-label=\"Name\" required",
                    )?),
                ),
                (
                    "business_admin_service_cost_input_ui_html".to_owned(),
                    Value::String(render_compact_input_fragment(
                        app_root,
                        "business_admin_service_cost_input",
                        "text",
                        "cost",
                        "Cost",
                        "",
                        "form-control form-control-compact",
                        " placeholder=\"Cost\" autocomplete=\"false\" aria-label=\"Cost\" inputmode=\"decimal\" required",
                    )?),
                ),
                (
                    "business_admin_service_duration_input_ui_html".to_owned(),
                    Value::String(render_compact_input_fragment(
                        app_root,
                        "business_admin_service_duration_input",
                        "number",
                        "duration_minutes",
                        "Duration",
                        "45",
                        "form-control form-control-compact",
                        " min=\"1\" max=\"999\" placeholder=\"Time\" autocomplete=\"false\" aria-label=\"Duration\" required",
                    )?),
                ),
                (
                    "business_admin_service_sort_order_select_ui_html".to_owned(),
                    Value::String(render_compact_select_fragment(
                        app_root,
                        "service-create-sort-order",
                        "sort_order",
                        "Display Order",
                        "form-control form-control-compact",
                        " aria-label=\"Display Order\" required",
                        service_sort_order_options_html(app_root, root, business_id, 0, true)?,
                    )?),
                ),
                (
                    "business_admin_service_description_textarea_ui_html".to_owned(),
                    Value::String(render_textarea_fragment(
                        app_root,
                        &format!("service-create-description-{business_slug}"),
                        "description",
                        "Description",
                        "",
                        "form-control",
                        " rows=\"4\" aria-label=\"Description\"",
                    )?),
                ),
                (
                    "business_admin_service_image_input_ui_html".to_owned(),
                    Value::String(render_fragment_with_params(
                        app_root,
                        "templates/shared/fragments/ui_input.html",
                        serde_json::Map::from_iter([
                            (
                                "id".to_owned(),
                                Value::String("service-create-image".to_owned()),
                            ),
                            ("input_type".to_owned(), Value::String("file".to_owned())),
                            (
                                "name".to_owned(),
                                Value::String("service_image".to_owned()),
                            ),
                            (
                                "label".to_owned(),
                                Value::String("Service image".to_owned()),
                            ),
                            (
                                "label_class".to_owned(),
                                Value::String("sr-only".to_owned()),
                            ),
                            (
                                "class_name".to_owned(),
                                Value::String("sr-only business-edit-hidden-input".to_owned()),
                            ),
                            ("value".to_owned(), Value::String(String::new())),
                            (
                                "attributes_html".to_owned(),
                                Value::String(" accept=\"image/*\" data-file-input-label=\"service-create-image-file-name\"".to_owned()),
                            ),
                            ("help_html".to_owned(), Value::String(String::new())),
                        ]),
                    )?),
                ),
                (
                    "business_admin_service_submit_button_ui_html".to_owned(),
                    Value::String(render_icon_button_fragment(
                        app_root,
                        "business_admin_service_submit_button",
                        "submit",
                        "btn btn-success btn-icon btn-icon-sm business-admin-save-button",
                        " title=\"Save Service\" aria-label=\"Save Service\"",
                        "templates/shared/fragments/ui_content_save_service.html",
                        serde_json::Map::new(),
                    )?),
                ),
                (
                    "service_create_technicians_empty_style".to_owned(),
                    Value::String("display:none;".to_owned()),
                ),
                (
                    "service_create_technicians_empty_message".to_owned(),
                    Value::String("No technicians yet.".to_owned()),
                ),
                (
                    "service_create_technician_assignment_rows_html".to_owned(),
                    Value::String(service_create_technician_rows_html),
                ),
            ]),
        )?,
    )?;
    let availability_rows_html =
        dynamic_render_business_admin_availability_rows_html(root, business_slug, app_root)?;
    let availability_body_html = render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_admin_availability_body.html",
        serde_json::Map::from_iter([
            (
                "availability_rows_html".to_owned(),
                Value::String(availability_rows_html),
            ),
            (
                "availability_create_path".to_owned(),
                Value::String(availability_create_path.clone()),
            ),
            (
                "business_admin_availability_day_select_ui_html".to_owned(),
                Value::String(render_compact_select_fragment(
                    app_root,
                    &format!("availability-day-{business_slug}"),
                    "day_of_week",
                    "Day",
                    "form-control form-control-compact availability-inline-input",
                    " autocomplete=\"off\"",
                    render_day_select_options(app_root, "Mon", true)?,
                )?),
            ),
            (
                "business_admin_availability_start_time_input_ui_html".to_owned(),
                Value::String(render_compact_input_fragment(
                    app_root,
                    &format!("availability-create-start-{business_slug}"),
                    "time",
                    "start_time",
                    "Start",
                    "09:00",
                    "form-control form-control-compact availability-inline-input",
                    " autocomplete=\"off\"",
                )?),
            ),
            (
                "business_admin_availability_end_time_input_ui_html".to_owned(),
                Value::String(render_compact_input_fragment(
                    app_root,
                    &format!("availability-create-end-{business_slug}"),
                    "time",
                    "end_time",
                    "End",
                    "17:00",
                    "form-control form-control-compact availability-inline-input",
                    " autocomplete=\"off\"",
                )?),
            ),
            (
                "business_admin_availability_submit_button_ui_html".to_owned(),
                Value::String(render_icon_button_fragment(
                    app_root,
                    &format!("availability-submit-{business_slug}"),
                    "submit",
                    "btn btn-success btn-icon btn-icon-lg business-admin-save-button",
                    "",
                    "templates/shared/fragments/ui_content_apply_hours.html",
                    serde_json::Map::new(),
                )?),
            ),
        ]),
    )?;
    let availability_panel_html = render_workspace_panel_html_business_logic_local(
        app_root,
        "card business-admin-half-card business-admin-availability-card",
        "business-admin-services-header",
        "Availability",
        "",
        &availability_body_html,
    )?;
    let technician_body_html = render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_admin_technicians_body.html",
        serde_json::Map::from_iter([
            (
                "technician_rows_html".to_owned(),
                Value::String(
                    super::business::dynamic_business_admin_technician_rows_html_from_root(
                        root,
                        business_slug,
                        app_root,
                    )?,
                ),
            ),
            (
                "technician_create_path".to_owned(),
                Value::String(technician_create_path),
            ),
            (
                "business_admin_technician_name_input_ui_html".to_owned(),
                Value::String(render_compact_input_fragment(
                    app_root,
                    "business_admin_technician_name_input",
                    "text",
                    "name",
                    "Name",
                    "",
                    "form-control form-control-compact",
                    " placeholder=\"Name\" autocomplete=\"name\" aria-label=\"Name\" required",
                )?),
            ),
            (
                "business_admin_technician_email_input_ui_html".to_owned(),
                Value::String(render_compact_input_fragment(
                    app_root,
                    "business_admin_technician_email_input",
                    "email",
                    "email",
                    "Email",
                    "",
                    "form-control form-control-compact",
                    " placeholder=\"Email\" autocomplete=\"email\" aria-label=\"Email\" required",
                )?),
            ),
            (
                "business_admin_technician_submit_button_ui_html".to_owned(),
                Value::String(render_icon_button_fragment(
                    app_root,
                    "business_admin_technician_submit_button",
                    "button",
                    "btn btn-success btn-icon btn-icon-sm business-admin-save-button business-admin-technician-add-button",
                    &format!(
                        " title=\"Add Technician\" aria-label=\"Add Technician\" hx-post=\"/businesses/{business_slug}/technicians/new/\" hx-include=\"closest form\" hx-target=\"#business-technician-rows\" hx-swap=\"innerHTML\""
                    ),
                    "templates/shared/fragments/ui_content_add_technician.html",
                    serde_json::Map::new(),
                )?),
            ),
        ]),
    )?;
    let technician_panel_html = render_workspace_panel_html_business_logic_local(
        app_root,
        "card business-admin-half-card business-admin-sticky-card",
        "business-admin-services-header",
        "Technicians",
        "",
        &technician_body_html,
    )?;
    let lower_grid_html = render_workspace_split_grid_html_business_logic_local(
        app_root,
        "business-admin-half-grid",
        &availability_panel_html,
        &technician_panel_html,
    )?;
    let delete_dialog_html = render_workspace_dialog_html_business_logic_local(
        app_root,
        "business-delete-dialog",
        "business-delete-dialog",
        "business-delete-dialog-shell",
        "business-delete-dialog-copy",
        &render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_admin_delete_dialog_copy.html",
            serde_json::Map::from_iter([(
                "business_name".to_owned(),
                Value::String(business_name.clone()),
            )]),
        )?,
        "business-delete-dialog-actions",
        &render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_admin_delete_dialog_actions.html",
            serde_json::Map::from_iter([
                ("delete_path".to_owned(), Value::String(delete_path)),
                (
                    "business_admin_delete_confirm_button_ui_html".to_owned(),
                    Value::String(render_icon_button_fragment(
                        app_root,
                        "business_admin_delete_confirm_button",
                        "submit",
                        "btn btn-danger btn-icon btn-icon-lg",
                        " title=\"Delete Business\" aria-label=\"Delete Business\"",
                        "templates/shared/fragments/ui_content_delete_business.html",
                        serde_json::Map::new(),
                    )?),
                ),
                (
                    "business_admin_delete_cancel_button_ui_html".to_owned(),
                    Value::String(render_icon_button_fragment(
                        app_root,
                        "business_admin_delete_cancel_button",
                        "button",
                        "btn btn-secondary btn-icon btn-icon-lg",
                        " title=\"Cancel\" aria-label=\"Cancel\" data-dialog-close=\"true\"",
                        "templates/shared/fragments/ui_content_cancel.html",
                        serde_json::Map::new(),
                    )?),
                ),
            ]),
        )?,
    )?;
    compact(&Value::Object(serde_json::Map::from_iter([
        ("business_name".to_owned(), Value::String(business_name)),
        ("top_grid_html".to_owned(), Value::String(top_grid_html)),
        (
            "services_panel_html".to_owned(),
            Value::String(services_panel_html),
        ),
        ("lower_grid_html".to_owned(), Value::String(lower_grid_html)),
        (
            "delete_dialog_html".to_owned(),
            Value::String(delete_dialog_html),
        ),
    ])))
}

/// Builds business calendar page params from a loaded state root.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_template_params_from_root_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_template_params_from_root_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_template_params_from_root_json`].
/// - `year`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_template_params_from_root_json`].
/// - `month`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_template_params_from_root_json`].
/// - `date`: Input consumed by [`crate::runtime::json_commands::dynamic_business_calendar_template_params_from_root_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_calendar_template_params_from_root_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_business_calendar_template_params_from_root_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_calendar_template_params_from_root_json(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_calendar_template_params_from_root_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
    year: Option<&str>,
    month: Option<&str>,
    date: Option<&str>,
    _actor_user_id: i64,
    csrf_token: &str,
) -> Option<String> {
    if std::env::var("PHAROS_TRACE_CALENDAR_RENDER")
        .ok()
        .as_deref()
        == Some("1")
    {
        eprintln!(
            "TRACE calendar render start slug={business_slug} year={:?} month={:?} date={:?}",
            year, month, date
        );
    }
    let business = bounded_state_array(root, "businesses")
        .iter()
        .find(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))?;
    let business_id = business.get("id").and_then(Value::as_i64)?;
    let business_name = business.get("name").map(value_to_text).unwrap_or_default();
    let availability = bounded_state_array(root, "business_availability");
    let appointments = bounded_state_array(root, "appointments");
    let requested_date = date
        .filter(|value| value.len() == 10 && value.as_bytes().get(4) == Some(&b'-'))
        .map(ToOwned::to_owned);
    let selected_year = year
        .and_then(|value| value.parse::<i32>().ok())
        .filter(|value| (2000..=2100).contains(value))
        .or_else(|| {
            requested_date
                .as_deref()
                .and_then(|value| value.get(0..4))
                .and_then(|value| value.parse().ok())
        });
    let selected_month = month
        .and_then(|value| value.parse::<u32>().ok())
        .filter(|value| (1..=12).contains(value))
        .or_else(|| {
            requested_date
                .as_deref()
                .and_then(|value| value.get(5..7))
                .and_then(|value| value.parse().ok())
        });
    let now = pharos_runtime_core::time::current_timestamp_utc();
    let today = now.get(..10)?.to_owned();
    let current_year = today.get(..4)?.parse::<i32>().ok()?;
    let current_month = today.get(5..7)?.parse::<u32>().ok()?;
    let fallback_date = if selected_year.is_none() && selected_month.is_none() {
        today
    } else {
        format!(
            "{:04}-{:02}-01",
            selected_year.unwrap_or(current_year),
            selected_month.unwrap_or(current_month)
        )
    };
    let selected_date = requested_date.unwrap_or(fallback_date);
    let selected_year = selected_year
        .or_else(|| selected_date.get(0..4).and_then(|value| value.parse().ok()))
        .unwrap_or(current_year);
    let selected_month = selected_month
        .or_else(|| selected_date.get(5..7).and_then(|value| value.parse().ok()))
        .unwrap_or(current_month);
    let month_label = [
        "January",
        "February",
        "March",
        "April",
        "May",
        "June",
        "July",
        "August",
        "September",
        "October",
        "November",
        "December",
    ][selected_month.saturating_sub(1) as usize]
        .to_owned();
    let days_in_month = days_in_month_business_logic_local(selected_year, selected_month);
    let first_day = day_abbrev_for_ymd_business_logic_local(selected_year, selected_month, 1)?;
    let first_index = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
        .iter()
        .position(|day| *day == first_day)
        .unwrap_or(0);
    let calendar_base_path = format!("/business/{business_slug}/calendar/");
    let mut calendar_rows_html = String::new();
    for week in 0..6 {
        let mut cells_html = String::new();
        for column in 0..7 {
            let grid_index = week * 7 + column;
            let day_number = grid_index - first_index as i32 + 1;
            if day_number < 1 || day_number > days_in_month as i32 {
                cells_html.push_str(&render_fragment_with_params(
                    app_root,
                    "templates/businesses/fragments/business_calendar_empty_day_cell.html",
                    serde_json::Map::from_iter([(
                        "cell_class".to_owned(),
                        Value::String("day".to_owned()),
                    )]),
                )?);
                continue;
            }
            let day_number = day_number as u32;
            let date_value = format!("{selected_year:04}-{selected_month:02}-{day_number:02}");
            let weekday =
                day_abbrev_for_ymd_business_logic_local(selected_year, selected_month, day_number)?;
            let day_schedule: Vec<&Value> = availability
                .iter()
                .filter(|row| row.get("business_id").and_then(Value::as_i64) == Some(business_id))
                .filter(|row| {
                    business_day_matches_group(
                        row.get("day_of_week").and_then(Value::as_str).unwrap_or(""),
                        weekday,
                    )
                })
                .collect();
            let day_has_booking = appointments.iter().any(|row| {
                row_i64_value(row, "business_id") == Some(business_id)
                    && row_date_time(row).0 == date_value
            });

            cells_html.push_str(&render_fragment_with_params(
                app_root,
                "templates/businesses/fragments/business_calendar_day_cell.html",
                serde_json::Map::from_iter([
                    (
                        "day_cell_classes".to_owned(),
                        Value::String(
                            [
                                (date_value == selected_date).then_some("today"),
                                day_has_booking.then_some("has-appointments"),
                            ]
                            .into_iter()
                            .flatten()
                            .map(|class_name| format!(" {class_name}"))
                            .collect::<String>(),
                        ),
                    ),
                    (
                        "day_path".to_owned(),
                        Value::String(format!(
                            "{calendar_base_path}?year={selected_year}&month={selected_month:02}&date={date_value}"
                        )),
                    ),
                    (
                        "day_number".to_owned(),
                        Value::String(day_number.to_string()),
                    ),
                    (
                        "day_chip_style".to_owned(),
                        Value::String(if date_value == selected_date {
                            "background:var(--primary);color:#fff;".to_owned()
                        } else if day_has_booking {
                            "background:#dcfce7;color:#166534;".to_owned()
                        } else {
                            "background:var(--gray-200);color:var(--gray-700);".to_owned()
                        }),
                    ),
                    ("appointment_summary".to_owned(), Value::String(String::new())),
                    (
                        "availability_color".to_owned(),
                        Value::String(if day_schedule.is_empty() {
                            String::new()
                        } else {
                            "var(--primary)".to_owned()
                        }),
                    ),
                    (
                        "availability_summary".to_owned(),
                        Value::String(String::new()),
                    ),
                ]),
            )?);
        }
        calendar_rows_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_calendar_week_row.html",
            serde_json::Map::from_iter([("cells_html".to_owned(), Value::String(cells_html))]),
        )?);
    }
    let selected_weekday = selected_date
        .get(8..10)
        .and_then(|day| day.parse::<u32>().ok())
        .and_then(|day| {
            day_abbrev_for_ymd_business_logic_local(selected_year, selected_month, day)
        })?;
    let selected_schedule: Vec<&Value> = availability
        .iter()
        .filter(|row| row.get("business_id").and_then(Value::as_i64) == Some(business_id))
        .filter(|row| {
            business_day_matches_group(
                row.get("day_of_week").and_then(Value::as_str).unwrap_or(""),
                selected_weekday,
            )
        })
        .collect();
    let mut selected_schedule_rows_html = String::new();
    for row in &selected_schedule {
        selected_schedule_rows_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_calendar_schedule_row.html",
            serde_json::Map::from_iter([
                (
                    "start_time".to_owned(),
                    Value::String(
                        row.get("start_time")
                            .map(value_to_text)
                            .map(|value| formatted_clock_time_business_logic_local(&value))
                            .unwrap_or_else(|| "9:00 AM".to_owned()),
                    ),
                ),
                (
                    "end_time".to_owned(),
                    Value::String(
                        row.get("end_time")
                            .map(value_to_text)
                            .map(|value| formatted_clock_time_business_logic_local(&value))
                            .unwrap_or_else(|| "5:00 PM".to_owned()),
                    ),
                ),
            ]),
        )?);
    }
    let default_booking_time = selected_schedule
        .first()
        .and_then(|row| row.get("start_time"))
        .map(value_to_text)
        .filter(|value| generated_surface_text_is_time(value))
        .map(|value| value.get(0..5).unwrap_or("09:00").to_owned())
        .unwrap_or_else(|| "09:00".to_owned());
    let mut service_options_html = String::new();
    let mut service_option_index = 0usize;
    for service in bounded_state_array(root, "services")
        .iter()
        .filter(|service| row_i64_value(service, "business_id") == Some(business_id))
    {
        let service_id = row_i64_value(service, "id").unwrap_or(0);
        if service_id <= 0 {
            continue;
        }
        let service_label = service
            .get("name")
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| format!("Service {service_id}"));
        let duration_minutes = row_i64_value(service, "duration_minutes")
            .unwrap_or(45)
            .max(1);
        service_options_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_calendar_option_with_duration.html",
            Map::from_iter([
                (
                    "option_value".to_owned(),
                    Value::String(service_id.to_string()),
                ),
                (
                    "option_label".to_owned(),
                    Value::String(format!("{service_label} · {duration_minutes} min")),
                ),
                (
                    "duration_minutes".to_owned(),
                    Value::String(duration_minutes.to_string()),
                ),
                (
                    "booking_option_index".to_owned(),
                    Value::String(String::new()),
                ),
                (
                    "selected_attr".to_owned(),
                    Value::String(if service_option_index == 0 {
                        " selected".to_owned()
                    } else {
                        String::new()
                    }),
                ),
            ]),
        )?);
        service_option_index = service_option_index.saturating_add(1);
        if let Some(booking_options) = service.get("booking_options").and_then(Value::as_array) {
            for (booking_option_index, booking_option) in booking_options.iter().enumerate() {
                let option_duration_minutes = row_i64_value(booking_option, "duration_minutes")
                    .unwrap_or(duration_minutes)
                    .max(1);
                let option_label = booking_option
                    .get("label")
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| format!("{option_duration_minutes} min"));
                service_options_html.push_str(&render_fragment_with_params(
                    app_root,
                    "templates/businesses/fragments/business_calendar_option_with_duration.html",
                    Map::from_iter([
                        (
                            "option_value".to_owned(),
                            Value::String(service_id.to_string()),
                        ),
                        (
                            "option_label".to_owned(),
                            Value::String(format!(
                                "{service_label} · {option_label} · {option_duration_minutes} min"
                            )),
                        ),
                        (
                            "duration_minutes".to_owned(),
                            Value::String(option_duration_minutes.to_string()),
                        ),
                        (
                            "booking_option_index".to_owned(),
                            Value::String(booking_option_index.to_string()),
                        ),
                        (
                            "selected_attr".to_owned(),
                            Value::String(if service_option_index == 0 {
                                " selected".to_owned()
                            } else {
                                String::new()
                            }),
                        ),
                    ]),
                )?);
                service_option_index = service_option_index.saturating_add(1);
            }
        }
    }
    let mut internal_technician_options_html = String::new();
    for technician in bounded_state_array(root, "technicians")
        .iter()
        .filter(|technician| row_i64_value(technician, "business_id") == Some(business_id))
    {
        let technician_id = row_i64_value(technician, "id").unwrap_or(0);
        if technician_id <= 0 {
            continue;
        }
        let technician_label = technician
            .get("name")
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| format!("Technician {technician_id}"));
        let booked_slots = appointments
            .iter()
            .filter(|appointment| row_i64_value(appointment, "business_id") == Some(business_id))
            .filter(|appointment| {
                row_i64_value(appointment, "technician_id") == Some(technician_id)
            })
            .filter(|appointment| row_date_time(appointment).0 == selected_date)
            .filter(|appointment| {
                appointment.get("status").map(value_to_text).as_deref() != Some("cancelled")
            })
            .filter_map(|appointment| {
                let (_, booked_time) = row_date_time(appointment);
                let duration = appointment
                    .get("service_duration_minutes")
                    .and_then(Value::as_i64)
                    .or_else(|| {
                        row_i64_value(appointment, "service_id")
                            .and_then(|service_id| {
                                state_row_by_i64(root, "services", "id", service_id)
                            })
                            .and_then(|service| row_i64_value(service, "duration_minutes"))
                    })
                    .unwrap_or(45)
                    .max(1);
                generated_surface_text_is_time(&booked_time)
                    .then(|| format!("{}:{duration}", booked_time.get(0..5).unwrap_or("00:00")))
            })
            .collect::<Vec<_>>()
            .join(",");
        internal_technician_options_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_calendar_technician_option.html",
            Map::from_iter([
                (
                    "option_value".to_owned(),
                    Value::String(technician_id.to_string()),
                ),
                ("option_label".to_owned(), Value::String(technician_label)),
                ("booked_slots".to_owned(), Value::String(booked_slots)),
                ("selected_attr".to_owned(), Value::String(String::new())),
            ]),
        )?);
    }
    let mut appointment_rows_html = String::new();
    for row in appointments
        .iter()
        .filter(|row| row_i64_value(row, "business_id") == Some(business_id))
        .filter(|row| row_date_time(row).0 == selected_date)
    {
        let appointment_id = row_i64_value(row, "id").unwrap_or(0);
        let (appointment_date, appointment_time) = row_date_time(row);
        let service = row_i64_value(row, "service_id")
            .and_then(|id| state_row_by_i64(root, "services", "id", id));
        let appointment_duration_minutes = row
            .get("service_duration_minutes")
            .and_then(Value::as_i64)
            .or_else(|| service.and_then(|service| row_i64_value(service, "duration_minutes")))
            .unwrap_or(45)
            .max(1);
        let appointment_end_time = row
            .get("end_time")
            .map(value_to_text)
            .and_then(|value| {
                value
                    .get(11..16)
                    .or_else(|| value.get(0..5))
                    .map(ToOwned::to_owned)
            })
            .filter(|value| !value.is_empty())
            .or_else(|| {
                appointment_time_plus_minutes(&appointment_time, appointment_duration_minutes)
            })
            .unwrap_or_default();
        let technician = row_i64_value(row, "technician_id")
            .and_then(|id| state_row_by_i64(root, "technicians", "id", id));
        let customer =
            row_i64_value(row, "user_id").and_then(|id| state_row_by_i64(root, "users", "id", id));
        let appointment_type = service
            .and_then(|value| value.get("name"))
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "Appointment".to_owned());
        let technician_name = technician
            .and_then(|value| value.get("name"))
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "Unassigned".to_owned());
        let customer_name = customer
            .and_then(|value| value.get("full_name").or_else(|| value.get("display_name")))
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "Customer".to_owned());
        let customer_email = customer
            .and_then(|value| value.get("email"))
            .map(value_to_text)
            .unwrap_or_default();
        let payment_status = row
            .get("payment_status")
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "not required".to_owned());
        let notes_text = row
            .get("notes")
            .map(value_to_text)
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "None".to_owned());
        let dialog_id = format!("business-calendar-appointment-{appointment_id}");
        let csrf_token_input_ui_html = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/csrf_hidden_input.html",
            Map::from_iter([(
                "csrf_token".to_owned(),
                Value::String(csrf_token.to_owned()),
            )]),
        )?;
        let mut technician_options_html = String::new();
        let current_technician_id = row_i64_value(row, "technician_id").unwrap_or(0);
        for option in bounded_state_array(root, "technicians")
            .iter()
            .filter(|technician| row_i64_value(technician, "business_id") == Some(business_id))
        {
            let technician_id = row_i64_value(option, "id").unwrap_or(0);
            if technician_id <= 0 {
                continue;
            }
            if !super::business::dynamic_technician_unbooked_for_slot(
                root,
                business_id,
                technician_id,
                &appointment_date,
                &appointment_time,
                appointment_duration_minutes,
                appointment_id,
            ) {
                continue;
            }
            let technician_label = option
                .get("name")
                .map(value_to_text)
                .filter(|value| !value.is_empty())
                .unwrap_or_else(|| format!("Technician {technician_id}"));
            technician_options_html.push_str(&render_fragment_with_params(
                app_root,
                "templates/shared/fragments/select_option.html",
                Map::from_iter([
                    (
                        "option_value".to_owned(),
                        Value::String(technician_id.to_string()),
                    ),
                    ("option_label".to_owned(), Value::String(technician_label)),
                    (
                        "selected_attr".to_owned(),
                        Value::String(if technician_id == current_technician_id {
                            " selected".to_owned()
                        } else {
                            String::new()
                        }),
                    ),
                ]),
            )?);
        }
        let return_to_path = format!(
            "/business/{business_slug}/calendar/?year={selected_year}&month={selected_month:02}&date={selected_date}"
        );
        let dialog_copy_html = render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_calendar_appointment_dialog_copy.html",
            Map::from_iter([
                (
                    "appointment_id".to_owned(),
                    Value::String(appointment_id.to_string()),
                ),
                (
                    "appointment_type".to_owned(),
                    Value::String(appointment_type.clone()),
                ),
                (
                    "appointment_duration_minutes".to_owned(),
                    Value::String(appointment_duration_minutes.to_string()),
                ),
                (
                    "appointment_date".to_owned(),
                    Value::String(appointment_date.clone()),
                ),
                (
                    "appointment_time".to_owned(),
                    Value::String(formatted_clock_time_business_logic_local(&appointment_time)),
                ),
                (
                    "appointment_end_time".to_owned(),
                    Value::String(formatted_clock_time_business_logic_local(
                        &appointment_end_time,
                    )),
                ),
                (
                    "customer_name".to_owned(),
                    Value::String(customer_name.clone()),
                ),
                ("customer_email".to_owned(), Value::String(customer_email)),
                (
                    "technician_name".to_owned(),
                    Value::String(technician_name.clone()),
                ),
                ("payment_status".to_owned(), Value::String(payment_status)),
                ("notes_text".to_owned(), Value::String(notes_text)),
            ]),
        )?;
        let dialog_actions_html = render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_calendar_appointment_dialog_actions.html",
            Map::from_iter([
                (
                    "appointment_id".to_owned(),
                    Value::String(appointment_id.to_string()),
                ),
                (
                    "assign_technician_path".to_owned(),
                    Value::String(format!("/appointments/{appointment_id}/assign-technician/")),
                ),
                ("return_to_path".to_owned(), Value::String(return_to_path)),
                (
                    "technician_options_html".to_owned(),
                    Value::String(technician_options_html),
                ),
                (
                    "reschedule_path".to_owned(),
                    Value::String(format!("/b/{business_slug}/")),
                ),
                (
                    "complete_path".to_owned(),
                    Value::String(format!("/appointments/{appointment_id}/complete/")),
                ),
                (
                    "cancel_path".to_owned(),
                    Value::String(format!("/appointments/{appointment_id}/cancel/")),
                ),
                (
                    "csrf_token_input_ui_html".to_owned(),
                    Value::String(csrf_token_input_ui_html),
                ),
            ]),
        )?;
        let appointment_dialog_html = render_workspace_dialog_html_business_logic_local(
            app_root,
            &dialog_id,
            "business-calendar-dialog",
            "business-calendar-dialog-shell",
            "business-calendar-dialog-copy",
            &dialog_copy_html,
            "business-calendar-dialog-actions",
            &dialog_actions_html,
        )?;
        appointment_rows_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_calendar_appointment_row.html",
            Map::from_iter([
                ("dialog_id".to_owned(), Value::String(dialog_id)),
                (
                    "appointment_type".to_owned(),
                    Value::String(appointment_type),
                ),
                (
                    "technician_name".to_owned(),
                    Value::String(format!("Assigned: {technician_name}")),
                ),
                (
                    "appointment_time".to_owned(),
                    Value::String(formatted_clock_time_business_logic_local(&appointment_time)),
                ),
                (
                    "appointment_dialog_html".to_owned(),
                    Value::String(appointment_dialog_html),
                ),
            ]),
        )?);
    }
    if appointment_rows_html.is_empty() {
        appointment_rows_html = render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_calendar_appointments_empty.html",
            serde_json::Map::new(),
        )?;
    }
    let return_to_path = format!(
        "/business/{business_slug}/calendar/?year={selected_year}&month={selected_month:02}&date={selected_date}"
    );
    let internal_booking_copy_html = render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_calendar_internal_booking_dialog_copy.html",
        Map::from_iter([
            (
                "business_id".to_owned(),
                Value::String(business_id.to_string()),
            ),
            (
                "selected_date".to_owned(),
                Value::String(selected_date.clone()),
            ),
            (
                "default_booking_time".to_owned(),
                Value::String(default_booking_time),
            ),
            (
                "create_appointment_path".to_owned(),
                Value::String(format!(
                    "/business/{business_slug}/calendar/appointments/new/"
                )),
            ),
            ("return_to_path".to_owned(), Value::String(return_to_path)),
            (
                "service_options_html".to_owned(),
                Value::String(service_options_html),
            ),
            (
                "internal_technician_options_html".to_owned(),
                Value::String(internal_technician_options_html),
            ),
            (
                "csrf_token_input_ui_html".to_owned(),
                Value::String(render_fragment_with_params(
                    app_root,
                    "templates/shared/fragments/csrf_hidden_input.html",
                    Map::from_iter([(
                        "csrf_token".to_owned(),
                        Value::String(csrf_token.to_owned()),
                    )]),
                )?),
            ),
        ]),
    )?;
    let internal_booking_dialog_html = render_workspace_dialog_html_business_logic_local(
        app_root,
        "business-calendar-internal-booking",
        "business-calendar-dialog",
        "business-calendar-dialog-shell",
        "business-calendar-dialog-copy",
        &internal_booking_copy_html,
        "business-calendar-dialog-actions",
        "",
    )?;
    let prev_month = if selected_month == 1 {
        12
    } else {
        selected_month - 1
    };
    let prev_year = if selected_month == 1 {
        selected_year - 1
    } else {
        selected_year
    };
    let next_month = if selected_month == 12 {
        1
    } else {
        selected_month + 1
    };
    let next_year = if selected_month == 12 {
        selected_year + 1
    } else {
        selected_year
    };
    compact(&Value::Object(serde_json::Map::from_iter([
        ("business_name".to_owned(), Value::String(business_name)),
        (
            "landing_path".to_owned(),
            Value::String(format!("/b/{business_slug}/")),
        ),
        (
            "manage_path".to_owned(),
            Value::String(format!("/businesses/{business_slug}/")),
        ),
        ("month_label".to_owned(), Value::String(month_label)),
        (
            "selected_year".to_owned(),
            Value::String(selected_year.to_string()),
        ),
        (
            "selected_date".to_owned(),
            Value::String(selected_date.clone()),
        ),
        (
            "calendar_rows_html".to_owned(),
            Value::String(calendar_rows_html),
        ),
        (
            "selected_schedule_empty_style".to_owned(),
            Value::String(if selected_schedule.is_empty() {
                String::new()
            } else {
                "display:none;".to_owned()
            }),
        ),
        (
            "selected_schedule_list_style".to_owned(),
            Value::String(if selected_schedule.is_empty() {
                "display:none;".to_owned()
            } else {
                "display:flex;".to_owned()
            }),
        ),
        (
            "selected_schedule_rows_html".to_owned(),
            Value::String(selected_schedule_rows_html),
        ),
        (
            "selected_schedule_cta_style".to_owned(),
            Value::String(if selected_schedule.is_empty() {
                "display:none".to_owned()
            } else {
                "display:block;".to_owned()
            }),
        ),
        (
            "selected_schedule_public_booking_path".to_owned(),
            Value::String(format!("/b/{business_slug}/")),
        ),
        (
            "appointment_rows_html".to_owned(),
            Value::String(appointment_rows_html),
        ),
        (
            "internal_booking_dialog_html".to_owned(),
            Value::String(internal_booking_dialog_html),
        ),
        (
            "prev_month_path".to_owned(),
            Value::String(format!(
                "{calendar_base_path}?year={prev_year}&month={prev_month:02}"
            )),
        ),
        (
            "next_month_path".to_owned(),
            Value::String(format!(
                "{calendar_base_path}?year={next_year}&month={next_month:02}"
            )),
        ),
    ])))
}

/// Builds the business create page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_create_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_create_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_create_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_create_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_create_page_params_json(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_create_page_params_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    dynamic_business_admin_page_params_json(root, business_slug, app_root)
}

/// Builds the business dashboard page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_dashboard_page_params_from_root_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_dashboard_page_params_from_root_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_dashboard_page_params_from_root_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_dashboard_page_params_from_root_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_dashboard_page_params_from_root_json(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_dashboard_page_params_from_root_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    dynamic_business_admin_page_params_json(root, business_slug, app_root)
}

/// Builds the business dashboard page parameters from state.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_dashboard_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_dashboard_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_dashboard_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_dashboard_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_dashboard_page_params_json(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_dashboard_page_params_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    dynamic_business_dashboard_page_params_from_root_json(root, business_slug, app_root)
}

/// Builds a business edit page parameter document.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_edit_page_params_from_root_json_dup_local`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_edit_page_params_from_root_json_dup_local`].
/// - `business_id`: Input consumed by [`crate::runtime::json_commands::dynamic_business_edit_page_params_from_root_json_dup_local`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_edit_page_params_from_root_json_dup_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_edit_page_params_from_root_json_dup_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_edit_page_params_from_root_json_dup_local(std::path::Path::new("."), "demo", todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_edit_page_params_from_root_json_dup_local(
    root: &Value,
    business_slug: &str,
    business_id: i64,
    app_root: &Path,
) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("business_slug".into(), Value::String(business_slug.into()));
    extra.insert("business_id".into(), Value::from(business_id));
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    page_params_value(root, "business-edit", extra)
}

/// Builds the business edit page parameters from state.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_edit_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_edit_page_params_json`].
/// - `business_id`: Input consumed by [`crate::runtime::json_commands::dynamic_business_edit_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_edit_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_edit_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_edit_page_params_json(std::path::Path::new("."), "demo", todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_edit_page_params_json(
    root: &Value,
    business_slug: &str,
    business_id: i64,
    app_root: &Path,
) -> Option<String> {
    dynamic_business_edit_page_params_from_root_json_dup_local(
        root,
        business_slug,
        business_id,
        app_root,
    )
}

/// Resolves one business media URL under the app-owned media directory.
///
/// # Parameters
///
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_media_url`].
/// - `media_url`: Input consumed by [`crate::runtime::json_commands::dynamic_business_media_url`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_media_url`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_media_url("demo", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_media_url(business_slug: &str, media_url: &str) -> Option<String> {
    if business_slug.is_empty() || media_url.is_empty() || media_url.contains(['\r', '\n']) {
        return None;
    }
    Some(format!(
        "/media/businesses/{}/{}",
        business_slug,
        media_url.trim_start_matches('/')
    ))
}

/// Builds profile page parameters from persisted state.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_profile_page_params_json`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::dynamic_profile_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_profile_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_profile_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_profile_page_params_json(std::path::Path::new("."), 1, std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_profile_page_params_json(
    root: &Value,
    user_id: i64,
    app_root: &Path,
) -> Option<String> {
    let user = state_row_by_i64(root, "users", "id", user_id)?;
    let full_name = user
        .get("full_name")
        .map(value_to_text)
        .filter(|value| !value.is_empty())
        .or_else(|| user.get("display_name").map(value_to_text))
        .unwrap_or_default();
    let email = user.get("email").map(value_to_text).unwrap_or_default();
    let phone_number = user
        .get("phone_number")
        .map(value_to_text)
        .unwrap_or_default();
    let address = user.get("address").map(value_to_text).unwrap_or_default();
    let payment_preference = user
        .get("payment_preference")
        .map(value_to_text)
        .filter(|value| !value.is_empty())
        .unwrap_or_else(|| "pay_on_site".to_owned());
    let google_status = bounded_state_array(root, "google_calendar_connections")
        .iter()
        .find(|row| row_i64_value(row, "user_id") == Some(user_id))
        .and_then(|row| row.get("connection_status"))
        .map(value_to_text)
        .filter(|value| !value.is_empty())
        .unwrap_or_else(|| "Disconnected".to_owned());
    let mut subscription_rows_html = String::new();
    for subscription in bounded_state_array(root, "subscriptions")
        .iter()
        .filter(|row| row_i64_value(row, "user_id") == Some(user_id))
    {
        let Some(business) = row_i64_value(subscription, "business_id")
            .and_then(|id| state_row_by_i64(root, "businesses", "id", id))
        else {
            continue;
        };
        let business_slug = business.get("slug").map(value_to_text).unwrap_or_default();
        if business_slug.is_empty() {
            continue;
        }
        let unsubscribe_button = render_fragment_with_params(
            app_root,
            "templates/shared/fragments/ui_button.html",
            Map::from_iter([
                (
                    "id".to_owned(),
                    Value::String(format!("profile-unsubscribe-{business_slug}")),
                ),
                ("type".to_owned(), Value::String("submit".to_owned())),
                (
                    "class_name".to_owned(),
                    Value::String("btn btn-danger btn-sm".to_owned()),
                ),
                ("attributes_html".to_owned(), Value::String(String::new())),
                (
                    "content".to_owned(),
                    Value::String("Unsubscribe".to_owned()),
                ),
            ]),
        )?;
        subscription_rows_html.push_str(&render_fragment_with_params(
            app_root,
            "templates/profile/fragments/subscription_row.html",
            Map::from_iter([
                ("business_slug".to_owned(), Value::String(business_slug)),
                (
                    "business_name".to_owned(),
                    Value::String(
                        business
                            .get("name")
                            .map(value_to_text)
                            .unwrap_or_else(|| "Business".to_owned()),
                    ),
                ),
                (
                    "profile_unsubscribe_button_ui_html".to_owned(),
                    Value::String(unsubscribe_button),
                ),
            ]),
        )?);
    }
    let subscriptions_empty = subscription_rows_html.is_empty();
    let subscriptions_empty_html = if subscriptions_empty {
        render_fragment_with_params(
            app_root,
            "templates/profile/fragments/subscriptions_empty.html",
            Map::new(),
        )?
    } else {
        String::new()
    };
    compact(&Value::Object(Map::from_iter([
        ("full_name".to_owned(), Value::String(full_name)),
        ("email".to_owned(), Value::String(email)),
        ("phone_number".to_owned(), Value::String(phone_number)),
        ("address".to_owned(), Value::String(address)),
        (
            "selected_payment_preference".to_owned(),
            Value::String(payment_preference),
        ),
        ("google_status".to_owned(), Value::String(google_status)),
        (
            "subscriptions_list_style".to_owned(),
            Value::String(if subscriptions_empty {
                "display:none;".to_owned()
            } else {
                String::new()
            }),
        ),
        (
            "subscription_rows_html".to_owned(),
            Value::String(subscription_rows_html),
        ),
        (
            "subscriptions_empty_style".to_owned(),
            Value::String(if subscriptions_empty {
                String::new()
            } else {
                "display:none;".to_owned()
            }),
        ),
        (
            "subscriptions_empty_html".to_owned(),
            Value::String(subscriptions_empty_html),
        ),
    ])))
}

pub fn dynamic_booking_detail_page_params_from_root_json(
    root: &Value,
    user_id: i64,
    booking_id: i64,
) -> Option<String> {
    let booking = state_row_by_i64(root, "bookings", "id", booking_id)
        .filter(|row| row_i64_value(row, "user_id") == Some(user_id))?;
    let (date, time) = row_date_time(booking);
    compact(&Value::Object(Map::from_iter([
        (
            "booking_title".to_owned(),
            Value::String(
                booking
                    .get("title")
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| "Booking".to_owned()),
            ),
        ),
        ("date_value".to_owned(), Value::String(date)),
        (
            "time_value".to_owned(),
            Value::String(formatted_clock_time_business_logic_local(&time)),
        ),
        (
            "status_value".to_owned(),
            Value::String(
                booking
                    .get("status")
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| "confirmed".to_owned()),
            ),
        ),
    ])))
}

pub fn dynamic_appointment_detail_page_params_from_root_json(
    root: &Value,
    user_id: i64,
    appointment_id: i64,
    app_root: &Path,
) -> Option<String> {
    let appointment = state_row_by_i64(root, "appointments", "id", appointment_id)?;
    let business = row_i64_value(appointment, "business_id")
        .and_then(|id| state_row_by_i64(root, "businesses", "id", id))?;
    let appointment_user_id = row_i64_value(appointment, "user_id").unwrap_or(0);
    let owner_id = row_i64_value(business, "owner_id").unwrap_or(0);
    if appointment_user_id != user_id && owner_id != user_id {
        return None;
    }
    let service = row_i64_value(appointment, "service_id")
        .and_then(|id| state_row_by_i64(root, "services", "id", id));
    let technician = row_i64_value(appointment, "technician_id")
        .and_then(|id| state_row_by_i64(root, "technicians", "id", id));
    let customer = state_row_by_i64(root, "users", "id", appointment_user_id);
    let (date, time) = row_date_time(appointment);
    let service_cost = appointment
        .get("service_cost")
        .map(value_to_text)
        .filter(|value| !value.is_empty());
    let service_cost_block = if let Some(cost) = service_cost.as_deref() {
        render_fragment_with_params(
            app_root,
            "templates/appointments/detail/fragments/service_cost_block.html",
            Map::from_iter([("service_cost".to_owned(), Value::String(cost.to_owned()))]),
        )?
    } else {
        String::new()
    };
    let notes = appointment
        .get("notes")
        .map(value_to_text)
        .unwrap_or_default();
    let notes_block = if notes.is_empty() {
        String::new()
    } else {
        render_fragment_with_params(
            app_root,
            "templates/appointments/detail/fragments/notes_block.html",
            Map::from_iter([("notes_text".to_owned(), Value::String(notes))]),
        )?
    };
    compact(&Value::Object(Map::from_iter([
        (
            "service_name".to_owned(),
            Value::String(
                service
                    .and_then(|row| row.get("name"))
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| "Appointment".to_owned()),
            ),
        ),
        (
            "business_slug".to_owned(),
            Value::String(business.get("slug").map(value_to_text).unwrap_or_default()),
        ),
        (
            "business_public_path".to_owned(),
            Value::String(format!(
                "/b/{}/",
                business.get("slug").map(value_to_text).unwrap_or_default()
            )),
        ),
        (
            "business_name".to_owned(),
            Value::String(
                business
                    .get("name")
                    .map(value_to_text)
                    .unwrap_or_else(|| "Business".to_owned()),
            ),
        ),
        ("date_value".to_owned(), Value::String(date)),
        (
            "time_value".to_owned(),
            Value::String(formatted_clock_time_business_logic_local(&time)),
        ),
        (
            "status_value".to_owned(),
            Value::String(
                appointment
                    .get("status")
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| "scheduled".to_owned()),
            ),
        ),
        (
            "technician_name".to_owned(),
            Value::String(
                technician
                    .and_then(|row| row.get("name"))
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| "Unassigned".to_owned()),
            ),
        ),
        (
            "duration_minutes".to_owned(),
            Value::String(
                appointment
                    .get("service_duration_minutes")
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| "45".to_owned()),
            ),
        ),
        (
            "customer_name".to_owned(),
            Value::String(
                customer
                    .and_then(|row| row.get("full_name").or_else(|| row.get("display_name")))
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| "Customer".to_owned()),
            ),
        ),
        (
            "customer_email".to_owned(),
            Value::String(
                customer
                    .and_then(|row| row.get("email"))
                    .map(value_to_text)
                    .unwrap_or_default(),
            ),
        ),
        (
            "customer_phone".to_owned(),
            Value::String(
                customer
                    .and_then(|row| row.get("phone_number"))
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| "Not provided".to_owned()),
            ),
        ),
        (
            "customer_address".to_owned(),
            Value::String(
                customer
                    .and_then(|row| row.get("address"))
                    .map(value_to_text)
                    .filter(|value| !value.is_empty())
                    .unwrap_or_else(|| "Not provided".to_owned()),
            ),
        ),
        (
            "service_cost_block".to_owned(),
            Value::String(service_cost_block),
        ),
        ("notes_block".to_owned(), Value::String(notes_block)),
    ])))
}

/// Builds service booking form parameters from state.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_from_root_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_from_root_json`].
/// - `service_id`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_from_root_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_from_root_json`].
/// - `error_message`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_from_root_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_service_book_form_page_params_from_root_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_service_book_form_page_params_from_root_json(std::path::Path::new("."), "demo", todo!(), std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_service_book_form_page_params_from_root_json(
    root: &Value,
    business_slug: &str,
    service_id: i64,
    app_root: &Path,
    error_message: &str,
) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("business_slug".into(), Value::String(business_slug.into()));
    extra.insert("service_id".into(), Value::from(service_id));
    extra.insert("error".into(), Value::String(error_message.into()));
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    page_params_value(root, "service-book-form", extra)
}

/// Builds service booking form parameters from state file.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_json`].
/// - `service_id`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_json`].
/// - `error_message`: Input consumed by [`crate::runtime::json_commands::dynamic_service_book_form_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_service_book_form_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_service_book_form_page_params_json(todo!(), "demo", todo!(), std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_service_book_form_page_params_json(
    state_path: &Path,
    business_slug: &str,
    service_id: i64,
    app_root: &Path,
    error_message: &str,
) -> Option<String> {
    dynamic_service_book_form_page_params_from_root_json(
        &json_doc_load_file(state_path)?,
        business_slug,
        service_id,
        app_root,
        error_message,
    )
}

/// Builds service edit parameters from state.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_service_edit_page_params_from_root_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_service_edit_page_params_from_root_json`].
/// - `service_id`: Input consumed by [`crate::runtime::json_commands::dynamic_service_edit_page_params_from_root_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_service_edit_page_params_from_root_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_service_edit_page_params_from_root_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_service_edit_page_params_from_root_json(std::path::Path::new("."), "demo", todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_service_edit_page_params_from_root_json(
    root: &Value,
    business_slug: &str,
    service_id: i64,
    app_root: &Path,
) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("business_slug".into(), Value::String(business_slug.into()));
    extra.insert("service_id".into(), Value::from(service_id));
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    page_params_value(root, "service-edit", extra)
}

/// Builds service edit parameters from state file.
///
/// # Parameters
///
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::dynamic_service_edit_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_service_edit_page_params_json`].
/// - `service_id`: Input consumed by [`crate::runtime::json_commands::dynamic_service_edit_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_service_edit_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_service_edit_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_service_edit_page_params_json(todo!(), "demo", todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_service_edit_page_params_json(
    state_path: &Path,
    business_slug: &str,
    service_id: i64,
    app_root: &Path,
) -> Option<String> {
    dynamic_service_edit_page_params_from_root_json(
        &json_doc_load_file(state_path)?,
        business_slug,
        service_id,
        app_root,
    )
}

/// Performs rating score f64.
fn rating_score_f64(value: &Value) -> f64 {
    value
        .as_f64()
        .or_else(|| value.as_i64().map(|number| number as f64))
        .unwrap_or(0.0)
}

/// Performs rating score label.
fn rating_score_label(score: f64) -> String {
    if (score.fract()).abs() < 0.000_001 {
        format!("{score:.0}/5")
    } else {
        format!("{score:.1}/5")
    }
}

/// Performs rating stars HTML.
fn rating_stars_html(app_root: &Path, score: f64) -> Option<String> {
    let clamped = score.clamp(0.0, 5.0);
    let full = clamped.floor() as usize;
    let has_half = (clamped - full as f64) >= 0.5;
    let empty = 5usize.saturating_sub(full + usize::from(has_half));
    let mut out = String::new();
    for _ in 0..full {
        out.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_rating_star.html",
            Map::from_iter([(
                "class_name".to_owned(),
                Value::String("bi-star-fill".to_owned()),
            )]),
        )?);
    }
    if has_half {
        out.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_rating_star.html",
            Map::from_iter([(
                "class_name".to_owned(),
                Value::String("bi-star-half".to_owned()),
            )]),
        )?);
    }
    for _ in 0..empty {
        out.push_str(&render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_rating_star.html",
            Map::from_iter([("class_name".to_owned(), Value::String("bi-star".to_owned()))]),
        )?);
    }
    Some(out)
}

/// Builds the business landing page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_landing_page_params_json`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_business_landing_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_business_landing_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_business_landing_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_business_landing_page_params_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_business_landing_page_params_json(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_business_landing_page_params_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    let business = generated::dynamic_find_business_by_slug(root, business_slug)?;
    let business_id = business.get("id").and_then(Value::as_i64)?;
    let business_name = value_to_text(business.get("name").unwrap_or(&Value::Null));
    let description = value_to_text(business.get("description").unwrap_or(&Value::Null));
    let secondary_color = business
        .get("secondary_color")
        .and_then(Value::as_str)
        .filter(|value| value.len() == 7 && value.starts_with('#'))
        .unwrap_or("#e5e7eb");
    let hero_style = format!(
        "background:{secondary_color};color:{};",
        contrast_text_color_business_logic_local(secondary_color)
    );

    let image_html = business
        .get("image_url")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .and_then(|image_url| {
            render_app_fragment_from_doc(
                &app_root.to_string_lossy(),
                "templates/businesses/fragments/business_landing_image.html",
                &Value::Object(Map::from_iter([
                    ("image_url".to_owned(), Value::String(image_url.to_owned())),
                    ("image_alt".to_owned(), Value::String(business_name.clone())),
                ])),
            )
        })
        .unwrap_or_default();

    let cta_html = render_app_fragment_from_doc(
        &app_root.to_string_lossy(),
        "templates/businesses/fragments/business_logged_out_cta.html",
        &Value::Object(Map::from_iter([(
            "business_slug".to_owned(),
            Value::String(business_slug.to_owned()),
        )])),
    )
    .unwrap_or_default();

    let mut service_cards_html = String::new();
    let mut services = bounded_state_array(root, "services")
        .iter()
        .filter(|service| {
            service.get("business_id").and_then(Value::as_i64) == Some(business_id)
                && service
                    .get("is_active")
                    .and_then(Value::as_bool)
                    .unwrap_or(true)
        })
        .collect::<Vec<_>>();
    services.sort_by_key(|service| {
        service
            .get("sort_order")
            .and_then(Value::as_i64)
            .unwrap_or(i64::MAX)
    });
    for service in services.into_iter().take(MAX_OUTPUT_ROWS_JSON) {
        let service_id = service
            .get("id")
            .and_then(Value::as_i64)
            .unwrap_or_default();
        let service_name = value_to_text(service.get("name").unwrap_or(&Value::Null));
        let image_url = service
            .get("image_url")
            .or_else(|| service.get("image"))
            .map(value_to_text)
            .unwrap_or_default();
        let primary_color = service
            .get("primary_color")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty());
        let visual_html =
            service_visual_html(app_root, Some(&image_url), &service_name, primary_color)
                .unwrap_or_default();
        let card_params = Value::Object(Map::from_iter([
            (
                "business_slug".to_owned(),
                Value::String(business_slug.to_owned()),
            ),
            ("service_id".to_owned(), Value::from(service_id)),
            ("service_visual_html".to_owned(), Value::String(visual_html)),
            ("service_name".to_owned(), Value::String(service_name)),
            (
                "service_duration_minutes".to_owned(),
                Value::from(
                    service
                        .get("duration_minutes")
                        .and_then(Value::as_i64)
                        .unwrap_or(45),
                ),
            ),
            (
                "service_cost".to_owned(),
                Value::String(value_to_text(service.get("cost").unwrap_or(&Value::Null))),
            ),
            (
                "service_description".to_owned(),
                Value::String(value_to_text(
                    service.get("description").unwrap_or(&Value::Null),
                )),
            ),
        ]));
        if let Some(card) = render_app_fragment_from_doc(
            &app_root.to_string_lossy(),
            "templates/businesses/fragments/business_service_card.html",
            &card_params,
        ) {
            service_cards_html.push_str(&card);
        }
    }
    if service_cards_html.is_empty() {
        service_cards_html = render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_services_empty.html",
            Map::new(),
        )?;
    }

    let mut rating_rows_html = String::new();
    for rating in bounded_state_array(root, "ratings")
        .iter()
        .filter(|rating| rating.get("business_id").and_then(Value::as_i64) == Some(business_id))
        .take(MAX_OUTPUT_ROWS_JSON)
    {
        let score = rating_score_f64(rating.get("score").unwrap_or(&Value::Null));
        if let Some(row) = render_app_fragment_from_doc(
            &app_root.to_string_lossy(),
            "templates/businesses/fragments/business_rating_row.html",
            &Value::Object(Map::from_iter([
                (
                    "rating_score_label".to_owned(),
                    Value::String(rating_score_label(score)),
                ),
                (
                    "rating_stars_html".to_owned(),
                    Value::String(rating_stars_html(app_root, score)?),
                ),
                (
                    "rating_comment".to_owned(),
                    Value::String(value_to_text(rating.get("comment").unwrap_or(&Value::Null))),
                ),
            ])),
        ) {
            rating_rows_html.push_str(&row);
        }
    }
    if rating_rows_html.is_empty() {
        rating_rows_html = render_fragment_with_params(
            app_root,
            "templates/businesses/fragments/business_ratings_empty.html",
            Map::new(),
        )?;
    }

    compact(&Value::Object(Map::from_iter([
        (
            "business_slug".to_owned(),
            Value::String(business_slug.to_owned()),
        ),
        ("business_name".to_owned(), Value::String(business_name)),
        (
            "business_description".to_owned(),
            Value::String(description),
        ),
        ("hero_style".to_owned(), Value::String(hero_style)),
        (
            "private_badge_html".to_owned(),
            Value::String(String::new()),
        ),
        ("business_image_html".to_owned(), Value::String(image_html)),
        ("cta_html".to_owned(), Value::String(cta_html)),
        (
            "service_cards_html".to_owned(),
            Value::String(service_cards_html),
        ),
        (
            "rating_rows_html".to_owned(),
            Value::String(rating_rows_html),
        ),
    ])))
}

/// Builds the diagnostics page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_diagnostics_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_diagnostics_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_diagnostics_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_diagnostics_page_params_json(std::path::Path::new("."), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_diagnostics_page_params_json(root: &Value, app_root: &Path) -> Option<String> {
    let mut extra = Map::new();
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    extra.insert(
        "audit_events".into(),
        Value::Array(bounded_state_array(root, "audit_events").to_vec()),
    );
    page_params_value(root, "diagnostics", extra)
}

/// Renders diagnostics page params.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::render_diagnostics_page_params`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_diagnostics_page_params`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_diagnostics_page_params`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_diagnostics_page_params(std::path::Path::new("."), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_diagnostics_page_params(root: &Value, app_root: &Path) -> Option<String> {
    dynamic_diagnostics_page_params_json(root, app_root)
}

/// Builds the explore page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_explore_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_explore_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_explore_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_explore_page_params_json(std::path::Path::new("."), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_explore_page_params_json(root: &Value, app_root: &Path) -> Option<String> {
    let mut extra = Map::new();
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    extra.insert(
        "businesses".into(),
        Value::Array(bounded_state_array(root, "businesses").to_vec()),
    );
    page_params_value(root, "explore", extra)
}

/// Builds a job-queue detail page parameter document.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_job_queue_detail_page_params_json`].
/// - `job_id`: Input consumed by [`crate::runtime::json_commands::dynamic_job_queue_detail_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_job_queue_detail_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_job_queue_detail_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_job_queue_detail_page_params_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_job_queue_detail_page_params_json(std::path::Path::new("."), todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_job_queue_detail_page_params_json(
    root: &Value,
    job_id: i64,
    app_root: &Path,
) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("job_id".into(), Value::from(job_id));
    extra.insert(
        "app_root".into(),
        Value::String(app_root.to_string_lossy().into_owned()),
    );
    extra.insert(
        "job".into(),
        bounded_state_array(root, "job_executions")
            .iter()
            .find(|row| row.get("id").and_then(Value::as_i64) == Some(job_id))
            .cloned()
            .unwrap_or(Value::Null),
    );
    page_params_value(root, "job-queue-detail", extra)
}

/// Builds bounded, app-fragment-backed job-queue list page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_job_queue_list_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_job_queue_list_page_params_json`].
/// - `query_string`: Input consumed by [`crate::runtime::json_commands::dynamic_job_queue_list_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_job_queue_list_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_job_queue_list_page_params_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_job_queue_list_page_params_json(std::path::Path::new("."), std::path::Path::new("apps/dev_docs"), "page=1");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_job_queue_list_page_params_json(
    root: &Value,
    app_root: &Path,
    query_string: &str,
) -> Option<String> {
    const PAGE_SIZE: usize = 20;
    let requested_status = request_query_value(query_string, "status").unwrap_or_default();
    let status_filter = match requested_status.as_str() {
        "queued" | "running" | "succeeded" | "failed" | "cancelled" => requested_status,
        _ => String::new(),
    };
    let search_query = request_query_value(query_string, "q")
        .unwrap_or_default()
        .chars()
        .take(160)
        .collect::<String>();
    let requested_page = request_query_value(query_string, "page")
        .and_then(|value| value.parse::<usize>().ok())
        .filter(|value| *value > 0)
        .unwrap_or(1)
        .min(1_000_000);
    let jobs = bounded_state_array(root, "job_executions");
    let mut queued_count = 0_usize;
    let mut running_count = 0_usize;
    let mut succeeded_count = 0_usize;
    let mut failed_count = 0_usize;
    let mut cancelled_count = 0_usize;
    let matches_filters = |row: &Value| {
        let status = row
            .get("execution_status")
            .and_then(Value::as_str)
            .unwrap_or_default();
        (status_filter.is_empty() || status == status_filter)
            && (search_query.is_empty()
                || row
                    .get("job_id")
                    .map(value_to_text)
                    .is_some_and(|value| value.contains(&search_query))
                || row
                    .get("handler_id")
                    .map(value_to_text)
                    .is_some_and(|value| value.contains(&search_query)))
    };
    let mut matched_count = 0_usize;
    for row in jobs.iter().filter(|row| row.is_object()) {
        let status = row
            .get("execution_status")
            .and_then(Value::as_str)
            .unwrap_or_default();
        match status {
            "queued" => queued_count += 1,
            "running" => running_count += 1,
            "succeeded" => succeeded_count += 1,
            "failed" => failed_count += 1,
            "cancelled" => cancelled_count += 1,
            _ => {}
        }
        if matches_filters(row) {
            matched_count += 1;
        }
    }
    let supplied_page = root.get("_job_page");
    if let Some(metadata) = supplied_page {
        let count = |status: &str| {
            metadata
                .get("counts")?
                .get(status)?
                .as_u64()
                .and_then(|count| usize::try_from(count).ok())
        };
        queued_count = count("queued")?;
        running_count = count("running")?;
        succeeded_count = count("succeeded")?;
        failed_count = count("failed")?;
        cancelled_count = count("cancelled")?;
        matched_count = usize::try_from(metadata.get("matched_count")?.as_u64()?).ok()?;
    }
    let page_count = matched_count.div_ceil(PAGE_SIZE).max(1);
    let page = if let Some(metadata) = supplied_page {
        usize::try_from(metadata.get("page")?.as_u64()?).ok()?
    } else {
        requested_page.min(page_count)
    };
    let start = if supplied_page.is_some() {
        0
    } else {
        (page - 1) * PAGE_SIZE
    };
    let mut job_rows = String::new();
    for row in jobs
        .iter()
        .filter(|row| row.is_object() && matches_filters(row))
        .skip(start)
        .take(PAGE_SIZE)
    {
        let job_id = row.get("id").and_then(Value::as_i64).unwrap_or_default();
        let status = row
            .get("execution_status")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let action_buttons = if matches!(status, "queued" | "running") {
            let button = render_fragment_with_params(
                app_root,
                "templates/shared/fragments/ui_button.html",
                Map::from_iter([
                    (
                        "id".to_owned(),
                        Value::String(format!("job-cancel-{job_id}")),
                    ),
                    ("button_type".to_owned(), Value::String("submit".to_owned())),
                    (
                        "class_name".to_owned(),
                        Value::String("btn btn-danger btn-sm".to_owned()),
                    ),
                    ("attributes_html".to_owned(), Value::String(String::new())),
                    (
                        "content_html".to_owned(),
                        Value::String("Cancel".to_owned()),
                    ),
                ]),
            )?;
            render_fragment_with_params(
                app_root,
                "templates/queue/fragments/job_cancel_action.html",
                Map::from_iter([
                    ("job_id_path".to_owned(), Value::from(job_id)),
                    (
                        "job_cancel_button_ui_html".to_owned(),
                        Value::String(button),
                    ),
                ]),
            )?
        } else if matches!(status, "failed" | "cancelled") {
            let button = render_fragment_with_params(
                app_root,
                "templates/shared/fragments/ui_button.html",
                Map::from_iter([
                    (
                        "id".to_owned(),
                        Value::String(format!("job-retry-{job_id}")),
                    ),
                    ("button_type".to_owned(), Value::String("submit".to_owned())),
                    (
                        "class_name".to_owned(),
                        Value::String("btn btn-secondary btn-sm".to_owned()),
                    ),
                    ("attributes_html".to_owned(), Value::String(String::new())),
                    ("content_html".to_owned(), Value::String("Retry".to_owned())),
                ]),
            )?;
            render_fragment_with_params(
                app_root,
                "templates/queue/fragments/job_retry_action.html",
                Map::from_iter([
                    ("job_id_path".to_owned(), Value::from(job_id)),
                    ("job_retry_button_ui_html".to_owned(), Value::String(button)),
                ]),
            )?
        } else {
            String::new()
        };
        job_rows.push_str(&render_fragment_with_params(
            app_root,
            "templates/queue/fragments/job_row.html",
            Map::from_iter([
                ("job_id_path".to_owned(), Value::from(job_id)),
                ("job_id_text".to_owned(), Value::from(job_id)),
                (
                    "job_key".to_owned(),
                    Value::String(row.get("job_id").map(value_to_text).unwrap_or_default()),
                ),
                (
                    "handler_id".to_owned(),
                    Value::String(row.get("handler_id").map(value_to_text).unwrap_or_default()),
                ),
                ("job_status".to_owned(), Value::String(status.to_owned())),
                (
                    "attempt_count".to_owned(),
                    Value::from(
                        row.get("attempt_count")
                            .and_then(Value::as_i64)
                            .unwrap_or_default(),
                    ),
                ),
                (
                    "max_attempts".to_owned(),
                    Value::from(
                        row.get("max_attempts")
                            .and_then(Value::as_i64)
                            .unwrap_or_default(),
                    ),
                ),
                (
                    "created_at".to_owned(),
                    Value::String(row.get("created_at").map(value_to_text).unwrap_or_default()),
                ),
                ("action_buttons".to_owned(), Value::String(action_buttons)),
            ]),
        )?);
    }
    if job_rows.is_empty() {
        job_rows = render_fragment_with_params(
            app_root,
            "templates/queue/fragments/job_empty_row.html",
            Map::from_iter([(
                "message".to_owned(),
                Value::String("No jobs match the current filter.".to_owned()),
            )]),
        )?;
    }
    let mut pager = String::new();
    let status_query_html = if status_filter.is_empty() {
        String::new()
    } else {
        render_fragment_with_params(
            app_root,
            "templates/queue/fragments/job_query_suffix.html",
            Map::from_iter([
                ("query_name".to_owned(), Value::String("status".to_owned())),
                (
                    "query_value".to_owned(),
                    Value::String(url_encode_query_component(&status_filter)),
                ),
            ]),
        )?
        .trim()
        .to_owned()
    };
    let search_query_html = if search_query.is_empty() {
        String::new()
    } else {
        render_fragment_with_params(
            app_root,
            "templates/queue/fragments/job_query_suffix.html",
            Map::from_iter([
                ("query_name".to_owned(), Value::String("q".to_owned())),
                (
                    "query_value".to_owned(),
                    Value::String(url_encode_query_component(&search_query)),
                ),
            ]),
        )?
        .trim()
        .to_owned()
    };
    for (link_page, label, trailing_space) in [
        (
            page.checked_sub(1).filter(|value| *value > 0),
            "← Prev",
            page < page_count,
        ),
        ((page < page_count).then_some(page + 1), "Next →", false),
    ] {
        let Some(link_page) = link_page else {
            continue;
        };
        pager.push_str(&render_fragment_with_params(
            app_root,
            "templates/queue/fragments/job_pager_link.html",
            Map::from_iter([
                ("page_number".to_owned(), Value::from(link_page)),
                (
                    "status_query_html".to_owned(),
                    Value::String(status_query_html.clone()),
                ),
                (
                    "search_query_html".to_owned(),
                    Value::String(search_query_html.clone()),
                ),
                ("link_label".to_owned(), Value::String(label.to_owned())),
                (
                    "trailing_space".to_owned(),
                    Value::String(if trailing_space { " " } else { "" }.to_owned()),
                ),
            ]),
        )?);
    }
    compact(&Value::Object(Map::from_iter([
        ("queued_count".to_owned(), Value::from(queued_count)),
        ("running_count".to_owned(), Value::from(running_count)),
        ("succeeded_count".to_owned(), Value::from(succeeded_count)),
        ("failed_count".to_owned(), Value::from(failed_count)),
        ("cancelled_count".to_owned(), Value::from(cancelled_count)),
        ("page".to_owned(), Value::from(page)),
        ("page_count".to_owned(), Value::from(page_count)),
        ("status_filter".to_owned(), Value::String(status_filter)),
        ("search_query".to_owned(), Value::String(search_query)),
        ("job_rows".to_owned(), Value::String(job_rows)),
        ("pager".to_owned(), Value::String(pager)),
    ])))
}

/// Renders the declared service visual fragment with escaped data.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_render_service_visual_html`].
/// - `service`: Input consumed by [`crate::runtime::json_commands::dynamic_render_service_visual_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_render_service_visual_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_render_service_visual_html(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_render_service_visual_html(app_root: &Path, service: &Value) -> Option<String> {
    let name = value_to_text(service.get("name").unwrap_or(&Value::Null));
    let image = service
        .get("image_url")
        .map(value_to_text)
        .unwrap_or_default();
    let color = service
        .get("primary_color")
        .map(value_to_text)
        .filter(|value| !value.is_empty());
    service_visual_html(app_root, Some(&image), &name, color.as_deref())
}

/// Renders a workspace panel.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_workspace_panel_html_business_logic_local`].
/// - `panel_class`: Input consumed by [`crate::runtime::json_commands::render_workspace_panel_html_business_logic_local`].
/// - `header_class`: Input consumed by [`crate::runtime::json_commands::render_workspace_panel_html_business_logic_local`].
/// - `title_text`: Input consumed by [`crate::runtime::json_commands::render_workspace_panel_html_business_logic_local`].
/// - `header_actions_html`: Input consumed by [`crate::runtime::json_commands::render_workspace_panel_html_business_logic_local`].
/// - `body_html`: Input consumed by [`crate::runtime::json_commands::render_workspace_panel_html_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_workspace_panel_html_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_workspace_panel_html_business_logic_local(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_workspace_panel_html_business_logic_local(
    app_root: &Path,
    panel_class: &str,
    header_class: &str,
    title_text: &str,
    header_actions_html: &str,
    body_html: &str,
) -> Option<String> {
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/workspace_panel.html",
        Map::from_iter([
            (
                "panel_class".to_owned(),
                Value::String(panel_class.to_owned()),
            ),
            (
                "header_class".to_owned(),
                Value::String(header_class.to_owned()),
            ),
            (
                "title_text".to_owned(),
                Value::String(title_text.to_owned()),
            ),
            (
                "header_actions_html".to_owned(),
                Value::String(header_actions_html.to_owned()),
            ),
            ("body_html".to_owned(), Value::String(body_html.to_owned())),
        ]),
    )
}

/// Renders two workspace panels in a bounded grid.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_workspace_split_grid_html_business_logic_local`].
/// - `grid_class`: Input consumed by [`crate::runtime::json_commands::render_workspace_split_grid_html_business_logic_local`].
/// - `left_html`: Input consumed by [`crate::runtime::json_commands::render_workspace_split_grid_html_business_logic_local`].
/// - `right_html`: Input consumed by [`crate::runtime::json_commands::render_workspace_split_grid_html_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_workspace_split_grid_html_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_workspace_split_grid_html_business_logic_local(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_workspace_split_grid_html_business_logic_local(
    app_root: &Path,
    grid_class: &str,
    left_html: &str,
    right_html: &str,
) -> Option<String> {
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/workspace_split_grid.html",
        Map::from_iter([
            (
                "grid_class".to_owned(),
                Value::String(grid_class.to_owned()),
            ),
            ("left_html".to_owned(), Value::String(left_html.to_owned())),
            (
                "right_html".to_owned(),
                Value::String(right_html.to_owned()),
            ),
        ]),
    )
}

/// Renders a workspace dialog with app-owned inner fragments.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_workspace_dialog_html_business_logic_local`].
/// - `dialog_id`: Input consumed by [`crate::runtime::json_commands::render_workspace_dialog_html_business_logic_local`].
/// - `dialog_class`: Input consumed by [`crate::runtime::json_commands::render_workspace_dialog_html_business_logic_local`].
/// - `shell_class`: Input consumed by [`crate::runtime::json_commands::render_workspace_dialog_html_business_logic_local`].
/// - `copy_class`: Input consumed by [`crate::runtime::json_commands::render_workspace_dialog_html_business_logic_local`].
/// - `copy_html`: Input consumed by [`crate::runtime::json_commands::render_workspace_dialog_html_business_logic_local`].
/// - `actions_class`: Input consumed by [`crate::runtime::json_commands::render_workspace_dialog_html_business_logic_local`].
/// - `actions_html`: Input consumed by [`crate::runtime::json_commands::render_workspace_dialog_html_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_workspace_dialog_html_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_workspace_dialog_html_business_logic_local(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_workspace_dialog_html_business_logic_local(
    app_root: &Path,
    dialog_id: &str,
    dialog_class: &str,
    shell_class: &str,
    copy_class: &str,
    copy_html: &str,
    actions_class: &str,
    actions_html: &str,
) -> Option<String> {
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/workspace_dialog.html",
        Map::from_iter([
            ("dialog_id".to_owned(), Value::String(dialog_id.to_owned())),
            (
                "dialog_class".to_owned(),
                Value::String(dialog_class.to_owned()),
            ),
            (
                "shell_class".to_owned(),
                Value::String(shell_class.to_owned()),
            ),
            (
                "copy_class".to_owned(),
                Value::String(copy_class.to_owned()),
            ),
            ("copy_html".to_owned(), Value::String(copy_html.to_owned())),
            (
                "actions_class".to_owned(),
                Value::String(actions_class.to_owned()),
            ),
            (
                "actions_html".to_owned(),
                Value::String(actions_html.to_owned()),
            ),
        ]),
    )
}

/// Returns the calendar color contrast text.
///
/// # Parameters
///
/// - `background`: Input consumed by [`crate::runtime::json_commands::contrast_text_color_business_logic_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::contrast_text_color_business_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::contrast_text_color_business_logic_local(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn contrast_text_color_business_logic_local(background: &str) -> &'static str {
    let hex = background.trim_start_matches('#');
    let value = u32::from_str_radix(hex, 16).unwrap_or(0xffffff);
    let red = (value >> 16) & 0xff;
    let green = (value >> 8) & 0xff;
    let blue = value & 0xff;
    if red * 299 + green * 587 + blue * 114 >= 128000 {
        "#111827"
    } else {
        "#ffffff"
    }
}

/// Returns service-name initials, treating parentheses and whitespace as word separators.
///
/// # Parameters
///
/// - `name`: Input consumed by [`crate::runtime::json_commands::dynamic_service_abbreviation`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::dynamic_service_abbreviation`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_service_abbreviation`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_service_abbreviation("name");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_service_abbreviation(name: &str) -> String {
    name.split(|character: char| character.is_whitespace() || matches!(character, '(' | ')'))
        .filter_map(|word| word.chars().next())
        .collect::<String>()
        .to_uppercase()
}

/// Returns a safe service badge color.
///
/// # Parameters
///
/// - `primary_color`: Input consumed by [`crate::runtime::json_commands::dynamic_service_badge_color`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::dynamic_service_badge_color`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_service_badge_color`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_service_badge_color(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_service_badge_color(primary_color: &str) -> &'static str {
    let color = primary_color.trim();
    if color.len() == 7
        && color.starts_with('#')
        && color[1..].bytes().all(|byte| byte.is_ascii_hexdigit())
    {
        "var(--service-primary-color)"
    } else {
        "#475569"
    }
}

/// Initializes an incremental SHA-256 context.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::sha256_init_logic_local`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::sha256_init_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::sha256_init_logic_local();
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn sha256_init_logic_local() -> Sha256 {
    Sha256::new()
}

/// Updates an incremental SHA-256 context.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::runtime::json_commands::sha256_update_logic_local`].
/// - `bytes`: Input consumed by [`crate::runtime::json_commands::sha256_update_logic_local`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::sha256_update_logic_local`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::sha256_update_logic_local(todo!(), b"");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn sha256_update_logic_local(context: &mut Sha256, bytes: &[u8]) {
    context.update(bytes);
}

/// Finalizes an incremental SHA-256 context.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::runtime::json_commands::sha256_final_logic_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::sha256_final_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::sha256_final_logic_local(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn sha256_final_logic_local(context: Sha256) -> [u8; 32] {
    context.finalize().into()
}

/// Computes a one-block SHA-256 digest for the transform contract.
///
/// # Parameters
///
/// - `block`: Input consumed by [`crate::runtime::json_commands::sha256_transform_logic_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::sha256_transform_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::sha256_transform_logic_local(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn sha256_transform_logic_local(block: &[u8]) -> [u8; 32] {
    Sha256::digest(block).into()
}

/// Rotates a 32-bit word right by a masked count.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::sha256_rotr_logic_local`].
/// - `count`: Input consumed by [`crate::runtime::json_commands::sha256_rotr_logic_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::sha256_rotr_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::sha256_rotr_logic_local("value", 0);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn sha256_rotr_logic_local(value: u32, count: u32) -> u32 {
    value.rotate_right(count & 31)
}

/// Returns a lowercase SHA-256 hexadecimal digest.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::sha256_hex`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::sha256_hex`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::sha256_hex("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn sha256_hex(value: &[u8]) -> String {
    pharos_runtime_core::support::sha256_hex(value)
}

/// Returns the weekday abbreviation for a validated ISO date.
///
/// # Parameters
///
/// - `year`: Input consumed by [`crate::runtime::json_commands::day_abbrev_for_ymd_business_logic_local`].
/// - `month`: Input consumed by [`crate::runtime::json_commands::day_abbrev_for_ymd_business_logic_local`].
/// - `day`: Input consumed by [`crate::runtime::json_commands::day_abbrev_for_ymd_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::day_abbrev_for_ymd_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::day_abbrev_for_ymd_business_logic_local(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn day_abbrev_for_ymd_business_logic_local(
    year: i32,
    month: u32,
    day: u32,
) -> Option<&'static str> {
    let days = days_from_civil(year, month, day)?;
    Some(["Thu", "Fri", "Sat", "Sun", "Mon", "Tue", "Wed"][days.rem_euclid(7) as usize])
}

/// Formats a validated time range.
fn formatted_clock_time_business_logic_local(time_text: &str) -> String {
    let Some((hour_text, minute_text)) = time_text.split_once(':') else {
        return time_text.to_owned();
    };
    let Some(hour) = hour_text.parse::<u32>().ok() else {
        return time_text.to_owned();
    };
    let Some(minute) = minute_text.parse::<u32>().ok() else {
        return time_text.to_owned();
    };
    if hour > 23 || minute > 59 {
        return time_text.to_owned();
    }
    let suffix = if hour < 12 { "AM" } else { "PM" };
    let display_hour = match hour % 12 {
        0 => 12,
        value => value,
    };
    format!("{display_hour}:{minute:02} {suffix}")
}

fn appointment_time_plus_minutes(time_text: &str, duration_minutes: i64) -> Option<String> {
    let (hour_text, minute_text) = time_text.split_once(':')?;
    let hour = hour_text.parse::<i64>().ok()?;
    let minute = minute_text.parse::<i64>().ok()?;
    if !(0..=23).contains(&hour) || !(0..=59).contains(&minute) || duration_minutes <= 0 {
        return None;
    }
    let total_minutes = hour
        .saturating_mul(60)
        .saturating_add(minute)
        .saturating_add(duration_minutes);
    let day_minutes = 24 * 60;
    let normalized_minutes = total_minutes.rem_euclid(day_minutes);
    Some(format!(
        "{:02}:{:02}",
        normalized_minutes / 60,
        normalized_minutes % 60
    ))
}

/// Performs formatted time range business logic local.
///
/// # Parameters
///
/// - `start_time`: Input consumed by [`crate::runtime::json_commands::formatted_time_range_business_logic_local`].
/// - `end_time`: Input consumed by [`crate::runtime::json_commands::formatted_time_range_business_logic_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::formatted_time_range_business_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::formatted_time_range_business_logic_local(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn formatted_time_range_business_logic_local(start_time: &str, end_time: &str) -> String {
    if start_time.is_empty() {
        return formatted_clock_time_business_logic_local(end_time);
    }
    if end_time.is_empty() {
        return formatted_clock_time_business_logic_local(start_time);
    }
    format!(
        "{}–{}",
        formatted_clock_time_business_logic_local(start_time),
        formatted_clock_time_business_logic_local(end_time)
    )
}

/// Performs days from civil.
fn days_from_civil(year: i32, month: u32, day: u32) -> Option<i64> {
    if !(1..=12).contains(&month)
        || day == 0
        || day > days_in_month_business_logic_local(year, month)
    {
        return None;
    }
    let y = year - i32::from(month <= 2);
    let era = i64::from(y).div_euclid(400);
    let yoe = i64::from(y).rem_euclid(400);
    let mp = i64::from(month) + if month > 2 { -3 } else { 9 };
    let doy = (153 * mp + 2) / 5 + i64::from(day) - 1;
    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
    Some(era * 146097 + doe - 719468)
}

/// Returns the number of days in a Gregorian month.
///
/// # Parameters
///
/// - `year`: Input consumed by [`crate::runtime::json_commands::days_in_month_business_logic_local`].
/// - `month`: Input consumed by [`crate::runtime::json_commands::days_in_month_business_logic_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::days_in_month_business_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::days_in_month_business_logic_local(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn days_in_month_business_logic_local(year: i32, month: u32) -> u32 {
    match month {
        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
        4 | 6 | 9 | 11 => 30,
        2 if year.rem_euclid(4) == 0
            && (year.rem_euclid(100) != 0 || year.rem_euclid(400) == 0) =>
        {
            29
        }
        2 => 28,
        _ => 0,
    }
}

/// Finds the named month.
///
/// # Parameters
///
/// - `month`: Input consumed by [`crate::runtime::json_commands::month_name_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::month_name_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::month_name_business_logic_local(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn month_name_business_logic_local(month: u32) -> Option<&'static str> {
    [
        "",
        "January",
        "February",
        "March",
        "April",
        "May",
        "June",
        "July",
        "August",
        "September",
        "October",
        "November",
        "December",
    ]
    .get(month as usize)
    .copied()
    .filter(|value| !value.is_empty())
}

/// Shifts a year/month pair by a bounded number of months.
///
/// # Parameters
///
/// - `year`: Input consumed by [`crate::runtime::json_commands::month_shift_business_logic_local`].
/// - `month`: Input consumed by [`crate::runtime::json_commands::month_shift_business_logic_local`].
/// - `shift`: Input consumed by [`crate::runtime::json_commands::month_shift_business_logic_local`].
/// - `u32`: Input consumed by [`crate::runtime::json_commands::month_shift_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::month_shift_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::month_shift_business_logic_local(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn month_shift_business_logic_local(year: i32, month: u32, shift: i32) -> Option<(i32, u32)> {
    if !(1..=12).contains(&month) {
        return None;
    }
    let index = year
        .checked_mul(12)?
        .checked_add(month as i32 - 1)?
        .checked_add(shift)?;
    Some((index.div_euclid(12), index.rem_euclid(12) as u32 + 1))
}

/// Appends an ISO date to a bounded string buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::append_date_business_logic_local`].
/// - `year`: Input consumed by [`crate::runtime::json_commands::append_date_business_logic_local`].
/// - `month`: Input consumed by [`crate::runtime::json_commands::append_date_business_logic_local`].
/// - `day`: Input consumed by [`crate::runtime::json_commands::append_date_business_logic_local`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::append_date_business_logic_local`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::append_date_business_logic_local(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn append_date_business_logic_local(
    output: &mut String,
    year: i32,
    month: u32,
    day: u32,
) -> bool {
    if days_from_civil(year, month, day).is_none() {
        return false;
    }
    let text = format!("{year:04}-{month:02}-{day:02}");
    if output.len().saturating_add(text.len()) > MAX_TEXT_BYTES {
        return false;
    }
    output.push_str(&text);
    true
}

/// Returns the Monday-based index of a weekday name.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::weekday_monday_index_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::weekday_monday_index_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::weekday_monday_index_business_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::weekday_monday_index_business_logic_local("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn weekday_monday_index_business_logic_local(value: &str) -> Option<u8> {
    [
        "monday",
        "tuesday",
        "wednesday",
        "thursday",
        "friday",
        "saturday",
        "sunday",
    ]
    .iter()
    .position(|name| name.eq_ignore_ascii_case(value))
    .map(|index| index as u8)
}

/// Finds a technician row scoped to one business.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::find_technician_for_business_logic_local`].
/// - `technician_id`: Input consumed by [`crate::runtime::json_commands::find_technician_for_business_logic_local`].
/// - `business_id`: Input consumed by [`crate::runtime::json_commands::find_technician_for_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::find_technician_for_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::find_technician_for_business_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::find_technician_for_business_logic_local(std::path::Path::new("."), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn find_technician_for_business_logic_local(
    root: &Value,
    technician_id: i64,
    business_id: i64,
) -> Option<Value> {
    bounded_state_array(root, "technicians")
        .iter()
        .find(|row| {
            row.get("id").and_then(Value::as_i64) == Some(technician_id)
                && row.get("business_id").and_then(Value::as_i64) == Some(business_id)
        })
        .cloned()
}

/// Finds a user row by identifier.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::find_user_by_id_business_logic_local`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::find_user_by_id_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::find_user_by_id_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::find_user_by_id_business_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::find_user_by_id_business_logic_local(std::path::Path::new("."), 1);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn find_user_by_id_business_logic_local(root: &Value, user_id: i64) -> Option<Value> {
    bounded_state_array(root, "users")
        .iter()
        .find(|row| row.get("id").and_then(Value::as_i64) == Some(user_id))
        .cloned()
}

/// Returns whether a signup account type is allowed by the closed set.
///
/// # Parameters
///
/// - `account_type`: Input consumed by [`crate::runtime::json_commands::dynamic_signup_account_type_allowed`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::dynamic_signup_account_type_allowed`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_signup_account_type_allowed(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_signup_account_type_allowed(account_type: &str) -> bool {
    matches!(
        account_type,
        "personal" | "business" | "technician" | "admin"
    )
}

/// Counts slash-separated route segments.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::count_segments`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::count_segments`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::count_segments`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::count_segments(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn count_segments(path: &str) -> usize {
    path.split('/')
        .filter(|segment| !segment.is_empty())
        .count()
}

/// Returns one slash-separated segment by index.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::get_segment`].
/// - `index`: Input consumed by [`crate::runtime::json_commands::get_segment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::get_segment`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::get_segment`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::get_segment(std::path::Path::new("fixture.json"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn get_segment(path: &str, index: usize) -> Option<String> {
    path.split('/')
        .filter(|segment| !segment.is_empty())
        .nth(index)
        .map(ToOwned::to_owned)
}

/// Returns one segment's byte length.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::segment_length`].
/// - `index`: Input consumed by [`crate::runtime::json_commands::segment_length`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::segment_length`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::segment_length(std::path::Path::new("fixture.json"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn segment_length(path: &str, index: usize) -> usize {
    get_segment(path, index)
        .map(|value| value.len())
        .unwrap_or(0)
}

/// Returns one query parameter value.
///
/// # Parameters
///
/// - `query`: Input consumed by [`crate::runtime::json_commands::dynamic_query_value`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::dynamic_query_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_query_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_query_value("page=1", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_query_value(query: &str, key: &str) -> Option<String> {
    request_query_value(query, key)
}

/// Returns an array-valued runtime state section.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::state_array_runtime_local`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::state_array_runtime_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::state_array_runtime_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::state_array_runtime_local(std::path::Path::new("."), "items");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn state_array_runtime_local(root: &Value, section: &str) -> Vec<Value> {
    bounded_state_array(root, section).to_vec()
}

/// Appends bounded runtime text.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_append_runtime_local`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::text_append_runtime_local`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::text_append_runtime_local`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_append_runtime_local(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_append_runtime_local(output: &mut String, value: &str) -> bool {
    text_buffer_append_format(output, value)
}

/// Escapes runtime text for HTML.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::html_escaped`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::html_escaped`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::html_escaped("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn html_escaped(value: &str) -> String {
    html_escape_text(value)
}

/// Adds an escaped string to a page parameter map.
///
/// # Parameters
///
/// - `map`: Input consumed by [`crate::runtime::json_commands::runtime_page_params_add_string`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::runtime_page_params_add_string`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::runtime_page_params_add_string`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::runtime_page_params_add_string`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_page_params_add_string(todo!(), "key", "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_page_params_add_string(
    map: &mut Map<String, Value>,
    key: &str,
    value: &str,
) -> bool {
    if key.is_empty() {
        return false;
    }
    map.insert(key.to_owned(), Value::String(value.to_owned()));
    true
}

/// Adds an escaped string to a page parameter map.
///
/// # Parameters
///
/// - `map`: Input consumed by [`crate::runtime::json_commands::runtime_page_params_add_escaped_string`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::runtime_page_params_add_escaped_string`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::runtime_page_params_add_escaped_string`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::runtime_page_params_add_escaped_string`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_page_params_add_escaped_string(todo!(), "key", "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_page_params_add_escaped_string(
    map: &mut Map<String, Value>,
    key: &str,
    value: &str,
) -> bool {
    runtime_page_params_add_string(map, key, &html_escape_text(value))
}

/// Serializes a page parameter map.
///
/// # Parameters
///
/// - `map`: Input consumed by [`crate::runtime::json_commands::runtime_page_params_write`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::runtime_page_params_write`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_page_params_write(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_page_params_write(map: &Map<String, Value>) -> Option<String> {
    compact(&Value::Object(map.clone()))
}

/// Returns a validated management path segment.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::runtime_manage_path_segment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::runtime_manage_path_segment`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::runtime_manage_path_segment`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_manage_path_segment("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_manage_path_segment(value: &str) -> Option<String> {
    (!value.is_empty()
        && value.len() <= 128
        && value
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_')))
    .then(|| value.to_owned())
}

/// Ensures a runtime text buffer has bounded capacity.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::runtime_text_buffer_reserve`].
/// - `additional`: Input consumed by [`crate::runtime::json_commands::runtime_text_buffer_reserve`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::runtime_text_buffer_reserve`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_text_buffer_reserve(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_text_buffer_reserve(output: &mut String, additional: usize) -> bool {
    output
        .len()
        .checked_add(additional)
        .is_some_and(|length| length <= MAX_TEXT_BYTES)
        && output.try_reserve(additional).is_ok()
}

/// Checks whether a UI attribute name is safe.
///
/// # Parameters
///
/// - `name`: Input consumed by [`crate::runtime::json_commands::runtime_ui_attribute_is_valid`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::runtime_ui_attribute_is_valid`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::runtime_ui_attribute_is_valid`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_ui_attribute_is_valid("name");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_ui_attribute_is_valid(name: &str) -> bool {
    !name.is_empty()
        && name
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_')
}

/// Compares two strings exactly.
///
/// # Parameters
///
/// - `left`: Input consumed by [`crate::runtime::json_commands::streq`].
/// - `right`: Input consumed by [`crate::runtime::json_commands::streq`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::streq`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::streq(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn streq(left: &str, right: &str) -> bool {
    left == right
}

/// Appends formatted text to a runtime buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_append_format_runtime_local`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::text_append_format_runtime_local`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::text_append_format_runtime_local`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_append_format_runtime_local(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_append_format_runtime_local(output: &mut String, value: &str) -> bool {
    text_buffer_append_format(output, value)
}

/// Normalizes an email body to CRLF line endings.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::email_body_crlf_dup`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::email_body_crlf_dup`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_body_crlf_dup("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_body_crlf_dup(value: &str) -> String {
    value
        .replace("\r\n", "\n")
        .replace('\r', "\n")
        .replace('\n', "\r\n")
}

/// Returns a stable RFC-style date header value.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::email_date_header_dup`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_date_header_dup();
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_date_header_dup() -> String {
    format!(
        "Date: {}",
        super::dynamic::now_unix_epoch_text_logic_local()
    )
}

/// Resolves one email configuration value from app and runtime configuration.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::email_effective_value`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::email_effective_value`].
/// - `prefix`: Input consumed by [`crate::runtime::json_commands::email_effective_value`].
/// - `suffix`: Input consumed by [`crate::runtime::json_commands::email_effective_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::email_effective_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_effective_value(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_effective_value(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    prefix: &str,
    suffix: &str,
) -> Option<String> {
    let key = if prefix.is_empty() {
        suffix.to_owned()
    } else {
        format!("{prefix}_{suffix}")
    };
    config::dynamic_config_effective_value(app_root, runtime_conf_path, &key)
}

/// Looks up one bounded email template variable.
///
/// # Parameters
///
/// - `vars`: Input consumed by [`crate::runtime::json_commands::email_template_lookup_var`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::email_template_lookup_var`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::email_template_lookup_var`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_template_lookup_var(todo!(), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_template_lookup_var(vars: &Value, key: &str) -> Option<String> {
    vars.get(key)
        .map(value_to_text)
        .filter(|value| value.len() <= MAX_TEXT_BYTES)
}

/// Appends one YAML block line after removing the declared indentation.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::json_commands::email_yaml_append_block_line`].
/// - `line`: Input consumed by [`crate::runtime::json_commands::email_yaml_append_block_line`].
/// - `indent_to_strip`: Input consumed by [`crate::runtime::json_commands::email_yaml_append_block_line`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::email_yaml_append_block_line`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_yaml_append_block_line(&mut [], todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_yaml_append_block_line(
    buffer: &mut String,
    line: &str,
    indent_to_strip: usize,
) -> bool {
    let stripped = line.get(line.len().min(indent_to_strip)..).unwrap_or("");
    if buffer.len().saturating_add(stripped.len() + 2) > MAX_TEXT_BYTES {
        return false;
    }
    buffer.push_str(stripped);
    buffer.push('\n');
    true
}

/// Stores a completed YAML block in a mutable template object.
///
/// # Parameters
///
/// - `parsed`: Input consumed by [`crate::runtime::json_commands::email_yaml_finalize_block`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::email_yaml_finalize_block`].
/// - `buffer`: Input consumed by [`crate::runtime::json_commands::email_yaml_finalize_block`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::email_yaml_finalize_block`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_yaml_finalize_block(todo!(), "key", &mut []);
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_yaml_finalize_block(parsed: &mut Map<String, Value>, key: &str, buffer: &str) -> bool {
    if key.is_empty() {
        return false;
    }
    parsed.insert(
        key.to_owned(),
        Value::String(buffer.trim_end_matches('\n').to_owned()),
    );
    true
}

/// Stores a scalar YAML field in a mutable template object.
///
/// # Parameters
///
/// - `parsed`: Input consumed by [`crate::runtime::json_commands::email_yaml_store_field`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::email_yaml_store_field`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::email_yaml_store_field`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::email_yaml_store_field`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_yaml_store_field(todo!(), "key", "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_yaml_store_field(parsed: &mut Map<String, Value>, key: &str, value: &str) -> bool {
    if key.is_empty() || value.len() > MAX_TEXT_BYTES {
        return false;
    }
    parsed.insert(
        key.to_owned(),
        Value::String(value.trim().trim_matches(['"', '\'']).to_owned()),
    );
    true
}

/// Clears a parsed email YAML template.
///
/// # Parameters
///
/// - `parsed`: Input consumed by [`crate::runtime::json_commands::email_yaml_template_clear`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::email_yaml_template_clear`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_yaml_template_clear(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_yaml_template_clear(parsed: &mut Map<String, Value>) {
    parsed.clear();
}

/// Resolves a namespaced email configuration key.
///
/// # Parameters
///
/// - `prefix`: Input consumed by [`crate::runtime::json_commands::email_config_key_dup`].
/// - `suffix`: Input consumed by [`crate::runtime::json_commands::email_config_key_dup`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::email_config_key_dup`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_config_key_dup(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_config_key_dup(prefix: &str, suffix: &str) -> Option<String> {
    (!suffix.is_empty()).then(|| {
        if prefix.is_empty() {
            suffix.to_owned()
        } else {
            format!("{prefix}_{suffix}")
        }
    })
}

/// Rejects CRLF header injection in email field values.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::email_has_header_breaks`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::email_has_header_breaks`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_has_header_breaks("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_has_header_breaks(value: &str) -> bool {
    value.contains('\r') || value.contains('\n')
}

/// Removes one layer of matching email-template quotes.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::email_template_unquote_dup`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::email_template_unquote_dup`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::email_template_unquote_dup("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn email_template_unquote_dup(value: &str) -> String {
    let value = value.trim();
    if value.len() >= 2
        && ((value.starts_with('"') && value.ends_with('"'))
            || (value.starts_with('\'') && value.ends_with('\'')))
    {
        value[1..value.len() - 1].to_owned()
    } else {
        value.to_owned()
    }
}

/// Releases a parsed URL value by normal Rust ownership rules.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::free_parsed_http_url_logic_local`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::free_parsed_http_url_logic_local`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::free_parsed_http_url_logic_local("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn free_parsed_http_url_logic_local(value: Option<(String, String, Option<u16>)>) {
    drop(value);
}

/// Renders an app-owned shared fragment from a parameter document.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_shared_asset_fragment_from_doc`].
/// - `relative_path`: Input consumed by [`crate::runtime::json_commands::render_shared_asset_fragment_from_doc`].
/// - `params`: Input consumed by [`crate::runtime::json_commands::render_shared_asset_fragment_from_doc`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_shared_asset_fragment_from_doc`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_shared_asset_fragment_from_doc(std::path::Path::new("apps/dev_docs"), "page", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_shared_asset_fragment_from_doc(
    app_root: &Path,
    relative_path: &str,
    params: &Value,
) -> Option<String> {
    generated::render_generated_admin_fragment_from_value_runtime(
        app_root,
        relative_path,
        params.as_object()?,
    )
}

/// Builds profile page parameters from a state root.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::profile_render_page_params_json`].
/// - `user_id`: Input consumed by [`crate::runtime::json_commands::profile_render_page_params_json`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::profile_render_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::profile_render_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::profile_render_page_params_json(std::path::Path::new("."), 1, std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn profile_render_page_params_json(
    root: &Value,
    user_id: i64,
    app_root: &Path,
) -> Option<String> {
    dynamic_profile_page_params_json(root, user_id, app_root)
}

/// Tests whether a path ends with a validated suffix.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::runtime_path_has_suffix`].
/// - `suffix`: Input consumed by [`crate::runtime::json_commands::runtime_path_has_suffix`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::runtime_path_has_suffix`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_path_has_suffix(std::path::Path::new("fixture.json"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_path_has_suffix(path: &Path, suffix: &str) -> bool {
    !suffix.is_empty() && path.to_string_lossy().ends_with(suffix)
}

/// Renders availability rows from persisted business state.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::dynamic_build_business_admin_availability_rows_html`].
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_build_business_admin_availability_rows_html`].
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::dynamic_build_business_admin_availability_rows_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_build_business_admin_availability_rows_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_build_business_admin_availability_rows_html(std::path::Path::new("."), "demo", std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_build_business_admin_availability_rows_html(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    dynamic_render_business_admin_availability_rows_html(root, business_slug, app_root)
}

/// Finds a Google Calendar connection scoped to a business.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::state_find_google_calendar_connection_for_business_logic_local`].
/// - `business_id`: Input consumed by [`crate::runtime::json_commands::state_find_google_calendar_connection_for_business_logic_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::state_find_google_calendar_connection_for_business_logic_local`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::state_find_google_calendar_connection_for_business_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::state_find_google_calendar_connection_for_business_logic_local(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn state_find_google_calendar_connection_for_business_logic_local(
    root: &Value,
    business_id: i64,
) -> Option<Value> {
    bounded_state_array(root, "calendar_connections")
        .iter()
        .find(|row| {
            row.get("business_id").and_then(Value::as_i64) == Some(business_id)
                && row
                    .get("provider")
                    .and_then(Value::as_str)
                    .is_some_and(|value| value.eq_ignore_ascii_case("google"))
        })
        .cloned()
}

/// Finds one payment provider account row for a business and provider.
pub fn state_find_payment_provider_account_for_business_logic_local(
    root: &Value,
    business_id: i64,
    provider: &str,
) -> Option<Value> {
    if provider.is_empty() {
        return None;
    }
    bounded_state_array(root, "payment_provider_accounts")
        .iter()
        .find(|row| {
            row.get("owner_resource_type")
                .and_then(Value::as_str)
                .unwrap_or("business")
                == "business"
                && row.get("owner_resource_id").and_then(Value::as_i64) == Some(business_id)
                && row
                    .get("provider_id")
                    .or_else(|| row.get("provider"))
                    .and_then(Value::as_str)
                    .is_some_and(|value| value.eq_ignore_ascii_case(provider))
        })
        .cloned()
}

fn payment_provider_display_label(provider_id: &str) -> String {
    if provider_id.eq_ignore_ascii_case("stripe") {
        return "Stripe".to_owned();
    }
    let normalized = provider_id.replace(['_', '-'], " ");
    let mut chars = normalized.chars();
    let Some(first) = chars.next() else {
        return "Provider".to_owned();
    };
    format!("{}{}", first.to_uppercase(), chars.as_str())
}

fn business_payment_provider_ui_config(app_root: &Path) -> (String, String) {
    let manifest = read_json_or_yaml_file(&app_root.join("pharos.app.json"))
        .or_else(|| read_json_or_yaml_file(&app_root.join("pharos.app.yml")));
    let provider_id = manifest
        .as_ref()
        .and_then(|root| root.get("payments"))
        .and_then(|payments| payments.get("provider_management"))
        .and_then(|management| management.get("supported_providers"))
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .find_map(|provider| {
            provider
                .get("provider")
                .and_then(Value::as_str)
                .or_else(|| provider.as_str())
        })
        .filter(|provider| {
            !provider.is_empty()
                && provider.len() <= 64
                && provider
                    .bytes()
                    .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-'))
        })
        .unwrap_or("stripe")
        .to_owned();
    let label = payment_provider_display_label(&provider_id);
    (provider_id, label)
}

fn business_payment_provider_paths(
    business_slug: &str,
    payment_provider_id: &str,
) -> (String, String, String) {
    (
        format!("/businesses/{business_slug}/payment-providers/{payment_provider_id}/connect/"),
        format!("/businesses/{business_slug}/payment-providers/{payment_provider_id}/refresh/"),
        format!("/businesses/{business_slug}/payment-providers/{payment_provider_id}/disconnect/"),
    )
}

fn business_payment_provider_status(
    root: &Value,
    business_id: i64,
    payment_provider_id: &str,
    payment_provider_label: &str,
) -> (String, String) {
    let payment_provider_account = state_find_payment_provider_account_for_business_logic_local(
        root,
        business_id,
        payment_provider_id,
    );
    let status_label = payment_provider_account
        .as_ref()
        .and_then(|row| row.get("connection_state").or_else(|| row.get("status")))
        .and_then(Value::as_str)
        .map(|status| match status {
            "connected" => "Connected",
            "connect_requested" | "redirect_pending" | "callback_received" => "Onboarding started",
            "verification_pending" => "Verification pending",
            "restricted" => "Connected with restrictions",
            "revoked_externally" => "Revoked externally",
            "failed" => "Failed",
            _ => "Disconnected",
        })
        .unwrap_or("Disconnected")
        .to_owned();
    let status_detail = payment_provider_account
        .as_ref()
        .and_then(|row| {
            row.get("status_reason_detail")
                .or_else(|| row.get("last_error_message"))
        })
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .map(ToOwned::to_owned)
        .unwrap_or_else(|| match status_label.as_str() {
            "Connected" => format!(
                "{payment_provider_label} account linked and available for business payments."
            ),
            "Onboarding started" => format!(
                "{payment_provider_label} onboarding is in progress and waiting for callback completion."
            ),
            "Verification pending" => {
                format!(
                    "{payment_provider_label} returned successfully, but the account still needs authoritative capability verification."
                )
            }
            "Connected with restrictions" => {
                format!(
                    "{payment_provider_label} account linked but still restricted for one or more capabilities."
                )
            }
            "Revoked externally" => {
                format!(
                    "The provider reported that the {payment_provider_label} connection is no longer valid."
                )
            }
            "Failed" => format!(
                "The last {payment_provider_label} operation failed. Refresh or reconnect to retry."
            ),
            _ => "No business payment provider is connected yet.".to_owned(),
        });
    (status_label, status_detail)
}

fn payment_provider_action_button_html(
    app_root: &Path,
    id: &str,
    label: &str,
    class_name: &str,
) -> Option<String> {
    render_fragment_with_params(
        app_root,
        "templates/shared/fragments/ui_button.html",
        Map::from_iter([
            ("id".to_owned(), Value::String(id.to_owned())),
            ("button_type".to_owned(), Value::String("submit".to_owned())),
            (
                "class_name".to_owned(),
                Value::String(class_name.to_owned()),
            ),
            ("attributes_html".to_owned(), Value::String(String::new())),
            ("content_html".to_owned(), Value::String(label.to_owned())),
        ]),
    )
}

/// Builds payment provider setup page parameters for one business.
///
/// # Parameters
///
/// - `root`: Loaded UCAL dynamic runtime state.
/// - `business_slug`: Route-owned business slug.
/// - `app_root`: UCAL app artifact root used for declared fragments.
///
/// # Returns
///
/// Returns JSON template parameters when the business and declared fragments can
/// be resolved. The values intentionally include only paths, labels, and
/// rendered button fragments; provider secrets and OAuth credentials are never
/// included in the page payload.
pub fn dynamic_payment_provider_setup_page_params_from_root_json(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    let business = bounded_state_array(root, "businesses")
        .iter()
        .find(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))?;
    let business_id = business.get("id").and_then(Value::as_i64)?;
    let business_name = business.get("name").map(value_to_text).unwrap_or_default();
    let (payment_provider_id, payment_provider_label) =
        business_payment_provider_ui_config(app_root);
    let (payment_provider_status_label, payment_provider_status_detail) =
        business_payment_provider_status(
            root,
            business_id,
            &payment_provider_id,
            &payment_provider_label,
        );
    let (
        payment_provider_connect_path,
        payment_provider_refresh_path,
        payment_provider_disconnect_path,
    ) = business_payment_provider_paths(business_slug, &payment_provider_id);
    let mut params = Map::from_iter([
        ("business_name".to_owned(), Value::String(business_name)),
        (
            "business_admin_path".to_owned(),
            Value::String(format!("/businesses/{business_slug}/")),
        ),
        (
            "payment_provider_label".to_owned(),
            Value::String(payment_provider_label.clone()),
        ),
        (
            "payment_provider_status_label".to_owned(),
            Value::String(payment_provider_status_label),
        ),
        (
            "payment_provider_status_detail".to_owned(),
            Value::String(payment_provider_status_detail),
        ),
        (
            "payment_provider_connect_path".to_owned(),
            Value::String(payment_provider_connect_path),
        ),
        (
            "payment_provider_refresh_path".to_owned(),
            Value::String(payment_provider_refresh_path),
        ),
        (
            "payment_provider_disconnect_path".to_owned(),
            Value::String(payment_provider_disconnect_path),
        ),
        (
            "payment_provider_connect_button_ui_html".to_owned(),
            Value::String(payment_provider_action_button_html(
                app_root,
                "payment_provider_connect_button",
                &format!("Connect {payment_provider_label}"),
                "btn btn-primary",
            )?),
        ),
        (
            "payment_provider_refresh_button_ui_html".to_owned(),
            Value::String(payment_provider_action_button_html(
                app_root,
                "payment_provider_refresh_button",
                "Refresh status",
                "btn btn-secondary",
            )?),
        ),
        (
            "payment_provider_disconnect_button_ui_html".to_owned(),
            Value::String(payment_provider_action_button_html(
                app_root,
                "payment_provider_disconnect_button",
                "Disconnect",
                "btn btn-danger",
            )?),
        ),
    ]);
    for (key, value) in super::payment_provider::payment_provider_template_params(
        root,
        app_root,
        business_slug,
        &payment_provider_id,
    ) {
        params.insert(key, value);
    }
    for key in [
        "owner_payment_provider_status_label",
        "owner_payment_provider_status_icon",
        "owner_payment_provider_mode_demo_label",
        "owner_payment_provider_mode_live_label",
        "owner_payment_provider_credentials_state_label",
        "owner_payment_provider_setup_eyebrow",
        "owner_payment_provider_setup_headline",
        "owner_payment_provider_setup_body",
        "owner_payment_provider_credentials_headline",
        "owner_payment_provider_credentials_body",
        "owner_payment_provider_client_id_label",
        "owner_payment_provider_client_id_placeholder",
        "owner_payment_provider_client_secret_label",
        "owner_payment_provider_client_secret_placeholder",
        "owner_payment_provider_save_credentials_label",
        "owner_payment_provider_delete_credentials_label",
        "owner_payment_provider_connect_label",
        "owner_payment_provider_refresh_label",
        "owner_payment_provider_back_label",
    ] {
        if let Some(value) = super::payment_provider::payment_provider_copy_value(app_root, key) {
            params.insert(key.to_owned(), Value::String(value));
        }
    }
    params.insert(
        "owner_payment_provider_action_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/test/"
        )),
    );
    params.insert(
        "owner_payment_provider_refresh_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/refresh/"
        )),
    );
    params.insert(
        "owner_payment_provider_credentials_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/credentials/"
        )),
    );
    params.insert(
        "owner_payment_provider_credentials_delete_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/credentials/delete/"
        )),
    );
    params.insert(
        "owner_payment_provider_mode_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/mode/"
        )),
    );
    params.insert(
        "payment_provider_feedback_message".to_owned(),
        Value::String(String::new()),
    );
    compact(&Value::Object(params))
}

pub fn dynamic_business_edit_external_integrations_html(
    root: &Value,
    business_slug: &str,
    app_root: &Path,
) -> Option<String> {
    let business = bounded_state_array(root, "businesses")
        .iter()
        .find(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))?;
    let business_id = business.get("id").and_then(Value::as_i64)?;
    let (payment_provider_id, _payment_provider_label) =
        business_payment_provider_ui_config(app_root);
    let connection_status =
        if state_find_google_calendar_connection_for_business_logic_local(root, business_id)
            .is_some()
        {
            "Connected"
        } else {
            "Disconnected"
        };
    let mut params = Map::from_iter([
        (
            "connection_status".to_owned(),
            Value::String(connection_status.to_owned()),
        ),
        (
            "business_admin_google_mode_input_ui_html".to_owned(),
            Value::String(render_hidden_input_fragment(
                app_root,
                "business_edit_google_mode_input",
                "mode",
                "business",
            )?),
        ),
        (
            "business_admin_google_slug_input_ui_html".to_owned(),
            Value::String(render_hidden_input_fragment(
                app_root,
                "business_edit_google_slug_input",
                "business_slug",
                business_slug,
            )?),
        ),
        (
            "business_admin_google_next_input_ui_html".to_owned(),
            Value::String(render_hidden_input_fragment(
                app_root,
                "business_edit_google_next_input",
                "next",
                &format!("/businesses/{business_slug}/edit/"),
            )?),
        ),
        (
            "payment_provider_feedback_message".to_owned(),
            Value::String(String::new()),
        ),
    ]);
    for (key, value) in super::payment_provider::payment_provider_template_params(
        root,
        app_root,
        business_slug,
        &payment_provider_id,
    ) {
        params.insert(key, value);
    }
    for key in [
        "owner_payment_provider_status_label",
        "owner_payment_provider_status_icon",
        "owner_payment_provider_mode_demo_label",
        "owner_payment_provider_mode_live_label",
        "owner_payment_provider_credentials_state_label",
        "owner_payment_provider_credentials_headline",
        "owner_payment_provider_credentials_body",
        "owner_payment_provider_client_id_label",
        "owner_payment_provider_client_id_placeholder",
        "owner_payment_provider_client_secret_label",
        "owner_payment_provider_client_secret_placeholder",
        "owner_payment_provider_save_credentials_label",
        "owner_payment_provider_delete_credentials_label",
        "owner_payment_provider_connect_label",
        "owner_payment_provider_refresh_label",
    ] {
        if let Some(value) = super::payment_provider::payment_provider_copy_value(app_root, key) {
            params.insert(key.to_owned(), Value::String(value));
        }
    }
    params.insert(
        "owner_payment_provider_action_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/test/"
        )),
    );
    params.insert(
        "owner_payment_provider_refresh_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/refresh/"
        )),
    );
    params.insert(
        "owner_payment_provider_credentials_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/credentials/"
        )),
    );
    params.insert(
        "owner_payment_provider_credentials_delete_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/credentials/delete/"
        )),
    );
    params.insert(
        "owner_payment_provider_mode_href".to_owned(),
        Value::String(format!(
            "/businesses/{business_slug}/payment-providers/{payment_provider_id}/mode/"
        )),
    );
    render_fragment_with_params(
        app_root,
        "templates/businesses/fragments/business_edit_external_integrations.html",
        params,
    )
}

/// Releases a PostgreSQL runtime configuration.
///
/// # Parameters
///
/// - `_config`: Input consumed by [`crate::runtime::json_commands::free_postgresql_runtime_config_runtime_local`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::free_postgresql_runtime_config_runtime_local`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::free_postgresql_runtime_config_runtime_local(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn free_postgresql_runtime_config_runtime_local<T>(_config: T) {}

/// Finds a business by numeric identifier.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::find_business_by_id_runtime_local`].
/// - `business_id`: Input consumed by [`crate::runtime::json_commands::find_business_by_id_runtime_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::find_business_by_id_runtime_local`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::find_business_by_id_runtime_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::find_business_by_id_runtime_local(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn find_business_by_id_runtime_local(root: &Value, business_id: i64) -> Option<Value> {
    bounded_state_array(root, "businesses")
        .iter()
        .find(|row| row.get("id").and_then(Value::as_i64) == Some(business_id))
        .cloned()
}

/// Converts a JSON value to an integer without panicking.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::long_from_value_runtime_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::long_from_value_runtime_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::long_from_value_runtime_local("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn long_from_value_runtime_local(value: &Value) -> i64 {
    super::ops_bridge::long_from_value(value)
}

/// Builds registration page parameters with one escaped error message.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::register_page_params_with_error_json`].
/// - `error_text`: Input consumed by [`crate::runtime::json_commands::register_page_params_with_error_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::register_page_params_with_error_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::register_page_params_with_error_json(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn register_page_params_with_error_json(root: &Value, error_text: &str) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("error".into(), Value::String(error_text.into()));
    page_params_value(root, "register", extra)
}

/// Returns a path for a generated admin composition.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::runtime_generated_surface_admin_composition_path`].
/// - `composition_id`: Input consumed by [`crate::runtime::json_commands::runtime_generated_surface_admin_composition_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::runtime_generated_surface_admin_composition_path`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::runtime_generated_surface_admin_composition_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_generated_surface_admin_composition_path(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_admin_composition_path(
    root: &Value,
    composition_id: &str,
) -> Option<String> {
    root.get("compositions")?
        .as_array()?
        .iter()
        .find(|row| row.get("id").and_then(Value::as_str) == Some(composition_id))
        .and_then(|row| row.get("path").and_then(Value::as_str))
        .map(ToOwned::to_owned)
}

/// Finds one named composition section.
///
/// # Parameters
///
/// - `composition`: Input consumed by [`crate::runtime::json_commands::runtime_generated_surface_composition_find_section`].
/// - `section_id`: Input consumed by [`crate::runtime::json_commands::runtime_generated_surface_composition_find_section`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::runtime_generated_surface_composition_find_section`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::runtime_generated_surface_composition_find_section`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_generated_surface_composition_find_section(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_composition_find_section<'a>(
    composition: &'a Value,
    section_id: &str,
) -> Option<&'a Value> {
    composition
        .get("sections")?
        .as_array()?
        .iter()
        .find(|row| row.get("id").and_then(Value::as_str) == Some(section_id))
}

/// Returns whether a composition section is enabled.
///
/// # Parameters
///
/// - `section`: Input consumed by [`crate::runtime::json_commands::runtime_generated_surface_composition_section_enabled`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::runtime_generated_surface_composition_section_enabled`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_generated_surface_composition_section_enabled("items");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_composition_section_enabled(section: &Value) -> bool {
    section
        .get("enabled")
        .and_then(Value::as_bool)
        .unwrap_or(true)
}

/// Finds a named form in a generated surface document.
///
/// # Parameters
///
/// - `surface`: Input consumed by [`crate::runtime::json_commands::runtime_surface_find_form`].
/// - `form_id`: Input consumed by [`crate::runtime::json_commands::runtime_surface_find_form`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::runtime_surface_find_form`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::runtime_surface_find_form`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_surface_find_form(todo!(), "form");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_surface_find_form<'a>(surface: &'a Value, form_id: &str) -> Option<&'a Value> {
    surface
        .get("forms")?
        .as_array()?
        .iter()
        .find(|form| form.get("id").and_then(Value::as_str) == Some(form_id))
}

/// Appends bounded text to a runtime buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::runtime_text_buffer_append`].
/// - `text`: Input consumed by [`crate::runtime::json_commands::runtime_text_buffer_append`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::runtime_text_buffer_append`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_text_buffer_append(todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_text_buffer_append(output: &mut String, text: &str) -> bool {
    text_buffer_append_format(output, text)
}

/// Clears a runtime text buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::runtime_text_buffer_free`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::runtime_text_buffer_free`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_text_buffer_free(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_text_buffer_free(output: &mut String) {
    output.clear();
}

/// Renders a service media URL using the canonical media route.
///
/// # Parameters
///
/// - `business_slug`: Input consumed by [`crate::runtime::json_commands::dynamic_service_media_url`].
/// - `media_url`: Input consumed by [`crate::runtime::json_commands::dynamic_service_media_url`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_service_media_url`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_service_media_url("demo", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_service_media_url(business_slug: &str, media_url: &str) -> Option<String> {
    super::dynamic::media_disk_path(Path::new("."), business_slug, media_url).or_else(|| {
        (!business_slug.is_empty() && !media_url.is_empty()).then(|| {
            format!(
                "/media/businesses/{business_slug}/{}",
                media_url.trim_start_matches('/')
            )
        })
    })
}

/// Renders a generated admin fragment from an app-owned document.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_generated_admin_fragment_from_doc`].
/// - `relative_path`: Input consumed by [`crate::runtime::json_commands::render_generated_admin_fragment_from_doc`].
/// - `params`: Input consumed by [`crate::runtime::json_commands::render_generated_admin_fragment_from_doc`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_generated_admin_fragment_from_doc`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_generated_admin_fragment_from_doc(std::path::Path::new("apps/dev_docs"), "page", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_generated_admin_fragment_from_doc(
    app_root: &Path,
    relative_path: &str,
    params: &Value,
) -> Option<String> {
    render_shared_asset_fragment_from_doc(app_root, relative_path, params)
}

/// Tests whether an array contains a numeric value.
///
/// # Parameters
///
/// - `array`: Input consumed by [`crate::runtime::json_commands::json_array_contains_long_runtime_local`].
/// - `wanted`: Input consumed by [`crate::runtime::json_commands::json_array_contains_long_runtime_local`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::json_array_contains_long_runtime_local`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::json_array_contains_long_runtime_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_array_contains_long_runtime_local(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_array_contains_long_runtime_local(array: &Value, wanted: i64) -> bool {
    array.as_array().is_some_and(|items| {
        items
            .iter()
            .any(|item| item.as_i64().or_else(|| item.as_str()?.parse().ok()) == Some(wanted))
    })
}

/// Builds login page parameters from a validated error and next path.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::login_page_params_json`].
/// - `error_text`: Input consumed by [`crate::runtime::json_commands::login_page_params_json`].
/// - `next_path`: Input consumed by [`crate::runtime::json_commands::login_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::login_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::login_page_params_json(std::path::Path::new("."), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn login_page_params_json(root: &Value, error_text: &str, next_path: &str) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("error".into(), Value::String(error_text.into()));
    extra.insert("next".into(), Value::String(next_path.into()));
    page_params_value(root, "login", extra)
}

/// Builds password-reset completion page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::password_reset_complete_page_params_json`].
/// - `error_text`: Input consumed by [`crate::runtime::json_commands::password_reset_complete_page_params_json`].
/// - `token`: Input consumed by [`crate::runtime::json_commands::password_reset_complete_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::password_reset_complete_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::password_reset_complete_page_params_json(std::path::Path::new("."), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn password_reset_complete_page_params_json(
    root: &Value,
    error_text: &str,
    token: &str,
) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("error".into(), Value::String(error_text.into()));
    extra.insert("token".into(), Value::String(token.into()));
    page_params_value(root, "password-reset-complete", extra)
}

/// Builds password-reset request page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::password_reset_request_page_params_json`].
/// - `error_text`: Input consumed by [`crate::runtime::json_commands::password_reset_request_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::password_reset_request_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::password_reset_request_page_params_json(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn password_reset_request_page_params_json(root: &Value, error_text: &str) -> Option<String> {
    let mut extra = Map::new();
    extra.insert("error".into(), Value::String(error_text.into()));
    page_params_value(root, "password-reset-request", extra)
}

/// Builds registration page parameters.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::register_page_params_json`].
/// - `error_text`: Input consumed by [`crate::runtime::json_commands::register_page_params_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::register_page_params_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::register_page_params_json(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn register_page_params_json(root: &Value, error_text: &str) -> Option<String> {
    register_page_params_with_error_json(root, error_text)
}

/// Returns at most `limit` UTF-8 bytes from a string without splitting characters.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::strndup`].
/// - `limit`: Input consumed by [`crate::runtime::json_commands::strndup`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::strndup`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::strndup`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::strndup("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn strndup(value: &str, limit: usize) -> String {
    value.chars().take(limit).collect()
}

/// Copies a bounded string as an owned Rust value.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::strdup`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::strdup`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::strdup("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn strdup(value: &str) -> String {
    strndup(value, MAX_TEXT_BYTES)
}

/// Splits a bounded string into delimiter-separated owned fields.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::strtok_r`].
/// - `delimiter`: Input consumed by [`crate::runtime::json_commands::strtok_r`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::strtok_r`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::strtok_r`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::strtok_r("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn strtok_r(value: &str, delimiter: &str) -> Vec<String> {
    if delimiter.is_empty() {
        return vec![value.to_owned()];
    }
    value
        .split(delimiter)
        .filter(|part| !part.is_empty())
        .map(ToOwned::to_owned)
        .take(4096)
        .collect()
}

/// Serializes one JSON string using the canonical escaping policy.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::encode_json_string_literal`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::encode_json_string_literal`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::encode_json_string_literal("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn encode_json_string_literal(value: &str) -> Option<String> {
    serde_json::to_string(value).ok()
}

/// Converts bytes to lowercase hexadecimal text.
///
/// # Parameters
///
/// - `bytes`: Input consumed by [`crate::runtime::json_commands::bytes_to_hex_logic_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::bytes_to_hex_logic_local`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::bytes_to_hex_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::bytes_to_hex_logic_local(b"");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn bytes_to_hex_logic_local(bytes: &[u8]) -> String {
    pharos_runtime_core::support::hex_digest(bytes)
}

/// Computes HMAC-SHA256 for a bounded message using the shared runtime primitive.
///
/// # Parameters
///
/// - `key`: Input consumed by [`crate::runtime::json_commands::hmac_sha256_logic_local`].
/// - `data`: Input consumed by [`crate::runtime::json_commands::hmac_sha256_logic_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::hmac_sha256_logic_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::hmac_sha256_logic_local("key", b"");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn hmac_sha256_logic_local(key: &[u8], data: &[u8]) -> [u8; 32] {
    super::dynamic::hmac_sha256(key, data)
}

/// Finds one multipart boundary parameter from a Content-Type header.
///
/// # Parameters
///
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::dynamic_multipart_boundary`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_multipart_boundary`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_multipart_boundary`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_multipart_boundary(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_multipart_boundary(content_type: &str) -> Option<String> {
    let parameter = content_type.split(';').find_map(|part| {
        let (name, value) = part.trim().split_once('=')?;
        name.eq_ignore_ascii_case("boundary")
            .then_some(value.trim().trim_matches('"').to_owned())
    })?;
    (!parameter.is_empty() && parameter.len() <= 512 && !parameter.contains(['\r', '\n']))
        .then_some(parameter)
}

/// Finds a byte sequence in a bounded byte slice.
///
/// # Parameters
///
/// - `haystack`: Input consumed by [`crate::runtime::json_commands::multipart_memmem`].
/// - `needle`: Input consumed by [`crate::runtime::json_commands::multipart_memmem`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::multipart_memmem`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::multipart_memmem(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn multipart_memmem(haystack: &[u8], needle: &[u8]) -> Option<usize> {
    if needle.is_empty() {
        return Some(0);
    }
    haystack
        .windows(needle.len())
        .position(|window| window == needle)
}

/// Copies one checked byte range.
///
/// # Parameters
///
/// - `body`: Input consumed by [`crate::runtime::json_commands::multipart_dup_range`].
/// - `start`: Input consumed by [`crate::runtime::json_commands::multipart_dup_range`].
/// - `length`: Input consumed by [`crate::runtime::json_commands::multipart_dup_range`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::multipart_dup_range`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::multipart_dup_range(b"", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn multipart_dup_range(body: &[u8], start: usize, length: usize) -> Option<Vec<u8>> {
    let end = start.checked_add(length)?;
    (end <= body.len() && length <= super::http::PHAROS_HTTP_MAX_MULTIPART_BODY_BYTES)
        .then(|| body[start..end].to_vec())
}

/// Finds a multipart field and returns filename plus content bytes.
///
/// # Parameters
///
/// - `body`: Raw multipart request body bytes.
/// - `content_type`: Request content type containing the multipart boundary.
/// - `field_name`: Multipart form field to extract.
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::dynamic_multipart_find_part`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::dynamic_multipart_find_part`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::dynamic_multipart_find_part(b"", todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_multipart_find_part(
    body: &[u8],
    content_type: &str,
    field_name: &str,
) -> Option<(Option<String>, Vec<u8>)> {
    let boundary = dynamic_multipart_boundary(content_type)?;
    let marker = format!("--{boundary}").into_bytes();
    let mut cursor = multipart_memmem(body, &marker)?;
    while cursor < body.len() {
        let header_start = cursor.checked_add(marker.len() + 2)?;
        if header_start > body.len() {
            return None;
        }
        let header_end =
            multipart_memmem(&body[header_start..], b"\r\n\r\n")?.checked_add(header_start)?;
        let headers = std::str::from_utf8(&body[header_start..header_end]).ok()?;
        let disposition = headers.lines().find(|line| {
            line.to_ascii_lowercase()
                .starts_with("content-disposition:")
        })?;
        let name = disposition.split(';').find_map(|part| {
            let (key, value) = part.trim().split_once('=')?;
            key.eq_ignore_ascii_case("name")
                .then_some(value.trim().trim_matches('"'))
        })?;
        let filename = disposition.split(';').find_map(|part| {
            let (key, value) = part.trim().split_once('=')?;
            key.eq_ignore_ascii_case("filename")
                .then_some(value.trim().trim_matches('"').to_owned())
        });
        let content_start = header_end + 4;
        let next_marker = multipart_memmem(&body[content_start..], &marker)
            .map(|offset| offset + content_start)?;
        let content_end = next_marker.saturating_sub(2);
        if name == field_name {
            return Some((filename, body[content_start..content_end].to_vec()));
        }
        cursor = next_marker;
    }
    None
}

/// Extracts one multipart text field from an in-memory request body as UTF-8.
///
/// # Parameters
///
/// - `body`: Input consumed by [`crate::runtime::json_commands::multipart_extract_text_from_bytes`].
/// - `content_type`: Input consumed by [`crate::runtime::json_commands::multipart_extract_text_from_bytes`].
/// - `field_name`: Input consumed by [`crate::runtime::json_commands::multipart_extract_text_from_bytes`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::multipart_extract_text_from_bytes`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::multipart_extract_text_from_bytes(b"", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn multipart_extract_text_from_bytes(
    body: &[u8],
    content_type: &str,
    field_name: &str,
) -> Option<String> {
    let (_, bytes) = dynamic_multipart_find_part(body, content_type, field_name)?;
    String::from_utf8(bytes).ok()
}

/// Returns the audit-event count for a state JSON document.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::json_commands::audit_event_count`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::audit_event_count`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::audit_event_count(std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn audit_event_count(root: &Value) -> String {
    bounded_state_array(root, "audit_events").len().to_string()
}

/// Exports relational state through the selected backend contract.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::export_runtime_state_json`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::export_runtime_state_json`].
/// - `app_id`: Input consumed by [`crate::runtime::json_commands::export_runtime_state_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::export_runtime_state_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::export_runtime_state_json(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn export_runtime_state_json(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    app_id: Option<&str>,
) -> Option<String> {
    dynamic_runtime_state_export_json_runtime(app_root, runtime_conf_path, app_id)
}

/// Imports a validated relational state file through the selected backend contract.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::import_runtime_state_file`].
/// - `runtime_conf_path`: Input consumed by [`crate::runtime::json_commands::import_runtime_state_file`].
/// - `app_id`: Input consumed by [`crate::runtime::json_commands::import_runtime_state_file`].
/// - `state_path`: Input consumed by [`crate::runtime::json_commands::import_runtime_state_file`].
/// - `expected_audit_count`: Input consumed by [`crate::runtime::json_commands::import_runtime_state_file`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::import_runtime_state_file`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::import_runtime_state_file(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn import_runtime_state_file(
    app_root: &Path,
    runtime_conf_path: Option<&Path>,
    app_id: Option<&str>,
    state_path: &Path,
    expected_audit_count: Option<&str>,
) -> i32 {
    dynamic_runtime_state_import_json_runtime(
        app_root,
        runtime_conf_path,
        app_id,
        state_path,
        expected_audit_count,
    )
}

/// Returns whether the relational backend is authoritative for this app.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::relational_runtime_authority_enabled_runtime_local`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::relational_runtime_authority_enabled_runtime_local`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::relational_runtime_authority_enabled_runtime_local(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn relational_runtime_authority_enabled_runtime_local(app_root: &Path) -> bool {
    relational_runtime_authority_enabled(app_root)
}

/// Returns a migration contract document as compact JSON.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::migration_contract_text_dup_runtime_local`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::migration_contract_text_dup_runtime_local`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::migration_contract_text_dup_runtime_local(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn migration_contract_text_dup_runtime_local(path: &Path) -> Option<String> {
    compact(&read_json_file(path)?)
}

/// Returns a stable file signature based on metadata and content hash.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::native_file_signature`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::native_file_signature`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::native_file_signature(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn native_file_signature(path: &Path) -> Option<String> {
    let bytes = fs::read(path).ok()?;
    Some(bytes_to_hex_logic_local(&Sha256::digest(&bytes)))
}

/// Loads a JSON document from disk with size and object-depth guards.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::json_doc_load_file`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_doc_load_file`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::json_doc_load_file`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_doc_load_file(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_doc_load_file(path: &Path) -> Option<Value> {
    let metadata = fs::metadata(path).ok()?;
    if !metadata.is_file() || metadata.len() > MAX_TEXT_BYTES as u64 {
        return None;
    }
    serde_json::from_str(&fs::read_to_string(path).ok()?).ok()
}

/// Reads bounded file bytes for direct runtime consumers.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::read_file_bytes`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::read_file_bytes`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::read_file_bytes(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn read_file_bytes(path: &Path) -> Option<Vec<u8>> {
    let bytes = fs::read(path).ok()?;
    (bytes.len() <= MAX_TEXT_BYTES).then_some(bytes)
}

/// Writes bounded binary data to an app-owned file.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::write_binary_file`].
/// - `bytes`: Input consumed by [`crate::runtime::json_commands::write_binary_file`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::write_binary_file`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::write_binary_file(std::path::Path::new("fixture.json"), b"");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn write_binary_file(path: &Path, bytes: &[u8]) -> i32 {
    if bytes.len() > MAX_TEXT_BYTES {
        return 64;
    }
    super::fs::write_binary_file(path, bytes, 0o640)
        .map(|_| 0)
        .unwrap_or(69)
}

/// Applies a base path to root-relative HTML URLs without touching external URLs.
///
/// # Parameters
///
/// - `html`: Input consumed by [`crate::runtime::json_commands::apply_base_path_html`].
/// - `base_path`: Input consumed by [`crate::runtime::json_commands::apply_base_path_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::apply_base_path_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::apply_base_path_html(todo!(), "/app");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn apply_base_path_html(html: &str, base_path: Option<&str>) -> Option<String> {
    template_apply_base_path(html, base_path)
}

/// Builds layout parameters from a bounded JSON document.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::build_layout_page_params`].
/// - `params`: Input consumed by [`crate::runtime::json_commands::build_layout_page_params`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::build_layout_page_params`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::build_layout_page_params(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn build_layout_page_params(app_root: &Path, params: &Value) -> Option<String> {
    let _ = app_root;
    compact(params)
}

/// Finds a declared page file below an app directory.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::runtime_find_declared_page_relative_path_in_directory`].
/// - `page_id`: Input consumed by [`crate::runtime::json_commands::runtime_find_declared_page_relative_path_in_directory`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::runtime_find_declared_page_relative_path_in_directory`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_find_declared_page_relative_path_in_directory(std::path::Path::new("apps/dev_docs"), "home");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_find_declared_page_relative_path_in_directory(
    app_root: &Path,
    page_id: &str,
) -> Option<String> {
    declared_page_relative_path(app_root, page_id)
}

/// Matches a declared page filename to a validated page identifier.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::runtime_declared_page_file_matches_id`].
/// - `page_id`: Input consumed by [`crate::runtime::json_commands::runtime_declared_page_file_matches_id`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::runtime_declared_page_file_matches_id`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::runtime_declared_page_file_matches_id(std::path::Path::new("fixture.json"), "home");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn runtime_declared_page_file_matches_id(path: &Path, page_id: &str) -> bool {
    path.file_stem()
        .and_then(|value| value.to_str())
        .is_some_and(|value| value == page_id || value.strip_suffix(".page") == Some(page_id))
}

/// Appends a bounded formatted fragment to a text buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_buffer_append_format`].
/// - `text`: Input consumed by [`crate::runtime::json_commands::text_buffer_append_format`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::text_buffer_append_format`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_buffer_append_format(todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_buffer_append_format(output: &mut String, text: &str) -> bool {
    if output.len().saturating_add(text.len()) > MAX_TEXT_BYTES {
        return false;
    }
    output.push_str(text);
    true
}

/// Performs JSON find string recursive.
fn json_find_string_recursive(value: &Value, key: &str) -> Option<String> {
    match value {
        Value::Object(map) => {
            if let Some(text) = map.get(key).and_then(Value::as_str) {
                return Some(text.to_owned());
            }
            map.values()
                .find_map(|entry| json_find_string_recursive(entry, key))
        }
        Value::Array(items) => items
            .iter()
            .find_map(|entry| json_find_string_recursive(entry, key)),
        _ => None,
    }
}

/// Finds a string field in a bounded JSON document.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::json_find_string`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_find_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_find_string`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::json_find_string`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_find_string("{}", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_find_string(text: &str, key: &str) -> Option<String> {
    if key.is_empty() || text.len() > MAX_TEXT_BYTES {
        return None;
    }
    json_find_string_recursive(&serde_json::from_str(text).ok()?, key)
}

/// Finds a string field after a caller-selected text offset.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::json_find_string_after`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_find_string_after`].
/// - `start_at`: Input consumed by [`crate::runtime::json_commands::json_find_string_after`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_find_string_after`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::json_find_string_after`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_find_string_after("{}", "key", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_find_string_after(text: &str, key: &str, start_at: &str) -> Option<String> {
    let offset = text.find(start_at)?;
    json_find_string(&text[offset..], key)
}

/// Finds a string field inside a named JSON section.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::json_find_string_in_section`].
/// - `section`: Input consumed by [`crate::runtime::json_commands::json_find_string_in_section`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_find_string_in_section`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_find_string_in_section`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::json_find_string_in_section`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_find_string_in_section("{}", "items", "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_find_string_in_section(text: &str, section: &str, key: &str) -> Option<String> {
    if section.is_empty() || key.is_empty() {
        return None;
    }
    let root: Value = serde_json::from_str(text).ok()?;
    let section = root.get(section)?;
    json_find_string_recursive(section, key)
}

/// Looks up a safe key in a line-oriented runtime configuration file.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::json_commands::conf_lookup_value`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::conf_lookup_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::conf_lookup_value`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::conf_lookup_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::conf_lookup_value(std::path::Path::new("fixture.json"), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn conf_lookup_value(path: &Path, key: &str) -> Option<String> {
    if key.is_empty()
        || key
            .bytes()
            .any(|byte| !byte.is_ascii_alphanumeric() && byte != b'_')
    {
        return None;
    }
    let metadata = fs::metadata(path).ok()?;
    if metadata.len() > MAX_TEXT_BYTES as u64 {
        return None;
    }
    fs::read_to_string(path).ok()?.lines().find_map(|line| {
        let (candidate, raw) = line.split_once('=')?;
        (candidate.trim() == key).then(|| raw.trim().trim_matches(['"', '\'']).to_owned())
    })
}

/// Appends text to a bounded template buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_buffer_append`].
/// - `text`: Input consumed by [`crate::runtime::json_commands::text_buffer_append`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::text_buffer_append`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_buffer_append(todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_buffer_append(output: &mut String, text: &str) -> bool {
    text_buffer_append_format(output, text)
}

/// Appends one character to a bounded template buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_buffer_append_char`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::text_buffer_append_char`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::text_buffer_append_char`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_buffer_append_char(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_buffer_append_char(output: &mut String, value: char) -> bool {
    let mut encoded = [0u8; 4];
    text_buffer_append(output, value.encode_utf8(&mut encoded))
}

/// Escapes and appends one template value.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_buffer_append_html_escaped`].
/// - `text`: Input consumed by [`crate::runtime::json_commands::text_buffer_append_html_escaped`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::text_buffer_append_html_escaped`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_buffer_append_html_escaped(todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_buffer_append_html_escaped(output: &mut String, text: &str) -> bool {
    text_buffer_append(output, &html_escape_text(text))
}

/// Releases a template buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_buffer_free`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::text_buffer_free`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_buffer_free(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_buffer_free(output: &mut String) {
    output.clear();
    output.shrink_to_fit();
}

/// Reserves bounded template buffer capacity.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_buffer_reserve`].
/// - `needed_length`: Input consumed by [`crate::runtime::json_commands::text_buffer_reserve`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::text_buffer_reserve`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_buffer_reserve(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_buffer_reserve(output: &mut String, needed_length: usize) -> bool {
    needed_length <= MAX_TEXT_BYTES
        && output
            .try_reserve(needed_length.saturating_sub(output.len()))
            .is_ok()
}

/// Takes a template buffer's contents.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_buffer_take`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::text_buffer_take`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_buffer_take(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_buffer_take(output: &mut String) -> Option<String> {
    (!output.is_empty()).then(|| std::mem::take(output))
}

/// Loads a JSON root from bounded text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::load_root_from`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::load_root_from`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::load_root_from`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::load_root_from("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn load_root_from(text: &str) -> Option<Value> {
    (text.len() <= MAX_TEXT_BYTES)
        .then(|| serde_json::from_str(text).ok())
        .flatten()
}

/// Converts a JSON value to its template text representation.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::template_value_text`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::template_value_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_value_text("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_value_text(value: &Value) -> String {
    match value {
        Value::Null => String::new(),
        Value::String(text) => text.clone(),
        Value::Bool(flag) => flag.to_string(),
        Value::Number(number) => number.to_string(),
        other => serde_json::to_string(other).unwrap_or_default(),
    }
}

/// Validates whether a template reference uses one approved URL scheme.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::template_reference_has_allowed_url_scheme`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::template_reference_has_allowed_url_scheme`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_reference_has_allowed_url_scheme("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_reference_has_allowed_url_scheme(text: &str) -> bool {
    template_url_reference_allowed(text)
}

/// Performs template value usd minor text.
fn template_value_usd_minor_text(value: &Value) -> Option<String> {
    let minor = match value {
        Value::Number(number) => number.as_i64()?,
        Value::String(text) => text.parse::<i64>().ok()?,
        _ => return None,
    };
    currency_minor_text(minor, "USD")
}

/// Formats exact integer minor units for supported currencies without floating-point rounding.
pub(super) fn currency_minor_text(amount: i64, currency: &str) -> Option<String> {
    let prefix = match currency {
        "USD" => "$",
        "JPY" => "¥",
        "EUR" => "€",
        "GBP" => "£",
        "CAD" => "CAD ",
        "AUD" => "AUD ",
        _ => return None,
    };
    let sign = if amount < 0 { "-" } else { "" };
    let absolute = amount.unsigned_abs();
    Some(if currency == "JPY" {
        format!("{sign}{prefix}{absolute}")
    } else {
        format!("{sign}{prefix}{}.{:02}", absolute / 100, absolute % 100)
    })
}

/// Classifies a placeholder as text, path, URL, HTML, or formatted USD minor units.
///
/// # Parameters
///
/// - `name`: Input consumed by [`crate::runtime::json_commands::template_placeholder_kind`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::template_placeholder_kind`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::template_placeholder_kind("name");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn template_placeholder_kind(name: &str) -> String {
    if name.starts_with("html:") {
        "html".to_owned()
    } else if name.starts_with("path:") {
        "path".to_owned()
    } else if name.starts_with("url:") {
        "url".to_owned()
    } else if name.starts_with("usd_minor:") {
        "usd_minor".to_owned()
    } else if name.starts_with("currency_minor:") {
        "currency_minor".to_owned()
    } else {
        "text".to_owned()
    }
}

/// Appends a JSON value after applying the placeholder kind security policy.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::runtime::json_commands::text_buffer_append_template_value`].
/// - `value`: Input consumed by [`crate::runtime::json_commands::text_buffer_append_template_value`].
/// - `kind`: Input consumed by [`crate::runtime::json_commands::text_buffer_append_template_value`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::text_buffer_append_template_value`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::text_buffer_append_template_value(todo!(), "value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn text_buffer_append_template_value(output: &mut String, value: &Value, kind: &str) -> bool {
    match kind {
        "html" => text_buffer_append(output, &template_value_text(value)),
        "path" if template_path_reference_allowed(&template_value_text(value)) => {
            text_buffer_append_html_escaped(output, &template_value_text(value))
        }
        "url" if template_url_reference_allowed(&template_value_text(value)) => {
            text_buffer_append_html_escaped(output, &template_value_text(value))
        }
        "usd_minor" => template_value_usd_minor_text(value)
            .is_some_and(|text| text_buffer_append_html_escaped(output, &text)),
        "text" => text_buffer_append_html_escaped(output, &template_value_text(value)),
        _ => false,
    }
}

/// Renders template text with an explicit default placeholder kind.
///
/// # Parameters
///
/// - `template_text`: Input consumed by [`crate::runtime::json_commands::render_template_text_with_default_kind`].
/// - `params_root`: Input consumed by [`crate::runtime::json_commands::render_template_text_with_default_kind`].
/// - `default_kind`: Input consumed by [`crate::runtime::json_commands::render_template_text_with_default_kind`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_template_text_with_default_kind`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::render_template_text_with_default_kind`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_template_text_with_default_kind(todo!(), &serde_json::json!({}), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_template_text_with_default_kind(
    template_text: &str,
    params_root: &Value,
    default_kind: &str,
) -> Option<String> {
    let params = params_root.as_object()?;
    let mut output = String::new();
    let mut cursor = 0usize;
    while let Some(offset) = template_text[cursor..].find('{') {
        let open = cursor + offset;
        text_buffer_append(&mut output, &template_text[cursor..open]).then_some(())?;
        let close = template_text[open + 1..].find('}')? + open + 1;
        let raw = &template_text[open + 1..close];
        let (kind, key) = raw
            .split_once(':')
            .map_or((default_kind, raw), |(kind, key)| (kind, key));
        if kind == "currency_minor" {
            let value = params.get(key)?;
            let amount = value.as_i64().or_else(|| value.as_str()?.parse().ok())?;
            let text = currency_minor_text(amount, params.get("currency")?.as_str()?)?;
            text_buffer_append_html_escaped(&mut output, &text).then_some(())?;
        } else {
            text_buffer_append_template_value(&mut output, params.get(key)?, kind).then_some(())?;
        }
        cursor = close + 1;
    }
    text_buffer_append(&mut output, &template_text[cursor..]).then_some(output)
}

/// Resolves a shared JSON template fragment.
///
/// # Parameters
///
/// - `fragment_name`: Input consumed by [`crate::runtime::json_commands::shared_asset_fragment_path_json`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::json_commands::shared_asset_fragment_path_json`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::shared_asset_fragment_path_json(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn shared_asset_fragment_path_json(fragment_name: &str) -> bool {
    fragment_name.starts_with("templates/shared/")
        && !fragment_name.contains("..")
        && !fragment_name.contains('\0')
}

/// Returns a shared fragment's rendered HTML.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_shared_asset_fragment_json`].
/// - `fragment_name`: Input consumed by [`crate::runtime::json_commands::render_shared_asset_fragment_json`].
/// - `params_root`: Input consumed by [`crate::runtime::json_commands::render_shared_asset_fragment_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_shared_asset_fragment_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_shared_asset_fragment_json(std::path::Path::new("apps/dev_docs"), todo!(), &serde_json::json!({}));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_shared_asset_fragment_json(
    app_root: &str,
    fragment_name: &str,
    params_root: &Value,
) -> Option<String> {
    shared_asset_fragment_path_json(fragment_name)
        .then(|| render_app_fragment_from_doc(app_root, fragment_name, params_root))
        .flatten()
}

/// Renders an app-owned JSON template fragment.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_app_fragment`].
/// - `fragment_name`: Input consumed by [`crate::runtime::json_commands::render_app_fragment`].
/// - `params_root`: Input consumed by [`crate::runtime::json_commands::render_app_fragment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_app_fragment`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_app_fragment(std::path::Path::new("apps/dev_docs"), todo!(), &serde_json::json!({}));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_app_fragment(
    app_root: &str,
    fragment_name: &str,
    params_root: &Value,
) -> Option<String> {
    render_app_fragment_from_doc(app_root, fragment_name, params_root)
}

/// Renders an app-owned fragment from an in-memory parameter document.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::json_commands::render_app_fragment_from_doc`].
/// - `fragment_name`: Input consumed by [`crate::runtime::json_commands::render_app_fragment_from_doc`].
/// - `params_root`: Input consumed by [`crate::runtime::json_commands::render_app_fragment_from_doc`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::render_app_fragment_from_doc`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::json_commands::render_app_fragment_from_doc`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::render_app_fragment_from_doc(std::path::Path::new("apps/dev_docs"), todo!(), &serde_json::json!({}));
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn render_app_fragment_from_doc(
    app_root: &str,
    fragment_name: &str,
    params_root: &Value,
) -> Option<String> {
    if app_root.is_empty()
        || fragment_name.is_empty()
        || fragment_name.contains("..")
        || Path::new(fragment_name).is_absolute()
        || !params_root.is_object()
    {
        return None;
    }
    render_template_text_with_default_kind(
        &fs::read_to_string(Path::new(app_root).join(fragment_name)).ok()?,
        params_root,
        "text",
    )
}

/// Reads one JSON document from bounded text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::json_commands::json_doc_load_text`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_doc_load_text`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_doc_load_text("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_doc_load_text(text: &str) -> Option<Value> {
    load_root_from(text)
}

/// Releases an optional JSON document.
///
/// # Parameters
///
/// - `document`: Input consumed by [`crate::runtime::json_commands::json_doc_free`].
///
/// # Returns
///
/// Returns after [`crate::runtime::json_commands::json_doc_free`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_doc_free(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_doc_free(document: &mut Option<Value>) {
    *document = None;
}

/// Returns one object member without cloning it.
///
/// # Parameters
///
/// - `object`: Input consumed by [`crate::runtime::json_commands::json_obj_get`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_obj_get`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_obj_get`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_obj_get(todo!(), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_obj_get<'a>(object: &'a Value, key: &str) -> Option<&'a Value> {
    object.as_object()?.get(key)
}

/// Returns one object array member.
///
/// # Parameters
///
/// - `object`: Input consumed by [`crate::runtime::json_commands::json_obj_get_array`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_obj_get_array`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_obj_get_array`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_obj_get_array(todo!(), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_obj_get_array<'a>(object: &'a Value, key: &str) -> Option<&'a Vec<Value>> {
    json_obj_get(object, key)?.as_array()
}

/// Duplicates one object string member.
///
/// # Parameters
///
/// - `object`: Input consumed by [`crate::runtime::json_commands::json_obj_get_string`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_obj_get_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_obj_get_string`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_obj_get_string(todo!(), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_obj_get_string(object: &Value, key: &str) -> Option<String> {
    json_obj_get(object, key)?.as_str().map(ToOwned::to_owned)
}

/// Reads one object integer member with a default.
///
/// # Parameters
///
/// - `object`: Input consumed by [`crate::runtime::json_commands::json_obj_get_long_default`].
/// - `key`: Input consumed by [`crate::runtime::json_commands::json_obj_get_long_default`].
/// - `default_value`: Input consumed by [`crate::runtime::json_commands::json_obj_get_long_default`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::json_commands::json_obj_get_long_default`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_obj_get_long_default(todo!(), "key", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_obj_get_long_default(object: &Value, key: &str, default_value: i64) -> i64 {
    json_obj_get(object, key)
        .and_then(Value::as_i64)
        .unwrap_or(default_value)
}

/// Reads a JSON integer value.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_long_from_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_long_from_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_long_from_value("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_long_from_value(value: &Value) -> Option<i64> {
    value.as_i64()
}

/// Serializes one JSON value compactly.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::json_commands::json_serialize_compact`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::json_commands::json_serialize_compact`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::json_commands::json_serialize_compact("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::json_commands`] for adjacent helpers that share the same runtime surface.
pub fn json_serialize_compact(value: &Value) -> Option<String> {
    serde_json::to_string(value).ok()
}

#[cfg(test)]
mod tests {
    /// Checks shared template binding, cycle limits and filesystem confinement.
    #[test]
    fn shared_template_includes_are_bounded_and_confined() {
        let workspace = std::path::Path::new("tmp/0.8.4-testing")
            .join(format!("template-includes-{}", std::process::id()));
        let root = workspace.join("templates");
        std::fs::create_dir_all(root.join("fragments")).unwrap();
        let page = root.join("page.html");
        let fragment = root.join("fragments/form.html");
        std::fs::write(&page, "{include:fragments/form.html}").unwrap();
        std::fs::write(&fragment, "<label>{name}</label>").unwrap();
        assert_eq!(
            super::render_file_template(&page, &serde_json::json!({"name":"<script>"})),
            Some("<label>&lt;script&gt;</label>".to_owned())
        );
        std::fs::write(&fragment, "{include:fragments/form.html}").unwrap();
        assert!(super::render_file_template(&page, &serde_json::json!({})).is_none());
        std::fs::write(&page, "{include:../outside.html}").unwrap();
        assert!(super::render_file_template(&page, &serde_json::json!({})).is_none());
        #[cfg(unix)]
        {
            std::fs::write(workspace.join("outside.html"), "outside").unwrap();
            std::os::unix::fs::symlink(
                "../../outside.html",
                fragment.with_file_name("escape.html"),
            )
            .unwrap();
            std::fs::write(&page, "{include:fragments/escape.html}").unwrap();
            assert!(super::render_file_template(&page, &serde_json::json!({})).is_none());
        }
        std::fs::remove_dir_all(workspace).unwrap();
    }
    #[test]
    fn service_initials_include_every_word() {
        for name in [
            "Initial Consultation (Online)",
            "Initial Consultation(Online)",
            "() Initial (Consultation) ((Online)) ()",
        ] {
            assert_eq!(super::dynamic_service_abbreviation(name), "ICO");
        }
        assert_eq!(super::dynamic_service_abbreviation(" () () "), "");
        assert_eq!(
            super::dynamic_service_abbreviation("  deep tissue massage therapy  "),
            "DTMT"
        );
        assert_eq!(
            super::dynamic_service_abbreviation("énergie relaxante"),
            "ÉR"
        );
        let app_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("apps/ucal");
        let visual = super::service_visual_html(
            &app_root,
            None,
            "deep tissue massage therapy",
            Some("#123456"),
        )
        .unwrap();
        assert!(visual.contains("DTMT"));
        let online = super::service_visual_html(
            &app_root,
            None,
            "Initial Consultation (Online)",
            Some("#123456"),
        )
        .unwrap();
        assert!(online.contains("<span>ICO</span>"));
    }
    #[test]
    fn service_order_picker_counts_only_active_services() {
        let app_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("apps/ucal");
        let state = serde_json::json!({"services": [
            {"business_id": 1, "is_active": true, "sort_order": 1},
            {"business_id": 1, "is_active": false, "sort_order": 99},
            {"business_id": 2, "is_active": true, "sort_order": 1}
        ]});
        let adding =
            super::service_sort_order_options_html(&app_root, &state, 1, 99, true).unwrap();
        let editing =
            super::service_sort_order_options_html(&app_root, &state, 1, 99, false).unwrap();
        assert_eq!(adding.matches("<option").count(), 2);
        assert_eq!(editing.matches("<option").count(), 1);
        assert!(adding.contains("value=\"2\" selected"));
        assert!(editing.contains("value=\"1\" selected"));
    }
    use super::*;

    #[test]
    fn appointments_page_params_render_user_appointment_rows() {
        let root = serde_json::json!({
            "businesses": [{"id": 7, "slug": "lotus-studio", "name": "Lotus Thai Massage"}],
            "services": [{"id": 3, "business_id": 7, "name": "Thai Massage", "duration_minutes": 60}],
            "appointments": [{
                "id": 11,
                "user_id": 42,
                "business_id": 7,
                "service_id": 3,
                "date": "2026-09-12",
                "time": "13:30",
                "status": "confirmed",
                "payment_status": "demo"
            }]
        });
        let params = dynamic_appointments_page_params_from_root_json(
            &root,
            42,
            Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/apps/ucal")),
        )
        .expect("appointments params");
        let params: Value = serde_json::from_str(&params).expect("json params");
        let html = params
            .get("appointment_items")
            .and_then(Value::as_str)
            .unwrap_or_default();
        assert!(html.contains("Thai Massage"));
        assert!(html.contains("Lotus Thai Massage"));
        assert!(html.contains("2026-09-12 at 1:30 PM"));
        assert!(!html.contains("No appointments"));
    }

    #[test]
    fn user_bookings_page_params_render_persisted_booking_rows() {
        let root = serde_json::json!({
            "bookings": [{
                "id": 4,
                "user_id": 9,
                "title": "Internal booking",
                "date": "2026-09-15",
                "time": "10:00",
                "status": "confirmed"
            }]
        });
        let params = dynamic_user_bookings_page_params_from_root_json(
            &root,
            9,
            Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/apps/ucal")),
        )
        .expect("bookings params");
        let params: Value = serde_json::from_str(&params).expect("json params");
        let html = params
            .get("booking_rows_html")
            .and_then(Value::as_str)
            .unwrap_or_default();
        assert!(html.contains("Internal booking"));
        assert!(html.contains("2026-09-15"));
        assert!(html.contains("10:00 AM"));
        assert!(!html.contains("No bookings yet"));
    }

    #[test]
    fn profile_page_params_render_signed_in_user_state() {
        let root = serde_json::json!({
            "users": [{
                "id": 2,
                "email": "customer@example.test",
                "display_name": "Customer One",
                "full_name": "Customer One",
                "phone_number": "555-0102",
                "address": "1 Market Road",
                "payment_preference": "credit_card"
            }],
            "businesses": [{"id": 1, "slug": "lotus-studio", "name": "Lotus Thai Massage"}],
            "subscriptions": [{"id": 1, "user_id": 2, "business_id": 1}],
            "google_calendar_connections": [{"id": 1, "user_id": 2, "connection_status": "connected"}]
        });
        let params = dynamic_profile_page_params_json(
            &root,
            2,
            Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/apps/ucal")),
        )
        .expect("profile");
        let params: Value = serde_json::from_str(&params).expect("json params");
        assert_eq!(
            params.get("full_name").and_then(Value::as_str),
            Some("Customer One")
        );
        assert_eq!(
            params
                .get("selected_payment_preference")
                .and_then(Value::as_str),
            Some("credit_card")
        );
        assert_eq!(
            params.get("google_status").and_then(Value::as_str),
            Some("connected")
        );
        assert!(
            params
                .get("subscription_rows_html")
                .and_then(Value::as_str)
                .unwrap_or_default()
                .contains("Lotus Thai Massage")
        );
    }

    #[test]
    fn appointment_detail_params_render_related_records() {
        let root = serde_json::json!({
            "users": [{"id": 2, "email": "customer@example.test", "full_name": "Customer One"}],
            "businesses": [{"id": 7, "owner_id": 1, "slug": "lotus-studio", "name": "Lotus Thai Massage"}],
            "services": [{"id": 3, "business_id": 7, "name": "Thai Massage"}],
            "appointments": [{
                "id": 11,
                "user_id": 2,
                "business_id": 7,
                "service_id": 3,
                "date": "2026-09-12",
                "time": "13:30",
                "status": "confirmed",
                "service_cost": "55",
                "notes": "Prefers afternoon"
            }]
        });
        let params = dynamic_appointment_detail_page_params_from_root_json(
            &root,
            2,
            11,
            Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/apps/ucal")),
        )
        .expect("appointment detail");
        let params: Value = serde_json::from_str(&params).expect("json params");
        assert_eq!(
            params.get("service_name").and_then(Value::as_str),
            Some("Thai Massage")
        );
        assert_eq!(
            params.get("business_name").and_then(Value::as_str),
            Some("Lotus Thai Massage")
        );
        assert_eq!(
            params.get("customer_name").and_then(Value::as_str),
            Some("Customer One")
        );
        assert!(
            params
                .get("notes_block")
                .and_then(Value::as_str)
                .unwrap_or_default()
                .contains("Prefers afternoon")
        );
    }

    /// Verifies both public states update their accessible label and visual class.
    #[test]
    fn business_public_toggle_matches_current_state() {
        let app_root = Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/apps/ucal"));
        for (public, label, class) in [
            (true, "Public", "business-is-public"),
            (false, "Private", "business-is-private"),
        ] {
            let html = dynamic_render_business_admin_public_state_button_html(
                app_root,
                "lotus-studio",
                public,
            )
            .expect("toggle");
            assert!(html.contains(&format!("aria-label=\"{label}\"")));
            assert!(html.contains(&format!("aria-pressed=\"{public}\"")));
            assert!(html.contains(class));
            assert!(!html.contains("style=\""));
        }
    }

    #[test]
    fn business_calendar_params_render_clickable_appointment_dialogs() {
        let root = serde_json::json!({
            "users": [{"id": 2, "email": "customer@example.test", "full_name": "Customer One"}],
            "businesses": [{"id": 7, "owner_id": 1, "slug": "lotus-studio", "name": "Lotus Thai Massage"}],
            "services": [{
                "id": 3,
                "business_id": 7,
                "name": "Thai Massage",
                "duration_minutes": 45,
                "booking_options": [
                    {
                        "label": "Extended Thai",
                        "duration_minutes": 75,
                        "cost": "90.00"
                    }
                ]
            }],
            "technicians": [{"id": 5, "business_id": 7, "name": "Tech One"}],
            "business_availability": [{"id": 1, "business_id": 7, "day_of_week": "Sat", "start_time": "08:00", "end_time": "16:00"}],
            "appointments": [{
                "id": 11,
                "user_id": 2,
                "business_id": 7,
                "service_id": 3,
                "technician_id": 5,
                "date": "2026-09-12",
                "time": "13:30",
                "end_time": "2026-09-12T14:15:00Z",
                "service_duration_minutes": 45,
                "status": "confirmed",
                "payment_status": "paid",
                "notes": "Prefers afternoon"
            },
            {
                "id": 12,
                "user_id": 2,
                "business_id": 7,
                "service_id": 3,
                "technician_id": 5,
                "date": "2026-09-13",
                "time": "13:30",
                "status": "confirmed",
                "payment_status": "paid",
                "notes": "Second day"
            }]
        });
        let before = pharos_runtime_core::time::current_timestamp_utc();
        let default_params = dynamic_business_calendar_template_params_from_root_json(
            &root,
            "lotus-studio",
            Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/apps/ucal")),
            None,
            None,
            None,
            2,
            "csrf-test-token",
        )
        .expect("default calendar params");
        let after = pharos_runtime_core::time::current_timestamp_utc();
        let default_params: Value =
            serde_json::from_str(&default_params).expect("default json params");
        let selected = default_params["selected_date"]
            .as_str()
            .expect("selected date");
        assert!(selected == &before[..10] || selected == &after[..10]);
        let params = dynamic_business_calendar_template_params_from_root_json(
            &root,
            "lotus-studio",
            Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/apps/ucal")),
            None,
            None,
            Some("2026-09-12"),
            2,
            "csrf-test-token",
        )
        .expect("calendar params");
        let params: Value = serde_json::from_str(&params).expect("json params");
        let html = params
            .get("appointment_rows_html")
            .and_then(Value::as_str)
            .unwrap_or_default();
        assert!(html.contains("data-dialog-open=\"business-calendar-appointment-11\""));
        assert!(html.contains("Thai Massage"));
        assert!(html.contains("Thai Massage · 45 min"));
        assert!(html.contains("Assigned: Tech One"));
        assert!(html.contains("<strong>1:30 PM–2:15 PM • 2026-09-12</strong> • Tech One"));
        assert!(html.contains("<span>Customer One • customer@example.test</span><span class=\"business-calendar-dialog-payment-status\">paid</span>"));
        assert!(html.contains("<strong>Notes:</strong> Prefers afternoon"));
        assert!(html.contains("csrf-test-token"));
        assert!(html.contains("/appointments/11/cancel/"));
        assert!(html.contains("/appointments/11/complete/"));
        assert!(html.contains("business-calendar-dialog-title-row"));
        assert!(html.contains("aria-label=\"Assign Technician\""));
        assert!(!html.contains("title=\"Assign Technician\""));
        let internal_dialog_html = params
            .get("internal_booking_dialog_html")
            .and_then(Value::as_str)
            .unwrap_or_default();
        assert!(internal_dialog_html.contains("business-calendar-internal-booking"));
        assert!(internal_dialog_html.contains("/business/lotus-studio/calendar/appointments/new/"));
        assert!(internal_dialog_html.contains("value=\"3\" data-booking-option-index=\"\""));
        assert!(internal_dialog_html.contains("Thai Massage · 45 min"));
        assert!(internal_dialog_html.contains("data-booking-option-index=\"0\""));
        assert!(internal_dialog_html.contains("Thai Massage · Extended Thai · 75 min"));
        assert!(internal_dialog_html.contains("data-calendar-booking-option-index"));
        assert!(internal_dialog_html.contains("data-calendar-booking-technician"));
        let calendar_html = params
            .get("calendar_rows_html")
            .and_then(Value::as_str)
            .unwrap_or_default();
        assert!(
            calendar_html.contains("background:var(--primary);color:#fff;"),
            "selected day remains blue"
        );
        assert!(
            calendar_html.contains("background:#dcfce7;color:#166534;"),
            "non-selected booked days render light green"
        );
        assert!(
            calendar_html.contains("has-appointments"),
            "booked days include an appointment state class"
        );
        assert!(
            calendar_html.contains("background:var(--gray-200);color:var(--gray-700);"),
            "unbooked days remain grey"
        );
    }

    #[test]
    fn architect_layout_hides_builder_settings_until_authenticated() {
        let app_root = Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/apps/architect"));
        let anonymous = template_layout_page_html(
            app_root,
            Some("/architect"),
            Some("architect_shell"),
            Some("en"),
            "Architect Sign In",
            "<section>login</section>",
            Some("/accounts/login/"),
            false,
            0,
        )
        .expect("anonymous architect layout");
        assert!(anonymous.contains("Pharos Architect"));
        assert!(!anonymous.contains(r#"aria-label="Home""#));
        assert!(!anonymous.contains(r#"aria-label="Settings""#));
        assert!(!anonymous.contains(r#"aria-label="File""#));
        assert!(!anonymous.contains("/architect/settings"));
        assert!(!anonymous.contains("/architect/editor"));

        let build_user = template_layout_page_html(
            app_root,
            Some("/architect"),
            Some("architect_shell"),
            Some("en"),
            "Pharos Architect",
            "<section>builder</section>",
            Some("/"),
            true,
            1,
        )
        .expect("build user architect layout");
        assert!(build_user.contains(r#"class="nav-icon-button architect-nav-file-link""#));
        assert!(build_user.contains(r#"aria-label="Home""#));
        assert!(build_user.contains(r#"aria-label="File""#));
        assert!(build_user.contains(r#"aria-label="Settings""#));
        assert!(build_user.contains(r#"hx-get="/architect/settings""#));
        assert!(build_user.contains(r#"hx-get="/architect/editor""#));
        assert!(build_user.contains(r#"<span class="nav-button__tooltip">Home</span>"#));
        assert!(build_user.contains(r#"<span class="nav-button__tooltip">File</span>"#));
        assert!(build_user.contains(r#"<span class="nav-button__tooltip">Settings</span>"#));
        assert!(build_user.contains("/architect/settings"));
        assert!(build_user.contains("/architect/editor"));
        assert!(build_user.contains(r#"aria-label="Log out""#));
        assert!(build_user.contains(r#"class="nav-button__icon""#));
        assert!(build_user.contains(r#"bi-box-arrow-right"#));
        assert!(build_user.contains(r#"action="/architect/accounts/logout/""#));

        let admin = template_layout_page_html(
            app_root,
            Some("/architect"),
            Some("architect_shell"),
            Some("en"),
            "Pharos Architect",
            "<section>builder</section>",
            Some("/"),
            true,
            1,
        )
        .expect("admin architect layout");
        assert!(admin.contains(r#"aria-label="Home""#));
        assert!(admin.contains(r#"aria-label="File""#));
        assert!(admin.contains(r#"aria-label="Settings""#));
        assert!(admin.contains(r#"hx-get="/architect/settings""#));
        assert!(admin.contains(r#"hx-get="/architect/editor""#));
        assert!(admin.contains(r#"<span class="nav-button__tooltip">Settings</span>"#));
        assert!(admin.contains("/architect/settings"));
    }

    #[test]
    fn layout_browser_title_prefixes_app_name_without_duplicate_branding() {
        let app_root =
            std::env::temp_dir().join(format!("pharos-title-test-{}", std::process::id()));
        std::fs::create_dir_all(&app_root).expect("create title fixture app");
        std::fs::write(
            app_root.join("pharos.app.json"),
            r#"{"app_id":"commerce_test","name":"Beacon Beats"}"#,
        )
        .expect("write title fixture manifest");

        assert_eq!(
            layout_browser_title(&app_root, "Checkout"),
            "Beacon Beats - Checkout"
        );
        assert_eq!(
            layout_browser_title(&app_root, "Checkout — Beacon Beats"),
            "Beacon Beats - Checkout"
        );
        assert_eq!(
            layout_browser_title(&app_root, "Beacon Beats — Audio that moves the room"),
            "Beacon Beats - Audio that moves the room"
        );

        std::fs::remove_dir_all(app_root).ok();
    }
}