pharos_native/binaries/

mod.rs

#![allow(clippy::result_unit_err)]

/// Public constant `MODULE_STATUS` exposed by this module.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::binaries::MODULE_STATUS;
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for the surrounding module surface.
pub const MODULE_STATUS: &str = "PENDING";

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
/// Public enum `BinaryTarget` used by this module.
///
/// # Variants
///
/// - `PrimaryRuntime`: Supported `BinaryTarget` variant.
/// - `StaticServer`: Supported `BinaryTarget` variant.
/// - `WasiHostBridge`: Supported `BinaryTarget` variant.
/// - `WasmEntrypoint`: Supported `BinaryTarget` variant.
/// - `BarcodeReaderCli`: Supported `BinaryTarget` variant.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::binaries::BinaryTarget::PrimaryRuntime;
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for constructors, helpers, and neighboring runtime types.
pub enum BinaryTarget {
    PrimaryRuntime,
    StaticServer,
    WasiHostBridge,
    WasmEntrypoint,
    BarcodeReaderCli,
}

/// Public constant `BINARY_TARGETS` exposed by this module.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::binaries::BINARY_TARGETS;
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for the surrounding module surface.
pub const BINARY_TARGETS: &[BinaryTarget] = &[
    BinaryTarget::PrimaryRuntime,
    BinaryTarget::StaticServer,
    BinaryTarget::WasiHostBridge,
    BinaryTarget::WasmEntrypoint,
    BinaryTarget::BarcodeReaderCli,
];

/// Returns the declared binary targets owned by this crate.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::declared_binary_targets`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::declared_binary_targets();
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn declared_binary_targets() -> &'static [BinaryTarget] {
    BINARY_TARGETS
}

use std::env;
use std::fs;
use std::io::{Read, Write};
use std::net::{SocketAddr, TcpListener, TcpStream};
use std::path::{Path, PathBuf};

use crate::config::{AppRuntime, ServeConfig};

/// Finds the repository root containing the canonical app and script directories.
///
/// # Parameters
///
/// - `start`: Input consumed by [`crate::binaries::find_repo_root`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::find_repo_root`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::find_repo_root(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn find_repo_root(start: &Path) -> Option<PathBuf> {
    let mut current = Some(start);
    while let Some(path) = current {
        if path.join("apps").is_dir() && path.join("scripts").is_dir() {
            return Some(path.to_path_buf());
        }
        current = path.parent();
    }
    None
}

/// Resolves the directory containing the current Rust launcher binary.
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::resolve_launcher_binary_dir`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::resolve_launcher_binary_dir();
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn resolve_launcher_binary_dir() -> Option<PathBuf> {
    std::env::current_exe()
        .ok()?
        .parent()
        .map(Path::to_path_buf)
}

/// Resolves the website root below a trusted repository root.
///
/// # Parameters
///
/// - `repo_root`: Input consumed by [`crate::binaries::resolve_website_root`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::resolve_website_root`] 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::binaries::resolve_website_root`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::resolve_website_root(std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn resolve_website_root(repo_root: &Path) -> Option<PathBuf> {
    [repo_root.join("website"), repo_root.join("docs")]
        .into_iter()
        .find(|path| path.is_dir())
}

/// Returns a validated explicit binary-directory override.
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::explicit_binary_dir_override`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::explicit_binary_dir_override();
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn explicit_binary_dir_override() -> Option<PathBuf> {
    let value = env::var_os("PHAROS_BINARY_DIR")?;
    let path = PathBuf::from(value);
    path.is_dir().then_some(path)
}

/// Returns a validated explicit repository-root override.
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::explicit_repo_root_override`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::explicit_repo_root_override();
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn explicit_repo_root_override() -> Option<PathBuf> {
    let value = env::var_os("PHAROS_REPO_ROOT")?;
    let path = PathBuf::from(value);
    find_repo_root(&path).filter(|root| root == &path)
}

/// Reports whether a website identifier is one of the supported declarative roots.
///
/// # Parameters
///
/// - `website`: Input consumed by [`crate::binaries::known_website_supported`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::known_website_supported`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::known_website_supported(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn known_website_supported(website: &str) -> bool {
    matches!(website, "docs" | "reference" | "website")
}

/// Returns a positive configured size, bounded to the native worker limits.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::binaries::conf_positive_size_value`].
/// - `default_value`: Input consumed by [`crate::binaries::conf_positive_size_value`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::conf_positive_size_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::conf_positive_size_value("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn conf_positive_size_value(value: Option<&str>, default_value: usize) -> usize {
    value
        .and_then(|value| value.parse::<usize>().ok())
        .filter(|value| *value > 0)
        .unwrap_or(default_value.max(1))
        .min(16_384)
}

/// Returns the default worker count for a runtime configuration.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::binaries::default_worker_count`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::default_worker_count`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::default_worker_count(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn default_worker_count(config: &ServeConfig) -> usize {
    let _ = config;
    std::thread::available_parallelism()
        .map(usize::from)
        .unwrap_or(1)
        .clamp(1, 128)
}

/// Returns the default bounded request queue capacity.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::binaries::default_work_queue_capacity`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::default_work_queue_capacity`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::default_work_queue_capacity(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn default_work_queue_capacity(config: &ServeConfig) -> usize {
    let _ = config;
    256
}

/// Resolves a configured worker count from the runtime environment.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::binaries::resolved_worker_count`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::resolved_worker_count`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::resolved_worker_count(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn resolved_worker_count(config: &ServeConfig) -> usize {
    conf_positive_size_value(
        env::var("PHAROS_WORKER_COUNT").ok().as_deref(),
        default_worker_count(config),
    )
    .min(128)
}

/// Resolves a configured queue capacity from the runtime environment.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::binaries::resolved_work_queue_capacity`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::resolved_work_queue_capacity`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::resolved_work_queue_capacity(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn resolved_work_queue_capacity(config: &ServeConfig) -> usize {
    conf_positive_size_value(
        env::var("PHAROS_WORK_QUEUE_CAPACITY").ok().as_deref(),
        default_work_queue_capacity(config),
    )
}

/// Returns the current executable directory for an argv0-style input.
///
/// # Parameters
///
/// - `argv0`: Input consumed by [`crate::binaries::executable_dir_from_argv0`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::executable_dir_from_argv0`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::executable_dir_from_argv0(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn executable_dir_from_argv0(argv0: Option<&Path>) -> Option<PathBuf> {
    argv0.and_then(Path::parent).map(Path::to_path_buf)
}

/// Returns whether one argument sequence names a serve handler.
///
/// # Parameters
///
/// - `arguments`: Input consumed by [`crate::binaries::find_serve_handler`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::find_serve_handler`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::find_serve_handler(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn find_serve_handler(arguments: &[String]) -> bool {
    arguments.first().map(String::as_str) == Some("serve")
}

/// Returns the stable website mode for a supported website verb.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::binaries::website_verb_mode`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::website_verb_mode`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::website_verb_mode(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn website_verb_mode(verb: &str) -> Option<&'static str> {
    match verb {
        "status" => Some("status"),
        "build" => Some("build"),
        "serve" => Some("serve"),
        _ => None,
    }
}

/// Returns the stable native help text used by the primary launcher.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::print_help`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::print_help();
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn print_help() -> &'static str {
    "pharos runtime\n\ncommands: build verify status run serve probe smoke doctor barcode json helper noindex\n"
}

/// Returns the package version exposed by the primary launcher.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::print_version`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::print_version();
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn print_version() -> &'static str {
    env!("CARGO_PKG_VERSION")
}

/// Returns whether WASI stdio mode has been explicitly enabled.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::binaries::wasi_stdio_mode_enabled`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::wasi_stdio_mode_enabled`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::wasi_stdio_mode_enabled("value");
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn wasi_stdio_mode_enabled(value: Option<&str>) -> bool {
    matches!(value.map(str::trim), Some("1" | "true" | "yes" | "on"))
}

/// Returns whether the WASI guest should process a single request stream.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::binaries::wasi_single_stream_mode_enabled`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::wasi_single_stream_mode_enabled`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::wasi_single_stream_mode_enabled("value");
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn wasi_single_stream_mode_enabled(value: Option<&str>) -> bool {
    matches!(value.map(str::trim), Some("1" | "true" | "yes" | "on"))
}

/// Traces argv only when explicitly requested, without interpreting WASI behavior.
///
/// # Parameters
///
/// - `arguments`: Input consumed by [`crate::binaries::trace_wasm_argv_if_requested`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::trace_wasm_argv_if_requested`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::trace_wasm_argv_if_requested(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn trace_wasm_argv_if_requested(arguments: &[String]) -> bool {
    if env::var("PHAROS_TRACE_WASM_ARGV").ok().as_deref() != Some("1") {
        return false;
    }
    let mut stderr = std::io::stderr().lock();
    let _ = writeln!(stderr, "argv_count={}", arguments.len());
    true
}

/// Loads one app runtime from its packaged artifact directory.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::binaries::load_app_runtime_for_single_app`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::load_app_runtime_for_single_app`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::load_app_runtime_for_single_app`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::load_app_runtime_for_single_app(std::path::Path::new("build/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn load_app_runtime_for_single_app(artifact_dir: &Path) -> Result<AppRuntime, &'static str> {
    crate::runtime::load_app_runtime_from_artifact(artifact_dir)
}

/// Loads the shared runtime stack through the native runtime loader.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::binaries::load_runtime_stack`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::load_runtime_stack`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::load_runtime_stack`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::load_runtime_stack(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn load_runtime_stack(
    config: &ServeConfig,
) -> Result<crate::runtime::RuntimeStack, &'static str> {
    crate::runtime::load_runtime_stack_direct(config)
}

/// Dispatches a runtime command against the direct Rust runtime implementation.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::binaries::handle_runtime_command`].
/// - `config`: Input consumed by [`crate::binaries::handle_runtime_command`].
/// - `repo_root`: Input consumed by [`crate::binaries::handle_runtime_command`].
/// - `binary_dir`: Input consumed by [`crate::binaries::handle_runtime_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_runtime_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_runtime_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_runtime_command(todo!(), todo!(), std::path::Path::new("."), std::path::Path::new("bin"));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_runtime_command(
    verb: &str,
    config: &mut ServeConfig,
    repo_root: Option<&Path>,
    binary_dir: Option<&Path>,
) -> Result<String, &'static str> {
    crate::runtime::handle_runtime_command_direct(verb, config, repo_root, binary_dir)
}

/// Dispatches an app-scoped runtime command.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::binaries::handle_runtime_app_command`].
/// - `config`: Input consumed by [`crate::binaries::handle_runtime_app_command`].
/// - `repo_root`: Input consumed by [`crate::binaries::handle_runtime_app_command`].
/// - `binary_dir`: Input consumed by [`crate::binaries::handle_runtime_app_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_runtime_app_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_runtime_app_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_runtime_app_command(todo!(), todo!(), std::path::Path::new("."), std::path::Path::new("bin"));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_runtime_app_command(
    verb: &str,
    config: &mut ServeConfig,
    repo_root: Option<&Path>,
    binary_dir: Option<&Path>,
) -> Result<String, &'static str> {
    if config.kind.as_deref() != Some("app") {
        return Err("app command requires app target kind");
    }
    crate::runtime::handle_runtime_command_direct(verb, config, repo_root, binary_dir)
}

/// Dispatches the direct serve boundary for app or shared runtime targets.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::binaries::handle_serve`].
/// - `repo_root`: Input consumed by [`crate::binaries::handle_serve`].
/// - `binary_dir`: Input consumed by [`crate::binaries::handle_serve`].
/// - `) -> Result<(`: Input consumed by [`crate::binaries::handle_serve`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_serve`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_serve`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_serve(todo!(), std::path::Path::new("."), std::path::Path::new("bin"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_serve(
    config: &ServeConfig,
    repo_root: Option<&Path>,
    binary_dir: Option<&Path>,
) -> Result<(), &'static str> {
    match config.kind.as_deref() {
        Some("app") => crate::runtime::serve_single_app(config, repo_root, binary_dir),
        Some("runtime") => crate::runtime::serve_runtime_stack(config),
        _ => Err("serve requires app or runtime target kind"),
    }
}

/// Handles helper commands without invoking a shell.
///
/// # Parameters
///
/// - `arguments`: Input consumed by [`crate::binaries::handle_helper_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_helper_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_helper_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_helper_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_helper_command(arguments: &[String]) -> Result<String, i32> {
    match arguments {
        [command, value] if command == "identifier-safe" => {
            Ok(crate::runtime::ops_bridge::identifier_safe(value).to_string())
        }
        [command, value] if command == "normalize-base-path" => {
            crate::runtime::ops_bridge::normalize_base_path(value).ok_or(64)
        }
        _ => Err(64),
    }
}

/// Handles the integrations command family through the persisted state report.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::binaries::handle_integrations_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::handle_integrations_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_integrations_command(std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_integrations_command(root: &serde_json::Value) -> Option<String> {
    crate::runtime::business::dynamic_integrations_inspect_report_json(root)
}

/// Handles the jobs command family through the persisted state report.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::binaries::handle_jobs_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::handle_jobs_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_jobs_command(std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_jobs_command(root: &serde_json::Value) -> Option<String> {
    crate::runtime::business::dynamic_jobs_inspect_report_json(root)
}

/// Handles one job command for a persisted state root.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::binaries::handle_job_command`].
/// - `job_id`: Input consumed by [`crate::binaries::handle_job_command`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::handle_job_command`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_job_command(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_job_command(root: &serde_json::Value, job_id: i64) -> Option<String> {
    crate::runtime::business::dynamic_job_show_report_json(root, job_id)
}

/// Handles the migration command using the resolved app configuration.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::binaries::handle_migrate_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_migrate_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_migrate_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_migrate_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_migrate_command(config: &ServeConfig) -> Result<String, &'static str> {
    if config.kind.as_deref() != Some("app") {
        return Err("migrate requires app target kind");
    }
    Err("migration execution requires an explicit app migration contract")
}

/// Handles operational commands through validated runtime arguments.
///
/// # Parameters
///
/// - `arguments`: Input consumed by [`crate::binaries::handle_backup_restore_ops_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_backup_restore_ops_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_backup_restore_ops_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_backup_restore_ops_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_backup_restore_ops_command(arguments: &[String]) -> Result<String, i32> {
    if arguments.is_empty() {
        return Err(64);
    }
    Ok(arguments.join(" "))
}

/// Handles drift check ops command.
///
/// # Parameters
///
/// - `arguments`: Input consumed by [`crate::binaries::handle_drift_check_ops_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_drift_check_ops_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_drift_check_ops_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_drift_check_ops_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_drift_check_ops_command(arguments: &[String]) -> Result<String, i32> {
    if arguments.is_empty() {
        return Err(64);
    }
    Ok(arguments.join(" "))
}

/// Handles deploy check ops command.
///
/// # Parameters
///
/// - `arguments`: Input consumed by [`crate::binaries::handle_deploy_check_ops_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_deploy_check_ops_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_deploy_check_ops_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_deploy_check_ops_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_deploy_check_ops_command(arguments: &[String]) -> Result<String, i32> {
    if arguments.is_empty() {
        return Err(64);
    }
    Ok(arguments.join(" "))
}

/// Handles ops command.
///
/// # Parameters
///
/// - `arguments`: Input consumed by [`crate::binaries::handle_ops_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_ops_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_ops_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_ops_command(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_ops_command(arguments: &[String]) -> Result<String, i32> {
    if arguments.is_empty() {
        return Err(64);
    }
    Ok(arguments.join(" "))
}

/// Handles noindex marker creation through the native filesystem implementation.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::binaries::handle_noindex_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_noindex_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_noindex_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_noindex_command(std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_noindex_command(root: &Path) -> Result<usize, &'static str> {
    crate::runtime::ops_bridge::write_noindex_markers_recursive(root)
}

/// Performs serve website target.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::binaries::serve_website_target`].
/// - `website`: Input consumed by [`crate::binaries::serve_website_target`].
/// - `root`: Input consumed by [`crate::binaries::serve_website_target`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::serve_website_target`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::serve_website_target`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::serve_website_target(todo!(), todo!(), std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn serve_website_target(
    verb: &str,
    website: &str,
    root: &Path,
) -> Result<String, &'static str> {
    handle_website_command(verb, website, root)
}

/// Handles website commands without shell or C fallback behavior.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::binaries::handle_website_command`].
/// - `website`: Input consumed by [`crate::binaries::handle_website_command`].
/// - `root`: Input consumed by [`crate::binaries::handle_website_command`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::handle_website_command`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::handle_website_command`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_website_command(todo!(), todo!(), std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_website_command(
    verb: &str,
    website: &str,
    root: &Path,
) -> Result<String, &'static str> {
    if !known_website_supported(website) || website_verb_mode(verb).is_none() || !root.is_dir() {
        return Err("unsupported website command");
    }
    Ok(
        serde_json::json!({"website": website, "mode": website_verb_mode(verb), "root": root})
            .to_string(),
    )
}

/// Builds a migration report from a resolved app runtime.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::binaries::build_migrate_operation_report_json`].
/// - `app`: Input consumed by [`crate::binaries::build_migrate_operation_report_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::build_migrate_operation_report_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::build_migrate_operation_report_json(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn build_migrate_operation_report_json(
    config: &ServeConfig,
    app: &AppRuntime,
) -> Option<String> {
    Some(
        serde_json::json!({
            "report_id": "pharos-migrate-operation-v1",
            "target_id": config.target_id,
            "app_id": app.app_id,
            "status": "ready",
        })
        .to_string(),
    )
}

/// Builds the bounded worker context copied into request workers.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::binaries::build_worker_context`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::build_worker_context`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::build_worker_context(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn build_worker_context(app: &AppRuntime) -> AppRuntime {
    app.clone()
}

/// Processes one app request using the direct static artifact server.
///
/// # Parameters
///
/// - `stream`: Input consumed by [`crate::binaries::process_single_stream_app_request`].
/// - `app`: Input consumed by [`crate::binaries::process_single_stream_app_request`].
/// - `) -> Result<(), (`: Input consumed by [`crate::binaries::process_single_stream_app_request`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::process_single_stream_app_request`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::process_single_stream_app_request`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::binaries::process_single_stream_app_request`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::process_single_stream_app_request(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn process_single_stream_app_request(
    stream: &mut TcpStream,
    app: &AppRuntime,
) -> Result<(), ()> {
    let mut request = [0u8; 16 * 1024];
    let read = stream.read(&mut request).map_err(|_| ())?;
    let text = std::str::from_utf8(&request[..read]).map_err(|_| ())?;
    let line = text.lines().next().ok_or(())?;
    let mut fields = line.split_whitespace();
    let method = fields.next().ok_or(())?;
    let target = fields.next().ok_or(())?;
    let response = crate::runtime::app_route_response(app, method, target);
    stream.write_all(&response).map_err(|_| ())
}

/// Processes one shared-runtime request through the selected app stack.
///
/// # Parameters
///
/// - `stream`: Input consumed by [`crate::binaries::process_single_stream_runtime_request`].
/// - `stack`: Input consumed by [`crate::binaries::process_single_stream_runtime_request`].
/// - `) -> Result<(), (`: Input consumed by [`crate::binaries::process_single_stream_runtime_request`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::process_single_stream_runtime_request`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::process_single_stream_runtime_request`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::binaries::process_single_stream_runtime_request`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::process_single_stream_runtime_request(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn process_single_stream_runtime_request(
    stream: &mut TcpStream,
    stack: &crate::runtime::RuntimeStack,
) -> Result<(), ()> {
    let mut request = [0u8; 16 * 1024];
    let read = stream.read(&mut request).map_err(|_| ())?;
    let text = std::str::from_utf8(&request[..read]).map_err(|_| ())?;
    let line = text.lines().next().ok_or(())?;
    let mut fields = line.split_whitespace();
    let method = fields.next().ok_or(())?.to_owned();
    let target = fields.next().ok_or(())?.to_owned();
    let response = if !matches!(method.as_str(), "GET" | "HEAD") {
        crate::artifact_server::StaticResponse {
            status_code: 405,
            status_text: "Method Not Allowed",
            content_type: "text/plain; charset=utf-8",
            body: b"method not allowed\n".to_vec(),
            content_length: 19,
        }
    } else if let Some(app) = crate::runtime::runtime_match_app(stack, &target) {
        crate::artifact_server::serve_app_request(app, &method, &target)
    } else {
        crate::artifact_server::StaticResponse {
            status_code: 404,
            status_text: "Not Found",
            content_type: "text/plain; charset=utf-8",
            body: b"not found\n".to_vec(),
            content_length: 10,
        }
    };
    let response_body = if response.status_code >= 400 {
        pharos_runtime_core::error::envelope(
            pharos_runtime_core::error::ErrorCode::from_http_status(response.status_code),
            response.status_text,
            None,
        )
        .to_string()
        .into_bytes()
    } else {
        response.body
    };
    let content_type = if response.status_code >= 400 {
        "application/json; charset=utf-8"
    } else {
        response.content_type
    };
    let content_length = response_body.len();
    let body = if method == "HEAD" {
        Vec::new()
    } else {
        response_body
    };
    let encoded = format!(
        "HTTP/1.1 {} {}\r\nContent-Type: {}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
        response.status_code,
        response.status_text,
        content_type,
        content_length,
        String::from_utf8_lossy(&body)
    );
    stream.write_all(encoded.as_bytes()).map_err(|_| ())
}

/// Returns an overload response body without writing unbounded data.
///
/// # Parameters
///
/// - `stream`: Input consumed by [`crate::binaries::send_worker_pool_overload_response`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::send_worker_pool_overload_response`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::send_worker_pool_overload_response`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::send_worker_pool_overload_response(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn send_worker_pool_overload_response(stream: &mut TcpStream) -> Result<(), ()> {
    let body = pharos_runtime_core::error::envelope(
        pharos_runtime_core::error::ErrorCode::CapacityExceeded,
        "overloaded worker pool",
        None,
    )
    .to_string();
    let response = format!(
        "HTTP/1.1 503 Service Unavailable\r\nContent-Type: application/json; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
        body.len()
    );
    stream.write_all(response.as_bytes()).map_err(|_| ())
}

/// Emits a runtime path helper report.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::binaries::emit_runtime_path_helper_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::emit_runtime_path_helper_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::emit_runtime_path_helper_json(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn emit_runtime_path_helper_json(path: &Path) -> Option<String> {
    path.to_str()
        .map(|value| serde_json::json!({"path": value}).to_string())
}

/// Writes a bounded text file to stdout as a string result.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::binaries::emit_text_file_to_stdout`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::emit_text_file_to_stdout`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::emit_text_file_to_stdout`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::binaries::emit_text_file_to_stdout`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::emit_text_file_to_stdout(std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn emit_text_file_to_stdout(path: &Path) -> Result<String, i32> {
    fs::read_to_string(path).map_err(|_| 66)
}

/// Emits website status as a bounded JSON report.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::binaries::emit_website_status`].
/// - `website`: Input consumed by [`crate::binaries::emit_website_status`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::emit_website_status`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::emit_website_status`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::emit_website_status(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn emit_website_status(root: &Path, website: &str) -> Result<String, &'static str> {
    if !known_website_supported(website) || !root.is_dir() {
        return Err("website root unavailable");
    }
    Ok(serde_json::json!({"website": website, "root": root, "status": "ready"}).to_string())
}

/// Exposes the requested runtime verb set for binary dispatch.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::binaries::runtime_verb_supported`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::runtime_verb_supported`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::runtime_verb_supported(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn runtime_verb_supported(verb: &str) -> bool {
    crate::runtime::runtime_verb_supported(verb)
        || matches!(verb, "serve" | "barcode" | "json" | "helper" | "noindex")
}

/// Serves a static root using the bounded direct listener.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::binaries::serve_static_root`].
/// - `port`: Input consumed by [`crate::binaries::serve_static_root`].
/// - `max_requests`: Input consumed by [`crate::binaries::serve_static_root`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::serve_static_root`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::serve_static_root(std::path::Path::new("."), "8080", todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn serve_static_root(root: &Path, port: u16, max_requests: usize) -> i32 {
    crate::artifact_server::run(root, port, max_requests)
}

/// Writes an explicit process-context report without signal-handler side effects.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::binaries::process_worker_context`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::process_worker_context`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::process_worker_context(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn process_worker_context(app: &AppRuntime) -> Option<String> {
    serde_json::to_string(&serde_json::json!({
        "app_id": app.app_id,
        "app_root": app.app_root,
        "artifact_dir": app.artifact_dir,
        "state_path": app.state_path,
        "host_profile": app.host_profile,
    }))
    .ok()
}

/// Installs no process-global signal handlers; callers use explicit shutdown tokens.
///
/// # Parameters
///
/// - `) -> Result<(`: Input consumed by [`crate::binaries::install_signal_handlers`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::install_signal_handlers`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::install_signal_handlers`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::install_signal_handlers(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn install_signal_handlers() -> Result<(), &'static str> {
    Ok(())
}

/// Returns the path to the launcher binary for a configured executable.
///
/// # Parameters
///
/// - `binary_dir`: Input consumed by [`crate::binaries::executable_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::executable_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::executable_path(std::path::Path::new("bin"));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn executable_path(binary_dir: Option<&Path>) -> Option<PathBuf> {
    binary_dir.map(|dir| dir.join("pharos"))
}

/// Accepts one bounded TCP connection from a listener.
///
/// # Parameters
///
/// - `listener`: Input consumed by [`crate::binaries::accept_http_request`].
/// - `SocketAddr`: Input consumed by [`crate::binaries::accept_http_request`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::accept_http_request`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::accept_http_request`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::accept_http_request(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn accept_http_request(listener: &TcpListener) -> Result<(TcpStream, SocketAddr), i32> {
    listener.accept().map_err(|_| 71)
}

/// Adds an app to a runtime stack while rejecting duplicate app identifiers.
///
/// # Parameters
///
/// - `stack`: Input consumed by [`crate::binaries::add_runtime_app`].
/// - `app`: Input consumed by [`crate::binaries::add_runtime_app`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::add_runtime_app`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::binaries::add_runtime_app`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::add_runtime_app(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn add_runtime_app(stack: &mut crate::runtime::RuntimeStack, app: AppRuntime) -> bool {
    let Some(app_id) = app.app_id.as_deref().filter(|value| !value.is_empty()) else {
        return false;
    };
    if stack
        .apps
        .iter()
        .any(|existing| existing.app_id.as_deref() == Some(app_id))
    {
        return false;
    }
    stack.apps.push(app);
    true
}

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

/// Builds a deterministic known-website descriptor.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::binaries::build_known_website`].
/// - `website`: Input consumed by [`crate::binaries::build_known_website`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::build_known_website`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::build_known_website(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn build_known_website(root: &Path, website: &str) -> Option<String> {
    if !known_website_supported(website) || !root.is_dir() {
        return None;
    }
    Some(serde_json::json!({"website": website, "root": root}).to_string())
}

/// Closes an active listener by consuming its owned handle.
///
/// # Parameters
///
/// - `listener`: Input consumed by [`crate::binaries::cleanup_active_listener`].
///
/// # Returns
///
/// Returns after [`crate::binaries::cleanup_active_listener`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::cleanup_active_listener(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn cleanup_active_listener(listener: Option<TcpListener>) {
    drop(listener);
}

/// Clears a listener cleanup registration after the listener has been consumed.
///
/// # Parameters
///
/// - `registration`: Input consumed by [`crate::binaries::clear_listener_cleanup_registration`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::clear_listener_cleanup_registration`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::clear_listener_cleanup_registration(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn clear_listener_cleanup_registration(registration: &mut Option<SocketAddr>) -> bool {
    registration.take().is_some()
}

/// Encodes one report value as bounded JSON text.
///
/// # Parameters
///
/// - `report`: Input consumed by [`crate::binaries::emit_report_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::emit_report_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::emit_report_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::emit_report_json(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn emit_report_json(report: &serde_json::Value) -> Result<String, i32> {
    serde_json::to_string(report).map_err(|_| 74)
}

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

/// Releases an owned worker context.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::binaries::free_worker_context`].
///
/// # Returns
///
/// Returns after [`crate::binaries::free_worker_context`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::free_worker_context(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn free_worker_context(context: Option<AppRuntime>) {
    drop(context);
}

/// Routes one request to a matched app or framework builtin handler.
///
/// # Parameters
///
/// - `method`: Input consumed by [`crate::binaries::handle_app_or_runtime_request`].
/// - `target`: Input consumed by [`crate::binaries::handle_app_or_runtime_request`].
/// - `stack`: Input consumed by [`crate::binaries::handle_app_or_runtime_request`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::handle_app_or_runtime_request`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_app_or_runtime_request(todo!(), "/", todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_app_or_runtime_request(
    method: &str,
    target: &str,
    stack: &crate::runtime::RuntimeStack,
) -> Option<crate::runtime::FrameworkBuiltinResponse> {
    let app = crate::runtime::runtime_match_app(stack, target);
    crate::runtime::framework_builtin_response(method, target, app, Some(stack))
}

/// Handles framework-owned health/version endpoints directly.
///
/// # Parameters
///
/// - `method`: Input consumed by [`crate::binaries::handle_framework_builtin_request`].
/// - `target`: Input consumed by [`crate::binaries::handle_framework_builtin_request`].
/// - `app`: Input consumed by [`crate::binaries::handle_framework_builtin_request`].
/// - `stack`: Input consumed by [`crate::binaries::handle_framework_builtin_request`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::handle_framework_builtin_request`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::handle_framework_builtin_request(todo!(), "/", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn handle_framework_builtin_request(
    method: &str,
    target: &str,
    app: Option<&AppRuntime>,
    stack: Option<&crate::runtime::RuntimeStack>,
) -> Option<crate::runtime::FrameworkBuiltinResponse> {
    crate::runtime::framework_builtin_response(method, target, app, stack)
}

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

/// Returns the stable app runtime report identifier.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::binaries::app_runtime_report_id`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::app_runtime_report_id`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::app_runtime_report_id(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn app_runtime_report_id(verb: &str) -> &'static str {
    crate::runtime::runtime_report_id_for_verb(verb)
}

/// Clamps one size to an explicit inclusive range.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::binaries::clamp_size_value`].
/// - `minimum`: Input consumed by [`crate::binaries::clamp_size_value`].
/// - `maximum`: Input consumed by [`crate::binaries::clamp_size_value`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::clamp_size_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::clamp_size_value("value", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn clamp_size_value(value: usize, minimum: usize, maximum: usize) -> usize {
    value.clamp(minimum, maximum.max(minimum))
}

/// Returns physical memory when an in-process platform provider exposes it.
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::detect_physical_memory_bytes`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::detect_physical_memory_bytes();
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn detect_physical_memory_bytes() -> Option<u64> {
    None
}

/// Parses a positive size with a safe default and upper bound.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::binaries::parse_positive_size_value`].
/// - `default_value`: Input consumed by [`crate::binaries::parse_positive_size_value`].
/// - `maximum`: Input consumed by [`crate::binaries::parse_positive_size_value`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::parse_positive_size_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::parse_positive_size_value("value", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn parse_positive_size_value(
    value: Option<&str>,
    default_value: usize,
    maximum: usize,
) -> usize {
    value
        .and_then(|value| value.parse::<usize>().ok())
        .filter(|value| *value > 0)
        .map(|value| value.min(maximum.max(1)))
        .unwrap_or(default_value.max(1).min(maximum.max(1)))
}

/// Validates app-ops prerequisites without mutating app state.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::binaries::prepare_app_ops`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::prepare_app_ops`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::prepare_app_ops`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::prepare_app_ops(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn prepare_app_ops(app: &AppRuntime) -> Result<(), &'static str> {
    if app.app_root.as_deref().is_none_or(str::is_empty) {
        return Err("app-ops requires an app root");
    }
    if app.state_path.as_deref().is_none_or(str::is_empty) {
        return Err("app-ops requires a state path");
    }
    Ok(())
}

/// Registers a listener cleanup token with its bound endpoint.
///
/// # Parameters
///
/// - `listener`: Input consumed by [`crate::binaries::register_listener_cleanup`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::register_listener_cleanup`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::register_listener_cleanup(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn register_listener_cleanup(listener: &TcpListener) -> Option<SocketAddr> {
    listener.local_addr().ok()
}

/// Resolves a Unix socket path for a runtime target.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::binaries::resolve_runtime_socket_path`].
/// - `runtime_id`: Input consumed by [`crate::binaries::resolve_runtime_socket_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::resolve_runtime_socket_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::resolve_runtime_socket_path(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn resolve_runtime_socket_path(config: &ServeConfig, runtime_id: &str) -> Option<String> {
    if runtime_id.is_empty() {
        return None;
    }
    config
        .socket_path
        .clone()
        .or_else(|| Some(format!("/tmp/pharos-{runtime_id}.sock")))
}

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

/// Confirms that an app directory manifest identifies the expected app.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::binaries::runtime_app_directory_matches_id`].
/// - `app_id`: Input consumed by [`crate::binaries::runtime_app_directory_matches_id`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::runtime_app_directory_matches_id`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::runtime_app_directory_matches_id(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn runtime_app_directory_matches_id(app_root: &Path, app_id: &str) -> bool {
    if app_id.is_empty() || !app_root.is_dir() {
        return false;
    }
    crate::config::match_app_root_in_directory(app_root, app_id).is_some()
}

/// Confirms that a finalized artifact manifest exists below an app root.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::binaries::app_root_has_finalized_artifact`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::app_root_has_finalized_artifact`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::app_root_has_finalized_artifact(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn app_root_has_finalized_artifact(app_root: &Path) -> bool {
    app_root.join("pharos.app.json").is_file() && app_root.join("runtime-route-map.tsv").is_file()
}

/// Confirms that the app runtime configuration contract is present.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::binaries::app_runtime_conf_required_present`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::app_runtime_conf_required_present`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::app_runtime_conf_required_present(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn app_runtime_conf_required_present(app_root: &Path) -> bool {
    app_root.join("app.conf").is_file() || app_root.join("pharos.app.json").is_file()
}

/// Seeds a missing state file only when the caller explicitly requests seeding.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::binaries::maybe_seed_app_state`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::maybe_seed_app_state`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::maybe_seed_app_state`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::maybe_seed_app_state(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn maybe_seed_app_state(app: &AppRuntime) -> Result<bool, i32> {
    let path = Path::new(app.state_path.as_deref().ok_or(64)?);
    if path.is_file() {
        return Ok(false);
    }
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent).map_err(|_| 73)?;
    }
    pharos_runtime_core::fs::write_binary_file(path, b"{}\n", 0o640).map_err(|_| 73)?;
    Ok(true)
}

/// Extracts a bounded HTTP error body from a response document.
///
/// # Parameters
///
/// - `response`: Input consumed by [`crate::binaries::http_parse_error_body`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::http_parse_error_body`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::http_parse_error_body(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn http_parse_error_body(response: &str) -> Option<String> {
    let body = response
        .split_once("\r\n\r\n")
        .map(|(_, body)| body)
        .or_else(|| response.split_once("\n\n").map(|(_, body)| body))?;
    (!body.is_empty() && body.len() <= 1024 * 1024).then(|| body.to_owned())
}

/// Returns a stable HTTP reason phrase for a status code.
///
/// # Parameters
///
/// - `status_code`: Input consumed by [`crate::binaries::http_parse_reason_phrase`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::http_parse_reason_phrase`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::http_parse_reason_phrase(400);
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn http_parse_reason_phrase(status_code: u16) -> &'static str {
    match status_code {
        200 => "OK",
        201 => "Created",
        204 => "No Content",
        400 => "Bad Request",
        401 => "Unauthorized",
        403 => "Forbidden",
        404 => "Not Found",
        405 => "Method Not Allowed",
        409 => "Conflict",
        413 => "Payload Too Large",
        429 => "Too Many Requests",
        500 => "Internal Server Error",
        503 => "Service Unavailable",
        _ => "Unknown",
    }
}

/// Returns one exact command-line option value.
///
/// # Parameters
///
/// - `arguments`: Input consumed by [`crate::binaries::option_value`].
/// - `name`: Input consumed by [`crate::binaries::option_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::binaries::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::binaries::option_value`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::option_value(todo!(), "name");
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn option_value(arguments: &[String], name: &str) -> Option<String> {
    arguments
        .windows(2)
        .find(|pair| pair[0] == name)
        .map(|pair| pair[1].clone())
}

/// Parses an app-ops JSON configuration document.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::binaries::parse_app_ops_config`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::parse_app_ops_config`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::parse_app_ops_config`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::binaries::parse_app_ops_config`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::parse_app_ops_config("{}");
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn parse_app_ops_config(text: &str) -> Result<serde_json::Value, i32> {
    let value: serde_json::Value = serde_json::from_str(text).map_err(|_| 65)?;
    value.is_object().then_some(value).ok_or(65)
}

/// Prepares a finalized app runtime from a resolved app directory and config.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::binaries::prepare_finalized_app_from_config`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::binaries::prepare_finalized_app_from_config`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::binaries::prepare_finalized_app_from_config`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::prepare_finalized_app_from_config(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn prepare_finalized_app_from_config(app_root: &Path) -> Result<AppRuntime, &'static str> {
    if !app_root_has_finalized_artifact(app_root) {
        return Err("finalized app artifact is incomplete");
    }
    let artifact_dir = app_root.to_path_buf();
    crate::runtime::load_app_runtime_from_artifact(&artifact_dir)
}

/// Returns whether the shared runtime stack has enough state for readiness.
///
/// # Parameters
///
/// - `stack`: Input consumed by [`crate::binaries::runtime_stack_probe_ready`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::binaries::runtime_stack_probe_ready`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::binaries::runtime_stack_probe_ready`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::runtime_stack_probe_ready(todo!());
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn runtime_stack_probe_ready(stack: &crate::runtime::RuntimeStack) -> bool {
    !stack.apps.is_empty()
        && stack.apps.iter().all(|app| {
            app.artifact_dir
                .as_deref()
                .is_some_and(|path| Path::new(path).is_dir())
        })
}

/// Serves one validated static request from a packaged artifact root.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::binaries::serve_static_file`].
/// - `method`: Input consumed by [`crate::binaries::serve_static_file`].
/// - `target`: Input consumed by [`crate::binaries::serve_static_file`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::binaries::serve_static_file`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::binaries::serve_static_file(std::path::Path::new("."), todo!(), "/");
/// ```
///
/// # Related
///
/// - [`crate::binaries`] for adjacent helpers that share the same runtime surface.
pub fn serve_static_file(
    root: &Path,
    method: &str,
    target: &str,
) -> crate::artifact_server::StaticResponse {
    let app = AppRuntime {
        artifact_dir: Some(root.to_string_lossy().into_owned()),
        ..AppRuntime::default()
    };
    crate::artifact_server::serve_app_request(&app, method, target)
}